104這些範例突出了常見的 CLI 模式。如果命令指定了檔案（例如 `auth.py` 或 `build-error.txt`），請替換為您自己專案中的檔案。在 CI 或其他指令碼環境中，添加 [`--bare`](#start-faster-with-bare-mode)，以便 Claude Code 啟動時不載入主機的 hooks、plugins、自動記憶或 `CLAUDE.md`。104這些範例突出了常見的 CLI 模式。如果命令指定了檔案（例如 `auth.py` 或 `build-error.txt`），請替換為您自己專案中的檔案。在 CI 或其他指令碼環境中，添加 [`--bare`](#start-faster-with-bare-mode)，以便 Claude Code 啟動時不載入主機的 hooks、plugins、自動記憶或 `CLAUDE.md`。
105 105
106<h3 id="pipe-data-through-claude">106<h3 id="pipe-data-through-claude">
107 透過 Claude 傳輸資料107 透過 Claude 管道傳輸資料
108</h3>108</h3>
109 109
110非互動模式讀取 stdin，因此您可以像任何其他命令列工具一樣透過管道傳入資料並重新導向回應。110非互動模式讀取 stdin，因此您可以像任何其他命令列工具一樣管道傳輸資料並重新導向回應。
111 111
112此範例將建置日誌傳輸到 Claude 並將說明寫入檔案：112此範例將建置日誌管道傳輸到 Claude，並將說明寫入檔案：
113 113
114```bash theme={null}114```bash theme={null}
115cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt115cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
116```116```
117 117
118使用 `--output-format json` 時，回應承載包括 `total_cost_usd` 和按模型的成本明細，因此指令碼呼叫者可以追蹤支出而無需查詢[使用儀表板](/docs/zh-TW/costs)。當您使用 `--continue` 或 `--resume` 繼續較早的對話時，執行會報告對話的整體總計，[包括較早執行的支出](/docs/zh-TW/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)。這兩個數字都是[用戶端估計](/docs/zh-TW/agent-sdk/cost-tracking)，可能與您的實際帳單不同。118使用 `--output-format json` 時，回應承載包括 `total_cost_usd` 和按模型的成本明細，因此指令碼呼叫者可以追蹤支出，而無需查詢[使用儀表板](/docs/zh-TW/costs)。當您使用 `--continue` 或 `--resume` 繼續較早的對話時，執行會報告對話的整體總計，[包括較早執行的支出](/docs/zh-TW/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)。兩個數字都是[用戶端估計](/docs/zh-TW/agent-sdk/cost-tracking)，可能與您的實際帳單不同。
119 119
120<Note>120<Note>
121 管道 stdin 的上限為 10MB。如果超過上限，Claude Code 會以清晰的錯誤訊息退出並返回非零狀態。若要處理更大的輸入，請將內容寫入檔案，並在提示中參考檔案路徑，而不是透過管道傳輸。121 管道傳輸的 stdin 上限為 10MB。如果超過上限，Claude Code 會以清晰的錯誤訊息退出，並返回非零狀態。若要處理較大的輸入，請將內容寫入檔案，並在提示中參考檔案路徑，而不是管道傳輸。
122</Note>122</Note>
123 123
124如果 Claude Code 無法讀取 stdin（例如因為啟動它的程序斷開了其端點），Claude Code 會向 stderr 列印警告並繼續使用命令列中的提示。在 v2.1.211 之前，Windows 上無法讀取的 stdin 會導致工作階段崩潰或無輸出地無聲退出。124如果 Claude Code 無法讀取 stdin（例如因為啟動它的程序斷開了其端點），Claude Code 會向 stderr 列印警告並繼續執行命令列中的提示。在 v2.1.211 之前，Windows 上無法讀取的 stdin 會導致工作階段崩潰或以無輸出的方式無聲退出。
125 125
126<h3 id="add-claude-to-a-build-script">126<h3 id="add-claude-to-a-build-script">
127 將 Claude 添加到建置指令碼127 將 Claude 新增到建置指令碼
128</h3>128</h3>
129 129
130您可以在指令碼中包裝非互動呼叫，以將 Claude 用作專案特定的 linter 或審查者。130您可以在指令碼中包裝非互動呼叫，以將 Claude 用作專案特定的 linter 或審查者。
131 131
132此 `package.json` 指令碼將針對 `main` 的差異傳輸到 Claude，並要求它報告拼寫錯誤。傳輸差異意味著 Claude 不需要 Bash 權限來讀取它，而轉義的雙引號使指令碼可移植到 Windows：132此 `package.json` 指令碼將針對 `main` 的差異管道傳輸到 Claude，並要求它報告拼寫錯誤。管道傳輸差異意味著 Claude 不需要 Bash 權限來讀取它，而逸出的雙引號使指令碼可移植到 Windows：
133 133
134```json theme={null}134```json theme={null}
135{135{
145 取得結構化輸出145 取得結構化輸出
146</h3>146</h3>
147 147
148使用 `--output-format` 控制回應的返回方式：148使用 `--output-format` 控制回應的傳回方式：
149 149
150* `text`（預設）：純文字輸出150* `text`（預設）：純文字輸出
151* `json`：包含結果、工作階段 ID 和中繼資料的結構化 JSON151* `json`：包含結果、工作階段 ID 和中繼資料的結構化 JSON
152* `stream-json`：用於即時串流的換行分隔 JSON152* `stream-json`：換行分隔的 JSON，用於即時串流
153 153
154此範例以 JSON 格式返回專案摘要及工作階段中繼資料，文字結果在 `result` 欄位中：154此範例以 JSON 形式傳回專案摘要及工作階段中繼資料，文字結果在 `result` 欄位中：
155 155
156```bash theme={null}156```bash theme={null}
157claude -p "Summarize this project" --output-format json157claude -p "Summarize this project" --output-format json
159 159
160若要取得符合特定結構描述的輸出，請使用 `--output-format json` 搭配 `--json-schema` 和 [JSON Schema](https://json-schema.org/) 定義。回應包括關於請求的中繼資料（工作階段 ID、使用情況等），結構化輸出在 `structured_output` 欄位中。160若要取得符合特定結構描述的輸出，請使用 `--output-format json` 搭配 `--json-schema` 和 [JSON Schema](https://json-schema.org/) 定義。回應包括關於請求的中繼資料（工作階段 ID、使用情況等），結構化輸出在 `structured_output` 欄位中。
161 161
162此範例從 auth.py 提取函式名稱並將其作為字串陣列返回：162此範例從 auth.py 提取函式名稱並將其傳回為字串陣列：
163 163
164```bash theme={null}164```bash theme={null}
165claude -p "Extract the main function names from auth.py" \165claude -p "Extract the main function names from auth.py" \
167 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'167 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
168```168```
169 169
170如果值不是有效的 JSON Schema，`claude` 會以 `Error: --json-schema is not a valid JSON Schema` 退出，後面跟著驗證器的診斷。Claude Code 接受使用 `format` 關鍵字的結構描述，例如 `"format": "email"`，但將 `format` 視為註解，不強制執行。在 v2.1.205 之前，Claude Code 無聲地忽略無效的結構描述並返回非結構化文字，並將任何包含 `format` 的結構描述視為無效。170如果值不是有效的 JSON Schema，`claude` 會以 `Error: --json-schema is not a valid JSON Schema` 退出，後面跟著驗證器的診斷。Claude Code 接受使用 `format` 關鍵字的結構描述，例如 `"format": "email"`，但將 `format` 視為註解，不強制執行。在 v2.1.205 之前，Claude Code 無聲地忽略無效的結構描述並傳回非結構化文字，並將任何包含 `format` 的結構描述視為無效。
171 171
172<Tip>172<Tip>
173 使用 [jq](https://jqlang.org/) 之類的工具來解析回應並提取特定欄位：173 使用 [jq](https://jqlang.org/) 之類的工具來解析回應並提取特定欄位：
188 串流回應188 串流回應
189</h3>189</h3>
190 190
191使用 `--output-format stream-json` 搭配 `--verbose` 和 `--include-partial-messages` 以在產生令牌時接收它們。每一行都是代表一個事件的 JSON 物件：191使用 `--output-format stream-json` 搭配 `--verbose` 和 `--include-partial-messages` 以在產生令牌時接收它們。每一行都是代表事件的 JSON 物件：
192 192
193```bash theme={null}193```bash theme={null}
194claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages194claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
195```195```
196 196
197串流的最後一行是包含最終回應文字、成本和工作階段中繼資料的 `result` 訊息。197串流的最後一行是 `result` 訊息，包含最終回應文字、成本和工作階段中繼資料。
198 198
199如果您的消費者緩慢讀取串流，Claude Code 會等待佇列中的輸出排出後再退出，根據仍在佇列中的數量調整等待時間，上限為 30 秒。在 v2.1.214 之前，退出等待上限約為 2 秒，這可能會截斷大型回應的末尾。199如果您的消費者緩慢讀取串流，Claude Code 會等待佇列中的輸出排出後再退出，根據仍在佇列中的數量調整等待時間，上限為 30 秒。在 v2.1.214 之前，退出等待上限約為 2 秒，這可能會截斷大型回應的末尾。
200 200
201以下範例使用 [jq](https://jqlang.org/) 篩選文字增量並僅顯示串流文字。`-r` 旗標輸出原始字串（無引號），`-j` 不帶換行符連接，因此令牌連續串流：201以下範例使用 [jq](https://jqlang.org/) 篩選文字增量並僅顯示串流文字。`-r` 旗標輸出原始字串（無引號），`-j` 在沒有換行符的情況下聯接，以便令牌連續串流：
202 202
203```bash theme={null}203```bash theme={null}
204claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \204claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
205 jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'205 jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
206```206```
207 207
208如需具有回呼和訊息物件的程式化串流，請參閱 Agent SDK 文件中的[即時串流回應](/docs/zh-TW/agent-sdk/streaming-output)。208如需具有回呼和訊息物件的程式設計串流，請參閱 Agent SDK 文件中的[即時串流回應](/docs/zh-TW/agent-sdk/streaming-output)。
209 209
210<h4 id="follow-subagent-messages">210<h4 id="follow-subagent-messages">
211 追蹤子代理訊息211 追蹤子代理訊息
212</h4>212</h4>
213 213
214來自[子代理](/docs/zh-TW/sub-agents)的訊息在串流中顯示為 `assistant` 和 `user` 訊息，其 `parent_tool_use_id` 欄位是產生子代理的工具呼叫的 ID。來自主要對話的訊息在該欄位中帶有 `null`。214來自[子代理](/docs/zh-TW/sub-agents)的訊息在串流中顯示為 `assistant` 和 `user` 訊息，其 `parent_tool_use_id` 欄位是產生子代理的工具呼叫的 ID。來自主對話的訊息在該欄位中帶有 `null`。
215 215
216來自在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行的子代理的第一條訊息是 `user` 訊息，帶有驅動它的提示。在該第一條訊息之後，Claude Code 發出：216來自在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行的子代理的第一條訊息是 `user` 訊息，帶有驅動它的提示。在該第一條訊息之後，Claude Code 發出：
217 217
218* **預設情況下**：子代理的 `tool_use` 和 `tool_result` 區塊。218* **預設情況下**：子代理的 `tool_use` 和 `tool_result` 區塊。
219* **使用 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 或 [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-TW/env-vars)**：子代理的文字和思考區塊，因此您可以重建每個子代理的文字記錄。這需要 Claude Code v2.1.211 或更新版本。219* **使用 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 或 [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-TW/env-vars)**：子代理的文字和思考區塊，以便您可以重建每個子代理的文字記錄。這需要 Claude Code v2.1.211 或更新版本。
220 220
221當您啟用任一選項時，Claude Code 從[每個巢狀深度的子代理](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)轉發訊息，無論每個子代理是使用 Agent 工具產生還是作為[分叉的 skill](/docs/zh-TW/skills#run-skills-in-a-subagent)啟動。分叉的 skill 產生的子代理的訊息，以及在子代理或另一個分叉的 skill 內啟動的分叉的 skill，需要 Claude Code v2.1.275 或更新版本。在 `parent_tool_use_id` 中，巢狀子代理的訊息帶有啟動它的 Agent 或 Skill 工具呼叫的 ID，因此您可以透過追蹤這些 ID 來重建完整的巢狀樹。在 v2.1.219 之前，來自巢狀子代理的訊息不會出現在串流中。221當您啟用任一選項時，Claude Code 會轉發來自[每個巢狀深度的子代理](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)的訊息，無論每個子代理是使用 Agent 工具產生的還是作為[分叉 skill](/docs/zh-TW/skills#run-skills-in-a-subagent) 啟動的。分叉 skill 產生的子代理的訊息，以及在子代理或另一個分叉 skill 內啟動的分叉 skill，需要 Claude Code v2.1.275 或更新版本。在 `parent_tool_use_id` 中，巢狀子代理的訊息帶有啟動它的 Agent 或 Skill 工具呼叫的 ID，因此您可以透過追蹤這些 ID 來重建完整的巢狀樹。在 v2.1.219 之前，巢狀子代理的訊息不會出現在串流中。
222 222
223[在子代理中執行](/docs/zh-TW/skills#run-skills-in-a-subagent)的 Skills 在串流中以相同方式出現：分叉的 skill 的第一條訊息是 `user` 訊息，帶有驅動執行的 skill 內容。如果您啟用任一選項，串流也會帶有分叉的 skill 的文字和思考區塊。在 v2.1.265 之前，只有分叉的 skill 的 `tool_use` 和 `tool_result` 區塊出現在串流中。223在子代理中[執行的 Skills](/docs/zh-TW/skills#run-skills-in-a-subagent) 在串流中以相同方式出現：分叉 skill 的第一條訊息是 `user` 訊息，帶有驅動執行的 skill 內容。如果您啟用任一選項，串流也會帶有分叉 skill 的文字和思考區塊。在 v2.1.265 之前，只有分叉 skill 的 `tool_use` 和 `tool_result` 區塊出現在串流中。
224 224
225<h4 id="handle-api-retries">225<h4 id="handle-api-retries">
226 處理 API 重試226 處理 API 重試
227</h4>227</h4>
228 228
229當 API 請求因可重試的錯誤而失敗時，Claude Code 在重試前發出 `system/api_retry` 事件。在 v2.1.246 或更新版本上，當 `401` 或 `403` 拒絕 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 認證時，Claude Code 無聲地進行前兩次重試，沒有事件，然後從第三次連續重試開始照常發出事件。無聲重試仍計入 `attempt`。您可以使用該事件在自己的介面中顯示重試進度。229當 API 請求因可重試的錯誤而失敗時，Claude Code 在重試前發出 `system/api_retry` 事件。在 v2.1.246 或更新版本上，當 `401` 或 `403` 拒絕 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 認證時，Claude Code 會以無事件的方式進行前兩次重試，然後從第三次連續重試開始照常發出事件。無聲重試仍計入 `attempt`。您可以使用事件在自己的介面中顯示重試進度。
230 230
231| 欄位 | 類型 | 說明 |231| 欄位 | 類型 | 說明 |
232| - | - | - |232| - | - | - |
248`system/init` 事件報告工作階段中繼資料，包括模型、工具、MCP 伺服器和載入的 plugins。除非啟動事件在其前面，否則它是串流中的第一個事件：248`system/init` 事件報告工作階段中繼資料，包括模型、工具、MCP 伺服器和載入的 plugins。除非啟動事件在其前面，否則它是串流中的第一個事件：
249 249
250* `plugin_install` 事件，當設定 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/zh-TW/env-vars) 時。250* `plugin_install` 事件，當設定 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/zh-TW/env-vars) 時。
251* [`hook_started`、`hook_progress` 和 `hook_response` 事件](/docs/zh-TW/agent-sdk/typescript#sdkhookstartedmessage)，當配置的 [`SessionStart`](/docs/zh-TW/hooks#sessionstart) 或 [`Setup`](/docs/zh-TW/hooks#setup) hook 執行時。這些在 hook 產生時作為串流。Claude Code v2.1.169 至 v2.1.203 在 hook 完成後以一個批次傳遞它們，仍在 `system/init` 之前；v2.1.204 恢復了即時傳遞。251* [`hook_started`、`hook_progress` 和 `hook_response` 事件](/docs/zh-TW/agent-sdk/typescript#sdkhookstartedmessage)，當配置的 [`SessionStart`](/docs/zh-TW/hooks#sessionstart) 或 [`Setup`](/docs/zh-TW/hooks#setup) hook 執行時。這些會在 hook 產生時串流。Claude Code v2.1.169 至 v2.1.203 在 hook 完成後以一個批次傳遞它們，仍在 `system/init` 之前；v2.1.204 恢復了即時傳遞。
252 252
253該事件還帶有一個選用的 `capabilities` 字串陣列，命名此 Claude Code 版本實現的協議行為，例如 `interrupt_receipt_v1` 或 `interrupt_cancel_queued_v1`。檢查它以進行功能偵測，而不是比較版本字串，並忽略您不認識的值。該欄位需要 Claude Code v2.1.205 或更新版本，在較早版本中不存在。有關功能清單，請參閱 [`SDKSystemMessage`](/docs/zh-TW/agent-sdk/typescript#sdksystemmessage)。253該事件還帶有一個選用的 `capabilities` 字串陣列，命名此 Claude Code 版本實現的協議行為，例如 `interrupt_receipt_v1` 或 `interrupt_cancel_queued_v1`。檢查它以進行功能偵測，而不是比較版本字串，並忽略您不認識的值。該欄位需要 Claude Code v2.1.205 或更新版本，在較早版本中不存在。請參閱 [`SDKSystemMessage`](/docs/zh-TW/agent-sdk/typescript#sdksystemmessage) 以取得功能清單。
254 254
255<h4 id="fail-ci-when-a-plugin-or-mcp-server-doesn’t-load">255<h4 id="fail-ci-when-a-plugin-or-mcp-server-doesn’t-load">
256 當 plugin 或 MCP 伺服器未載入時使 CI 失敗256 當 plugin 或 MCP 伺服器未載入時使 CI 失敗
261| 欄位 | 類型 | 說明 |261| 欄位 | 類型 | 說明 |
262| - | - | - |262| - | - | - |
263| `plugins` | 陣列 | 成功載入的 plugins，每個都有 `name` 和 `path` |263| `plugins` | 陣列 | 成功載入的 plugins，每個都有 `name` 和 `path` |
264| `plugin_errors` | 陣列 | plugin 載入時錯誤，每個都有 `plugin`、`type` 和 `message`。包括不滿足的依賴版本和 `--plugin-dir` 載入失敗，例如遺失的路徑或無效的存檔。受影響的 plugins 從 `plugins` 中移除。當沒有錯誤時，該鍵被省略 |264| `plugin_errors` | 陣列 | plugin 載入時間錯誤，每個都有 `plugin`、`type` 和 `message`。包括不滿足的依賴版本和 `--plugin-dir` 載入失敗，例如遺失的路徑或無效的存檔。未載入的 plugin 不在 `plugins` 中。當沒有錯誤時，會省略該鍵 |
265 265
266當 `--plugin-dir` 目錄或存檔本身載入失敗時，其 `plugin_errors` 項目包括解析的絕對路徑作為 `path`。使用它來判斷多個 `--plugin-dir` 值中哪一個失敗。`path` 欄位需要 Claude Code v2.1.283 或更新版本。266當 `--plugin-dir` 目錄或存檔本身無法載入時，其 `plugin_errors` 項目包括已解析的絕對路徑作為 `path`。使用它來判斷多個 `--plugin-dir` 值中哪個失敗。`path` 欄位需要 Claude Code v2.1.283 或更新版本。
267 267
268以相同方式使用 MCP 伺服器欄位。當您使用 `-p` 傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，Claude Code 在執行第一個回合前等待仍在等待的伺服器，最多等待 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時，預設為 30 秒。具有[快取工具清單](/docs/zh-TW/agent-sdk/mcp#connection-timing)的遠端伺服器跳過等待，在 `system/init` 中顯示 `pending`，並在其第一次工具呼叫時連接。等待需要 Claude Code v2.1.221 或更新版本。268以相同方式使用 MCP 伺服器欄位。當您使用 `-p` 傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，Claude Code 會等待仍在等待的伺服器，直到 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）。具有[快取工具清單](/docs/zh-TW/agent-sdk/mcp#connection-timing)的遠端伺服器會跳過等待，在 `system/init` 中顯示 `pending`，並在其第一次工具呼叫時連接。等待需要 Claude Code v2.1.221 或更新版本。
269 269
270Claude Code 在啟動時驗證每個 `--mcp-config` 項目，並跳過驗證失敗的項目，例如沒有 `type` 的 `url` 項目。執行繼續並乾淨地退出，因此檢查這些欄位以捕捉未載入的伺服器：270Claude Code 在啟動時驗證每個 `--mcp-config` 項目，並跳過驗證失敗的項目，例如沒有 `type` 的 `url` 項目。執行會繼續並乾淨地退出，因此檢查這些欄位以捕捉未載入的伺服器：
271 271
272| 欄位 | 類型 | 說明 |272| 欄位 | 類型 | 說明 |
273| - | - | - |273| - | - | - |
274| `mcp_servers` | 陣列 | 工作階段中的 MCP 伺服器，每個都有 `name` 和 `status` |274| `mcp_servers` | 陣列 | 工作階段中的 MCP 伺服器，每個都有 `name` 和 `status` |
275| `mcp_server_errors` | 陣列 | 由配置驗證跳過的 `--mcp-config` 項目，每個都有 `name`、`type` 和 `message`。`type` 是跳過類別，例如 `unknown_type`、`url_missing_type`、`invalid_config` 或 `reserved_name`；將您不認識的值視為通用跳過。受影響的伺服器從 `mcp_servers` 中移除。當沒有錯誤時，該鍵被省略，因此 CI 閘道可以在非空陣列上失敗。需要 Claude Code v2.1.219 或更新版本 |275| `mcp_server_errors` | 陣列 | 由配置驗證跳過的 `--mcp-config` 項目，每個都有 `name`、`type` 和 `message`。`type` 是跳過類別，例如 `unknown_type`、`url_missing_type`、`invalid_config` 或 `reserved_name`；將您不認識的值視為通用跳過。受影響的伺服器不在 `mcp_servers` 中。當沒有錯誤時，會省略該鍵，因此 CI 閘道可以在非空陣列上失敗。需要 Claude Code v2.1.219 或更新版本 |
276 276
277當您在終端中手動執行命令時，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 或更新版本。277當您在終端機中手動執行命令時，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 或更新版本。
278 278
279<h4 id="track-plugin-installs">279<h4 id="track-plugin-installs">
280 追蹤 plugin 安裝280 追蹤 plugin 安裝
281</h4>281</h4>
282 282
283當設定 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/zh-TW/env-vars) 時，Claude Code 在第一個回合前安裝 marketplace plugins 時發出 `system/plugin_install` 事件。使用這些在您自己的 UI 中顯示安裝進度。283當設定 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/zh-TW/env-vars) 時，Claude Code 在第一次轉向前安裝市場 plugins 時發出 `system/plugin_install` 事件。使用這些在您自己的 UI 中顯示安裝進度。
284 284
285| 欄位 | 類型 | 說明 |285| 欄位 | 類型 | 說明 |
286| - | - | - |286| - | - | - |
287| `type` | `"system"` | 訊息類型 |287| `type` | `"system"` | 訊息類型 |
288| `subtype` | `"plugin_install"` | 將此識別為 plugin 安裝事件 |288| `subtype` | `"plugin_install"` | 將此識別為 plugin 安裝事件 |
289| `status` | `"started"`、`"installed"`、`"failed"` 或 `"completed"` | `started` 和 `completed` 括住整體安裝；`installed` 和 `failed` 報告個別 marketplaces |289| `status` | `"started"`、`"installed"`、`"failed"` 或 `"completed"` | `started` 和 `completed` 括住整體安裝；`installed` 和 `failed` 報告個別市場 |
290| `name` | 字串，選用 | marketplace 名稱，在 `installed` 和 `failed` 上出現 |290| `name` | 字串，選用 | 市場名稱，在 `installed` 和 `failed` 上出現 |
291| `error` | 字串，選用 | 失敗訊息，在 `failed` 上出現 |291| `error` | 字串，選用 | 失敗訊息，在 `failed` 上出現 |
292| `uuid` | 字串 | 唯一事件識別碼 |292| `uuid` | 字串 | 唯一事件識別碼 |
293| `session_id` | 字串 | 事件所屬的工作階段 |293| `session_id` | 字串 | 事件所屬的工作階段 |
294 294
295<h3 id="auto-approve-tools">295<h3 id="auto-approve-tools">
296 自動批准工具296 自動核准工具
297</h3>297</h3>
298 298
299使用 `--allowedTools` 讓 Claude 使用某些工具而無需提示。此範例執行測試套件並修復失敗，允許 Claude 執行 Bash 命令和讀取/編輯檔案而無需請求權限：299使用 `--allowedTools` 讓 Claude 使用某些工具而無需提示。列出 `Read` 和 `Edit` 讓 Claude 讀取和編輯檔案而無需詢問權限。列出 `Bash` 對 shell 命令執行相同操作，除非在[自動模式](/docs/zh-TW/permission-modes#how-auto-mode-evaluates-actions)中啟動的執行中，Claude Code 會將裸 `Bash` 項目作為廣泛允許規則刪除，自動模式會改為評估每個命令。此範例執行測試套件並使用列出的這三個工具修復失敗：
300 300
301```bash theme={null}301```bash theme={null}
302claude -p "Run the test suite and fix any failures" \302claude -p "Run the test suite and fix any failures" \
303 --allowedTools "Bash,Read,Edit"303 --allowedTools "Bash,Read,Edit"
304```304```
305 305
306若要為整個工作階段設定基準而不是列出個別工具，請傳遞[權限模式](/docs/zh-TW/permission-modes)。對於 `-p`，[內建啟動權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)在每個計畫上都是 Manual，因此傳遞您想要的權限模式：306若要為整個工作階段設定基準而不是列出個別工具，請傳遞[權限模式](/docs/zh-TW/permission-modes)。未設定權限模式的執行採用[內建啟動權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)，可能是 `auto`，因此傳遞您想要的：
307 307
308* **`auto`**：傳遞 `--permission-mode auto` 以讓分類器審查大多數操作，而不是您308* **`auto`**：傳遞 `--permission-mode auto` 以讓分類器審查大多數操作，而不是您
309* **`dontAsk`**：Claude Code 拒絕每個會提示的呼叫，這對鎖定的 CI 執行很有用。在 Manual 模式中不需要批准的操作仍會執行，例如在您的工作目錄中讀取檔案和[唯讀命令集](/docs/zh-TW/permissions#read-only-commands)，以及您的 `--allowedTools` 項目或 `permissions.allow` 規則涵蓋的操作。`AskUserQuestion`、connector 工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使在允許規則匹配時也被拒絕309* **`dontAsk`**：Claude Code 拒絕每個會以其他方式提示的呼叫，這對鎖定的 CI 執行很有用。在 Manual 模式中不需要核准的操作仍會執行，例如在您的工作目錄中讀取檔案和[唯讀命令集](/docs/zh-TW/permissions#read-only-commands)，您的 `--allowedTools` 項目或 `permissions.allow` 規則涵蓋的操作也會執行。`AskUserQuestion`、連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使在允許規則符合時也會被拒絕
310* **`acceptEdits`**：Claude 寫入檔案而無需提示，Claude Code 自動批准常見的檔案系統命令，例如 `mkdir`、`touch`、`mv` 和 `cp`。[沒有模式自動批准的操作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)仍然適用。除了唯讀命令集，其他 shell 命令和網路請求仍需要 `--allowedTools` 項目或 `permissions.allow` 規則。請參閱[`acceptEdits` 自動批准的內容](/docs/zh-TW/permission-modes#auto-approve-file-edits-with-acceptedits-mode)以取得完整清單310* **`acceptEdits`**：Claude 寫入檔案而無需提示，Claude Code 自動核准常見的檔案系統命令，例如 `mkdir`、`touch`、`mv` 和 `cp`。[沒有模式自動核准的操作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)仍然適用。除了唯讀命令集，其他 shell 命令和網路請求仍需要 `--allowedTools` 項目或 `permissions.allow` 規則。請參閱[`acceptEdits` 自動核准的內容](/docs/zh-TW/permission-modes#auto-approve-file-edits-with-acceptedits-mode)以取得完整清單
311 311
312此範例使用 `acceptEdits` 作為基準應用 lint 修復：312此範例以 `acceptEdits` 作為基準應用 lint 修復：
313 313
314```bash theme={null}314```bash theme={null}
315claude -p "Apply the lint fixes" --permission-mode acceptEdits315claude -p "Apply the lint fixes" --permission-mode acceptEdits
316```316```
317 317
318<h3 id="turn-off-permission-prompts-in-unattended-runs">318<h3 id="turn-off-permission-prompts-in-unattended-runs">
319 在無人值守執行中關閉權限提示319 在無人值守的執行中關閉權限提示
320</h3>320</h3>
321 321
322當沒有人可用於回答權限提示時，傳遞 `--permission-prompts none`，例如在排程工作中。當您的執行有權限主機時，該旗標最重要：具有 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input)的 Agent SDK 應用程式，或您使用 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 傳遞的 MCP 工具。沒有該旗標，您的執行會等待該主機回答每個權限請求。322當沒有人可用於回答權限提示時，傳遞 `--permission-prompts none`，例如在排程的工作中。當您的執行有權限主機時，該旗標最重要：具有 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input)的 Agent SDK 應用程式，或您使用 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 傳遞的 MCP 工具。沒有該旗標，您的執行會等待該主機回答每個權限請求。
323 323
324使用該旗標，您的執行不會查詢主機或等待它。任何會提示的內容都被拒絕，除非 `PermissionRequest` hook 允許它，Claude 被告知沒有人可以批准請求且不應重試它，執行繼續。在沒有主機的 `-p` 執行中，這些請求無論如何都被拒絕，該旗標也告知 Claude 不要重試它們。權限規則、[`PermissionRequest` hooks](/docs/zh-TW/hooks#permissionrequest) 和您設定的權限模式仍然首先決定每個呼叫；Claude Code 僅拒絕其他任何內容都無法解決的請求。324使用該旗標，您的執行不會查詢主機或等待它。任何會提示的內容都會被拒絕，除非 `PermissionRequest` hook 允許它，Claude 被告知沒有人可以核准請求且不應重試它，執行會繼續。在沒有主機的 `-p` 執行中，這些請求無論如何都會被拒絕，該旗標也會告訴 Claude 不要重試它們。權限規則、[`PermissionRequest` hooks](/docs/zh-TW/hooks#permissionrequest) 和您設定的權限模式仍會首先決定每個呼叫；Claude Code 只拒絕其他任何內容都無法解決的請求。
325 325
326此範例在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中執行無人值守的任務。分類器照常審查每個操作，Claude Code 拒絕任何會回退到提示的內容：326此範例在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中執行無人值守的任務。分類器照常審查每個操作，Claude Code 拒絕任何會回退到提示的內容：
327 327
329claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none329claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none
330```330```
331 331
332使用 `--permission-prompts none`，Claude Code 移除需要來自人員的答案的工具，例如 [`AskUserQuestion`](/docs/zh-TW/tools-reference#askuserquestion-tool-behavior)，因此 Claude 無法呼叫它們。任何沒有 [`Elicitation` hook](/docs/zh-TW/hooks#elicitation) 回答的 [MCP 引出請求](/docs/zh-TW/mcp#respond-to-mcp-elicitation-requests)都被取消。332使用 `--permission-prompts none`，Claude Code 會移除需要來自人員的答案的工具，例如 [`AskUserQuestion`](/docs/zh-TW/tools-reference#askuserquestion-tool-behavior)，因此 Claude 無法呼叫它們。任何沒有 [`Elicitation` hook](/docs/zh-TW/hooks#elicitation) 回答的 [MCP 引出請求](/docs/zh-TW/mcp#respond-to-mcp-elicitation-requests)都會被取消。
333 333
334使用 `--output-format stream-json`，拒絕顯示為 `permission_denied` 系統訊息，最終結果訊息在 `permission_denials` 中列出它們。334使用 `--output-format stream-json` 時，拒絕會顯示為 `permission_denied` 系統訊息，最終結果訊息在 `permission_denials` 中列出它們。
335 335
336<Note>336<Note>
337 `--permission-prompts` 旗標需要 Claude Code v2.1.259 或更新版本。較早版本以未知選項錯誤拒絕它。337 `--permission-prompts` 旗標需要 Claude Code v2.1.259 或更新版本。較早版本會以未知選項錯誤拒絕它。
338</Note>338</Note>
339 339
340<h3 id="create-a-commit">340<h3 id="create-a-commit">
348 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"348 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
349```349```
350 350
351`--allowedTools` 旗標使用[權限規則語法](/docs/zh-TW/settings-reference#permission-rule-syntax)。尾部的 ` *` 啟用前綴匹配，因此 `Bash(git diff *)` 允許任何以 `git diff` 開頭的命令。空格在 `*` 之前很重要：沒有它，`Bash(git diff*)` 也會匹配 `git diff-index`。351`--allowedTools` 旗標使用[權限規則語法](/docs/zh-TW/settings-reference#permission-rule-syntax)。尾部的 ` *` 啟用前綴匹配，因此 `Bash(git diff *)` 允許任何以 `git diff` 開頭的命令。空格在 `*` 之前很重要：沒有它，`Bash(git diff*)` 也會符合 `git diff-index`。
352 352
353<Note>353<Note>
354 命令支援在 `-p` 模式中有所不同：354 命令支援在 `-p` 模式中有所不同：
355 355
356 * 使用者調用的 [skills](/docs/zh-TW/skills) 和自訂命令有效。在提示字串中包含 `/skill-name`，Claude Code 在執行前展開它。356 * 使用者叫用的 [skills](/docs/zh-TW/skills) 和自訂命令有效。在提示字串中包含 `/skill-name`，Claude Code 會在執行前展開它。
357 * 僅在終端介面中執行的內建命令，例如 `/login`，不可用。357 * 只在終端機介面中執行的內建命令（例如 `/login`）不可用。
358 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename` 接受值作為引數，例如 `/model sonnet`，`/mcp` 不帶引數列印伺服器狀態的文字摘要。這些形式需要 Claude Code v2.1.205 或更新版本，並遵循每個命令的[可用性注意事項](/docs/zh-TW/commands#all-commands)。358 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename` 接受值作為引數，例如 `/model sonnet`，`/mcp` 不帶引數會列印伺服器狀態的文字摘要。這些形式需要 Claude Code v2.1.205 或更新版本，並遵循每個命令的[可用性注意事項](/docs/zh-TW/commands#all-commands)。
359 * 若要變更設定，將 `key=value` 傳遞給 `/config`，例如 `/config thinking=false`。359 * 若要變更設定，請將 `key=value` 傳遞給 `/config`，例如 `/config thinking=false`。
360 * `/output-style <style>` 切換[輸出樣式](/docs/zh-TW/output-styles)，`/output-style` 單獨列出它們。需要 Claude Code v2.1.269 或更新版本。360 * `/output-style <style>` 切換[輸出樣式](/docs/zh-TW/output-styles)，`/output-style` 單獨列出它們。需要 Claude Code v2.1.269 或更新版本。
361</Note>361</Note>
362 362
364 自訂系統提示364 自訂系統提示
365</h3>365</h3>
366 366
367使用 `--append-system-prompt` 添加指示同時保持 Claude Code 的預設行為。此範例將 PR 差異傳輸到 Claude 並指示它審查安全漏洞。將其儲存為 shell 指令碼，例如 `review.sh`：367使用 `--append-system-prompt` 在保持 Claude Code 預設行為的同時新增指示。此範例將 PR 差異管道傳輸到 Claude，並指示它審查安全漏洞。將其儲存為 shell 指令碼，例如 `review.sh`：
368 368
369```bash theme={null}369```bash theme={null}
370gh pr diff "$1" | claude -p \370gh pr diff "$1" | claude -p \
372 --output-format json372 --output-format json
373```373```
374 374
375在指令碼中，`"$1"` 代表您在命令列上傳遞的第一個引數。執行 `bash review.sh 123`，shell 將 `"$1"` 替換為 `123`，因此指令碼會擷取 PR 123 的差異。Claude Code 以 JSON 格式列印審查，文字在 `result` 欄位中。375在指令碼中，`"$1"` 代表您在命令列上傳遞的第一個引數。執行 `bash review.sh 123`，shell 會將 `"$1"` 替換為 `123`，因此指令碼會擷取 PR 123 的差異。Claude Code 以 JSON 形式列印審查，文字在 `result` 欄位中。
376 376
377有關更多選項，請參閱[系統提示旗標](/docs/zh-TW/cli-reference#system-prompt-flags)，包括 `--system-prompt` 以完全替換預設提示。377請參閱[系統提示旗標](/docs/zh-TW/cli-reference#system-prompt-flags)以取得更多選項，包括 `--system-prompt` 以完全取代預設提示。
378 378
379<h3 id="continue-conversations">379<h3 id="continue-conversations">
380 繼續對話380 繼續對話
381</h3>381</h3>
382 382
383使用 `--continue` 繼續最近的對話，或使用 `--resume` 搭配工作階段 ID 繼續特定對話。在 Claude Code v2.1.257 或更新版本上，當您傳遞 `--continue` 時，Claude Code 開啟已完成但未仍在執行的[背景工作階段](/docs/zh-TW/sessions#resume-a-session)。此範例執行審查，然後傳送後續提示：383使用 `--continue` 繼續最近的對話，或使用 `--resume` 搭配工作階段 ID 繼續特定對話。在 Claude Code v2.1.257 或更新版本上，當您傳遞 `--continue` 時，Claude Code 會開啟已完成但仍在執行的[背景工作階段](/docs/zh-TW/sessions#resume-a-session)。此範例執行審查，然後傳送後續提示：
384 384
385```bash theme={null}385```bash theme={null}
386# First request386# First request
391claude -p "Generate a summary of all issues found" --continue391claude -p "Generate a summary of all issues found" --continue
392```392```
393 393
394如果您執行多個對話，擷取工作階段 ID 以繼續特定對話：394如果您執行多個對話，請擷取工作階段 ID 以繼續特定對話：
395 395
396```bash theme={null}396```bash theme={null}
397session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')397session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
398claude -p "Continue that review" --resume "$session_id"398claude -p "Continue that review" --resume "$session_id"
399```399```
400 400
401您可以從不同的目錄執行這兩個命令：Claude Code [按其 ID 找到工作階段](/docs/zh-TW/sessions#resume-a-session)在此機器上的任何專案中。在 v2.1.223 之前，Claude Code 僅在目前專案目錄及其 git worktrees 中尋找 ID，因此您必須從同一目錄執行兩個命令。401您可以從不同的目錄執行這兩個命令：Claude Code [按其 ID 在此機器上的任何專案中找到工作階段](/docs/zh-TW/sessions#resume-a-session)。在 v2.1.223 之前，Claude Code 只在目前專案目錄及其 git worktrees 中尋找 ID，因此您必須從同一目錄執行兩個命令。
402 402
403代替工作階段 ID，您可以將 `--resume` 傳遞工作階段的 `.jsonl` [文字記錄檔案](/docs/zh-TW/sessions#where-transcripts-are-stored)的絕對路徑，Claude Code 繼續儲存在該檔案中的對話。403您可以將工作階段的絕對路徑傳遞給 `--resume`，而不是工作階段 ID，該路徑指向工作階段的 `.jsonl` [文字記錄檔](/docs/zh-TW/sessions#where-transcripts-are-stored)，Claude Code 會繼續儲存在該檔案中的對話。
404 404
405<h2 id="next-steps">405<h2 id="next-steps">
406 後續步驟406 後續步驟
