首页文档Octohz Agent 教程OctoHz 智能互通：Bridge 安装与联调教程

OctoHz 智能互通：Bridge 安装与联调教程

OctoHz 智能互通：给一台机器装上 Bridge（教程）

适用版本：octohz-agent-bridge 2.0.2（只实现 A2A 1.0，不兼容 v0.3，也不放行 1.1/2.0 等未实现版本）。目标：让一台机器上的智能体（Hermes 等）加入 OctoHz 智能互通，能和其他机器上的智能体互相调用，并由 OctoHz 统一管理身份、授权和审计。

0. 先搞清楚：每台机器要装什么

只装一个文件：octohz-agent-bridge。 它是静态单文件，不需要装 Node、Python、Java 或任何运行时，不依赖数据库。

但机器上必须已经有一个在运行的 A2A 服务（Bridge 只是它前面的“门卫”，不负责智能体本身）：

智能体	本机 A2A 服务	现状
Hermes	Hermes 自带的原生 A2A，通常 `http://127.0.0.1:9900`	✅ 可以直接接入
Codex	OctoHz A2A Adapter（资源 19），`--backend codex`（`http://127.0.0.1:41241`）	✅ 已发布，需 Bridge 2.0.2+
Claude Code	OctoHz A2A Adapter（资源 19），`--backend claude`（`http://127.0.0.1:41242`）	✅ 已发布，需 Bridge 2.0.2+
DeepSeek Harness	OctoHz A2A Adapter（资源 19），`--backend harness`（`http://127.0.0.1:41243`）	✅ 已发布，需 Bridge 2.0.2+
其他模型 API	需要通用 Model A2A Adapter	⚠️ 还没做，暂时不能接入

三个后端由同一个官方适配器程序提供（Windows / macOS / Linux 通用，含 service install 装成开机自启服务），严格 A2A 1.0、默认只读、只监听 127.0.0.1，默认端口错开，同机每个后端各开一个进程即可并存。权限档位、已验证与未验证的平台见资源页。

每台机器还需要：

系统时间准确（开启 NTP）。票据只有 30 秒容差，时间偏差大会被大面积拒绝。
能出站访问 https://octohz.com（443），用于心跳、申请票据、Relay。
如果要让同一局域网的机器直连：放行本机 9910 端口（入站）。不想开放端口也可以，只走 Relay（Bridge 会主动出站连接）。

1. 下载并校验

二进制放在 OctoHz 网站的固定地址，不需要登录、不需要令牌：

https://octohz.com/downloads/agent-bridge/2.0.2/

按目标机器的系统选择文件：

系统	文件名
Linux x86_64	`octohz-agent-bridge-linux-amd64`
Linux ARM64	`octohz-agent-bridge-linux-arm64`
Windows 10/11 x64	`octohz-agent-bridge-windows-amd64.exe`
macOS Apple 芯片	`octohz-agent-bridge-darwin-arm64`
macOS Intel	`octohz-agent-bridge-darwin-amd64`

Linux / macOS（以 Linux x86_64 为例，其他系统换文件名）：

cd /tmp
curl -fsSLO https://octohz.com/downloads/agent-bridge/2.0.2/octohz-agent-bridge-linux-amd64
sha256sum octohz-agent-bridge-linux-amd64          # macOS 用：shasum -a 256 文件名

Windows（PowerShell）：

Invoke-WebRequest https://octohz.com/downloads/agent-bridge/2.0.2/octohz-agent-bridge-windows-amd64.exe -OutFile octohz-agent-bridge.exe
(Get-FileHash .\octohz-agent-bridge.exe -Algorithm SHA256).Hash.ToLower()

必须校验 SHA-256，并且以下表为准（2.0.2）。输出必须和对应行完全一致，不一致就停下，不要运行，也不要改用服务器上的 SHA256SUMS（它和二进制在同一个地方，不能作为独立依据）：

0f13c2dd976b20d11ee1ee057ff3cbf6fe73df4b1da67e16d32b45762fc2c634  octohz-agent-bridge-linux-amd64
b968addd1a148f941a8ef884c56362400afb26b970b995047fd9f8a4dbb30314  octohz-agent-bridge-linux-arm64
f3b190e4fb0742515c02dd852dede80df1a22e91110ccb86cc0547c6c80e624b  octohz-agent-bridge-windows-amd64.exe
7fb045f2c7343337f9f5af1a0e4f15e186035c7a04e5fce4c29a356ab095c700  octohz-agent-bridge-darwin-arm64
334b5ca817d89c586eeaab25f272f964c5b8750e7926156c030de86095ebdea9  octohz-agent-bridge-darwin-amd64

