📌 本讲摘要

前 20 讲我们学的所有扩展机制（SubAgent / Skills / Hooks / MCP / Tools）都是交互式------人在回路里、Claude 推理、人确认。本讲进入无人值守------Headless 模式：让 Claude Code 脱离人的实时操控、以守护进程般的姿态嵌入 CI/CD 流水线。3 个核心主题：Headless 模式基础（claude -p 非交互模式 + 守护进程）/ GitHub Actions 集成（自动 PR Review + 自动修复）/ 权限收窄（机器自治的安全边界）。目的是让你把 Claude Code 从 IDE 工具变成 CI 工具------提交代码 → Claude 自动审查 → 自动修复 → 自动部署。

本讲的三条主线：

第一、Headless 模式基础 + GitHub Actions 集成------claude -p "任务" 让 Claude 跑任务后退出；GitHub Actions workflow 配 Claude Code action,push 触发后自动 PR Review、审查结果写 PR 评论。

第二、自动修复 + 自动 commit------Claude 跑完审查发现可修复 bug → 自动 Edit 改 → 自动 commit → push 回 PR；危险操作仍被 Hook 拦截（Headless 模式下 Hook 仍生效）。

第三、权限收窄 + 机器自治工程实践------通过 Hook 收窄（白名单命令）/ env 限制（只读 token)/ sandbox（不让 Claude 改生产环境）;5 条工程实践：CI token 单独管理 / Hook 白名单 / 沙箱 / 失败 fallback / 日志完整。

学完本讲、你应该能用 claude -p 跑 Headless 模式、能配 GitHub Actions 自动化 PR Review、能设计 CI/CD 中的机器自治安全边界、能区分 Headless 和交互式的工程定位。

📖 详细内容

Headless 模式基础：`claude -p` 非交互模式

前 20 讲 Claude Code 都是交互式------人在回路里、Claude 推理、人确认。本讲进入无人值守------Headless 模式：Claude 跑任务后退出、不等人确认。

3 种 Headless 模式

模式 1：单次任务模式 (claude -p "任务")------Claude 跑任务、完成后退出、stdout 输出结果。例：claude -p "review this PR and list issues" 输出审查结果后退出。

模式 2：stdin 模式 (echo "任务" | claude -p)------任务从 stdin 读、适合脚本管道。例：git diff | claude -p "总结这次改动" 把 git diff 通过 stdin 给 Claude,Claude 输出总结。

模式 3：守护进程模式(daemon)------Claude 跑成后台进程、接受远程调用。适合长连接场景（不常用、本讲不深入）。

3 种模式的选择：CI 自动化用模式 1 / 2、长连接用模式 3。

单次任务模式的 3 个关键参数

参数 1：-p 任务------指定任务描述。Claude 看到任务后开始推理、完成后 stdout 输出结果。

