第8章 Orca 移动端伴侣应用

移动端伴侣应用

将 Orca 移动应用与桌面端配对，随时随地监控 agent、从手机上解决 worktree 卡住的问题。

Orca 移动伴侣是一款 iOS/Android 应用，与桌面端 Orca 配对后，为你提供以只读为主的运行中 agent 视图——包括 agent 状态、最近的终端滚动记录，以及手机上真正需要的控制功能（回复 prompt、休眠 worktree、查看源码控制、切换 agent 账户）。配对只需一次，桌面端始终是权威数据源。

Orca Mobile——在手机上查看 agent 状态、滚动记录并快速回复。

移动端能做什么

查看每个 worktree、其 agent 及当前状态（工作中 / 已完成 / 等待输入）。移动端会把所有已连接主机（本地桌面和远程 Orca 服务器）的 worktree 汇总在同一个列表里，切换时无需换设备。SSH 主机上的 workspace 会在行徽标上显示该主机的健康状况——措辞与桌面端一致——机器掉线一眼可见。

在手机上浏览 workspace 的完整文件树——包括深层嵌套路径——无需等待桌面端即可打开任意文件。视频和音乐文件可在手机上直接预览播放。

以 Chat UI（聊天式记录）或原始终端的方式打开受支持的 agent 会话。可在 Settings → Chat UI 中设置设备默认方式，也可以长按某个会话标签页单独切换。

拉取最近的终端滚动记录，了解 agent 做了什么、问了什么。终端流结束后，视图会接受新的快照而不是停留在旧内容上。聊天式视图中的 Markdown 支持渲染消息里包含的 Mermaid 图表，原生聊天界面也显示与桌面端相同的内联可视化和 subagent 行。

在移动端终端视图中选择、复制、粘贴文本——长按选中，通过分享面板粘贴回复内容。

终端Accessory 工具行提供手机键盘上不便输入的按键，包括 Tab 和 Shift+Tab；若希望每个按键字符直接发送到当前终端，可切换到 Live 模式。

当 agent 等待输入时，发送简短回复（继续、是、自由文本），附加照片或文件，或点击麦克风语音输入回复。Live 模式下，语音文本会插入当前终端且不会自动按回车。Chat UI 中，附加图片会以缩略图形式显示在你的消息上，可以带文字或不带文字发送。

从会话标签栏运行 Quick Commands——即与桌面端同步的已保存终端命令或 agent prompt。

长按会话标签页可批量关闭（关闭其他标签页、关闭左侧标签页、关闭右侧标签页）。未保存的 markdown 标签页和已固定的标签页会被跳过。

需要检查响应式页面时，可用 Web 或 Mobile 视图打开浏览器会话。手机上打开的浏览器标签页在桌面端最小化或进入屏保时仍会继续加载。

打开 worktree 的 Source Control，在手机上查看变更文件、暂存或取消暂存、提交代码。

随时随地切换活跃 agent 账户，查看用量和限流状态。当 Codex 获得重置额度时，可在账户页面直接使用。

从手机创建 workspace，支持与桌面端相同的 Smart 源模式：Smart、GitHub、Linear、GitLab、Branch 和 Name。连接了多台桌面端时，New Workspace 会先询问在哪台主机上创建（仅连接一台时跳过选择器）。

从手机在 workspace 上启动 agent；标签页会立即出现在桌面端，且启动操作不会把桌面窗口切换到该 workspace。

打开主机卡片的 ⋯ 菜单，进行编辑、连接、移除等操作（长按仍可作为快捷方式）。

无需重新配对即可修改已保存主机的显示名称或连接地址（例如桌面端在家用局域网和 Tailscale 之间切换时）。

在主机列表和打开的会话之间以滑动动画切换；返回时会把页面的主机栈滑回原位。

在 iPad 上，主机可通过单个侧边栏随时访问，在主机列表和会话之间切换时聊天草稿会被保留。

agent 完成时收到推送通知，与桌面端通知保持一致。应用还会提示有新版移动端可安装，并提供发布链接。

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

配对

在桌面端，从账户/状态菜单打开 Orca 的配对流程，Orca 会显示一次性配对码。

在移动端，打开 Orca 伴侣应用，选择 Pair，然后粘贴配对码。（也可以从桌面端通过深链直接跳到移动端配对界面。）

可用时优先通过 Orca Relay 配对——只有 Relay 需要登录。Relay 模式下局域网地址选择是可选的（想要局域网快速通道时可展开）；局域网配对仍需填写地址。

配对交换会为该手机建立设备令牌；请在你所选的路径上保持桌面端可达。

关闭桌面应用会断开直连/局域网会话，直到你重新打开它。基于 Relay 的配对跟随桌面端的 Relay 连接——主机离线时重新打开桌面端即可。

配对完成后，手机会以桌面端机器名命名主机并显示其操作系统。你可以在桌面端 Settings → Remote Orca Servers 中修改机器名，手机重连时会自动同步。

Chat UI

与桌面端相同的支持聊天的 agent——Claude、Codex、Grok、OpenCode、OMP 和 Pi——移动端可以用 Chat UI 而非原始终端打开会话，理念与桌面端的 Chat UI 一致：可读的会话记录、输入框、权限/提问界面以及图片附件。

设备默认——首次启动时，移动端会询问此手机上会话的打开方式。之后可在 Settings → Chat UI → Open sessions in Chat UI 中修改。在你选择 Chat UI 之前，默认是终端。

按会话覆盖——长按会话标签页，选择 Switch to chat view 或 Switch to terminal view。该覆盖只对当前标签页生效，不影响设备默认设置。