安装并确认版本：

sudo install -m 0755 /tmp/octohz-agent-bridge-linux-amd64 /usr/local/bin/octohz-agent-bridge
octohz-agent-bridge version        # 应显示 octohz-agent-bridge 2.0.2

Windows：把 octohz-agent-bridge.exe 放到固定目录（例如 C:\octohz-agent-bridge\），后面命令里的 octohz-agent-bridge 换成该 exe 的完整路径。

也可以用 OctoHz CLI 一键安装（可选，需要 Node 18+；不想装 Node 就按上面直接下载）：

npm i -g octohz@2.15.1          # 需要 2.15.1 或更新
octohz agent bridge install     # 自动识别系统和 CPU，下载对应文件，并用 CLI 内置的 SHA-256 校验，不通过就拒绝安装
octohz agent bridge version     # 之后所有 Bridge 命令都可以写成 octohz agent bridge <命令>

CLI 里的哈希表随 npm 包发布，与下载服务器相互独立；Bridge 出新版本时需要先升级 CLI 才能装到新版本。适配器也已随 CLI 一起提供（octohz agent adapter ...）。默认装到 ~/.octohz/bin，可用 --dir 指定。

2. 在 OctoHz 网页里先建好节点

打开 https://octohz.com/my/agent-hub （我的资料 → 密码库 → 智能互通）。

局域网标签 → 创建局域网（例如“家里”）。同一个局域网里的节点才能看到彼此的局域网地址。已经建过就跳过。
智能体标签 → 创建智能体：
- 节点类型：选 Hermes
- 节点名称：例如“二娃”（agent_id 由系统生成，不用填）
- 所属局域网：选“家里”
- 允许谁调用：勾选具体的智能体名称（不是类型）。不勾就是拒绝所有其他节点。
- 允许的权限：默认“全部”只针对被勾选的智能体
点 创建并获取注册码，得到形如 ABCD-EFGH 的注册码。

注册码 10 分钟内有效，只显示一次，用一次就作废。 拿到后马上做第 3 步。过期了就到该智能体的编辑抽屉里点“重新获取注册码”。

3. 在目标机器上认领（setup）

--upstream 填这台机器上 A2A 服务的地址，只允许回环地址（127.0.0.1）。--san 填这台机器在局域网里的 IP（用于自签名证书）。

octohz-agent-bridge setup \
  --code ABCD-EFGH \
  --upstream http://127.0.0.1:9900 \
  --san 192.168.38.191

成功时会依次看到：✓ 已生成本机密钥、✓ 认领成功，节点 ID: …、✓ 已生成自签名证书、✓ 配置已写入 …，并打印“本节点将上报”的地址。

参数说明：

参数	含义
`--code`	第 2 步的注册码
`--upstream`	本机 A2A 服务地址（仅回环）
`--upstream-token-env NAME`	如果本机 A2A 服务需要静态 Token：Token 放进环境变量 `NAME`，配置里只记变量名
`--san IP或域名`	自签名证书的地址，可重复；不写则自动取本机内网 IP
`--port` / `--local-port`	对外端口（默认 9910）/ 本机虚拟入口端口（默认 9911，仅 127.0.0.1）
`--no-relay`	不使用 Relay（不建议）
`--host`	对外监听地址，默认 `0.0.0.0`（启用 TLS 时）；只想在某块网卡上监听时才改
`--public-url URL`	对外可达地址，如 `https://192.168.38.191:9910`；机器有多块网卡、自动取到的内网 IP 不对时用它指定（会作为局域网端点上报）
`--no-tls`	关闭 TLS，仅本机开发：此时强制只监听 `127.0.0.1`，别的机器连不上
`--base-url URL`	OctoHz 地址，默认 `https://octohz.com`；一般不用改
`--dev-insecure`	仅本机开发：允许 `http://` 的 OctoHz 与直连地址；正式环境不要用
`--config` / `--state-dir`	配置文件 / 状态目录位置（用专用账号跑服务时才需要，见下面的默认路径）

