文档 / 运行 Orca 的方式

Orca 并不局限于你的笔记本电脑。每个工作树（worktree）都运行在某个地方——你面前的机器上、你自己已有的某台机器上、共享的常驻服务器上，或是为某个工作区专门启动的全新云 VM 上。

本页是导览图。深入内容位于链接页面中。

概览¶

Orca 不销售托管 VPS 服务。远程模式始终使用由你掌控的机器和云账户。

1. 本地桌面¶

安装 Orca，打开项目，创建工作树。智能体、终端和浏览器与 UI 运行在同一台机器上。

这是大多数人的默认路径。参见你的首次 3 智能体会话和工作树。

2. SSH 目标¶

将 Orca 指向任何 SSH 主机——性能更强的 Mac mini、Linux VPS、GPU 机器、带 SSH 的云沙箱。创建工作树时，在 Run on 下选择该主机。智能体和 git worktree 在远程运行；编辑器、diff 和 UI 留在你的笔记本电脑上。

适合场景：远程主机上已经备好你的仓库、工具和凭据，而你希望用一台笔记本电脑上的 Orca 驱动多台机器。

设置概要：

1. 在设置 → SSH下添加主机。
2. 测试连接（主机上必须安装 git 才能使用仓库工作树）。
3. 创建工作树，并在 Run on 下选择 SSH 目标。自动补全列表会列出已就绪的主机；对于已连接但尚未针对该项目完成设置的主机，会显示不可选的 setup-needed 行。

SSH 工作树可以在 VS Code Remote-SSH 中打开；在 SFTP 允许的情况下可以下载远程文件夹；即使远程主机无法编译终端原生组件（请为 shell 安装构建工具），文件和 git 功能也仍然可用。详情参见 SSH 工作树和教程通过 SSH 在远程机器上工作。

3. 远程 Orca 服务器¶

让 Orca 在你掌控的机器上持续运行——旧笔记本电脑、Mac mini、家庭服务器、云 VPS 或团队机器。将你的笔记本电脑、浏览器客户端或手机与该运行时配对。服务器持有项目、工作树、终端和智能体进程；客户端只是 UI。

适合场景：

• 你希望笔记本电脑休眠后智能体仍继续运行
• 移动端应能重新连接到相同的会话
• 自动化或后端应在稳定主机上启动会话

最简单的设置：在两台电脑上都安装 Orca 和 Tailscale。在服务器上，打开 设置 → 远程 Orca 服务器 → 将此应用作为服务器广播 → 新建链接，选择其 Tailscale 地址，并生成访问链接。在客户端上，选择 添加服务器，粘贴该链接。

对于无头 Linux 服务器或由服务托管的 VM，可以使用 orca serve 作为替代方案。在 Linux 上，CLI 名为 orca-ide，因此首次启动命令是：

orca-ide serve --pairing-address <reachable-tailscale-ip-or-hostname>

完整详情：远程 Orca 服务器。

SSH 与远程 Orca 服务器¶

4. 云 VM（按工作区环境）¶

每个工作树都可以根据检入仓库的配方（recipe）（orca.yaml + 生命周期脚本）启动自己独立的按需环境——云沙箱、VM 或本地 Docker 容器。创建即启动；挂起/恢复/销毁即拆除。Orca 只是一个轻量封装：你的服务商账户、镜像和账单仍然属于你。

在产品 UI 中，该界面位于设置 → 实验功能下，标签为 Cloud VM。配方仍然会创建按工作区划分的环境。

目前人们接入的服务商包括 Vercel Sandbox、Fly、Modal、普通 SSH 主机和本地 Docker。连接方式要么是 Orca 服务器（配方启动 orca serve 并返回配对 URL），要么是 SSH（配方返回连接详情，Orca 据此拨号连接）。

适合场景：你希望每个任务都有干净的隔离、可销毁的计算资源，或者希望所有智能体都启动到同一个标准环境中。

设置概要：

1. 在设置 → 实验功能下启用 Cloud VM。该面板包含简短的 Create a Cloud VM 指南，以及配方/运行时控制项。
2. 如有需要，安装/更新 Cloud VM / 按工作区环境技能（skill）。
3. 在任意工作区中，向智能体发出请求：

Use the orca-per-workspace-env skill to set up a per-workspace environment for this repo.

1. 该技能依次引导：前置条件 → 基础快照 → 代理身份验证 → orca.yaml 配方 → doctor 验证。
2. 当 配方 部分出现配方时，创建一个工作树，并在 运行于 下选择它。

配方仅当 environmentRecipes 条目位于项目 orca.yaml 的 主 检出（而不仅是功能分支）上时，才会在工作区创建中显示。在你迭代脚本期间，Doctor 和实时配置仍可从任意分支运行。

云 VM 不会为你提供 Orca 托管的 VPS。你自行提供提供商（并向该提供商付费）。Orca 运行你的 create/suspend/resume/destroy 脚本，并通过它们打印的配对 URL 或 SSH 详情进行连接。

如何选择¶

• 保持本地：如果笔记本电脑足够快，且代理是短生命周期的。
• SSH：如果你已有 VPS 或开发机，并希望将代理放在那里，而无需安装第二个 Orca 运行时。
• 远程 Orca 服务器：如果你希望有一个始终在线的 Orca 运行时，用于移动端、浏览器和自动化。
• 云 VM / 按工作区环境：如果每个任务都应获得一个全新的、由配方定义的沙箱，并且该沙箱随工作树一起销毁。

你可以在一个安装中混合使用多种模式：本地工作树用于快速编辑，SSH 用于 GPU 机器，以及一个配方用于类似 CI 的隔离。

相关¶

• SSH 工作树
• 远程 Orca 服务器
• 工作树
• 移动端
• 设置参考