参数 2:--allowedTools ------限制 Claude 能调的工具（权限收窄）。例：claude -p "review PR" --allowedTools "Read,Grep,Glob,Bash(git:*)" 只允许 Read / Grep / Glob / Bash(git 命令）。

参数 3：--output-format------指定输出格式（json / text / stream-json）。CI 集成常用 json 格式（便于解析）。

3 个参数让 Headless 模式可控------任务明确 / 权限收窄 / 输出可解析。

Headless 的 4 个适用场景

CI 自动化------GitHub Actions / GitLab CI 触发、跑 PR Review / 自动修复 / 部署。
Cron 定时任务------每天跑 1 次 Claude 自动总结昨天的代码改动 / 自动整理 changelog。
Webhook 触发------GitHub push 触发 / Sentry 异常触发、Claude 跑诊断 / 修复。
批处理脚本------批量跑 Claude 任务（每文件 1 次）、适合大规模数据处理。

4 个场景都无人参与------Headless 模式的核心价值：把 Claude Code 从人用工具变成机器用工具。

GitHub Actions 集成：自动 PR Review

Headless 模式最常见的应用是 GitHub Actions 集成------开发者 push 代码 → GitHub Actions 触发 → Claude Code Headless 跑 PR Review → 审查结果写 PR 评论。

step 1：在仓库里配 GitHub Actions workflow

在 .github/workflows/claude-review.yml 配 workflow、触发条件：PR 打开 / 同步 / push。完整配置见后面GitHub Actions workflow 完整配置代码块。

step 2：GitHub Actions 跑 Claude Code action

用 Anthropic 官方提供的 Claude Code GitHub Action（或第三方）、在 workflow 里调用。Action 内部跑 claude -p "review this PR",Claude 读 PR diff / 推理 / 写审查意见。

step 3：Claude 审查结果写回 PR 评论

Claude 输出的审查意见用 GitHub API 写回 PR 评论、开发者看到完整的审查报告。

3 步形成自动化 PR Review 流水线------开发者 push 代码、几分钟后 PR 上有 Claude 的审查意见、无需人工参与。

触发条件的选择

触发 1：pull_request 触发(PR 打开 / 同步）--- 适合 PR-based 工作流（GitHub flow）。

触发 2：push 触发(push 到 main / develop)--- 适合 main-based 工作流。

触发 3：workflow_dispatch 手动触发--- 适合按需跑场景、开发者手动点按钮跑 Claude 审查。

触发 4：schedule 定时触发(cron)--- 适合每天跑一次健康检查。

4 种触发条件覆盖所有 CI 场景、PR Review 用触发 1 / 2 最常见。

自动修复与自动 commit

PR Review 是被动------Claude 指出问题、人修复。本节升级到主动修复------Claude 跑完审查发现可修复 bug → 自动 Edit 改 → 自动 commit → push 回 PR。

自动修复的 3 个步骤

步骤 1：Claude 跑审查 (claude -p "review this PR, find fixable bugs")------Claude 不仅指出问题、还标记哪些可以自动修复。

步骤 2：Claude 自动 Edit 改------Claude 对可自动修复的问题用 Edit 工具改文件（格式问题 / 简单 bug / 缺 timeout / 缺测试）。

步骤 3：自动 commit + push ------Claude 跑 Bash git add . && git commit -m "fix: auto-fix by Claude" && git push 把修改推回 PR 分支。

3 步形成自动修复流水线------开发者 push 代码、Claude 跑审查 + 自动修复 + 推回、开发者只需要看 diff 确认是否合理。

Headless 模式下 Hook 仍生效

重要：Headless 模式不是放任 Claude 跑,Hook 仍生效。PreToolUse Hook 仍能拦危险命令（rm -rf / curl | sh),Stop Hook 仍能检查未提交 / 测试通过。

Headless + Hook 的协同：CI token 权限收窄 + Hook 白名单命令 = 机器自治的安全边界。Claude 在 CI 跑也出不了大错。

自动修复的边界

不要全自动修复所有 bug------只自动修复低风险 / 明确的问题（格式 / 简单 bug / 缺 timeout）。复杂 bug（架构问题 / 性能瓶颈）仍由人判断。

边界判断：这个 bug Claude 能高置信度修复吗?能 → 自动修；不能 → 仅标记让人看。

权限收窄：机器自治的安全边界

Headless 模式下 Claude 跑在 CI、不能放任------必须有安全边界。3 个维度收窄权限。

维度 1：HW 白名单命令（PreToolUse 拦危险）

Headless 模式下配置更严的 PreToolUse HW：白名单允许的命令(git:*, pytest:*, ruff:*, npm run test)、其他命令都拦（rm -rf / curl | sh / dd 等）。

白名单 vs 黑名单：白名单更严------只允许明确知道安全的命令；黑名单只拦已知的危险、可能漏掉新出现的危险。CI 推荐白名单。

维度 2：CI token 权限收窄（env 限制）

GitHub Actions 用 GITHUB_TOKEN（自动提供）,token scope 收窄到 contents: read（只读）或 contents: write（仅 PR 写回）。绝不用 admin token、避免 Claude 改生产环境。

同理、Anthropic API key 用 ANTHROPIC_API_KEY 单独管理、只给 CI 用、不和其他 key 混。

维度 3：Sandbox 沙箱（不让 Claude 改生产）

用 Docker 沙箱跑 Claude Code------Claude 在容器里跑、容器和主机隔离。即使 Claude 跑了 rm -rf、也只删容器内文件、不会影响主机 / 生产环境。

沙箱 vs 主机直跑：沙箱安全但启动慢（每次 workflow 启动容器）；主机直跑快但有风险。CI 推荐沙箱。

3 维权限收窄 = 机器自治的安全边界------Claude 在 CI 跑也出不了大错。

机器自治的工程实践 5 条

5 条工程实践是 Headless 模式的检查清单、任何 CI 集成 Claude Code 都应该按这 5 条评估。

实践 1：CI token 单独管理

CI 用的 token(GITHUB_TOKEN / ANTHROPIC_API_KEY）单独生成、scope 收窄（只读 / 仅 PR 写回）、不进代码仓库（用 GitHub Actions secrets）。token 泄露时影响范围最小。

实践 2：HW 白名单命令

CI 用的 Hook 配置比开发用更严------白名单命令（git:*, pytest:*, ruff:*, npm run test)、其他命令都拦。PreToolUse HW 配 deny-pipe-exec + deny-extra-dangerous + 白名单三层。

实践 3：沙箱跑危险操作

Claude 在 Docker 沙箱里跑、容器和主机隔离。沙箱启动慢但安全。生产环境的 Claude 跑一定要沙箱、开发环境的本地 Claude 跑可直跑。

实践 4：失败 fallback（回退人工）

CI 跑 Claude 失败（网络超时 / API 报错 / 任务失败）时、不能直接挂------回退到人工 review 标记或等下次 push 重试。fallback 机制确保 CI 不会因为 Claude 故障而停摆。

实践 5：日志完整记录

CI 跑 Claude 的所有输出（任务 / stdout / stderr / Hook 拦截 / 决策点）都完整记录到 GitHub Actions log、便于事后审计。出问题时能从日志看到Claude 跑了什么 / HW 拦了什么 / Claude 怎么推理。

维度	配置	风险	推荐
HW 白名单	PreToolUse ci-allowlist.sh	无 = Claude 跑任意命令	配（白名单 git/pytest/ruff)
token 收窄	permissions: contents:read	admin token = Claude 改生产	配（只读 / 仅 PR 写回）
沙箱	Docker 跑 Claude	主机直跑 = rm -rf 删主机	配（沙箱 + 容器隔离）
fallback	continue-on-error + 人工 label	无 = Claude 失败 CI 挂	配（回退人工 review)
日志	GitHub Actions 自动记录	不完整 = 出事无法审计	配（任务 / stdout / HW / 决策点）

