agents: include allow-list hint in disallowed model override error by crhan · Pull Request #82979 · openclaw/openclaw

crhan · 2026-05-17T07:07:25Z

Summary

Append the agents.defaults.models allow-list hint to the
Model override "X" is not allowed for agent "Y" error thrown by
src/agents/agent-command.ts. A peer code path in
src/auto-reply/reply/get-reply-directives-apply.ts:72 already
includes a helpful hint
(Add ${rejectedRef} to agents.defaults.models or pick an allowed model with /model list.); this brings the agent-command path to
parity.

This PR was originally scoped to include docs/openai.md and
docs/codex-harness.md rewrites based on observed behavior on the
2026.5.12 stable release. ClawSweeper review on current main
correctly pointed out that #82864
(Fix OpenAI Codex runtime provider routing) already addresses
the underlying routing / auth-bridging gap, so those docs as
written on main are accurate; my proposed rewrites would have
regressed them. I've dropped the docs hunks. The remaining
change is the additive error-message hint, which ClawSweeper
flagged as "plausible" and is independent of the routing fix.

Change

src/agents/agent-command.ts (~line 926):

-          `Model override "${sanitizeForLog(explicitRef.provider)}/${sanitizeForLog(explicitRef.model)}" is not allowed for agent "${sessionAgentId}".`,
+          `Model override "${sanitizeForLog(explicitRef.provider)}/${sanitizeForLog(explicitRef.model)}" is not allowed for agent "${sessionAgentId}". Add it to agents.defaults.models or pick an allowed model with "openclaw models list".`,

Backward compatibility

Existing test (src/commands/agent.test.ts:1068) uses
toThrow(string) which is substring matching, so the additional
hint at the tail does not break it. No test changes required.

(Optional follow-up: bring src/gateway/http-utils.ts:105 to
parity — it uses toEqual({ errorMessage }) exact matching and
would require updating the test, so excluded to keep scope
minimal.)

[Bug] openai-codex provider blocked by Cloudflare JS Challenge when accessed via proxy in mainland China #67670 — same Cloudflare 403 symptom in 2026.5.12 release.
Resolved on main by Fix OpenAI Codex runtime provider routing #82864; this PR is unrelated to that
routing fix but the user-facing error hint helps anyone who
encounters the allow-list semantics for unrelated reasons.
[Bug] Docs and onboarding silently route users to the PI path instead of the Codex app-server runtime, causing chatgpt.com 403 in Cloudflare-sensitive environments #82978 — companion issue I filed and ClawSweeper closed as
already implemented (correctly, on main).

clawsweeper · 2026-05-17T07:08:28Z

Codex review: needs real behavior proof before merge.

Summary
The PR appends an agents.defaults.models allow-list recovery hint to the disallowed explicit model override error in src/agents/agent-command.ts.

Reproducibility: yes. for the current error path: source and existing tests show a disallowed one-off model override reaches the visibilityPolicy.allowsKey rejection in agentCommand. I did not run it because this review is read-only, and the PR body does not provide after-patch runtime output.

Real behavior proof
Needs real behavior proof before merge: The PR body explains the source path but does not show after-patch real behavior; the contributor should add redacted terminal output, copied live output, logs, or a screenshot showing the new error, then update the PR body for re-review.

Next step before merge
The next action is contributor proof for an external PR; an automated repair lane cannot supply evidence from the contributor's real setup.

Security
Cleared: The reduced diff is a one-line error-message change with no dependency, CI, credential, install, or code-execution surface change.

Review details

Best possible solution:

Keep the scope reduced to one consistent allow-list hint across CLI and chat model-override rejection paths, without reviving the stale Codex docs workaround.

Do we have a high-confidence way to reproduce the issue?

Yes for the current error path: source and existing tests show a disallowed one-off model override reaches the visibilityPolicy.allowsKey rejection in agentCommand. I did not run it because this review is read-only, and the PR body does not provide after-patch runtime output.

Is this the best way to solve the issue?

Yes, the reduced patch is a narrow maintainable way to solve the remaining error-message gap and mirrors an existing peer hint. The merge gate that remains is contributor-supplied real behavior proof, not a code-design blocker.

