tunnelbox · 手机遥控你电脑上的 AI 智能体

核心特性

一个"遥控器"，指挥你所有 AI

为 CLI / headless 智能体生态加一层统一的远程适配网关，会话、流式、权限、命令归一化。

svg-connect

反向连接，免公网 IP

电脑端适配器主动向外连接中继，无需公网 IP、端口映射或隧道，任意防火墙 / 公司网络皆可穿透。

svg-agents

多智能体同机并存

一台电脑同时跑 opencode、Claude Code、Codex…每个独立配对、独立会话，手机端智能体列表一键切换，甚至可横向对比同一任务。

svg-approve

危险操作手机审批

执行 bash / 编辑文件前，权限请求实时推送到手机审批卡——允许 / 拒绝 / 总是允许，一键完成，绝不自动放行。

svg-scan

扫码即配对

终端打印二维码与配对码，手机 App「扫一扫配对」扫码即自动连接；配对码一次性、10 分钟过期，防泄露滥用。

svg-layers

统一协议，后端零感知

会话列表 / 流式输出 / 权限审批 / 斜杠命令全部归一化为统一协议，手机端无需知道背后是哪个智能体。

svg-lock

隐私优先

中继只做无状态转发，不落盘任何会话内容；全链路 TLS。对隐私敏感的用户可自托管中继，数据完全可控。

支持矩阵

主流 CLI 智能体，全部纳入

每种智能体对应一个适配器，把它的会话 / 流式 / 权限归一化为统一远程协议——relay 与手机端零感知。

智能体	适配器方式	类型	状态
O opencode	进程内插件（@tunnelbox/opencode）	A	✅ MVP · 已实现
DS DeepSeek Harness (dsh)	原生 Cordis 插件（@tunnelbox/dsh-tunnelbox）	B	✅ 已实现
CC Claude Code	claude-agent-sdk 桥接（独立进程）	B	✅ 已实现
CX Codex	codex exec --json 桥接（独立进程）	B	✅ 已实现
OW OpenClaw	官方 Gateway operator WS 连接	B	✅ 已实现 · 待实测
HM Hermes	hermes chat -Q -q oneshot 桥接（含 Native 插件）	B	✅ 已实现 · 实验
CS Cursor	Cursor CLI agent -p headless（独立进程）	B	✅ 已实现 · 实验

A 进程内插件 · 运行在智能体服务器进程内；B CLI / headless 桥接 · 独立连接器进程驱动非交互模式。支持同类型多实例（opencode1 / opencode2…）。

工作原理

反向连接 + 无状态中继

给智能体生态加一层统一远程适配网关：手机连中继，电脑适配器反向连中继，消息双向转发。

svg-phone

手机端

手机 App

HTTPS + WSS 连接中继
查看会话与流式输出
下发任务 / 审批权限

svg-relay

中继 relay（Go）

云服务器 · 可自托管

配对 / 鉴权 / 转发
无状态，不落盘会话
NATS 多节点横向扩展

svg-pc

电脑端

智能体适配器

主动向外连接（出站 WS）
opencode：进程内插件
其他：独立 CLI / SDK 桥接

适配器主动连出

反向连接天然穿透 NAT / 防火墙，公司网络、宿舍环境也能用，无需公网 IP 或隧道服务。

中继只转发

成本低、易横向扩展；节点无状态，断开自动重连，会话数据永远只存在于你电脑的智能体本地。

一次配对，长期使用

首次扫码配对后签发会话 token，之后自动连接免重复扫码；配置 MySQL 后中继重启也无需重新配对。

下载 / 使用

现在就用起来

从官网下载 tunnelbox 手机 App（Android / iOS 均已上架），扫码或点按下载。

扫码下载 App

Android · iOS

tunnelbox App

原生手机 App：扫码配对、远程会话、流式输出、危险操作审批与消息推送，全部功能一应俱全。

Android 下载 iOS 下载

使用教程

三步配对，四步起飞