Headless vs 交互式 + 与其他扩展机制协同

Headless 是另一种使用方式、不是另一种工具------其他 5 种扩展机制（SubAgent / Skills / Hooks / MCP / Tools）在 Headless 模式下仍可用。

Headless vs 交互式

交互式：人在回路、Claude 推理 → 调工具 → 输出 → 人确认 → 继续。适合开发阶段（探索性任务）。

Headless：人不在回路、Claude 跑任务 → 退出。适合CI 阶段（可预测任务）。

2 种模式的工作流：开发用交互式调通 → 沉淀为 Headless 跑 CI。例：开发用交互式调通"PR Review"流程 → 配 GitHub Actions 用 Headless 跑同样流程。

维度	交互式	Headless
触发方式	人启动 Claude Code	CI / cron / webhook 自动触发
用户参与	人在回路（确认 / 决策）	人不在回路（Claude 自主）
适用场景	开发（探索性 / 调试）	CI / 定时任务（可预测）
权限	本地用户权限（较宽）	CI token 收窄 + HW 白名单（较严）
输出	人眼看（交互式输出）	stdout / JSON（脚本解析）
调试	本地日志 / 重跑	CI 日志 / re-run workflow

5 种扩展机制在 Headless 下仍可用

• Tools：Headless 下 Read / Write / Bash 仍可用、只是没人确认、Claude 直接推理调。

• Skills：Headless 下 .claude/skills/ 仍加载、Claude 仍按 description 自动发现。

• SubAgent：Headless 下 @name 仍能调 SubAgent（只是 SubAgent 完成没人确认、直接汇总结果）。

• Hooks：Headless 下 4 类事件仍触发、PreToolUse 仍能拦、PostToolUse 仍能记录、Stop 仍能门控。

• MCP：Headless 下 .mcp.json 仍加载、Claude 仍能调 mcp__xxx__yyy。

5 种机制无障碍切换------开发交互式用 5 种机制、CI Headless 也用 5 种机制。区别只在有没有人确认。

