name: claude-code-headless description: “以无交互界面的方式编程运行Claude Code。触发条件：headless、CLI自动化、–print、output-format、stream-json、CI/CD、脚本编写。” compatibility: “Claude Code CLI” allowed-tools: “Bash Read” depends-on: [] related-skills: [claude-code-hooks, claude-code-debug]

Claude Code 无头模式

从脚本中运行Claude Code，无需交互界面。

快速开始

# 基础无头执行
claude -p "解释这段代码" --allowedTools "Read,Grep"

# JSON输出用于解析
claude -p "列出文件" --output-format json

# 继续对话
claude -p "开始分析" --output-format json > result.json
session=$(jq -r '.session_id' result.json)
claude --resume "$session" "现在修复问题"

核心CLI选项

标志	描述
`-p`, `--print`	非交互（无头）模式
`--output-format`	text、json、stream-json
`-r`, `--resume`	通过会话ID恢复
`-c`, `--continue`	继续最近会话
`--allowedTools`	逗号分隔的允许工具
`--disallowedTools`	逗号分隔的禁止工具
`--mcp-config`	MCP服务器配置JSON路径
`--verbose`	启用详细日志
`--append-system-prompt`	添加到系统提示词

权限模式

模式	标志	效果
默认	(无)	请求权限
接受编辑	`--permission-mode acceptEdits`	自动接受文件更改
绕过	`--permission-mode bypassPermissions`	跳过所有提示

输出格式

文本（默认）

claude -p "你好"
# 输出：人类可读的响应

JSON

claude -p "你好" --output-format json

{
  "type": "result",
  "subtype": "success",
  "result": "你好！我能帮你什么？",
  "session_id": "abc123",
  "total_cost_usd": 0.001,
  "duration_ms": 1234,
  "num_turns": 1
}

Stream-JSON

claude -p "你好" --output-format stream-json
# 实时JSONL输出每条消息

常见模式

带工具限制的脚本

claude -p "分析代码库" \
  --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Write,Edit,Bash"

CI/CD集成

claude -p "审查此PR差异" \
  --permission-mode acceptEdits \
  --output-format json \
  --append-system-prompt "关注安全问题"

多轮自动化

session=$(claude -p "开始任务" --output-format json | jq -r '.session_id')
claude --resume "$session" "继续第二步"
claude --resume "$session" "最终完成并报告"

错误处理

result=$(claude -p "任务" --output-format json)
if [[ $(echo "$result" | jq -r '.is_error') == "true" ]]; then
    echo "错误: $(echo "$result" | jq -r '.result')" >&2
    exit 1
fi

官方文档

https://code.claude.com/docs/en/headless - 无头模式参考
https://code.claude.com/docs/en/settings - 设置和权限

附加资源

./references/cli-options.md - 完整CLI标志参考
./references/output-formats.md - 输出格式模式
./references/integration-patterns.md - CI/CD和脚本示例

另请参阅： claude-code-hooks 用于自动化事件，claude-code-debug 用于故障排除