文档 / 移动伴侣

Orca 移动伴侣是一款 iOS/Android 应用，可与桌面端 Orca 配对，并为你提供运行中 agent 的以只读为主的视图——包括 agent 状态、最近的终端滚动历史，以及你真正希望从手机上使用的控制（回复 prompt、让工作树休眠、查看源代码控制、切换 agent 账户）。配对只需一次，桌面端始终是权威来源。

移动伴侣目前处于 beta 阶段。从 App Store 安装 iOS 版本，加入 TestFlight 预览 渠道，或从 当前 APK 0.0.48 安装 Android 版本。

移动端可以做什么¶

• 查看每个工作树、其 agent 以及当前状态（工作中 / 已完成 / 等待输入）。移动端会在单个视图中列出你已连接的所有主机（本地桌面和远程 Orca 服务器）上的工作树，因此在它们之间切换无需更换设备。
• 从移动端浏览工作区的完整文件树——包括深层嵌套路径——这样你可以直接打开任意文件，而无需等待桌面端。
• 在 Chat UI（聊天式记录）或原始终端中打开受支持的 agent 会话。在 Settings → Chat UI 中设置设备默认值，或长按会话标签以仅切换该标签。
• 加载最近的终端滚动历史，以便查看 agent 执行或询问了什么。聊天式视图中的 Markdown 可以在消息包含图表时渲染 Mermaid 图表。
• 从移动终端视图中选择、复制和粘贴文本——长按进行选择，通过共享面板粘贴回回复。
• 使用终端附件行输入手机键盘上不便使用的按键，包括 Tab 和 Shift+Tab；或者当每个输入的字符都应直接发送到活动终端时，切换到 Live。
• 当 agent 等待输入时，发送简短回复（continue、yes、自由文本），附加照片或文件，或点击麦克风进行语音输入。在 Live 模式下，语音输入的文字会插入到活动终端中，无需替你按下 Return。在 Chat UI 中，附加的图片会以缩略图形式显示在你的消息上，可以带文本或不带文本发送。
• 从会话标签栏运行 Quick Commands——这些是已保存的终端命令或 agent prompt，会与桌面端列表同步。
• 长按会话标签以执行批量关闭操作（Close Other Tabs、Close Tabs to the Left、Close Tabs to the Right）。未保存的 Markdown 标签和固定标签会被跳过。
• 当需要从手机查看响应式页面时，以 Web 或 Mobile 视图打开浏览器会话。
• 为工作树打开源代码控制，以查看已更改的文件、暂存或取消暂存，并从手机提交。
• 切换当前活动的 agent 账户，并随时查看用量 / 速率限制状态。当 Codex 已获得重置额度时，可从账户界面使用其中一个。
• 从移动端创建工作区，使用与桌面端相同的 Smart 源模式：Smart、GitHub、Linear、GitLab、Branch 和 Name。当存在多个已连接桌面时，New Workspace 会询问应由哪个主机先创建（只有一个已连接主机时会跳过选择器）。
• 打开主机卡片的 ⋯ 菜单，执行 Edit、Connect、Remove 及相关操作（长按仍然可以作为快捷方式）。
• 无需重新配对即可编辑已保存主机的显示名称或连接地址（例如桌面端在家庭 LAN 和 Tailscale 之间移动时）。
• 当 agent 完成时接收推送通知，与桌面通知保持一致。

移动应用有意不是完整的编辑器——它是为你已在运行的桌面端提供的遥控器。

配对¶

1. 在桌面端，从账户 / 状态菜单打开 Orca 的配对流程。Orca 会显示一次性配对码。
2. 在移动端，打开 Orca 伴侣应用并选择 Pair，然后粘贴配对码。（你也可以从桌面端通过深度链接直接进入移动端配对界面。）
3. 在可用时，优先使用 Orca Relay 进行配对——仅 Relay 需要登录。Relay 上的本地网络地址选择器是可选的（当你想要 LAN 快速路径时展开它）；LAN 配对仍然需要一个地址。
4. 配对交换会为该手机建立设备 token；请保持桌面端在你选择的路径上可达。

关闭桌面端应用会断开直接 / LAN 会话，直到你重新打开它。基于 Relay 的配对遵循桌面端 Relay 连接——如果主机离线，请重新打开桌面端。

Chat UI¶

对于支持聊天的 agent（Claude、Codex 以及 Orca 识别的其他 agent），移动端可以在 Chat UI 中打开会话，而不是原始终端——这与桌面端的 Chat UI 思路相同：可读的记录、输入框、权限 / 问题以及图片附件。

• 设备默认值 — 首次启动时，移动端会询问会话应如何在此手机上打开。之后可在 Settings → Chat UI → Open sessions in Chat UI 中更改。在你选择 Chat UI 之前，默认值为终端。
• 按会话 — 长按会话标签，选择 Switch to chat view 或 Switch to terminal view。该覆盖设置仅对该标签生效，不会更改设备默认值。
• 输入框 — 输入回复、使用 @ 提及工作区文件、使用共享目录中支持 agent 的 / 斜杠命令（Claude 与 Codex 命令集，含描述）、附加照片或进行语音输入。附加的图片会显示为可移除的缩略图，并随发送一起携带（包括仅发送图片和多张图片附件）。
• 模型与会话选项 — 输入框会显示当前模型和会话选项的胶囊行。点击它即可选择模型或选项（包括直接选择 Codex 模型），而无需切换到原始终端。
• 桌面端仍然拥有 agent — Chat UI 是配对桌面会话的视图，而不是独立的云端 agent。