所有智能体都走同一条路径：电脑装适配器 → 手机扫码 → 开干。下方「各智能体安装手册」提供每个智能体的傻瓜式分步命令，可一键复制。

1

第 1 步 · 电脑上运行你的智能体适配器

安装并运行对应智能体的适配器（命令见下方「各智能体安装手册」）。适配器启动后，终端会打印 二维码 + 配对码。

2

第 2 步 · 在手机上安装并打开 tunnelbox App

从官网下载并安装 tunnelbox App（Android / iOS 均已上架），登录账号。

3

第 3 步 · 扫一扫配对

点「扫一扫配对」扫终端二维码即自动连接；也可手动输入配对码。配对成功后智能体出现在首页列表。

4

第 4 步 · 开始远程操作

进入智能体聊天页：会话 Tab 切换 / 新建、发送提示词、实时流式输出、危险操作审批卡、运行中一键「停止」。

各智能体安装手册

按你的智能体选择下方标签，照着命令一步步来——每条命令都可一键复制。

中继地址按环境统一为三档：开发 ws://192.168.1.124:8081 · 测试 wss://relay.wxngrok.com · 生产 wss://relay.tunnelbox.top。插件源码不含中继 URL：构建/安装时用 --env development|test|production 选一次并注入（缺省 production），运行期可用 TUNNELBOX_RELAY_URL 或显式配置覆盖。下方"可选配置"示例按生产（官方在线中继）给出。

① 前置条件

推荐环境：macOS / Linux / Windows（WSL）
无需单独安装 Node —— opencode 自带 Bun 运行时，插件直接在其中运行

② 安装 opencode（官方）

先安装 opencode 本体（官方一键脚本，macOS / Linux；Windows 建议用 WSL，或用 Chocolatey / Scoop）：

# macOS / Linux（官方一键安装脚本）
curl -fsSL https://opencode.ai/install | bash

# Windows（PowerShell）：Chocolatey / Scoop / WSL
choco install opencode

安装后运行 opencode --version 能看到版本号即成功。

③ 安装 tunnelbox 适配器

1在 opencode.json 的 plugin 数组加入 npm 包（首次启动自动安装）

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@tunnelbox/opencode"]
}

④ 运行与配对

2重启 opencode（建议 --print-logs），插件自动连接中继并打印二维码与配对码。之后可在 opencode 内输入「显示手机配对码」或 /pair 随时取码，聊天中会同时给出配对码与可扫二维码。

opencode serve --print-logs

✅ 看到 [tunnelbox] 打印的二维码即成功，用手机扫一扫配对。

⑤ 可选配置与提示

连接官方中继无需任何配置。自定义中继地址：用环境变量 TUNNELBOX_RELAY_URL，或在 opencode.json 用对象形式传 options.relayUrl：

// opencode.json（自定义中继地址时）
{
  "plugin": [{ "package": "@tunnelbox/opencode", "options": { "relayUrl": "wss://relay.tunnelbox.top" } }]
}

状态文件保存在 ~/.config/opencode/remote-state.json。同一台电脑可同时运行多个智能体适配器，各自独立配对、互不干扰，手机端智能体列表一键切换。

① 前置条件

Node.js ≥ 22（tunnelbox 适配器需要）
付费 Claude 账号（Pro / Max / Team，或 Anthropic Console API key）

② 安装 Claude Code（官方）

先安装 Claude Code 本体（官方原生安装器，自动更新，无需额外运行时）：

# macOS / Linux / WSL（官方原生安装）
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

安装后运行 claude --version 看到版本号即成功；首次启动需用付费 Claude 账号登录。

③ 安装 tunnelbox 适配器

1用 npm 全局安装适配器（无需克隆仓库）

# 无需克隆仓库
npm install -g @tunnelbox/claude-code

④ 运行与配对

2启动适配器（常驻电脑），终端打印二维码与配对码。手机端无需安装任何 Claude SDK。

tunnelbox-claude-code

