@xyagent/cli 0.0.1

package/README.md

@@ -0,0 +1,860 @@
+# @xyagent/cli
+
+把本地 AI runtime（OpenClaw 或 Hermes）接入 Agentlink relay 服务的独立 CLI。
+
+手机端 App 通过 relay 跟本地 runtime 对话，CLI 负责：
+
+- 配对：把手机 App 账号和本地 runtime 绑定到同一个 relay gateway
+- 桥接：长时间运行一个中继 worker，把 relay 队列里的请求拉下来、喂给本地 runtime、再把事件发回 relay
+- 守护：用系统服务（launchd / systemd / Task Scheduler）让桥接在后台常驻
+
+**深入文档**：
+
+- [docs/PAIR_FLOW.md](docs/PAIR_FLOW.md) — `agentlink pair` 完整流程：每一步做了什么、改了哪些文件、`--runtime all` 模式遇到 runtime 缺失怎么处理、对 OpenClaw 配置改动的安全性分析、故障排查 checklist
+- [docs/EXTERNAL_AGENTS.md](docs/EXTERNAL_AGENTS.md) — claude / codex 等外部 agent 接入指南
+- [docs/LOGGING.md](docs/LOGGING.md) — 日志格式与排查
+- [docs/PLATFORM.md](docs/PLATFORM.md) — 跨平台细节（launchd / systemd / Windows）
+- [agentlink-server/TOOL_EVENTS.md](../agentlink-server/TOOL_EVENTS.md) — 工具调用链事件 schema（OpenClaw plugin / Hermes / Codex / Claude → server `session.tool` 字段映射 + 真实样例）
+
+---
+
+## 1. 整体架构
+
+```
+┌────────────────┐    HTTPS / SSE    ┌───────────────────────┐
+│   Mobile App   │◀─────────────────▶│   Relay Server (Go)   │
+│  (nexus_flutter)│                  │  go-relay-test.xyagent.com   │
+└────────────────┘                   │                       │
+                                     │  MySQL + Redis        │
+                                     └───────────┬───────────┘
+                                                 │
+                                 long-poll  +   POST events
+                                                 │
+                                     ┌───────────▼───────────┐
+                                     │   agentlink CLI (Node) │
+                                     │   bin/agentlink        │
+                                     │                       │
+                                     │  ┌─────────────────┐  │
+                                     │  │ Bridge worker   │  │
+                                     │  └────────┬────────┘  │
+                                     └───────────┼───────────┘
+                                                 │
+                ┌───────────────┬────────────────┼────────────────┬──────────────┐
+                │               │                │                │              │
+        (runtime=openclaw) (runtime=hermes) (runtime=claude) (runtime=codex)     │
+                │               │                │                │              │
+        HTTP /v1/responses   agentlink-      agentlink-      agentlink-       (其他 runtime
+                │            agent hermes    agent claude   agent codex       走相同 shim)
+                ▼               ▼                ▼                ▼              ▼
+        ┌────────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
+        │ OpenClaw GW    │  │ Hermes JS  │  │ Claude CLI │  │ Codex MCP  │
+        │ (外部进程)      │  │ HTTP/cmd   │  │ stream-json│  │ stdio      │
+        │ 127.0.0.1:<p>  │  │ backend    │  │            │  │            │
+        └────────────────┘  └────────────┘  └────────────┘  └────────────┘
+```
+
+**核心架构（重构后）**：4 种 runtime 走**完全统一的 long-poll 模式**，CLI 端不做协议翻译。
+
+```
+启动 (任意 runtime bridge)
+  │
+  1. POST /v1/pair-codes/<code>/consume
+       body  { client_user_id, runtime }
+       resp  { gw_id, bridge_token, runtime }
+  │
+  2. 持久化 ~/.agentlink/ext-<runtime>-last.json
+  │
+  3. long-poll loop（永不退出）：
+       ┌─ GET /v1/gateways/<gw>/requests/next?waitSeconds=25
+       │    Bearer <bridge_token>
+       │    ↓ 拿到 user request
+       │
+       ├─ 调本地 runtime（LLM HTTP / Claude CLI / Codex MCP / OpenClaw HTTP）
+       │
+       ├─ 流式 POST /v1/gateways/<gw>/requests/<rid>/events
+       │    body 是该 runtime 的 native 事件（stream-json / OpenAI SSE chunk / codex/event 等）
+       │    ↑↑↑ 服务端 internal/adapter/<runtime>/ 翻译为统一信封
+       │
+       └─ 心跳 POST /v1/gateways/<gw>/meta（每 10s）
+```
+
+**关键特征（重构后）**：
+
+- CLI bridge **不知道**统一 Agent SSE 协议（`/v1/agents/threads/*` 端点）的存在
+- CLI bridge **直接发** runtime 自己的原生事件，服务端 `adapter/<runtime>/` 做 native → unified envelope 翻译
+- 之前 CLI 端的 `src-ext/core/unified_relay_shim.mjs` 翻译层 + `src-shared/agent-client/` HTTP 封装**已整体删除**
+- 4 个 bridge（OpenClaw / Hermes / Claude / Codex）共用同一套 `relayWorker` long-poll 主循环
+
+三个关键角色：
+
+| 角色             | 位置                                              | 职责                                                                                            |
+| ---------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| **Relay Server** | `agentlink-server/`（Go）                          | 握住 App ↔ runtime 之间的所有流量；`internal/adapter/<runtime>/` 把 native 事件翻成统一信封      |
+| **CLI**          | `bin/agentlink` + `bin/agentlink-agent`（Node ≥22）| 配对 + 桥接；4 种 runtime 共用 `relayWorker` long-poll 主循环；不做协议翻译                      |
+| **Runtime**      | OpenClaw gateway / Hermes(JS) / Claude CLI / Codex CLI | 实际执行 AI turn 的进程或本地 LLM 调用                                                          |
+
+### 4 种 runtime bridge 对比
+
+| Runtime  | 启动命令                  | 入口文件                                                              | native 协议（POST 给服务端的事件格式）        | 服务端 adapter                          |
+| -------- | ------------------------- | --------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------- |
+| OpenClaw | `agentlink bridge`        | `src/tunnel.mjs` + `src/tunnel_proxy.mjs` + `src/tunnel_state.mjs`    | OpenClaw `/v1/responses` SSE chunk            | `internal/adapter/openclaw`             |
+| Hermes   | `agentlink-agent hermes`  | `src-ext/runtime/hermes/index.mjs`                                    | OpenAI-compatible SSE / NDJSON               | `internal/adapter/hermes`（共享 openclaw 逻辑） |
+| Claude   | `agentlink-agent claude`  | `src-ext/runtime/claude/index.mjs`                                    | Claude CLI stream-json                       | `internal/adapter/claude`               |
+| Codex    | `agentlink-agent codex`   | `src-ext/runtime/codex/index.mjs`                                     | Codex MCP `codex/event` notification         | `internal/adapter/codex`                |
+
+4 个 bridge 入口文件大小都 ≤ 800 行硬限，最大约 700 行。
+
+---
+
+## 2. 代码结构
+
+```
+agentlink-cli/
+├── bin/
+│   ├── agentlink              # 用户入口（setup / pair / bridge / service / tunnel）
+│   ├── agentlink-agent        # bridge 子进程入口（claude / codex / hermes）
+│   └── agentlink-mcp-stdio    # codex 反向 MCP stdio bridge
+├── src/                       # OpenClaw bridge + tunnel + 共享工具
+│   ├── core.mjs               # URL / code 归一化 / 路径解析等
+│   ├── tunnel.mjs             # OpenClaw bridge 主循环（277 行）
+│   ├── tunnel_proxy.mjs       # OpenClaw HTTP / SSE 转发（476 行）
+│   ├── tunnel_state.mjs       # 文件锁 / 状态机（301 行）
+│   └── tunnel_service.mjs     # OpenClaw 桥接的 service install/uninstall
+├── src-shared/                # 纯基础设施（无业务依赖）
+│   ├── logger.mjs             # 结构化 JSON 日志
+│   ├── correlation.mjs        # cid 生成 / 解析
+│   └── relay-defaults.json    # 默认 relay URL
+├── src-ext/                   # External Agents（Claude / Codex / Hermes）
+│   ├── bin.mjs                # agentlink-agent 入口分发
+│   ├── commands/              # pair / service / agent / reload / help 子命令
+│   ├── core/
+│   │   ├── pairCodeClient.mjs   # POST /v1/pair-codes/<code>/consume + 状态持久化
+│   │   ├── relayWorker.mjs      # 4 个 bridge 共用的 long-poll 主循环
+│   │   ├── relayWorkerHttp.mjs  # bridge_token Bearer header / fetchJson 工具
+│   │   ├── sessionSlot.mjs      # 单 session 槽状态机
+│   │   ├── stateMachine.mjs     # 通用 FSM
+│   │   ├── approvalGateway.mjs  # HITL 工具审批
+│   │   ├── mcpStdioClient.mjs   # MCP stdio 客户端（codex 用）
+│   │   ├── agentlinkToolsRegistry.mjs / agentlinkToolsServer.mjs # 反向工具注入
+│   │   ├── accountResolver.mjs  # accountId/clientUserId 解析
+│   │   └── usageReporter.mjs    # token 用量上报
+│   ├── runtime/
+│   │   ├── claude/index.mjs   # Claude bridge（spawn `claude` CLI + stream-json，223 行）
+│   │   ├── codex/index.mjs    # Codex bridge（spawn `codex` MCP stdio，240 行）
+│   │   └── hermes/index.mjs   # Hermes bridge（OpenAI-compatible HTTP / subprocess，256 行）
+│   ├── service/
+│   │   └── serviceManager.mjs # launchd / systemd / Task Scheduler 统一接入
+│   └── openclaw-plugin/       # agentlink-hooks OpenClaw 插件源码（详见 docs/PLUGIN_ACTIVE_RUNS.md）
+└── test/                      # node --test 测试套件（72 个 test）
+```
+
+**Hermes 已 100% JS 化** —— 旧 `runtime/hermes_bridge/` Python 目录已删除。`bin/agentlink` 中所有 Python 探测 / spawn 逻辑也已清除。
+
+**已删除的代码（重构清理）**：
+
+- `src-ext/core/unified_relay_shim.mjs` —— 整个文件删除。之前 CLI 在这里把 legacy `{kind: ...}` 事件翻译成统一信封 + POST 到 `/v1/agents/threads/<tid>/events`，现在改由服务端 adapter 翻译
+- `src-shared/agent-client/` —— 整个目录删除。CLI bridge 不再调统一协议端点，因此不需要 `/v1/agents/*` HTTP + SSE 客户端
+- 各 runtime 子目录里的 unified 翻译辅助文件（如 `usageReporter` 的 envelope 包装等）
+
+`bin/agentlink` 本身只 spawn `agentlink-agent` 子进程；`openclaw` CLI 是外部可执行文件，通过 `PATH` / `OPENCLAW_HOME` 定位。
+
+---
+
+## 3. 4 种 runtime 模式
+
+CLI 通过 `runtimeKind` 分流。**所有 runtime 在线协议层完全一致** —— 4 个 bridge 共用 `src-ext/core/relayWorker.mjs` long-poll 主循环，通过相同的 3 个端点跟 relay 通讯：
+
+- `POST /v1/pair-codes/<code>/consume`（启动配对）
+- `GET /v1/gateways/<gw>/requests/next?waitSeconds=25`（长轮询拉用户消息）
+- `POST /v1/gateways/<gw>/requests/<rid>/events`（流式回 native 事件）
+- `POST /v1/gateways/<gw>/meta`（10s 心跳）
+
+唯一的差异是 bridge 内部对接的本地 runtime 进程，以及推回 relay 的 native 事件格式。**CLI 不做协议翻译**，服务端 `internal/adapter/<runtime>/` 把 native 事件统一翻译为 unified envelope 落库 `agent_events` 表。
+
+### 3.1 OpenClaw 模式（默认）
+
+```
+ App ──► Relay ──► CLI bridge (Node) ──► HTTP POST /v1/responses ──► OpenClaw Gateway
+                                                                          │
+                                     events  ◄──────────────── SSE / JSON ┘
+                                     (publish back to relay)
+```
+
+- 入口：`agentlink bridge`（`src/tunnel.mjs` 主循环 + `tunnel_proxy.mjs` HTTP / SSE 转发 + `tunnel_state.mjs` 状态机）
+- OpenClaw 是独立的外部进程（`openclaw gateway run`），监听 `127.0.0.1:<port>`
+- CLI 把 relay long-poll 拉下来的请求转成 `POST /v1/responses`，再把流式响应原样切片发回 relay
+- 网关鉴权：CLI 从 `~/.openclaw/config.json` 读 `gateway.auth.token`
+- 服务端 `internal/adapter/openclaw` 把 OpenClaw 的 SSE chunk 翻译为统一信封事件
+
+### 3.2 Hermes 模式（pure JS，已替代旧 Python bridge）
+
+```
+ App ──► Relay ──► agentlink-agent hermes ──► OpenAI-compatible HTTP
+   long-poll        (Node 22+ stdlib fetch)        (or external command)
+```
+
+- 入口：`agentlink-agent hermes`（`src-ext/runtime/hermes/index.mjs`，256 行）
+- 走 `relayWorker` long-poll：拿到 user request → 调本地 LLM → 流式回 OpenAI-compatible SSE chunk 给 relay
+- 后端 2 选 1：
+  - **HTTP**：`HERMES_BRIDGE_API_BASE_URL` + `HERMES_BRIDGE_API_KEY`（OpenAI / DeepSeek / 自建 vLLM 等）
+  - **subprocess**：`HERMES_BRIDGE_COMMAND="<path-to-binary>"`（newline-delimited JSON 协议）
+- 本地 transcript 存在 `~/.agentlink/hermes/sessions/<sessionId>.json`
+- 零 Python 依赖
+
+### 3.3 Claude 模式
+
+```
+ App ──► Relay ──► agentlink-agent claude ──► spawn `claude` CLI (stream-json)
+```
+
+- 入口：`agentlink-agent claude`（`src-ext/runtime/claude/index.mjs`，223 行）
+- spawn 外部 `claude` CLI（Anthropic 官方），从 stdout 读 stream-json，**直接**作为事件 POST 到 `/v1/gateways/<gw>/requests/<rid>/events`
+- 服务端 `internal/adapter/claude` 解析 stream-json，把 `assistant_message_delta` / `tool_use_block` / `parent_tool_use_id` 等翻译成统一信封事件（`content_block.delta` / `tool_use` / subagent run_id 等）
+- 工具审批走 `approvalGateway`：PreToolUse hook → 推 interrupt block → 等 App 端 resume
+
+### 3.4 Codex 模式
+
+```
+ App ──► Relay ──► agentlink-agent codex ──► spawn `codex` MCP stdio server
+```
+
+- 入口：`agentlink-agent codex`（`src-ext/runtime/codex/index.mjs`，240 行）
+- 通过 MCP stdio 协议跟 `codex` CLI 通信，反向注入 `agentlink-mcp-stdio` 作为工具服务器
+- `codex/event` notification 直接序列化为事件 POST 给 relay
+- 服务端 `internal/adapter/codex` 把 `codex/event` 翻译为统一信封
+
+4 种 runtime 使用**独立**的 relay 凭证和独立的 session 模型（见 `AppRuntimeKind` 枚举），配对流程里由 App 端决定写哪一组。
+
+---
+
+## 4. Relay 协议
+
+CLI 跟 relay 之间只走 HTTP（长轮询 + POST），没有 WebSocket。关键端点：
+
+### 4.1 配对阶段
+
+| 端点                                       | 方向        | 用途                                                                 |
+| ------------------------------------------ | ----------- | -------------------------------------------------------------------- |
+| `POST /v1/pair-sessions`                   | App → Relay | App 创建 4 位 pair code（含 `accountId` / `runtimeKind`）            |
+| `GET /v1/pair-sessions/{code}`             | CLI → Relay | （openclaw 模式）查配对 session 是否存在、读出 App 设定的 runtimeKind |
+| **`POST /v1/pair-codes/{code}/consume`**   | CLI → Relay | **统一入口**：消费 4 位码，body `{client_user_id, runtime}` → 颁发 `{gw_id, bridge_token, runtime}` |
+
+兼容性：服务端仍保留 `POST /api/ext/pair-codes/<code>/consume?runtime=<rt>`（legacy 老 CLI 用），新 CLI 默认调 `/v1/pair-codes/...`，404 / 410 时回退老端点（升级期间双端兼容）。
+
+### 4.2 桥接阶段
+
+| 端点                                                  | 方向               | 用途                                                                                |
+| ----------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
+| `GET /v1/gateways/{gwId}/requests/next?waitSeconds=N` | CLI/bridge → Relay | long-poll 下一个 request（204 表示超时）                                            |
+| `POST /v1/gateways/{gwId}/requests/{reqId}/events`    | CLI/bridge → Relay | 推 native 事件（`start` / `chunk` / `end` / `error` / `response`），服务端 adapter 翻译为 unified envelope |
+| `POST /v1/gateways/{gwId}/chat-events`                | CLI → Relay        | OpenClaw 模式下发送结构化聊天事件（供 App 做 structured history）                   |
+| `POST /v1/gateways/{gwId}/meta`                       | CLI/bridge → Relay | presence 心跳（`online` / `connected` / `state`），默认 10s 一次                    |
+| `GET/DELETE /v1/gateways/{gwId}/binding`              | CLI → Relay        | 查询 / 解绑当前 gateway                                                             |
+| `POST /v1/gateways/{gwId}/reset`                      | CLI → Relay        | 硬重置（`agentlink reset`）                                                          |
+
+**鉴权**：桥接阶段所有端点用 `Authorization: Bearer <bridge_token>`（pair-codes consume 颁发，单向 producer-only）。
+
+> **bridge_token vs client_token**
+>
+> CLI 持有的是 `bridge_token`（producer 凭证）：能 long-poll 拉 user request、能 POST events 推回。
+> App 侧持有的是 `client_token`（consumer 凭证）：能 GET `/v1/agents/threads/<tid>/stream` 订阅、能查询 thread 状态。
+> **两个 token 互不可换用**，混用返回 403。
+
+### 4.3 事件形状
+
+桥接 worker 发回 relay 的事件统一是：
+
+```json
+{
+  "event": "start|chunk|end|error|response",
+  "sessionKey": "agent:<id>:relay-gw:<gwId>::<sessionKey>",
+  "runId": "...",
+  "statusCode": 200,
+  "contentType": "text/event-stream; charset=utf-8",
+  "data": "...",
+  "createdAtMs": 1713312000000
+}
+```
+
+`sessionKey` 格式前后端不一致：App 侧带装饰前缀（`agent:` / `relay-gw:`），relay 事件来的是裸 key。两边比较必须归一化（Go 端 `normalizeSessionKeyForMatch`，Flutter 端 `_sessionKeyMatchesForPreview`）。
+
+---
+
+## 5. 典型流程
+
+### 5.1 配对（`agentlink pair <code>`，统一 long-poll 模式）
+
+4 种 runtime 走完全一致的配对流程（OpenClaw 多一步本地 daemon 重启，详见 [docs/PAIR_FLOW.md](docs/PAIR_FLOW.md)）：
+
+```
+   App                          Relay                          CLI
+    │                             │                             │
+    │ 1. POST /v1/pair-sessions   │                             │
+    │    {runtime, accountId,     │                             │
+    │     clientUserId}           │                             │
+    ├────────────────────────────▶│                             │
+    │                             │                             │
+    │ 2. App 屏幕显示 4 位 code   │                             │
+    │                             │                             │
+    │                             │   3. 用户在 CLI 输入 code   │
+    │                             │                             │
+    │                             │ 4. POST /v1/pair-codes/     │
+    │                             │      <code>/consume         │
+    │                             │    {client_user_id,         │
+    │                             │     runtime}                │
+    │                             │◀────────────────────────────┤
+    │                             │                             │
+    │                             │ 5. {gw_id, bridge_token,    │
+    │                             │     runtime}                │
+    │                             ├────────────────────────────▶│
+    │                             │                             │
+    │                             │   6. 持久化到               │
+    │                             │      ~/.agentlink/          │
+    │                             │      ext-<runtime>-last.json│
+    │                             │                             │
+    │                             │   7. 进入 long-poll loop:   │
+    │                             │      GET .../requests/next  │
+    │                             │◀────────────────────────────┤
+    │                             │                             │
+    │ 8. App 端订阅 thread        │                             │
+    │    GET /v1/agents/threads/  │                             │
+    │    <tid>/stream             │                             │
+    ├────────────────────────────▶│                             │
+```
+
+配对完成判定 = `/pair-codes/<code>/consume` 返回 `gw_id` + `bridge_token`。CLI 立刻进入 long-poll 主循环，不需要再等 App 端"确认"。
+
+持久化位置（按 runtime 分文件，互不干扰）：
+
+```
+~/.agentlink/ext-openclaw-last.json
+~/.agentlink/ext-hermes-last.json
+~/.agentlink/ext-claude-last.json
+~/.agentlink/ext-codex-last.json
+```
+
+文件内容：`{ gw_id, runtime, relay_url, bridge_token, saved_at }`。`session_id` 字段保留作老 CLI 兼容（值与 `gw_id` 相同）。
+
+### 5.2 桥接（`agentlink bridge`，OpenClaw 模式）
+
+```
+ ┌──────────┐                    ┌──────────┐              ┌────────────┐
+ │  CLI     │  long-poll 90s     │  Relay   │              │  OpenClaw  │
+ │  bridge  │───────────────────▶│          │              │  Gateway   │
+ │          │◀───────────────────│          │              │ /v1/resp.. │
+ │          │   request          │          │              │            │
+ │          │                    │          │              │            │
+ │          │─── POST /v1/resp ─────────────────────────▶  │            │
+ │          │◀── SSE stream ──────────────────────────────  │            │
+ │          │                    │          │              │            │
+ │          │── POST events ────▶│          │              │            │
+ │          │   (start/chunk/    │          │              │            │
+ │          │    end)            │          │              │            │
+ │          │                    │          │              │            │
+ │          │── POST meta ──────▶│          │              │            │
+ │          │   (heartbeat 10s)  │          │              │            │
+ └──────────┘                    └──────────┘              └────────────┘
+```
+
+- Bridge 使用 `acquireBridgeLock` 做文件锁，防止一台机器上两个 bridge 抢同一个 gateway
+- SIGINT/SIGTERM 时发一次 `state: "stopped"` presence，让 App 立刻看到离线（而不是等 25s TTL）
+
+### 5.3 桥接（Hermes / Claude / Codex 模式 — 统一 long-poll）
+
+3 个 External Agent runtime 共用同一套主循环，只是本地 backend 不同：
+
+```
+  agentlink-agent <hermes|claude|codex>
+    │
+    ├── relayWorker.run(handler):
+    │     loop:
+    │       req = GET /v1/gateways/<gw>/requests/next?waitSeconds=25
+    │       if 204 → continue   // long-poll 超时
+    │       handler(req, ctx) →
+    │
+    ├── handler 实现（按 runtime 分流）：
+    │     hermes: fetch(POST OpenAI /chat/completions, stream:true)
+    │             ↓ 每个 SSE chunk: ctx.publishEvent({kind:"chunk", data:...})
+    │     claude: spawn `claude` CLI（stream-json mode）
+    │             ↓ 每个 stream-json 事件: ctx.publishEvent({kind:"chunk", data:...})
+    │     codex:  MCP stdio 双向通讯 + 反向工具注入
+    │             ↓ 每个 codex/event: ctx.publishEvent({kind:"chunk", data:...})
+    │
+    ├── ctx.publishEvent → POST /v1/gateways/<gw>/requests/<rid>/events
+    │     body 是 native 事件，**不在 CLI 翻译**
+    │
+    └── 心跳 POST /v1/gateways/<gw>/meta（每 10s）
+```
+
+服务端 `internal/adapter/<runtime>/` 接到 native 事件后翻译为统一信封写入 `agent_events` 表。
+
+Hermes 会话历史持久化在 `~/.agentlink/hermes/sessions/<sessionId>.json`。无 Python，无 venv，无 pip install。
+
+---
+
+## 6. 安装 & 快速开始
+
+```bash
+npm i -g @xyagent/cli
+```
+
+OpenClaw 模式（默认）：
+
+```bash
+# 1) 准备 OpenClaw 配置 + relay 凭证
+agentlink setup \
+  --relay http://<relay-host>:8090 \
+  --public-base http://<gateway-public-host>:<port>
+
+# 2) 启动本地 OpenClaw gateway
+openclaw gateway run --bind loopback --port <port> --force
+
+# 3) 用 App 里生成的 code 完成配对
+agentlink pair 123456
+
+# 4) 把桥接装成后台服务
+agentlink service install
+```
+
+Hermes 模式（pure JS，无 Python 依赖）：
+
+```bash
+# 配置后端：HTTP（OpenAI-compatible）
+export HERMES_BRIDGE_API_BASE_URL=https://api.openai.com/v1
+export HERMES_BRIDGE_API_KEY=sk-xxx
+export HERMES_BRIDGE_MODEL=gpt-4o-mini
+
+# 或者用 subprocess 后端（外部 binary，NDJSON 协议）
+# export HERMES_BRIDGE_COMMAND=/path/to/my-llm-script
+
+# 配对（CLI 自动检测后端 env，未配置会报错）
+agentlink pair 123456 --runtime hermes
+
+# 前台跑（调试）
+agentlink bridge --runtime hermes
+```
+
+Claude / Codex External Agents：
+
+```bash
+# Claude Code / Codex CLI 需要先在本机安装并登录
+
+# 配对后会自动安装后台服务
+agentlink pair 1234 -r claude
+agentlink pair 1234 -r codex
+
+# 前台调试运行（当前终端内运行，Ctrl+C 可停止）
+agentlink bridge -r claude
+agentlink bridge -r codex
+```
+
+重装 App 后重新配对（典型场景）：
+
+```bash
+# 如果之前是 hermes 模式，配对报 "这台主机已经绑定过设备"
+agentlink reset --runtime hermes          # 只清 hermes 凭证，不动 openclaw
+agentlink pair <new-code> --runtime hermes
+
+# openclaw 模式不传 --runtime 即可
+agentlink reset
+agentlink pair <new-code>
+```
+
+---
+
+## 7. 命令参考
+
+```bash
+agentlink setup [--relay URL] [--public-base URL]              # 写配置 + 装权限
+agentlink pair <code> [--runtime openclaw|hermes|claude|codex] # 配对；claude/codex 默认会自动装后台服务
+agentlink bridge [--runtime openclaw|hermes|claude|codex]      # 前台运行桥接；claude/codex 用 Ctrl+C 停止
+agentlink service install|stop|uninstall|restart|status [--runtime ...] # 后台服务；claude/codex 中 stop 是 uninstall 别名
+agentlink uninstall --runtime claude|codex                     # claude/codex 完整卸载：停服务 + 清本地配对状态
+agentlink reset [--runtime openclaw|hermes] [--gateway GWID]   # 硬重置绑定
+agentlink pair-url [--account ID] [--code CODE]                # 生成手动配对 URL
+agentlink tunnel on <port> [--relay URL]                       # 暴露本地 HTTP 端口
+agentlink tunnel off <port> [--relay URL]                      # 关闭端口转发
+agentlink tunnel ls                                            # 查看 tunnel 状态
+agentlink status [--runtime openclaw|hermes]                   # 查当前 runtime / 服务 / 绑定
+```
+
+### Tunnel 快速测试
+
+```bash
+# 启一个本地测试服务（任何 HTTP 服务器都行；这里用 Node 内置）
+mkdir -p /tmp/agentlink-tunnel-demo
+printf 'hello tunnel\n' >/tmp/agentlink-tunnel-demo/index.html
+node -e 'import("node:http").then(({createServer})=>{import("node:fs").then(({readFileSync})=>{createServer((_,res)=>res.end(readFileSync("/tmp/agentlink-tunnel-demo/index.html"))).listen(8080,"127.0.0.1");console.log("listening on 127.0.0.1:8080");})})'
+```
+
+另一个终端：
+
+```bash
+agentlink tunnel on 8080
+```
+
+示例输出：
+
+```text
+Tunnel started
+Local:  http://127.0.0.1:8080
+Public: https://go-relay-test.xyagent.com/t/p8080-03ce6ff5
+Logs:   ~/.agentlink/logs/tunnel-8080.log
+Mode:   systemd-user
+```
+
+说明：
+
+- tunnel agent 会每 10 秒向 relay 发 heartbeat
+- relay 超过约 35 秒没收到 heartbeat，会把 tunnel 视为 offline，并对公网请求直接返回 `503 tunnel offline`
+- `agentlink tunnel on <port>` 会直接打印公网访问地址，示例里的 `Public: https://...` 就是可分享的访问 URL
+- 如果不传 `--relay`，默认使用 CLI 当前内置或环境变量指定的 relay 地址
+- 后台守护优先走当前平台的服务管理：
+  - Linux: `systemd --user`
+  - macOS: `launchd`
+  - Windows: `Task Scheduler`
+- 如果当前环境没有可用的服务管理器，会自动回退到 detached 进程，并在 `agentlink tunnel on` 输出里提示
+
+### Tunnel 技术实现
+
+这套 tunnel 是标准的反向内网穿透，不要求目标机器有公网 IP，也不要求目标机器开放入站端口。
+
+核心思路：
+
+- 外部用户访问的是 relay server 暴露出来的公网 URL，例如 `https://go-relay-test.xyagent.com/t/<slug>`
+- 内网机器上的 `agentlink tunnel agent` 主动连接 relay，通过长轮询拉取待处理请求
+- agent 在本机访问 `127.0.0.1:<port>`，再把响应回传给 relay
+- relay 把响应返回给浏览器或调用方
+
+涉及的 3 个角色：
+
+- `Client / Browser`
+  - 访问公网 tunnel 地址
+- `Relay Server`
+  - 负责创建 tunnel、分配 `slug`、接收公网请求、转发给 agent、返回响应
+- `Tunnel Agent`
+  - 运行在用户机器上，负责 heartbeat、拉取请求、访问本地服务、发布响应
+
+关键接口：
+
+- `POST /v1/tunnels`
+  - 创建 tunnel，返回 `id`、`agentToken`、`publicUrl`
+- `GET /v1/tunnels/:id/requests/next`
+  - agent 长轮询拉取待处理请求
+- `POST /v1/tunnels/:id/heartbeat`
+  - agent 上报存活状态
+- `POST /v1/tunnels/:id/responses/:reqId/publish`
+  - agent 发布本地服务响应
+- `GET /t/:slug/*path`
+  - 公网入口，外部流量从这里进入 tunnel
+
+工作流程：
+
+```mermaid
+sequenceDiagram
+    participant U as "User / Browser"
+    participant R as "Agentlink Relay Server"
+    participant A as "Agentlink Tunnel Agent"
+    participant L as "Local Service (127.0.0.1:8080)"
+
+    A->>R: "POST /v1/tunnels"
+    R-->>A: "id + agentToken + publicUrl"
+    A->>R: "POST /v1/tunnels/:id/heartbeat"
+    A->>R: "GET /v1/tunnels/:id/requests/next"
+
+    U->>R: "GET /t/:slug/api/echo?x=1"
+    R-->>A: "返回待处理 request"
+    A->>L: "GET http://127.0.0.1:8080/api/echo?x=1"
+    L-->>A: "200 + headers + body"
+    A->>R: "POST /v1/tunnels/:id/responses/:reqId/publish"
+    R-->>U: "200 + headers + body"
+```
+
+在线状态与恢复机制：
+
+- agent 每 `10s` 发送一次 heartbeat
+- server 超过约 `35s` 没收到 heartbeat，会把 tunnel 判定为 `offline`
+- `offline` 状态下，公网请求会直接返回 `503 tunnel offline`
+- 后台运行优先使用系统服务托管：
+  - Linux: `systemd --user`，root 环境额外支持 `systemd system service`
+  - macOS: `launchd`
+  - Windows: `Task Scheduler`
+- 如果 agent 进程异常退出，服务管理器会自动重启；如果没有服务管理器，则退回 detached 进程模式
+
+实现边界：
+
+- 当前 tunnel 第一版只支持 HTTP 请求/响应转发
+- 支持 path、query、JSON/body、常见响应头透传
+- 暂不包含 WebSocket、任意 TCP、UDP 转发
+- 公网入口当前使用路径路由 `/t/<slug>`，没有使用独立子域名
+
+复杂路由跳转的适配说明：
+
+- 大多数复杂 Web 系统都可以正常工作，包括：
+  - SPA 前端路由，例如 `react-router`、`vue-router`
+  - 后端页面路由，例如 `/admin/users/list`
+  - 带 query 的跳转，例如 `/orders?page=2&status=paid`
+  - 常见的 `301/302/307/308` 重定向
+- 这类场景通常没问题，因为 tunnel 会保留：
+  - 请求 path
+  - 原始 query string
+  - 常规请求头与响应头
+  - HTTP 状态码
+  - `x-forwarded-host`
+- 真正容易出问题的通常不是“路由复杂”，而是“应用把绝对地址写死”：
+  - 例如后端返回 `Location: http://127.0.0.1:8080/login`
+  - 或前端代码里写死 `http://内网IP:端口/...`
+  - 或登录回调地址、Cookie domain、绝对资源地址强依赖固定 host
+- 推荐应用侧尽量使用相对路径，或者正确读取反向代理后的 host/proto 信息生成跳转地址
+- 如果系统强依赖 WebSocket、HMR dev server、长连接 upgrade，当前版本需要单独验证，不能默认保证完全可用
+
+固定的 `curl` 用例：
+
+```bash
+# 1) GET 根路径
+curl -i https://go-relay-test.xyagent.com/t/p8080-03ce6ff5
+
+# 2) GET 带 path + query
+curl -i 'https://go-relay-test.xyagent.com/t/p8080-03ce6ff5/api/echo?name=agentlink&mode=query'
+
+# 3) POST JSON 到带 path + query 的入口
+curl -i \
+  -X POST \
+  'https://go-relay-test.xyagent.com/t/p8080-03ce6ff5/api/echo?source=curl&lang=zh' \
+  -H 'content-type: application/json' \
+  -d '{"hello":"world","from":"agentlink"}'
+```
+
+看 agent 日志：
+
+```bash
+tail -f ~/.agentlink/logs/tunnel-8080.log
+```
+
+关闭：
+
+```bash
+agentlink tunnel off 8080
+```
+
+`agentlink reset` 的行为：
+
+| 命令                             | 作用对象                                            |
+| -------------------------------- | --------------------------------------------------- |
+| `agentlink reset`                 | 重置 openclaw 凭证（并额外清空 hermes 凭证，兜底）  |
+| `agentlink reset --runtime hermes`| **只**清 hermes 凭证，openclaw 绑定不动             |
+
+reset 做的事：
+
+- 调 relay `DELETE /v1/gateways/{id}/binding` 清服务端绑定（配对码 / 会话 / 联系人）
+- 卸载目标 runtime 的后台服务（launchd / systemd / Task Scheduler）
+- 停掉目标 runtime 正在跑的桥接进程
+- 清 `~/.agentlink/config.json` 本地凭证：
+  - openclaw → 重新生成 `relayGatewayId` + 轮换 token，并连带清空 hermes 凭证
+  - hermes → 只删 `hermesRelayGatewayId` / `hermesRelayClientToken` / `hermesRelayGatewayToken`
+
+reset 完成后即可对同一 runtime 发起新的 `agentlink pair`。
+
+code 接受 `1234`、`123456` 或 `XXXX-XXXX`（参考 `normalizeProvidedCode`）。
+
+---
+
+## 8. 服务管理
+
+| 平台               | 机制              | 单元文件                                                    |
+| ------------------ | ----------------- | ----------------------------------------------------------- |
+| macOS              | launchd           | `~/Library/LaunchAgents/com.agentlink.bridge[-hermes].plist` |
+| Linux (systemd)    | systemd user unit | `~/.config/systemd/user/agentlink-bridge[-hermes].service`   |
+| Linux (无 systemd) | —                 | 只能手动 `agentlink bridge`，service install 会报友好错误    |
+| Windows            | Task Scheduler    | task name `Agentlink Bridge`                                 |
+
+OpenClaw 和 Hermes 两种 runtime 的服务名**不同**（参考 `serviceNames(runtimeKind)`），可以同时装一台机上跑两种：
+
+```bash
+agentlink service status                         # 默认看 openclaw
+agentlink service status --runtime hermes        # 看 hermes 服务
+agentlink service install                        # 装 openclaw bridge（默认）
+agentlink service install --runtime hermes       # 装 hermes bridge
+agentlink service uninstall [--runtime hermes]   # 停 + 删
+agentlink service restart   [--runtime hermes]   # 重启
+```
+
+日志：
+
+```bash
+# OpenClaw 桥接日志
+tail -f ~/.agentlink/logs/bridge.stdout.log
+tail -f ~/.agentlink/logs/bridge.stderr.log
+
+# Hermes 桥接日志
+tail -f ~/.agentlink/logs/bridge-hermes.stdout.log
+tail -f ~/.agentlink/logs/bridge-hermes.stderr.log
+```
+
+### Claude / Codex（External Agents）
+
+Claude / Codex 走的是独立的 `agentlink-agent` service 管理实现，命令入口仍然是顶层 `agentlink`：
+
+| 平台 | 机制 | 单元文件 |
+| ------------------ | ----------------- | ----------------------------------------------------------- |
+| macOS | launchd | `~/Library/LaunchAgents/com.agentlink.agent.<runtime>.plist` |
+| Linux (systemd) | systemd user unit | `~/.config/systemd/user/agentlink-agent-<runtime>.service` |
+| Linux (无 systemd) | — | 只能手动 `agentlink bridge -r <runtime>` |
+| Windows | Task Scheduler | `Agentlink\\Agent-<runtime>` |
+
+常用命令：
+
+```bash
+# 配对后自动装后台服务
+agentlink pair 1234 -r claude
+agentlink pair 1234 -r codex
+
+# 查看后台状态
+agentlink service status -r claude
+agentlink service status -r codex
+
+# 重装后台服务
+agentlink service restart -r claude
+agentlink service restart -r codex
+
+# 只停掉后台服务，但保留本地配对状态
+agentlink service stop -r claude
+agentlink service stop -r codex
+
+# `service uninstall` 对 claude/codex 与 `service stop` 等价
+agentlink service uninstall -r claude
+agentlink service uninstall -r codex
+
+# 完整卸载：停服务并清掉本地配对状态（~/.agentlink/ext-<runtime>-last.json）
+agentlink uninstall -r claude
+agentlink uninstall -r codex
+
+# 前台调试运行；停止方式就是 Ctrl+C
+agentlink bridge -r claude
+agentlink bridge -r codex
+```
+
+说明：
+
+- `agentlink pair <code> -r claude|codex` 成功后，会自动执行后台服务安装。
+- 对 `claude/codex` 来说，`agentlink service stop -r <runtime>` 和 `agentlink service uninstall -r <runtime>` 在当前实现里效果相同，都会卸载对应 service，但不会删除本地配对状态。
+- 如果你想彻底解绑本机上的 Claude / Codex，请使用 `agentlink uninstall -r <runtime>`，它会在停服务之外再清掉本地状态文件。
+
+---
+
+## 9. 状态与持久化
+
+| 路径                                         | 内容                                                          |
+| -------------------------------------------- | ------------------------------------------------------------- |
+| `~/.openclaw/openclaw.json`                  | OpenClaw gateway 配置（模型、端口、profile、relay 配置片段）  |
+| `~/.agentlink/config.json`                    | CLI 级别状态（`runtimeKind`、4 套 relay 凭证）                 |
+| `~/.agentlink/hermes/sessions/<sid>.json`    | Hermes JS bridge 的会话历史持久化                             |
+| `~/.agentlink/bridge-launch.sh`               | OpenClaw 桥接的 launchd/systemd 启动脚本                      |
+| `~/.agentlink/bridge-launch-hermes.sh`        | Hermes 桥接的 launchd/systemd 启动脚本                        |
+| `~/.agentlink/logs/`                          | 桥接 stdout / stderr 日志                                     |
+| `~/.openclaw/agentlink/runtime/bridge-*.lock` | 桥接文件锁（按 `relayUrl + gatewayId + gatewayBase` 取 hash） |
+
+`~/.agentlink/config.json` 里两套凭证并存：
+
+- **OpenClaw**：`relayGatewayId` / `relayClientToken` / `relayGatewayToken`
+- **Hermes**：`hermesRelayGatewayId` / `hermesRelayClientToken` / `hermesRelayGatewayToken`
+
+`runtimeKind` 字段记录最近一次配对的 runtime。敏感字段（`gateway.auth.token` / `channels.*.appSecret`）在 debug 输出里会被脱敏成 `***`。
+
+---
+
+## 10. 环境变量
+
+| 变量                                                                    | 作用                                                             |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `OPENCLAW_HOME`                                                         | 覆盖 OpenClaw 主目录（默认 `~/.openclaw`）                        |
+| `AGENTLINK_RELAY_URL`                                                    | 覆盖 relay 基址（默认 `https://go-relay-test.xyagent.com`）            |
+| `AGENTLINK_RELAY_TOKEN`                                                  | Bearer token（配对/绑定端点用）                                   |
+| `OPENCLAW_AGENTLINK_GATEWAY_BASE_URL`                                    | 覆盖本地 gateway 基址                                             |
+| `OPENCLAW_GATEWAY_PORT` / `OPENCLAW_GATEWAY_HOST`                       | 显式指定 host/port                                                |
+| `AGENTLINK_RELAY_GATEWAY_ID` / `_CLIENT_TOKEN` / `_GATEWAY_TOKEN`        | 覆盖 openclaw 的 relay 凭证                                       |
+| `AGENTLINK_HERMES_RELAY_GATEWAY_ID` / `_CLIENT_TOKEN` / `_GATEWAY_TOKEN` | 覆盖 hermes 的 relay 凭证                                         |
+| **`HERMES_BRIDGE_API_BASE_URL`**                                         | **Hermes JS bridge HTTP 后端：OpenAI-compatible base URL**         |
+| **`HERMES_BRIDGE_API_KEY`**                                              | **Hermes HTTP 后端 Bearer token**                                  |
+| **`HERMES_BRIDGE_MODEL`**                                                | **Hermes 默认模型名（`gpt-4o-mini` 等）**                          |
+| **`HERMES_BRIDGE_COMMAND`**                                              | **Hermes 子进程后端：外部 binary 路径（NDJSON 协议）**             |
+
+---
+
+## 11. Hermes JS bridge 多 provider 与流式
+
+Hermes JS bridge 通过 OpenAI-compatible HTTP 协议跑，任何兼容
+`POST /v1/chat/completions { stream: true }` 的服务都能直接接：OpenAI、Azure
+OpenAI、DeepSeek、自建 vLLM、LiteLLM、Ollama 兼容层。要切 provider 就改
+`HERMES_BRIDGE_API_BASE_URL`。
+
+流式默认按 OpenAI SSE 帧解析（`data:` 前缀 + `[DONE]` 终止符），逐 chunk 透传
+为 unified `content_block.delta`，最终一帧合并为 `content_block.completed`。
+
+不需要外部多 provider 配置文件 — 后端切换通过 env 完成：
+
+```bash
+# OpenAI 官方
+export HERMES_BRIDGE_API_BASE_URL=https://api.openai.com/v1
+export HERMES_BRIDGE_MODEL=gpt-4o-mini
+
+# DeepSeek
+export HERMES_BRIDGE_API_BASE_URL=https://api.deepseek.com/v1
+export HERMES_BRIDGE_MODEL=deepseek-chat
+
+# 本地 vLLM / Ollama 兼容层
+export HERMES_BRIDGE_API_BASE_URL=http://127.0.0.1:8000/v1
+export HERMES_BRIDGE_MODEL=qwen2.5
+```
+
+需要走非 OpenAI 协议（如 Anthropic 原生 `/messages`）？用 subprocess 后端：写
+一个外部 binary 实现 `stdin JSON → stdout NDJSON`，然后
+`export HERMES_BRIDGE_COMMAND=/path/to/my-binary`。bridge 会 spawn 它跑每个
+turn。
+
+模型选择用 `<provider>/<model-id>`（例 `minimax/MiniMax-M2.7`）。桥接先匹配配置的 provider，没匹配到才回退到默认 Hermes API server。
+
+---
+
+## 12. 已知陷阱
+
+1. **relay_client_token 可能在多设备共享** — 删除绑定前必须走 `canUseClientTokenDeleteFallback` 检查，避免误删别人的 binding
+2. **Session key 格式前后不一致** — App 侧装饰（`agent:xxx:relay-gw:GW-A::...`），relay 事件是裸 key。Flutter 用 `_sessionKeyMatchesForPreview` 宽松匹配
+3. **Windows 的 PowerShell 编码** — 服务注册时通过 Base64 传命令行，避免 CJK 路径在 cmd.exe 下被 mojibake
+4. **Hermes / OpenClaw 凭证是两套** — `AppRuntimeKind` 决定写哪一组，不能互相借用；`agentlink reset` 不传 `--runtime` 默认只重置 openclaw
+5. **Hermes cron 任务与配对无关** — `~/.hermes/cron/jobs.json` 是本地文件。一次性任务（`30m` / `2h` / 具体时间戳）执行后会**自动删除**，重新配对看不到是正常现象
+
+---
+
+## 13. 测试
+
+需要 Node.js ≥ 22。
+
+```bash
+npm test
+node --test test/cli.test.mjs
+```
+
+73 个测试（13 个测试文件），覆盖：
+
+- CLI basics / 平台路径 / OpenClaw home 解析 / XML & systemd 转义 / PID 检测 / 文件锁 / PowerShell Base64 / 服务状态 / Node 版本保护
+- `pairCodeClient` —— `/v1/pair-codes/<code>/consume` 协议契约 + legacy 端点回退
+- `relayWorker` —— long-poll 拉取 + publishEvent + 心跳 + 退避重试
+- `claudeParser` / `codexEventMapper` —— native 事件解析（CLI 端只解析不翻译）
+- `approvalGateway` / `elicitationHandler` —— HITL 工具审批
+- `mcpStdioClient` / `mcpStdioBridge` / `agentlinkTools` —— Codex 反向 MCP 工具注入
+- `usageReporter` —— token 用量上报
+
+> 之前 161 测试中有近一半是 `unified_relay_shim` 的 native → unified envelope 翻译契约测试。重构把翻译层挪到服务端 adapter 后，CLI 端只剩 73 测试覆盖 long-poll + pair-code consume + native 事件解析这些核心路径。
+
+CI：
+
+- GitLab CI (`.gitlab-ci.yml`)：Node 22 on Alpine
+- GitHub Actions (`.github/workflows/test.yml`)：Ubuntu / macOS / Windows × Node 22
+
+| 平台                                | 状态                         |
+| ----------------------------------- | ---------------------------- |
+| macOS (launchd)                     | 完全支持                     |
+| Linux + systemd                     | 完全支持                     |
+| Linux 无 systemd（Alpine / OpenRC） | 只支持手动 `agentlink bridge` |
+| Windows (Task Scheduler)            | 支持，CI 覆盖                |