文档 / 故障排除与 FAQ

Agent 无法启动¶

• 打开终端并手动运行 Agent 的 CLI。如果在那里失败，说明是 CLI 本身的认证或安装问题——不是 Orca 的问题。
• 确保 CLI 位于 Orca 可见的 PATH 中（检查 设置 → Agents）。
• 尝试选项卡上的 Restart 按钮。

Diff 视图显示不正确 / 卡住¶

• 点击 diff 工具栏上的刷新图标——Orca 会重新读取 worktree。
• 外部 git 操作（rebase、reset）可能发生在两次刷新之间。

Worktree 创建失败¶

• 起始 ref 可能尚未获取。在仓库中打开终端并运行 git fetch origin。
• 目标目录可能已经存在该分支的 worktree——删除它或选择新的分支名称。

Orca CLI 提示 “command not found”¶

在 设置 → 常规 → Orca CLI 中注册 CLI。在 macOS 上，它会将 shim 安装到 ~/.local/bin；请确保该路径位于 shell 的 PATH 中。

SSH 连接成功但远程终端失败¶

• 确认远程主机具备 Node 和首次中继安装所需的网络访问权限。
• 在 Linux 上，如果终端始终无法启动，请安装 C/C++ 工具链：make、g++/clang++、python3（参见 SSH worktrees）。
• 安装工具后重新连接，以便 Orca 重新安装原生模块。

SSH 文件可用但 “Download Folder” 不可用¶

文件夹下载需要递归 SFTP 传输。在仅使用系统 SSH 的连接上，文件下载可能仍然可用。可将终端中的 tar/scp 作为备用方案。

“Open in VS Code” 已禁用或仅限本地¶

• 使用 SSH worktree（而不是 Remote Orca Server 活动运行时）。
• 将 Open-in 命令设置为 VS Code / Insiders，而不是 Cursor 或多参数 shell 命令。
• 如果主机已被移除，请刷新 SSH 目标。

Kerberos 登录失败¶

• 确保 klist 显示主机 realm 的有效票据。
• 在 OpenSSH 配置中确认该 Host 的 GSSAPIAuthentication yes，然后在 设置 → SSH 中重新导入或重新测试目标。

浏览器显示 browser_no_tab¶

当前 worktree 中没有打开的选项卡。使用 orca tab create --url ... 打开一个，或手动打开浏览器窗格并导航。

性能与内存¶

• 关闭你未正在使用的 worktree。每个 worktree 都会保持文件监视器处于活动状态。
• 包含许多浏览器选项卡的分割布局是内存占用最大的——关闭不需要的浏览器。

GitHub PR 面板 / 检查 / Tasks 错误¶

速率限制、gh 认证错误、缺少 scopes 以及仓库访问问题都会显示在 Source Control 和 PR Checks 面板中。有关完整矩阵（包括为什么设置中的 GitHub API Budget 看起来正常，但 REST 仍被阻止），请参见 排查 GitHub 错误。

快速检查：

gh auth status -h github.com
gh api user
gh api rate_limit --jq '.resources.core'

日志¶

帮助 → 打开日志 会打开包含 Orca 日志的目录。提交 bug 时请附上这些日志。

报告问题¶

• 帮助 → 发送反馈（应用内）——将截图粘贴或拖入对话框，或选择图像文件；提交前会显示缩略图。如果 bug 难以复现，请附上日志。
• GitHub Issues——bug 和功能请求。
• Discord——实时帮助。