Back to Details

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"
claude -p "Explain this code" --allowedTools "Read,Grep"

JSON output for parsing

用于解析的JSON输出

claude -p "List files" --output-format 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选项

FlagDescription
-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

权限模式

ModeFlagEffect
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

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

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

官方文档

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
用于故障排查