默认配置路径（不写 --config 时）：

系统 / 用户	配置文件	状态目录（密钥、凭证、证书）
Linux，root	`/etc/octohz-agent-bridge/config.yaml`	`/var/lib/octohz-agent-bridge`
Linux / macOS，普通用户	`~/.octohz-agent-bridge/config.yaml`	`~/.octohz-agent-bridge`
macOS，root	`/var/lib/octohz-agent-bridge/config.yaml`	`/var/lib/octohz-agent-bridge`
Windows	`%ProgramData%\octohz-agent-bridge\config.yaml`	`%ProgramData%\octohz-agent-bridge`

setup、doctor、run、status、service 默认都读这个路径，必须用同一个用户执行，否则会找不到配置；setup 结尾打印的“配置已写入 …”就是准确路径，也可以每次都显式加 --config。

参数写错不会浪费注册码：上游地址不合法、OctoHz 地址不是 https 这类错误，会在消耗注册码之前就报出来。

不需要在网页里填 IP、端口、Relay 地址：连接端点、能力、A2A 版本都由 Bridge 上线后自动上报。

4. 检查环境（doctor）

octohz-agent-bridge doctor

每项前面是 ✓ 正常、! 警告、✗ 失败。如果还没有执行过第 3 步 setup（找不到配置文件），doctor 会在第一项“配置文件”就失败并直接退出，只打印一行 ✗ 配置文件 … no such file or directory 和“1 项检查未通过”，后面的检查都不会跑——先完成 setup（或用 --config 指向正确路径），再看下面这些项。重点看：

本机上游：应为 ✓，说明 127.0.0.1:9900 的 A2A 服务在跑
OctoHz 登录：应为 ✓
系统时间：偏差应在 10 秒内
JWKS、Relay：应为 ✓
Bridge 进程：此时还没运行，! 是正常的

有 ✗ 先按下面第 8 节排查，再继续。

5. 运行

先前台试跑（Ctrl+C 停止）：

octohz-agent-bridge run

看到 Bridge 已启动 和 已连接 Relay 就对了。回到网页“智能体”标签，这个节点应该显示在线。

装成系统服务（开机自启、崩溃自动拉起）：

Linux / macOS（最省事，以 root 运行，无加固）
```
sudo octohz-agent-bridge service install
sudo octohz-agent-bridge service start
```
注意：setup 和 service install 必须用同一个用户执行（这里都用 root）。服务读取该用户的默认配置：Linux root 是 /etc/octohz-agent-bridge/config.yaml，状态在 /var/lib/octohz-agent-bridge；macOS root 的配置在 /var/lib/octohz-agent-bridge/config.yaml。setup 结尾打印的“配置已写入 …”就是准确路径。所以用 sudo 装服务时，第 3 步的 setup 也要加 sudo。
Linux（更严格的隔离）：可改用专用账号 + systemd 加固运行；需要时向维护者索取部署说明。

Windows（管理员 PowerShell）

.\octohz-agent-bridge-windows-amd64.exe service install
.\octohz-agent-bridge-windows-amd64.exe service start

如果上游 A2A 服务需要 Token：服务模式下要把环境变量设置进服务环境里（systemd 用 sudo systemctl edit octohz-agent-bridge 加 Environment=NAME=值），不要写进配置文件。

查看状态：octohz-agent-bridge status。网页“Bridge 状态”标签也能看到心跳、LAN、Relay 状态，并可点“诊断”。

6. 让本机的智能体去调用别人

在这台机器的智能体（例如 Hermes）里，只配置本机虚拟地址：

a2a_agents:
  codex:
    url: "http://127.0.0.1:9911/a2a/<对方的 agent_id>"

<对方的 agent_id> 在网页智能体编辑抽屉里点“节点 ID”复制（默认缩略显示，点击复制）。Bridge 会自动完成：找对方地址、申请短期票据、选择局域网直连或 Relay、加上鉴权头。对方的 Agent Card 会被改写成这个虚拟地址，所以不会绕过 Bridge。

前提：对方节点的“允许谁调用”里勾选了本机这个智能体，并且两边 Bridge 都在线。

7. 联调（验证整条链路）

