Claude ACP 配置与避坑指南

Claude ACP 配置与避坑指南OpenClaw Claude Code (ACP Harness) 部署完整指南 | 枢归档1. 什么是 Claude ACPClaude ACPAgent Client Protocol是 OpenClaw 与外部 Agent Harness如 Claude Code之间的通信协议。通过 ACPOpenClaw 可以调度 Claude Code 作为子 Agent在指定工作目录下执行任务。典型应用场景复杂代码编写Claude Code 比通用 Agent 更擅长长周期项目开发需要持久上下文的对话任务2. 安装 acpxnpminstall-gacpx0.4.0注意acpx 版本必须与 OpenClaw 内置版本一致否则会报接口不兼容错误。版本不一致的表现# 全局装了 0.4.1内置 0.4.0 # → 接口不兼容报错如已安装其他版本先卸载再装指定版本npmuninstall-gacpxnpminstall-gacpx0.4.03. 配置文件完整示例完整配置位于C:\Users\user\.openclaw\openclaw.json分为 acp 配置段和 acpx 插件段。3.1 acp 配置段{acp:{enabled:true,dispatch:{enabled:true},backend:acpx,defaultAgent:claude,allowedAgents:[claude],maxConcurrentSessions:8,stream:{coalesceIdleMs:300,maxChunkChars:1200},runtime:{ttlMinutes:120}}}3.2 acpx 插件配置段{plugins:{allow:[acpx],entries:{acpx:{enabled:true,config:{permissionMode:approve-all,nonInteractivePermissions:deny,strictWindowsCmdWrapper:false,expectedVersion:any,command:D:\\xxxxx\\xxxxx\\nodeJs\\node_24\\node_global\\node_modules\\.bin\\acpx.cmd,cwd:claude工作目录}}}}}command是必须的不然会出问题3.3 配置项说明配置项值作用backendacpxACP 后端defaultAgentclaude默认调度的 HarnessallowedAgents[“claude”]允许的 Harness 列表permissionModeapprove-all自动批准所有文件读写/命令执行nonInteractivePermissionsdeny无 TTY 时静默拒绝权限strictWindowsCmdWrapperfalse用 shell 方式执行 acpx继承完整 PATHexpectedVersionany跳过 acpx 版本校验command指向 acpx.cmd必须是 acpx.cmd不能是 node.execwd项目路径spawn 时的工作目录4. 飞书配置可选4.1 创建应用在飞书开放平台创建应用获取 appid 和 secret。4.2 权限配置{scopes:{tenant:[im:message,im:message.p2p_msg:readonly,im:message:send_as_bot,im:resource,application:bot.menu:write],user:[im:chat.access_event.bot_p2p_chat:read]}}4.3 事件订阅订阅方式长连接WebSocket必加事件im.message.receive_v14.4 悬浮菜单动作发送内容发送文字消息/acp spawn claude --bind here绑定会话不过有点坑的是不知道为啥会创建大量的node进程可能有二百来个吧这个可以注意下发送文字消息/acp status发送文字消息/acp steer --session key 继续下一步发送文字消息/acp close4.5 openclaw.json 飞书配置{channels:{feishu:{enabled:true,connectionMode:websocket,dmPolicy:allowlist,allowFrom:[xxxx],streaming:true,groupPolicy:allowlist,accounts:{mohu:{appId:appId1,appSecret:appSecret1,name:agentId1}}}},bindings:[{match:{channel:feishu},agentId:mo}]}4.6 配对飞书给机器人发消息获取配对码执行审批openclaw pairing approve feishu 配对码5. Gateway 管理5.1 启动 Gatewayopenclaw gateway install openclaw gateway start5.2 计划任务管理schtasks /query /tn OpenClaw Gateway /fo list schtasks /end /tn OpenClaw Gateway schtasks /run /tn OpenClaw Gateway6. ACP 命令详解6.1 飞书悬浮菜单配置推荐在飞书机器人菜单配置以下动作通过按钮触发菜单按钮发送内容作用新建任务/acp spawn claude --bind here启动一个与当前飞书会话绑定的 Claude 会话查看状态/acp status查看当前所有 ACP 会话状态继续任务/acp steer --session key 指令向指定会话发送指令继续执行关闭会话/acp close关闭当前/指定会话6.2 常用命令# 健康检查确认 acpx 和 Claude Code 可用/acp doctor# 启动单次任务oneshot/acp spawn claude--modeoneshot --任务描述# 启动持久会话persistent/acp spawn claude--modepersistent--bindhere# 查看当前所有会话/acp status# 向指定会话发送指令/acp steer--sessionsession_key指令内容# 关闭会话/acp close--sessionsession_key# 或在飞书菜单直接发对应文字/acp spawn claude--bindhere# 绑定当前会话启动/acp status# 查看状态/acp close# 关闭当前会话6.3 会话管理# 持久会话特点- 会话保持上下文适合长周期任务 - 每次 spawn 生成一个新的 session_key - 通过--bindhere 将会话绑定到当前飞书私聊# oneshot vs persistent 对比|模式|上下文|适用场景||------|--------|---------||oneshot|无每次独立|简单一次性任务||persistent|保持|复杂长任务、多轮对话|# 指令注入steer/acp steer--sessionagent:acp:claude:abc123 继续写下一章 - steer 在当前模型调用结束后注入指令 - 适用于追加需求、修正方向、继续生成6.4 已知限制OpenClaw 内置 ACP 命令有限完整功能需依赖飞书悬浮菜单--mode persistent需要 Claude Code 支持 session 模式飞书端修改后需重新部署才能生效7. 避坑指南重点坑 1spawn 后 Claude 报 “bad option: --format”现象spawn 成功但 Claude 无响应日志显示bad option: --format原因strictWindowsCmdWrapper默认为 trueGateway 用非 shell 方式执行PATH 不完整command指向 node.exe 时参数被错误传递解法strictWindowsCmdWrapper:false,command:D:\\...\\acpx.cmd坑 2command 必须指向 acpx.cmd不能是 node.exe原因OpenClaw 发出--format json参数追加到 node.exe 后变成node.exe --format jsonnode 不识别此参数解法command必须指向 acpx.cmd不能是 node.exe 也不能是 cli.js坑 3acpx 版本不一致现象接口不兼容报错原因全局装了 0.4.1OpenClaw 内置 0.4.0版本不匹配解法npmuninstall-gacpxnpminstall-gacpx0.4.0坑 4spawn 后 Claude 找不到项目路径现象Claude 启动后无法定位 state.json 和上下文解法在 acpx config 设置cwd指定项目根目录在项目目录放置CLAUDE.md作为上下文入口坑 5cwd 配置的工作目录不存在现象Claude 启动后报路径错误解法确认cwd指向的目录存在且有正确的文件结构本文档由枢归档供星核 Agent 体系内部参考。