ACP 智能体故障排除
故障排除¶
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
ACP runtime backend is not configured |
后端插件缺失、已禁用，或被 plugins.allow 阻止。 |
安装并启用后端插件；如果设置了该允许列表，请在 plugins.allow 中包含 acpx，然后运行 /acp doctor。 |
ACP is disabled by policy (acp.enabled=false) |
ACP 已全局禁用。 | 设置 acp.enabled=true。 |
ACP dispatch is disabled by policy (acp.dispatch.enabled=false) |
普通线程消息的自动分发已禁用。 | 设置 acp.dispatch.enabled=true 以恢复自动线程路由；显式 sessions_spawn({ runtime: "acp" }) 调用仍然有效。 |
ACP agent "<id>" is not allowed by policy |
代理不在允许列表中。 | 使用允许的 agentId，或更新 acp.allowedAgents。 |
/acp doctor reports backend not ready right after startup |
后端插件缺失、已禁用、被允许/拒绝策略阻止，或其配置的可执行文件不可用。 | 安装/启用后端插件，重新运行 /acp doctor；如果仍不健康，请检查后端安装或策略错误。 |
| 未找到 Harness 命令 | 适配器 CLI 未安装、外部插件缺失，或非 Codex 适配器的首次运行 npx 获取失败。 |
运行 /acp doctor，在 Gateway 主机上安装/预热适配器，或显式配置 acpx 代理命令。 |
| 来自 harness 的模型未找到 | 模型 id 对其他 provider/harness 有效，但对当前 ACP 目标无效。 | 使用该 harness 列出的模型，在 harness 中配置模型，或省略覆盖项。 |
| 来自 harness 的供应商身份验证错误 | OpenClaw 运行正常，但目标 CLI/provider 未登录。 | 在 Gateway 主机环境中登录或提供所需的 provider 密钥。 |
Unable to resolve session target: ... |
无效的 key/id/label 令牌。 | 运行 /acp sessions，复制确切的 key/label，然后重试。 |
--bind here requires running /acp spawn inside an active ... conversation |
在没有活动可绑定会话的情况下使用了 --bind here。 |
移动到目标聊天/频道并重试，或使用未绑定 spawn。 |
Conversation bindings are unavailable for <channel>. |
适配器缺少当前会话的 ACP 绑定能力。 | 在支持的地方使用 /acp spawn ... --thread ...，配置顶层 bindings[]，或移动到受支持的频道。 |
--thread here requires running /acp spawn inside an active ... thread |
在线程上下文之外使用了 --thread here。 |
移动到目标线程，或使用 --thread auto/off。 |
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
Only <user-id> can rebind this channel/conversation/thread. |
另一个用户拥有当前绑定目标。 | 以所有者身份重新绑定，或使用其他会话或线程。 |
Thread bindings are unavailable for <channel>. |
适配器不支持线程绑定。 | 使用 --thread off，或迁移到受支持的适配器/频道。 |
Sandboxed sessions cannot spawn ACP sessions ... |
ACP 运行时位于宿主侧；请求方会话处于沙箱中。 | 在沙箱会话中使用 runtime="subagent"，或从非沙箱会话运行 ACP spawn。 |
sessions_spawn sandbox="require" is unsupported for runtime="acp" ... |
为 ACP 运行时请求了 sandbox="require"。 |
对于必需沙箱，使用 runtime="subagent"；或从非沙箱会话使用带有 sandbox="inherit" 的 ACP。 |
Cannot apply --model ... did not advertise model support |
目标 harness 未暴露通用 ACP 模型切换。 | 使用支持 ACP models/session/set_model 的 harness，使用 Codex ACP 模型引用，或者如果 harness 有自己的启动标志，则直接在 harness 中配置模型。 |
| 绑定会话缺少 ACP 元数据 | 过期/已删除的 ACP 会话元数据。 | 使用 /session unbind 分离，然后使用 /acp spawn --bind here 或 /acp spawn --thread here 重新创建。 |
| ACP 输入请求被拒绝或取消 | 表单/URL 格式错误、超出字段/选项限制、使用了不支持的约束，或所属回合已结束。 | 查看可见的拒绝原因，使用标准基础表单或有效的 HTTP(S) URL 重试，并在回答期间保持源回合处于活动状态。 |
PermissionPromptUnavailableError: Permission prompt unavailable in non-interactive mode |
permissionMode 在非交互式 ACP 会话中阻止写入/执行。 |
将 plugins.entries.acpx.config.permissionMode 设置为 approve-all；默认混合重载会自动应用插件更改。参见 权限配置。 |
| ACP 会话早期失败且输出很少 | 权限提示被 permissionMode/nonInteractivePermissions 阻止。 |
检查网关日志中的 AcpRuntimeError。如需完整权限，设置 permissionMode=approve-all；如需优雅降级，设置 nonInteractivePermissions=deny。 |
| ACP 会话完成工作后无限期停滞 | Harness 进程已结束，但 ACP 会话未报告完成。 | 更新 OpenClaw；当前 acpx 清理会在关闭和 Gateway 启动时回收 OpenClaw 拥有的过期 wrapper 和 adapter 进程。 |
Harness 看到 <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> |
内部事件信封泄漏到 ACP 边界之外。 | 更新 OpenClaw 并重新运行完成流程；外部 harness 应仅接收纯完成提示。 |
Note
Command blocked by PreToolUse hook: Native hook relay unavailable 属于
原生 Codex hook relay，而不是 ACP/acpx。在已绑定的 Codex 聊天中，使用 /new 或 /reset 开始
新会话；如果它成功一次，然后在
下一次原生工具调用时再次出现，请重启 Codex app-server 或 OpenClaw Gateway，
而不是重复使用 /new。参见
Codex harness 故障排查。
已知提供商故障即使 harness 未返回助手回复，也会包含恢复指导。无法识别的故障保留通用消息；原始提供商诊断信息保留在日志中。如果警告提示工具操作可能已经执行，请在重试前检查其结果。
超大 harness 消息¶
acpx 后端默认将每个来自 harness 的传入 ACP 消息限制为 64 MiB 原始字节。如果运行因 ACP_MESSAGE_TOO_LARGE 或 ACP message exceeded ACPX_MAX_ACP_MESSAGE_BYTES 失败，请减少 harness 输出，或在 Gateway 进程环境中将 ACPX_MAX_ACP_MESSAGE_BYTES 设置为更大的字节数。将其设置为 0 可允许不限大小的传入消息。
更改环境后，请重启 Gateway，以便新的 harness 连接使用该限制。对于直接的 acpx CLI 会话，请关闭现有的 warm owner 并启动新会话；warm owner 会保留其启动时的设置。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw