【Claude Code解惑】自动化 PR 机器人：基于 Claude Code 的 GitHub Action 实践

1. 从一次“评论刷屏”事故说起：PR 机器人到底解决什么问题

先说个真实场景。团队里有个 6 人小组，每周合并 40 多个 PR，维护者每天光看 diff 就要花两小时。有人提议“让 Claude 自动审一下”，于是随手写了个 GitHub Action，结果第一次跑就出事了：同一个 PR 因为synchronize事件被触发了 5 次，机器人连发 5 条几乎一样的评论，PR 页面直接被刷屏，维护者反而更累了。

这就是典型的“能跑”和“能用”之间的差距。Claude Code 驱动的 PR 机器人，本质是把大模型的代码理解能力塞进 GitHub 的事件流里，让它在 PR 打开或更新时自动做三件事：审阅变更、生成变更摘要、把结论作为评论贴回去。它适合谁？适合那些 PR 量大、维护者精力有限、又希望有一层“机器初筛”的团队；也适合个人项目，让每次提交都有一份即时的第二意见。

但要做好，绕不开几个工程细节：触发事件怎么选才不会重复触发、权限怎么配才能既发评论又不越权、diff 怎么喂给模型才不浪费 token、评论怎么更新而不是新增。这篇就按“能直接抄走”的标准，把 workflow YAML、权限配置、验证步骤和排障清单一次讲清楚，最后再说怎么把 endpoint 统一到 TaoToken 的 Key 通道，省得每个仓库都去配一遍原生 Key。

我试过把整套流程跑在三个不同规模的仓库上，从单人小项目到日更 20 个 PR 的团队仓库，下面这些配置都是踩过坑之后收敛出来的版本。

2. 前置准备：TaoToken 统一 Key 通道与仓库权限配置

在写 workflow 之前，先把“模型从哪来”这件事定下来。原生做法是每个仓库配一个ANTHROPIC_API_KEY，但仓库一多，Key 管理就成了噩梦：轮换要改 N 个地方，额度分散看不清，谁用了多少也不知道。更实际的做法是走TaoToken 统一 Key 通道，一个 Key 覆盖多个仓库的调用，endpoint 指向https://taotoken.net/api，模型 ID 仍然用 Claude 系列。

具体来说，你需要准备三样东西：

第一，一个 TaoToken 的 API Key。到控制台的 API Keys 页面生成，建议按“用途”命名，比如github-action-pr-bot，方便后续按项目统计消耗。生成后先复制保存，页面刷新就看不到了。

第二，仓库的 Actions 权限。进入仓库Settings → Actions → General，把Workflow permissions设为Read and write permissions。这一步很关键，因为机器人要发评论、要更新评论，默认的只读权限会直接让create_issue_comment报 403。如果你只想让它读不想让它写，那就得改成用pull_request_target事件配合单独的 token，复杂度会上升，新手不建议。

第三，把 Key 存进 Secrets。路径是Settings → Secrets and variables → Actions → New repository secret，名字填TAOTOKEN_API_KEY，值粘贴刚才的 Key。注意GITHUB_TOKEN是 GitHub 自动注入的，不需要你手动加，也不要去覆盖它。

这里有个容易忽略的点：Base URL 和 Key 要成对出现。很多人只改了 Key 没改 Base URL，结果请求还是打到原生 endpoint，报 401。正确的三件套是：

如果你用的是 Claude Code 这类 CLI 工具做本地调试，它的配置文件和 Action 里的环境变量是两套东西，别混。Action 里我们通过环境变量注入，CLI 里则是改settings.json。下面第 3 节会给出可直接复制的片段。

注意：不要把 Key 硬编码进 workflow YAML 或脚本里。GitHub 对公开仓库的日志有脱敏，但私有仓库的日志只有你自己能看，一旦泄露就是实打实的额度损失。

3. 可复制配置：workflow YAML 与脚本片段

这一节是全文的核心，直接给能跑的东西。先看 workflow 文件，放在.github/workflows/claude-pr-review.yml：

name: Claude PR Review on: pull_request: types: [opened, synchronize, reopened] permissions: contents: read pull-requests: write issues: write concurrency: group: claude-pr-${{ github.event.pull_request.number }} cancel-in-progress: true jobs: review: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Python uses: actions/setup-python@v5 with: python-version: '3.11' - name: Install deps run: pip install anthropic PyGithub - name: Run review env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} PR_NUMBER: ${{ github.event.pull_request.number }} REPO: ${{ github.repository }} run: python .github/scripts/pr_review.py