在调用方机器上执行（把 codex-xxxx 换成对方的 agent_id）。所有请求都必须显式带 A2A-Version: 1.0 头（方法 SendMessage、role 用 ROLE_USER、Part 没有 kind，用 mediaType）：

# 1) 读对方 Agent Card：看 supportedInterfaces[].url，应是 http://127.0.0.1:9911/a2a/codex-xxxx
curl -s -H 'A2A-Version: 1.0' http://127.0.0.1:9911/a2a/codex-xxxx/.well-known/agent-card.json

# 2) 发一条消息（A2A v1.0）
curl -s -X POST http://127.0.0.1:9911/a2a/codex-xxxx -H 'Content-Type: application/json' -H 'A2A-Version: 1.0' -d '{
  "jsonrpc":"2.0","id":1,"method":"SendMessage",
  "params":{"message":{"role":"ROLE_USER","messageId":"m-1","contextId":"demo-1",
  "parts":[{"text":"你好，这是一次联调，请回复 pong","mediaType":"text/plain"}]}}}'

目前只实现 A2A 1.0，只接受精确的 A2A-Version: 1.0，不兼容 v0.3。 缺少 A2A-Version 头、版本不是 1.0（如 0.3、1.1、2.0）、格式不对（v1.0、1），或使用 v0.3 方法名（message/send）都会得到 VersionNotSupportedError（HTTP 400 / -32009），请求不会被转发，活动记录标“协议版本不兼容”。对方那台机器上的 A2A 服务也必须是 v1.0：它的 Agent Card 没声明 v1.0，网页会标“协议版本不兼容”。第三方旧版 Agent 请先升级，或另外部署适配器（Bridge 内不做转换）。 v1.0 相对 v0.3 的破坏性变化：kind 被移除、role 改为 ROLE_USER / ROLE_AGENT、任务状态改为 TASK_STATE_*、方法名改为 PascalCase、响应改为 {"task": {…}} 包装。

成功后到网页“活动记录”标签，应该看到一条：发信方 → 收信方、发信方式（局域网直连 / OctoHz Relay）、最终结果（成功 / 失败 / 被拒绝，如上游 401 记为失败）、耗时。点开可看任务 ID、Context ID、Scope；不会显示任务正文。

关于活动记录：局域网直连和公网直连的流量不经过 OctoHz，OctoHz 无法直接观察，这条记录是两端 Bridge 各自主动上报的元数据（不含任务正文）。每次调用有一个全局唯一的 call_id，两端上报的记录用它对应。

1.2.0 起：事件先写入本机的持久队列（audit-queue.jsonl，最多 10000 条 / 20 MB / 保存 7 天）再上报；OctoHz 暂时不可用、Bridge 重启都不会丢，恢复后自动补报，重复上报不会产生重复记录。队列超限会淘汰最旧的记录，并把累计丢弃数上报，网页“Bridge 状态 → 诊断”里的“活动记录上报”一行能看到待补报条数和丢弃数。

1.1.x 及更早版本没有重试：上报那一刻 OctoHz 不可用，这次记录就会丢失，请升级。

还没有：事件签名、两端记录合并、“记录来源可信度”标记（服务端观测 / 节点上报 / 双方确认）。目前活动记录列表显示的是调用方上报的那一条；接收方上报的和 Relay 服务端观测的记录已入库，但暂不显示、也不与调用方的记录合并核对。所以“活动记录里没有这条”不等于“这次调用没有发生”。

预期的错误反应（说明护栏在工作）：

没被授权 → 403（“无法获得访问目标节点的票据”）
同一个 contextId 来回超过 5 轮 → 返回状态 TASK_STATE_REJECTED
消息里带 API Key / JWT / Bearer Token → 到对方时已被替换成 [REDACTED]
对方收到的文本前面会带 [UNTRUSTED EXTERNAL AGENT INPUT from …]，这是预期行为

8. 排错

先运行 octohz-agent-bridge doctor。

