@tunnelbox/cursor

English · 简体中文

官网： www.tunnelbox.top

tunnelbox Cursor 适配器（独立进程）：用手机远程驱动电脑上的 Cursor agent——会话 / 流式 / 工具审批 / 结构化提问与计划审批 / 中止 / 删除。它驱动 Cursor CLI 的 ACP 模式（agent acp），只向中继发出站连接（无需公网 IP / 端口映射）。

手机 App ──WSS──► relay ──WSS──► tunnelbox-cursor（本适配器）
                                      └─ agent acp   （Agent Client Protocol，stdio 上的 JSON-RPC）

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

在装有 Cursor CLI 并已配置的电脑上，按以下步骤操作一次即可。

第 0 步 — 准备手机

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

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

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

前置条件：Node.js ≥ 22，且本机已安装并登录 Cursor CLI（agent -p "hello" 可正常输出，且 agent acp 可用）。headless/ACP 走 Cursor 计费，需在你的套餐计划内。

npm install -g @tunnelbox/cursor

第 2 步 — 运行

tunnelbox-cursor

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

第 3 步 — 与手机配对

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

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

第 4 步 — 在手机上使用

在 App 里打开这台电脑，即可新建会话、发消息、看流式输出（含思考）、批准/拒绝工具调用、回答选择题与计划审批、中止运行中的会话。

配置

| 环境变量 | 默认 | 说明 | |---|---|---| | TUNNELBOX_RELAY_URL | state 保存的地址 | 中继地址 | | TUNNELBOX_CWD | process.cwd() | 默认工作区（agent 在该目录跑） | | TUNNELBOX_CURSOR_TRANSPORT | acp | acp（流式 + 手机审批/选择）或 print（旧 agent -p，无手机审批） | | TUNNELBOX_CURSOR_MODE | agent | agent / plan / ask（--mode） | | TUNNELBOX_CURSOR_MODEL | Cursor 默认 | --model | | TUNNELBOX_CURSOR_FORCE | 关 | 加 --force：自动放行工具调用（绕过手机审批） | | TUNNELBOX_CURSOR_YOLO | 关 | 加 --yolo（--force 别名，危险） | | TUNNELBOX_CURSOR_SANDBOX | enabled | --sandbox enabled/disabled | | TUNNELBOX_CURSOR_BIN | agent | Cursor CLI 可执行名/绝对路径 | | TUNNELBOX_CURSOR_ACP_ARGS | — | 追加到 acp 之后的参数 | | TUNNELBOX_CURSOR_ASK_BRIDGE | 开 | 设 0 关闭 MCP ask 桥（无选择卡） |

TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_CURSOR_MODE=plan tunnelbox-cursor

能力位

| 能力 | 值 | 说明 | |---|---|---| | streaming | ✅ | session/update 增量（agent_message_chunk delta） | | thinking | ✅ | agent_thought_chunk 增量（Cursor 提供时） | | permission | ✅ | session/request_permission → 手机审批卡；fail-closed | | questions | ✅ | 经注入的 MCP 工具 tunnelbox_ask / tunnelbox_plan → 手机选择卡/计划审批卡（Cursor ACP 无内建 AskQuestion 工具） | | commands | ✅ | /new、/help | | abort | ✅ | session/cancel | | workspaces | ✅ | 会话 cwd（session/new） |

审批与权限

• ACP 提供 session/request_permission：工具需要审批时，适配器推送手机审批卡并等待决定（allow-once / allow-always / reject-once）。
• fail-closed：离线、120s 超时、中继断开、进程退出或中止，一律回拒绝 / cancelled，绝不自动放行。
• --force / --yolo（环境变量 TUNNELBOX_CURSOR_FORCE / TUNNELBOX_CURSOR_YOLO）会让 Cursor 自动放行并绕过手机审批卡。除非理解风险，否则请保持关闭。
• 旧 print 传输无审批通道（permission=false）。

选择与计划审批（MCP ask 桥）

Cursor CLI 的 ACP 模式不给模型内建「AskQuestion」工具，因此适配器在每个会话注入一个本地 MCP server（session/new 的 mcpServers），提供两个工具：

• tunnelbox_ask —— 让用户在手机上做选择（单选/多选），阻塞等待作答；
• tunnelbox_plan —— 让用户在手机上批准一项计划。

工具会调用适配器内的本地 HTTP 桥（127.0.0.1 + 随机 token），由桥下发 question.request / permission.request 到手机并回填答案。首次调用前 Cursor 会先弹一次工具审批卡。可用 TUNNELBOX_CURSOR_ASK_BRIDGE=0 关闭。

会话模型

• 会话 = 本地镜像（~/.tunnelbox/cursor-sessions/<uuid>/）：每个流式部件/用户消息即时落盘，供列表/历史/删除。
• 续聊：ACP sessionId 记入镜像 meta，用 session/load（或 agent 声明支持时 session/resume）恢复上下文；恢复失败则新建会话。
• 状态文件：~/.tunnelbox/remote-state.cursor.json。

安全说明

• 默认不传 --force，因此每个受门控的工具调用都需要手机审批（fail-closed）；
• 请勿在不受信目录启用 --yolo；
• 请勿把敏感工程目录暴露给不受信手机。

多语言

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

故障排查

| 问题 | 解决 | |---|---| | 终端没有二维码/配对码 | 运行 tunnelbox-cursor --pair 打印新码 | | 需要换手机配对 | 在 App 设置里解绑，再带 --pair 运行 | | 已绑定但手机连不上 | 确认两端同一中继；查看 ~/.tunnelbox/tunnelbox.log | | 不支持 agent acp | 升级 Cursor CLI，或设 TUNNELBOX_CURSOR_TRANSPORT=print（失去手机审批） | | 使用自建中继 | 启动时带 TUNNELBOX_RELAY_URL=wss://<你的中继> |

状态文件

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

卸载

npm uninstall -g @tunnelbox/cursor

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

开发

实现细节（协议映射、源码结构、决策记录、待实测项）保存在源码仓库中本包旁的 DEV.md 与仓库 docs/ 下。离线 ACP 测试：npm run e2e；真机探针：npm run probe -- "提示词"。