跳轉到主要內容

​
概述

無頭模式允許您從命令列腳本和自動化工具以程式方式執行 Claude Code，無需任何互動式 UI。

​
基本用法

Claude Code 的主要命令列介面是 claude 命令。使用 --print（或 -p）旗標以非互動模式執行並列印最終結果： 
claude -p "Stage my changes and write a set of commits for them" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

​
配置選項

無頭模式利用 Claude Code 中所有可用的 CLI 選項。以下是用於自動化和腳本編寫的關鍵選項：
旗標描述範例
--print, -p以非互動模式執行claude -p "query"
--output-format指定輸出格式（text、json、stream-json）claude -p --output-format json
--resume, -r按工作階段 ID 繼續對話claude --resume abc123
--continue, -c繼續最近的對話claude --continue
--verbose啟用詳細日誌記錄claude --verbose
--append-system-prompt附加到系統提示（僅限 --print）claude --append-system-prompt "Custom instruction"
--allowedTools以空格分隔的允許工具清單，或

以逗號分隔的允許工具清單字串		claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedTools以空格分隔的拒絕工具清單，或

以逗號分隔的拒絕工具清單字串		claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-config從 JSON 檔案載入 MCP 伺服器claude --mcp-config servers.json
--permission-prompt-tool用於處理權限提示的 MCP 工具（僅限 --print）claude --permission-prompt-tool mcp__auth__prompt
如需完整的 CLI 選項和功能清單，請參閱 CLI 參考 文件。

​
多輪對話

對於多輪對話，您可以繼續對話或從最近的工作階段繼續： 
# 繼續最近的對話
claude --continue "Now refactor this for better performance"

# 按工作階段 ID 繼續特定對話
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"

# 以非互動模式繼續
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix all linting issues" --no-interactive

​
輸出格式

​
文字輸出（預設）

claude -p "Explain file src/components/Header.tsx"
# Output: This is a React component showing...

​
JSON 輸出

傳回包含中繼資料的結構化資料： 
claude -p "How does the data layer work?" --output-format json
回應格式： 
{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

​
串流 JSON 輸出

在接收到每條訊息時進行串流處理： 
claude -p "Build an application" --output-format stream-json
每個對話以初始 init 系統訊息開始，後面跟著使用者和助手訊息清單，最後是包含統計資訊的最終 result 系統訊息。每條訊息都作為單獨的 JSON 物件發出。

​
輸入格式

​
文字輸入（預設）

# 直接引數
claude -p "Explain this code"

# 從 stdin
echo "Explain this code" | claude -p

​
串流 JSON 輸入

透過 stdin 提供的訊息串流，其中每條訊息代表使用者的一個回合。這允許在不重新啟動 claude 二進位檔案的情況下進行多個對話回合，並允許在模型處理請求時為其提供指導。 每條訊息都是一個 JSON「使用者訊息」物件，遵循與輸出訊息架構相同的格式。訊息使用 jsonl 格式進行格式化，其中輸入的每一行都是完整的 JSON 物件。串流 JSON 輸入需要 -p 和 --output-format stream-json。 
echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

​
代理整合範例

​
SRE 事件回應機器人

#!/bin/bash

# 自動化事件回應代理
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "Incident: $incident_description (Severity: $severity)" \
      --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# 用法
investigate_incident "Payment API returning 500 errors" "high"

​
自動化安全審查

# 拉取請求的安全稽核代理
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# 用法並儲存到檔案
audit_pr 123 > security-report.json

​
多輪法律助手

# 具有工作階段持久性的法律文件審查
session_id=$(claude -p "Start legal review session" --output-format json | jq -r '.session_id')

# 分多個步驟審查合約
claude -p --resume "$session_id" "Review contract.pdf for liability clauses"
claude -p --resume "$session_id" "Check compliance with GDPR requirements"
claude -p --resume "$session_id" "Generate executive summary of risks"

​
最佳實踐

  • 使用 JSON 輸出格式進行程式化回應解析： 
    # 使用 jq 解析 JSON 回應
result=$(claude -p "Generate code" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')
  • 妥善處理錯誤 - 檢查結束代碼和 stderr： 
    if ! claude -p "$prompt" 2>error.log; then
    echo "Error occurred:" >&2
    cat error.log >&2
    exit 1
fi
  • 使用工作階段管理以在多輪對話中維持上下文
  • 考慮長時間執行操作的逾時： 
    timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
  • 在進行多個請求時尊重速率限制，透過在呼叫之間新增延遲

​
相關資源