-p 和您的提示以及任何 CLI 選項:
claude -p) 使用 Agent SDK。如需具有結構化輸出、工具核准回呼和原生訊息物件的 Python 和 TypeScript SDK 套件,請參閱 完整 Agent SDK 文件。
基本用法
在任何claude 命令中加上 -p(或 --print)旗標以非互動方式執行。並非每個 CLI 選項 都能與 -p 結合。Claude Code 拒絕 --bg,並在有任務描述時拒絕 --cloud,並會出現命名衝突的錯誤;--cloud 與工作階段 ID 和 -p 一起使用時,會 將訊息加入該雲端工作階段 並退出。您經常會與 -p 結合的選項包括:
此範例詢問 Claude 關於您的程式碼庫的問題並列印回應:
使用裸機模式更快啟動
加上--bare 以跳過 hooks、skills、自訂命令、subagents、已安裝的 plugins、MCP 伺服器、自動記憶和 CLAUDE.md 的自動探索來減少啟動時間。沒有它,claude -p 會載入互動工作階段會載入的相同 context,包括在工作目錄或 ~/.claude 中設定的任何內容。
裸機模式對於 CI 和指令碼很有用,您需要在每台機器上獲得相同的結果。隊友 ~/.claude 中的 hook 或專案 .mcp.json 中的 MCP 伺服器不會執行,因為裸機模式永遠不會讀取它們。您使用 --add-dir 命名的目錄是部分例外:裸機模式從其 .claude/skills/ 資料夾載入 skills,但仍然跳過其 .claude/commands/ 和 .claude/agents/ 資料夾。來自其他目錄的 Skills 涵蓋了哪些會載入和不會載入。
沒有 --bare,-p 工作階段會執行專案 .claude/settings.json 中的 hooks 並連接其 .mcp.json 中的伺服器,即使在您從未信任的資料夾中也是如此。-p 工作階段不會顯示工作區信任對話框和每個伺服器的核准提示。在您信任資料夾之前執行的內容 涵蓋了 -p 下每種類型的儲存庫內容以及如何將其排除。
此範例在裸機模式下執行一次性摘要任務,並預先核准 Read 工具,以便呼叫完成而無需權限提示。執行前設定 ANTHROPIC_API_KEY,因為裸機模式不使用您的訂閱登入:
ANTHROPIC_API_KEY,使用在 Claude Console 中建立的金鑰,或在 --settings JSON 中提供 apiKeyHelper。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 繼續照常讀取各自的提供者認證。
在裸機模式下,Claude 可以存取 Bash、檔案讀取和檔案編輯工具。使用旗標傳遞您需要的任何 context:
--bare 是用於指令碼和 SDK 呼叫的建議模式,並將在未來版本中成為 -p 的預設值。退出時的背景任務
如果 Claude 在claude -p 執行期間啟動 背景 Bash 任務(例如開發伺服器或監視組建),該 shell 會在 Claude 傳回其最終結果且 stdin 已關閉後約五秒鐘終止。寬限期允許在結果之後立即完成的任務仍然傳遞其輸出。
如果 Claude 啟動背景 subagent 或工作流程,claude -p 會改為保持開啟,直到該工作完成,因為其結果是最終輸出的一部分。
預設情況下,等待在 10 分鐘的連續空閒等待後結束,因此卡住的 subagent 或工作流程無法無限期地保持程序開啟。此時 Claude Code 會停止仍在執行的任何內容並捨棄其部分結果。要變更限制,請設定 CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS,或將其設定為 0 以無限期等待。
如果 Claude 在 claude -p 執行期間啟動 Monitor 監視,Claude Code 會等待監視直到其逾時或十分鐘上限結束等待,以先發生者為準。在等待期間,Claude 會持續回應監視報告的內容。預設情況下,監視在 Claude 啟動後五分鐘逾時。
使用 SIGTERM 停止執行
如果您使用 SIGTERM 停止claude -p 執行,例如使用 kill 或從程序監督程式,Claude Code 會以代碼 143 退出。Claude Code 會將進行中的轉換保留為未完成狀態,並且不會為其記錄任何結果。要改為結束轉換,請傳送 SIGINT,或在停止程序之前呼叫 Agent SDK 的 interrupt()。
在 SIGTERM 上,Claude Code 會終止仍在執行的任何 Bash 命令的程序樹。Claude Code 然後執行 SessionEnd hooks 並退出。退出時,Claude Code 不啟動新的工具呼叫、不傳送新的模型請求,也不執行除 SessionEnd 以外的任何 hook。如果執行在命令中間或在信號到達時等待權限提示的答案,Claude Code 會按如下方式處理該步驟:
- 執行命令:Claude Code 在工作階段中將命令記錄為已終止。
- 等待權限提示的答案:如果您向程序傳送 SIGTERM,Claude Code 會將提示保留為未回答。如果您的程式透過 Agent SDK 關閉工作階段,SDK 會在傳送任何信號之前結束 Claude Code 的輸入,Claude Code 會在輸入結束後立即取消提示。
CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1。
如果工作目錄被刪除
如果claude -p 或 Agent SDK 工作階段的工作目錄在工作階段中間被刪除,工作階段會繼續執行。當轉換在目錄遺失時啟動時,Claude Code 會在 stream-json 輸出中發出 警告訊息,且 shell 命令會失敗,直到目錄再次存在。
範例
這些範例突出了常見的 CLI 模式。如果命令指定了檔案(例如auth.py 或 build-error.txt),請替換為您自己專案中的檔案。在 CI 或其他指令碼環境中,添加 --bare,以便 Claude Code 啟動時不載入主機的 hooks、plugins、自動記憶或 CLAUDE.md。
透過 Claude 傳輸資料
非互動模式讀取 stdin,因此您可以像任何其他命令列工具一樣透過管道傳入資料並重新導向回應。 此範例將建置日誌傳輸到 Claude 並將說明寫入檔案:--output-format json 時,回應承載包括 total_cost_usd 和按模型的成本明細,因此指令碼呼叫者可以追蹤支出而無需查詢使用儀表板。當您使用 --continue 或 --resume 繼續較早的對話時,執行會報告對話的整體總計,包括較早執行的支出。這兩個數字都是用戶端估計,可能與您的實際帳單不同。
管道 stdin 的上限為 10MB。如果超過上限,Claude Code 會以清晰的錯誤訊息退出並返回非零狀態。若要處理更大的輸入,請將內容寫入檔案,並在提示中參考檔案路徑,而不是透過管道傳輸。
將 Claude 添加到建置指令碼
您可以在指令碼中包裝非互動呼叫,以將 Claude 用作專案特定的 linter 或審查者。 此package.json 指令碼將針對 main 的差異傳輸到 Claude,並要求它報告拼寫錯誤。傳輸差異意味著 Claude 不需要 Bash 權限來讀取它,而轉義的雙引號使指令碼可移植到 Windows:
npm run lint:claude 執行它。
取得結構化輸出
使用--output-format 控制回應的返回方式:
text(預設):純文字輸出json:包含結果、工作階段 ID 和中繼資料的結構化 JSONstream-json:用於即時串流的換行分隔 JSON
result 欄位中:
--output-format json 搭配 --json-schema 和 JSON Schema 定義。回應包括關於請求的中繼資料(工作階段 ID、使用情況等),結構化輸出在 structured_output 欄位中。
此範例從 auth.py 提取函式名稱並將其作為字串陣列返回:
claude 會以 Error: --json-schema is not a valid JSON Schema 退出,後面跟著驗證器的診斷。Claude Code 接受使用 format 關鍵字的結構描述,例如 "format": "email",但將 format 視為註解,不強制執行。在 v2.1.205 之前,Claude Code 無聲地忽略無效的結構描述並返回非結構化文字,並將任何包含 format 的結構描述視為無效。
串流回應
使用--output-format stream-json 搭配 --verbose 和 --include-partial-messages 以在產生令牌時接收它們。每一行都是代表一個事件的 JSON 物件:
result 訊息。
如果您的消費者緩慢讀取串流,Claude Code 會等待佇列中的輸出排出後再退出,根據仍在佇列中的數量調整等待時間,上限為 30 秒。在 v2.1.214 之前,退出等待上限約為 2 秒,這可能會截斷大型回應的末尾。
以下範例使用 jq 篩選文字增量並僅顯示串流文字。-r 旗標輸出原始字串(無引號),-j 不帶換行符連接,因此令牌連續串流:
追蹤子代理訊息
來自子代理的訊息在串流中顯示為assistant 和 user 訊息,其 parent_tool_use_id 欄位是產生子代理的工具呼叫的 ID。來自主要對話的訊息在該欄位中帶有 null。
來自在前景中執行的子代理的第一條訊息是 user 訊息,帶有驅動它的提示。在該第一條訊息之後,Claude Code 發出:
- 預設情況下:子代理的
tool_use和tool_result區塊。 - 使用
--forward-subagent-text或CLAUDE_CODE_FORWARD_SUBAGENT_TEXT:子代理的文字和思考區塊,因此您可以重建每個子代理的文字記錄。這需要 Claude Code v2.1.211 或更新版本。
parent_tool_use_id 中,巢狀子代理的訊息帶有啟動它的 Agent 或 Skill 工具呼叫的 ID,因此您可以透過追蹤這些 ID 來重建完整的巢狀樹。在 v2.1.219 之前,來自巢狀子代理的訊息不會出現在串流中。
在子代理中執行的 Skills 在串流中以相同方式出現:分叉的 skill 的第一條訊息是 user 訊息,帶有驅動執行的 skill 內容。如果您啟用任一選項,串流也會帶有分叉的 skill 的文字和思考區塊。在 v2.1.265 之前,只有分叉的 skill 的 tool_use 和 tool_result 區塊出現在串流中。
處理 API 重試
當 API 請求因可重試的錯誤而失敗時,Claude Code 在重試前發出system/api_retry 事件。在 v2.1.246 或更新版本上,當 401 或 403 拒絕 apiKeyHelper 認證時,Claude Code 無聲地進行前兩次重試,沒有事件,然後從第三次連續重試開始照常發出事件。無聲重試仍計入 attempt。您可以使用該事件在自己的介面中顯示重試進度。
讀取工作階段中繼資料
system/init 事件報告工作階段中繼資料,包括模型、工具、MCP 伺服器和載入的 plugins。除非啟動事件在其前面,否則它是串流中的第一個事件:
plugin_install事件,當設定CLAUDE_CODE_SYNC_PLUGIN_INSTALL時。hook_started、hook_progress和hook_response事件,當配置的SessionStart或Setuphook 執行時。這些在 hook 產生時作為串流。Claude Code v2.1.169 至 v2.1.203 在 hook 完成後以一個批次傳遞它們,仍在system/init之前;v2.1.204 恢復了即時傳遞。
capabilities 字串陣列,命名此 Claude Code 版本實現的協議行為,例如 interrupt_receipt_v1 或 interrupt_cancel_queued_v1。檢查它以進行功能偵測,而不是比較版本字串,並忽略您不認識的值。該欄位需要 Claude Code v2.1.205 或更新版本,在較早版本中不存在。有關功能清單,請參閱 SDKSystemMessage。
當 plugin 或 MCP 伺服器未載入時使 CI 失敗
使用system/init 事件中的 plugin 欄位來捕捉未載入的 plugin:
當
--plugin-dir 目錄或存檔本身載入失敗時,其 plugin_errors 項目包括解析的絕對路徑作為 path。使用它來判斷多個 --plugin-dir 值中哪一個失敗。path 欄位需要 Claude Code v2.1.283 或更新版本。
以相同方式使用 MCP 伺服器欄位。當您使用 -p 傳遞 --mcp-config 時,Claude Code 在執行第一個回合前等待仍在等待的伺服器,最多等待 MCP_TIMEOUT 啟動逾時,預設為 30 秒。具有快取工具清單的遠端伺服器跳過等待,在 system/init 中顯示 pending,並在其第一次工具呼叫時連接。等待需要 Claude Code v2.1.221 或更新版本。
Claude Code 在啟動時驗證每個 --mcp-config 項目,並跳過驗證失敗的項目,例如沒有 type 的 url 項目。執行繼續並乾淨地退出,因此檢查這些欄位以捕捉未載入的伺服器:
當您在終端中手動執行命令時,Claude Code 也會向 stderr 列印啟動警告,例如
Warning: 1 MCP server skipped due to invalid config:,後面跟著每個跳過項目的原因。當您重新導向 stderr 或當 CI 執行器或 SDK 主機等程式捕捉它時,Claude Code 不列印警告,僅在 mcp_server_errors 欄位中報告跳過的項目。警告需要 Claude Code v2.1.219 或更新版本。
追蹤 plugin 安裝
當設定CLAUDE_CODE_SYNC_PLUGIN_INSTALL 時,Claude Code 在第一個回合前安裝 marketplace plugins 時發出 system/plugin_install 事件。使用這些在您自己的 UI 中顯示安裝進度。
自動批准工具
使用--allowedTools 讓 Claude 使用某些工具而無需提示。此範例執行測試套件並修復失敗,允許 Claude 執行 Bash 命令和讀取/編輯檔案而無需請求權限:
-p,內建啟動權限模式在每個計畫上都是 Manual,因此傳遞您想要的權限模式:
auto:傳遞--permission-mode auto以讓分類器審查大多數操作,而不是您dontAsk:Claude Code 拒絕每個會提示的呼叫,這對鎖定的 CI 執行很有用。在 Manual 模式中不需要批准的操作仍會執行,例如在您的工作目錄中讀取檔案和唯讀命令集,以及您的--allowedTools項目或permissions.allow規則涵蓋的操作。AskUserQuestion、connector 工具您的組織設定為ask和標記為requiresUserInteraction的 MCP 工具即使在允許規則匹配時也被拒絕acceptEdits:Claude 寫入檔案而無需提示,Claude Code 自動批准常見的檔案系統命令,例如mkdir、touch、mv和cp。沒有模式自動批准的操作仍然適用。除了唯讀命令集,其他 shell 命令和網路請求仍需要--allowedTools項目或permissions.allow規則。請參閱acceptEdits自動批准的內容以取得完整清單
acceptEdits 作為基準應用 lint 修復:
在無人值守執行中關閉權限提示
當沒有人可用於回答權限提示時,傳遞--permission-prompts none,例如在排程工作中。當您的執行有權限主機時,該旗標最重要:具有 canUseTool 回呼的 Agent SDK 應用程式,或您使用 --permission-prompt-tool 傳遞的 MCP 工具。沒有該旗標,您的執行會等待該主機回答每個權限請求。
使用該旗標,您的執行不會查詢主機或等待它。任何會提示的內容都被拒絕,除非 PermissionRequest hook 允許它,Claude 被告知沒有人可以批准請求且不應重試它,執行繼續。在沒有主機的 -p 執行中,這些請求無論如何都被拒絕,該旗標也告知 Claude 不要重試它們。權限規則、PermissionRequest hooks 和您設定的權限模式仍然首先決定每個呼叫;Claude Code 僅拒絕其他任何內容都無法解決的請求。
此範例在自動模式中執行無人值守的任務。分類器照常審查每個操作,Claude Code 拒絕任何會回退到提示的內容:
--permission-prompts none,Claude Code 移除需要來自人員的答案的工具,例如 AskUserQuestion,因此 Claude 無法呼叫它們。任何沒有 Elicitation hook 回答的 MCP 引出請求都被取消。
使用 --output-format stream-json,拒絕顯示為 permission_denied 系統訊息,最終結果訊息在 permission_denials 中列出它們。
--permission-prompts 旗標需要 Claude Code v2.1.259 或更新版本。較早版本以未知選項錯誤拒絕它。建立提交
此範例審查暫存的變更並建立具有適當訊息的提交:--allowedTools 旗標使用權限規則語法。尾部的 * 啟用前綴匹配,因此 Bash(git diff *) 允許任何以 git diff 開頭的命令。空格在 * 之前很重要:沒有它,Bash(git diff*) 也會匹配 git diff-index。
命令支援在
-p 模式中有所不同:- 使用者調用的 skills 和自訂命令有效。在提示字串中包含
/skill-name,Claude Code 在執行前展開它。 - 僅在終端介面中執行的內建命令,例如
/login,不可用。 /model、/effort、/fast、/color和/rename接受值作為引數,例如/model sonnet,/mcp不帶引數列印伺服器狀態的文字摘要。這些形式需要 Claude Code v2.1.205 或更新版本,並遵循每個命令的可用性注意事項。- 若要變更設定,將
key=value傳遞給/config,例如/config thinking=false。 /output-style <style>切換輸出樣式,/output-style單獨列出它們。需要 Claude Code v2.1.269 或更新版本。
自訂系統提示
使用--append-system-prompt 添加指示同時保持 Claude Code 的預設行為。此範例將 PR 差異傳輸到 Claude 並指示它審查安全漏洞。將其儲存為 shell 指令碼,例如 review.sh:
"$1" 代表您在命令列上傳遞的第一個引數。執行 bash review.sh 123,shell 將 "$1" 替換為 123,因此指令碼會擷取 PR 123 的差異。Claude Code 以 JSON 格式列印審查,文字在 result 欄位中。
有關更多選項,請參閱系統提示旗標,包括 --system-prompt 以完全替換預設提示。
繼續對話
使用--continue 繼續最近的對話,或使用 --resume 搭配工作階段 ID 繼續特定對話。在 Claude Code v2.1.257 或更新版本上,當您傳遞 --continue 時,Claude Code 開啟已完成但未仍在執行的背景工作階段。此範例執行審查,然後傳送後續提示:
--resume 傳遞工作階段的 .jsonl 文字記錄檔案的絕對路徑,Claude Code 繼續儲存在該檔案中的對話。
後續步驟
- Agent SDK 快速入門:使用 Python 或 TypeScript 建立您的第一個 agent
- CLI 參考:所有 CLI 旗標和選項
- GitHub Actions:在 GitHub 工作流程中使用 Agent SDK
- GitLab CI/CD:在 GitLab 管道中使用 Agent SDK