以程式方式執行 Claude Code
使用 Agent SDK 從 CLI、Python 或 TypeScript 以程式方式執行 Claude Code。
Agent SDK 提供與 Claude Code 相同的工具、agent 迴圈和上下文管理。它可作為 CLI 用於指令碼和 CI/CD，或作為 Python 和 TypeScript 套件供完整的程式控制。
若要以非互動模式執行 Claude Code，請傳遞 -p 和您的提示以及任何 CLI 選項：
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
本頁涵蓋透過 CLI (claude -p) 使用 Agent SDK。如需具有結構化輸出、工具核准回呼和原生訊息物件的 Python 和 TypeScript SDK 套件，請參閱 完整 Agent SDK 文件。
基本用法
在任何 claude 命令中加上 -p（或 --print）旗標以非互動方式執行。並非每個 CLI 選項 都能與 -p 結合。Claude Code 拒絕 --bg，並在有任務描述時拒絕 --cloud，並會出現命名衝突的錯誤；--cloud 與工作階段 ID 和 -p 一起使用時，會 將訊息加入該雲端工作階段 並退出。您經常會與 -p 結合的選項包括：
此範例詢問 Claude 關於您的程式碼庫的問題並列印回應：
claude -p "What does the auth module do?"
Claude Code 在成功時以代碼 0 退出，在執行失敗時以非零代碼退出，因此您的指令碼可以根據退出狀態進行分支。如果您傳遞無效旗標，Claude Code 會在執行開始前向 stderr 報告錯誤。當執行內部發生失敗（例如缺少驗證）時，Claude Code 會將失敗列印為 stdout 上的結果。
使用裸機模式更快啟動
加上 --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，因為裸機模式不使用您的訂閱登入：
claude --bare -p "Summarize README.md" --allowedTools "Read"
在裸機模式下，Claude Code 永遠不會讀取 OAuth 認證或系統鑰匙圈。對於 Anthropic API，在環境中設定 ANTHROPIC_API_KEY，使用在 Claude Console 中建立的金鑰，或在 --settings JSON 中提供 apiKeyHelper。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 繼續照常讀取各自的提供者認證。
在裸機模式下，Claude 可以存取 Bash、檔案讀取和檔案編輯工具。使用旗標傳遞您需要的任何 context：
| 要載入 | 使用 |
|---|---|
| 系統提示詞新增 | --append-system-prompt、--append-system-prompt-file |
| 設定 | --settings <file-or-json> |
| MCP 伺服器 | --mcp-config <file-or-json> |
| 自訂 agent | --agents <file-or-json> |
| 一個 plugin | --plugin-dir <path>、--plugin-url <url> |
bare 模式也會限制工作階段執行期間發生的事情：
- MCP 伺服器：只有在命令列上提供的伺服器會連接，例如使用
--mcp-config。在互動工作階段中，除非您傳遞--ide，否則 Claude Code 也會跳過自動 IDE 連接。 - 系統提醒：Claude 會收到您的提示詞和工具結果，但不會附帶 Claude Code 原本會一併加入的 系統提醒。例如，當 Claude 先前讀取的檔案在磁碟上變更時，Claude 不會收到通知，也不會取得可用 skill 的清單，包括來自
--add-dir資料夾的 skill。 - 背景任務：不會執行任何背景任務。達到 逾時 的命令會停止，而不是 移至背景。
在 v2.1.286 之前，這些限制僅部分生效：互動式 --bare 工作階段會連接一般工作階段會連接的 MCP 伺服器，每個 --bare 工作階段都會傳送系統提醒，且背景任務仍可使用。
退出時的背景任務
如果 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 會將中斷的轉換保留為原樣，您的下一個提示會推動對話。要讓 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 啟動時不載入主機的 hook、外掛、自動記憶或 CLAUDE.md。
透過 Claude 傳遞資料
非互動模式會讀取 stdin，因此您可以像使用任何其他命令列工具一樣，將資料透過管道傳入，並將回應重新導向輸出。
此範例將建置日誌透過管道傳入 Claude，並將說明寫入檔案：
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
使用 --output-format json 時，回應 payload 會包含 total_cost_usd 以及依模型細分的費用，因此腳本化的呼叫端無需查閱使用量儀表板即可追蹤支出。當您使用 --continue 或 --resume 接續先前的對話時，該次執行會回報整個對話的總額，包含先前執行的支出。這兩個數字都是用戶端估算值，可能與您的實際帳單不同。
如果 Claude Code 無法讀取 stdin，例如啟動它的程序中斷了其一端的連線，Claude Code 會將警告輸出至 stderr，並繼續使用命令列中的提示詞。在 v2.1.211 之前，Windows 上無法讀取的 stdin 會導致工作階段當機，或使其在沒有任何輸出的情況下靜默結束。
將 Claude 加入建置腳本
您可以將非互動呼叫包裝在腳本中，把 Claude 當作專案專屬的 linter 或審查工具使用。
此 package.json 腳本會將相對於 main 的差異透過管道傳入 Claude，並要求它回報錯字。透過管道傳入差異意味著 Claude 不需要 Bash 權限即可讀取它，而跳脫的雙引號可讓腳本在 Windows 上保持可攜性：
{
"scripts": {
"lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
}
}
使用 npm run lint:claude 執行。
取得結構化輸出
使用 --output-format 控制回應的傳回方式：
text（預設）：純文字輸出json：包含結果、工作階段 ID 及中繼資料的結構化 JSONstream-json：以換行分隔的 JSON，用於即時串流
此範例以 JSON 格式傳回專案摘要及工作階段中繼資料，文字結果位於 result 欄位：
claude -p "Summarize this project" --output-format json
若要取得符合特定 schema 的輸出，請將 --output-format json 與 --json-schema 及 JSON Schema 定義搭配使用。回應會包含請求的中繼資料（工作階段 ID、使用量等），結構化輸出則位於 structured_output 欄位。
此範例會擷取函式名稱，並以字串陣列的形式傳回：
claude -p "Extract the main function names from auth.py" \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
如果該值不是有效的 JSON Schema，claude 會以 Error: --json-schema is not a valid JSON Schema 結束，並附上驗證器的診斷訊息。Claude Code 接受使用 format 關鍵字的 schema，例如 "format": "email"，但會將 format 視為註解而不強制執行。在 v2.1.205 之前，Claude Code 會靜默忽略無效的 schema 並傳回非結構化文字，且會將任何包含 format 的 schema 視為無效。
串流回應
將 --output-format stream-json 與 --verbose 及 --include-partial-messages 搭配使用，即可在 token 產生時即時接收。每一行都是代表一個事件的 JSON 物件：
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
串流的最後一行是 result 訊息，其中包含最終回應文字、費用及工作階段中繼資料。
如果您的消費端讀取串流的速度較慢，Claude Code 會等待佇列中的輸出消化完畢後再結束，等待時間會依仍在佇列中的量調整，上限為 30 秒。在 v2.1.214 之前，結束前的等待上限約為兩秒，可能會截斷大型回應的結尾。
以下範例使用 jq 篩選文字差量，僅顯示串流文字。-r 旗標會輸出原始字串（不含引號），-j 則會在不加換行的情況下串接，讓 token 持續串流：
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
如需使用回呼及訊息物件進行程式化串流，請參閱 Agent SDK 文件中的即時串流回應。
追蹤 subagent 訊息
來自 subagent 以及在 subagent 中執行的 skill 的訊息，會以 assistant 及 user 訊息的形式出現在串流中。其 parent_tool_use_id 欄位會指出每則訊息屬於哪一次執行。來自主對話的訊息在該欄位中則為 null。
分叉 skill 或在前景執行的 subagent 的第一則訊息，是一則 user 訊息，內含驅動它的提示詞或 skill 內容。在第一則訊息之後，Claude Code 會發出：
- 預設情況下：該次執行的
tool_use及tool_result區塊。 - 使用
--forward-subagent-text或CLAUDE_CODE_FORWARD_SUBAGENT_TEXT時：還會包含該次執行的文字及思考區塊，因此您可以重建每次執行的逐字稿。
啟用任一選項時，Claude Code 會轉發來自每個巢狀層級的 subagent 的訊息，無論每個 subagent 是透過 Agent 工具產生，還是以分叉 skill 的形式啟動。在 parent_tool_use_id 中，巢狀 subagent 的訊息會帶有啟動它的 Agent 或 Skill 工具呼叫 ID，因此您可以依循這些 ID 重建完整的巢狀樹狀結構。
由 Claude 透過工具呼叫啟動的執行，會帶有該工具呼叫的 ID。您透過將 /<skill-name> 作為提示詞傳入而啟動的分叉 skill 沒有工具呼叫，因此其訊息會改為帶有 forked-command- 值，並在它完成後才送達。請在第一欄中找到該次執行的啟動方式：
| 執行的啟動方式 | parent_tool_use_id |
其訊息送達的時機 |
|---|---|---|
| Claude 從主對話呼叫 Agent 工具 | 該 Agent tool_use 區塊的 ID |
在 subagent 運作期間 |
| Claude 從主對話為分叉 skill 呼叫 Skill 工具 | 該 Skill tool_use 區塊的 ID |
在分叉 skill 運作期間 |
您將 /<skill-name> 作為提示詞傳入 |
以 forked-command- 開頭的值 |
在分叉 skill 完成後一併依序送達 |
對於從提示詞啟動的分叉 skill，請以 forked-command- 前綴比對 parent_tool_use_id，因為其後的名稱可能與您輸入的名稱不同。
如果您的串流中缺少其中某些訊息，請對照以下最低版本檢查您的 Claude Code 版本：
--forward-subagent-text及CLAUDE_CODE_FORWARD_SUBAGENT_TEXT：v2.1.211 或更新版本- 在每個巢狀層級進行轉發：v2.1.219 或更新版本
- Claude 從主對話以 Skill 工具啟動的分叉 skill：其
tool_use及tool_result區塊需要 v2.1.86 或更新版本，其第一則user訊息以及文字及思考區塊需要 v2.1.265 或更新版本 - 由分叉 skill 產生的 subagent 的訊息，以及在 subagent 或另一個分叉 skill 內啟動的分叉 skill 的訊息：v2.1.275 或更新版本
- 您透過將
/<skill-name>作為提示詞傳入而啟動的分叉 skill 的訊息：v2.1.287 或更新版本
處理 API 重試
當 API 請求因可重試的錯誤而失敗時，Claude Code 會在重試前發出 system/api_retry 事件。在 v2.1.246 或更新版本中，當 401 或 403 拒絕 apiKeyHelper 憑證時，Claude Code 會靜默進行前兩次重試而不發出事件，從第三次連續重試起才照常發出事件。靜默重試仍會計入 attempt。您可以使用此事件在自己的介面中顯示重試進度。
| 欄位 | 類型 | 說明 |
|---|---|---|
type |
"system" |
訊息類型 |
subtype |
"api_retry" |
識別此為重試事件 |
attempt |
integer | 目前的嘗試次數，從 1 開始 |
max_retries |
integer | 此失敗原因所允許的重試總次數，可能少於整個工作階段的預算 |
retry_delay_ms |
integer | 距離下次嘗試的毫秒數 |
error_status |
integer 或 null | 失敗嘗試的 HTTP 狀態碼；若該次嘗試未收到來自 API 的 HTTP 回應，則為 null |
no_response |
object，選用 | 僅在失敗的嘗試未及時收到回應標頭時出現。waited_ms 是該次嘗試等待的時間，retry_wait_ms 是重試將等待的時間。在這些事件中，max_retries 反映此原因通常獲得的一次重試，而非整個工作階段的預算。需要 Claude Code v2.1.261 或更新版本 |
error |
string | 錯誤類別：authentication_failed、oauth_org_not_allowed、account_on_hold、billing_error、rate_limit、overloaded、invalid_request、model_not_found、server_error、max_output_tokens、cloud_credential_error 或 unknown |
uuid |
string | 唯一事件識別碼 |
session_id |
string | 事件所屬的工作階段 |
讀取工作階段中繼資料
system/init 事件會回報工作階段中繼資料，包括模型、工具、MCP 伺服器及已載入的外掛。除非有啟動事件排在它之前，否則它是串流中的第一個事件：
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。
在外掛或 MCP 伺服器未載入時讓 CI 失敗
使用 system/init 事件中的外掛欄位來偵測未載入的外掛：
| 欄位 | 類型 | 說明 |
|---|---|---|
plugins |
array | 成功載入的外掛，每個都包含 name 及 path |
plugin_errors |
array | 外掛載入時的錯誤，每個都包含 plugin、type 及 message。包括未滿足的相依性版本，以及 --plugin-dir 載入失敗，例如路徑不存在或封存檔無效。未載入的外掛不會出現在 plugins 中。沒有錯誤時會省略此鍵 |
當 --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 項目。執行會繼續並正常結束，因此請檢查這些欄位，以偵測從未載入的伺服器：
| 欄位 | 類型 | 說明 |
|---|---|---|
mcp_servers |
array | 工作階段中的 MCP 伺服器，每個都包含 name 及 status |
mcp_server_errors |
array | 因設定驗證而被略過的 --mcp-config 項目，每個都包含 name、type 及 message。type 是略過類別，例如 unknown_type、url_missing_type、invalid_config 或 reserved_name；請將無法辨識的值視為一般略過。受影響的伺服器不會出現在 mcp_servers 中。沒有錯誤時會省略此鍵，因此 CI 關卡可以在陣列非空時判定失敗。需要 Claude Code v2.1.219 或更新版本 |
當您在終端機中手動執行命令時，Claude Code 也會將啟動警告輸出至 stderr，例如 Warning: 1 MCP server skipped due to invalid config:，接著列出每個被略過項目的原因。當您重新導向 stderr，或由 CI 執行器或 SDK 主機等程式擷取 stderr 時，Claude Code 不會輸出警告，僅在 mcp_server_errors 欄位中回報被略過的項目。此警告需要 Claude Code v2.1.219 或更新版本。
追蹤外掛安裝
設定 CLAUDE_CODE_SYNC_PLUGIN_INSTALL 時，Claude Code 會在第一個回合之前安裝市集外掛的期間發出 system/plugin_install 事件。可使用這些事件在您自己的 UI 中呈現安裝進度。
| 欄位 | 類型 | 說明 |
|---|---|---|
type |
"system" |
訊息類型 |
subtype |
"plugin_install" |
識別此為外掛安裝事件 |
status |
"started"、"installed"、"failed" 或 "completed" |
started 及 completed 標示整體安裝的開始與結束；installed 及 failed 回報個別市集 |
name |
string，選用 | 市集名稱，出現在 installed 及 failed 上 |
error |
string，選用 | 失敗訊息，出現在 failed 上 |
uuid |
string | 唯一事件識別碼 |
session_id |
string | 事件所屬的工作階段 |
自動核准工具
使用 --allowedTools 讓 Claude 無需提示即可使用特定工具。列出 Read 及 Edit 可讓 Claude 在不請求權限的情況下讀取及編輯檔案。列出 Bash 對 shell 命令也有相同效果，但以自動模式啟動的執行除外；在此情況下，Claude Code 會將單獨的 Bash 項目視為過於寬泛的允許規則而捨棄，改由自動模式評估每個命令。此範例列出這三個工具，執行測試套件並修正失敗：
claude -p "Run the test suite and fix any failures" \
--allowedTools "Bash,Read,Edit"
若要為整個工作階段設定基準，而非列出個別工具，請傳入權限模式。沒有任何設定指定權限模式的執行會採用內建的起始權限模式，而它可能是 auto，因此請傳入您想要的模式：
auto：傳入--permission-mode auto，由分類器代替您審查大多數動作dontAsk：Claude Code 會拒絕所有原本會提示的呼叫，這對於受嚴格限制的 CI 執行很有用。在手動模式下無需核准的動作仍會執行，例如讀取工作目錄中的檔案及唯讀命令集，您的--allowedTools項目或permissions.allow規則涵蓋的動作也同樣會執行。AskUserQuestion、您的組織設為ask的連接器工具，以及標記為requiresUserInteraction的 MCP 工具，即使有允許規則相符仍會被拒絕acceptEdits：Claude 無需提示即可寫入檔案，且 Claude Code 會自動核准常見的檔案系統命令，例如mkdir、touch、mv及cp。任何模式都不會自動核准的動作仍然適用。除唯讀命令集外，其他 shell 命令及網路請求仍需要--allowedTools項目或permissions.allow規則。如需完整清單，請參閱acceptEdits自動核准的項目
此範例以 acceptEdits 作為基準套用 lint 修正：
claude -p "Apply the lint fixes" --permission-mode acceptEdits
在無人值守的執行中關閉權限提示
當沒有人能回應權限提示時，例如在排程工作中，請傳入 --permission-prompts none。當您的執行具有權限主機時，此旗標最為重要：具有 canUseTool 回呼的 Agent SDK 應用程式，或您透過 --permission-prompt-tool 傳入的 MCP 工具。若未使用此旗標，您的執行會等待該主機回應每個權限請求。
使用此旗標時，您的執行不會諮詢主機，也不會等待它。任何會觸發提示的動作都會被拒絕，除非有 PermissionRequest hook 允許；Claude 會被告知沒有人能核准該請求且不應重試，而執行會繼續進行。在沒有主機的 -p 執行中，這些請求無論如何都會被拒絕，而此旗標還會告知 Claude 不要重試。權限規則、PermissionRequest hook 以及您設定的權限模式仍會優先決定每個呼叫；Claude Code 只會拒絕其他機制都無法處理的請求。
此範例以自動模式執行無人值守的任務。分類器會照常審查每個動作，而 Claude Code 會拒絕任何原本會退回提示的動作：
claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none
使用 --permission-prompts none 時，Claude Code 會移除需要由人回應的工具，例如 AskUserQuestion，因此 Claude 無法呼叫它們。任何沒有 Elicitation hook 回應的 MCP elicitation 請求都會被取消。
使用 --output-format stream-json 時，拒絕會以 permission_denied 系統訊息的形式出現，而最終結果訊息會在 permission_denials 中列出這些拒絕。
建立提交
此範例會審查已暫存的變更，並以適當的訊息建立提交：
claude -p "Look at my staged changes and create an appropriate commit" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
--allowedTools 旗標使用權限規則語法。結尾的 * 會啟用前綴比對，因此 Bash(git diff *) 允許任何以 git diff 開頭的命令。* 前的空格很重要：若沒有空格，Bash(git diff*) 也會比對到 git diff-index。
自訂系統提示詞
使用 --append-system-prompt 新增指令，同時保留 Claude Code 的預設行為。此範例將 PR 差異透過管道傳入 Claude，並指示它審查安全性弱點。將其儲存為 shell 腳本，例如 review.sh：
gh pr diff "$1" | claude -p \
--append-system-prompt "You are a security engineer. Review for vulnerabilities." \
--output-format json
在此腳本中，"$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 會開啟已經完成的背景工作階段，但不會開啟仍在執行中的背景工作階段。此範例會執行一次審查，然後傳送後續提示詞：
# First request
claude -p "Review this codebase for performance issues"
# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
如果您同時進行多個對話，請擷取工作階段 ID 以繼續特定的對話：
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"
您可以從不同的目錄執行這兩個命令：Claude Code 會在此機器上的任何專案中依 ID 尋找工作階段。在 v2.1.223 之前，Claude Code 只會在目前的專案目錄及其 git worktree 中尋找該 ID，因此您必須從同一個目錄執行這兩個命令。
您也可以不傳入工作階段 ID，改為將工作階段 .jsonl 逐字稿檔案的絕對路徑傳給 --resume，Claude Code 會繼續該檔案中儲存的對話。
後續步驟
- Agent SDK 快速入門：使用 Python 或 TypeScript 建立您的第一個 agent
- CLI 參考：所有 CLI 旗標和選項
- GitHub Actions：在 GitHub 工作流程中使用 Agent SDK
- GitLab CI/CD：在 GitLab 管道中使用 Agent SDK