Agent coordination
ACP agents troubleshooting
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
ACP runtime backend is not configured |
Backend plugin missing, disabled, or blocked by plugins.allow. |
Install and enable backend plugin, include acpx in plugins.allow when that allowlist is set, then run /acp doctor. |
ACP is disabled by policy (acp.enabled=false) |
ACP globally disabled. | Set acp.enabled=true. |
ACP dispatch is disabled by policy (acp.dispatch.enabled=false) |
Automatic dispatch from normal thread messages disabled. | Set acp.dispatch.enabled=true to resume automatic thread routing; explicit sessions_spawn({ runtime: "acp" }) calls still work. |
ACP agent "<id>" is not allowed by policy |
Agent not in allowlist. | Use allowed agentId or update acp.allowedAgents. |
/acp doctor reports backend not ready right after startup |
Backend plugin is missing, disabled, blocked by allow/deny policy, or its configured executable is unavailable. | Install/enable the backend plugin, rerun /acp doctor, and inspect the backend install or policy error if it stays unhealthy. |
| Harness command not found | Adapter CLI is not installed, the external plugin is missing, or first-run npx fetch failed for a non-Codex adapter. |
Run /acp doctor, install/prewarm the adapter on the Gateway host, or configure the acpx agent command explicitly. |
| Model-not-found from the harness | Model id is valid for another provider/harness but not this ACP target. | Use a model listed by that harness, configure the model in the harness, or omit the override. |
| Vendor auth error from the harness | OpenClaw is healthy, but the target CLI/provider is not logged in. | Log in or provide the required provider key on the Gateway host environment. |
Unable to resolve session target: ... |
Bad key/id/label token. | Run /acp sessions, copy exact key/label, retry. |
--bind here requires running /acp spawn inside an active ... conversation |
--bind here used without an active bindable conversation. |
Move to the target chat/channel and retry, or use unbound spawn. |
Conversation bindings are unavailable for <channel>. |
Adapter lacks current-conversation ACP binding capability. | Use /acp spawn ... --thread ... where supported, configure top-level bindings[], or move to a supported channel. |
--thread here requires running /acp spawn inside an active ... thread |
--thread here used outside a thread context. |
Move to target thread or use --thread auto/off. |
Only <user-id> can rebind this channel/conversation/thread. |
Another user owns the active binding target. | Rebind as owner or use a different conversation or thread. |
Thread bindings are unavailable for <channel>. |
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. | Detach with /session unbind, then recreate with /acp spawn --bind here or /acp spawn --thread here. |
| ACP input request is declined or cancelled | The form/URL is malformed, exceeds field/choice limits, uses unsupported constraints, or the owning turn ended. | Read the visible decline reason, retry with a standard primitive form or valid HTTP(S) URL, and keep the originating turn active while answering. |
PermissionPromptUnavailableError: 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. |
| 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. |
| ACP session stalls indefinitely after completing work | Harness process finished but ACP session did not report completion. | Update OpenClaw; current acpx cleanup reaps OpenClaw-owned stale wrapper and adapter processes on close and Gateway startup. |
Harness sees <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> |
Internal event envelope leaked across the ACP boundary. | Update OpenClaw and rerun the completion flow; external harnesses should receive plain completion prompts only. |
Was this useful?
