第12章 故障排查与常见问题
故障排查与常见问题
Agent 无法启动
在 Orca 之外的普通终端中运行 Agent 的 CLI。如果在此处也失败，请检查 CLI 安装状态和登录情况。如果仅在 Orca 中失败，请遵循以下指导：
- 确保 CLI 位于 Orca 可识别的 PATH 中（检查“设置 → Agent”）。
- 尝试点击标签页上的“重启”按钮。
Codex 报告路径必须短于 SUN_LEN
将 Orca 更新到 v1.4.212 或更高版本。Codex 0.157 及后续版本在 Orca 管理的账户主目录中，若后台守护进程的 socket 路径过长，可能会触发此错误。Orca 现在会自动调整受影响的主目录；你无需移动账户或编辑系统级 ~/.codex/config.toml。详见“Codex in Orca”。
Orca 询问使用哪个配置文件副本
如果你的配置文件 JSON 和 SQLite 副本均可读但内容不一致，Orca 会显示每个副本的最后保存时间。选择“使用 SQLite（推荐）”或“使用 JSON”以保留该副本；Orca 会应用你的选择并重启。如果需要先检查副本，请选择“退出”。其他配置文件恢复错误仍可能显示独立的命令指导。
Diff 视图显示错误或卡住
- 点击 Diff 工具栏上的刷新图标 —— Orca 将重新读取 worktree。
- 外部 git 操作（rebase、reset）可能会在两次刷新之间执行。
Worktree 创建失败
- 起始引用可能未获取。在仓库中打开终端并运行 git fetch origin。
- 目标目录中可能已存在该分支的 worktree —— 删除它或选择新的分支名称。
Orca CLI 显示“command not found”
在“设置 → 常规 → Orca CLI”中注册 CLI。在 macOS 上，它会安装一个 shim 到 ~/.local/bin；请确保该路径在你的 shell PATH 中。在 Windows 上，orca 是安装程序添加到 PATH 的原生程序。
SSH 连接成功但远程终端失败
- Orca 在主机上设置其自行管理的服务器，因此错误的 Node 版本或缺失的构建工具不再阻塞连接。“设置 → SSH 主机”会显示主机运行的是哪个服务器，“设置 → 托管服务器”可以更新、回滚或恢复它。详见“SSH worktrees → 托管 Orca 服务器”。
- 托管服务器无法在其上运行的主机不再回退到旧 SSH 运行时：“设置 → SSH 主机”会解释原因，连接会因该原因失败。使用较旧版本的 Orca 以继续连接该主机。
- 从 v1.4.224 携带过来的终端仍接受输入和输出，但没有 orca CLI。在同一主机上打开新终端以使用 orca 命令。
SSH 用于文件正常但“下载文件夹”失败
文件夹下载需要递归 SFTP 传输。在仅限系统 SSH 的连接上，文件下载可能仍然有效。使用终端 tar/scp 作为后备方案。
“在 VS Code 中打开”已禁用或仅限本地
- 使用 SSH worktree（而非活动远程 Orca 服务器运行时）。
- 将“打开”命令设置为 VS Code / Insiders，而不是 Cursor 或多参数 shell 命令。
- 如果主机被移除，刷新 SSH 目标。
Kerberos 登录失败
- 确保 klist 显示主机域的有效票据。
- 在 OpenSSH 配置中确认该主机的 GSSAPIAuthentication 为 yes，然后在“设置 → SSH”中重新导入或重新测试目标。
浏览器显示 browser_no_tab
当前 worktree 中没有打开的标签页。使用 orca tab create --url ... 打开一个，或手动打开浏览器面板并导航。
性能与内存
- 关闭你未积极使用的 worktrees。每个 worktree 都会保持文件监听器处于活动状态。
- 带有许多浏览器标签页的分屏布局是最大的 RAM 使用者 —— 关闭不需要的浏览器。
GitHub PR 面板 / 检查 / 任务错误
速率限制、无效的 gh 认证、缺失的 scope 和仓库访问问题都会显示在“源代码管理”和“PR 检查”面板中。详见“GitHub 错误排查”了解完整矩阵（包括为什么“设置”中的 GitHub API 预算可能看起来正常，而 REST 仍被阻止）。
如果 Orca 声称 GitHub CLI 未安装，尽管 gh 在你的终端中可用，你的 PATH 上的 gh 启动器很可能挂起了。Orca 会继续寻找挂起的启动器并使用通过其版本检查的副本，而不是报告 CLI 缺失。
快速检查：
- gh auth status -h github.com
- gh api user
- gh api rate_limit --jq '.resources.core'
日志
“帮助 → 打开日志”会打开包含 Orca 日志的目录。提交错误报告时请附上这些日志。
报告问题
- “帮助 → 发送反馈”（应用内）—— 在对话框中粘贴或拖放截图，或选择图像文件；提交前会显示缩略图。当错误难以复现时，请附上日志。
- GitHub Issues —— 用于错误和功能请求。
- Discord —— 实时帮助。
