Documentation — Spybara

admin-setup.md +1 −0

Details

106| [Disable claude.ai sync](/docs/zh-TW/settings-reference#syncclaudeaiskills) | 停止 Claude Code 載入[skills](/docs/zh-TW/skills#how-synced-skills-behave)和[外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)您的開發人員在 claude.ai 上啟用。如果您為組織關閉 claude.ai 上的 Skills，Claude Code 會停止同步兩者，在 v2.1.273 或更新版本上，它也會移除已同步的。若要在不關閉 Skills 的情況下停止其中任一個，請在受管設定中將其鍵設定為 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |106| [Disable claude.ai sync](/docs/zh-TW/settings-reference#syncclaudeaiskills) | 停止 Claude Code 載入[skills](/docs/zh-TW/skills#how-synced-skills-behave)和[外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)您的開發人員在 claude.ai 上啟用。如果您為組織關閉 claude.ai 上的 Skills，Claude Code 會停止同步兩者，在 v2.1.273 或更新版本上，它也會移除已同步的。若要在不關閉 Skills 的情況下停止其中任一個，請在受管設定中將其鍵設定為 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |

107| [Hook restrictions](/docs/zh-TW/settings-reference#allowmanagedhooksonly) | 限制哪些 hooks 執行並限制 HTTP hook URL；請參閱[在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以了解完整的效果清單 | `allowManagedHooksOnly`、`allowedHttpHookUrls` |107| [Hook restrictions](/docs/zh-TW/settings-reference#allowmanagedhooksonly) | 限制哪些 hooks 執行並限制 HTTP hook URL；請參閱[在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以了解完整的效果清單 | `allowManagedHooksOnly`、`allowedHttpHookUrls` |

108| [Login enforcement](/docs/zh-TW/settings-reference#forceloginmethod) | 限制登入為特定方法或 Anthropic 組織。方法限制適用於 VS Code 擴充功能、Agent SDK、`claude setup-token` 和 `/install-github-app`，以及終端的互動式登入畫面（透過 `/login` 或首次執行上線到達），預先選擇方法而不強制執行；Claude Code 驗證終端、VS Code 擴充功能和 Agent SDK 中 claude.ai 帳戶登入的組織，不檢查 Claude Console 登入或[閘道](/docs/zh-TW/claude-apps-gateway)登入。在 v2.1.212 之前，只有終端登入應用任一鍵。設定時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的會話在啟動時被阻止；雲端提供者會話不受影響，除非這些認證之一或由較早的 Claude Console 登入儲存的 API 金鑰也存在 | `forceLoginMethod`、`forceLoginOrgUUID` |108| [Login enforcement](/docs/zh-TW/settings-reference#forceloginmethod) | 限制登入為特定方法或 Anthropic 組織。方法限制適用於 VS Code 擴充功能、Agent SDK、`claude setup-token` 和 `/install-github-app`，以及終端的互動式登入畫面（透過 `/login` 或首次執行上線到達），預先選擇方法而不強制執行；Claude Code 驗證終端、VS Code 擴充功能和 Agent SDK 中 claude.ai 帳戶登入的組織，不檢查 Claude Console 登入或[閘道](/docs/zh-TW/claude-apps-gateway)登入。在 v2.1.212 之前，只有終端登入應用任一鍵。設定時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的會話在啟動時被阻止；雲端提供者會話不受影響，除非這些認證之一或由較早的 Claude Console 登入儲存的 API 金鑰也存在 | `forceLoginMethod`、`forceLoginOrgUUID` |

109| [Provider restrictions](/docs/zh-TW/settings-reference#allowedproviders) | 限制機器可能使用的 API 提供者。不在列表中的提供者上的會話在啟動時、登入時以及下次聯絡 API 時被拒絕。需要 Claude Code v2.1.285 或更新版本 | `allowedProviders` |

110| [Configure the corporate launcher](/docs/zh-TW/corporate-launcher) | 使用必需的公司啟動器作為[背景代理監督員](/docs/zh-TW/agent-view#how-background-sessions-are-hosted)、其工作者和[其他涵蓋的背景程序](/docs/zh-TW/corporate-launcher#what-the-launcher-covers)的前綴，而不是關閉代理檢視 | `processWrapper` |111| [Configure the corporate launcher](/docs/zh-TW/corporate-launcher) | 使用必需的公司啟動器作為[背景代理監督員](/docs/zh-TW/agent-view#how-background-sessions-are-hosted)、其工作者和[其他涵蓋的背景程序](/docs/zh-TW/corporate-launcher#what-the-launcher-covers)的前綴，而不是關閉代理檢視 | `processWrapper` |

111| [Model restrictions](/docs/zh-TW/model-config#restrict-model-selection) | `availableModels` 篩選模型選擇器中出現的模型。新增 `enforceAvailableModels` 也會限制自動選擇的預設模型。請參閱[表面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)以了解此設定如何到達 CLI、網頁和 IDE | `availableModels`、`enforceAvailableModels` |112| [Model restrictions](/docs/zh-TW/model-config#restrict-model-selection) | `availableModels` 篩選模型選擇器中出現的模型。新增 `enforceAvailableModels` 也會限制自動選擇的預設模型。請參閱[表面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)以了解此設定如何到達 CLI、網頁和 IDE | `availableModels`、`enforceAvailableModels` |

agent-sdk/hooks.md +6 −2

Details

418 ```418 ```

419</CodeGroup>419</CodeGroup>

420 420

421若要確認阻止，請在 `PreToolUse` 下使用 `Write|Edit` 匹配器註冊回調，並要求代理在 `/etc` 下建立檔案：Write 工具在訊息流中的結果包含 `Writing to /etc is not allowed`，且不會建立任何檔案。

422

421<h3 id="auto-approve-specific-tools">423<h3 id="auto-approve-specific-tools">

422 自動批准特定工具424 自動批准特定工具

423</h3>425</h3>

468 470

469當事件觸發時，所有匹配的 hooks 並行執行。對於權限決定，最嚴格的結果獲勝：單個 `deny` 會阻止工具呼叫，無論其他 hooks 返回什麼。由於完成順序是不確定的，請編寫每個 hook 以獨立行動，而不是依賴另一個 hook 已執行。471當事件觸發時，所有匹配的 hooks 並行執行。對於權限決定，最嚴格的結果獲勝：單個 `deny` 會阻止工具呼叫，無論其他 hooks 返回什麼。由於完成順序是不確定的，請編寫每個 hook 以獨立行動，而不是依賴另一個 hook 已執行。

470 472

471下面的範例為每個工具呼叫註冊三個獨立檢查：473下面的範例為每個工具呼叫註冊三個獨立檢查。範例中的 hook 名稱，例如 Python 中的 `audit_logger` 或 TypeScript 中的 `auditLogger`，代表您定義的回調：

472 474

473<CodeGroup>475<CodeGroup>

474 ```python Python theme={null}476 ```python Python theme={null}

500 使用多工具匹配器篩選502 使用多工具匹配器篩選

501</h3>503</h3>

502 504

503使用多工具匹配器在相關工具間共享一個回調。此範例註冊三個具有不同範圍的匹配器：505使用多工具匹配器在相關工具間共享一個回調。此範例註冊三個具有不同範圍的匹配器，每個 hook 它命名代表您定義的回調：

504 506

505* 管道分隔的精確列表（`Write|Edit|NotebookEdit`）僅針對檔案修改工具觸發 `file_security_hook`。507* 管道分隔的精確列表（`Write|Edit|NotebookEdit`）僅針對檔案修改工具觸發 `file_security_hook`。

506* 正規表達式（`^mcp__`）針對任何名稱以 `mcp__` 開頭的 MCP 工具觸發 `mcp_audit_hook`。508* 正規表達式（`^mcp__`）針對任何名稱以 `mcp__` 開頭的 MCP 工具觸發 `mcp_audit_hook`。

585 ```587 ```

586</CodeGroup>588</CodeGroup>

587 589

590若要確認 hook 觸發，請註冊回調並要求代理將小任務委派給子代理，例如列出目前目錄中的檔案：當子代理完成時，回調會列印 `[SUBAGENT] Completed:` 行，其中包含子代理的 ID 和文字記錄路徑。

591

588<h3 id="make-http-requests-from-hooks">592<h3 id="make-http-requests-from-hooks">

589 從 hooks 發出 HTTP 請求593 從 hooks 發出 HTTP 請求

590</h3>594</h3>

agent-sdk/permissions.md +9 −0

Details

121 121

122權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 `query()` 時設定權限模式，或在串流工作階段期間動態變更它。122權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 `query()` 時設定權限模式，或在串流工作階段期間動態變更它。

123 123

124如果您未設定權限模式，Claude Code 會根據[工作階段開始時的模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)中的規則選擇起始權限模式：

125

126* 工作階段的[設定檔](/docs/zh-TW/settings#where-settings-live)中的 `permissions.defaultMode`（如果適用）

127* 否則為內建預設值，可以是[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)

128

129在自動模式中開始的工作階段會捨棄廣泛的允許規則，例如裸露的 `Bash` 項目，如[自動模式如何評估動作](/docs/zh-TW/permission-modes#how-auto-mode-evaluates-actions)所述。如果您的應用程式依賴 `default` 模式或此類規則，請明確傳遞 `default`。

130

131在 TypeScript Agent SDK v0.3.286 之前，省略 `permissionMode` 與傳遞 `default` 相同。

132

124<h3 id="available-modes">133<h3 id="available-modes">

125 可用模式134 可用模式

126</h3>135</h3>

agent-sdk/python.md +216 −77

Details

530 530

531| 方法 | 描述 |531| 方法 | 描述 |

532| :- | :- |532| :- | :- |

541| `rewind_files(user_message_id)` | 將檔案還原到指定使用者消息時的狀態。需要 `enable_file_checkpointing=True`。見 [檔案 checkpointing](/docs/zh-TW/agent-sdk/file-checkpointing) |541| `rewind_files(user_message_id)` | 將檔案還原到指定使用者訊息時的狀態。需要 `enable_file_checkpointing=True`。見 [檔案 checkpointing](/docs/zh-TW/agent-sdk/file-checkpointing) |

548 548

567asyncio.run(main())567asyncio.run(main())

568```568```

569 569

570> **重要：** 在迭代消息時，避免使用 `break` 提前退出，因為這可能導致 asyncio 清理問題。相反，讓迭代自然完成或使用標誌來追蹤何時找到所需內容。570> **重要：** 在迭代訊息時，避免使用 `break` 提前退出，因為這可能導致 asyncio 清理問題。相反，讓迭代自然完成或使用旗標來追蹤何時找到所需內容。

571 571

572<h4 id="example-continuing-a-conversation">572<h4 id="example-continuing-a-conversation">

573 範例 - 繼續對話573 範例 - 繼續對話

616 範例 - 使用 ClaudeSDKClient 進行串流輸入616 範例 - 使用 ClaudeSDKClient 進行串流輸入

617</h4>617</h4>

618 618

619`query()` 也接受使用者訊息字典的非同步可迭代物件，因此您可以在傳送時組合提示或包含內容區塊，例如影像。Claude Code 會在第一個產生的訊息到達時立即開始回應，無需等待可迭代物件完成，而 `receive_response()` 會在結束該回應的 `ResultMessage` 處停止。將 Claude 應該在回答前讀取的所有內容放入一個訊息中，如此產生器所做的，並將每個 `query()` 呼叫與其自己的 `receive_response()` 迴圈配對。

620

619```python theme={null}621```python theme={null}

620import asyncio622import asyncio

621from claude_agent_sdk import ClaudeSDKClient623from claude_agent_sdk import ClaudeSDKClient

622 624

623 625

624async def message_stream():626async def message_stream():

625 """Generate messages dynamically."""627 """Assemble the prompt at send time and yield it as one user message."""

626 yield {628 readings = {"Temperature": "25°C", "Humidity": "60%"}

627 "type": "user",629 data = ", ".join(f"{name}: {value}" for name, value in readings.items())

628 "message": {"role": "user", "content": "Analyze the following data:"},

629 }

630 await asyncio.sleep(0.5)

631 yield {

632 "type": "user",

633 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},

634 }

635 await asyncio.sleep(0.5)

636 yield {630 yield {

637 "type": "user",631 "type": "user",

638 "message": {"role": "user", "content": "What patterns do you see?"},632 "message": {

633 "role": "user",

634 "content": f"Analyze the following sensor data and describe any patterns you see: {data}",

635 },

639 }636 }

640 637

641 638

701```698```

702 699

703<Note>700<Note>

704 **中斷後的緩衝區行為：** `interrupt()` 發送停止信號但不清除消息緩衝區。已由中斷任務產生的消息，包括其 `ResultMessage`，保留在流中。您必須在讀取新查詢的回應之前使用 `receive_response()` 清空它們。如果您在 `interrupt()` 之後立即發送新查詢並僅呼叫一次 `receive_response()`，您將收到中斷任務的消息，而不是新查詢的回應。701 **中斷後的緩衝區行為：** `interrupt()` 發送停止信號但不清除訊息緩衝區。已由中斷任務產生的訊息，包括其 `ResultMessage`，保留在流中。您必須在讀取新查詢的回應之前使用 `receive_response()` 清空它們。如果您在 `interrupt()` 之後立即發送新查詢並僅呼叫一次 `receive_response()`，您將收到中斷任務的訊息，而不是新查詢的回應。

705</Note>702</Note>

706 703

707<h4 id="example-advanced-permission-control">704<h4 id="example-advanced-permission-control">

2712 2709

2713所有內建 Claude Code 工具的輸入/輸出結構描述文件。雖然 Python SDK 不會將這些匯出為類型，但它們代表訊息中工具輸入和輸出的結構。2710所有內建 Claude Code 工具的輸入/輸出結構描述文件。雖然 Python SDK 不會將這些匯出為類型，但它們代表訊息中工具輸入和輸出的結構。

2714 2711

2712每個顯示的輸出是您從該工具的 [`UserMessage.tool_use_result`](#usermessage) 讀取的值。鍵名完全按照 Claude Code 發出的方式出現。標註為 `| None` 且帶有「出現時」或「選擇性」註釋的鍵在不適用時會被省略。

2713

2715<h3 id="agent">2714<h3 id="agent">

2716 Agent2715 Agent

2717</h3>2716</h3>

2885 2884

2886**工具名稱：** `Bash`2885**工具名稱：** `Bash`

2887 2886

2888如需了解設定前景上限的內容，請參閱 [逾時和輸出限制](/docs/zh-TW/tools-reference#timeout-and-output-limits)。如需了解背景時間限制，請參閱 [背景命令](/docs/zh-TW/tools-reference#background-commands)。2887如需了解設定前景上限的內容，請參閱 [逾時和輸出限制](/docs/zh-TW/tools-reference#timeout-and-output-limits)。如需了解背景時間限制，請參閱 [背景命令的時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)。

2889 2888

2890**輸入：**2889**輸入：**

2891 2890

2962 2961

2963```python theme={null}2962```python theme={null}

2964{2963{

2965 "message": str, # 確認訊息2964 "filePath": str, # 被編輯的檔案

2966 "replacements": int, # 進行的替換次數2965 "oldString": str, # 被替換的文字

2967 "file_path": str, # 被編輯的檔案路徑2966 "newString": str, # 替換它的文字

2967 "originalFile": str | None, # 編輯前的檔案內容

2968 "structuredPatch": [ # 變更的 Diff 區塊

2969 {

2970 "oldStart": int,

2971 "oldLines": int,

2972 "newStart": int,

2973 "newLines": int,

2974 "lines": list[str],

2975 }

2976 ],

2977 "userModified": bool, # 使用者是否在接受前變更了建議的編輯

2978 "replaceAll": bool, # 是否替換了所有出現次數

2979 "gitDiff": { # 檔案的選擇性 git diff 摘要

2980 "filename": str,

2981 "status": "modified" | "added",

2982 "additions": int,

2983 "deletions": int,

2984 "changes": int,

2985 "patch": str,

2986 "repository": str | None, # 可用時的 GitHub owner/repo

2987 } | None,

2968}2988}

2969```2989```

2970 2990

2984}3004}

2985```3005```

2986 3006

2987**輸出（文字檔案）：**3007輸出根據 Claude 讀取的內容採用以下形式之一。檢查 `type` 鍵以區分它們。

3008

3009**輸出（type: `"text"`）：**

2988 3010

2989```python theme={null}3011```python theme={null}

2990{3012{

2991 "content": str, # 帶有行號的檔案內容3013 "type": "text",

2992 "total_lines": int, # 檔案中的總行數3014 "file": {

2993 "lines_returned": int, # 實際返回的行數3015 "filePath": str, # 被讀取的檔案

3016 "content": str, # 返回的內容

3017 "numLines": int, # 返回內容中的行數

3018 "startLine": int, # 內容開始的行號

3019 "totalLines": int, # 檔案中的總行數

3020 "truncatedByTokenCap": bool | None, # 當整個檔案讀取超過令牌上限且內容是第一頁時出現且為 True

3021 },

2994}3022}

2995```3023```

2996 3024

2997**輸出（影像）：**3025**輸出（type: `"image"`）：**

2998 3026

2999```python theme={null}3027```python theme={null}

3000{3028{

3001 "image": str, # Base64 編碼的影像資料3029 "type": "image",

3002 "mime_type": str, # 影像 MIME 類型3030 "file": {

3003 "file_size": int, # 檔案大小（位元組）3031 "base64": str, # Base64 編碼的影像資料

3032 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # 影像 MIME 類型

3033 "originalSize": int, # 原始檔案大小（位元組）

3034 "dimensions": { # 座標對應的選擇性大小資訊

3035 "originalWidth": int | None, # 選擇性；原始寬度（像素）

3036 "originalHeight": int | None, # 選擇性；原始高度（像素）

3037 "displayWidth": int | None, # 選擇性；調整大小後的寬度

3038 "displayHeight": int | None, # 選擇性；調整大小後的高度

3039 } | None,

3040 },

3041}

3042```

3043

3044**輸出（type: `"notebook"`）：**

3045

3046```python theme={null}

3047{

3048 "type": "notebook",

3049 "file": {

3050 "filePath": str, # 被讀取的筆記本

3051 "cells": list, # 筆記本儲存格

3052 },

3053}

3054```

3055

3056**輸出（type: `"pdf"`）：**

3057

3058```python theme={null}

3059{

3060 "type": "pdf",

3061 "file": {

3062 "filePath": str, # 被讀取的 PDF

3063 "base64": str, # Base64 編碼的 PDF 資料

3064 "originalSize": int, # 檔案大小（位元組）

3065 },

3066}

3067```

3068

3069**輸出（type: `"parts"`）：**

3070

3071```python theme={null}

3072{

3073 "type": "parts",

3074 "file": {

3075 "filePath": str, # 被讀取的 PDF

3076 "originalSize": int, # 檔案大小（位元組）

3077 "count": int, # 提取為影像的頁數

3078 "outputDir": str, # 包含提取的頁面影像的目錄

3079 },

3080 "firstPage": int | None, # 選擇性文件頁碼的第一個提取頁面

3081}

3082```

3083

3084**輸出（type: `"file_unchanged"`）：**

3085

3086```python theme={null}

3087{

3088 "type": "file_unchanged", # 檔案自 Claude 在此工作階段中上次讀取以來未變更，因此內容不會重複

3089 "file": {

3090 "filePath": str,

3091 },

3092 "source": "seeded" | None, # 當較早的副本來自在啟動時載入的 CLAUDE.md 或記憶體檔案而不是 Read 呼叫時出現

3004}3093}

3005```3094```

3006 3095

3023 3112

3024```python theme={null}3113```python theme={null}

3025{3114{

3026 "message": str, # 成功訊息3115 "type": "create" | "update", # 寫入是建立新檔案還是覆蓋現有檔案

3027 "bytes_written": int, # 寫入的位元組數3116 "filePath": str, # 被寫入的檔案

3028 "file_path": str, # 被寫入的檔案路徑3117 "content": str, # 被寫入的內容

3118 "structuredPatch": [ # Diff 區塊；新檔案、未變更或 Claude Code 跳過 diff 時為空

3119 {

3120 "oldStart": int,

3121 "oldLines": int,

3122 "newStart": int,

3123 "newLines": int,

3124 "lines": list[str],

3125 }

3126 ],

3127 "originalFile": str | None, # 先前的內容；新檔案時為 None 或先前內容太大而無法包含時

3128 "gitDiff": { # 檔案的選擇性 git diff 摘要

3129 "filename": str,

3130 "status": "modified" | "added",

3131 "additions": int,

3132 "deletions": int,

3133 "changes": int,

3134 "patch": str,

3135 "repository": str | None, # 可用時的 GitHub owner/repo

3136 } | None,

3137 "userModified": bool | None, # 選擇性；使用者是否在接受前編輯了建議的內容

3029}3138}

3030```3139```

3031 3140

3048 3157

3049```python theme={null}3158```python theme={null}

3050{3159{

3051 "matches": list[str], # 相符檔案路徑的陣列3160 "durationMs": int, # 執行搜尋所花的時間（毫秒）

3052 "count": int, # 找到的相符項目數3161 "numFiles": int, # 返回的路徑數，任何截斷後

3053 "search_path": str, # 使用的搜尋目錄3162 "filenames": list[str], # 相符的檔案路徑

3163 "truncated": bool, # 結果是否在 100 檔案限制處被截斷

3164 "totalMatches": int | None, # 選擇性截斷前相符檔案的總數；當 countIsComplete 為 False 時為下限

3165 "countIsComplete": bool | None, # 選擇性；totalMatches 是否精確

3054}3166}

3055```3167```

3056 3168

3169`totalMatches` 和 `countIsComplete` 需要 Claude Code v2.1.191 或更新版本。

3170

3057<h3 id="grep">3171<h3 id="grep">

3058 Grep3172 Grep

3059</h3>3173</h3>

3074 "-B": int | None, # 每個相符項目前顯示的行數3188 "-B": int | None, # 每個相符項目前顯示的行數

3075 "-A": int | None, # 每個相符項目後顯示的行數3189 "-A": int | None, # 每個相符項目後顯示的行數

3076 "-C": int | None, # 每個相符項目前後顯示的行數3190 "-C": int | None, # 每個相符項目前後顯示的行數

3191 "context": int | None, # 每個相符項目前後顯示的行數；-C 是別名

3192 "-o": bool | None, # 僅列印每行的相符部分

3077 "head_limit": int | None, # 將輸出限制為前 N 行/項目3193 "head_limit": int | None, # 將輸出限制為前 N 行/項目

3194 "offset": int | None, # 在套用 head_limit 前跳過前 N 行/項目

3078 "multiline": bool | None, # 啟用多行模式3195 "multiline": bool | None, # 啟用多行模式

3079}3196}

3080```3197```

3081 3198

3082**輸出（內容模式）：**3199**輸出：**

3083 3200

3084```python theme={null}3201```python theme={null}

3085{3202{

3086 "matches": [3203 "mode": "content" | "files_with_matches" | "count" | None, # 使用的輸出模式

3087 {3204 "numFiles": int, # 結果中的檔案數；內容模式中始終為 0

3088 "file": str,3205 "filenames": list[str], # files_with_matches 模式中的相符檔案；其他模式中為空

3089 "line_number": int | None,3206 "content": str | None, # 內容模式中的相符行，或計數模式中的每個檔案計數

3090 "line": str,3207 "numLines": int | None, # 內容中的行數，內容模式中出現

3091 "before_context": list[str] | None,3208 "numMatches": int | None, # 總相符計數，計數模式中出現

3092 "after_context": list[str] | None,3209 "totalFiles": int | None, # 選擇性 head_limit 和 offset 前的總數，files_with_matches 模式中

3093 }3210 "totalLines": int | None, # 選擇性 head_limit 和 offset 前的總數，內容模式中

3094 ],3211 "appliedLimit": int | None, # 當 head_limit 截斷結果時出現

3095 "total_matches": int,3212 "appliedOffset": int | None, # 當套用 offset 時出現

3096}3213}

3097```3214```

3098 3215

3099**輸出（files\_with\_matches 模式）：**3216Grep 在每個輸出模式中返回此 dict 形狀。哪些選擇性鍵出現取決於 `output_mode`。

3100 3217

3101```python theme={null}3218`totalFiles` 需要 Claude Code v2.1.208 或更新版本。`totalLines` 需要 Claude Code v2.1.210 或更新版本。

3102{

3103 "files": list[str], # 包含相符項目的檔案

3104 "count": int, # 包含相符項目的檔案數

3105}

3106```

3107 3219

3108<h3 id="notebookedit">3220<h3 id="notebookedit">

3109 NotebookEdit3221 NotebookEdit

3127 3239

3128```python theme={null}3240```python theme={null}

3129{3241{

3130 "message": str, # 成功訊息3242 "new_source": str, # 寫入儲存格的來源

3131 "edit_type": "replaced" | "inserted" | "deleted", # 執行的編輯類型3243 "old_source": str | None, # 先前的儲存格來源，替換和刪除時出現

3132 "cell_id": str | None, # 受影響的儲存格 ID3244 "cell_id": str | None, # 編輯的儲存格的 ID，可用時

3133 "total_cells": int, # 編輯後筆記本中的總儲存格數3245 "cell_type": "code" | "markdown", # 儲存格類型

3246 "language": str, # 筆記本的程式設計語言

3247 "edit_mode": str, # 使用的編輯模式

3248 "error": str | None, # 操作失敗時的錯誤訊息

3249 "notebook_path": str, # 筆記本檔案

3250 "original_file": str, # 編輯前的筆記本內容

3251 "updated_file": str, # 編輯後的筆記本內容

3134}3252}

3135```3253```

3136 3254

3228 3346

3229```python theme={null}3347```python theme={null}

3230{3348{

3231 "message": str, # 成功訊息3349 "oldTodos": [ # 更新前的待辦事項列表

3232 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},3350 {

3351 "content": str,

3352 "status": "pending" | "in_progress" | "completed",

3353 "activeForm": str,

3354 }

3355 ],

3356 "newTodos": [ # 更新後的待辦事項列表

3357 {

3358 "content": str,

3359 "status": "pending" | "in_progress" | "completed",

3360 "activeForm": str,

3361 }

3362 ],

3233}3363}

3234```3364```

3235 3365

3401 3531

3402```python theme={null}3532```python theme={null}

3403{3533{

3404 "message": str, # 確認訊息3534 "plan": str | None, # 呈現給使用者的計畫

3405 "approved": bool | None, # 使用者是否核准計畫3535 "isAgent": bool, # 當子代理呼叫工具時為 True

3536 "filePath": str | None, # 當計畫被儲存到檔案時出現

3537 "hasTaskTool": bool | None, # 選擇性；Agent 工具是否在目前內容中可用

3538 "planWasEdited": bool | None, # 當使用者在核准前編輯計畫時出現且為 True

3539 "awaitingLeaderApproval": bool | None, # 當隊友將計畫傳送給團隊主管核准時出現且為 True

3540 "requestId": str | None, # 該核准請求的選擇性 ID

3406}3541}

3407```3542```

3408 3543

3420}3555}

3421```3556```

3422 3557

3558結果是列表而不是 dict，因此 `tool_use_result` 為此工具保留 `list`。

3559

3423**輸出：**3560**輸出：**

3424 3561

3425```python theme={null}3562```python theme={null}

3426{3563[ # 每個資源一個項目

3427 "resources": [

3428 {3564 {

3429 "uri": str,3565 "uri": str, # 資源 URI

3430 "name": str,3566 "name": str, # 資源名稱

3431 "description": str | None,3567 "mimeType": str | None, # 選擇性 MIME 類型

3432 "mimeType": str | None,3568 "description": str | None, # 選擇性描述

3433 "server": str,3569 "server": str, # 提供此資源的伺服器

3434 }3570 }

3435 ],3571]

3436 "total": int,

3437}

3438```3572```

3439 3573

3440<h3 id="readmcpresource">3574<h3 id="readmcpresource">

3457```python theme={null}3591```python theme={null}

3458{3592{

3459 "contents": [3593 "contents": [

3460 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}3594 {

3595 "uri": str, # 資源 URI

3596 "mimeType": str | None, # 選擇性 MIME 類型

3597 "text": str | None, # 文字內容，或關於二進位內容的註釋

3598 "blobSavedTo": str | None, # 當 Claude Code 將二進位內容儲存到磁碟時出現；儲存檔案的路徑

3599 }

3461 ],3600 ],

3462 "server": str,3601 "error": str | None, # 當伺服器無法讀取資源時出現

3463}3602}

3464```3603```

3465 3604

agent-sdk/typescript.md +61 −59

Details

546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 啟用略過權限。使用 `permissionMode: 'bypassPermissions'` 時需要，可在啟動時或稍後透過 `setPermissionMode()` 設定。請參閱[計畫模式](/docs/zh-TW/agent-sdk/permissions#plan-mode-plan)以了解它如何與 `permissionMode: 'plan'` 互動 |546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 啟用略過權限。使用 `permissionMode: 'bypassPermissions'` 時需要，可在啟動時或稍後透過 `setPermissionMode()` 設定。請參閱[Plan Mode](/docs/zh-TW/agent-sdk/permissions#plan-mode-plan)以了解它如何與 `permissionMode: 'plan'` 互動 |

547| `allowedTools` | `string[]` | `[]` | 自動核准而不提示的工具。這不會限制 Claude 只能使用這些工具。如果您在此處命名其中一個[任務追蹤工具](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會選擇加入工作階段。其他未列出的工具會根據 `permissionMode` 和 `canUseTool` 進行處理。使用 `disallowedTools` 來封鎖工具。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |547| `allowedTools` | `string[]` | `[]` | 自動核准而不提示的工具。這不會限制 Claude 只能使用這些工具。如果您在此處命名其中一個[任務追蹤工具](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會選擇加入工作階段。其他未列出的工具會根據 `permissionMode` 和 `canUseTool` 進行處理。使用 `disallowedTools` 來封鎖工具。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自訂權限函式，僅在[權限流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)落實到提示時叫用。不會針對由 `allowedTools`、允許規則或 `permissionMode` 自動核准的呼叫叫用。允許規則不會預先核准[任何模式都不自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)。請參閱 [`CanUseTool`](#canusetool) 以取得詳細資訊 |549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自訂權限函式，僅在[權限流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)落實到提示時叫用。不會針對由 `allowedTools`、允許規則或 `permissionMode` 自動核准的呼叫叫用。允許規則不會預先核准[任何模式都不自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)。請參閱 [`CanUseTool`](#canusetool) 以取得詳細資訊 |

554| `disallowedTools` | `string[]` | `[]` | 要拒絕的工具。裸名稱（例如 `"Bash"`）會從 Claude 的內容中移除工具。範圍規則（例如 `"Bash(rm *)"`）會保留工具可用，並在每個權限模式中拒絕符合的呼叫，包括 `bypassPermissions`，針對[如所寫的](/docs/zh-TW/permissions#bash-rule-limits)命令。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |554| `disallowedTools` | `string[]` | `[]` | 要拒絕的工具。裸名稱（例如 `"Bash"`）會從 Claude 的內容中移除工具。範圍規則（例如 `"Bash(rm *)"`）會保留工具可用，並在每個權限模式中拒絕符合的呼叫，包括 `bypassPermissions`，針對[如所寫的](/docs/zh-TW/permissions#bash-rule-limits)命令。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

557| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變數。設定時，這會取代子程序環境而不是與 `process.env` 合併，因此請傳遞 `{ ...process.env, YOUR_VAR: 'value' }` 以保留繼承的變數（例如 `PATH`）。請參閱[處理緩慢或停滯的 API 回應](#handle-slow-or-stalled-api-responses)以取得此模式的範例，以及[環境變數](/docs/zh-TW/env-vars)以了解基礎 CLI 讀取的變數。設定 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中識別您的應用程式 |557| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變數。設定時，這會取代子程序環境而不是與 `process.env` 合併，因此請傳遞 `{ ...process.env, YOUR_VAR: 'value' }` 以保留繼承的變數（例如 `PATH`）。請參閱[處理緩慢或停滯的 API 回應](#handle-slow-or-stalled-api-responses)以取得此模式的範例，以及[環境變數](/docs/zh-TW/env-vars)以了解基礎 CLI 讀取的變數。設定 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中識別您的應用程式 |

575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 定義代理結果的輸出格式。請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs)以取得詳細資訊 |575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 定義代理結果的輸出格式。請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs)以取得詳細資訊 |

580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 誰回答權限提示：`'host'` 將它們路由到您的 [`canUseTool`](#canusetool) 回呼或 `permissionPromptToolName` 工具，而 `'none'` [拒絕會提示的呼叫](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更新版本 |580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 誰回答權限提示：`'host'` 將它們路由到您的 [`canUseTool`](#canusetool) 回呼或 `permissionPromptToolName` 工具，而 `'none'` [拒絕會提示的呼叫](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更新版本 |

584| `projectConfigRoot` | `string` | `undefined` | `cwd` 是其 worktree 的受信任簽出的絕對路徑。Claude Code 從此目錄而不是 `cwd` 讀取專案設定、`.mcp.json` 和專案的 `.claude/` 命令、代理、技能、工作流程、例行程序和輸出樣式，並將 `CLAUDE_PROJECT_DIR` 設定為它。Hooks、協助程式指令碼（例如 `apiKeyHelper`）和 stdio MCP 伺服器以此目錄作為其工作目錄啟動。`CLAUDE.md` 檔案和 `.claude/rules/` 仍從 `cwd` 載入。需要 Claude Code v2.1.275 或更新版本 |584| `projectConfigRoot` | `string` | `undefined` | `cwd` 是其 worktree 的受信任簽出的絕對路徑。Claude Code 從此目錄而不是 `cwd` 讀取專案設定、`.mcp.json` 和專案的 `.claude/` 命令、代理、技能、工作流程、例行程序和輸出樣式，並將 `CLAUDE_PROJECT_DIR` 設定為它。Hooks、協助程式指令碼（例如 `apiKeyHelper`）和 stdio MCP 伺服器以此目錄作為其工作目錄啟動。`CLAUDE.md` 檔案和 `.claude/rules/` 仍從 `cwd` 載入。需要 Claude Code v2.1.275 或更新版本 |

585| `promptSuggestions` | `boolean` | `false` | 啟用提示建議。在回合後，Claude Code 會發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示。Claude Code 不會為某些回合（例如當您的帳戶接近或達到使用量限制時）產生建議。請參閱[Claude Code 何時跳過建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions) |585| `promptSuggestions` | `boolean` | `false` | 啟用提示建議。在回合後，Claude Code 會發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示。Claude Code 不會為某些回合（例如當您的帳戶接近或達到使用量限制時）產生建議。請參閱[Claude Code 何時跳過建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions) |

594| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 預設值（所有來源） | 控制要載入哪些檔案系統設定。傳遞 `[]` 以停用使用者、專案和本機設定。[端點管理的原則](/docs/zh-TW/managed-settings#delivery-mechanisms)無論如何都會載入；當工作階段使用組織認證在[合格設定](/docs/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。請參閱[使用 Claude Code 功能](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |594| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 預設值（所有來源） | 控制要載入哪些檔案系統設定。傳遞 `[]` 以停用使用者、專案和本機設定。[端點管理的原則](/docs/zh-TW/managed-settings#delivery-mechanisms)無論如何都會載入；當工作階段使用組織認證在[合格設定](/docs/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。請參閱[使用 Claude Code 功能](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

595| `skills` | `string[] \| 'all'` | `undefined` | 工作階段可用的技能。傳遞 `'all'` 以啟用每個發現的技能，或傳遞技能名稱清單。僅傳遞確切名稱。在 Agent SDK v0.3.221 或更新版本上，SDK 會在啟動 Claude Code 程序之前以錯誤拒絕格式不正確和萬用字元形式的名稱。設定時，SDK 會自動將 Skill 工具新增到 `allowedTools`。如果您也傳遞 `tools`，請在該清單中包含 `'Skill'`。請參閱[技能](/docs/zh-TW/agent-sdk/skills) |595| `skills` | `string[] \| 'all'` | `undefined` | 工作階段可用的技能。傳遞 `'all'` 以啟用每個發現的技能，或傳遞技能名稱清單。僅傳遞確切名稱。在 Agent SDK v0.3.221 或更新版本上，SDK 會在啟動 Claude Code 程序之前以錯誤拒絕格式不正確和萬用字元形式的名稱。設定時，SDK 會自動將 Skill 工具新增到 `allowedTools`。如果您也傳遞 `tools`，請在該清單中包含 `'Skill'`。請參閱[Skills](/docs/zh-TW/agent-sdk/skills) |

697| 方法 | 說明 |697| 方法 | 說明 |

698| :- | :- |698| :- | :- |

699| `interrupt()` | 中斷查詢。僅在串流輸入模式中可用。當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中公告 `interrupt_receipt_v1` 功能時，使用列出中斷到達時待處理的訊息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 進行解析。在 v2.1.205 之前的 CLI 上解析 `undefined` |699| `interrupt()` | 中斷查詢。僅在串流輸入模式中可用。當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中公告 `interrupt_receipt_v1` 功能時，使用列出中斷到達時待處理的訊息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 進行解析。在 v2.1.205 之前的 CLI 上解析 `undefined` |

700| `rewindFiles(userMessageId, options?)` | 將檔案還原到指定使用者訊息時的狀態。傳遞 `{ dryRun: true }` 以預覽變更。需要 `enableFileCheckpointing: true`。請參閱[檔案檢查點](/docs/zh-TW/agent-sdk/file-checkpointing) |700| `rewindFiles(userMessageId, options?)` | 將檔案還原到指定使用者訊息時的狀態。傳遞 `{ dryRun: true }` 以預覽變更。需要 `enableFileCheckpointing: true`。請參閱[檔案 checkpointing](/docs/zh-TW/agent-sdk/file-checkpointing) |

716| `reloadOutputStyles()` | 重新讀取[輸出樣式](/docs/zh-TW/output-styles)從磁碟，以便您在中期工作階段新增或編輯的樣式檔案可供執行中的工作階段使用。使用列出重新載入後可用的樣式名稱的 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 進行解析。需要 Agent SDK v0.3.261 或更新版本 |716| `reloadOutputStyles()` | 重新讀取[輸出樣式](/docs/zh-TW/output-styles)從磁碟，以便您在中期工作階段新增或編輯的樣式檔案可供執行中的工作階段使用。使用列出重新載入後可用的樣式名稱的 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 進行解析。需要 Agent SDK v0.3.261 或更新版本 |

718| `reconnectMcpServer(serverName)` | 按名稱重新連線 MCP 伺服器。如果名稱也符合設定檔（例如 `.mcp.json` 或 `~/.claude.json`）中的項目，Claude Code 會重新連線您透過 [`mcpServers`](#options) 或 `setMcpServers()` 設定的伺服器，而不是設定檔項目。該解析順序需要 Claude Code v2.1.257 或更新版本 |718| `reconnectMcpServer(serverName)` | 按名稱重新連線 MCP 伺服器。如果名稱也符合設定檔（例如 `.mcp.json` 或 `~/.claude.json`）中的項目，Claude Code 會重新連線您透過 [`mcpServers`](#options) 或 `setMcpServers()` 設定的伺服器，而不是設定檔項目。該解析順序需要 Claude Code v2.1.257 或更新版本 |

719| `toggleMcpServer(serverName, enabled)` | 按名稱啟用或停用 MCP 伺服器，名稱解析與 `reconnectMcpServer()` 相同。停用會中斷伺服器連線 |719| `toggleMcpServer(serverName, enabled)` | 按名稱啟用或停用 MCP 伺服器，名稱解析與 `reconnectMcpServer()` 相同。停用會中斷伺服器連線並移除其工具；對於您使用 `setMcpServers()` 在中期工作階段新增的伺服器，工具移除需要 Claude Code v2.1.285 或更新版本 |

720| `setMcpServers(servers)` | 動態取代此工作階段的 MCP 伺服器集合。使用命名已新增和移除的伺服器以及任何錯誤的 [`McpSetServersResult`](#mcpsetserversresult) 進行解析 |720| `setMcpServers(servers)` | 動態取代此工作階段的 MCP 伺服器集合。使用命名已新增和移除的伺服器以及任何錯誤的 [`McpSetServersResult`](#mcpsetserversresult) 進行解析 |

721| `readMcpResource(serverName, uri)` | *Alpha。* 從連線的 MCP 伺服器讀取一個 MCP Apps `ui://` 資源，以便您的應用程式可以呈現工具的小工具。使用 [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) 進行解析。需要 TypeScript Agent SDK v0.3.280 或更新版本 |721| `readMcpResource(serverName, uri)` | *Alpha。* 從連線的 MCP 伺服器讀取一個 MCP Apps `ui://` 資源，以便您的應用程式可以呈現工具的小工具。使用 [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) 進行解析。需要 TypeScript Agent SDK v0.3.280 或更新版本 |

1273 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt1273 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt

1274 | "plan" // Planning mode - explore without editing1274 | "plan" // Planning mode - explore without editing

1275 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved1275 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved

1276 | "auto"; // Model classifier approves or denies permission prompts1276 | "auto"; // A model classifier reviews actions such as shell commands and network requests

1277```1277```

1278 1278

1279<h3 id="canusetool">1279<h3 id="canusetool">

1467];1467];

1468```1468```

1469 1469

1470如需建立和使用外掛程式的完整資訊，請參閱[外掛程式](/docs/zh-TW/agent-sdk/plugins)。1470如需建立和使用外掛程式的完整資訊，請參閱[Plugins](/docs/zh-TW/agent-sdk/plugins)。

1471 1471

1472<h2 id="message-types">1472<h2 id="message-types">

1473 訊息類型1473 訊息類型

1847```typescript theme={null}1847```typescript theme={null}

1848type SDKStartupFailureReason =1848type SDKStartupFailureReason =

1849 | "org_pin_api_key_conflict"1849 | "org_pin_api_key_conflict"

1850 | "provider_not_allowed"

1850 | "org_verify_failed"1851 | "org_verify_failed"

1851 | "org_pin_mismatch"1852 | "org_pin_mismatch"

1852 | "managed_settings_invalid"1853 | "managed_settings_invalid"

1869| 值 | 什麼停止了工作階段 |1870| 值 | 什麼停止了工作階段 |

1870| :- | :- |1871| :- | :- |

1871| `org_pin_api_key_conflict` | 受管設定[需要第一方或 Cloud 閘道登入](/docs/zh-TW/authentication#restrict-login-to-your-organization)，並且已設定 Anthropic API 金鑰、驗證令牌或 `apiKeyHelper` |1872| `org_pin_api_key_conflict` | 受管設定[需要第一方或 Cloud 閘道登入](/docs/zh-TW/authentication#restrict-login-to-your-organization)，並且已設定 Anthropic API 金鑰、驗證令牌或 `apiKeyHelper` |

1873| `provider_not_allowed` | 受管設定[列出此機器可能使用的 API 提供者](/docs/zh-TW/settings-reference#allowedproviders)，工作階段設定為不在清單中的提供者，或設定未固定的端點。需要 Claude Code v2.1.285 或更新版本 |

1874| `managed_settings_invalid` | 無法讀取受管原則設定，pin 未命名任何組織，或[受管模型限制](/docs/zh-TW/errors#managed-settings-block-the-default-model)不為預設選項留下任何允許的模型 |1876| `managed_settings_invalid` | 無法讀取受管原則設定，pin 未命名任何組織，或[受管模型限制](/docs/zh-TW/errors#managed-settings-block-the-default-model)不為預設選項留下任何允許的模型 |

3123 工具輸入類型3125 工具輸入類型

3124</h2>3126</h2>

3125 3127

3126所有內建 Claude Code 工具的輸入架構文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，可用於類型安全的工具互動。3128所有內建 Claude Code 工具的輸入結構描述文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，可用於類型安全的工具互動。

3127 3129

3128<h3 id="toolinputschemas">3130<h3 id="toolinputschemas">

3129 `ToolInputSchemas`3131 `ToolInputSchemas`

3177 Agent3179 Agent

3178</h3>3180</h3>

3179 3181

3180**工具名稱：** `Agent`。先前的名稱 `Task` 仍被接受為別名，[`SDKSystemMessage`](#sdksystemmessage) 初始化訊息中的 `tools` 陣列目前仍將此工具列為 `Task` 以保持向後相容性。3182**工具名稱：** `Agent`。先前的名稱 `Task` 仍被接受為別名，[`SDKSystemMessage`](#sdksystemmessage) 初始化訊息中的 `tools` 陣列目前為了向後相容性將此工具列為 `Task`。

3181 3183

3182<Note>3184<Note>

3183 `mode` 欄位在 Claude Code v2.1.212 或更新版本上已棄用且被忽略。子代理在父工作階段的權限模式或其定義的 [`permissionMode`](#agentdefinition) 中執行，[子代理繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes) 決定使用哪一個。3185 `mode` 欄位在 Claude Code v2.1.212 或更新版本上已棄用且被忽略。子代理在父工作階段的權限模式或其定義的 [`permissionMode`](#agentdefinition) 中執行，[子代理繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes) 決定使用哪一個。

3219};3221};

3220```3222```

3221 3223

3222在執行期間向使用者提出澄清問題。詳見[處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以了解使用詳情。3224在執行期間詢問使用者澄清問題。詳見[處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以了解使用詳情。

3223 3225

3224<h3 id="bash">3226<h3 id="bash">

3225 Bash3227 Bash

3237};3239};

3238```3240```

3239 3241

3240執行 Bash 命令，支援選擇性逾時和背景執行。工作目錄在命令之間保持不變，包括多輪工作階段後續執行的命令；shell 狀態（例如匯出的環境變數）則不會保持。如需了解哪些目錄變更會保留，詳見[命令之間保持的內容](/docs/zh-TW/tools-reference#what-persists-between-commands)。如需了解設定前景上限的因素，詳見[逾時和輸出限制](/docs/zh-TW/tools-reference#timeout-and-output-limits)。如需了解背景時間限制，詳見[背景命令](/docs/zh-TW/tools-reference#background-commands)。3242執行 Bash 命令，支援選擇性逾時和背景執行。工作目錄在命令之間保持不變，包括多輪工作階段後續執行的命令；shell 狀態（例如匯出的環境變數）則不會保持。如需了解哪些目錄變更會保留，詳見[命令之間保持的內容](/docs/zh-TW/tools-reference#what-persists-between-commands)。如需了解前景上限的設定方式，詳見[逾時和輸出限制](/docs/zh-TW/tools-reference#timeout-and-output-limits)。如需了解背景命令的時間限制，詳見[背景命令的時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)。

3241 3243

3242<h3 id="monitor">3244<h3 id="monitor">

3243 Monitor3245 Monitor

3257};3259};

3258```3260```

3259 3261

3260執行背景來源並將每個事件傳遞給 Claude，使其能夠做出反應而無需輪詢：`command` 執行指令碼並每行 stdout 發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。提供 `command` 或 `ws` 中的恰好一個。`ws` 來源需要 Claude Code v2.1.195 或更新版本。3262執行背景來源並將每個事件傳遞給 Claude，使其可以做出反應而無需輪詢：`command` 執行指令碼並每行 stdout 發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。恰好提供 `command` 或 `ws` 其中之一。`ws` 來源需要 Claude Code v2.1.195 或更新版本。

3261 3263

3262`timeout_ms` 是監視的截止時間（以毫秒為單位）。預設為 300000，接受最多 3600000 的值。有效截止時間最多為 1800000，即 30 分鐘，因此較大的接受值會縮短到該值。在截止時間時，監視結束，Claude 收到一個通知，以便在仍需要時啟動新的監視。3264`timeout_ms` 是監視的截止時間（毫秒）。預設為 300000，接受最多 3600000 的值。有效截止時間最多為 1800000，即 30 分鐘，因此較大的接受值會縮短至該值。在截止時間時監視結束，Claude 收到一個通知，以便在仍需要時啟動新監視。

3263 3265

3264匯出的類型將 `timeout_ms` 標記為必需，因為架構填入預設值；省略它的呼叫會驗證通過。3266匯出的類型將 `timeout_ms` 標記為必需，因為結構填入預設值；省略它的呼叫會驗證通過。

3265 3267

3266Monitor 執行命令時，遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示核准。詳見[Monitor 工具參考](/docs/zh-TW/tools-reference#monitor-tool)以了解行為和提供者可用性。3268當 Monitor 執行命令時，它遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示核准。詳見[Monitor 工具參考](/docs/zh-TW/tools-reference#monitor-tool)以了解行為和提供者可用性。

3267 3269

3268<h3 id="taskoutput">3270<h3 id="taskoutput">

3269 TaskOutput3271 TaskOutput

3270</h3>3272</h3>

3271 3273

3272在 Claude Code v2.1.277 中移除，連同其 `TaskOutputInput` 類型一起移除。先前從執行中或已完成的背景任務中擷取輸出；Claude 改用 `Read` 讀取背景任務的輸出檔案。3274在 Claude Code v2.1.277 中移除，連同其 `TaskOutputInput` 類型一起移除。先前用於擷取執行中或已完成的背景任務的輸出；Claude 改用 `Read` 讀取背景任務的輸出檔案。

3273 3275

3274仍命名 `TaskOutput` 的 `disallowedTools` 項目或拒絕規則會被忽略，不會發出警告。3276`disallowedTools` 項目或仍命名 `TaskOutput` 的拒絕規則會被忽略而不發出警告。

3275 3277

3276<h3 id="edit">3278<h3 id="edit">

3277 Edit3279 Edit

3307 3309

3308從本機檔案系統讀取檔案，包括文字、影片、PDF 和 Jupyter 筆記本。使用 `pages` 指定 PDF 頁面範圍（例如 `"1-5"`）。3310從本機檔案系統讀取檔案，包括文字、影片、PDF 和 Jupyter 筆記本。使用 `pages` 指定 PDF 頁面範圍（例如 `"1-5"`）。

3309 3311

3310對於 PDF，Claude 在 Read 呼叫的 `tool_result` 內容中接收檔案的內容。傳回 `pdf` [輸出](#tool-output-types)的讀取會帶有摘要 `text` 區塊，後面跟著 `document` 區塊。傳回 `parts` 輸出的讀取會帶有摘要 `text` 區塊，後面跟著每個提取頁面的一個區塊：`image` 區塊，或當 Claude Code 無法將其呈現為影片時命名該頁面的 `text` 區塊。在 Agent SDK v0.3.242 之前，Claude Code 在工具結果後作為單獨的 `user` 訊息傳遞檔案的內容。3312對於 PDF，Claude 在 Read 呼叫的 `tool_result` 內容中接收檔案的內容。傳回 `pdf` [輸出](#tool-output-types)的讀取會帶有摘要 `text` 區塊，後面跟著 `document` 區塊。傳回 `parts` 輸出的讀取會帶有摘要 `text` 區塊，後面跟著每個擷取頁面的一個區塊：`image` 區塊，或當 Claude Code 無法將其呈現為影片時命名頁面的 `text` 區塊。在 Agent SDK v0.3.242 之前，Claude Code 在工具結果後將檔案的內容作為單獨的 `user` 訊息傳遞。

3311 3313

3312<h3 id="write">3314<h3 id="write">

3313 Write3315 Write

3449};3451};

3450```3452```

3451 3453

3452執行[動態工作流程](/docs/zh-TW/workflows)：在背景中協調許多子代理並傳回一個統一結果的指令碼。Workflow 工具在 Agent SDK v0.3.149 及更新版本中可用。至少需要 `script`、`name` 或 `scriptPath` 中的一個。3454執行[動態工作流程](/docs/zh-TW/workflows)：在背景中協調許多子代理並傳回一個統一結果的指令碼。Workflow 工具在 Agent SDK v0.3.149 及更新版本中可用。至少需要 `script`、`name` 或 `scriptPath` 其中之一。

3453 3455

3454| 欄位 | 類型 | 說明 |3456| 欄位 | 類型 | 描述 |

3455| - | - | - |3457| - | - | - |

3456| `script` | `string` | 內嵌工作流程指令碼。必須以 `export const meta = { name, description }` 作為字面值開始，後面跟著使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的指令碼主體。`meta` 中的選擇性 `phases` 陣列在進度檢視中將代理分組到具名階段下 |3458| `script` | `string` | 內嵌工作流程指令碼。必須以 `export const meta = { name, description }` 作為字面值開始，後面跟著使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的指令碼主體。`meta` 中的選擇性 `phases` 陣列在進度檢視中將代理分組到具名階段下 |

3460| `resumeFromRunId` | `string` | 先前 `Workflow` 呼叫的執行 ID 以繼續。具有未變更輸入的已完成 `agent()` 呼叫通常傳回快取結果；其餘的執行即時。[暫停後繼續](/docs/zh-TW/workflows#resume-after-a-pause)涵蓋哪些已完成的呼叫重新執行。僅限同一工作階段 |3462| `resumeFromRunId` | `string` | 先前 `Workflow` 呼叫的執行 ID 以繼續。具有未變更輸入的已完成 `agent()` 呼叫通常傳回快取結果；其餘的執行即時。[暫停後繼續](/docs/zh-TW/workflows#resume-after-a-pause)涵蓋哪些已完成的呼叫會重新執行。僅限同一工作階段 |

3463 3465

3464<h3 id="todowrite">3466<h3 id="todowrite">

3465 TodoWrite3467 TodoWrite

3577};3579};

3578```3580```

3579 3581

3580退出 Plan Mode。`allowedPrompts` 欄位已棄用且被忽略；Claude Code 仍接受它以便現有呼叫者和文字記錄驗證。在 v2.1.205 之前，它要求基於提示的 Bash 權限以實施計畫。3582退出 Plan Mode。`allowedPrompts` 欄位已棄用且被忽略；Claude Code 仍接受它以便現有呼叫者和文字記錄驗證通過。在 v2.1.205 之前，它要求基於提示的 Bash 權限以實現計畫。

3581 3583

3582<h3 id="listmcpresources">3584<h3 id="listmcpresources">

3583 ListMcpResources3585 ListMcpResources

3648type EnterPlanModeInput = {};3650type EnterPlanModeInput = {};

3649```3651```

3650 3652

3651進入 Plan Mode，其中 Claude 在進行變更前研究並呈現計畫。3653進入 Plan Mode，Claude 在其中研究並在進行變更前提出計畫。

3652 3654

3653<h3 id="croncreate">3655<h3 id="croncreate">

3654 CronCreate3656 CronCreate

3665};3667};

3666```3668```

3667 3669

3668在本機時間的 5 欄位 cron 排程上排程提示執行。將 `recurring` 設定為 `false` 以在下一個符合時單次觸發。工作預設為工作階段範圍，啟動新對話會清除它們，使用 `--resume` 或 `--continue` 繼續會還原尚未過期的工作。詳見[排程任務](/docs/zh-TW/scheduled-tasks)。3670在本機時間的 5 欄位 cron 排程上排程提示執行。將 `recurring` 設定為 `false` 以在下一個符合時單次觸發。工作預設為工作階段範圍，使用 `--resume` 或 `--continue` 繼續時會還原尚未過期的工作。詳見[排程任務](/docs/zh-TW/scheduled-tasks)。

3669 3671

3670將 `durable` 設定為 `true` 以要求持久化到 `.claude/scheduled_tasks.json`，使工作在重新啟動後存活。持久化排程並非在每個工作階段都可用：當不可用時，Claude Code 接受 `durable: true` 但建立工作階段專用工作。讀取輸出的 `durable` 欄位以查看工作是否已持久化。3672將 `durable` 設定為 `true` 以要求持久化至 `.claude/scheduled_tasks.json`，使工作在重新啟動後存活。並非每個工作階段都提供持久排程：當不提供時，Claude Code 接受 `durable: true` 但建立工作為僅工作階段。讀取輸出的 `durable` 欄位以查看工作是否已持久化。

3671 3673

3672<h3 id="crondelete">3674<h3 id="crondelete">

3673 CronDelete3675 CronDelete

3681};3683};

3682```3684```

3683 3685

3684按從 `CronCreate` 傳回的 ID 刪除排程的 cron 工作。3686按 `CronCreate` 傳回的 ID 刪除排程的 cron 工作。

3685 3687

3686<h3 id="cronlist">3688<h3 id="cronlist">

3687 CronList3689 CronList

3693type CronListInput = {};3695type CronListInput = {};

3694```3696```

3695 3697

3696列出排程的 cron 工作：來自 `.claude/scheduled_tasks.json` 的持久化工作和來自目前工作階段的工作階段專用工作。3698列出排程的 cron 工作：來自 `.claude/scheduled_tasks.json` 的持久工作和來自目前工作階段的僅工作階段工作。

3697 3699

3698<h3 id="schedulewakeup">3700<h3 id="schedulewakeup">

3699 ScheduleWakeup3701 ScheduleWakeup

3711};3713};

3712```3714```

3713 3715

3714排程一次性喚醒，在延遲後觸發給定的提示。此工具支援自步調 `/loop` 命令。執行時間將 `delaySeconds` 限制在 60 到 3600 秒之間。除非 `stop` 為 true，否則 `delaySeconds`、`reason`、`prompt` 和 `noop` 欄位為必需。`noop: true` 報告沒有任何變更的喚醒。設定 `stop: true` 以取消待處理的喚醒並結束自步調 `/loop`。`stop` 欄位需要 Claude Code v2.1.202 或更新版本。詳見[工具參考中的 ScheduleWakeup 列](/docs/zh-TW/tools-reference)。3716排程一次性喚醒，在延遲後觸發給定的提示。此工具支援自步調 `/loop` 命令。執行時間將 `delaySeconds` 限制在 60 到 3600 秒之間。除非 `stop` 為 true，否則 `delaySeconds`、`reason`、`prompt` 和 `noop` 欄位為必需。`noop: true` 報告沒有任何變更的喚醒。設定 `stop: true` 會取消待處理的喚醒並結束自步調 `/loop`。`stop` 欄位需要 Claude Code v2.1.202 或更新版本。詳見[工具參考中的 ScheduleWakeup 列](/docs/zh-TW/tools-reference)。

3715 3717

3716<h3 id="remotetrigger">3718<h3 id="remotetrigger">

3717 RemoteTrigger3719 RemoteTrigger

3739};3741};

3740```3742```

3741 3743

3742管理[例行工作](/docs/zh-TW/routines)，即在雲端託管的排程和觸發 Claude Code 執行。此工具支援 `/schedule` 命令。`trigger_id` 對於 `get`、`update`、`run` 和 `list_runs` 動作為必需。`body` 對於 `create`、`update` 和 `create_webhook_trigger` 為必需，對於 `run` 為選擇性。3744管理[例行程序](/docs/zh-TW/routines)，即在雲端託管的排程和觸發 Claude Code 執行。此工具支援 `/schedule` 命令。`trigger_id` 對於 `get`、`update`、`run` 和 `list_runs` 動作為必需。`body` 對於 `create`、`update` 和 `create_webhook_trigger` 為必需，對於 `run` 為選擇性。

3743 3745

3744`create_webhook_trigger` 將事件來源附加到現有例行工作，例如觸發它的 [GitHub 事件](/docs/zh-TW/routines#add-a-github-trigger)。`body` 命名來源、事件和要觸發的例行工作。需要 Claude Code v2.1.225 或更新版本。3746`create_webhook_trigger` 將事件來源附加到現有例行程序，例如觸發它的 [GitHub 事件](/docs/zh-TW/routines#add-a-github-trigger)。`body` 命名來源、事件和要觸發的例行程序。需要 Claude Code v2.1.225 或更新版本。

3745 3747

3746`list_runs` 列出例行工作的最近執行，`get_run_log` 讀取一個執行的日誌。`session_id` 命名要讀取的執行，來自 `list_runs` 結果，`cursor` 透過任一動作的結果進行分頁。兩個動作都需要 Claude Code v2.1.227 或更新版本。3748`list_runs` 列出例行程序的最近執行，`get_run_log` 讀取一個執行的日誌。`session_id` 命名要讀取的執行（來自 `list_runs` 結果），`cursor` 分頁任一動作的結果。兩個動作都需要 Claude Code v2.1.227 或更新版本。

3747 3749

3748此工具僅在工作階段使用啟用例行工作的計畫的 claude.ai 帳戶進行驗證時可用，當您的組織政策停用[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 時不存在。在 Claude Code v2.1.227 或更新版本上，當所有者[為組織關閉例行工作](/docs/zh-TW/routines#routines-are-disabled-by-your-organizations-policy)時，該工具也不存在。在 v2.1.227 之前，僅關閉例行工作切換的工作階段仍顯示該工具，伺服器拒絕其呼叫。3750此工具僅在工作階段使用啟用例行程序的 claude.ai 帳戶進行驗證時可用，當您的組織政策停用[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)時不存在。在 Claude Code v2.1.227 或更新版本上，當擁有者[為組織關閉例行程序](/docs/zh-TW/routines#routines-are-disabled-by-your-organizations-policy)時，工具也不存在。在 v2.1.227 之前，僅關閉例行程序切換的工作階段仍顯示工具，伺服器拒絕其呼叫。

3749 3751

3750<h3 id="pushnotification">3752<h3 id="pushnotification">

3751 PushNotification3753 PushNotification

3760};3762};

3761```3763```

3762 3764

3763向使用者傳送主動推播通知。將 `message` 保持在 200 個字元以下，因為行動作業系統會截斷較長的文字。詳見[工具參考中的 PushNotification 列](/docs/zh-TW/tools-reference)以了解提供者可用性；推播傳遞透過 Anthropic 託管的基礎設施執行，無法從 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取。3765向使用者傳送主動推播通知。將 `message` 保持在 200 個字元以下，因為行動作業系統會截斷較長的文字。詳見[工具參考中的 PushNotification 列](/docs/zh-TW/tools-reference)以了解提供者可用性；推播傳遞通過 Anthropic 託管的基礎設施進行，該基礎設施無法從 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取。

3764 3766

3765<h3 id="repl">3767<h3 id="repl">

3766 REPL3768 REPL

3767</h3>3769</h3>

3768 3770

3769在 v2.1.275 中移除。透過 v2.1.274，實驗性 `REPL` 工具可以透過在 [`env` 選項](#options)中設定 `CLAUDE_CODE_REPL=1` 來開啟。3771在 v2.1.275 中移除。通過 v2.1.274，實驗性 `REPL` 工具可以通過在[`env` 選項](#options)中設定 `CLAUDE_CODE_REPL=1` 來開啟。

3770 3772

3771<h3 id="reportfindings">3773<h3 id="reportfindings">

3772 ReportFindings3774 ReportFindings

3790};3792};

3791```3793```

3792 3794

3793將程式碼審查發現報告為結構化清單，以便 Claude Code 可以呈現它們而不是將其列印為文字。`level` 是審查執行的工作量級別。發現按最嚴重優先排序，每次呼叫最多 32 個，當沒有倖存時陣列為空。需要 Claude Code v2.1.196 或更新版本。3795將程式碼審查發現報告為結構化清單，以便 Claude Code 可以呈現它們而不是將其列印為文字。`level` 是審查執行的工作量級別。發現按最嚴重優先排序，每次呼叫最多 32 個，當沒有發現存活時陣列為空。需要 Claude Code v2.1.196 或更新版本。

3794 3796

3795每個發現包含這些欄位：3797每個發現包含這些欄位：

3796 3798

3797* `file`：發現所在的儲存庫相對路徑。選擇性 `line` 是它錨定到的 1 索引行。3799* `file`：發現所在的儲存庫相對路徑。選擇性 `line` 是它錨定到的 1 索引行。

3798* `summary`：缺陷的單句陳述。`failure_scenario` 描述導致錯誤輸出或當機的具體輸入和狀態。3800* `summary`：缺陷的單句陳述。`failure_scenario` 描述導致錯誤輸出或當機的具體輸入和狀態。

3799* `short_summary`：選擇性的最多 60 個字元的壓縮標籤，用於緊湊顯示。需要 Claude Code v2.1.212 或更新版本。3801* `short_summary`：選擇性壓縮標籤，最多 60 個字元用於緊湊顯示。需要 Claude Code v2.1.212 或更新版本。

3800* `category`：選擇性的發現類型的短 kebab-case slug，例如 `correctness` 或 `test-coverage`。需要 Claude Code v2.1.199 或更新版本。3802* `category`：選擇性短 kebab-case 發現類型的 slug，例如 `correctness` 或 `test-coverage`。需要 Claude Code v2.1.199 或更新版本。

3801* `verdict`：在驗證通過執行時設定；在僅內嵌審查中不存在。3803* `verdict`：在驗證通過執行時設定；在僅內嵌審查上不存在。

3802* `outcome`：僅在應用修復後重新報告時設定。3804* `outcome`：僅在應用修復後重新報告時設定。

3803 3805

3804<h3 id="artifact">3806<h3 id="artifact">

3825};3827};

3826```3828```

3827 3829

3828將本機 `.html` 或 `.md` 檔案發佈為託管成品頁面，或列出使用者的已發佈成品。省略 `action` 或傳遞 `"publish"` 以發佈 `file_path`，這對於發佈動作為必需。每個以下欄位適用於發佈：3830將本機 `.html` 或 `.md` 檔案發佈為託管成品頁面，或列出使用者的已發佈成品。省略 `action` 或傳遞 `"publish"` 以發佈 `file_path`，這對於發佈動作為必需。以下每個欄位適用於發佈：

3829 3831

3830* `icon`：成品瀏覽器標籤圖示的一個短通用詞，例如 `chart` 或 `map`。Claude 在首次發佈時包含它，在更新時省略它，這會保留成品的儲存圖示。3832* `icon`：成品瀏覽器標籤圖示的一個短通用詞，例如 `chart` 或 `map`。Claude 在首次發佈時包含它，在更新時省略它，這保留成品的儲存圖示。

3831* `favicon`：已棄用，Claude 會省略它。3833* `favicon`：已棄用，Claude 省略它。

3832* `title`：當 HTML 檔案沒有 `<title>` 標籤時，在瀏覽器標籤和圖庫中命名已發佈頁面。3834* `title`：在瀏覽器標籤和圖庫中命名已發佈頁面，當 HTML 檔案沒有 `<title>` 標籤時。

3833* `url`：以現有成品為目標以就地更新，而不是建立新的。3835* `url`：目標是現有成品以就地更新，而不是建立新的。

3834 3836

3835`force` 是最後手段的覆蓋，捨棄另一個工作階段發佈的較新版本。發生衝突時，失敗的發佈會傳回較新的內容；Claude 將其變更合併到該內容上，或重新讀取成品，然後再次發佈。僅當使用者明確要求捨棄該版本時才傳遞 `force`。3837`force` 是最後手段覆蓋，丟棄另一個工作階段發佈的較新版本。在衝突時，失敗的發佈傳回較新的內容；Claude 將其變更合併到該內容上，或重新讀取成品，並再次發佈。僅當使用者明確要求丟棄該版本時傳遞 `force`。

3836 3838

3837傳遞 `"list"` 以列舉使用者的已發佈成品；只有 `limit` 和 `scope` 可能伴隨它。`scope` 預設為 `"mine"`，列出使用者擁有的成品；`"shared"` 列出其他人與使用者共享的成品，`"all"` 列出兩者。3839傳遞 `"list"` 以列舉使用者的已發佈成品；僅 `limit` 和 `scope` 可能伴隨它。`scope` 預設為 `"mine"`，列出使用者擁有的成品；`"shared"` 列出其他人與使用者共享的成品，`"all"` 列出兩者。

3838 3840

3839* `capabilities`：已發佈頁面使用的執行時功能，按功能名稱鍵入，例如[頁面可能呼叫的連接器](/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors)。成品服務驗證宣告並拒絕命名帳戶無法使用的功能或給予無效設定的發佈。傳遞 `{}` 以清除儲存的宣告，並在重新部署時省略欄位以保留它。需要 Agent SDK v0.3.235 或更新版本。3841* `capabilities`：已發佈頁面使用的執行時功能，按功能名稱鍵入，例如[頁面可能呼叫的連接器](/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors)。成品服務驗證宣告並拒絕命名帳戶無法使用的功能或給予一個無效設定的發佈。傳遞 `{}` 以清除儲存的宣告，在重新部署時省略欄位以保留它。需要 Agent SDK v0.3.235 或更新版本。

3840* `contract`：已發佈頁面執行的執行時版本。省略它以保留成品的目前版本，傳遞 `"latest"` 以升級，或傳遞特定版本以釘選或回滾。需要 Agent SDK v0.3.235 或更新版本。3842* `contract`：已發佈頁面執行的執行時版本。省略它以保留成品的目前版本，傳遞 `"latest"` 以升級，或傳遞特定版本以釘選或回滾。需要 Agent SDK v0.3.235 或更新版本。

3841 3843

3842類型已匯出，但該工具在 Agent SDK 工作階段中預設關閉。發佈還需要[成品可用性表](/docs/zh-TW/artifacts#availability)中的每個條件，使用 API 金鑰驗證的工作階段不符合。3844類型已匯出，但工具在 Agent SDK 工作階段中預設為關閉。發佈也需要[成品可用性表](/docs/zh-TW/artifacts#availability)中的每個條件，使用 API 金鑰驗證的工作階段不符合。

3843 3845

3844<h3 id="projects">3846<h3 id="projects">

3845 Projects3847 Projects

3868 3870

3869* `project_info`：傳回專案中繼資料和文件清單。3871* `project_info`：傳回專案中繼資料和文件清單。

3870* `project_read`：按 `path` 讀取一個文件。3872* `project_read`：按 `path` 讀取一個文件。

3871* `project_search`：使用 `query` 查詢專案的知識庫。`n` 限制點擊數，預設為 5。3873* `project_search`：使用 `query` 查詢專案的知識庫。`n` 限制點擊數並預設為 `5`。

3872* `project_write`：在 `path` 建立或取代文件，來自 `content`（帶有內嵌文字）或 `local_path`（命名工作目錄內的檔案）中的恰好一個。`present_to_user: true` 將寫入的文件標記為使用者需要查看的可交付成果。3874* `project_write`：在 `path` 建立或替換文件，恰好來自 `content`（帶有內嵌文字）或 `local_path`（命名工作目錄內的檔案）其中之一。`present_to_user: true` 將寫入的文件標記為使用者需要查看的可交付成果。

3873* `project_delete`：按 `path` 刪除文件。3875* `project_delete`：按 `path` 刪除文件。

3874 3876

3875<h3 id="readmcpresourcedir">3877<h3 id="readmcpresourcedir">

3885};3887};

3886```3888```

3887 3889

3888列出 MCP 伺服器上目錄資源的直接子項。僅可用於已宣告支援目錄列表的伺服器；列表不是遞迴的。目錄列表並非在每個工作階段都啟用：當關閉時，呼叫傳回空的 `resources` 清單，`error` 欄位報告目錄列表未啟用。3890列出 MCP 伺服器上目錄資源的直接子項。僅可用於已宣告支援目錄列表的伺服器；列表不是遞迴的。並非每個工作階段都啟用目錄列表：當關閉時，呼叫傳回空 `resources` 清單，`error` 欄位報告目錄列表未啟用。

3889 3891

3890<h3 id="refreshmcptools">3892<h3 id="refreshmcptools">

3891 RefreshMcpTools3893 RefreshMcpTools

3899};3901};

3900```3902```

3901 3903

3902重新查詢已連接 MCP 伺服器的工具清單並應用任何變更。類型已匯出，但 Claude Code 僅在您在 [`env` 選項](#options)中設定 `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` 時註冊該工具，並且僅在至少有一個 MCP 伺服器的工作階段中。需要 Claude Code v2.1.211 或更新版本。3904重新查詢已連接 MCP 伺服器的工具清單並應用任何變更。類型已匯出，但 Claude Code 僅在您在[`env` 選項](#options)中設定 `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` 時註冊工具，且僅在至少有一個 MCP 伺服器的工作階段中。需要 Claude Code v2.1.211 或更新版本。

3903 3905

3904<h3 id="showonboardingrolepicker">3906<h3 id="showonboardingrolepicker">

3905 ShowOnboardingRolePicker3907 ShowOnboardingRolePicker

3911type ShowOnboardingRolePickerInput = {};3913type ShowOnboardingRolePickerInput = {};

3912```3914```

3913 3915

3914在 Cowork 上線期間呈現可點擊的角色選擇器晶片列，以便使用者可以選擇其角色並取得相符的外掛程式安裝。不帶任何引數；角色清單由用戶端定義。呼叫會阻止直到使用者回應。3916在 Cowork 上線期間呈現可點擊的角色選擇器晶片列，以便使用者可以選擇其角色並取得相符的外掛程式安裝。不帶引數；角色清單由用戶端定義。呼叫會阻止直到使用者回應。

3915 3917

3916<h3 id="mcpinput">3918<h3 id="mcpinput">

3917 McpInput3919 McpInput

3925};3927};

3926```3928```

3927 3929

3928MCP 工具引數是開放物件：每個伺服器定義自己的參數，因此類型對欄位名稱或值不施加任何限制。請查閱伺服器自己的工具架構以了解特定工具接受的欄位。3930MCP 工具引數是開放物件：每個伺服器定義其自己的參數，因此類型對欄位名稱或值不施加任何限制。請查閱伺服器自己的工具結構以了解特定工具接受的欄位。

3929 3931

3930<h2 id="tool-output-types">3932<h2 id="tool-output-types">

3931 工具輸出類型3933 工具輸出類型

4141 4143

4142`timedOutAfterMs` 是逾時（以毫秒為單位），當命令達到其逾時並移至背景而不是明確從那裡開始時設定。`backgroundCwdHint` 在背景化命令包含目錄變更內建函式（例如 `cd`、`pushd`、`popd` 或 `chdir`）時設定，並注意工作階段工作目錄未變更。兩個欄位都需要 Claude Code v2.1.210 或更新版本。4144`timedOutAfterMs` 是逾時（以毫秒為單位），當命令達到其逾時並移至背景而不是明確從那裡開始時設定。`backgroundCwdHint` 在背景化命令包含目錄變更內建函式（例如 `cd`、`pushd`、`popd` 或 `chdir`）時設定，並注意工作階段工作目錄未變更。兩個欄位都需要 Claude Code v2.1.210 或更新版本。

4143 4145

4144當在前景執行的子代理擁有背景化命令時，該命令[在該子代理的執行結束時結束](/docs/zh-TW/tools-reference#background-commands)。Claude Code 在此類命令上將 `backgroundEndsWithFinalResponse` 設定為 `true`，並在命令存活該輪時省略欄位，如主對話或背景子代理啟動的命令一樣。此欄位需要 Claude Code v2.1.227 或更新版本。4146當在前景執行的子代理擁有背景化命令時，該命令[在該子代理的執行結束時結束](/docs/zh-TW/tools-reference#when-a-background-command-stops)。Claude Code 在此類命令上將 `backgroundEndsWithFinalResponse` 設定為 `true`，並在命令存活該輪時省略欄位，如主對話或背景子代理啟動的命令一樣。此欄位需要 Claude Code v2.1.227 或更新版本。

4145 4147

4146Claude Code 將 `gitOperation.commit.branch` 設定為 git 提交摘要行中命名的分支，並對在分離 HEAD 上進行的提交省略它。此欄位需要 Agent SDK v0.3.227 或更新版本。Claude Code 將 `gh pr reopen` 命令報告為 `reopened` PR 動作，需要 Agent SDK v0.3.234 或更新版本。4148Claude Code 將 `gitOperation.commit.branch` 設定為 git 提交摘要行中命名的分支，並對在分離 HEAD 上進行的提交省略它。此欄位需要 Agent SDK v0.3.227 或更新版本。Claude Code 將 `gh pr reopen` 命令報告為 `reopened` PR 動作，需要 Agent SDK v0.3.234 或更新版本。

4147 4149

agent-view.md +2 −20

Details

8 8

9Agent view（使用 `claude agents` 開啟）是所有背景工作階段的一個螢幕：什麼正在執行、什麼需要您的輸入，以及什麼已完成。分派新工作階段，一目瞭然地查看它們的狀態，而不是滾動瀏覽記錄，並且只在需要時才介入。每個背景工作階段都是一個完整的 Claude Code 對話，在沒有終端連接的情況下持續執行，因此您可以隨時開啟、回覆和離開。9Agent view（使用 `claude agents` 開啟）是所有背景工作階段的一個螢幕：什麼正在執行、什麼需要您的輸入，以及什麼已完成。分派新工作階段，一目瞭然地查看它們的狀態，而不是滾動瀏覽記錄，並且只在需要時才介入。每個背景工作階段都是一個完整的 Claude Code 對話，在沒有終端連接的情況下持續執行，因此您可以隨時開啟、回覆和離開。

10 10

11<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-light.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=7a186c96ed47d6700d084d77e786be65" className="dark:hidden" alt="終端中的 Agent view：標題顯示 Claude Code v2.1.140、模型、工作目錄和摘要計數。工作階段分組在'需要輸入'、'執行中'和'已完成'下，底部有分派輸入，頁尾有快捷鍵提示。" width="1772" height="780" data-path="images/agent-view-light.png" />11<img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-light.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=d6905012bee31f3e6b3920b09c05dd02" className="dark:hidden" alt="終端中的 Agent view。頂部的一行計算等待輸入、執行中和已完成的工作階段。四個工作階段分組在「需要輸入」、「執行中」和「已完成」下。每一行顯示工作階段的名稱、其最新狀態或問題，以及一個時間。底部是用於描述新任務的輸入和一行快捷鍵提示。" width="1872" height="680" data-path="images/agent-view-light.png" />

12 12

13<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-dark.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=a5bed7434bae368faea3a8f023b52aa2" className="hidden dark:block" alt="終端中的 Agent view：標題顯示 Claude Code v2.1.140、模型、工作目錄和摘要計數。工作階段分組在'需要輸入'、'執行中'和'已完成'下，底部有分派輸入，頁尾有快捷鍵提示。" width="1772" height="780" data-path="images/agent-view-dark.png" />13<img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-dark.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=fc3c195bfc57e313ced1f1beb36cee93" className="hidden dark:block" alt="終端中的 Agent view。頂部的一行計算等待輸入、執行中和已完成的工作階段。四個工作階段分組在「需要輸入」、「執行中」和「已完成」下。每一行顯示工作階段的名稱、其最新狀態或問題，以及一個時間。底部是用於描述新任務的輸入和一行快捷鍵提示。" width="1872" height="680" data-path="images/agent-view-dark.png" />

14 14

15當您有多個獨立任務 Claude 可以在不需要您監看每一步的情況下執行時，請使用 agent view。分派一個錯誤修復、一個拉取請求審查和一個不穩定測試調查作為三行，在另一個視窗中繼續工作，並在某一行顯示需要您或有結果時檢查。15當您有多個獨立任務 Claude 可以在不需要您監看每一步的情況下執行時，請使用 agent view。分派一個錯誤修復、一個拉取請求審查和一個不穩定測試調查作為三行，在另一個視窗中繼續工作，並在某一行顯示需要您或有結果時檢查。

16 16

958 958

959Claude Code 永遠不會重新啟動執行[shell 命令](#run-a-shell-command)的列，來自 `Enter` 或來自 `claude attach`，因為那樣會再次執行命令；該列的訊息和 `claude attach` 都說命令不會再次執行。959Claude Code 永遠不會重新啟動執行[shell 命令](#run-a-shell-command)的列，來自 `Enter` 或來自 `claude attach`，因為那樣會再次執行命令；該列的訊息和 `claude attach` 都說命令不會再次執行。

960 960

961<h4 id="terminal-host-died">

962 終端主機已死亡

963</h4>

~~964~~

965在 Linux 和 WSL 上，監督程序每隔幾秒檢查每個主機程序，無論您是否開啟工作階段，並在程序已退出但其與監督程序的連接從未關閉時將工作階段標記為失敗。

~~966~~

967* 在 agent view 中，該列顯示 `terminal host process died — press Enter to restart`。在它上面按 `Enter`，Claude Code 會在新的主機程序上重新啟動工作階段。

968* 從 shell，`claude attach <id>` 重新啟動已標記為失敗的工作階段。否則它會報告原因並退出，告訴您執行 `claude attach <id>`。

~~969~~

970<h4 id="session-isn’t-responding">

971 工作階段沒有回應

972</h4>

~~973~~

974當監督程序接受開啟但約十秒內沒有輸出到達時，Claude Code 會結束嘗試並提供重新啟動。僅僅停滯的工作階段，例如跨機器睡眠，不會達到此提供：監督程序[在開啟時自行重新啟動](#read-session-state)。

~~975~~

976* 在 agent view 中，頁腳顯示 `Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).` 在同一列上再次按 `Enter`，Claude Code 會停止無回應的程序並重新啟動工作階段；它在沒有第二次按下的情況下不會停止任何內容。

977* 從 shell，`claude attach <id>` 報告原因並退出，告訴您執行 `claude stop <id>`，然後 `claude attach <id>`。

~~978~~

979<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">961<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">

980 工作階段在啟動前失敗，並出現 `possibly low memory` 註記962 工作階段在啟動前失敗，並出現 `possibly low memory` 註記

981</h3>963</h3>

amazon-bedrock.md +12 −0

Details

384 384

385模型別名（例如 `opus`）不會作為釘選，Claude Code 無法識別的模型 ID（例如應用程式推論設定檔 ARN）也不會。385模型別名（例如 `opus`）不會作為釘選，Claude Code 無法識別的模型 ID（例如應用程式推論設定檔 ARN）也不會。

386 386

387當這些檢查發現您的帳戶無法呼叫的模型時，Claude Code 會在此機器上記住該拒絕長達一天，並在該時間內啟動時跳過記住的模型，而不會再次詢問 Amazon Bedrock。Claude Code 會在距離上次檢查已過十分鐘後，再次檢查目前預設模型的記住拒絕，因此您的管理員重新啟用的預設會恢復。若要關閉此記憶，請設定 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/zh-TW/env-vars)。

388

389<h3 id="when-a-model-is-disabled-mid-session">

390 當模型在工作階段中被停用時

391</h3>

392

393如果您的帳戶失去對工作階段執行所在模型的存取權，例如因為管理員在您的 Amazon Bedrock 帳戶中停用了它，Claude Code 會將工作階段切換到另一個模型，而不是讓每個請求都失敗，並顯示 `Switched to <fallback> because <model> is not available`。它會嘗試與啟動回退相同的模型：先嘗試同一層級的較早版本，對於沒有可用 Opus 版本的 Opus 工作階段，則嘗試預設的 Sonnet 模型。

394

395切換僅適用於您未釘選的層級，這與啟動回退的條件相同。在您選擇的特定版本上執行的工作階段，或在[應用程式推論設定檔 ARN](#map-each-model-version-to-an-inference-profile) 上執行的工作階段，會保持其模型，且沒有回退模型鏈，請求會失敗。在[自動模式](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)中，Claude Code 只會切換到自動模式在 Amazon Bedrock 上支援的模型。如果這些模型都無法使用，請求會失敗並顯示 [AWS 驗證失敗](/docs/zh-TW/errors#aws-authentication-failed)，並提示啟用該模型。

396

397您設定的[回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains)會取代層級切換：在這些拒絕上，Claude Code 會切換到您設定的回退。若要讓被拒絕的請求失敗而不是切換，請設定 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/zh-TW/env-vars)。您設定的回退鏈仍會在這些拒絕上切換；如果您希望每個被拒絕的請求都失敗，也請移除該鏈。

398

387<h2 id="cross-region-inference-profile-prefixes">399<h2 id="cross-region-inference-profile-prefixes">

388 跨區域推論設定檔前綴400 跨區域推論設定檔前綴

389</h2>401</h2>

artifacts.md +1 −1

Details

400 400

401一旦您在 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 檔案中或使用 `CLAUDE_CODE_DISABLE_ARTIFACT` 關閉 artifacts，或您的管理員在[受管設定](/docs/zh-TW/server-managed-settings)中關閉它們，就沒有設定檔能將其重新開啟。在 v2.1.242 之前，[優先順序堆疊](/docs/zh-TW/settings#settings-precedence)中較高位置的檔案可能會重新開啟 artifacts，即使較低優先順序的檔案設定了 `"enableArtifact": false`。401一旦您在 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 檔案中或使用 `CLAUDE_CODE_DISABLE_ARTIFACT` 關閉 artifacts，或您的管理員在[受管設定](/docs/zh-TW/server-managed-settings)中關閉它們，就沒有設定檔能將其重新開啟。

402 402

403您也可以在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定 `"enableArtifact": false`，以關閉該專案中工作階段的 artifacts。任一檔案中的 `"enableArtifact": true` 都不會將其重新開啟。在專案和本機設定中接受此金鑰需要 Claude Code v2.1.242 或更新版本。403您也可以在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定 `"enableArtifact": false`，以關閉該專案中工作階段的 artifacts。任一檔案中的 `"enableArtifact": true` 都不會將其重新開啟。在專案和本機設定中接受此金鑰需要 Claude Code v2.1.242 或更新版本。

404 404

authentication.md +20 −0

Details

194* **雲端提供商工作階段，例如 Amazon Bedrock**：僅在 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證，或由較早的 Claude Console 登入儲存的 API 金鑰仍然存在於機器上時被阻止。移除它，工作階段就會啟動。這些工作階段針對您的雲端提供商進行驗證，其存取原則管理它們194* **雲端提供商工作階段，例如 Amazon Bedrock**：僅在 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證，或由較早的 Claude Console 登入儲存的 API 金鑰仍然存在於機器上時被阻止。移除它，工作階段就會啟動。這些工作階段針對您的雲端提供商進行驗證，其存取原則管理它們

195* **[Anthropic 設定檔或聯盟認證](#anthropic-profiles-and-federation-credentials)**：除非 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證，或由較早的 Claude Console 登入儲存的 API 金鑰也存在於機器上，否則不會被阻止。金鑰不檢查設定檔屬於哪個組織195* **[Anthropic 設定檔或聯盟認證](#anthropic-profiles-and-federation-credentials)**：除非 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證，或由較早的 Claude Console 登入儲存的 API 金鑰也存在於機器上，否則不會被阻止。金鑰不檢查設定檔屬於哪個組織

196 196

197<h3 id="restrict-which-api-providers-a-machine-may-use">

198 限制機器可能使用的 API 提供商

199</h3>

200

201[受管設定](/docs/zh-TW/managed-settings) 中的 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 列出受管機器可能透過哪些服務到達 Claude，例如 Anthropic API、Amazon Bedrock 或 LLM 閘道。它補充 `forceLoginMethod` 和 `forceLoginOrgUUID`，這些控制工作階段在與 Anthropic 通話時使用的帳戶。需要 Claude Code v2.1.285 或更新版本。

202

203```json managed-settings.json theme={null}

204{

205 "forceLoginMethod": "claudeai",

206 "forceLoginOrgUUID": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"],

207 "allowedProviders": ["anthropic", "bedrock"]

208}

209```

210

211使用此檔案，簽入到您的 claude.ai 組織或為 Amazon Bedrock 配置的開發人員會正常啟動。為任何其他提供商設定的工作階段在啟動時被拒絕，執行中的工作階段切換到一個時在其下一個請求時被拒絕。[受管設定不允許此 API 提供商](/docs/zh-TW/errors#managed-settings-dont-allow-this-api-provider) 顯示每條訊息。

212

213* **允許 LLM 閘道或代理**：列出 `"customEndpoint"` 並在同一來源的受管 `env` 區塊中設定閘道的 URL。[設定參考](/docs/zh-TW/settings-reference#allowedproviders) 列出每個值並說明哪些端點變數需要受管 `env` 釘選。

214* **在受管機器上部署**：將清單放在承載您其餘原則的受管來源中。該項目的 [範圍注記](/docs/zh-TW/settings-reference#allowedproviders) 說明伺服器受管清單如何與其結合。

215* **僅伺服器受管設定**：您僅在 [伺服器受管設定](/docs/zh-TW/server-managed-settings) 中設定的清單只能到達擷取您組織設定的工作階段，因此將其視為您無法透過裝置管理到達的機器的便利性，而不是強制執行。[平台可用性](/docs/zh-TW/server-managed-settings#platform-availability) 列出哪些工作階段擷取它們。

216

197<h2 id="credential-management">217<h2 id="credential-management">

198 認證管理218 認證管理

199</h2>219</h2>

auto-mode-config.md +2 −6

Details

285 從 `/permissions` 編輯規則285 從 `/permissions` 編輯規則

286</h2>286</h2>

287 287

288若要檢視和編輯分類器規則而不開啟設定檔，請執行 [`/permissions`](/docs/zh-TW/permissions#manage-permissions) 並選取 **Auto mode** 索引標籤。該索引標籤需要 Claude Code v2.1.246 或更新版本，且僅在 [auto mode 可供您的工作階段使用](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 時才會出現。288若要檢視和編輯分類器規則和 `environment` 項目而不開啟設定檔，請執行 [`/permissions`](/docs/zh-TW/permissions#manage-permissions) 並選取 **Auto mode** 索引標籤。該索引標籤需要 Claude Code v2.1.246 或更新版本，且僅在 [auto mode 可供您的工作階段使用](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 時才會出現。

289 289

290該索引標籤列出來自 [分類器讀取的每個範圍](#where-the-classifier-reads-configuration) 的 `allow`、`soft_deny`、`hard_deny` 和 `environment` 項目，並顯示內建規則是否對每個區段生效。Claude Code 會將來自 [managed settings](/docs/zh-TW/server-managed-settings) 或 `--settings` 旗標的項目顯示為唯讀，並將您在該索引標籤上所做的每項變更儲存到 `~/.claude/settings.json`。從該索引標籤您可以：290Claude Code 會將來自 [managed settings](/docs/zh-TW/server-managed-settings) 或 `--settings` 旗標的項目顯示為唯讀，並將您在該索引標籤上所做的每項變更儲存到 `~/.claude/settings.json`。

~~291~~

292* 在 `allow`、`soft_deny` 和 `hard_deny` 區段中新增、編輯或刪除規則。當您在某個區段中新增第一個規則時，Claude Code 也會插入 `"$defaults"`，以便 [內建規則](#override-the-block-and-allow-rules) 保持生效。

293* 關閉或重新開啟 `allow`、`soft_deny` 或 `hard_deny` 的內建規則。Claude Code 會透過在您的該區段清單中新增或移除 `"$defaults"` 來記錄該選擇，因此在您可以關閉其內建規則之前，某個區段至少需要您自己的一個規則。

294* 在您的編輯器中將 `environment` 項目編輯為一份文件。如果您尚未設定任何 `environment` 項目，Claude Code 會先詢問是否要取代內建環境，然後在完整的內建文字上開啟編輯器。當您儲存時，Claude Code 會將您的 `autoMode.environment` 陣列取代為該文件。包含 `"$defaults"` 行以 [保留內建項目](#define-trusted-infrastructure)。

295 291

296<h2 id="route-all-shell-commands-through-the-classifier">292<h2 id="route-all-shell-commands-through-the-classifier">

297 透過分類器路由所有 shell 命令293 透過分類器路由所有 shell 命令

claude-apps-gateway-config.md +2 −0

Details

1396 1396

1397`parentSettingsBehavior: "merge"` 保持 Claude Desktop 將出站允許清單傳遞到其嵌入式 Claude Code 工作階段的功能；[將原則傳遞到 Claude Desktop 工作階段](/docs/zh-TW/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)說明了機制以及選擇加入必須位於何處。1397`parentSettingsBehavior: "merge"` 保持 Claude Desktop 將出站允許清單傳遞到其嵌入式 Claude Code 工作階段的功能；[將原則傳遞到 Claude Desktop 工作階段](/docs/zh-TW/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)說明了機制以及選擇加入必須位於何處。

1398 1398

1399若要防止開發人員使用雲端提供者變數或自己的 `ANTHROPIC_BASE_URL` 繞過閘道，請將 `"allowedProviders": ["gateway"]` 新增到同一檔案。Claude Code 隨後會拒絕機器上未設定為 Cloud 閘道的每個工作階段，並且僅在閘道是 `forceLoginGatewayUrl` 命名的閘道或檔案的 `env` 區塊設定為 `ANTHROPIC_BASE_URL` 的 URL 的閘道時才允許。`claude gateway` 拒絕在設定清單的機器上執行，因此請將鍵保留在閘道主機之外。請參閱設定參考中的 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 項目。需要 Claude Code v2.1.285 或更新版本。

1400

1399將 `managed-settings.json` 檔案部署到每個裝置，通常透過您的 MDM 平台。檔案路徑因平台而異。請參閱[每個機制儲存原則的位置](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy)。1401將 `managed-settings.json` 檔案部署到每個裝置，通常透過您的 MDM 平台。檔案路徑因平台而異。請參閱[每個機制儲存原則的位置](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy)。

1400 1402

1401根據預設，Windows 上的登錄原則或 macOS 上的受管偏好設定 plist 會取代 `managed-settings.json` 檔案，而不是與其合併，除了[上面的例外鍵和跨來源檢查](#precedence-with-other-managed-sources)。此程式碼片段中的所有三個鍵都遵循最高優先順序來源規則，因此透過群組原則或設定檔傳遞原則的機隊必須改為在該機制中放置全部三個。1403根據預設，Windows 上的登錄原則或 macOS 上的受管偏好設定 plist 會取代 `managed-settings.json` 檔案，而不是與其合併，除了[上面的例外鍵和跨來源檢查](#precedence-with-other-managed-sources)。此程式碼片段中的所有三個鍵都遵循最高優先順序來源規則，因此透過群組原則或設定檔傳遞原則的機隊必須改為在該機制中放置全部三個。

cli-reference.md +4 −3

Details

84| `--dangerously-skip-permissions` | 跳過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱[權限模式](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)以了解此操作跳過和不跳過的內容。對於使用 `--bg` 啟動的工作階段，當主管重新啟動工作階段時，模式[會保留](/docs/zh-TW/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |84| `--dangerously-skip-permissions` | 跳過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱[權限模式](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)以了解此操作跳過和不跳過的內容。對於使用 `--bg` 啟動的工作階段，當主管重新啟動工作階段時，模式[會保留](/docs/zh-TW/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |

87| `--desktop` | 在目前目錄上開啟 [Claude Desktop 應用程式](/docs/zh-TW/desktop)並結束而不在終端機中啟動工作階段。新增 `--continue` 或 `--resume` 搭配工作階段 ID，以[在 Desktop 中開啟該工作階段](/docs/zh-TW/desktop#coming-from-the-cli)。此處的 `--resume` 僅採用工作階段 ID，不採用名稱或文字記錄路徑。不採用提示和其他旗標，除了 `--verbose` 和 `--debug` 旗標，因為應用程式會自行啟動工作階段。在 macOS 和 x64 Windows 上可用，當您使用 Claude 訂閱登入時。需要 Claude Code v2.1.285 或更新版本 | `claude --desktop` |

88| `--disallowedTools`, `--disallowed-tools` | 拒絕規則。裸工具名稱會從 Claude 的內容中移除相符的工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)`）會保留工具可用，並僅拒絕[如所寫](/docs/zh-TW/permissions#bash-rule-limits)相符的呼叫。命名 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的規則在任何其他工具保持時無法移除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |89| `--disallowedTools`, `--disallowed-tools` | 拒絕規則。裸工具名稱會從 Claude 的內容中移除相符的工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)`）會保留工具可用，並僅拒絕[如所寫](/docs/zh-TW/permissions#bash-rule-limits)相符的呼叫。命名 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的規則在任何其他工具保持時無法移除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

89| `--effort` | 為目前工作階段設定[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用的等級取決於模型。`ultracode` 要求 `xhigh` 努力並[啟用 ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更新版本。覆蓋此工作階段的 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 設定，不會保留 | `claude --effort high` |90| `--effort` | 為目前工作階段設定[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用的等級取決於模型。`ultracode` 要求 `xhigh` 努力並[啟用 ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更新版本。覆蓋此工作階段的 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 設定，不會保留 | `claude --effort high` |

112| `--no-session-persistence` | 停用工作階段持續性，使工作階段不會儲存到磁碟且無法恢復。僅列印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/zh-TW/env-vars) 環境變數在任何模式中執行相同操作 | `claude -p --no-session-persistence "query"` |113| `--no-session-persistence` | 停用工作階段持續性，使工作階段不會儲存到磁碟且無法恢復。僅列印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/zh-TW/env-vars) 環境變數在任何模式中執行相同操作 | `claude -p --no-session-persistence "query"` |

114| `--permission-mode` | 以指定的[權限模式](/docs/zh-TW/permission-modes)開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 `manual` 作為 `default` 的別名。`manual` 別名選擇 UI 標籤為 Manual 的權限模式，需要 Claude Code v2.1.200 或更新版本；`claude --help` 會列出它代替 `default`，兩個值都有效。覆蓋設定檔案中的 `defaultMode`。沒有此旗標或 `--dangerously-skip-permissions`，新工作階段會以[工作階段開始的權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)中描述的權限模式開始。對於 `-p`，當未設定任何內容時為 `default` | `claude --permission-mode plan` |115| `--permission-mode` | 以指定的[權限模式](/docs/zh-TW/permission-modes)開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 `manual` 作為 `default` 的別名。`manual` 別名選擇 UI 標籤為 Manual 的權限模式，需要 Claude Code v2.1.200 或更新版本；`claude --help` 會列出它代替 `default`，兩個值都有效。覆蓋設定檔案中的 `defaultMode`。沒有此旗標或 `--dangerously-skip-permissions`，新工作階段會以[工作階段開始的權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)中描述的權限模式開始，這也涵蓋 `-p` 執行開始的內容 | `claude --permission-mode plan` |

115| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式中處理權限提示。Claude Code 會等待該工具的 MCP 伺服器連線，直到 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）。<br /><br />提示工具無法核准標記為[需要使用者互動](/docs/zh-TW/mcp#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 會將其 `allow` 結果轉換為拒絕。此限制需要 Claude Code v2.1.199 或更新版本 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |116| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式中處理權限提示。Claude Code 會等待該工具的 MCP 伺服器連線，直到 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）。<br /><br />提示工具無法核准標記為[需要使用者互動](/docs/zh-TW/mcp#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 會將其 `allow` 結果轉換為拒絕。此限制需要 Claude Code v2.1.199 或更新版本 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

116| `--permission-prompts` | 在列印模式中設定誰回答權限提示。使用預設 `host`，Claude Code 會將它們傳送到 Agent SDK 主機或 `--permission-prompt-tool` 工具。當沒有人可以回答時傳遞 `none`，Claude Code 會改為拒絕它們。請參閱[在無人值守執行中關閉權限提示](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更新版本 | `claude -p --permission-prompts none "query"` |117| `--permission-prompts` | 在列印模式中設定誰回答權限提示。使用預設 `host`，Claude Code 會將它們傳送到 Agent SDK 主機或 `--permission-prompt-tool` 工具。當沒有人可以回答時傳遞 `none`，Claude Code 會改為拒絕它們。請參閱[在無人值守執行中關閉權限提示](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更新版本 | `claude -p --permission-prompts none "query"` |

117| `--plugin-dir` | 從目錄或 `.zip` 封存載入 plugin，或從[plugins 資料夾](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session)載入多個，僅供此工作階段使用。每個旗標採用一個路徑。重複旗標以取得更多路徑：`--plugin-dir A --plugin-dir B.zip`。傳遞 plugins 資料夾需要 Claude Code v2.1.265 或更新版本 | `claude --plugin-dir ./my-plugin` |118| `--plugin-dir` | 從目錄或 `.zip` 封存載入 plugin，或從[plugins 資料夾](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session)載入多個，僅供此工作階段使用。每個旗標採用一個路徑。重複旗標以取得更多路徑：`--plugin-dir A --plugin-dir B.zip`。傳遞 plugins 資料夾需要 Claude Code v2.1.265 或更新版本 | `claude --plugin-dir ./my-plugin` |

119| `--print`, `-p` | 列印回應而不進行互動模式（請參閱 [Agent SDK 文件](/docs/zh-TW/agent-sdk/overview)以取得程式設計使用詳細資訊） | `claude -p "query"` |120| `--print`, `-p` | 列印回應而不進行互動模式（請參閱 [Agent SDK 文件](/docs/zh-TW/agent-sdk/overview)以取得程式設計使用詳細資訊）。對於在仍在執行的背景工作階段上 `--resume`，請參閱[恢復工作階段](/docs/zh-TW/sessions#resume-a-running-background-session) | `claude -p "query"` |

120| `--prompt-suggestions` | 在產生提示建議的每個轉後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示；非常短的對話可能不會產生任何提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱[提示建議](/docs/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |121| `--prompt-suggestions` | 在產生提示建議的每個轉後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示；非常短的對話可能不會產生任何提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱[提示建議](/docs/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

124| `--remote-control-session-name-prefix <prefix>` | 當未設定明確名稱時，[遠端控制](/docs/zh-TW/remote-control)自動產生工作階段名稱的前置詞。預設為您機器的主機名稱，產生名稱如 `myhost-graceful-unicorn`。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以取得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |125| `--remote-control-session-name-prefix <prefix>` | 當未設定明確名稱時，[遠端控制](/docs/zh-TW/remote-control)自動產生工作階段名稱的前置詞。預設為您機器的主機名稱，產生名稱如 `myhost-graceful-unicorn`。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以取得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |

125| `--replay-user-messages` | 從 stdin 重新發出使用者訊息回到 stdout 以進行確認。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |126| `--replay-user-messages` | 從 stdin 重新發出使用者訊息回到 stdout 以進行確認。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

126| `--restricted` | 以受限模式啟動。當評估工具在共用機器上驅動 `claude` 且 Claude Code 不得執行命令或讀取該機器的使用者和專案設定時使用。Claude Code 會移除執行命令或程式碼的內建工具以及 WebFetch，除非您在 `--tools` 中個別命名它們，而不是透過 `default` 預設集。它也會將內建檔案工具限制在[工作目錄](/docs/zh-TW/permissions#working-directories)、僅載入[受管設定](/docs/zh-TW/managed-settings)和 `--settings`、拒絕 [`bypassPermissions`](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，以及[拒絕從受限工作階段建立雲端工作階段](/docs/zh-TW/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更新版本 | `claude --restricted -p "query"` |127| `--restricted` | 以受限模式啟動。當評估工具在共用機器上驅動 `claude` 且 Claude Code 不得執行命令或讀取該機器的使用者和專案設定時使用。Claude Code 會移除執行命令或程式碼的內建工具以及 WebFetch，除非您在 `--tools` 中個別命名它們，而不是透過 `default` 預設集。它也會將內建檔案工具限制在[工作目錄](/docs/zh-TW/permissions#working-directories)、僅載入[受管設定](/docs/zh-TW/managed-settings)和 `--settings`、拒絕 [`bypassPermissions`](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，以及[拒絕從受限工作階段建立雲端工作階段](/docs/zh-TW/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更新版本 | `claude --restricted -p "query"` |

127| `--resume`, `-r` | 按 ID 或名稱恢復特定工作階段，或顯示互動選擇器以選擇工作階段。代替 ID，您可以傳遞工作階段 `.jsonl` [文字記錄檔](/docs/zh-TW/sessions#where-transcripts-are-stored)的絕對路徑。選擇器和名稱搜尋包括使用 `/add-dir` 新增此目錄的工作階段。當您傳遞工作階段 ID 時，Claude Code 會搜尋目前專案目錄及其 git worktrees，然後搜尋此機器上的所有其他專案。在 v2.1.223 之前，ID 搜尋僅涵蓋目前專案目錄及其 git worktrees。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中顯示，標記為 `bg` | `claude --resume auth-refactor` |128| `--resume`, `-r` | 按 ID 或名稱恢復特定工作階段，或顯示互動選擇器以選擇工作階段。代替 ID，您可以傳遞工作階段 `.jsonl` [文字記錄檔](/docs/zh-TW/sessions#where-transcripts-are-stored)的絕對路徑。選擇器和名稱搜尋包括使用 `/add-dir` 新增此目錄的工作階段。當您傳遞工作階段 ID 時，Claude Code 會搜尋目前專案目錄及其 git worktrees，然後搜尋此機器上的所有其他專案。在 v2.1.223 之前，ID 搜尋僅涵蓋目前專案目錄及其 git worktrees。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中顯示，標記為 `bg`。恢復仍在執行的工作階段[在此終端機中開啟該工作階段](/docs/zh-TW/sessions#resume-a-running-background-session)透過 `claude attach`，您在命令列上傳遞的提示會作為其下一個轉傳送給它。在 v2.1.285 之前，Claude Code 拒絕並列印 `claude attach` 命令以改為執行 | `claude --resume auth-refactor` |

128| `--safe-mode` | 以所有自訂停用開始以疑難排解損壞的設定：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理程式、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶不會載入。驗證、模型選擇、內建工具和權限正常運作，這與 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) 不同。受管設定原則仍適用，包括原則設定的 hooks、狀態列和檔案建議命令；受管 plugins、受管 skills、受管 CLAUDE.md 和原則設定的 MCP 伺服器不適用。用於檢查自訂是否觸發[自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)。設定 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-TW/env-vars) | `claude --safe-mode` |129| `--safe-mode` | 以所有自訂停用開始以疑難排解損壞的設定：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理程式、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶不會載入。驗證、模型選擇、內建工具和權限正常運作，這與 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) 不同。受管設定原則仍適用，包括原則設定的 hooks、狀態列和檔案建議命令；受管 plugins、受管 skills、受管 CLAUDE.md 和原則設定的 MCP 伺服器不適用。用於檢查自訂是否觸發[自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)。設定 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-TW/env-vars) | `claude --safe-mode` |

130| `--setting-sources` | 要載入的設定來源的逗號分隔清單（`user`、`project`、`local`）。請參閱[代理程式檢視](/docs/zh-TW/agent-view#what-carries-over-when-you-background)和[代理程式團隊](/docs/zh-TW/agent-teams#context-and-communication)以了解您從此工作階段啟動的工作階段繼承清單 | `claude --setting-sources user,project` |131| `--setting-sources` | 要載入的設定來源的逗號分隔清單（`user`、`project`、`local`）。請參閱[代理程式檢視](/docs/zh-TW/agent-view#what-carries-over-when-you-background)和[代理程式團隊](/docs/zh-TW/agent-teams#context-and-communication)以了解您從此工作階段啟動的工作階段繼承清單 | `claude --setting-sources user,project` |

cloud-environments.md +1 −1

Details

439 439

440* **Claude 執行的命令**：雲端環境不會設定自己的命令逾時，因此 Bash 工具的預設值適用。Claude 預設等待前景命令 2 分鐘，最多可要求 10 分鐘。440* **Claude 執行的命令**：雲端環境不會設定自己的命令逾時，因此 Bash 工具的預設值適用。Claude 預設等待前景命令 2 分鐘，最多可要求 10 分鐘。

441 441

442 當命令達到其[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)時，Claude Code [將其移到背景](/docs/zh-TW/tools-reference#background-commands)，而不是停止它，除非命令以 `sleep` 開頭。以這種方式移動的命令可以繼續執行最多 30 分鐘，然後 Claude Code 在其[背景時間限制](/docs/zh-TW/tools-reference#background-commands)處停止它。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為 `1800000` 毫秒以上會延長該限制以及前景預設值。442 當命令達到其[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)時，Claude Code [將其移到背景](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 開頭。以這種方式移動的命令可以繼續執行最多 30 分鐘，然後 Claude Code 在其[背景時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)處停止它。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為 `1800000` 毫秒以上會延長該限制以及前景預設值。

443* **SessionStart hooks**：Claude Code 在 600 秒後取消 `command` hook，除非您在 hook 項目上設定 [`timeout`](/docs/zh-TW/hooks#common-fields)（以秒為單位）。Claude Code 不會對您使用 [`async: true`](/docs/zh-TW/hooks#run-hooks-in-the-background) 執行的 hook 強制執行逾時。443* **SessionStart hooks**：Claude Code 在 600 秒後取消 `command` hook，除非您在 hook 項目上設定 [`timeout`](/docs/zh-TW/hooks#common-fields)（以秒為單位）。Claude Code 不會對您使用 [`async: true`](/docs/zh-TW/hooks#run-hooks-in-the-background) 執行的 hook 強制執行逾時。

444* **設定指令碼**：花費超過大約五分鐘的指令碼不會被快取。[指令碼需求](#script-requirements)涵蓋如何保持在該時間以下。444* **設定指令碼**：花費超過大約五分鐘的指令碼不會被快取。[指令碼需求](#script-requirements)涵蓋如何保持在該時間以下。

445* **閒置工作階段**：在幾分鐘沒有活動後，工作階段的 VM 會暫停並保存其檔案，稍後可以回收暫停的 VM。[設定環境變數](#set-environment-variables)描述工作階段在每種情況下會取得什麼，[環境已過期](/docs/zh-TW/claude-code-on-the-web#environment-expired)涵蓋如何重新開啟其 VM 已被回收的工作階段。445* **閒置工作階段**：在幾分鐘沒有活動後，工作階段的 VM 會暫停並保存其檔案，稍後可以回收暫停的 VM。[設定環境變數](#set-environment-variables)描述工作階段在每種情況下會取得什麼，[環境已過期](/docs/zh-TW/claude-code-on-the-web#environment-expired)涵蓋如何重新開啟其 VM 已被回收的工作階段。

commands.md +1 −1

Details

132| `/remote-control` | 使此工作階段可從 claude.ai 進行[遠端控制](/docs/zh-TW/remote-control)。在登出時運行它會列印遠端控制需要 claude.ai 訂閱並告訴您如何登入；在 v2.1.206 之前它報告 `Unknown command: /remote-control`。別名：`/rc` |132| `/remote-control` | 使此工作階段可從 claude.ai 進行[遠端控制](/docs/zh-TW/remote-control)。在登出時運行它會列印遠端控制需要 claude.ai 訂閱並告訴您如何登入；在 v2.1.206 之前它報告 `Unknown command: /remote-control`。別名：`/rc` |

134| `/rename [name]` | 重新命名目前工作階段並在提示詞欄上顯示名稱。沒有名稱時，從對話歷史記錄自動生成一個。也可在非互動模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更新版本。從每個重新命名表面，包括 claude.ai 和桌面應用程式，Claude Code 會用空格替換新名稱中的控制和不可見字元，並將名稱上限設為 200 個字元。一旦不可見字元被移除，如果名稱為空，Claude Code 會拒絕它並顯示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字元替換和長度上限需要 Claude Code v2.1.221 或更新版本。如果此機器上的另一個活動工作階段已使用您傳遞的名稱，Claude Code 會改為應用[它的變體](/docs/zh-TW/sessions#name-your-sessions) |134| `/rename [name]` | 重新命名目前工作階段並在提示詞欄上顯示名稱。沒有名稱時，從對話歷史記錄自動生成一個。也可在非互動模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更新版本。從每個重新命名表面，包括 claude.ai 和桌面應用程式，Claude Code 會用空格替換新名稱中的控制和不可見字元，並將名稱上限設為 200 個字元。一旦不可見字元被移除，如果名稱為空，Claude Code 會拒絕它並顯示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字元替換和長度上限需要 Claude Code v2.1.221 或更新版本。如果此機器上的另一個活動工作階段已使用您傳遞的名稱，Claude Code 會改為應用[它的變體](/docs/zh-TW/sessions#name-your-sessions) |

135| `/resume [session]` | 按 ID 或名稱恢復對話，或打開工作階段選擇器。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中標記為 `bg` 出現；仍在運行的工作階段無法在此恢復，因此從 `claude agents` 附加到它或先在那裡停止它。別名：`/continue` |135| `/resume [session]` | 按 ID 或名稱恢復對話，或打開工作階段選擇器。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中標記為 `bg` 出現。恢復仍在運行的工作階段，從選擇器或按 ID 或名稱，[打開該工作階段](/docs/zh-TW/sessions#resume-a-running-background-session)：您目前的對話移動到背景，此終端附加到運行中的工作階段。在空提示詞上按 `←` 返回代理檢視，這也列出您留下的對話。在 v2.1.285 之前，Claude Code 拒絕並告訴您使用 `claude attach` 打開工作階段或先在那裡停止它。別名：`/continue` |

136| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/zh-TW/code-review#review-a-diff-locally) 的別名：檢查目前差異或您傳遞的 PR 編號、分支或路徑，例如 `/review 1234`，並採用相同的工作量級別和標誌。沒有給定級別時，檢查重複使用您最後輸入的 `low` 到 `max` 級別；有關確切規則，請參閱[本地檢查差異](/docs/zh-TW/code-review#review-a-diff-locally)。對於深度雲端檢查，使用 [`/code-review ultra`](/docs/zh-TW/ultrareview)。在 v2.1.223 之前，`/review` 是一個單獨的命令，按編號對 GitHub 拉取請求進行單次通過、唯讀檢查，在運行時不帶引數時列出打開的 PR 以選擇；從 v2.1.186 到 v2.1.201，它運行與 `/code-review medium` 相同的多代理引擎 |136| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/zh-TW/code-review#review-a-diff-locally) 的別名：檢查目前差異或您傳遞的 PR 編號、分支或路徑，例如 `/review 1234`，並採用相同的工作量級別和標誌。沒有給定級別時，檢查重複使用您最後輸入的 `low` 到 `max` 級別；有關確切規則，請參閱[本地檢查差異](/docs/zh-TW/code-review#review-a-diff-locally)。對於深度雲端檢查，使用 [`/code-review ultra`](/docs/zh-TW/ultrareview)。在 v2.1.223 之前，`/review` 是一個單獨的命令，按編號對 GitHub 拉取請求進行單次通過、唯讀檢查，在運行時不帶引數時列出打開的 PR 以選擇；從 v2.1.186 到 v2.1.201，它運行與 `/code-review medium` 相同的多代理引擎 |

138| `/run` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 啟動並驅動您的專案應用程式以查看變更工作，而不僅僅是通過測試。請參閱[運行和驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app) |138| `/run` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 啟動並驅動您的專案應用程式以查看變更工作，而不僅僅是通過測試。請參閱[運行和驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app) |

context-window.md +1 −1

Details

1634 1634

1635如果您需要更大的視窗而不是更小的對話，Fable 模型、Sonnet 5 及更高版本、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 萬令牌上下文視窗。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解按計劃的可用性以及如何選擇 `[1m]` 模型變體。壓縮在更大的限制下以相同方式工作。1635如果您需要更大的視窗而不是更小的對話，Fable 模型、Sonnet 5 及更高版本、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 萬令牌上下文視窗。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解按計劃的可用性以及如何選擇 `[1m]` 模型變體。壓縮在更大的限制下以相同方式工作。

1636 1636

1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文視窗運行，沒有 `[1m]` 變體可選擇。請參閱[Sonnet 5.5 和 Sonnet 5 上下文視窗](/docs/zh-TW/model-config#sonnet-5-5-and-sonnet-5-context-window)以了解其自動壓縮閾值和 LLM 閘道例外。1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文視窗運行，沒有 `[1m]` 變體可選擇。請參閱[Sonnet 5.5 和 Sonnet 5 上下文視窗](/docs/zh-TW/model-config#sonnet-5-5-and-sonnet-5-context-window)以了解其自動壓縮閾值，以及[閘道後面的上下文視窗](/docs/zh-TW/model-config#context-window-behind-a-gateway)以了解當您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](/docs/zh-TW/llm-gateway)時 Claude Code 如何調整視窗大小。

1638 1638

1639自動壓縮運行的位置取決於您的模型和設定。請參閱[預設自動壓縮閾值](/docs/zh-TW/model-config#default-auto-compact-thresholds)以了解每個模型的邊界，以及[為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)，如果 Claude Code 為您的模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）假設了錯誤的視窗。1639自動壓縮運行的位置取決於您的模型和設定。請參閱[預設自動壓縮閾值](/docs/zh-TW/model-config#default-auto-compact-thresholds)以了解每個模型的邊界，以及[為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)，如果 Claude Code 為您的模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）假設了錯誤的視窗。

1640 1640

costs.md +1 −1

Details

51 51

52行中的未命中、預期重建以及溫暖或冷部分的含義如下：52行中的未命中、預期重建以及溫暖或冷部分的含義如下：

53 53

54* **Misses**：重新處理快取已保存內容的請求，包括最後一次未命中的時間以及這些請求寫回快取的 token 數量。當請求重新處理超過 5% 且至少 2,000 個 token 的內容時，Claude Code 會將請求計為未命中，這些內容本可從快取中讀取。[使快取失效的操作](/docs/zh-TW/prompt-caching#actions-that-invalidate-the-cache)列出了常見原因。當 Claude Code 可以識別最後一次未命中的可能原因時，該行也會命名它，例如 `likely cause: tool definitions changed`。可能原因文字需要 Claude Code v2.1.260 或更新版本。54* **Misses**：重新處理快取已保存內容的請求，包括最後一次未命中的時間以及這些請求寫回快取的 token 數量。[使快取失效的操作](/docs/zh-TW/prompt-caching#actions-that-invalidate-the-cache)列出了常見原因。當 Claude Code 可以識別最後一次未命中的可能原因時，該行也會命名它，例如 `likely cause: tool definitions changed`。可能原因文字需要 Claude Code v2.1.260 或更新版本。

55* **Expected rebuilds**：當 Claude Code 本身剛剛重寫對話時，通過[壓縮](/docs/zh-TW/prompt-caching#compacting-the-conversation)或從上下文中清除舊工具結果，它會將相同類型的未命中計為預期重建。此部分僅在至少發生一次預期重建後才出現。55* **Expected rebuilds**：當 Claude Code 本身剛剛重寫對話時，通過[壓縮](/docs/zh-TW/prompt-caching#compacting-the-conversation)或從上下文中清除舊工具結果，它會將相同類型的未命中計為預期重建。此部分僅在至少發生一次預期重建後才出現。

56* **Warm or cold**：快取的前綴是否仍在其[快取生命週期](/docs/zh-TW/prompt-caching#cache-lifetime)內，以及生效的 TTL。當快取冷時，該行顯示工作階段已閒置多長時間。當沒有回應報告快取 token 時，該行以 `no prompt caching reported by the API` 結尾。56* **Warm or cold**：快取的前綴是否仍在其[快取生命週期](/docs/zh-TW/prompt-caching#cache-lifetime)內，以及生效的 TTL。當快取冷時，該行顯示工作階段已閒置多長時間。當沒有回應報告快取 token 時，該行以 `no prompt caching reported by the API` 結尾。

57 57

desktop.md +8 −0

Details

967 967

968若要將 CLI 會話移至 Desktop，請在終端機中執行 `/desktop`。Claude 儲存您的會話並在桌面應用程式中開啟它，然後退出 CLI。此命令在 macOS 和 x64 Windows 上可用，當您使用 Claude 訂閱登入時。它不適用於 API 金鑰驗證或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。968若要將 CLI 會話移至 Desktop，請在終端機中執行 `/desktop`。Claude 儲存您的會話並在桌面應用程式中開啟它，然後退出 CLI。此命令在 macOS 和 x64 Windows 上可用，當您使用 Claude 訂閱登入時。它不適用於 API 金鑰驗證或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

969 969

970從您的 shell，[`claude --desktop`](/docs/zh-TW/cli-reference#cli-flags) 直接開啟 Desktop，無需啟動終端機會話。它需要 Claude Code v2.1.285 或更新版本，並具有與 `/desktop` 相同的平台和登入要求。沒有其他引數時，它會在目前目錄中開啟 Desktop。若要在 Desktop 中開啟現有的 CLI 會話，請為此目錄中最近的對話新增 `--continue`，或使用 `/status` 顯示的會話 ID 新增 `--resume`：

971

972```bash theme={null}

973claude --desktop --resume <session-id>

974```

975

976Claude Code 列印 `Opening session <session-id> in Claude Desktop`，會話在應用程式中開啟，命令退出。會話名稱不能代替 ID。Claude Code 不會移動在另一個終端機中開啟或仍在背景執行的會話。如果未安裝 Claude Desktop，命令會列印下載連結並退出。

977

970您也可以從 Desktop 內部使用 `/resume` 取得 CLI 會話。此命令在本機會話中可用，不在 SSH、WSL 或雲端會話中可用。978您也可以從 Desktop 內部使用 `/resume` 取得 CLI 會話。此命令在本機會話中可用，不在 SSH、WSL 或雲端會話中可用。

971 979

972若要在 Desktop 中繼續終端機會話：980若要在 Desktop 中繼續終端機會話：

errors.md +61 −33

Details

323| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [工作階段儲存警告](#transcript-saving-is-off-skip-prompt-history) |323| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [工作階段儲存警告](#transcript-saving-is-off-skip-prompt-history) |

324| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [工作階段儲存警告](#transcript-saving-is-off-child-session-marker) |324| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [工作階段儲存警告](#transcript-saving-is-off-child-session-marker) |

325| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [設定警告](#fullscreen-failed-start-notice) |325| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [全螢幕轉譯](/docs/zh-TW/fullscreen#fullscreen-renderer-didnt-finish-starting) |

326| `Claude Code exited after an unrecoverable interface error (...)` | [設定警告](#exited-after-an-unrecoverable-interface-error) |326| `Claude Code exited after an unrecoverable interface error (...)` | [設定警告](#exited-after-an-unrecoverable-interface-error) |

328| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [設定警告](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |328| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [設定警告](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |

333| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [設定警告](#managed-settings-block-the-default-model) |333| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [設定警告](#managed-settings-block-the-default-model) |

334| `Your organization's managed settings allow Claude Code to use: <providers>` | [設定警告](#managed-settings-dont-allow-this-api-provider) |

335| `Your organization's managed settings allow Claude Code to use no API provider at all` | [設定警告](#managed-settings-dont-allow-this-api-provider) |

334| `MCP server <name> is blocked by enterprise managed policy` | [設定警告](#mcp-server-is-blocked-by-enterprise-managed-policy) |336| `MCP server <name> is blocked by enterprise managed policy` | [設定警告](#mcp-server-is-blocked-by-enterprise-managed-policy) |

335| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [設定警告](#managed-settings-document-could-not-be-parsed) |337| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [設定警告](#managed-settings-document-could-not-be-parsed) |

339| `Unable to read managed policy settings` | [設定警告](#unable-to-read-managed-policy-settings) |

338| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [設定警告](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |341| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [設定警告](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |

3208"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.3211"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

3209```3212```

3210 3213

3211Claude Code 按 URL 匹配這些主機，所以當您使用 `claude mcp add` 或在 `.mcp.json` 中新增的伺服器指向其中之一時，訊息會出現。

~~3212~~

3213**該怎麼做：**3214**該怎麼做：**

3214 3215

3215* 使用 `claude mcp remove <name>` 移除您的項目，以便它無法隱藏相同 URL 上的 claude.ai 連接器3216* 使用 `claude mcp remove <name>` 移除您的項目，以便它無法隱藏相同 URL 上的 claude.ai 連接器

3657 無法開啟 Claude Desktop3658 無法開啟 Claude Desktop

3658</h3>3659</h3>

3659 3660

3660您執行了 [`/desktop`](/docs/zh-TW/desktop#coming-from-the-cli) 或其別名 `/app`，Claude Code 用來開啟 Claude Desktop 的系統命令失敗。工作階段保持在終端中。3661您執行了 [`/desktop`](/docs/zh-TW/desktop#coming-from-the-cli) 或其別名 `/app` 在工作階段中，或在您的 shell 中執行了 [`claude --desktop`](/docs/zh-TW/cli-reference#cli-flags)，Claude Code 用來開啟 Claude Desktop 的系統命令失敗。在 `/desktop` 後，工作階段保持在終端中；`claude --desktop` 列印訊息而沒有 `Error:` 前綴並以狀態 1 結束。

3662

3663括號中的文字命名失敗的命令，帶有其結束狀態和其錯誤輸出的第一行（如果它產生了）。在 macOS 上該命令是 `open`，如此範例；在 Windows 上它是 `rundll32`：

3661 3664

3662```text theme={null}3665```text theme={null}

3663Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and run /desktop again.3666Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

3664```3667```

3665 3668

3666**該怎麼做：**3669**該怎麼做：**

3667 3670

3668* 自己開啟 Claude Desktop，然後再次執行 `/desktop`3671* 自己開啟 Claude Desktop，然後再次執行 `/desktop` 或 `claude --desktop`

3669* 若要讀取該命令的完整錯誤輸出，使用 `/debug` 開啟偵錯日誌，再次執行 `/desktop`，並檢查偵錯日誌3672* 若要讀取該命令的完整錯誤輸出，使用 `/debug` 開啟偵錯日誌，再次執行 `/desktop`，或執行 `claude --desktop --debug-file <path>`，然後檢查偵錯日誌

3670 3673

3671在 v2.1.275 之前，訊息是 `Failed to open Claude Desktop. Please try opening it manually.`，沒有說明什麼失敗。3674在 v2.1.285 之前，訊息以 `Open Claude Desktop and run /desktop again.` 結尾。在 v2.1.275 之前，它是 `Failed to open Claude Desktop. Please try opening it manually.`，沒有說明什麼失敗。

3672 3675

3673<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3676<h3 id="terminal-setup-left-your-zed-keymap-unchanged">

3674 /terminal-setup 保持您的 Zed 快捷鍵不變3677 /terminal-setup 保持您的 Zed 快捷鍵不變

4626terminal host process died — press Enter to restart4629terminal host process died — press Enter to restart

4627```4630```

4628 4631

4629如果您在檢查執行之前開啟列，頁腳顯示 `This session's terminal host process died (the conversation is saved) — press Enter to restart it`，列變為失敗。

~~4630~~

4631從殼層，`claude attach <id>` 重新啟動已標記為死主機失敗的工作階段，否則列印原因並退出：4632從殼層，`claude attach <id>` 重新啟動已標記為死主機失敗的工作階段，否則列印原因並退出：

4632 4633

4633```text theme={null}4634```text theme={null}

5023 5024

5024Claude Code 將大多數這些訊息寫入 stderr，而不是寫入對話中，並在啟動時寫入大多數訊息。當訊息出現在其他地方（例如在偵錯日誌中或作為對話檢視中的啟動通知）或在其他時間（例如[要求時的無法辨識模型診斷行](#unrecognized-model-id-on-a-request)）時，條目會說明這一點。5025Claude Code 將大多數這些訊息寫入 stderr，而不是寫入對話中，並在啟動時寫入大多數訊息。當訊息出現在其他地方（例如在偵錯日誌中或作為對話檢視中的啟動通知）或在其他時間（例如[要求時的無法辨識模型診斷行](#unrecognized-model-id-on-a-request)）時，條目會說明這一點。

5025 5026

5026<h3 id="fullscreen-failed-start-notice">

5027 全螢幕轉譯器未完成啟動

5028</h3>

~~5029~~

5030此機器上的先前[全螢幕](/docs/zh-TW/fullscreen)工作階段在完成啟動前退出，因此 Claude Code 在傳統轉譯器上啟動此工作階段並列印以下其中一個通知：

~~5031~~

5032```text theme={null}

5033Claude Code 的全螢幕轉譯器上次在此機器上未完成啟動，因此此次啟動使用傳統轉譯器。它將在下次啟動時嘗試全螢幕；/tui default 保持傳統轉譯器。

~~5034~~

5035Claude Code 的全螢幕轉譯器在此機器上多次啟動失敗，因此已在此處關閉。執行 /tui fullscreen 以再次嘗試（這也會在更新後重設）。

5036```

~~5037~~

5038**該怎麼做：**

~~5039~~

5040* 遵循[全螢幕轉譯](/docs/zh-TW/fullscreen#fullscreen-renderer-didnt-finish-starting)。它說明您會收到哪個通知、Claude Code 在後續工作階段中的作用，以及如何再次嘗試全螢幕或保持傳統轉譯器。

5041* 如果已終止的工作階段列印了結束訊息，請參閱 [Claude Code 在無法復原的介面錯誤後退出](#exited-after-an-unrecoverable-interface-error)以了解它命名的內容。

~~5042~~

5043在 v2.1.236 之前，Claude Code 未列印通知，並在啟動失敗後繼續在全螢幕轉譯中啟動工作階段。

~~5044~~

5045<h3 id="exited-after-an-unrecoverable-interface-error">5027<h3 id="exited-after-an-unrecoverable-interface-error">

5046 Claude Code 在無法復原的介面錯誤後退出5028 Claude Code 在無法復原的介面錯誤後退出

5047</h3>5029</h3>

5193* 如果您管理設定，將您的使用者可以執行的模型新增到 `availableModels`，或縮小阻止每個後備的 `deniedModels` 項目。[阻止特定模型或版本](/docs/zh-TW/model-config#block-specific-models-or-versions)描述預設選項如何降級5175* 如果您管理設定，將您的使用者可以執行的模型新增到 `availableModels`，或縮小阻止每個後備的 `deniedModels` 項目。[阻止特定模型或版本](/docs/zh-TW/model-config#block-specific-models-or-versions)描述預設選項如何降級

5194* 如果您不管理它們，將訊息傳送給您的管理員。您自己的設定檔案無法擴大受管 `availableModels` 或 `deniedModels` 清單5176* 如果您不管理它們，將訊息傳送給您的管理員。您自己的設定檔案無法擴大受管 `availableModels` 或 `deniedModels` 清單

5195 5177

5178<h3 id="managed-settings-dont-allow-this-api-provider">

5179 受管設定不允許此 API 提供者

5180</h3>

5181

5182您的組織的[受管設定](/docs/zh-TW/managed-settings)設定了 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 清單，且工作階段的 API 提供者不在其上，或工作階段使用的端點不是以該項目要求的方式固定的。Claude Code 在啟動前、登入前或工作階段下次聯絡 API 時拒絕。訊息以允許的提供者開頭：

5183

5184```text theme={null}

5185您的組織的受管設定允許 Claude Code 使用：Anthropic API、Amazon Bedrock。

5186```

5187

5188當清單為空時，訊息改為讀作：

5189

5190```text theme={null}

5191您的組織的受管設定允許 Claude Code 使用沒有 API 提供者（allowedProviders 是空清單），因此它無法在此機器上啟動。

5192```

5193

5194當每個項目都無法辨識時，括號讀作 `(allowedProviders lists only unrecognized entries)` 代替。

5195

5196**該怎麼做：**

5197

5198* 遵循訊息的 `To continue:` 步驟

5199* 如果您管理設定，訊息的以 `Admins:` 開頭的行命名要新增的項目或要固定的值，[`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 項目說明哪個來源的 `env` 區塊可以固定它

5200

5196<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5201<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">

5197 MCP 伺服器被企業受管策略阻止5202 MCP 伺服器被企業受管策略阻止

5198</h3>5203</h3>

5246* 如果您管理機器，修復命名的文件使其解析為 JSON 物件，或移除檔案、設定檔或登錄值。空的 `managed-settings.json` 計為 `{}` 且不會阻止啟動。5251* 如果您管理機器，修復命名的文件使其解析為 JSON 物件，或移除檔案、設定檔或登錄值。空的 `managed-settings.json` 計為 `{}` 且不會阻止啟動。

5247* 如果您不管理，請要求您的管理員修復已部署的文件。您自己的設定檔案中沒有任何內容會導致或清除此錯誤。5252* 如果您不管理，請要求您的管理員修復已部署的文件。您自己的設定檔案中沒有任何內容會導致或清除此錯誤。

5248 5253

5254<h3 id="unable-to-read-managed-policy-settings">

5255 無法讀取受管策略設定

5256</h3>

5257

5258您的組織部署[受管設定](/docs/zh-TW/managed-settings)，且其中一個已部署的來源存在但無法讀取，原因例如 I/O 錯誤而不是作業系統拒絕讀取。沒有其他管理來源提供策略，Claude Code 在啟動時退出，而不是執行而不使用來源可能帶來的策略：

5259

5260```text theme={null}

5261無法讀取受管策略設定。

5262此機器可能需要組織登入強制執行，但策略檔案無法載入。

5263聯絡您的管理員。

5264

5265詳細資訊：<source>: <reason>

5266```

5267

5268在相同狀態下，登入流程、來自已執行工作階段的 API 要求，以及 [`claude gateway`](/docs/zh-TW/claude-apps-gateway) 伺服器被拒絕，使用命名 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 的第一行變體。

5269

5270作業系統拒絕的讀取（例如在僅限根的檔案上）不會產生此退出：[工作階段啟動時不使用該來源的策略](/docs/zh-TW/managed-settings#find-entries-claude-code-dropped)。對於無法解析的來源，Claude Code 以[命名來源的不同訊息](#managed-settings-document-could-not-be-parsed)退出。

5271

5272**該怎麼做：**

5273

5274* 如果您管理機器，修復 `Detail:` 行命名的問題，以便已部署的來源可以讀取，或移除來源

5275* 如果您不管理，將訊息傳送給您的管理員。您自己的設定檔案中沒有任何內容會導致或清除此錯誤

5276

5277在 v2.1.285 之前，僅使用 claude.ai 或 Claude Console 認證登入的工作階段以此訊息退出，作業系統拒絕的讀取也產生了它。

5278

5249<h3 id="otelheadershelper-failed">5279<h3 id="otelheadershelper-failed">

5250 otelHeadersHelper 失敗5280 otelHeadersHelper 失敗

5251</h3>5281</h3>

5344* 在警告在括號中命名的來源處修復規則：設定檔案路徑，或 `--allowed-tools` 旗標本身。不存在於磁碟上的 `claude-settings-<hash>.json` 路徑代表內聯 `--settings` 值。修復您傳遞給該旗標的 JSON。5374* 在警告在括號中命名的來源處修復規則：設定檔案路徑，或 `--allowed-tools` 旗標本身。不存在於磁碟上的 `claude-settings-<hash>.json` 路徑代表內聯 `--settings` 值。修復您傳遞給該旗標的 JSON。

5345* 如果來源讀取 `managed policy settings`，將警告轉發給維護您受管設定的人，因為您無法自己清除它。5375* 如果來源讀取 `managed policy settings`，將警告轉發給維護您受管設定的人，因為您無法自己清除它。

5346 5376

5347Claude Code 不警告具有相同形狀的拒絕和詢問規則：它拒絕或提示它們相符的額外命令，而不是批准它們。它也不警告子命令在第一個 `*` 之前的規則，例如 `Bash(git commit *)`，或沒有單詞（除了選項）跟在 `*` 後的規則，例如 `Bash(git *)`，或關於 `:*` 前綴規則如 `Bash(git:*)`。

~~5348~~

5349在[背景工作階段](/docs/zh-TW/agent-view)或使用 `--output-format json` 或 `stream-json` 時，Claude Code 將警告寫入偵錯日誌而不是 stderr，因此機器讀取輸出保持乾淨。使用 `--debug` 在 `~/.claude/debug/<session-id>.txt` 處擷取它。在 v2.1.246 之前，Claude Code 接受這些規則而不警告。5377在[背景工作階段](/docs/zh-TW/agent-view)或使用 `--output-format json` 或 `stream-json` 時，Claude Code 將警告寫入偵錯日誌而不是 stderr，因此機器讀取輸出保持乾淨。使用 `--debug` 在 `~/.claude/debug/<session-id>.txt` 處擷取它。在 v2.1.246 之前，Claude Code 接受這些規則而不警告。

5350 5378

5351<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5379<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">

5458 回應品質似乎低於預期5486 回應品質似乎低於預期

5459</h2>5487</h2>

5460 5488

5461如果 Claude 的回答似乎不如您預期的那樣有能力，但沒有顯示錯誤，原因通常是對話狀態而非模型本身。Claude Code 不會無聲地更改模型版本。它只能在三種特定情況下切換到備用模型：5489如果 Claude 的回答似乎不如您預期的那樣有能力，但沒有顯示錯誤，原因通常是對話狀態而非模型本身。Claude Code 不會無聲地更改模型版本。它只能在這些情況下切換到備用模型：

5462 5490

5463* 配置的 [`--fallback-model`](/docs/zh-TW/cli-reference#cli-flags) 在可用性錯誤後接管該輪次，並在文字記錄中顯示通知5491* 配置的 [`--fallback-model`](/docs/zh-TW/cli-reference#cli-flags) 在可用性錯誤後接管該輪次，並在文字記錄中顯示通知

5464* Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用5492* Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用，或您的帳戶[在工作階段中途失去對它的存取權](/docs/zh-TW/amazon-bedrock#when-a-model-is-disabled-mid-session)

5465* [自動模型備用](/docs/zh-TW/model-config#automatic-model-fallback)在 Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5 和 Opus 5 上將工作階段移至標記類別的備用模型（當該類別有備用模型時），並在文字記錄中顯示通知5493* [自動模型備用](/docs/zh-TW/model-config#automatic-model-fallback)在 Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5 和 Opus 5 上將工作階段移至標記類別的備用模型（當該類別有備用模型時），並在文字記錄中顯示通知

5466 5494

5467下面的模型選擇檢查可以捕捉第二和第三種情況；第一種情況顯示為文字記錄通知而非 `/model` 變更。[模型設定](/docs/zh-TW/model-config)說明每個備用何時適用。5495下面的模型選擇檢查可以捕捉第二和第三種情況；第一種情況顯示為文字記錄通知而非 `/model` 變更。[模型設定](/docs/zh-TW/model-config)說明每個備用何時適用。

google-vertex-ai.md +12 −0

Details

293 293

294模型別名（例如 `opus`）不會作為固定，Claude Code 無法識別的模型 ID 也不會。294模型別名（例如 `opus`）不會作為固定，Claude Code 無法識別的模型 ID 也不會。

295 295

296當這些檢查發現您的專案無法呼叫的模型時，Claude Code 會在此機器上記住拒絕長達一天，並在該時間內啟動時略過記住的模型，而不會再次詢問 Agent Platform。Claude Code 會在距離上次檢查已過十分鐘後，再次檢查目前預設模型的記住拒絕，因此您的管理員重新啟用的預設值會恢復。若要關閉此記憶功能，請設定 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/zh-TW/env-vars)。

297

298<h3 id="when-a-model-is-disabled-mid-session">

299 當模型在工作階段中被停用時

300</h3>

301

302如果您的專案失去對工作階段執行所在模型的存取權，例如因為管理員在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中停用它，Claude Code 會將工作階段切換到另一個模型，而不是讓每個請求都失敗，並顯示 `Switched to <fallback> because <model> is not available`。它會嘗試與啟動回退相同的模型：先嘗試相同層級的較早版本，對於沒有可用 Opus 版本的 Opus 工作階段，則嘗試預設 Sonnet 模型。

303

304切換僅適用於您未固定的層級，這與啟動回退的條件相同。在您選擇的特定版本上的工作階段會保持其模型，且沒有回退模型鏈，請求會失敗。在 [auto mode](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) 中，Claude Code 只會切換到 Agent Platform 上 auto mode 支援的模型。如果這些模型都無法使用，請求會失敗。

305

306您設定的[回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains)會取代層級切換：在這些拒絕上，Claude Code 會切換到您設定的回退。若要讓被拒絕的請求失敗而不是切換，請設定 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/zh-TW/env-vars)。您設定的回退鏈仍會在這些拒絕上切換；如果您想讓每個被拒絕的請求都失敗，也請移除該鏈。

307

296<h2 id="iam-configuration">308<h2 id="iam-configuration">

297 IAM 設定309 IAM 設定

298</h2>310</h2>

headless.md +57 −57

Details

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

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 後續步驟

hooks.md +1 −3

Details

459 457

460當 Claude Code 無法確定 Bash 輸入執行哪些命令時，它無論如何都會執行您的 hook。因為 `if` 篩選器是盡力而為的，請使用 [權限系統](/docs/zh-TW/permissions) 而不是 hook 來強制執行硬允許或拒絕。458當 Claude Code 無法確定 Bash 輸入執行哪些命令時，它無論如何都會執行您的 hook。因為 `if` 篩選器是盡力而為的，請使用 [權限系統](/docs/zh-TW/permissions) 而不是 hook 來強制執行硬允許或拒絕。

1938| :- | :- |1936| :- | :- |

1939| `permissionDecision` | `"allow"` 跳過權限提示，除了 [任何模式自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves) 和 `AskUserQuestion` 和 `ExitPlanMode`，它們需要 [`updatedInput` 與它配對](#allow-with-updatedinput)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 無論 hook 返回什麼都會被評估 |1937| `permissionDecision` | `"allow"` 跳過權限提示，除了 [任何模式自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves) 和 `AskUserQuestion` 和 `ExitPlanMode`，它們需要 [`updatedInput` 與它配對](#allow-with-updatedinput)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 無論 hook 返回什麼都會被評估 |

1940| `permissionDecisionReason` | 對於 `"ask"`，顯示給使用者但不顯示 Claude。對於 `"deny"`，顯示給 Claude。對於 `"allow"` 和 `"defer"`，寫入 [debug log](#debug-hooks) 僅 |1938| `permissionDecisionReason` | 對於 `"ask"`，顯示給使用者但不顯示 Claude。對於 `"deny"`，顯示給 Claude。對於 `"allow"` 和 `"defer"`，寫入 [debug log](#debug-hooks) 僅 |

1941| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。Claude Code 根據您的 hook 返回的輸入評估權限規則和 Bash 命令的 [自動背景資格](/docs/zh-TW/tools-reference#background-commands)，而不是 Claude 傳送的輸入。與 `"allow"` 結合以自動核准，或與 `"ask"` 結合以向使用者顯示修改的輸入。對於 `"defer"`，忽略 |1939| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。Claude Code 根據您的 hook 返回的輸入評估權限規則和 Bash 命令的 [自動背景資格](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)，而不是 Claude 傳送的輸入。與 `"allow"` 結合以自動核准，或與 `"ask"` 結合以向使用者顯示修改的輸入。對於 `"defer"`，忽略 |

1942| `additionalContext` | 與工具結果一起新增到 Claude 背景資訊的字串。當 `permissionDecision` 為 `"defer"` 時忽略。有關詳細資訊，請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |1940| `additionalContext` | 與工具結果一起新增到 Claude 背景資訊的字串。當 `permissionDecision` 為 `"defer"` 時忽略。有關詳細資訊，請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |

1943 1941

1944當多個 PreToolUse hooks 返回不同的決定時，優先順序為 `deny` > `defer` > `ask` > `allow`。1942當多個 PreToolUse hooks 返回不同的決定時，優先順序為 `deny` > `defer` > `ask` > `allow`。

interactive-mode.md +4 −6

Details

346* 提示 Claude Code 在背景執行命令346* 提示 Claude Code 在背景執行命令

347* 按 `Ctrl+B` 將一般 Bash 工具叫用移至背景。Tmux 使用者必須按 `Ctrl+B` 兩次，因為 tmux 的前置鍵。347* 按 `Ctrl+B` 將一般 Bash 工具叫用移至背景。Tmux 使用者必須按 `Ctrl+B` 兩次，因為 tmux 的前置鍵。

348 348

349當命令在完成前達到逾時時，Claude Code 會自動[將其移至背景](/docs/zh-TW/tools-reference#background-commands)，而不是停止它，除非命令以 `sleep` 開頭。若要變更命令執行多久後才會發生這種情況，請設定 [Bash 逾時環境變數](/docs/zh-TW/tools-reference#timeout-and-output-limits)。349當命令在完成前達到逾時時，Claude Code 會自動[將其移至背景](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 開頭。如果您已使用 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/zh-TW/env-vars#variables) 關閉背景工作，或透過以[裸機模式](/docs/zh-TW/headless#start-faster-with-bare-mode)啟動，命令會在逾時時停止。若要變更逾時，請設定 [Bash 逾時環境變數](/docs/zh-TW/tools-reference#timeout-and-output-limits)。

350 350

351**主要功能：**351**主要功能：**

352 352

358* 在 macOS 和 Linux 上，當作業系統發出記憶體壓力信號時，Claude Code 會終止執行中的背景工作，前提是工作階段已閒置至少 30 分鐘且沒有執行任何轉向或子代理。需要 Claude Code v2.1.193 或更新版本358* 在 macOS 和 Linux 上，當作業系統發出記憶體壓力信號時，Claude Code 會終止執行中的背景工作，前提是工作階段已閒置至少 30 分鐘且沒有執行任何轉向或子代理。需要 Claude Code v2.1.193 或更新版本

359 * [偵錯日誌](/docs/zh-TW/debug-your-config)會說明為什麼工作被停止，或為什麼壓力事件讓它們繼續執行359 * [偵錯日誌](/docs/zh-TW/debug-your-config)會說明為什麼工作被停止，或為什麼壓力事件讓它們繼續執行

360 * 將 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/zh-TW/env-vars) 設定為 `1` 以關閉記憶體壓力停止360 * 將 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/zh-TW/env-vars) 設定為 `1` 以關閉記憶體壓力停止

361* 背景 Bash 和 PowerShell 命令有時間限制，從命令進入背景的時刻開始計算：30 分鐘，或 Claude 在啟動背景命令時要求的 `timeout`，最多 2 小時。使用 `Ctrl+B` 等方式在執行時移至背景的命令，從移動時起獲得 30 分鐘。當命令達到其限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動它（如果工作仍需要的話）。兩個環境變數會提高限制（以毫秒為單位），且都不能縮短限制：361* 背景 Bash 和 PowerShell 命令有時間限制，從命令進入背景的時刻開始計算：30 分鐘，或 Claude 在啟動背景命令時要求的 `timeout`，最多 2 小時。使用 `Ctrl+B` 等方式在執行時移至背景的命令，從移動時起獲得 30 分鐘。當命令達到其限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動它（如果工作仍需要的話）。若要延長限制，請參閱工具參考中的[提高背景命令的時間限制](/docs/zh-TW/tools-reference#raise-the-time-limit-for-background-commands)

362 * 將 [`BASH_DEFAULT_TIMEOUT_MS`](/docs/zh-TW/env-vars) 設定為高於 `1800000` 以用該值取代 30 分鐘的預設值，也適用於移動的命令362* 由前景[子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的背景命令在該子代理的執行結束時結束，無論是完成、失敗或被中斷；請參閱工具參考中的[背景命令停止時](/docs/zh-TW/tools-reference#when-a-background-command-stops)

363 * 將 [`BASH_MAX_TIMEOUT_MS`](/docs/zh-TW/env-vars) 設定為高於 `7200000` 以提高 2 小時的最大值。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `7200000` 也會以相同方式提高它

364* 由前景[子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的背景命令在該子代理的執行結束時結束，無論是完成、失敗或被中斷；請參閱工具參考中的[背景命令](/docs/zh-TW/tools-reference#background-commands)

365 363

366若要停用所有背景工作功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。詳細資訊請參閱[環境變數](/docs/zh-TW/env-vars)。364若要停用所有背景工作功能，請將 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/zh-TW/env-vars#variables) 環境變數設定為 `1`。以[裸機模式](/docs/zh-TW/headless#start-faster-with-bare-mode)啟動也會將其關閉。

367 365

368**常見的背景命令：**366**常見的背景命令：**

369 367

keybindings.md +1 −3

Details

545* 在西里爾字母等非拉丁配置下，當終端機使用 Kitty 鍵盤協議並報告該位置時，Claude Code 會根據按鍵的美式配置位置來符合 Ctrl 快捷鍵。在這樣的終端機中，使用俄文配置時，按下 Ctrl 和實體 W 鍵會觸發 `ctrl+w`。在不報告位置的終端機中，Claude Code 會符合終端機為按鍵發送的任何內容：ASCII 控制碼會觸發拉丁快捷鍵，而作為西里爾字元到達的按鍵不符合任何繫結545* 在西里爾字母等非拉丁配置下，當終端機使用 Kitty 鍵盤協議並報告該位置時，Claude Code 會根據按鍵的美式配置位置來符合 Ctrl 快捷鍵。在這樣的終端機中，使用俄文配置時，按下 Ctrl 和實體 W 鍵會觸發 `ctrl+w`。在不報告位置的終端機中，Claude Code 會符合終端機為按鍵發送的任何內容：ASCII 控制碼會觸發拉丁快捷鍵，而作為西里爾字元到達的按鍵不符合任何繫結

546* 在重新排列拉丁字母的配置下，例如 AZERTY，Claude Code 會符合按鍵輸入的字母，因此按下 Ctrl 和標記為 A 的按鍵會觸發 `ctrl+a`546* 在重新排列拉丁字母的配置下，例如 AZERTY，Claude Code 會符合按鍵輸入的字母，因此按下 Ctrl 和標記為 A 的按鍵會觸發 `ctrl+a`

547 547

548在 v2.1.247 之前，在使用 Kitty 鍵盤協議的終端機（例如 Ghostty、Kitty、WezTerm 和 iTerm2）中，在非拉丁配置下按下 Ctrl 快捷鍵不會觸發其繫結。

~~549~~

550<h3 id="chords">548<h3 id="chords">

551 和弦549 和弦

552</h3>550</h3>

697* 拼寫錯誤的修飾鍵，例如 `ctl+k`。Claude Code 會捨棄它無法識別的部分，並將繫結應用於剩餘的按鍵，在此範例中為 `k`。695* 拼寫錯誤的修飾鍵，例如 `ctl+k`。Claude Code 會捨棄它無法識別的部分，並將繫結應用於剩餘的按鍵，在此範例中為 `k`。

698* 無效的上下文名稱696* 無效的上下文名稱

699* 無效的動作值，例如不是字串或 `null` 的動作697* 無效的動作值，例如不是字串或 `null` 的動作

700* 未知的動作名稱，例如已註冊動作的拼寫錯誤。Claude Code 會跳過該繫結並保持該按鍵的任何預設繫結有效。在 v2.1.246 之前，具有未知動作名稱的繫結會無聲地停用該按鍵698* 未知的動作名稱，例如已註冊動作的拼寫錯誤。Claude Code 會跳過該繫結並保持該按鍵的任何預設繫結有效。

701* 保留快捷鍵衝突699* 保留快捷鍵衝突

702* 同一上下文中的重複繫結700* 同一上下文中的重複繫結

703 701

llm-gateway.md +2 −0

Details

45 45

46[為您的組織推出 LLM gateway](/docs/zh-TW/llm-gateway-rollout)逐步介紹每個步驟，並顯示在每個步驟分發的配置檔案。gateway 是組織設置的一部分；有關政策強制執行、使用情況可見性和資料處理決策，請參閱[為您的組織設置 Claude Code](/docs/zh-TW/admin-setup)。46[為您的組織推出 LLM gateway](/docs/zh-TW/llm-gateway-rollout)逐步介紹每個步驟，並顯示在每個步驟分發的配置檔案。gateway 是組織設置的一部分；有關政策強制執行、使用情況可見性和資料處理決策，請參閱[為您的組織設置 Claude Code](/docs/zh-TW/admin-setup)。

47 47

48若要讓透過 `ANTHROPIC_BASE_URL` 到達的 gateway 成為受管機器唯一可以使用的目的地，請在相同的受管設定檔中將 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 設定為 `["customEndpoint"]`，並將 gateway 的 `ANTHROPIC_BASE_URL` 放在該檔案的 `env` 區塊中。Claude Code 隨後會拒絕指向其他任何地方的工作階段，包括直接指向 Anthropic 或開發人員自己的代理，並且只接受 `ANTHROPIC_BASE_URL` 具有您在該處設定的值。對於透過提供商特定端點變數（例如 `ANTHROPIC_BEDROCK_BASE_URL`）到達的 gateway，`allowedProviders` 項目會指定要固定的變數。需要 Claude Code v2.1.285 或更新版本。

48<h2 id="subscriptions-and-gateways">50<h2 id="subscriptions-and-gateways">

49 訂閱和 gateway51 訂閱和 gateway

50</h2>52</h2>

llm-gateway-protocol.md +1 −1

Details

310 310

311Claude Code 使用以下兩個認證標頭發送發現請求，並省略其值無法解析的標頭。發送兩個標頭需要 Claude Code v2.1.248 或更新版本。較早的版本在設定 `ANTHROPIC_AUTH_TOKEN` 時僅發送 `Authorization`，否則僅發送 `x-api-key`。311Claude Code 使用以下兩個認證標頭發送發現請求，並省略其值無法解析的標頭。發送兩個標頭需要 Claude Code v2.1.248 或更新版本。較早的版本在設定 `ANTHROPIC_AUTH_TOKEN` 時僅發送 `Authorization`，否則僅發送 `x-api-key`。

312 312

313* `Authorization`：`ANTHROPIC_AUTH_TOKEN` 作為持有人令牌，否則 [`apiKeyHelper`](/docs/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 值作為持有人令牌。在這種情況下，Claude Code 會等待幫助程式返回後再發送請求。313* `Authorization`：`ANTHROPIC_AUTH_TOKEN` 作為持有人令牌，否則 [`apiKeyHelper`](/docs/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 值作為持有人令牌。

314* `x-api-key`：Claude Code 解析的 API 金鑰，例如 `ANTHROPIC_API_KEY`。當幫助程式值是唯一的認證時，此標頭也會攜帶它，因此該值會在兩個標頭中到達。314* `x-api-key`：Claude Code 解析的 API 金鑰，例如 `ANTHROPIC_API_KEY`。當幫助程式值是唯一的認證時，此標頭也會攜帶它，因此該值會在兩個標頭中到達。

315 315

316Claude Code 也會發送來自 `ANTHROPIC_CUSTOM_HEADERS` 的任何標頭。當自訂標頭具有非空值時，Claude Code 會發送它來代替同名的內建標頭，不區分大小寫地匹配名稱。316Claude Code 也會發送來自 `ANTHROPIC_CUSTOM_HEADERS` 的任何標頭。當自訂標頭具有非空值時，Claude Code 會發送它來代替同名的內建標頭，不區分大小寫地匹配名稱。

managed-settings.md +8 −2

Details

199 199

200[閘道登入金鑰](#choose-a-delivery-mechanism) 遵循單獨的規則。Claude Code 永遠不會從伺服器管理的設定讀取它們，因此當伺服器管理的設定是選定的來源時，機器上具有原則金鑰的最高排名管理員來源仍然提供它們。在排名低於該來源的管理員來源中的值，或在 HKCU 登錄中的值，被忽略。200[閘道登入金鑰](#choose-a-delivery-mechanism) 遵循單獨的規則。Claude Code 永遠不會從伺服器管理的設定讀取它們，因此當伺服器管理的設定是選定的來源時，機器上具有原則金鑰的最高排名管理員來源仍然提供它們。在排名低於該來源的管理員來源中的值，或在 HKCU 登錄中的值，被忽略。

201 201

202[`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 有自己的規則：其項目的 Scope 備註說明機器上設定的列表如何與伺服器管理的列表結合。需要 Claude Code v2.1.285 或更新版本。

203

202當管理員來源設定 `allowManagedMcpServersOnly` 或 `allowedMcpServers` 列表且該值不是生效的值時，`/status` 和 `claude doctor` 命名該來源和金鑰。204當管理員來源設定 `allowManagedMcpServersOnly` 或 `allowedMcpServers` 列表且該值不是生效的值時，`/status` 和 `claude doctor` 命名該來源和金鑰。

203 205

204<h3 id="compose-every-managed-source">206<h3 id="compose-every-managed-source">

353* 空的受管理設定檔案計為 `{}`。355* 空的受管理設定檔案計為 `{}`。

354* 使用者可寫的 HKCU 登錄檔金鑰中的格式不正確的值永遠不會阻止啟動。Claude Code 將其報告為 `/status` 和 `claude doctor` 中的通知。356* 使用者可寫的 HKCU 登錄檔金鑰中的格式不正確的值永遠不會阻止啟動。Claude Code 將其報告為 `/status` 和 `claude doctor` 中的通知。

355 357

356如果受管理設定檔案、drop-in 檔案或 `managed-settings.d/` 目錄無法讀取，且沒有管理員來源提供政策，使用 claude.ai 或 Claude Console 認證登入的工作階段將在啟動時退出，並顯示聯絡管理員的訊息。358當受管理設定檔案、drop-in 檔案、`managed-settings.d/` 目錄、MDM 設定檔或 HKLM 登錄檔值存在但無法讀取，且沒有管理員來源提供政策時，發生的情況取決於讀取失敗的原因：

359

360* 如果作業系統拒絕讀取，例如在僅限根目錄的檔案上，每個工作階段都會在沒有該來源政策的情況下啟動。`/status` 和 `claude doctor` 記錄失敗，使用 `-p` 執行也會將其列印到 stderr。

361* 對於任何其他讀取失敗，例如 I/O 錯誤，每個工作階段都會在啟動時退出，並顯示[聯絡管理員的訊息](/docs/zh-TW/errors#unable-to-read-managed-policy-settings)。

357 362

358要尋找丟棄的項目，請查看以下三個位置之一：363要尋找丟棄的項目，請查看以下三個位置之一：

359 364

387| 欄位 | 存在但無效時的行為 |392| 欄位 | 存在但無效時的行為 |

388| :- | :- |393| :- | :- |

389| `allowedMcpServers` | 強制執行為空的允許清單，直到修復該值，因此使用者添加的任何 MCP 伺服器都不被允許。您的組織通過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 提供的伺服器仍然會載入，`managed-mcp.json` 伺服器根據[伺服器如何被評估](/docs/zh-TW/managed-mcp#how-a-server-is-evaluated)載入。個別無效項目被剝離，有效子集被強制執行。 |394| `allowedMcpServers` | 強制執行為空的允許清單，直到修復該值，因此使用者添加的任何 MCP 伺服器都不被允許。您的組織通過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 提供的伺服器仍然會載入，`managed-mcp.json` 伺服器根據[伺服器如何被評估](/docs/zh-TW/managed-mcp#how-a-server-is-evaluated)載入。個別無效項目被剝離，有效子集被強制執行。 |

395| [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) | 強制執行為空的允許清單，直到修復該值，因此每個 API 提供者都被拒絕，Claude Code 不會在機器上啟動。如果只有個別項目不是已知的提供者名稱，Claude Code 會丟棄並報告該項目，並強制執行其餘項目。 |

390| `allowedHttpHookUrls` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#allowedhttphookurls)，直到您修復該值，因此 HTTP hook 只有在另一個設定檔案列出其 URL 時才會執行。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |396| `allowedHttpHookUrls` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#allowedhttphookurls)，直到您修復該值，因此 HTTP hook 只有在另一個設定檔案列出其 URL 時才會執行。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |

391| `httpHookAllowedEnvVars` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#httphookallowedenvvars)，直到您修復該值，因此標頭變數只有在另一個設定檔案命名它時才會被插值。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |397| `httpHookAllowedEnvVars` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#httphookallowedenvvars)，直到您修復該值，因此標頭變數只有在另一個設定檔案命名它時才會被插值。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |

437 443

438其中大多數是鎖定：鎖定所管理的值，例如權限規則或 `sandbox.network.allowedDomains`，是任何層級都可以設定的普通金鑰，而鎖定會告訴 Claude Code 只遵守受管理的值。444其中大多數是鎖定：鎖定所管理的值，例如權限規則或 `sandbox.network.allowedDomains`，是任何層級都可以設定的普通金鑰，而鎖定會告訴 Claude Code 只遵守受管理的值。

439 445

440該表涵蓋權限、外掛程式和傳遞控制。對於此處未列出的任何金鑰，[設定參考](/docs/zh-TW/settings-reference#all-settings)索引的「範圍」欄會說明它是否為僅受管理；其中剩餘的僅受管理金鑰包括閘道登入 URL、版本、瀏覽器、行動模擬器、SSH 主機、Desktop 本機工作階段、沙箱二進位路徑、模型定價、模型限制和 CLAUDE.md 控制。446該表涵蓋權限、外掛程式和傳遞控制。對於此處未列出的任何金鑰，[設定參考](/docs/zh-TW/settings-reference#all-settings)索引的「範圍」欄會說明它是否為僅受管理。

441 447

442| 設定 | 說明 |448| 設定 | 說明 |

443| :- | :- |449| :- | :- |

mcp.md +175 −175

Details

65</Steps>65</Steps>

66 66

67<h2 id="installing-mcp-servers">67<h2 id="installing-mcp-servers">

~~68 安裝 MCP servers~~68 安裝 MCP 伺服器

69</h2>69</h2>

70 70

~~71MCP servers 可以根據您的需求以多種方式進行配置：~~71MCP 伺服器可以根據您的需求以多種方式進行設定：

72 72

73<h3 id="option-1-add-a-remote-http-server">73<h3 id="option-1-add-a-remote-http-server">

~~74 選項 1：新增遠端 HTTP server~~74 選項 1：新增遠端 HTTP 伺服器

75</h3>75</h3>

76 76

~~77HTTP servers 是連接到遠端 MCP servers 的推薦選項。這是雲端服務最廣泛支援的傳輸方式。~~77HTTP 伺服器是連接到遠端 MCP 伺服器的建議選項。這是雲端服務最廣泛支援的傳輸方式。

78 78

79```bash theme={null}79```bash theme={null}

80# 基本語法80# 基本語法

88 --header "Authorization: Bearer your-token"88 --header "Authorization: Bearer your-token"

89```89```

90 90

91當透過 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 配置 MCP servers 時，`type` 欄位接受 `streamable-http` 作為 `http` 的別名。MCP 規範使用名稱 `streamable-http` 作為此傳輸，因此從 server 文件複製的配置無需修改即可運作。91在透過 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 設定 MCP 伺服器時，`type` 欄位接受 `streamable-http` 作為 `http` 的別名。MCP 規範使用名稱 `streamable-http` 作為此傳輸方式，因此從伺服器文件複製的設定無需修改即可運作。

92 92

93沒有 `type` 但有 `url` 的 JSON 項目是配置錯誤，因為 Claude Code 將沒有 `type` 的項目讀取為 stdio server。Claude Code 會跳過該 server 並報告 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。在 v2.1.202 之前，Claude Code 將此配置錯誤報告為 `command: expected string, received undefined`。93具有 `url` 但沒有 `type` 的 JSON 項目是設定錯誤，因為 Claude Code 將沒有 `type` 的項目讀取為 stdio 伺服器。Claude Code 會跳過該伺服器並報告 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。在 v2.1.202 之前，Claude Code 將此誤設定報告為 `command: expected string, received undefined`。

94 94

95只有 SDK 主機應用程式（例如 [Agent SDK](/docs/zh-TW/agent-sdk/mcp) 應用程式或 [桌面應用程式](/docs/zh-TW/desktop)）可以註冊進程內 `"type": "sdk"` server。Claude Code 會跳過 `.mcp.json`、`~/.claude.json` 或設定中的 `"type": "sdk"` 項目，並報告 `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`。95只有 SDK 主機應用程式（例如 [Agent SDK](/docs/zh-TW/agent-sdk/mcp) 應用程式或 [桌面應用程式](/docs/zh-TW/desktop)）可以註冊進程內 `"type": "sdk"` 伺服器。Claude Code 會跳過 `.mcp.json`、`~/.claude.json` 或設定中的 `"type": "sdk"` 項目，並報告 `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`。

96 96

97在 `--output-format stream-json` 執行中，Claude Code 也會在 `system/init` 事件的 [`mcp_server_errors` 欄位](/docs/zh-TW/headless#stream-responses)中報告跳過的 `--mcp-config` 項目，因此指令碼可以偵測到 server 從未載入。這需要 Claude Code v2.1.219 或更新版本。97在 `--output-format stream-json` 執行中，Claude Code 也會在 `system/init` 事件的 [`mcp_server_errors` 欄位](/docs/zh-TW/headless#stream-responses)中報告跳過的 `--mcp-config` 項目，以便指令碼可以偵測伺服器從未載入。這需要 Claude Code v2.1.219 或更新版本。

98 98

99<h3 id="option-2-add-a-remote-sse-server">99<h3 id="option-2-add-a-remote-sse-server">

100 選項 2：新增遠端 SSE server100 選項 2：新增遠端 SSE 伺服器

101</h3>101</h3>

102 102

103<Warning>103<Warning>

104 SSE (Server-Sent Events) 傳輸已棄用。請改用 HTTP servers（如果可用）。104 SSE (Server-Sent Events) 傳輸已棄用。請改用 HTTP 伺服器（如果可用）。

105</Warning>105</Warning>

106 106

107某些服務仍然只公開 SSE 端點。使用與 [HTTP server](#option-1-add-a-remote-http-server) 相同的 `claude mcp add --transport http <name> <url>` 命令新增這些。Claude Code 首先嘗試 HTTP 傳輸，當 server 不接受時切換到 SSE。自動切換需要 Claude Code v2.1.265 或更新版本。107某些服務仍然只公開 SSE 端點。使用與 [HTTP 伺服器](#option-1-add-a-remote-http-server)相同的 `claude mcp add --transport http <name> <url>` 命令新增這些。Claude Code 首先嘗試 HTTP 傳輸，當伺服器不接受時切換到 SSE。自動切換需要 Claude Code v2.1.265 或更新版本。

108 108

109在較早的版本上，或直接透過 SSE 連接，請改為傳遞 `--transport sse`：109在較早版本上，或直接透過 SSE 連接，請改為傳遞 `--transport sse`：

110 110

111```bash theme={null}111```bash theme={null}

112# 基本語法112# 基本語法

121```121```

122 122

123<h3 id="option-3-add-a-local-stdio-server">123<h3 id="option-3-add-a-local-stdio-server">

124 選項 3：新增本機 stdio server124 選項 3：新增本機 stdio 伺服器

125</h3>125</h3>

126 126

127Stdio servers 在您的機器上作為本機程序執行。它們非常適合需要直接系統存取或自訂指令碼的工具。127Stdio 伺服器在您的機器上作為本機程序執行。它們非常適合需要直接系統存取或自訂指令碼的工具。

128 128

129Claude Code 在生成的 server 環境中設定 `CLAUDE_PROJECT_DIR` 為專案根目錄，因此您的 server 可以解析專案相對路徑，而無需依賴工作目錄。這與 hooks 在其 `CLAUDE_PROJECT_DIR` 變數中接收的目錄相同。從您的 server 程序內部讀取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。129Claude Code 在生成的伺服器環境中設定 `CLAUDE_PROJECT_DIR` 為專案根目錄，因此您的伺服器可以解析專案相對路徑，而無需依賴工作目錄。這是 hooks 在其 `CLAUDE_PROJECT_DIR` 變數中接收的相同目錄。從伺服器程序內部讀取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。

130 130

131`CLAUDE_PROJECT_DIR` 是穩定的專案根目錄，在 session 中途新增或移除工作目錄時不會變更。限制自身檔案系統存取到一組允許目錄的 server 應該改為實作 MCP `roots/list` 請求。Claude Code 使用 session 的啟動目錄加上您透過 `--add-dir`、`/add-dir` 或 `additionalDirectories` 設定授予的每個[額外工作目錄](/docs/zh-TW/permissions#working-directories)來回答 `roots/list`。當該集合變更時，Claude Code 會傳送 `notifications/roots/list_changed`。在 v2.1.203 之前，`roots/list` 只傳回啟動目錄，Claude Code 不會傳送 `notifications/roots/list_changed`。131`CLAUDE_PROJECT_DIR` 是穩定的專案根目錄，在您於工作階段中途新增或移除工作目錄時不會變更。限制自身檔案系統存取到一組允許目錄的伺服器應改為實作 MCP `roots/list` 請求。Claude Code 使用工作階段的啟動目錄加上您透過 `--add-dir`、`/add-dir` 或 `additionalDirectories` 設定授予的每個 [額外工作目錄](/docs/zh-TW/permissions#working-directories)來回答 `roots/list`。當該集合變更時，Claude Code 會傳送 `notifications/roots/list_changed`。在 v2.1.203 之前，`roots/list` 只傳回啟動目錄，Claude Code 不會傳送 `notifications/roots/list_changed`。

132 132

133此變數在 server 的環境中設定，而不是在 Claude Code 自己的環境中，因此在專案範圍的 `.mcp.json` 項目或本機或使用者範圍的 server 項目中透過 `${VAR}` 擴展參考它需要預設值，例如 `${CLAUDE_PROJECT_DIR:-.}`。Plugin 提供的 MCP 配置直接替換 `${CLAUDE_PROJECT_DIR}`，不需要預設值。133此變數設定在伺服器的環境中，而不是在 Claude Code 自身的環境中，因此在專案範圍的 `.mcp.json` 項目或 `~/.claude.json` 中的本機或使用者範圍伺服器項目的 `command` 或 `args` 中透過 `${VAR}` 擴展參考它需要預設值，例如 `${CLAUDE_PROJECT_DIR:-.}`。外掛提供的 MCP 設定直接替換 `${CLAUDE_PROJECT_DIR}`，不需要預設值。

134 134

135```bash theme={null}135```bash theme={null}

136# 基本語法136# 基本語法

137claude mcp add [options] <name> -- <command> [args...]137claude mcp add [options] <name> -- <command> [args...]

138 138

139# 實際範例：新增 Airtable server139# 實際範例：新增 Airtable 伺服器

140claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \140claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \

141 -- npx -y airtable-mcp-server141 -- npx -y airtable-mcp-server

142```142```

143 143

144<Note>144<Note>

~~145 **重要：使用 `--` 分隔 server 引數**~~145 **重要：使用 `--` 分隔伺服器引數**

146 146

147 對於 stdio servers，`--` (雙破折號) 將 Claude 自己的選項（例如 `--transport`、`--env` 和 `--scope`）與執行 server 的命令和引數分開。`--` 之後的所有內容都會原封不動地傳遞給 server。147 對於 stdio 伺服器，`--`（雙破折號）分隔 Claude 自身的選項（例如 `--transport`、`--env` 和 `--scope`）與執行伺服器的命令和引數。`--` 之後的所有內容都會原封不動地傳遞給伺服器。

148 148

149 例如：149 例如：

150 150

151 * `claude mcp add --transport stdio myserver -- npx server` → 執行 `npx server`151 * `claude mcp add --transport stdio myserver -- npx server` → 執行 `npx server`

152 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 執行 `python server.py --port 8080`，環境中有 `KEY=value`152 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 執行 `python server.py --port 8080`，環境中有 `KEY=value`

153 153

154 沒有 `--`，Claude Code 會嘗試解析 server 的旗標（例如上面的 `--port`）作為自己的選項。154 沒有 `--`，Claude Code 會嘗試將伺服器的旗標（例如上面的 `--port`）解析為自身的選項。

155 155

156 `--env` 接受多個 `KEY=value` 對。如果 server 名稱直接跟在 `--env` 之後，CLI 會將該名稱讀取為另一對並拒絕它，因此請在 `--env` 和 server 名稱之間放置至少一個其他選項，例如 `--transport stdio`。156 `--env` 接受多個 `KEY=value` 對。如果伺服器名稱直接跟在 `--env` 之後，CLI 會將名稱讀取為另一對並拒絕它，因此請在 `--env` 和伺服器名稱之間放置至少一個其他選項，例如 `--transport stdio`。

157</Note>157</Note>

158 158

159<h3 id="option-4-add-a-remote-websocket-server">159<h3 id="option-4-add-a-remote-websocket-server">

160 選項 4：新增遠端 WebSocket server160 選項 4：新增遠端 WebSocket 伺服器

161</h3>161</h3>

162 162

163WebSocket servers 保持持久的雙向連接，適合遠端 MCP servers 主動向 Claude 推送事件。當您的 server 只回應請求時，請改用 HTTP，因為 HTTP 支援 OAuth 和 `claude mcp add --transport` 旗標，而 WebSocket 都不支援。163WebSocket 伺服器保持持久雙向連接，適合遠端 MCP 伺服器主動向 Claude 推送事件。當您的伺服器只回應請求時，請改用 HTTP，因為 HTTP 支援 OAuth 和 `claude mcp add --transport` 旗標，而 WebSocket 都不支援。

164 164

165在 `.mcp.json` 中或使用 `claude mcp add-json` 配置 WebSocket servers：165在 `.mcp.json` 中或使用 `claude mcp add-json` 設定 WebSocket 伺服器：

166 166

167```bash theme={null}167```bash theme={null}

168claude mcp add-json events-server \168claude mcp add-json events-server \

169 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'169 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

170```170```

171 171

172`type: "ws"` 項目接受與 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 欄位。驗證僅限標頭，因此在 `headers` 中傳遞靜態 token，或在連接時使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 生成一個。`claude mcp add --transport` 旗標不接受 `ws`。172`type: "ws"` 項目接受與 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 欄位。驗證僅限標頭，因此在 `headers` 中傳遞靜態令牌或在連接時使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 產生令牌。`claude mcp add --transport` 旗標不接受 `ws`。

173 173

174<h3 id="add-a-server-from-setup-instructions-written-for-another-client">174<h3 id="add-a-server-from-setup-instructions-written-for-another-client">

175 從為另一個用戶端編寫的設定指示新增 server175 從為另一個用戶端編寫的設定指示新增伺服器

176</h3>176</h3>

177 177

178MCP servers 不是 Claude Code 特有的，因此 server 的設定指示可能是為 Claude Desktop、Cursor 或另一個 MCP 用戶端編寫的，並且不提供 `claude mcp add` 命令。若要新增 server，請在這些指示中尋找 URL、啟動命令或 JSON 區塊：178MCP 伺服器不是 Claude Code 特有的，因此伺服器的設定指示可能是為 Claude Desktop、Cursor 或另一個 MCP 用戶端編寫的，並且不提供 `claude mcp add` 命令。若要新增伺服器，請在這些指示中尋找 URL、啟動命令或 JSON 區塊：

179 179

180* **URL**，例如 `https://mcp.example.com/mcp`：server 是遠端的。180* **URL**（例如 `https://mcp.example.com/mcp`）：伺服器是遠端的。

181* **啟動命令**，例如 `npx -y @example/mcp-server`：server 在您的機器上執行。181* **啟動命令**（例如 `npx -y @example/mcp-server`）：伺服器在您的機器上執行。

182* **`mcpServers` JSON 區塊**：為另一個用戶端的設定檔案編寫的配置。182* **`mcpServers` JSON 區塊**：為另一個用戶端的設定檔編寫的設定。

183 183

184每一個都是 [安裝 MCP servers](#installing-mcp-servers) 中四個選項之一所採用的輸入。在下面找到您擁有的形狀，以將其轉換為 Claude Code 接受的命令。除非您新增 `--scope project` 或 `--scope user`，否則每個命令都會寫入[本機範圍](#local-scope)。184每一個都是 [安裝 MCP 伺服器](#installing-mcp-servers)中四個選項之一接受的輸入。在下面找到您擁有的形狀，將其轉換為 Claude Code 接受的命令。除非您新增 `--scope project` 或 `--scope user`，否則每個命令都會寫入 [本機範圍](#local-scope)。

185 185

186<h4 id="from-a-url">186<h4 id="from-a-url">

187 從 URL187 從 URL

188</h4>188</h4>

189 189

190URL 表示 server 是遠端的。對於 `https://` 端點，使用 `--transport http` 新增它，或當指示說端點使用 SSE 時遵循[選項 2](#option-2-add-a-remote-sse-server)。對於 `wss://` 端點，改為使用[選項 4](#option-4-add-a-remote-websocket-server)，因為 `--transport` 不接受 `ws`：190URL 表示伺服器是遠端的。對於 `https://` 端點，使用 `--transport http` 新增它，或在指示說端點使用 SSE 時遵循 [選項 2](#option-2-add-a-remote-sse-server)。對於 `wss://` 端點，改為使用 [選項 4](#option-4-add-a-remote-websocket-server)，因為 `--transport` 不接受 `ws`：

191 191

192```bash theme={null}192```bash theme={null}

193claude mcp add --transport http example https://mcp.example.com/mcp193claude mcp add --transport http example https://mcp.example.com/mcp

194```194```

195 195

196如果指示也提供 API 金鑰或 token 標頭，請使用 `--header` 傳遞它，如[選項 1](#option-1-add-a-remote-http-server) 所示。196如果指示也提供 API 金鑰或令牌標頭，請使用 `--header` 傳遞它，如 [選項 1](#option-1-add-a-remote-http-server)所示。

197 197

198<h4 id="from-an-npx-uvx-or-binary-command">198<h4 id="from-an-npx-uvx-or-binary-command">

199 從 `npx`、`uvx` 或二進位命令199 從 `npx`、`uvx` 或二進位命令

200</h4>200</h4>

201 201

202啟動命令表示 server 作為本機 stdio 程序執行。將整個命令放在 `--` 之後，以便 Claude Code 將 `-y` 等旗標傳遞給啟動 server 的命令，而不是將它們讀取為自己的選項。使用 `--env` 傳遞指示要求的任何環境變數，在 server 名稱之後和 `--` 之前：202啟動命令表示伺服器作為本機 stdio 程序執行。將整個命令放在 `--` 之後，以便 Claude Code 將旗標（例如 `-y`）傳遞給啟動伺服器的命令，而不是將其讀取為自身的選項。使用 `--env` 傳遞指示要求的任何環境變數，在伺服器名稱之後和 `--` 之前：

203 203

204```bash theme={null}204```bash theme={null}

205claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server205claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

206```206```

207 207

208[選項 3](#option-3-add-a-local-stdio-server) 完整涵蓋 `--` 分隔符。208[選項 3](#option-3-add-a-local-stdio-server)完整涵蓋 `--` 分隔符。

209 209

210<h4 id="from-an-mcpservers-json-block">210<h4 id="from-an-mcpservers-json-block">

211 從 `mcpServers` JSON 區塊211 從 `mcpServers` JSON 區塊

213 213

214為另一個 MCP 用戶端（例如 Claude Desktop）編寫的 `mcpServers` 區塊使用 Claude Code 讀取的包裝器金鑰和項目形狀。將 `mcpServers` 內的物件傳遞給 `claude mcp add-json`，而不是包裝器。兩個項目需要先修復：214為另一個 MCP 用戶端（例如 Claude Desktop）編寫的 `mcpServers` 區塊使用 Claude Code 讀取的包裝器金鑰和項目形狀。將 `mcpServers` 內的物件傳遞給 `claude mcp add-json`，而不是包裝器。兩個項目需要先修復：

215 215

216* **沒有 `type` 的 `url`**：新增 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以符合端點。Claude Code 將沒有 `type` 的項目讀取為 stdio server，因此沒有 `type` 的 `url` 項目會失敗。216* **`url` 沒有 `type`**：新增 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以符合端點。Claude Code 將沒有 `type` 的項目讀取為 stdio 伺服器，因此沒有 `type` 的 `url` 項目會失敗。

217* **具有字母、數字、連字號和底線以外字元的金鑰**：選擇僅使用這些字元的 server 名稱。否則金鑰是 server 名稱。217* **金鑰包含字母、數字、連字號和底線以外的字元**：選擇僅使用這些字元的伺服器名稱。否則金鑰是伺服器名稱。

218 218

219例如，此區塊：219例如，此區塊：

220 220

235claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'235claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

236```236```

237 237

238[從 JSON 配置新增 MCP servers](#add-mcp-servers-from-json-configuration) 涵蓋 `add-json` 的 shell 逃逸和 `--scope` 旗標。若要改為與您的團隊共享 server，請新增 `--scope project`，或在您的專案根目錄的 `.mcp.json` 中的 `mcpServers` 下新增項目並提交它。[專案範圍](#project-scope)涵蓋 Claude Code 如何載入和批准該檔案。238[從 JSON 設定新增 MCP 伺服器](#add-mcp-servers-from-json-configuration)涵蓋 `add-json` 的 shell 逃逸和 `--scope` 旗標。若要與您的團隊共享伺服器，請改為新增 `--scope project`，或在您的專案根目錄的 `.mcp.json` 下的 `mcpServers` 下新增項目並提交它。[專案範圍](#project-scope)涵蓋 Claude Code 如何載入和核准該檔案。

239 239

240每個 `claude mcp add` 和 `claude mcp add-json` 命令都會列印一行 `Added ...`。若要檢查 Claude Code 是否已連接，請執行 `claude mcp get <name>`；[Server 狀態](#server-status)涵蓋它顯示的狀態和 `.mcp.json` servers 的批准步驟。240每個 `claude mcp add` 和 `claude mcp add-json` 命令在成功時列印 `Added ...` 行。若要檢查 Claude Code 是否已連接，請執行 `claude mcp get <name>`；[伺服器狀態](#server-status)涵蓋它顯示的狀態和 `.mcp.json` 伺服器的核准步驟。

241 241

242<h3 id="managing-your-servers">242<h3 id="managing-your-servers">

243 管理您的 servers243 管理您的伺服器

244</h3>244</h3>

245 245

246配置後，您可以使用這些命令管理您的 MCP servers：246設定後，您可以使用這些命令管理您的 MCP 伺服器：

247 247

248```bash theme={null}248```bash theme={null}

249# 列出所有已配置的 servers249# 列出所有已設定的伺服器

250claude mcp list250claude mcp list

251 251

252# 取得特定 server 的詳細資訊252# 取得特定伺服器的詳細資訊

253claude mcp get notion253claude mcp get notion

254 254

255# 移除 server255# 移除伺服器

256claude mcp remove notion256claude mcp remove notion

257 257

258# (在 Claude Code 中) 檢查 server 狀態258# （在 Claude Code 內）檢查伺服器狀態

259/mcp259/mcp

260```260```

261 261

262當您移除遠端 server 時，Claude Code 也會刪除為該 server 儲存的 OAuth tokens 和用戶端註冊。262移除遠端伺服器時，Claude Code 也會刪除為該伺服器儲存的 OAuth 令牌和用戶端註冊。

263 263

264<h4 id="server-status">264<h4 id="server-status">

265 Server 狀態265 伺服器狀態

266</h4>266</h4>

267 267

268`claude mcp add` 透過列印 `Added ...` 行確認成功新增，這表示配置已寫入。如果命令改為列印 `was not saved` 訊息，請參閱 [MCP server was not saved or removed](/docs/zh-TW/errors#mcp-server-was-not-saved-or-removed)；對於 `may not have been saved` 訊息，請參閱 [MCP server may not have been saved or removed](/docs/zh-TW/errors#mcp-server-may-not-have-been-saved-or-removed)。268`claude mcp add` 透過列印 `Added ...` 行確認成功新增，這表示設定已寫入。如果命令改為列印 `was not saved` 訊息，請參閱 [MCP 伺服器未儲存或移除](/docs/zh-TW/errors#mcp-server-was-not-saved-or-removed)；對於 `may not have been saved` 訊息，請參閱 [MCP 伺服器可能未儲存或移除](/docs/zh-TW/errors#mcp-server-may-not-have-been-saved-or-removed)。

269 269

270`claude mcp list` 然後在它列出的每個 server 旁邊顯示健康狀態，例如 `✔ Connected`、`! Needs authentication` 或 `✘ Failed to connect`。失敗狀態表示 Claude Code 無法連接到該 server，而不是列表命令失敗。270`claude mcp list` 在它列出的每個伺服器旁邊顯示健康狀態，例如 `✔ Connected`、`! Needs authentication` 或 `✘ Failed to connect`。失敗狀態表示 Claude Code 無法連接到該伺服器，而不是列表命令失敗。

271 271

272此列表中的狀態報告配置決定而不是連接嘗試，因此 Claude Code 在不連接到 server 的情況下列印它們：272此列表中的狀態報告設定決定而不是連接嘗試，因此 Claude Code 在不連接到伺服器的情況下列印它們：

273 273

274* ``⏸ Pending approval (run `claude` to approve)``：來自 `.mcp.json` 的專案範圍 server，您尚未批准。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都顯示它。執行 `claude` 互動式命令以檢查和批准它。274* ``⏸ Pending approval (run `claude` to approve)``：來自 `.mcp.json` 的專案範圍伺服器，您尚未核准。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都顯示它。執行 `claude` 互動式地檢查並核准它。

275* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-TW/settings-reference#disabledmcpjsonservers) 項目拒絕的 `.mcp.json` server。Claude Code 只在 `claude mcp get <name>` 中顯示它。275* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-TW/settings-reference#disabledmcpjsonservers) 項目拒絕的 `.mcp.json` 伺服器。Claude Code 只在 `claude mcp get <name>` 中顯示它。

276* `⊘ Disabled for this project (re-enable via /mcp)`：專案的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的 server。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都顯示它。從 `/mcp` 面板重新開啟 server。在 v2.1.238 之前，兩個命令都連接到已停用的 server 以進行健康檢查並報告連接結果。276* `⊘ Disabled for this project (re-enable via /mcp)`：專案的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的伺服器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都顯示它。從 `/mcp` 面板重新開啟伺服器。

277 277

278WebSocket servers 不會出現在 `claude mcp list` 輸出中。使用 `claude mcp get <name>` 或 `/mcp` 面板檢查它們。278WebSocket 伺服器不會出現在 `claude mcp list` 輸出中。使用 `claude mcp get <name>` 或 `/mcp` 面板檢查它們。

279 279

280<h4 id="project-server-approvals-and-workspace-trust">280<h4 id="project-server-approvals-and-workspace-trust">

281 專案 server 批准和工作區信任281 專案伺服器核准和工作區信任

282</h4>282</h4>

283 283

284自 v2.1.196 起，`claude mcp list` 和 `claude mcp get` 只從未簽入儲存庫的設定檔案中讀取 `.mcp.json` 批准，直到您透過在其中執行 `claude` 並接受工作區信任對話框來信任工作區。複製的儲存庫無法批准自己的 servers：提交到專案 `.claude/settings.json` 的 [`enableAllProjectMcpServers`](/docs/zh-TW/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](/docs/zh-TW/settings-reference#enabledmcpjsonservers) 在不受信任的資料夾中被忽略，server 保持在 `⏸ Pending approval` 而不是被連接和健康檢查。284從 v2.1.196 開始，`claude mcp list` 和 `claude mcp get` 只從未簽入儲存庫的設定檔讀取 `.mcp.json` 核准，直到您透過執行 `claude` 並接受工作區信任對話來信任工作區。複製的儲存庫無法核准自身的伺服器：提交到專案的 `.claude/settings.json` 的 [`enableAllProjectMcpServers`](/docs/zh-TW/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](/docs/zh-TW/settings-reference#enabledmcpjsonservers) 在不受信任的資料夾中被忽略，伺服器保持在 `⏸ Pending approval` 而不是被連接和健康檢查。

285 285

286這些來源的批准仍然適用於不受信任的資料夾：286這些來源的核准在不受信任的資料夾中仍然適用：

287 287

288* 您的使用者 `~/.claude/settings.json`288* 您的使用者 `~/.claude/settings.json`

289* 受管設定289* 受管設定

290* 使用 `--settings` 傳遞的設定290* 使用 `--settings` 傳遞的設定

291 291

292Claude Code 也會套用來自未追蹤 `.claude/settings.local.json` 的批准，但它執行 git 以檢查檔案是否被追蹤，並且它只在[受信任的資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)中執行該檢查。在您從未信任的資料夾中，Claude Code 會等待信任對話框，然後才能套用檔案的批准，除非該資料夾是您自己的配置主目錄：您的主目錄，或您已設定為 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 的 `.claude` 的目錄。在 v2.1.207 之前，Claude Code 在您從未信任的資料夾中套用了來自未追蹤 `.claude/settings.local.json` 的批准。292Claude Code 也應用來自未追蹤 `.claude/settings.local.json` 的核准，但它執行 git 來檢查檔案是否被追蹤，並且只在 [受信任的資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)中執行該檢查。在您從未信任的資料夾中，Claude Code 會等待信任對話，然後才應用檔案的核准，除非資料夾是您自己的設定主目錄：您的主目錄，或其 `.claude` 您已設定為 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 的目錄。在 v2.1.207 之前，Claude Code 即使在您從未信任的資料夾中也應用來自未追蹤 `.claude/settings.local.json` 的核准。

293 293

294任何設定檔案中的 `disabledMcpjsonServers` 項目仍然會拒絕 server。294任何設定檔中的 `disabledMcpjsonServers` 項目仍然拒絕伺服器。

295 295

296<h4 id="server-status-detail">296<h4 id="server-status-detail">

297 Server 狀態詳細資訊297 伺服器狀態詳細資訊

298</h4>298</h4>

299 299

300在 `/mcp` 中（包括 server 的選單）和 [`/plugin`](/docs/zh-TW/plugins/install) 管理器中，您之前使用過的遠端 HTTP 或 SSE server 可以顯示 `cached` 狀態，例如 `cached 2h ago · connects on first use · 5 tools`。Claude Code 從發現快取（在上一個 session 中儲存）載入了 server 的工具列表，而不是在啟動時連接，Claude Code 在 Claude 首次呼叫 server 的其中一個工具時連接 server。工具從您的第一條訊息開始可用，因此您無需執行任何操作。發現快取及其 `cached` 狀態需要 Claude Code v2.1.221 或更新版本。300在 `/mcp` 中（包括伺服器的選單）和 [`/plugin`](/docs/zh-TW/plugins/install) 管理員中，您之前使用過的遠端 HTTP 或 SSE 伺服器可以顯示 `cached` 狀態，例如 `cached 2h ago · connects on first use · 5 tools`。Claude Code 從發現快取（在上一個工作階段中儲存）載入伺服器的工具列表，而不是在啟動時連接，Claude Code 在 Claude 首次呼叫伺服器的工具之一時連接伺服器。工具從您的第一條訊息開始可用，因此您無需執行任何操作。發現快取及其 `cached` 狀態需要 Claude Code v2.1.221 或更新版本。

301 301

302發現快取預設為關閉，除非逐步推出已為您的帳戶啟用它。設定 [`MCP_DISCOVERY_CACHE=1`](/docs/zh-TW/env-vars) 以開啟它，或設定 `0` 以在推出啟用它時保持關閉。在 v2.1.238 之前，快取預設為開啟。302發現快取預設關閉，除非逐步推出已為您的帳戶啟用它。設定 [`MCP_DISCOVERY_CACHE=1`](/docs/zh-TW/env-vars) 以開啟它，或設定 `0` 以在推出啟用它時保持關閉。在 v2.1.238 之前，快取預設開啟。

303 303

304當您從 server 選單中選擇 **Disable** 或 **Clear authentication** 時，Claude Code 也會捨棄該 server 的快取項目。**Reconnect** 在已連接或失敗的 server 上也會捨棄它；在 `cached` server 上，**Reconnect** 現在連接 server 並保留項目。捨棄項目後，Claude Code 從 server 而不是從快取中擷取 server 的工具列表。304當您從 `/mcp` 中的伺服器選單選擇 **Disable** 或 **Clear authentication** 時，Claude Code 也會捨棄該伺服器的快取項目。**Reconnect** 在已連接或失敗的伺服器上也會捨棄它；在 `cached` 伺服器上，**Reconnect** 現在連接伺服器並保留項目。Claude Code 在捨棄項目後下次連接到伺服器時，它會從伺服器而不是從快取中擷取工具列表。

305 305

306當 server 的狀態為 `✘ Failed to connect` 時，`claude mcp list` 會將失敗詳細資訊附加到該狀態行，`claude mcp get <name>` 在 `Issue:` 行上顯示它：HTTP 狀態或錯誤代碼，加上 server 傳回的任何錯誤文字。server 在 `/mcp` 中的詳細檢視在其 `Issue:` 列中包含相同的 server 報告文字。Claude Code 從此詳細資訊中編輯類似認證的文字，並且永遠不會包含擴展的 server URL，它可能攜帶機密。Claude Code 不會將詳細資訊附加到 `✘ Connection error` 狀態，因為它會列印的例外文字可以嵌入該 URL。在 v2.1.219 之前，兩個命令都只顯示裸失敗狀態，沒有狀態代碼或 server 的錯誤文字。306當伺服器的狀態為 `✘ Failed to connect` 時，`claude mcp list` 將失敗詳細資訊附加到該狀態行，`claude mcp get <name>` 在 `Issue:` 行上顯示它：HTTP 狀態或錯誤代碼，加上伺服器傳回的任何錯誤文字。伺服器在 `/mcp` 中的詳細檢視在其 `Issue:` 列中包含相同的伺服器報告文字。Claude Code 從此詳細資訊中編輯類似認證的文字，並且永遠不包括擴展的伺服器 URL，它可能攜帶機密。Claude Code 不會將詳細資訊附加到 `✘ Connection error` 狀態，因為它會列印的異常文字可以嵌入該 URL。在 v2.1.219 之前，兩個命令都只顯示裸露的失敗狀態，沒有狀態代碼或伺服器的錯誤文字。

307 307

308當您從 `/mcp` 完成驗證且連接仍然因 HTTP 狀態或傳輸錯誤代碼而失敗時，Claude Code 會在嘗試後列印的訊息中新增該代碼和 server URL 的來源。來源是方案和主機，加上 URL 命名時的連接埠，例如 `https://mcp.example.com`。308當您從 `/mcp` 完成驗證且連接仍然因 HTTP 狀態或傳輸錯誤代碼而失敗時，Claude Code 會在嘗試後列印的訊息中新增該代碼和伺服器 URL 的來源。來源是方案和主機，加上 URL 命名的連接埠（例如 `https://mcp.example.com`）。

309 309

310* 路徑和查詢永遠不會出現在該訊息中。310* 路徑和查詢永遠不會出現在該訊息中。

311* 對於本機、專案或使用者[範圍](#mcp-installation-scopes)中的 server 或受管 MCP 配置中的 server，來源顯示在該配置中寫入的主機，因此主機中的 `${VAR}` 參考在訊息中不會展開。311* 對於本機、專案或使用者 [範圍](#mcp-installation-scopes)中的伺服器或受管 MCP 設定，來源顯示該設定中寫入的主機，因此主機中的 `${VAR}` 參考在訊息中不會展開。

312* 對於沒有狀態或錯誤代碼的失敗，Claude Code 顯示錯誤文字而不顯示來源。312* 對於沒有狀態或錯誤代碼的失敗，Claude Code 顯示錯誤文字而不顯示來源。

313 313

314配置為空 `url` 的遠端 server 在 `/mcp`、`claude mcp list` 和 [`/plugin`](/docs/zh-TW/plugins/install) 管理器中顯示為 `not configured`，Claude Code 不會嘗試連接到它。Plugin 可以包含一個佔位符項目，例如此項目，用於您稍後配置的連接器，因此 Claude Code 不會將其報告為錯誤或設定問題。server 在 `/mcp` 中的詳細檢視會讀取 `No URL configured for this server`；設定項目的 `url` 以連接它。在 v2.1.208 之前，Claude Code 將空 `url` 報告為配置問題，並提示重新連接。314設定為空 `url` 的遠端伺服器在 `/mcp`、`claude mcp list` 和 [`/plugin`](/docs/zh-TW/plugins/install) 管理員中顯示為 `not configured`，Claude Code 不會嘗試連接到它。外掛可以包含此類佔位符項目，用於您稍後設定的連接器，因此 Claude Code 不會將其報告為錯誤或設定問題。伺服器在 `/mcp` 中的詳細檢視讀取 `No URL configured for this server`；設定項目的 `url` 以連接它。在 v2.1.208 之前，Claude Code 將空 `url` 報告為設定問題，並提示重新連接。

315 315

316<h4 id="configuration-warnings">316<h4 id="configuration-warnings">

317 配置警告317 設定警告

318</h4>318</h4>

319 319

320Claude Code 警告下面的配置問題。每個項目說明 Claude Code 檢查的內容以及如何清除警告：320Claude Code 警告下面的設定問題。每個項目說明 Claude Code 檢查的內容以及如何清除警告：

321 321

322* **隱藏的空白**：當 MCP 配置值攜帶隱藏的前導或尾隨空白時，Claude Code 會發出警告，這通常來自貼上帶有尾隨換行符的 token。Claude Code 檢查 `command`、`url`、每個 `args` 項目以及 `env` 和 `headers` 下的值和金鑰名稱。Claude Code 在 `claude mcp list` 輸出和 `/mcp` 中顯示警告，命名受影響的欄位而不回顯其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不會修剪空白，並完全按照寫入的方式使用值，因此編輯配置以移除它。322* **隱藏空白**：當 MCP 設定值攜帶隱藏的前導或尾隨空白時，Claude Code 會發出警告，這通常來自貼上帶有尾隨換行符的令牌。Claude Code 檢查 `command`、`url`、每個 `args` 項目以及 `env` 和 `headers` 下的值和金鑰名稱。Claude Code 在 `claude mcp list` 輸出和 `/mcp` 中顯示警告，命名受影響的欄位而不回顯其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不會修剪空白並完全按照寫入的方式使用值，因此編輯設定以移除它。

323* **在多個範圍中具有相同名稱**：如果您在多個[範圍](#mcp-installation-scopes)中定義相同的 server 名稱，具有不同的端點，Claude Code 會在 `claude mcp list` 輸出和 `/mcp` 中警告衝突。Claude Code 按端點儲存 OAuth 登入，因此當您驗證在一個專案中載入的定義時，您仍然需要在不同定義載入的專案中單獨登入。保留您想要的端點並使用 `claude mcp remove <name> --scope <scope>` 移除其他端點。在警告中，Claude Code 引用每個範圍的端點，如在您的配置中寫入的，具有[`${VAR}` 參考](#environment-variable-expansion-in-mcp-json)未展開，因此它永遠不會顯示已解析的值，例如 API 金鑰。323* **在多個範圍中使用相同名稱**：如果您在多個 [範圍](#mcp-installation-scopes)中定義相同的伺服器名稱，但端點不同，Claude Code 會在 `claude mcp list` 輸出和 `/mcp` 中警告衝突。Claude Code 按端點儲存 OAuth 登入，因此當您驗證在一個專案中載入的定義時，您仍然需要在不同定義載入的專案中單獨登入。保留您想要的端點並使用 `claude mcp remove <name> --scope <scope>` 移除其他端點。在警告中，Claude Code 引用每個範圍的端點，如您的設定中所寫，帶有 [`${VAR}` 參考](#environment-variable-expansion-in-mcp-json)未展開，因此它永遠不會顯示已解析的值，例如 API 金鑰。

324* **保留名稱**：Claude Code 保留其內建 servers 的名稱，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定義了具有保留名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。`claude mcp add` 會以錯誤拒絕保留名稱。`Claude Preview` 和 `Claude Browser` 都命名了 [Claude Code 桌面應用程式的預覽窗格](/docs/zh-TW/desktop#preview-your-app)使用的內建 server。在 v2.1.205 之前，`Claude Browser` 未被保留，因此使用者配置的 server 可以在該名稱下註冊。324* **保留名稱**：Claude Code 保留其內建伺服器的名稱，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的設定定義具有保留名稱的伺服器，Claude Code 會在載入時跳過它並顯示警告，要求您重新命名它。`claude mcp add` 拒絕帶有錯誤的保留名稱。`Claude Preview` 和 `Claude Browser` 都命名 [Claude Code 桌面應用程式的預覽窗格](/docs/zh-TW/desktop#preview-your-app)使用的內建伺服器。

325* **遺漏的環境變數**：如果配置中的 [`${VAR}` 參考](#environment-variable-expansion-in-mcp-json)命名未設定且沒有 `:-default` 的變數，Claude Code 會在 `claude mcp list` 輸出和 `/mcp` 中警告，命名變數，並仍然使用 `${VAR}` 文字未展開載入 server。設定變數或新增 `${VAR:-default}` 後備。在遠端 server 的 `url` 和 `headers` 中，某些認證變數[讀取為空](#credential-variables-that-read-as-empty)，沒有警告。325* **遺漏環境變數**：如果伺服器設定中的 [`${VAR}` 參考](#environment-variable-expansion-in-mcp-json)命名未設定且沒有 `:-default` 的變數，Claude Code 會在 `claude mcp list` 輸出和 `/mcp` 中警告，命名變數，並仍然載入伺服器，`${VAR}` 文字未展開。設定變數或新增 `${VAR:-default}` 後備。在遠端伺服器的 `url` 和 `headers` 中，某些認證變數 [讀取為空](#credential-variables-that-read-as-empty)，沒有警告。

326 326

327<h4 id="tool-availability">327<h4 id="tool-availability">

328 工具可用性328 工具可用性

329</h4>329</h4>

330 330

331`/mcp` 面板在每個已連接的 server 旁邊顯示工具計數，並標記宣告工具功能但未公開任何工具的 servers。331`/mcp` 面板在每個已連接伺服器旁邊顯示工具計數，並標記宣傳工具功能但不公開工具的伺服器。

332 332

333如果您的請求需要來自仍在背景連接的 server 的工具，Claude 會在繼續之前等待該 server。等待如何發生取決於您的配置：333如果您的請求需要仍在背景連接的伺服器中的工具，Claude 會在繼續之前等待該伺服器。等待的方式取決於您的設定：

334 334

335* **使用[工具搜尋](#scale-with-mcp-tool-search)（預設）**：等待發生在 `ToolSearch` 呼叫內。335* **使用 [工具搜尋](#scale-with-mcp-tool-search)（預設）**：等待發生在 `ToolSearch` 呼叫內。

336* **沒有工具搜尋**：Claude 改為使用 `WaitForMcpServers` 工具。沒有工具搜尋的配置包括自訂 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false` 和 Google Cloud 的 Agent Platform 上早於 Claude 4.5 世代的模型。336* **沒有工具搜尋**：Claude 改為使用 `WaitForMcpServers` 工具。沒有工具搜尋的設定包括自訂 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false` 和 Google Cloud 的 Agent Platform 上早於 Claude 4.5 世代的模型。

337* **在 Microsoft Foundry [部署託管在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**：Claude 在工具搜尋路徑上啟動，而不是使用 `WaitForMcpServers`，因為 Claude Code 只從 API 發現部署的伺服器端拒絕。Claude Code 將該部署切換到[前期載入](#scale-with-mcp-tool-search)後，來自完成連接的 server 的工具在 Claude 的下一個請求上變得可用。337* **在 Microsoft Foundry [部署託管在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**：Claude 開始於工具搜尋路徑而不是 `WaitForMcpServers`，因為 Claude Code 只從 API 發現部署的伺服器端拒絕。Claude Code 將該部署切換到 [前期載入](#scale-with-mcp-tool-search)後，來自完成連接的伺服器的工具在 Claude 的下一個請求上變得可用。

338 338

339啟用工具搜尋後，當 server 在 Claude 工作時完成連接時，Claude Code 在同一輪的下一個請求中將 server 的工具名稱列出給 Claude。Claude 然後可以搜尋和呼叫這些工具，而無需等待您的下一條訊息。339啟用工具搜尋後，當伺服器在 Claude 工作時完成連接時，Claude Code 在同一轉中的下一個請求上將伺服器的工具名稱列出給 Claude。Claude 然後可以搜尋並呼叫這些工具，而無需等待您的下一條訊息。

340 340

341<h3 id="disable-a-server-without-removing-it">341<h3 id="disable-a-server-without-removing-it">

342 停用 server 而不移除它342 在不移除的情況下停用伺服器

343</h3>343</h3>

344 344

345在 `/mcp` 面板中切換 server 關閉，以停止 Claude Code 連接到它，而不會失去其配置。Claude Code 仍然在 `/mcp` 中列出 server，標記為已停用。345在 `/mcp` 面板中切換伺服器關閉，以停止 Claude Code 連接到它，而不會失去其設定。Claude Code 仍然在 `/mcp` 中列出伺服器，標記為已停用。

346 346

347當您切換 server 時，Claude Code 在 `~/.claude.json` 中按專案記錄您的選擇，在兩個涵蓋不相交 server 集合的列表之一中：347當您切換伺服器時，Claude Code 在 `~/.claude.json` 中按專案記錄您的選擇，在兩個涵蓋不相交伺服器集合的列表之一中：

348 348

349* `disabledMcpServers`：使用者配置的 servers、plugin servers、您的組織[透過受管設定提供](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)的 servers、Claude Code [自己擷取](#how-connectors-reach-claude-code)的 claude.ai 連接器以及預設為開啟的內建 servers 的選擇退出列表。Claude Code 不會連接到您在此列出的 server。當您使用[停用 claude.ai 連接器](#disable-claude-ai-connectors)中所述的按專案 `/mcp` 切換停用 claude.ai 連接器時，Claude Code 會在此列表下使用其顯示名稱（例如 `claude.ai Slack`）寫入它。349* `disabledMcpServers`：使用者設定伺服器、外掛伺服器、您的組織 [透過受管設定提供](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)的伺服器、Claude Code [自身擷取](#how-connectors-reach-claude-code)的 claude.ai 連接器以及預設開啟的內建伺服器的選擇退出列表。Claude Code 不連接您在此列出的伺服器。當您使用 [停用 claude.ai 連接器](#disable-claude-ai-connectors)中描述的按專案 `/mcp` 切換停用 claude.ai 連接器時，Claude Code 在此列表下使用其顯示名稱寫入它，例如 `claude.ai Slack`。

350* `enabledMcpServers`：預設為關閉的內建 servers（例如 `computer-use`）的選擇加入列表。Claude Code 只在您在此列出時連接到預設關閉的 server。350* `enabledMcpServers`：預設關閉的內建伺服器（例如 `computer-use`）的選擇加入列表。Claude Code 只在您在此列出時連接預設關閉的伺服器。

351 351

352Claude Code 為每個 server 查詢恰好兩個列表之一，因此兩個列表都不會覆蓋另一個。如果您將常規 server 新增到 `enabledMcpServers`，或將預設關閉的內建 server 新增到 `disabledMcpServers`，Claude Code 會忽略該項目。352Claude Code 為每個伺服器查詢恰好兩個列表之一，因此兩個列表都不會覆蓋另一個。如果您將常規伺服器新增到 `enabledMcpServers`，或將預設關閉的內建伺服器新增到 `disabledMcpServers`，Claude Code 會忽略該項目。

353 353

354`disabledMcpServers` 和 `enabledMcpServers` 與 [`enabledMcpjsonServers`](/docs/zh-TW/settings-reference#enabledmcpjsonservers) 和 [`disabledMcpjsonServers`](/docs/zh-TW/settings-reference#disabledmcpjsonservers) 無關，它們控制專案 `.mcp.json` 檔案中定義的 servers 的批准。354`disabledMcpServers` 和 `enabledMcpServers` 與 [`enabledMcpjsonServers`](/docs/zh-TW/settings-reference#enabledmcpjsonservers) 和 [`disabledMcpjsonServers`](/docs/zh-TW/settings-reference#disabledmcpjsonservers) 無關，它們控制專案的 `.mcp.json` 檔案中定義的伺服器的核准。

355 355

356<h3 id="mcp-client-runtimes">356<h3 id="mcp-client-runtimes">

357 MCP 用戶端執行時357 MCP 用戶端執行時

358</h3>358</h3>

359 359

360Claude Code 透過兩個用戶端執行時之一連接到 MCP servers。v1 執行時建立在 MCP TypeScript SDK 1.x 上。v2 執行時是 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上的相同代碼，它新增了 MCP 協議修訂版 2026-07-28。此頁面的其餘部分適用於兩個執行時，除非某個部分命名 v2 執行時。360Claude Code 透過兩個用戶端執行時之一連接到 MCP 伺服器。v1 執行時建立在 MCP TypeScript SDK 1.x 上。v2 執行時是 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上的相同代碼，它新增 MCP 協議修訂 2026-07-28。此頁面的其餘部分適用於兩個執行時，除非某個部分命名 v2 執行時。

361 361

362Claude Code 每次啟動時選擇執行時，並保持到您退出。在[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的 sessions 中，它在 Claude Code v2.1.232 或更新版本上使用 v2 執行時。362Claude Code 每次啟動時選擇執行時，並保持到您退出。在 [擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中，它在 Claude Code v2.1.232 或更新版本上使用 v2 執行時。

363 363

364在不擷取功能旗標的 sessions 中，Claude Code 在 Claude Code v2.1.274 或更新版本上預設使用 v2 執行時：364在不擷取功能旗標的工作階段中，Claude Code 在 Claude Code v2.1.274 或更新版本上預設使用 v2 執行時：

365 365

366* Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的 Sessions，除非嵌入 Claude Code 的主機平台設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars)366* Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的工作階段，除非嵌入 Claude Code 的主機平台設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars)

367* 透過 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 登入的 Sessions367* 透過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)登入的工作階段

368* 您關閉遙測或功能旗標擷取的 Sessions，例如使用 `DISABLE_TELEMETRY`368* 您關閉遙測或功能旗標擷取的工作階段，例如使用 `DISABLE_TELEMETRY`

369 369

370在 v2 上，Claude Code 也：370在 v2 上，Claude Code 也：

371 371

372* 詢問 HTTP servers 是否支援較新的修訂版，並與支援的 servers 一起使用它。它也在擷取功能旗標的 sessions 中詢問 claude.ai 連接器 servers。若要讓它詢問 stdio servers 或每個 session 中的連接器 servers，請設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto`。它連接到每個其他 server，如 v1 所做的那樣。372* 詢問 HTTP 伺服器他們是否支援較新的修訂，並與支援的伺服器一起使用它。它也在擷取功能旗標的工作階段中詢問 claude.ai 連接器伺服器。若要讓它詢問 stdio 伺服器或每個工作階段中的連接器伺服器，請設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto`。它連接到每個其他伺服器，如 v1 所做的那樣。

373* 從較新修訂版上的 servers 接收 `list_changed` 通知，透過它保持開啟的[流](#notification-streams-on-the-v2-runtime)。373* 在 [它保持開啟的流](#notification-streams-on-the-v2-runtime)上從較新修訂上的伺服器接收 `list_changed` 通知。

374* 不註冊在較新修訂版上連接的[channel](#push-messages-with-channels) server，因為該修訂版無法攜帶 channel 訊息。374* 不註冊在較新修訂上連接的 [通道](#push-messages-with-channels)伺服器，因為該修訂無法攜帶通道訊息。

375* 失敗[MCP OAuth 登入](#authenticate-with-remote-mcp-servers)，其授權回應命名意外的簽發者。375* 失敗 [MCP OAuth 登入](#authenticate-with-remote-mcp-servers)，其授權回應命名意外發行者。

376* 只將 [MCP OAuth](#authenticate-with-remote-mcp-servers) 認證傳送到透過 HTTPS 或在 `localhost`、`127.0.0.1` 或 `::1` 提供的 token 端點。對於 token 端點為其他地方（例如您本機網路上的裝置）的純 `http://` 的 server，登入失敗。請參閱 [Refusing to send credentials to non-https token endpoint](/docs/zh-TW/errors#refusing-to-send-credentials-to-non-https-token-endpoint)。376* 僅將 [MCP OAuth](#authenticate-with-remote-mcp-servers) 認證傳送到透過 HTTPS 或在 `localhost`、`127.0.0.1` 或 `::1` 上提供的令牌端點。對於令牌端點為其他地方（例如本機網路上的裝置）的純 `http://` 的伺服器，登入失敗。請參閱 [拒絕將認證傳送到非 https 令牌端點](/docs/zh-TW/errors#refusing-to-send-credentials-to-non-https-token-endpoint)。

377 377

378Anthropic 可以使用 Claude Code 擷取的功能旗標將特定 server 保持在較早的協議上，或關閉該流。378Anthropic 可以使用功能旗標 Claude Code 擷取將特定伺服器保持在較早的協議上，或關閉該流。

379 379

380若要自己選擇執行時，請設定 [`MCP_SDK_GENERATION`](/docs/zh-TW/env-vars) 為 `v1` 或 `v2`。若要決定 Claude Code 是否詢問，請設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto` 或 `legacy`。380若要自行選擇執行時，請設定 [`MCP_SDK_GENERATION`](/docs/zh-TW/env-vars) 為 `v1` 或 `v2`。若要決定 Claude Code 是否詢問，請設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto` 或 `legacy`。

381 381

382<h3 id="dynamic-tool-updates">382<h3 id="dynamic-tool-updates">

383 動態工具更新383 動態工具更新

384</h3>384</h3>

385 385

386Claude Code 支援 MCP `list_changed` 通知，允許 MCP servers 動態更新其可用工具、提示和資源，而無需您斷開連接並重新連接。當 MCP server 傳送 `list_changed` 通知時，Claude Code 會自動重新整理該 server 的可用功能。386Claude Code 支援 MCP `list_changed` 通知，允許 MCP 伺服器動態更新其可用工具、提示和資源，而無需您斷開連接並重新連接。當 MCP 伺服器傳送 `list_changed` 通知時，Claude Code 會自動重新整理來自該伺服器的可用功能。

387 387

388如果重新整理請求失敗，Claude Code 會保留 server 之前發現的工具、提示和資源，直到稍後的重新整理成功。在 v2.1.214 之前，重新整理期間的暫時性錯誤會將 server 的工具、提示和資源替換為空列表。388如果重新整理請求失敗，Claude Code 會保留伺服器之前發現的工具、提示和資源，直到稍後的重新整理成功。在 v2.1.214 之前，重新整理期間的暫時性錯誤會將伺服器的工具、提示和資源替換為空列表。

389 389

390<h4 id="notification-streams-on-the-v2-runtime">390<h4 id="notification-streams-on-the-v2-runtime">

391 v2 執行時上的通知流391 v2 執行時上的通知流

392</h4>392</h4>

393 393

394在 [v2 執行時](#mcp-client-runtimes)上，Claude Code 從較新協議修訂版上的 server 接收 `list_changed` 通知，透過它保持開啟的流。當流關閉時，Claude Code 會重新開啟它，有兩個限制：394在 [v2 執行時](#mcp-client-runtimes)上，Claude Code 在它保持開啟的流上從較新協議修訂上的伺服器接收 `list_changed` 通知。當流關閉時，Claude Code 會重新開啟它，有兩個限制：

395 395

396* **流在 10 秒內再次關閉**：Claude Code 最多重新開啟它三次，然後停止該連接。396* **流在 10 秒內再次關閉**：Claude Code 最多重新開啟三次，然後停止該連接。

397* **流保持開啟超過 10 秒，然後關閉**，如流到無伺服器主機通常所做的那樣：在一小時內五次重新開啟後，Claude Code 在下一次之前等待約六小時。397* **流保持開啟超過 10 秒，然後關閉**（如流到無伺服器主機通常所做的那樣）：在一小時內五次重新開啟後，Claude Code 在下一次之前等待約六小時。

398 398

399直到流重新開啟，您保留 server 的最後擷取的工具、提示和資源。若要更快地選擇其變更，請從 `/mcp` 重新連接 server。399直到流重新開啟，您保留伺服器的最後擷取工具、提示和資源。若要更快地選擇其變更，請從 `/mcp` 重新連接伺服器。

400 400

401<h3 id="automatic-reconnection">401<h3 id="automatic-reconnection">

402 自動重新連接402 自動重新連接

403</h3>403</h3>

404 404

405Claude Code 重新連接在 session 中途斷開的遠端 server，並在暫時性錯誤後重試 HTTP 或 SSE server 的首次連接。Stdio servers 是本機程序，Claude Code 不會自動重新連接它們。405Claude Code 重新連接在工作階段中途掉線的遠端伺服器，並在暫時性錯誤後重試 HTTP 或 SSE 伺服器的首次連接。Stdio 伺服器是本機程序，Claude Code 不會自動重新連接它們。

406 406

407<h4 id="mid-session-drops-of-a-remote-server">407<h4 id="mid-session-drops-of-a-remote-server">

408 遠端 server 的中途斷開408 遠端伺服器的工作階段中途掉線

409</h4>409</h4>

410 410

411Claude Code 使用指數退避重新連接已斷開的遠端 server：最多五次嘗試，從一秒延遲開始，每次加倍。您看到的內容取決於您如何執行 Claude Code：411Claude Code 使用指數退避重新連接掉線的遠端伺服器：最多五次嘗試，從一秒延遲開始，每次加倍。您看到的內容取決於您如何執行 Claude Code：

412 412

413* **在互動式 session 中**：`/mcp` 在 Claude Code 重新連接時將 server 顯示為待處理。五次失敗嘗試後，Claude Code 將 server 標記為失敗，或在 server 需要再次授權時標記為需要驗證。當它將 server 標記為失敗時，您會看到 `MCP server "<name>" disconnected · open /mcp to reconnect` 通知。您可以從 `/mcp` 手動重試。413* **在互動式工作階段中**：`/mcp` 在 Claude Code 重新連接時將伺服器顯示為待處理。在五次失敗嘗試後，Claude Code 將伺服器標記為失敗，或在伺服器需要再次授權時標記為需要驗證。當它將伺服器標記為失敗時，您會看到 `MCP server "<name>" disconnected · open /mcp to reconnect` 通知。您可以從 `/mcp` 手動重試。

414* **在 [`claude -p`](/docs/zh-TW/headless) 執行和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) sessions 中**：Claude Code 按相同的時間表重新連接，沒有 `/mcp` 面板顯示嘗試。414* **在 [`claude -p`](/docs/zh-TW/headless) 執行和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 工作階段中**：Claude Code 按相同的時間表重新連接，沒有 `/mcp` 面板顯示嘗試。

415 415

416<h4 id="failed-first-connections">416<h4 id="failed-first-connections">

417 失敗的首次連接417 失敗的首次連接

418</h4>418</h4>

419 419

420當 HTTP 或 SSE server 的首次連接因暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）失敗時，Claude Code 最多重試三次。如果連接仍然失敗，Claude Code 將 server 標記為失敗。Claude Code 在啟動時和 server 在 session 中途新增時以這種方式重試。這包括 Claude Code 從其配置新增到[雲端 session](/docs/zh-TW/claude-code-on-the-web) 的 server 和您使用 Agent SDK 的 [`setMcpServers()`](/docs/zh-TW/agent-sdk/typescript) 新增的 server。420當 HTTP 或 SSE 伺服器的首次連接因暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）失敗時，Claude Code 最多重試三次。如果連接仍然失敗，Claude Code 將伺服器標記為失敗。

421 421

422Claude Code 在這些情況下不會重試：422Claude Code 在這些情況下不重試：

423 423

424* WebSocket server 的首次連接424* WebSocket 伺服器的首次連接

425* 驗證或找不到錯誤，因為它需要配置變更才能解決。當 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 是 server 的 `Authorization` 標頭的唯一來源時，Claude Code 無論如何都會重試驗證錯誤，因為它在每次嘗試時重新執行 helper 並可以選擇新的認證425* 驗證或找不到錯誤，因為它需要設定變更才能解決。當 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 是伺服器唯一的 `Authorization` 標頭來源時，Claude Code 仍然重試驗證錯誤，因為它在每次嘗試時重新執行助手並可以選擇新認證

426 426

427<h4 id="failed-discovery-requests">427<h4 id="failed-discovery-requests">

428 失敗的發現請求428 失敗的發現請求

429</h4>429</h4>

430 430

431server 連接後，Claude Code 向它傳送功能發現請求，例如 `tools/list`、`prompts/list` 和 `resources/list`。Claude Code 在暫時性網路或 server 錯誤後最多重試這些請求三次，短退避。它不會重試驗證錯誤、4xx 回應或請求逾時。431伺服器連接後，Claude Code 向其傳送功能發現請求，例如 `tools/list`、`prompts/list` 和 `resources/list`。Claude Code 在暫時性網路或伺服器錯誤後使用短退避最多重試這些請求三次。它不重試驗證錯誤、4xx 回應或請求逾時。

432 432

433<h4 id="how-claude-learns-that-a-server-failed">433<h4 id="how-claude-learns-that-a-server-failed">

434 Claude 如何了解 server 失敗434 Claude 如何了解伺服器失敗

435</h4>435</h4>

436 436

437Claude Code 是否告訴 Claude 配置的 server 無法連接取決於[工具搜尋](#scale-with-mcp-tool-search)，預設為開啟：437Claude Code 是否告訴 Claude 關於失敗連接的已設定伺服器取決於 [工具搜尋](#scale-with-mcp-tool-search)（預設開啟）：

438 438

439* 使用工具搜尋，Claude Code 告訴 Claude 哪個 server 失敗及其連接錯誤，因此 Claude 在其回應中報告連接失敗。Claude Code 在找不到匹配工具的 `ToolSearch` 結果中包含相同的資訊。439* 使用工具搜尋，Claude Code 告訴 Claude 哪個伺服器失敗及其連接錯誤，因此 Claude 在其回應中報告連接失敗。Claude Code 在 `ToolSearch` 結果中包含相同的資訊，該結果找不到匹配的工具。

440* 在任何[沒有工具搜尋的配置](#configure-tool-search)中，Claude Code 不會向 Claude 報告失敗的 server 連接。440* 在任何 [沒有工具搜尋的設定](#configure-tool-search)中，Claude Code 不向 Claude 報告失敗的伺服器連接。

441 441

442<h3 id="push-messages-with-channels">442<h3 id="push-messages-with-channels">

443 使用 channels 推送訊息443 使用通道推送訊息

444</h3>444</h3>

445 445

446MCP server 也可以直接將訊息推送到您的 session 中，以便 Claude 可以回應外部事件，例如 CI 結果、監控警報或聊天訊息。若要啟用此功能，您的 server 宣告 `claude/channel` 功能，並在啟動時使用 `--channels` 旗標選擇加入。請參閱 [Channels](/docs/zh-TW/channels) 以使用官方支援的 channel，或 [Channels reference](/docs/zh-TW/channels-reference) 以建立您自己的。446MCP 伺服器也可以直接將訊息推送到您的工作階段，以便 Claude 可以對外部事件（如 CI 結果、監控警報或聊天訊息）做出反應。若要啟用此功能，您的伺服器宣告 `claude/channel` 功能，您在啟動時使用 `--channels` 旗標選擇加入。請參閱 [通道](/docs/zh-TW/channels)以使用官方支援的通道，或 [通道參考](/docs/zh-TW/channels-reference)以建立您自己的。

447 447

448在 [v2 執行時](#mcp-client-runtimes)上，如果您設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto` 且 channel server 協商 MCP 協議修訂版 2026-07-28，它無法傳遞 channel 訊息，因此 Claude Code 不會將其註冊為 channel。保留變數未設定，或將其設定為 `legacy`，將 stdio servers 保持在較早的握手上。448在 [v2 執行時](#mcp-client-runtimes)上，如果您設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto` 且通道伺服器協商 MCP 協議修訂 2026-07-28，它無法傳遞通道訊息，因此 Claude Code 不會將其註冊為通道。保持變數未設定或設定為 `legacy` 會將 stdio 伺服器保持在較早的握手上。

449 449

450<Tip>450<Tip>

451 提示：451 提示：

452 452

453 * 使用 `-s` 或 `--scope` 旗標指定配置的儲存位置：453 * 使用 `-s` 或 `--scope` 旗標指定設定的儲存位置：

454 * `local` (預設)：僅在目前專案中對您可用454 * `local`（預設）：僅在目前專案中對您可用

455 * `project`：透過 `.mcp.json` 檔案與專案中的所有人共享455 * `project`：透過 `.mcp.json` 檔案與專案中的每個人共享

456 * `user`：在所有專案中對您可用456 * `user`：在所有專案中對您可用

457 * 使用 `-e` 或 `--env` 旗標設定環境變數 (例如，`-e KEY=value`)457 * 使用 `-e` 或 `--env` 旗標設定環境變數（例如 `-e KEY=value`）

458 * `--transport` 和 `--header` 旗標也接受 `-t` 和 `-H` 短形式458 * `--transport` 和 `--header` 旗標也接受 `-t` 和 `-H` 短形式

459 * 使用 `MCP_TIMEOUT` 環境變數配置 MCP server 啟動逾時 (例如，`MCP_TIMEOUT=10000 claude` 設定 10 秒逾時)459 * 使用 `MCP_TIMEOUT` 環境變數設定 MCP 伺服器啟動逾時（例如 `MCP_TIMEOUT=10000 claude` 設定 10 秒逾時）

460 * 透過在該 server 的 `.mcp.json` 項目中新增 `timeout` 欄位（以毫秒為單位）來設定每個 server 的工具執行逾時，例如 `"timeout": 600000` 表示十分鐘。這只會覆寫該 server 的 `MCP_TOOL_TIMEOUT` 環境變數460 * 透過將 `timeout` 欄位（以毫秒為單位）新增到該伺服器的 `.mcp.json` 項目來設定按伺服器工具執行逾時，例如 `"timeout": 600000` 表示十分鐘。這僅針對該伺服器覆蓋 `MCP_TOOL_TIMEOUT` 環境變數

461 * 當 MCP 工具輸出超過 10,000 個 tokens 時，Claude Code 會顯示警告，並預設將輸出限制為 25,000 個 tokens。若要增加此限制，請設定 `MAX_MCP_OUTPUT_TOKENS` 環境變數 (例如，`MAX_MCP_OUTPUT_TOKENS=50000`)；警告閾值是固定的。請參閱 [MCP output limits and warnings](#mcp-output-limits-and-warnings)461 * 當 MCP 工具輸出超過 10,000 個令牌時，Claude Code 顯示警告，預設限制輸出為 25,000 個令牌。若要提高限制，請設定 `MAX_MCP_OUTPUT_TOKENS` 環境變數（例如 `MAX_MCP_OUTPUT_TOKENS=50000`）；警告閾值是固定的。請參閱 [MCP 輸出限制和警告](#mcp-output-limits-and-warnings)

462 * 使用 `/mcp` 向需要 OAuth 2.0 驗證的遠端 servers 進行驗證462 * 使用 `/mcp` 驗證需要 OAuth 2.0 驗證的遠端伺服器

463</Tip>463</Tip>

464 464

465每個 server 的 `timeout` 是每個工具呼叫的硬牆鐘限制，來自 server 的進度通知不會延長它。低於 1000 的值會被忽略並落回到 `MCP_TOOL_TIMEOUT`，或在該變數未設定時落回到其預設值約 28 小時。對於 HTTP、SSE 或[claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) server，還有第二個每個請求的計時器，涵蓋每個請求直到 server 的第一個回應位元組。Claude Code 將該計時器設定為三個值中最大的：60 秒、適用於 server 的工具逾時和 `MCP_TIMEOUT`。未設定的 `MCP_TOOL_TIMEOUT` 的 28 小時預設值不會進入該比較，低於 60 秒的值不會縮短計時器。Stdio 和 WebSocket servers 沒有每個請求的計時器。465按伺服器 `timeout` 是每個工具呼叫的硬牆鐘限制，來自伺服器的進度通知不會延長它。低於 1000 的值被忽略並落回 `MCP_TOOL_TIMEOUT`，或在該變數未設定時落回其約 28 小時的預設值。對於 HTTP、SSE 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)伺服器，還有第二個按請求計時器，涵蓋每個請求到伺服器的第一個回應位元組。Claude Code 將該計時器設定為三個值中最大的：60 秒、適用於伺服器的工具逾時和 `MCP_TIMEOUT`。未設定 `MCP_TOOL_TIMEOUT` 的 28 小時預設值不進入該比較，低於 60 秒的值不會縮短計時器。Stdio 和 WebSocket 伺服器沒有按請求計時器。

466 466

467每個 server 至少 1000 的 `timeout` 也會作為下面所述的閒置逾時的下限：Claude Code 永遠不會因為閒置而在每個 server 的 `timeout` 之前中止該 server 的工具呼叫。需要 Claude Code v2.1.203 或更新版本。467至少 1000 的按伺服器 `timeout` 也充當下面描述的空閒逾時的下限：Claude Code 永遠不會因空閒而中止該伺服器的工具呼叫早於按伺服器 `timeout`。需要 Claude Code v2.1.203 或更新版本。

468 468

469對遠端 MCP server 的工具呼叫如果在閒置視窗內沒有傳送回應和進度通知，會以錯誤中止，而不是等待牆鐘限制。它適用於除 IDE servers 和 SDK 進程內 servers 之外的每種 server 類型。HTTP、SSE、WebSocket 和 [claude.ai 連接器](#use-mcp-servers-from-claude-ai) servers 的閒置視窗預設為五分鐘，stdio servers 的預設為 30 分鐘。在 v2.1.203 之前，stdio servers 不受閒置逾時限制。469對 MCP 伺服器的工具呼叫，在空閒視窗內不傳送回應且不傳送進度通知，會因錯誤而中止，而不是等待牆鐘限制。空閒逾時適用於除 IDE 伺服器和 SDK 進程內伺服器外的每個伺服器類型。空閒視窗預設為 HTTP、SSE、WebSocket 和 [claude.ai 連接器](#use-mcp-servers-from-claude-ai)伺服器的五分鐘，以及 stdio 伺服器的 30 分鐘。在 v2.1.203 之前，stdio 伺服器免除空閒逾時。

470 470

471在毫秒中設定 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-TW/env-vars) 環境變數以變更閒置視窗，或將其設定為 `0` 以停用檢查。471在毫秒中設定 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-TW/env-vars)環境變數以變更空閒視窗，或設定為 `0` 以停用檢查。

472 472

473這些逾時限制呼叫可以執行多長時間，不一定總是它阻止 session 多長時間：執行超過兩分鐘的主對話呼叫會先移至背景工作。請參閱[長工具呼叫的自動背景化](#automatic-backgrounding-of-long-tool-calls)。473這些逾時限制呼叫可以執行多長時間，不總是它阻止工作階段多長時間：執行超過兩分鐘的主對話呼叫首先移動到背景任務。請參閱 [長工具呼叫的自動背景化](#automatic-backgrounding-of-long-tool-calls)。

474 474

475<h3 id="automatic-backgrounding-of-long-tool-calls">475<h3 id="automatic-backgrounding-of-long-tool-calls">

476 長工具呼叫的自動背景化476 長工具呼叫的自動背景化

477</h3>477</h3>

478 478

479主對話中仍在執行兩分鐘後的 MCP 工具呼叫會移至背景工作，而不是阻止 session。Claude 立即接收工作 ID 並繼續工作，結果在呼叫解決時作為工作通知到達。自動背景化需要 Claude Code v2.1.212 或更新版本。479主對話中仍在執行兩分鐘後的 MCP 工具呼叫移動到背景任務，而不是阻止工作階段。Claude 立即接收任務 ID 並繼續工作，結果在呼叫解決時作為任務通知到達。自動背景化需要 Claude Code v2.1.212 或更新版本。

480 480

481工作出現在 [`/tasks`](/docs/zh-TW/commands#all-commands) 中，您也可以在其中停止它，它不會在退出 session 時存活。工作的項目顯示 server 報告的最新進度。481任務出現在 [`/tasks`](/docs/zh-TW/commands#all-commands)中，您也可以在其中停止它，它不會在退出工作階段時存活。任務的項目顯示伺服器報告的最新進度。

482 482

483每個呼叫限制仍然適用於呼叫在背景執行時：由每個 server `timeout` 或 [`MCP_TOOL_TIMEOUT`](/docs/zh-TW/env-vars) 設定的牆鐘限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-TW/env-vars) 設定的閒置逾時。483按呼叫限制仍然適用於呼叫在背景中執行時：由按伺服器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](/docs/zh-TW/env-vars)設定的牆鐘限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-TW/env-vars)設定的空閒逾時。

484 484

485設定 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/zh-TW/env-vars) 環境變數（以毫秒為單位）以變更閾值，或將其設定為 `0` 以關閉自動背景化。設定 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 為 `1` 也會關閉它，以及所有其他背景工作功能。485在毫秒中設定 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/zh-TW/env-vars)環境變數以變更閾值，或設定為 `0` 以關閉自動背景化。設定 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 為 `1` 也會關閉它，以及所有其他背景任務功能。

486 486

487某些呼叫永遠不會移至背景：487某些呼叫永遠不會移動到背景：

488 488

489* 來自 [subagents](/docs/zh-TW/sub-agents) 的呼叫；Claude Code 只背景化主對話呼叫489* 來自 [子代理](/docs/zh-TW/sub-agents)的呼叫；Claude Code 只背景化主對話呼叫

490* 對 IDE servers 的呼叫490* 對 IDE 伺服器的呼叫

491* 在[非互動式模式](/docs/zh-TW/headless)中的呼叫，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 設定為 `1`，因為一次性執行可能在結果到達之前結束491* 在 [非互動式模式](/docs/zh-TW/headless)中的呼叫，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 設定為 `1`，因為一次性執行可能在結果到達之前結束

492 492

493等待開啟[引發對話](#respond-to-mcp-elicitation-requests)的呼叫在對話開啟時不會背景化；server 被阻止在您的輸入上，而不是緩慢，因此 Claude Code 會延遲移動，直到對話關閉。493等待開啟 [引出對話](#respond-to-mcp-elicitation-requests)的呼叫在對話開啟時不會背景化；伺服器被阻止在您的輸入上，而不是緩慢，因此 Claude Code 將移動延遲到對話關閉。

494 494

495<h3 id="plugin-provided-mcp-servers">495<h3 id="plugin-provided-mcp-servers">

496 Plugin 提供的 MCP servers496 外掛提供的 MCP 伺服器

497</h3>497</h3>

498 498

499[Plugins](/docs/zh-TW/plugins/overview) 可以捆綁 MCP servers，在啟用 plugin 時提供工具和整合。Plugin MCP servers 的工作方式與使用者配置的 servers 相同。499[外掛](/docs/zh-TW/plugins/overview)可以捆綁 MCP 伺服器，在您啟用外掛時提供工具和整合。外掛 MCP 伺服器的工作方式與使用者設定的伺服器相同。

500 500

501**Plugin MCP servers 的工作方式**：501**外掛 MCP 伺服器如何工作**：

502 502

503* Plugins 在 plugin 根目錄的 `.mcp.json` 中或在 `plugin.json` 中內聯定義 MCP servers503* 外掛在外掛根目錄的 `.mcp.json` 中或內聯在 `plugin.json` 中定義 MCP 伺服器

504* 啟用 plugin 時，其 MCP servers 會自動啟動504* 當您啟用外掛時，Claude Code 自動啟動其 MCP 伺服器

505* Claude Code 將 plugin MCP 工具與手動配置的 MCP 工具一起提供505* Claude Code 將外掛 MCP 工具與手動設定的 MCP 工具一起提供

506* 您透過安裝或卸載 plugin 新增和移除 plugin servers，而不是使用 `/mcp` 命令。您仍然可以在 `/mcp` 中[切換已安裝的 plugin server 關閉](#disable-a-server-without-removing-it)，這會停止 Claude Code 連接到它，而不會移除 plugin506* 您透過安裝或卸載外掛新增和移除外掛伺服器，而不是使用 `/mcp` 命令。您仍然可以 [在 `/mcp` 中切換已安裝的外掛伺服器關閉](#disable-a-server-without-removing-it)，這會停止 Claude Code 連接到它，而不會移除外掛

507 507

508**Plugin MCP 配置範例**：508**範例外掛 MCP 設定**：

509 509

510在 plugin 根目錄的 `.mcp.json` 中：510在外掛根目錄的 `.mcp.json` 中：

511 511

512```json theme={null}512```json theme={null}

513{513{

523}523}

524```524```

525 525

526或在 `plugin.json` 中內聯：526或內聯在 `plugin.json` 中：

527 527

528```json theme={null}528```json theme={null}

529{529{

537}537}

538```538```

539 539

540**Plugin MCP 功能**：540**外掛 MCP 功能**：

541 541

542* **自動生命週期**：servers 在這些點連接和斷開：542* **自動生命週期**：伺服器在這些點連接和斷開連接：

543 * 在 session 啟動時，Claude Code 自動連接已啟用 plugins 的 servers。在 `/mcp` 中，您之前使用過的遠端 (HTTP 或 SSE) plugin server 可以顯示[`cached` 狀態](#server-status-detail)而不是；Claude Code 在 Claude 首次呼叫其其中一個工具時連接它543 * 在工作階段啟動時，Claude Code 自動連接已啟用外掛的伺服器。在 `/mcp` 中，您之前使用過的遠端（HTTP 或 SSE）外掛伺服器可以改為顯示 [`cached` 狀態](#server-status-detail)；Claude Code 在 Claude 首次呼叫其工具之一時連接它

544 * 如果您在 session 期間啟用或停用 plugin，Claude Code 在變更套用時連接或斷開其 MCP servers。[在不重新啟動的情況下套用 plugin 變更](/docs/zh-TW/plugins/cli-reference#reload-plugins)描述何時發生。在沒有互動式終端的 session 中，`/reload-plugins` 不會連接或斷開 plugin MCP servers；這些變更在您的下一個 session 中生效544 * 如果您在工作階段期間啟用或停用外掛，Claude Code 在變更適用時連接或斷開其 MCP 伺服器。[在不重新啟動的情況下應用外掛變更](/docs/zh-TW/plugins/cli-reference#reload-plugins)描述何時發生。在沒有互動式終端的工作階段中，`/reload-plugins` 不連接或斷開外掛 MCP 伺服器；這些變更在您的下一個工作階段中生效

545 * 當您重新載入時，Claude Code 保留配置未變更的 plugin servers 的即時連接，並在您[替換 session 的 MCP server 列表](/docs/zh-TW/agent-sdk/typescript#mcpsetserversresult)而不命名它們時執行相同操作545 * 當您重新載入時，Claude Code 保留設定未變更的外掛伺服器的即時連接，並在您 [從 Agent SDK 替換工作階段的 MCP 伺服器列表](/docs/zh-TW/agent-sdk/typescript#mcpsetserversresult)而不命名它們時執行相同操作

546 * 當您在 v2.1.246 或更新版本上[使用 `/cd` 移動 session](/docs/zh-TW/permissions#move-the-session-to-another-directory) 時，Claude Code 連接新目錄的設定啟用的 plugins 的 servers，並斷開不再啟用的 plugins 的 servers，因此您不需要在移動後執行 `/reload-plugins`546 * 當您在 v2.1.246 或更新版本上 [使用 `/cd` 移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)時，Claude Code 連接新目錄的設定啟用的外掛的伺服器，並斷開不再啟用的外掛的伺服器，因此您不需要在移動後執行 `/reload-plugins`

547 * 在[雲端 sessions](/docs/zh-TW/claude-code-on-the-web) 中，對尚未連接的 plugin server 的 MCP 呼叫（例如在閒置 session 喚醒後），按需啟動 server 並等待它連接547 * 在 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，對尚未連接的外掛伺服器的 MCP 呼叫（例如空閒工作階段喚醒後）按需啟動伺服器並等待它連接

548* **路徑佔位符**：`${CLAUDE_PLUGIN_ROOT}` 解析為 plugin 的安裝目錄，`${CLAUDE_PLUGIN_DATA}` 解析為其[持久狀態](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)目錄，`${CLAUDE_PROJECT_DIR}` 解析為穩定的專案根目錄。替換適用於：548* **路徑佔位符**：`${CLAUDE_PLUGIN_ROOT}` 解析為外掛的安裝目錄，`${CLAUDE_PLUGIN_DATA}` 解析為其 [持久狀態](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)目錄，`${CLAUDE_PROJECT_DIR}` 解析為穩定的專案根目錄。替換適用於：

549 * `stdio` servers：`command`、`args`、`env`549 * `stdio` 伺服器：`command`、`args`、`env`

550 * `http`、`sse` 和 `ws` servers：`url`、`headers` 和 `headersHelper`550 * `http`、`sse` 和 `ws` 伺服器：`url`、`headers` 和 `headersHelper`

551* **使用者環境存取**：存取與手動配置的 servers 相同的環境變數551* **使用者環境存取**：存取與手動設定伺服器相同的環境變數

552* **多種傳輸類型**：支援 stdio、SSE、HTTP 和 WebSocket 傳輸，傳輸支援可能因 server 而異552* **多個傳輸類型**：支援 stdio、SSE、HTTP 和 WebSocket 傳輸，儘管傳輸支援可能因伺服器而異

553 553

554Plugin servers 在 `/mcp` 中出現，並有指示器顯示它們來自 plugins。554外掛伺服器出現在 `/mcp` 中，指標顯示它們來自外掛。

555 555

556**Plugin MCP 工具名稱**：556對於外掛的 stdio 伺服器，`claude mcp get` 列印 `Command: stdio`、空 `Args:` 行和每個環境變數作為 `NAME=[REDACTED]`。值被隱藏，因為它們可能攜帶認證。

557 557

558來自 plugin 捆綁的 MCP server 的工具在其可呼叫名稱中包含 plugin 名稱和 server 金鑰。完整形式是 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 以外的任何字元都被替換為 `_`。對於在名為 `my-plugin` 的 plugin 中捆綁的 `database-tools` server，`query` 工具可呼叫為：558**外掛 MCP 工具名稱**：

559

560來自外掛捆綁的 MCP 伺服器的工具在其可呼叫名稱中包含外掛名稱和伺服器金鑰。完整形式是 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 以外的任何字元都被替換為 `_`。對於名為 `my-plugin` 的外掛中捆綁的 `database-tools` 伺服器，`query` 工具可呼叫為：

559 561

560```562```

561mcp__plugin_my-plugin_database-tools__query563mcp__plugin_my-plugin_database-tools__query

562```564```

563 565

564在 [permission rules](/docs/zh-TW/permissions)、skill 的 `allowed-tools` 列表、[subagent 的 `tools` 欄位](/docs/zh-TW/sub-agents#available-tools) 或 [hook matcher](/docs/zh-TW/hooks#match-mcp-tools) 中參考工具時，請使用此完整名稱。針對裸 server 金鑰（例如 `mcp__database-tools__.*`）編寫的 hook matcher 永遠不會針對 plugin 捆綁的 server 觸發。566在 [權限規則](/docs/zh-TW/permissions)、技能的 `allowed-tools` 列表、[子代理的 `tools` 欄位](/docs/zh-TW/sub-agents#available-tools)或 [hook 匹配器](/docs/zh-TW/hooks#match-mcp-tools)中參考工具時使用此完整名稱。針對裸伺服器金鑰編寫的 hook 匹配器（例如 `mcp__database-tools__.*`）永遠不會針對外掛捆綁的伺服器觸發。

565 567

566server 本身在範圍名稱 `plugin:<plugin-name>:<server-name>` 下註冊，例如 `plugin:my-plugin:database-tools`。在需要配置的 server 名稱的地方使用該名稱，例如 [`mcp_tool` hook 的 `server` 欄位](/docs/zh-TW/hooks#mcp-tool-hook-fields)。568伺服器本身在範圍名稱 `plugin:<plugin-name>:<server-name>` 下註冊，例如 `plugin:my-plugin:database-tools`。在預期已設定伺服器名稱的地方使用該名稱，例如 [`mcp_tool` hook 的 `server` 欄位](/docs/zh-TW/hooks#mcp-tool-hook-fields)。

567 569

568請參閱 [plugin 元件參考](/docs/zh-TW/plugins/components#mcp-servers)，了解有關使用 plugins 捆綁 MCP servers 的詳細資訊。570請參閱 [外掛元件參考](/docs/zh-TW/plugins/components#mcp-servers)以取得有關使用外掛捆綁 MCP 伺服器的詳細資訊。

569 571

570<h2 id="mcp-installation-scopes">572<h2 id="mcp-installation-scopes">

571 MCP 安裝範圍573 MCP 安裝範圍

1458* 頂層屬性名稱必須為 1 到 64 個字元長，且只能使用 ASCII 字母和數字、`_`、`.` 和 `-`1460* 頂層屬性名稱必須為 1 到 64 個字元長，且只能使用 ASCII 字母和數字、`_`、`.` 和 `-`

1459* 綱要必須對 JSON Schema draft 2020-12 元綱要有效。Claude Code 會對未宣告 `$schema` 的綱要和宣告 draft 2020-12 的綱要套用此檢查。宣告任何其他方言的綱要會跳過此檢查，但上述屬性名稱檢查仍然適用1461* 綱要必須對 JSON Schema draft 2020-12 元綱要有效。Claude Code 會對未宣告 `$schema` 的綱要和宣告 draft 2020-12 的綱要套用此檢查。宣告任何其他方言的綱要會跳過此檢查，但上述屬性名稱檢查仍然適用

1460 1462

1461Claude Code 會在[根層級組合子重寫](#tool-input-schemas-with-a-root-level-combinator)之後執行檢查，對它實際會傳送的綱要進行檢查。

~~1462~~

1463當 Claude Code 排除一個工具時，它會在伺服器的日誌中記錄原因，並告訴 Claude 它排除了哪些工具以及原因，以便您可以詢問 Claude 為什麼工具遺失。如果您修復伺服器上的綱要，下次 Claude Code 載入伺服器的工具時，該工具就會恢復。1463當 Claude Code 排除一個工具時，它會在伺服器的日誌中記錄原因，並告訴 Claude 它排除了哪些工具以及原因，以便您可以詢問 Claude 為什麼工具遺失。如果您修復伺服器上的綱要，下次 Claude Code 載入伺服器的工具時，該工具就會恢復。

1464 1464

1465Claude Code 透過從 Anthropic 取得的功能旗標來開啟排除功能。在[停用旗標取得的部署](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)上，或在旗標從未到達的機器上（例如隔離的機器），Claude Code 仍會執行檢查並在伺服器的日誌中記錄哪個工具會被拒絕，但仍會將工具的綱要傳送給 API。API 會拒絕包含該綱要的請求，並[返回 400 錯誤，按位置命名工具](/docs/zh-TW/errors#tool-input-schema-is-invalid)。在 v2.1.216 之前，沒有部署執行這些檢查。1465Claude Code 透過從 Anthropic 取得的功能旗標來開啟排除功能。在[停用旗標取得的部署](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)上，或在旗標從未到達的機器上（例如隔離的機器），Claude Code 仍會執行檢查並在伺服器的日誌中記錄哪個工具會被拒絕，但仍會將工具的綱要傳送給 API。API 會拒絕包含該綱要的請求，並[返回 400 錯誤，按位置命名工具](/docs/zh-TW/errors#tool-input-schema-is-invalid)。在 v2.1.216 之前，沒有部署執行這些檢查。

mcp-quickstart.md +1 −1

Details

360 360

361 接下來發生的情況告訴您問題在哪裡：361 接下來發生的情況告訴您問題在哪裡：

362 362

363 * 命令啟動並等待輸入：伺服器本身有效。執行 `claude mcp get <name>` 並確認那裡顯示的命令與您剛執行的相符。如果顯示的命令與您輸入的不同，您可能省略了伺服器命令前的 `--` 分隔符。移除伺服器並使用 `--` 重新新增。如果您手寫了 `.mcp.json`，檢查其語法和位置。363 * 命令啟動並等待輸入：伺服器本身有效。執行 `claude mcp get <name>` 並確認那裡顯示的命令與您剛執行的相符。如果顯示的命令與您輸入的不同，您可能省略了伺服器命令前的 `--` 分隔符。移除伺服器並使用 `--` 重新新增。如果您手寫了 `.mcp.json`，檢查其語法和位置。在 v2.1.285 之前，`claude mcp get` 對於保存時沒有 `type` 欄位的 stdio 項目（例如手寫的 `.mcp.json` 項目）不列印 `Command` 行。在這些版本上，執行 `claude mcp list` 代替，它無論如何都會列印命令行。

364 * 命令錯誤：訊息命名缺少的內容，例如 Node.js 或瀏覽器。364 * 命令錯誤：訊息命名缺少的內容，例如 Node.js 或瀏覽器。

365 </Accordion>365 </Accordion>

366 366

monitoring-usage.md +1 −0

Details

1430* `error.type`：Claude Code 停止工作階段的原因。僅在 `refused` 事件上存在：1430* `error.type`：Claude Code 停止工作階段的原因。僅在 `refused` 事件上存在：

1431 * `"helper_failed"`：[原則協助程式執行失敗](/docs/zh-TW/settings-reference#helper-failures)1431 * `"helper_failed"`：[原則協助程式執行失敗](/docs/zh-TW/settings-reference#helper-failures)

1432 * `"policy_invalid"`：管理設定包含停止 Claude Code 啟動的錯誤，或管理來源無法載入，因此 Claude Code 無法檢查組織登入強制執行1432 * `"policy_invalid"`：管理設定包含停止 Claude Code 啟動的錯誤，或管理來源無法載入，因此 Claude Code 無法檢查組織登入強制執行

1433 * `"provider_not_allowed"`：工作階段會使用 API 提供者，或將提供者的流量發送到管理 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 列表不允許的主機。需要 Claude Code v2.1.285 或更新版本

1433 * `"consent_rejected"`：使用者拒絕了伺服器管理設定的[安全核准對話框](/docs/zh-TW/server-managed-settings#security-approval-dialogs)1434 * `"consent_rejected"`：使用者拒絕了伺服器管理設定的[安全核准對話框](/docs/zh-TW/server-managed-settings#security-approval-dialogs)

1434 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) 需要的設定擷取失敗1435 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) 需要的設定擷取失敗

1435 * `"gateway_rejected"`：[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)以 HTTP 403 回答管理設定載入1436 * `"gateway_rejected"`：[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)以 HTTP 403 回答管理設定載入

network-config.md +1 −1

Details

247| `registry.npmjs.org` | 外掛程式安裝（擷取 npm 來源外掛程式套件和安裝外掛程式的 Node.js 套件相依性）、`npx` 啟動的 MCP 伺服器，以及 npm 和 bun 安裝 Claude Code 本身的套件登錄 |247| `registry.npmjs.org` | 外掛程式安裝（擷取 npm 來源外掛程式套件和安裝外掛程式的 Node.js 套件相依性）、`npx` 啟動的 MCP 伺服器，以及 npm 和 bun 安裝 Claude Code 本身的套件登錄 |

249| `*.frame.claudeusercontent.com` | [Artifact](/docs/zh-TW/artifacts) 內容讀取。當 Claude 開啟 Artifact 時，CLI 會從此主機擷取 Artifact 的檔案，且僅當 Artifact 工具[可用](/docs/zh-TW/artifacts#availability)於您的帳戶時。若要關閉工具並移除此需求，請設定 [`"enableArtifact": false`](/docs/zh-TW/settings-reference#enableartifact) 或 [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/zh-TW/env-vars)；Claude Code 也會遵守已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 設定。請參閱[停用 Artifact](/docs/zh-TW/artifacts#disable-artifacts) 以了解這些設定如何互動 |249| `*.frame.claudeusercontent.com` | [Artifact](/docs/zh-TW/artifacts) 內容讀取。當 Claude 開啟 Artifact 時，CLI 會從此主機擷取 Artifact 的檔案，且僅當 Artifact 工具[可用](/docs/zh-TW/artifacts#availability)於您的帳戶時。若要關閉工具並移除此需求，請設定 [`"enableArtifact": false`](/docs/zh-TW/settings-reference#enableartifact) 或 [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/zh-TW/env-vars) |

250| `github.com` | 複製 GitHub 託管的[外掛程式市集](/docs/zh-TW/plugins/overview)和外掛程式，包括官方 Anthropic 市集，透過 HTTPS 或 SSH。若要僅透過 HTTPS 複製 GitHub `owner/repo` 來源，請設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars) |250| `github.com` | 複製 GitHub 託管的[外掛程式市集](/docs/zh-TW/plugins/overview)和外掛程式，包括官方 Anthropic 市集，透過 HTTPS 或 SSH。若要僅透過 HTTPS 複製 GitHub `owner/repo` 來源，請設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars) |

251| `raw.githubusercontent.com` | [`/release-notes`](/docs/zh-TW/commands) 的變更日誌摘要。在互動式工作階段中，Claude Code 也會在啟動時在背景擷取它，當其快取的變更日誌尚未涵蓋執行中的版本時，例如更新後的首次啟動；非互動式和雲端工作階段永遠不會擷取它 |251| `raw.githubusercontent.com` | [`/release-notes`](/docs/zh-TW/commands) 的變更日誌摘要。在互動式工作階段中，Claude Code 也會在啟動時在背景擷取它，當其快取的變更日誌尚未涵蓋執行中的版本時，例如更新後的首次啟動；非互動式和雲端工作階段永遠不會擷取它 |

252| `*-review.googlesource.com` | 在 `googlesource.com` 簽出上進行 Gerrit 變更查詢。當 Claude Desktop Code 索引標籤工作階段在[受信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)的簽出上啟動或繼續時，其 `origin` 是 `googlesource.com` 主機，Claude Code 會匿名詢問該主機的 `-review` 伺服器，以取得與 HEAD 的 `Change-Id` 相符的開啟變更，每次啟動或繼續一次。其他工作階段類型會略過查詢，且不會連線到其他 Gerrit 主機。選用：使用 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 停用 |252| `*-review.googlesource.com` | 在 `googlesource.com` 簽出上進行 Gerrit 變更查詢。當 Claude Desktop Code 索引標籤工作階段在[受信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)的簽出上啟動或繼續時，其 `origin` 是 `googlesource.com` 主機，Claude Code 會匿名詢問該主機的 `-review` 伺服器，以取得與 HEAD 的 `Change-Id` 相符的開啟變更，每次啟動或繼續一次。其他工作階段類型會略過查詢，且不會連線到其他 Gerrit 主機。選用：使用 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 停用 |

permission-modes.md +3 −3

Details

86| 您如何執行 Claude Code | 內建起始權限模式 |86| 您如何執行 Claude Code | 內建起始權限模式 |

87| :- | :- |87| :- | :- |

88| 任何設定檔將 `disableAutoMode` 設定為 `"disable"` | `default` |88| 任何設定檔將 `disableAutoMode` 設定為 `"disable"` | `default` |

~~89| `claude -p` 或 [Agent SDK](/docs/zh-TW/agent-sdk/permissions) | `default` |~~89| `claude -p` 或 [Agent SDK](/docs/zh-TW/agent-sdk/permissions#permission-modes) | 在[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中為 `default`。在不擷取的工作階段中，例如在第三方提供者上或關閉遙測的情況下，Claude Code v2.1.285 或更新版本上為 `auto`，較早版本上為 `default`。組織政策禁止 `auto` 預設的工作階段會改為以 `default` 啟動 |

90| 在終端或透過 [VS Code 擴充功能](/docs/zh-TW/vs-code) | Claude Code v2.1.283 或更新版本上的 `auto`；在較早的版本上，Pro、Max 或 Team 方案上的 `auto`（在[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中），否則為 `default` |90| 在終端或透過 [VS Code 擴充功能](/docs/zh-TW/vs-code) | Claude Code v2.1.283 或更新版本上的 `auto`；在較早的版本上，Pro、Max 或 Team 方案上的 `auto`（在[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中），否則為 `default` |

91 91

92在您[安裝或升級後的第一個工作階段](/docs/zh-TW/env-vars#first-session-after-an-install-or-upgrade)中，Claude Code 可以在其功能旗標到達之前選擇起始權限模式。該工作階段可能以不同的權限模式啟動，而不是表格給出的模式，您的下一個工作階段符合表格。92在您[安裝或升級後的第一個工作階段](/docs/zh-TW/env-vars#first-session-after-an-install-or-upgrade)中，Claude Code 可以在其功能旗標到達之前選擇起始權限模式。該工作階段可能以不同的權限模式啟動，而不是表格給出的模式，您的下一個工作階段符合表格。

98* 在終端中，一次，在工作階段頂部98* 在終端中，一次，在工作階段頂部

99* 在 VS Code 擴充功能中，作為新對話螢幕上的卡片，直到您關閉它99* 在 VS Code 擴充功能中，作為新對話螢幕上的卡片，直到您關閉它

100 100

101在 Pro、Max 和 Team 方案上，如果您的 `~/.claude/settings.json` 將 `defaultMode` 設定為 `auto` 以外的值，且沒有其他設定檔設定它，您的工作階段會繼續以該模式啟動。Claude Code 會在終端或 VS Code 擴充功能中詢問一次，是否將設定變更為自動模式。如果您拒絕，您的設定會保持原樣。101如果您的 `~/.claude/settings.json` 將 `defaultMode` 設定為 `auto` 以外的值，且沒有其他設定檔設定它，您的工作階段會繼續以該模式啟動。在 Pro、Max 和 Team 方案上，以及在[不擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中，Claude Code 會在終端或 VS Code 擴充功能中詢問一次，是否將設定變更為自動模式。如果您拒絕，您的設定會保持原樣。

102 102

103<h3 id="start-in-a-different-mode">103<h3 id="start-in-a-different-mode">

104 以不同的權限模式啟動104 以不同的權限模式啟動

322 Bedrock、Agent Platform 或 Foundry 上的自動模式322 Bedrock、Agent Platform 或 Foundry 上的自動模式

323</h3>323</h3>

324 324

325在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段上，自動模式預設可用。使用 Claude Code v2.1.283 或更新版本，它也是互動式終端和 [VS Code](/docs/zh-TW/vs-code) 工作階段的[內建起始權限模式](#which-mode-a-session-starts-in)。要自己選擇起始權限模式，請按照[以不同權限模式啟動](#start-in-a-different-mode)的描述設定 `permissions.defaultMode`，或從 VS Code 擴充功能的模式指示器中選擇權限模式。325在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段上，自動模式預設可用。當沒有其他設定權限模式時，它也是[內建起始權限模式](#which-mode-a-session-starts-in)，在該部分的表格列出的版本上。要自己選擇起始權限模式，請按照[以不同權限模式啟動](#start-in-a-different-mode)的描述設定 `permissions.defaultMode`，或從 VS Code 擴充功能的模式指示器中選擇權限模式。

326 326

327這些提供者上僅支援 Claude Sonnet 5 或更新版本、Opus 4.7 或更新版本和 Fable 模型。在任何其他模型上，工作階段改為以手動模式啟動。327這些提供者上僅支援 Claude Sonnet 5 或更新版本、Opus 4.7 或更新版本和 Fable 模型。在任何其他模型上，工作階段改為以手動模式啟動。

328 328

permissions.md +2 −2

Details

765| 設定檔案中的 [Hooks](/docs/zh-TW/hooks)、[`env`](/docs/zh-TW/settings-reference#env) 區塊和輔助命令（例如 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper)），以及專案技能的 [hooks](/docs/zh-TW/hooks#hooks-in-skills-and-agents) 和 [`allowed-tools`](/docs/zh-TW/skills#pre-approve-tools-for-a-skill) | 已使用 | 已使用。工作區信任在任何工作階段中都不會限制技能的 `allowed-tools` |765| 設定檔案中的 [Hooks](/docs/zh-TW/hooks)、[`env`](/docs/zh-TW/settings-reference#env) 區塊和輔助命令（例如 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper)），以及專案技能的 [hooks](/docs/zh-TW/hooks#hooks-in-skills-and-agents) 和 [`allowed-tools`](/docs/zh-TW/skills#pre-approve-tools-for-a-skill) | 已使用 | 已使用。工作區信任在任何工作階段中都不會限制技能的 `allowed-tools` |

766| `.claude/settings.json` 中的 `permissions.allow` 規則和 `additionalDirectories` | 在您接受信任對話框之前不使用，對話框會再次出現列出它們 | 不使用。Claude Code 會列印 [`this workspace has not been trusted`](/docs/zh-TW/errors#workspace-has-not-been-trusted) 警告到 stderr |766| `.claude/settings.json` 中的 `permissions.allow` 規則和 `additionalDirectories` | 在您接受信任對話框之前不使用，對話框會再次出現列出它們 | 不使用。Claude Code 會列印 [`this workspace has not been trusted`](/docs/zh-TW/errors#workspace-has-not-been-trusted) 警告到 stderr |

767| 專案 [subagent](/docs/zh-TW/sub-agents#hooks-in-subagent-frontmatter) 中的 frontmatter hooks、專案 [`@skills-dir` 外掛程式](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)，以及來自儲存庫或 `--add-dir` 目錄的 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目 | 不使用，不提供對話框 | 不使用 |767| 專案 [subagent](/docs/zh-TW/sub-agents#hooks-in-subagent-frontmatter) 中的 frontmatter hooks、專案 [`@skills-dir` 外掛程式](/docs/zh-TW/plugins/loading#plugins-shared-through-a-repository)，以及來自儲存庫或 `--add-dir` 目錄的 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目 | 不使用，不提供對話框 | 不使用 |

768| 來自儲存庫或 `--add-dir` 目錄的 subagent 的 frontmatter 中的內聯 [`mcpServers`](/docs/zh-TW/sub-agents#scope-mcp-servers-to-a-subagent)。在 v2.1.238 之前，Claude Code 在兩種情況下都載入這些伺服器 | 不使用，不提供對話框 | 不使用 |768| 來自儲存庫或 `--add-dir` 目錄的 subagent 的 frontmatter 中的內聯 [`mcpServers`](/docs/zh-TW/sub-agents#scope-mcp-servers-to-a-subagent) | 不使用，不提供對話框 | 不使用 |

769| `.mcp.json` 中的伺服器，包括儲存庫[在其自己的設定中批准的伺服器](/docs/zh-TW/mcp#project-server-approvals-and-workspace-trust) | Claude Code 在連接它們之前會詢問您。儲存庫自己的批准不計算 | 連接而不詢問，無論是否批准。SDK 只在 `settingSources` 包含專案設定時才載入它們。同一資料夾中的 `claude mcp list` 仍然將此類伺服器報告為待處理 |769| `.mcp.json` 中的伺服器，包括儲存庫[在其自己的設定中批准的伺服器](/docs/zh-TW/mcp#project-server-approvals-and-workspace-trust) | Claude Code 在連接它們之前會詢問您。儲存庫自己的批准不計算 | 連接而不詢問，無論是否批准。SDK 只在 `settingSources` 包含專案設定時才載入它們。同一資料夾中的 `claude mcp list` 仍然將此類伺服器報告為待處理 |

770| `.mcp.json` 中伺服器上的 [`headersHelper`](/docs/zh-TW/mcp#trust-a-folder-before-its-headershelper-runs)。在 v2.1.238 之前，Claude Code 在兩種情況下都執行輔助程式 | 在您接受信任對話框之前不執行，對話框會再次出現命名輔助程式的聲明位置。Claude Code 在此之前僅使用其靜態 `headers` 連接伺服器 | 不執行。Claude Code 使用其靜態 `headers` 連接伺服器，並為每個伺服器列印 [`headersHelper not run`](/docs/zh-TW/errors#headershelper-not-run) 行到 stderr |770| `.mcp.json` 中伺服器上的 [`headersHelper`](/docs/zh-TW/mcp#trust-a-folder-before-its-headershelper-runs) | 在您接受信任對話框之前不執行，對話框會再次出現命名輔助程式的聲明位置。Claude Code 在此之前僅使用其靜態 `headers` 連接伺服器 | 不執行。Claude Code 使用其靜態 `headers` 連接伺服器，並為每個伺服器列印 [`headersHelper not run`](/docs/zh-TW/errors#headershelper-not-run) 行到 stderr |

771 771

772對於需要此確切資料夾被信任的列，手動信任它：在 `~/.claude.json` 中設定 `projects["<path>"].hasTrustDialogAccepted` 為 `true`，其中 `<path>` 是儲存庫根目錄，或儲存庫外的資料夾本身。Claude Code 在跳過的 subagent hook 或內聯 MCP 伺服器的偵錯日誌行中列印確切的鍵，在跳過的允許規則的 stderr 警告中列印，以及在跳過的輔助程式的 `headersHelper not run` 行中列印。772對於需要此確切資料夾被信任的列，手動信任它：在 `~/.claude.json` 中設定 `projects["<path>"].hasTrustDialogAccepted` 為 `true`，其中 `<path>` 是儲存庫根目錄，或儲存庫外的資料夾本身。Claude Code 在跳過的 subagent hook 或內聯 MCP 伺服器的偵錯日誌行中列印確切的鍵，在跳過的允許規則的 stderr 警告中列印，以及在跳過的輔助程式的 `headersHelper not run` 行中列印。

773 773

plugins/cli-reference.md +38 −2

Details

29每個子命令共享這些結束代碼、plugin 引數和範圍值：29每個子命令共享這些結束代碼、plugin 引數和範圍值：

30 30

31* **結束代碼**：成功時為 `0`，失敗時為 `1`。`validate` 為非預期錯誤新增結束 `2`，`eval` 新增 [其部分](#plugin-eval) 中列出的代碼。31* **結束代碼**：成功時為 `0`，失敗時為 `1`。`validate` 為非預期錯誤新增結束 `2`，`eval` 新增 [其部分](#plugin-eval) 中列出的代碼。

~~32* **Plugin 引數**：`<plugin>` 引數是 plugin `name` 或 `name@marketplace`。當兩個市場提供相同名稱時，使用限定形式。~~32* **Plugin 引數**：`<plugin>` 引數是 plugin `name` 或 `name@marketplace`。當兩個市場提供相同名稱時，使用限定形式。`configure` 僅接受限定形式。

33* **範圍**：`--scope` 接受 `user`、`project` 或 `local`，並命名命令寫入的設定檔。`update` 也接受 `managed`。33* **範圍**：`--scope` 接受 `user`、`project` 或 `local`，並命名命令寫入的設定檔。`update` 也接受 `managed`。

34 34

35<h3 id="plugin-init">35<h3 id="plugin-init">

87| 旗標 | 說明 |87| 旗標 | 說明 |

88| :- | :- |88| :- | :- |

89| `-s, --scope <scope>` | 安裝範圍：`user`、`project` 或 `local`。預設為 `user` |89| `-s, --scope <scope>` | 安裝範圍：`user`、`project` 或 `local`。預設為 `user` |

90| `--config <key=value>` | 設定 plugin 的 manifest 宣告的 [`userConfig`](/docs/zh-TW/plugins/manifest-reference) 選項。為每個選項重複旗標。需要 Claude Code v2.1.147 或更新版本 |90| `--config <key=value>` | 設定 plugin 的 manifest 宣告的 [`userConfig`](/docs/zh-TW/plugins/manifest-reference) 選項。為每個選項重複旗標。需要 Claude Code v2.1.147 或更新版本。寫成 `<server>.<key>` 的金鑰設定 [bundled MCP server](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server) 在其自己的 `user_config` 中宣告的設定，用於 plugin 內附帶的 bundle 檔案。`<server>.<key>` 形式需要 Claude Code v2.1.285 或更新版本 |

91| `-y, --yes` | 接受顯示的安裝命令，無需 `Run this command now?` 提示。當命令在 Claude Code 工作階段內執行時（例如從 Bash 工具或 hook）被忽略。需要 Claude Code v2.1.229 或更新版本 |91| `-y, --yes` | 接受顯示的安裝命令，無需 `Run this command now?` 提示。當命令在 Claude Code 工作階段內執行時（例如從 Bash 工具或 hook）被忽略。需要 Claude Code v2.1.229 或更新版本 |

92| `--accept-command <sha256>` | 接受顯示的安裝命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result) 在 `shownCommand` 中報告，代替 `-y`。無法與 `-y` 結合。請參閱 [接受顯示的安裝命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更新版本 |92| `--accept-command <sha256>` | 接受顯示的安裝命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result) 在 `shownCommand` 中報告，代替 `-y`。無法與 `-y` 結合。請參閱 [接受顯示的安裝命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更新版本 |

93| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，而不是人類可讀的訊息，供指令碼使用。請參閱 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更新版本 |93| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，而不是人類可讀的訊息，供指令碼使用。請參閱 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更新版本 |

297| :- | :- |297| :- | :- |

300| `--data-size [plugin]` | 測量每個已安裝 plugin 的 [saved data directory](#what-an-uninstall-deletes-and-keeps)，或僅測量命名 plugin 的，以 `name@marketplace` 形式給出。沒有 `--json` 時無效。如果名稱沒有安裝記錄，命令列印 `--data-size names a plugin that is not installed` 並結束 `1`，而不是列印列表。需要 Claude Code v2.1.285 或更新版本 |

300 301

301Claude Code 按每個 plugin 的載入方式對人類可讀的輸出進行分組：302Claude Code 按每個 plugin 的載入方式對人類可讀的輸出進行分組：

302 303

332| `hasUserConfig` | boolean | 當 plugin 已載入且其 manifest 宣告 [`userConfig` 選項](/docs/zh-TW/plugins/manifest-reference#user-configuration) 時存在且為 `true`。對於無法載入的 plugin 不存在，無論其 manifest 宣告什麼。保存的值永遠不包括。需要 Claude Code v2.1.285 或更新版本 |

333| `projectEnabled` | boolean | 專案的共享 `.claude/settings.json` 是否開啟 plugin。僅市場安裝。需要 Claude Code v2.1.285 或更新版本 |

334| `dataDirSize` | object | 使用 `--data-size`，plugin 的 [saved data directory](#what-an-uninstall-deletes-and-keeps) 的大小為 `bytes` 和 `human`；當目錄遺漏或空白時不存在。僅市場安裝。需要 Claude Code v2.1.285 或更新版本 |

335| `dataDirUnreadable` | boolean | 使用 `--data-size`，當保存的資料目錄存在但無法測量時為 `true`。僅市場安裝。需要 Claude Code v2.1.285 或更新版本 |

331 336

332使用 `--json --available`，Claude Code 列印一個物件而不是陣列。其 `installed` 欄位保存已安裝 plugin 物件的陣列，其 `available` 欄位保存每個未安裝市場 plugin 的一個物件，欄位如下。337使用 `--json --available`，Claude Code 列印一個物件而不是陣列。其 `installed` 欄位保存已安裝 plugin 物件的陣列，其 `available` 欄位保存每個未安裝市場 plugin 的一個物件，欄位如下。

333 338

371 376

372對於未載入的 plugin，Claude Code 列印 ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.`` 並結束 `1`。377對於未載入的 plugin，Claude Code 列印 ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.`` 並結束 `1`。

373 378

379<h3 id="plugin-configure">

380 plugin configure

381</h3>

382

383顯示已安裝 plugin 的 [`userConfig`](/docs/zh-TW/plugins/manifest-reference#user-configuration) 選項及其設定的選項，或儲存在 stdin 上傳入的值。需要 Claude Code v2.1.285 或更新版本。

384

385```bash theme={null}

386claude plugin configure <plugin>

387```

388

389| 旗標 | 說明 |

390| :- | :- |

391| `--values-stdin` | 從 stdin 讀取選項值作為單行字串的 JSON 物件並儲存它們。您遺漏的選項保留其儲存的值 |

392| `--json` | 將結果列印為 stdout 上的一個 JSON 物件。不使用 `--values-stdin`，物件帶有選項的 `schema` 和 `choices`、其起始 `inputs` 以及 `configured` 和 `unconfigured` 選項名稱。使用 `--values-stdin`，它帶有 `saved` 選項名稱，以及當它們可以被讀回時，`unconfigured` 選項名稱 |

393

394不使用旗標，命令列出每個選項，最多三個標籤：`required` 或 `optional`，然後 `sensitive` 用於 manifest 宣告為敏感的選項，然後 `set` 或 `not set`。它列印沒有儲存的值。使用 `--json`，輸出包括不敏感選項的儲存值，永遠不包括敏感選項的文字。

395

396若要儲存值，將它們寫入檔案作為將選項金鑰對應到字串值的 JSON 物件，然後在 stdin 上傳遞檔案。將 `formatter@my-marketplace` 替換為您自己的 plugin 的 id，如 `claude plugin list` 所示。此範例從包含 `{"api_url": "https://example.com"}` 的檔案 `values.json` 設定一個名為 `api_url` 的選項：

397

398```bash theme={null}

399claude plugin configure formatter@my-marketplace --values-stdin < values.json

400```

401

402Claude Code 根據選項的宣告類型驗證每個值，並列印 `Configuration saved. Restart Claude Code to apply it.` 如果您傳遞 manifest 未宣告的金鑰，或驗證失敗的值，命令不儲存任何內容，列印 `Failed to save configuration:` 加上原因，並結束 `1`。使用 `--json`，被拒絕的值也列印 stdout 上的物件，其 `refused` 欄位帶有 `message`，以及當一個選項有問題時，其 `option` 金鑰。

403

404傳遞 plugin 的完整 `name@marketplace` id，如 `claude plugin list` 所示。`configure` 不接受裸 `name`。當沒有已載入的 plugin 有該 id 時，命令列印 `No installed plugin has the id "<plugin>".` 並結束 `1`。

405

406對於 bundled MCP server 的設定，請參閱 [`plugin install --config`](#plugin-install) 或 `/plugin` 中的 **Configure** 項目。

407

374<h3 id="plugin-prune">408<h3 id="plugin-prune">

375 plugin prune409 plugin prune

376</h3>410</h3>

469claude plugin eval init [name] [options]503claude plugin eval init [name] [options]

470```504```

471 505

506從 plugin 的根資料夾執行命令，保存 `.claude-plugin/plugin.json` 或 skill 的 `SKILL.md` 的目錄。若要有意在另一個目錄中建立架構套件，傳遞 `--eval-dir`。

507

472在終端中，命令開啟互動式 Claude Code 工作階段以進行編寫訪談。在訪談中，Claude 執行以下操作：508在終端中，命令開啟互動式 Claude Code 工作階段以進行編寫訪談。在訪談中，Claude 執行以下操作：

473 509

4741. 讀取 plugin5101. 讀取 plugin

plugins/components.md +13 −2

Details

868 868

869伺服器從捆綁的 manifest 中的 `name` 獲取其名稱。869伺服器從捆綁的 manifest 中的 `name` 獲取其名稱。

870 870

871捆綁的 manifest 可以在 `user_config` 區塊中宣告伺服器需要的設定。具有沒有已儲存值的必需設定的捆綁伺服器不會啟動。`/plugin` **Errors** 標籤顯示 `Bundled MCP server "<name>" was not started: it needs configuration`。

872

873使用者可以透過以下兩種方式之一提供值：

874

875* **在 `/plugin` 中**：在 **Installed** 標籤上選擇外掛程式並選擇 **Configure**

876* **在安裝時，從 shell**：傳遞 [`--config <server>.<key>=<value>`](/docs/zh-TW/plugins/cli-reference#plugin-install) 至 `claude plugin install`。需要 Claude Code v2.1.285 或更新版本，且僅適用於外掛程式內打包的捆綁。

877

871如需傳輸和驗證，請參閱 [MCP](/docs/zh-TW/mcp#plugin-provided-mcp-servers)。878如需傳輸和驗證，請參閱 [MCP](/docs/zh-TW/mcp#plugin-provided-mcp-servers)。

872 879

873<h3 id="lsp-servers">880<h3 id="lsp-servers">

1071 設定對話方塊何時出現1078 設定對話方塊何時出現

1072</h3>1079</h3>

1073 1080

1074對話方塊僅在互動式 `/plugin` 介面中出現。當使用者執行以下任何操作時，它會為任何尚未設定的選項開啟：1081對話方塊是互動式 `/plugin` 介面的一部分。當使用者執行以下任何操作時，它會為任何尚未設定的選項開啟：

1075 1082

1076* 在 `/plugin` 中安裝外掛程式1083* 在 `/plugin` 中安裝外掛程式

1077* 在工作階段內執行 `/plugin install <plugin>@<marketplace>`1084* 在工作階段內執行 `/plugin install <plugin>@<marketplace>`

1079 1086

1080若要在任何時間開啟相同的對話方塊，使用者執行 `/plugin configure <plugin>@<marketplace>`。1087若要在任何時間開啟相同的對話方塊，使用者執行 `/plugin configure <plugin>@<marketplace>`。

1081 1088

1082`claude plugin install` shell 命令從不提示 `userConfig` 值。若要從 shell 設定值，將每個值作為 `--config KEY=VALUE` 傳遞。當選項保持未設定時，命令列印 `userConfig options not yet set` 行，命名兩種設定方式。[`userConfig` 對話方塊從不出現](/docs/zh-TW/plugins/troubleshooting#the-userconfig-dialog-never-appears) 引用該行。1089VS Code 擴充功能的 [管理外掛程式對話方塊](/docs/zh-TW/vs-code#install-plugins) 在安裝後會以表單形式要求未設定的選項，外掛程式列上的齒輪圖示會再次開啟表單，顯示每個選項。

1090

1091`claude plugin install` shell 命令從不提示 `userConfig` 值。若要從 shell 設定值，在安裝時將每個值作為 `--config KEY=VALUE` 傳遞，或之後將 JSON 物件管道傳輸到 [`claude plugin configure --values-stdin`](/docs/zh-TW/plugins/cli-reference#plugin-configure)。

1092

1093當選項保持未設定時，`claude plugin install` 列印 `userConfig options not yet set` 行。如需該行的確切文字，請參閱 [The `userConfig` 對話方塊從不出現](/docs/zh-TW/plugins/troubleshooting#the-userconfig-dialog-never-appears)。

1083 1094

1084如需選項欄位、每個值儲存的位置、元件如何參考已儲存的值以及哪些欄位拒絕 `${user_config.*}`，請參閱 [使用者設定](/docs/zh-TW/plugins/manifest-reference#user-configuration)。1095如需選項欄位、每個值儲存的位置、元件如何參考已儲存的值以及哪些欄位拒絕 `${user_config.*}`，請參閱 [使用者設定](/docs/zh-TW/plugins/manifest-reference#user-configuration)。

1085 1096

plugins/install.md +8 −2

Details

72 摘要的最後一句告訴您外掛程式在此工作階段中是否可用：72 摘要的最後一句告訴您外掛程式在此工作階段中是否可用：

73 73

74 * **Active now**：`Plugin is now active.` 不需要重新載入。74 * **Active now**：`Plugin is now active.` 不需要重新載入。

75 * **Active, but a server needs setup**：`Plugin is now active.` 後面跟著 `Its bundled MCP server needs configuration before it can start`。外掛程式的 [bundled MCP server](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server) 在您設定其選項之前無法啟動。在 `/plugin` 的 **Installed** 標籤上選擇外掛程式，然後選擇 **Configure** 以設定伺服器的選項。

75 * **Reload needed**：`Run /reload-plugins to activate.` 面板關閉，Claude Code 為您執行該重新載入。如果重新載入會 [使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，它會警告並改為保留外掛程式待處理。執行 `/reload-plugins --force` 以無論如何啟動它，這會花費一個未快取的請求。76 * **Reload needed**：`Run /reload-plugins to activate.` 面板關閉，Claude Code 為您執行該重新載入。如果重新載入會 [使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，它會警告並改為保留外掛程式待處理。執行 `/reload-plugins --force` 以無論如何啟動它，這會花費一個未快取的請求。

76 * **Load failed**：`The plugin couldn't be loaded`。在 `/plugin` 中開啟 **Errors** 標籤以了解原因，然後請參閱 [安裝後：外掛程式無法運作](/docs/zh-TW/plugins/troubleshooting#plugin-installed-but-not-working)。77 * **Load failed**：`The plugin couldn't be loaded`。在 `/plugin` 中開啟 **Errors** 標籤以了解原因，然後請參閱 [安裝後：外掛程式無法運作](/docs/zh-TW/plugins/troubleshooting#plugin-installed-but-not-working)。

77 </Step>78 </Step>

248私人市集是您需要認證才能複製的儲存庫中的市集，在 GitHub 或任何其他 git 主機上。您使用與公開市集相同的 `/plugin marketplace add` 或 `claude plugin marketplace add` 命令新增它。Claude Code 使用機器上已有的 git 認證複製它，永遠不會提示，因此每種連接方式都有要求：249私人市集是您需要認證才能複製的儲存庫中的市集，在 GitHub 或任何其他 git 主機上。您使用與公開市集相同的 `/plugin marketplace add` 或 `claude plugin marketplace add` 命令新增它。Claude Code 使用機器上已有的 git 認證複製它，永遠不會提示，因此每種連接方式都有要求：

249 250

250* **HTTPS**：您的 git 認證助手適用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 設定的存取有效。互動式提示被抑制，因此您從未驗證過的主機會失敗而不是要求密碼。251* **HTTPS**：您的 git 認證助手適用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 設定的存取有效。互動式提示被抑制，因此您從未驗證過的主機會失敗而不是要求密碼。

251* **SSH**：主機必須已在您的 `known_hosts` 檔案中，金鑰必須在沒有密碼提示的情況下工作，因為主機指紋和密碼提示也被抑制。252* **SSH**：主機必須已在您的 `known_hosts` 檔案中，金鑰必須在沒有密碼提示的情況下工作。如果您的 git 設定在 `GIT_SSH_COMMAND`、`GIT_SSH` 或您的 git 設定的 `core.sshCommand` 中命名 SSH 程式，Claude Code 會執行該程式。

252* **GitHub `owner/repo` shorthand**：Claude Code 檢查您的 SSH 金鑰是否驗證到 `github.com`，如果驗證則透過 SSH 複製，如果不驗證則透過 HTTPS 複製。設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars#variables) 以跳過該檢查並始終透過 HTTPS 複製。253* **GitHub `owner/repo` shorthand**：Claude Code 檢查您的 SSH 金鑰是否驗證到 `github.com`，如果驗證則透過 SSH 複製，如果不驗證則透過 HTTPS 複製。設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars#variables) 以跳過該檢查並始終透過 HTTPS 複製。

253 254

254當您執行 `/plugin install`、`/plugin marketplace update` 和 `claude plugin update` 時，相同的認證適用。255當您執行 `/plugin install`、`/plugin marketplace update` 和 `claude plugin update` 時，相同的認證適用。

288 289

289* 輸入以按名稱或描述篩選。290* 輸入以按名稱或描述篩選。

290* 按 **Space** 啟用或停用選定的外掛程式，按 **f** 將其加入最愛。291* 按 **Space** 啟用或停用選定的外掛程式，按 **f** 將其加入最愛。

291* 按 **Enter** 開啟外掛程式的詳細資訊。那裡的選單提供 **Disable plugin** 或 **Enable plugin**、**Update now** 和 **Uninstall**。採用設定的外掛程式也提供 **Configure options**。292* 按 **Enter** 開啟外掛程式的詳細資訊。

293

294外掛程式的詳細資訊功能表提供 **Disable plugin** 或 **Enable plugin**、**Update now** 和 **Uninstall**。採用設定的外掛程式會出現兩個額外項目，外掛程式可以同時顯示兩者：

295

296* **Configure options**：當外掛程式的資訊清單宣告 [`userConfig` 選項](/docs/zh-TW/plugins/manifest-reference#user-configuration) 時顯示。開啟這些選項的對話框

297* **Configure**：當外掛程式包含 [封裝的 MCP 伺服器](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server) 時顯示。設定該伺服器自己的 `user_config` 設定

292 298

293標籤也可以在 **Managed** 範圍顯示外掛程式。您的組織透過 [受管設定](/docs/zh-TW/settings#settings-files) 安裝了這些，您無法在此啟用、停用或卸載它們。299標籤也可以在 **Managed** 範圍顯示外掛程式。您的組織透過 [受管設定](/docs/zh-TW/settings#settings-files) 安裝了這些，您無法在此啟用、停用或卸載它們。

294 300

plugins/troubleshooting.md +40 −2

Details

201 201

202成功的新增會列印 `Successfully added marketplace: <name>`。202成功的新增會列印 `Successfully added marketplace: <name>`。

203 203

204<h3 id="invalid-git-url">

205 `Invalid git URL`

206</h3>

207

208您新增了市集、安裝了外掛程式，或從 git 位址執行了更新，命令失敗，訊息中顯示 `Invalid git URL`。

209

210Claude Code 在執行 git 之前檢查每個 git 位址。它拒絕其協議不支援的位址。它也拒絕 git 可能讀取為命名不同伺服器或資料夾的位址，而不是位址顯示的位址。

211

212位址後面的文字命名要變更的內容。按照訊息所說重寫位址並再次執行命令。

213

214改為說 `is blocked by enterprise policy` 的拒絕來自您組織的設定。請參閱 [市集來源被企業政策阻止](#marketplace-source-is-blocked-by-enterprise-policy)。

215

204<h3 id="path-does-not-exist">216<h3 id="path-does-not-exist">

205 `Path does not exist: <path>`217 `Path does not exist: <path>`

206</h3>218</h3>

410 422

411`claude plugin install` 在您的 shell 中列印不同的訊息。對於已在目標範圍安裝的外掛程式，它列印 `Plugin "<name>@<marketplace>" is already installed (scope: user)` 並以退出代碼 0 退出。如果其快取目錄遺失，相同的命令會重新下載它。423`claude plugin install` 在您的 shell 中列印不同的訊息。對於已在目標範圍安裝的外掛程式，它列印 `Plugin "<name>@<marketplace>" is already installed (scope: user)` 並以退出代碼 0 退出。如果其快取目錄遺失，相同的命令會重新下載它。

412 424

425<h3 id="plugin-would-share-its-folder">

426 `"<plugin>" was not installed: it would share its folder with "<other>"`

427</h3>

428

429您透過 `claude plugin install`、`/plugin` 或工作階段中的安裝建議安裝了外掛程式，Claude Code 拒絕了它，並顯示此行或 `would share its saved data with`。

430

431被拒絕的外掛程式的 id 和已安裝的外掛程式的 id 對應到磁碟上的相同資料夾：一旦 `.` 和 `@` 被寫成 `-`，它們就是相同的。在 macOS 和 Windows 上，僅在大寫字母中不同的 id 也對應到相同的資料夾。安裝兩者會將一個外掛程式的檔案放在另一個的資料夾中，因此 Claude Code 拒絕，已安裝的外掛程式保留其檔案。

432

433訊息命名了解決方案：

434

435* **其他外掛程式已安裝**：訊息說 `Only one of the two can be installed.` 並命名 `claude plugin uninstall` 命令或 `/plugin` 中的卸載步驟，以移除其他外掛程式。執行它，然後再次安裝。對於卸載移除的內容，請參閱 [卸載刪除和保留的內容](/docs/zh-TW/plugins/cli-reference#what-an-uninstall-deletes-and-keeps)。

436* **兩個 id 在一次安裝中到達**，例如外掛程式及其需要的依賴項：沒有安裝順序可以幫助。只有列出這兩個外掛程式的市集的維護者可以修復它，方法是重新命名其中一個。當兩者來自不同的市集時，任一個的維護者都可以。

437

413<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">438<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">

414 `This plugin uses a source type your Claude Code version does not support`439 `This plugin uses a source type your Claude Code version does not support`

415</h3>440</h3>

790* **`URL is unset or invalid`**：URL 使用的 `${user_config.*}` 選項未設定。執行 `/plugin configure <plugin>` 以設定它815* **`URL is unset or invalid`**：URL 使用的 `${user_config.*}` 選項未設定。執行 `/plugin configure <plugin>` 以設定它

791* **`has an invalid MCP url`** 或 **`headersHelper for MCP server '<server>' references ${user_config.*}`**：外掛程式自己的配置有問題。修復您外掛程式的 MCP 配置中的 `url` 或 `headersHelper`，或如果外掛程式不是您的，向外掛程式的作者報告。`headersHelper` 情況在 [外掛程式命令參考 user\_config](/docs/zh-TW/errors#plugin-command-references-user-config) 下有自己的條目816* **`has an invalid MCP url`** 或 **`headersHelper for MCP server '<server>' references ${user_config.*}`**：外掛程式自己的配置有問題。修復您外掛程式的 MCP 配置中的 `url` 或 `headersHelper`，或如果外掛程式不是您的，向外掛程式的作者報告。`headersHelper` 情況在 [外掛程式命令參考 user\_config](/docs/zh-TW/errors#plugin-command-references-user-config) 下有自己的條目

792 817

818<h4 id="bundled-mcp-server-name-was-not-started-it-needs-configuration">

819 `Bundled MCP server "<name>" was not started: it needs configuration`

820</h4>

821

822外掛程式包括伺服器作為 [MCPB 套件](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server)，宣告 `user_config`，且必需的設定沒有已保存的值或已保存的值無法通過套件自己的驗證，因此 Claude Code 跳過啟動伺服器。外掛程式的其餘部分有效。

823

824在 `/plugin` 的 **Installed** 標籤上選擇外掛程式，並選擇 **Configure** 以提供值。保存後，`/plugin` 顯示 `Configuration saved.` 並關閉，Claude Code 重新載入外掛程式，如 [管理已安裝的外掛程式](/docs/zh-TW/plugins/install#manage-installed-plugins) 下所述。伺服器在該重新載入應用後啟動。在 v2.1.285 之前，Claude Code 跳過伺服器而不顯示此行。

825

793<h4 id="server-is-configured-but-never-connects">826<h4 id="server-is-configured-but-never-connects">

794 Server is configured but never connects827 Server is configured but never connects

795</h4>828</h4>

934 967

935您的外掛程式宣告 `userConfig` 選項，但安裝時不會出現設定對話框。968您的外掛程式宣告 `userConfig` 選項，但安裝時不會出現設定對話框。

936 969

937互動式安裝會顯示對話框，而 shell 命令改為將值作為旗標：970安裝是否要求這些值取決於您在何處執行它：

938 971

939* **在工作階段中的 `/plugin install`，或 `/plugin` 中的 Discover 標籤**：對話框是此互動式安裝的一部分972* **在工作階段中的 `/plugin install`，或 `/plugin` 中的 Discover 標籤**：對話框是此互動式安裝的一部分

973* **VS Code 擴充功能的管理外掛程式對話框**：在安裝後以表單形式要求未設定的選項。在 v2.1.285 之前，在該處安裝不會顯示選項表單，因此請使用 `/plugin configure <plugin>@<marketplace>` 從終端機工作階段設定值

940* **在您的 shell 中的 `claude plugin install`**：永遠不會提示 `userConfig` 值。它會儲存您傳遞的任何 `--config KEY=VALUE` 值，當選項保持未設定時，它會列印 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` 當任何未設定的選項是必需的時，`(M required)` 跟隨 `not yet set`。974* **在您的 shell 中的 `claude plugin install`**：永遠不會提示 `userConfig` 值。它會儲存您傳遞的任何 `--config KEY=VALUE` 值，當選項保持未設定時，它會列印 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` 當任何未設定的選項是必需的時，`(M required)` 跟隨 `not yet set`。

941 975

942如果您從 shell 安裝，請使用 `--config` 傳遞值，每個選項一個旗標：976如果您從 shell 安裝，請使用 `--config` 傳遞值，每個選項一個旗標：

945claude plugin install my-plugin@my-marketplace --config api_url=https://example.com979claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

946```980```

947 981

948當每個選項都設定時，安裝輸出不會包含 `not yet set` 行。若要之後改為開啟對話框，請在工作階段中執行 `/plugin configure my-plugin@my-marketplace`。982當每個選項都設定時，安裝輸出不會包含 `not yet set` 行。

983

984若要之後改為開啟對話框，請在工作階段中執行 `/plugin configure my-plugin@my-marketplace`。從 shell，[`claude plugin configure`](/docs/zh-TW/plugins/cli-reference#plugin-configure) 顯示哪些選項仍未設定，並儲存在 stdin 上管道傳入的值。它需要 Claude Code v2.1.285 或更新版本。

949 985

950如果您傳遞資訊清單未宣告的 `--config` 鍵，外掛程式仍會安裝，命令會列印 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` 後面跟著外掛程式確實宣告的鍵。986如果您傳遞資訊清單未宣告的 `--config` 鍵，外掛程式仍會安裝，命令會列印 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` 後面跟著外掛程式確實宣告的鍵。

951 987

988對於運送[MCPB 套件檔案](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server)的外掛程式，該檔案宣告其自身的 `user_config`，訊息改為讀取 `isn't declared in this plugin's userConfig or by its bundled MCP servers.`，已知的鍵包括該伺服器的鍵，寫成 `<server>.<key>`。資訊清單按 URL 參考的套件在安裝時不會被讀取，因此其鍵不會被列出，訊息會說在 `/plugin` 中設定它。設定 `<server>.<key>` 鍵需要 Claude Code v2.1.285 或更新版本。

989

952<h3 id="claude-plugin-validate-reports-errors">990<h3 id="claude-plugin-validate-reports-errors">

953 `claude plugin validate` 報告錯誤991 `claude plugin validate` 報告錯誤

954</h3>992</h3>

scheduled-tasks.md +1 −1

Details

84<span id="loop-provider-differences" />84<span id="loop-provider-differences" />

85 85

86<Note>86<Note>

87 動態選擇的間隔和[內建維護提示](#run-the-built-in-maintenance-prompt)在每個提供者上都有效，並且[功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)已關閉。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，或擷取已關閉時，兩者都需要 Claude Code v2.1.248 或更新版本。在這些情況下，在較早版本上，沒有間隔的提示會在固定的 10 分鐘排程上執行，沒有提示的 `/loop` 會列印使用訊息。87 動態選擇的間隔和[內建維護提示](#run-the-built-in-maintenance-prompt)在每個提供者上都有效，並且[功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)已關閉。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，或擷取已關閉時，兩者都需要 Claude Code v2.1.248 或更新版本。

88</Note>88</Note>

89 89

90<h3 id="run-the-built-in-maintenance-prompt">90<h3 id="run-the-built-in-maintenance-prompt">

self-hosted-environments.md +1 −1

Details

87執行器一次為一個擁有者服務。執行器認領的第一個工作階段將執行器鎖定到該工作階段的擁有者，執行器隨後只為該擁有者執行工作階段，達到設定的容量。擁有者是誰取決於工作階段如何啟動：87執行器一次為一個擁有者服務。執行器認領的第一個工作階段將執行器鎖定到該工作階段的擁有者，執行器隨後只為該擁有者執行工作階段，達到設定的容量。擁有者是誰取決於工作階段如何啟動：

88 88

89* **使用者啟動的工作階段**：擁有者是該使用者的帳戶。89* **使用者啟動的工作階段**：擁有者是該使用者的帳戶。

90* **Claude Tag 頻道工作階段**：Claude 執行它們時沒有附加使用者帳戶，因此擁有者是啟動工作階段的 [Claude Tag 代理](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity)。該代理啟動的每個頻道工作階段都有相同的擁有者，無論誰發送了 Slack 訊息，因此當您以 `--capacity` 大於 1 或正 `--drain-grace-sec` 執行它時，鎖定到它的執行器為不同人員啟動的工作階段服務。鎖定到使用者的執行器永遠不會認領這些，鎖定到 Claude Tag 代理的執行器永遠不會認領使用者的工作階段。90* **Claude Tag 頻道工作階段**：Claude 執行它們時沒有附加使用者帳戶，因此擁有者是啟動工作階段的 [Claude Tag 代理](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity)。該代理啟動的每個頻道工作階段都有相同的擁有者，無論誰發送了 Slack 訊息，因此當您以 `--capacity` 大於 1 或正 `--drain-grace-sec` 執行它時，鎖定到它的執行器為不同人員啟動的工作階段服務。

91 91

92因此，最小艦隊大小是您預期同時活躍的擁有者數量，計算使用者和 Claude Tag 代理。92因此，最小艦隊大小是您預期同時活躍的擁有者數量，計算使用者和 Claude Tag 代理。

93 93

server-managed-settings.md +2 −1

Details

163 跨受管來源的個別金鑰例外163 跨受管來源的個別金鑰例外

164</h3>164</h3>

165 165

166三種金鑰是無合併規則的例外：166這些金鑰是無合併規則的例外：

167 167

168* **跨來源鎖定金鑰**：一小組金鑰，例如沙箱允許清單鎖定，[列在受管設定頁面上](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)。當任何管理員控制的受管來源設定它們時，Claude Code 會遵守它們；使用者可寫入的 HKCU 登錄層級被排除。168* **跨來源鎖定金鑰**：一小組金鑰，例如沙箱允許清單鎖定，[列在受管設定頁面上](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)。當任何管理員控制的受管來源設定它們時，Claude Code 會遵守它們；使用者可寫入的 HKCU 登錄層級被排除。

169 169

171* **`env` 區塊**：除了與認證金鑰配對的遙測單位和路由變數（下面涵蓋）外，它會跨管理員控制的來源按金鑰合併。對於每個環境變數，定義它的最高優先順序來源會獲勝，較低的管理員來源會填入較高來源未設定的變數。因此，端點管理的 `env` 項目會在伺服器管理的設定未設定該變數時套用，或在快取的伺服器值[等待伺服器確認時被保留](#fetch-and-caching-behavior)時套用。需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，Claude Code 僅套用選定來源的整個 `env` 區塊。171* **`env` 區塊**：除了與認證金鑰配對的遙測單位和路由變數（下面涵蓋）外，它會跨管理員控制的來源按金鑰合併。對於每個環境變數，定義它的最高優先順序來源會獲勝，較低的管理員來源會填入較高來源未設定的變數。因此，端點管理的 `env` 項目會在伺服器管理的設定未設定該變數時套用，或在快取的伺服器值[等待伺服器確認時被保留](#fetch-and-caching-behavior)時套用。需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，Claude Code 僅套用選定來源的整個 `env` 區塊。

172 * **遙測單位**：`OTEL_EXPORTER_OTLP_*` 匯出器金鑰、`OTEL_LOG_*` 內容擷取切換、`OTEL_LOGS_EXPORTER` 以及測試版追蹤變數 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT` 遵循設定任何這些變數的最高來源作為一個單位。傳遞 `otelHeadersHelper` 認證金鑰的來源也會聲稱該單位，但僅在它是選定來源時才會放置這些變數：未被選定但傳遞該金鑰的來源不會貢獻其中任何一個，仍然會阻止較低來源填入它們。無論哪種方式，來自一個來源的匯出器端點永遠無法與來自另一個來源的認證配對。172 * **遙測單位**：`OTEL_EXPORTER_OTLP_*` 匯出器金鑰、`OTEL_LOG_*` 內容擷取切換、`OTEL_LOGS_EXPORTER` 以及測試版追蹤變數 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT` 遵循設定任何這些變數的最高來源作為一個單位。傳遞 `otelHeadersHelper` 認證金鑰的來源也會聲稱該單位，但僅在它是選定來源時才會放置這些變數：未被選定但傳遞該金鑰的來源不會貢獻其中任何一個，仍然會阻止較低來源填入它們。無論哪種方式，來自一個來源的匯出器端點永遠無法與來自另一個來源的認證配對。

173 * **認證配對的路由**：將路由變數與選定來源專用認證金鑰（例如 `apiKeyHelper` 或 `otelHeadersHelper`）配對的來源，僅在它贏得該位置時才會貢獻這些路由變數。173 * **認證配對的路由**：將路由變數與選定來源專用認證金鑰（例如 `apiKeyHelper` 或 `otelHeadersHelper`）配對的來源，僅在它贏得該位置時才會貢獻這些路由變數。

174* **`allowedProviders`**：在機器上設定的清單和伺服器管理的清單會按照[其項目的 Scope 備註](/docs/zh-TW/settings-reference#allowedproviders)所述進行合併。需要 Claude Code v2.1.285 或更新版本

174* **閘道登入金鑰**：Claude Code 永遠不會從伺服器管理的設定讀取 [`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-TW/settings-reference#gatewayinternalnetworks) 或 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 的 `"gateway"` 值，因此伺服器管理的設定中的值既不會套用，也不會隱藏在 MDM 原則或受管設定檔中設定的值。[`managedSourcesBehavior` 項目](/docs/zh-TW/settings-reference#managedsourcesbehavior)說明機器上的哪個管理員來源提供它們。175* **閘道登入金鑰**：Claude Code 永遠不會從伺服器管理的設定讀取 [`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-TW/settings-reference#gatewayinternalnetworks) 或 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 的 `"gateway"` 值，因此伺服器管理的設定中的值既不會套用，也不會隱藏在 MDM 原則或受管設定檔中設定的值。[`managedSourcesBehavior` 項目](/docs/zh-TW/settings-reference#managedsourcesbehavior)說明機器上的哪個管理員來源提供它們。

175 176

176<h3 id="fetch-and-caching-behavior">177<h3 id="fetch-and-caching-behavior">

sessions.md +20 −2

Details

29 29

30`claude --continue` 會開啟已完成的[背景 session](/docs/zh-TW/agent-view)，但不會開啟仍在執行的 session；開啟已完成的背景 sessions 需要 Claude Code v2.1.257 或更新版本。如果您最近的對話是您[移到背景](/docs/zh-TW/agent-view#send-the-session-to-the-background)的對話，且它仍在那裡執行，Claude Code 會以 `Your most recent conversation is running in the background` 和該 session 的 ID 退出。從 [`claude agents`](/docs/zh-TW/agent-view#attach-to-a-session) 附加到 session，或執行 `claude --resume` 以選擇另一個。30`claude --continue` 會開啟已完成的[背景 session](/docs/zh-TW/agent-view)，但不會開啟仍在執行的 session；開啟已完成的背景 sessions 需要 Claude Code v2.1.257 或更新版本。如果您最近的對話是您[移到背景](/docs/zh-TW/agent-view#send-the-session-to-the-background)的對話，且它仍在那裡執行，Claude Code 會以 `Your most recent conversation is running in the background` 和該 session 的 ID 退出。從 [`claude agents`](/docs/zh-TW/agent-view#attach-to-a-session) 附加到 session，或執行 `claude --resume` 以選擇另一個。

31 31

32<span id="resume-a-running-background-session" />

34當您使用 `claude --resume` 或 `/resume` 恢復的對話屬於仍在執行的[背景 session](/docs/zh-TW/agent-view) 時，Claude Code 會開啟執行中的 session 本身。在命令列上使用 `--bg` 時，恢復是[背景分派](/docs/zh-TW/agent-view#from-your-shell)。在 v2.1.285 之前，Claude Code 會拒絕並告訴您使用 `claude attach <id>` 開啟 session，或先使用 `claude stop <id>` 停止它。

36* **從您的 shell**：`claude --resume <session>` 在同一終端機中對該 session 執行 [`claude attach`](/docs/zh-TW/agent-view#attach-to-a-session)，而不是載入文字記錄本身。您在命令列上傳遞的提示，如 `claude --resume <session> "check the tests too"`，會先作為該 session 的下一個輪次進行。Claude Code 會列印 `Sent your prompt to the background session (<id>); opening it…` 然後附加。在終端機上輸入的 `claude -p --resume <session> "prompt"` 也會執行相同操作，因此 `-p` 不會保持該執行非互動式。

38 當命令列具有以下任何情況時，Claude Code 不會開啟 session：

40 * 管道或重新導向的輸入或輸出

41 * 設定 session 的旗標，例如 `--permission-mode`、`--model` 或 `--settings`

42 * 讀取輸出的旗標，例如 `--output-format json` 或 `--json-schema`

43 * 限制或倒帶執行的旗標，例如 `--max-turns` 或 `--max-budget-usd`

45 使用這些中的任何一個，或當[代理檢視已關閉](/docs/zh-TW/agent-view#turn-off-agent-view)時，Claude Code 不會傳送任何內容，並以狀態 1 退出，列印 session 在背景執行以及開啟它的 `claude attach <id>` 命令，或當它無法確定 ID 時告訴您在 `claude agents` 中找到它。新增 `--fork-session` 以恢復對話的副本。要在您自己的 session 中繼續對話本身，並套用您的旗標，請執行 `claude stop <id>`，然後重複該命令。

47 以 `/` 或 `!` 開頭的提示不會被傳送，當 session 等待您回答問題時也不會傳送任何提示。在這兩種情況下，Claude Code 都不會開啟 session，訊息會包含 `Your prompt was not sent to it` 以及原因。

48* **從 session 內**：`/resume` 將您目前的對話移到背景，並將此終端機附加到執行中的 session，列印 `Opening "<title>", running in the background (<id>)`。在空提示上按 `←` 以返回代理檢視，這也會列出您留下的對話。當目前的對話無法移到背景時（例如因為您已附加到背景 session 或 session 持久性已關閉），`/resume` 會列印要執行的 `claude attach` 命令。

32您可以從任何目錄執行 `claude --resume <session-id>`：Claude Code 會先在目前專案目錄及其 git worktrees 中查找 ID，然後在此機器上的所有其他專案中查找，因此它會找到在其他地方啟動或使用 [`/cd`](/docs/zh-TW/commands) 移動的 session。跨專案搜尋只有在恰好一個其他專案持有該 ID 的訊息文字記錄時才會解析 ID，因此手動複製的重複項會導致 Claude Code 報告找不到，而不是恢復任意副本。如果沒有儲存的 session 符合該 ID，Claude Code 會報告 `No conversation found with session ID: <session-id>`。在 v2.1.223 之前，查詢會停在目前專案目錄及其 git worktrees，因此您必須從 session 最後工作的目錄恢復。50您可以從任何目錄執行 `claude --resume <session-id>`：Claude Code 會先在目前專案目錄及其 git worktrees 中查找 ID，然後在此機器上的所有其他專案中查找，因此它會找到在其他地方啟動或使用 [`/cd`](/docs/zh-TW/commands) 移動的 session。跨專案搜尋只有在恰好一個其他專案持有該 ID 的訊息文字記錄時才會解析 ID，因此手動複製的重複項會導致 Claude Code 報告找不到，而不是恢復任意副本。如果沒有儲存的 session 符合該 ID，Claude Code 會報告 `No conversation found with session ID: <session-id>`。在 v2.1.223 之前，查詢會停在目前專案目錄及其 git worktrees，因此您必須從 session 最後工作的目錄恢復。

33 51

34<h3 id="what-a-resumed-session-restores">52<h3 id="what-a-resumed-session-restores">

35 恢復的 session 會復原什麼53 恢復的 session 會復原什麼

36</h3>54</h3>

37 55

~~38恢復的 session 會復原對話以及儲存在其中的狀態：~~56當 Claude Code 從其文字記錄載入對話時，恢復的 session 會復原對話以及儲存在其中的狀態：

39 57

40* 對話歷史記錄：完整歷史記錄，包括工具呼叫和結果。當前一個程序結束時仍在執行的工具（例如在當機中），在您恢復時不會完成或再次執行；Claude 會看到呼叫標記為在其結果被記錄之前被切斷，並被告知在再次執行之前檢查它是否生效，除非設定了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-TW/env-vars#variables)。在 v2.1.281 之前，Claude Code 會從對話中刪除被切斷的呼叫，或將其顯示為您中斷的呼叫。58* 對話歷史記錄：完整歷史記錄，包括工具呼叫和結果。當前一個程序結束時仍在執行的工具（例如在當機中），在您恢復時不會完成或再次執行；Claude 會看到呼叫標記為在其結果被記錄之前被切斷，並被告知在再次執行之前檢查它是否生效，除非設定了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-TW/env-vars#variables)。在 v2.1.281 之前，Claude Code 會從對話中刪除被切斷的呼叫，或將其顯示為您中斷的呼叫。

41* 模型：session 會在其使用的模型上繼續。當模型已被淘汰或不被 `availableModels` 允許時，模型不會被復原；當 `--model` 旗標或 `ANTHROPIC_MODEL` 系列環境變數在啟動時選擇一個時；或在使用提供者特定部署 ID 的提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations)；請參閱[模型設定](/docs/zh-TW/model-config#setting-your-model)以了解解析順序。59* 模型：session 會在其使用的模型上繼續。當模型已被淘汰或不被 `availableModels` 允許時，模型不會被復原；當 `--model` 旗標或 `ANTHROPIC_MODEL` 系列環境變數在啟動時選擇一個時；或在使用提供者特定部署 ID 的提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations)；請參閱[模型設定](/docs/zh-TW/model-config#setting-your-model)以了解解析順序。

51 恢復時的權限模式69 恢復時的權限模式

52</h4>70</h4>

53 71

~~54Claude Code 啟動恢復的 session 所在的權限模式取決於您如何恢復：~~72Claude Code 啟動恢復的 session 所在的權限模式取決於您如何恢復。下面的情況適用於 Claude Code 從其文字記錄載入對話時；當您[開啟仍在執行的背景 session](#resume-a-running-background-session) 時，該 session 會保持它所在的權限模式。

55 73

56* 終端機：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時），不帶 `-p`。Claude Code 會復原 session 所在的權限模式，除了表格中的情況。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。74* 終端機：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時），不帶 `-p`。Claude Code 會復原 session 所在的權限模式，除了表格中的情況。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。

57* 非互動式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 會在新 `claude -p` 執行會啟動的權限模式中啟動執行，除了在[下面的條件](#resume-in-plan-mode-with-p)下以 Plan Mode 結束的 session 會在 Plan Mode 中恢復。75* 非互動式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 會在新 `claude -p` 執行會啟動的權限模式中啟動執行，除了在[下面的條件](#resume-in-plan-mode-with-p)下以 Plan Mode 結束的 session 會在 Plan Mode 中恢復。

settings-reference.md +52 −5

Details

3675 `spinnerTipsOverride`3676 `spinnerTipsOverride`

3676</h3>3677</h3>

3677 3678

3678將您自己的提示新增到 Claude Code 在 Claude 工作時顯示的[旋轉器提示](#spinnertipsenabled)，或用您的提示取代內建提示。Claude Code 將您的提示放在與內建提示相同的輪換中：它選擇未顯示時間最長的提示，跳過仍在冷卻期中的提示，並按優先順序打破平局。3679將您自己的提示新增到 Claude Code 在 Claude 工作時顯示的[旋轉器提示](#spinnertipsenabled)，或用您的提示取代內建提示。Claude Code 將您的提示放在與內建提示相同的輪換中。

3679 3680

3680如果您將 [`spinnerTipsEnabled`](#spinnertipsenabled) 設定為 `false`，Claude Code 會隱藏所有提示，包括您的提示。3681如果您將 [`spinnerTipsEnabled`](#spinnertipsenabled) 設定為 `false`，Claude Code 會隱藏所有提示，包括您的提示。

3681 3682

3683* **類型**：具有 `tips`、`tipsFile`、`label` 和 `excludeDefault` 欄位的物件，每個都是可選的3684* **類型**：具有 `tips`、`tipsFile`、`label` 和 `excludeDefault` 欄位的物件，每個都是可選的

3684* **預設**：未設定，因此 Claude Code 僅顯示內建提示3685* **預設**：未設定，因此 Claude Code 僅顯示內建提示

3685 3686

3686提示物件、`tipsFile`、`label` 和「範圍」行的規則（專案和本機設定僅貢獻純字串）需要 Claude Code v2.1.247 或更新版本。在較早的版本上，專案或本機檔案的 `excludeDefault` 也適用。3687提示物件、`tipsFile`、`label` 和「範圍」行的規則（專案和本機設定僅貢獻純字串）需要 Claude Code v2.1.247 或更新版本。

3687 3688

3688每個 `tips` 項目是純字串或具有以下欄位的物件：3689每個 `tips` 項目是純字串或具有以下欄位的物件：

3689 3690

5653 5654

5654* **範圍**：[`任何檔案`](#scopes)5655* **範圍**：[`任何檔案`](#scopes)

5655* **類型**：布林值5656* **類型**：布林值

5656 * `true`：Claude Code 為該檔案適用的每個工作階段關閉 Artifact 工具，且沒有其他檔案將其重新開啟。在 v2.1.242 之前，優先順序較高的檔案可能會覆寫較低檔案的 `true`，而不是該金鑰作為鎖定5657 * `true`：Claude Code 為該檔案適用的每個工作階段關閉 Artifact 工具，且沒有其他檔案將其重新開啟

5657 * `false`：忽略；若要保持工具開啟，請移除該金鑰5658 * `false`：忽略；若要保持工具開啟，請移除該金鑰

5658* **預設**：未設定，因此工具遵循您帳戶的[可用性](/docs/zh-TW/artifacts#availability)5659* **預設**：未設定，因此工具遵循您帳戶的[可用性](/docs/zh-TW/artifacts#availability)

5659* **每個工作階段的覆寫**：[`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/zh-TW/env-vars) 設定為 `1` 會為一個工作階段關閉工具5660* **每個工作階段的覆寫**：[`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/zh-TW/env-vars) 設定為 `1` 會為一個工作階段關閉工具

5740}5741}

5741```5742```

5742 5743

5743當您自己的使用者設定以外的來源保持工具關閉時，Claude Code 會在 `/config` 中隱藏 **Artifacts** 列，因為在那裡開啟它不會改變任何事情。[停用 artifacts](/docs/zh-TW/artifacts#disable-artifacts) 列出關閉工具的每一種方式。在 v2.1.242 之前，Claude Code 在專案和本機設定中忽略此金鑰，[優先順序堆疊](/docs/zh-TW/settings#settings-precedence)中較高的檔案可能會在較低檔案的關閉上將工具重新開啟。5744當您自己的使用者設定以外的來源保持工具關閉時，Claude Code 會在 `/config` 中隱藏 **Artifacts** 列，因為在那裡開啟它不會改變任何事情。[停用 artifacts](/docs/zh-TW/artifacts#disable-artifacts) 列出關閉工具的每一種方式。

5744 5745

5745<h3 id="inputneedednotifenabled">5746<h3 id="inputneedednotifenabled">

5746 `inputNeededNotifEnabled`5747 `inputNeededNotifEnabled`

5879 5880

5880透過協助指令碼提供認證，對於組織，強制執行登入方法或組織。請參閱[驗證](/docs/zh-TW/authentication)。5881透過協助指令碼提供認證，對於組織，強制執行登入方法或組織。請參閱[驗證](/docs/zh-TW/authentication)。

5881 5882

5883<h3 id="allowedproviders">

5884 `allowedProviders`

5885</h3>

5886

5887列出機器可能透過其到達 Claude 的服務，例如 Anthropic API、Amazon Bedrock 或 LLM 閘道。未列出的提供者上的工作階段在啟動時、登入時以及下次聯絡 API 時被拒絕，因此在工作階段中期切換到未列出的提供者也被拒絕。[拒絕訊息](/docs/zh-TW/errors#managed-settings-dont-allow-this-api-provider)會命名選擇提供者的內容和繼續的步驟。需要 Claude Code v2.1.285 或更新版本。

5888

5889* **範圍**：[`受管`](#scopes)。機器自己的管理員來源設定的清單、MDM 原則和受管設定檔，在伺服器受管設定也提供一個時繼續適用：工作階段可能只使用兩個清單上的提供者，因此伺服器受管清單可以縮小機器允許的內容，但永遠無法擴大它。哪個機器來源的 `allowedProviders` 計數遵循[Claude Code 如何結合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)。透過伺服器受管設定單獨提供的清單僅到達[擷取伺服器受管設定](/docs/zh-TW/server-managed-settings#platform-availability)的工作階段。

5890* **類型**：字串陣列，每個都是以下之一：

5891 * `"anthropic"`：Anthropic 自己的主機上的 Anthropic API，透過 claude.ai 或 Console 登入或 API 金鑰。將其與 [`forceLoginMethod`](#forceloginmethod) 或 [`forceLoginOrgUUID`](#forceloginorguuid) 配對以也限制登入

5892 * `"bedrock"`：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)

5893 * `"vertex"`：[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai)，前身為 Vertex AI

5894 * `"foundry"`：[Microsoft Foundry](/docs/zh-TW/microsoft-foundry)

5895 * `"anthropicAws"`：[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)

5896 * `"mantle"`：Amazon Bedrock [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。[在 Invoke API 旁邊執行 Mantle](/docs/zh-TW/amazon-bedrock#run-mantle-alongside-the-invoke-api) 的工作階段使用兩個提供者，因此將 `"bedrock"` 和 `"mantle"` 一起列出

5897 * `"customEndpoint"`：Anthropic API 或雲端提供者的 API 傳送到另一個主機，例如由 `ANTHROPIC_BASE_URL` 命名的 [LLM 閘道](/docs/zh-TW/llm-gateway)、提供者的 `ANTHROPIC_*_BASE_URL` 變數，或不是裸資源名稱的 `ANTHROPIC_FOUNDRY_RESOURCE` 值。Claude Code 僅針對受管 [`env`](#env) 區塊固定的確切值允許它

5898 * `"gateway"`：[Cloud 閘道](/docs/zh-TW/claude-apps-gateway)登入

5899* **預設**：未設定，所以可以使用任何提供者

5900

5901```json managed-settings.json theme={null}

5902{

5903 "allowedProviders": ["anthropic", "bedrock"]

5904}

5905```

5906

5907每個雲端提供者的項目表示該提供者自己的服務，包括其區域、FIPS 和私人端點。

5908

5909Claude Code 不認識為提供者名稱的項目被丟棄並報告，清單的其餘部分保持強制執行。使用空清單，或其每個項目都無法識別的清單，Claude Code 拒絕每個提供者，不在機器上啟動。

5910

5911<h4 id="endpoints-that-need-a-pin-in-managed-env">

5912 需要在受管 `env` 中固定的端點

5913</h4>

5914

5915固定是在受管 [`env`](#env) 區塊中設定的端點變數值。當工作階段將提供者的流量傳送到該提供者自己的服務以外的地方時，Claude Code 僅在工作階段的值與固定值相同時允許它。這些端點需要一個：

5916

5917* **`"customEndpoint"` 工作階段**：命名主機的變數，例如 `ANTHROPIC_BASE_URL`

5918* **Amazon Bedrock**：AWS SDK 的 `AWS_ENDPOINT_URL`、`AWS_ENDPOINT_URL_BEDROCK` 和 `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` 變數，當它們指向 Bedrock 自己的服務以外時。工作階段保持在 `"bedrock"` 下而不是 `"customEndpoint"`

5919* **閘道登入的 URL**：工作階段保持在 `"gateway"` 下，[`forceLoginGatewayUrl`](#forcelogingatewayurl) 也計為固定

5920

5921哪些 `env` 區塊計為固定取決於清單設定的位置：

5922

5923* **機器上的管理員來源設定清單**：僅機器自己的管理員來源的 `env` 區塊計為固定

5924* **僅伺服器受管設定設定清單**：這些伺服器受管設定中的 `env` 值也計為固定

5925

5926清單不判斷雲端提供者的認證和租賃變數或網路路徑，例如 `HTTPS_PROXY` 和憑證設定。在受管 `env` 區塊中為整個機隊設定這些。

5927

5882<h3 id="apikeyhelper">5928<h3 id="apikeyhelper">

5883 `apiKeyHelper`5929 `apiKeyHelper`

5884</h3>5930</h3>

6401| :- | :- | :- |6447| :- | :- | :- |

6402| 清單 | 合併來自每個來源的項目 | [`permissions.allow`](#permissions-allow)、[`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 和其他清單金鑰 |6448| 清單 | 合併來自每個來源的項目 | [`permissions.allow`](#permissions-allow)、[`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 和其他清單金鑰 |

6403| 鎖定 | 套用任何來源設定的最嚴格值。當沒有來源設定嚴格值時，只從最高來源套用較寬鬆的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布林值或列舉鎖定 |6449| 鎖定 | 套用任何來源設定的最嚴格值。當沒有來源設定嚴格值時，只從最高來源套用較寬鬆的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布林值或列舉鎖定 |

6404| 限制允許清單 | 從設定它的最高來源整體取得清單，不從較低的來源新增項目。當最高來源未設定時，從下一個較低的來源整體取得 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 鏈 |6450| 限制允許清單 | 從設定它的最高來源整體取得清單，不從較低的來源新增項目。當最高來源未設定時，從下一個較低的來源整體取得 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`allowedProviders`](#allowedproviders)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 鏈 |

6405| 整體取值 | 從設定它的最高來源整體取得值，不合併來自較低來源的項目或欄位。當最高來源未設定時，從下一個較低的來源整體取得 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) |6451| 整體取值 | 從設定它的最高來源整體取得值，不合併來自較低來源的項目或欄位。當最高來源未設定時，從下一個較低的來源整體取得 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) |

6407| 只從最高優先順序來源讀取 | 只從攜帶原則金鑰的最高優先順序來源讀取金鑰，因此即使最高來源未設定任何值，較低來源的值也會被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod) 的 `"claudeai"` 和 `"console"` 值、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) |6453| 只從最高優先順序來源讀取 | 只從攜帶原則金鑰的最高優先順序來源讀取金鑰，因此即使最高來源未設定任何值，較低來源的值也會被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod) 的 `"claudeai"` 和 `"console"` 值、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) |

6415* **[`policyHelper`](#policyhelper)**: Claude Code 只在攜帶原則金鑰的最高來源是 MDM 原則或受管設定檔案時接受它，因此在伺服器受管設定下它不適用。6461* **[`policyHelper`](#policyhelper)**: Claude Code 只在攜帶原則金鑰的最高來源是 MDM 原則或受管設定檔案時接受它，因此在伺服器受管設定下它不適用。

6416* **[`modelOverrides`](#modeloverrides)**: 與 `availableModels` 配對。Claude Code 從設定它的最高來源取得 `modelOverrides`，除非較高的來源設定 `availableModels` 而不設定 `modelOverrides`。在這種情況下，它會忽略來自每個來源的 `modelOverrides`。6462* **[`modelOverrides`](#modeloverrides)**: 與 `availableModels` 配對。Claude Code 從設定它的最高來源取得 `modelOverrides`，除非較高的來源設定 `availableModels` 而不設定 `modelOverrides`。在這種情況下，它會忽略來自每個來源的 `modelOverrides`。

6417* **[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`gatewayInternalNetworks`](#gatewayinternalnetworks) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 從不從伺服器受管設定讀取它們中的任何一個，因此那裡的值既不適用也不隱藏在 MDM 原則或受管設定檔案中設定的值。在機器上的管理員來源中，只有攜帶原則金鑰的排名最高的來源提供它們，無論伺服器受管設定是否也存在。6463* **[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`gatewayInternalNetworks`](#gatewayinternalnetworks) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 從不從伺服器受管設定讀取它們中的任何一個，因此那裡的值既不適用也不隱藏在 MDM 原則或受管設定檔案中設定的值。在機器上的管理員來源中，只有攜帶原則金鑰的排名最高的來源提供它們，無論伺服器受管設定是否也存在。

6464* **[`allowedProviders`](#allowedproviders)**: 在表格的規則之後，機器本身的清單仍然限制結果，如其項目的範圍附註所述。

6418 6465

6419若要確認機器上合併了哪些來源，請執行 `/status` 並[讀取 `Setting sources` 行](/docs/zh-TW/managed-settings#read-the-source-in-/status)。6466若要確認機器上合併了哪些來源，請執行 `/status` 並[讀取 `Setting sources` 行](/docs/zh-TW/managed-settings#read-the-source-in-/status)。

6420 6467

skills.md +1 −1

Details

740 740

741* **工作目錄**：Claude Code 在工作階段 shell 的目前工作目錄中執行每個命令。當 Claude 執行 `cd` 時，該目錄會移動。在必須每次都以相同方式解析的路徑中使用 [`${CLAUDE_SKILL_DIR}` 或 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)。741* **工作目錄**：Claude Code 在工作階段 shell 的目前工作目錄中執行每個命令。當 Claude 執行 `cd` 時，該目錄會移動。在必須每次都以相同方式解析的路徑中使用 [`${CLAUDE_SKILL_DIR}` 或 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)。

742* **stderr**：使用預設 `bash` shell，Claude Code 會將 stderr 合併到 stdout。命令寫入 stderr 的任何內容都會出現在注入的文字中。742* **stderr**：使用預設 `bash` shell，Claude Code 會將 stderr 合併到 stdout。命令寫入 stderr 的任何內容都會出現在注入的文字中。

743* **逾時**：每個命令在 Bash 工具的預設 2 分鐘[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)下執行。當 Bash 工具[將逾時命令移到背景](/docs/zh-TW/tools-reference#background-commands)時，技能仍會呈現。注入的文字會報告移動並命名背景工作和收集命令輸出的檔案。當命令是 Bash 工具永遠不會自動背景執行的命令時，Claude Code 會在逾時時終止它。該失敗會[中止呼叫](#when-an-injected-command-fails)。743* **逾時**：每個命令在 Bash 工具的預設 2 分鐘[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)下執行。當 Bash 工具[將逾時命令移到背景](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)時，技能仍會呈現。注入的文字會報告移動並命名背景工作和收集命令輸出的檔案。當命令是 Bash 工具永遠不會自動背景執行的命令時，Claude Code 會在逾時時終止它。該失敗會[中止呼叫](#when-an-injected-command-fails)。

744* **輸出大小**：超過 Bash 工具內聯上限的輸出會作為檔案路徑加上簡短預覽到達，而不是截斷的文字。[輸出限制](/docs/zh-TW/tools-reference#output-limits)涵蓋上限以及如何調整每個邊界。744* **輸出大小**：超過 Bash 工具內聯上限的輸出會作為檔案路徑加上簡短預覽到達，而不是截斷的文字。[輸出限制](/docs/zh-TW/tools-reference#output-limits)涵蓋上限以及如何調整每個邊界。

745 745

746PowerShell 工具對其執行的命令應用相同的逾時、背景執行和輸出上限行為。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)部分以了解其具體內容。746PowerShell 工具對其執行的命令應用相同的逾時、背景執行和輸出上限行為。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)部分以了解其具體內容。

statusline.md +7 −7

Details

20以下是一個[多行狀態列](#display-multiple-lines)的範例，在第一行顯示 git 資訊，在第二行顯示顏色編碼的 context 列。20以下是一個[多行狀態列](#display-multiple-lines)的範例，在第一行顯示 git 資訊，在第二行顯示顏色編碼的 context 列。

21 21

22<Frame>22<Frame>

23 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="多行狀態列，在第一行顯示模型名稱、目錄、git 分支，在第二行顯示 context 使用進度列、成本和持續時間" width="776" height="212" data-path="images/statusline-multiline.png" />23 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-multiline.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=a9d0a2fe8e446d80b1abc46da3f93270" alt="多行狀態列，在第一行顯示模型名稱、目錄、git 分支，在第二行顯示 context 使用進度列、成本和持續時間" width="1224" height="262" data-path="images/statusline-multiline.png" />

24</Frame>24</Frame>

25 25

26本頁面介紹[設定基本狀態列](#set-up-a-status-line)、說明[資料如何從 Claude Code 流向您的指令碼](#how-status-lines-work)、列出[您可以顯示的所有欄位](#available-data)，並提供[常見模式的現成範例](#examples)，例如 git 狀態、成本追蹤和進度列。26本頁面介紹[設定基本狀態列](#set-up-a-status-line)、說明[資料如何從 Claude Code 流向您的指令碼](#how-status-lines-work)、列出[您可以顯示的所有欄位](#available-data)，並提供[常見模式的現成範例](#examples)，例如 git 狀態、成本追蹤和進度列。

93這些範例使用 Bash 指令碼，適用於 macOS 和 Linux。在 Windows 上，請參閱 [Windows 設定](#windows-configuration)以取得 PowerShell 和 Git Bash 範例。93這些範例使用 Bash 指令碼，適用於 macOS 和 Linux。在 Windows 上，請參閱 [Windows 設定](#windows-configuration)以取得 PowerShell 和 Git Bash 範例。

94 94

95<Frame>95<Frame>

96 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-quickstart.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=696445e59ca0059213250651ad23db6b" alt="狀態列顯示模型名稱、目錄和 context 百分比" width="726" height="164" data-path="images/statusline-quickstart.png" />96 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-quickstart.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=88a7eab9c1038dd098ee8e284d96b7e6" alt="狀態列顯示模型名稱、目錄和 context 百分比" width="1224" height="224" data-path="images/statusline-quickstart.png" />

97</Frame>97</Frame>

98 98

99<Steps>99<Steps>

444顯示目前模型和 context window 使用情況，帶有視覺進度列。每個指令碼從 stdin 讀取 JSON，提取 `used_percentage` 欄位，並建立一個 10 字元的列，其中填充的塊（▓）代表使用情況：444顯示目前模型和 context window 使用情況，帶有視覺進度列。每個指令碼從 stdin 讀取 JSON，提取 `used_percentage` 欄位，並建立一個 10 字元的列，其中填充的塊（▓）代表使用情況：

445 445

446<Frame>446<Frame>

447 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-context-window-usage.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=15b58ab3602f036939145dde3165c6f7" alt="狀態列顯示模型名稱和帶有百分比的進度列" width="448" height="152" data-path="images/statusline-context-window-usage.png" />447 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-context-window-usage.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=f3918a549912dc47e90f2b69e68bc847" alt="狀態列顯示模型名稱和帶有百分比的進度列" width="1224" height="224" data-path="images/statusline-context-window-usage.png" />

448</Frame>448</Frame>

449 449

450<CodeGroup>450<CodeGroup>

513顯示 git 分支，帶有暫存和修改檔案的顏色編碼指示器。此指令碼使用 [ANSI 逃逸碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)表示終端顏色：`\033[32m` 是綠色，`\033[33m` 是黃色，`\033[0m` 重設為預設值。513顯示 git 分支，帶有暫存和修改檔案的顏色編碼指示器。此指令碼使用 [ANSI 逃逸碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)表示終端顏色：`\033[32m` 是綠色，`\033[33m` 是黃色，`\033[0m` 重設為預設值。

514 514

515<Frame>515<Frame>

516 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-git-context.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e656f34f90d1d9a1d0e220988914345f" alt="狀態列顯示模型、目錄、git 分支和暫存和修改檔案的彩色指示器" width="742" height="178" data-path="images/statusline-git-context.png" />516 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-git-context.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=f13c190724d9ec7188c17cd2f98b7bf4" alt="狀態列顯示模型、目錄、git 分支和暫存和修改檔案的彩色指示器" width="1224" height="224" data-path="images/statusline-git-context.png" />

517</Frame>517</Frame>

518 518

519每個指令碼檢查目前目錄是否是 git 儲存庫，計算暫存和修改檔案，並顯示顏色編碼的指示器：519每個指令碼檢查目前目錄是否是 git 儲存庫，計算暫存和修改檔案，並顯示顏色編碼的指示器：

611每個指令碼將成本格式化為貨幣，並將毫秒轉換為分鐘和秒：611每個指令碼將成本格式化為貨幣，並將毫秒轉換為分鐘和秒：

612 612

613<Frame>613<Frame>

614 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-cost-tracking.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e3444a51fe6f3440c134bd5f1f08ad29" alt="狀態列顯示模型名稱、工作階段成本和持續時間" width="588" height="180" data-path="images/statusline-cost-tracking.png" />614 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-cost-tracking.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=925f7024c3b38be0f0eca63564bfb52f" alt="狀態列顯示模型名稱、工作階段成本和持續時間" width="1224" height="224" data-path="images/statusline-cost-tracking.png" />

615</Frame>615</Frame>

616 616

617<CodeGroup>617<CodeGroup>

672您的指令碼可以輸出多行以建立更豐富的顯示。672您的指令碼可以輸出多行以建立更豐富的顯示。

673 673

674<Frame>674<Frame>

675 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="多行狀態列，在第一行顯示模型名稱、目錄、git 分支，在第二行顯示 context 使用進度列、成本和持續時間" width="776" height="212" data-path="images/statusline-multiline.png" />675 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-multiline.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=a9d0a2fe8e446d80b1abc46da3f93270" alt="多行狀態列，在第一行顯示模型名稱、目錄、git 分支，在第二行顯示 context 使用進度列、成本和持續時間" width="1224" height="262" data-path="images/statusline-multiline.png" />

676</Frame>676</Frame>

677 677

678此範例結合了多種技術：基於閾值的顏色（70% 以下為綠色，70-89% 為黃色，90%+ 為紅色）、進度列和 git 分支資訊。每個 `print` 或 `echo` 陳述式建立單獨的行：678此範例結合了多種技術：基於閾值的顏色（70% 以下為綠色，70-89% 為黃色，90%+ 為紅色）、進度列和 git 分支資訊。每個 `print` 或 `echo` 陳述式建立單獨的行：

781此範例建立指向您的 GitHub 儲存庫的可點擊連結。按住 Cmd（macOS）或 Ctrl（Windows/Linux）並點擊以在瀏覽器中開啟連結。781此範例建立指向您的 GitHub 儲存庫的可點擊連結。按住 Cmd（macOS）或 Ctrl（Windows/Linux）並點擊以在瀏覽器中開啟連結。

782 782

783<Frame>783<Frame>

784 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-links.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=4bcc6e7deb7cf52f41ab85a219b52661" alt="狀態列顯示指向 GitHub 儲存庫的可點擊連結" width="726" height="198" data-path="images/statusline-links.png" />784 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-links.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=4778a144a28cb498c99d5fa018bb374a" alt="狀態列顯示指向 GitHub 儲存庫的可點擊連結" width="1224" height="224" data-path="images/statusline-links.png" />

785</Frame>785</Frame>

786 786

787每個指令碼取得 git 遠端 URL，將 SSH 格式轉換為 HTTPS，並將儲存庫名稱包裝在 OSC 8 逃逸碼中。Bash 版本使用 `printf '%b'`，它比 `echo -e` 更可靠地跨不同 shell 解釋反斜杠逃逸：787每個指令碼取得 git 遠端 URL，將 SSH 格式轉換為 HTTPS，並將儲存庫名稱包裝在 OSC 8 逃逸碼中。Bash 版本使用 `printf '%b'`，它比 `echo -e` 更可靠地跨不同 shell 解釋反斜杠逃逸：

third-party-integrations.md +2 −0

Details

253 253

254安全團隊可以設定受管權限，以決定 Claude Code 允許和不允許執行的操作，這些權限無法被本機設定覆寫。[瞭解更多](/docs/zh-TW/security)。254安全團隊可以設定受管權限，以決定 Claude Code 允許和不允許執行的操作，這些權限無法被本機設定覆寫。[瞭解更多](/docs/zh-TW/security)。

255 255

256若要限制受管機器可以使用的部署選項，請在受管設定中設定 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders)。例如，`["bedrock"]` 只允許 Amazon Bedrock，不允許其他；同時啟用 Mantle 端點的 Bedrock 機隊也會列出 `"mantle"`。該項目說明哪些端點變數也需要受管 `env` 固定。需要 Claude Code v2.1.285 或更新版本。

257

256<h3 id="leverage-mcp-for-integrations">258<h3 id="leverage-mcp-for-integrations">

257 使用 MCP 進行整合259 使用 MCP 進行整合

258</h3>260</h3>

tools-reference.md +20 −5

Details

174* `BASH_DEFAULT_TIMEOUT_MS` — 當 Claude 不傳遞逾時時的預設值；預設為兩分鐘174* `BASH_DEFAULT_TIMEOUT_MS` — 當 Claude 不傳遞逾時時的預設值；預設為兩分鐘

175* `BASH_MAX_TIMEOUT_MS` — 使用預設值時，設定上限以限制 Claude 要求的任何內容：有效上限是兩者中較大的，預設為十分鐘175* `BASH_MAX_TIMEOUT_MS` — 使用預設值時，設定上限以限制 Claude 要求的任何內容：有效上限是兩者中較大的，預設為十分鐘

176 176

177對於 Claude 在背景啟動的命令，`timeout` 改為設定命令在背景執行的時間長度，其中單獨的預設值和最大值在[背景命令](#background-commands)下描述。[PowerShell 工具](#powershell-tool)遵循相同的逾時規則並讀取相同的兩個變數。177對於 Claude 在背景啟動的命令，`timeout` 改為設定命令在背景執行的時間長度，其中單獨的預設值和最大值在[背景命令時間限制](#time-limit-for-background-commands)下描述。[PowerShell 工具](#powershell-tool)遵循相同的逾時規則並讀取相同的兩個變數。

178 178

179<h4 id="output-limits">179<h4 id="output-limits">

180 輸出限制180 輸出限制

199 199

200對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 `run_in_background: true` 以將命令作為背景工作啟動並在其執行時繼續工作。使用 `/tasks` 列出並停止背景工作。在您從那裡停止一個後，或從連接的用戶端（例如桌面應用程式）停止後，Claude 會繼續而不是等待。如果子代理啟動了命令，則是該子代理繼續。200對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 `run_in_background: true` 以將命令作為背景工作啟動並在其執行時繼續工作。使用 `/tasks` 列出並停止背景工作。在您從那裡停止一個後，或從連接的用戶端（例如桌面應用程式）停止後，Claude 會繼續而不是等待。如果子代理啟動了命令，則是該子代理繼續。

201 201

202[前景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的命令在該子代理的執行結束時停止，無論它完成、失敗或被中斷。主對話或背景子代理啟動的命令在最終回應後繼續執行，直到它退出、被停止或達到其時間限制。在使用 `-p` 旗標的非互動模式中，[背景命令在執行的最終結果後不久結束](/docs/zh-TW/headless#background-tasks-at-exit)。202<h4 id="when-a-background-command-stops">

203 背景命令何時停止

204</h4>

205

206[前景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的命令在該子代理的執行結束時停止，無論它完成、失敗或被中斷。主對話或背景子代理啟動的命令在最終回應後繼續執行，直到它退出、被停止或達到其[時間限制](#time-limit-for-background-commands)。在使用 `-p` 旗標的非互動模式中，[背景命令在執行的最終結果後不久結束](/docs/zh-TW/headless#background-tasks-at-exit)。

207

208<h4 id="time-limit-for-background-commands">

209 背景命令的時間限制

210</h4>

203 211

204背景 Bash 和 PowerShell 命令有時間限制，從命令進入背景的時刻開始計算：212背景 Bash 和 PowerShell 命令有時間限制，從命令進入背景的時刻開始計算：

205 213

206* Claude 在背景啟動的命令獲得 30 分鐘，或 Claude 使用 `run_in_background` 傳遞的 `timeout`，最多 2 小時214* Claude 在背景啟動的命令獲得 30 分鐘，或 Claude 使用 `run_in_background` 傳遞的 `timeout`，最多 2 小時

207* 在前景啟動然後移至背景的命令，例如使用 `Ctrl+B` 或在其逾時時，從移動時獲得 30 分鐘215* 在前景啟動然後移至背景的命令，例如使用 `Ctrl+B` 或在其逾時時，從移動時獲得 30 分鐘

208 216

217當背景命令達到其時間限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動命令，如果工作仍然需要的話。停止通知讀作 `Background command "<description>" was stopped after reaching its background time limit`。

218

219<h4 id="raise-the-time-limit-for-background-commands">

220 提高背景命令的時間限制

221</h4>

222

209兩個[環境變數](/docs/zh-TW/env-vars)提高這些限制，對於 Bash 和 PowerShell 命令一樣。兩者都採用毫秒，且都不能縮短限制：較低的值會保留 30 分鐘的預設值和 2 小時的最大值。223兩個[環境變數](/docs/zh-TW/env-vars)提高這些限制，對於 Bash 和 PowerShell 命令一樣。兩者都採用毫秒，且都不能縮短限制：較低的值會保留 30 分鐘的預設值和 2 小時的最大值。

210 224

211* 將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `1800000` 以用該值替換 30 分鐘的預設值，無論是對於 Claude 啟動時不帶 `timeout` 的命令還是對於移動的命令225* 將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `1800000` 以用該值替換 30 分鐘的預設值，無論是對於 Claude 啟動時不帶 `timeout` 的命令還是對於移動的命令

212* 將 `BASH_MAX_TIMEOUT_MS` 設定為高於 `7200000` 以將 2 小時的最大值提高到該值。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `7200000` 以相同方式提高最大值226* 將 `BASH_MAX_TIMEOUT_MS` 設定為高於 `7200000` 以將 2 小時的最大值提高到該值。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `7200000` 以相同方式提高最大值

213 227

214當背景命令達到其時間限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動命令，如果工作仍然需要的話。停止通知讀作 `Background command "<description>" was stopped after reaching its background time limit`。228<h4 id="foreground-commands-that-move-to-the-background">

229 移至背景的前景命令

230</h4>

215 231

216當前景命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它，除非命令以 `sleep` 開頭。移動的命令的時間限制從移動時開始計算，前景子代理的移動命令仍然在該子代理的執行結束時停止。232當前景命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它，除非命令以 `sleep` 開頭。移動的命令的[時間限制](#time-limit-for-background-commands)從移動時開始計算，前景子代理的移動命令仍然在該子代理的執行結束時停止。

217 233

218設定 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-TW/env-vars#variables) 會停用自動背景化以及其餘的背景工作功能。234設定 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-TW/env-vars#variables) 會停用自動背景化以及其餘的背景工作功能。

219 235

246無論您列出什麼，這些規則都適用：262無論您列出什麼，這些規則都適用：

247 263

248* **未知名稱**：Claude Code 會忽略它不識別的名稱264* **未知名稱**：Claude Code 會忽略它不識別的名稱

249* **Bash、PowerShell 和 Monitor**：Claude Code 無論您列出什麼，都會將 Bash、PowerShell 和 Monitor 工具命令保持在上限以下

250* **變數未設定**：Claude Code 從 Anthropic 從伺服器傳遞的設定中取得其他限制類型的集合，該集合可能隨時間變化，因此當您需要不變的集合時設定變數265* **變數未設定**：Claude Code 從 Anthropic 從伺服器傳遞的設定中取得其他限制類型的集合，該集合可能隨時間變化，因此當您需要不變的集合時設定變數

251* **權限閘控 hook**：即使每種類型都受限，Claude Code 也會從上限中排除可以阻止或變更動作結果的 hook，以及任何此類 hook 呼叫的 MCP 伺服器，因此核心終止權限閘控 hook 無法允許它正在阻止的動作266* **權限閘控 hook**：即使每種類型都受限，Claude Code 也會從上限中排除可以阻止或變更動作結果的 hook，以及任何此類 hook 呼叫的 MCP 伺服器，因此核心終止權限閘控 hook 無法允許它正在阻止的動作

252 267

ultrareview.md +1 −1

Details

66 66

67在 PR 模式中，雲端沙箱直接從主機複製提取請求，而不是組合您的本機工作樹。PR 模式適用於 `github.com` 上的儲存庫和[GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體上的儲存庫，這些執行個體已由擁有者連接到 Claude Code。67在 PR 模式中，雲端沙箱直接從主機複製提取請求，而不是組合您的本機工作樹。PR 模式適用於 `github.com` 上的儲存庫和[GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體上的儲存庫，這些執行個體已由擁有者連接到 Claude Code。

68 68

69對於 `github.com` 上的儲存庫，沙箱使用連接到您 Claude 帳戶的 GitHub 帳戶進行複製，因此該帳戶必須能夠讀取 PR 的儲存庫。Claude Code 在建立雲端工作階段前檢查此項，除非您已設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars#variables)，並在[未連接帳戶](/docs/zh-TW/errors#no-github-account-is-connected-to-your-claude-account)或[帳戶無法看到儲存庫](/docs/zh-TW/errors#your-connected-github-account-cant-see-the-repository)時拒絕啟動；拒絕會命名修正方式。在 v2.1.248 之前，Claude Code 在啟動前不檢查此項。69對於 `github.com` 上的儲存庫，沙箱使用連接到您 Claude 帳戶的 GitHub 帳戶進行複製，因此該帳戶必須能夠讀取 PR 的儲存庫。

70 70

71執行 [`/web-setup`](/docs/zh-TW/web-quickstart#connect-from-your-terminal) 以將您的 GitHub CLI 登入連接到您的 Claude 帳戶。71執行 [`/web-setup`](/docs/zh-TW/web-quickstart#connect-from-your-terminal) 以將您的 GitHub CLI 登入連接到您的 Claude 帳戶。

72 72

vs-code.md +25 −5

Details

58 58

59 * **活動列**：點擊左側邊欄中的 Spark 圖示以開啟工作階段清單。點擊任何工作階段以將其開啟至您的[偏好位置](#extension-settings)，或開始新的工作階段。此圖示在活動列中始終可見。59 * **活動列**：點擊左側邊欄中的 Spark 圖示以開啟工作階段清單。點擊任何工作階段以將其開啟至您的[偏好位置](#extension-settings)，或開始新的工作階段。此圖示在活動列中始終可見。

60 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），輸入「Claude Code」，然後選擇一個選項，例如「在新標籤中開啟」60 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），輸入「Claude Code」，然後選擇一個選項，例如「在新標籤中開啟」

61 * **狀態列**：如果您已將 [`preferredLocation`](#extension-settings) 設定為 `sidebar`，或使用**Claude Code: Open in Side Bar** 開啟 Claude，請點擊視窗右下角的 **✻ Claude Code**。即使沒有開啟檔案，這也能運作。61 * **狀態列**：點擊視窗右下角的 **✻ Claude Code**。即使沒有開啟檔案，這也能運作。

62 62

63 您可以拖曳 Claude 面板以在 VS Code 中的任何位置重新定位。詳細資訊請參閱[自訂您的工作流程](#customize-your-workflow)。63 您可以拖曳 Claude 面板以在 VS Code 中的任何位置重新定位。詳細資訊請參閱[自訂您的工作流程](#customize-your-workflow)。

64 </Step>64 </Step>

362 362

363在 Plugins 標籤中：363在 Plugins 標籤中：

364 364

365* **已安裝的 plugins** 顯示在頂部，並帶有切換開關以啟用或停用它們365* **已安裝的 plugins** 顯示在頂部，並帶有切換開關以啟用或停用它們。

366 * 如果您關閉您專案的共享 `.claude/settings.json` 開啟的 plugin，擴充功能會先詢問：**為我停用**只為您關閉它，而**為所有人停用**會變更共享檔案。

366* **可用的 plugins** 來自您設定的 marketplaces，顯示在下方367* **可用的 plugins** 來自您設定的 marketplaces，顯示在下方

367* 搜尋以按名稱或描述篩選 plugins368* 搜尋以按名稱或描述篩選 plugins

368* 點擊任何可用 plugin 上的**安裝**369* 點擊任何可用 plugin 上的**安裝**

373* **為此專案安裝**：與專案協作者共享（專案範圍）374* **為此專案安裝**：與專案協作者共享（專案範圍）

374* **本機安裝**：僅供您使用，僅在此儲存庫中（本機範圍）375* **本機安裝**：僅供您使用，僅在此儲存庫中（本機範圍）

375 376

377安裝完成後，表單會要求任何尚未設定的 plugin [設定選項](/docs/zh-TW/plugins/components#user-configuration)。若要稍後檢閱或變更選項，請點擊 plugin 列上的齒輪圖示。

378

379敏感文字欄位會被遮罩，您之前儲存的密碼會顯示 **(未變更)**。將欄位留空以保留儲存的值。

380

381儲存變更後，開啟的工作階段會重新載入其 plugins，對話框會顯示**重新啟動 Claude 以套用 plugin 變更**。

382

383<h3 id="uninstall-plugins">

384 解除安裝 plugins

385</h3>

386

387每個已安裝的列都會命名它安裝的[範圍](/docs/zh-TW/plugins/install#choose-an-install-scope)。若要解除安裝該安裝，請點擊列的垃圾桶圖示。暗淡的垃圾桶圖示標記您無法從此工作區解除安裝的列，例如您的組織管理的 plugin 或為另一個專案安裝的 plugin。

388

389擴充功能在兩種情況下會先詢問：

390

391* **您專案的共享 `.claude/settings.json` 開啟的 plugin**：選擇**為我停用**，這會為您的協作者保留已安裝的 plugin，或**為所有人解除安裝**，這會移除專案的安裝並使用 [`--keep-data`](/docs/zh-TW/plugins/cli-reference#what-an-uninstall-deletes-and-keeps)，因此 plugin 的已儲存資料目錄會保留。如果您已經為自己關閉了 plugin，垃圾桶圖示會移除您自己的安裝而不會出現問題。

392* **否則，具有已儲存資料的 plugin 的最後一個安裝**：選擇是否保留或刪除資料；**保留**是預設值

393

376<h3 id="share-a-plugin-install-link">394<h3 id="share-a-plugin-install-link">

377 分享 plugin 安裝連結395 分享 plugin 安裝連結

378</h3>396</h3>

407 425

408* 輸入 GitHub 儲存庫、URL 或本機路徑以新增 marketplace426* 輸入 GitHub 儲存庫、URL 或本機路徑以新增 marketplace

409* 點擊重新整理圖示以更新 marketplace 的 plugin 清單427* 點擊重新整理圖示以更新 marketplace 的 plugin 清單

410* 點擊垃圾桶圖示以移除 marketplace428* 點擊垃圾桶圖示以移除 marketplace。移除它會[解除安裝您從中安裝的每個 plugin](/docs/zh-TW/plugins/install#manage-marketplaces)，因此確認會先命名這些 plugins

429

430您在對話框中進行的 plugin 變更會立即套用到該 VS Code 視窗中開啟的 Claude Code 工作階段。

411 431

412您在對話框中進行的 plugin 變更會立即套用到該 VS Code 視窗中開啟的 Claude Code 工作階段。如果您開啟對話框的工作階段無法重新載入其 plugins，對話框會提供重試或在該工作階段中重新啟動 Claude 的選項。432如果您開啟對話框的工作階段無法重新載入其 plugins，對話框會提供重試或在該工作階段中重新啟動 Claude 的選項。

413 433

414<Note>434<Note>

415 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中設定的 plugins 和 marketplaces 也可在 CLI 中使用，反之亦然。435 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中設定的 plugins 和 marketplaces 也可在 CLI 中使用，反之亦然。

7884. **停用衝突的擴充功能**：暫時停用其他 AI 擴充功能（Cline、Continue 等）8084. **停用衝突的擴充功能**：暫時停用其他 AI 擴充功能（Cline、Continue 等）

7895. **檢查工作區信任**：擴充功能在受限模式下無法運作8095. **檢查工作區信任**：擴充功能在受限模式下無法運作

790 810

791或者，如果您已將 [`preferredLocation`](#extension-settings) 設定為 `sidebar`，或使用 **Claude Code: Open in Side Bar** 開啟 Claude，請點擊**狀態列**（右下角）中的「✻ Claude Code」。即使沒有開啟檔案，這也能運作。您也可以使用**命令選擇板**（`Cmd+Shift+P` / `Ctrl+Shift+P`）並輸入「Claude Code」。811或者，點擊**狀態列**（視窗右下角）中的 **✻ Claude Code**。即使沒有開啟檔案，這也能運作。您也可以使用**命令選擇板**（`Cmd+Shift+P` / `Ctrl+Shift+P`）並輸入「Claude Code」。

792 812

793<h3 id="cmd-esc-does-nothing-on-macos">813<h3 id="cmd-esc-does-nothing-on-macos">

794 Cmd+Esc 在 macOS 上無法運作814 Cmd+Esc 在 macOS 上無法運作

worktrees.md +1 −1

Details

145* worktree 屬於您未背景的 `--worktree` 會話，無論其年齡如何。145* worktree 屬於您未背景的 `--worktree` 會話，無論其年齡如何。

146* 您自己使用 `git worktree add` 建立了 worktree，即使您隨後在其中執行了 `--worktree <name>` 會話並背景了該會話。146* 您自己使用 `git worktree add` 建立了 worktree，即使您隨後在其中執行了 `--worktree <name>` 會話並背景了該會話。

147 147

148Claude Code 會將標記寫入它使用 git 建立的每個 worktree 的 git 中繼資料中，掃描會保留任何沒有標記的 worktree，包括 [`WorktreeCreate` hook](#non-git-version-control) 建立的 worktree。在 v2.1.246 之前，掃描沒有檢查標記，當舊的背景會話記錄指向它時，可能會移除您自己建立的 worktree。148Claude Code 會將標記寫入它使用 git 建立的每個 worktree 的 git 中繼資料中，掃描會保留任何沒有標記的 worktree，包括 [`WorktreeCreate` hook](#non-git-version-control) 建立的 worktree。

149 149

150當代理正在執行時，Claude Code 會在其 worktree 上執行 `git worktree lock`，以便並行清理無法將其移除，並在代理完成時釋放鎖定。Claude Code 對為背景會話建立的 worktree 執行相同的鎖定，同時會話執行，因此掃描會保留 worktree 並且 `git worktree remove` 拒絕移除它。150當代理正在執行時，Claude Code 會在其 worktree 上執行 `git worktree lock`，以便並行清理無法將其移除，並在代理完成時釋放鎖定。Claude Code 對為背景會話建立的 worktree 執行相同的鎖定，同時會話執行，因此掃描會保留 worktree 並且 `git worktree remove` 拒絕移除它。

151 151

Documentation 2026-09-30 23:00 UTC to 2026-10-01 11:57 UTC