几个关键点解释一下。concurrency那段是防刷屏的核心：同一个 PR 的多次触发会被合并，cancel-in-progress: true让旧任务直接取消，只保留最新一次。permissions里pull-requests: write和issues: write是发评论必需的，contents: read用来读代码。types只监听opened、synchronize、reopened，不要加edited，否则改个标题都会触发。

然后是脚本.github/scripts/pr_review.py，重点是客户端初始化和评论更新逻辑：

import os import json import time from github import Github from anthropic import Anthropic # 三件套：Base URL + Key + Model ID client = Anthropic( api_key=os.environ["TAOTOKEN_API_KEY"], base_url="https://taotoken.net/api", ) MODEL_ID = "claude-3-5-sonnet-20241022" MARKER = "<!-- claude-pr-bot -->" def get_diff(pr): parts = [] for f in pr.get_files(): if f.patch: parts.append(f"File: {f.filename}\n{f.patch}") return "\n\n".join(parts) def build_prompt(diff_text): return f"""你是资深代码审查专家。审查以下 PR 变更，按 JSON 数组返回问题。 每个元素包含 type(bug/style/security/performance)、severity(1/2/3)、 file、line_start、message、suggestion。 没有问题返回 []。只报告确定的问题，避免误报。 diff: {diff_text} """ def call_model(prompt, retries=3): for i in range(retries): try: resp = client.messages.create( model=MODEL_ID, max_tokens=2000, temperature=0.0, messages=[{"role": "user", "content": prompt}], ) text = resp.content[0].text start, end = text.find("["), text.rfind("]") + 1 return json.loads(text[start:end]) except Exception as e: if i == retries - 1: raise time.sleep(2 ** i) def upsert_comment(pr, body): for c in pr.get_issue_comments(): if MARKER in c.body: c.edit(body) return pr.create_issue_comment(body) def main(): g = Github(os.environ["GITHUB_TOKEN"]) repo = g.get_repo(os.environ["REPO"]) pr = repo.get_pull(int(os.environ["PR_NUMBER"])) diff = get_diff(pr) if not diff.strip(): return issues = call_model(build_prompt(diff)) if not issues: body = f"{MARKER}\n## Claude 审查结果\n\n未发现明显问题。" else: lines = [f"{MARKER}\n## Claude 审查结果\n"] for it in issues: lines.append( f"- **{it['type']}** (severity {it['severity']}) " f"`{it['file']}` 行 {it.get('line_start', '?')}\n" f" {it['message']}" ) body = "\n".join(lines) upsert_comment(pr, body) if __name__ == "__main__": main()

upsert_comment是解决刷屏的关键：先找带MARKER的旧评论，找到就编辑，找不到才新建。这样无论触发多少次，PR 上永远只有一条机器人评论。

如果你本地用 Claude Code 调试，settings.json里对应的是：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的 TaoToken Key", "ANTHROPIC_MODEL": "claude-3-5-sonnet-20241022" } }

注意 CLI 用的是ANTHROPIC_BASE_URL，而 Python SDK 用的是base_url参数，名字不一样，别抄错。

4. 验证请求：用测试 PR 跑通评论与状态检查

配置写完了，别急着往主仓库推。先建一个测试分支，改一行代码，开一个 PR，观察 Action 的行为。验证分四步走。

第一步，看 Action 有没有被触发。进Actions标签页，应该能看到Claude PR Review这个 workflow 正在跑或已跑完。点进去看日志，如果卡在Install deps说明网络问题，卡在Run review就要看具体报错。

第二步，看评论有没有出现。回到 PR 页面，往下翻，应该有一条带<!-- claude-pr-bot -->标记的评论。如果没出现，先检查permissions是不是漏了pull-requests: write。

第三步，验证“更新而非新增”。在同一个 PR 上再推一个 commit，触发synchronize。等 Action 跑完，刷新页面，评论数量应该还是 1 条，内容被更新了。如果变成 2 条，说明MARKER匹配逻辑有问题，检查一下c.body里是不是真的包含那个标记。

第四步，验证状态检查。如果你想让机器人作为合并门禁，可以在 workflow 里加一个步骤，当发现severity == 3的问题时让 job 失败：

- name: Fail on critical if: env.HAS_CRITICAL == 'true' run: exit 1

这样 PR 页面底部会出现一个红色的检查项，配合分支保护规则就能阻止合并。不过新手建议先只报告不拦截，跑一两周看看误报率再决定要不要加门禁。

一个成功的日志片段长这样：

Processing PR #42 in your-org/your-repo Diff size: 187 lines Calling model claude-3-5-sonnet-20241022... Received response in 4.1s Parsed 2 issues Comment updated (id=123456789)

