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。正确的三件套是配置项值Base URLhttps://taotoken.net/apiAPI Key存在TAOTOKEN_API_KEYSecret 里Model IDclaude-3-5-sonnet-20241022或你账号可用的 Claude 模型如果你用的是 Claude Code 这类 CLI 工具做本地调试它的配置文件和 Action 里的环境变量是两套东西别混。Action 里我们通过环境变量注入CLI 里则是改settings.json。下面第 3 节会给出可直接复制的片段。注意不要把 Key 硬编码进 workflow YAML 或脚本里。GitHub 对公开仓库的日志有脱敏但私有仓库的日志只有你自己能看一旦泄露就是实打实的额度损失。3. 可复制配置workflow YAML 与脚本片段这一节是全文的核心直接给能跑的东西。先看 workflow 文件放在.github/workflows/claude-pr-review.ymlname: 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/checkoutv4 with: fetch-depth: 0 - name: Setup Python uses: actions/setup-pythonv5 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_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://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(fFile: {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, retries3): for i in range(retries): try: resp client.messages.create( modelMODEL_ID, max_tokens2000, temperature0.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 (id123456789)看到Comment updated就说明更新逻辑生效了。如果看到Comment created而这是第二次触发那就是没匹配到旧评论。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错来。我把踩过的坑列成对照表你遇到时直接对号入座。401 Unauthorized。最常见的原因是 Base URL 和 Key 不匹配。检查两点base_url是不是https://taotoken.net/apiKey 是不是从 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.jsonCline 看 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 文档。整套流程跑下来最花时间的其实不是写代码而是调触发条件和评论更新逻辑。把这两块弄稳剩下的就是按团队习惯微调提示词了。