Claude Code 在 CI 里跑：从本机 claude -p 到 GitHub Actions 的完整例子（自动审 PR、控成本）

本文根据 Claude Code 官方《Claude Code GitHub Actions》和《Run Claude Code programmatically》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。工作流里的提示词和参数组合是本站自己拟的示例。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 已经看过 /guides/claude-code-headless-mode 和 /guides/claude-code-github-actions，但想看一个从头到尾串起来的例子的人；
• 想让每个 PR 自动过一遍 Claude 审查，又担心费用失控的团队；
• 想先在本机把命令调通，再放进 CI 的人。

结论先说

1. 先本机，后 CI：同一段提示词、同样的 --allowedTools，在本机用 claude -p 跑通再搬到工作流里，排错成本最低。
2. CI 里用 --bare：官方说它能让每台机器得到一致的结果，不会读到别人 ~/.claude 里的 hook 或项目 .mcp.json 里的服务器；它不读订阅登录，要设置 ANTHROPIC_API_KEY。
3. GitHub Actions 里有 prompt 就是自动化模式：不等 @claude 评论，直接按触发事件运行；默认结果只写在工作流日志里。
4. 权限要显式给：官方写明自动化模式下，普通文本提示词没有 shell 和 GitHub API 权限，除非用 --allowedTools 或 permissions.allow 授予。
5. 成本靠三道闸：--max-turns、工作流超时、并发限制，加上一份简短的 CLAUDE.md。

图：本站根据 Claude Code 官方《Claude Code GitHub Actions》 整理的示意图

一、第一步：本机用 claude -p 跑通

假设要做的事是「审查当前分支相对 main 的改动，只报严重问题」。官方有现成的管道写法：把 diff 通过标准输入交给 Claude，它就不需要 Bash 权限去读 diff。先试一个最朴素的版本：

bash
git diff main...HEAD | claude --bare -p "你是代码审查员。只指出会导致 bug 或安全问题的改动，每条一行：文件名:行号 问题。没有问题就只回复 OK。"

要让脚本能判断结果，用官方的 --output-format json 加 --json-schema，结构化结果在 structured_output 字段里：

bash
git diff main...HEAD | claude --bare -p "审查这份 diff，列出严重问题" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"issues":{"type":"array","items":{"type":"string"}}},"required":["issues"]}' \
  | jq '.structured_output.issues'

两个官方提醒要放进脚本：

• 如果运行结束时没有有效的结构化输出（比如 Claude 拒绝了请求），响应里没有 structured_output 字段，所以脚本里要先判断字段存在，再使用；
• 退出码：成功是 0，失败是非 0。不过官方也说，运行过程中的失败（比如缺少认证）会把失败信息作为结果打印到标准输出，所以不要只看退出码。

输入有 10MB 的上限：超过会报错退出，大改动要先写到文件再在提示词里引用路径。

先在本机确认输出符合预期，再往下走。可以在 claude -p 的结果里看到 total_cost_usd（官方说这是客户端估算，可能与账单有出入），用来估一个 PR 大概花多少。

二、第二步：把审查标准写进 CLAUDE.md

CI 里每次运行都会读仓库里的 CLAUDE.md（不加 --bare 时；GitHub Action 按官方最佳实践页的说法同样会遵循它）。把审查口径写进去，比每次改工作流里的提示词方便：

markdown
## 代码审查
- 只关注：会导致运行错误、数据丢失、越权或密钥泄露的改动
- 不要评论代码风格，格式问题由 lint 负责
- 每条意见写明文件名和行号

官方提醒要保持精简，因为它每次运行都会被读入。写法参考 /guides/claude-code-claude-md-templates-frontend-backend-data。

三、第三步：配置密钥与应用

官方推荐的快速路径：在仓库里打开 claude，运行 /install-github-app，它会安装 Claude GitHub App、保存仓库密钥，并推一个带工作流文件的分支、帮你打开创建 PR 的页面。这条命令只对 github.com 仓库有效，需要你有仓库管理员权限，并先安装、登录 GitHub CLI（gh auth login）。

