# 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）](https://octohz.com/resources/item/19)，`--backend codex`（`http://127.0.0.1:41241`） | ✅ 已发布，需 Bridge 2.0.2+ |
| Claude Code | [OctoHz A2A Adapter（资源 19）](https://octohz.com/resources/item/19)，`--backend claude`（`http://127.0.0.1:41242`） | ✅ 已发布，需 Bridge 2.0.2+ |
| DeepSeek Harness | [OctoHz A2A Adapter（资源 19）](https://octohz.com/resources/item/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 为例，其他系统换文件名）：

```bash
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）**：

```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
```

安装并确认版本：

```bash
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 就按上面直接下载）：

```bash
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 （我的资料 → 密码库 → 智能互通）。

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

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

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

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

```bash
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）

```bash
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 停止）：

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

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

- **Linux / macOS（最省事，以 root 运行，无加固）**
  ```bash
  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）**
  ```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）里，**只配置本机虚拟地址**：

```yaml
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`）：

```bash
# 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](https://octohz.com/resources/item/19)（资源 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 的密钥、设备凭证、配置都在状态目录里，**升级不需要重新认领**，也不需要新的注册码：

```bash
# 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 秒内恢复。


---

**分类**：Octohz Agent 教程
**链接**：https://octohz.com/docs?doc=86