vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 13:40:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify codex runtime routing

Browse Source
This commit is contained in:
Peter Steinberger
2026-04-26 04:38:39 +01:00
parent 6336ed4166
commit 6d4f65c9d4
6 changed files with 212 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/tools/acp-agents-setup.md
View File

@@ -11,6 +11,20 @@ For the overview, operator runbook, and concepts, see [ACP agents](/tools/acp-ag
The sections below cover acpx harness config, plugin setup for the MCP bridges, and permission configuration.
Use this page only when you are setting up the ACP/acpx route. For native Codex
app-server runtime config, use [Codex harness](/plugins/codex-harness). For
OpenAI API keys or Codex OAuth model-provider config, use
[OpenAI](/providers/openai).
Codex has two OpenClaw routes:
| Route | Config/command | Setup page |
| -------------------------- | ------------------------------------------------------ | --------------------------------------- |
| Native Codex app-server | `/codex ...`, `embeddedHarness.runtime: "codex"` | [Codex harness](/plugins/codex-harness) |
| Explicit Codex ACP adapter | `/acp spawn codex`, `runtime: "acp", agentId: "codex"` | This page |
Prefer the native route unless you explicitly need ACP/acpx behavior.
## acpx harness support (current)
Current acpx built-in harness aliases:

19
docs/tools/acp-agents.md
View File

@@ -20,6 +20,11 @@ If you want Codex or Claude Code to connect as an external MCP client directly
to existing OpenClaw channel conversations, use [`openclaw mcp serve`](/cli/mcp)
instead of ACP.
ACP is not the default Codex path. It is the external-harness path. The native
Codex app-server plugin owns `/codex ...` controls and the
`embeddedHarness.runtime: "codex"` embedded runtime; ACP owns
`/acp ...` controls and `sessions_spawn({ runtime: "acp" })` sessions.
## Which page do I want?
There are three nearby surfaces that are easy to confuse:
@@ -35,6 +40,12 @@ There are three nearby surfaces that are easy to confuse:
Usually, yes. Fresh installs ship the bundled `acpx` runtime plugin enabled by default, with a plugin-local pinned `acpx` binary that OpenClaw probes and self-repairs on startup. Run `/acp doctor` for a readiness check.
OpenClaw only teaches agents about ACP spawning when ACP is truly usable: ACP
must be enabled, dispatch must not be disabled, the current session must not be
sandbox-blocked, and a runtime backend must be loaded. If those conditions are
not met, ACP plugin skills and `sessions_spawn` ACP guidance stay hidden so the
agent does not suggest an unavailable backend.
First-run gotchas:
- If `plugins.allow` is set, it is a restrictive plugin inventory and must include `acpx`; otherwise the bundled default is intentionally blocked and `/acp doctor` reports the missing allowlist entry.
@@ -142,6 +153,14 @@ thread records. Use explicit ACP only when you want the ACP runtime/session
model. The embedded Codex support boundary is documented in the
[Codex harness v1 support contract](/plugins/codex-harness#v1-support-contract).
For model/provider/runtime selection, remember:
- `openai-codex/*` is the PI Codex OAuth/subscription route.
- `openai/*` plus `embeddedHarness.runtime: "codex"` is the native Codex
app-server embedded runtime route.
- `/codex ...` is native Codex conversation control.
- `/acp ...` or `runtime: "acp"` is explicit ACP/acpx control.
Natural-language triggers that should route to the ACP runtime:
- "Run this as a one-shot Claude Code ACP session and summarize the result."