5 者的协同场景

典型 Headless 协同：GitHub Actions 触发 → Claude Headless 跑任务 → 用 Tools 读 PR diff → 用 SubAgent(code-reviewer）做代码审查 → 用 Hook 拦危险命令 / 记录审计 → 用 MCP(GitHub）把审查结果写回 PR 评论 → 退出。

5 种机制在 Headless 下原班人马工作、只是人不在回路。机器自治 = 5 机制 + 安全边界 + fallback + 日志。

🛠️ 实战代码

📄 第 21 讲配套：Headless 模式命令完整示例（claude -p 跑任务 / stdin 输入 / 输出到 stdout)

复制代码

#!/usr/bin/env bash
# Headless 模式命令完整示例

# === 模式 1:单次任务模式 ===
# 跑 PR Review,完成后退出
claude -p "review this PR and list issues" \
  --allowedTools "Read,Grep,Glob,Bash(git:diff),Bash(git:log)" \
  --output-format json

# === 模式 2:stdin 模式(管道) ===
# 把 git diff 通过 stdin 给 Claude
git diff main..HEAD | claude -p "总结这次改动的关键变更" \
  --output-format text

# === 模式 3:链式管道 ===
# 先 git diff,再 claude 总结,再写到 CHANGELOG
git diff main..HEAD \
  | claude -p "提取这次改动的关键功能,生成 changelog 条目" \
  | tee -a CHANGELOG.md

# === 模式 4:输出到文件 ===
claude -p "生成这次 PR 的审查报告" \
  --output-format json \
  > /tmp/claude-review.json 2> /tmp/claude-error.log

# === 模式 5:JSON 输出便于解析 ===
RESULT=$(claude -p "review this PR" --output-format json)
ISSUE_COUNT=$(echo "$RESULT" | jq '.issues | length')
echo "Claude found $ISSUE_COUNT issues"

# === 模式 6:--allowedTools 权限收窄 ===
# 只允许 Read / Grep / Glob + git 命令,其他都禁止
claude -p "review this PR" \
  --allowedTools "Read,Grep,Glob,Bash(git:*)" \
  --output-format json

# 严禁命令:
# - 不允许 Edit / Write(只读,不修改文件)
# - 不允许 Bash(rm|curl|sh)(危险命令)
# - 不允许 Bash(dd|chmod)(底层操作)

📄 第 21 讲配套：GitHub Actions workflow 完整配置（自动 PR Review 触发 + Claude Code action + 评论写回）

复制代码

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  # PR 打开 / 同步时触发
  pull_request:
    types: [opened, synchronize, reopened]
  # 也支持 push 到 main
  push:
    branches: [main, develop]

# 最小权限:只读 + 评论写回
permissions:
  contents: read       # 读代码
  pull-requests: write # 写 PR 评论

jobs:
  claude-review:
    runs-on: ubuntu-latest
    timeout-minutes: 10  # 10 分钟超时
    steps:
      # 1. 检出代码
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 完整历史(便于 git diff)

      # 2. 配置 .claude 目录(HW / Skills / SubAgent 配置)
      - name: Setup .claude
        run: |
          mkdir -p .claude/hooks
          # 把团队沉淀的 HW 复制到 .claude/hooks
          cp .github/claude-config/hooks/*.sh .claude/hooks/
          chmod +x .claude/hooks/*.sh

      # 3. 跑 Claude Code 审查
      - name: Claude Review
        id: review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 跑 PR Review(Headless 模式)
          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

      # 4. 把审查结果写回 PR 评论
      - 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
            });

# === 关键配置解释 ===
# on.pull_request: PR 打开 / 同步时触发
# permissions: 最小权限(只读 + 评论写回)
# allowedTools: 只允许 Read / Grep / Glob / git 命令(权限收窄)
# secrets.ANTHROPIC_API_KEY: 从 GitHub Secrets 读 API key(不进代码)
# timeout-minutes: 10 分钟超时(避免挂死)

📄 第 21 讲配套：自动修复 + 自动 commit 完整流程（审查 → 修复 → commit → push)

复制代码

# .github/workflows/claude-auto-fix.yml
name: Claude Auto-Fix

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: write  # 需要 write 权限(自动 commit)
  pull-requests: write

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup .claude
        run: |
          mkdir -p .claude/hooks
          cp .github/claude-config/hooks/*.sh .claude/hooks/
          chmod +x .claude/hooks/*.sh

      # 1. Claude 审查 + 自动修复
      - name: Claude Review and Fix
        id: fix
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Claude 跑审查 + 标记可自动修复的问题 + 自动 Edit
          FIX_RESULT=$(claude -p "review this PR, find auto-fixable issues (format / timeout / simple bugs) and fix them with Edit tool" \
            --allowedTools "Read,Grep,Glob,Edit,Write,Bash(git:*),Bash(rff:format),Bash(ruff:check)" \
            --output-format json)
          echo "fix_result=$FIX_RESULT" >> $GITHUB_OUTPUT

      # 2. 自动 commit(只在有改动时)
      - name: Commit Auto-Fix
        run: |
          if ! git diff --quiet; then
            git config user.name "Claude Auto-Fix"
            git config user.email "claude@anthropic.com"
            git add .
            git commit -m "fix: auto-fix by Claude Code Review

            - 格式问题(ruff format)
            - 简单 bug(缺 timeout / 缺错误处理)
            - 缺测试覆盖

            Reviewed-by: Claude Code"
            git push
          else
            echo "No changes to commit"
          fi

      # 3. 写 PR 评论说明自动修复了什么
      - name: Post Fix Comment
        uses: actions/github-script@v7
        with:
          script: |
            const result = `${{ steps.fix.outputs.fix_result }}`;
            const body = `## Claude Auto-Fix\n\n${result}`;
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: body
            });

# === 安全约束 ===
# 1. allowedTools 收窄(只允许 git / ruff / Edit,不开放 rm / curl)
# 2. HW 拦截(deny-pipe-exec + deny-extra-dangerous)
# 3. 沙箱(Docker 跑 Claude,容器隔离)
# 4. 只自动修复低风险 / 明确的问题(格式 / 简单 bug)
# 5. 复杂 bug 仅标记不修复(让人判断)

📄 第 21 讲配套：机器自治权限收窄 5 维配置（HW / token / sandbox / fallback / 日志）

复制代码

# 机器自治权限收窄 5 维配置

## 维度 1:HW 白名单命令(PreToolUse 拦危险)
HW 配置:
  PreToolUse matcher: "Bash"
  行为: 只允许白名单命令
  白名单: git:*, pytest:*, ruff:*, npm run test, make test
  黑名单(拒绝): rm -rf, curl | sh, dd, chmod 777, git push --force

```bash
# .claude/hooks/ci-allowlist.sh
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

维度 2:CI token 权限收窄(env 限制)

GitHub Actions permissions:

contents: read # 只读代码

pull-requests: write # 评论写回(可选)

绝不用 admin / write 全部权限

GitHub Secrets:

ANTHROPIC_API_KEY: 单独管理(不进代码)

GITHUB_TOKEN: 自动提供,scope 收窄

维度 3:Sandbox 沙箱(不让 Claude 改生产)

Docker 跑 Claude:

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y curl git python3

RUN curl -fsSL https://claude.ai/install.sh | sh

WORKDIR /workspace

容器和主机隔离,即使 Claude 跑了 rm -rf,只删容器内

维度 4:失败 fallback(回退人工)

workflow 配置:

steps:

name: Claude Review

continue-on-error: true # Claude 失败不阻塞 CI

name: Notify Failure

if: failure()

run: |

Claude 失败时,标记 PR "需要人工 review"

gh pr edit $PR_NUMBER --add-label "needs-human-review"

gh pr comment $PR_NUMBER --body "⚠️ Claude Review 失败,请人工 review"

维度 5:日志完整记录

GitHub Actions 自动记录:

workflow 触发时间 / 触发人
Claude 跑的任务
Claude stdout / stderr 输出
HW 拦截记录(PreToolUse / PostToolUse / Stop)
Claude 最终审查结果
exit code / 耗时

=== 5 维配置检查清单 ===

1. HW 白名单命令配了吗? (没配 = 补)

2. CI token 权限收窄了吗? (用 admin = 改)

3. Claude 在沙箱跑吗? (主机直跑 = 改)

4. Claude 失败有 fallback 吗? (没 fallback = 补)

5. 日志完整记录吗? (只记成功 = 改)

复制代码

## ⚠️ 常见坑

> **⚠️ Headless 模式没配 HW 拦截（机器自治的 Claude 没拦截、跑出 rm -rf)**
> Headless = 放任的致命错误：以为 Headless 模式 Claude 自动跑、不用配 HW。结果 Claude 推理中跑了 `rm -rf node_modules/` 试图重装依赖、把整个项目删了。修正：Headless 模式下 HW 必须配（更严、白名单命令）,PreToolUse 拦截所有非白名单命令。判断标准：你的 Headless workflow 有 PreToolUse HW 吗?没有、补 HW。
> **⚠️ CI token 权限过大（用 admin token 让 Claude 改生产、改用 repo scope + read-only)**
> admin token 自杀陷阱：GitHub Actions 用 admin token(`permissions: write-all`),Claude 用这个 token 能改生产环境（force-push main / 改 workflow / 删 repo）。修正：token scope 收窄------`permissions: contents: read` + `pull-requests: write`。Claude 只读代码 + 写 PR 评论、不能改生产。判断标准：你的 CI token scope 收窄到最小吗?没用 admin token 吧?用了、改 scope。
> **⚠️ Claude 失败没 fallback（网络超时 / API 报错 / 任务失败、CI 直接挂、没回退人工）**
> Claude 挂 = CI 挂陷阱：Claude 跑失败（网络超时 / Anthropic API 报错 / 任务复杂超时）,workflow 直接 fail,PR 阻塞无法 merge。修正：加 fallback------`continue-on-error: true`(Claude 失败不阻塞 CI)+ 失败时给 PR 加 label "needs-human-review" + 写评论⚠️ Claude Review 失败、请人工 review。CI 不会因为 Claude 故障而停摆。判断标准：你的 CI 失败时会回退人工 review 吗?不会、补 fallback。
> **⚠️ 日志不完整（只记成功不记失败、出事后无法审计、完整记录 stdout / stderr / 决策点）**
> 日志残缺陷阱：CI 跑 Claude 只记成功任务的输出、失败任务 / HW 拦截 / Claude 推理过程不记。出事后想看"Claude 那天跑了什么 / HW 拦了什么 / Claude 怎么推理"------找不到。修正：完整日志------任务输入 / Claude stdout / Claude stderr / HW 拦截记录（PreToolUse / PostToolUse / Stop)/ 决策点（Claude 为什么选这个工具）/ exit code / 耗时。GitHub Actions 自动记录、但要确保这些字段都打。判断标准：你能从 CI 日志回溯"Claude 那次 PR Review 的完整推理过程"吗?不能、补日志。

## 💡 一句话备忘

> Headless 模式让 Claude Code 从 IDE 工具变成 CI 工具------`claude -p` 跑非交互任务、GitHub Actions 自动 PR Review + 自动修复、5 维权限收窄（HW 白名单 / token 收窄 / 沙箱 / fallback / 日志）保障机器自治的安全边界。

《Claude Code 工程化实战》第 21 讲 Headless 模式与 CI/CD 集成

📖 详细内容

Headless 模式基础：claude -p 非交互模式

GitHub Actions 集成：自动 PR Review

自动修复与自动 commit

权限收窄：机器自治的安全边界

机器自治的工程实践 5 条

Headless vs 交互式 + 与其他扩展机制协同

🛠️ 实战代码

维度 2:CI token 权限收窄(env 限制)

绝不用 admin / write 全部权限

维度 3:Sandbox 沙箱(不让 Claude 改生产)

容器和主机隔离,即使 Claude 跑了 rm -rf,只删容器内

维度 4:失败 fallback(回退人工)

Claude 失败时,标记 PR "需要人工 review"

维度 5:日志完整记录

=== 5 维配置检查清单 ===

1. HW 白名单命令配了吗? (没配 = 补)

2. CI token 权限收窄了吗? (用 admin = 改)

3. Claude 在沙箱跑吗? (主机直跑 = 改)

4. Claude 失败有 fallback 吗? (没 fallback = 补)

5. 日志完整记录吗? (只记成功 = 改)

Headless 模式基础：`claude -p` 非交互模式