openclaw - 💡(How to fix) Fix [Feature]: Warn before doctor --fix --non-interactive forces agentRuntime: "codex" globally [1 comments, 2 participants]

Summary

openclaw doctor --fix --non-interactive silently writes agents.defaults.agentRuntime.id = "codex" without an explicit warning surfaced in the change summary. For users running on a ChatGPT subscription who also use local Ollama models alongside OpenAI models, this fails closed on every non-OpenAI turn and produces no visible error in the channel UI.

Problem to solve

After running doctor --fix --non-interactive to migrate from legacy openai-codex/* refs to the canonical openai/* + codex runtime config, dashboard model switching to any Ollama model causes:

• 3-dot indicator disappears immediately
• No reply in Discord or Dashboard
• gateway.err.log only shows candidate_failed reason=unknown next=none plus Live session model switch requested: ollama/...
• gemma4:e4b happens to surface a clearer 400: "The 'gemma4:e4b' model is not supported when using Codex with a ChatGPT account."

The root cause is documented (docs/plugins/codex-harness.md L277-286: "Do not set agentRuntime.id: 'codex' globally if the same agent should freely switch between Codex and non-Codex provider models"), but:

1. The doctor migration writes this exact "global codex" config without surfacing the tradeoff
2. The error path on the Ollama side fails silently rather than telling the operator that the forced runtime rejected the model
3. After flipping the config back to "auto", the operator hits a second trap: existing sessions keep the pinned agentHarnessId and the change appears to do nothing until /new or /reset

Net effect: an operator who never touched local models during the initial Codex migration discovers the regression days later, when the local-model usage actually starts. Recovery is one config line, but discovery is expensive.

Proposed solution

Three small docs/UX improvements (no behavioral change to the runtime itself):

1. doctor --fix change summary: When the migration is about to set agents.defaults.agentRuntime.id = "codex" globally, print a one-line warning like note: this forces every embedded turn through Codex. If you also use non-OpenAI providers, see docs/plugins/codex-harness.md#add-codex-alongside-other-models. Even better: detect that the config also enumerates ollama/* providers under agents.defaults.models and elevate the warning.

2. Surface the "global codex blocks non-OpenAI model" failure mode: when a live session model switch request resolves to a non-OpenAI model and the current agentRuntime.id is "codex", emit a structured log/agent-visible message that names the runtime policy, not just reason=unknown next=none.

3. Docs Troubleshooting section: add a short "I changed agentRuntime and nothing happened" entry referencing the session pin behavior in attempt-execution.ts:672-693 and pointing to /new / /reset as the explicit unwedge step.

Alternatives considered

• Operator discipline (always run doctor --fix interactively, always read the docs first): matches what the docs already recommend, but in practice --non-interactive is what gets reached for in automated flows, and the failure mode is non-obvious enough to cost real time.
• Auto-rewriting "codex" to "auto" when other providers are detected: changes behavior, hides intent, not recommended. The warning surface is the right level.

Additional context

Real incident report (in Japanese, but the chronology and root-cause analysis is detailed): https://github.com/Hidetsugu55/openclaw-setup/pull/15

The fix on our side was a single config-set agents.defaults.agentRuntime.id auto + session /new. The official docs were complete; the gap was that the docs were the only place where the tradeoff was visible.

OpenClaw versions involved: 2026.5.6 (initial migration), 2026.5.7 (still reproduces).