企业官网建设流程全解析

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.yml：

name: 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/checkout@v4 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-script@v7 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_KEY，workflow 里${{ secrets.ANTHROPIC_API_KEY }}有没有拼写错误。还有一种情况是 Key 本身失效了，去控制台重新生成一个。注意 Key 只在生成时显示一次，复制时不要带前后空格。

local proxy failed / connection refused：Base 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 的调试成本比本地高得多，能本地验证的就别留给流水线。