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. |
