Agent Office 隧道详解:tunnel 如何把 worker 的服务器拉到你的电脑
Agent Office 隧道详解:tunnel 如何把 worker 的服务器拉到你的电脑
Agent Office(一个卡通 3D 虚拟办公室,团队在其中雇佣 Claude Code 等 AI worker 干活)自带一条命令行隧道:agent-office tunnel 把远程服务器上 worker 启动的 web 服务(如 npm run dev)自动映射到你本地电脑的相同端口,实现"服务器在云上,预览在本机"的无缝体验。本文带你一次看懂它的工作原理、用法与安全设计。
为什么需要这条隧道?
当 Agent Office 部署在远程服务器(AWS、Railway、Fly.io 等)上时,worker 启动的开发服务器监听在那台机器上,而不是你的电脑。你本机的 http://localhost:5173 打不到 worker 的 Vite 服务,设计师和队友也很难直接"看到"worker 的产出。
tunnel 命令正是为此而生(详见官方文档 docs/tunnel.md):
- 同一端口:worker 在 5173 起服务,你本地就打开 5173;worker 停掉服务,几秒后端口自动关闭。
- 零维护:不需要每个服务单独执行命令,新服务出现时自动开通。
- 一行搞定:
agent-office tunnel office@203.0.113.7
这个 SSH 地址就是办公室内 👥 Invite teammates 面板显示的地址(在 Railway、Fly.io、Dokploy 上形如 ssh://office@host:2222)。运行后它会自动:① 打通到办公室的 SSH 隧道;② 在浏览器打开办公室;③ 持续跟踪所有 worker 的服务端口。
快速上手:安装与登录
tunnel 是 agent-office 的一部分,要求 Node.js 20+,安装后无需在本地跑办公室:
# 仅安装、不启动办公室(Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/AgentSystemLabs/agent-office/main/install.sh | AGENT_OFFICE_INSTALL_ONLY=1 bash
首次运行会以和浏览器相同的方式登录:在终端输入办公室密码(有账号则输入名字和密码)。登录态保存在 ~/.config/agent-office/tunnel.json(仅当前用户可读),两周内不用重复输入;删除该文件即登出。脚本场景可改用环境变量 AGENT_OFFICE_PASSWORD(配合 --name)。
💡 如果办公室版本过旧(无法列出 worker 的服务),命令会明确提示:通过 ☰ 菜单 → ⬆️ Upgrade the office 或部署脚本的
update升级后再试。
工作原理:三个角色协同
隧道功能的核心代码集中在 src/server/tunnel/ 目录,它是整个项目里唯一运行在你自己电脑上的组件:
1️⃣ 服务器端:每 4 秒扫描端口
办公室每 4 秒扫描一次本机 TCP 监听端口(Linux 用 ss,macOS 用 lsof),把每个端口归属到启动它的 worker(按进程树、AGENT_OFFICE_WORKER_ID 环境变量、worktree 工作目录逐级判断),只发布应答 HTTP 的端口,并抓取页面 <title> 作为服务名。逻辑在 services.ts 中。
2️⃣ 本地端:轮询 + 同步端口
tunnel 客户端每 2 秒请求一次 GET /api/services(见 index.ts 中的 POLL_MS),对比"办公室列表"与"本地已打开的端口",差量同步:
- 新端口 → 在本地
127.0.0.1和::1上监听; - 服务消失 → 端口保留约 10 秒再关闭(forwarder.ts 中的
LINGER_MS),避免开发服务器热重启时"闪断"; - 端口被占用 → 跳过并提示,等端口空闲后自动开启;
- WebSockets 也被转发,所以 Vite 热更新(HMR)正常工作。
3️⃣ 转发链路:一切流量只走办公室这一个端口
这是设计最巧妙的地方:本地收到的请求并不直连 worker,而是发给办公室自己的端口(默认 4600),由办公室中继(relay)到 worker 的服务器。办公室通过请求头 x-agent-office-service: <port> 或 Host 名(localhost:5173)判断该请求属于哪个 worker,转发逻辑在 relay.ts 与 wire.ts 中定义。
这带来两个好处:
- 被邀请的 SSH 密钥只需允许转发那一个端口即可,不需要为每个服务开新端口;
- worker 的服务器永远看不到办公室的会话 Cookie,中继时会剥离(
withoutOfficeCookies)。
🔄 断线自动重连
SSH 隧道断开(笔记本休眠、Wi-Fi 切换)时,客户端在约一分钟内感知到(ServerAliveInterval=15 心跳探测,见 ssh.ts),随后以指数退避(2s → 4s → … 最长 30s)自动重连,重连期间本地端口保持打开。
常用命令选项一览
agent-office tunnel [地址] [选项] [-- <ssh 选项>]
-p, --port <n> SSH 方式下,办公室在本机占用的端口
--office-port <n> 办公室在其机器上的端口(默认 4600)
--name <name> 以指定账号登录(或 AGENT_OFFICE_NAME)
--password <pw> 直接提供密码(或 AGENT_OFFICE_PASSWORD)
--no-open 不自动打开浏览器
--insecure 接受自签名证书(--self-signed 启动的办公室)
-- 之后的参数原样传给 ssh,例如使用非默认密钥:
agent-office tunnel office@203.0.113.7 -- -i ~/.ssh/office
如果办公室已经能通过浏览器访问(本地部署、自有域名或 tailnet),直接把该地址传给 tunnel 即可,它不会改动你现有的访问方式:
agent-office tunnel https://office.example.com
办公室里 🌐 Services 面板(挂在休息区墙上,也可从 ☰ 菜单 打开,代码在 services.ts)会按你当前的进入方式显示可复制的 tunnel 命令;单击某一行还能生成只转发单个服务的裸 ssh -L 命令——无需安装任何东西就能临时预览某个 worker 的产出。
安全设计:隧道"能做什么"与"不能做什么"
- 只监听本机回环地址(
127.0.0.1/::1),且只接受 Host 为localhost的请求——外网网页无法把自己的域名指向这些端口(wire.ts 中的LOOPBACK_NAME校验,不匹配返回 421); - 登录态即通行证:tunnel 自身完成了办公室登录,所以浏览器、
curl、测试脚本都能直接使用这些端口,无需再输入密码——相当于在本机跑了一个开发服务器; - 只中继、不越权:中继请求永远只去 worker 的 web 服务;端口上没服务时返回 "Not running" 页面,绝不会把办公室自身的页面暴露出去;
- Ctrl-C 一键全关:所有本地端口随命令退出而释放;
- 登录会话(而非密码)存于权限 0600 的
tunnel.json,见 session.ts。
延伸阅读:相关文件
| 内容 | 路径 |
|---|---|
| 隧道功能官方文档 | docs/tunnel.md |
| 客户端入口(命令解析、轮询循环) | src/server/tunnel/index.ts |
| 本地端口监听与同步 | src/server/tunnel/forwarder.ts |
| SSH 隧道与自动重连 | src/server/tunnel/ssh.ts |
| 登录与会话持久化 | src/server/tunnel/session.ts |
| 客户端↔办公室的通信协议 | src/server/tunnel/wire.ts |
| 服务器端请求中继 | src/server/relay.ts |
| 端口扫描与归属判断 | src/server/services.ts |
| 整体架构说明(含 Services 一节) | docs/how-it-works.md |
| 各云平台部署指南 | docs/aws.md、docs/fly.md、docs/railway.md |
小结
agent-office tunnel 用"每 2 秒轮询 + 端口差量同步 + 单一入口中继"三板斧,把远程 worker 的 web 服务像本地开发一样自然地搬到你的电脑上:同端口、热更新可用、断线自愈、权限最小化。只要在你的电脑终端里让它安静地跑着,团队里的任何人都可以实时查看 AI worker 构建的每一版页面。