输入框——输入回复、@ 提及 workspace 文件、使用来自共享目录的 agent 感知 / 斜杠命令（Claude 与 Codex 各有命令集并带描述）、附加照片或语音输入。附加的图片显示为可移除的缩略图并随消息一起发送（包括纯图片消息和多图附件）。

模型与会话选项——输入框上方有一排胶囊按钮，显示当前模型和会话选项。点按即可选择模型或选项（包括直接选择 Codex 模型，以及当前模型支持时感知提供商的 Fast 模式），无需切到原始终端。

桌面端始终掌控 agent——Chat UI 只是对配对桌面端会话的一个视图，不是独立的云端 agent。

Quick Commands

在 worktree 会话中，从会话标签栏（新建终端按钮旁）打开 Quick Commands。命令列表与桌面端相同，双向同步。

Terminal Command——在新标签页粘贴或运行 shell 命令（可选不自动按回车，方便先编辑）。

Agent Prompt——用已保存的 prompt 内容打开指定 agent。

通过每行的复制按钮把命令内容复制到剪贴板（内容为空时禁用）。

命令可设为全局或当前项目范围。可在面板中添加、编辑和删除；桌面端主机负责强制执行共享列表上限。

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

会话标签页

长按会话栏中的标签页可进行标签操作，包括关闭、关闭其他标签页、关闭左侧标签页和关闭右侧标签页。批量关闭会跳过有未保存修改的 markdown 标签页（移动端关闭时没有保存提示）和已固定的标签页。对支持聊天的 agent 标签页，同一长按面板还可以在 Chat UI 和终端之间切换。

账户切换器

移动端提供与桌面端状态栏相同的账户切换器，包括非活跃账户的内联用量显示。当提供商上报会话或周额度的重置时间戳时，账户页面会显示重置倒计时。在这里切换会同步切换到配对的桌面端。

当活跃的 Codex 账户获得限流重置额度时，账户页面会显示可用数量（以及下一个何时过期）和 Use reset 操作。确认后为当前 Codex 目标（主机或 WSL 发行版）消耗一个额度并刷新符合条件的限流窗口。手机会记录操作日志，连接不稳时重试不会重复消耗。结果包括成功、没有符合条件的项目、额度用尽，或重置已被应用过。另见 Usage & rate-limit tracking。

创建 workspace

从移动端主屏幕打开 Create Workspace / New Workspace 并选择源模式。Smart 会搜索所有受支持的任务提供商和分支；特定提供商模式则将创建范围限定在 GitHub、Linear、GitLab、某个分支或纯 workspace 名称。选择源后，可在创建前用 Advanced 设置命名和分支选项，然后在配对的桌面端上创建 workspace。如果连接了多台桌面端，需要先选择主机（选择器会显示每个端点，避免相似名称混淆）。没有连接桌面端时，该操作保持禁用。

编辑配对主机

在主机列表中，点按主机卡片的 ⋯ 按钮（或长按卡片），选择 Edit host。

Name——仅在此手机上显示的名称。它会覆盖桌面端的机器名；清空后恢复使用桌面端名称。

Address——IP、host:port 或 ws:// / wss://。省略端口时保留当前端口（或默认 6768）。修改地址只改变此手机的连接目标，不会重新配对。适用于同一桌面端在不同路径可达的情况（例如家用局域网与 Tailscale）。

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

移动端源码控制

在 worktree 会话中点按分支图标打开 Source Control。适合做小的后续操作：查看分支状态、检查变更路径、暂存或取消暂存文件，暂存就绪后提交。如果分支已有 GitHub pull request，可在空 PR 状态下用 Link an existing PR 关联它，而不是新建。

移动端浏览器视图

移动端浏览器面板有 Web / Mobile 切换。用 Web 查看正常页面，用 Mobile 让配对的桌面端浏览器提供手机尺寸的响应式视口。

终端设置

移动端终端有专门的 Terminal settings 界面（Settings → Terminal）：

Text size——50%–200% 的基准缩放，由 WebView 在适应宽度之上应用。终端中的双指缩放会对齐相同预设并持久保存。此设置为设备级，不影响桌面端终端。

Autocomplete & autocorrect——默认关闭，让系统不会在命令栏改写命令、参数或路径。开启后可获得手机式输入体验；无论开关与否，实时键盘捕获输入始终直接传输原始按键。

键盘会像原生屏幕一样遮挡页面，页面会上报自身高度，使输入框和活跃输入区域在你打字时保持可见。

故障排除

Worktree 转圈卡住——手机通过桌面 agent 进程的心跳跟踪状态。如果桌面端显示空闲而手机显示工作中，强制刷新该 worktree 行即可同步状态。

配对失败——确保桌面端和手机登录的是同一个 Orca 账户。配对码几分钟内过期；在屏幕上放太久就重新生成一个。

认证失败 / 配对无效——桌面端不再接受此设备令牌（例如桌面端清除了已配对设备）。先尝试横幅上的 Retry（临时拒绝无需重新配对即可恢复）。如果持续失败，从桌面端使用 Re-pair，或移除主机后重新配对。

更新 Orca Mobile / 更新电脑上的 Orca——手机与桌面端使用带版本号的移动协议。任一方太旧时，移动端会屏蔽该主机，并引导你前往 App Store（iOS）、GitHub Releases（Android APK 或桌面端）更新，然后返回主机列表。更新后刷新连接；如果提示仍在，移除主机并重新配对。

Quick Commands 不可用——更新配对的桌面端，使其支持 quick-commands 能力。

无法连接桌面端——手机与桌面端必须共享网络路径（局域网、Tailscale 或你配对时使用的路径）。关闭桌面应用会断开连接；重新打开桌面端后手机会自动重连。