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

crhan · crhan · commit 992868048bf9 · 2026-05-17T15:24:52.000+08:00
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 #82979 review thread for the broader context: this PR was originally larger but ClawSweeper correctly pointed out that #82864 already lands the routing fixes I had documented as a workaround, so the docs hunks have been dropped.
diff --git a/src/agents/agent-command.ts b/src/agents/agent-command.ts
@@ -923,7 +923,7 @@ async function agentCommandInternal(
       const explicitKey = modelKey(explicitRef.provider, explicitRef.model);
       if (!visibilityPolicy.allowsKey(explicitKey)) {
         throw new Error(
-          `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".`,
         );
       }
       provider = explicitRef.provider;

Original file line number	Diff line number	Diff line change
`@@ -923,7 +923,7 @@ async function agentCommandInternal(`
`923`	`923`	`const explicitKey = modelKey(explicitRef.provider, explicitRef.model);`
`924`	`924`	`if (!visibilityPolicy.allowsKey(explicitKey)) {`
`925`	`925`	`throw new Error(`
`926`		- `Model override "${sanitizeForLog(explicitRef.provider)}/${sanitizeForLog(explicitRef.model)}" is not allowed for agent "${sessionAgentId}".`,
	`926`	+ `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".`,
`927`	`927`	`);`
`928`	`928`	`}`
`929`	`929`	`provider = explicitRef.provider;`