Claude Code 不仅是交互式 CLI，还支持「无头模式」（Headless Mode）——通过 -p 参数以编程方式运行，适合脚本自动化、CI/CD 流水线和批量任务。
什么是无头模式？
无头模式通过 -p（--print）参数运行，Claude Code 执行任务后直接输出结果，不需要用户交互：
bash
claude -p "查找 auth.py 中的 Bug 并修复" --allowedTools "Read,Edit,Bash"背后的 Agent SDK 提供与 Claude Code 相同的工具、Agent 循环和上下文管理，也可作为 Python 和 TypeScript 包使用。
基础用法
bash
# 问一个关于代码库的问题，直接输出答案
claude -p "auth 模块做了什么？"
# 带工具权限
claude -p "运行测试套件并修复失败" --allowedTools "Bash,Read,Edit"
# 查看项目结构
claude -p "列出这个项目的主要组件" --allowedTools "Read,Bash"获取结构化输出
JSON 输出
bash
claude -p "总结这个项目" --output-format json响应格式：
json
{
"result": "项目摘要文本...",
"session_id": "sess_xxx",
"usage": { "input_tokens": 1234, "output_tokens": 567 }
}按指定 Schema 结构化输出
bash
claude -p "提取 auth.py 中的主要函数名" \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'结果在响应的 structured_output 字段中。
流式输出（实时 Token 流）
bash
claude -p "解释递归" \
--output-format stream-json \
--verbose \
--include-partial-messages配合 jq 实时显示文本：
bash
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'精细控制工具权限
bash
# 只允许特定 Git 操作
claude -p "查看暂存区变更并创建合适的提交" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"Bash(git diff *) 的末尾 * 启用前缀匹配，允许所有以 git diff 开头的命令。注意 * 前有空格——Bash(git diff*) 不加空格会匹配 git diff-index 等不相关命令。
自定义系统提示
bash
# 将 PR diff 管道给 Claude 做安全审查
gh pr diff "$1" | claude -p \
--append-system-prompt "你是安全工程师，专注于检查漏洞。" \
--output-format json--append-system-prompt：在默认系统提示后追加（保留 Claude Code 的编码能力）
--system-prompt：完全替换默认系统提示
多轮对话（继续会话）
继续最近的对话
bash
# 第一轮
claude -p "审查这个代码库的性能问题"
# 继续最近的对话
claude -p "现在聚焦在数据库查询上" --continue
claude -p "生成所有问题的总结报告" --continue通过 Session ID 恢复特定对话
bash
# 保存 Session ID
session_id=$(claude -p "开始审查" --output-format json | jq -r '.session_id')
# 恢复特定对话
claude -p "继续那次审查" --resume "$session_id"CI/CD 实战场景
GitHub Actions：PR 安全审查
yaml
jobs:
security-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 安全审查
run: |
gh pr diff ${{ github.event.number }} | claude -p \
--append-system-prompt "你是安全工程师，专注检查漏洞。" \
--output-format json > review.json自动修复 Lint 错误
bash
#!/bin/bash
claude -p "运行 ruff 检查，修复所有 lint 错误，然后提交" \
--allowedTools "Bash,Read,Edit" \
--continue批量处理多个文件
bash
for file in src/**/*.py; do
claude -p "为 $file 添加类型注解" \
--allowedTools "Read,Edit" \
--output-format json
done输出格式对比
| 格式 | 说明 | 适用场景 |
|---|---|---|
text（默认） | 纯文本 | 简单脚本、终端显示 |
json | 结构化 JSON（含 session_id、usage） | CI/CD、需要元数据 |
stream-json | 换行分隔的实时 JSON | 流式处理、实时监控 |
Agent SDK（Python/TypeScript）
对于需要结构化输出、工具审批回调和原生消息对象的场景，使用 Agent SDK 包：
python
# Python Agent SDK
from anthropic.agents import AgentSDK
sdk = AgentSDK()
result = sdk.run(
prompt="分析代码库并生成报告",
allowed_tools=["Read", "Bash"],
output_format="json"
)详细文档见：Agent SDK 文档
原文：Run Claude Code programmatically | 来源：Anthropic 官方文档