-p 是非交互模式的钥匙——它让 Claude Code 从交互式 REPL 变成 可以嵌入脚本、管道、CI 任务的命令行工具。

核心标志一览

基础用法

# 最简单的 headless 调用
$ claude -p "用一句话解释什么是 React Server Components"

# 管道输入：把文件内容传给 Claude
$ cat src/auth.ts | claude -p "找出这段代码中的安全漏洞"

# 管道输出：把 Claude 的回答写入文件
$ claude -p "为 src/utils.ts 中所有导出函数生成 JSDoc" > docs.md

# 结构化输出：JSON 格式便于程序消费
$ claude -p "列出项目中所有 TODO 注释" --output-format json \
    | jq '.result'

输出格式对比

无人值守 ≠ 无限制。Headless 模式有严格的权限控制—— 你必须显式声明 Claude 可以使用哪些工具、可以执行哪些命令。

--allowedTools 工具白名单

在 -p 模式下，Claude 默认只能读取文件。 通过 --allowedTools 显式授权更多能力：

# 只允许读取和编辑文件
$ claude -p "修复 auth.ts 中的 bug" \
    --allowedTools "Read,Edit"

# 允许执行特定命令（前缀匹配）
$ claude -p "运行测试并修复失败用例" \
    --allowedTools "Read,Edit,Bash(npm test *),Bash(npx tsc *)"

# 允许 git 操作
$ claude -p "提交所有变更" \
    --allowedTools "Bash(git diff *),Bash(git add *),Bash(git commit *)"

权限模式

安全清单

Anthropic 官方提供的 claude-code-action 可以在 GitHub Actions 中 直接调用 Claude Code——自动审查 PR、修复问题、生成文档。

GitHub Actions 工作流

实战：PR 自动审查

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

on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  review:
    runs-on: ubuntu-latest
    # 仅在 PR 评论中 @claude 被提及时触发
    if: |
      github.event_name == 'pull_request' ||
      contains(github.event.comment.body, '@claude')
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            审查这个 PR 的代码变更：
            1. 检查是否有安全漏洞
            2. 检查是否有性能问题
            3. 检查代码风格是否符合项目规范
            4. 给出改进建议
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"

CI 用例速览

Headless 模式的真正威力在于组合——用 Unix 管道把多个 Claude 调用串联成完整的自动化流水线。

会话管理：多步工作流

# Step 1 — 启动分析，捕获 session_id
$ session_id=$(claude -p "分析 src/api/ 目录的架构" \
    --output-format json | jq -r '.session_id')

# Step 2 — 基于上一步的上下文继续
$ claude -p "基于刚才的分析，找出最需要重构的三个文件" \
    --resume "$session_id"

# 或者直接继续最近的会话
$ claude -p "继续，开始重构第一个文件" --continue

管道组合模式

# 完整示例：AI 生成 commit message
$ git diff --staged | claude -p \
    "根据这个 diff 生成简洁的 commit message，只输出消息文本" \
    --bare | git commit -F -

# 批量代码审查：扫描所有变更文件
$ git diff --name-only HEAD~5 | while read f; do
    echo "=== $f ==="
    claude -p "审查这个文件中最近的变更，发现潜在问题" \
        --allowedTools "Read,Bash(git diff *)" --bare
  done > review-report.md

# 结构化输出 + jq 提取
$ claude -p "列出所有 API 端点" \
    --output-format json \
    --json-schema '{"type":"object","properties":{"endpoints":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}}}}}' \
    | jq '.result.structured_output.endpoints[]'

当 Shell 管道不够用时——用 Agent SDK 在 TypeScript 或 Python 中嵌入 Claude Code， 构建完全定制的自动化系统。

TypeScript SDK

import { query } from "@anthropic-ai/claude-code";

// 基础调用：流式获取结果
for await (const message of query({
  prompt: "找出 src/api/ 中所有未处理的异常",
  options: {
    allowedTools: ["Read", "Bash"],
    permissionMode: "dontAsk",
    maxTurns: 10,
  }
})) {
  if ("result" in message) {
    console.log(message.result);  // 最终结果
  }
}

Python SDK

from claude_code import query, ClaudeCodeOptions

# 异步流式调用
async for message in query(
    prompt="分析 tests/ 目录的覆盖率盲区",
    options=ClaudeCodeOptions(
        allowed_tools=["Read", "Bash(npm test *)"],
        permission_mode="dontAsk",
        max_turns=10,
    )
):
    if hasattr(message, "result"):
        print(message.result)

SDK vs CLI 对比

1. -p 标志的作用是什么？它和交互模式在权限上有什么核心区别？
2. --bare 标志在 CI 中为什么是推荐的？它跳过了哪些自动发现过程？
3. --allowedTools 的前缀匹配语法如何工作？给出一个只允许 git 和 npm 命令的示例。
4. 在 GitHub Actions 中使用 claude-code-action 时，API Key 应该存储在哪里？为什么？
5. Agent SDK 的 query() 函数返回的是什么类型？如何获取最终结果？