看到Comment updated就说明更新逻辑生效了。如果看到Comment created而这是第二次触发，那就是没匹配到旧评论。

5. 常见报错排查：401、local proxy failed 与 reading choices

这一节按真实报错来。我把踩过的坑列成对照表，你遇到时直接对号入座。

401 Unauthorized。最常见的原因是 Base URL 和 Key 不匹配。检查两点：base_url是不是https://taotoken.net/api，Key 是不是从 TaoToken 控制台生成的。还有一种情况是 Secret 名字写错，比如 YAML 里写TAOTOKEN_API_KEY，但 Secrets 里存的是TAOTOKEN_KEY，这种拼写差异不会报错，只会让环境变量为空，然后 401。

local proxy failed / connection error。这类报错通常出现在 runner 网络受限的场景。GitHub 托管 runner 一般能直连，但如果你用了自托管 runner 且配了网络策略，就可能连不上。排查方法是先在 runner 上curl -I https://taotoken.net/api看通不通。注意不要在任何地方配置来路不明的网络工具，企业环境走正规出口即可。

reading 'choices' of undefined。这个报错说明你拿到的响应结构不是预期的。原因通常是 endpoint 指向了一个 OpenAI 兼容格式的地址，但 SDK 用的是 Anthropic 格式，两者响应体不一样。确认你用的是anthropic这个库，而不是openai库，并且base_url指向的是 Anthropic 兼容端点。

OAuth token 相关报错。如果你在本地用 Claude Code 登录过，它可能缓存了 OAuth 凭证，和 Action 里的 API Key 冲突。Action 环境是干净的，不会有这个问题；本地调试时如果报 OAuth 错，清掉~/.claude下的缓存再试。

403 Resource not accessible by integration。这是权限问题，回到Settings → Actions → General，确认Workflow permissions是Read and write。如果仓库属于组织，还要看组织级别有没有限制。

评论发出来是空的或格式乱。多半是模型返回的 JSON 被 markdown 代码块包裹了，text.find("[")没找到。可以在解析前先text.replace("```json", "").replace("```", "")清洗一下。

Codex auth.json / Cline MCP / CC Switch 场景。如果你同时用这些工具，记住它们各自有独立的配置文件，不要指望改一处全都生效。Codex 看auth.json，Cline 看 MCP 配置，CC Switch 看它自己的 profile。统一到 TaoToken 时，每个工具都要单独填 Base URL、Key、Model ID 三件套。

排障时最有用的一招是：在脚本里把resp的原始文本打出来（注意别打 Key），看一眼模型到底返回了什么，比猜快得多。

6. 把机器人用顺手：从能跑到好用的几个调整

跑通之后，真正决定它好不好用的是几个细节。

控制 diff 大小。一个 2000 行的 PR 直接喂进去，token 消耗大、延迟高、还容易触发上下文截断。可以在脚本里加个判断，超过 800 行就只取前几个文件，或者按文件分片多次调用再合并结果。实测下来，单次 diff 控制在 500 行以内，响应时间和准确率都比较平衡。

给提示词加团队规则。默认提示只做通用审查，你可以把团队的规范塞进去，比如“禁止使用 print 调试”“所有公开函数必须有类型注解”。这些规则用自然语言写就行，模型能理解。规则放在单独的rules.md里，脚本读取后拼进 prompt，改规则不用动代码。

缓存相同 diff。如果同一个 commit 被重复触发（比如手动 rerun），没必要再调一次模型。可以用 commit SHA 做 key，把结果存到actions/cache里，命中就直接发评论。这一步能省不少额度。

监控消耗。TaoToken 控制台能看到每个 Key 的调用量和消耗，建议每周看一眼。如果某个仓库突然涨得厉害，多半是触发了死循环或者 diff 异常大，及时排查。

评论的可读性。别把模型返回的原始 JSON 直接贴出来，转成 markdown 列表，严重问题加粗，建议用引用块。维护者扫一眼就能抓住重点，而不是读一坨结构化数据。

最后说 CTA 的分流。如果你主要是在排障和接入阶段，先去 API Keys 页面 生成 Key，再对照 接入文档 把 Base URL 和模型 ID 填对。想先验证模型输出质量，可以到 模型对话 里手动贴一段 diff 试试效果。如果你打算长期跑编码类 Agent 任务，比如让机器人做更复杂的重构建议，Coding Plan 会比按量计费更划算。控制台在 这里，Claude Code 相关配置参考 ClaudeCodeAnthropic 文档。

整套流程跑下来，最花时间的其实不是写代码，而是调触发条件和评论更新逻辑。把这两块弄稳，剩下的就是按团队习惯微调提示词了。