1. 为什么要把 Claude Code 塞进 CI/CD从交互式到无人值守的真实痛点Claude Code 的 Headless 模式简单说就是让claude -p 任务在没有人盯着终端的情况下跑完任务、输出结果、然后退出。它适合谁适合那些已经把代码审查、格式检查、changelog 生成这类重复劳动交给流水线但还想再加一层语义级检查的团队。传统 CI 能告诉你测试过没过、lint 有没有报错但它看不懂这个 PR 的改动有没有引入并发隐患这个函数改名后调用方有没有漏改这类需要理解上下文的问题。Headless 模式补的就是这一层。我试过在本地手动跑claude -p做 PR 审查效果不错但每次都要人肉触发等于没解决根本问题。真正的价值在于把它接进 GitHub Actions开发者 push 代码流水线自动拉起 Claude读 diff、跑检查、把结论写回 PR 评论。整个过程无人参与失败也不阻塞合并只是给一个需要人工看一眼的信号。这里有个关键认知Headless 不是另一个工具而是 Claude Code 的另一种使用方式。你在交互式里用的 Tools、Skills、Hooks、SubAgent、MCP在 Headless 下全部照常生效区别只在于没有人按确认键。所以安全边界必须提前设计好——白名单命令、最小权限 token、沙箱隔离、失败回退、完整日志这五件事一个都不能少。下面从接入配置开始一步步把这条流水线跑通。2. TaoToken 前置Base URL、API Key 与模型 ID 三件套怎么配在把claude -p接进 Actions 之前先要在本地确认 Claude Code 能正常调用模型。TaoToken 提供的是兼容 Anthropic 协议的接入方式你需要准备三样东西Base URL、API Key、Model ID。这三件套在后面的 workflow 里会以环境变量的形式出现所以先在本地跑通再搬到 CI 里。Base URL 填https://taotoken.net/api这是 API 入口注意不要带任何查询参数。API Key 在控制台的 API Keys 页面生成生成后只显示一次复制保存好。Model ID 按你实际要用的模型填比如claude-sonnet-4-20250514这类标识具体以文档里的模型列表为准。本地配置有两种方式。一种是写进~/.claude/settings.json适合长期使用另一种是用环境变量适合 CI 这种一次性环境。先看 settings.json 的写法{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Claude Code 的配置文件体系路径通常是~/.claude/settings.json字段名要和上面保持一致。改完之后在终端里跑一句最简单的验证claude -p 回复 ok --output-format text如果输出里能看到ok或者类似的正常回复说明 Base URL 和 Key 都通了。如果报 401多半是 Key 复制时带了空格或者引号如果报连接失败检查 Base URL 有没有多写斜杠或者路径。对于 CI 环境不要把 Key 写进 settings.json 提交到仓库。正确做法是在 GitHub 仓库的 Settings → Secrets and variables → Actions 里新建一个 secret名字叫ANTHROPIC_API_KEY值填你的 Key。workflow 里通过${{ secrets.ANTHROPIC_API_KEY }}引用。Base URL 和 Model ID 不是敏感信息可以直接写在 workflow 的 env 块里也可以放进仓库的 Variables。这里要提醒一点TaoToken 的 API Key 和 GitHub 的 GITHUB_TOKEN 是两回事前者用于调用模型后者用于操作仓库。两个都要单独管理scope 各自收窄。GITHUB_TOKEN 在 workflow 里通过permissions字段控制后面会详细写。3. 可复制配置GitHub Actions workflow 与 settings 片段这一节给出可以直接复制进仓库的配置。先建目录结构在仓库根目录下创建.github/workflows/和.github/claude-config/hooks/。workflow 文件放在前者Hook 脚本放在后者。先看完整的 workflow YAML文件名claude-review.ymlname: Claude Code Review on: pull_request: types: [opened, synchronize, reopened] push: branches: [main, develop] permissions: contents: read pull-requests: write jobs: claude-review: runs-on: ubuntu-latest timeout-minutes: 10 steps: - name: Checkout uses: actions/checkoutv4 with: fetch-depth: 0 - name: Setup .claude run: | mkdir -p .claude/hooks cp .github/claude-config/hooks/*.sh .claude/hooks/ chmod x .claude/hooks/*.sh - name: Claude Review id: review env: ANTHROPIC_BASE_URL: https://taotoken.net/api ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ANTHROPIC_MODEL: claude-sonnet-4-20250514 run: | REVIEW_RESULT$(claude -p review this PR, list issues by severity \ --allowedTools Read,Grep,Glob,Bash(git:diff),Bash(git:log) \ --output-format json) echo review_result$REVIEW_RESULT $GITHUB_OUTPUT - name: Post PR Comment uses: actions/github-scriptv7 with: script: | const review ${{ steps.review.outputs.review_result }}; const body ## Claude Code Review\n\n${review}; github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, body: body });几个关键点解释一下。permissions里contents: read让 Claude 只能读代码pull-requests: write允许写 PR 评论不给 admin 权限。fetch-depth: 0是为了让git diff能拿到完整历史否则浅克隆会导致 diff 不完整。--allowedTools限制了 Claude 能调用的工具只给读文件和 git 查询类命令不给 Edit、Write、rm、curl。--output-format json让输出结构化方便后续解析。再看 Hook 白名单脚本放在.github/claude-config/hooks/ci-allowlist.sh#!/usr/bin/env bash INPUT$(cat) COMMAND$(echo $INPUT | jq -r .tool_input.command // ) if echo $COMMAND | grep -qE ^(git|pytest|ruff|npm run test|make test)\b; then exit 0 fi echo CI 模式拒绝: $COMMAND 不在白名单 2 exit 2这个脚本挂在 PreToolUse 事件上任何不在白名单里的 Bash 命令都会被拦下。白名单只放 git、pytest、ruff、npm run test、make test 这几类其他一律拒绝。这样即使 Claude 在推理过程中想跑rm -rf或者curl | sh也会被 Hook 挡住。如果你还想加自动修复能力可以再建一个claude-auto-fix.yml把--allowedTools里加上Edit,Write并在 commit 步骤里判断git diff --quiet有改动才提交。但自动修复只建议处理格式问题、缺 timeout、简单 bug 这类低风险项复杂逻辑改动还是留给人判断。4. 验证请求本地 claude -p 调用与 Actions 运行日志确认配置写完之后先别急着 push。在本地把claude -p跑一遍确认输出格式和工具限制都符合预期。用 stdin 模式模拟 CI 里的 diff 输入git diff main..HEAD | claude -p 总结这次改动的关键点 \ --allowedTools Read,Grep,Glob,Bash(git:diff) \ --output-format text如果本地能正常输出总结说明 Base URL、Key、Model ID 三件套没问题。再测一下 JSON 输出claude -p review this PR --output-format json | jq .JSON 能正常解析说明后面 workflow 里的jq提取逻辑也能跑通。这一步很关键因为 CI 里出问题排查成本高本地先验证能省很多时间。本地通过后把 workflow 和 Hook 脚本提交到仓库开一个测试 PR。push 之后到 GitHub 的 Actions 标签页找到这次运行点进去看日志。重点看三个地方Setup .claude 步骤有没有成功复制 Hook 脚本Claude Review 步骤的 stdout 里有没有正常的审查结果Post PR Comment 步骤有没有报权限错误。如果 Claude Review 步骤输出为空先检查ANTHROPIC_API_KEYsecret 有没有配、名字有没有拼错。如果报local proxy failed或者连接超时检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/多了斜杠或者网络策略有没有限制出站。如果 Post PR Comment 报 403检查permissions里pull-requests: write有没有加。运行成功后回到 PR 页面应该能看到一条由 github-actions 机器人发的评论里面是 Claude 的审查结论。到这一步一条无人值守的 AI 检查流水线就跑通了。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth实际跑的时候报错集中在几个地方。下面按真实报错信息对照排查。401 Unauthorized最常见。原因通常是 API Key 没配、配错、或者 secret 名字和 workflow 里引用的不一致。检查 GitHub Secrets 里的名字是不是ANTHROPIC_API_KEYworkflow 里${{ secrets.ANTHROPIC_API_KEY }}有没有拼写错误。还有一种情况是 Key 本身失效了去控制台重新生成一个。注意 Key 只在生成时显示一次复制时不要带前后空格。local proxy failed / connection refusedBase URL 配置问题。确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api不要带尾部斜杠不要带查询参数。如果本地能通、CI 不通检查 workflow 的 env 块有没有正确传递这个变量。有些团队会在仓库级别设 Variables但 workflow 里没引用也会导致 CI 里读不到。reading choices / unexpected response format模型返回的结构和预期不符。多半是 Model ID 写错了或者用了不兼容的模型标识。去文档里核对当前可用的 Model ID确保和ANTHROPIC_MODEL一致。另外--output-format json要求模型返回结构化内容如果模型不支持会解析失败可以先用text格式验证。OAuth / authentication failed如果你在本地用过 Claude Code 的 OAuth 登录CI 里不会复用那个凭证。CI 必须用 API Key 方式不能依赖本地登录态。检查 workflow 里有没有正确设置ANTHROPIC_API_KEY以及有没有误把本地的~/.claude配置带进 CI。Hook 没生效检查.claude/hooks/目录下脚本有没有执行权限workflow 里chmod x那步有没有跑。另外 Hook 的 matcher 要匹配Bash事件类型要挂在PreToolUse上。如果脚本里用了jq确认 runner 环境里有安装ubuntu-latest 默认带 jq一般没问题。Claude 失败导致 CI 挂掉给 Claude Review 步骤加continue-on-error: true失败时不阻塞后续步骤。再加一个if: failure()的步骤给 PR 打上needs-human-review标签并写评论说明。这样 CI 不会因为模型服务波动而卡住合并流程。6. 把 claude -p 接进流水线之后长期编码与 Agent 场景的延伸跑通 PR Review 只是起点。同样的 Headless 模式可以扩展到更多场景每天定时跑一次 changelog 生成用schedule触发Sentry 报警触发 webhook让 Claude 自动诊断异常批量处理脚本对每个文件跑一次语义检查。这些场景的共同点是任务可预测、输出可结构化、失败可回退。如果你打算把 Claude Code 长期用在编码和 Agent 类任务上建议单独规划一套 Coding Plan把模型调用额度、并发限制、日志留存都纳入管理。API Key 按用途分开CI 用的和本地开发用的不要混在一起方便出问题时定位和吊销。接入文档里有更完整的参数说明和模型列表配置过程中遇到字段不确定的地方对照文档核对一遍比反复试错快。模型对话页面可以用来快速验证某个 Model ID 是否可用不用每次都改 workflow 再 push。控制台的 API Keys 页面负责生成和吊销 Key建议给 CI 单独建一个 Key命名上带ci-前缀方便识别。最后留一个实用习惯每次改完 workflow先在本地用act或者手动跑一遍claude -p命令确认命令本身没问题再 push 到仓库。CI 的调试成本比本地高得多能本地验证的就别留给流水线。