You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Agent delivery: report `deliverySucceeded=false` when outbound delivery returns no adapter result, so claimed/empty delivery paths no longer masquerade as successful sends. Fixes #78532. Thanks @joeyfrasier.
184
184
- Cron/isolated runs: fail implicit announce delivery before model execution when `delivery.channel=last` has no previous route, so recurring jobs do not spend tokens before hitting a permanent delivery-target error. Fixes #78608. Thanks @sallyom.
185
185
- Gateway/sessions: persist a new generated transcript file when daily gateway-agent session rollover changes the session id, while preserving custom transcript paths. Fixes #78607. Thanks @nailujac, @zerone0x, and @sallyom.
186
-
- Doctor/OpenAI Codex: revert the 2026.5.5 `doctor --fix` repair that rewrote valid `openai-codex/*` ChatGPT/Codex OAuth routes to `openai/*`, which could break OAuth-only GPT-5.5 setups or accidentally move users onto the OpenAI API-key route. If 2026.5.5 already changed your default model, run `openclaw models set openai-codex/gpt-5.5 && openclaw config validate` to switch the default agent back to the Codex OAuth PI route. Fixes #78407.
186
+
- Doctor/OpenAI Codex: repair legacy `openai-codex/*` agent model refs and stale OpenAI PI session pins to `openai/*` with the Codex runtime, preserving existing `openai-codex` auth profiles so ChatGPT/Codex OAuth users do not fall back to OpenAI API-key routing. Fixes #78407.
187
187
- Telegram: keep the polling watchdog tied to `getUpdates` liveness so unrelated outbound Bot API calls cannot mask a wedged inbound poller. Fixes #78422. Thanks @ai-hpc.
188
188
- Discord/groups: instruct group-chat agents to stay silent when a message is addressed to someone else, replying only when invited or correcting key facts. (#78615)
189
189
- Discord/groups: tell Discord-channel agents to wrap bare URLs as `<https://example.com>` so link previews do not expand into uninvited embeds. (#78614)
| Native Codex app-server runtime |`openai/*`plus `agentRuntime.id: "codex"`| Runs the embedded agent turn through Codex app-server. This is the usual ChatGPT/Codex subscription setup. |
47
-
| Codex OAuth provider route|`openai-codex/*` model refs| Uses ChatGPT/Codex subscription OAuth through the normal OpenClaw PI runner. |
48
-
| Codex ACP adapter |`runtime: "acp"`, `agentId: "codex"`| Runs Codex through the external ACP/acpx control plane. Use only when ACP/acpx is explicitly asked. |
49
-
| Native Codex chat-control command set |`/codex ...`| Binds, resumes, steers, stops, and inspects Codex app-server threads from chat. |
50
-
| OpenAI Platform API route for GPT/Codex-style models|`openai/*`model refs | Uses OpenAI API-key auth unless a runtime override, such as `agentRuntime.id: "codex"`, runs the turn.|
| Native Codex app-server runtime |`openai/*`model refs | Runs OpenAI embedded agent turns through Codex app-server. This is the usual ChatGPT/Codex subscription setup. |
47
+
| Codex OAuth auth profiles|`openai-codex` auth provider| Stores ChatGPT/Codex subscription auth that the Codex app-server harness consumes.|
48
+
| Codex ACP adapter |`runtime: "acp"`, `agentId: "codex"`| Runs Codex through the external ACP/acpx control plane. Use only when ACP/acpx is explicitly asked.|
49
+
| Native Codex chat-control command set |`/codex ...`| Binds, resumes, steers, stops, and inspects Codex app-server threads from chat.|
50
+
| OpenAI Platform API route for non-agent surfaces|`openai/*`plus API-key auth| Used for direct OpenAI APIs such as images, embeddings, speech, and realtime. |
51
51
52
52
Those surfaces are intentionally independent. Enabling the `codex` plugin makes
53
-
the native app-server features available; it does not rewrite
54
-
`openai-codex/*`into `openai/*`, does not change existing sessions, and does
55
-
not make ACP the Codex default. Selecting `openai-codex/*` means "use the Codex
56
-
OAuth provider route" unless you separately force a runtime.
53
+
the native app-server features available; `openclaw doctor --fix` owns legacy
54
+
`openai-codex/*`route repair and stale session pin cleanup. Selecting
55
+
`openai/*`for an agent model now means "run this through Codex" unless a
56
+
non-agent OpenAI API surface is being used.
57
57
58
58
The common ChatGPT/Codex subscription setup uses Codex OAuth for auth, but keeps
59
59
the model ref as `openai/*` and selects the `codex` runtime:
@@ -63,9 +63,6 @@ the model ref as `openai/*` and selects the `codex` runtime:
63
63
agents: {
64
64
defaults: {
65
65
model:"openai/gpt-5.5",
66
-
agentRuntime: {
67
-
id:"codex",
68
-
},
69
66
},
70
67
},
71
68
}
@@ -88,20 +85,23 @@ This is the agent-facing decision tree:
88
85
1. If the user asks for **Codex bind/control/thread/resume/steer/stop**, use the
89
86
native `/codex` command surface when the bundled `codex` plugin is enabled.
90
87
2. If the user asks for **Codex as the embedded runtime** or wants the normal
91
-
subscription-backed Codex agent experience, use
92
-
`openai/<model>` with `agentRuntime.id: "codex"`.
93
-
3. If the user asks for **Codex OAuth/subscription auth on the normal OpenClaw
94
-
runner**, use `openai-codex/<model>` and leave the runtime as PI.
95
-
4. If the user explicitly says **ACP**, **acpx**, or **Codex ACP adapter**, use
88
+
subscription-backed Codex agent experience, use `openai/<model>`.
89
+
3. If the user explicitly chooses **PI for an OpenAI model**, keep the model ref
90
+
as `openai/<model>` and set `agentRuntime.id: "pi"`. A selected
91
+
`openai-codex` auth profile is routed internally through PI's legacy
92
+
Codex-auth transport.
93
+
4. If legacy config still contains **`openai-codex/*` model refs**, repair it to
94
+
`openai/<model>` with `openclaw doctor --fix`.
95
+
5. If the user explicitly says **ACP**, **acpx**, or **Codex ACP adapter**, use
96
96
ACP with `runtime: "acp"` and `agentId: "codex"`.
97
-
5. If the request is for **Claude Code, Gemini CLI, OpenCode, Cursor, Droid, or
97
+
6. If the request is for **Claude Code, Gemini CLI, OpenCode, Cursor, Droid, or
98
98
another external harness**, use ACP/acpx, not the native sub-agent runtime.
Copy file name to clipboardExpand all lines: docs/gateway/config-agents.md
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -387,7 +387,7 @@ Time format in system prompt. Default: `auto` (OS preference).
387
387
-`toolProgressDetail`: detail mode for `/verbose` tool summaries and progress-draft tool lines. Values: `"explain"` (default, compact human labels) or `"raw"` (append raw command/detail when available). Per-agent `agents.list[].toolProgressDetail` overrides this default.
388
388
-`reasoningDefault`: default reasoning visibility for agents. Values: `"off"`, `"on"`, `"stream"`. Per-agent `agents.list[].reasoningDefault` overrides this default. Configured reasoning defaults are only applied for owners, authorized senders, or operator-admin gateway contexts when no per-message or session reasoning override is set.
-`model.primary`: format `provider/model` (e.g. `openai/gpt-5.5` for API-key access or `openai-codex/gpt-5.5` for Codex OAuth). If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider (deprecated compatibility behavior, so prefer explicit `provider/model`). If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.
390
+
-`model.primary`: format `provider/model` (e.g. `openai/gpt-5.5` for OpenAI API-key or Codex OAuth access). If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider (deprecated compatibility behavior, so prefer explicit `provider/model`). If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.
391
391
-`models`: the configured model catalog and allowlist for `/model`. Each entry can include `alias` (shortcut) and `params` (provider-specific, for example `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
392
392
- Safe edits: use `openclaw config set agents.defaults.models '<json>' --strict-json --merge` to add entries. `config set` refuses replacements that would remove existing allowlist entries unless you pass `--replace`.
393
393
- Provider-scoped configure/onboarding flows merge selected provider models into this map and preserve unrelated providers already configured.
@@ -426,24 +426,24 @@ model, see [Agent runtimes](/concepts/agent-runtimes).
426
426
-`id`: `"auto"`, `"pi"`, a registered plugin harness id, or a supported CLI backend alias. The bundled Codex plugin registers `codex`; the bundled Anthropic plugin provides the `claude-cli` CLI backend.
427
427
-`id: "auto"` lets registered plugin harnesses claim supported turns and uses PI when no harness matches. An explicit plugin runtime such as `id: "codex"` requires that harness and fails closed if it is unavailable or fails.
428
428
- Environment override: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` overrides `id` for that process.
429
-
-For Codex-only deployments, set `model: "openai/gpt-5.5"` and `agentRuntime.id: "codex"`.
429
+
-OpenAI agent models use the Codex harness by default; `agentRuntime.id: "codex"` remains valid when you want to make that explicit.
430
430
- For Claude CLI deployments, prefer `model: "anthropic/claude-opus-4-7"` plus `agentRuntime.id: "claude-cli"`. Legacy `claude-cli/claude-opus-4-7` model refs still work for compatibility, but new config should keep provider/model selection canonical and put the execution backend in `agentRuntime.id`.
431
431
- Older runtime-policy keys are rewritten to `agentRuntime` by `openclaw doctor --fix`.
432
-
- Harness choice is pinned per session id after the first embedded run. Config/env changes affect new or reset sessions, not an existing transcript. Legacy sessions with transcript history but no recorded pin are treated as PI-pinned. `/status` reports the effective runtime, for example `Runtime: OpenClaw Pi Default` or `Runtime: OpenAI Codex`.
432
+
- Harness choice is pinned per session id after the first embedded run. Config/env changes affect new or reset sessions, not an existing transcript. Legacy OpenAI sessions with transcript history but no recorded pin use Codex; stale OpenAI PI pins can be repaired with `openclaw doctor --fix`. `/status` reports the effective runtime, for example `Runtime: OpenClaw Pi Default` or `Runtime: OpenAI Codex`.
433
433
- This only controls text agent-turn execution. Media generation, vision, PDF, music, video, and TTS still use their provider/model settings.
434
434
435
435
**Built-in alias shorthands** (only apply when the model is in `agents.defaults.models`):
Copy file name to clipboardExpand all lines: docs/gateway/doctor.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -264,7 +264,7 @@ That stages grounded durable candidates into the short-term dreaming store while
264
264
If you previously added legacy OpenAI transport settings under `models.providers.openai-codex`, they can shadow the built-in Codex OAuth provider path that newer releases use automatically. Doctor warns when it sees those old transport settings alongside Codex OAuth so you can remove or rewrite the stale transport override and get the built-in routing/fallback behavior back. Custom proxies and header-only overrides are still supported and do not trigger this warning.
265
265
</Accordion>
266
266
<Accordiontitle="2f. Codex route repair">
267
-
Doctor checks for legacy `openai-codex/*` model refs. Native Codex harness routing uses canonical `openai/*` model refs plus `agentRuntime.id: "codex"` so the turn goes through the Codex app-server harness instead of the OpenClaw PI OpenAI path.
267
+
Doctor checks for legacy `openai-codex/*` model refs. Native Codex harness routing uses canonical `openai/*` model refs; OpenAI agent turns go through the Codex app-server harness instead of the OpenClaw PI OpenAI path.
268
268
269
269
In `--fix` / `--repair` mode, doctor rewrites affected default-agent and per-agent refs, including primary models, fallbacks, heartbeat/subagent/compaction overrides, hooks, channel model overrides, and stale persisted session route state:
0 commit comments