编程式调用（headless 模式）

Claude Code 可以通过 -p 标志在非交互模式下运行，适合脚本、CI/CD 和自动化流程。Agent SDK 还提供了 Python 和 TypeScript 包，支持结构化输出、工具批准回调和原生消息对象。

基本用法

在任意 claude 命令中加入 -p（或 --print）标志即可非交互运行：

claude -p "查找并修复 auth.py 中的 Bug" --allowedTools "Read,Edit,Bash"

所有 CLI 选项 都支持 -p，包括：

• --continue（继续对话）
• --allowedTools（自动批准工具）
• --output-format（控制输出格式）

bare 模式（更快启动）

加入 --bare 可以跳过 Hooks、Skills、插件、MCP 服务器、自动记忆和 CLAUDE.md 的自动发现，大幅缩短启动时间：

claude --bare -p "总结这个文件" --allowedTools "Read"

--bare 适用场景：

• CI/CD 流程（需要在每台机器上得到相同结果）
• 不想受本机配置影响的脚本

bare 模式下 Claude 有 Bash、文件读取和文件编辑工具。如需加载额外上下文：

需要加载的内容	使用方式
系统提示补充	--append-system-prompt 或 --append-system-prompt-file
设置	--settings <file-or-json>
MCP 服务器	--mcp-config <file-or-json>
自定义代理	--agents <json>

bare 模式跳过 OAuth 和密钥链读取，认证必须来自 ANTHROPIC_API_KEY 或 --settings 中的 apiKeyHelper。

注意：--bare 是脚本和 SDK 调用的推荐模式，未来版本中将成为 -p 的默认行为。

输出格式

纯文本（默认）

claude -p "这个认证模块是做什么的？"

JSON 格式（含元数据）

claude -p "总结这个项目" --output-format json

输出示例：

{
  "result": "这个项目是一个...",
  "session_id": "sess_abc123",
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 567
  }
}

使用 jq 提取结果：

claude -p "总结这个项目" --output-format json | jq -r '.result'

结构化 JSON 输出

使用 --json-schema 获取符合特定 Schema 的输出：

claude -p "提取 auth.py 中的主要函数名" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

结构化输出在响应的 structured_output 字段中：

claude -p "提取函数名" \
  --output-format json \
  --json-schema '...' \
  | jq '.structured_output'

流式 JSON 输出（实时处理）

claude -p "解释递归" --output-format stream-json --verbose --include-partial-messages

每行一个 JSON 对象，实时输出。用 jq 过滤文本 delta：

claude -p "写一首诗" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

预批准工具

使用 --allowedTools 让 Claude 无需提示使用特定工具：

claude -p "运行测试套件并修复所有失败" \
  --allowedTools "Bash,Read,Edit"

支持精细的命令级权限（权限规则语法）：

# 只允许 git 子命令
claude -p "查看暂存变更并创建一个适当的提交" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Bash(git diff *) 末尾的空格+* 很重要：允许所有以 git diff 开头的命令。没有空格会导致 git diff* 匹配 git diff-index 等非预期命令。

继续对话

# 第一次请求
claude -p "审查代码库的性能问题"

# 继续最近的对话
claude -p "现在专注于数据库查询" --continue
claude -p "生成所有发现的摘要" --continue

运行多个会话时，捕获 session_id 以便恢复特定会话：

session_id=$(claude -p "开始审查" --output-format json | jq -r '.session_id')
claude -p "继续那个审查" --resume "$session_id"

实用示例

分析日志文件

tail -200 app.log | claude -p "如果有异常请告诉我根本原因"

代码审查（管道输入）

gh pr diff "$1" | claude -p \
  --append-system-prompt "你是安全工程师，审查是否有漏洞。" \
  --output-format json

多步骤流水线

#!/bin/bash
# 分析 + 修复 + 验证

# 1. 分析
claude --bare -p "分析认证系统中的安全问题" \
  --permission-mode plan \
  --max-turns 5 \
  --tools "Read,Glob,Grep" \
  --output-format json > analysis.json

# 2. 修复
session_id=$(jq -r '.session_id' analysis.json)
claude --bare -p "实现修复方案" \
  --resume "$session_id" \
  --allowedTools "Read,Edit,Bash"

# 3. 验证
claude --bare -p "运行测试验证修复" \
  --allowedTools "Bash(npm test)"

CI/CD 集成

在 package.json 中：

{
  "scripts": {
    "lint:claude": "claude --bare -p '检查 main 的变更，报告问题' --output-format text",
    "review:security": "claude --bare -p '审查安全问题' --output-format json"
  }
}

GitHub Actions 中使用

- name: 代码安全检查
  run: |
    claude --bare -p "检查这个 PR 是否有安全漏洞" \
      --allowedTools "Read,Glob,Grep" \
      --output-format json | jq '.result'
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

流式 API 重试事件

API 请求失败时，Claude Code 会发出 system/api_retry 事件：

字段	说明
type	"system"
subtype	"api_retry"
attempt	当前尝试次数（从 1 开始）
max_retries	总重试次数
retry_delay_ms	下次尝试前等待毫秒数
error_status	HTTP 状态码（连接错误为 null）
error	错误类别（authentication_failed、rate_limit、server_error 等）

Python / TypeScript SDK

对于需要结构化输出、工具批准回调和原生消息对象的场景，请使用 Agent SDK 包：

• Python SDK：文档
• TypeScript SDK：文档

# Python
pip install claude-agent-sdk

# TypeScript / Node.js
npm install @anthropic-ai/agent-sdk

相关资源

• Agent SDK 文档：Python/TypeScript 完整 SDK
• CLI 参考：所有命令行标志
• GitHub Actions：在 GitHub 工作流中使用
• GitLab CI/CD：在 GitLab 流水线中使用
• 权限配置：工具权限语法