From 9e9e02418840fbcd2ecb1d32cb8a03c26d2b15fc Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 25 Apr 2026 21:52:26 +0100 Subject: [PATCH] docs: clarify ACP model override support --- CHANGELOG.md | 3 +++ docs/tools/acp-agents-setup.md | 5 +++++ docs/tools/acp-agents.md | 5 +++-- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bc1ef0bb8fc..7e91f0745f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -79,6 +79,9 @@ Docs: https://docs.openclaw.ai - ACP/sessions_spawn: reject normal OpenClaw config agent ids when callers explicitly request `runtime="acp"`, while allowing agents configured with `runtime.type="acp"` to resolve to their ACP harness id. Fixes #63914. +- ACP/models: document that non-Codex ACP model overrides require adapter + support for ACP `models` plus `session/set_model`, so unsupported harnesses + fail clearly instead of silently falling back to their defaults. - Plugins/Voice Call: treat missing provider credentials as setup-incomplete during Gateway startup and log the missing keys as a warning instead of a runtime startup error, while keeping explicit command/tool errors when used. Thanks diff --git a/docs/tools/acp-agents-setup.md b/docs/tools/acp-agents-setup.md index fed83c9c85f..ad71262477c 100644 --- a/docs/tools/acp-agents-setup.md +++ b/docs/tools/acp-agents-setup.md @@ -35,6 +35,11 @@ If your local Cursor install still exposes ACP as `agent acp`, override the `cur Direct acpx CLI usage can also target arbitrary adapters via `--agent `, but that raw escape hatch is an acpx CLI feature (not the normal OpenClaw `agentId` path). +Model control is adapter-capability dependent. Codex ACP model refs are +normalized by OpenClaw before startup. Other harnesses need ACP `models` plus +`session/set_model` support; if a harness exposes neither that ACP capability +nor its own startup model flag, OpenClaw/acpx cannot force a model selection. + ## Required config Core ACP baseline: diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index 4034f5d8443..4b6ceda4cbb 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -336,7 +336,7 @@ Interface details: - `resumeSessionId` (optional): resume an existing ACP session instead of creating a new one. The agent replays its conversation history via `session/load`. Requires `runtime: "acp"`. - `streamTo` (optional): `"parent"` streams initial ACP run progress summaries back to the requester session as system events. - When available, accepted responses include `streamLogPath` pointing to a session-scoped JSONL log (`.acp-stream.jsonl`) you can tail for full relay history. -- `model` (optional): explicit model override for the ACP child session. Honored for `runtime: "acp"` so the child uses the requested model instead of silently falling back to the target agent default. Codex ACP spawns normalize OpenClaw Codex refs such as `openai-codex/gpt-5.4` to Codex ACP startup config before `session/new`; slash forms such as `openai-codex/gpt-5.4/high` also set Codex ACP reasoning effort. +- `model` (optional): explicit model override for the ACP child session. Codex ACP spawns normalize OpenClaw Codex refs such as `openai-codex/gpt-5.4` to Codex ACP startup config before `session/new`; slash forms such as `openai-codex/gpt-5.4/high` also set Codex ACP reasoning effort. Other harnesses must advertise ACP `models` and support `session/set_model`; otherwise OpenClaw/acpx fails clearly instead of silently falling back to the target agent default. - `thinking` (optional): explicit thinking/reasoning effort for the ACP child session. For Codex ACP, `minimal` maps to low effort, `low`/`medium`/`high`/`xhigh` map directly, and `off` omits the reasoning-effort startup override. ## Delivery model @@ -530,7 +530,7 @@ Notes: Equivalent operations: -- `/acp model ` maps to runtime config key `model`. For Codex ACP, OpenClaw normalizes `openai-codex/` to the adapter model id and maps slash reasoning suffixes such as `openai-codex/gpt-5.4/high` to Codex ACP `reasoning_effort`. +- `/acp model ` maps to runtime config key `model`. For Codex ACP, OpenClaw normalizes `openai-codex/` to the adapter model id and maps slash reasoning suffixes such as `openai-codex/gpt-5.4/high` to Codex ACP `reasoning_effort`. For other harnesses, model control depends on adapter support for ACP `models` and `session/set_model`. - `/acp set thinking ` maps to runtime config key `thinking`. For Codex ACP, OpenClaw sends the corresponding `reasoning_effort` where the adapter supports one. - `/acp permissions ` maps to runtime config key `approval_policy`. - `/acp timeout ` maps to runtime config key `timeout`. @@ -561,6 +561,7 @@ plugin-tools and OpenClaw-tools MCP bridges, and ACP permission modes, see | `Thread bindings are unavailable for .` | Adapter lacks thread binding capability. | Use `--thread off` or move to supported adapter/channel. | | `Sandboxed sessions cannot spawn ACP sessions ...` | ACP runtime is host-side; requester session is sandboxed. | Use `runtime="subagent"` from sandboxed sessions, or run ACP spawn from a non-sandboxed session. | | `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | `sandbox="require"` requested for ACP runtime. | Use `runtime="subagent"` for required sandboxing, or use ACP with `sandbox="inherit"` from a non-sandboxed session. | +| `Cannot apply --model ... did not advertise model support` | The target harness does not expose generic ACP model switching. | Use a harness that advertises ACP `models`/`session/set_model`, use Codex ACP model refs, or configure the model directly in the harness if it has its own startup flag. | | Missing ACP metadata for bound session | Stale/deleted ACP session metadata. | Recreate with `/acp spawn`, then rebind/focus thread. | | `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blocks writes/exec in non-interactive ACP session. | Set `plugins.entries.acpx.config.permissionMode` to `approve-all` and restart gateway. See [Permission configuration](/tools/acp-agents-setup#permission-configuration). | | ACP session fails early with little output | Permission prompts are blocked by `permissionMode`/`nonInteractivePermissions`. | Check gateway logs for `AcpRuntimeError`. For full permissions, set `permissionMode=approve-all`; for graceful degradation, set `nonInteractivePermissions=deny`. |