如何把自己开发的AI代理接入acpx自定义代理与.acpxrc.json配置完整指南【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpxacpx是一个无头headlessCLI 客户端用于管理有状态的 Agent Client ProtocolACP会话。本指南面向新手手把手教你把自己开发的 AI 代理接入 acpx从最快的“一行命令”试跑到用项目级配置文件.acpxrc.json注册一个可随时调用的自定义代理名称并说明你的代理需要满足哪些 ACP 协议要求。一、先搞清楚acpx 和自定义代理是什么关系简单来说acpx 负责“管会话”你的代理负责“干活”acpx启动你的 ACP 服务器进程、管理持久会话、处理权限、输出结构化事件你的代理一个能通过标准输入输出stdio说 ACP 协议的命令比如node ./scripts/acp-server.mjs两者之间JSON-RPC 2.0 over stdio。官方内置了 codex、claude 等 20 多个代理适配器见 docs/agents.md但不要求你的代理在内置注册表里——任何会说 ACP 的命令都能接入详见 docs/custom-agents.md。二、接入自定义代理的 3 种方式由快到稳1️⃣ 直接把命令名当参数最快试跑在 Unix 类系统上一个既不在内置注册表、也未配置的代理名会被当作原始命令直接执行。只要你的代理二进制已在PATH里acpx my-agent review this patch acpx my-agent sessions newmy-agent这个字符串就是被 spawn 的命令。适合快速验证你的 ACP 服务器能否跑通。2️⃣--agent逃生舱带参数/路径时命令带参数或特殊路径时用--agent commandacpx --agent ./bin/my-custom-acp-server do something acpx --agent node ./scripts/acp-dev-server.mjs --mode ci exec summarize changes注意两条规则来自 docs/custom-agents.md--agent不能和位置参数代理名同时出现否则报用法错误整条命令字符串会成为会话作用域键的一部分——两个不同的命令串就是两个不同的会话。 Windows 上自定义启动必须用下面第 3 种“配置式argv”方式--agent仅支持 Unix。3️⃣ 配置文件注册具名代理推荐可复用把命令写进配置文件后就能用友好名字调用这也是团队里最稳的接入方式{ agents: { ci-bot: { argv: [node, ./scripts/ci-acp-bridge.mjs, --profile, internal] } } }之后任意目录里都能这样用acpx ci-bot sessions new acpx ci-bot run validation checks三、.acpxrc.json 完整解析1. 两个配置文件与优先级acpx 通过两个 JSON 文件配置完整说明见 docs/config.md优先级文件作用范围1最高CLI 命令行参数当次调用2项目/.acpxrc.json当前仓库3~/.acpx/config.json全局项目配置是叠加在全局之上的部分覆盖缺失的键继承全局agents和auth按键合并。用acpx config show可随时查看合并后的最终结果。2.agents字段怎么写键是你敲命令时用的友好名acpx 名字 …argv是推荐写法第一项是可执行文件其余每一项原样作为一个参数传递天然规避 shell 引号问题与内置代理同名会直接覆盖内置代理——比如把codex指向你内部打包的适配器{ agents: { codex: { argv: [/usr/local/bin/codex-acp, --profile, stable] } } }旧的{ command: …, args: […] }写法在command是无空格裸命令时会自动迁移带引号的命令会被拒绝建议一律改用argv。3. Windows 特别注意Windows 不能直接执行.sh文件也不会替你猜解释器需要显式写出{ agents: { my-agent: { argv: [bash, C:\\tools\\bin\\agent.sh] } } }4. 鉴权凭证auth如果你的代理在initialize后要求 ACPauthenticate握手凭证按以下顺序解析环境变量ACPX_AUTH_METHOD_ID方法 ID 大写配置文件里的auth映射。{ auth: { my_agent_token: sk-… } }找不到凭证时authPolicy: skip默认会让你的代理自行处理登录fail则直接报错。5. 给某个仓库锁定内部代理的典型.acpxrc.json{ agents: { internal: { command: /opt/internal/acp-bridge, args: [--profile, stable] } } }放进仓库根目录全仓库的acpx internal …都会走这个内部桥接器——这正是 per-repo 覆盖的最佳实践。四、你的代理需要满足哪些 ACP 要求acpx 自带的一致性测试规范 给出了最小可用清单你的自定义代理必须✅ 走 stdio 的 JSON-RPC 2.0请求带唯一id通知不带✅ 实现核心方法initialize、session/new、session/prompt、session/cancel✅initialize响应包含协议版本agentCapabilities若提供必须是 JSON 对象✅session/prompt执行中至少发出一条session/update通知成功时用响应里的stopReason收尾✅ 未知会话 ID、非法参数要返回明确的 JSON-RPC 错误通常是-32602不能静默成功✅ 如实声明模型配置能力ACP 0.25 推荐分类式 model config option。另外fs/*和terminal/*客户端方法会经过 acpx 的权限策略文件操作受工作目录边界约束终端命令不是操作系统级沙箱。五、容易踩的坑会话作用域与消息大小1. 命令字符串就是会话身份会话由三元组(agentCommand, 绝对cwd, 可选name)定界docs/sessions.md。把--agent ./bin/v1升级到./bin/v2会切换作用域旧会话不再被恢复。升级代理二进制时请保持“稳定的可执行路径”原地替换文件内容并确认你的适配器支持恢复已保存的会话。2. 单条 ACP 消息默认上限 64 MiB代理回传的超大结构化消息比如带图片会被ACP_MESSAGE_TOO_LARGE拒绝。可用环境变量ACPX_MAX_ACP_MESSAGE_BYTES调大如134217728 128 MiB设为0则不限制。注意这是每条消息的上限不是内存预算。3.session/new失败时某些 ACP 服务器需要先完成自己的工作区/项目映射才能建会话。先用与服务器预期一致的环境变量和cwd在服务器侧验证项目初始化再重试sessions new。六、验收清单接入完成长这样# 1. 配置已生效 acpx config show # 2. 创建会话并拿到会话 ID acpx ci-bot sessions new # 3. 发送提示词看到 [tool] 事件流和 [done] end_turn acpx ci-bot summarize this repository # 4. 多轮对话自动复用同一会话 acpx ci-bot now propose a one-line fix # 5. 无状态一次性运行不落盘 acpx ci-bot exec list TODO comments如果以上全部跑通恭喜你——自己的 AI 代理已经正式接入 acpx可以像内置代理一样享有持久会话、命名工作流、--format json事件流和权限管控等全部能力参考 docs/quickstart.md 了解更多会话玩法。七、延伸阅读docs/custom-agents.md — 自定义代理三种接入方式与排错docs/config.md — 配置文件全量键位、优先级与鉴权docs/agents.md — 内置代理注册表与覆盖示例agents/OpenClaw.md — 一个“仓库本地覆盖内置代理”的完整案例conformance/spec/v1.md — ACP 一致性规范 v1草稿docs/permissions.md — 权限策略与文件系统护栏【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考