What I checked:

Current main error path: Current main rejects explicit one-off model overrides that are not allowed by the model visibility policy and throws the shorter error without the recovery hint. (src/agents/agent-command.ts:924, 635b947e32e0)
PR diff scope: The PR head commit changes only src/agents/agent-command.ts and replaces the disallowed override error string with the proposed allow-list hint; no docs, dependencies, CI, or security-sensitive files remain in the diff. (src/agents/agent-command.ts:926, 992868048bf9)
Peer message already has recovery hint: The chat directive reset path already tells users to add the rejected model to agents.defaults.models or pick an allowed model with /model list, so the remaining PR change matches an existing user-facing pattern. (src/auto-reply/reply/get-reply-directives-apply.ts:72, 635b947e32e0)
Existing focused coverage exercises the path: The current agent command test drives a disallowed model override and asserts the old error prefix; that supports the source path but does not prove the new suffix after the patch. (src/commands/agent.test.ts:1068, 635b947e32e0)
CLI command and allow-list docs are valid: The CLI registers openclaw models list, and the models docs describe both the allow-list behavior and CLI model listing, so the proposed CLI-side hint points at real documented surfaces. (src/cli/models-cli.ts:30, 635b947e32e0)
Prior review context was addressed: The provided GitHub timeline shows the earlier docs findings applied to a larger pre-force-push diff; the author then force-pushed commit 992868048bf9b17d48c3aa92fd545188b9e70373 and explicitly dropped the stale docs hunks. (992868048bf9)

Likely related people:

@steipete: Recent git log --follow history shows Peter Steinberger authored aaadf721e3602002e24352ba039e06f56dd18dfd, which touched src/agents/agent-command.ts shortly after the baseline import. (role: recent area contributor; confidence: medium; commits: aaadf721e360; files: src/agents/agent-command.ts)
ragesaq: The related merged routing fix 58f1db1bc8eb5eb7bf32225227ed51bdcf2447d3 is central to the PR discussion and updated nearby OpenAI Codex agent routing tests/docs, though it did not touch this exact error string. (role: adjacent owner; confidence: medium; commits: 58f1db1bc8eb; files: src/agents/openai-codex-routing.ts, src/agents/openai-codex-routing.test.ts, docs/plugins/codex-harness.md)

Remaining risk / open question:

The PR body does not include after-patch terminal output, copied live output, logs, or a screenshot showing the new error hint in a real run.
The existing focused test asserts only the old error prefix, so the new recovery suffix is not locked by a dedicated assertion.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 635b947e32e0.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f87138719e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-17T07:09:41Z