✅ 看到二维码即成功，用手机扫一扫配对。

⑤ 可选配置与提示

全部可选。常用示例：

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CWD=D:/workspace/project \
TUNNELBOX_CLAUDE_MODE=plan \
tunnelbox-claude-code

工具审批默认推送到手机审批卡（允许 / 拒绝 / 总是允许）；断线或 120 秒超时一律自动拒绝（fail-closed），绝不自动放行。模式可选 default / plan / acceptEdits / bypassPermissions。

① 前置条件

Node.js ≥ 22
OpenAI 账号（ChatGPT Plus / Pro，或平台 API key）

② 安装 Codex CLI（官方）

先安装 Codex CLI 本体（官方安装脚本或 npm）：

# macOS / Linux（官方安装脚本）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows PowerShell
irm https://chatgpt.com/codex/install.ps1 | iex

# 或 Node：npm install -g @openai/codex
npm install -g @openai/codex

安装后运行 codex --version 确认，然后 codex login 完成登录。

③ 安装 tunnelbox 适配器

1用 npm 全局安装适配器（无需克隆仓库）

# 无需克隆仓库
npm install -g @tunnelbox/codex

④ 运行与配对

2启动适配器（常驻电脑），终端打印二维码与配对码。

tunnelbox-codex

✅ 看到二维码即成功，用手机扫一扫配对。

⑤ 可选配置与提示

全部可选。常用示例：

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CODEX_SANDBOX=workspace-write \
TUNNELBOX_CODEX_APPROVAL=on \
tunnelbox-codex

手机审批（实验）：codex 会经 PermissionRequest hook 把工具请求推到手机审批卡（默认开启，TUNNELBOX_CODEX_APPROVAL=off 关闭）；断线 / 超时一律自动拒绝（fail-closed）。放行边界仍由 --sandbox 决定（read-only / workspace-write / danger-full-access）。

① 前置条件

Node.js ^22.19 或 ≥24
DeepSeek API key（dsh 凭证文件 $DSH_HOME/.credentials.yaml，默认 ~/.dsh）

② 安装 DeepSeek Harness（官方）

先安装 dsh 本体（DeepSeek 官方 npm 包，需 Node.js ^22.19 或 >=24）：

# 全局安装 dsh（官方包）
npm install -g @deepseek-ai/dsh

# 或免安装快速体验：npx @deepseek-ai/dsh web

安装后运行 dsh --version 看到版本号即成功；首次使用需在 dsh 中配置 DeepSeek API key（保存到 $DSH_HOME/.credentials.yaml）。

③ 安装 tunnelbox 适配器

1从 npm 安装到 dsh 的 profile（一次性，无需克隆仓库）

dsh plugin --profile tunnelbox add @tunnelbox/dsh-tunnelbox
dsh --profile tunnelbox --dump-config   # 确认 tunnelbox-dsh 层

④ 运行与配对

2启动 harness + 插件，终端打印二维码与配对码：

dsh --profile tunnelbox

✅ 看到二维码即成功。模型 / 工作目录可在 profile 的 cordis.yml 中配置。

⑤ 可选配置与提示

全部可选。profile 配置示例（cordis.patch.yml）：

- id: tunnelbox-dsh
  config:
    relayUrl: 'wss://relay.tunnelbox.top'
    model: 'deepseek-v4-flash'
    cwd: 'D:/workspace/project'

审批遵循 dsh 的 approval / sandbox-policy（默认 workspace-write + ask），危险操作推送到手机。多实例：分别设置不同的 DSH_HOME 即可。

① 前置条件

Node.js ≥ 22.19
本机 OpenClaw Gateway 可运行（模型配置在 onboard 阶段完成）

② 安装 OpenClaw（官方）

先安装 OpenClaw（官方安装脚本）并完成 onboard 引导：

# macOS / Linux（官方安装脚本）
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

# 安装后完成引导
openclaw onboard

