From 676eb91250039bed3c602f926caee3e91abdd490 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Sun, 26 Apr 2026 00:01:26 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@8e12c24d17218dc50023aaf5543df1b7c36520aa --- .openclaw-sync/source.json | 4 ++-- docs/concepts/agent-runtimes.md | 14 ++++++++++++++ docs/plugins/codex-harness.md | 6 ++++++ docs/tools/acp-agents.md | 21 +++++++++++---------- docs/tools/subagents.md | 6 +++--- 5 files changed, 36 insertions(+), 15 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 2454893d2..083acb7e0 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "e918e5f75cb065fe4c8b7c618517b540d00fba72", - "syncedAt": "2026-04-25T23:58:11.281Z" + "sha": "8e12c24d17218dc50023aaf5543df1b7c36520aa", + "syncedAt": "2026-04-25T23:59:57.116Z" } diff --git a/docs/concepts/agent-runtimes.md b/docs/concepts/agent-runtimes.md index 56e1130e7..2dd067f5b 100644 --- a/docs/concepts/agent-runtimes.md +++ b/docs/concepts/agent-runtimes.md @@ -46,6 +46,20 @@ That means OpenClaw selects an OpenAI model ref, then asks the Codex app-server runtime to run the embedded agent turn. It does not mean the channel, model provider catalog, or OpenClaw session store becomes Codex. +When the bundled `codex` plugin is enabled, natural-language Codex control +should use the native `/codex` command surface (`/codex bind`, `/codex threads`, +`/codex resume`, `/codex steer`, `/codex stop`) instead of ACP. Use ACP for +Codex only when the user explicitly asks for ACP/acpx or is testing the ACP +adapter path. Claude Code, Gemini CLI, OpenCode, Cursor, and similar external +harnesses still use ACP. + +| You mean... | Use... | +| --------------------------------------- | -------------------------------------------- | +| Codex app-server chat/thread control | `/codex ...` from the bundled `codex` plugin | +| Codex app-server embedded agent runtime | `embeddedHarness.runtime: "codex"` | +| OpenAI Codex OAuth on the PI runner | `openai-codex/*` model refs | +| Claude Code or other external harness | ACP/acpx | + For the OpenAI-family prefix split, see [OpenAI](/providers/openai) and [Model providers](/concepts/model-providers). For the Codex runtime support contract, see [Codex harness](/plugins/codex-harness#v1-support-contract). diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index f2847597c..a0b0ca848 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -20,6 +20,12 @@ If you are trying to orient yourself, start with `openai/gpt-5.5` is the model ref, `codex` is the runtime, and Telegram, Discord, Slack, or another channel remains the communication surface. +The same plugin also owns the native `/codex` chat-control command surface. If +the plugin is enabled and the user asks to bind, resume, steer, stop, or inspect +Codex threads from chat, agents should prefer `/codex ...` over ACP. ACP remains +the explicit fallback when the user asks for ACP/acpx or is testing the ACP +Codex adapter. + Native Codex turns keep OpenClaw plugin hooks as the public compatibility layer. These are in-process OpenClaw hooks, not Codex `hooks.json` command hooks: diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index 3ce29df5a..977713904 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -12,7 +12,7 @@ title: "ACP agents" [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) sessions let OpenClaw run external coding harnesses (for example Pi, Claude Code, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI, and other supported ACPX harnesses) through an ACP backend plugin. -If you ask OpenClaw in plain language to bind or control Codex in the current conversation, OpenClaw should use the native Codex app-server plugin (`/codex bind`, `/codex threads`, `/codex resume`). If you ask for `/acp`, ACP, acpx, or a Codex background child session, OpenClaw can still route Codex through ACP. Each ACP session spawn is tracked as a [background task](/automation/tasks). +If you ask OpenClaw in plain language to bind or control Codex in the current conversation and the bundled `codex` plugin is enabled, OpenClaw should use the native Codex app-server plugin (`/codex bind`, `/codex threads`, `/codex resume`, `/codex steer`, `/codex stop`) instead of ACP. If you ask for `/acp`, ACP, acpx, or an ACP adapter test explicitly, OpenClaw can still route Codex through ACP. Each ACP session spawn is tracked as a [background task](/automation/tasks). If you ask OpenClaw in plain language to "start Claude Code in a thread" or use another external harness, OpenClaw should route that request to the ACP runtime (not the native sub-agent runtime). @@ -24,12 +24,12 @@ instead of ACP. There are three nearby surfaces that are easy to confuse: -| You want to... | Use this | Notes | -| ----------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Bind or control Codex in the current conversation | `/codex bind`, `/codex threads` | Native Codex app-server path; includes bound chat replies, image forwarding, model/fast/permissions, stop, and steer controls. ACP is an explicit fallback | -| Run Claude Code, Gemini CLI, explicit Codex ACP, or another external harness _through_ OpenClaw | This page: ACP agents | Chat-bound sessions, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, background tasks, runtime controls | -| Expose an OpenClaw Gateway session _as_ an ACP server for an editor or client | [`openclaw acp`](/cli/acp) | Bridge mode. IDE/client talks ACP to OpenClaw over stdio/WebSocket | -| Reuse a local AI CLI as a text-only fallback model | [CLI Backends](/gateway/cli-backends) | Not ACP. No OpenClaw tools, no ACP controls, no harness runtime | +| You want to... | Use this | Notes | +| ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bind or control Codex in the current conversation | `/codex bind`, `/codex threads` | Native Codex app-server path when the `codex` plugin is enabled; includes bound chat replies, image forwarding, model/fast/permissions, stop, and steer controls. ACP is an explicit fallback | +| Run Claude Code, Gemini CLI, explicit Codex ACP, or another external harness _through_ OpenClaw | This page: ACP agents | Chat-bound sessions, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, background tasks, runtime controls | +| Expose an OpenClaw Gateway session _as_ an ACP server for an editor or client | [`openclaw acp`](/cli/acp) | Bridge mode. IDE/client talks ACP to OpenClaw over stdio/WebSocket | +| Reuse a local AI CLI as a text-only fallback model | [CLI Backends](/gateway/cli-backends) | Not ACP. No OpenClaw tools, no ACP controls, no harness runtime | ## Does this work out of the box? @@ -53,7 +53,8 @@ Quick `/acp` flow from chat: 5. **Steer** without replacing context — `/acp steer tighten logging and continue` 6. **Stop** — `/acp cancel` (current turn) or `/acp close` (session + bindings) -Natural-language triggers that should route to the native Codex plugin: +Natural-language triggers that should route to the native Codex plugin when it +is enabled: - "Bind this Discord channel to Codex." - "Attach this chat to Codex thread ``." @@ -77,7 +78,7 @@ Natural-language triggers that should route to the ACP runtime: - "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread." - "Run Codex through ACP in a background thread." -OpenClaw picks `runtime: "acp"`, resolves the harness `agentId`, binds to the current conversation or thread when supported, and routes follow-ups to that session until close/expiry. Codex only follows this path when ACP is explicit or the requested background runtime still needs ACP. +OpenClaw picks `runtime: "acp"`, resolves the harness `agentId`, binds to the current conversation or thread when supported, and routes follow-ups to that session until close/expiry. Codex only follows this path when ACP/acpx is explicit or the native Codex plugin is unavailable for the requested operation. For `sessions_spawn`, `runtime: "acp"` is advertised only when ACP is enabled, the requester is not sandboxed, and an ACP runtime backend is loaded. It targets @@ -90,7 +91,7 @@ harness id. ## ACP versus sub-agents -Use ACP when you want an external harness runtime. Use native Codex app-server for Codex conversation binding/control. Use sub-agents when you want OpenClaw-native delegated runs. +Use ACP when you want an external harness runtime. Use native Codex app-server for Codex conversation binding/control when the `codex` plugin is enabled. Use sub-agents when you want OpenClaw-native delegated runs. | Area | ACP session | Sub-agent run | | ------------- | ------------------------------------- | ---------------------------------- | diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index 9c9132c96..a77512a6a 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -60,7 +60,7 @@ transcript path on disk when you need the raw full transcript. - `--model` and `--thinking` override defaults for that specific run. - Use `info`/`log` to inspect details and output after completion. - `/subagents spawn` is one-shot mode (`mode: "run"`). For persistent thread-bound sessions, use `sessions_spawn` with `thread: true` and `mode: "session"`. -- For ACP harness sessions (Codex, Claude Code, Gemini CLI, OpenCode), use `sessions_spawn` with `runtime: "acp"` when the tool advertises that runtime, and see [ACP Agents](/tools/acp-agents), especially the [ACP delivery model](/tools/acp-agents#delivery-model) when debugging completions or agent-to-agent loops. OpenClaw hides `runtime: "acp"` until ACP is enabled, the requester is not sandboxed, and a backend plugin such as `acpx` is loaded. `runtime: "acp"` expects an external ACP harness id, or an `agents.list[]` entry with `runtime.type="acp"`; use the default sub-agent runtime for normal OpenClaw config agents from `agents_list`. +- For ACP harness sessions (Claude Code, Gemini CLI, OpenCode, or explicit Codex ACP/acpx), use `sessions_spawn` with `runtime: "acp"` when the tool advertises that runtime, and see [ACP Agents](/tools/acp-agents), especially the [ACP delivery model](/tools/acp-agents#delivery-model) when debugging completions or agent-to-agent loops. When the `codex` plugin is enabled, Codex chat/thread control should prefer `/codex ...` over ACP unless the user explicitly asks for ACP/acpx. OpenClaw hides `runtime: "acp"` until ACP is enabled, the requester is not sandboxed, and a backend plugin such as `acpx` is loaded. `runtime: "acp"` expects an external ACP harness id, or an `agents.list[]` entry with `runtime.type="acp"`; use the default sub-agent runtime for normal OpenClaw config agents from `agents_list`. Primary goals: @@ -103,7 +103,7 @@ Tool params: - `task` (required) - `label?` (optional) - `agentId?` (optional; spawn under another agent id if allowed) -- `runtime?` (`subagent|acp`, default `subagent`; `acp` is only for external ACP harnesses such as `codex`, `claude`, `gemini`, or `opencode`, or for `agents.list[]` entries whose `runtime.type` is `acp`) +- `runtime?` (`subagent|acp`, default `subagent`; `acp` is only for external ACP harnesses such as `claude`, `gemini`, `opencode`, or explicitly requested Codex ACP/acpx, or for `agents.list[]` entries whose `runtime.type` is `acp`) - `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result) - `thinking?` (optional; overrides thinking level for the sub-agent run) - `runTimeoutSeconds?` (defaults to `agents.defaults.subagents.runTimeoutSeconds` when set, otherwise `0`; when set, the sub-agent run is aborted after N seconds) @@ -159,7 +159,7 @@ Allowlist: Discovery: -- Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`. +- Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`. The response includes each listed agent's effective model and embedded runtime metadata so callers can distinguish PI, Codex app-server, and other configured native runtimes. Auto-archive: