文档 / 远程 Orca 服务器
远程 Orca 服务器让一台计算机执行工作，而另一台计算机提供 UI。服务器保存项目、工作树、终端、标签页、提供商账户和代理会话。你的笔记本电脑连接到正在运行的该 Orca 实例。
最简单的设置是在两台计算机上都安装 Orca 桌面应用，并通过 Tailscale 连接。此路径无需运行 orca serve。
远程 Orca 服务器处于 Beta 阶段。请将服务器和客户端保留在你控制的私有网络路径上， 例如同一个 Tailscale tailnet 或 LAN。
在哪里运行¶
Client computer · Orca client
Shows the UI and sends your input
│
│ private network route
▼
Server computer · Orca server
Stores repos and worktrees
Runs terminals and agents
请在服务器计算机上安装并认证 Codex、Claude Code、OpenCode、git 以及任何提供商 CLI。笔记本电脑上的登录状态不会自动同步到服务器。
在无头 orca serve 主机上，请从服务器 shell 注册托管的 Claude/Codex 账户（远程客户端会禁用添加账户）：
无需设置界面即可安装或刷新代理技能：
推荐：桌面应用 + Tailscale¶
你需要：
- 两台计算机均已安装并更新 Orca
- 两台计算机均已安装 Tailscale
- 两台计算机均已登录到同一个 tailnet
- 服务器计算机处于唤醒、在线状态，并且正在运行 Orca
Tailscale 会为服务器提供一个通常以 100. 开头的私有地址。Orca 会将其放在连接地址选择器的首位。
1. 在服务器上创建访问链接¶
在应当保持会话运行的那台计算机上：
- 打开 Orca 桌面应用。
- 打开设置 → 远程 Orca 服务器。
- 在将此应用作为服务器发布下，点击新建链接。
- 对于连接地址，选择 Tailscale 地址。它通常形如
100.x.y.z。 - 点击生成访问链接。
- 复制配对另一个 Orca 客户端下的链接。
如果缺少 Tailscale 地址，请确认 Tailscale 已连接，并点击连接地址旁的刷新按钮。
配对 URL 授予对此 Orca 运行时的访问权限。请像对待密码一样对待它，并只发送给你打算配对的 客户端。
2. 在笔记本电脑上添加服务器¶
在你打算用作客户端的计算机上：
- 打开设置 → 远程 Orca 服务器。
- 点击添加服务器。
- 输入一个易于识别的名称，例如
Remote Server。 - 粘贴来自服务器的访问链接。
- 点击添加服务器。
- 如果已保存的服务器显示已断开，请点击连接。
添加服务器会将其保存，而不会强制将所有新项目都放到该服务器上。只有当你希望服务器路由的项目、终端、提供商检查以及浏览器或移动端交接默认使用该服务器时，才打开高级 → 活动服务器。
使用远程服务器¶
当服务器显示已连接后，选择它或它的某个项目，然后正常使用 Orca。终端、代理进程、文件、工作树和会话状态都位于服务器计算机上。
当多个已配对客户端共享该服务器时，侧边栏筛选器可以提供隐藏其他客户端的工作区，以便此设备仅列出它创建的工作区。参见工作树 → 侧边栏布局。
这意味着：
- 当客户端笔记本电脑休眠或断开连接时，代理会继续运行；
- 服务器需要这些代理使用的仓库、工具和凭据；
- 服务器必须保持唤醒并连接到 tailnet；
- 重新连接客户端或重新打开 Orca 会返回到由服务器拥有的工作区、标签页和可见窗格状态，而不会重复已配对的标签页；
- 你在服务器上删除的项目会从每个已配对客户端的侧边栏中消失（不会出现永久残留行）。
访问与安全¶
Orca 会为每个已配对客户端创建独立的、可撤销的 token。服务器会在共享服务器访问下列出这些 token。
- 点击授权旁边的垃圾桶按钮以撤销它。正在使用该授权的活跃客户端会立即断开连接。
- 生成另一个链接会替换之前未使用的链接。已经配对的客户端会保留它们自己的授权，直到你撤销它们。
- 请将 Tailscale ACL 或授权范围保持得尽可能窄，以你的配置允许为限。
- 不要将 Orca 端口直接转发到公共互联网。优先使用 Tailscale、WireGuard、受信任的 LAN、SSH 转发或经过身份验证的隧道。
- 不要为另一台计算机选择
127.0.0.1。该地址仅在服务器本机上有效。
替代方案：orca serve¶
当主机应当在没有桌面窗口的情况下运行时，使用 orca serve——例如无头 Linux 服务器或服务管理的 VM。对于你可以保持登录状态的 MacBook 或桌面，上述应用内设置更简单。
在服务器上安装 Orca 及其捆绑的 CLI，然后运行：
Linux CLI 的名称是 orca-ide，因为 GNOME Orca 屏幕阅读器已经占用了
/usr/bin/orca。打包的 orca serve 确实会将一个单独的 orca 写入 ~/.local/bin，但只在其启动时写入，因此该垫片永远不可能是启动服务器的命令。当主机为 Linux 时，在本页中请将 orca
serve 读作 orca-ide serve。参见安装 →
Linux。
orca serve --pairing-address <server-tailscale-ip-or-hostname>
# Linux
orca-ide serve --pairing-address <server-tailscale-ip-or-hostname>
例如：
该命令：
- 在不打开桌面窗口的情况下启动 Orca 运行时；
- 在前台运行，直到你按下
Ctrl-C； - 打印绑定的端点和运行时配对 URL；
- 仅将
--pairing-address用作客户端应拨号的地址。
将打印出的配对 URL 粘贴到客户端的设置 → 远程 Orca 服务器 → 添加服务器中。
当防火墙、隧道或服务定义需要固定端口时，添加 --port 6768：
orca serve --port 6768 --pairing-address 100.64.1.20
# Linux
orca-ide serve --port 6768 --pairing-address 100.64.1.20
每次只使用一种主机模式。如果 Orca 桌面应用已在共享该计算机，请勿为同一配置启动第二个 orca serve 进程。
无头服务器上的移动设备¶
对于 Orca 移动应用，请请求一个移动设备专用的二维码和链接：
orca serve --pairing-address 100.64.1.20 --mobile-pairing
# Linux
orca-ide serve --pairing-address 100.64.1.20 --mobile-pairing
保持手机位于同一 tailnet，打开 Orca Mobile，选择 配对，然后扫描终端中的二维码或粘贴打印出的链接。
桌面应用还是 orca serve？¶
| 服务器上的桌面应用 | orca serve |
|
|---|---|---|
| 最适用于 | 旧笔记本电脑、Mac mini 或台式机 | 无头 Linux 设备、虚拟机或托管服务 |
| 设置 | 设置和按钮 | 终端命令和服务配置 |
| 服务器窗口 | 打开 | 无 |
| 访问链接 | 新建链接 → 生成访问链接 | 打印在终端中 |
| 生命周期 | 桌面应用运行期间 | 前台进程或服务运行期间 |
远程 Orca 服务器还是 SSH？¶
当笔记本电脑上的 Orca 应拥有运行时，并且仅使用另一台机器来运行选定的工作树和终端时，请使用 SSH 工作树。
当另一台机器应拥有完整的 Orca 运行时，并为桌面、浏览器、移动或自动化客户端保留共享会话时，请使用远程 Orca 服务器。
有关完整对比，请参阅 运行 Orca 的方式。
故障排除¶
未列出 Tailscale 地址¶
在服务器上，确认 Tailscale 已连接，然后单击 连接地址 旁边的刷新按钮。两台计算机都必须登录到同一 tailnet。Tailscale IPv4 地址通常以 100. 开头。
服务器已断开连接¶
确认服务器计算机已唤醒，Orca 仍在运行，并且 Tailscale 显示两台设备均在线。如果一台设备无法访问另一台设备，请检查你的 tailnet ACL 或授权。
如果服务器行报告了不兼容的协议版本，请在两台计算机上更新 Orca。
访问链接被共享给了错误的人¶
在服务器上，打开 设置 → 远程 Orca 服务器 → 共享服务器访问，并撤销该授权。为预期客户端生成一个新链接。
服务器找不到代理 CLI¶
在服务器计算机上安装并认证该 CLI。远程会话使用服务器的 PATH、主目录和凭据，而不是客户端的。
orca serve 广播了错误的地址¶
停止该命令，并使用客户端可以访问的地址重新启动它：
不要为远程客户端使用通配符地址或 127.0.0.1。
后续步骤¶
- 在 运行 Orca 的方式 中比较所有运行模式。
- 当笔记本电脑应拥有 Orca 运行时，请使用 SSH 工作树。
- 有关
orca serve标志和自动化命令，请参阅 Orca CLI 参考。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 orca48/orca