+        3. Mirror the OAuth profile from `auth-profiles.json` to the per-agent
+           Codex home so the spawned codex app-server can pick it up. If you
+           already signed in via the standalone codex CLI:
+
+           ```bash
+           mkdir -p ~/.openclaw/agents/<agent-id>/agent/codex-home
+           cp ~/.codex/auth.json ~/.openclaw/agents/<agent-id>/agent/codex-home/
+           chmod 600 ~/.openclaw/agents/<agent-id>/agent/codex-home/auth.json


Don't require copying standalone Codex auth

For users who followed the preceding openclaw models auth login --provider openai-codex step, this new instruction points at ~/.codex/auth.json, which often will not exist and is not the OpenClaw auth store. The Codex harness already reads OpenClaw auth profiles and bridges them into the app-server (extensions/codex/src/app-server/auth-bridge.ts resolves the openai-codex profile and sends account/login/start), so documenting a manual copy from standalone Codex can make fresh OpenClaw OAuth setups fail at cp or pick up stale personal Codex credentials instead of the selected OpenClaw profile.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-17T07:09:41Z

+  runtime**. "Auto mode" does not currently choose the codex runtime
+  automatically based on plugin availability — without an explicit
+  `agentRuntime.id`, OpenAI-family model refs (`openai/*`, `openai-codex/*`)
+  resolve to the PI runtime even when `@openclaw/codex` is installed. This is


Don't say enabled Codex auto mode still falls back to PI

When the Codex plugin is registered, this statement is no longer true: resolveAgentHarnessPolicy() returns implicit codex for normal openai/* models, and selectAgentHarnessDecision() only falls back to PI for that implicit policy when getRegisteredAgentHarness("codex") is missing; the existing selection test also covers the default Codex path. As written, users who have installed/enabled @openclaw/codex are told they must add explicit agentRuntime.id to avoid PI even though auto mode will select the Codex harness once it is available, contradicting the route summary and basic deployment examples on the same page.

Useful? React with 👍 / 👎.

Mirror the existing helpful hint from src/auto-reply/reply/get-reply-directives-apply.ts:72 onto the parallel error thrown in src/agents/agent-command.ts when an explicit model override is rejected by the visibility policy. Existing test (src/commands/agent.test.ts:1068) uses toThrow(string) substring matching, so appending the hint is backward compatible and no test changes are required. See openclaw#82979 review thread for the broader context: this PR was originally larger but ClawSweeper correctly pointed out that openclaw#82864 already lands the routing fixes I had documented as a workaround, so the docs hunks have been dropped.

crhan · 2026-05-17T07:25:15Z

Comment on PR #82979 explaining scope reduction

在 force-push 之前发，让 ClawSweeper / 路过的 maintainer 知道 context。

Thanks @clawsweeper for the careful review — you're right that
the docs hunks contradict current main. I was diagnosing on the
2026.5.12 stable release where #82864 hadn't landed yet, so what
I observed (openai-codex/* PI fallback, no auto-install, no
auth bridge) was real on that build but is no longer accurate
against main. Documenting the workaround into the canonical
docs would regress them once #82864 ships, so I'm dropping the
docs hunks.

I've also pushed the same scope reduction in a force-push:
the remaining change is just the additive agents.defaults.models
allow-list hint on the disallowed-model-override error
(src/agents/agent-command.ts:926), which mirrors the existing
hint in src/auto-reply/reply/get-reply-directives-apply.ts:72
and which ClawSweeper described as "plausible". Scope-reduced PR
title: agents: include allow-list hint in disallowed model override error.

Apologies for the noise on the docs side.

crhan · 2026-05-17T07:39:34Z

Closing this — once #82864 lands in a stable release, the underlying routing path that originally drove me to this allow-list error message will not be the common code path anymore, so the remaining 1-line hint here doesn't justify maintainer review time. The hint is still mirrored in src/auto-reply/reply/get-reply-directives-apply.ts:72 for the auto-reply path which is what most users hit. Thanks @clawsweeper for the review and for pointing at #82864.

openclaw-barnacle Bot added docs Improvements or additions to documentation agents Agent runtime and tooling size: XS triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 17, 2026

chatgpt-codex-connector Bot reviewed May 17, 2026

View reviewed changes

crhan force-pushed the docs/codex-onboarding-accuracy branch from f871387 to 9928680 Compare May 17, 2026 07:24

openclaw-barnacle Bot removed the docs Improvements or additions to documentation label May 17, 2026

crhan changed the title ~~docs(codex): correct onboarding instructions and surface allow-list hint in model override error~~ agents: include allow-list hint in disallowed model override error May 17, 2026

clawsweeper Bot added P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. impact:auth-provider Auth, provider routing, model choice, or SecretRef resolution may break. labels May 17, 2026

crhan closed this May 17, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

agents: include allow-list hint in disallowed model override error#82979

agents: include allow-list hint in disallowed model override error#82979
crhan wants to merge 1 commit into
openclaw:mainfrom
crhan:docs/codex-onboarding-accuracy

crhan commented May 17, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 17, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 17, 2026

Uh oh!

chatgpt-codex-connector Bot May 17, 2026

Uh oh!

crhan commented May 17, 2026

Uh oh!

crhan commented May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

crhan commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change

Backward compatibility

Related

Uh oh!

clawsweeper Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 17, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 17, 2026

Choose a reason for hiding this comment

Uh oh!

crhan commented May 17, 2026

Comment on PR #82979 explaining scope reduction

Uh oh!

crhan commented May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

crhan commented May 17, 2026 •

edited

Loading

clawsweeper Bot commented May 17, 2026 •

edited

Loading