将自定义 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 伪装身份，再到部署配对——每一步都附带踩坑记录，希望能帮到有类似需求的开发者。

背景知识

在动手之前，有几个核心概念需要先搞清楚。

ACP：Agent Client Protocol

ACP 是一种基于 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，由社区开发。它的特点是：

• 原生支持 ACP（JSON-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），接入非常丝滑：

1. 确保本地已安装对应的 Agent 工具
2. 打开扣子桌面端，进入「设置」→「本地 Agent」
3. 系统自动识别本地已安装的 Agent（coze-bridge 在后台默默完成了检测）
4. 选择要接入的 Agent，点击「添加」
5. 在项目空间中即可 @调用本地 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 数组，数组中至少包含一个带有isDefault=true标记的 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 "%~2"=="silent" ( if "%~3"=="agents" ( if "%~4"=="list" ( 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 条目。但问题在于：

• 环境变量修改后，已经运行的进程不会自动获取新的 PATH
• coze-bridge 作为桌面端的后台进程，需要重启才能感知到 PATH 变化
• 即使重启，某些 Windows 版本对 PATH 的解析顺序也可能导致找不到

最终方案：System32

C:\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\。这是最暴力但最可靠的方式。如果你不想“污染”系统目录，可以尝试：

1. 添加系统级（而非用户级）PATH 环境变量
2. 修改后重启扣子桌面端（不是最小化，是彻底退出再启动）

坑二：frameworksCache 缓存

现象：wrapper 部署成功后，coze-bridge 仍然报告“未检测到 OpenClaw”。

原因：coze-bridge 在~/.coze/bridge/config.json中维护了一个frameworksCache字段，缓存了之前的检测结果。如果之前检测失败，这个缓存会“记住”失败状态。

解决方案：

1. 等待自动刷新：coze-bridge 在执行配对操作前会自动调用detectAll()刷新缓存
2. 手动清理：编辑~/.coze/bridge/config.json，清空frameworksCache字段
3. 重启 coze-bridge 进程

坑三：积分报错 Credit balance is too low

现象：配对完成后，实际调用时报错Credit balance is too low (code: -32603)，但网页端显示积分充足（359,623 积分）。

可能原因：

• PAT Token 关联的积分池不同：桌面端使用的 Personal Access Token（PAT）可能与网页端登录的账号关联不同的积分池或配额计划
• 项目级配额限制：某些项目空间可能有独立的配额上限
• 后端临时异常：积分服务的 API 与 Agent 调用服务之间存在延迟或状态不一致

排查建议：

1. 确认 PAT Token 对应的账号与网页端一致
2. 检查项目空间的配额设置
3. 等待一段时间后重试（如果是后端临时异常）
4. 联系扣子官方支持（客服虾：kzfeedback@coze.email）

坑四：Windows App Alias 拦截

现象：将文件放到 WindowsApps 目录后，命令行执行时跳转到 Microsoft Store 而非执行脚本。

原因：Windows 10/11 默认启用了“应用执行别名”（App Execution Alias）功能。当你在命令行输入一个与 Microsoft Store 应用同名的命令时，系统会优先跳转到 Store 应用，而不是执行本地文件。

解决方案：

• 不要使用 WindowsApps 目录
• 或者在「设置」→「应用」→「高级应用设置」→「应用执行别名」中关闭相关开关

技术原理与可扩展性讨论

Shim Wrapper 模式的本质

我们在这次实战中使用的 Shim Wrapper 模式，本质上是一种接口适配层技术。它在操作系统层面伪装成一个已知的二进制文件，将请求透明地转发给实际的目标程序。

这种模式在软件工程中有着广泛的应用：

其核心优势在于：不需要修改任何一方的代码。扣子的 coze-bridge 不需要知道 Hermes 的存在，Hermes 也不需要知道扣子的检测逻辑。一切适配工作都在操作系统层面的 wrapper 中完成。

ACP 协议的开放性

这次成功的根本前提在于 ACP 协议的标准化。由于 Hermes 和 OpenClaw 都实现了相同的 ACP 协议（JSON-RPC 2.0 over stdio），wrapper 只需要处理“身份伪装”（返回正确的版本号和 Agent 列表），实际的 ACP 通信可以完全透传，无需任何协议转换。

如果两个 Agent 使用不同的通信协议，那就需要在 wrapper