第 02 模块 · 3 节

Remote Orca Servers 与 orca serve

《Orca 生产级工程》02 远程与多机运行 · 本节时长 26 分钟

一台机器干活,一台机器看Remote Orca Server 让一台电脑干活、另一台只提供 UI。服务器持有项目、工作树、终端、标签、提供方账号与 Agent 会话;笔记本、浏览器客户端、手机接入这个运行中的 Orca 实例。

谁跑什么

客户端(Client) 服务器(Server)
显示 UI、发送输入 存放仓库与工作树
运行终端与 Agent

凭据在服务器上:Codex、Claude Code、OpenCode、git 与各 provider CLI 都要装在服务器并登录。笔记本上的登录不会自动带到服务器。


最简路径:桌面 App + Tailscale

两端装 Orca + Tailscale,加入同一 tailnet(服务器私有地址通常以 100. 开头):

  1. 服务器端:Settings → Remote Orca Servers → Advertise this app as a server → New Link → 连接地址选 Tailscale 地址 → Generate Access Link → 复制配对 URL
  2. 客户端:Settings → Remote Orca Servers → Add Server → 起个名(如 Remote Server)→ 粘贴配对 URL → Add Server
  3. 显示 Disconnected 就点 Connect;Advanced → Active Server 才把新项目默认路由到服务器

安全红线:配对 URL 相当于访问口令,只能发给要配对的客户端;不要直接把 Orca 端口暴露到公网,优先 Tailscale / WireGuard / 可信 LAN / SSH 隧道 / 认证隧道。令牌逐个客户端独立、可撤销。


无头替代:orca serve

无桌面窗口的运行方式(无头 Linux、服务管理的 VM):

orca serve --pairing-address 100.64.1.20
  • 无窗口启动 Orca 运行时,前台运行直到 Ctrl-C
  • 打印绑定的 endpoint 与运行时配对 URL
  • 需要固定端口时加 --port 6768
  • 手机接入用 --mobile-pairing(打印移动端 QR 与链接)
  • 一台主机同一时间只用一个 host 模式:桌面 App 已在共享时别再起第二个 serve

无头服务器上注册托管账号与技能(远程客户端会禁用 Add account):

orca account add --agent claude
orca account add --agent codex
orca account list
orca skills install --skill orca-cli --skill orchestration

Server 的日常行为

  • Agent 在客户端笔记本休眠或断开时继续跑
  • 服务器需保持在线并连 tailnet;重连/重开客户端回到服务器持有的工作区、标签与可见面板状态,不会重复配对标签
  • 服务器上删除的项目从所有配对客户端消失(无幽灵行)
  • 多客户端共享时,侧边栏筛选可开 Hide other-client workspaces

SSH 还是 Server?

维度 SSH 工作树 Remote Orca Server
运行时归属 笔记本 Orca 远程机器(桌面 or orca serve)
断连 Agent 在主机上继续,笔记本重挂 完整会话状态留在服务器
多客户端 一台笔记本驱动主机 笔记本、web、移动端、自动化共享同一运行时
典型配置 导入 SSH config、选 Run on 共享 App 或跑 serve,URL 配对

落地练习:搭一次配对

  1. 两端装 Orca + Tailscale 并同 tailnet
  2. 服务器生成访问链接,客户端 Add Server 配对
  3. 在服务器端跑一个 Agent,笔记本休眠再唤醒,确认 Agent 没停
  4. 试一次 orca serve --pairing-address(或至少看它的文档输出)
  5. 在服务器上 orca account list 确认账号

怎么判断做对了?——客户端重连后回到同一工作区,Agent 会话仍在,且没有重复的配对标签。

卡住了怎么办? 地址没列出:确认 Tailscale 已连、点连接地址旁的刷新;配对失败:检查两端同 tailnet,URL 别含尾随字符。


小结

  1. Server 持有完整运行时,客户端只是 UI
  2. 最简配对:两端 Orca + Tailscale + 访问链接
  3. orca serve 提供无头运行时,含 mobile-pairing
  4. 令牌逐客户端独立可撤销;别把端口暴露公网
  5. 选型:SSH 偏「借算力」,Server 偏「共享运行时」

下一节,编排与自动化。