现象	处理
`setup` 提示“注册码无效或已过期”	10 分钟有效且只能用一次；网页里“重新获取注册码”。连续猜错会被限流（429），等几分钟
`doctor` 的“本机上游”失败	本机 A2A 服务没启动，或 `--upstream` 端口错了（重新 setup 不需要新注册码：已认领会沿用密钥）
`doctor` 的“系统时间”失败	校准时间（NTP）
网页显示节点“离线”	Bridge 没在跑，或不能出站访问 octohz.com；`status` / 服务日志查看
网页显示“异常”	心跳在线但自检有失败项，点“Bridge 状态 → 诊断”看是哪一项。若诊断里只有“系统时间”偏差约 30 秒且机器时间其实准确，是 1.1.1 及以前版本的已知缺陷，升级到 1.1.2
调用方拿到 `403`	目标节点的“允许谁调用”没勾选调用方，或权限不够
调用方拿到 `401`	票据无效：多半是系统时间偏差
调用方拿到 `502 无法连接目标节点`	局域网不可达且 Relay 也不通；确认两边 Bridge 都在线，且目标能连上 Relay
一直走 OctoHz Relay，不走局域网	两个节点没有加入同一个局域网（或没设置网络互通），或目标没放行 9910

9. 吊销与卸载

吊销节点：网页“智能体”→ 编辑 →“吊销”（红色）。之后立即停止心跳和票据，已签发的票据最长 5 分钟内自然失效；可以“恢复”。
本机彻底退出：octohz-agent-bridge revoke --yes（通知 OctoHz 禁用，并删除本机密钥与凭证，不可恢复）。之后重新接入要在网页“重新获取注册码”再 setup。
卸载服务：sudo octohz-agent-bridge service stop && sudo octohz-agent-bridge service uninstall，再删除二进制。

10. 已知限制（2.0.2）

超时：Bridge 等本机上游返回的时间默认 3 分钟（配置 upstream.response_timeout），整体请求上限 10 分钟（security.request_timeout）。超时会返回 504（upstream_timeout / target_timeout）并在活动记录里标失败；等待超时后 Bridge 不会换连接方式重发（目标可能仍在执行）。任务经常超过几分钟的，请用流式响应，或让上游立即返回 task_id 再用 GetTask 查询。
Codex、Claude Code、DeepSeek Harness 已由官方 OctoHz A2A Adapter（资源 19）统一提供，见第 0 节；原先分开发布的资源 16 / 17 / 18 已下线。通用模型 Adapter 还没做。
Push 回调默认拒绝（回调签名链路未实现）。
活动记录靠 Bridge 上报：1.2.0 起有持久队列与重试，但暂无事件签名、两端合并、来源可信度标记（见第 7 节说明）。
1.1.0 存在 A2A v1.0 兼容缺陷，1.1.1 及以前存在“节点第二个心跳起被误判为异常”的缺陷（时钟偏差算错），请使用 2.0.2 或更新版本（1.2.0 起活动记录不再因 OctoHz 暂时不可用而丢失；2.0.0 起只支持 A2A 1.0 并按最终结果记录；2.0.0 会错误放行 1.1/2.0，请勿使用）。
下载地址是公开的（不需要登录）；防篡改靠本文档里的哈希表，所以请一定按第 1 节校验。
Linux 的 systemd 服务、Windows 服务模式没有在真实机器上验证过；如果你是第一批安装的人，遇到问题请把 doctor 输出和服务日志（不含任何令牌）发给维护者。
没有接入真实的 Hermes 联调；已经用模拟的上游服务和真实 Relay 跑通了直连与 Relay 两条路径。

11. 升级到新版本

Bridge 的密钥、设备凭证、配置都在状态目录里，升级不需要重新认领，也不需要新的注册码：

# 1) 下载新版本并按第 1 节校验哈希
cd /tmp && curl -fsSLO https://octohz.com/downloads/agent-bridge/2.0.2/octohz-agent-bridge-linux-amd64 && sha256sum octohz-agent-bridge-linux-amd64
# 2) 停止 → 替换 → 启动（作为服务运行时）
sudo systemctl stop octohz-agent-bridge          # 或：sudo octohz-agent-bridge service stop
sudo install -m 0755 /tmp/octohz-agent-bridge-linux-amd64 /usr/local/bin/octohz-agent-bridge
octohz-agent-bridge version                      # 确认新版本号
sudo systemctl start octohz-agent-bridge         # 或：sudo octohz-agent-bridge service start

前台运行的：Ctrl+C 停止，替换文件后重新 octohz-agent-bridge run。网页“Bridge 状态”里节点约 30 秒内恢复。