Claude 连接 GitHub 失败——三步排查

连不上 GitHub 或显示没仓库?OAuth scope / 组织权限 / 仓库可见性三层挨个查。

你在 Claude 里点 “Connect GitHub”,OAuth 走完了,但 Claude 要么说”找不到任何仓库”,要么只列出 5 个 public 仓库(你的私有项目一个都看不到),要么干脆显示 “could not connect to github”——这是 GitHub 三层访问控制(OAuth scope / SSO / Org third-party approval)在拦你。

GitHub 比 Notion 或 Google Drive 麻烦,因为它对企业账号默认非常保守:Org 管理员要单独审批每个第三方 App,且 SSO 强制下未审批的 token 会被 silently 过滤,连错误都不报。

常见原因

按命中率从高到低:

1. OAuth scope 没勾 private repo

GitHub OAuth 默认只授权 public_repo(只能读公共仓库)。要访问私有仓库,必须显式勾 repo scope——很多人授权时一路 Next,错过了这步。

如何判断github.com/settings/applications → Authorized OAuth Apps → Claude → 看 Permissions。如果没有 “Full control of private repositories”,scope 不够。

2. Org 强制 SSO 但 Claude 未审批

Enterprise org 启用 SAML SSO 后,所有第三方 App 默认被排除在 SSO 范围外。你的个人 token 能用,但访问需要 SSO 的私有仓库时 GitHub 直接返回 0,不报错。

如何判断:在 github.com/settings/applications → Claude → Organization access → 看你的 org 是否显示 “Request” 按钮而非 “Authorized”。

3. Org 要求管理员审批第三方 App

某些 org 在 Settings → Third-party access → OAuth app policy 里启用了 “Require approval for all OAuth apps”。这种情况下,即使你授权了,Claude 仍然拿不到 org 内任何仓库。

如何判断:在 GitHub 上访问目标 org → Settings → Third-party Access → 看 Claude 是否在 “Pending” 或 “Denied” 列表。

4. 你授权的 GitHub 账号 ≠ 你想读的账号

最隐蔽的坑。你在 Claude 里登录用 personal@gmail.com,点 GitHub OAuth 时浏览器里已经登着 personal-github,所以授权给了 personal——但你想找的代码在 work-github 账号下。

如何判断github.com 看左上角头像,对照 Claude 里 “Connected as” 显示的账号名。

5. Personal Access Token 模式没开 fine-grained 范围

如果你用 PAT 而非 OAuth(某些自部署/企业场景),PAT 默认 scope 太宽或太窄都会导致 Claude 失败。Fine-grained PAT 要显式选 Repository access。

如何判断:你用的是 PAT 还是 OAuth?看 Claude 连接时是弹 GitHub OAuth 页还是要你贴 token。

6. Rate limit / abuse detection

短时间内连续重试授权或大量查询,会触发 GitHub 的 abuse rate limit,返回 403。

如何判断:错误消息含 “rate limit exceeded” 或 “abuse detection.”

最短修复路径

Step 1:撤销旧授权,重新走 OAuth

访问 https://github.com/settings/applications
  → Authorized OAuth Apps → Claude → Revoke
回 Claude → Settings → Connectors → GitHub → Disconnect → Connect

授权弹窗里仔细勾

  • repo (Full control of private repositories)
  • read:org (Read org and team membership)
  • 如果列了具体 org,逐个 Grant access

Step 2:处理 SSO

授权完后,回到 github.com/settings/applications → Claude → Organization access:

  • Org 显示 “Authorized” → OK
  • Org 显示 “Request” 按钮 → 点击发送审批请求给 org owner
  • Org 显示 “Denied” → 找 org owner 改成 allow

写邮件给 org owner 时,附 Claude 的 OAuth app URL 和你要访问的仓库列表,比模糊请求快得多。

Step 3:处理 Org Third-party 审批

如果整个 org 在 OAuth restriction 模式:

你不是 org owner → 联系 owner:
  "Please approve Claude (OAuth app by Anthropic) in
   Org Settings → Third-party Access → Pending requests."

你是 org owner → 自己在 Settings → Third-party Access
  → OAuth app policy 里 Approve "Claude."

Step 4:账号校验

在 Claude 里发:

请用 GitHub Connector 列出我能访问的所有 org 名称。

对照你预期的账号 / org,不一致就是连错了账号。Disconnect 后在浏览器先切到正确的 GitHub 账号再 Connect。

Step 5:PAT 模式特殊处理

如果你用 fine-grained PAT:

访问 https://github.com/settings/personal-access-tokens/new
  → Repository access → All repositories(或精选)
  → Permissions:
    - Contents: Read
    - Metadata: Read
    - Pull requests: Read(如果要读 PR)
    - Issues: Read(如果要读 issue)
  → 生成后立即复制(只显示一次)粘贴回 Claude

Step 6:Rate limit 等 1 小时再试

如果触发 abuse limit,Disconnect → 等 60 分钟(不是 5 分钟)→ Connect,并降低初始查询频率。

预防建议

  • 在密码管理器里记下”哪个 GitHub 账号授权了 Claude”,避免下次又混
  • 加入新 org 当天就申请 third-party access,不要等用到的时候才发现要等审批
  • Personal / work 账号用不同浏览器 profile,避免授权串号
  • PAT 用 fine-grained 类型而非 classic,最小权限原则
  • 个人项目和工作项目分两个 Claude Workspace,分别授权对应 GitHub 账号

相关阅读

标签: #Claude #排查 #排查