claude-code-headless

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Headless Mode

Claude Code 无头模式

Run Claude Code from scripts without interactive UI.

无需交互式UI，通过脚本运行Claude Code。

Quick Start

快速开始

bash

undefined

bash

undefined

Basic headless execution

基础无头模式执行

claude -p "Explain this code" --allowedTools "Read,Grep"

JSON output for parsing

用于解析的JSON输出

claude -p "List files" --output-format json

Continue conversation

继续对话

claude -p "Start analysis" --output-format json > result.json session=$(jq -r '.session_id' result.json) claude --resume "$session" "Now fix the issues"

undefined

claude -p "Start analysis" --output-format json > result.json session=$(jq -r '.session_id' result.json) claude --resume "$session" "Now fix the issues"

undefined

Essential CLI Options

核心CLI选项

Flag	Description
`-p` , `--print`	Non-interactive (headless) mode
`--output-format`	text, json, stream-json
`-r` , `--resume`	Resume by session ID
`-c` , `--continue`	Continue most recent session
`--allowedTools`	Comma-separated allowed tools
`--disallowedTools`	Comma-separated denied tools
`--mcp-config`	Path to MCP server config JSON
`--verbose`	Enable verbose logging
`--append-system-prompt`	Add to system prompt

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

Permission Modes

权限模式

Mode	Flag	Effect
Default	(none)	Prompt for permissions
Accept edits	`--permission-mode acceptEdits`	Auto-accept file changes
Bypass	`--permission-mode bypassPermissions`	Skip all prompts

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

Output Formats

输出格式

Text (default)

文本（默认）

bash

claude -p "Hello"

bash

claude -p "Hello"

Outputs: Human-readable response

输出：人类可读的响应内容

undefined

undefined

JSON

bash

claude -p "Hello" --output-format json

json

{
  "type": "result",
  "subtype": "success",
  "result": "Hello! How can I help?",
  "session_id": "abc123",
  "total_cost_usd": 0.001,
  "duration_ms": 1234,
  "num_turns": 1
}

bash

claude -p "Hello" --output-format json

json

{
  "type": "result",
  "subtype": "success",
  "result": "Hello! How can I help?",
  "session_id": "abc123",
  "total_cost_usd": 0.001,
  "duration_ms": 1234,
  "num_turns": 1
}

Stream-JSON

bash

claude -p "Hello" --output-format stream-json

bash

claude -p "Hello" --output-format stream-json

Real-time JSONL output for each message

每条消息的实时JSONL输出

undefined

undefined

Common Patterns

常见使用模式

Script with tool restrictions

限制工具的脚本

bash

claude -p "Analyze the codebase" \
  --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Write,Edit,Bash"

bash

claude -p "Analyze the codebase" \
  --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Write,Edit,Bash"

CI/CD integration

CI/CD集成

bash

claude -p "Review this PR diff" \
  --permission-mode acceptEdits \
  --output-format json \
  --append-system-prompt "Focus on security issues"

bash

claude -p "Review this PR diff" \
  --permission-mode acceptEdits \
  --output-format json \
  --append-system-prompt "Focus on security issues"

Multi-turn automation

多轮对话自动化

bash

session=$(claude -p "Start task" --output-format json | jq -r '.session_id')
claude --resume "$session" "Continue with step 2"
claude --resume "$session" "Finalize and report"

bash

session=$(claude -p "Start task" --output-format json | jq -r '.session_id')
claude --resume "$session" "Continue with step 2"
claude --resume "$session" "Finalize and report"

Error Handling

错误处理

bash

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

bash

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

Official Documentation

官方文档

https://code.claude.com/docs/en/headless - Headless mode reference
https://code.claude.com/docs/en/settings - Settings and permissions

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

Additional Resources

额外资源

```
./references/cli-options.md
```
- Complete CLI flag reference
```
./references/output-formats.md
```
- Output format schemas
```
./references/integration-patterns.md
```
- CI/CD and scripting examples

See Also:

claude-code-hooks

for automation events,

claude-code-debug

for troubleshooting

```
./references/cli-options.md
```
- 完整CLI标识参考
```
./references/output-formats.md
```
- 输出格式架构
```
./references/integration-patterns.md
```
- CI/CD与脚本示例

另请参阅：

claude-code-hooks

用于自动化事件，

claude-code-debug

用于故障排查