Quick Commands¶

从工作树会话中，从会话标签栏打开 Quick Commands（位于新建终端旁边）。命令与桌面端使用相同的已保存列表，并双向同步。

• 终端命令 — 在新标签页中粘贴或运行 shell 命令（可以选择不按回车，以便先编辑）。
• Agent Prompt — 使用已保存的 prompt 正文打开选定的智能体。
• 通过行上的复制控件将命令正文复制到剪贴板（正文为空时禁用）。
• 将命令设为全局范围或仅限当前项目。可以在面板中新增、编辑和删除；桌面端主机强制执行共享列表上限。

如果配对的桌面端版本过旧，启动器将被禁用，直到你更新桌面端。

会话标签页¶

在会话条中长按标签页可执行标签页操作，包括关闭、关闭其他标签页、关闭左侧标签页和关闭右侧标签页。批量关闭会跳过有未保存更改的 Markdown 标签页（移动端关闭时不提示保存）和固定标签页。对于支持聊天的智能体标签页，同一个长按面板可以切换聊天界面 ↔ 终端。

账户切换器¶

移动端应用提供与桌面端状态栏相同的账户切换器，包括非活动账户的内联用量信息。当提供方报告其会话或每周窗口的重置时间戳时，账户界面会显示重置倒计时。在此处切换账户会同步切换配对的桌面端。

当当前 Codex 账户获得了速率限制重置积分时，账户界面会显示可用数量（以及下一个积分何时过期）和使用重置操作。确认后将消耗当前 Codex 目标（主机或 WSL 发行版）的一个积分，并刷新符合条件的速率限制窗口。手机会为该尝试记录日志，因此连接不稳定后的重试不会重复消耗积分。结果包括：成功、没有符合重置条件的内容、没有剩余积分，或重置已应用。另请参阅用量与速率限制跟踪。

创建工作区¶

在移动端主屏幕上，打开创建工作区 / 新建工作区并选择源模式。智能模式会跨受支持的任务提供方和分支进行搜索；特定提供方模式会将创建范围缩小到 GitHub、Linear、GitLab、某个分支或普通工作区名称。选择源之后，在配对桌面端创建工作区之前，使用高级进行命名和分支控制。如果连接了多个桌面端，请先选择主机（选择器会显示每个端点，以便相似名称保持可区分）。如果没有已连接的桌面端，该操作将保持禁用。

编辑已配对主机¶

在主机列表中，点击主机卡片上的⋯按钮（或长按卡片），然后选择编辑主机。

• 名称 — 仅在此手机上显示的显示名称。
• 地址 — IP、host:port 或 ws:// / wss://。缺少端口时保留当前端口（或默认为 6768）。编辑地址只会更改此手机的连接位置；不会重新配对。当同一桌面端可通过不同路径访问时（例如家庭局域网与 Tailscale），请使用此功能。

保存地址更改后会重新连接到新端点。配对令牌保持不变。

移动端源代码管理¶

从工作树会话中，点击分支图标以打开源代码管理。用于小型后续操作：检查分支状态、查看已更改的路径、暂存或取消暂存文件，并在暂存集就绪后提交。如果分支已有 GitHub 拉取请求，请使用空 PR 状态下的关联现有 PR来关联它，而不是创建新的。

移动端浏览器视图¶

移动端浏览器面板有一个网页 / 移动开关。使用网页查看正常页面，使用移动请求配对桌面端浏览器提供手机尺寸的响应式视口。

终端设置¶

移动端终端有专门的终端设置界面（设置 → 终端）：

• 文字大小 — WebView 在适配宽度基础上应用的 50%–200% 基准缩放。终端中的双指缩放会吸附到相同的预设并持久保存。该设置按设备生效，不会更改桌面端终端。
• 自动补全与自动纠正 — 默认关闭，因此操作系统不会重写命令栏中的命令、标志或路径。如需手机风格输入可将其打开；无论是否开启，实时键盘捕获输入仍会流式传输原始按键。

故障排查¶

• 工作树上的加载动画卡住 — 手机会跟踪来自桌面端智能体进程的心跳。如果桌面端显示空闲但手机显示正在工作，请强制刷新工作树行以同步状态。
• 配对失败 — 请确保你的桌面端和手机登录了同一个 Orca 账户。配对码会在几分钟后过期；如果屏幕上停留太久，请生成一个新的。
• 身份验证失败 / 配对无效 — 桌面端不再接受此设备令牌（例如桌面端清除了已配对设备之后）。请先尝试横幅上的重试（临时性拒绝可能无需重新配对即可恢复）。如果仍然失败，请使用桌面端的重新配对，或移除该主机并重新配对。
• 更新 Orca Mobile / 更新你电脑上的 Orca — 手机和桌面端使用带版本号的移动协议进行通信。如果任一端过旧，移动端会阻止该主机并引导你前往 App Store（iOS）、GitHub Releases（Android APK 或桌面端），然后返回主机列表。更新后，刷新连接；如果消息仍然存在，请移除主机并重新配对。
• 快速命令不可用 — 更新配对的桌面端，使其通告快速命令能力。
• 无法访问桌面端 — 手机和桌面端必须共享同一条网络路径（局域网、Tailscale 或你使用的配对路径）。关闭桌面端应用会断开连接；重新打开桌面端后，手机会自动重新连接。

将移动端通知与桌面端通知配对使用，以便智能体完成提醒到达正确的设备。对于无头机器，请使用远程 Orca 服务器的移动配对。在桌面端和移动端的用量与速率限制跟踪下跟踪提供方用量。