手动配置时：安装 Claude GitHub App；在仓库 Secrets 中添加 ANTHROPIC_API_KEY（Claude Console 的 API Key），或者订阅用户用 claude setup-token 生成令牌存为 CLAUDE_CODE_OAUTH_TOKEN。官方特别写了：永远不要把 Key 提交进仓库，只放 Secrets。多个仓库共享时，官方建议用 API Key 而不是 OAuth 令牌，因为令牌绑定的是运行 setup-token 那个人的订阅。订阅和 API 的取舍见 /guides/claude-code-pro-max-or-api。

四、第四步：写自动审查的工作流

下面的触发事件、权限块和 action 版本取自官方示例的写法，prompt 和 claude_args 是本站按官方说明拼的：

yaml
name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            审查本 PR 相对 ${{ github.base_ref }} 的改动，只报严重问题，按 CLAUDE.md 的「代码审查」要求。
            用 git diff 查看改动，输出文件名:行号和问题；没有问题就写 OK。
          claude_args: |
            --max-turns 8
            --allowedTools "Read,Grep,Glob,Bash(git diff *),Bash(git log *)"

逐段说明：

• on.pull_request.types：官方审查示例用的同一组事件；
• concurrency 与 cancel-in-progress：同一个 PR 连续推送时取消旧的运行，对应官方成本建议里的「使用 GitHub 并发控制限制并行运行」；
• timeout-minutes：对应「设置工作流级超时避免跑飞」；
• id-token: write：官方说明这是 action 默认使用 GitHub App 认证所需；
• prompt 一旦存在，就是自动化模式，不再等待 @claude；
• --max-turns 8：官方 claude_args 的常见参数，限制回合数；
• --allowedTools：自动化模式下授予 shell 与读取权限，Bash(git diff *) 的写法是官方的前缀匹配语法；
• fetch-depth: 0：本站补充，为了能比较 base 分支，官方示例用的是 1，如果你只需要看改动文件的内容可以保留 1。

结果去哪里看：官方写明，自动化模式默认结果出现在工作流运行日志里。若希望审查意见直接成为 PR 上的评论，官方的现成做法是安装 code-review 插件并带 --comment（官方「Run a skill」一节），以及在 claude_args 里允许 mcp__github_inline_comment__create_inline_comment。官方还说明：公开仓库里来自 fork 的 PR 拿不到 Secrets，所以审查只对同仓库分支的 PR 生效。

五、同一个仓库再加「@claude 随叫随到」

自动审查之外，官方最基本的工作流是让评论里的 @claude 触发（交互模式，不写 prompt）：

yaml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

官方指出触发者必须有仓库写权限，机器人账号默认会被拒绝，以防循环触发。

六、出问题先看哪里

图：本站根据 Claude Code 官方《Claude Code GitHub Actions》 整理的示意图

官方排查页的要点：评论 @claude 没反应，检查 GitHub App 是否安装、工作流是否启用、Secrets 是否设置、评论里是否是完整的 @claude 单词、评论者是否有写权限；Claude 推送的提交没触发 CI，是因为用默认 GITHUB_TOKEN 提交的代码不会触发工作流，去掉传给 action 的 github_token；认证失败，先在本机用同一个 Key 或令牌运行 claude 验证。

常见问题

Q：一次审查大概花多少钱？

官方不给固定数字，只说取决于提示词和回复长度、任务复杂度、代码库大小，价格以官方定价页为准。可以用本机 JSON 输出里的 total_cost_usd 做估算。

Q：用订阅还是 API？

订阅令牌适合个人仓库，团队共享用 API Key，详见第三节。想了解订阅方案可看 Claude Code 订阅方案。

相关教程

• /guides/claude-code-headless-mode
• /guides/claude-code-github-actions
• /guides/claude-code-permission-modes

参考资料

• Claude Code 官方：Claude Code GitHub Actions — https://code.claude.com/docs/en/github-actions
• Claude Code 官方：Run Claude Code programmatically — https://code.claude.com/docs/en/headless