安装引导完成后 openclaw 命令可用、Gateway 正常运行即成功。

③ 安装 tunnelbox 适配器

1用 npm 全局安装适配器（无需克隆仓库）

# 无需克隆仓库
npm install -g @tunnelbox/openclaw

2放行首次设备配对（一次性）

适配器首次连接本机 Gateway 会发起设备配对请求，需要你手动放行：

openclaw devices list              # 记下 requestId
openclaw devices approve <requestId>

④ 运行与配对

3启动适配器（连接本机 Gateway），放行设备后终端打印 tunnelbox 二维码：

tunnelbox-openclaw

✅ 设备放行后看到二维码即成功，用手机扫一扫配对。

⑤ 可选配置与提示

全部可选。常用示例：

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789 \
tunnelbox-openclaw

会话删除 = 归档（Gateway 无硬删）。首次配对用的 bootstrap token 可经 openclaw configure --section gateway 设置，或用 TUNNELBOX_OPENCLAW_TOKEN。

① 前置条件

Node.js ≥ 22
Hermes 账号 / 模型 API key（hermes setup 时配置）

② 安装 Hermes Agent（官方）

先安装 Hermes Agent（官方安装脚本）并完成设置：

# 官方安装脚本
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 安装后完成设置
hermes setup

运行 hermes chat -Q -q "hi" 能正常应答即成功。

③ 安装 tunnelbox 适配器

1用 npm 全局安装适配器（无需克隆仓库）

# 无需克隆仓库
npm install -g @tunnelbox/hermes

④ 运行与配对

2启动适配器（常驻电脑），终端打印二维码与配对码。

tunnelbox-hermes

✅ 看到二维码即成功，用手机扫一扫配对。

⑤ 可选配置与提示

全部可选。常用示例：

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" \
tunnelbox-hermes

说明：本适配器（headless）不提供手机审批，危险操作由 hermes 自身安全策略兜底（fail-closed）；会话按 Hermes 真实会话续聊（首轮后自动发现会话 id）。交互式会话的审批/提问走 Hermes 官方原生插件（native-plugin/）。

① 前置条件

Node.js ≥ 22
Cursor 账号（headless 使用按 Cursor 计划计费）

② 安装 Cursor CLI（官方）

先安装 Cursor CLI 本体（官方安装脚本）：

# macOS / Linux（官方安装脚本）
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

运行 agent -p "hello" 能正常输出即成功（headless 走 Cursor 计费）。

③ 安装 tunnelbox 适配器

1用 npm 全局安装适配器（无需克隆仓库）

# 无需克隆仓库
npm install -g @tunnelbox/cursor

④ 运行与配对

2启动适配器（常驻电脑），终端打印二维码与配对码。headless 走 Cursor 计费，请确认在计划内。

tunnelbox-cursor

✅ 看到二维码即成功，用手机扫一扫配对。

⑤ 可选配置与提示

全部可选。常用示例（plan 模式 + 允许改文件）：

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CURSOR_MODE=plan \
TUNNELBOX_CURSOR_FORCE=1 \
tunnelbox-cursor

手机审批不可行（Cursor 官方 hooks 仅面向 IDE/Cloud agents，headless agent -p 无外部审批中继）；print 模式抑制思考流（无 thinking 卡）。放行由 permissions allow/deny + --force/--yolo + --sandbox 决定。默认只读（不传 --force，agent 只出方案不改文件）；要真正改代码需 TUNNELBOX_CURSOR_FORCE=1。未装 CLI？macOS / Linux：curl https://cursor.com/install -fsS | bash；Windows：irm 'https://cursor.com/install?win32=true' | iex。

进阶：更多智能体与自托管

各适配器 README：上方「各智能体安装手册」之外，更深入的架构 / 协议细节见仓库 plugin/ 下各适配器的 README。
自托管中继：docker compose up -d 一键部署 relay（可选 MySQL 持久化），配 nginx 反代 HTTPS；配置 NATS_URL 即可多节点横向扩展。

