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; default hybrid reload applies the plugin change automatically. 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 <<>>	Internal event envelope leaked across the ACP boundary.	Update OpenClaw and rerun the completion flow; external harnesses should receive plain completion prompts only.

Known provider failures include recovery guidance even when the harness returns no assistant reply. Unrecognized failures keep a generic message; raw provider diagnostics stay in the logs. If a warning says tool actions may have already run, check their results before retrying.

Oversized harness messages

The acpx backend limits each incoming ACP message from a harness to 64 MiB of raw bytes by default. If a run fails with ACP_MESSAGE_TOO_LARGE or ACP message exceeded ACPX_MAX_ACP_MESSAGE_BYTES, reduce the harness output or set ACPX_MAX_ACP_MESSAGE_BYTES in the Gateway process environment to a larger byte count. Setting it to 0 permits unlimited incoming message sizes.

Restart the Gateway after changing the environment so new harness connections use the limit. For direct acpx CLI sessions, close the existing warm owner and start a new session; warm owners keep their startup setting.