文档 / 排查 GitHub 错误

Orca 通过你机器上的 GitHub CLI（gh）（或远程 Orca 主机）与 GitHub 通信。当 PR 状态、检查、问题或 Tasks 无法刷新时，原因几乎总是 GitHub 身份验证、权限或 API 速率限制——而不是 PR 面板本身损坏。

本页介绍你最常见的错误以及如何修复它们。

快速排查¶

速率限制（最常见）¶

GitHub 为每个已认证用户提供共享的小时配额。该账户上的每个工具都会共享它：Orca、终端中的 gh、调用 gh 的 Claude/Codex/Grok 代理、CI 脚本、浏览器扩展和其他应用。

Orca 关注的配额桶¶

当主要配额桶耗尽时，GitHub 会返回 HTTP 403，并附带类似 API rate limit exceeded 的消息。Orca 会将其归类为速率限制，在可能的情况下保留最后已知的 PR 状态，并在短时间内停止生成更多 gh 调用，以免单次限制演变成大量失败。

为什么设置看起来“正常”，但 PR 面板被阻止¶

设置 → Git → GitHub API 预算 读取 GitHub 的特殊 rate_limit 端点。该探测不受速率限制统计影响，有时仍会报告剩余配额，而同一用户的真实 REST 调用已经返回 remaining: 0。

当它们不一致时，按以下顺序信任：

1. PR / Checks 面板上的错误（实时请求失败）
2. 真实的 CLI 检查（见下文）
3. 设置中的预算数字（有用，但仅用于探测）

也不要将 GitHub API 预算 与 Accounts 下的 Claude / Codex / Grok 用量 混淆——那些是 AI 提供商限制，而不是 GitHub 的 REST 配额。

从终端确认速率限制¶

# Probe (does not consume quota; can look healthier than reality)
gh api rate_limit --jq '.resources | {core, graphql, search}'

# Real REST call — this is what PR refresh depends on
gh api user -i 2>&1 | head -40

如果 gh api user 返回 403，并带有 API rate limit exceeded 和 X-Ratelimit-Remaining: 0，则该账户的 REST 访问会被阻止，直到 X-Ratelimit-Reset（Unix 纪元秒）。

通常是什么消耗配额¶

• 同时打开许多 Orca 窗口或 electron-dev 构建（每个都可能刷新 PR / Tasks）
• 自动化 gh 的代理（分配 PR/问题、轮询检查、批量 GraphQL）
• 在刷新 PR 面板的同时进行大量 Tasks / 多仓库扇出
• 使用同一 GitHub 用户令牌的其他应用

该怎么做¶

1. 等待错误中或 X-Ratelimit-Reset 中显示的小时重置。
2. 减少并发的 GitHub 客户端——退出多余的 Orca 实例，并暂停批量 gh 自动化。
3. 在受限期间避免在 PR 面板上反复刷新；Orca 已经在退避。
4. 在脚本中优先批量处理 GraphQL；不要使用个人账户对大量集合逐个 PR 循环 REST。
5. 重置后，如果 PR 刷新仍然失败，请重新检查身份验证（下一节）。

身份验证问题¶

Orca 继承该主机上 gh 使用的任何配置。

检查状态¶

gh auth status -h github.com
gh api user --jq '{login, id}'

正常输出：已登录、令牌有效，gh api user 返回你的登录名。

常见陷阱¶

你的 shell 配置文件中的 GITHUB_TOKEN / GH_TOKEN
如果这些变量被导出（例如在 ~/.bash_profile 或 ~/.zshrc 中 export GITHUB_TOKEN=$(gh auth token)），gh 会优先使用它们而不是密钥环。过期或错误的环境变量令牌会导致令人困惑的身份验证或速率限制行为。取消设置它们并重新登录：

unset GITHUB_TOKEN GH_TOKEN
gh auth logout -h github.com
gh auth login -h github.com

过期或被吊销的令牌
gh auth status 可能显示令牌无效。运行 gh auth login（或 gh auth refresh），然后重启 Orca 以使其获取新凭据。

组织 SAML SSO
私有组织仓库可能需要对令牌进行 SSO 授权。从 GitHub 令牌设置中打开该组织的 SSO 授权链接，然后重试。

远程 / SSH worktrees
GitHub 认证是按主机进行的。在笔记本电脑上登录不会使远程机器上的 gh 处于登录状态。SSH 到该主机并在那里运行 gh auth login，或针对该环境使用 Orca 的远程服务器 GitHub 预算视图。

权限和仓库错误¶

解决方法：

• 确认在浏览器中登录为与 gh api user 相同的用户时，PR/仓库可以打开
• 使用包含 repo 的经典权限范围重新认证（如果你使用这些功能，还包括 read:org / project）
• 对于 GitHub Enterprise，请确保 gh 已针对该主机名完成认证（gh auth login --hostname …）

网络和 GitHub 故障¶

关于超时、“could not resolve host”或“GitHub is unreachable”的消息属于连接问题：

• 检查 GitHub Status
• 尝试不使用 VPN / 企业代理
• 在远程主机上，确认到 api.github.com 的出站 HTTPS 可用

GitHub CLI 缺失¶

如果 Orca 报告 GitHub CLI 不可用：

1. 安装 gh
2. 确认在普通终端中 which gh 可用
3. 完全退出并重新打开 Orca（使 PATH 匹配）
4. 在 Windows 上，请为 Orca 启动的同一环境安装（WSL 或原生）

Orca 在 GitHub 失败时的行为¶

• 速率限制 / 故障：PR 和 Checks 面板会优先显示最后已知状态并附带简短横幅，而不是清空 UI。
• 硬性认证 / 权限失败：你会看到明确的空状态或横幅文案，提示你修复登录或访问权限。
• 熔断器：在出现主要速率限制 403 后，Orca 会短暂拒绝为该桶（core、search 或 graphql）启动新的 gh 进程，以保持应用响应并避免问题进一步恶化。

在 Orca 中检查 GitHub API 预算¶

打开 设置 → Git，找到 GitHub API 预算：

• REST / Search / GraphQL 来自 GitHub 探测的剩余次数
• 等待限制解除后刷新
• 在远程 Orca 服务器上，使用远程高级预算视图查看服务器所有的 gh 身份（本地设置仅显示桌面客户端）

仍然卡住？¶

1. 在与 Orca 使用的相同机器/用户下的终端中，使用 gh pr view 或 gh api user 复现一次。
2. 收集日志：帮助 → 打开日志。

3. 提交 issue，附上已分类的错误文本（不要包含机密信息）、gh auth status 的脱敏输出，以及终端中的 gh 是否以相同方式失败。

4. GitHub Issues

5. Discord

相关¶

• 托管评审、issue 和 Actions — 依赖 GitHub 的 PR 和 Checks 功能
• 设置参考 — 集成和 Git 面板
• 用量与速率限制跟踪 — AI 提供商限制（Claude/Codex），不是 GitHub API
• 故障排除与常见问题 — 通用 Orca 问题