GitHub 仓库 → 需求文档与接口规范 →

常见问题

FAQ

我的电脑没有公网 IP，在公司网络 / 宿舍能用吗？

可以。电脑端适配器只发出站 WebSocket 连接（反向连接），无需公网 IP、端口映射或隧道，可穿透 NAT 与防火墙，公司网络也可正常使用。

我的消息会经过中继，安全吗？

中继仅做无状态转发，不落盘任何会话内容；全链路 TLS；配对码一次性且 10 分钟过期；会话 token 以 sha256 哈希存储。对隐私敏感的用户可选择自托管中继，数据完全在自己服务器上。

会话历史存在哪里？

只存在你电脑上智能体的本地存储。App 打开会话时实时向电脑拉取；电脑关机或插件离线时无法获取历史；中继不做云同步或备份——这正是"隐私友好 + 低成本"的设计取舍。

支持哪些智能体？能同时开多个吗？

支持 opencode、Claude Code、Codex、DeepSeek Harness、OpenClaw、Hermes、Cursor，且同类型可多开（如 opencode1 / opencode2），每个独立配对与连接，手机端列表一键切换，可让不同智能体跑同一任务横向对比。

危险操作一定会经过我审批吗？

是的。执行 bash / 编辑文件等工具调用时，遵循各智能体原生的 ask / 审批模型把权限请求推送到手机，人工允许 / 拒绝后才执行；也可对某工具选择「总是允许」（仅当次会话）。

免费吗？可以自托管 / 部署吗？

开源免费（详见仓库 LICENSE）。relay 可自托管：Docker / docker compose 一键部署，nginx 反代 HTTPS，支持 MySQL 持久化与 NATS 多节点扩展；Android / iOS App 已在官网提供下载。

和 AionUi 这类产品有什么不同？

tunnelbox 以手机远程控制为核心：中继反向连接 + Android/iOS 原生 App，随时随地遥控电脑上的多个 CLI 智能体；统一协议、无状态中继、自托管友好，一台电脑跑多个智能体统一管理。

用手机遥控电脑上的 AI 智能体

一个"遥控器"，指挥你所有 AI

反向连接，免公网 IP

多智能体同机并存

危险操作手机审批

扫码即配对

统一协议，后端零感知

隐私优先

主流 CLI 智能体，全部纳入

反向连接 + 无状态中继

手机端

中继 relay（Go）

电脑端

现在就用起来

tunnelbox App

三步配对，四步起飞

第 1 步 · 电脑上运行你的智能体适配器

第 2 步 · 在手机上安装并打开 tunnelbox App

第 3 步 · 扫一扫配对

第 4 步 · 开始远程操作

各智能体安装手册

① 前置条件

② 安装 opencode（官方）

③ 安装 tunnelbox 适配器

④ 运行与配对

⑤ 可选配置与提示

① 前置条件

② 安装 Claude Code（官方）

③ 安装 tunnelbox 适配器

④ 运行与配对

⑤ 可选配置与提示

① 前置条件

② 安装 Codex CLI（官方）

③ 安装 tunnelbox 适配器

④ 运行与配对

⑤ 可选配置与提示

① 前置条件

② 安装 DeepSeek Harness（官方）

③ 安装 tunnelbox 适配器

④ 运行与配对

⑤ 可选配置与提示

① 前置条件

② 安装 OpenClaw（官方）

③ 安装 tunnelbox 适配器

④ 运行与配对

⑤ 可选配置与提示

① 前置条件

② 安装 Hermes Agent（官方）

③ 安装 tunnelbox 适配器

④ 运行与配对

⑤ 可选配置与提示

① 前置条件

② 安装 Cursor CLI（官方）

③ 安装 tunnelbox 适配器

④ 运行与配对

⑤ 可选配置与提示

进阶：更多智能体与自托管

FAQ

把 AI 装进口袋，现在出发

用手机遥控
电脑上的 AI 智能体