DevAgent Docs

简体中文

English

简体中文

English

主题

排查 GitHub 错误 ​

诊断 DevAgent PR 检查、Tasks 和 Source Control 中出现的速率限制、认证失败以及其他 GitHub CLI 错误。

DevAgent 通过你机器上（或远端 DevAgent 主机上）的 GitHub CLI (gh) 与 GitHub 通信。当 PR 状态、检查、issue 或 Tasks 无法刷新时，原因几乎总是 GitHub 认证、权限或 API 速率限制——而不是 PR 面板本身出了故障。

本页涵盖你最常遇到的错误以及修复方法。

快速分诊 ​

你所看到的现象

可能的原因

首先尝试

"GitHub is rate-limiting requests" / "rate limit exceeded (core)"

你的用户的 GitHub REST (core) 配额已用尽

等待重置；停止额外的 gh / agent / DevAgent 使用；查看 设置 → Git → GitHub API Budget

"GitHub authentication is unavailable" / gh auth 提示

gh 未登录、token 过期，或 GITHUB_TOKEN 有误

运行 gh auth status，然后 gh auth login

"GitHub did not allow access" / HTTP 403（非速率限制）

缺少 scope，或无权访问该仓库

用 repo（以及所需的 org SSO）重新认证；确认你能在浏览器中打开该 PR

"repository is unavailable" / HTTP 404

remote 有误、无权访问的私有仓库，或仓库被重命名

检查 git remote -v 和浏览器访问权限

"GitHub is unreachable" / 超时

网络、代理、VPN，或 GitHub 故障

查看 githubstatus.com；断开 VPN 后重试

"GitHub CLI is unavailable"

DevAgent 所使用的 PATH 中缺少 gh

安装 gh 并重启 DevAgent

速率限制（最常见） ​

GitHub 为每个已认证用户分配一个共享的每小时配额。该账户下的每个工具都共用它：DevAgent、终端里的 gh、调用 gh 的 Claude/Codex/Grok agent、CI 脚本、浏览器扩展以及其他应用。

DevAgent 关心的配额桶（bucket） ​

桶

覆盖范围

典型限额（已认证）

REST (core)

大多数 PR/issue/API 调用（gh pr view、检查元数据、许多 REST 端点）

5,000 / 小时

GraphQL

Project/Tasks 以及一些更复杂的 PR 查询

5,000 点 / 小时

Search

由搜索驱动的列表

30 / 分钟

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

为什么 设置 看起来"正常"而 PR 面板却被阻塞 ​

设置 → Git → GitHub API Budget 读取的是 GitHub 特殊的 rate_limit 端点。该探测请求豁免于速率限制计数，因此有时它仍报告有剩余配额，而同一用户的真实 REST 调用实际上已经返回 remaining: 0。

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

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

另外，不要把 GitHub API Budget 与 Accounts 下的 Claude / Codex / Grok 使用量混淆——后者是 AI 提供方的限额，而非 GitHub 的 REST 配额。

从终端确认是否遇到速率限制 ​

# 探测（不消耗配额；可能看起来比实际更健康）
gh api rate_limit --jq '.resources | {core, graphql, search}'

# 真实的 REST 调用——PR 刷新正是依赖于此
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 epoch 秒数）为止。

通常是什么在消耗配额 ​

  • 同时打开了多个 DevAgent 窗口或 electron-dev 构建（每个都可能刷新 PR / Tasks）
  • 自动化调用 gh 的 agent（分配 PR/issue、轮询检查、批量 GraphQL）
  • 繁重的 Tasks / 多仓库并行，同时还在刷新 PR 面板
  • 其他应用使用了同一个 GitHub 用户 token

该怎么办 ​

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

认证问题 ​

DevAgent 沿用该主机上 gh 所使用的一切认证信息。

检查状态 ​

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

健康的输出：已登录、token 有效、gh api user 返回你的登录名。

常见的坑 ​

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

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

过期或被吊销的 token
gh auth status 可能会显示 token 无效。运行 gh auth login（或 gh auth refresh），然后重启 DevAgent 以便它读取新凭据。

Org SAML SSO
私有的 org 仓库可能需要为 token 授权 SSO。从 GitHub token 设置中打开该 org 的 SSO 授权链接，然后重试。

远端 / SSH worktree
GitHub 认证是**按主机（per host）**的。在你的笔记本上登录并不会为远端机器上的 gh 登录。通过 SSH 登入该主机并在那里运行 gh auth login，或者为该环境使用 DevAgent 的远端服务器 GitHub 预算视图。

权限与仓库错误 ​

症状

含义

HTTP 403 但没有"rate limit"

token 缺少 scope，或你无权查看该资源

HTTP 404 / "could not resolve to a Repository"

仓库不存在、被重命名，或对此 token 不可见

"resource not accessible by integration"

该 App/token 类型无法执行该操作

修复方法：

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

网络与 GitHub 故障 ​

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

  • 查看 GitHub Status
  • 尝试断开 VPN / 公司代理
  • 在远端主机上，确认到 api.github.com 的出站 HTTPS 可用

缺少 GitHub CLI ​

如果 DevAgent 报告 GitHub CLI 不可用：

  1. 安装 gh
  2. 确认在普通终端中 which gh 能正常工作
  3. 完全退出并重新打开 DevAgent（以便 PATH 一致）
  4. 在 Windows 上，为 DevAgent 启动的同一环境安装（WSL vs 原生）

当 GitHub 出错时 DevAgent 的行为 ​

  • 速率限制 / 故障：PR 和 Checks 面板会优先保留最后已知状态并附上一条简短横幅，而不是清空 UI。
  • 严重的认证 / 权限失败：你会看到清晰的空状态或横幅文案，提示你修复登录或访问权限。
  • 熔断器（circuit breaker）：在遇到主速率限制 403 之后，DevAgent 会短暂拒绝为该桶（core、search 或 graphql）派生新的 gh，以使应用保持响应，避免把窟窿越挖越深。

在 DevAgent 中查看 GitHub API Budget ​

打开 设置 → Git 并找到 GitHub API Budget：

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

仍然卡住？ ​

  1. 在 DevAgent 所使用的同一台机器/同一用户下，用 gh pr view 或 gh api user 在终端里复现一次。
  2. 收集日志：Help → Open Logs。
  3. 提交一个 issue，附上已归类的错误文本（不含机密）、脱敏后的 gh auth status 输出，以及终端里的 gh 是否以同样方式失败。

相关内容 ​

DevAgent 桌面客户端文档

© 2026 Clouditera。保留所有权利。