@tunnelbox/hermes

English · 简体中文

官网： www.tunnelbox.top

tunnelbox Hermes 适配器（独立进程）：用手机远程驱动电脑上的 Hermes Agent——会话 / 流式 / 中止 / 删除。它驱动 Hermes CLI（headless oneshot），只向中继发出站连接（无需公网 IP / 端口映射）。

手机 App ──WSS──► relay ──WSS──► tunnelbox-hermes（本适配器）
                                      └─ hermes chat [--resume <id>] -Q -q "<text>"（每条消息拉起一个 hermes 子进程）

快速上手（安装 → 运行 → 配对 → 使用）

在装有 Hermes 并完成配置的电脑上，按以下步骤操作一次即可。

第 0 步 — 准备手机

在官网下载并安装 tunnelbox App（Android / iOS 均已上架）：https://www.tunnelbox.top

• 按提示登录/注册账号。

第 1 步 — 电脑上安装适配器

前置条件：Node.js ≥ 22，且本机已安装 Hermes Agent（NousResearch/hermes-agent）并完成登录/模型配置——hermes chat -Q -q "hi" 能正常应答。

npm install -g @tunnelbox/hermes

第 2 步 — 运行

tunnelbox-hermes

首次启动会连接中继，并在终端打印配对二维码 + 配对码。

第 3 步 — 与手机配对

在手机 App 点「扫一扫配对」，扫描终端二维码（或手动输入配对码）。配对码一次性有效，约 10 分钟。

• 绑定后再次启动会打印「已绑定账号，从手机「我的电脑」直接连接」，不再刷新码；
• 随时需要新码：运行 tunnelbox-hermes --pair。

第 4 步 — 在手机上使用

在 App 里打开这台电脑，即可新建会话、发消息、看流式输出、中止运行中的会话。

本包的 headless 桥（spawn-per-message）为整段 fallback 路径；需要实时远程控制（逐 token 流式 / 双向消息 / 手机审批 / 选择）请安装官方 Native 插件（native-plugin/，进程内，需本机运行 Hermes CLI/Gateway）。headless 本身不提供手机审批。

配置

| 环境变量 | 默认 | 说明 | |---|---|---| | TUNNELBOX_RELAY_URL | state 保存的地址 | 中继地址 | | TUNNELBOX_CWD | process.cwd() | 默认工作区 | | TUNNELBOX_HERMES_MODEL | hermes 默认 | --model | | TUNNELBOX_HERMES_PROVIDER | hermes 默认 | --provider（如 nous/openrouter） | | TUNNELBOX_HERMES_TOOLSETS | hermes 默认 | --toolsets（逗号分隔） | | TUNNELBOX_HERMES_VERBOSE | 关 | --verbose | | TUNNELBOX_HERMES_BIN | hermes | hermes 可执行名/绝对路径（可带前置参数，如 node /path/fake） |

TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" tunnelbox-hermes

能力位

| 能力 | 值 | 说明 | |---|---|---| | streaming | ✅ | chat -Q -q 整段一次性输出 → 回合级 text+complete 回传 | | thinking | ❌ | oneshot 无结构化推理部件 | | permission | ❌ | headless 无官方审批通道 → Hermes 自身策略/沙箱 fail-closed 兜底（手机审批见 native-plugin/） | | commands | ✅ | /new、/help | | abort | ✅ | kill 子进程（SIGTERM → SIGKILL） |

会话模型

• 会话 = 本地镜像（~/.tunnelbox/hermes-sessions/<uuid>/）：每条消息即时落盘，供列表/历史/删除。
• 续聊：首轮后经 hermes sessions list --workspace <目录> 发现 Hermes 真实会话 id 存镜像，后续每轮 chat --resume <id> -Q -q（Hermes 官方持久化保证多轮上下文）。已在 Hermes v0.21.1 真机验证（hermes -z 不续聊、自定义 id 无效）。
• 状态文件：~/.tunnelbox/remote-state.hermes.json。

安全说明

• 工具执行/命令授权由 Hermes 自身策略管理（危险命令 fail-closed）；本适配器不自动放行，也不改写用户 ~/.hermes/config.yaml。
• 请勿在不受信目录运行不受限工具集，也别把敏感工程目录暴露给不受信手机。

多语言

用户可见输出支持 8 种语言（zh-CN / zh-TW / en-US / ja-JP / ko-KR / fr-FR / de-DE / es-ES）。解析顺序：TUNNELBOX_LANG > remote-state.hermes.json 的 lang > 系统 locale > 默认 en-US。

故障排查

| 问题 | 解决 | |---|---| | 终端没有二维码/配对码 | 运行 tunnelbox-hermes --pair 打印新码 | | 需要换手机配对 | 在 App 设置里解绑，再带 --pair 运行 | | 已绑定但手机连不上 | 确认两端同一中继；查看 ~/.tunnelbox/tunnelbox.log | | 使用自建中继 | 启动时带 TUNNELBOX_RELAY_URL=wss://<你的中继> | | Hermes 应答异常/行为不符 | 在装有 hermes 的机器运行 npm run probe，输出结构化诊断回传维护者 |

状态文件

• ~/.tunnelbox/remote-state.hermes.json — agentID（+ 语言）
• ~/.tunnelbox/hermes-sessions/ — 本地会话镜像
• ~/.tunnelbox/tunnelbox.log — 适配器日志

卸载

npm uninstall -g @tunnelbox/hermes

仅当不再使用任何 tunnelbox 适配器时，才删除 ~/.tunnelbox（各适配器共享状态）。

开发

实现细节（协议映射、源码结构、决策记录、待实测项）保存在源码仓库中本包旁的 DEV.md 与仓库 docs/ 下。