将自定义 Agent 接入扣子 Coze：以 Hermes Agent 为例的完整实战指南

引言2026 年 6 月扣子Coze发布了 3.0 版本。这次更新的核心亮点之一是多 Agent 协作与项目空间——你可以把本地跑的编程 Agent如 Claude Code、Codex CLI、OpenClaw接入扣子在统一的对话界面里 调用它们让它们与扣子云端 Agent 协同完成任务。听起来很美好对吧但如果你用的 Agent 不在官方支持的三种框架列表里呢本文记录了一次真实的“破门而入”经历将一台本地运行的 Hermes Agent v0.16.0 接入扣子 3.0 的完整过程。从逆向分析扣子的检测逻辑到编写 Shim Wrapper 伪装身份再到部署配对——每一步都附带踩坑记录希望能帮到有类似需求的开发者。背景知识在动手之前有几个核心概念需要先搞清楚。ACPAgent Client ProtocolACP 是一种基于 JSON-RPC 2.0 over stdio 的 Agent 通信协议。你可以把它理解为 Agent 世界的“USB 接口”——只要你遵循这个协议任何 Agent 都能和任何客户端对话。目前支持 ACP 协议的 Agent 框架包括 Claude Code、Codex CLI、OpenClaw、Hermes 等。它们都通过标准输入/输出stdin/stdout交换 JSON-RPC 消息这意味着通信链路极其简单没有 HTTP 服务器没有 WebSocket没有端口绑定——一个子进程就是一切。coze-bridge扣子的桥接组件coze-bridge 是扣子桌面端的一个后台组件职责是发现本地已安装的 Agent 框架检测它们的版本和可用 Agent 列表建立与选定 Agent 的 ACP 通信连接转发扣子云端发来的任务请求你可以把 coze-bridge 想象成一个“前台接待”——它先检查你带了什么证件版本号、Agent 列表确认身份后才放行。Hermes Agent我们的主角Hermes Agent v0.16.0 是一个支持 ACP 协议的本地 AI Agent由社区开发。它的特点是原生支持 ACPJSON-RPC 2.0 over stdio可配置不同的底层模型本文作者使用的是 kimi-k2.7-code支持插件集成如微信集成工作空间和二进制文件位于%USERPROFILE%\AppData\Local\hermes\Hermes 的 ACP 二进制文件路径为%USERPROFILE%\AppData\Local\hermes\hermes-agent\venv\Scripts\hermes-acp.exe官方标准接入方式在开始“野路子”之前先看看正规流程是什么样的。对于扣子原生支持的三种框架Claude Code、Codex CLI、OpenClaw接入非常丝滑确保本地已安装对应的 Agent 工具打开扣子桌面端进入「设置」→「本地 Agent」系统自动识别本地已安装的 Agentcoze-bridge 在后台默默完成了检测选择要接入的 Agent点击「添加」在项目空间中即可 调用本地 Agent整个过程不需要手动配置任何参数coze-bridge 会自动在系统 PATH 中找到对应的二进制文件完成版本校验和 Agent 列表获取。但问题是——Hermes 不在那三种框架里。coze-bridge 的检测逻辑是硬编码的它只认 claude、codex、openclaw 这三个名字。实战为非官方 Agent 创建 Shim Wrapper核心思路既然 coze-bridge 只认 OpenClaw那我们就伪装成 OpenClaw。具体做法创建一个“垫片”Shim程序放到系统 PATH 里让 coze-bridge 以为它在调用 OpenClaw但实际上所有 ACP 请求都被透传给了 Hermes Agent。这就像你去一个只认会员卡的老式健身房你办了一张别人的卡——前台扫码时显示的是会员信息但实际进去训练的是你。第一步逆向分析 coze-bridge 的检测逻辑要让伪装成功首先得搞清楚 coze-bridge 到底在检查什么。通过逆向分析 coze-bridge 的源码我们还原了它检测 OpenClaw 的完整流程阶段一二进制发现coze-bridge 在系统全局 PATH 中搜索名为openclaw的可执行文件。注意它用的是which不是where也不是遍历 PATH 逐个目录查找——这意味着二进制文件的名称和位置必须完全正确。which openclaw阶段二版本校验要求返回一个合法的版本号字符串。这一步比较简单只要不是空输出就行。openclaw --version阶段三Agent 列表获取这是最关键的一步。coze-bridge 要求返回一个标准格式的 JSON 数组数组中至少包含一个带有isDefaulttrue标记的 Agent 条目。期望的输出格式如下openclaw --log-level silent agents list --json[{id:agent-name,workspace:/path/to/workspace,isDefault:true}]阶段四缓存刷新在执行配对pair操作之前coze-bridge 会自动调用detectAll()函数刷新~/.coze/bridge/config.json中的frameworksCache字段。如果你之前检测失败过这个缓存可能记录了“未检测到 OpenClaw”的状态需要手动清理或等待自动刷新。第二步开发 Wrapper 脚本分析清楚了检测逻辑接下来就是编写 wrapper。我们选择了 Windows 批处理脚本.cmd因为它无需额外运行时依赖且能被 Windows 的 which 等价操作识别。以下是openclaw.cmd的核心逻辑echo off setlocal enabledelayedexpansion REM REM OpenClaw Shim Wrapper for Hermes Agent REM REM --- 参数路由 --- REM 情况1: --version 查询 if %~1--version ( echo 0.1.0 exit /b 0 ) REM 情况2: Agent 列表查询 REM 完整命令: openclaw --log-level silent agents list --json if %~1--log-level ( if %~2silent ( if %~3agents ( if %~4list ( if %~5--json ( echo [{id:hermes-agent,workspace:%USERPROFILE%\\AppData\\Local\\hermes\\workspace,isDefault:true}] exit /b 0 ) ) ) ) ) REM 情况3: 所有其他请求 → 透传给 Hermes ACP set HERMES_ACP%USERPROFILE%\AppData\Local\hermes\hermes-agent\venv\Scripts\hermes-acp.exe %HERMES_ACP% %* exit /b %ERRORLEVEL%关键设计点参数路由脚本根据传入的参数决定行为。--version和agents list走本地应答分支其余所有参数原封不动传给 Hermes ACP。透传机制%*表示将所有原始参数透传给 Hermes ACP 二进制确保 ACP 协议的完整通信不受影响。退出码传递exit /b %ERRORLEVEL%确保 Hermes ACP 的退出码被正确传递回 coze-bridge。这个脚本的本质是一个协议感知的路由器——它在应用层拦截了 coze-bridge 的身份检测请求同时对底层的 ACP 通信完全透明。第三步部署与 PATH 配置踩坑重灾区写好 wrapper 后下一个问题就是放到哪里。这一步是整个过程中踩坑最多的环节。尝试一放在本地应用目录最初将openclaw.cmd放到%USERPROFILE%\AppData\Local\hermes\openclaw.cmd虽然这个目录在用户的某些 PATH 配置里但 coze-bridge 的which命令找不到它。原因coze-bridge 可能使用的 which 实现只扫描系统级 PATH不包含用户级 PATH。尝试二复制到 WindowsApps 目录这是 Windows 10/11 的应用别名目录通常在 PATH 中。但实际操作时发现Windows 的 App Alias 机制会拦截对这个目录的文件访问——系统把它当作 Microsoft Store 应用的跳转入口而不是一个普通的文件目录。手动放入的文件会被系统忽略或覆盖。尝试三添加用户级 PATH 环境变量通过「系统属性」→「环境变量」添加了用户级 PATH 条目。但问题在于环境变量修改后已经运行的进程不会自动获取新的 PATHcoze-bridge 作为桌面端的后台进程需要重启才能感知到 PATH 变化即使重启某些 Windows 版本对 PATH 的解析顺序也可能导致找不到最终方案System32C:\Windows\System32是 Windows 系统的全局可执行文件目录始终在系统 PATH 的最前面。把 wrapper 放在这里coze-bridge 的which openclaw必定能找到。⚠️ 注意写入 System32 需要管理员权限。可以通过管理员身份的 CMD 或 PowerShell 执行copy openclaw.cmd C:\Windows\System32\openclaw.cmd第四步验证检测通过部署完成后手动验证每一步检测C:\ openclaw.cmd --version 0.1.0 C:\ openclaw.cmd --log-level silent agents list --json [{id:hermes-agent,workspace:%USERPROFILE%\\AppData\\Local\\hermes\\workspace,isDefault:true}]两条命令的输出都符合 coze-bridge 的预期格式。第五步执行配对打开扣子桌面端进入「设置」→「本地 Agent」执行 coze-bridge 配对命令。系统输出✅ 已配对连接完成Hermes Agent 成功接入扣子 3.0。在后续的项目空间中可以通过 OpenClaw 来调用它——虽然名字显示的是 OpenClaw但实际干活的是 Hermes。踩坑记录与排障指南整个过程中遇到的主要问题汇总如下方便遇到类似情况的同学快速定位。坑一PATH 解析的层级问题现象wrapper 文件明明存在但 coze-bridge 就是找不到。原因Windows 的 PATH 解析有系统级和用户级之分。coze-bridge 内部的 which 实现可能只扫描系统级 PATH。此外Electron 应用扣子桌面端基于 Electron在启动时获取的 PATH 可能与终端中的 PATH 不同。解决方案直接放到C:\Windows\System32\。这是最暴力但最可靠的方式。如果你不想“污染”系统目录可以尝试添加系统级而非用户级PATH 环境变量修改后重启扣子桌面端不是最小化是彻底退出再启动坑二frameworksCache 缓存现象wrapper 部署成功后coze-bridge 仍然报告“未检测到 OpenClaw”。原因coze-bridge 在~/.coze/bridge/config.json中维护了一个frameworksCache字段缓存了之前的检测结果。如果之前检测失败这个缓存会“记住”失败状态。解决方案等待自动刷新coze-bridge 在执行配对操作前会自动调用detectAll()刷新缓存手动清理编辑~/.coze/bridge/config.json清空frameworksCache字段重启 coze-bridge 进程坑三积分报错 Credit balance is too low现象配对完成后实际调用时报错Credit balance is too low (code: -32603)但网页端显示积分充足359,623 积分。可能原因PAT Token 关联的积分池不同桌面端使用的 Personal Access TokenPAT可能与网页端登录的账号关联不同的积分池或配额计划项目级配额限制某些项目空间可能有独立的配额上限后端临时异常积分服务的 API 与 Agent 调用服务之间存在延迟或状态不一致排查建议确认 PAT Token 对应的账号与网页端一致检查项目空间的配额设置等待一段时间后重试如果是后端临时异常联系扣子官方支持客服虾kzfeedbackcoze.email坑四Windows App Alias 拦截现象将文件放到 WindowsApps 目录后命令行执行时跳转到 Microsoft Store 而非执行脚本。原因Windows 10/11 默认启用了“应用执行别名”App Execution Alias功能。当你在命令行输入一个与 Microsoft Store 应用同名的命令时系统会优先跳转到 Store 应用而不是执行本地文件。解决方案不要使用 WindowsApps 目录或者在「设置」→「应用」→「高级应用设置」→「应用执行别名」中关闭相关开关技术原理与可扩展性讨论Shim Wrapper 模式的本质我们在这次实战中使用的 Shim Wrapper 模式本质上是一种接口适配层技术。它在操作系统层面伪装成一个已知的二进制文件将请求透明地转发给实际的目标程序。这种模式在软件工程中有着广泛的应用场景Shim 伪装成实际连接到本文案例OpenClawHermes AgentAPI 版本兼容v1 API endpointv2 后端服务工具链迁移旧版 CLI 工具新版替代工具游戏模组原始游戏 DLL修改后的 DLL其核心优势在于不需要修改任何一方的代码。扣子的 coze-bridge 不需要知道 Hermes 的存在Hermes 也不需要知道扣子的检测逻辑。一切适配工作都在操作系统层面的 wrapper 中完成。ACP 协议的开放性这次成功的根本前提在于 ACP 协议的标准化。由于 Hermes 和 OpenClaw 都实现了相同的 ACP 协议JSON-RPC 2.0 over stdiowrapper 只需要处理“身份伪装”返回正确的版本号和 Agent 列表实际的 ACP 通信可以完全透传无需任何协议转换。如果两个 Agent 使用不同的通信协议那就需要在 wrapper