Closes #128076
Related: #120728 #120656 #128077 #142010

What Problem This Solves

Fixes an issue where agents would refuse owner-authorized work that needs a credential the owner already supplied: typing a password into a login form through the browser tool, running a command with a workspace credential file, or completing setup for a remote operator who has no reachable Control UI. The refusal came from a blanket prompt block added in #120728, which told every agent to keep credentials out of "commands, arguments, URLs, tool arguments, and shell text". Operators running unattended browser logins reported their previously working flows breaking after upgrading; #128076/#128077 and #142010 report the same class.

Why This Change Was Made

The block was a prompt-level patch for a tool-routing miss. The original report (#120656) came from the local embedded TUI, which strips the openclaw and gateway tools, so the model had no masked handoff to call and improvised "paste the token here". The masked-entry surfaces already carry their own guidance in their tool descriptions (secrets, connect_channel, open_setup), and the block duplicated that guidance while adding only the harmful "never in tool arguments" rule.

This change deletes the blanket contract from the core system prompt, Codex developer instructions, Copilot guidance, and the system-agent prompts, and keeps credential routing where the surfaces live: one clause on the openclaw setup tool and delegate tool descriptions. What remains shared is deliberately narrow and lives in src/agents/credential-safety-prompt.ts under the shipped SDK name buildCredentialSafetyPrompt: the private login-code handoff line for group conversations (the owner-requested behavior from #139196), plus a terminal setup route (openclaw channels add <channel> / openclaw configure) emitted only when neither the openclaw nor the gateway tool is callable, which is the embedded/local TUI case. The helper takes { controlToolsAvailable }; the legacy string argument is accepted and ignored under a dated compat record through 2026-11-30, so plugins built against 2026.9.3 keep loading. The egress usage line stays with the secrets tool description. Out of scope: transcript redaction (#104992), the browser tool, configuration, and in-process delegation for --local mode (follow-up).

User Impact

• Agents complete owner-authorized tasks with owner-supplied credentials again, including browser form fills and commands that read workspace credential files, without echoing the values into chat.
• Setup flows still collect channel tokens, API keys, and passwords through masked entry, and the model is told so where it matters: on the setup tools themselves.
• Local embedded TUI sessions now get a working route (openclaw channels add <channel> or openclaw configure) instead of an unreachable "use masked entry" instruction.
• Every system prompt shrinks by roughly 1,000 characters (1,700 with the secrets tool).
• Plugins importing buildCredentialSafetyPrompt keep working; pass { controlToolsAvailable } instead of the old string argument before 2026-11-30 (SDK migration guide and compat registry updated).

Thanks @ejc3 for the reachability analysis in #128077 and @Stephane-fci for the workspace-credential report in #142010.

Evidence

• Regression test: the new capability-routing test in src/agents/system-prompt.test.ts fails on the original code for the no-control-tools case (missing terminal route) and passes after the change; the three cases with openclaw/gateway present stay unchanged.
• Changed test files pass: src/agents/system-prompt.test.ts (154), src/system-agent/assistant.test.ts (7), Codex thread-lifecycle (218) and thread-prompt (18), Copilot attempt (152) and prompt-guidance (12); full Copilot suite 541/541.
• Prompt snapshot fixtures regenerated with scripts/generate-prompt-snapshots.ts --write; only the contract lines and offsets change. Codex happy-path developer instructions shrink from 3,672 to 2,448 characters.
• SDK surface check passes with counts unchanged from base (4,447 public / 2,629 callable); test/scripts/plugin-sdk-surface-report.test.ts passes locally (it failed on the first head, which had removed the export).
• New src/agents/credential-safety-prompt.test.ts covers both availability cases and the ignored legacy string; Codex and Copilot prompt tests cover callable, disabled, deferred, and absent control tools.
• node scripts/check-changed.mjs: 28 checks pass; the extension-lint step is blocked locally by the nested-worktree ancestor node_modules guard, so the changed extension files were linted directly with oxlint --tsconfig extensions/tsconfig.json (clean). CI runs the real lane.
• Docs checks: mdx, link audit (12,603 links, 0 broken), i18n glossary, format, config examples (1,219), markdownlint. git diff --check clean.
• Pre-existing, unrelated: extensions/codex/src/app-server/attempt-startup.test.ts "reapplies prepared auth before thread startup after a managed Computer Use restart" fails identically on base 4b9ff9dd206.
• CI shard leak fixed (third commit): src/agents/schema-normalization-runtime-contract.test.ts failed only in shard core-unit-fast-1 because src/agents/auth-profiles/session-override.model-endpoint.test.ts loads the Arcee plugin through Jiti, whose transport module republishes globalThis.openclawOpenAIResponsesTransportTestApi for the shared worker; the endpoint test now restores the original property after the file. Reproduced in the same shard locally (3 failures), fixed (8,495 shard tests pass, both file orders pass). This PR's added test file shifted shard composition, which is why the pre-existing leak surfaced here. Follow-up worth considering: make the publisher in packages/ai/src/transports/openai-responses-transport.ts first-publication-wins so no other test can trip it.
• Codex autoreview (P0–P2): scoped-clean on the final patch.
• Proof gap: this is prompt text; no live-model run was performed to demonstrate a specific model's refusal disappearing.

Review response (ClawSweeper on c08ddc3)

• P1, keep the shipped SDK export: accepted. buildCredentialSafetyPrompt stays exported under its shipped name with narrowed content; the old string argument is deprecated via the dated compat registry (agent-harness-credential-prompt-string-argument, through 2026-11-30). Surface counts are back to base, so no budget change.
• P2, terminal setup route in native harness prompts: accepted. Codex buildDeveloperInstructions and Copilot buildCopilotPromptGuidance now call the same helper with availability derived from their callable openclaw/gateway tools and disableTools.
• Security concern, private login-code handoff: retained as one line in the shared helper, so it still reaches every prompt owner. The blanket "keep secrets out of tool arguments" rule is the only thing removed.
• Maintainer decision: remove the blanket use prohibition, keep the private-delivery guidance. That is what this head does.

Review response (ClawSweeper revision 2 on 037c3a1)

The exact-head review reports both prior findings resolved, no actionable code defect, and no security finding. Its remaining merge-risk/proof items are addressed as follows:

• SDK behavior transition: accepted as part of the owner-approved change. Existing plugins retain the shipped buildCredentialSafetyPrompt import and legacy string-call compatibility through 2026-11-30, while intentionally receiving narrower prompt content. A legacy string call receives private login-code handoff guidance; plugins must pass { controlToolsAvailable: false } to select terminal setup guidance. Core, Codex, and Copilot callers already pass availability. The compatibility test covers legacy strings, omitted/unknown availability, and both explicit availability states; the SDK surface check reports unchanged public/callable counts. This preserves import/call compatibility, not the removed blanket policy text.
• Policy scope and live-proof limitation: the owner-approved decision removes the blanket prompt prohibition across admitted sessions; this is not an owner-only runtime override. Existing runtime admission, tool authorization, protected-store egress, masked setup collection, and private login-code delivery guidance remain in place. No after-change live-model disclosure/refusal measurement was performed. That limitation is explicitly accepted for this prompt-policy transition; focused prompt evidence does not claim to establish live login behavior.
• Data-model classification: no persistent data model, SQLite schema/version, stored credential format, migration, backfill, or recovery path changes. src/plugins/compat/registry-records.ts adds a static PluginCompatRecord describing the SDK argument deprecation; src/plugins/compat/registry.ts reads this in-memory registry. Upgrade proof concerns the shipped SDK import/call contract, covered by the retained export, ignored legacy-string test, unchanged surface counts, and dated migration guidance above. Database migration/reopen proof is not applicable to this metadata-only addition.

Source LOC is +55/-39 (net +16), including the required 18-line static compatibility record; excluding that metadata, runtime source is net -2. Tests/fixtures are +193/-258 (net -65). Landing preserved the reviewed implementation; the rebase resolution retained both existing test blocks.

Landing rebase verification

Rebased onto main 9865df7610c858975899e9abc3699f9bdcb7d858; new head 780b2fe35d71d539179424c78c57000f8f669d2c. The only conflict was in extensions/codex/src/app-server/thread-prompt.test.ts: both main's Git co-author tests and this PR's credential-routing tests are retained byte-for-byte. Outside that file, the old-head-to-new-head diff equals the old-base-to-new-base diff after ignoring diff hunk coordinates and blob IDs. No other source edits were made during landing.

On the rebased head:

• node scripts/run-vitest.mjs extensions/codex/src/app-server/thread-prompt.test.ts extensions/codex/src/app-server/thread-lifecycle.test.ts src/agents/credential-safety-prompt.test.ts src/agents/system-prompt.test.ts test/scripts/plugin-sdk-surface-report.test.ts src/plugins/compat/registry.test.ts: 441 tests passed across six files and five shards.
• node --import ./scripts/tsx.mjs scripts/generate-prompt-snapshots.ts --check: all seven files current; no fixture regeneration commit needed.
• git diff --check: clean.
• Exact-head CI attached: https://github.com/openclaw/openclaw/actions/runs/34386840789 (completed successfully; no job reruns).

Review response (ClawSweeper revision 5 on 780b2fe)

The exact-head review reports no actionable findings or security findings and confirms both original findings are resolved. Its two remaining checklist items are covered by the existing maintainer decisions above:

• SDK policy transition: accepted. Import and legacy-string-call compatibility remain through 2026-11-30; narrower output is the intended owner-approved behavior. The absence of an after-change live-model refusal/disclosure measurement remains explicitly accepted and is not represented as passing live proof.
• Data-model compatibility: no persistent data model changes. src/plugins/compat/registry-records.ts:174 adds static metadata returned directly by src/plugins/compat/registry.ts:8. No SQLite schema/version, credential storage, backfill, or runtime migration changes. The retained SDK export, legacy-string test, unchanged SDK surface, and passing registry test provide the relevant upgrade evidence; database migration/reopen proof does not apply.

Exact-head CI run 34386840789 completed successfully. The native watcher returned GREEN with zero pending checks. The rebased implementation is unchanged beyond preserving both adjacent test blocks; no additional code edits were made.