ACP 是 OpenClaw 用于将长时/高风险操作隔离到子进程的核心机制，解决主 Agent 循环被阻塞的问题。
核心思想
主 Agent 循环是串行的。将慢操作（Azure API、Terraform apply 等）放到 ACP 子进程中执行，即使子进程挂起，主循环依然响应。本质是 进程隔离 应用于 AI Agent 编排。
两种 ACP 使用方向
| 方向 | 说明 |
|---|---|
| ACP sessions inside OpenClaw | 通过 acpx 插件将外部 harness（Claude Code、Codex、Gemini CLI）作为受监督子进程运行 |
| OpenClaw ACP bridge | openclaw acp CLI 命令，让 IDE 通过 stdio 将 prompt 转发到 OpenClaw Gateway |
快速配置
# 安装 acpx 插件
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
# 验证
/acp doctor
# 配置
openclaw config set acp.enabled true
openclaw config set acp.backend "acpx"
openclaw config set acp.defaultAgent "claude-code"
openclaw config set acp.maxConcurrentSessions 8权限注意：ACP session 无 TTY，默认权限模型会在文件写入/exec 时抛 AcpRuntimeError。需配置 permissionMode 和 nonInteractivePermissions。
常用命令
/acp spawn — 启动新 session
/acp status — 查看运行中的 session
/acp timeout <s> — 设置超时
/acp steer — 向运行中 session 发送指令
/acp cancel — 终止卡住的 session
/acp close — 正常关闭
四种非阻塞模式
| 模式 | 适用场景 |
|---|---|
| Exec Backgrounding | 已知时长的 shell 命令；exec 工具 + timeout + yieldMs |
| ACP Sessions | 复杂多步骤工作（含工具调用、文件操作、决策） |
| Cron Reconciliation | 定期检查状态，替代等待完成 |
| Webhooks | 事件驱动；外部系统完成后 POST /hooks/agent |
实践中四种组合使用：ACP session 处理重活，exec backgrounding 处理快命令，cron 做状态对账，webhook 做事件通知。
故障排查
| 症状 | 原因 | 解决 |
|---|---|---|
spawn 后立即 AcpRuntimeError | 非交互权限配置缺失 | 检查 permissionMode 和 nonInteractivePermissions |
| Zombie sessions 占满并发槽 | session 完成后未正常关闭 | /acp status 检查，设置 runtime.ttlMinutes |
| 主循环阻塞 | inline exec 调用长时操作 | 迁移到 ACP session |
相关概念
- openclaw-multi-agent-timeout — 多 Agent 超时问题的完整诊断与修复
- awesome-openclaw-skills — OpenClaw skill 生态