Documentation — Spybara

accessibility.md +18 −18

Details

22 22

23* 針對一個工作階段：執行 `claude --ax-screen-reader`。23* 針對一個工作階段：執行 `claude --ax-screen-reader`。

24* 針對從一個 shell 啟動的工作階段：將 `CLAUDE_AX_SCREEN_READER` 環境變數設定為 `1`。在 Bash 或 Zsh 中，執行 `export CLAUDE_AX_SCREEN_READER=1`；在 PowerShell 中，執行 `$env:CLAUDE_AX_SCREEN_READER = "1"`。將該行新增至您的 shell 設定檔以涵蓋每個 shell。24* 針對從一個 shell 啟動的工作階段：將 `CLAUDE_AX_SCREEN_READER` 環境變數設定為 `1`。在 Bash 或 Zsh 中，執行 `export CLAUDE_AX_SCREEN_READER=1`；在 PowerShell 中，執行 `$env:CLAUDE_AX_SCREEN_READER = "1"`。將該行新增至您的 shell 設定檔以涵蓋每個 shell。

~~25* 針對機器上的每個工作階段：將 `"axScreenReader": true` 新增至您的使用者[設定檔](/zh-TW/settings)。這涵蓋任何終端，包括 VS Code 整合終端。~~25* 針對機器上的每個工作階段：將 `"axScreenReader": true` 新增至您的使用者[設定檔](/docs/zh-TW/settings)。這涵蓋任何終端，包括 VS Code 整合終端。

26 26

27<Note>27<Note>

28 這些方法按優先順序列出：[`--ax-screen-reader`](/zh-TW/cli-reference#cli-flags) 旗標會覆寫 [`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 環境變數，而環境變數會覆寫 [`axScreenReader`](/zh-TW/settings#available-settings) 設定。28 這些方法按優先順序列出：[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標會覆寫 [`CLAUDE_AX_SCREEN_READER`](/docs/zh-TW/env-vars) 環境變數，而環境變數會覆寫 [`axScreenReader`](/docs/zh-TW/settings#available-settings) 設定。

29</Note>29</Note>

30 30

31如果您透過 SSH 使用 Claude Code，請在執行 Claude Code 的遠端機器上設定環境變數或設定。31如果您透過 SSH 使用 Claude Code，請在執行 Claude Code 的遠端機器上設定環境變數或設定。

32 32

33當模式開啟時，Claude Code 列印的第一件事是確認行，命名開啟它的方法：`[Screen Reader Mode: on via flag]`、`[Screen Reader Mode: on via env]` 或 `[Screen Reader Mode: on via settings]`。此方法命名格式需要 Claude Code v2.1.206 或更新版本。當 Claude Code 重新啟動自身時（例如完成安裝更新），新程序會透過 `CLAUDE_AX_SCREEN_READER` 環境變數繼承該模式，因此其確認行會讀取 `[Screen Reader Mode: on via env]`，無論您使用了哪種方法。33當模式開啟時，Claude Code 列印的第一件事是確認行，命名開啟它的方法：`[Screen Reader Mode: on via flag]`、`[Screen Reader Mode: on via env]` 或 `[Screen Reader Mode: on via settings]`。此方法命名格式需要 Claude Code v2.1.206 或更新版本。當 Claude Code 重新啟動自身時（例如完成安裝更新），新程序會透過 `CLAUDE_AX_SCREEN_READER` 環境變數繼承該模式，因此其確認行會讀取 `[Screen Reader Mode: on via env]`，無論您使用了哪種方法。

~~34{/* max-version: 2.1.205 */}較早版本會列印 `[Accessible screen reader mode: on]`。~~34較早版本會列印 `[Accessible screen reader mode: on]`。

35 35

36<h2 id="turn-off-screen-reader-mode">36<h2 id="turn-off-screen-reader-mode">

37 關閉螢幕閱讀器模式37 關閉螢幕閱讀器模式

48* 介面 chrome 沒有方框繪製字元48* 介面 chrome 沒有方框繪製字元

49* 沒有僅限顏色的提示49* 沒有僅限顏色的提示

50* 沒有未變更內容的重繪；進度微調器呈現為靜態文字50* 沒有未變更內容的重繪；進度微調器呈現為靜態文字

51* Claude 回覆中的表格讀作 `Header: value` 句子而不是方框字元網格。{/* min-version: 2.1.198 */}需要 Claude Code v2.1.198 或更新版本；較早版本即使在螢幕閱讀器模式下也會將表格繪製為網格。51* Claude 回覆中的表格讀作 `Header: value` 句子而不是方框字元網格。需要 Claude Code v2.1.198 或更新版本；較早版本即使在螢幕閱讀器模式下也會將表格繪製為網格。

52 52

53輸出會累積在您終端的回滾中，因此您可以使用螢幕閱讀器的檢查命令或終端的搜尋功能重新閱讀較早的回合。53輸出會累積在您終端的回滾中，因此您可以使用螢幕閱讀器的檢查命令或終端的搜尋功能重新閱讀較早的回合。

54 54

55螢幕閱讀器模式呈現為純滾動文字，即使您已使用 [`tui` 設定](/zh-TW/settings#available-settings)開啟[全螢幕呈現](/zh-TW/fullscreen)；當模式啟用時，該設定無效。附加的背景工作階段仍會全螢幕呈現；請參閱[已知限制](#known-limitations)。55螢幕閱讀器模式呈現為純滾動文字，即使您已使用 [`tui` 設定](/docs/zh-TW/settings#available-settings)開啟[全螢幕呈現](/docs/zh-TW/fullscreen)；當模式啟用時，該設定無效。附加的背景工作階段仍會全螢幕呈現；請參閱[已知限制](#known-limitations)。

56 56

57文字記錄中的每條訊息都以標籤開頭，您的螢幕閱讀器會宣佈該標籤，命名其內容：您的訊息、Claude 的回覆、工具活動、錯誤和提示。這些標籤也可搜尋，因此您可以透過搜尋終端的回滾在文字記錄的各個部分之間跳躍：57文字記錄中的每條訊息都以標籤開頭，您的螢幕閱讀器會宣佈該標籤，命名其內容：您的訊息、Claude 的回覆、工具活動、錯誤和提示。這些標籤也可搜尋，因此您可以透過搜尋終端的回滾在文字記錄的各個部分之間跳躍：

58 58

64| `tool error:` | 失敗的工具 |64| `tool error:` | 失敗的工具 |

65| `error:` | 對話中的錯誤，例如失敗的 API 請求 |65| `error:` | 對話中的錯誤，例如失敗的 API 請求 |

66| `Permission Required:` | 等待您回答的權限提示 |66| `Permission Required:` | 等待您回答的權限提示 |

68 68

69終端游標跟隨輸入插入符號，因此螢幕閱讀器的讀取目前行命令會以您正在編輯的提示回答「我在哪裡」。69終端游標跟隨輸入插入符號，因此螢幕閱讀器的讀取目前行命令會以您正在編輯的提示回答「我在哪裡」。

70 70

102* 出現權限提示102* 出現權限提示

103* 執行時間超過 5 秒的工具完成103* 執行時間超過 5 秒的工具完成

104 104

105鈴聲是您終端的標準警報。若要將其靜音，請變更您終端應用程式中的鈴聲設定。鈴聲不需要螢幕閱讀器模式：在模式外，將 [`preferredNotifChannel`](/zh-TW/settings#available-settings) 設定為 `"terminal_bell"` 以在 Claude 等待您時獲得類似警報。請參閱[取得終端鈴聲或通知](/zh-TW/terminal-config#get-a-terminal-bell-or-notification)。105鈴聲是您終端的標準警報。若要將其靜音，請變更您終端應用程式中的鈴聲設定。鈴聲不需要螢幕閱讀器模式：在模式外，將 [`preferredNotifChannel`](/docs/zh-TW/settings#available-settings) 設定為 `"terminal_bell"` 以在 Claude 等待您時獲得類似警報。請參閱[取得終端鈴聲或通知](/docs/zh-TW/terminal-config#get-a-terminal-bell-or-notification)。

106 106

107<h2 id="accessibility-settings-beyond-screen-reader-mode">107<h2 id="accessibility-settings-beyond-screen-reader-mode">

108 螢幕閱讀器模式以外的無障礙設定108 螢幕閱讀器模式以外的無障礙設定

110 110

111這些選項可解決螢幕閱讀器模式以外的無障礙需求。它們都可與其一起使用。111這些選項可解決螢幕閱讀器模式以外的無障礙需求。它們都可與其一起使用。

112 112

113* `CLAUDE_CODE_ACCESSIBILITY` [環境變數](/zh-TW/env-vars)適用於螢幕放大鏡。設定 `CLAUDE_CODE_ACCESSIBILITY=1` 以保持原生終端游標可見，以便放大鏡（例如 macOS Zoom）可以追蹤游標位置。113* `CLAUDE_CODE_ACCESSIBILITY` [環境變數](/docs/zh-TW/env-vars)適用於螢幕放大鏡。設定 `CLAUDE_CODE_ACCESSIBILITY=1` 以保持原生終端游標可見，以便放大鏡（例如 macOS Zoom）可以追蹤游標位置。

114* `prefersReducedMotion` [設定](/zh-TW/settings#available-settings)可減少或停用微調器、閃爍和其他動畫，而不會變更介面的其餘部分。114* `prefersReducedMotion` [設定](/docs/zh-TW/settings#available-settings)可減少或停用微調器、閃爍和其他動畫，而不會變更介面的其餘部分。

115* `theme` [設定](/zh-TW/settings#available-settings)選擇介面顏色，包括色盲友善的 `dark-daltonized` 和 `light-daltonized` 主題。115* `theme` [設定](/docs/zh-TW/settings#available-settings)選擇介面顏色，包括色盲友善的 `dark-daltonized` 和 `light-daltonized` 主題。

116 116

117<h2 id="known-limitations">117<h2 id="known-limitations">

118 已知限制118 已知限制

121某些行為未針對螢幕閱讀器模式進行調整：121某些行為未針對螢幕閱讀器模式進行調整：

122 122

123* 當螢幕閱讀器執行時，螢幕閱讀器模式不會自動開啟。123* 當螢幕閱讀器執行時，螢幕閱讀器模式不會自動開啟。

124* 模式變更（例如進入[計畫模式](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)）尚未宣佈。124* 模式變更（例如進入[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)）尚未宣佈。

125* 使用 `claude attach` 或從代理檢視附加到[背景工作階段](/zh-TW/agent-view)會進入終端的替代螢幕，該螢幕沒有原生回滾。這與[其他附加工作階段的行為相同](/zh-TW/fullscreen)。若要返回，請在空提示上按左箭頭，或如果對話框有焦點，請按 Ctrl+Z。125* 使用 `claude attach` 或從代理檢視附加到[背景工作階段](/docs/zh-TW/agent-view)會進入終端的替代螢幕，該螢幕沒有原生回滾。這與[其他附加工作階段的行為相同](/docs/zh-TW/fullscreen)。若要返回，請在空提示上按左箭頭，或如果對話框有焦點，請按 Ctrl+Z。

126* Claude Code 在其在結束時列印的摘要中宣佈成本，而不是按回合。126* Claude Code 在其在結束時列印的摘要中宣佈成本，而不是按回合。

127* 螢幕閱讀器模式不會使用 `-p` 旗標變更[非互動模式](/zh-TW/headless)。非互動模式已寫入純文字，並保持為指令碼的替代方案。127* 螢幕閱讀器模式不會使用 `-p` 旗標變更[非互動模式](/docs/zh-TW/headless)。非互動模式已寫入純文字，並保持為指令碼的替代方案。

128 128

129<h2 id="report-an-issue">129<h2 id="report-an-issue">

130 報告問題130 報告問題

138 138

139這些頁面包含此頁面涵蓋內容的完整參考項目和相關設定：139這些頁面包含此頁面涵蓋內容的完整參考項目和相關設定：

140 140

141* [設定](/zh-TW/settings#available-settings)：`axScreenReader`、`prefersReducedMotion`、`theme` 和 `preferredNotifChannel` 項目141* [設定](/docs/zh-TW/settings#available-settings)：`axScreenReader`、`prefersReducedMotion`、`theme` 和 `preferredNotifChannel` 項目

142* [環境變數](/zh-TW/env-vars)：`CLAUDE_AX_SCREEN_READER` 和 `CLAUDE_CODE_ACCESSIBILITY` 項目142* [環境變數](/docs/zh-TW/env-vars)：`CLAUDE_AX_SCREEN_READER` 和 `CLAUDE_CODE_ACCESSIBILITY` 項目

143* [CLI 參考](/zh-TW/cli-reference#cli-flags)：`--ax-screen-reader` 旗標143* [CLI 參考](/docs/zh-TW/cli-reference#cli-flags)：`--ax-screen-reader` 旗標

144* [終端配置](/zh-TW/terminal-config)：螢幕閱讀器模式外的鈴聲、通知和主題144* [終端配置](/docs/zh-TW/terminal-config)：螢幕閱讀器模式外的鈴聲、通知和主題

145* [非互動模式](/zh-TW/headless)：指令碼化 `claude -p` 執行，不使用螢幕閱讀器模式寫入純文字145* [非互動模式](/docs/zh-TW/headless)：指令碼化 `claude -p` 執行，不使用螢幕閱讀器模式寫入純文字

advisor.md +17 −17

Details

22 22

23顧問適合長期、多步驟的任務，其中大多數輪次是例行的，但計畫品質決定結果。範例包括大型重構、錯誤不斷重複的除錯會話，以及您希望在 Claude 宣佈完成前獨立檢查的任務。23顧問適合長期、多步驟的任務，其中大多數輪次是例行的，但計畫品質決定結果。範例包括大型重構、錯誤不斷重複的除錯會話，以及您希望在 Claude 宣佈完成前獨立檢查的任務。

24 24

25在短期任務（幾乎沒有計畫空間）或每個輪次都需要最強模型的工作上，它的價值較少。對於這些情況，[切換主要模型](/zh-TW/model-config#setting-your-model)，或查看[顧問與 opusplan 和子代理的比較](#compare-with-related-features)以了解獲取第二意見的其他方式。25在短期任務（幾乎沒有計畫空間）或每個輪次都需要最強模型的工作上，它的價值較少。對於這些情況，[切換主要模型](/docs/zh-TW/model-config#setting-your-model)，或查看[顧問與 opusplan 和子代理的比較](#compare-with-related-features)以了解獲取第二意見的其他方式。

26 26

27<h2 id="enable-the-advisor">27<h2 id="enable-the-advisor">

28 啟用顧問28 啟用顧問

31您可以透過三種方式設定顧問模型：31您可以透過三種方式設定顧問模型：

32 32

33* **`/advisor` 命令**：在會話中途設定或變更顧問，並將其儲存為預設值33* **`/advisor` 命令**：在會話中途設定或變更顧問，並將其儲存為預設值

~~34* **`advisorModel` 設定**：在您的[設定檔](/zh-TW/settings)中配置持久預設值~~34* **`advisorModel` 設定**：在您的[設定檔](/docs/zh-TW/settings)中配置持久預設值

35* **`--advisor` 旗標**：在啟動時為單一會話設定顧問35* **`--advisor` 旗標**：在啟動時為單一會話設定顧問

36 36

37如果其中任何一個設定了顧問模型，則對於主要模型[支援它](#choose-an-advisor-model)的會話，顧問會被啟用。若要停止使用它，請參閱[關閉顧問](#turn-the-advisor-off)。37如果其中任何一個設定了顧問模型，則對於主要模型[支援它](#choose-an-advisor-model)的會話，顧問會被啟用。若要停止使用它，請參閱[關閉顧問](#turn-the-advisor-off)。

38 38

39<Note>39<Note>

~~40 若要使用 Fable 5 作為顧問，您需要 Claude Code v2.1.170 或更新版本以及您的組織的 [Fable 5 存取權](/zh-TW/model-config#work-with-fable-5)。~~40 若要使用 Fable 5 作為顧問，您需要 Claude Code v2.1.170 或更新版本以及您的組織的 [Fable 5 存取權](/docs/zh-TW/model-config#work-with-fable-5)。

41</Note>41</Note>

42 42

43<h3 id="use-the-/advisor-command">43<h3 id="use-the-/advisor-command">

50/advisor opus50/advisor opus

51```51```

52 52

53您的選擇會儲存到使用者設定中的 `advisorModel`，並在會話間保持。如果您組織的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單排除了已儲存的顧問模型，則顧問不會被叫用，直到您使用 `/advisor` 選擇允許的模型。如果您目前的主要模型不支援顧問，選擇仍會被儲存，並在您使用 [`/model`](/zh-TW/model-config#setting-your-model) 切換到[相容的主要模型](#choose-an-advisor-model)時啟動。53您的選擇會儲存到使用者設定中的 `advisorModel`，並在會話間保持。如果您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除了已儲存的顧問模型，則顧問不會被叫用，直到您使用 `/advisor` 選擇允許的模型。如果您目前的主要模型不支援顧問，選擇仍會被儲存，並在您使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 切換到[相容的主要模型](#choose-an-advisor-model)時啟動。

54 54

55<h3 id="set-advisormodel-in-settings">55<h3 id="set-advisormodel-in-settings">

56 在設定中設定 `advisorModel`56 在設定中設定 `advisorModel`

74claude --advisor opus74claude --advisor opus

75```75```

76 76

77該旗標在該會話中優先於 `advisorModel` 設定。如果會話的主要模型不支援顧問，或如果要求的顧問模型被您組織的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單排除，它會以錯誤退出。77該旗標在該會話中優先於 `advisorModel` 設定。如果會話的主要模型不支援顧問，或如果要求的顧問模型被您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除，它會以錯誤退出。

78 78

79<h2 id="choose-an-advisor-model">79<h2 id="choose-an-advisor-model">

80 選擇顧問模型80 選擇顧問模型

83顧問的能力必須至少與主要模型相同。每個主要模型接受的顧問為：83顧問的能力必須至少與主要模型相同。每個主要模型接受的顧問為：

84 84

85| 主要模型 | 接受的顧問 | 備註 |85| 主要模型 | 接受的顧問 | 備註 |

~~86| ----------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------- |~~86| ------------------- | ----------------------- | -------------------------------------------------------------------------------------- |

88| Sonnet 4.6 | Fable、Opus、Sonnet | |88| Sonnet 4.6 | Fable、Opus、Sonnet | |

~~92| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 或 Sonnet 顧問會被拒絕 |~~92| Fable 5 (v2.1.170+) | Fable | Opus 或 Sonnet 顧問會被拒絕 |

93 93

94Fable 5 需要 Claude Code v2.1.170 或更新版本以及 Fable 5 存取權，無論它是充當主要模型還是顧問。94Fable 5 需要 Claude Code v2.1.170 或更新版本以及 Fable 5 存取權，無論它是充當主要模型還是顧問。

95 95

141 141

142每個顧問呼叫都會將對話發送到顧問模型，因此除了主要模型的使用外，還會以顧問模型的費率消耗代幣。使用 API 計費時，顧問代幣按顧問模型的輸入和輸出費率計費。在訂閱計畫上，顧問使用計入您計畫的使用限制。142每個顧問呼叫都會將對話發送到顧問模型，因此除了主要模型的使用外，還會以顧問模型的費率消耗代幣。使用 API 計費時，顧問代幣按顧問模型的輸入和輸出費率計費。在訂閱計畫上，顧問使用計入您計畫的使用限制。

143 143

144Claude 在決策點而非每個輪次都呼叫顧問，因此將更快的主要模型與更強大的顧問配對通常比全程執行更強大的模型成本更低。顧問使用計入 [`/usage`](/zh-TW/costs#track-your-costs) 顯示的會話總計。144Claude 在決策點而非每個輪次都呼叫顧問，因此將更快的主要模型與更強大的顧問配對通常比全程執行更強大的模型成本更低。顧問使用計入 [`/usage`](/docs/zh-TW/costs#track-your-costs) 顯示的會話總計。

145 145

146有關顧問代幣如何在 API 回應中報告的資訊，請參閱 Claude API 文件中的[使用和計費](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing)。146有關顧問代幣如何在 API 回應中報告的資訊，請參閱 Claude API 文件中的[使用和計費](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing)。

147 147

149 對提示快取的影響149 對提示快取的影響

150</h2>150</h2>

151 151

152在會話中途啟用或停用顧問不會使主要模型的[提示快取](/zh-TW/prompt-caching)失效。與[變更模型或努力等級](/zh-TW/prompt-caching#actions-that-invalidate-the-cache)不同，切換 `/advisor` 會保持快取的前綴完整，顧問返回的指導會在後續輪次中作為文字記錄的一部分被快取。152在會話中途啟用或停用顧問不會使主要模型的[提示快取](/docs/zh-TW/prompt-caching)失效。與[變更模型或努力等級](/docs/zh-TW/prompt-caching#actions-that-invalidate-the-cache)不同，切換 `/advisor` 會保持快取的前綴完整，顧問返回的指導會在後續輪次中作為文字記錄的一部分被快取。

153 153

154顧問模型自身對對話的讀取不會被快取。每個顧問呼叫都會全新處理完整的文字記錄，呼叫之間沒有重複使用。154顧問模型自身對對話的讀取不會被快取。每個顧問呼叫都會全新處理完整的文字記錄，呼叫之間沒有重複使用。

155 155

159 159

160顧問工具需要以下所有條件：160顧問工具需要以下所有條件：

161 161

162* **僅限 Anthropic API**：顧問是伺服器執行的工具。它在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。透過配置有 `ANTHROPIC_BASE_URL` 的 [LLM 閘道](/zh-TW/llm-gateway)，可用性取決於閘道是否將請求完整轉發到 Anthropic API。162* **僅限 Anthropic API**：顧問是伺服器執行的工具。它在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。透過配置有 `ANTHROPIC_BASE_URL` 的 [LLM 閘道](/docs/zh-TW/llm-gateway)，可用性取決於閘道是否將請求完整轉發到 Anthropic API。

163* **支援的主要模型**：Opus 4.6 或更新版本、Sonnet 4.6 或更新版本，或 Haiku 4.5。{/* min-version: 2.1.170 */}Fable 5 在 Claude Code v2.1.170 或更新版本上也符合條件。163* **支援的主要模型**：Opus 4.6 或更新版本、Sonnet 4.6 或更新版本，或 Haiku 4.5。Fable 5 在 Claude Code v2.1.170 或更新版本上也符合條件。

164 164

165<h2 id="turn-the-advisor-off">165<h2 id="turn-the-advisor-off">

166 關閉顧問166 關閉顧問

172/advisor off172/advisor off

173```173```

174 174

175若要完全停用顧問工具，設定 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`。`/advisor` 命令變為無法使用，任何已設定的 `advisorModel` 都會被忽略。`--advisor` 旗標被接受但沒有效果；傳遞它的現有指令碼會繼續運作而不會出現錯誤。請參閱[環境變數](/zh-TW/env-vars)。175若要完全停用顧問工具，設定 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`。`/advisor` 命令變為無法使用，任何已設定的 `advisorModel` 都會被忽略。`--advisor` 旗標被接受但沒有效果；傳遞它的現有指令碼會繼續運作而不會出現錯誤。請參閱[環境變數](/docs/zh-TW/env-vars)。

176 176

177<h2 id="compare-with-related-features">177<h2 id="compare-with-related-features">

178 與相關功能的比較178 與相關功能的比較

183| 方法 | 更強大的模型何時執行 | 如何啟動 |183| 方法 | 更強大的模型何時執行 | 如何啟動 |

184| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------- |184| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------- |

186| [`opusplan`](/zh-TW/model-config#opusplan-model-setting) | 在計畫模式期間（當 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許時），然後切換到 Sonnet 以執行 | 您進入計畫模式 |186| [`opusplan`](/docs/zh-TW/model-config#opusplan-model-setting) | 在計畫模式期間（當 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許時），然後切換到 Sonnet 以執行 | 您進入計畫模式 |

189 189

190<h2 id="see-also">190<h2 id="see-also">

191 另請參閱191 另請參閱

192</h2>192</h2>

193 193

194* [模型配置](/zh-TW/model-config)：切換模型、設定努力等級並使用 `opusplan`194* [模型配置](/docs/zh-TW/model-config)：切換模型、設定努力等級並使用 `opusplan`

195* [有效管理成本](/zh-TW/costs)：跨模型追蹤代幣使用195* [有效管理成本](/docs/zh-TW/costs)：跨模型追蹤代幣使用

196* [Claude API 中的顧問工具](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)：了解基礎伺服器工具，或直接從 Messages API 使用它196* [Claude API 中的顧問工具](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)：了解基礎伺服器工具，或直接從 Messages API 使用它

197* [顧問策略](https://claude.com/blog/the-advisor-strategy)：為什麼將快速主要模型與更強大的顧問配對有效197* [顧問策略](https://claude.com/blog/the-advisor-strategy)：為什麼將快速主要模型與更強大的顧問配對有效

agent-sdk/hooks.md +21 −21

Details

26 </Step>26 </Step>

27 27

28 <Step title="SDK 收集已註冊的 hooks">28 <Step title="SDK 收集已註冊的 hooks">

29 SDK 檢查為該事件類型註冊的 hooks。這包括您在 `options.hooks` 中傳遞的回調 hooks 和來自設定檔案的 shell 命令 hooks，當相應的 [`settingSources`](/zh-TW/agent-sdk/typescript#settingsource) 或 [`setting_sources`](/zh-TW/agent-sdk/python#settingsource) 項目啟用時（預設 `query()` 選項就是這樣）。29 SDK 檢查為該事件類型註冊的 hooks。這包括您在 `options.hooks` 中傳遞的回調 hooks 和來自設定檔案的 shell 命令 hooks，當相應的 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#settingsource) 或 [`setting_sources`](/docs/zh-TW/agent-sdk/python#settingsource) 項目啟用時（預設 `query()` 選項就是這樣）。

30 </Step>30 </Step>

31 31

32 <Step title="匹配器篩選哪些 hooks 執行">32 <Step title="匹配器篩選哪些 hooks 執行">

155| `PostToolUseFailure` | 是 | 是 | 工具執行失敗 | 處理或記錄工具錯誤 |155| `PostToolUseFailure` | 是 | 是 | 工具執行失敗 | 處理或記錄工具錯誤 |

156| `PostToolBatch` | 否 | 是 | 一整批工具呼叫解決，每批一次，在下一個模型呼叫之前 | 為整個批次注入約定 |156| `PostToolBatch` | 否 | 是 | 一整批工具呼叫解決，每批一次，在下一個模型呼叫之前 | 為整個批次注入約定 |

157| `UserPromptSubmit` | 是 | 是 | 使用者提示提交 | 將額外上下文注入提示 |157| `UserPromptSubmit` | 是 | 是 | 使用者提示提交 | 將額外上下文注入提示 |

158| [`UserPromptExpansion`](/zh-TW/hooks#userpromptexpansion) | 否 | 是 | 使用者輸入的命令在到達 Claude 之前擴展為提示 | 阻止命令直接呼叫或在輸入技能時新增上下文 |158| [`UserPromptExpansion`](/docs/zh-TW/hooks#userpromptexpansion) | 否 | 是 | 使用者輸入的命令在到達 Claude 之前擴展為提示 | 阻止命令直接呼叫或在輸入技能時新增上下文 |

159| `MessageDisplay` | 否 | 是 | 助手訊息包含文字完成，每則訊息一次，包含完整訊息文字 | 編輯或重新格式化顯示的文字，不改變記錄 |159| `MessageDisplay` | 否 | 是 | 助手訊息包含文字完成，每則訊息一次，包含完整訊息文字 | 編輯或重新格式化顯示的文字，不改變記錄 |

160| `Stop` | 是 | 是 | 代理執行停止 | 在退出前保存會話狀態 |160| `Stop` | 是 | 是 | 代理執行停止 | 在退出前保存會話狀態 |

161| `SubagentStart` | 是 | 是 | 子代理初始化 | 追蹤平行任務生成 |161| `SubagentStart` | 是 | 是 | 子代理初始化 | 追蹤平行任務生成 |

213 匹配器213 匹配器

214</h3>214</h3>

215 215

216使用匹配器篩選您的回調何時觸發。`matcher` 欄位根據 hook 事件類型匹配不同的值。例如，工具型 hooks 匹配工具名稱，而 `Notification` hooks 匹配通知類型。請參閱 [Claude Code hooks 參考](/zh-TW/hooks#matcher-patterns)以取得每個事件類型的完整匹配器值列表。216使用匹配器篩選您的回調何時觸發。`matcher` 欄位根據 hook 事件類型匹配不同的值。例如，工具型 hooks 匹配工具名稱，而 `Notification` hooks 匹配通知類型。請參閱 [Claude Code hooks 參考](/docs/zh-TW/hooks#matcher-patterns)以取得每個事件類型的完整匹配器值列表。

217 217

218SDK 匹配器遵循與[設定檔案中的匹配器](/zh-TW/hooks#matcher-patterns)相同的規則。只包含字母、數字、`_`、`-`、空格、`,` 和 `|` 的匹配器會被比較為精確字串，其中替代項由 `|` 或 `,` 分隔，並可選擇周圍空格，因此 `Write|Edit` 和 `Write, Edit` 各自精確匹配這兩個工具，而 `code-reviewer` 只匹配該代理類型。匹配器 `*`、空字串或完全省略匹配器會匹配事件的每次出現。218SDK 匹配器遵循與[設定檔案中的匹配器](/docs/zh-TW/hooks#matcher-patterns)相同的規則。只包含字母、數字、`_`、`-`、空格、`,` 和 `|` 的匹配器會被比較為精確字串，其中替代項由 `|` 或 `,` 分隔，並可選擇周圍空格，因此 `Write|Edit` 和 `Write, Edit` 各自精確匹配這兩個工具，而 `code-reviewer` 只匹配該代理類型。匹配器 `*`、空字串或完全省略匹配器會匹配事件的每次出現。

219 219

220包含任何其他字元的匹配器會被評估為未錨定的正規表達式，因此 `^mcp__` 匹配每個 MCP 工具，而 `Edit.*` 同時匹配 `Edit` 和 `NotebookEdit`。當您需要全字符串匹配時，請用 `^` 和 `$` 包裝正規表達式。220包含任何其他字元的匹配器會被評估為未錨定的正規表達式，因此 `^mcp__` 匹配每個 MCP 工具，而 `Edit.*` 同時匹配 `Edit` 和 `NotebookEdit`。當您需要全字符串匹配時，請用 `^` 和 `$` 包裝正規表達式。

221 221

225 225

226| 選項 | 類型 | 預設值 | 描述 |226| 選項 | 類型 | 預設值 | 描述 |

227| --------- | ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |227| --------- | ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

228| `matcher` | `string` | `undefined` | 針對事件的篩選欄位匹配的模式，遵循上述比較規則。對於工具 hooks，這是工具名稱。內建工具包括 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`、`WebFetch`、`Agent` 等（請參閱[工具輸入類型](/zh-TW/agent-sdk/typescript#tool-input-types)以取得完整列表）。MCP 工具使用模式 `mcp__<server>__<action>`。 |228| `matcher` | `string` | `undefined` | 針對事件的篩選欄位匹配的模式，遵循上述比較規則。對於工具 hooks，這是工具名稱。內建工具包括 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`、`WebFetch`、`Agent` 等（請參閱[工具輸入類型](/docs/zh-TW/agent-sdk/typescript#tool-input-types)以取得完整列表）。MCP 工具使用模式 `mcp__<server>__<action>`。 |

231 231

234對於工具型 hooks，匹配器只按工具名稱篩選，不按檔案路徑或其他參數篩選。要按檔案路徑篩選，請在回調內檢查 `tool_input.file_path`。234對於工具型 hooks，匹配器只按工具名稱篩選，不按檔案路徑或其他參數篩選。要按檔案路徑篩選，請在回調內檢查 `tool_input.file_path`。

235 235

236<Tip>236<Tip>

237 **發現工具名稱：** 請參閱[工具輸入類型](/zh-TW/agent-sdk/typescript#tool-input-types)以取得內建工具名稱的完整列表，或新增沒有匹配器的 hook 以記錄您的會話進行的所有工具呼叫。237 **發現工具名稱：** 請參閱[工具輸入類型](/docs/zh-TW/agent-sdk/typescript#tool-input-types)以取得內建工具名稱的完整列表，或新增沒有匹配器的 hook 以記錄您的會話進行的所有工具呼叫。

238 238

239 **MCP 工具命名：** MCP 工具始終以 `mcp__` 開頭，後跟伺服器名稱和操作：`mcp__<server>__<action>`。例如，如果您配置名為 `playwright` 的伺服器，其工具將被命名為 `mcp__playwright__browser_screenshot`、`mcp__playwright__browser_click` 等。伺服器名稱來自您在 `mcpServers` 配置中使用的鍵。239 **MCP 工具命名：** MCP 工具始終以 `mcp__` 開頭，後跟伺服器名稱和操作：`mcp__<server>__<action>`。例如，如果您配置名為 `playwright` 的伺服器，其工具將被命名為 `mcp__playwright__browser_screenshot`、`mcp__playwright__browser_click` 等。伺服器名稱來自您在 `mcpServers` 配置中使用的鍵。

240</Tip>240</Tip>

249 249

250每個 hook 回調接收三個參數：250每個 hook 回調接收三個參數：

251 251

252* **輸入資料：** 一個包含事件詳細資訊的類型物件。每個 hook 類型都有自己的輸入形狀。例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`。請參閱 [TypeScript](/zh-TW/agent-sdk/typescript#hookinput) 和 [Python](/zh-TW/agent-sdk/python#hookinput) SDK 參考中的完整類型定義。252* **輸入資料：** 一個包含事件詳細資訊的類型物件。每個 hook 類型都有自己的輸入形狀。例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`。請參閱 [TypeScript](/docs/zh-TW/agent-sdk/typescript#hookinput) 和 [Python](/docs/zh-TW/agent-sdk/python#hookinput) SDK 參考中的完整類型定義。

253 * 所有 hook 輸入共享 `session_id`、`cwd` 和 `hook_event_name`。253 * 所有 hook 輸入共享 `session_id`、`cwd` 和 `hook_event_name`。

254 * 當 hook 在子代理內觸發時，`agent_id` 和 `agent_type` 會被填充。在 TypeScript 中，這些在基本 hook 輸入上，可供所有 hook 類型使用。在 Python 中，它們是 `PreToolUse`、`PostToolUse`、`PostToolUseFailure` 和 `PermissionRequest` 上的可選欄位，以及 `SubagentStart` 和 `SubagentStop` 上的必需欄位。254 * 當 hook 在子代理內觸發時，`agent_id` 和 `agent_type` 會被填充。在 TypeScript 中，這些在基本 hook 輸入上，可供所有 hook 類型使用。在 Python 中，它們是 `PreToolUse`、`PostToolUse`、`PostToolUseFailure` 和 `PermissionRequest` 上的可選欄位，以及 `SubagentStart` 和 `SubagentStop` 上的必需欄位。

255* **工具使用 ID**（`str | None` / `string | undefined`）：關聯同一工具呼叫的 `PreToolUse` 和 `PostToolUse` 事件。255* **工具使用 ID**（`str | None` / `string | undefined`）：關聯同一工具呼叫的 `PreToolUse` 和 `PostToolUse` 事件。

262您的回調返回一個具有兩類欄位的物件：262您的回調返回一個具有兩類欄位的物件：

263 263

264* **頂級欄位**在每個事件上的工作方式相同：`systemMessage` 向使用者顯示訊息，`continue`（Python 中的 `continue_`）決定此 hook 後代理是否繼續執行。264* **頂級欄位**在每個事件上的工作方式相同：`systemMessage` 向使用者顯示訊息，`continue`（Python 中的 `continue_`）決定此 hook 後代理是否繼續執行。

265* **`hookSpecificOutput`** 控制目前操作。內部的欄位取決於 hook 事件類型。對於 `PreToolUse` hooks，這是您設定 `permissionDecision`（`"allow"`、`"deny"`、`"ask"` 或 `"defer"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。返回 `"defer"` 會結束查詢，以便您可以[稍後繼續](/zh-TW/hooks#defer-a-tool-call-for-later)。對於 `PostToolUse` hooks，您可以設定 `additionalContext` 以將資訊附加到工具結果。要在 Claude 看到之前替換工具的輸出，請設定 `updatedToolOutput`，這適用於兩個 SDK 中的任何工具。較舊的 `updatedMCPToolOutput` 欄位僅替換 MCP 工具輸出，已被棄用。265* **`hookSpecificOutput`** 控制目前操作。內部的欄位取決於 hook 事件類型。對於 `PreToolUse` hooks，這是您設定 `permissionDecision`（`"allow"`、`"deny"`、`"ask"` 或 `"defer"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。返回 `"defer"` 會結束查詢，以便您可以[稍後繼續](/docs/zh-TW/hooks#defer-a-tool-call-for-later)。對於 `PostToolUse` hooks，您可以設定 `additionalContext` 以將資訊附加到工具結果。要在 Claude 看到之前替換工具的輸出，請設定 `updatedToolOutput`，這適用於兩個 SDK 中的任何工具。較舊的 `updatedMCPToolOutput` 欄位僅替換 MCP 工具輸出，已被棄用。

266 266

267返回 `{}` 以允許操作而不進行變更。SDK 回調 hooks 使用與 [Claude Code shell 命令 hooks](/zh-TW/hooks#json-output) 相同的 JSON 輸出格式，其記錄每個欄位和事件特定選項。對於 SDK 類型定義，請參閱 [TypeScript](/zh-TW/agent-sdk/typescript#synchookjsonoutput) 和 [Python](/zh-TW/agent-sdk/python#synchookjsonoutput) SDK 參考。267返回 `{}` 以允許操作而不進行變更。SDK 回調 hooks 使用與 [Claude Code shell 命令 hooks](/docs/zh-TW/hooks#json-output) 相同的 JSON 輸出格式，其記錄每個欄位和事件特定選項。對於 SDK 類型定義，請參閱 [TypeScript](/docs/zh-TW/agent-sdk/typescript#synchookjsonoutput) 和 [Python](/docs/zh-TW/agent-sdk/python#synchookjsonoutput) SDK 參考。

268 268

269<Note>269<Note>

270 當多個 hooks 或權限規則適用時，`deny` 優先於 `defer`，`defer` 優先於 `ask`，`ask` 優先於 `allow`。如果任何 hook 返回 `deny`，操作將被阻止，無論其他 hooks 如何。270 當多個 hooks 或權限規則適用時，`deny` 優先於 `defer`，`defer` 優先於 `ask`，`ask` 優先於 `allow`。如果任何 hook 返回 `deny`，操作將被阻止，無論其他 hooks 如何。

539 追蹤子代理活動539 追蹤子代理活動

540</h3>540</h3>

541 541

542使用 `SubagentStop` hooks 監控子代理何時完成其工作。請參閱 [TypeScript](/zh-TW/agent-sdk/typescript#hookinput) 和 [Python](/zh-TW/agent-sdk/python#hookinput) SDK 參考中的完整輸入類型。此範例在每次子代理完成時記錄摘要：542使用 `SubagentStop` hooks 監控子代理何時完成其工作。請參閱 [TypeScript](/docs/zh-TW/agent-sdk/typescript#hookinput) 和 [Python](/docs/zh-TW/agent-sdk/python#hookinput) SDK 參考中的完整輸入類型。此範例在每次子代理完成時記錄摘要：

543 543

544<CodeGroup>544<CodeGroup>

545 ```python Python theme={null}545 ```python Python theme={null}

791* 驗證 hook 事件名稱正確且區分大小寫（`PreToolUse`，而不是 `preToolUse`）791* 驗證 hook 事件名稱正確且區分大小寫（`PreToolUse`，而不是 `preToolUse`）

792* 檢查您的匹配器模式是否與工具名稱完全匹配792* 檢查您的匹配器模式是否與工具名稱完全匹配

793* 確保 hook 在 `options.hooks` 中的正確事件類型下793* 確保 hook 在 `options.hooks` 中的正確事件類型下

794* 對於支援匹配器的非工具 hooks，如 `Notification` 和 `SubagentStop`，匹配器匹配不同的欄位，而 `Stop` 完全忽略匹配器（請參閱[匹配器模式](/zh-TW/hooks#matcher-patterns)）794* 對於支援匹配器的非工具 hooks，如 `Notification` 和 `SubagentStop`，匹配器匹配不同的欄位，而 `Stop` 完全忽略匹配器（請參閱[匹配器模式](/docs/zh-TW/hooks#matcher-patterns)）

795* 當代理達到 [`max_turns`](/zh-TW/agent-sdk/python#claudeagentoptions) 限制時，hooks 可能不會觸發，因為會話在 hooks 可以執行前結束795* 當代理達到 [`max_turns`](/docs/zh-TW/agent-sdk/python#claudeagentoptions) 限制時，hooks 可能不會觸發，因為會話在 hooks 可以執行前結束

796 796

797<h3 id="matcher-not-filtering-as-expected">797<h3 id="matcher-not-filtering-as-expected">

798 匹配器未按預期篩選798 匹配器未按預期篩選

818* 增加 `HookMatcher` 配置中的 `timeout` 值818* 增加 `HookMatcher` 配置中的 `timeout` 值

819* 在 TypeScript 中使用第三個回調參數中的 `AbortSignal` 以優雅地處理取消819* 在 TypeScript 中使用第三個回調參數中的 `AbortSignal` 以優雅地處理取消

820 820

821{/* min-version: 2.1.208 */}超過其超時時間的 `UserPromptSubmit` 或 [`UserPromptExpansion`](/zh-TW/hooks#userpromptexpansion) 回調會以超時訊息阻止該提示，會話繼續進行。在回調待處理時中斷查詢會取消待處理的工具呼叫。在 v2.1.208 之前，這些事件上的回調超時會以 `error_during_execution` 結束查詢，在待處理的 `PreToolUse` 回調期間中斷可能會讓工具呼叫繼續進行。821超過其超時時間的 `UserPromptSubmit` 或 [`UserPromptExpansion`](/docs/zh-TW/hooks#userpromptexpansion) 回調會以超時訊息阻止該提示，會話繼續進行。在回調待處理時中斷查詢會取消待處理的工具呼叫。在 v2.1.208 之前，這些事件上的回調超時會以 `error_during_execution` 結束查詢，在待處理的 `PreToolUse` 回調期間中斷可能會讓工具呼叫繼續進行。

822 822

823<h3 id="tool-blocked-unexpectedly">823<h3 id="tool-blocked-unexpectedly">

824 工具意外被阻止824 工具意外被阻止

852 Python 中不可用會話 hooks852 Python 中不可用會話 hooks

853</h3>853</h3>

854 854

855`SessionStart` 和 `SessionEnd` 可以在 TypeScript 中註冊為 SDK 回調 hooks，但在 Python SDK 中不可用，因為其 `HookEvent` 類型省略它們。在 Python 中，它們僅作為[shell 命令 hooks](/zh-TW/hooks#hook-events)在設定檔案中定義，例如 `.claude/settings.json`。要從您的 SDK 應用程式載入 shell 命令 hooks，請使用 [`setting_sources`](/zh-TW/agent-sdk/python#settingsource) 或 [`settingSources`](/zh-TW/agent-sdk/typescript#settingsource) 包括適當的設定來源：855`SessionStart` 和 `SessionEnd` 可以在 TypeScript 中註冊為 SDK 回調 hooks，但在 Python SDK 中不可用，因為其 `HookEvent` 類型省略它們。在 Python 中，它們僅作為[shell 命令 hooks](/docs/zh-TW/hooks#hook-events)在設定檔案中定義，例如 `.claude/settings.json`。要從您的 SDK 應用程式載入 shell 命令 hooks，請使用 [`setting_sources`](/docs/zh-TW/agent-sdk/python#settingsource) 或 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#settingsource) 包括適當的設定來源：

856 856

857<CodeGroup>857<CodeGroup>

858 ```python Python theme={null}858 ```python Python theme={null}

890 systemMessage 未出現在輸出中890 systemMessage 未出現在輸出中

891</h3>891</h3>

892 892

893`systemMessage` 欄位向使用者顯示訊息，而不是模型。預設情況下，SDK 只會在訊息流中呈現 `SessionStart` 和 `Setup` hooks 的 hook 輸出，因此除非您設定 `includeHookEvents`（Python 中的 `include_hook_events`），否則來自任何其他 hook 事件的訊息不會出現。要改為將上下文傳遞給模型，請返回 [`additionalContext`](/zh-TW/hooks#add-context-for-claude)。893`systemMessage` 欄位向使用者顯示訊息，而不是模型。預設情況下，SDK 只會在訊息流中呈現 `SessionStart` 和 `Setup` hooks 的 hook 輸出，因此除非您設定 `includeHookEvents`（Python 中的 `include_hook_events`），否則來自任何其他 hook 事件的訊息不會出現。要改為將上下文傳遞給模型，請返回 [`additionalContext`](/docs/zh-TW/hooks#add-context-for-claude)。

894 894

895如果您需要可靠地將 hook 決定呈現給您的應用程式，請分別記錄它們或使用專用輸出頻道。895如果您需要可靠地將 hook 決定呈現給您的應用程式，請分別記錄它們或使用專用輸出頻道。

896 896

898 相關資源898 相關資源

899</h2>899</h2>

900 900

901* [Claude Code hooks 參考](/zh-TW/hooks)：完整的 JSON 輸入/輸出架構、事件文件和匹配器模式901* [Claude Code hooks 參考](/docs/zh-TW/hooks)：完整的 JSON 輸入/輸出架構、事件文件和匹配器模式

902* [Claude Code hooks 指南](/zh-TW/hooks-guide)：shell 命令 hook 範例和逐步解說902* [Claude Code hooks 指南](/docs/zh-TW/hooks-guide)：shell 命令 hook 範例和逐步解說

903* [TypeScript SDK 參考](/zh-TW/agent-sdk/typescript)：hook 類型、輸入/輸出定義和配置選項903* [TypeScript SDK 參考](/docs/zh-TW/agent-sdk/typescript)：hook 類型、輸入/輸出定義和配置選項

904* [Python SDK 參考](/zh-TW/agent-sdk/python)：hook 類型、輸入/輸出定義和配置選項904* [Python SDK 參考](/docs/zh-TW/agent-sdk/python)：hook 類型、輸入/輸出定義和配置選項

905* [權限](/zh-TW/agent-sdk/permissions)：控制您的代理可以做什麼905* [權限](/docs/zh-TW/agent-sdk/permissions)：控制您的代理可以做什麼

906* [自訂工具](/zh-TW/agent-sdk/custom-tools)：建立工具以擴展代理功能906* [自訂工具](/docs/zh-TW/agent-sdk/custom-tools)：建立工具以擴展代理功能

agent-sdk/permissions.md +25 −25

Details

6 6

7> 使用權限模式、hooks 和宣告式允許/拒絕規則來控制您的代理程式如何使用工具。7> 使用權限模式、hooks 和宣告式允許/拒絕規則來控制您的代理程式如何使用工具。

8 8

9Claude Agent SDK 提供權限控制來管理 Claude 如何使用工具。使用權限模式和規則來定義自動允許的內容，並使用 [`canUseTool` 回呼](/zh-TW/agent-sdk/user-input) 在執行時處理其他所有情況。9Claude Agent SDK 提供權限控制來管理 Claude 如何使用工具。使用權限模式和規則來定義自動允許的內容，並使用 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 在執行時處理其他所有情況。

10 10

11<Note>11<Note>

12 本頁涵蓋權限模式和規則。若要建立互動式核准流程，讓使用者在執行時核准或拒絕工具請求，請參閱 [處理核准和使用者輸入](/zh-TW/agent-sdk/user-input)。12 本頁涵蓋權限模式和規則。若要建立互動式核准流程，讓使用者在執行時核准或拒絕工具請求，請參閱 [處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input)。

13</Note>13</Note>

14 14

15<h2 id="how-permissions-are-evaluated">15<h2 id="how-permissions-are-evaluated">

20 20

21<Steps>21<Steps>

22 <Step title="Hooks">22 <Step title="Hooks">

23 首先執行 [hooks](/zh-TW/agent-sdk/hooks)。Hook 可以直接拒絕呼叫或將其傳遞。返回 `allow` 的 hook 不會跳過下面的拒絕和詢問規則；無論 hook 結果如何，這些規則都會被評估。23 首先執行 [hooks](/docs/zh-TW/agent-sdk/hooks)。Hook 可以直接拒絕呼叫或將其傳遞。返回 `allow` 的 hook 不會跳過下面的拒絕和詢問規則；無論 hook 結果如何，這些規則都會被評估。

24 </Step>24 </Step>

25 25

26 <Step title="拒絕規則">26 <Step title="拒絕規則">

27 檢查 `deny` 規則（來自 `disallowed_tools` 和 [settings.json](/zh-TW/settings#permission-settings)）。如果拒絕規則符合，工具會被阻止，即使在 `bypassPermissions` 模式下也是如此。裸名稱拒絕規則（如 `Bash`）會在此評估開始前將工具從 Claude 的上下文中移除，因此只有範圍規則（如 `Bash(rm *)`）會在此步驟中被檢查。27 檢查 `deny` 規則（來自 `disallowed_tools` 和 [settings.json](/docs/zh-TW/settings#permission-settings)）。如果拒絕規則符合，工具會被阻止，即使在 `bypassPermissions` 模式下也是如此。裸名稱拒絕規則（如 `Bash`）會在此評估開始前將工具從 Claude 的上下文中移除，因此只有範圍規則（如 `Bash(rm *)`）會在此步驟中被檢查。

28 </Step>28 </Step>

29 29

30 <Step title="詢問規則">30 <Step title="詢問規則">

31 檢查來自 [settings.json](/zh-TW/settings#permission-settings) 的 `ask` 規則。如果詢問規則符合，呼叫會傳遞到您的 [`canUseTool` 回呼](/zh-TW/agent-sdk/user-input) 以進行確認，即使在 `bypassPermissions` 模式下也是如此。31 檢查來自 [settings.json](/docs/zh-TW/settings#permission-settings) 的 `ask` 規則。如果詢問規則符合，呼叫會傳遞到您的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 以進行確認，即使在 `bypassPermissions` 模式下也是如此。

32 32

33 需要使用者互動的工具行為相同：`AskUserQuestion` 和 MCP 工具（其伺服器設定 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool)）總是會傳遞到回呼，即使允許規則符合時也是如此。在 `dontAsk` 模式下，兩種情況都會被拒絕，因為該模式永遠不會提示。{/* min-version: 2.1.199 */}MCP 註解需要 Claude Code v2.1.199 或更新版本。33 需要使用者互動的工具行為相同：`AskUserQuestion` 和 MCP 工具（其伺服器設定 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool)）總是會傳遞到回呼，即使允許規則符合時也是如此。在 `dontAsk` 模式下，兩種情況都會被拒絕，因為該模式永遠不會提示。MCP 註解需要 Claude Code v2.1.199 或更新版本。

34 34

35 [claude.ai 連接器](/zh-TW/mcp#organization-controls-on-connector-tools) 工具（您的組織已設定為 `ask`）也會在此步驟離開流程。每個呼叫都會傳遞到回呼，即使在 `bypassPermissions` 模式下，即使允許規則符合時也是如此。回呼會收到原因 `Your organization requires approval for this tool`。在 `dontAsk` 模式下，呼叫會被拒絕，因為該模式永遠不會提示。35 [claude.ai 連接器](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 工具（您的組織已設定為 `ask`）也會在此步驟離開流程。每個呼叫都會傳遞到回呼，即使在 `bypassPermissions` 模式下，即使允許規則符合時也是如此。回呼會收到原因 `Your organization requires approval for this tool`。在 `dontAsk` 模式下，呼叫會被拒絕，因為該模式永遠不會提示。

36 </Step>36 </Step>

37 37

38 <Step title="權限模式">38 <Step title="權限模式">

44 </Step>44 </Step>

45 45

46 <Step title="canUseTool 回呼">46 <Step title="canUseTool 回呼">

47 如果上述任何步驟都未解決，請呼叫您的 [`canUseTool` 回呼](/zh-TW/agent-sdk/user-input) 以做出決定。在 `dontAsk` 模式下，此步驟會被跳過，工具會被拒絕。47 如果上述任何步驟都未解決，請呼叫您的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 以做出決定。在 `dontAsk` 模式下，此步驟會被跳過，工具會被拒絕。

48 </Step>48 </Step>

49</Steps>49</Steps>

50 50

57 57

58具有指定符的項目（例如 `Bash(ls *)`）和 `acceptEdits` 模式不會觸發它，來自設定檔的允許規則對檢查不可見。58具有指定符的項目（例如 `Bash(ls *)`）和 `acceptEdits` 模式不會觸發它，來自設定檔的允許規則對檢查不可見。

59 59

60使用 `process.on('warning', ...)` 進行監聽，並匹配代碼以記錄或抑制它。若要無論模式和規則如何都控制每個工具呼叫，請改用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)。60使用 `process.on('warning', ...)` 進行監聽，並匹配代碼以記錄或抑制它。若要無論模式和規則如何都控制每個工具呼叫，請改用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)。

61 61

62本頁重點關注 **允許和拒絕規則** 以及 **權限模式**。對於其他步驟：62本頁重點關注 **允許和拒絕規則** 以及 **權限模式**。對於其他步驟：

63 63

~~64* **Hooks：** 執行自訂程式碼以允許、拒絕或修改工具請求。請參閱 [使用 hooks 控制執行](/zh-TW/agent-sdk/hooks)。~~64* **Hooks：** 執行自訂程式碼以允許、拒絕或修改工具請求。請參閱 [使用 hooks 控制執行](/docs/zh-TW/agent-sdk/hooks)。

~~65* **canUseTool 回呼：** 在執行時提示使用者核准，當沒有較早的步驟解決呼叫時。請參閱 [處理核准和使用者輸入](/zh-TW/agent-sdk/user-input)。~~65* **canUseTool 回呼：** 在執行時提示使用者核准，當沒有較早的步驟解決呼叫時。請參閱 [處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input)。

66 66

67<h2 id="allow-and-deny-rules">67<h2 id="allow-and-deny-rules">

68 允許和拒絕規則68 允許和拒絕規則

81 81

82`Read` 和 `Edit` 的限定規則採用路徑模式。`Edit(path)` 規則管理所有寫入檔案的內建工具，包括 `Write` 和 `NotebookEdit`；`Write(path)` 規則永遠不會被檔案權限檢查符合。82`Read` 和 `Edit` 的限定規則採用路徑模式。`Edit(path)` 規則管理所有寫入檔案的內建工具，包括 `Write` 和 `NotebookEdit`；`Write(path)` 規則永遠不會被檔案權限檢查符合。

83 83

84使用 `//path` 表示絕對檔案系統路徑：`Edit(//secrets/**)` 的拒絕規則會阻止在磁碟上 `/secrets` 下任何位置的寫入。使用單個前導斜線，`Edit(/secrets/**)` 會在規則的來源處錨定。對於通過 `allowed_tools` 或 `disallowed_tools` 傳遞的規則，這表示工作階段的工作目錄，因此規則不會阻止磁碟上的 `/secrets`。請參閱 [Read 和 Edit 規則](/zh-TW/permissions#read-and-edit) 以了解四種錨定形式以及來自設定檔案的規則如何解析。84使用 `//path` 表示絕對檔案系統路徑：`Edit(//secrets/**)` 的拒絕規則會阻止在磁碟上 `/secrets` 下任何位置的寫入。使用單個前導斜線，`Edit(/secrets/**)` 會在規則的來源處錨定。對於通過 `allowed_tools` 或 `disallowed_tools` 傳遞的規則，這表示工作階段的工作目錄，因此規則不會阻止磁碟上的 `/secrets`。請參閱 [Read 和 Edit 規則](/docs/zh-TW/permissions#read-and-edit) 以了解四種錨定形式以及來自設定檔案的規則如何解析。

85 85

86<Warning>86<Warning>

87 **自動批准的工具永遠不會到達 `canUseTool`。** 在任何較早步驟中批准的工具呼叫，由 `acceptEdits` 或 `bypassPermissions` 或允許規則批准，會跳過您的 `canUseTool` 回呼，因此您在那裡放置的權限檢查會被該工具無聲地略過。`AskUserQuestion`、標記為 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 仍會到達回呼，即使允許規則符合時也是如此。87 **自動批准的工具永遠不會到達 `canUseTool`。** 在任何較早步驟中批准的工具呼叫，由 `acceptEdits` 或 `bypassPermissions` 或允許規則批准，會跳過您的 `canUseTool` 回呼，因此您在那裡放置的權限檢查會被該工具無聲地略過。`AskUserQuestion`、標記為 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 仍會到達回呼，即使允許規則符合時也是如此。

88 88

89 涵蓋範圍取決於條目的形式：像 `Read` 或 `mcp__github__get_issue` 這樣的裸名稱會自動批准對該工具的每個呼叫，而像 `Bash(ls *)` 這樣的限定規則只會自動批准符合的呼叫，其他 `Bash` 呼叫仍會通過回呼。對於必須在每個工具呼叫上執行的檢查，請使用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)：hook 在每個其他步驟之前執行，hook 拒絕甚至在 `bypassPermissions` 模式中也適用。89 涵蓋範圍取決於條目的形式：像 `Read` 或 `mcp__github__get_issue` 這樣的裸名稱會自動批准對該工具的每個呼叫，而像 `Bash(ls *)` 這樣的限定規則只會自動批准符合的呼叫，其他 `Bash` 呼叫仍會通過回呼。對於必須在每個工具呼叫上執行的檢查，請使用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)：hook 在每個其他步驟之前執行，hook 拒絕甚至在 `bypassPermissions` 模式中也適用。

90</Warning>90</Warning>

91 91

92對於鎖定的代理程式，將 `allowedTools` 與 `permissionMode: "dontAsk"` 配對。列出的工具會被批准，除了上述警告中的始終提示工具外；其他任何工具都會被直接拒絕，而不是提示：92對於鎖定的代理程式，將 `allowedTools` 與 `permissionMode: "dontAsk"` 配對。列出的工具會被批准，除了上述警告中的始終提示工具外；其他任何工具都會被直接拒絕，而不是提示：

102 **`allowed_tools` 不會限制 `bypassPermissions`。** `allowed_tools` 只會預先批准您列出的工具。未列出的工具不會被任何允許規則符合，並會通過權限模式，其中 `bypassPermissions` 會批准它們。將 `allowed_tools=["Read"]` 與 `permission_mode="bypassPermissions"` 一起設定仍然會批准每個工具，包括 `Bash`、`Write` 和 `Edit`。如果您需要 `bypassPermissions` 但想要阻止特定工具，請使用 `disallowed_tools`。102 **`allowed_tools` 不會限制 `bypassPermissions`。** `allowed_tools` 只會預先批准您列出的工具。未列出的工具不會被任何允許規則符合，並會通過權限模式，其中 `bypassPermissions` 會批准它們。將 `allowed_tools=["Read"]` 與 `permission_mode="bypassPermissions"` 一起設定仍然會批准每個工具，包括 `Bash`、`Write` 和 `Edit`。如果您需要 `bypassPermissions` 但想要阻止特定工具，請使用 `disallowed_tools`。

103</Warning>103</Warning>

104 104

105您也可以在 `.claude/settings.json` 中宣告式地設定允許、拒絕和詢問規則。當啟用 `project` 設定來源時，這些規則會被讀取，預設 `query()` 選項就是這樣。如果您明確設定 `setting_sources`（TypeScript：`settingSources`），請包含 `"project"` 以便它們適用。請參閱 [權限設定](/zh-TW/settings#permission-settings) 以了解規則語法。105您也可以在 `.claude/settings.json` 中宣告式地設定允許、拒絕和詢問規則。當啟用 `project` 設定來源時，這些規則會被讀取，預設 `query()` 選項就是這樣。如果您明確設定 `setting_sources`（TypeScript：`settingSources`），請包含 `"project"` 以便它們適用。請參閱 [權限設定](/docs/zh-TW/settings#permission-settings) 以了解規則語法。

106 106

107<h2 id="permission-modes">107<h2 id="permission-modes">

108 權限模式108 權限模式

119| 模式 | 描述 | 工具行為 |119| 模式 | 描述 | 工具行為 |

120| :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |120| :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |

122| `dontAsk` | 拒絕而不是提示 | 任何未被 `allowed_tools` 或規則預先批准的內容都會被拒絕；連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具即使您已預先批准它們也會被拒絕。`canUseTool` 永遠不會被呼叫 |122| `dontAsk` | 拒絕而不是提示 | 任何未被 `allowed_tools` 或規則預先批准的內容都會被拒絕；連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具即使您已預先批准它們也會被拒絕。`canUseTool` 永遠不會被呼叫 |

124| `bypassPermissions` | 繞過權限檢查 | 工具執行時無需權限提示，除了明確的[`ask` 規則](#how-permissions-are-evaluated)符合的工具、連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具（謹慎使用） |124| `bypassPermissions` | 繞過權限檢查 | 工具執行時無需權限提示，除了明確的[`ask` 規則](#how-permissions-are-evaluated)符合的工具、連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具（謹慎使用） |

127 127

128<Warning>128<Warning>

129 **子代理程式繼承：** 當父代理程式使用 `bypassPermissions`、`acceptEdits` 或 `auto` 時，所有子代理程式都會繼承該模式，且無法按子代理程式覆蓋。子代理程式可能有不同的系統提示和行為限制較少，因此繼承 `bypassPermissions` 會授予它們完整的自主系統存取權。明確的[`ask` 規則](#how-permissions-are-evaluated)、連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具仍然會強制提示。129 **子代理程式繼承：** 當父代理程式使用 `bypassPermissions`、`acceptEdits` 或 `auto` 時，所有子代理程式都會繼承該模式，且無法按子代理程式覆蓋。子代理程式可能有不同的系統提示和行為限制較少，因此繼承 `bypassPermissions` 會授予它們完整的自主系統存取權。明確的[`ask` 規則](#how-permissions-are-evaluated)、連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具仍然會強制提示。

130</Warning>130</Warning>

131 131

132<h3 id="set-permission-mode">132<h3 id="set-permission-mode">

260 不詢問模式（`dontAsk`）260 不詢問模式（`dontAsk`）

261</h4>261</h4>

262 262

263將任何權限提示轉換為拒絕。由 `allowed_tools`、`settings.json` 允許規則或作為 hook 執行的工具會正常執行。連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具即使允許規則符合也會被拒絕。其他所有內容都會被拒絕，而不呼叫 `canUseTool`。263將任何權限提示轉換為拒絕。由 `allowed_tools`、`settings.json` 允許規則或作為 hook 執行的工具會正常執行。連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具即使允許規則符合也會被拒絕。其他所有內容都會被拒絕，而不呼叫 `canUseTool`。

264 264

265**使用時機：** 您想要為無頭代理程式提供固定的明確工具表面，並且更喜歡硬拒絕而不是無聲依賴 `canUseTool` 不存在。265**使用時機：** 您想要為無頭代理程式提供固定的明確工具表面，並且更喜歡硬拒絕而不是無聲依賴 `canUseTool` 不存在。

266 266

273<Warning>273<Warning>

274 謹慎使用。Claude 在此模式下具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。274 謹慎使用。Claude 在此模式下具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。

275 275

276 `allowed_tools` 不會限制此模式。每個工具都會被批准，而不僅僅是您列出的工具。拒絕規則（`disallowed_tools`）、明確的 `ask` 規則和 hooks 會在模式檢查之前被評估，仍然可以阻止工具。連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具仍然會透過您的 `canUseTool` 回呼進行。276 `allowed_tools` 不會限制此模式。每個工具都會被批准，而不僅僅是您列出的工具。拒絕規則（`disallowed_tools`）、明確的 `ask` 規則和 hooks 會在模式檢查之前被評估，仍然可以阻止工具。連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具仍然會透過您的 `canUseTool` 回呼進行。

277</Warning>277</Warning>

278 278

279<h4 id="plan-mode-plan">279<h4 id="plan-mode-plan">

280 規劃模式（`plan`）280 規劃模式（`plan`）

281</h4>281</h4>

282 282

283Claude 探索程式碼庫並產生計畫而不編輯您的原始檔案。唯讀工具在預設模式下執行。檔案編輯在規劃模式下永遠不會自動批准，即使允許規則符合。它們改為透過您的 `canUseTool` 回呼提示。Claude 可能會使用 `AskUserQuestion` 在最終確定計畫之前澄清需求。請參閱[處理核准和使用者輸入](/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以處理這些提示。283Claude 探索程式碼庫並產生計畫而不編輯您的原始檔案。唯讀工具在預設模式下執行。檔案編輯在規劃模式下永遠不會自動批准，即使允許規則符合。它們改為透過您的 `canUseTool` 回呼提示。Claude 可能會使用 `AskUserQuestion` 在最終確定計畫之前澄清需求。請參閱[處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以處理這些提示。

284 284

285**使用時機：** 您想要 Claude 提出變更建議而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。285**使用時機：** 您想要 Claude 提出變更建議而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。

286 286

290 290

291對於權限評估流程中的其他步驟：291對於權限評估流程中的其他步驟：

292 292

293* [處理核准和使用者輸入](/zh-TW/agent-sdk/user-input)：互動式核准提示和澄清問題293* [處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input)：互動式核准提示和澄清問題

294* [Hooks 指南](/zh-TW/agent-sdk/hooks)：在代理程式生命週期中的關鍵點執行自訂程式碼294* [Hooks 指南](/docs/zh-TW/agent-sdk/hooks)：在代理程式生命週期中的關鍵點執行自訂程式碼

295* [權限規則](/zh-TW/settings#permission-settings)：`settings.json` 中的宣告式允許/拒絕規則295* [權限規則](/docs/zh-TW/settings#permission-settings)：`settings.json` 中的宣告式允許/拒絕規則

agent-sdk/python.md +38 −38

Details

18pip install claude-agent-sdk18pip install claude-agent-sdk

19```19```

20 20

~~21如需 uv、Windows PowerShell 和 API 金鑰設定，請參閱 [Agent SDK 概觀中的開始使用](/zh-TW/agent-sdk/overview#get-started)。~~21如需 uv、Windows PowerShell 和 API 金鑰設定，請參閱 [Agent SDK 概觀中的開始使用](/docs/zh-TW/agent-sdk/overview#get-started)。

22 22

23<h2 id="choosing-between-query-and-claudesdkclient">23<h2 id="choosing-between-query-and-claudesdkclient">

24 在 `query()` 和 `ClaudeSDKClient` 之間選擇24 在 `query()` 和 `ClaudeSDKClient` 之間選擇

73 `query()`73 `query()`

74</h3>74</h3>

75 75

76為每次與 Claude Code 的互動建立新 session。返回一個非同步迭代器，在消息到達時產生消息。每次呼叫 `query()` 都會重新開始，不記得先前的互動，除非您傳遞 `continue_conversation=True` 或在 [`ClaudeAgentOptions`](#claudeagentoptions) 中傳遞 `resume`。請參閱 [Sessions](/zh-TW/agent-sdk/sessions)。76為每次與 Claude Code 的互動建立新 session。返回一個非同步迭代器，在消息到達時產生消息。每次呼叫 `query()` 都會重新開始，不記得先前的互動，除非您傳遞 `continue_conversation=True` 或在 [`ClaudeAgentOptions`](#claudeagentoptions) 中傳遞 `resume`。請參閱 [Sessions](/docs/zh-TW/agent-sdk/sessions)。

77 77

78```python theme={null}78```python theme={null}

79async def query(79async def query(

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

907| 屬性 | 類型 | 預設 | 描述 |907| 屬性 | 類型 | 預設 | 描述 |

908| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |908| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

909| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools 配置。使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的預設 tools |909| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools 配置。使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的預設 tools |

910| `allowed_tools` | `list[str]` | `[]` | 自動批准的 tools，無需提示。這不會限制 Claude 僅使用這些 tools；未列出的 tools 會進入 `permission_mode` 和 `can_use_tool`。使用 `disallowed_tools` 來阻止 tools。見 [權限](/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |910| `allowed_tools` | `list[str]` | `[]` | 自動批准的 tools，無需提示。這不會限制 Claude 僅使用這些 tools；未列出的 tools 會進入 `permission_mode` 和 `can_use_tool`。使用 `disallowed_tools` 來阻止 tools。見 [權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

911| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | 系統提示配置。傳遞字串以取得自訂提示，`{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示（可選 `"append"`），或 `{"type": "file", "path": "..."}` 以從磁碟載入大型提示。見 [`SystemPromptPreset`](#systempromptpreset) 和 [`SystemPromptFile`](#systempromptfile) |911| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | 系統提示配置。傳遞字串以取得自訂提示，`{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示（可選 `"append"`），或 `{"type": "file", "path": "..."}` 以從磁碟載入大型提示。見 [`SystemPromptPreset`](#systempromptpreset) 和 [`SystemPromptFile`](#systempromptfile) |

912| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 伺服器配置或配置檔案路徑 |912| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 伺服器配置或配置檔案路徑 |

913| `strict_mcp_config` | `bool` | `False` | 當為 `True` 時，僅使用在 `mcp_servers` 中傳遞的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛程式提供的 MCP 伺服器和 [claude.ai 連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對應到 CLI `--strict-mcp-config` 旗標 |913| `strict_mcp_config` | `bool` | `False` | 當為 `True` 時，僅使用在 `mcp_servers` 中傳遞的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛程式提供的 MCP 伺服器和 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對應到 CLI `--strict-mcp-config` 旗標 |

919| `disallowed_tools` | `list[str]` | `[]` | 要拒絕的 tools。裸名稱（例如 `"Bash"`）會從 Claude 的上下文中移除該 tool。範圍規則（例如 `"Bash(rm *)"`）會保留該 tool 可用，並在每個權限模式（包括 `bypassPermissions`）中拒絕匹配的呼叫。見 [權限](/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |919| `disallowed_tools` | `list[str]` | `[]` | 要拒絕的 tools。裸名稱（例如 `"Bash"`）會從 Claude 的上下文中移除該 tool。範圍規則（例如 `"Bash(rm *)"`）會保留該 tool 可用，並在每個權限模式（包括 `bypassPermissions`）中拒絕匹配的呼叫。見 [權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

924| `output_format` | `dict[str, Any] \| None` | `None` | 結構化回應的輸出格式（例如 `{"type": "json_schema", "schema": {...}}`）。見 [結構化輸出](/zh-TW/agent-sdk/structured-outputs) 以了解詳情 |924| `output_format` | `dict[str, Any] \| None` | `None` | 結構化回應的輸出格式（例如 `{"type": "json_schema", "schema": {...}}`）。見 [結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs) 以了解詳情 |

926| `cwd` | `str \| Path \| None` | `None` | 目前工作目錄 |926| `cwd` | `str \| Path \| None` | `None` | 目前工作目錄 |

930| `env` | `dict[str, str]` | `{}` | 環境變數合併到繼承的程序環境之上。見 [環境變數](/zh-TW/env-vars) 以了解底層 CLI 讀取的變數，以及 [處理緩慢或停滯的 API 回應](#handle-slow-or-stalled-api-responses) 以了解逾時相關變數 |930| `env` | `dict[str, str]` | `{}` | 環境變數合併到繼承的程序環境之上。見 [環境變數](/docs/zh-TW/env-vars) 以了解底層 CLI 讀取的變數，以及 [處理緩慢或停滯的 API 回應](#handle-slow-or-stalled-api-responses) 以了解逾時相關變數 |

931| `extra_args` | `dict[str, str \| None]` | `{}` | 直接傳遞給 CLI 的其他 CLI 參數 |931| `extra_args` | `dict[str, str \| None]` | `{}` | 直接傳遞給 CLI 的其他 CLI 參數 |

944| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 預設值：所有來源） | 控制要載入哪些檔案系統設定。傳遞 `[]` 以停用使用者、專案和本地設定。無論如何都會載入受管原則設定；當 session 使用組織認證在[符合條件的配置](/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。見 [使用 Claude Code 功能](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |944| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 預設值：所有來源） | 控制要載入哪些檔案系統設定。傳遞 `[]` 以停用使用者、專案和本地設定。無論如何都會載入受管原則設定；當 session 使用組織認證在[符合條件的配置](/docs/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。見 [使用 Claude Code 功能](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

951 951

952<h4 id="handle-slow-or-stalled-api-responses">952<h4 id="handle-slow-or-stalled-api-responses">

966```966```

967 967

968* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求逾時，以毫秒為單位。預設 `600000`。適用於主迴圈和所有子代理。968* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求逾時，以毫秒為單位。預設 `600000`。適用於主迴圈和所有子代理。

969* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。預設 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 視窗，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長中斷的無人值守執行，設定 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它無限期重試容量錯誤，{/* min-version: 2.1.199 */}自 Claude Code v2.1.199 起，會將其他暫時性錯誤的預設值提高到 `300` 並移除此變數的上限。969* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。預設 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 視窗，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長中斷的無人值守執行，設定 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它無限期重試容量錯誤，自 Claude Code v2.1.199 起，會將其他暫時性錯誤的預設值提高到 `300` 並移除此變數的上限。

970* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程式。預設 `600000`。在每個串流事件上重置；停滯時中止子代理，將任務標記為失敗，並將錯誤呈現給父代理，包含任何部分結果。不適用於同步子代理。970* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程式。預設 `600000`。在每個串流事件上重置；停滯時中止子代理，將任務標記為失敗，並將錯誤呈現給父代理，包含任何部分結果。不適用於同步子代理。

971* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但回應本體停止串流時中止請求。監視程式預設在所有提供者上啟用；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以停用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000` 並限制在該最小值。中止的請求會經過正常重試路徑。971* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但回應本體停止串流時中止請求。監視程式預設在所有提供者上啟用；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以停用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000` 並限制在該最小值。中止的請求會經過正常重試路徑。

972 972

1008| `type` | 是 | 必須是 `"preset"` 以使用預設系統提示 |1008| `type` | 是 | 必須是 `"preset"` 以使用預設系統提示 |

1009| `preset` | 是 | 必須是 `"claude_code"` 以使用 Claude Code 的系統提示 |1009| `preset` | 是 | 必須是 `"claude_code"` 以使用 Claude Code 的系統提示 |

1010| `append` | 否 | 要附加到預設系統提示的其他指示 |1010| `append` | 否 | 要附加到預設系統提示的其他指示 |

1011| `exclude_dynamic_sections` | 否 | 將每個 session 上下文（例如工作目錄、git 狀態和記憶體路徑）從系統提示移到第一個使用者消息。改進跨使用者和機器的提示快取重複使用。見 [修改系統提示](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1011| `exclude_dynamic_sections` | 否 | 將每個 session 上下文（例如工作目錄、git 狀態和記憶體路徑）從系統提示移到第一個使用者消息。改進跨使用者和機器的提示快取重複使用。見 [修改系統提示](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

1012 1012

1013<h3 id="systempromptfile">1013<h3 id="systempromptfile">

1014 `SystemPromptFile`1014 `SystemPromptFile`

1015</h3>1015</h3>

1016 1016

1017用於從檔案而不是作為字串傳遞自訂系統提示的配置。SDK 將此對應到 CLI [`--system-prompt-file`](/zh-TW/cli-reference#system-prompt-flags) 旗標。當提示很大時使用檔案形式：SDK 在 CLI 子程序 argv 上傳遞字串 `system_prompt`，受限於 OS 命令列長度限制，在 SDK 發送任何 API 請求之前。在 Linux 上，單個參數長於大約 128 KB 會在程序生成時失敗，出現 `Argument list too long`。在 Windows 上，整個命令列上限為大約 32 KB，因此字串形式在較低閾值失敗。1017用於從檔案而不是作為字串傳遞自訂系統提示的配置。SDK 將此對應到 CLI [`--system-prompt-file`](/docs/zh-TW/cli-reference#system-prompt-flags) 旗標。當提示很大時使用檔案形式：SDK 在 CLI 子程序 argv 上傳遞字串 `system_prompt`，受限於 OS 命令列長度限制，在 SDK 發送任何 API 請求之前。在 Linux 上，單個參數長於大約 128 KB 會在程序生成時失敗，出現 `Argument list too long`。在 Windows 上，整個命令列上限為大約 32 KB，因此字串形式在較低閾值失敗。

1018 1018

1019```python theme={null}1019```python theme={null}

1020class SystemPromptFile(TypedDict):1020class SystemPromptFile(TypedDict):

1047 預設行為1047 預設行為

1048</h4>1048</h4>

1049 1049

1050當 `setting_sources` 被省略或為 `None` 時，`query()` 載入與 Claude Code CLI 相同的檔案系統設定：使用者、專案和本地。無論如何都會載入受管原則設定；當 session 使用組織認證在[符合條件的配置](/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。見 [settingSources 不控制的內容](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) 以了解無論此選項如何都會讀取的輸入，以及如何停用它們。1050當 `setting_sources` 被省略或為 `None` 時，`query()` 載入與 Claude Code CLI 相同的檔案系統設定：使用者、專案和本地。無論如何都會載入受管原則設定；當 session 使用組織認證在[符合條件的配置](/docs/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。見 [settingSources 不控制的內容](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) 以了解無論此選項如何都會讀取的輸入，以及如何停用它們。

1051 1051

1052<h4 id="why-use-setting_sources">1052<h4 id="why-use-setting_sources">

1053 為什麼使用 setting\_sources1053 為什麼使用 setting\_sources

1257 1257

1258返回 `PermissionResult`（`PermissionResultAllow` 或 `PermissionResultDeny`）。1258返回 `PermissionResult`（`PermissionResultAllow` 或 `PermissionResultDeny`）。

1259 1259

1260回呼是互動式權限提示的 SDK 替代品：它僅在[權限評估流程](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)解決為提示時呼叫。由 `allowed_tools` 項目、設定允許規則或權限模式（例如 `acceptEdits` 或 `bypassPermissions`）已批准的 tool 呼叫永遠不會呼叫它。要限制每個 tool 呼叫，改用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)。1260回呼是互動式權限提示的 SDK 替代品：它僅在[權限評估流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)解決為提示時呼叫。由 `allowed_tools` 項目、設定允許規則或權限模式（例如 `acceptEdits` 或 `bypassPermissions`）已批准的 tool 呼叫永遠不會呼叫它。要限制每個 tool 呼叫，改用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)。

1261 1261

1262`AskUserQuestion`、標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP tools，以及您的組織設定為 [`ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 的連接器 tools 即使允許規則相符也會到達回呼。在 `dontAsk` 模式下，這些呼叫會被拒絕，而不呼叫回呼。1262`AskUserQuestion`、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP tools，以及您的組織設定為 [`ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 的連接器 tools 即使允許規則相符也會到達回呼。在 `dontAsk` 模式下，這些呼叫會被拒絕，而不呼叫回呼。

1263 1263

1264<h3 id="toolpermissioncontext">1264<h3 id="toolpermissioncontext">

1265 `ToolPermissionContext`1265 `ToolPermissionContext`

1606]1606]

1607```1607```

1608 1608

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

1610 1610

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

1612 消息類型1612 消息類型

1749 1749

1750| 鍵 | 類型 | 描述 |1750| 鍵 | 類型 | 描述 |

1751| ----------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------- |1751| ----------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------- |

1752| `input_tokens` | `int` | 頂層代理迴圈消耗的輸入令牌。[子代理令牌不包括在內](/zh-TW/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)；使用 `model_usage` 進行整個樹的計算。 |1752| `input_tokens` | `int` | 頂層代理迴圈消耗的輸入令牌。[子代理令牌不包括在內](/docs/zh-TW/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)；使用 `model_usage` 進行整個樹的計算。 |

1753| `output_tokens` | `int` | 頂層代理迴圈產生的輸出令牌。子代理令牌不包括在內。 |1753| `output_tokens` | `int` | 頂層代理迴圈產生的輸出令牌。子代理令牌不包括在內。 |

1754| `cache_creation_input_tokens` | `int` | 用於建立新快取項目的令牌。 |1754| `cache_creation_input_tokens` | `int` | 用於建立新快取項目的令牌。 |

1755| `cache_read_input_tokens` | `int` | 從現有快取項目讀取的令牌。 |1755| `cache_read_input_tokens` | `int` | 從現有快取項目讀取的令牌。 |

1756 1756

1757`model_usage` 字典將模型名稱對應到每個模型的使用情況。內部字典鍵使用 camelCase，因為該值從基礎 CLI 程序未修改地傳遞，符合 TypeScript [`ModelUsage`](/zh-TW/agent-sdk/typescript#modelusage) 類型：1757`model_usage` 字典將模型名稱對應到每個模型的使用情況。內部字典鍵使用 camelCase，因為該值從基礎 CLI 程序未修改地傳遞，符合 TypeScript [`ModelUsage`](/docs/zh-TW/agent-sdk/typescript#modelusage) 類型：

1758 1758

1759| 鍵 | 類型 | 描述 |1759| 鍵 | 類型 | 描述 |

1760| -------------------------- | ------- | ----------------------------------------------------------------------------------- |1760| -------------------------- | ------- | ----------------------------------------------------------------------------------- |

1763| `cacheReadInputTokens` | `int` | 此模型的快取讀取令牌。 |1763| `cacheReadInputTokens` | `int` | 此模型的快取讀取令牌。 |

1764| `cacheCreationInputTokens` | `int` | 此模型的快取建立令牌。 |1764| `cacheCreationInputTokens` | `int` | 此模型的快取建立令牌。 |

1765| `webSearchRequests` | `int` | 此模型進行的網路搜尋請求。 |1765| `webSearchRequests` | `int` | 此模型進行的網路搜尋請求。 |

1767| `contextWindow` | `int` | 此模型的上下文視窗大小。 |1767| `contextWindow` | `int` | 此模型的上下文視窗大小。 |

1768| `maxOutputTokens` | `int` | 此模型的最大輸出令牌限制。 |1768| `maxOutputTokens` | `int` | 此模型的最大輸出令牌限制。 |

1769 1769

2090 Hook 類型2090 Hook 類型

2091</h2>2091</h2>

2092 2092

2093如需使用 hooks 的綜合指南，包括範例和常見模式，見 [Hooks 指南](/zh-TW/agent-sdk/hooks)。2093如需使用 hooks 的綜合指南，包括範例和常見模式，見 [Hooks 指南](/docs/zh-TW/agent-sdk/hooks)。

2094 2094

2095<h3 id="hookevent">2095<h3 id="hookevent">

2096 `HookEvent`2096 `HookEvent`

2474 `HookSpecificOutput`2474 `HookSpecificOutput`

2475</h4>2475</h4>

2476 2476

2477包含 hook 事件名稱和事件特定欄位的 `TypedDict`。形狀取決於 `hookEventName` 值。如需每個 hook 事件的可用欄位的完整詳情，見 [使用 hooks 控制執行](/zh-TW/agent-sdk/hooks#outputs)。2477包含 hook 事件名稱和事件特定欄位的 `TypedDict`。形狀取決於 `hookEventName` 值。如需每個 hook 事件的可用欄位的完整詳情，見 [使用 hooks 控制執行](/docs/zh-TW/agent-sdk/hooks#outputs)。

2478 2478

2479事件特定輸出類型的判別聯合。`hookEventName` 欄位決定哪些欄位有效。2479事件特定輸出類型的判別聯合。`hookEventName` 欄位決定哪些欄位有效。

2480 2480

2639 2639

2640**Tool 名稱：** `AskUserQuestion`2640**Tool 名稱：** `AskUserQuestion`

2641 2641

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

2643 2643

2644**輸入：**2644**輸入：**

2645 2645

2717 2717

2718執行背景來源並將每個事件傳遞給 Claude，以便它可以做出反應而無需輪詢：`command` 執行指令碼並每個 stdout 行發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。請提供 `command` 或 `ws` 中的恰好一個。2718執行背景來源並將每個事件傳遞給 Claude，以便它可以做出反應而無需輪詢：`command` 執行指令碼並每個 stdout 行發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。請提供 `command` 或 `ws` 中的恰好一個。

2719 2719

2720當 Monitor 執行命令時，它遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示批准。{/* min-version: 2.1.195 */}`ws` 來源需要 Claude Code v2.1.195 或更新版本。見 [Monitor tool 參考](/zh-TW/tools-reference#monitor-tool) 以了解行為和提供者可用性。2720當 Monitor 執行命令時，它遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示批准。`ws` 來源需要 Claude Code v2.1.195 或更新版本。見 [Monitor tool 參考](/docs/zh-TW/tools-reference#monitor-tool) 以了解行為和提供者可用性。

2721 2721

2722**輸入：**2722**輸入：**

2723 2723

2995**Tool 名稱：** `TodoWrite`2995**Tool 名稱：** `TodoWrite`

2996 2996

2997<Note>2997<Note>

2998 自 Claude Code v2.1.142 起，`TodoWrite` 預設為停用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。見 [遷移到 Task tools](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 以更新您的監視程式碼，或設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以還原為 `TodoWrite`。2998 自 Claude Code v2.1.142 起，`TodoWrite` 預設為停用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。見 [遷移到 Task tools](/docs/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 以更新您的監視程式碼，或設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以還原為 `TodoWrite`。

2999</Note>2999</Note>

3000 3000

3001**輸入：**3001**輸入：**

3699 `SandboxNetworkConfig`3699 `SandboxNetworkConfig`

3700</h3>3700</h3>

3701 3701

3702沙箱模式的網路特定配置。這些設定適用於當父 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 為 `True` 時的沙箱化 Bash 命令。它們不會限制 WebFetch 工具，該工具改用[權限規則](/zh-TW/permissions#webfetch)。3702沙箱模式的網路特定配置。這些設定適用於當父 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 為 `True` 時的沙箱化 Bash 命令。它們不會限制 WebFetch 工具，該工具改用[權限規則](/docs/zh-TW/permissions#webfetch)。

3703 3703

3704```python theme={null}3704```python theme={null}

3705class SandboxNetworkConfig(TypedDict, total=False):3705class SandboxNetworkConfig(TypedDict, total=False):

3728 3728

3729<Note>3729<Note>

3730 內建沙箱 proxy 根據請求的主機名稱強制執行網路允許清單，不會終止或檢查 TLS 流量，因此[網域前置](https://en.wikipedia.org/wiki/Domain_fronting)等技術可能會繞過它。有關詳細資訊，請參閱[沙箱安全限制](/zh-TW/sandboxing#security-limitations)，以及[安全部署](/zh-TW/agent-sdk/secure-deployment#traffic-forwarding)以配置 TLS 終止 proxy。3730 內建沙箱 proxy 根據請求的主機名稱強制執行網路允許清單，不會終止或檢查 TLS 流量，因此[網域前置](https://en.wikipedia.org/wiki/Domain_fronting)等技術可能會繞過它。有關詳細資訊，請參閱[沙箱安全限制](/docs/zh-TW/sandboxing#security-limitations)，以及[安全部署](/docs/zh-TW/agent-sdk/secure-deployment#traffic-forwarding)以配置 TLS 終止 proxy。

3731</Note>3731</Note>

3732 3732

3733<h3 id="sandboxignoreviolations">3733<h3 id="sandboxignoreviolations">

3831 另見3831 另見

3832</h2>3832</h2>

3833 3833

3834* [SDK 概述](/zh-TW/agent-sdk/overview) - 一般 SDK 概念3834* [SDK 概述](/docs/zh-TW/agent-sdk/overview) - 一般 SDK 概念

3835* [TypeScript SDK 參考](/zh-TW/agent-sdk/typescript) - TypeScript SDK 文件3835* [TypeScript SDK 參考](/docs/zh-TW/agent-sdk/typescript) - TypeScript SDK 文件

3836* [CLI 參考](/zh-TW/cli-reference) - 命令列介面3836* [CLI 參考](/docs/zh-TW/cli-reference) - 命令列介面

3837* [常見工作流程](/zh-TW/common-workflows) - 逐步指南3837* [常見工作流程](/docs/zh-TW/common-workflows) - 逐步指南

agent-sdk/subagents.md +16 −16

Details

17 17

18您可以通過三種方式建立子代理：18您可以通過三種方式建立子代理：

19 19

20* **以程式方式**：在您的 `query()` 選項中使用 `agents` 參數。請參閱 [TypeScript](/zh-TW/agent-sdk/typescript#agentdefinition) 和 [Python](/zh-TW/agent-sdk/python#agentdefinition) 參考資料20* **以程式方式**：在您的 `query()` 選項中使用 `agents` 參數。請參閱 [TypeScript](/docs/zh-TW/agent-sdk/typescript#agentdefinition) 和 [Python](/docs/zh-TW/agent-sdk/python#agentdefinition) 參考資料

~~21* **基於檔案系統**：在 `.claude/agents/` 目錄中將代理定義為 markdown 檔案。請參閱[將子代理定義為檔案](/zh-TW/sub-agents)~~21* **基於檔案系統**：在 `.claude/agents/` 目錄中將代理定義為 markdown 檔案。請參閱[將子代理定義為檔案](/docs/zh-TW/sub-agents)

22* **內置通用代理**：Claude 可以隨時通過 Agent 工具呼叫內置的 `general-purpose` 子代理，無需您定義任何內容22* **內置通用代理**：Claude 可以隨時通過 Agent 工具呼叫內置的 `general-purpose` 子代理，無需您定義任何內容

23 23

24本指南重點介紹程式化方法，這是 SDK 應用程式的推薦方法。24本指南重點介紹程式化方法，這是 SDK 應用程式的推薦方法。

199 199

200在 Python SDK 中，多字欄位名稱（例如 `disallowedTools` 和 `mcpServers`）保持其 camelCase 拼寫以匹配線路格式，而不是遵循 Python 的 snake\_case 慣例。有關詳細信息，請參閱 [`AgentDefinition` 參考](/zh-TW/agent-sdk/python#agentdefinition)。200在 Python SDK 中，多字欄位名稱（例如 `disallowedTools` 和 `mcpServers`）保持其 camelCase 拼寫以匹配線路格式，而不是遵循 Python 的 snake\_case 慣例。有關詳細信息，請參閱 [`AgentDefinition` 參考](/docs/zh-TW/agent-sdk/python#agentdefinition)。

201 201

202Claude Code v2.1.198 中的兩個子代理行為已更改：202Claude Code v2.1.198 中的兩個子代理行為已更改：

203 203

204* 子代理預設在背景中運行。省略 [`run_in_background`](/zh-TW/agent-sdk/typescript) 輸入的 Agent 工具調用會啟動背景子代理，當 Claude 需要結果才能繼續時，它會設定 `run_in_background: false`。在 v2.1.198 之前，省略 `run_in_background` 會同步運行子代理。設定 `background` 欄位為 `true` 以強制特定代理進行背景執行，無論 Claude 請求什麼。204* 子代理預設在背景中運行。省略 [`run_in_background`](/docs/zh-TW/agent-sdk/typescript) 輸入的 Agent 工具調用會啟動背景子代理，當 Claude 需要結果才能繼續時，它會設定 `run_in_background: false`。在 v2.1.198 之前，省略 `run_in_background` 會同步運行子代理。設定 `background` 欄位為 `true` 以強制特定代理進行背景執行，無論 Claude 請求什麼。

205* 子代理繼承主會話的擴展思考配置。在較早的版本中，無論主會話的設定如何，擴展思考在子代理內被禁用。205* 子代理繼承主會話的擴展思考配置。在較早的版本中，無論主會話的設定如何，擴展思考在子代理內被禁用。

206 206

207<Note>207<Note>

208 {/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，子代理可以生成自己的子代理。位於主代理下方五個級別的子代理無法生成進一步的子代理，無論其是否在前景或背景中運行。若要防止子代理生成其他子代理，請從其 `tools` 陣列中省略 `Agent` 或將其添加到 `disallowedTools`。有關完整的深度規則，請參閱[嵌套子代理](/zh-TW/sub-agents#spawn-nested-subagents)。208 自 Claude Code v2.1.172 起，子代理可以生成自己的子代理。位於主代理下方五個級別的子代理無法生成進一步的子代理，無論其是否在前景或背景中運行。若要防止子代理生成其他子代理，請從其 `tools` 陣列中省略 `Agent` 或將其添加到 `disallowedTools`。有關完整的深度規則，請參閱[嵌套子代理](/docs/zh-TW/sub-agents#spawn-nested-subagents)。

209</Note>209</Note>

210 210

211<h3 id="filesystem-based-definition-alternative">211<h3 id="filesystem-based-definition-alternative">

212 基於檔案系統的定義（替代方案）212 基於檔案系統的定義（替代方案）

213</h3>213</h3>

214 214

215您也可以在 `.claude/agents/` 目錄中將子代理定義為 markdown 檔案。有關此方法的詳細信息，請參閱 [Claude Code 子代理文檔](/zh-TW/sub-agents)。以程式方式定義的代理優先於具有相同名稱的基於檔案系統的代理。215您也可以在 `.claude/agents/` 目錄中將子代理定義為 markdown 檔案。有關此方法的詳細信息，請參閱 [Claude Code 子代理文檔](/docs/zh-TW/sub-agents)。以程式方式定義的代理優先於具有相同名稱的基於檔案系統的代理。

216 216

217<Note>217<Note>

218 即使不定義自訂子代理，Claude 也可以生成內置的 `general-purpose` 子代理。這對於委派研究或探索任務而無需創建專門代理很有用。請在 `allowedTools` 中包含 `Agent`，以便這些調用自動批准，無需權限提示。218 即使不定義自訂子代理，Claude 也可以生成內置的 `general-purpose` 子代理。這對於委派研究或探索任務而無需創建專門代理很有用。請在 `allowedTools` 中包含 `Agent`，以便這些調用自動批准，無需權限提示。

224 224

225子代理的上下文窗口從新開始（無父對話），但並非空的。從父代理到子代理的唯一通道是 Agent 工具的提示詞字符串，因此請直接在該提示詞中包含子代理需要的任何檔案路徑、錯誤消息或決策。225子代理的上下文窗口從新開始（無父對話），但並非空的。從父代理到子代理的唯一通道是 Agent 工具的提示詞字符串，因此請直接在該提示詞中包含子代理需要的任何檔案路徑、錯誤消息或決策。

226 226

227{/* min-version: 2.1.206 */}具有 [`SendMessage`](/zh-TW/tools-reference) 工具的子代理會在開始時獲得在該會話中運行的其他命名代理的列表，因此它知道可以向哪些名稱發送消息。Claude Code 會自動在子代理的第一輪中添加該列表。[分叉](/zh-TW/sub-agents#fork-the-current-conversation)不會獲得該列表，因為它繼承了父對話。該列表需要 Claude Code v2.1.206 或更高版本。227具有 [`SendMessage`](/docs/zh-TW/tools-reference) 工具的子代理會在開始時獲得在該會話中運行的其他命名代理的列表，因此它知道可以向哪些名稱發送消息。Claude Code 會自動在子代理的第一輪中添加該列表。[分叉](/docs/zh-TW/sub-agents#fork-the-current-conversation)不會獲得該列表，因為它繼承了父對話。該列表需要 Claude Code v2.1.206 或更高版本。

228 228

229| 子代理接收 | 子代理不接收 |229| 子代理接收 | 子代理不接收 |

230| :---------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------- |230| :---------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------- |

232| 項目 CLAUDE.md（通過 [`settingSources`](/zh-TW/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 加載） | 預加載的技能內容，除非在 `AgentDefinition.skills` 中列出 |232| 項目 CLAUDE.md（通過 [`settingSources`](/docs/zh-TW/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 加載） | 預加載的技能內容，除非在 `AgentDefinition.skills` 中列出 |

234 234

235<Note>235<Note>

236 父代理逐字接收子代理的最終消息作為 Agent 工具結果，但可能在其自己的回應中進行摘要。要在面向用戶的回應中逐字保留子代理輸出，請在您傳遞給主 `query()` 調用的提示詞或 `systemPrompt` 選項中包含執行此操作的指令。236 父代理逐字接收子代理的最終消息作為 Agent 工具結果，但可能在其自己的回應中進行摘要。要在面向用戶的回應中逐字保留子代理輸出，請在您傳遞給主 `query()` 調用的提示詞或 `systemPrompt` 選項中包含執行此操作的指令。

237</Note>237</Note>

238 238

239{/* min-version: 2.1.199 */}結束子代理早期的 API 錯誤（例如速率限制）永遠不會作為其結果傳遞。如果速率限制、過載或伺服器錯誤中斷已經產生文本輸出的前景子代理，Agent 工具會返回該部分輸出並附註子代理未完成。{/* min-version: 2.1.200 */}未產生任何內容的子代理，或其唯一輸出是沒有文本的工具調用，會失敗並顯示錯誤消息 `Agent terminated early due to an API error`，後跟錯誤詳情。請參閱[子代理中的 API 錯誤](/zh-TW/sub-agents#api-errors-in-subagents)以了解前景和背景行為。239結束子代理早期的 API 錯誤（例如速率限制）永遠不會作為其結果傳遞。如果速率限制、過載或伺服器錯誤中斷已經產生文本輸出的前景子代理，Agent 工具會返回該部分輸出並附註子代理未完成。未產生任何內容的子代理，或其唯一輸出是沒有文本的工具調用，會失敗並顯示錯誤消息 `Agent terminated early due to an API error`，後跟錯誤詳情。請參閱[子代理中的 API 錯誤](/docs/zh-TW/sub-agents#api-errors-in-subagents)以了解前景和背景行為。

240 240

241此部分輸出處理需要 Claude Code v2.1.199 或更高版本。在 v2.1.199 中，速率限制、過載或伺服器錯誤使僅工具調用的形狀保留為空的部分結果，僅包含截斷注釋。241此部分輸出處理需要 Claude Code v2.1.199 或更高版本。在 v2.1.199 中，速率限制、過載或伺服器錯誤使僅工具調用的形狀保留為空的部分結果，僅包含截斷注釋。

242 242

441 441

442您可以恢復子代理以繼續中斷的地方，而不是從頭開始。恢復的子代理保留其完整的對話歷史，包括所有先前的工具調用、結果和推理。442您可以恢復子代理以繼續中斷的地方，而不是從頭開始。恢復的子代理保留其完整的對話歷史，包括所有先前的工具調用、結果和推理。

443 443

444當子代理完成時，Agent 工具結果包含一個文字區塊，其中包含 `agentId: <id>`。內置的 [`Explore` 和 `Plan` 代理](/zh-TW/sub-agents#built-in-subagents) 是一次性的，不會返回 `agentId`，因此當您需要恢復時，請使用自訂代理或 `general-purpose`。要以程式方式恢復子代理：444當子代理完成時，Agent 工具結果包含一個文字區塊，其中包含 `agentId: <id>`。內置的 [`Explore` 和 `Plan` 代理](/docs/zh-TW/sub-agents#built-in-subagents) 是一次性的，不會返回 `agentId`，因此當您需要恢復時，請使用自訂代理或 `general-purpose`。要以程式方式恢復子代理：

445 445

4461. **捕獲會話 ID**：在第一個查詢期間從訊息中提取 `session_id`4461. **捕獲會話 ID**：在第一個查詢期間從訊息中提取 `session_id`

4472. **提取代理 ID**：從 Agent 工具結果文字中解析 `agentId`4472. **提取代理 ID**：從 Agent 工具結果文字中解析 `agentId`

661 使用動態工作流程進行擴展661 使用動態工作流程進行擴展

662</h2>662</h2>

663 663

664子代理適用於每轉委派幾個任務。對於協調數十到數百個代理的運行，請使用 `Workflow` 工具，它將編排移到運行時在對話上下文外執行的腳本中。請參閱[動態工作流程](/zh-TW/workflows)以了解工作流程與逐轉子代理委派的區別。664子代理適用於每轉委派幾個任務。對於協調數十到數百個代理的運行，請使用 `Workflow` 工具，它將編排移到運行時在對話上下文外執行的腳本中。請參閱[動態工作流程](/docs/zh-TW/workflows)以了解工作流程與逐轉子代理委派的區別。

665 665

666`Workflow` 工具在 TypeScript Agent SDK v0.3.149 及更高版本中可用。在 `allowedTools` 中包含 `Workflow` 以自動批准工作流程運行。工具輸入和輸出架構列在 [TypeScript 參考](/zh-TW/agent-sdk/typescript#workflow)中。666`Workflow` 工具在 TypeScript Agent SDK v0.3.149 及更高版本中可用。在 `allowedTools` 中包含 `Workflow` 以自動批准工作流程運行。工具輸入和輸出架構列在 [TypeScript 參考](/docs/zh-TW/agent-sdk/typescript#workflow)中。

667 667

668<h2 id="troubleshooting">668<h2 id="troubleshooting">

669 故障排除669 故障排除

690* **`--disable-slash-commands`**：使用此旗標啟動的會話不監視這些目錄，並且始終需要重新啟動以加載新檔案。690* **`--disable-slash-commands`**：使用此旗標啟動的會話不監視這些目錄，並且始終需要重新啟動以加載新檔案。

691* **具有相同名稱的程式化代理**：傳遞給 `query()` 的 `agents` 會覆蓋具有相同名稱的檔案系統代理。691* **具有相同名稱的程式化代理**：傳遞給 `query()` 的 `agents` 會覆蓋具有相同名稱的檔案系統代理。

692 692

693有關檔案格式，請參閱[如何編寫子代理檔案](/zh-TW/sub-agents#write-subagent-files)。693有關檔案格式，請參閱[如何編寫子代理檔案](/docs/zh-TW/sub-agents#write-subagent-files)。

694 694

695<h3 id="long-prompt-failures-on-windows">695<h3 id="long-prompt-failures-on-windows">

696 Windows 上的長提示詞失敗696 Windows 上的長提示詞失敗

702 相關文檔702 相關文檔

703</h2>703</h2>

704 704

705* [Claude Code 子代理](/zh-TW/sub-agents)：包括基於檔案系統定義的全面子代理文檔705* [Claude Code 子代理](/docs/zh-TW/sub-agents)：包括基於檔案系統定義的全面子代理文檔

706* [動態工作流程](/zh-TW/workflows)：從腳本協調許多子代理，用於對話太大的工作706* [動態工作流程](/docs/zh-TW/workflows)：從腳本協調許多子代理，用於對話太大的工作

707* [SDK 概述](/zh-TW/agent-sdk/overview)：Claude Agent SDK 入門707* [SDK 概述](/docs/zh-TW/agent-sdk/overview)：Claude Agent SDK 入門

agent-sdk/todo-tracking.md +7 −7

Details

40 範例40 範例

41</h2>41</h2>

42 42

~~43在執行這些範例之前，請按照[快速入門](/zh-TW/agent-sdk/quickstart)安裝 Claude Agent SDK。~~43在執行這些範例之前，請按照[快速入門](/docs/zh-TW/agent-sdk/quickstart)安裝 Claude Agent SDK。

44 44

45每個範例會執行到代理程式完成並產生其最終結果訊息為止。如果工作階段先達到其輪次限制，該結果訊息會有 `error_max_turns` 子類型。檢查 `subtype` 以偵測該結束。45每個範例會執行到代理程式完成並產生其最終結果訊息為止。如果工作階段先達到其輪次限制，該結果訊息會有 `error_max_turns` 子類型。檢查 `subtype` 以偵測該結束。

46 46

47這些範例使用單次 `query()` 呼叫。在產生 `error_max_turns` 結果後，`query()` 會拋出包含 `Reached maximum number of turns` 的錯誤。每個範例都將其迴圈包裝在 try 區塊中，以便在發生這種情況時乾淨地退出。47這些範例使用單次 `query()` 呼叫。在產生 `error_max_turns` 結果後，`query()` 會拋出包含 `Reached maximum number of turns` 的錯誤。每個範例都將其迴圈包裝在 try 區塊中，以便在發生這種情況時乾淨地退出。

48 48

~~49請參閱[處理結果](/zh-TW/agent-sdk/agent-loop#handle-the-result)以了解結果子類型。~~49請參閱[處理結果](/docs/zh-TW/agent-sdk/agent-loop#handle-the-result)以了解結果子類型。

50 50

51<h3 id="monitoring-todo-changes">51<h3 id="monitoring-todo-changes">

52 監控待辦事項變更52 監控待辦事項變更

253 遷移到 Task 工具253 遷移到 Task 工具

254</h2>254</h2>

255 255

256Task 工具將單個 `TodoWrite` 呼叫分割為每個新項目的 `TaskCreate` 和每個狀態變更的 `TaskUpdate`，並提供 `TaskList` 和 `TaskGet` 供模型讀回當前清單。您的監控代碼仍然檢查助手流中的 `tool_use` 區塊，但維護一個由任務 ID 鍵入的映射，而不是在每次呼叫時替換整個清單。{/* min-version: 2.1.142 */}Task 工具是 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 起的預設值，因此不需要 `options.env` 變更。256Task 工具將單個 `TodoWrite` 呼叫分割為每個新項目的 `TaskCreate` 和每個狀態變更的 `TaskUpdate`，並提供 `TaskList` 和 `TaskGet` 供模型讀回當前清單。您的監控代碼仍然檢查助手流中的 `tool_use` 區塊，但維護一個由任務 ID 鍵入的映射，而不是在每次呼叫時替換整個清單。Task 工具是 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 起的預設值，因此不需要 `options.env` 變更。

257 257

259| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |259| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

338 相關文檔338 相關文檔

339</h2>339</h2>

340 340

341* [TypeScript SDK 參考](/zh-TW/agent-sdk/typescript)341* [TypeScript SDK 參考](/docs/zh-TW/agent-sdk/typescript)

342* [Python SDK 參考](/zh-TW/agent-sdk/python)342* [Python SDK 參考](/docs/zh-TW/agent-sdk/python)

343* [串流與單一模式](/zh-TW/agent-sdk/streaming-vs-single-mode)343* [串流與單一模式](/docs/zh-TW/agent-sdk/streaming-vs-single-mode)

344* [自訂工具](/zh-TW/agent-sdk/custom-tools)344* [自訂工具](/docs/zh-TW/agent-sdk/custom-tools)

agent-sdk/typescript.md +70 −72

Details

6 6

7> TypeScript Agent SDK 的完整 API 參考，包括所有函數、類型和介面。7> TypeScript Agent SDK 的完整 API 參考，包括所有函數、類型和介面。

8 8

~~9<script src="/components/typescript-sdk-type-links.js" defer />~~9<script src="/docs/components/typescript-sdk-type-links.js" defer />

10 10

11<h2 id="installation">11<h2 id="installation">

12 安裝12 安裝

296</h4>296</h4>

297 297

298| 屬性 | 類型 | 描述 |298| 屬性 | 類型 | 描述 |

299| :------------------- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |299| :------------------- | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |

305| `parent_agent_id` | `string \| null` | 對於來自[嵌套子代理](/zh-TW/sub-agents#spawn-nested-subagents)的消息，生成它的子代理的 `agentId`。對於主會話消息、來自頂級子代理的消息和較舊的會話為 `null`。{/* min-version: 2.1.202 */}需要 Claude Code v2.1.202 或更高版本 |305| `parent_agent_id` | `string \| null` | 對於來自[嵌套子代理](/docs/zh-TW/sub-agents#spawn-nested-subagents)的消息，生成它的子代理的 `agentId`。對於主會話消息、來自頂級子代理的消息和較舊的會話為 `null`。需要 Claude Code v2.1.202 或更高版本 |

306 306

307<h4 id="example-3">307<h4 id="example-3">

308 示例308 示例

423| :------------------------------ | :------------------------------------ | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |423| :------------------------------ | :------------------------------------ | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |

426| `options.managedSettings` | `Settings` | `undefined` | 由嵌入主機提供的限制性策略層設定。當存在管理員部署的託管層時被丟棄；當 [`parentSettingsBehavior`](/zh-TW/settings#available-settings) 為 `"merge"` 時在該層下合併。非限制性鍵（如 `model`）會被靜默丟棄，以便此選項可以加強託管策略但不能放寬它 |426| `options.managedSettings` | `Settings` | `undefined` | 由嵌入主機提供的限制性策略層設定。當存在管理員部署的託管層時被丟棄；當 [`parentSettingsBehavior`](/docs/zh-TW/settings#available-settings) 為 `"merge"` 時在該層下合併。非限制性鍵（如 `model`）會被靜默丟棄，以便此選項可以加強託管策略但不能放寬它 |

428 428

429<h4 id="return-type-resolvedsettings">429<h4 id="return-type-resolvedsettings">

477| `allowedTools` | `string[]` | `[]` | 無需提示即可自動批准的工具。這不會將 Claude 限制為僅這些工具；未列出的工具會進入 `permissionMode` 和 `canUseTool`。使用 `disallowedTools` 來阻止工具。見 [Permissions](/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |477| `allowedTools` | `string[]` | `[]` | 無需提示即可自動批准的工具。這不會將 Claude 限制為僅這些工具；未列出的工具會進入 `permissionMode` 和 `canUseTool`。使用 `disallowedTools` 來阻止工具。見 [Permissions](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

479| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定義權限函數，僅在 [permission flow](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 進入提示時調用。不會為 `allowedTools`、allow 規則或 `permissionMode` 自動批准的調用調用。`AskUserQuestion`、connector tools [您的組織設置為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP tools 即使您已允許它們也會到達它；在 `dontAsk` 模式下這些會被拒絕。見 [`CanUseTool`](#canusetool) 了解詳情 |479| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定義權限函數，僅在 [permission flow](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 進入提示時調用。不會為 `allowedTools`、allow 規則或 `permissionMode` 自動批准的調用調用。`AskUserQuestion`、connector tools [您的組織設置為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP tools 即使您已允許它們也會到達它；在 `dontAsk` 模式下這些會被拒絕。見 [`CanUseTool`](#canusetool) 了解詳情 |

484| `disallowedTools` | `string[]` | `[]` | 要拒絕的工具。裸名稱如 `"Bash"` 會從 Claude 的上下文中移除該工具。作用域規則如 `"Bash(rm *)"` 會保留該工具可用，並在每個權限模式中拒絕匹配的調用，包括 `bypassPermissions`。見 [Permissions](/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |484| `disallowedTools` | `string[]` | `[]` | 要拒絕的工具。裸名稱如 `"Bash"` 會從 Claude 的上下文中移除該工具。作用域規則如 `"Bash(rm *)"` 會保留該工具可用，並在每個權限模式中拒絕匹配的調用，包括 `bypassPermissions`。見 [Permissions](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

487| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變量。設置此項時，這會替換子進程環境而不是與 `process.env` 合併，因此傳遞 `{ ...process.env, YOUR_VAR: 'value' }` 以保留繼承的變量如 `PATH`。見 [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) 了解此模式的示例，以及 [Environment variables](/zh-TW/env-vars) 了解底層 CLI 讀取的變量。設置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中標識您的應用程序 |487| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變量。設置此項時，這會替換子進程環境而不是與 `process.env` 合併，因此傳遞 `{ ...process.env, YOUR_VAR: 'value' }` 以保留繼承的變量如 `PATH`。見 [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) 了解此模式的示例，以及 [Environment variables](/docs/zh-TW/env-vars) 了解底層 CLI 讀取的變量。設置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中標識您的應用程序 |

490| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他參數 |490| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他參數 |

502| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服務器配置 |502| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服務器配置 |

504| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | 用於處理 MCP elicitation 請求的回調。當 MCP 服務器請求用戶輸入且沒有 hooks 首先處理它時調用。未提供時，未處理的 elicitation 請求會自動被拒絕 |504| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | 用於處理 MCP elicitation 請求的回調。當 MCP 服務器請求用戶輸入且沒有 hooks 首先處理它時調用。未提供時，未處理的 elicitation 請求會自動被拒絕 |

505| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 為代理結果定義輸出格式。見 [Structured outputs](/zh-TW/agent-sdk/structured-outputs) 了解詳情 |505| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 為代理結果定義輸出格式。見 [Structured outputs](/docs/zh-TW/agent-sdk/structured-outputs) 了解詳情 |

506| `outputStyle` | `string` | `undefined` | 不是 `Options` 字段。改為在內聯 [`settings`](/zh-TW/settings) 對象或設置文件中設置 `outputStyle`。見 [Activate an output style](/zh-TW/agent-sdk/modifying-system-prompts#activate-an-output-style) |506| `outputStyle` | `string` | `undefined` | 不是 `Options` 字段。改為在內聯 [`settings`](/docs/zh-TW/settings) 對象或設置文件中設置 `outputStyle`。見 [Activate an output style](/docs/zh-TW/agent-sdk/modifying-system-prompts#activate-an-output-style) |

518| `sessionStore` | [`SessionStore`](/zh-TW/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 將會話記錄鏡像到外部後端，以便任何主機都可以恢復它們。見 [Persist sessions to external storage](/zh-TW/agent-sdk/session-storage) |518| `sessionStore` | [`SessionStore`](/docs/zh-TW/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 將會話記錄鏡像到外部後端，以便任何主機都可以恢復它們。見 [Persist sessions to external storage](/docs/zh-TW/agent-sdk/session-storage) |

521| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默認值（所有源） | 控制加載哪些文件系統設置。傳遞 `[]` 以禁用用戶、項目和本地設置。無論如何都會加載 [Endpoint-managed policy](/zh-TW/settings#settings-files)；當會話使用組織憑證在 [eligible configuration](/zh-TW/server-managed-settings#platform-availability) 上進行身份驗證時，會獲取服務器管理的設置。見 [Use Claude Code features](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |521| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默認值（所有源） | 控制加載哪些文件系統設置。傳遞 `[]` 以禁用用戶、項目和本地設置。無論如何都會加載 [Endpoint-managed policy](/docs/zh-TW/settings#settings-files)；當會話使用組織憑證在 [eligible configuration](/docs/zh-TW/server-managed-settings#platform-availability) 上進行身份驗證時，會獲取服務器管理的設置。見 [Use Claude Code features](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

526| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系統提示配置。傳遞字符串以獲得自定義提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示。使用預設對象形式時，添加 `append` 以使用其他指令擴展它，並設置 `excludeDynamicSections: true` 以將每個會話上下文移到第一個用戶消息中以獲得 [better prompt-cache reuse across machines](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |526| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系統提示配置。傳遞字符串以獲得自定義提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示。使用預設對象形式時，添加 `append` 以使用其他指令擴展它，並設置 `excludeDynamicSections: true` 以將每個會話上下文移到第一個用戶消息中以獲得 [better prompt-cache reuse across machines](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

527| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API 端任務預算（以令牌為單位）。設置後，模型會被告知其剩餘令牌預算，以便它可以調整工具使用速度並在達到限制前完成 |527| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API 端任務預算（以令牌為單位）。設置後，模型會被告知其剩餘令牌預算，以便它可以調整工具使用速度並在達到限制前完成 |

528| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行為。見 [`ThinkingConfig`](#thinkingconfig) 了解選項 |528| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行為。見 [`ThinkingConfig`](#thinkingconfig) 了解選項 |

552```552```

553 553

554* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求超時，以毫秒為單位。默認 `600000`。適用於主循環和所有子代理。554* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求超時，以毫秒為單位。默認 `600000`。適用於主循環和所有子代理。

555* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。默認 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 窗口，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長時間中斷的無人值守運行，設置 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它無限期重試容量錯誤，{/* min-version: 2.1.199 */}自 Claude Code v2.1.199 起，為其他瞬時錯誤提高默認值至 `300` 並移除此變量的上限。555* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。默認 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 窗口，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長時間中斷的無人值守運行，設置 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它無限期重試容量錯誤，自 Claude Code v2.1.199 起，為其他瞬時錯誤提高默認值至 `300` 並移除此變量的上限。

556* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程序。默認 `600000`。在每個流事件上重置；在停滯時中止子代理，將任務標記為失敗，並將錯誤與任何部分結果一起呈現給父代理。不適用於同步子代理。556* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程序。默認 `600000`。在每個流事件上重置；在停滯時中止子代理，將任務標記為失敗，並將錯誤與任何部分結果一起呈現給父代理。不適用於同步子代理。

557* `CLAUDE_ENABLE_STREAM_WATCHDOG` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但響應正文停止流式傳輸時中止請求。監視程序對所有提供商默認開啟；設置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默認為 `300000` 並被限制為該最小值。中止的請求通過正常重試路徑進行。557* `CLAUDE_ENABLE_STREAM_WATCHDOG` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但響應正文停止流式傳輸時中止請求。監視程序對所有提供商默認開啟；設置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默認為 `300000` 並被限制為該最小值。中止的請求通過正常重試路徑進行。

558 558

594</h4>594</h4>

595 595

596| 方法 | 描述 |596| 方法 | 描述 |

597| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |597| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

598| `interrupt()` | 中斷查詢。僅在流式輸入模式下可用。{/* min-version: 2.1.205 */}當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中公告 `interrupt_receipt_v1` 功能時，使用列出存活中斷的排隊消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 進行解決。在 v2.1.205 之前的 CLI 上解決為 `undefined` |598| `interrupt()` | 中斷查詢。僅在流式輸入模式下可用。當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中公告 `interrupt_receipt_v1` 功能時，使用列出存活中斷的排隊消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 進行解決。在 v2.1.205 之前的 CLI 上解決為 `undefined` |

599| `rewindFiles(userMessageId, options?)` | 將文件恢復到指定用戶消息時的狀態。傳遞 `{ dryRun: true }` 以預覽更改。需要 `enableFileCheckpointing: true`。見 [File checkpointing](/zh-TW/agent-sdk/file-checkpointing) |599| `rewindFiles(userMessageId, options?)` | 將文件恢復到指定用戶消息時的狀態。傳遞 `{ dryRun: true }` 以預覽更改。需要 `enableFileCheckpointing: true`。見 [File checkpointing](/docs/zh-TW/agent-sdk/file-checkpointing) |

605| `reinitialize()` | {/* min-version: 2.1.195 */}重新發送 `initialize` 控制請求到運行的 CLI，並返回新鮮的結果而不是緩存的首次連接結果。在傳輸間隙後使用它，例如在斷開連接後重新附加到會話，以便待處理的權限請求再次到達您的 `canUseTool` 回調。使回調對每個請求 ID 冪等，因為響應丟失的請求會再次被分派。需要 Claude Code v2.1.195 或更高版本 |605| `reinitialize()` | 重新發送 `initialize` 控制請求到運行的 CLI，並返回新鮮的結果而不是緩存的首次連接結果。在傳輸間隙後使用它，例如在斷開連接後重新附加到會話，以便待處理的權限請求再次到達您的 `canUseTool` 回調。使回調對每個請求 ID 冪等，因為響應丟失的請求會再次被分派。需要 Claude Code v2.1.195 或更高版本 |

619 `applyFlagSettings()`619 `applyFlagSettings()`

620</h4>620</h4>

621 621

622在運行會話上更改任何 [settings](/zh-TW/settings)，無需重新啟動查詢。當沒有專用設置器的設置需要在會話中期更改時使用它，例如在代理讀取不受信任的輸入後收緊 `permissions`。`setModel()` 和 `setPermissionMode()` 是這兩個鍵的專用設置器；`applyFlagSettings()` 是接受任何設置鍵子集的通用形式，在此處傳遞 `model` 的行為與 `setModel()` 相同。622在運行會話上更改任何 [settings](/docs/zh-TW/settings)，無需重新啟動查詢。當沒有專用設置器的設置需要在會話中期更改時使用它，例如在代理讀取不受信任的輸入後收緊 `permissions`。`setModel()` 和 `setPermissionMode()` 是這兩個鍵的專用設置器；`applyFlagSettings()` 是接受任何設置鍵子集的通用形式，在此處傳遞 `model` 的行為與 `setModel()` 相同。

623 623

624只有某些鍵在會話中期生效：624只有某些鍵在會話中期生效：

625 625

626* **在下一個轉數上應用**：`model`、`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切換 `agent` 也會在下一個轉數上應用該代理的模型覆蓋、hooks 和系統提示。626* **在下一個轉數上應用**：`model`、`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切換 `agent` 也會在下一個轉數上應用該代理的模型覆蓋、hooks 和系統提示。

627* **在會話中期無效**：系統提示選項。這些在啟動時解決一次，因此運行會話保持原始值，即使調用成功。要更改它們，請啟動新會話。627* **在會話中期無效**：系統提示選項。這些在啟動時解決一次，因此運行會話保持原始值，即使調用成功。要更改它們，請啟動新會話。

628 628

629`effortLevel` 接受 [effort level](/zh-TW/model-config#adjust-effort-level) 名稱。它也接受 `"ultracode"`，它以 `xhigh` 努力運行會話並打開 [ultracode](/zh-TW/workflows#let-claude-decide-with-ultracode)。`Settings` 類型聲明 `effortLevel` 沒有該值，因此在 TypeScript 中傳遞等效的 `{ ultracode: true }`。{/* min-version: 2.1.203 */}`ultracode` 值需要 Claude Code v2.1.203 或更高版本，並且僅由 `applyFlagSettings()` 接受，不由設置文件中的 `effortLevel` 鍵接受。629`effortLevel` 接受 [effort level](/docs/zh-TW/model-config#adjust-effort-level) 名稱。它也接受 `"ultracode"`，它以 `xhigh` 努力運行會話並打開 [ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)。`Settings` 類型聲明 `effortLevel` 沒有該值，因此在 TypeScript 中傳遞等效的 `{ ultracode: true }`。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，並且僅由 `applyFlagSettings()` 接受，不由設置文件中的 `effortLevel` 鍵接受。

630 630

631這些值被寫入標誌設置層，這是內聯 `query()` 的 `settings` 選項在啟動時填充的同一層。標誌設置位於 [settings precedence order](/zh-TW/settings#settings-precedence) 的頂部附近：它們覆蓋用戶、項目和本地設置，只有託管策略設置可以覆蓋它們。這是 [on-page precedence section](#settings-precedence) 稱為編程選項的同一層。631這些值被寫入標誌設置層，這是內聯 `query()` 的 `settings` 選項在啟動時填充的同一層。標誌設置位於 [settings precedence order](/docs/zh-TW/settings#settings-precedence) 的頂部附近：它們覆蓋用戶、項目和本地設置，只有託管策略設置可以覆蓋它們。這是 [on-page precedence section](#settings-precedence) 稱為編程選項的同一層。

632 632

633連續調用淺合併頂級鍵。第二次調用 `{ permissions: {...} }` 會替換先前調用中的整個 `permissions` 對象，而不是深度合併到其中。要從標誌層清除鍵並回退到較低優先級源，請為該鍵傳遞 `null`。傳遞 `undefined` 沒有效果，因為 JSON 序列化會將其刪除。633連續調用淺合併頂級鍵。第二次調用 `{ permissions: {...} }` 會替換先前調用中的整個 `permissions` 對象，而不是深度合併到其中。要從標誌層清除鍵並回退到較低優先級源，請為該鍵傳遞 `null`。傳遞 `undefined` 沒有效果，因為 JSON 序列化會將其刪除。

634 634

714 714

715* 僅出現已使用 UUID 入隊的消息。空數組並不意味著沒有其他內容會運行。715* 僅出現已使用 UUID 入隊的消息。空數組並不意味著沒有其他內容會運行。

716* 僅列出主線程消息。發送給子代理的消息超出範圍。716* 僅列出主線程消息。發送給子代理的消息超出範圍。

717* 列表可以包括您的客戶端從未發送的 UUID，例如 [scheduled task](/zh-TW/scheduled-tasks) 觸發器。忽略您不認識的 UUID，而不是將其視為錯誤。717* 列表可以包括您的客戶端從未發送的 UUID，例如 [scheduled task](/docs/zh-TW/scheduled-tasks) 觸發器。忽略您不認識的 UUID，而不是將其視為錯誤。

718 718

719收據是在處理中斷時拍攝的快照，在乾淨中斷時，它在中斷轉數的 [`SDKResultMessage`](#sdkresultmessage) 之前到達。在該結果之後讀取收據而不是檢查隊列：循環立即啟動下一個排隊轉數，因此您在結果後檢查的隊列已經改變。719收據是在處理中斷時拍攝的快照，在乾淨中斷時，它在中斷轉數的 [`SDKResultMessage`](#sdkresultmessage) 之前到達。在該結果之後讀取收據而不是檢查隊列：循環立即啟動下一個排隊轉數，因此您在結果後檢查的隊列已經改變。

720 720

792 Default behavior792 Default behavior

793</h4>793</h4>

794 794

795當 `settingSources` 被省略或 `undefined` 時，`query()` 加載與 Claude Code CLI 相同的文件系統設置：用戶、項目和本地。託管策略設置在所有情況下都會加載；當會話使用組織憑證在 [eligible configuration](/zh-TW/server-managed-settings#platform-availability) 上進行身份驗證時，會獲取服務器管理的設置。見 [What settingSources does not control](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解無論此選項如何都會讀取的輸入，以及如何禁用它們。795當 `settingSources` 被省略或 `undefined` 時，`query()` 加載與 Claude Code CLI 相同的文件系統設置：用戶、項目和本地。託管策略設置在所有情況下都會加載；當會話使用組織憑證在 [eligible configuration](/docs/zh-TW/server-managed-settings#platform-availability) 上進行身份驗證時，會獲取服務器管理的設置。見 [What settingSources does not control](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解無論此選項如何都會讀取的輸入，以及如何禁用它們。

796 796

797<h4 id="why-use-settingsources">797<h4 id="why-use-settingsources">

798 Why use settingSources798 Why use settingSources

913 913

914用於控制工具使用的自定義權限函數類型。914用於控制工具使用的自定義權限函數類型。

915 915

916函數是 SDK 替代交互式權限提示：它僅在 [permission evaluation flow](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 解決為提示時調用。已由 `allowedTools` 條目、設置 allow 規則或權限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具調用永遠不會調用它。要限制每個工具調用，改用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)。916函數是 SDK 替代交互式權限提示：它僅在 [permission evaluation flow](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 解決為提示時調用。已由 `allowedTools` 條目、設置 allow 規則或權限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具調用永遠不會調用它。要限制每個工具調用，改用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)。

917 917

918`AskUserQuestion`、標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP tools 和 connector tools [您的組織設置為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 即使 allow 規則匹配也會到達函數。在 `dontAsk` 模式下這些調用會被拒絕，無需調用它。918`AskUserQuestion`、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP tools 和 connector tools [您的組織設置為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 即使 allow 規則匹配也會到達函數。在 `dontAsk` 模式下這些調用會被拒絕，無需調用它。

919 919

920```typescript theme={null}920```typescript theme={null}

921type CanUseTool = (921type CanUseTool = (

985 985

986| 字段 | 類型 | 描述 |986| 字段 | 類型 | 描述 |

987| :------------------------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------------- |987| :------------------------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------------- |

989 989

990<h3 id="mcpserverconfig">990<h3 id="mcpserverconfig">

991 `McpServerConfig`991 `McpServerConfig`

1091];1091];

1092```1092```

1093 1093

1094有關創建和使用 plugins 的完整信息，見 [Plugins](/zh-TW/agent-sdk/plugins)。1094有關創建和使用 plugins 的完整信息，見 [Plugins](/docs/zh-TW/agent-sdk/plugins)。

1095 1095

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

1097 消息類型1097 消息類型

1210};1210};

1211```1211```

1212 1212

1213從會話外部注入的用戶轉數，其 [`origin`](#sdkmessageorigin) 類型為 `peer` 或 `channel`，無論是在活躍轉數期間傳遞還是在會話閒置時啟動新轉數，都會作為重放到達流。{/* min-version: 2.1.207 */}在 v2.1.207 之前，在會話閒置時傳遞的注入轉數在流上不產生任何消息，僅在您重新讀取記錄時出現。1213從會話外部注入的用戶轉數，其 [`origin`](#sdkmessageorigin) 類型為 `peer` 或 `channel`，無論是在活躍轉數期間傳遞還是在會話閒置時啟動新轉數，都會作為重放到達流。在 v2.1.207 之前，在會話閒置時傳遞的注入轉數在流上不產生任何消息，僅在您重新讀取記錄時出現。

1214 1214

1215<h3 id="sdkresultmessage">1215<h3 id="sdkresultmessage">

1216 `SDKResultMessage`1216 `SDKResultMessage`

1279 1279

1280`origin` 字段轉發觸發此結果的用戶消息的 [`SDKMessageOrigin`](#sdkmessageorigin)。當後台任務完成且 SDK 注入合成後續轉數時，生成的 `SDKResultMessage` 攜帶 `origin: { kind: "task-notification" }`。檢查此字段以區分回答您的提示的結果與為後台任務後續發出的結果，以便您可以路由或抑制後者。對於在任何用戶轉數之前發出的結果（例如啟動錯誤），該字段不存在。1280`origin` 字段轉發觸發此結果的用戶消息的 [`SDKMessageOrigin`](#sdkmessageorigin)。當後台任務完成且 SDK 注入合成後續轉數時，生成的 `SDKResultMessage` 攜帶 `origin: { kind: "task-notification" }`。檢查此字段以區分回答您的提示的結果與為後台任務後續發出的結果，以便您可以路由或抑制後者。對於在任何用戶轉數之前發出的結果（例如啟動錯誤），該字段不存在。

1281 1281

1282當 `PreToolUse` hook 返回 `permissionDecision: "defer"` 時，結果具有 `stop_reason: "tool_deferred"` 和 `deferred_tool_use` 攜帶待處理工具的 `id`、`name` 和 `input`。讀取此字段以在您自己的 UI 中顯示請求，然後使用相同的 `session_id` 恢復以繼續。有關完整往返，請參閱[稍後延遲工具調用](/zh-TW/hooks#defer-a-tool-call-for-later)。1282當 `PreToolUse` hook 返回 `permissionDecision: "defer"` 時，結果具有 `stop_reason: "tool_deferred"` 和 `deferred_tool_use` 攜帶待處理工具的 `id`、`name` 和 `input`。讀取此字段以在您自己的 UI 中顯示請求，然後使用相同的 `session_id` 恢復以繼續。有關完整往返，請參閱[稍後延遲工具調用](/docs/zh-TW/hooks#defer-a-tool-call-for-later)。

1283 1283

1284<h3 id="sdksystemmessage">1284<h3 id="sdksystemmessage">

1285 `SDKSystemMessage`1285 `SDKSystemMessage`

1313};1313};

1314```1314```

1315 1315

1316{/* min-version: 2.1.205 */}

~~1317~~

1318`capabilities` 陣列命名此 CLI 實現的協議行為，因此您可以進行功能檢測而不是比較 `claude_code_version` 字符串。這是一個開放集合：忽略您不認識的值，並檢查您依賴其行為的特定功能。該字段需要 Claude Code v2.1.205 或更高版本，在較早的 CLI 上不存在。1316`capabilities` 陣列命名此 CLI 實現的協議行為，因此您可以進行功能檢測而不是比較 `claude_code_version` 字符串。這是一個開放集合：忽略您不認識的值，並檢查您依賴其行為的特定功能。該字段需要 Claude Code v2.1.205 或更高版本，在較早的 CLI 上不存在。

1319 1317

1320| 功能 | 含義 |1318| 功能 | 含義 |

1396 `SDKPluginInstallMessage`1394 `SDKPluginInstallMessage`

1397</h3>1395</h3>

1398 1396

1399插件安裝進度事件。當設置 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars) 時發出，以便您的 Agent SDK 應用程式可以在第一個轉數之前追蹤市場插件安裝。`started` 和 `completed` 狀態括起整體安裝。`installed` 和 `failed` 狀態報告單個市場並包括 `name`。1397插件安裝進度事件。當設置 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/zh-TW/env-vars) 時發出，以便您的 Agent SDK 應用程式可以在第一個轉數之前追蹤市場插件安裝。`started` 和 `completed` 狀態括起整體安裝。`installed` 和 `failed` 狀態報告單個市場並包括 `name`。

1400 1398

1401```typescript theme={null}1399```typescript theme={null}

1402type SDKPluginInstallMessage = {1400type SDKPluginInstallMessage = {

1479```1477```

1480 1478

1481| `kind` | 含義 |1479| `kind` | 含義 |

1482| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1480| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1485| `peer` | 來自另一個代理的消息。對於通過 `SendMessage` 發送到 `main` 的進程內[隊友](/zh-TW/agent-teams)，`from` 是隊友的名稱，`senderTaskId` 是其任務 ID。對於跨會話對等體（例如另一個本地 Claude Code 進程），`from` 是發送者地址，`senderTaskId` 不存在。{/* min-version: 2.1.205 */}}`name` 和 `body` 需要 Claude Code v2.1.205 或更高版本。`name` 是發送者的顯示名稱，由 Claude Code 規範化：它去除 Unicode 控制、格式、代理和行或段落分隔符代碼點，然後修剪結果並將其限制為 64 個代碼點，並帶有省略號。`body` 是去除對等信封的已解碼消息正文，與模型看到的內容完全相同。對於隊友消息，`body` 始終存在；對於跨會話對等體，僅當轉數恰好是由 Claude Code 形成的一個對等信封時才存在。呈現 `name` 和 `body` 而不是重新解析消息文本。 |1483| `peer` | 來自另一個代理的消息。對於通過 `SendMessage` 發送到 `main` 的進程內[隊友](/docs/zh-TW/agent-teams)，`from` 是隊友的名稱，`senderTaskId` 是其任務 ID。對於跨會話對等體（例如另一個本地 Claude Code 進程），`from` 是發送者地址，`senderTaskId` 不存在。}`name` 和 `body` 需要 Claude Code v2.1.205 或更高版本。`name` 是發送者的顯示名稱，由 Claude Code 規範化：它去除 Unicode 控制、格式、代理和行或段落分隔符代碼點，然後修剪結果並將其限制為 64 個代碼點，並帶有省略號。`body` 是去除對等信封的已解碼消息正文，與模型看到的內容完全相同。對於隊友消息，`body` 始終存在；對於跨會話對等體，僅當轉數恰好是由 Claude Code 形成的一個對等信封時才存在。呈現 `name` 和 `body` 而不是重新解析消息文本。 |

1489 1487

1490<h2 id="hook-types">1488<h2 id="hook-types">

1491 Hook 類型1489 Hook 類型

1492</h2>1490</h2>

1493 1491

1494有關使用 hooks 的綜合指南，包括示例和常見模式，見 [Hooks 指南](/zh-TW/agent-sdk/hooks)。1492有關使用 hooks 的綜合指南，包括示例和常見模式，見 [Hooks 指南](/docs/zh-TW/agent-sdk/hooks)。

1495 1493

1496<h3 id="hookevent">1494<h3 id="hookevent">

1497 `HookEvent`1495 `HookEvent`

1600};1598};

1601```1599```

1602 1600

1603`prompt_id` 欄位是一個 UUID，用於識別目前正在處理的使用者提示。它與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/zh-TW/monitoring-usage#event-correlation-attributes)相符，在第一個使用者輸入之前不存在。需要 Claude Code v2.1.196 或更新版本。1601`prompt_id` 欄位是一個 UUID，用於識別目前正在處理的使用者提示。它與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/docs/zh-TW/monitoring-usage#event-correlation-attributes)相符，在第一個使用者輸入之前不存在。需要 Claude Code v2.1.196 或更新版本。

1604 1602

1605<h4 id="pretoolusehookinput">1603<h4 id="pretoolusehookinput">

1606 `PreToolUseHookInput`1604 `PreToolUseHookInput`

2071};2069};

2072```2070```

2073 2071

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

2075 2073

2076<h3 id="bash">2074<h3 id="bash">

2077 Bash2075 Bash

2110};2108};

2111```2109```

2112 2110

2113運行後台來源並將每個事件傳遞給 Claude，以便它可以在不輪詢的情況下做出反應：`command` 運行腳本並每個 stdout 行發出一個事件，`ws` 打開 WebSocket 並每個文本幀發出一個事件。提供 `command` 或 `ws` 中的恰好一個。{/* min-version: 2.1.195 */}`ws` 來源需要 Claude Code v2.1.195 或更高版本。2111運行後台來源並將每個事件傳遞給 Claude，以便它可以在不輪詢的情況下做出反應：`command` 運行腳本並每個 stdout 行發出一個事件，`ws` 打開 WebSocket 並每個文本幀發出一個事件。提供 `command` 或 `ws` 中的恰好一個。`ws` 來源需要 Claude Code v2.1.195 或更高版本。

2114 2112

2115為會話長度的監視（如日誌尾部）設置 `persistent: true`。Monitor 運行命令時，遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示批准。見 [Monitor 工具參考](/zh-TW/tools-reference#monitor-tool) 了解行為和提供商可用性。2113為會話長度的監視（如日誌尾部）設置 `persistent: true`。Monitor 運行命令時，遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示批准。見 [Monitor 工具參考](/docs/zh-TW/tools-reference#monitor-tool) 了解行為和提供商可用性。

2116 2114

2117<h3 id="taskoutput">2115<h3 id="taskoutput">

2118 TaskOutput2116 TaskOutput

2234};2232};

2235```2233```

2236 2234

2237按 ID 停止運行的後台任務或 shell。{/* min-version: 2.1.198 */}自 v2.1.198 起，`task_id` 也接受代理團隊隊友或按代理 ID 或名稱的命名後台代理。2235按 ID 停止運行的後台任務或 shell。自 v2.1.198 起，`task_id` 也接受代理團隊隊友或按代理 ID 或名稱的命名後台代理。

2238 2236

2239<h3 id="notebookedit">2237<h3 id="notebookedit">

2240 NotebookEdit2238 NotebookEdit

2301};2299};

2302```2300```

2303 2301

2304運行 [動態工作流](/zh-TW/workflows)：一個在後台協調許多子代理並返回一個統一結果的腳本。`Workflow` 工具在 Agent SDK v0.3.149 及更高版本中可用。至少需要 `script`、`name` 或 `scriptPath` 之一。2302運行 [動態工作流](/docs/zh-TW/workflows)：一個在後台協調許多子代理並返回一個統一結果的腳本。`Workflow` 工具在 Agent SDK v0.3.149 及更高版本中可用。至少需要 `script`、`name` 或 `scriptPath` 之一。

2305 2303

2306| 字段 | 類型 | 描述 |2304| 字段 | 類型 | 描述 |

2307| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2305| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2330創建和管理結構化任務列表以跟蹤進度。2328創建和管理結構化任務列表以跟蹤進度。

2331 2329

2332<Note>2330<Note>

2333 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 預設為禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。見 [遷移到 Task 工具](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 更新您的監視代碼，或設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢復為 `TodoWrite`。2331 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 預設為禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。見 [遷移到 Task 工具](/docs/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 更新您的監視代碼，或設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢復為 `TodoWrite`。

2334</Note>2332</Note>

2335 2333

2336<h3 id="taskcreate">2334<h3 id="taskcreate">

2570 2568

2571返回子代理的結果。在 `status` 字段上區分：`"completed"` 用於已完成的任務，`"async_launched"` 用於後台任務，以及 `"remote_launched"` 用於 Claude Code 分派到遠端雲端工作階段的任務，其中 `sessionUrl` 連結到該工作階段，`taskId` 識別它。2569返回子代理的結果。在 `status` 字段上區分：`"completed"` 用於已完成的任務，`"async_launched"` 用於後台任務，以及 `"remote_launched"` 用於 Claude Code 分派到遠端雲端工作階段的任務，其中 `sessionUrl` 連結到該工作階段，`taskId` 識別它。

2572 2570

2573`completed` 和 `async_launched` 變體上的 `resolvedModel` 字段命名子代理實際運行的模型，當應用 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 或其他覆蓋時，該模型可能與請求的 `model` 輸入不同。{/* min-version: 2.1.174 */}此字段需要 Claude Code v2.1.174 或更高版本。2571`completed` 和 `async_launched` 變體上的 `resolvedModel` 字段命名子代理實際運行的模型，當應用 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 或其他覆蓋時，該模型可能與請求的 `model` 輸入不同。此字段需要 Claude Code v2.1.174 或更高版本。

2574 2572

2575在 `completed` 變體上，當子代理在隔離的 git worktree 中運行時，`worktreePath` 被設置，當 Claude Code 創建它時，`worktreeBranch` 命名該 worktree 的分支。`usage.service_tier` 攜帶 API 為子代理的請求報告的服務層字符串。2573在 `completed` 變體上，當子代理在隔離的 git worktree 中運行時，`worktreePath` 被設置，當 Claude Code 創建它時，`worktreeBranch` 命名該 worktree 的分支。`usage.service_tier` 攜帶 API 為子代理的請求報告的服務層字符串。

2576 2574

2936返回之前和更新的任務列表。2934返回之前和更新的任務列表。

2937 2935

2938<Note>2936<Note>

2939 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 預設為禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。請參閱[遷移到 Task 工具](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools)以更新您的監視代碼，或設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢復為 `TodoWrite`。2937 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 預設為禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。請參閱[遷移到 Task 工具](/docs/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools)以更新您的監視代碼，或設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢復為 `TodoWrite`。

2940</Note>2938</Note>

2941 2939

2942<h3 id="taskcreate-2">2940<h3 id="taskcreate-2">

3230```3228```

3231 3229

3232| 字段 | 類型 | 描述 |3230| 字段 | 類型 | 描述 |

3233| :------------------------- | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3231| :------------------------- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |

3235| `resolvedModel` | `string \| undefined` | 此項目的 `value` 解析為的規範線路模型 ID。別名項目（如 `sonnet`）解析為明確的模型 ID（如 `claude-sonnet-5`），因此主機可以將儲存的明確模型 ID 與涵蓋它的別名項目進行匹配。{/* min-version: 2.1.197 */}需要 Claude Code v2.1.197 或更高版本。 |3233| `resolvedModel` | `string \| undefined` | 此項目的 `value` 解析為的規範線路模型 ID。別名項目（如 `sonnet`）解析為明確的模型 ID（如 `claude-sonnet-5`），因此主機可以將儲存的明確模型 ID 與涵蓋它的別名項目進行匹配。需要 Claude Code v2.1.197 或更高版本。 |

3327 `ModelUsage`3325 `ModelUsage`

3328</h3>3326</h3>

3329 3327

3330結果消息中返回的每個模型使用統計。`costUSD` 值是客戶端估計。見 [跟蹤成本和使用情況](/zh-TW/agent-sdk/cost-tracking) 了解計費注意事項。3328結果消息中返回的每個模型使用統計。`costUSD` 值是客戶端估計。見 [跟蹤成本和使用情況](/docs/zh-TW/agent-sdk/cost-tracking) 了解計費注意事項。

3331 3329

3332```typescript theme={null}3330```typescript theme={null}

3333type ModelUsage = {3331type ModelUsage = {

3392 `CallToolResult`3390 `CallToolResult`

3393</h3>3391</h3>

3394 3392

3395MCP 工具結果類型（來自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是一個 JSON 對象，可以與 `content` 一起返回，包括圖像塊。見 [返回結構化數據](/zh-TW/agent-sdk/custom-tools#return-structured-data)。3393MCP 工具結果類型（來自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是一個 JSON 對象，可以與 `content` 一起返回，包括圖像塊。見 [返回結構化數據](/docs/zh-TW/agent-sdk/custom-tools#return-structured-data)。

3396 3394

3397```typescript theme={null}3395```typescript theme={null}

3398type CallToolResult = {3396type CallToolResult = {

3742 3740

3743啟動時不發出任何內容。每當會話的 CLI 進程啟動或重新啟動時重置為空集，並讓下一個成員資格變化重新填充它。3741啟動時不發出任何內容。每當會話的 CLI 進程啟動或重新啟動時重置為空集，並讓下一個成員資格變化重新填充它。

3744 3742

3745{/* min-version: 2.1.203 */}需要 Claude Code v2.1.203 或更高版本。3743需要 Claude Code v2.1.203 或更高版本。

3746 3744

3747```typescript theme={null}3745```typescript theme={null}

3748type SDKBackgroundTasksChangedMessage = {3746type SDKBackgroundTasksChangedMessage = {

3762 `SDKThinkingTokensMessage`3760 `SDKThinkingTokensMessage`

3763</h3>3761</h3>

3764 3762

3765在 Claude 生成思考塊（包括編輯過的思考塊）時發出，帶有迄今為止生成的思考令牌的運行估計。`estimated_tokens` 是當前思考塊的運行總計，`estimated_tokens_delta` 是此幀攜帶的增量。將其用於進度顯示。頂級代理循環的最終計數是結果消息的 `usage.output_tokens`，它[不包括子代理令牌](/zh-TW/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)；使用 [`modelUsage`](#modelusage) 進行整樹會計。3763在 Claude 生成思考塊（包括編輯過的思考塊）時發出，帶有迄今為止生成的思考令牌的運行估計。`estimated_tokens` 是當前思考塊的運行總計，`estimated_tokens_delta` 是此幀攜帶的增量。將其用於進度顯示。頂級代理循環的最終計數是結果消息的 `usage.output_tokens`，它[不包括子代理令牌](/docs/zh-TW/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)；使用 [`modelUsage`](#modelusage) 進行整樹會計。

3766 3764

3767{/* min-version: 2.1.153 */}需要 Claude Code v2.1.153 或更高版本。3765需要 Claude Code v2.1.153 或更高版本。

3768 3766

3769```typescript theme={null}3767```typescript theme={null}

3770type SDKThinkingTokensMessage = {3768type SDKThinkingTokensMessage = {

3817};3815};

3818```3816```

3819 3817

3820{/* min-version: 2.1.181 */}當 `errorCode` 為 `"credits_required"` 時，拒絕來自 claude.ai 訂閱，其包含的使用量已耗盡，會話無法繼續，直到用戶購買使用額度。`canUserPurchaseCredits` 指示經過身份驗證的用戶是否可以為帳戶購買額度，`hasChargeableSavedPaymentMethod` 指示是否有保存的付款方式。這三個字段在非信用額度必需拒絕的速率限制事件上不存在。需要 Claude Code v2.1.181 或更高版本。3818當 `errorCode` 為 `"credits_required"` 時，拒絕來自 claude.ai 訂閱，其包含的使用量已耗盡，會話無法繼續，直到用戶購買使用額度。`canUserPurchaseCredits` 指示經過身份驗證的用戶是否可以為帳戶購買額度，`hasChargeableSavedPaymentMethod` 指示是否有保存的付款方式。這三個字段在非信用額度必需拒絕的速率限制事件上不存在。需要 Claude Code v2.1.181 或更高版本。

3821 3819

3822<h3 id="sdklocalcommandoutputmessage">3820<h3 id="sdklocalcommandoutputmessage">

3823 `SDKLocalCommandOutputMessage`3821 `SDKLocalCommandOutputMessage`

3881};3879};

3882```3880```

3883 3881

3884{/* min-version: 2.1.203 */}SDK 的已發佈類型在 Claude Code v2.1.203 及更高版本中聲明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用該類型而不聲明它，因此當 `skipLibCheck` 被禁用時，在 `type === "conversation_reset"` 上縮小範圍失敗類型檢查。3882SDK 的已發佈類型在 Claude Code v2.1.203 及更高版本中聲明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用該類型而不聲明它，因此當 `skipLibCheck` 被禁用時，在 `type === "conversation_reset"` 上縮小範圍失敗類型檢查。

3885 3883

3886<h3 id="aborterror">3884<h3 id="aborterror">

3887 `AbortError`3885 `AbortError`

3932| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 沙箱環境中的自訂 ripgrep 二進制配置 |3930| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 沙箱環境中的自訂 ripgrep 二進制配置 |

3933 3931

3934<Note>3932<Note>

3935 沙箱取決於平台支援，在 Linux 上，還需要 `bubblewrap` 和 `socat` 等工具。當 `enabled` 為 `true` 且沙箱無法啟動時，`query()` 會報告一條 `result` 訊息，其中 `subtype: "error_during_execution"`，並在 `errors` 中包含原因。對於單一訊息 `query()` 呼叫，SDK 會在產生該錯誤結果後拋出異常，因此請將迴圈包裝在 try 區塊中以繼續執行。請參閱[處理結果](/zh-TW/agent-sdk/agent-loop#handle-the-result)以了解錯誤合約。3933 沙箱取決於平台支援，在 Linux 上，還需要 `bubblewrap` 和 `socat` 等工具。當 `enabled` 為 `true` 且沙箱無法啟動時，`query()` 會報告一條 `result` 訊息，其中 `subtype: "error_during_execution"`，並在 `errors` 中包含原因。對於單一訊息 `query()` 呼叫，SDK 會在產生該錯誤結果後拋出異常，因此請將迴圈包裝在 try 區塊中以繼續執行。請參閱[處理結果](/docs/zh-TW/agent-sdk/agent-loop#handle-the-result)以了解錯誤合約。

3936 3934

3937 要改為運行無沙箱，請設置 `failIfUnavailable: false`。3935 要改為運行無沙箱，請設置 `failIfUnavailable: false`。

3938</Note>3936</Note>

3974 `SandboxNetworkConfig`3972 `SandboxNetworkConfig`

3975</h3>3973</h3>

3976 3974

3977沙箱模式的網絡特定配置。這些設置適用於當父級 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 為 `true` 時的沙箱化 Bash 命令。它們不限制 WebFetch 工具，該工具改用[權限規則](/zh-TW/permissions#webfetch)。3975沙箱模式的網絡特定配置。這些設置適用於當父級 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 為 `true` 時的沙箱化 Bash 命令。它們不限制 WebFetch 工具，該工具改用[權限規則](/docs/zh-TW/permissions#webfetch)。

3978 3976

3979```typescript theme={null}3977```typescript theme={null}

3980type SandboxNetworkConfig = {3978type SandboxNetworkConfig = {

3993| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------- |3991| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------- |

4002 4000

4003<Note>4001<Note>

4004 內置沙箱代理根據請求的主機名強制執行 `allowedDomains`，並且不終止或檢查 TLS 流量，因此[網域前置](https://en.wikipedia.org/wiki/Domain_fronting)等技術可能會繞過它。有關詳細資訊，請參閱[沙箱安全限制](/zh-TW/sandboxing#security-limitations)，以及[安全部署](/zh-TW/agent-sdk/secure-deployment#traffic-forwarding)以配置 TLS 終止代理。4002 內置沙箱代理根據請求的主機名強制執行 `allowedDomains`，並且不終止或檢查 TLS 流量，因此[網域前置](https://en.wikipedia.org/wiki/Domain_fronting)等技術可能會繞過它。有關詳細資訊，請參閱[沙箱安全限制](/docs/zh-TW/sandboxing#security-limitations)，以及[安全部署](/docs/zh-TW/agent-sdk/secure-deployment#traffic-forwarding)以配置 TLS 終止代理。

4005</Note>4003</Note>

4006 4004

4007<h3 id="sandboxfilesystemconfig">4005<h3 id="sandboxfilesystemconfig">

4079<Warning>4077<Warning>

4080 使用 `dangerouslyDisableSandbox: true` 運行的命令具有完整的系統訪問權限。確保您的 `canUseTool` 處理程序仔細驗證這些請求。4078 使用 `dangerouslyDisableSandbox: true` 運行的命令具有完整的系統訪問權限。確保您的 `canUseTool` 處理程序仔細驗證這些請求。

4081 4079

4082 如果 `permissionMode` 設置為 `bypassPermissions` 且 `allowUnsandboxedCommands` 啟用，模型可以自主執行沙箱外的命令，無需任何批准提示（明確的[`ask` 規則](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)仍會強制執行一個）。此組合實際上允許模型無聲地逃離沙箱隔離。4080 如果 `permissionMode` 設置為 `bypassPermissions` 且 `allowUnsandboxedCommands` 啟用，模型可以自主執行沙箱外的命令，無需任何批准提示（明確的[`ask` 規則](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)仍會強制執行一個）。此組合實際上允許模型無聲地逃離沙箱隔離。

4083</Warning>4081</Warning>

4084 4082

4085<h2 id="see-also">4083<h2 id="see-also">

4086 另見4084 另見

4087</h2>4085</h2>

4088 4086

4089* [SDK 概述](/zh-TW/agent-sdk/overview) - 常規 SDK 概念4087* [SDK 概述](/docs/zh-TW/agent-sdk/overview) - 常規 SDK 概念

4090* [Python SDK 參考](/zh-TW/agent-sdk/python) - Python SDK 文檔4088* [Python SDK 參考](/docs/zh-TW/agent-sdk/python) - Python SDK 文檔

4091* [CLI 參考](/zh-TW/cli-reference) - 命令行介面4089* [CLI 參考](/docs/zh-TW/cli-reference) - 命令行介面

4092* [常見工作流](/zh-TW/common-workflows) - 分步指南4090* [常見工作流](/docs/zh-TW/common-workflows) - 分步指南

agent-sdk/user-input.md +18 −18

Details

12 12

13對於澄清問題，Claude 會生成問題和選項。您的角色是將它們呈現給使用者並返回他們的選擇。您無法將自己的問題添加到此流程中；如果您需要自己詢問使用者某些事項，請在應用程式邏輯中單獨進行。13對於澄清問題，Claude 會生成問題和選項。您的角色是將它們呈現給使用者並返回他們的選擇。您無法將自己的問題添加到此流程中；如果您需要自己詢問使用者某些事項，請在應用程式邏輯中單獨進行。

14 14

15回呼可以無限期地保持待處理狀態。執行保持暫停狀態，直到您的回呼返回，SDK 只在查詢本身被取消時才取消等待。如果使用者可能需要比您的流程合理保持運行的時間更長的時間來回應，請返回 [`defer` hook 決定](/zh-TW/hooks#defer-a-tool-call-for-later)，它允許流程退出並稍後從持久化會話恢復。15回呼可以無限期地保持待處理狀態。執行保持暫停狀態，直到您的回呼返回，SDK 只在查詢本身被取消時才取消等待。如果使用者可能需要比您的流程合理保持運行的時間更長的時間來回應，請返回 [`defer` hook 決定](/docs/zh-TW/hooks#defer-a-tool-call-for-later)，它允許流程退出並稍後從持久化會話恢復。

16 16

17本指南向您展示如何檢測每種類型的請求並做出適當的回應。17本指南向您展示如何檢測每種類型的請求並做出適當的回應。

18 18

44 44

45回呼在兩種情況下觸發：45回呼在兩種情況下觸發：

46 46

471. **工具需要批准**：Claude 想要使用未被[權限規則](/zh-TW/agent-sdk/permissions)或權限模式自動批准的工具。檢查 `tool_name` 以查看工具（例如 `"Bash"`、`"Write"`）。471. **工具需要批准**：Claude 想要使用未被[權限規則](/docs/zh-TW/agent-sdk/permissions)或權限模式自動批准的工具。檢查 `tool_name` 以查看工具（例如 `"Bash"`、`"Write"`）。

482. **Claude 提出問題**：Claude 呼叫 `AskUserQuestion` 工具。檢查 `tool_name == "AskUserQuestion"` 以不同方式處理它。如果您指定 `tools` 陣列，請包含 `AskUserQuestion` 以使其正常工作。有關詳細資訊，請參閱[處理澄清問題](#handle-clarifying-questions)。482. **Claude 提出問題**：Claude 呼叫 `AskUserQuestion` 工具。檢查 `tool_name == "AskUserQuestion"` 以不同方式處理它。如果您指定 `tools` 陣列，請包含 `AskUserQuestion` 以使其正常工作。有關詳細資訊，請參閱[處理澄清問題](#handle-clarifying-questions)。

49 49

50<Warning>50<Warning>

51 **回呼永遠不會針對自動批准的工具觸發。** [權限評估流程](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)中任何較早的批准、允許規則或 `acceptEdits` 或 `bypassPermissions` 等模式，都會在諮詢 `canUseTool` 之前解決呼叫。如果您在 `allowed_tools` 中列出工具，除非詢問規則或 `plan` 模式將呼叫路由回提示，否則該工具的 `canUseTool` 檢查永遠不會執行。對於必須應用於每個工具呼叫的邏輯，請使用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)，它在流程的其餘部分之前執行，可以允許、拒絕或修改請求。51 **回呼永遠不會針對自動批准的工具觸發。** [權限評估流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)中任何較早的批准、允許規則或 `acceptEdits` 或 `bypassPermissions` 等模式，都會在諮詢 `canUseTool` 之前解決呼叫。如果您在 `allowed_tools` 中列出工具，除非詢問規則或 `plan` 模式將呼叫路由回提示，否則該工具的 `canUseTool` 檢查永遠不會執行。對於必須應用於每個工具呼叫的邏輯，請使用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)，它在流程的其餘部分之前執行，可以允許、拒絕或修改請求。

52 52

53 `AskUserQuestion`、標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)即使在允許規則相符時也會到達回呼。在 `dontAsk` 模式中，這些呼叫會被拒絕，而不會叫用回呼。53 `AskUserQuestion`、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)即使在允許規則相符時也會到達回呼。在 `dontAsk` 模式中，這些呼叫會被拒絕，而不會叫用回呼。

54</Warning>54</Warning>

55 55

~~56您也可以使用 [`PermissionRequest` hook](/zh-TW/agent-sdk/hooks#available-hooks) 在 Claude 等待批准時發送外部通知（Slack、電子郵件、推送）。~~56您也可以使用 [`PermissionRequest` hook](/docs/zh-TW/agent-sdk/hooks#available-hooks) 在 Claude 等待批准時發送外部通知（Slack、電子郵件、推送）。

57 57

58<h2 id="handle-tool-approval-requests">58<h2 id="handle-tool-approval-requests">

59 處理工具批准請求59 處理工具批准請求

65| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |65| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

68| `options` (TS) / `context` (Python) | 其他上下文，包括可選的 `suggestions`（建議的 `PermissionUpdate` 條目以避免重新提示）和取消信號。在 TypeScript 中，`signal` 是 `AbortSignal`；在 Python 中，信號欄位保留供將來使用。有關 Python，請參閱 [`ToolPermissionContext`](/zh-TW/agent-sdk/python#toolpermissioncontext)。 |68| `options` (TS) / `context` (Python) | 其他上下文，包括可選的 `suggestions`（建議的 `PermissionUpdate` 條目以避免重新提示）和取消信號。在 TypeScript 中，`signal` 是 `AbortSignal`；在 Python 中，信號欄位保留供將來使用。有關 Python，請參閱 [`ToolPermissionContext`](/docs/zh-TW/agent-sdk/python#toolpermissioncontext)。 |

69 69

70`input` 物件包含工具特定的參數。常見範例：70`input` 物件包含工具特定的參數。常見範例：

71 71

76| `Edit` | `file_path`、`old_string`、`new_string` |76| `Edit` | `file_path`、`old_string`、`new_string` |

77| `Read` | `file_path`、`offset`、`limit` |77| `Read` | `file_path`、`offset`、`limit` |

78 78

~~79有關完整的輸入架構，請參閱 SDK 參考：[Python](/zh-TW/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/zh-TW/agent-sdk/typescript#tool-input-types)。~~79有關完整的輸入架構，請參閱 SDK 參考：[Python](/docs/zh-TW/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/docs/zh-TW/agent-sdk/typescript#tool-input-types)。

80 80

81您可以向使用者顯示此資訊，以便他們可以決定是否允許或拒絕該操作，然後返回適當的回應。81您可以向使用者顯示此資訊，以便他們可以決定是否允許或拒絕該操作，然後返回適當的回應。

82 82

200</CodeGroup>200</CodeGroup>

201 201

202<Note>202<Note>

203 在 Python 中，`can_use_tool` 需要[串流模式](/zh-TW/agent-sdk/streaming-vs-single-mode)。當您透過 `query(prompt=generator)` 或 `ClaudeSDKClient.connect(prompt=async_iterable)` 傳遞有限的訊息流時，SDK 會在最後一條訊息之後關閉輸入流，在權限回呼可以被調用之前，除非已註冊的 hook 或進程內 MCP 伺服器保持它開放。上面的範例使用返回 `{"continue_": True}` 的 `PreToolUse` hook 保持它開放。使用沒有提示的連接並透過 `ClaudeSDKClient.query()` 發送訊息會自動保持流開放，不需要 hook。203 在 Python 中，`can_use_tool` 需要[串流模式](/docs/zh-TW/agent-sdk/streaming-vs-single-mode)。當您透過 `query(prompt=generator)` 或 `ClaudeSDKClient.connect(prompt=async_iterable)` 傳遞有限的訊息流時，SDK 會在最後一條訊息之後關閉輸入流，在權限回呼可以被調用之前，除非已註冊的 hook 或進程內 MCP 伺服器保持它開放。上面的範例使用返回 `{"continue_": True}` 的 `PreToolUse` hook 保持它開放。使用沒有提示的連接並透過 `ClaudeSDKClient.query()` 發送訊息會自動保持流開放，不需要 hook。

204</Note>204</Note>

205 205

206此範例使用 y/n 流程，其中除 `y` 以外的任何輸入都被視為拒絕。在實踐中，您可能會構建一個更豐富的 UI，讓使用者修改請求、提供回饋或完全重定向 Claude。有關所有回應方式，請參閱[回應工具請求](#respond-to-tool-requests)。206此範例使用 y/n 流程，其中除 `y` 以外的任何輸入都被視為拒絕。在實踐中，您可能會構建一個更豐富的 UI，讓使用者修改請求、提供回饋或完全重定向 Claude。有關所有回應方式，請參閱[回應工具請求](#respond-to-tool-requests)。

216| **允許** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` |216| **允許** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` |

217| **拒絕** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` |217| **拒絕** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` |

218 218

219允許時，工具會使用 Claude 要求的輸入執行，除非您返回修改的輸入，TypeScript 中為 `updatedInput` 或 Python 中為 `updated_input`。{/* min-version: 2.1.207 */}在 v2.1.207 之前，Claude Code 拒絕了省略 `updatedInput` 的允許結果，並以驗證錯誤拒絕了工具呼叫。219允許時，工具會使用 Claude 要求的輸入執行，除非您返回修改的輸入，TypeScript 中為 `updatedInput` 或 Python 中為 `updated_input`。在 v2.1.207 之前，Claude Code 拒絕了省略 `updatedInput` 的允許結果，並以驗證錯誤拒絕了工具呼叫。

220 220

221拒絕時，提供說明原因的訊息。Claude 會看到此訊息並可能調整其方法。221拒絕時，提供說明原因的訊息。Claude 會看到此訊息並可能調整其方法。

222 222

247* **批准並記住**：回應建議的權限規則，以便匹配的呼叫在下次跳過提示247* **批准並記住**：回應建議的權限規則，以便匹配的呼叫在下次跳過提示

248* **拒絕**：阻止工具並告訴 Claude 原因248* **拒絕**：阻止工具並告訴 Claude 原因

249* **建議替代方案**：阻止但引導 Claude 朝著使用者想要的方向發展249* **建議替代方案**：阻止但引導 Claude 朝著使用者想要的方向發展

250* **完全重定向**：使用[串流輸入](/zh-TW/agent-sdk/streaming-vs-single-mode)向 Claude 發送全新指令250* **完全重定向**：使用[串流輸入](/docs/zh-TW/agent-sdk/streaming-vs-single-mode)向 Claude 發送全新指令

251 251

252<Tabs>252<Tabs>

253 <Tab title="批准">253 <Tab title="批准">

311 </Tab>311 </Tab>

312 312

313 <Tab title="批准並記住">313 <Tab title="批准並記住">

314 使用者批准且不想再被詢問此類呼叫。第三個回呼參數帶有 `suggestions`，這是現成的 [`PermissionUpdate`](/zh-TW/agent-sdk/typescript#permissionupdate) 條目陣列。在 `updatedPermissions` 中回應其中一個以應用它。具有 `localSettings` 目的地的建議會將規則寫入 `.claude/settings.local.json`，以便未來的工作階段跳過匹配呼叫的提示。314 使用者批准且不想再被詢問此類呼叫。第三個回呼參數帶有 `suggestions`，這是現成的 [`PermissionUpdate`](/docs/zh-TW/agent-sdk/typescript#permissionupdate) 條目陣列。在 `updatedPermissions` 中回應其中一個以應用它。具有 `localSettings` 目的地的建議會將規則寫入 `.claude/settings.local.json`，以便未來的工作階段跳過匹配呼叫的提示。

315 315

316 Python 範例需要 `claude-agent-sdk` 0.1.80 或更新版本。316 Python 範例需要 `claude-agent-sdk` 0.1.80 或更新版本。

317 317

415 </Tab>415 </Tab>

416 416

417 <Tab title="完全重定向">417 <Tab title="完全重定向">

418 如需完全改變方向（不只是輕推），請使用[串流輸入](/zh-TW/agent-sdk/streaming-vs-single-mode)向 Claude 直接發送新指令。這會繞過目前的工具請求，並為 Claude 提供全新的指令來遵循。418 如需完全改變方向（不只是輕推），請使用[串流輸入](/docs/zh-TW/agent-sdk/streaming-vs-single-mode)向 Claude 直接發送新指令。這會繞過目前的工具請求，並為 Claude 提供全新的指令來遵循。

419 </Tab>419 </Tab>

420</Tabs>420</Tabs>

421 421

426當 Claude 需要在具有多個有效方法的任務上獲得更多方向時，它會呼叫 `AskUserQuestion` 工具。這會使用 `toolName` 設定為 `AskUserQuestion` 的方式觸發您的 `canUseTool` 回呼。輸入包含 Claude 的問題作為多選選項，您將其顯示給使用者並返回他們的選擇。426當 Claude 需要在具有多個有效方法的任務上獲得更多方向時，它會呼叫 `AskUserQuestion` 工具。這會使用 `toolName` 設定為 `AskUserQuestion` 的方式觸發您的 `canUseTool` 回呼。輸入包含 Claude 的問題作為多選選項，您將其顯示給使用者並返回他們的選擇。

427 427

428<Tip>428<Tip>

429 澄清問題在 [`plan` 模式](/zh-TW/agent-sdk/permissions#plan-mode-plan)中特別常見，Claude 在其中探索程式碼庫並在提出計畫前提出問題。這使得計畫模式非常適合互動式工作流程，您希望 Claude 在進行更改前收集需求。429 澄清問題在 [`plan` 模式](/docs/zh-TW/agent-sdk/permissions#plan-mode-plan)中特別常見，Claude 在其中探索程式碼庫並在提出計畫前提出問題。這使得計畫模式非常適合互動式工作流程，您希望 Claude 在進行更改前收集需求。

430</Tip>430</Tip>

431 431

432以下步驟顯示如何處理澄清問題：432以下步驟顯示如何處理澄清問題：

864 串流輸入864 串流輸入

865</h3>865</h3>

866 866

867當您需要以下情況時，使用[串流輸入](/zh-TW/agent-sdk/streaming-vs-single-mode)：867當您需要以下情況時，使用[串流輸入](/docs/zh-TW/agent-sdk/streaming-vs-single-mode)：

868 868

869* **在任務中途中斷代理**：在 Claude 工作時發送取消信號或改變方向869* **在任務中途中斷代理**：在 Claude 工作時發送取消信號或改變方向

870* **提供額外上下文**：添加 Claude 需要的資訊，無需等待它詢問870* **提供額外上下文**：添加 Claude 需要的資訊，無需等待它詢問

876 自訂工具876 自訂工具

877</h3>877</h3>

878 878

879當您需要以下情況時，使用[自訂工具](/zh-TW/agent-sdk/custom-tools)：879當您需要以下情況時，使用[自訂工具](/docs/zh-TW/agent-sdk/custom-tools)：

880 880

881* **收集結構化輸入**：構建超越 `AskUserQuestion` 多選格式的表單、精靈或多步驟工作流程881* **收集結構化輸入**：構建超越 `AskUserQuestion` 多選格式的表單、精靈或多步驟工作流程

882* **整合外部批准系統**：連接到現有的票務、工作流程或批准平台882* **整合外部批准系統**：連接到現有的票務、工作流程或批准平台

888 相關資源888 相關資源

889</h2>889</h2>

890 890

891* [配置權限](/zh-TW/agent-sdk/permissions)：設定權限模式和規則891* [配置權限](/docs/zh-TW/agent-sdk/permissions)：設定權限模式和規則

892* [使用 hooks 控制執行](/zh-TW/agent-sdk/hooks)：在代理生命週期的關鍵點執行自訂程式碼892* [使用 hooks 控制執行](/docs/zh-TW/agent-sdk/hooks)：在代理生命週期的關鍵點執行自訂程式碼

893* [TypeScript SDK 參考](/zh-TW/agent-sdk/typescript#canusetool)：完整 canUseTool API 文件893* [TypeScript SDK 參考](/docs/zh-TW/agent-sdk/typescript#canusetool)：完整 canUseTool API 文件

agent-teams.md +30 −30

Details

7> 協調多個 Claude Code 實例作為團隊一起工作，具有共享任務、代理間訊息傳遞和集中管理。7> 協調多個 Claude Code 實例作為團隊一起工作，具有共享任務、代理間訊息傳遞和集中管理。

8 8

9<Warning>9<Warning>

10 Agent teams 是實驗性功能，預設為停用。透過在 [settings.json](/zh-TW/settings) 或環境中新增 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 來啟用。若沒有該變數，工作階段啟動時不會設定任何團隊、不會寫入團隊目錄，Claude 也不會生成或提議隊友。Agent teams 在工作階段恢復、任務協調和關閉行為方面有[已知限制](#limitations)。10 Agent teams 是實驗性功能，預設為停用。透過在 [settings.json](/docs/zh-TW/settings) 或環境中新增 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 來啟用。若沒有該變數，工作階段啟動時不會設定任何團隊、不會寫入團隊目錄，Claude 也不會生成或提議隊友。Agent teams 在工作階段恢復、任務協調和關閉行為方面有[已知限制](#limitations)。

11</Warning>11</Warning>

12 12

13Agent teams 讓您協調多個 Claude Code 實例一起工作。一個工作階段充當團隊主管，協調工作、分配任務並綜合結果。隊友獨立工作，各自在自己的 context window 中，並直接相互溝通。13Agent teams 讓您協調多個 Claude Code 實例一起工作。一個工作階段充當團隊主管，協調工作、分配任務並綜合結果。隊友獨立工作，各自在自己的 context window 中，並直接相互溝通。

14 14

~~15與 [subagents](/zh-TW/sub-agents) 不同，subagents 在單個工作階段內運行，只能向主代理報告，您也可以直接與個別隊友互動，無需透過主管。~~15與 [subagents](/docs/zh-TW/sub-agents) 不同，subagents 在單個工作階段內運行，只能向主代理報告，您也可以直接與個別隊友互動，無需透過主管。

16 16

17<Note>17<Note>

18 本頁描述的是 v2.1.178 版本的 agent teams。設定 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 後，生成隊友不再需要設定步驟，工作階段退出時會自動清理。在 v2.1.178 之前，您需要要求 Claude 先建立並命名團隊，Claude 使用 `TeamCreate` 和 `TeamDelete` 工具來設定和移除它。這兩個工具已不存在。Agent 工具上的 `team_name` 輸入被接受但被忽略，`TaskCreated`、`TaskCompleted` 和 `TeammateIdle` [hook payloads](/zh-TW/hooks#taskcreated) 中的 `team_name` 欄位帶有工作階段衍生的名稱，已被棄用。18 本頁描述的是 v2.1.178 版本的 agent teams。設定 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 後，生成隊友不再需要設定步驟，工作階段退出時會自動清理。在 v2.1.178 之前，您需要要求 Claude 先建立並命名團隊，Claude 使用 `TeamCreate` 和 `TeamDelete` 工具來設定和移除它。這兩個工具已不存在。Agent 工具上的 `team_name` 輸入被接受但被忽略，`TaskCreated`、`TaskCompleted` 和 `TeammateIdle` [hook payloads](/docs/zh-TW/hooks#taskcreated) 中的 `team_name` 欄位帶有工作階段衍生的名稱，已被棄用。

19</Note>19</Note>

20 20

21<h2 id="when-to-use-agent-teams">21<h2 id="when-to-use-agent-teams">

29* **使用競爭假設進行除錯**：隊友並行測試不同的理論，更快地收斂到答案29* **使用競爭假設進行除錯**：隊友並行測試不同的理論，更快地收斂到答案

30* **跨層協調**：跨越前端、後端和測試的變更，各由不同的隊友負責30* **跨層協調**：跨越前端、後端和測試的變更，各由不同的隊友負責

31 31

32Agent teams 增加了協調開銷，並使用的 tokens 遠多於單個工作階段。當隊友可以獨立運作時，它們效果最佳。對於順序任務、相同檔案編輯或具有許多依賴關係的工作，單個工作階段或 [subagents](/zh-TW/sub-agents) 更有效。32Agent teams 增加了協調開銷，並使用的 tokens 遠多於單個工作階段。當隊友可以獨立運作時，它們效果最佳。對於順序任務、相同檔案編輯或具有許多依賴關係的工作，單個工作階段或 [subagents](/docs/zh-TW/sub-agents) 更有效。

33 33

34<h3 id="compare-with-subagents">34<h3 id="compare-with-subagents">

35 與 subagents 比較35 與 subagents 比較

36</h3>36</h3>

37 37

~~38Agent teams 和 [subagents](/zh-TW/sub-agents) 都讓您並行化工作，但它們的運作方式不同。根據您的工作人員是否需要相互溝通來選擇：~~38Agent teams 和 [subagents](/docs/zh-TW/sub-agents) 都讓您並行化工作，但它們的運作方式不同。根據您的工作人員是否需要相互溝通來選擇：

39 39

40<Frame caption="Subagents 只向主代理報告結果，彼此不交談。在 agent teams 中，隊友共享任務列表、認領工作並直接相互溝通。">40<Frame caption="Subagents 只向主代理報告結果，彼此不交談。在 agent teams 中，隊友共享任務列表、認領工作並直接相互溝通。">

41 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=2f8db9b4f3705dd3ab931fbe2d96e42a" className="dark:hidden" alt="比較 subagent 和 agent team 架構的圖表。Subagents 由主代理生成、執行工作並報告結果。Agent teams 透過共享任務列表進行協調，隊友彼此直接溝通。" width="4245" height="1615" data-path="images/subagents-vs-agent-teams-light.png" />41 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=2f8db9b4f3705dd3ab931fbe2d96e42a" className="dark:hidden" alt="比較 subagent 和 agent team 架構的圖表。Subagents 由主代理生成、執行工作並報告結果。Agent teams 透過共享任務列表進行協調，隊友彼此直接溝通。" width="4245" height="1615" data-path="images/subagents-vs-agent-teams-light.png" />

57 啟用 agent teams57 啟用 agent teams

58</h2>58</h2>

59 59

~~60Agent teams 預設為停用。透過將 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 環境變數設定為 `1`，在您的 shell 環境或透過 [settings.json](/zh-TW/settings) 來啟用：~~60Agent teams 預設為停用。透過將 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 環境變數設定為 `1`，在您的 shell 環境或透過 [settings.json](/docs/zh-TW/settings) 來啟用：

61 61

62```json settings.json theme={null}62```json settings.json theme={null}

63{63{

81one on UX, one on technical architecture, one playing devil's advocate.81one on UX, one on technical architecture, one playing devil's advocate.

82```82```

83 83

~~84從那裡，Claude 會建立一個[共享任務列表](/zh-TW/interactive-mode#task-list)，為每個觀點生成隊友，讓他們探索問題，並在完成時綜合發現。~~84從那裡，Claude 會建立一個[共享任務列表](/docs/zh-TW/interactive-mode#task-list)，為每個觀點生成隊友，讓他們探索問題，並在完成時綜合發現。

85 85

86主管的終端在提示輸入下方的 agent 面板中列出隊友。從面板中：86主管的終端在提示輸入下方的 agent 面板中列出隊友。從面板中：

87 87

89* **Enter**：開啟所選隊友的記錄並直接向其傳送訊息89* **Enter**：開啟所選隊友的記錄並直接向其傳送訊息

90* **Escape**：中斷所選隊友的目前回合90* **Escape**：中斷所選隊友的目前回合

91 91

92{/* min-version: 2.1.199 */}自 v2.1.199 起，當任何隊友或子 agent 仍在工作時，閒置隊友的列會保留在面板中，因此您可以選擇它來檢視其記錄或向其分配更多工作。一旦面板中的每個 agent 都閒置，閒置列會在 30 秒後隱藏，並在隊友的下一個回合時重新出現；隊友在隱藏時仍保持執行狀態且可定址。在 v2.1.181 至 v2.1.198 中，閒置列在其自己的回合結束後 30 秒隱藏，即使其他隊友仍在工作；v2.1.181 之前的版本不會隱藏閒置列。92自 v2.1.199 起，當任何隊友或子 agent 仍在工作時，閒置隊友的列會保留在面板中，因此您可以選擇它來檢視其記錄或向其分配更多工作。一旦面板中的每個 agent 都閒置，閒置列會在 30 秒後隱藏，並在隊友的下一個回合時重新出現；隊友在隱藏時仍保持執行狀態且可定址。在 v2.1.181 至 v2.1.198 中，閒置列在其自己的回合結束後 30 秒隱藏，即使其他隊友仍在工作；v2.1.181 之前的版本不會隱藏閒置列。

93 93

94當超過三個隊友同時閒置時，前三個之外的列會摺疊成單一列，計算摺疊的隊友，例如當五個閒置時顯示 `2 idle agents`。選擇它並按 Enter 以展開摺疊的列，或按 Esc 以再次摺疊它們。工作中的隊友、失敗的隊友和您正在檢視的隊友始終保持自己的列。94當超過三個隊友同時閒置時，前三個之外的列會摺疊成單一列，計算摺疊的隊友，例如當五個閒置時顯示 `2 idle agents`。選擇它並按 Enter 以展開摺疊的列，或按 Esc 以再次摺疊它們。工作中的隊友、失敗的隊友和您正在檢視的隊友始終保持自己的列。

95 95

116 116

117預設值是 `"in-process"`。在 v2.1.179 之前，預設值是 `"auto"`，因此升級的工作階段如果之前開啟了分割窗格，現在會保持在一個終端中，除非您明確設定模式。設定 `"auto"` 以在您已在 tmux 工作階段內運行或您的終端是 iTerm2 時啟用分割窗格，否則回退到 in-process。`"tmux"` 設定啟用分割窗格模式，並根據您的終端自動偵測是否使用 tmux 或 iTerm2。117預設值是 `"in-process"`。在 v2.1.179 之前，預設值是 `"auto"`，因此升級的工作階段如果之前開啟了分割窗格，現在會保持在一個終端中，除非您明確設定模式。設定 `"auto"` 以在您已在 tmux 工作階段內運行或您的終端是 iTerm2 時啟用分割窗格，否則回退到 in-process。`"tmux"` 設定啟用分割窗格模式，並根據您的終端自動偵測是否使用 tmux 或 iTerm2。

118 118

119{/* min-version: 2.1.186 */}自 v2.1.186 起，設定 `"iterm2"` 以明確使用 iTerm2 原生分割窗格。此模式需要 [`it2` CLI](https://github.com/mkusaka/it2)，如果 `it2` 遺失，會顯示帶有安裝命令的錯誤。當您的終端是 iTerm2 且 tmux 可作為備用方案時，在 `"auto"` 或 `"tmux"` 下會出現提供安裝 `it2` 或切換到 tmux 的設定提示。119自 v2.1.186 起，設定 `"iterm2"` 以明確使用 iTerm2 原生分割窗格。此模式需要 [`it2` CLI](https://github.com/mkusaka/it2)，如果 `it2` 遺失，會顯示帶有安裝命令的錯誤。當您的終端是 iTerm2 且 tmux 可作為備用方案時，在 `"auto"` 或 `"tmux"` 下會出現提供安裝 `it2` 或切換到 tmux 的設定提示。

120 120

121若要覆蓋預設值，請在 `~/.claude/settings.json` 中設定 [`teammateMode`](/zh-TW/settings#available-settings)：121若要覆蓋預設值，請在 `~/.claude/settings.json` 中設定 [`teammateMode`](/docs/zh-TW/settings#available-settings)：

122 122

123```json theme={null}123```json theme={null}

124{124{

150 150

151隊友預設不會繼承主管的 `/model` 選擇。若要變更在提示未指定模型時使用的模型，請在 `/config` 中設定**預設隊友模型**。選擇\*\*預設（主管的模型）\*\*以讓隊友遵循主管的目前模型。151隊友預設不會繼承主管的 `/model` 選擇。若要變更在提示未指定模型時使用的模型，請在 `/config` 中設定**預設隊友模型**。選擇\*\*預設（主管的模型）\*\*以讓隊友遵循主管的目前模型。

152 152

153{/* min-version: 2.1.186 */}隊友繼承主管的[努力程度](/zh-TW/model-config#adjust-effort-level)。在分割窗格模式中，這從 v2.1.186 開始適用；較早的版本未將主管的工作階段努力傳遞給分割窗格隊友。153隊友繼承主管的[努力程度](/docs/zh-TW/model-config#adjust-effort-level)。在分割窗格模式中，這從 v2.1.186 開始適用；較早的版本未將主管的工作階段努力傳遞給分割窗格隊友。

154 154

155<h3 id="require-plan-approval-for-teammates">155<h3 id="require-plan-approval-for-teammates">

156 要求隊友的計畫批准156 要求隊友的計畫批准

176* **In-process 模式**：使用上下箭頭鍵在 agent 面板中選擇隊友，然後按 Enter 鍵查看其工作階段並輸入以傳送訊息。在選定的隊友上按 `x` 以停止它。按 Ctrl+T 切換任務列表。176* **In-process 模式**：使用上下箭頭鍵在 agent 面板中選擇隊友，然後按 Enter 鍵查看其工作階段並輸入以傳送訊息。在選定的隊友上按 `x` 以停止它。按 Ctrl+T 切換任務列表。

177* **Split-pane 模式**：點擊隊友的窗格以直接與其工作階段互動。每個隊友都有自己終端的完整檢視。177* **Split-pane 模式**：點擊隊友的窗格以直接與其工作階段互動。每個隊友都有自己終端的完整檢視。

178 178

179當您正在查看 in-process 隊友時，純文字和 [skills](/zh-TW/skills) 會傳送給該隊友，但內建命令仍在主管的工作階段中運行。179當您正在查看 in-process 隊友時，純文字和 [skills](/docs/zh-TW/skills) 會傳送給該隊友，但內建命令仍在主管的工作階段中運行。

180 180

181隊友的模型和快速模式在它生成時是固定的，因此 `/model` 和 `/fast` 只會變更主管的設定。{/* min-version: 2.1.199 */}自 v2.1.199 起，在查看隊友時輸入任一命令會顯示通知，表示變更適用於主管；較早的版本會將其應用於主管而不提示。`/effort` 仍適用於所查看隊友的後續回合，因為隊友遵循主管的[努力程度](/zh-TW/model-config#adjust-effort-level)。181隊友的模型和快速模式在它生成時是固定的，因此 `/model` 和 `/fast` 只會變更主管的設定。自 v2.1.199 起，在查看隊友時輸入任一命令會顯示通知，表示變更適用於主管；較早的版本會將其應用於主管而不提示。`/effort` 仍適用於所查看隊友的後續回合，因為隊友遵循主管的[努力程度](/docs/zh-TW/model-config#adjust-effort-level)。

182 182

183<h3 id="assign-and-claim-tasks">183<h3 id="assign-and-claim-tasks">

184 分配和認領任務184 分配和認領任務

211 使用 hooks 強制執行品質閘門211 使用 hooks 強制執行品質閘門

212</h3>212</h3>

213 213

214使用 [hooks](/zh-TW/hooks) 在隊友完成工作或任務建立或完成時強制執行規則：214使用 [hooks](/docs/zh-TW/hooks) 在隊友完成工作或任務建立或完成時強制執行規則：

215 215

216* [`TeammateIdle`](/zh-TW/hooks#teammateidle)：當隊友即將閒置時運行。以代碼 2 退出以發送反饋並保持隊友工作。216* [`TeammateIdle`](/docs/zh-TW/hooks#teammateidle)：當隊友即將閒置時運行。以代碼 2 退出以發送反饋並保持隊友工作。

217* [`TaskCreated`](/zh-TW/hooks#taskcreated)：當任務正在建立時運行。以代碼 2 退出以防止建立並發送反饋。217* [`TaskCreated`](/docs/zh-TW/hooks#taskcreated)：當任務正在建立時運行。以代碼 2 退出以防止建立並發送反饋。

218* [`TaskCompleted`](/zh-TW/hooks#taskcompleted)：當任務被標記為完成時運行。以代碼 2 退出以防止完成並發送反饋。218* [`TaskCompleted`](/docs/zh-TW/hooks#taskcompleted)：當任務被標記為完成時運行。以代碼 2 退出以防止完成並發送反饋。

219 219

220<h2 id="how-agent-teams-work">220<h2 id="how-agent-teams-work">

221 Agent teams 如何工作221 Agent teams 如何工作

258* **Team config**：`~/.claude/teams/{team-name}/config.json`258* **Team config**：`~/.claude/teams/{team-name}/config.json`

259* **Task list**：`~/.claude/tasks/{team-name}/`259* **Task list**：`~/.claude/tasks/{team-name}/`

260 260

261Claude Code 在工作階段啟動時自動生成這兩者，並在隊友加入、閒置或離開時更新它們。團隊配置目錄在工作階段結束時被移除。任務列表目錄在本地保留，永遠不會上傳，因此恢復的工作階段會保留其任務。保留期由您已經控制的相同 [`cleanupPeriodDays`](/zh-TW/settings#available-settings) 管理，用於工作階段記錄。261Claude Code 在工作階段啟動時自動生成這兩者，並在隊友加入、閒置或離開時更新它們。團隊配置目錄在工作階段結束時被移除。任務列表目錄在本地保留，永遠不會上傳，因此恢復的工作階段會保留其任務。保留期由您已經控制的相同 [`cleanupPeriodDays`](/docs/zh-TW/settings#available-settings) 管理，用於工作階段記錄。

262 262

263團隊配置保存運行時狀態，例如工作階段 ID 和 tmux 窗格 ID，因此不要手動編輯或預先編寫它：您的變更會在下次狀態更新時被覆蓋。263團隊配置保存運行時狀態，例如工作階段 ID 和 tmux 窗格 ID，因此不要手動編輯或預先編寫它：您的變更會在下次狀態更新時被覆蓋。

264 264

272 為隊友使用 subagent 定義272 為隊友使用 subagent 定義

273</h3>273</h3>

274 274

275生成隊友時，您可以參考來自任何 [subagent 範圍](/zh-TW/sub-agents#choose-the-subagent-scope)的 [subagent](/zh-TW/sub-agents) 類型：專案、使用者、plugin 或 CLI 定義。這讓您定義一個角色一次，例如安全審查者或測試執行者，並將其同時重複使用為委派的 subagent 和 agent team 隊友。275生成隊友時，您可以參考來自任何 [subagent 範圍](/docs/zh-TW/sub-agents#choose-the-subagent-scope)的 [subagent](/docs/zh-TW/sub-agents) 類型：專案、使用者、plugin 或 CLI 定義。這讓您定義一個角色一次，例如安全審查者或測試執行者，並將其同時重複使用為委派的 subagent 和 agent team 隊友。

276 276

277若要使用 subagent 定義，在要求 Claude 生成隊友時按名稱提及它：277若要使用 subagent 定義，在要求 Claude 生成隊友時按名稱提及它：

278 278

292 292

293隊友開始時具有主管的權限設定。如果主管使用 `--dangerously-skip-permissions` 運行，所有隊友也會這樣做。生成後，您可以更改個別隊友模式，但在生成時無法設定每個隊友的模式。293隊友開始時具有主管的權限設定。如果主管使用 `--dangerously-skip-permissions` 運行，所有隊友也會這樣做。生成後，您可以更改個別隊友模式，但在生成時無法設定每個隊友的模式。

294 294

295當一個代理透過 `SendMessage` 向另一個代理發送訊息時，接收代理會被告知它來自另一個 Claude 工作階段，而不是來自您。隊友無法批准權限提示或代表您提供同意，被拒絕某項操作的隊友無法將其轉發給另一個隊友以繞過檢查。在 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中，分類器將從另一個代理轉發的批准聲明視為不受信任的輸入，而不是來自您的確認。295當一個代理透過 `SendMessage` 向另一個代理發送訊息時，接收代理會被告知它來自另一個 Claude 工作階段，而不是來自您。隊友無法批准權限提示或代表您提供同意，被拒絕某項操作的隊友無法將其轉發給另一個隊友以繞過檢查。在 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中，分類器將從另一個代理轉發的批准聲明視為不受信任的輸入，而不是來自您的確認。

296 296

297隊友權限提示會出現在主管工作階段中，因此請在那裡自己批准它們。[Plan approval](#require-plan-approval-for-teammates) 是設計的例外：主管工作階段會授予隊友 plan approvals，無需向您發出單獨的提示。297隊友權限提示會出現在主管工作階段中，因此請在那裡自己批准它們。[Plan approval](#require-plan-approval-for-teammates) 是設計的例外：主管工作階段會授予隊友 plan approvals，無需向您發出單獨的提示。

298 298

305**隊友如何分享資訊：**305**隊友如何分享資訊：**

306 306

307* **自動訊息傳遞**：當隊友發送訊息時，它們會自動傳遞給收件人。主管不需要輪詢更新。307* **自動訊息傳遞**：當隊友發送訊息時，它們會自動傳遞給收件人。主管不需要輪詢更新。

308* **閒置通知**：當隊友完成並停止時，他們會自動通知主管。{/* min-version: 2.1.198 */}自 v2.1.198 起，隊友的回合因 API 錯誤而結束時會通知主管它失敗並包含錯誤文本，而不是看起來正常完成。308* **閒置通知**：當隊友完成並停止時，他們會自動通知主管。自 v2.1.198 起，隊友的回合因 API 錯誤而結束時會通知主管它失敗並包含錯誤文本，而不是看起來正常完成。

309* **共享任務列表**：所有代理都可以看到任務狀態並認領可用工作。309* **共享任務列表**：所有代理都可以看到任務狀態並認領可用工作。

310* **隊友訊息傳遞**：按名稱向一個特定隊友發送訊息。若要聯繫所有人，請為每個收件人發送一條訊息。310* **隊友訊息傳遞**：按名稱向一個特定隊友發送訊息。若要聯繫所有人，請為每個收件人發送一條訊息。

311 311

315 Token 使用315 Token 使用

316</h3>316</h3>

317 317

318Agent teams 使用的 tokens 遠多於單個工作階段。每個隊友都有自己的 context window，token 使用量隨活躍隊友數量而增加。對於研究、審查和新功能工作，額外的 tokens 通常是值得的。對於日常任務，單個工作階段更具成本效益。請參閱 [agent team token 成本](/zh-TW/costs#agent-team-token-costs)以了解使用指南。318Agent teams 使用的 tokens 遠多於單個工作階段。每個隊友都有自己的 context window，token 使用量隨活躍隊友數量而增加。對於研究、審查和新功能工作，額外的 tokens 通常是值得的。對於日常任務，單個工作階段更具成本效益。請參閱 [agent team token 成本](/docs/zh-TW/costs#agent-team-token-costs)以了解使用指南。

319 319

320<h2 id="use-case-examples">320<h2 id="use-case-examples">

321 使用案例範例321 使用案例範例

379 379

380隊友數量沒有硬性限制，但實際限制適用：380隊友數量沒有硬性限制，但實際限制適用：

381 381

382* **Token 成本線性增加**：每個隊友都有自己的 context window 並獨立消耗 tokens。請參閱 [agent team token 成本](/zh-TW/costs#agent-team-token-costs)以了解詳情。382* **Token 成本線性增加**：每個隊友都有自己的 context window 並獨立消耗 tokens。請參閱 [agent team token 成本](/docs/zh-TW/costs#agent-team-token-costs)以了解詳情。

383* **協調開銷增加**：更多隊友意味著更多通訊、任務協調和潛在衝突383* **協調開銷增加**：更多隊友意味著更多通訊、任務協調和潛在衝突

384* **收益遞減**：超過一定點後，額外的隊友不會按比例加快工作384* **收益遞減**：超過一定點後，額外的隊友不會按比例加快工作

385 385

386對於大多數工作流程，從 3-5 個隊友開始。這平衡了並行工作與可管理的協調。本指南中的範例使用 3-5 個隊友，因為該範圍在不同任務類型中效果很好。386對於大多數工作流程，從 3-5 個隊友開始。這平衡了並行工作與可管理的協調。本指南中的範例使用 3-5 個隊友，因為該範圍在不同任務類型中效果很好。

387 387

388每個隊友有 5-6 個[任務](/zh-TW/agent-teams#architecture)可以保持每個人的生產力，而不會過度的上下文切換。如果您有 15 個獨立任務，3 個隊友是一個很好的起點。388每個隊友有 5-6 個[任務](/docs/zh-TW/agent-teams#architecture)可以保持每個人的生產力，而不會過度的上下文切換。如果您有 15 個獨立任務，3 個隊友是一個很好的起點。

389 389

390只有當工作真正受益於隊友同時工作時才擴展。三個專注的隊友通常優於五個分散的隊友。390只有當工作真正受益於隊友同時工作時才擴展。三個專注的隊友通常優於五個分散的隊友。

391 391

452 過多權限提示452 過多權限提示

453</h3>453</h3>

454 454

455隊友權限請求冒泡到主管，這可能會造成摩擦。在生成隊友之前在 [permission settings](/zh-TW/permissions) 中預批准常見操作以減少中斷。455隊友權限請求冒泡到主管，這可能會造成摩擦。在生成隊友之前在 [permission settings](/docs/zh-TW/permissions) 中預批准常見操作以減少中斷。

456 456

457<h3 id="teammates-stopping-on-errors">457<h3 id="teammates-stopping-on-errors">

458 隊友在錯誤時停止458 隊友在錯誤時停止

463* 直接給他們額外的指示463* 直接給他們額外的指示

464* 生成替換隊友以繼續工作464* 生成替換隊友以繼續工作

465 465

466{/* min-version: 2.1.198 */}自 v2.1.198 起，來自主管或另一隊友的訊息會喚醒正在等待重試失敗 API 請求的 in-process 隊友，因此它會立即重試，而不是等待完整的重試延遲。466自 v2.1.198 起，來自主管或另一隊友的訊息會喚醒正在等待重試失敗 API 請求的 in-process 隊友，因此它會立即重試，而不是等待完整的重試延遲。

467 467

468<h3 id="lead-shuts-down-before-work-is-done">468<h3 id="lead-shuts-down-before-work-is-done">

469 主管在工作完成前關閉469 主管在工作完成前關閉

493* **關閉可能很慢**：隊友在關閉前完成其目前請求或工具呼叫，這可能需要時間。493* **關閉可能很慢**：隊友在關閉前完成其目前請求或工具呼叫，這可能需要時間。

494* **每個工作階段一個團隊**：一個工作階段恰好有一個團隊，範圍限於該工作階段。您無法建立其他具名團隊或在工作階段之間共享團隊。494* **每個工作階段一個團隊**：一個工作階段恰好有一個團隊，範圍限於該工作階段。您無法建立其他具名團隊或在工作階段之間共享團隊。

495* **沒有嵌套團隊**：隊友無法生成自己的隊友。只有主管可以管理團隊。495* **沒有嵌套團隊**：隊友無法生成自己的隊友。只有主管可以管理團隊。

496* **沒有來自 in-process 隊友的背景子代理**：in-process 隊友自己的子代理在前景中執行。要求背景子代理，無論是使用 `run_in_background` 或設定 `background: true` 的子代理定義，都會傳回錯誤，因為隊友的背景工作無法超越主管的程序。從主要對話啟動的子代理遵循[背景預設](/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。496* **沒有來自 in-process 隊友的背景子代理**：in-process 隊友自己的子代理在前景中執行。要求背景子代理，無論是使用 `run_in_background` 或設定 `background: true` 的子代理定義，都會傳回錯誤，因為隊友的背景工作無法超越主管的程序。從主要對話啟動的子代理遵循[背景預設](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。

497* **主管是固定的**：主要工作階段在其生命週期內是主管。您無法將隊友提升為主管或轉移領導權。497* **主管是固定的**：主要工作階段在其生命週期內是主管。您無法將隊友提升為主管或轉移領導權。

498* **權限在生成時設定**：所有隊友開始時具有主管的權限模式。您可以在生成後更改個別隊友模式，但在生成時無法設定每個隊友的模式。498* **權限在生成時設定**：所有隊友開始時具有主管的權限模式。您可以在生成後更改個別隊友模式，但在生成時無法設定每個隊友的模式。

499* **分割窗格需要 tmux 或 iTerm2**：預設 in-process 模式在任何終端中工作。VS Code 的整合終端、Windows Terminal 或 Ghostty 不支援分割窗格模式。499* **分割窗格需要 tmux 或 iTerm2**：預設 in-process 模式在任何終端中工作。VS Code 的整合終端、Windows Terminal 或 Ghostty 不支援分割窗格模式。

508 508

509探索並行工作和委派的相關方法：509探索並行工作和委派的相關方法：

510 510

511* **輕量級委派**：[subagents](/zh-TW/sub-agents) 在您的工作階段內為研究或驗證生成幫助代理，更適合不需要代理間協調的任務511* **輕量級委派**：[subagents](/docs/zh-TW/sub-agents) 在您的工作階段內為研究或驗證生成幫助代理，更適合不需要代理間協調的任務

512* **手動並行工作階段**：[Git worktrees](/zh-TW/worktrees) 讓您自己運行多個 Claude Code 工作階段，無需自動化團隊協調512* **手動並行工作階段**：[Git worktrees](/docs/zh-TW/worktrees) 讓您自己運行多個 Claude Code 工作階段，無需自動化團隊協調

513* **比較方法**：請參閱 [subagent vs agent team](/zh-TW/features-overview#compare-similar-features) 比較以了解並排細分513* **比較方法**：請參閱 [subagent vs agent team](/docs/zh-TW/features-overview#compare-similar-features) 比較以了解並排細分

agent-view.md +87 −87

Details

16 16

17當您想在任何代理的工作階段中更直接地工作時，附加到該行以進入完整對話。17當您想在任何代理的工作階段中更直接地工作時，附加到該行以進入完整對話。

18 18

~~19若要比較 agent view 與 subagents、agent teams 和 worktrees，請參閱 [平行執行代理](/zh-TW/agents)。~~19若要比較 agent view 與 subagents、agent teams 和 worktrees，請參閱 [平行執行代理](/docs/zh-TW/agents)。

20 20

21<Note>21<Note>

22 Agent view 是研究預覽版本，需要 Claude Code v2.1.139 或更新版本。使用 `claude --version` 檢查您的版本。隨著功能的發展，介面和快捷鍵可能會改變。22 Agent view 是研究預覽版本，需要 Claude Code v2.1.139 或更新版本。使用 `claude --version` 檢查您的版本。隨著功能的發展，介面和快捷鍵可能會改變。

70 70

71您可以使用 `claude agents` 作為主要進入點而不是 `claude`：從 agent view 分派每個工作，在需要完整對話時附加，然後按 `←` 返回表格。71您可以使用 `claude agents` 作為主要進入點而不是 `claude`：從 agent view 分派每個工作，在需要完整對話時附加，然後按 `←` 返回表格。

72 72

73{/* min-version: 2.1.205 */}在常規 `claude` 工作階段內，提示頁尾的 `←` 提示會計算正在等待您的背景 agent 數量，例如 `← 2 agents`，當沒有任何 agent 需要輸入時會返回 `← for agents`。超過 99 的計數顯示為 `99+`。當終端獲得焦點時，計數大約每十秒刷新一次，當焦點返回時立即刷新。當計數移動時以及當 agent 完成時，它會短暫改變顏色，除非啟用了 [`prefersReducedMotion` 設定](/zh-TW/settings#available-settings)，並且在[螢幕閱讀器模式](/zh-TW/accessibility)中隱藏。在 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/zh-TW/third-party-integrations) 上，提示保持其純 `← for agents` 形式，不顯示計數。需要 Claude Code v2.1.205 或更新版本。73在常規 `claude` 工作階段內，提示頁尾的 `←` 提示會計算正在等待您的背景 agent 數量，例如 `← 2 agents`，當沒有任何 agent 需要輸入時會返回 `← for agents`。超過 99 的計數顯示為 `99+`。當終端獲得焦點時，計數大約每十秒刷新一次，當焦點返回時立即刷新。當計數移動時以及當 agent 完成時，它會短暫改變顏色，除非啟用了 [`prefersReducedMotion` 設定](/docs/zh-TW/settings#available-settings)，並且在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中隱藏。在 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations) 上，提示保持其純 `← for agents` 形式，不顯示計數。需要 Claude Code v2.1.205 或更新版本。

74 74

75<h2 id="monitor-sessions-with-agent-view">75<h2 id="monitor-sessions-with-agent-view">

76 使用 agent view 監控工作階段76 使用 agent view 監控工作階段

78 78

79執行 `claude agents` 開啟 agent view。它接管整個終端並列出按狀態分組的每個工作階段，固定的工作階段和需要您的工作階段在頂部。每行顯示工作階段的名稱、當前活動和其年齡，從工作階段建立時開始計算；已完成的工作階段的年齡會凍結在執行花費的時間。79執行 `claude agents` 開啟 agent view。它接管整個終端並列出按狀態分組的每個工作階段，固定的工作階段和需要您的工作階段在頂部。每行顯示工作階段的名稱、當前活動和其年齡，從工作階段建立時開始計算；已完成的工作階段的年齡會凍結在執行花費的時間。

80 80

81名稱以該工作階段中由 [`/color`](/zh-TW/commands) 設定的顏色著色。{/* min-version: 2.1.199 */}自 v2.1.199 起，當您使用 `←` 或 `/background` [背景化工作階段](#from-inside-a-session)時，顏色會保留。81名稱以該工作階段中由 [`/color`](/docs/zh-TW/commands) 設定的顏色著色。自 v2.1.199 起，當您使用 `←` 或 `/background` [背景化工作階段](#from-inside-a-session)時，顏色會保留。

82 82

83根據預設，該列表顯示您啟動的每個背景工作階段，跨越所有您的專案。在一個儲存庫中工作的工作階段和在不同 worktree 中工作的另一個工作階段都會出現在這裡，無論您從哪個目錄開啟 agent view。要將檢視範圍限制在一個專案，請傳遞 `--cwd`：83根據預設，該列表顯示您啟動的每個背景工作階段，跨越所有您的專案。在一個儲存庫中工作的工作階段和在不同 worktree 中工作的另一個工作階段都會出現在這裡，無論您從哪個目錄開啟 agent view。要將檢視範圍限制在一個專案，請傳遞 `--cwd`：

84 84

88 88

89這只會顯示在該目錄下啟動的工作階段。已[移入 worktree](#how-file-edits-are-isolated)在 `~/projects/my-app/.claude/worktrees/` 下的工作階段仍然算作屬於 `~/projects/my-app`。89這只會顯示在該目錄下啟動的工作階段。已[移入 worktree](#how-file-edits-are-isolated)在 `~/projects/my-app/.claude/worktrees/` 下的工作階段仍然算作屬於 `~/projects/my-app`。

90 90

91您在其他終端中開啟的互動工作階段在您[背景化它們](#from-inside-a-session)之前不會出現。[Subagents](/zh-TW/sub-agents) 和 [teammates](/zh-TW/agent-teams) 工作階段產生的不會列為單獨的行。91您在其他終端中開啟的互動工作階段在您[背景化它們](#from-inside-a-session)之前不會出現。[Subagents](/docs/zh-TW/sub-agents) 和 [teammates](/docs/zh-TW/agent-teams) 工作階段產生的不會列為單獨的行。

92 92

93```text theme={null}93```text theme={null}

94Pinned94Pinned

131| :---------- | :------------------------------------------------------------- |131| :---------- | :------------------------------------------------------------- |

132| `✻` 或動畫 `✽` | 工作階段程序處於活動狀態並立即回覆 |132| `✻` 或動畫 `✽` | 工作階段程序處於活動狀態並立即回覆 |

133| `∙` | 程序已退出。您仍然可以查看、回覆或附加，Claude 從中斷的地方重新啟動 |133| `∙` | 程序已退出。您仍然可以查看、回覆或附加，Claude 從中斷的地方重新啟動 |

134| `✢` | 一個 [`/loop`](/zh-TW/scheduled-tasks) 工作階段在迭代之間休眠。該行顯示其執行計數和倒計時 |134| `✢` | 一個 [`/loop`](/docs/zh-TW/scheduled-tasks) 工作階段在迭代之間休眠。該行顯示其執行計數和倒計時 |

135 135

136出現在行右邊緣的 `#N` 標籤是[工作階段開啟的拉取請求](#pull-request-status)，不是狀態圖示的一部分。136出現在行右邊緣的 `#N` 標籤是[工作階段開啟的拉取請求](#pull-request-status)，不是狀態圖示的一部分。

137 137

138終端標籤標題在 agent view 開啟時顯示等待輸入計數：當工作階段需要輸入時為 `2 awaiting input · claude agents`，或當沒有工作階段需要輸入時為 `claude agents`。138終端標籤標題在 agent view 開啟時顯示等待輸入計數：當工作階段需要輸入時為 `2 awaiting input · claude agents`，或當沒有工作階段需要輸入時為 `claude agents`。

139 139

140自 v2.1.198 起，當 agent view 開啟時，Claude Code 也會通過您配置的[終端通知頻道](/zh-TW/terminal-config#get-a-terminal-bell-or-notification)發送通知，當本機背景工作階段開始需要您的輸入、完成或失敗時。在排程上執行的工作階段，例如 [`/loop`](/zh-TW/scheduled-tasks) 工作階段，只在需要您的輸入時通知。通知使用與 Claude Code 其餘部分相同的 [`preferredNotifChannel` 設定](/zh-TW/settings#available-settings)，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 [`Notification` hook](/zh-TW/hooks#notification)。140自 v2.1.198 起，當 agent view 開啟時，Claude Code 也會通過您配置的[終端通知頻道](/docs/zh-TW/terminal-config#get-a-terminal-bell-or-notification)發送通知，當本機背景工作階段開始需要您的輸入、完成或失敗時。在排程上執行的工作階段，例如 [`/loop`](/docs/zh-TW/scheduled-tasks) 工作階段，只在需要您的輸入時通知。通知使用與 Claude Code 其餘部分相同的 [`preferredNotifChannel` 設定](/docs/zh-TW/settings#available-settings)，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 [`Notification` hook](/docs/zh-TW/hooks#notification)。

141 141

142背景工作階段不需要任何開啟的終端即可繼續工作。單獨的[監督程序](#the-supervisor-process)執行它們，因此您可以關閉 agent view、關閉 shell 或啟動新的互動工作階段，您分派的工作會繼續進行。142背景工作階段不需要任何開啟的終端即可繼續工作。單獨的[監督程序](#the-supervisor-process)執行它們，因此您可以關閉 agent view、關閉 shell 或啟動新的互動工作階段，您分派的工作會繼續進行。

143 143

149 行摘要149 行摘要

150</h3>150</h3>

151 151

152每行中的單行摘要由 [Haiku-class 模型](/zh-TW/model-config)生成，因此該行可以告訴您工作階段正在做什麼、需要什麼或生成了什麼，無需開啟記錄。當工作階段主動工作時，該行文字最多每 15 秒從工作階段自己的最近輸出更新一次，無需發送模型請求，模型在每個回合結束時寫入新摘要。152每行中的單行摘要由 [Haiku-class 模型](/docs/zh-TW/model-config)生成，因此該行可以告訴您工作階段正在做什麼、需要什麼或生成了什麼，無需開啟記錄。當工作階段主動工作時，該行文字最多每 15 秒從工作階段自己的最近輸出更新一次，無需發送模型請求，模型在每個回合結束時寫入新摘要。

153 153

154工作中的行顯示工作階段說它正在做什麼，被阻止的行顯示它正在詢問的問題。在長回合期間，模型也會大約每分鐘重寫一次摘要，每次重寫後等待時間加倍，最多四分鐘，因此繁忙的行不會持續顯示過時的摘要。摘要文字填充該行的剩餘寬度，只在終端的右邊緣截斷；開啟[查看面板](#peek-and-reply)以讀取邊緣裁剪的句子。在 v2.1.206 之前，文字在 64 列處截斷，無論終端寬度如何。154工作中的行顯示工作階段說它正在做什麼，被阻止的行顯示它正在詢問的問題。在長回合期間，模型也會大約每分鐘重寫一次摘要，每次重寫後等待時間加倍，最多四分鐘，因此繁忙的行不會持續顯示過時的摘要。摘要文字填充該行的剩餘寬度，只在終端的右邊緣截斷；開啟[查看面板](#peek-and-reply)以讀取邊緣裁剪的句子。在 v2.1.206 之前，文字在 64 列處截斷，無論終端寬度如何。

155 155

156當列表[按目錄分組](#organize-the-list)時，摘要以工作階段的狀態作為著色詞開頭，例如 `Needs input · double jump or wall climb?`。在預設狀態分組中，組標題已命名狀態，因此該行只顯示摘要。在 v2.1.205 之前，按目錄分組的行不帶狀態詞。156當列表[按目錄分組](#organize-the-list)時，摘要以工作階段的狀態作為著色詞開頭，例如 `Needs input · double jump or wall climb?`。在預設狀態分組中，組標題已命名狀態，因此該行只顯示摘要。在 v2.1.205 之前，按目錄分組的行不帶狀態詞。

157 157

158整個輸出不包含字母或數字的回合，例如在安靜迭代中列印單個符號的 [`/loop`](/zh-TW/scheduled-tasks) 工作階段，保持該行的先前摘要和狀態。在 v2.1.205 之前，該回合被重新分類，可能會將等待您輸入的工作階段翻轉回 `Working`。158整個輸出不包含字母或數字的回合，例如在安靜迭代中列印單個符號的 [`/loop`](/docs/zh-TW/scheduled-tasks) 工作階段，保持該行的先前摘要和狀態。在 v2.1.205 之前，該回合被重新分類，可能會將等待您輸入的工作階段翻轉回 `Working`。

159 159

160回合結束摘要和每次中途重寫都是通過您的正常提供者的一個簡短 Haiku-class 請求，按照與工作階段本身相同的[資料使用條款](/zh-TW/data-usage)計費和處理。15 秒的模型重寫之間的更新重用工作階段自己的輸出，不發送請求。在第三方提供者（例如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和自訂閘道）上，當未配置 Haiku 模型時，請求會回退到工作階段的主要模型。設定 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-TW/model-config#environment-variables)以在這些提供者上為這些摘要選擇模型。160回合結束摘要和每次中途重寫都是通過您的正常提供者的一個簡短 Haiku-class 請求，按照與工作階段本身相同的[資料使用條款](/docs/zh-TW/data-usage)計費和處理。15 秒的模型重寫之間的更新重用工作階段自己的輸出，不發送請求。在第三方提供者（例如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和自訂閘道）上，當未配置 Haiku 模型時，請求會回退到工作階段的主要模型。設定 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/zh-TW/model-config#environment-variables)以在這些提供者上為這些摘要選擇模型。

161 161

162<h3 id="pull-request-status">162<h3 id="pull-request-status">

163 拉取請求狀態163 拉取請求狀態

202 202

203無法傳遞的回覆，因為背景服務無法連接或發送失敗，會被保存並在其程序再次啟動時作為其下一個提示發送到工作階段，錯誤訊息說回覆已保存。以 `!` 前綴的回覆不會被保存，因為保存的文字會作為純提示而不是 Bash 命令到達工作階段。203無法傳遞的回覆，因為背景服務無法連接或發送失敗，會被保存並在其程序再次啟動時作為其下一個提示發送到工作階段，錯誤訊息說回覆已保存。以 `!` 前綴的回覆不會被保存，因為保存的文字會作為純提示而不是 Bash 命令到達工作階段。

204 204

205啟用[語音聽寫](/zh-TW/voice-dictation)後，在回覆輸入有焦點時按住或點擊您的推送通話鍵以聽寫回覆，而不是輸入。同樣的方式也適用於 agent view 底部的分派輸入。205啟用[語音聽寫](/docs/zh-TW/voice-dictation)後，在回覆輸入有焦點時按住或點擊您的推送通話鍵以聽寫回覆，而不是輸入。同樣的方式也適用於 agent view 底部的分派輸入。

206 206

207使用 `↑` 和 `↓` 查看相鄰工作階段而無需關閉面板，或按 `→` 附加。207使用 `↑` 和 `↓` 查看相鄰工作階段而無需關閉面板，或按 `→` 附加。

208 208

212 212

213在選定的行上按 `Enter` 或 `→` 附加。Agent view 被完整的互動工作階段替換。附加時，Claude 發佈您離開時發生的簡短回顧。213在選定的行上按 `Enter` 或 `→` 附加。Agent view 被完整的互動工作階段替換。附加時，Claude 發佈您離開時發生的簡短回顧。

214 214

215附加時，工作階段的行為與任何其他 Claude Code 工作階段相同：[命令](/zh-TW/commands)、快捷鍵和功能都有效，下面列出的例外除外。215附加時，工作階段的行為與任何其他 Claude Code 工作階段相同：[命令](/docs/zh-TW/commands)、快捷鍵和功能都有效，下面列出的例外除外。

216 216

217背景工作階段拒絕 `/install-github-app` 和 [`/mcp`](/zh-TW/mcp) 設定列表，包括其驗證動作，無論您是附加還是從查看面板回覆。訊息會引導您到常規 `claude` 工作階段，而 `/mcp reconnect <server>`、`/mcp enable` 和 `/mcp disable` 仍然有效。217背景工作階段拒絕 `/install-github-app` 和 [`/mcp`](/docs/zh-TW/mcp) 設定列表，包括其驗證動作，無論您是附加還是從查看面板回覆。訊息會引導您到常規 `claude` 工作階段，而 `/mcp reconnect <server>`、`/mcp enable` 和 `/mcp disable` 仍然有效。

218 218

219附加的工作階段始終以[全螢幕模式](/zh-TW/fullscreen)呈現，無論您的 `tui` 設定如何，因為背景工作階段沒有終端滾動回溯可附加。使用 `PgUp`、`PgDn` 或滑鼠滾輪滾動，並按 `Ctrl+O` 進入記錄模式。您終端的原生滾動和 tmux 複製模式只顯示當前視口，與執行任何全螢幕應用程式時相同。219附加的工作階段始終以[全螢幕模式](/docs/zh-TW/fullscreen)呈現，無論您的 `tui` 設定如何，因為背景工作階段沒有終端滾動回溯可附加。使用 `PgUp`、`PgDn` 或滑鼠滾輪滾動，並按 `Ctrl+O` 進入記錄模式。您終端的原生滾動和 tmux 複製模式只顯示當前視口，與執行任何全螢幕應用程式時相同。

220 220

221在空提示上按 `←` 或執行 `/exit` 以分離並返回 agent view。自 v2.1.198 起，無論您是從 agent view 開啟工作階段還是從 shell 執行 `claude attach <id>`，這都以相同的方式工作。221在空提示上按 `←` 或執行 `/exit` 以分離並返回 agent view。自 v2.1.198 起，無論您是從 agent view 開啟工作階段還是從 shell 執行 `claude attach <id>`，這都以相同的方式工作。

222 222

230 230

231如果工具在您按 `←` 時執行，Claude Code 會等待最多約十秒鐘讓它完成然後背景化，回應在背景工作階段中繼續。再次按 `←` 以立即背景化，而不是等待。當進行中的工作無法轉移到背景工作階段時，`Background this session?` 對話會首先出現，與 [`/background`](#from-inside-a-session) 相同。231如果工具在您按 `←` 時執行，Claude Code 會等待最多約十秒鐘讓它完成然後背景化，回應在背景工作階段中繼續。再次按 `←` 以立即背景化，而不是等待。當進行中的工作無法轉移到背景工作階段時，`Background this session?` 對話會首先出現，與 [`/background`](#from-inside-a-session) 相同。

232 232

233當 [subagents](/zh-TW/sub-agents) 執行時，十秒限制不適用。Claude Code 會繼續等待，以便它們的工作能夠轉移，並在等待時顯示 `Still backgrounding after the current tool` 通知；再次按 `←` 以立即背景化而不等待，這會從頭開始重新啟動 subagents。在 v2.1.203 之前，等待在十秒後結束，執行中的 subagents 會在沒有警告的情況下從頭開始重新啟動。233當 [subagents](/docs/zh-TW/sub-agents) 執行時，十秒限制不適用。Claude Code 會繼續等待，以便它們的工作能夠轉移，並在等待時顯示 `Still backgrounding after the current tool` 通知；再次按 `←` 以立即背景化而不等待，這會從頭開始重新啟動 subagents。在 v2.1.203 之前，等待在十秒後結束，執行中的 subagents 會在沒有警告的情況下從頭開始重新啟動。

234 234

235該行會被建立，即使是從沒有對話歷史的全新工作階段，所以 `→` 會返回到它。{/* max-version: 2.1.202 */}在 v2.1.203 之前，當該行是唯一的行時，agent view 會在其下方顯示一個入門提示。235該行會被建立，即使是從沒有對話歷史的全新工作階段，所以 `→` 會返回到它。在 v2.1.203 之前，當該行是唯一的行時，agent view 會在其下方顯示一個入門提示。

236 236

237您可以在 `/config` 中使用 `leftArrowOpensAgents` 設定關閉此快捷鍵。237您可以在 `/config` 中使用 `leftArrowOpensAgents` 設定關閉此快捷鍵。

238 238

311 311

312在 agent view 底部的輸入框中輸入提示，然後按 `Enter` 啟動新的背景工作階段。工作階段從提示自動命名；稍後可以使用 `Ctrl+R` 重命名它。312在 agent view 底部的輸入框中輸入提示，然後按 `Enter` 啟動新的背景工作階段。工作階段從提示自動命名；稍後可以使用 `Ctrl+R` 重命名它。

313 313

314工作階段稍後獲得的名稱也會出現在其行上，包括當您在該工作階段中[接受計畫](/zh-TW/permission-modes#review-and-approve-a-plan)時 Claude 衍生的名稱。在 v2.1.207 之前，通過接受計畫命名的背景工作階段在 `/status` 中顯示該名稱，但在您自己重命名之前不會在其 agent-view 行上顯示。314工作階段稍後獲得的名稱也會出現在其行上，包括當您在該工作階段中[接受計畫](/docs/zh-TW/permission-modes#review-and-approve-a-plan)時 Claude 衍生的名稱。在 v2.1.207 之前，通過接受計畫命名的背景工作階段在 `/status` 中顯示該名稱，但在您自己重命名之前不會在其 agent-view 行上顯示。

315 315

316將圖像粘貼到提示中以包含螢幕截圖或圖表與任務。316將圖像粘貼到提示中以包含螢幕截圖或圖表與任務。

317 317

318粘貼的文字超過 800 個字符或超過兩行會摺疊為 `[Pasted text #N]` 佔位符，以便輸入保持在一行；完整文字會在您分派時發送。{/* min-version: 2.1.207 */}要在分派前檢查或編輯摺疊的文字，請再次粘貼相同的文字，佔位符會展開回輸入框。在至少 90 列寬的終端上，粘貼後會在輸入下方出現 `paste again to expand` 提醒，持續幾秒鐘。在 v2.1.207 之前，再次粘貼相同的文字會新增第二個佔位符，而不是展開第一個。318粘貼的文字超過 800 個字符或超過兩行會摺疊為 `[Pasted text #N]` 佔位符，以便輸入保持在一行；完整文字會在您分派時發送。要在分派前檢查或編輯摺疊的文字，請再次粘貼相同的文字，佔位符會展開回輸入框。在至少 90 列寬的終端上，粘貼後會在輸入下方出現 `paste again to expand` 提醒，持續幾秒鐘。在 v2.1.207 之前，再次粘貼相同的文字會新增第二個佔位符，而不是展開第一個。

319 319

320前綴或提及提示的部分以控制工作階段如何啟動：320前綴或提及提示的部分以控制工作階段如何啟動：

321 321

322| 輸入 | 效果 |322| 輸入 | 效果 |

323| :---------------------- | :---------------------------------------------------------------------------------------- |323| :---------------------- | :---------------------------------------------------------------------------------------- |

334* `/exit` 和 `/quit` 關閉 agent view334* `/exit` 和 `/quit` 關閉 agent view

335* `/logout` 將您登出335* `/logout` 將您登出

336* `/model` 設定[分派模型](#set-the-model)336* `/model` 設定[分派模型](#set-the-model)

337* {/* min-version: 2.1.198 */}自 v2.1.198 起，`/login` 開啟登入對話框，讓您無需附加到工作階段即可再次登入337* 自 v2.1.198 起，`/login` 開啟登入對話框，讓您無需附加到工作階段即可再次登入

338 338

339Skills、您自己的命令和提示擴展內建命令（例如 `/init`）會作為新背景工作階段的第一個提示發送。其他內建命令會顯示 `attach to a session to run it` 提示。{/* min-version: 2.1.203 */}您輸入的所有內容都會保留在提示旁邊的輸入框中，以便您可以編輯它。在 v2.1.203 之前，提示會清除輸入，輸入的文字會遺失。339Skills、您自己的命令和提示擴展內建命令（例如 `/init`）會作為新背景工作階段的第一個提示發送。其他內建命令會顯示 `attach to a session to run it` 提示。您輸入的所有內容都會保留在提示旁邊的輸入框中，以便您可以編輯它。在 v2.1.203 之前，提示會清除輸入，輸入的文字會遺失。

340 340

341將重複任務打包為 [skill](/zh-TW/skills)可讓您從 agent view 多次啟動相同的工作流程，無需重新輸入提示。341將重複任務打包為 [skill](/docs/zh-TW/skills)可讓您從 agent view 多次啟動相同的工作流程，無需重新輸入提示。

342 342

343當相同的 `@name` 同時與 subagent 和同級儲存庫匹配時，subagent 優先。不帶 `@` 的第一個單詞形式也適用，因此以與您的 subagent 名稱之一匹配的單詞開頭的提示會分派該 subagent 而不是將該單詞視為純文本。當您想要明確時，請使用 `@` 形式，或以不同的單詞開頭提示以避免匹配。343當相同的 `@name` 同時與 subagent 和同級儲存庫匹配時，subagent 優先。不帶 `@` 的第一個單詞形式也適用，因此以與您的 subagent 名稱之一匹配的單詞開頭的提示會分派該 subagent 而不是將該單詞視為純文本。當您想要明確時，請使用 `@` 形式，或以不同的單詞開頭提示以避免匹配。

344 344

352* 在父目錄中開啟 `claude agents`，並在提示中使用 `@<repo>` 提及子儲存庫。輸入 `@` 會列出這些目標：352* 在父目錄中開啟 `claude agents`，並在提示中使用 `@<repo>` 提及子儲存庫。輸入 `@` 會列出這些目標：

353 353

354 * 啟動目錄下一級的 Git 儲存庫354 * 啟動目錄下一級的 Git 儲存庫

355 * 您啟動的儲存庫的已註冊 [git worktrees](/zh-TW/worktrees)，位於其目錄樹內，例如 Claude 在 `.claude/worktrees/` 下建立的那些，標記有其簽出的分支。使用 `git worktree add ../feature` 等方式在儲存庫外新增的 Worktrees 不會被列出355 * 您啟動的儲存庫的已註冊 [git worktrees](/docs/zh-TW/worktrees)，位於其目錄樹內，例如 Claude 在 `.claude/worktrees/` 下建立的那些，標記有其簽出的分支。使用 `git worktree add ../feature` 等方式在儲存庫外新增的 Worktrees 不會被列出

356 * 任何已在列表中有工作階段的目錄356 * 任何已在列表中有工作階段的目錄

357 357

358 名稱包含空格的目錄不會被列出。{/* min-version: 2.1.203 */}在 v2.1.203 之前，已註冊的 worktrees 不會被列出，因此分派到其中意味著從該 worktree 的目錄執行 `claude --bg`。358 名稱包含空格的目錄不會被列出。在 v2.1.203 之前，已註冊的 worktrees 不會被列出，因此分派到其中意味著從該 worktree 的目錄執行 `claude --bg`。

359* 從 shell，`cd` 進入目錄並執行 `claude --bg "<prompt>"`。359* 從 shell，`cd` 進入目錄並執行 `claude --bg "<prompt>"`。

360 360

361當 agent view 按目錄分組時，突出顯示的行的目錄成為分派目標，因此您可以滾動到組並在其中分派，無需重新輸入路徑。361當 agent view 按目錄分組時，突出顯示的行的目錄成為分派目標，因此您可以滾動到組並在其中分派，無需重新輸入路徑。

366 366

367執行 `/background` 或其別名 `/bg` 將當前對話移動到背景工作階段。傳遞提示，例如 `/bg run the test suite and fix any failures`，以在分派前發送一個額外的指令。如果 Claude 在您執行 `/bg` 時正在回應，回應會在背景工作階段中繼續。367執行 `/background` 或其別名 `/bg` 將當前對話移動到背景工作階段。傳遞提示，例如 `/bg run the test suite and fix any failures`，以在分派前發送一個額外的指令。如果 Claude 在您執行 `/bg` 時正在回應，回應會在背景工作階段中繼續。

368 368

369退出仍有背景工作執行的互動工作階段（例如 subagents、背景 shell 命令、工作流程或 [monitors](/zh-TW/tools-reference#monitor-tool)）會顯示 `Background work is running` 對話而不是立即退出。{/* min-version: 2.1.198 */}自 v2.1.198 起，對話框提供 `Move to background and exit` 以及 `Exit anyway` 和 `Stay`。選擇它會以與 `/background` 相同的方式將工作階段移動到背景，然後返回您的 shell，因此可以繼續的工作會保持執行，工作階段會出現在 agent view 中。當 agent view [關閉](#turn-off-agent-view)時，不會顯示此選項。369退出仍有背景工作執行的互動工作階段（例如 subagents、背景 shell 命令、工作流程或 [monitors](/docs/zh-TW/tools-reference#monitor-tool)）會顯示 `Background work is running` 對話而不是立即退出。自 v2.1.198 起，對話框提供 `Move to background and exit` 以及 `Exit anyway` 和 `Stay`。選擇它會以與 `/background` 相同的方式將工作階段移動到背景，然後返回您的 shell，因此可以繼續的工作會保持執行，工作階段會出現在 agent view 中。當 agent view [關閉](#turn-off-agent-view)時，不會顯示此選項。

370 370

371從互動工作階段背景化會啟動一個新的進程，該進程從保存的對話恢復，進行中的工作會轉移到它：執行中的背景 shell 命令、背景化的 subagents、動態工作流程和您使用 [`/loop`](/zh-TW/scheduled-tasks)建立的排定任務會轉移到背景工作階段並在那裡繼續執行。Subagent 與它啟動的所有內容一起移動，因此只有當所有工作都能轉移時它才會轉移，包括在 Windows 上。要停止進行中的工作而不是轉移它，請設定 [`CLAUDE_DISABLE_ADOPT=1`](/zh-TW/env-vars#variables)環境變數；Claude Code 隨後會要求您在背景化前確認。371從互動工作階段背景化會啟動一個新的進程，該進程從保存的對話恢復，進行中的工作會轉移到它：執行中的背景 shell 命令、背景化的 subagents、動態工作流程和您使用 [`/loop`](/docs/zh-TW/scheduled-tasks)建立的排定任務會轉移到背景工作階段並在那裡繼續執行。Subagent 與它啟動的所有內容一起移動，因此只有當所有工作都能轉移時它才會轉移，包括在 Windows 上。要停止進行中的工作而不是轉移它，請設定 [`CLAUDE_DISABLE_ADOPT=1`](/docs/zh-TW/env-vars#variables)環境變數；Claude Code 隨後會要求您在背景化前確認。

372 372

373無法轉移的工作，例如執行中的 [monitor](/zh-TW/tools-reference#monitor-tool)，會被停止。擁有監視器的背景化 subagent 會與它一起被停止。當任何此類工作執行時，Claude Code 會顯示 `Background this session?` 對話，以便您可以在停止前確認。373無法轉移的工作，例如執行中的 [monitor](/docs/zh-TW/tools-reference#monitor-tool)，會被停止。擁有監視器的背景化 subagent 會與它一起被停止。當任何此類工作執行時，Claude Code 會顯示 `Background this session?` 對話，以便您可以在停止前確認。

374 374

375進入背景後，工作階段可以啟動新的 subagents、monitors 和背景命令，這些命令在稍後分離和重新附加時保持執行。375進入背景後，工作階段可以啟動新的 subagents、monitors 和背景命令，這些命令在稍後分離和重新附加時保持執行。

376 376

383* `--fallback-model`383* `--fallback-model`

384* `--allow-dangerously-skip-permissions`384* `--allow-dangerously-skip-permissions`

385 385

386您在工作階段期間使用 [`/add-dir`](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)新增的目錄也會傳遞。386您在工作階段期間使用 [`/add-dir`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)新增的目錄也會傳遞。

387 387

388傳遞 `--allow-dangerously-skip-permissions` 會在背景化工作階段中保持 `bypassPermissions` 可達，但它不會授予任何新的權限。該模式仍然需要在任何工作階段使用它之前進行相同的一次性互動接受，如[Permission mode, model, and effort](#permission-mode-model-and-effort)中所述。388傳遞 `--allow-dangerously-skip-permissions` 會在背景化工作階段中保持 `bypassPermissions` 可達，但它不會授予任何新的權限。該模式仍然需要在任何工作階段使用它之前進行相同的一次性互動接受，如[Permission mode, model, and effort](#permission-mode-model-and-effort)中所述。

389 389

397claude --bg "investigate the flaky SettingsChangeDetector test"397claude --bg "investigate the flaky SettingsChangeDetector test"

398```398```

399 399

400提示是位置引數，不是 `-p` 值。{/* min-version: 2.1.198 */}自 v2.1.198 起，將 `--bg` 與 `-p` 或 `--print` 結合會在建立任何工作階段前被拒絕並出現錯誤，因為 `--print` 永遠不會啟動 `claude agents` 附加到的互動工作階段。400提示是位置引數，不是 `-p` 值。自 v2.1.198 起，將 `--bg` 與 `-p` 或 `--print` 結合會在建立任何工作階段前被拒絕並出現錯誤，因為 `--print` 永遠不會啟動 `claude agents` 附加到的互動工作階段。

401 401

402要執行特定 subagent 作為工作階段的主代理，將 `--bg` 與 `--agent` 結合：402要執行特定 subagent 作為工作階段的主代理，將 `--bg` 與 `--agent` 結合：

403 403

445 檔案編輯如何隔離445 檔案編輯如何隔離

446</h3>446</h3>

447 447

448每個背景工作階段，無論是從 agent view、`/bg` 或 `claude --bg` 啟動，都在您的工作目錄中啟動。編輯檔案前，Claude 將工作階段移動到 `.claude/worktrees/` 下的隔離 [git worktrees](/zh-TW/worktrees)中，因此並行工作階段可以讀取相同的檢出，但每個都寫入自己的。448每個背景工作階段，無論是從 agent view、`/bg` 或 `claude --bg` 啟動，都在您的工作目錄中啟動。編輯檔案前，Claude 將工作階段移動到 `.claude/worktrees/` 下的隔離 [git worktrees](/docs/zh-TW/worktrees)中，因此並行工作階段可以讀取相同的檢出，但每個都寫入自己的。

449 449

450Claude 在以下情況下跳過 worktree：450Claude 在以下情況下跳過 worktree：

451 451

452* 工作階段已在連結的 git worktree 內，無論 Claude 是在 `.claude/worktrees/` 下建立它，還是您使用 `git worktree add` 在其他地方建立它452* 工作階段已在連結的 git worktree 內，無論 Claude 是在 `.claude/worktrees/` 下建立它，還是您使用 `git worktree add` 在其他地方建立它

453* 工作目錄不是 git 儲存庫且沒有配置 [`WorktreeCreate` hook](/zh-TW/hooks#worktreecreate)453* 工作目錄不是 git 儲存庫且沒有配置 [`WorktreeCreate` hook](/docs/zh-TW/hooks#worktreecreate)

454* 寫入在工作目錄外454* 寫入在工作目錄外

455 455

456要為 git worktrees 不實用的儲存庫關閉 worktree 隔離，請將 [`worktree.bgIsolation`](/zh-TW/settings#worktree-settings)設定為 `"none"`。背景工作階段隨後直接編輯您的工作副本，無需先移動到 worktree。將設定新增到專案的 `.claude/settings.json`：456要為 git worktrees 不實用的儲存庫關閉 worktree 隔離，請將 [`worktree.bgIsolation`](/docs/zh-TW/settings#worktree-settings)設定為 `"none"`。背景工作階段隨後直接編輯您的工作副本，無需先移動到 worktree。將設定新增到專案的 `.claude/settings.json`：

457 457

458```json theme={null}458```json theme={null}

459{459{

463}463}

464```464```

465 465

466在 git 儲存庫外，工作階段直接寫入工作目錄，彼此之間不隔離，因此避免分派編輯相同檔案的並行工作階段。如果您使用不同的版本控制系統，請配置 [`WorktreeCreate` hook](/zh-TW/worktrees#non-git-version-control)，Claude 會以與 git 相同的方式隔離編輯。466在 git 儲存庫外，工作階段直接寫入工作目錄，彼此之間不隔離，因此避免分派編輯相同檔案的並行工作階段。如果您使用不同的版本控制系統，請配置 [`WorktreeCreate` hook](/docs/zh-TW/worktrees#non-git-version-control)，Claude 會以與 git 相同的方式隔離編輯。

467 467

468當 hook 在不是 git 儲存庫的目錄中失敗時，工作階段會跳過該目錄的隔離並就地編輯工作目錄。在 git 儲存庫內，寫入會保持被阻止，直到工作階段隔離。在 v2.1.203 之前，處於該狀態的背景工作階段無法編輯任何檔案：每次寫入都被拒絕，直到它隔離，hook 永遠無法隔離該目錄。468當 hook 在不是 git 儲存庫的目錄中失敗時，工作階段會跳過該目錄的隔離並就地編輯工作目錄。在 git 儲存庫內，寫入會保持被阻止，直到工作階段隔離。在 v2.1.203 之前，處於該狀態的背景工作階段無法編輯任何檔案：每次寫入都被拒絕，直到它隔離，hook 永遠無法隔離該目錄。

469 469

476 476

477要找到工作階段的 worktree 路徑，查看工作階段或附加並檢查其工作目錄。477要找到工作階段的 worktree 路徑，查看工作階段或附加並檢查其工作目錄。

478 478

479[subagent](/zh-TW/sub-agents)背景工作階段生成的會繼承工作階段的工作目錄，因此其檔案編輯會進入工作階段的 worktree 而不是您的工作副本。要給 subagent 其自己的單獨 worktree，請在其 frontmatter 中設定 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)或在生成它時傳遞 `isolation: "worktree"`。479[subagent](/docs/zh-TW/sub-agents)背景工作階段生成的會繼承工作階段的工作目錄，因此其檔案編輯會進入工作階段的 worktree 而不是您的工作副本。要給 subagent 其自己的單獨 worktree，請在其 frontmatter 中設定 [`isolation: worktree`](/docs/zh-TW/sub-agents#supported-frontmatter-fields)或在生成它時傳遞 `isolation: "worktree"`。

480 480

481自 v2.1.198 起，在隔離 worktree 中隔離其程式碼更改的背景工作階段也會提交、推送其自己的分支，並開啟草稿拉取請求而無需停止詢問。當拉取請求開啟時，[`#N` 標籤](#pull-request-status)會出現在其行上。它永遠不會推送到 `main` 或 `master`，永遠不會強制推送或合併，並且當您告訴它不要開啟拉取請求或儲存庫沒有遠端時會跳過拉取請求。481自 v2.1.198 起，在隔離 worktree 中隔離其程式碼更改的背景工作階段也會提交、推送其自己的分支，並開啟草稿拉取請求而無需停止詢問。當拉取請求開啟時，[`#N` 標籤](#pull-request-status)會出現在其行上。它永遠不會推送到 `main` 或 `master`，永遠不會強制推送或合併，並且當您告訴它不要開啟拉取請求或儲存庫沒有遠端時會跳過拉取請求。

482 482

486 設定模型486 設定模型

487</h3>487</h3>

488 488

489agent view 標題中顯示的模型名稱是分派預設值。您從輸入啟動的新工作階段使用此模型，這來自您使用者設定中的 [`model` setting](/zh-TW/settings#available-settings)。通過在 [`/model` picker](/zh-TW/model-config)中選擇模型來設定它，或直接編輯設定。489agent view 標題中顯示的模型名稱是分派預設值。您從輸入啟動的新工作階段使用此模型，這來自您使用者設定中的 [`model` setting](/docs/zh-TW/settings#available-settings)。通過在 [`/model` picker](/docs/zh-TW/model-config)中選擇模型來設定它，或直接編輯設定。

490 490

491要為整個 agent view 工作階段覆蓋分派預設值，請在開啟 agent view 時傳遞 `--model`。請參閱[Permission mode, model, and effort](#permission-mode-model-and-effort)。491要為整個 agent view 工作階段覆蓋分派預設值，請在開啟 agent view 時傳遞 `--model`。請參閱[Permission mode, model, and effort](#permission-mode-model-and-effort)。

492 492

503 503

504* 從 shell，使用 `claude --bg` 傳遞 `--model`。504* 從 shell，使用 `claude --bg` 傳遞 `--model`。

505* 附加到執行中的工作階段並執行 `/model` 以切換：從選擇器中選擇，或輸入 `/model <name>`，會保存為您的新工作階段預設值，除非您在選擇器中按 `s` 進行僅工作階段切換。如果工作階段被重新生成，僅工作階段切換會持續。505* 附加到執行中的工作階段並執行 `/model` 以切換：從選擇器中選擇，或輸入 `/model <name>`，會保存為您的新工作階段預設值，除非您在選擇器中按 `s` 進行僅工作階段切換。如果工作階段被重新生成，僅工作階段切換會持續。

506* 分派一個 [subagent](/zh-TW/sub-agents)，其 frontmatter 設定 `model` 欄位。506* 分派一個 [subagent](/docs/zh-TW/sub-agents)，其 frontmatter 設定 `model` 欄位。

507 507

508<h3 id="permission-mode-model-and-effort">508<h3 id="permission-mode-model-and-effort">

509 Permission mode, model, and effort509 Permission mode, model, and effort

510</h3>510</h3>

511 511

512背景工作階段從它執行的目錄讀取其 [settings](/zh-TW/settings)，就像您在那裡啟動了 `claude` 一樣。這包括專案設定中的 [`env` values](/zh-TW/settings#available-settings)，因此在那裡設定的 `ANTHROPIC_MODEL` 或提供者變數適用於該目錄中的背景工作階段。512背景工作階段從它執行的目錄讀取其 [settings](/docs/zh-TW/settings)，就像您在那裡啟動了 `claude` 一樣。這包括專案設定中的 [`env` values](/docs/zh-TW/settings#available-settings)，因此在那裡設定的 `ANTHROPIC_MODEL` 或提供者變數適用於該目錄中的背景工作階段。

513 513

514雲提供者選擇，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及 `ANTHROPIC_DEFAULT_*_MODEL` 別名遵循分派工作階段的 shell。{/* min-version: 2.1.206 */}如果您在該 shell 中匯出 [`CLAUDE_CODE_EXTRA_BODY`](/zh-TW/env-vars)請求體覆蓋，它也會以相同方式到達工作階段。在 v2.1.206 之前，背景工作者忽略了 shell 匯出的 `CLAUDE_CODE_EXTRA_BODY`。514雲提供者選擇，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及 `ANTHROPIC_DEFAULT_*_MODEL` 別名遵循分派工作階段的 shell。如果您在該 shell 中匯出 [`CLAUDE_CODE_EXTRA_BODY`](/docs/zh-TW/env-vars)請求體覆蓋，它也會以相同方式到達工作階段。在 v2.1.206 之前，背景工作者忽略了 shell 匯出的 `CLAUDE_CODE_EXTRA_BODY`。

515 515

516如果您在分派 shell 中匯出閘道 `ANTHROPIC_BASE_URL`，它也會到達工作階段，以及 `ANTHROPIC_CUSTOM_HEADERS`，當監督者使用相同的閘道環境執行且工作階段在您分派的目錄中執行或是您自己的工作階段使用 `←` 或 `/background` 背景化時。這是當第一個開啟 agent view 或分派背景工作階段的 shell 是閘道 shell 時的正常情況。使用 `@repo` 或 `--cwd` 分派到不同目錄不會攜帶 shell 的閘道；該專案的 [settings](/zh-TW/settings)提供端點。請參閱[the supervisor process](#the-supervisor-process)以了解背景工作階段如何源自提供者設定和認證。516如果您在分派 shell 中匯出閘道 `ANTHROPIC_BASE_URL`，它也會到達工作階段，以及 `ANTHROPIC_CUSTOM_HEADERS`，當監督者使用相同的閘道環境執行且工作階段在您分派的目錄中執行或是您自己的工作階段使用 `←` 或 `/background` 背景化時。這是當第一個開啟 agent view 或分派背景工作階段的 shell 是閘道 shell 時的正常情況。使用 `@repo` 或 `--cwd` 分派到不同目錄不會攜帶 shell 的閘道；該專案的 [settings](/docs/zh-TW/settings)提供端點。請參閱[the supervisor process](#the-supervisor-process)以了解背景工作階段如何源自提供者設定和認證。

517 517

518[permission mode](/zh-TW/permissions)取決於您如何啟動工作階段。使用 `/bg` 或 `←` 背景化現有工作階段會保持當前權限模式，因此您切換到 `acceptEdits` 或 `auto` 的工作階段在分離後仍保持該模式。從 agent view 輸入分派或從 shell 執行 `claude --bg` 使用該目錄設定中的 `defaultMode`，或分派的 [subagent 的 frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields)中的 `permissionMode`。518[permission mode](/docs/zh-TW/permissions)取決於您如何啟動工作階段。使用 `/bg` 或 `←` 背景化現有工作階段會保持當前權限模式，因此您切換到 `acceptEdits` 或 `auto` 的工作階段在分離後仍保持該模式。從 agent view 輸入分派或從 shell 執行 `claude --bg` 使用該目錄設定中的 `defaultMode`，或分派的 [subagent 的 frontmatter](/docs/zh-TW/sub-agents#supported-frontmatter-fields)中的 `permissionMode`。

519 519

520背景工作階段啟動時的權限模式、模型和努力，以及它攜帶的 [configuration flags](#from-inside-a-session)，在監督者稍後 [stops and restarts](#the-supervisor-process)其進程時都會持續。您使用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 啟動的工作階段在該重新啟動後保持 `bypassPermissions`，而不是回退到目錄的 `defaultMode`，並且您使用 `/model` 或 `/effort` 在工作階段中途更改的模型或努力會被保留。520背景工作階段啟動時的權限模式、模型和努力，以及它攜帶的 [configuration flags](#from-inside-a-session)，在監督者稍後 [stops and restarts](#the-supervisor-process)其進程時都會持續。您使用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 啟動的工作階段在該重新啟動後保持 `bypassPermissions`，而不是回退到目錄的 `defaultMode`，並且您使用 `/model` 或 `/effort` 在工作階段中途更改的模型或努力會被保留。

521 521

522工作階段從 [`effortLevel` setting](/zh-TW/settings#available-settings)而不是從 `--effort` 或 `/effort` 取得的努力不會在分派時固定：為工作階段啟動的每個進程都會再次讀取設定，因此編輯 `settings.json` 中的 `effortLevel` 會到達您使用 `←` 或 `/bg` 背景化的工作階段及其稍後的重新啟動。在 v2.1.203 之前，背景化工作階段會記錄其設定衍生的努力，就像您傳遞了 `--effort` 一樣，因此稍後的 `effortLevel` 編輯永遠無法到達它。522工作階段從 [`effortLevel` setting](/docs/zh-TW/settings#available-settings)而不是從 `--effort` 或 `/effort` 取得的努力不會在分派時固定：為工作階段啟動的每個進程都會再次讀取設定，因此編輯 `settings.json` 中的 `effortLevel` 會到達您使用 `←` 或 `/bg` 背景化的工作階段及其稍後的重新啟動。在 v2.1.203 之前，背景化工作階段會記錄其設定衍生的努力，就像您傳遞了 `--effort` 一樣，因此稍後的 `effortLevel` 編輯永遠無法到達它。

523 523

524您使用 [`/rename`](/zh-TW/commands) 或 `Ctrl+R` 設定的名稱也會在該重新啟動時持續，因此 [`claude --resume <name>`](/zh-TW/sessions#name-your-sessions) 仍會解析工作階段。在 v2.1.202 之前，重新啟動會將工作階段還原為分派時的名稱，新名稱停止解析。524您使用 [`/rename`](/docs/zh-TW/commands) 或 `Ctrl+R` 設定的名稱也會在該重新啟動時持續，因此 [`claude --resume <name>`](/docs/zh-TW/sessions#name-your-sessions) 仍會解析工作階段。在 v2.1.202 之前，重新啟動會將工作階段還原為分派時的名稱，新名稱停止解析。

525 525

526要為您從 agent view 分派的每個工作階段設定預設值，請在開啟它時傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 中的任何一個：526要為您從 agent view 分派的每個工作階段設定預設值，請在開啟它時傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 中的任何一個：

527 527

529claude agents --permission-mode plan --model opus --effort high529claude agents --permission-mode plan --model opus --effort high

530```530```

531 531

532`--agent` 設定 [subagent](/zh-TW/sub-agents)，當分派提示未使用 `@name` 或作為第一個單詞命名時使用。如果設定了 [`agent` setting](/zh-TW/settings#available-settings)，則預設為該設定，否則為內建的全能 `claude` 代理。在分派輸入中命名 subagent 會覆蓋兩者。532`--agent` 設定 [subagent](/docs/zh-TW/sub-agents)，當分派提示未使用 `@name` 或作為第一個單詞命名時使用。如果設定了 [`agent` setting](/docs/zh-TW/settings#available-settings)，則預設為該設定，否則為內建的全能 `claude` 代理。在分派輸入中命名 subagent 會覆蓋兩者。

533 533

534`claude agents` 也接受 `--dangerously-skip-permissions` 作為 `--permission-mode bypassPermissions` 的簡寫，以及 `--allow-dangerously-skip-permissions` 以在每個分派工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以該模式啟動。兩者都與 [top-level CLI flags](/zh-TW/cli-reference)相符。534`claude agents` 也接受 `--dangerously-skip-permissions` 作為 `--permission-mode bypassPermissions` 的簡寫，以及 `--allow-dangerously-skip-permissions` 以在每個分派工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以該模式啟動。兩者都與 [top-level CLI flags](/docs/zh-TW/cli-reference)相符。

535 535

536活動預設值出現在分派輸入下方的頁腳中。536活動預設值出現在分派輸入下方的頁腳中。

537 537

538沒有這些標誌，工作階段使用該目錄設定中的 `defaultMode` 或分派的 [subagent 的 frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields)中的 `permissionMode`，以及 agent view 標題中顯示的模型。538沒有這些標誌，工作階段使用該目錄設定中的 `defaultMode` 或分派的 [subagent 的 frontmatter](/docs/zh-TW/sub-agents#supported-frontmatter-fields)中的 `permissionMode`，以及 agent view 標題中顯示的模型。

539 539

540使用 `bypassPermissions` 與 `claude --bg --permission-mode` 被拒絕，直到您通過執行 `claude --dangerously-skip-permissions` 一次互動式接受了繞過免責聲明，因為該模式讓您未監視的工作階段無需批准即可行動。將 `--dangerously-skip-permissions` 或 `--permission-mode bypassPermissions` 傳遞給 `claude agents` 會在您之前未接受時顯示相同的免責聲明，接受會將 `bypassPermissions` 應用於您從檢視啟動的工作階段。傳遞 `--allow-dangerously-skip-permissions` 也會顯示相同的免責聲明，接受會在這些工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以它啟動它們。540使用 `bypassPermissions` 與 `claude --bg --permission-mode` 被拒絕，直到您通過執行 `claude --dangerously-skip-permissions` 一次互動式接受了繞過免責聲明，因為該模式讓您未監視的工作階段無需批准即可行動。將 `--dangerously-skip-permissions` 或 `--permission-mode bypassPermissions` 傳遞給 `claude agents` 會在您之前未接受時顯示相同的免責聲明，接受會將 `bypassPermissions` 應用於您從檢視啟動的工作階段。傳遞 `--allow-dangerously-skip-permissions` 也會顯示相同的免責聲明，接受會在這些工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以它啟動它們。

541 541

547 547

548| 標誌 | 效果 |548| 標誌 | 效果 |

549| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------- |549| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------- |

555 555

556每個值重複 `--add-dir`、`--plugin-dir` 或 `--mcp-config` 一次。空格分隔的形式，例如 `--add-dir a b c`，不支援與 `claude agents` 一起使用。556每個值重複 `--add-dir`、`--plugin-dir` 或 `--mcp-config` 一次。空格分隔的形式，例如 `--add-dir a b c`，不支援與 `claude agents` 一起使用。

601 601

602分派 shell 的 `PATH` 以相同方式應用於工作程序，因此工作階段執行的 shell 命令會找到您的終端所擁有的相同工具。在 v2.1.203 之前，背景工作階段保持啟動監督程序的 shell 的 `PATH`，因此自那時以來添加到您 `PATH` 的工具可能會遺失，最常見的是在 Windows 上。602分派 shell 的 `PATH` 以相同方式應用於工作程序，因此工作階段執行的 shell 命令會找到您的終端所擁有的相同工具。在 v2.1.203 之前，背景工作階段保持啟動監督程序的 shell 的 `PATH`，因此自那時以來添加到您 `PATH` 的工具可能會遺失，最常見的是在 Windows 上。

603 603

604背景工作階段不會繼承閘道端點變數（例如 `ANTHROPIC_BASE_URL` 或等效的 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 基礎 URL 變數）來自啟動監督程序的 shell。如果您分派的 shell 中未匯出閘道，工作階段會使用您的儲存認證和專案目錄的[設定](/zh-TW/settings)中 `env` 區塊中的任何 `env` 值。要在專案中指向每個工作階段到 [LLM 閘道](/zh-TW/llm-gateway)，請在該專案的 `.claude/settings.json` `env` 區塊中設定 `ANTHROPIC_BASE_URL`。604背景工作階段不會繼承閘道端點變數（例如 `ANTHROPIC_BASE_URL` 或等效的 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 基礎 URL 變數）來自啟動監督程序的 shell。如果您分派的 shell 中未匯出閘道，工作階段會使用您的儲存認證和專案目錄的[設定](/docs/zh-TW/settings)中 `env` 區塊中的任何 `env` 值。要在專案中指向每個工作階段到 [LLM 閘道](/docs/zh-TW/llm-gateway)，請在該專案的 `.claude/settings.json` `env` 區塊中設定 `ANTHROPIC_BASE_URL`。

605 605

606{/* min-version: 2.1.203 */}在您分派的 shell 中匯出的閘道 `ANTHROPIC_BASE_URL` 會到達該工作階段的工作程序。`ANTHROPIC_CUSTOM_HEADERS` 和與它們一起匯出的認證會與它一起轉發。這發生在監督程序從具有相同閘道的環境啟動時。監督程序從開啟 agent view 或分派背景工作階段的第一個 shell 捕獲其環境，因此從閘道 shell 啟動會給予它該環境。轉發也僅適用於分派到您分派的目錄或使用 `←` 或 `/background` 從您自己的工作階段背景化的工作階段：使用 `@repo` 或 `--cwd` 分派到不同目錄不會攜帶 shell 的閘道，該專案的 `settings.json` `env` 區塊改為提供端點。當監督程序的環境攜帶不同的閘道或沒有閘道時，工作程序會針對預設端點保持您的儲存認證，而不是混合一個環境的認證與另一個環境的端點。在 v2.1.203 之前，分派 shell 的 `ANTHROPIC_BASE_URL` 被丟棄，而與它一起匯出的 `ANTHROPIC_API_KEY` 被保留，因此閘道的金鑰被發送到預設端點，每個請求都失敗並出現 401。606在您分派的 shell 中匯出的閘道 `ANTHROPIC_BASE_URL` 會到達該工作階段的工作程序。`ANTHROPIC_CUSTOM_HEADERS` 和與它們一起匯出的認證會與它一起轉發。這發生在監督程序從具有相同閘道的環境啟動時。監督程序從開啟 agent view 或分派背景工作階段的第一個 shell 捕獲其環境，因此從閘道 shell 啟動會給予它該環境。轉發也僅適用於分派到您分派的目錄或使用 `←` 或 `/background` 從您自己的工作階段背景化的工作階段：使用 `@repo` 或 `--cwd` 分派到不同目錄不會攜帶 shell 的閘道，該專案的 `settings.json` `env` 區塊改為提供端點。當監督程序的環境攜帶不同的閘道或沒有閘道時，工作程序會針對預設端點保持您的儲存認證，而不是混合一個環境的認證與另一個環境的端點。在 v2.1.203 之前，分派 shell 的 `ANTHROPIC_BASE_URL` 被丟棄，而與它一起匯出的 `ANTHROPIC_API_KEY` 被保留，因此閘道的金鑰被發送到預設端點，每個請求都失敗並出現 401。

607 607

608轉發的端點僅適用於該活動程序，永遠不會寫入磁碟。當監督程序停止閒置工作階段並稍後重新啟動它時，重新啟動的程序會再次從您的設定中讀取其端點：使用閘道 `ANTHROPIC_AUTH_TOKEN` 時，它會回退到您的儲存認證，使用閘道發行的 `ANTHROPIC_API_KEY` 時，在設定中設定閘道之前可能無法進行身份驗證。608轉發的端點僅適用於該活動程序，永遠不會寫入磁碟。當監督程序停止閒置工作階段並稍後重新啟動它時，重新啟動的程序會再次從您的設定中讀取其端點：使用閘道 `ANTHROPIC_AUTH_TOKEN` 時，它會回退到您的儲存認證，使用閘道發行的 `ANTHROPIC_API_KEY` 時，在設定中設定閘道之前可能無法進行身份驗證。

609 609

615 615

616* 在此期間完成的背景 shell 命令會報告為已完成及其輸出616* 在此期間完成的背景 shell 命令會報告為已完成及其輸出

617* 動態工作流程會從中斷的地方恢復617* 動態工作流程會從中斷的地方恢復

618* [背景子代理](/zh-TW/sub-agents#run-subagents-in-foreground-or-background)會從其自己的文字記錄恢復618* [背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)會從其自己的文字記錄恢復

619 619

620{/* min-version: 2.1.198 */}自 v2.1.198 起，交付涵蓋所有三項。在 v2.1.198 之前，它只涵蓋 shell 命令和工作流程，因此背景子代理會與程序一起停止，並在下次喚醒時報告為失敗。620自 v2.1.198 起，交付涵蓋所有三項。在 v2.1.198 之前，它只涵蓋 shell 命令和工作流程，因此背景子代理會與程序一起停止，並在下次喚醒時報告為失敗。

621 621

622其狀態僅存在於程序內部的工作會與它一起停止，而不是被交付。那是子代理啟動的 shell 命令，恢復的子代理可以再次啟動，以及執行中的[監視器](/zh-TW/tools-reference#monitor-tool)，其事件流無法移動到另一個程序。622其狀態僅存在於程序內部的工作會與它一起停止，而不是被交付。那是子代理啟動的 shell 命令，恢復的子代理可以再次啟動，以及執行中的[監視器](/docs/zh-TW/tools-reference#monitor-tool)，其事件流無法移動到另一個程序。

623 623

624刪除工作階段會停止它交付的所有內容。要讓所有工作階段的背景工作與程序一起停止而不是被交付，請將 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/zh-TW/env-vars#variables) 環境變數設定為 `1`。624刪除工作階段會停止它交付的所有內容。要讓所有工作階段的背景工作與程序一起停止而不是被交付，請將 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/docs/zh-TW/env-vars#variables) 環境變數設定為 `1`。

625 625

626重新啟動的程序會找到[移入 worktree](#how-file-edits-are-isolated) 中途任務的工作階段的對話：當文字記錄不在工作階段啟動的位置時，Claude Code 也會在儲存庫的已註冊 worktrees 下查看。在 v2.1.207 之前，在其程序停止後從 agent view 重新開啟該工作階段可能會顯示只有其原始提示的空白對話，文字記錄仍完整保存在磁碟上；在 v2.1.207 或更新版本上再次開啟工作階段會恢復它。626重新啟動的程序會找到[移入 worktree](#how-file-edits-are-isolated) 中途任務的工作階段的對話：當文字記錄不在工作階段啟動的位置時，Claude Code 也會在儲存庫的已註冊 worktrees 下查看。在 v2.1.207 之前，在其程序停止後從 agent view 重新開啟該工作階段可能會顯示只有其原始提示的空白對話，文字記錄仍完整保存在磁碟上；在 v2.1.207 或更新版本上再次開啟工作階段會恢復它。

627 627

631 631

632當主機記憶體不足時，監督程序首先停止閒置的未釘選工作階段，只有在釋放任何資源時才停止閒置的釘選工作階段。632當主機記憶體不足時，監督程序首先停止閒置的未釘選工作階段，只有在釋放任何資源時才停止閒置的釘選工作階段。

633 633

634監督程序監視磁碟上已安裝的 Claude Code 二進位檔案，並在常規[自動更新程序](/zh-TW/setup#auto-updates)替換它後重新啟動到新版本。這是本地檔案監視，不是網路檢查。背景工作階段是分離的程序，因此它們在重新啟動期間繼續執行，新監督程序重新連接到它們。閒置的釘選工作階段也會就地重新啟動到新版本，以便它在您不重新附加的情況下獲取更新。634監督程序監視磁碟上已安裝的 Claude Code 二進位檔案，並在常規[自動更新程序](/docs/zh-TW/setup#auto-updates)替換它後重新啟動到新版本。這是本地檔案監視，不是網路檢查。背景工作階段是分離的程序，因此它們在重新啟動期間繼續執行，新監督程序重新連接到它們。閒置的釘選工作階段也會就地重新啟動到新版本，以便它在您不重新附加的情況下獲取更新。

635 635

636一旦新監督程序接管，它也會在短暫延遲後在背景中一次重新啟動幾個剩餘的閒置工作階段到新版本，該延遲讓在重新啟動期間連接的終端有時間先重新連接。正在工作、等待您的輸入或已連接終端的工作階段不會被中斷；它會在其程序下次重新啟動時移動到新版本。在 v2.1.206 之前，監督程序每分鐘只移動幾個閒置工作階段到新版本，因此工作階段在更新後可能會繼續執行舊版本一段時間。636一旦新監督程序接管，它也會在短暫延遲後在背景中一次重新啟動幾個剩餘的閒置工作階段到新版本，該延遲讓在重新啟動期間連接的終端有時間先重新連接。正在工作、等待您的輸入或已連接終端的工作階段不會被中斷；它會在其程序下次重新啟動時移動到新版本。在 v2.1.206 之前，監督程序每分鐘只移動幾個閒置工作階段到新版本，因此工作階段在更新後可能會繼續執行舊版本一段時間。

637 637

643 狀態存儲位置643 狀態存儲位置

644</h3>644</h3>

645 645

646工作階段狀態存儲在您的 Claude Code 配置目錄下。如果您設定 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars)，監督程序改用該目錄而不是 `~/.claude`，並作為具有其自己工作階段的單獨實例執行。646工作階段狀態存儲在您的 Claude Code 配置目錄下。如果您設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)，監督程序改用該目錄而不是 `~/.claude`，並作為具有其自己工作階段的單獨實例執行。

647 647

648| 路徑 | 內容 |648| 路徑 | 內容 |

649| :------------------------------- | :------------------------------- |649| :------------------------------- | :------------------------------- |

658 658

659該命令也會在執行中的監督程序版本與您叫用的 `claude` 版本不同時發出警告，這會在監督程序尚未重新啟動到新版本的更新後發生。警告會顯示兩個版本，並告訴您執行 `claude daemon stop --any` 以採用新版本。當 Claude Code 安裝為作業系統服務時，建議的命令是 `claude daemon stop`，不帶該旗標。659該命令也會在執行中的監督程序版本與您叫用的 `claude` 版本不同時發出警告，這會在監督程序尚未重新啟動到新版本的更新後發生。警告會顯示兩個版本，並告訴您執行 `claude daemon stop --any` 以採用新版本。當 Claude Code 安裝為作業系統服務時，建議的命令是 `claude daemon stop`，不帶該旗標。

660 660

661工作階段在該版本不匹配時保持完整：較舊的 Claude Code 版本更新工作階段的 `state.json` 時會保留它不識別的欄位，並保持工作階段列出。{/* min-version: 2.1.200 */}在 `roster.json` 中的工作階段列表遵循相同規則：較舊的版本在重寫時會保留較新版本寫入的欄位，因此由較新版本啟動的工作階段保持可達，並在監督程序重新啟動後繼續接受輸入。在 v2.1.200 之前，較舊的版本在重寫時可能會丟棄這些欄位。661工作階段在該版本不匹配時保持完整：較舊的 Claude Code 版本更新工作階段的 `state.json` 時會保留它不識別的欄位，並保持工作階段列出。在 `roster.json` 中的工作階段列表遵循相同規則：較舊的版本在重寫時會保留較新版本寫入的欄位，因此由較新版本啟動的工作階段保持可達，並在監督程序重新啟動後繼續接受輸入。在 v2.1.200 之前，較舊的版本在重寫時可能會丟棄這些欄位。

662 662

663在 Windows 上，當 daemon 的 pipe-key 檔案被鎖定或無法讀取時，`claude daemon status` 會顯示基礎檔案錯誤，而不是報告通用連接失敗。663在 Windows 上，當 daemon 的 pipe-key 檔案被鎖定或無法讀取時，`claude daemon status` 會顯示基礎檔案錯誤，而不是報告通用連接失敗。

664 664

666 關閉 agent view666 關閉 agent view

667</h3>667</h3>

668 668

669要完全關閉背景代理和 agent view，將 `disableAgentView` [設定](/zh-TW/settings)設為 `true` 或設定 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 環境變數。管理員可以通過[受管設定](/zh-TW/permissions#managed-settings)強制執行此操作。669要完全關閉背景代理和 agent view，將 `disableAgentView` [設定](/docs/zh-TW/settings)設為 `true` 或設定 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 環境變數。管理員可以通過[受管設定](/docs/zh-TW/permissions#managed-settings)強制執行此操作。

670 670

671<h2 id="troubleshooting">671<h2 id="troubleshooting">

672 故障排除672 故障排除

690 背景化顯示 `Background this session?` 對話690 背景化顯示 `Background this session?` 對話

691</h3>691</h3>

692 692

693如果按 `←` 將當前工作階段放在背景中顯示 `Background this session?` 對話，工作階段有進行中的工作無法轉移到背景工作階段，例如執行中的 [monitor](/zh-TW/tools-reference#monitor-tool)，Claude Code 不會無聲地停止它。對話命名將被停止的工作，並分別計算轉移的任務。執行 `/tasks` 以查看正在執行的內容，然後確認以無論如何背景化或選擇 `Stay` 讓工作先完成。請參閱[從工作階段內部](#from-inside-a-session)以了解哪些任務類型轉移，哪些被停止。693如果按 `←` 將當前工作階段放在背景中顯示 `Background this session?` 對話，工作階段有進行中的工作無法轉移到背景工作階段，例如執行中的 [monitor](/docs/zh-TW/tools-reference#monitor-tool)，Claude Code 不會無聲地停止它。對話命名將被停止的工作，並分別計算轉移的任務。執行 `/tasks` 以查看正在執行的內容，然後確認以無論如何背景化或選擇 `Stay` 讓工作先完成。請參閱[從工作階段內部](#from-inside-a-session)以了解哪些任務類型轉移，哪些被停止。

694 694

695<h3 id="prompt-rejected-as-too-short">695<h3 id="prompt-rejected-as-too-short">

696 提示被拒絕為過短696 提示被拒絕為過短

752 752

753下一個 `claude agents` 或 `claude --bg` 啟動新的監督程序，該程序會讀取您的已儲存認證。如果您使用環境變數（例如 `ANTHROPIC_API_KEY`）而不是 `/login` 進行驗證，請從設定該變數的 shell 執行下一個命令。753下一個 `claude agents` 或 `claude --bg` 啟動新的監督程序，該程序會讀取您的已儲存認證。如果您使用環境變數（例如 `ANTHROPIC_API_KEY`）而不是 `/login` 進行驗證，請從設定該變數的 shell 執行下一個命令。

754 754

755請參閱[錯誤參考](/zh-TW/errors#could-not-resolve-authentication-method)以取得完整的原因和修復清單。755請參閱[錯誤參考](/docs/zh-TW/errors#could-not-resolve-authentication-method)以取得完整的原因和修復清單。

756 756

757<h3 id="background-sessions-can’t-read-desktop-documents-or-downloads-on-macos">757<h3 id="background-sessions-can’t-read-desktop-documents-or-downloads-on-macos">

758 背景工作階段無法在 macOS 上讀取 Desktop、Documents 或 Downloads758 背景工作階段無法在 macOS 上讀取 Desktop、Documents 或 Downloads

766 背景工作階段無法在 macOS 上連接到本機網路主機766 背景工作階段無法在 macOS 上連接到本機網路主機

767</h3>767</h3>

768 768

769在 macOS 15 及更新版本上，系統會阻止程序連接到您本機網路上的裝置，直到您授予本機網路權限。在 v2.1.198 之前，背景工作階段主機從未請求該權限，因此針對 LAN 位址的命令失敗，出現 `connect: no route to host`，即使相同的命令在前景終端中有效。{/* min-version: 2.1.198 */}自 v2.1.198 起，背景工作階段中連接到本機網路位址的第一個命令會觸發 Claude Code 的 macOS 本機網路權限提示。授予一次，這些命令就能像在前景終端中一樣連接到 LAN 主機。769在 macOS 15 及更新版本上，系統會阻止程序連接到您本機網路上的裝置，直到您授予本機網路權限。在 v2.1.198 之前，背景工作階段主機從未請求該權限，因此針對 LAN 位址的命令失敗，出現 `connect: no route to host`，即使相同的命令在前景終端中有效。自 v2.1.198 起，背景工作階段中連接到本機網路位址的第一個命令會觸發 Claude Code 的 macOS 本機網路權限提示。授予一次，這些命令就能像在前景終端中一樣連接到 LAN 主機。

770 770

771<h3 id="a-session-is-slow-to-respond-after-attaching">771<h3 id="a-session-is-slow-to-respond-after-attaching">

772 工作階段在附加後響應緩慢772 工作階段在附加後響應緩慢

780 `.claude/worktrees/` 正在填滿780 `.claude/worktrees/` 正在填滿

781</h3>781</h3>

782 782

783在 agent view 中刪除工作階段會移除 Claude 為其建立的 worktree，而無法安全移除的 worktree 會[保留其工作階段列](#organize-the-list)，以便不會被孤立。`claude rm` 會保留具有未提交變更的 worktree，並列印保留的路徑。在專案目錄中使用 `git worktree list` 列出剩餘條目，並使用 `git worktree remove <path>` 移除每個。請參閱[清理 worktrees](/zh-TW/worktrees#clean-up-worktrees)。783在 agent view 中刪除工作階段會移除 Claude 為其建立的 worktree，而無法安全移除的 worktree 會[保留其工作階段列](#organize-the-list)，以便不會被孤立。`claude rm` 會保留具有未提交變更的 worktree，並列印保留的路徑。在專案目錄中使用 `git worktree list` 列出剩餘條目，並使用 `git worktree remove <path>` 移除每個。請參閱[清理 worktrees](/docs/zh-TW/worktrees#clean-up-worktrees)。

784 784

785<h2 id="limitations">785<h2 id="limitations">

786 限制786 限制

798 798

799如需了解在平行中執行 Claude 的其他方式，請參閱：799如需了解在平行中執行 Claude 的其他方式，請參閱：

800 800

801* [在平行中執行代理](/zh-TW/agents)：比較 agent view 與 subagents、agent teams 和 worktrees801* [在平行中執行代理](/docs/zh-TW/agents)：比較 agent view 與 subagents、agent teams 和 worktrees

802* [Agent teams](/zh-TW/agent-teams)：協調相互傳遞訊息的多個工作階段802* [Agent teams](/docs/zh-TW/agent-teams)：協調相互傳遞訊息的多個工作階段

803* [Claude Code on the web](/zh-TW/claude-code-on-the-web)：在受管雲環境中執行工作階段，而不是本地執行803* [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)：在受管雲環境中執行工作階段，而不是本地執行

804 804

805<h2 id="version-history">805<h2 id="version-history">

806 版本歷史806 版本歷史

809Agent view 在研究預覽期間發展迅速。如果您使用較舊的 Claude Code 版本，本頁上的某些行為可能會有所不同；特別是，`claude agents` 會以 `unknown option` 錯誤拒絕它尚不支援的旗標。下表列出了每個旗標和行為何時新增。809Agent view 在研究預覽期間發展迅速。如果您使用較舊的 Claude Code 版本，本頁上的某些行為可能會有所不同；特別是，`claude agents` 會以 `unknown option` 錯誤拒絕它尚不支援的旗標。下表列出了每個旗標和行為何時新增。

810 810

811| 版本 | 變更 |811| 版本 | 變更 |

812| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |812| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

813| v2.1.208 | {/* min-version: 2.1.208 */}附加到其程序已停止的工作階段會顯示其記錄的最後一屏，同時程序啟動，而不是只顯示 `Session is starting` 備註。無法傳遞的回覆（因為背景服務無法連線或傳送失敗）會被保存，並在其程序再次啟動時作為工作階段的下一個提示傳送；在此版本之前，背景服務無法連線時遺失的回覆會被丟棄。其自身二進位檔被更新取代的程序仍然可以啟動監督程序，從已安裝的 `claude` 啟動器或磁碟上的最新版本，而不是失敗直到 Claude Code 重新啟動。執行較舊版本的監督程序永遠不會將由較新版本啟動的閒置工作階段重新啟動到其自身較舊的二進位檔。刪除工作階段會移除其 worktree，即使工作階段將 worktree 移到不同的分支，並在 worktree 有未推送到任何地方的提交或另一個工作階段聲稱它時將 worktree 與工作階段列保持在一起，而不是銷毀提交或孤立 worktree。`/install-github-app` 和 `/mcp` 設定清單及其驗證動作在背景工作階段中被拒絕，並顯示命名替代方案的訊息；在 v2.1.208 中，`/model` 選擇器以相同方式被拒絕，輸入的 `/model <name>` 只切換該工作階段，而不是也保存您的預設模型。 |813| v2.1.208 | 附加到其程序已停止的工作階段會顯示其記錄的最後一屏，同時程序啟動，而不是只顯示 `Session is starting` 備註。無法傳遞的回覆（因為背景服務無法連線或傳送失敗）會被保存，並在其程序再次啟動時作為工作階段的下一個提示傳送；在此版本之前，背景服務無法連線時遺失的回覆會被丟棄。其自身二進位檔被更新取代的程序仍然可以啟動監督程序，從已安裝的 `claude` 啟動器或磁碟上的最新版本，而不是失敗直到 Claude Code 重新啟動。執行較舊版本的監督程序永遠不會將由較新版本啟動的閒置工作階段重新啟動到其自身較舊的二進位檔。刪除工作階段會移除其 worktree，即使工作階段將 worktree 移到不同的分支，並在 worktree 有未推送到任何地方的提交或另一個工作階段聲稱它時將 worktree 與工作階段列保持在一起，而不是銷毀提交或孤立 worktree。`/install-github-app` 和 `/mcp` 設定清單及其驗證動作在背景工作階段中被拒絕，並顯示命名替代方案的訊息；在 v2.1.208 中，`/model` 選擇器以相同方式被拒絕，輸入的 `/model <name>` 只切換該工作階段，而不是也保存您的預設模型。 |

814| v2.1.207 | {/* min-version: 2.1.207 */}查看面板以列截斷的句子開啟，例如等待您的工作階段的確切問題，並顯示被阻止的工作階段已等待多長時間，作為單一 `waiting 3m` 行，而不是將相同的時間戳記前綴到狀態句子和問題。在分派輸入中再次貼上相同的文字會展開摺疊的 `[Pasted text #N]` 預留位置，而不是新增第二個。按名稱接受計畫的背景工作階段會在其列上顯示該名稱。移入 worktree 的背景工作階段在其程序從 agent view 重新啟動時會保留其對話。 |814| v2.1.207 | 查看面板以列截斷的句子開啟，例如等待您的工作階段的確切問題，並顯示被阻止的工作階段已等待多長時間，作為單一 `waiting 3m` 行，而不是將相同的時間戳記前綴到狀態句子和問題。在分派輸入中再次貼上相同的文字會展開摺疊的 `[Pasted text #N]` 預留位置，而不是新增第二個。按名稱接受計畫的背景工作階段會在其列上顯示該名稱。移入 worktree 的背景工作階段在其程序從 agent view 重新啟動時會保留其對話。 |

815| v2.1.206 | {/* min-version: 2.1.206 */}列摘要填充列的剩餘寬度，並僅在終端的右邊緣截斷，而不是在 64 欄處。監督程序重新啟動到新的 Claude Code 版本後，它會在背景中將剩餘的閒置背景工作階段重新啟動到該版本，而不是每分鐘幾個。使用 `Ctrl+X` 或 `claude rm` 刪除工作階段也會從監督程序的工作階段清單中清除它，因此列在監督程序重新啟動後不再重新出現。 |815| v2.1.206 | 列摘要填充列的剩餘寬度，並僅在終端的右邊緣截斷，而不是在 64 欄處。監督程序重新啟動到新的 Claude Code 版本後，它會在背景中將剩餘的閒置背景工作階段重新啟動到該版本，而不是每分鐘幾個。使用 `Ctrl+X` 或 `claude rm` 刪除工作階段也會從監督程序的工作階段清單中清除它，因此列在監督程序重新啟動後不再重新出現。 |

816| v2.1.205 | {/* min-version: 2.1.205 */}列摘要顯示工作階段自己的單行報告（在 64 欄處截斷），而不是原始工具叫用或 `done/total` 計數；目錄分組列以彩色狀態字開啟。查看面板以完整狀態句子開啟，對於等待您的工作階段，其確切問題顯示在回覆輸入上方。編輯、評論、關閉或使用 `gh` 標記拉取請求為就緒的工作階段會連結到它，不僅是建立或簽出拉取請求的工作階段，推送會連結拉取請求，即使本機分支名稱不符，建立命令的輸出超過內聯限制的拉取請求也會連結。沒有可讀文字的轉向會保留工作階段的先前狀態，而不是將其翻轉回 `Working`。`claude attach` 會等待最多約 60 秒以重新啟動的工作階段，並顯示狀態行說明原因，而不是失敗。 |816| v2.1.205 | 列摘要顯示工作階段自己的單行報告（在 64 欄處截斷），而不是原始工具叫用或 `done/total` 計數；目錄分組列以彩色狀態字開啟。查看面板以完整狀態句子開啟，對於等待您的工作階段，其確切問題顯示在回覆輸入上方。編輯、評論、關閉或使用 `gh` 標記拉取請求為就緒的工作階段會連結到它，不僅是建立或簽出拉取請求的工作階段，推送會連結拉取請求，即使本機分支名稱不符，建立命令的輸出超過內聯限制的拉取請求也會連結。沒有可讀文字的轉向會保留工作階段的先前狀態，而不是將其翻轉回 `Working`。`claude attach` 會等待最多約 60 秒以重新啟動的工作階段，並顯示狀態行說明原因，而不是失敗。 |

817| v2.1.203 | {/* min-version: 2.1.203 */}在分派 shell 中匯出的閘道 `ANTHROPIC_BASE_URL` 會到達從它分派的工作階段進入同一目錄，當監督程序共享該閘道環境時，而不是在保留隨之匯出的 API 金鑰時被丟棄。分派 shell 的 `PATH` 會套用到每個工作階段的工作程序。在子代理執行時按 `←` 會等待它們，而不是在十秒後重新啟動它們。空清單始終顯示區段標題，每個標題下方有描述。在分派輸入中輸入 `@` 也會列出啟動儲存庫的已註冊 git worktrees，這些 worktrees 位於其目錄樹內。從 `effortLevel` 設定繼承的努力會在稍後編輯該設定時跟隨，而不是在分派時固定。開啟其對話已在另一個執行中工作階段中開啟的已停止工作階段會被拒絕並顯示訊息，而不是使列失敗。在 agent view 中不可用的命令會在輸入中保留輸入的文字。在 git 儲存庫外失敗的 `WorktreeCreate` hook 不再阻止工作階段編輯檔案。 |817| v2.1.203 | 在分派 shell 中匯出的閘道 `ANTHROPIC_BASE_URL` 會到達從它分派的工作階段進入同一目錄，當監督程序共享該閘道環境時，而不是在保留隨之匯出的 API 金鑰時被丟棄。分派 shell 的 `PATH` 會套用到每個工作階段的工作程序。在子代理執行時按 `←` 會等待它們，而不是在十秒後重新啟動它們。空清單始終顯示區段標題，每個標題下方有描述。在分派輸入中輸入 `@` 也會列出啟動儲存庫的已註冊 git worktrees，這些 worktrees 位於其目錄樹內。從 `effortLevel` 設定繼承的努力會在稍後編輯該設定時跟隨，而不是在分派時固定。開啟其對話已在另一個執行中工作階段中開啟的已停止工作階段會被拒絕並顯示訊息，而不是使列失敗。在 agent view 中不可用的命令會在輸入中保留輸入的文字。在 git 儲存庫外失敗的 `WorktreeCreate` hook 不再阻止工作階段編輯檔案。 |

818| v2.1.202 | {/* min-version: 2.1.202 */}使用 `/rename` 或 `Ctrl+R` 在背景工作階段上設定的名稱在監督程序停止並重新啟動其程序時會保留，而不是還原為工作階段分派時的名稱。 |818| v2.1.202 | 使用 `/rename` 或 `Ctrl+R` 在背景工作階段上設定的名稱在監督程序停止並重新啟動其程序時會保留，而不是還原為工作階段分派時的名稱。 |

819| v2.1.200 | {/* min-version: 2.1.200 */}較舊的 Claude Code 版本在 `roster.json` 中重寫工作階段清單時會保留較新版本寫入的欄位，符合現有的 `state.json` 保證，因此由較新版本啟動的工作階段在監督程序重新啟動後繼續接受輸入。當您開啟已停止回應的工作階段時，監督程序會重新啟動其程序，工作階段會從中斷的地方繼續中斷的回應。 |819| v2.1.200 | 較舊的 Claude Code 版本在 `roster.json` 中重寫工作階段清單時會保留較新版本寫入的欄位，符合現有的 `state.json` 保證，因此由較新版本啟動的工作階段在監督程序重新啟動後繼續接受輸入。當您開啟已停止回應的工作階段時，監督程序會重新啟動其程序，工作階段會從中斷的地方繼續中斷的回應。 |

820| v2.1.199 | {/* min-version: 2.1.199 */}背景工作階段的程序在低記憶體主機上完成啟動前退出時，其列狀態會顯示 `possibly low memory — free some up and retry`，而不是只顯示裸露的退出原因。使用 `←` 或 `/background` 背景化工作階段會將其 `/color` 帶到新列。 |820| v2.1.199 | 背景工作階段的程序在低記憶體主機上完成啟動前退出時，其列狀態會顯示 `possibly low memory — free some up and retry`，而不是只顯示裸露的退出原因。使用 `←` 或 `/background` 背景化工作階段會將其 `/color` 帶到新列。 |

821| v2.1.198 | {/* min-version: 2.1.198 */}Agent view 在背景工作階段需要輸入、完成或失敗時透過 `preferredNotifChannel` 傳送通知，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 `Notification` hook。`←` 和 `/exit` 在 `claude attach <id>` 內返回 agent view 而不是退出到 shell；`Ctrl+Z` 返回到 shell。隔離其工作在 worktree 中的背景工作階段會提交、推送其自己的隔離分支（絕不是 `main` 或 `master`），並在完成時開啟草稿拉取請求，而不是先詢問。`/login` 在 agent view 中執行並開啟登入對話框。`Background work is running` 退出對話框提供 `Move to background and exit`。退出交付也涵蓋背景子代理，它們在下次喚醒時從其記錄恢復，而不是被報告為失敗。`claude --bg` 與 `-p` 或 `--print` 結合會被拒絕並出現錯誤。 |821| v2.1.198 | Agent view 在背景工作階段需要輸入、完成或失敗時透過 `preferredNotifChannel` 傳送通知，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 `Notification` hook。`←` 和 `/exit` 在 `claude attach <id>` 內返回 agent view 而不是退出到 shell；`Ctrl+Z` 返回到 shell。隔離其工作在 worktree 中的背景工作階段會提交、推送其自己的隔離分支（絕不是 `main` 或 `master`），並在完成時開啟草稿拉取請求，而不是先詢問。`/login` 在 agent view 中執行並開啟登入對話框。`Background work is running` 退出對話框提供 `Move to background and exit`。退出交付也涵蓋背景子代理，它們在下次喚醒時從其記錄恢復，而不是被報告為失敗。`claude --bg` 與 `-p` 或 `--print` 結合會被拒絕並出現錯誤。 |

822| v2.1.196 | {/* min-version: 2.1.196 */}單一 `←` 按下會背景化前景工作階段；較早的版本需要兩次按下，帶有頁尾提示和確認。傳遞給 `claude agents` 的 `--dangerously-skip-permissions` 會顯示繞過免責聲明，而不是被無聲地丟棄。您從未命名的互動工作階段在工作階段清單和 `claude agents --json` 中帶有預設名稱，例如 `my-app-3f`。背景 shell 命令和動態工作流程在工作階段的程序被停止、重新啟動或更新時存活，包括在 Windows 上；設定 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 以關閉交付。在重新啟動時誤讀為空的記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除。 |822| v2.1.196 | 單一 `←` 按下會背景化前景工作階段；較早的版本需要兩次按下，帶有頁尾提示和確認。傳遞給 `claude agents` 的 `--dangerously-skip-permissions` 會顯示繞過免責聲明，而不是被無聲地丟棄。您從未命名的互動工作階段在工作階段清單和 `claude agents --json` 中帶有預設名稱，例如 `my-app-3f`。背景 shell 命令和動態工作流程在工作階段的程序被停止、重新啟動或更新時存活，包括在 Windows 上；設定 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 以關閉交付。在重新啟動時誤讀為空的記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除。 |

823| v2.1.195 | {/* min-version: 2.1.195 */}進行中的工作在您背景化 Windows 上的工作階段時也會轉移；設定 `CLAUDE_DISABLE_ADOPT=1` 以改為停止它。`Completed` 組填充剩餘的垂直空間，標題在短終端上壓縮。較舊的 Claude Code 版本不再丟棄較新工作階段的 `state.json` 欄位或隱藏這些工作階段。附加到已停止的工作階段會立即切換，而不是顯示空白螢幕最多五秒。無法接受連接的監督程序會自行退出並釋放其鎖定。 |823| v2.1.195 | 進行中的工作在您背景化 Windows 上的工作階段時也會轉移；設定 `CLAUDE_DISABLE_ADOPT=1` 以改為停止它。`Completed` 組填充剩餘的垂直空間，標題在短終端上壓縮。較舊的 Claude Code 版本不再丟棄較新工作階段的 `state.json` 欄位或隱藏這些工作階段。附加到已停止的工作階段會立即切換，而不是顯示空白螢幕最多五秒。無法接受連接的監督程序會自行退出並釋放其鎖定。 |

824| v2.1.174 | {/* min-version: 2.1.174 */}背景工作階段不再繼承閘道端點變數，例如來自監督程序啟動 shell 的 `ANTHROPIC_BASE_URL`；監督程序向預先準備的工作程序提供新的認證快照，修復虛假的 `Could not resolve authentication method` 錯誤。 |824| v2.1.174 | 背景工作階段不再繼承閘道端點變數，例如來自監督程序啟動 shell 的 `ANTHROPIC_BASE_URL`；監督程序向預先準備的工作程序提供新的認證快照，修復虛假的 `Could not resolve authentication method` 錯誤。 |

825| v2.1.172 | {/* min-version: 2.1.172 */}分派輸入中的 `/model` 設定工作階段範圍的分派模型覆蓋。 |825| v2.1.172 | 分派輸入中的 `/model` 設定工作階段範圍的分派模型覆蓋。 |

826| v2.1.161 | {/* min-version: 2.1.161 */}列摘要顯示平行工作項目的 `done/total` 計數；查看面板命名最長執行的平行工作項目。 |826| v2.1.161 | 列摘要顯示平行工作項目的 `done/total` 計數；查看面板命名最長執行的平行工作項目。 |

827| v2.1.157 | {/* min-version: 2.1.157 */}`claude agents` 接受 `--agent`；分派的工作階段尊重 `agent` 設定。 |827| v2.1.157 | `claude agents` 接受 `--agent`；分派的工作階段尊重 `agent` 設定。 |

828| v2.1.145 | {/* min-version: 2.1.145 */}查看面板回覆輸入和分派輸入中支援語音聽寫。 |828| v2.1.145 | 查看面板回覆輸入和分派輸入中支援語音聽寫。 |

829| v2.1.143 | {/* min-version: 2.1.143 */}`worktree.bgIsolation` 設定新增；`claude agents` 接受 `--allow-dangerously-skip-permissions`。 |829| v2.1.143 | `worktree.bgIsolation` 設定新增；`claude agents` 接受 `--allow-dangerously-skip-permissions`。 |

830| v2.1.142 | {/* min-version: 2.1.142 */}`claude agents` 接受 `--permission-mode`、`--model`、`--effort`、`--dangerously-skip-permissions`、`--settings`、`--add-dir`、`--plugin-dir`、`--mcp-config` 和 `--strict-mcp-config`。 |830| v2.1.142 | `claude agents` 接受 `--permission-mode`、`--model`、`--effort`、`--dangerously-skip-permissions`、`--settings`、`--add-dir`、`--plugin-dir`、`--mcp-config` 和 `--strict-mcp-config`。 |

831| v2.1.141 | {/* min-version: 2.1.141 */}`claude agents` 接受 `--cwd` 以將清單範圍限定為一個專案。 |831| v2.1.141 | `claude agents` 接受 `--cwd` 以將清單範圍限定為一個專案。 |

832| v2.1.139 | {/* min-version: 2.1.139 */}Agent view 作為研究預覽版本引入。 |832| v2.1.139 | Agent view 作為研究預覽版本引入。 |

agents.md +25 −25

Details

6 6

7> 比較 Claude Code 同時處理多個任務的方式：子代理、代理視圖、代理團隊和動態工作流。7> 比較 Claude Code 同時處理多個任務的方式：子代理、代理視圖、代理團隊和動態工作流。

8 8

9[子代理](/zh-TW/sub-agents)、[代理視圖](/zh-TW/agent-view)、[代理團隊](/zh-TW/agent-teams) 和 [動態工作流](/zh-TW/workflows) 各自以不同的方式並行化工作。正確的選擇取決於您是否想要自己留在每個對話中、交付任務並稍後檢查，或讓 Claude 為您協調一組工作人員。9[子代理](/docs/zh-TW/sub-agents)、[代理視圖](/docs/zh-TW/agent-view)、[代理團隊](/docs/zh-TW/agent-teams) 和 [動態工作流](/docs/zh-TW/workflows) 各自以不同的方式並行化工作。正確的選擇取決於您是否想要自己留在每個對話中、交付任務並稍後檢查，或讓 Claude 為您協調一組工作人員。

10 10

11| 方法 | 它提供什麼 | 何時使用 |11| 方法 | 它提供什麼 | 何時使用 |

12| :------------------------- | :----------------------------------------------- | :----------------------------------------------------------------------- |12| :------------------------- | :----------------------------------------------- | :----------------------------------------------------------------------- |

17 17

~~18在每種方法中，工作人員都是 Claude 會話。要涉及不同的工具，請將其作為 [MCP server](/zh-TW/mcp) 公開給 Claude。~~18在每種方法中，工作人員都是 Claude 會話。要涉及不同的工具，請將其作為 [MCP server](/docs/zh-TW/mcp) 公開給 Claude。

19 19

20還有兩個工具支持這項工作，但它們本身不是運行代理的方式：20還有兩個工具支持這項工作，但它們本身不是運行代理的方式：

21 21

22* [Worktrees](/zh-TW/worktrees) 為每個會話提供單獨的 git 檢出，因此並行會話永遠不會編輯相同的文件。將它們用於您自己運行的會話。代理視圖會自動將每個調度的會話移動到自己的 worktree 中，您生成的子代理也可以各自獲得一個。22* [Worktrees](/docs/zh-TW/worktrees) 為每個會話提供單獨的 git 檢出，因此並行會話永遠不會編輯相同的文件。將它們用於您自己運行的會話。代理視圖會自動將每個調度的會話移動到自己的 worktree 中，您生成的子代理也可以各自獲得一個。

23* [`/batch`](/zh-TW/commands) 是一個 [skill](/zh-TW/skills)，它讓 Claude 將一個大型更改分成 5 到 30 個 worktree 隔離的子代理，每個都打開一個拉取請求。它是子代理和 worktrees 的打包使用，不是一個單獨的協調風格。23* [`/batch`](/docs/zh-TW/commands) 是一個 [skill](/docs/zh-TW/skills)，它讓 Claude 將一個大型更改分成 5 到 30 個 worktree 隔離的子代理，每個都打開一個拉取請求。它是子代理和 worktrees 的打包使用，不是一個單獨的協調風格。

24 24

25還有一些其他功能在沒有您驅動每一步的情況下運行 Claude，但它們解決的問題與在代理之間分割工作不同：25還有一些其他功能在沒有您驅動每一步的情況下運行 Claude，但它們解決的問題與在代理之間分割工作不同：

26 26

~~27* 一個 [background bash command](/zh-TW/interactive-mode#background-bash-commands) 運行一個 shell 命令而不阻止對話。它不會生成一個代理。~~27* 一個 [background bash command](/docs/zh-TW/interactive-mode#background-bash-commands) 運行一個 shell 命令而不阻止對話。它不會生成一個代理。

28* 一個 [forked subagent](/zh-TW/sub-agents#fork-the-current-conversation) 是一個繼承您完整對話上下文而不是從頭開始的子代理。它是一種生成子代理的方式，不是一個單獨的表面。28* 一個 [forked subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation) 是一個繼承您完整對話上下文而不是從頭開始的子代理。它是一種生成子代理的方式，不是一個單獨的表面。

~~29* 一個 [routine](/zh-TW/routines) 在 Anthropic 的雲中按計劃運行一個會話，而不是在您的機器上並行運行。~~29* 一個 [routine](/docs/zh-TW/routines) 在 Anthropic 的雲中按計劃運行一個會話，而不是在您的機器上並行運行。

30 30

31<Note>31<Note>

~~32 同時運行多個會話或子代理會增加令牌使用量。有關使用情況和速率限制詳細信息，請參閱 [Costs](/zh-TW/costs)。~~32 同時運行多個會話或子代理會增加令牌使用量。有關使用情況和速率限制詳細信息，請參閱 [Costs](/docs/zh-TW/costs)。

33</Note>33</Note>

34 34

35<h2 id="choose-an-approach">35<h2 id="choose-an-approach">

39正確的方法取決於誰協調工作、工作人員是否需要通信以及他們是否編輯相同的文件：39正確的方法取決於誰協調工作、工作人員是否需要通信以及他們是否編輯相同的文件：

40 40

41* **誰協調工作？**41* **誰協調工作？**

~~42 * Claude 在一個對話中委派和收集結果：[subagents](/zh-TW/sub-agents)~~42 * Claude 在一個對話中委派和收集結果：[subagents](/docs/zh-TW/sub-agents)

~~43 * 您交付獨立任務並稍後檢查：[agent view](/zh-TW/agent-view)~~43 * 您交付獨立任務並稍後檢查：[agent view](/docs/zh-TW/agent-view)

~~44 * Claude 計劃、分配和監督一組工作人員：[agent teams](/zh-TW/agent-teams)，實驗性且默認禁用~~44 * Claude 計劃、分配和監督一組工作人員：[agent teams](/docs/zh-TW/agent-teams)，實驗性且默認禁用

45 * 一個腳本而不是 Claude 的逐輪判斷來保持協調：[dynamic workflows](/zh-TW/workflows)。請參閱 [workflows 與 subagents 和 skills 的比較方式](/zh-TW/workflows#when-to-use-a-workflow)45 * 一個腳本而不是 Claude 的逐輪判斷來保持協調：[dynamic workflows](/docs/zh-TW/workflows)。請參閱 [workflows 與 subagents 和 skills 的比較方式](/docs/zh-TW/workflows#when-to-use-a-workflow)

46* **工作人員需要相互交談嗎？** Subagents 將結果報告回生成它們的對話，agent view 會話只向您報告。agent team 中的隊友共享任務列表並直接相互發送消息。46* **工作人員需要相互交談嗎？** Subagents 將結果報告回生成它們的對話，agent view 會話只向您報告。agent team 中的隊友共享任務列表並直接相互發送消息。

47* **任務是否涉及相同的文件？** 使用 [worktrees](/zh-TW/worktrees) 隔離工作。Subagents 和您自己運行的會話可以各自使用單獨的 worktree。Agent teams 不會在 worktrees 中隔離隊友，因此 [分區工作](/zh-TW/agent-teams#avoid-file-conflicts)，以便每個隊友擁有不同的文件集。47* **任務是否涉及相同的文件？** 使用 [worktrees](/docs/zh-TW/worktrees) 隔離工作。Subagents 和您自己運行的會話可以各自使用單獨的 worktree。Agent teams 不會在 worktrees 中隔離隊友，因此 [分區工作](/docs/zh-TW/agent-teams#avoid-file-conflicts)，以便每個隊友擁有不同的文件集。

48 48

49<h2 id="check-on-running-work">49<h2 id="check-on-running-work">

50 檢查運行中的工作50 檢查運行中的工作

52 52

53檢查運行中工作的命令取決於您使用的方法：53檢查運行中工作的命令取決於您使用的方法：

54 54

~~55* 對於後台會話，`claude agents` 打開 [代理視圖](/zh-TW/agent-view)：一個屏幕顯示每個會話、其狀態以及哪些需要您的輸入。~~55* 對於後台會話，`claude agents` 打開 [代理視圖](/docs/zh-TW/agent-view)：一個屏幕顯示每個會話、其狀態以及哪些需要您的輸入。

56* 對於當前會話中的子代理，命名的後台子代理出現在 @-mention 類型提前中，並顯示其狀態。{/* min-version: 2.1.198 */}從 v2.1.198 開始，`/agents` 不再打開面板；它打印一個通知，指向子代理文件位置。要 [創建和編輯自定義子代理](/zh-TW/sub-agents#configure-subagents)，請詢問 Claude 或直接編輯文件。儘管名稱相似，但 `/agents` 與 `claude agents` 分開。56* 對於當前會話中的子代理，命名的後台子代理出現在 @-mention 類型提前中，並顯示其狀態。從 v2.1.198 開始，`/agents` 不再打開面板；它打印一個通知，指向子代理文件位置。要 [創建和編輯自定義子代理](/docs/zh-TW/sub-agents#configure-subagents)，請詢問 Claude 或直接編輯文件。儘管名稱相似，但 `/agents` 與 `claude agents` 分開。

57* 對於當前會話後台運行的任何內容，`/tasks` 列出每個項目，並讓您檢查、附加到或停止它。該列表還包括已完成的子代理。57* 對於當前會話後台運行的任何內容，`/tasks` 列出每個項目，並讓您檢查、附加到或停止它。該列表還包括已完成的子代理。

58* 對於動態工作流程，`/workflows` 列出運行和已完成的運行、每個運行所處的階段，以及有多少代理已完成。58* 對於動態工作流程，`/workflows` 列出運行和已完成的運行、每個運行所處的階段，以及有多少代理已完成。

59 59

~~60有關所有會話的桌面視圖，請參閱 [桌面應用中的並行會話](/zh-TW/desktop#work-in-parallel-with-sessions)。~~60有關所有會話的桌面視圖，請參閱 [桌面應用中的並行會話](/docs/zh-TW/desktop#work-in-parallel-with-sessions)。

61 61

62<h2 id="learn-more">62<h2 id="learn-more">

63 了解更多63 了解更多

65 65

66下面的每個指南涵蓋一種方法的設置和配置：66下面的每個指南涵蓋一種方法的設置和配置：

67 67

~~68* [創建自定義子代理](/zh-TW/sub-agents)：定義可重用的專家並控制他們可以使用的工具。~~68* [創建自定義子代理](/docs/zh-TW/sub-agents)：定義可重用的專家並控制他們可以使用的工具。

~~69* [使用代理視圖管理代理](/zh-TW/agent-view)：調度會話、監視其狀態並在需要時附加。~~69* [使用代理視圖管理代理](/docs/zh-TW/agent-view)：調度會話、監視其狀態並在需要時附加。

~~70* [協調代理團隊](/zh-TW/agent-teams)：設置領導者和隊友、分配任務並審查他們的工作。~~70* [協調代理團隊](/docs/zh-TW/agent-teams)：設置領導者和隊友、分配任務並審查他們的工作。

~~71* [協調動態工作流](/zh-TW/workflows)：運行捆綁的工作流或讓 Claude 編寫一個運行許多子代理並驗證其發現相互對比的工作流。~~71* [協調動態工作流](/docs/zh-TW/workflows)：運行捆綁的工作流或讓 Claude 編寫一個運行許多子代理並驗證其發現相互對比的工作流。

~~72* [使用 worktrees 運行並行會話](/zh-TW/worktrees)：在隔離的檢出中啟動 Claude、控制複製的內容並在之後進行清理。~~72* [使用 worktrees 運行並行會話](/docs/zh-TW/worktrees)：在隔離的檢出中啟動 Claude、控制複製的內容並在之後進行清理。

amazon-bedrock.md +28 −28

Details

107 </Step>107 </Step>

108 108

109 <Step title="遵循精靈提示">109 <Step title="遵循精靈提示">

110 選擇您如何向 AWS 進行驗證：從您的 `~/.aws` 目錄偵測到的 AWS 設定檔、Amazon Bedrock API 金鑰、存取金鑰和密碼，或已在您的環境中的認證。精靈會選取您的區域，驗證您的帳戶可以叫用哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的[使用者設定檔](/zh-TW/settings)的 `env` 區塊，因此您不需要自己匯出環境變數。110 選擇您如何向 AWS 進行驗證：從您的 `~/.aws` 目錄偵測到的 AWS 設定檔、Amazon Bedrock API 金鑰、存取金鑰和密碼，或已在您的環境中的認證。精靈會選取您的區域，驗證您的帳戶可以叫用哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的[使用者設定檔](/docs/zh-TW/settings)的 `env` 區塊，因此您不需要自己匯出環境變數。

111 </Step>111 </Step>

112</Steps>112</Steps>

113 113

114登入後，隨時執行 `/setup-bedrock` 以重新開啟精靈並變更您的認證、區域或模型固定。模型固定步驟從您目前固定的模型開始。精靈會寫入 `~/.claude/settings.json`，或在設定 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars#variables) 時寫入 `$CLAUDE_CONFIG_DIR/settings.json`。114登入後，隨時執行 `/setup-bedrock` 以重新開啟精靈並變更您的認證、區域或模型固定。模型固定步驟從您目前固定的模型開始。精靈會寫入 `~/.claude/settings.json`，或在設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars#variables) 時寫入 `$CLAUDE_CONFIG_DIR/settings.json`。

115 115

116<h2 id="set-up-manually">116<h2 id="set-up-manually">

117 手動設定117 手動設定

162export AWS_PROFILE=your-profile-name162export AWS_PROFILE=your-profile-name

163```163```

164 164

165Claude Code 從設定檔的 `sso_region` 命名的 IAM Identity Center 區域要求角色認證，這不需要與您執行 Amazon Bedrock 的區域相符。{/* min-version: 2.1.208 */}在 v2.1.207 中，Amazon Bedrock 區域覆寫了 `sso_region`，因此 IAM Identity Center 執行個體在不同區域的設定檔無法使用 `Session token not found or invalid` 錯誤進行驗證。165Claude Code 從設定檔的 `sso_region` 命名的 IAM Identity Center 區域要求角色認證，這不需要與您執行 Amazon Bedrock 的區域相符。在 v2.1.207 中，Amazon Bedrock 區域覆寫了 `sso_region`，因此 IAM Identity Center 執行個體在不同區域的設定檔無法使用 `Session token not found or invalid` 錯誤進行驗證。

166 166

167**選項 D：AWS 管理主控台認證**167**選項 D：AWS 管理主控台認證**

168 168

186 186

187Claude Code 解析 AWS 預設認證提供者鏈一次，並將已解析的認證保留在記憶體中。它會重複使用它們，直到它們過期前五分鐘，或在沒有過期時間時使用一小時，因此 SSO 支援的設定檔大約每個認證生命週期從 IAM Identity Center 要求一次認證。來自 API 的認證錯誤會清除快取，重試會解析新認證。187Claude Code 解析 AWS 預設認證提供者鏈一次，並將已解析的認證保留在記憶體中。它會重複使用它們，直到它們過期前五分鐘，或在沒有過期時間時使用一小時，因此 SSO 支援的設定檔大約每個認證生命週期從 IAM Identity Center 要求一次認證。來自 API 的認證錯誤會清除快取，重試會解析新認證。

188 188

189{/* min-version: 2.1.207 */}在 v2.1.207 之前，Claude Code 在每個 API 要求時解析鏈，因此 SSO 支援的設定檔每次都從 IAM Identity Center 要求新認證，在大型部署中可能會被節流。189在 v2.1.207 之前，Claude Code 在每個 API 要求時解析鏈，因此 SSO 支援的設定檔每次都從 IAM Identity Center 要求新認證，在大型部署中可能會被節流。

190 190

191快取涵蓋上面的每個認證選項，除了 Amazon Bedrock API 金鑰，它不使用提供者鏈。若要改為在每個要求時解析鏈，請設定 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/zh-TW/env-vars)。191快取涵蓋上面的每個認證選項，除了 Amazon Bedrock API 金鑰，它不使用提供者鏈。若要改為在每個要求時解析鏈，請設定 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-TW/env-vars)。

192 192

193鏈的每次解析在 60 秒後逾時。如果鏈中的步驟停滯，例如等待無法接收的輸入的 `credential_process` 協助程式，要求會失敗，並出現 [`AWS default-chain credential resolve timed out`](/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)。如果您的鏈執行合法需要更長時間的互動式登入，例如透過 `aws-vault` 之類的包裝程式進行瀏覽器型 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/zh-TW/env-vars) 以毫秒為單位提高限制。在 v2.1.207 之前，停滯的認證解析會使要求無限期等待。193鏈的每次解析在 60 秒後逾時。如果鏈中的步驟停滯，例如等待無法接收的輸入的 `credential_process` 協助程式，要求會失敗，並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)。如果您的鏈執行合法需要更長時間的互動式登入，例如透過 `aws-vault` 之類的包裝程式進行瀏覽器型 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制。在 v2.1.207 之前，停滯的認證解析會使要求無限期等待。

194 194

195<h4 id="advanced-credential-configuration">195<h4 id="advanced-credential-configuration">

196 進階認證設定196 進階認證設定

197</h4>197</h4>

198 198

199Claude Code 支援 AWS SSO 和公司身分提供者的自動認證重新整理。將這些設定新增至您的 Claude Code 設定檔（請參閱[設定](/zh-TW/settings)以了解檔案位置）。199Claude Code 支援 AWS SSO 和公司身分提供者的自動認證重新整理。將這些設定新增至您的 Claude Code 設定檔（請參閱[設定](/docs/zh-TW/settings)以了解檔案位置）。

200 200

201這兩個設定有不同的觸發條件：201這兩個設定有不同的觸發條件：

202 202

235}235}

236```236```

237 237

238{/* min-version: 2.1.181 */}自 Claude Code v2.1.181 起，`aws configure export-credentials --format process` 的平面輸出也被接受，具有相同的金鑰在頂層而不是巢狀在 `Credentials` 下。238自 Claude Code v2.1.181 起，`aws configure export-credentials --format process` 的平面輸出也被接受，具有相同的金鑰在頂層而不是巢狀在 `Credentials` 下。

239 239

240`Expiration` 是選用的。{/* min-version: 2.1.176 */}自 Claude Code v2.1.176 起，當命令傳回有效的 ISO 8601 `Expiration` 時，Claude Code 會快取認證直到該時間前五分鐘。沒有它，或在較早版本上，認證會快取一小時。240`Expiration` 是選用的。自 Claude Code v2.1.176 起，當命令傳回有效的 ISO 8601 `Expiration` 時，Claude Code 會快取認證直到該時間前五分鐘。沒有它，或在較早版本上，認證會快取一小時。

241 241

242當您設定 `awsCredentialExport` 而不設定 `awsAuthRefresh` 時，Claude Code 會直接使用匯出的認證，不會在啟動時重新解析 AWS 預設認證提供者鏈。在 v2.1.206 之前，啟動也會重新解析預設提供者鏈，這會在您的代理設定之外進行即時 SSO 或 STS 呼叫，並可能在具有受限出口的網路上阻止第一個提示數分鐘。242當您設定 `awsCredentialExport` 而不設定 `awsAuthRefresh` 時，Claude Code 會直接使用匯出的認證，不會在啟動時重新解析 AWS 預設認證提供者鏈。在 v2.1.206 之前，啟動也會重新解析預設提供者鏈，這會在您的代理設定之外進行即時 SSO 或 STS 呼叫，並可能在具有受限出口的網路上阻止第一個提示數分鐘。

243 243

263 263

264為 Claude Code 啟用 Amazon Bedrock 時，請記住以下事項：264為 Claude Code 啟用 Amazon Bedrock 時，請記住以下事項：

265 265

266* {/* min-version: 2.1.172 */}自 v2.1.172 起，您只需設定 `AWS_REGION` 以覆寫您的 AWS 設定檔的區域，或在您的設定檔沒有區域時設定。Claude Code 按此順序解析區域：266* 自 v2.1.172 起，您只需設定 `AWS_REGION` 以覆寫您的 AWS 設定檔的區域，或在您的設定檔沒有區域時設定。Claude Code 按此順序解析區域：

267 267

268 * `AWS_REGION`268 * `AWS_REGION`

269 * `AWS_DEFAULT_REGION`269 * `AWS_DEFAULT_REGION`

272 272

273 作用中設定檔是 `AWS_PROFILE`（如果已設定），否則為 `default`。設定 `AWS_SHARED_CREDENTIALS_FILE` 或 `AWS_CONFIG_FILE` 以指向非預設檔案路徑。執行 `/status` 以查看已解析的區域。當區域來自您的 AWS 設定檔或預設回退時，`/status` 也會記錄來源。在 v2.1.171 及更早版本上，Claude Code 不會讀取 AWS 設定檔，因此請明確設定 `AWS_REGION`。273 作用中設定檔是 `AWS_PROFILE`（如果已設定），否則為 `default`。設定 `AWS_SHARED_CREDENTIALS_FILE` 或 `AWS_CONFIG_FILE` 以指向非預設檔案路徑。執行 `/status` 以查看已解析的區域。當區域來自您的 AWS 設定檔或預設回退時，`/status` 也會記錄來源。在 v2.1.171 及更早版本上，Claude Code 不會讀取 AWS 設定檔，因此請明確設定 `AWS_REGION`。

274* 使用 Amazon Bedrock 時，`/logout` 命令無法使用，因為驗證是透過 AWS 認證處理的。274* 使用 Amazon Bedrock 時，`/logout` 命令無法使用，因為驗證是透過 AWS 認證處理的。

275* WebSearch 工具在 Amazon Bedrock 上無法使用。請參閱 [WebSearch 工具行為](/zh-TW/tools-reference#websearch-tool-behavior)。275* WebSearch 工具在 Amazon Bedrock 上無法使用。請參閱 [WebSearch 工具行為](/docs/zh-TW/tools-reference#websearch-tool-behavior)。

276* 您可以使用設定檔來設定環境變數，例如 `AWS_PROFILE`，您不想將其洩露給其他程序。請參閱[設定](/zh-TW/settings)以取得更多資訊。276* 您可以使用設定檔來設定環境變數，例如 `AWS_PROFILE`，您不想將其洩露給其他程序。請參閱[設定](/docs/zh-TW/settings)以取得更多資訊。

277 277

278<h3 id="4-pin-model-versions">278<h3 id="4-pin-model-versions">

279 4. 固定模型版本279 4. 固定模型版本

293export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'293export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

294```294```

295 295

296這些變數使用跨區域推論設定檔 ID（帶有 `us.` 前綴）。如果您使用不同的區域前綴或應用程式推論設定檔，請相應調整。在 AWS GovCloud 區域中，使用 `us-gov.` 前綴。如需目前和舊版模型 ID，請參閱[模型概觀](https://platform.claude.com/docs/en/about-claude/models/overview)。請參閱[模型設定](/zh-TW/model-config#pin-models-for-third-party-deployments)以取得完整的環境變數清單。296這些變數使用跨區域推論設定檔 ID（帶有 `us.` 前綴）。如果您使用不同的區域前綴或應用程式推論設定檔，請相應調整。在 AWS GovCloud 區域中，使用 `us-gov.` 前綴。如需目前和舊版模型 ID，請參閱[模型概觀](https://platform.claude.com/docs/en/about-claude/models/overview)。請參閱[模型設定](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)以取得完整的環境變數清單。

297 297

298Claude Code 使用這些預設模型，當未設定固定變數時：298Claude Code 使用這些預設模型，當未設定固定變數時：

299 299

311 Opus 模型的每權杖價格高於 Sonnet 模型，因此未固定主要模型的部署在更新至 v2.1.207 或更新版本後會以 Opus 費率計費。若要將 Sonnet 4.5 保持為主要模型，請將 `ANTHROPIC_MODEL` 設定為其完整模型 ID。使用 `ANTHROPIC_DEFAULT_SONNET_MODEL` 引導預設值且未設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 的部署會保持其引導的 Sonnet 模型作為預設值。311 Opus 模型的每權杖價格高於 Sonnet 模型，因此未固定主要模型的部署在更新至 v2.1.207 或更新版本後會以 Opus 費率計費。若要將 Sonnet 4.5 保持為主要模型，請將 `ANTHROPIC_MODEL` 設定為其完整模型 ID。使用 `ANTHROPIC_DEFAULT_SONNET_MODEL` 引導預設值且未設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 的部署會保持其引導的 Sonnet 模型作為預設值。

312</Warning>312</Warning>

313 313

314{/* min-version: 2.1.207 */}在 v2.1.207 之前，Amazon Bedrock 上的主要模型預設為 Sonnet 4.5，`opus` 別名解析為 Opus 4.6，背景工作始終使用主要模型。314在 v2.1.207 之前，Amazon Bedrock 上的主要模型預設為 Sonnet 4.5，`opus` 別名解析為 Opus 4.6，背景工作始終使用主要模型。

315 315

316若要進一步自訂模型，請使用以下其中一種方法：316若要進一步自訂模型，請使用以下其中一種方法：

317 317

330export ENABLE_PROMPT_CACHING_1H=1330export ENABLE_PROMPT_CACHING_1H=1

331```331```

332 332

3331 小時快取 TTL 的計費費率高於 5 分鐘預設值。請參閱[快取生命週期](/zh-TW/prompt-caching#cache-lifetime)。3331 小時快取 TTL 的計費費率高於 5 分鐘預設值。請參閱[快取生命週期](/docs/zh-TW/prompt-caching#cache-lifetime)。

334 334

335<Note>Prompt caching 可能不適用於所有 Amazon Bedrock 區域。如果快取權杖計數保持為零，請檢查 Amazon Bedrock 文件中的[支援的模型、區域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。</Note>335<Note>Prompt caching 可能不適用於所有 Amazon Bedrock 區域。如果快取權杖計數保持為零，請檢查 Amazon Bedrock 文件中的[支援的模型、區域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。</Note>

336 336

338 將每個模型版本對應至推論設定檔338 將每個模型版本對應至推論設定檔

339</h4>339</h4>

340 340

341`ANTHROPIC_DEFAULT_*_MODEL` 環境變數為每個模型系列設定一個推論設定檔。如果您的組織需要在 `/model` 選擇器中公開同一系列的多個版本，每個版本都路由到其自己的應用程式推論設定檔 ARN，請改用[設定檔](/zh-TW/settings#settings-files)中的 `modelOverrides` 設定。341`ANTHROPIC_DEFAULT_*_MODEL` 環境變數為每個模型系列設定一個推論設定檔。如果您的組織需要在 `/model` 選擇器中公開同一系列的多個版本，每個版本都路由到其自己的應用程式推論設定檔 ARN，請改用[設定檔](/docs/zh-TW/settings#settings-files)中的 `modelOverrides` 設定。

342 342

343此範例將四個 Opus 版本對應至不同的 ARN，以便使用者可以在它們之間切換，而無需繞過您組織的推論設定檔：343此範例將四個 Opus 版本對應至不同的 ARN，以便使用者可以在它們之間切換，而無需繞過您組織的推論設定檔：

344 344

353}353}

354```354```

355 355

356當使用者在 `/model` 中選取其中一個版本時，Claude Code 會使用對應的 ARN 呼叫 Amazon Bedrock。{/* min-version: 2.1.200 */}當您透過 `--model` 或 `ANTHROPIC_MODEL` 直接傳遞 Anthropic 模型 ID 時，相同的對應也適用。沒有覆寫的版本會回退到內建的 Amazon Bedrock 模型 ID 或在啟動時發現的任何相符推論設定檔。在 v2.1.200 之前，`--model` 和 `ANTHROPIC_MODEL` 值會直接到達 Amazon Bedrock，而不會通過覆寫對應。請參閱[覆寫每個版本的模型 ID](/zh-TW/model-config#override-model-ids-per-version)，以了解覆寫如何與 `availableModels` 和其他模型設定互動的詳細資訊。356當使用者在 `/model` 中選取其中一個版本時，Claude Code 會使用對應的 ARN 呼叫 Amazon Bedrock。當您透過 `--model` 或 `ANTHROPIC_MODEL` 直接傳遞 Anthropic 模型 ID 時，相同的對應也適用。沒有覆寫的版本會回退到內建的 Amazon Bedrock 模型 ID 或在啟動時發現的任何相符推論設定檔。在 v2.1.200 之前，`--model` 和 `ANTHROPIC_MODEL` 值會直接到達 Amazon Bedrock，而不會通過覆寫對應。請參閱[覆寫每個版本的模型 ID](/docs/zh-TW/model-config#override-model-ids-per-version)，以了解覆寫如何與 `availableModels` 和其他模型設定互動的詳細資訊。

357 357

358<h2 id="startup-model-checks">358<h2 id="startup-model-checks">

359 啟動模型檢查359 啟動模型檢查

361 361

362當 Claude Code 以 Amazon Bedrock 設定啟動時，它會驗證它打算使用的模型在您的帳戶中是否可存取。362當 Claude Code 以 Amazon Bedrock 設定啟動時，它會驗證它打算使用的模型在您的帳戶中是否可存取。

363 363

364如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的帳戶可以叫用較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的[使用者設定檔](/zh-TW/settings)並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。指向[應用程式推論設定檔 ARN](#map-each-model-version-to-an-inference-profile) 的固定會被跳過，因為這些由您的管理員管理。364如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的帳戶可以叫用較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的[使用者設定檔](/docs/zh-TW/settings)並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。指向[應用程式推論設定檔 ARN](#map-each-model-version-to-an-inference-profile) 的固定會被跳過，因為這些由您的管理員管理。

365 365

366如果您尚未固定模型且目前預設值在您的帳戶中不可用，Claude Code 會在目前工作階段中回退並顯示通知。它會先嘗試預設模型的較早版本，當預設值是 Opus 模型且沒有可用的 Opus 版本時，會回退到預設 Sonnet 模型。回退不會被保留。在您的 Amazon Bedrock 帳戶中啟用較新模型或[固定版本](#4-pin-model-versions)以使選擇永久化。366如果您尚未固定模型且目前預設值在您的帳戶中不可用，Claude Code 會在目前工作階段中回退並顯示通知。它會先嘗試預設模型的較早版本，當預設值是 Opus 模型且沒有可用的 Opus 版本時，會回退到預設 Sonnet 模型。回退不會被保留。在您的 Amazon Bedrock 帳戶中啟用較新模型或[固定版本](#4-pin-model-versions)以使選擇永久化。

367 367

426 426

427Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Amazon Bedrock 上支援 [1M 權杖內容視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)。Sonnet 5 透過 [Mantle 端點](#use-the-mantle-endpoint)提供，且始終以 1M 視窗執行，沒有 `[1m]` 變體可選擇。對於其他模型，當您選取 1M 模型變體時，Claude Code 會自動啟用擴展內容視窗。427Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Amazon Bedrock 上支援 [1M 權杖內容視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)。Sonnet 5 透過 [Mantle 端點](#use-the-mantle-endpoint)提供，且始終以 1M 視窗執行，沒有 `[1m]` 變體可選擇。對於其他模型，當您選取 1M 模型變體時，Claude Code 會自動啟用擴展內容視窗。

428 428

429[設定精靈](#sign-in-with-bedrock)在固定模型時提供 1M 內容選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。請參閱[為第三方部署固定模型](/zh-TW/model-config#pin-models-for-third-party-deployments)以取得詳細資訊。429[設定精靈](#sign-in-with-bedrock)在固定模型時提供 1M 內容選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。請參閱[為第三方部署固定模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)以取得詳細資訊。

430 430

431<h2 id="service-tiers">431<h2 id="service-tiers">

432 服務層級432 服務層級

444 AWS Guardrails444 AWS Guardrails

445</h2>445</h2>

446 446

447[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) 可讓您為 Claude Code 實施內容篩選。在 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)中建立 Guardrail，發佈版本，然後將 Guardrail 標頭新增至您的[設定檔](/zh-TW/settings)。如果您使用跨區域推論設定檔，請在 Guardrail 上啟用跨區域推論。447[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) 可讓您為 Claude Code 實施內容篩選。在 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)中建立 Guardrail，發佈版本，然後將 Guardrail 標頭新增至您的[設定檔](/docs/zh-TW/settings)。如果您使用跨區域推論設定檔，請在 Guardrail 上啟用跨區域推論。

448 448

449範例設定：449範例設定：

450 450

473export AWS_REGION=us-east-1473export AWS_REGION=us-east-1

474```474```

475 475

476Claude Code 從 AWS 區域構造端點 URL。{/* min-version: 2.1.172 */}自 v2.1.172 起，區域的解析優先順序與[上面的 Amazon Bedrock](#3-configure-claude-code) 相同；較早的版本僅使用 `AWS_REGION`。若要為自訂端點或閘道覆寫 URL，請設定 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`。476Claude Code 從 AWS 區域構造端點 URL。自 v2.1.172 起，區域的解析優先順序與[上面的 Amazon Bedrock](#3-configure-claude-code) 相同；較早的版本僅使用 `AWS_REGION`。若要為自訂端點或閘道覆寫 URL，請設定 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`。

477 477

478在 Claude Code 內執行 `/status` 以確認。當 Mantle 處於作用中時，提供者行會顯示 `Amazon Bedrock (Mantle)`。478在 Claude Code 內執行 `/status` 以確認。當 Mantle 處於作用中時，提供者行會顯示 `Amazon Bedrock (Mantle)`。

479 479

500export CLAUDE_CODE_USE_MANTLE=1500export CLAUDE_CODE_USE_MANTLE=1

501```501```

502 502

503若要在 `/model` 選擇器中顯示 Mantle 模型，請在[設定檔](/zh-TW/settings)中的 `availableModels` 中列出其 ID。此設定也會將選擇器限制為列出的項目。列出 `anthropic.claude-haiku-4-5` 會從選擇器中移除裸 `haiku` 別名，因此也請列出版本前綴或您想保持可選的版本的完整 ID。Mantle ID 和 `haiku` 別名會解析為相同的模型系列，因此合併只會保留更具體的項目。請參閱[合併行為](/zh-TW/model-config#merge-behavior)：503若要在 `/model` 選擇器中顯示 Mantle 模型，請在[設定檔](/docs/zh-TW/settings)中的 `availableModels` 中列出其 ID。此設定也會將選擇器限制為列出的項目。列出 `anthropic.claude-haiku-4-5` 會從選擇器中移除裸 `haiku` 別名，因此也請列出版本前綴或您想保持可選的版本的完整 ID。Mantle ID 和 `haiku` 別名會解析為相同的模型系列，因此合併只會保留更具體的項目。請參閱[合併行為](/docs/zh-TW/model-config#merge-behavior)：

504 504

505```json theme={null}505```json theme={null}

506{506{

508}508}

509```509```

510 510

511帶有 `anthropic.` 前綴的項目會新增為自訂選擇器選項並路由到 Mantle。將 `anthropic.claude-haiku-4-5` 替換為您的帳戶已被授予的模型 ID。請參閱[限制模型選擇](/zh-TW/model-config#restrict-model-selection)以了解 `availableModels` 如何與其他模型設定互動。511帶有 `anthropic.` 前綴的項目會新增為自訂選擇器選項並路由到 Mantle。將 `anthropic.claude-haiku-4-5` 替換為您的帳戶已被授予的模型 ID。請參閱[限制模型選擇](/docs/zh-TW/model-config#restrict-model-selection)以了解 `availableModels` 如何與其他模型設定互動。

512 512

513當兩個提供者都處於作用中時，`/status` 會顯示 `Amazon Bedrock + Amazon Bedrock (Mantle)`。513當兩個提供者都處於作用中時，`/status` 會顯示 `Amazon Bedrock + Amazon Bedrock (Mantle)`。

514 514

516 透過閘道路由 Mantle516 透過閘道路由 Mantle

517</h3>517</h3>

518 518

519如果您的組織透過集中式 [LLM 閘道](/zh-TW/llm-gateway)路由模型流量，該閘道在伺服器端注入 AWS 認證，請停用用戶端驗證，以便 Claude Code 傳送沒有 SigV4 簽名或 `x-api-key` 標頭的請求：519如果您的組織透過集中式 [LLM 閘道](/docs/zh-TW/llm-gateway)路由模型流量，該閘道在伺服器端注入 AWS 認證，請停用用戶端驗證，以便 Claude Code 傳送沒有 SigV4 簽名或 `x-api-key` 標頭的請求：

520 520

521```bash theme={null}521```bash theme={null}

522export CLAUDE_CODE_USE_MANTLE=1522export CLAUDE_CODE_USE_MANTLE=1

528 Mantle 環境變數528 Mantle 環境變數

529</h3>529</h3>

530 530

531這些變數特定於 Mantle 端點。請參閱[環境變數](/zh-TW/env-vars)以取得完整清單。531這些變數特定於 Mantle 端點。請參閱[環境變數](/docs/zh-TW/env-vars)以取得完整清單。

532 532

533| 變數 | 目的 |533| 變數 | 目的 |

534| :-------------------------------------- | :---------------------------------------- |534| :-------------------------------------- | :---------------------------------------- |

545 使用 SSO 和公司代理的驗證迴圈545 使用 SSO 和公司代理的驗證迴圈

546</h3>546</h3>

547 547

548如果在使用 AWS SSO 時瀏覽器標籤頻繁開啟，請從您的[設定檔](/zh-TW/settings)中移除 `awsAuthRefresh` 設定。這可能發生在公司 VPN 或 TLS 檢查代理中斷 SSO 瀏覽器流程時。Claude Code 將中斷的連線視為驗證失敗，重新執行 `awsAuthRefresh`，並無限迴圈。548如果在使用 AWS SSO 時瀏覽器標籤頻繁開啟，請從您的[設定檔](/docs/zh-TW/settings)中移除 `awsAuthRefresh` 設定。這可能發生在公司 VPN 或 TLS 檢查代理中斷 SSO 瀏覽器流程時。Claude Code 將中斷的連線視為驗證失敗，重新執行 `awsAuthRefresh`，並無限迴圈。

549 549

550如果您的網路環境干擾自動瀏覽器型 SSO 流程，請在啟動 Claude Code 之前手動使用 `aws sso login`，而不是依賴 `awsAuthRefresh`。550如果您的網路環境干擾自動瀏覽器型 SSO 流程，請在啟動 Claude Code 之前手動使用 `aws sso login`，而不是依賴 `awsAuthRefresh`。

551 551

573 573

574在 v2.1.208 之前，相同的配置錯誤會在整個回應被緩衝後顯示為 `API Error: Truncated event message received`。574在 v2.1.208 之前，相同的配置錯誤會在整個回應被緩衝後顯示為 `API Error: Truncated event message received`。

575 575

576若要修復此問題，請配置閘道以不修改地傳遞 `InvokeModelWithResponseStream` 回應主體及其 `Content-Type` 標頭。如果閘道只重寫標頭並完整傳遞二進位主體，請設定 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/zh-TW/env-vars) 以在修復閘道之前跳過檢查。關閉檢查後，已轉換的回應主體會再次失敗，並顯示 `Truncated event message received`。576若要修復此問題，請配置閘道以不修改地傳遞 `InvokeModelWithResponseStream` 回應主體及其 `Content-Type` 標頭。如果閘道只重寫標頭並完整傳遞二進位主體，請設定 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/docs/zh-TW/env-vars) 以在修復閘道之前跳過檢查。關閉檢查後，已轉換的回應主體會再次失敗，並顯示 `Truncated event message received`。

577 577

578<h3 id="zero-token-counts-in-/context">578<h3 id="zero-token-counts-in-/context">

579 /context 中的零權杖計數579 /context 中的零權杖計數

587 Mantle 端點錯誤587 Mantle 端點錯誤

588</h3>588</h3>

589 589

590如果在設定 `CLAUDE_CODE_USE_MANTLE` 後 `/status` 未顯示 `Amazon Bedrock (Mantle)`，則該變數未到達程序。確認它已在您啟動 `claude` 的 shell 中匯出，或在[設定檔](/zh-TW/settings)的 `env` 區塊中設定它。590如果在設定 `CLAUDE_CODE_USE_MANTLE` 後 `/status` 未顯示 `Amazon Bedrock (Mantle)`，則該變數未到達程序。確認它已在您啟動 `claude` 的 shell 中匯出，或在[設定檔](/docs/zh-TW/settings)的 `env` 區塊中設定它。

591 591

592來自 Mantle 端點的 `403`（具有有效認證）表示您的 AWS 帳戶尚未被授予存取您要求的模型的權限。請聯絡您的 AWS 帳戶團隊以要求存取。592來自 Mantle 端點的 `403`（具有有效認證）表示您的 AWS 帳戶尚未被授予存取您要求的模型的權限。請聯絡您的 AWS 帳戶團隊以要求存取。

593 593

artifacts.md +15 −19

Details

6 6

7> 成品將 Claude Code 的工作轉變為可在 claude.ai 上的即時互動頁面，您可以保持私人、與您的組織分享，或發佈到公開連結。7> 成品將 Claude Code 的工作轉變為可在 claude.ai 上的即時互動頁面，您可以保持私人、與您的組織分享，或發佈到公開連結。

8 8

~~9{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}~~

11<Note>9<Note>

12 成品適用於 Pro、Max、Team 和 Enterprise 方案，並需要使用 [`/login`](/zh-TW/setup#authenticate) 登入的工作階段。請參閱[可用性](#availability)以了解完整的需求集合。10 成品適用於 Pro、Max、Team 和 Enterprise 方案，並需要使用 [`/login`](/docs/zh-TW/setup#authenticate) 登入的工作階段。請參閱[可用性](#availability)以了解完整的需求集合。

13</Note>11</Note>

14 12

15成品是一個即時互動網頁，Claude Code 從您的工作階段發佈到 claude.ai 上的私人 URL。您在瀏覽器中開啟它，當工作階段繼續進行時，它會就地更新。當您想讓其他人看到它時，可以從頁面標題中分享它。例如，使用成品來引導審查者查看帶有註解差異的拉取請求、從工作階段資料建立儀表板，或保持調查時間軸，隨著 Claude 工作而填入。13成品是一個即時互動網頁，Claude Code 從您的工作階段發佈到 claude.ai 上的私人 URL。您在瀏覽器中開啟它，當工作階段繼續進行時，它會就地更新。當您想讓其他人看到它時，可以從頁面標題中分享它。例如，使用成品來引導審查者查看帶有註解差異的拉取請求、從工作階段資料建立儀表板，或保持調查時間軸，隨著 Claude 工作而填入。

22 何時使用成品20 何時使用成品

23</h2>21</h2>

24 22

25當終端文字不是 Claude 產生的內容的正確媒介時，請使用成品：輸出更容易查看和互動，而不是逐行閱讀。Claude 從您的工作階段可以到達的任何內容建立頁面，包括您的程式碼庫和它通過您的[連接工具](/zh-TW/mcp)提取的資料，因此頁面可以顯示需要段落才能描述的內容。例如，要求 Claude：23當終端文字不是 Claude 產生的內容的正確媒介時，請使用成品：輸出更容易查看和互動，而不是逐行閱讀。Claude 從您的工作階段可以到達的任何內容建立頁面，包括您的程式碼庫和它通過您的[連接工具](/docs/zh-TW/mcp)提取的資料，因此頁面可以顯示需要段落才能描述的內容。例如，要求 Claude：

26 24

27* 引導審查者查看帶有註解差異的拉取請求25* 引導審查者查看帶有註解差異的拉取請求

28* 從工作階段已經提取的資料呈現儀表板26* 從工作階段已經提取的資料呈現儀表板

104 使用 MCP 連接器拉取即時資料102 使用 MCP 連接器拉取即時資料

105</h2>103</h2>

106 104

107{/* plan-availability: feature=artifact-mcp plans=pro,max,team,enterprise providers=anthropic */}105每次有人查看 artifact 時，它都可以呼叫 [MCP 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)，因此頁面會顯示目前資料，而不是建立該頁面的工作階段所收集的快照。來自 artifact 的連接器呼叫適用於 Pro、Max、Team 和 Enterprise 方案，並需要 Claude Code v2.1.209 或更新版本。在較早的版本上，Claude 會使用工作階段在建立頁面時收集的任何資料來發佈頁面。

~~108~~

109每次有人查看 artifact 時，它都可以呼叫 [MCP 連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)，因此頁面會顯示目前資料，而不是建立該頁面的工作階段所收集的快照。來自 artifact 的連接器呼叫適用於 Pro、Max、Team 和 Enterprise 方案，並需要 Claude Code v2.1.209 或更新版本。在較早的版本上，Claude 會使用工作階段在建立頁面時收集的任何資料來發佈頁面。

110 106

111若要建立由連接器支援的頁面，請在提示中命名連接器和您想要的資料：107若要建立由連接器支援的頁面，請在提示中命名連接器和您想要的資料：

112 108

202 改進視覺設計198 改進視覺設計

203</h2>199</h2>

204 200

205自 Claude Code v2.1.183 起，Claude 在建立成品時應用內建設計技能，因此頁面無需額外提示即可獲得刻意的調色板、排版和佈局。該技能還會在選擇自己的設計之前在您的專案中尋找現有的設計系統。要保持成品與您產品品牌的一致性，請在 Claude 可以找到的地方記錄您的設計令牌，例如專案的 [CLAUDE.md](/zh-TW/memory) 或您的儲存庫中的主題檔案：201自 Claude Code v2.1.183 起，Claude 在建立成品時應用內建設計技能，因此頁面無需額外提示即可獲得刻意的調色板、排版和佈局。該技能還會在選擇自己的設計之前在您的專案中尋找現有的設計系統。要保持成品與您產品品牌的一致性，請在 Claude 可以找到的地方記錄您的設計令牌，例如專案的 [CLAUDE.md](/docs/zh-TW/memory) 或您的儲存庫中的主題檔案：

206 202

207```markdown theme={null}203```markdown theme={null}

208## Design system204## Design system

243| 要求 | 可用時間 |239| 要求 | 可用時間 |

244| :---- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |240| :---- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

245| 方案 | Pro、Max、Team 或 Enterprise。在 Pro 和 Max 方案上，成品僅供您私人使用，不適用管理員管理。在 Team 方案上，成品預設開啟。在 Enterprise 方案上，Owner 在 claude.ai 管理設定中[啟用它們](#manage-artifacts-for-your-organization)。 |241| 方案 | Pro、Max、Team 或 Enterprise。在 Pro 和 Max 方案上，成品僅供您私人使用，不適用管理員管理。在 Team 方案上，成品預設開啟。在 Enterprise 方案上，Owner 在 claude.ai 管理設定中[啟用它們](#manage-artifacts-for-your-organization)。 |

246| 驗證 | 工作階段由 claude.ai 帳戶支援：在 CLI 或桌面應用程式中使用 `/login` 登入。Claude Tag 工作階段透過代理程式的身分登入，因此不需要任何步驟。使用 API 金鑰、[閘道令牌](/zh-TW/llm-gateway)或雲端提供者認證的工作階段無法發佈。 |242| 驗證 | 工作階段由 claude.ai 帳戶支援：在 CLI 或桌面應用程式中使用 `/login` 登入。Claude Tag 工作階段透過代理程式的身分登入，因此不需要任何步驟。使用 API 金鑰、[閘道令牌](/docs/zh-TW/llm-gateway)或雲端提供者認證的工作階段無法發佈。 |

247| 模型提供者 | Anthropic API。在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上不可用。 |243| 模型提供者 | Anthropic API。在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上不可用。 |

248| 組織政策 | 客戶管理的加密金鑰 (CMEK)、HIPAA 和[零資料保留](/zh-TW/zero-data-retention)未為組織啟用。 |244| 組織政策 | 客戶管理的加密金鑰 (CMEK)、HIPAA 和[零資料保留](/docs/zh-TW/zero-data-retention)未為組織啟用。 |

249| 表面 | Claude Code CLI 版本 2.1.183 或更新版本，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在 Claude Tag 和成品都為組織啟用時也可以發佈成品。在 [Agent SDK](/zh-TW/agent-sdk/overview)、GitHub Action 和 MCP 伺服器上下文中預設關閉，以及當設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/zh-TW/env-vars) 時。 |245| 表面 | Claude Code CLI 版本 2.1.183 或更新版本，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在 Claude Tag 和成品都為組織啟用時也可以發佈成品。在 [Agent SDK](/docs/zh-TW/agent-sdk/overview)、GitHub Action 和 MCP 伺服器上下文中預設關閉，以及當設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 時。 |

250 246

251<h2 id="disable-artifacts">247<h2 id="disable-artifacts">

252 停用成品248 停用成品

256 252

257| 方法 | 設定 |253| 方法 | 設定 |

258| :------------------------- | :---------------------------------- |254| :------------------------- | :---------------------------------- |

262 258

263<h2 id="manage-artifacts-for-your-organization">259<h2 id="manage-artifacts-for-your-organization">

264 為您的組織管理成品260 為您的組織管理成品

300 允許列表檢視器網域296 允許列表檢視器網域

301</h3>297</h3>

302 298

303claude.ai 上的檢視器從沙箱化的 `*.claudeusercontent.com` 來源載入每個成品。如果您的組織限制出站網路存取，請將該網域新增到您的允許列表中，以及 `claude.ai`。請參閱[網路存取要求](/zh-TW/network-config#network-access-requirements)以了解完整清單。299claude.ai 上的檢視器從沙箱化的 `*.claudeusercontent.com` 來源載入每個成品。如果您的組織限制出站網路存取，請將該網域新增到您的允許列表中，以及 `claude.ai`。請參閱[網路存取要求](/docs/zh-TW/network-config#network-access-requirements)以了解完整清單。

304 300

305<h3 id="list-and-delete-artifacts-with-the-compliance-api">301<h3 id="list-and-delete-artifacts-with-the-compliance-api">

306 使用 Compliance API 列出和刪除成品302 使用 Compliance API 列出和刪除成品

320 相關資源316 相關資源

321</h2>317</h2>

322 318

323* 瀏覽與成品配對的[提示模式和工作流程](/zh-TW/prompt-library)319* 瀏覽與成品配對的[提示模式和工作流程](/docs/zh-TW/prompt-library)

324* 將您重複使用的成品提示轉變為[技能](/zh-TW/skills)，以便您可以將其作為命令呼叫320* 將您重複使用的成品提示轉變為[技能](/docs/zh-TW/skills)，以便您可以將其作為命令呼叫

325* [連接 MCP 伺服器](/zh-TW/mcp)，以便 Claude 可以將資料提取到成品中，同時建置頁面321* [連接 MCP 伺服器](/docs/zh-TW/mcp)，以便 Claude 可以將資料提取到成品中，同時建置頁面

authentication.md +28 −28

Details

12 登入 Claude Code12 登入 Claude Code

13</h2>13</h2>

14 14

~~15[安裝 Claude Code](/zh-TW/setup#install-claude-code) 後，在您的終端機中執行 `claude`。首次啟動時，Claude Code 會為您開啟瀏覽器視窗以供登入。~~15[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code) 後，在您的終端機中執行 `claude`。首次啟動時，Claude Code 會為您開啟瀏覽器視窗以供登入。

16 16

17如果瀏覽器未自動開啟，請按 `c` 將登入 URL 複製到您的剪貼簿，然後將其貼到您的瀏覽器中。17如果瀏覽器未自動開啟，請按 `c` 將登入 URL 複製到您的剪貼簿，然後將其貼到您的瀏覽器中。

18 18

25* **Claude Pro 或 Max 訂閱**：使用您的 Claude.ai 帳戶登入。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 訂閱。25* **Claude Pro 或 Max 訂閱**：使用您的 Claude.ai 帳戶登入。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 訂閱。

26* **Claude for Teams 或 Enterprise**：使用您的團隊管理員邀請您的 Claude.ai 帳戶登入。26* **Claude for Teams 或 Enterprise**：使用您的團隊管理員邀請您的 Claude.ai 帳戶登入。

27* **Claude Console**：使用您的 Console 認證登入。您的管理員必須先 [邀請您](#claude-console-authentication)。27* **Claude Console**：使用您的 Console 認證登入。您的管理員必須先 [邀請您](#claude-console-authentication)。

28* **雲端提供商**：如果您的組織使用 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry)，請在執行 `claude` 之前設定所需的環境變數，或在登入提示符處選擇 **3rd-party platform**，這會為 Bedrock 和 Vertex AI 啟動互動式設定精靈。不需要瀏覽器登入。28* **雲端提供商**：如果您的組織使用 [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` 之前設定所需的環境變數，或在登入提示符處選擇 **3rd-party platform**，這會為 Bedrock 和 Vertex AI 啟動互動式設定精靈。不需要瀏覽器登入。

29* **雲端閘道**：如果您的組織執行自託管的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)，請透過 `/login` 使用公司 SSO 登入。閘道簽發的權杖是工作階段的唯一認證。29* **雲端閘道**：如果您的組織執行自託管的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)，請透過 `/login` 使用公司 SSO 登入。閘道簽發的權杖是工作階段的唯一認證。

30 30

31管理員可以使用 [`forceLoginMethod` 和 `forceLoginOrgUUID`](/zh-TW/settings#available-settings) 受管設定來限制互動式登入。當設定其中任一項時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時會被封鎖；雲端提供商工作階段不受影響。31管理員可以使用 [`forceLoginMethod` 和 `forceLoginOrgUUID`](/docs/zh-TW/settings#available-settings) 受管設定來限制互動式登入。當設定其中任一項時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時會被封鎖；雲端提供商工作階段不受影響。

32 32

33若要登出並重新驗證，請在 Claude Code 提示符處輸入 `/logout`。登出也會重設您的首次啟動設定狀態，因此下次您執行 `claude` 時，它會再次引導您完成登入和設定。33若要登出並重新驗證，請在 Claude Code 提示符處輸入 `/logout`。登出也會重設您的首次啟動設定狀態，因此下次您執行 `claude` 時，它會再次引導您完成登入和設定。

34 34

~~35如果您在登入時遇到問題，請參閱 [驗證疑難排解](/zh-TW/troubleshoot-install#login-and-authentication)。~~35如果您在登入時遇到問題，請參閱 [驗證疑難排解](/docs/zh-TW/troubleshoot-install#login-and-authentication)。

36 36

37<h2 id="set-up-team-authentication">37<h2 id="set-up-team-authentication">

38 設定團隊驗證38 設定團隊驗證

42 42

43* [Claude for Teams 或 Enterprise](#claude-for-teams-or-enterprise)，建議用於大多數團隊43* [Claude for Teams 或 Enterprise](#claude-for-teams-or-enterprise)，建議用於大多數團隊

44* [Claude Console](#claude-console-authentication)44* [Claude Console](#claude-console-authentication)

~~45* [Claude apps gateway](/zh-TW/claude-apps-gateway)，一個自託管閘道，使用您的 IdP 簽署開發人員，並將推論路由到您配置的雲端提供商~~45* [Claude apps gateway](/docs/zh-TW/claude-apps-gateway)，一個自託管閘道，使用您的 IdP 簽署開發人員，並將推論路由到您配置的雲端提供商

~~46* [Amazon Bedrock](/zh-TW/amazon-bedrock)~~46* [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)

~~47* [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)~~47* [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)

~~48* [Microsoft Foundry](/zh-TW/microsoft-foundry)~~48* [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)

49 49

50<h3 id="claude-for-teams-or-enterprise">50<h3 id="claude-for-teams-or-enterprise">

51 Claude for Teams 或 Enterprise51 Claude for Teams 或 Enterprise

99 每個受邀使用者需要：99 每個受邀使用者需要：

100 100

101 * 接受 Console 邀請101 * 接受 Console 邀請

102 * [檢查系統要求](/zh-TW/setup#system-requirements)102 * [檢查系統要求](/docs/zh-TW/setup#system-requirements)

103 * [安裝 Claude Code](/zh-TW/setup#install-claude-code)103 * [安裝 Claude Code](/docs/zh-TW/setup#install-claude-code)

104 * 使用 Console 帳戶認證登入104 * 使用 Console 帳戶認證登入

105 </Step>105 </Step>

106</Steps>106</Steps>

113 113

114<Steps>114<Steps>

115 <Step title="遵循提供商設定">115 <Step title="遵循提供商設定">

116 遵循 [Amazon Bedrock 文件](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform 文件](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry 文件](/zh-TW/microsoft-foundry)。116 遵循 [Amazon Bedrock 文件](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform 文件](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry 文件](/docs/zh-TW/microsoft-foundry)。

117 </Step>117 </Step>

118 118

119 <Step title="分發配置">119 <Step title="分發配置">

120 將環境變數和產生雲端認證的說明分發給您的使用者。深入瞭解如何 [在此管理配置](/zh-TW/settings)。120 將環境變數和產生雲端認證的說明分發給您的使用者。深入瞭解如何 [在此管理配置](/docs/zh-TW/settings)。

121 </Step>121 </Step>

122 122

123 <Step title="安裝 Claude Code">123 <Step title="安裝 Claude Code">

124 使用者可以 [安裝 Claude Code](/zh-TW/setup#install-claude-code)。124 使用者可以 [安裝 Claude Code](/docs/zh-TW/setup#install-claude-code)。

125 </Step>125 </Step>

126</Steps>126</Steps>

127 127

136 * 在 Linux 上，認證儲存在 `~/.claude/.credentials.json` 中，檔案模式為 `0600`。136 * 在 Linux 上，認證儲存在 `~/.claude/.credentials.json` 中，檔案模式為 `0600`。

137 * 在 Windows 上，認證儲存在 `%USERPROFILE%\.claude\.credentials.json` 中，並繼承您的使用者設定檔目錄的存取控制，預設情況下將檔案限制為您的使用者帳戶。137 * 在 Windows 上，認證儲存在 `%USERPROFILE%\.claude\.credentials.json` 中，並繼承您的使用者設定檔目錄的存取控制，預設情況下將檔案限制為您的使用者帳戶。

138 * 如果您在 Linux 或 Windows 上設定了 `CLAUDE_CONFIG_DIR` 環境變數，`.credentials.json` 檔案將位於該目錄下。138 * 如果您在 Linux 或 Windows 上設定了 `CLAUDE_CONFIG_DIR` 環境變數，`.credentials.json` 檔案將位於該目錄下。

139 * Claude Code 透過 `/login` 和 `/logout` 管理 `.credentials.json`。若要透過自訂 API 端點路由請求，請改為設定 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 環境變數。139 * Claude Code 透過 `/login` 和 `/logout` 管理 `.credentials.json`。若要透過自訂 API 端點路由請求，請改為設定 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 環境變數。

140* **支援的驗證類型**：Claude.ai 認證、Claude API 認證、Microsoft Foundry Auth、Bedrock Auth、Vertex Auth 和 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段令牌。140* **支援的驗證類型**：Claude.ai 認證、Claude API 認證、Microsoft Foundry Auth、Bedrock Auth、Vertex Auth 和 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段令牌。

141* **自訂認證指令碼**：[`apiKeyHelper`](/zh-TW/settings#available-settings) 設定可以配置為執行傳回 API 金鑰的 shell 指令碼。141* **自訂認證指令碼**：[`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 設定可以配置為執行傳回 API 金鑰的 shell 指令碼。

142* **重新整理間隔**：根據預設，`apiKeyHelper` 在 5 分鐘後或在 HTTP 401 回應時呼叫。設定 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 環境變數以自訂重新整理間隔。142* **重新整理間隔**：根據預設，`apiKeyHelper` 在 5 分鐘後或在 HTTP 401 回應時呼叫。設定 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 環境變數以自訂重新整理間隔。

143* **緩慢協助程式通知**：如果 `apiKeyHelper` 花費超過 10 秒的時間傳回金鑰，Claude Code 會在提示符列中顯示警告通知，顯示經過的時間。如果您經常看到此通知，請檢查您的認證指令碼是否可以最佳化。143* **緩慢協助程式通知**：如果 `apiKeyHelper` 花費超過 10 秒的時間傳回金鑰，Claude Code 會在提示符列中顯示警告通知，顯示經過的時間。如果您經常看到此通知，請檢查您的認證指令碼是否可以最佳化。

144* **協助程式失敗**：{/* min-version: 2.1.208 */}當指令碼以錯誤結束、逾時或不列印任何內容時，請求在三次嘗試內失敗，並顯示 [`Your apiKeyHelper script is failing`](/zh-TW/errors#your-apikeyhelper-script-is-failing)。在 v2.1.208 之前，協助程式失敗會在大約十次無聲重試後顯示為通用 401。144* **協助程式失敗**：當指令碼以錯誤結束、逾時或不列印任何內容時，請求在三次嘗試內失敗，並顯示 [`Your apiKeyHelper script is failing`](/docs/zh-TW/errors#your-apikeyhelper-script-is-failing)。在 v2.1.208 之前，協助程式失敗會在大約十次無聲重試後顯示為通用 401。

145 145

146`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 適用於 CLI 和包裝它的介面，包括 VS Code 擴充功能、Agent SDK 和 GitHub Actions。Claude Desktop 和雲端工作階段不會呼叫 `apiKeyHelper` 或讀取這些環境變數：它們使用 OAuth，除了執行[第三方推論配置](/zh-TW/llm-gateway-connect#desktop-app)的桌面工作階段外，該工作階段使用該配置的認證進行驗證。146`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 適用於 CLI 和包裝它的介面，包括 VS Code 擴充功能、Agent SDK 和 GitHub Actions。Claude Desktop 和雲端工作階段不會呼叫 `apiKeyHelper` 或讀取這些環境變數：它們使用 OAuth，除了執行[第三方推論配置](/docs/zh-TW/llm-gateway-connect#desktop-app)的桌面工作階段外，該工作階段使用該配置的認證進行驗證。

147 147

148<h3 id="renew-an-expiring-login">148<h3 id="renew-an-expiring-login">

149 續約即將過期的登入149 續約即將過期的登入

153 153

154執行 `/login` 以續約。警告僅供參考，永遠不會阻止請求：驗證會持續運作，直到登入實際過期。登入生命週期本身保持不變；提前警告是 v2.1.203 新增的功能。154執行 `/login` 以續約。警告僅供參考，永遠不會阻止請求：驗證會持續運作，直到登入實際過期。登入生命週期本身保持不變；提前警告是 v2.1.203 新增的功能。

155 155

156{/* min-version: 2.1.206 */}一旦儲存的登入過期且無法重新整理，每個請求都會失敗，並顯示 [`Login expired · Please run /login`](/zh-TW/errors#login-expired)，直到您再次登入。在 v2.1.206 之前，過期的登入會顯示為模型錯誤。156一旦儲存的登入過期且無法重新整理，每個請求都會失敗，並顯示 [`Login expired · Please run /login`](/docs/zh-TW/errors#login-expired)，直到您再次登入。在 v2.1.206 之前，過期的登入會顯示為模型錯誤。

157 157

158警告僅在 claude.ai 或 Claude Console 登入是有效認證時出現，而不是在雲端提供商、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 提供認證時出現。158警告僅在 claude.ai 或 Claude Console 登入是有效認證時出現，而不是在雲端提供商、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 提供認證時出現。

159 159

160對於執行無人值守的工作階段，提前續約最為重要。在[代理檢視中的背景工作階段](/zh-TW/agent-view)或[遠端控制](/zh-TW/remote-control)工作階段一旦超過登入生命週期，一旦認證過期就會停止進行，在您再次登入之前無法恢復。160對於執行無人值守的工作階段，提前續約最為重要。在[代理檢視中的背景工作階段](/docs/zh-TW/agent-view)或[遠端控制](/docs/zh-TW/remote-control)工作階段一旦超過登入生命週期，一旦認證過期就會停止進行，在您再次登入之前無法恢復。

161 161

162<h3 id="authentication-precedence">162<h3 id="authentication-precedence">

163 驗證優先順序163 驗證優先順序

165 165

166當存在多個認證時，Claude Code 按此順序選擇一個：166當存在多個認證時，Claude Code 按此順序選擇一個：

167 167

1681. 雲端提供商認證，當設定了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY` 時。請參閱[第三方整合](/zh-TW/third-party-integrations)以取得設定。1681. 雲端提供商認證，當設定了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY` 時。請參閱[第三方整合](/docs/zh-TW/third-party-integrations)以取得設定。

1692. `ANTHROPIC_AUTH_TOKEN` 環境變數。作為 `Authorization: Bearer` 標頭傳送。當透過[LLM 閘道或代理](/zh-TW/llm-gateway)路由時使用此選項，該閘道或代理使用持有人令牌而不是 Anthropic API 金鑰進行驗證。1692. `ANTHROPIC_AUTH_TOKEN` 環境變數。作為 `Authorization: Bearer` 標頭傳送。當透過[LLM 閘道或代理](/docs/zh-TW/llm-gateway)路由時使用此選項，該閘道或代理使用持有人令牌而不是 Anthropic API 金鑰進行驗證。

1703. `ANTHROPIC_API_KEY` 環境變數。作為 `X-Api-Key` 標頭傳送。用於直接 Anthropic API 存取，使用來自 [Claude Console](https://platform.claude.com) 的金鑰。在互動模式下，系統會提示您一次以核准或拒絕金鑰，您的選擇會被記住。若要稍後變更，請使用 `/config` 中的「使用自訂 API 金鑰」切換。在非互動模式 (`-p`) 中，當金鑰存在時始終使用該金鑰。1703. `ANTHROPIC_API_KEY` 環境變數。作為 `X-Api-Key` 標頭傳送。用於直接 Anthropic API 存取，使用來自 [Claude Console](https://platform.claude.com) 的金鑰。在互動模式下，系統會提示您一次以核准或拒絕金鑰，您的選擇會被記住。若要稍後變更，請使用 `/config` 中的「使用自訂 API 金鑰」切換。在非互動模式 (`-p`) 中，當金鑰存在時始終使用該金鑰。

1714. [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼輸出。用於動態或輪換認證，例如從保管庫擷取的短期令牌。1714. [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 指令碼輸出。用於動態或輪換認證，例如從保管庫擷取的短期令牌。

1725. `CLAUDE_CODE_OAUTH_TOKEN` 環境變數。由 [`claude setup-token`](#generate-a-long-lived-token) 產生的長期 OAuth 令牌。用於 CI 管道和指令碼，其中瀏覽器登入不可用。1725. `CLAUDE_CODE_OAUTH_TOKEN` 環境變數。由 [`claude setup-token`](#generate-a-long-lived-token) 產生的長期 OAuth 令牌。用於 CI 管道和指令碼，其中瀏覽器登入不可用。

1736. 來自 `/login` 的訂閱 OAuth 認證。這是 Claude Pro、Max、Team 和 Enterprise 使用者的預設值。1736. 來自 `/login` 的訂閱 OAuth 認證。這是 Claude Pro、Max、Team 和 Enterprise 使用者的預設值。

174 174

175已簽署的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段位於此清單之外：它是一個提供商選擇，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，並且優先於它們。當閘道工作階段存在時，CLI 使用閘道令牌進行驗證，即使設定了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，上面的持有人令牌、API 金鑰和 `apiKeyHelper` 項目也不會被使用。175已簽署的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段位於此清單之外：它是一個提供商選擇，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，並且優先於它們。當閘道工作階段存在時，CLI 使用閘道令牌進行驗證，即使設定了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，上面的持有人令牌、API 金鑰和 `apiKeyHelper` 項目也不會被使用。

176 176

177如果您有有效的 Claude 訂閱，但您的環境中也設定了 `ANTHROPIC_API_KEY`，則 API 金鑰在核准後優先。如果金鑰屬於已停用或過期的組織，這可能會導致驗證失敗。執行 `unset ANTHROPIC_API_KEY` 以回退到您的訂閱，並檢查 `/status` 以確認哪種方法處於活動狀態。`Login method` 列會顯示您的訂閱帳戶，當 API 金鑰在使用中時會出現 `API key` 列。177如果您有有效的 Claude 訂閱，但您的環境中也設定了 `ANTHROPIC_API_KEY`，則 API 金鑰在核准後優先。如果金鑰屬於已停用或過期的組織，這可能會導致驗證失敗。執行 `unset ANTHROPIC_API_KEY` 以回退到您的訂閱，並檢查 `/status` 以確認哪種方法處於活動狀態。`Login method` 列會顯示您的訂閱帳戶，當 API 金鑰在使用中時會出現 `API key` 列。

178 178

179[網頁版 Claude Code](/zh-TW/claude-code-on-the-web) 始終使用您的訂閱認證。如果您在沙箱環境中設定 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，它不會覆蓋您的訂閱認證。179[網頁版 Claude Code](/docs/zh-TW/claude-code-on-the-web) 始終使用您的訂閱認證。如果您在沙箱環境中設定 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，它不會覆蓋您的訂閱認證。

180 180

181<h3 id="generate-a-long-lived-token">181<h3 id="generate-a-long-lived-token">

182 產生長期令牌182 產生長期令牌

194export CLAUDE_CODE_OAUTH_TOKEN=your-token194export CLAUDE_CODE_OAUTH_TOKEN=your-token

195```195```

196 196

197此令牌使用您的 Claude 訂閱進行驗證，需要 Pro、Max、Team 或 Enterprise 方案。它的範圍僅限於推論，無法建立 [Remote Control](/zh-TW/remote-control) 工作階段。197此令牌使用您的 Claude 訂閱進行驗證，需要 Pro、Max、Team 或 Enterprise 方案。它的範圍僅限於推論，無法建立 [Remote Control](/docs/zh-TW/remote-control) 工作階段。

198 198

199[Bare mode](/zh-TW/headless#start-faster-with-bare-mode) 不讀取 `CLAUDE_CODE_OAUTH_TOKEN`。如果您的指令碼傳遞 `--bare`，請改用 `ANTHROPIC_API_KEY` 或 `apiKeyHelper` 進行驗證。199[Bare mode](/docs/zh-TW/headless#start-faster-with-bare-mode) 不讀取 `CLAUDE_CODE_OAUTH_TOKEN`。如果您的指令碼傳遞 `--bare`，請改用 `ANTHROPIC_API_KEY` 或 `apiKeyHelper` 進行驗證。

auto-mode-config.md +18 −18

Details

6 6

7> 告訴自動模式分類器您的組織信任哪些儲存庫、儲存桶和網域。設定環境內容、覆蓋預設的封鎖和允許規則，並使用自動模式 CLI 子命令檢查您的有效設定。7> 告訴自動模式分類器您的組織信任哪些儲存庫、儲存桶和網域。設定環境內容、覆蓋預設的封鎖和允許規則，並使用自動模式 CLI 子命令檢查您的有效設定。

8 8

9[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)讓 Claude Code 無需例行權限提示即可執行，方法是透過分類器路由工具呼叫，該分類器會封鎖任何不可逆、破壞性或針對您環境外的操作。拒絕和明確要求規則在分類器之前進行評估，仍然會封鎖或提示。使用 `autoMode` 設定區塊告訴該分類器您的組織信任哪些儲存庫、儲存桶和網域，以便它停止封鎖例行內部操作。9[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)讓 Claude Code 無需例行權限提示即可執行，方法是透過分類器路由工具呼叫，該分類器會封鎖任何不可逆、破壞性或針對您環境外的操作。拒絕和明確要求規則在分類器之前進行評估，仍然會封鎖或提示。使用 `autoMode` 設定區塊告訴該分類器您的組織信任哪些儲存庫、儲存桶和網域，以便它停止封鎖例行內部操作。

10 10

11<Note>11<Note>

12 自動模式適用於所有提供者上的所有使用者，包括 Anthropic API、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)工作階段。如果 Claude Code 報告您的帳戶無法使用自動模式，請檢查[完整要求](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，其中也涵蓋支援的模型和 Team 及 Enterprise 方案上的擁有者啟用。{/* min-version: 2.1.207 */}在 v2.1.158 至 v2.1.206 中，Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude 應用程式閘道工作階段上的自動模式需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了該要求。12 自動模式適用於所有提供者上的所有使用者，包括 Anthropic API、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段。如果 Claude Code 報告您的帳戶無法使用自動模式，請檢查[完整要求](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，其中也涵蓋支援的模型和 Team 及 Enterprise 方案上的擁有者啟用。在 v2.1.158 至 v2.1.206 中，Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude 應用程式閘道工作階段上的自動模式需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了該要求。

13</Note>13</Note>

14 14

15根據預設，分類器只信任工作目錄和目前儲存庫的已設定遠端。推送到您公司的原始碼控制組織或寫入團隊雲端儲存桶等操作會被封鎖，直到您將它們新增到 `autoMode.environment`。15根據預設，分類器只信任工作目錄和目前儲存庫的已設定遠端。推送到您公司的原始碼控制組織或寫入團隊雲端儲存桶等操作會被封鎖，直到您將它們新增到 `autoMode.environment`。

16 16

~~17如需了解如何啟用自動模式及其預設封鎖的內容，請參閱[權限模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)。此頁面是設定參考。~~17如需了解如何啟用自動模式及其預設封鎖的內容，請參閱[權限模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)。此頁面是設定參考。

18 18

19此頁面涵蓋如何：19此頁面涵蓋如何：

20 20

32 32

33自動模式預設允許推送到您的工作分支、例行推送到儲存庫預設分支，以及建立拉取請求。分類器僅在推送存在風險時才會阻止，例如強制推送或繞過您設定的審查的內容。如果您想在每次推送或拉取請求前進行人工檢查點，請新增權限規則：下面的配方會保持自動模式對所有其他操作開啟。33自動模式預設允許推送到您的工作分支、例行推送到儲存庫預設分支，以及建立拉取請求。分類器僅在推送存在風險時才會阻止，例如強制推送或繞過您設定的審查的內容。如果您想在每次推送或拉取請求前進行人工檢查點，請新增權限規則：下面的配方會保持自動模式對所有其他操作開啟。

34 34

35最直接的機制是 [`permissions.ask`](/zh-TW/permissions#permission-rule-syntax)。內容範圍的 ask 規則（如下面的規則）在分類器之前進行評估，並且始終強制權限提示，即使在自動模式下也是如此，因為明確的 ask 規則是您要求提示該操作的明確意圖。在您的 [設定](/zh-TW/settings#settings-files) 中新增規則：35最直接的機制是 [`permissions.ask`](/docs/zh-TW/permissions#permission-rule-syntax)。內容範圍的 ask 規則（如下面的規則）在分類器之前進行評估，並且始終強制權限提示，即使在自動模式下也是如此，因為明確的 ask 規則是您要求提示該操作的明確意圖。在您的 [設定](/docs/zh-TW/settings#settings-files) 中新增規則：

36 36

37```json theme={null}37```json theme={null}

38{38{

51| :---------- | :-------------------- | :--------------------------------------------------------------------------------------------------- |51| :---------- | :-------------------- | :--------------------------------------------------------------------------------------------------- |

55 55

56<h2 id="where-the-classifier-reads-configuration">56<h2 id="where-the-classifier-reads-configuration">

57 分類器讀取設定的位置57 分類器讀取設定的位置

58</h2>58</h2>

59 59

60分類器讀取與 Claude 本身載入相同的 [CLAUDE.md](/zh-TW/memory) 內容，因此在您專案的 CLAUDE.md 中的指令（例如「永遠不要強制推送」）會同時引導 Claude 和分類器。請從該處開始了解專案慣例和行為規則。60分類器讀取與 Claude 本身載入相同的 [CLAUDE.md](/docs/zh-TW/memory) 內容，因此在您專案的 CLAUDE.md 中的指令（例如「永遠不要強制推送」）會同時引導 Claude 和分類器。請從該處開始了解專案慣例和行為規則。

61 61

62對於跨專案適用的規則，例如受信任的基礎設施或組織範圍的拒絕規則，請使用 `autoMode` 設定區塊。分類器從以下範圍讀取 `autoMode`：62對於跨專案適用的規則，例如受信任的基礎設施或組織範圍的拒絕規則，請使用 `autoMode` 設定區塊。分類器從以下範圍讀取 `autoMode`：

63 63

64| 範圍 | 檔案 | 用途 |64| 範圍 | 檔案 | 用途 |

65| :------------------------- | :--------------------------------------- | :--------------- |65| :------------------------- | :--------------------------------------- | :--------------- |

69 69

70分類器不會從 `.claude/settings.json` 或 `.claude/settings.local.json` 中的專案設定讀取 `autoMode`。兩個檔案都位於儲存庫目錄中，因此已簽入的儲存庫或建置步驟可能會注入自己的允許規則。在 v2.1.207 之前，分類器也會讀取 `.claude/settings.local.json`；請將該檔案中的任何 `autoMode` 區塊移至 `~/.claude/settings.json`。排除 `.claude/settings.local.json` 也會關閉儲存庫提交該檔案或本機工具或建置步驟寫入該檔案的情況。70分類器不會從 `.claude/settings.json` 或 `.claude/settings.local.json` 中的專案設定讀取 `autoMode`。兩個檔案都位於儲存庫目錄中，因此已簽入的儲存庫或建置步驟可能會注入自己的允許規則。在 v2.1.207 之前，分類器也會讀取 `.claude/settings.local.json`；請將該檔案中的任何 `autoMode` 區塊移至 `~/.claude/settings.json`。排除 `.claude/settings.local.json` 也會關閉儲存庫提交該檔案或本機工具或建置步驟寫入該檔案的情況。

72來自每個範圍的項目會被合併。開發者可以使用個人項目擴展 `environment`、`allow`、`soft_deny` 和 `hard_deny`，但無法移除受管理設定提供的項目。由於允許規則在分類器內部充當軟區塊規則的例外，開發者新增的 `allow` 項目可以覆蓋組織的 `soft_deny` 項目：組合是累加的，而不是硬政策邊界。72來自每個範圍的項目會被合併。開發者可以使用個人項目擴展 `environment`、`allow`、`soft_deny` 和 `hard_deny`，但無法移除受管理設定提供的項目。由於允許規則在分類器內部充當軟區塊規則的例外，開發者新增的 `allow` 項目可以覆蓋組織的 `soft_deny` 項目：組合是累加的，而不是硬政策邊界。

73 73

74<Note>74<Note>

75 分類器是在[權限系統](/zh-TW/permissions)之後執行的第二道閘門。對於無論使用者意圖或分類器設定如何都必須永遠不執行的動作，請在受管理設定中使用 `permissions.deny`，它會在諮詢分類器之前阻止該動作，且無法被覆蓋。75 分類器是在[權限系統](/docs/zh-TW/permissions)之後執行的第二道閘門。對於無論使用者意圖或分類器設定如何都必須永遠不執行的動作，請在受管理設定中使用 `permissions.deny`，它會在諮詢分類器之前阻止該動作，且無法被覆蓋。

76</Note>76</Note>

77 77

78<h2 id="define-trusted-infrastructure">78<h2 id="define-trusted-infrastructure">

87 * **組織**87 * **組織**

88 * **Claude Code 的主要用途**：預設為軟體開發88 * **Claude Code 的主要用途**：預設為軟體開發

89 * **雲端提供者**89 * **雲端提供者**

90 * **儲存庫可見性**：除非其遠端主機和名稱另有指示，{/* min-version: 2.1.200 */}或工作階段中較早的可見性檢查分類器讀取顯示它是公開的。分類器讀取您的訊息和 Claude 執行的命令，而不是它們的輸出，因此證據必須是它能讀取的東西，例如您自己的訊息將儲存庫命名為公開；單獨執行 `gh repo view` 的輸出無法到達它。成績單證據檢查需要 Claude Code v2.1.200 或更新版本90 * **儲存庫可見性**：除非其遠端主機和名稱另有指示，或工作階段中較早的可見性檢查分類器讀取顯示它是公開的。分類器讀取您的訊息和 Claude 執行的命令，而不是它們的輸出，因此證據必須是它能讀取的東西，例如您自己的訊息將儲存庫命名為公開；單獨執行 `gh repo view` 的輸出無法到達它。成績單證據檢查需要 Claude Code v2.1.200 或更新版本

91 * **內部共享 / 程式碼片段託管**：公開貼上和 gist 服務被視為在信任邊界外，直到您命名一個91 * **內部共享 / 程式碼片段託管**：公開貼上和 gist 服務被視為在信任邊界外，直到您命名一個

92 * **組織特定的 CLI**92 * **組織特定的 CLI**

93 * **祕密管理**93 * **祕密管理**

96 * **網路態勢**96 * **網路態勢**

97 * **受保護的部署命名空間 / 環境**：回退到敏感遠端目標啟發式方法，直到您命名它們97 * **受保護的部署命名空間 / 環境**：回退到敏感遠端目標啟發式方法，直到您命名它們

98 * **資料保留 / 解密**98 * **資料保留 / 解密**

99* **信任槽位**：命名分類器視為在您邊界內的內容。槽位是受信任儲存庫、原始碼控制、受信任內部網域、受信任雲端儲存桶、關鍵內部服務和內部套件登錄。儲存庫和原始碼控制項目預設為工作儲存庫及其設定的遠端。所有其他信任槽位預設為 `None configured`，因此在您新增之前沒有其他內容是受信任的。{/* min-version: 2.1.203 */}儲存庫的可見性僅限於機密材料：私人儲存庫是機密材料的可接受目的地，但將儲存庫設為私人永遠不會清除祕密或個人或受信任的資料到其中，分類器將從工作儲存庫外部移植、重新指向或首次讀取的內容視為不是該儲存庫自己的工作。此範圍設定需要 Claude Code v2.1.203 或更新版本。99* **信任槽位**：命名分類器視為在您邊界內的內容。槽位是受信任儲存庫、原始碼控制、受信任內部網域、受信任雲端儲存桶、關鍵內部服務和內部套件登錄。儲存庫和原始碼控制項目預設為工作儲存庫及其設定的遠端。所有其他信任槽位預設為 `None configured`，因此在您新增之前沒有其他內容是受信任的。儲存庫的可見性僅限於機密材料：私人儲存庫是機密材料的可接受目的地，但將儲存庫設為私人永遠不會清除祕密或個人或受信任的資料到其中，分類器將從工作儲存庫外部移植、重新指向或首次讀取的內容視為不是該儲存庫自己的工作。此範圍設定需要 Claude Code v2.1.203 或更新版本。

100* **敏感度槽位**：命名保護規則視為高風險的內容。槽位是敏感資料位置與受眾、敏感遠端目標和受保護的 IaC 範圍。每個預設為廣泛的啟發式方法，例如將任何名稱包含 `prod` 或 `production` 的主機或命名空間視為敏感遠端目標，因此保護規則在您設定任何內容之前就處於活動狀態。在敏感度槽位中命名具體目標會使這些規則應用於命名的目標而不是啟發式方法。100* **敏感度槽位**：命名保護規則視為高風險的內容。槽位是敏感資料位置與受眾、敏感遠端目標和受保護的 IaC 範圍。每個預設為廣泛的啟發式方法，例如將任何名稱包含 `prod` 或 `production` 的主機或命名空間視為敏感遠端目標，因此保護規則在您設定任何內容之前就處於活動狀態。在敏感度槽位中命名具體目標會使這些規則應用於命名的目標而不是啟發式方法。

101 101

102要在預設值旁邊新增您自己的項目，請在陣列中包含字面字串 `"$defaults"`。預設項目會在該位置被插入，因此您的自訂項目可以在它們之前或之後。102要在預設值旁邊新增您自己的項目，請在陣列中包含字面字串 `"$defaults"`。預設項目會在該位置被插入，因此您的自訂項目可以在它們之前或之後。

125* **受信任的內部網域**：您網路內的 API、儀表板和服務的主機名稱，例如 `*.internal.example.com`125* **受信任的內部網域**：您網路內的 API、儀表板和服務的主機名稱，例如 `*.internal.example.com`

126* **關鍵內部服務**：CI、工件登錄、內部套件索引、事件工具126* **關鍵內部服務**：CI、工件登錄、內部套件索引、事件工具

127* **內部套件登錄**：私人 npm、PyPI 或其他登錄，安裝應該透過它路由，因此繞過它以使用公開登錄的安裝會被阻止127* **內部套件登錄**：私人 npm、PyPI 或其他登錄，安裝應該透過它路由，因此繞過它以使用公開登錄的安裝會被阻止

128* **敏感資料位置與受眾**：保存個人資料、機密業務資料、認證、受管制資料或類似敏感材料的儲存桶、資料庫或路徑，以及每個位置中的資料可能被共享的受眾，因此分類器保護這些位置而不是從內容猜測。{/* min-version: 2.1.195 */}{/* max-version: 2.1.197 */}Claude Code v2.1.195 至 v2.1.197 將此項目命名為 PII / 受管制資料位置，並且僅涵蓋保存個人或受管制資料的位置，不包括受眾維度128* **敏感資料位置與受眾**：保存個人資料、機密業務資料、認證、受管制資料或類似敏感材料的儲存桶、資料庫或路徑，以及每個位置中的資料可能被共享的受眾，因此分類器保護這些位置而不是從內容猜測。Claude Code v2.1.195 至 v2.1.197 將此項目命名為 PII / 受管制資料位置，並且僅涵蓋保存個人或受管制資料的位置，不包括受眾維度

129* **敏感遠端目標**：計為生產的命名空間、主機或容器，因此遠端 shell 和連接埠轉發到它們需要您的明確批准129* **敏感遠端目標**：計為生產的命名空間、主機或容器，因此遠端 shell 和連接埠轉發到它們需要您的明確批准

130* **受保護的 IaC 範圍**：其應用或銷毀應始終要求您命名變更的基礎設施資源130* **受保護的 IaC 範圍**：其應用或銷毀應始終要求您命名變更的基礎設施資源

131* **其他上下文**：受管制行業的限制、多租戶基礎設施或影響分類器應將什麼視為風險的合規要求131* **其他上下文**：受管制行業的限制、多租戶基礎設施或影響分類器應將什麼視為風險的合規要求

165* `autoMode.soft_deny`：使用者意圖可以清除的破壞性操作165* `autoMode.soft_deny`：使用者意圖可以清除的破壞性操作

166* `autoMode.allow`：軟阻止規則的例外166* `autoMode.allow`：軟阻止規則的例外

167 167

168每個都是散文描述的陣列，讀取為自然語言規則。對於在分類器之前執行的工具模式型硬阻止，請使用 [`permissions.deny`](/zh-TW/permissions)。168每個都是散文描述的陣列，讀取為自然語言規則。對於在分類器之前執行的工具模式型硬阻止，請使用 [`permissions.deny`](/docs/zh-TW/permissions)。

169 169

170在分類器內，優先順序分為四個層級：170在分類器內，優先順序分為四個層級：

171 171

254claude auto-mode defaults254claude auto-mode defaults

255```255```

256 256

257{/* min-version: 2.1.208 */}若要讀取一個規則的完整措辭而不透過 `jq` 管道，請傳遞 `--label` 搭配規則標籤的開頭，例如 `claude auto-mode defaults --label 'Git Destructive'`。比對是對每個規則標籤的不區分大小寫前綴，沒有比對的部分會列印為空清單。需要 Claude Code v2.1.208 或更新版本。257若要讀取一個規則的完整措辭而不透過 `jq` 管道，請傳遞 `--label` 搭配規則標籤的開頭，例如 `claude auto-mode defaults --label 'Git Destructive'`。比對是對每個規則標籤的不區分大小寫前綴，沒有比對的部分會列印為空清單。需要 Claude Code v2.1.208 或更新版本。

258 258

259列印分類器實際使用的內容為 JSON，在設定的地方應用您的設定，否則使用預設值：259列印分類器實際使用的內容為 JSON，在設定的地方應用您的設定，否則使用預設值：

260 260

282 282

283對同一目的地的重複拒絕通常意味著分類器缺少上下文。將該目的地新增到 `autoMode.environment`，然後執行 `claude auto-mode config` 確認它生效。283對同一目的地的重複拒絕通常意味著分類器缺少上下文。將該目的地新增到 `autoMode.environment`，然後執行 `claude auto-mode config` 確認它生效。

284 284

285要以程式設計方式對拒絕做出反應，請使用 [`PermissionDenied` hook](/zh-TW/hooks#permissiondenied)。285要以程式設計方式對拒絕做出反應，請使用 [`PermissionDenied` hook](/docs/zh-TW/hooks#permissiondenied)。

286 286

287<h2 id="see-also">287<h2 id="see-also">

288 另請參閱288 另請參閱

289</h2>289</h2>

290 290

291* [權限模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)：自動模式是什麼、它預設阻止什麼以及如何啟用它291* [權限模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)：自動模式是什麼、它預設阻止什麼以及如何啟用它

292* [受管設定](/zh-TW/server-managed-settings)：在您的組織中部署 `autoMode` 設定292* [受管設定](/docs/zh-TW/server-managed-settings)：在您的組織中部署 `autoMode` 設定

293* [權限](/zh-TW/permissions)：在分類器執行之前應用的允許、詢問和拒絕規則293* [權限](/docs/zh-TW/permissions)：在分類器執行之前應用的允許、詢問和拒絕規則

294* [設定](/zh-TW/settings)：完整的設定參考，包括 `autoMode` 鍵294* [設定](/docs/zh-TW/settings)：完整的設定參考，包括 `autoMode` 鍵

checkpointing.md +5 −5

Details

21Claude Code 追蹤由其檔案編輯工具所做的所有變更：21Claude Code 追蹤由其檔案編輯工具所做的所有變更：

22 22

23* 每個使用者提示都會建立一個新的 checkpoint23* 每個使用者提示都會建立一個新的 checkpoint

24* Claude Code 在一個會話中保留最近 100 個 checkpoint 的檔案快照。捨棄較舊的 checkpoint 會刪除沒有其他 checkpoint 參考的快照檔案，除了每個檔案的第一個快照，VS Code 擴充功能將其用作會話差異的基準。{/* min-version: 2.1.208 */}在 v2.1.208 之前，這些被取代的快照檔案會保留在磁碟上，直到會話被清理。24* Claude Code 在一個會話中保留最近 100 個 checkpoint 的檔案快照。捨棄較舊的 checkpoint 會刪除沒有其他 checkpoint 參考的快照檔案，除了每個檔案的第一個快照，VS Code 擴充功能將其用作會話差異的基準。在 v2.1.208 之前，這些被取代的快照檔案會保留在磁碟上，直到會話被清理。

25* Checkpoints 與對話一起儲存，因此恢復的會話仍然可以 `/rewind` 回到它們25* Checkpoints 與對話一起儲存，因此恢復的會話仍然可以 `/rewind` 回到它們

26* 自動清理，與會話一起在 30 天後刪除（可配置）26* 自動清理，與會話一起在 30 天後刪除（可配置）

27 27

66在這兩種情況下，原始訊息都保存在會話記錄中，因此 Claude 可以在需要時參考詳細資訊。您可以輸入可選指示來引導摘要的重點。這類似於 `/compact`，但更有針對性：您不是總結整個對話，而是選擇所選訊息的哪一側要壓縮。66在這兩種情況下，原始訊息都保存在會話記錄中，因此 Claude 可以在需要時參考詳細資訊。您可以輸入可選指示來引導摘要的重點。這類似於 `/compact`，但更有針對性：您不是總結整個對話，而是選擇所選訊息的哪一側要壓縮。

67 67

68<Note>68<Note>

69 總結讓您保持在同一會話中並壓縮上下文。如果您想嘗試不同的方法，同時保持原始會話完整，請改用 [fork](/zh-TW/sessions#branch-a-session)（`claude --continue --fork-session`）。69 總結讓您保持在同一會話中並壓縮上下文。如果您想嘗試不同的方法，同時保持原始會話完整，請改用 [fork](/docs/zh-TW/sessions#branch-a-session)（`claude --continue --fork-session`）。

70</Note>70</Note>

71 71

72<h2 id="common-use-cases">72<h2 id="common-use-cases">

118 另請參閱118 另請參閱

119</h2>119</h2>

120 120

121* [Interactive mode](/zh-TW/interactive-mode) - 快捷鍵和會話控制121* [Interactive mode](/docs/zh-TW/interactive-mode) - 快捷鍵和會話控制

122* [Commands](/zh-TW/commands) - 使用 `/rewind` 存取 checkpoints122* [Commands](/docs/zh-TW/commands) - 使用 `/rewind` 存取 checkpoints

123* [CLI reference](/zh-TW/cli-reference) - 命令列選項123* [CLI reference](/docs/zh-TW/cli-reference) - 命令列選項

claude-apps-gateway.md +5 −5

Details

62<Note>62<Note>

63 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。63 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。

64 64

65 Anthropic 營運的公開閘道端點是例外：`/login` 透過 `https://` 接受它們。這些是 Anthropic 本身營運的一小組固定閘道；它們不是您可以選擇或配置的部署選項。清單編譯到 Claude Code 中，因此沒有配置可以將主機名新增到其中，您託管的任何閘道都不符合豁免資格。{/* min-version: 2.1.206 */}在 v2.1.206 之前，`/login` 像任何其他公開地址一樣拒絕這些端點。65 Anthropic 營運的公開閘道端點是例外：`/login` 透過 `https://` 接受它們。這些是 Anthropic 本身營運的一小組固定閘道；它們不是您可以選擇或配置的部署選項。清單編譯到 Claude Code 中，因此沒有配置可以將主機名新增到其中，您託管的任何閘道都不符合豁免資格。在 v2.1.206 之前，`/login` 像任何其他公開地址一樣拒絕這些端點。

66</Note>66</Note>

67 67

68<h3 id="prerequisites">68<h3 id="prerequisites">

72在開始之前，請準備好以下內容：72在開始之前，請準備好以下內容：

73 73

74| 您需要 | 詳細資訊 |74| 您需要 | 詳細資訊 |

75| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |75| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

76| Claude Code v2.1.195 或更新版本 | `claude gateway` 子命令和閘道登入流程在 v2.1.195 中發布。較早的公開版本不包含它們。執行閘道伺服器的機器和每個開發人員的機器都必須是 v2.1.195 或更新版本；執行 `claude update` 以取得最新版本。{/* min-version: 2.1.198 */}[Claude Platform on AWS 上游](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)在閘道伺服器上需要 Claude Code v2.1.198 或更新版本。 |76| Claude Code v2.1.195 或更新版本 | `claude gateway` 子命令和閘道登入流程在 v2.1.195 中發布。較早的公開版本不包含它們。執行閘道伺服器的機器和每個開發人員的機器都必須是 v2.1.195 或更新版本；執行 `claude update` 以取得最新版本。[Claude Platform on AWS 上游](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)在閘道伺服器上需要 Claude Code v2.1.198 或更新版本。 |

77| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，例如 PingFederate。閘道針對它執行標準 OIDC 發現和授權碼流程。不支援 SAML 和 LDAP。 |77| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，例如 PingFederate。閘道針對它執行標準 OIDC 發現和授權碼流程。不支援 SAML 和 LDAP。 |

78| PostgreSQL 14 或更新版本 | 支援裝置登入流程，其中瀏覽器回呼寫入，輪詢 CLI 讀取，加上速率限制計數器。任何受管 Postgres 都可以，包括最小層級。在未配置支出限制的情況下，閘道儲存幾 KB 的短期身份驗證狀態；使用[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)，它還持有應備份的耐久支出、稽核和身份表。建議透過 `?sslmode=require` 使用 TLS。 |78| PostgreSQL 14 或更新版本 | 支援裝置登入流程，其中瀏覽器回呼寫入，輪詢 CLI 讀取，加上速率限制計數器。任何受管 Postgres 都可以，包括最小層級。在未配置支出限制的情況下，閘道儲存幾 KB 的短期身份驗證狀態；使用[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)，它還持有應備份的耐久支出、稽核和身份表。建議透過 `?sslmode=require` 使用 TLS。 |

79| 模型上游 | Amazon Bedrock 認證、Claude Platform on AWS 認證、Google Cloud 認證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援多個上游和故障轉移。 |79| 模型上游 | Amazon Bedrock 認證、Claude Platform on AWS 認證、Google Cloud 認證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援多個上游和故障轉移。 |

80| HTTPS | 閘道必須可從開發人員筆記型電腦和用於登入的任何瀏覽器透過 `https://` 到達；閘道在同一監聽器上提供裝置驗證頁面。透過 `listen.tls` 提供 TLS 憑證，或在 TLS 終止入口後執行並設定 `listen.public_url`。純 `http://` 來源僅在本地開發的環回上接受。 |80| HTTPS | 閘道必須可從開發人員筆記型電腦和用於登入的任何瀏覽器透過 `https://` 到達；閘道在同一監聽器上提供裝置驗證頁面。透過 `listen.tls` 提供 TLS 憑證，或在 TLS 終止入口後執行並設定 `listen.public_url`。純 `http://` 來源僅在本地開發的環回上接受。 |

81| 私有網路地址 | 在 `/login` 處，Claude Code 要求閘道的主機名或 IP 地址僅解析為私有地址：RFC 1918、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或本地開發的環回。檢查在每個解析的 IP 上執行，因此如果名稱解析到的任何地址是公開的，`/login` 會拒絕該 URL。如果開發人員機器透過公司代理路由 HTTPS，登入還要求代理主機解析為私有地址；如果不是，將閘道主機新增到 `NO_PROXY`，以便 CLI 直接連接。{/* min-version: 2.1.206 */}Anthropic 營運的公開閘道端點豁免於私有地址和代理檢查：`/login` 透過精確主機名符合接受它們，因此私有網路要求僅適用於您自己託管的閘道。在 v2.1.206 之前，`/login` 像任何其他公開地址一樣拒絕 Anthropic 營運的端點。 |81| 私有網路地址 | 在 `/login` 處，Claude Code 要求閘道的主機名或 IP 地址僅解析為私有地址：RFC 1918、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或本地開發的環回。檢查在每個解析的 IP 上執行，因此如果名稱解析到的任何地址是公開的，`/login` 會拒絕該 URL。如果開發人員機器透過公司代理路由 HTTPS，登入還要求代理主機解析為私有地址；如果不是，將閘道主機新增到 `NO_PROXY`，以便 CLI 直接連接。Anthropic 營運的公開閘道端點豁免於私有地址和代理檢查：`/login` 透過精確主機名符合接受它們，因此私有網路要求僅適用於您自己託管的閘道。在 v2.1.206 之前，`/login` 像任何其他公開地址一樣拒絕 Anthropic 營運的端點。 |

82| Linux 執行時 | 閘道伺服器僅在原生 Linux 二進位檔上執行。macOS 適用於本地開發。Windows 不支援作為伺服器平台。 |82| Linux 執行時 | 閘道伺服器僅在原生 Linux 二進位檔上執行。macOS 適用於本地開發。Windows 不支援作為伺服器平台。 |

83 83

84閘道伺服器需要原生 `claude` 二進位檔；如[安裝 Claude Code](/docs/zh-TW/setup) 中所述下載固定版本。伺服器使用在 Claude Code 在 Node 下執行時不可用的執行時功能。如果您在啟動時看到 `requires the native binary`，請切換到其中一個獨立安裝方法。84閘道伺服器需要原生 `claude` 二進位檔；如[安裝 Claude Code](/docs/zh-TW/setup) 中所述下載固定版本。伺服器使用在 Claude Code 在 Node 下執行時不可用的執行時功能。如果您在啟動時看到 `requires the native binary`，請切換到其中一個獨立安裝方法。

328| 伺服器端網路搜尋 | 不可用 | CLI 無法看到閘道路由到的上游提供商，因此無法驗證網路搜尋支援並在閘道會話上禁用 WebSearch |328| 伺服器端網路搜尋 | 不可用 | CLI 無法看到閘道路由到的上游提供商，因此無法驗證網路搜尋支援並在閘道會話上禁用 WebSearch |

329| 標準提示快取 | 可用 | `cache_control` 斷點被轉發到每個上游 |329| 標準提示快取 | 可用 | `cache_control` 斷點被轉發到每個上游 |

330| 1 小時快取 TTL | 不可用 | CLI 在閘道會話上省略擴展快取 TTL 測試版，因為並非閘道可以路由到的每個上游都支援 1 小時 TTL，因此透過閘道的提示快取使用 5 分鐘 TTL；請參閱上面的測試版標頭備註 |330| 1 小時快取 TTL | 不可用 | CLI 在閘道會話上省略擴展快取 TTL 測試版，因為並非閘道可以路由到的每個上游都支援 1 小時 TTL，因此透過閘道的提示快取使用 5 分鐘 TTL；請參閱上面的測試版標頭備註 |

331| 自動模式 | 可用 | 遵循[第三方提供商規則](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)：只有第三方提供商上符合條件的模型可以使用它。{/* min-version: 2.1.207 */}在 v2.1.207 之前，閘道會話上的自動模式需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，可透過受管原則 `env` 區塊傳遞 |331| 自動模式 | 可用 | 遵循[第三方提供商規則](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)：只有第三方提供商上符合條件的模型可以使用它。在 v2.1.207 之前，閘道會話上的自動模式需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，可透過受管原則 `env` 區塊傳遞 |

332| 僅限第一方的最佳化，例如全域快取範圍和令牌高效工具 | 不可用 | CLI 在閘道會話上不啟用它們；請參閱上面的測試版標頭備註 |332| 僅限第一方的最佳化，例如全域快取範圍和令牌高效工具 | 不可用 | CLI 在閘道會話上不啟用它們；請參閱上面的測試版標頭備註 |

333| OTLP/gRPC | 不支援 | 僅 OTLP over HTTP |333| OTLP/gRPC | 不支援 | 僅 OTLP over HTTP |

334| SAML、LDAP 和其他非 OIDC 身份驗證 | 不支援 | 僅 OIDC。如果需要，使用 OIDC 橋接 |334| SAML、LDAP 和其他非 OIDC 身份驗證 | 不支援 | 僅 OIDC。如果需要，使用 OIDC 橋接 |

claude-apps-gateway-deploy.md +1 −1

Details

20<Note>20<Note>

21 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。21 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。

22 22

23 Anthropic 運營的公開閘道端點是例外：`/login` 透過 `https://` 接受它們。這些是 Anthropic 本身運營的一小組固定閘道；它們不是您可以選擇或配置的部署選項。該清單已編譯到 Claude Code 中，因此沒有配置可以將主機名新增到其中，您託管的任何閘道都不符合豁免條件。{/* min-version: 2.1.206 */}在 v2.1.206 之前，`/login` 像拒絕任何其他公開地址一樣拒絕這些端點。23 Anthropic 運營的公開閘道端點是例外：`/login` 透過 `https://` 接受它們。這些是 Anthropic 本身運營的一小組固定閘道；它們不是您可以選擇或配置的部署選項。該清單已編譯到 Claude Code 中，因此沒有配置可以將主機名新增到其中，您託管的任何閘道都不符合豁免條件。在 v2.1.206 之前，`/login` 像拒絕任何其他公開地址一樣拒絕這些端點。

24</Note>24</Note>

25 25

26<h2 id="identity-provider-setup">26<h2 id="identity-provider-setup">

claude-code-on-the-web.md +5 −5

Details

140 140

141每個雲端工作階段在 claude.ai 上都有一個成績單 URL，工作階段可以從 `CLAUDE_CODE_REMOTE_SESSION_ID` 環境變數讀取自己的 ID。使用此在 PR 正文、提交訊息、Slack 貼文或生成的報告中放置可追蹤的連結，以便審查者可以開啟產生它們的執行。141每個雲端工作階段在 claude.ai 上都有一個成績單 URL，工作階段可以從 `CLAUDE_CODE_REMOTE_SESSION_ID` 環境變數讀取自己的 ID。使用此在 PR 正文、提交訊息、Slack 貼文或生成的報告中放置可追蹤的連結，以便審查者可以開啟產生它們的執行。

142 142

143自 v2.1.179 起，Claude 在網頁工作階段中建立的提交包括 `Claude-Session: <url>` git 預告片，PR 正文包括工作階段 URL 在其自己的行上。{/* min-version: 2.1.182 */}從 v2.1.182 起，設定 [`attribution.sessionUrl`](/docs/zh-TW/settings#attribution-settings) 為 `false` 以省略預告片和 PR 正文連結。143自 v2.1.179 起，Claude 在網頁工作階段中建立的提交包括 `Claude-Session: <url>` git 預告片，PR 正文包括工作階段 URL 在其自己的行上。從 v2.1.182 起，設定 [`attribution.sessionUrl`](/docs/zh-TW/settings#attribution-settings) 為 `false` 以省略預告片和 PR 正文連結。

144 144

145若要在提交或 PR 以外的其他內容中包括工作階段連結，例如 Claude 發佈的 Slack 訊息或它寫入的報告檔案，請讓 Claude 執行以下命令並使用其輸出。該命令將環境變數值中的 `cse_` 前綴轉換為成績單 URL 期望的 `session_` 前綴：145若要在提交或 PR 以外的其他內容中包括工作階段連結，例如 Claude 發佈的 Slack 訊息或它寫入的報告檔案，請讓 Claude 執行以下命令並使用其輸出。該命令將環境變數值中的 `cse_` 前綴轉換為成績單 URL 期望的 `session_` 前綴：

146 146

669 669

670這會在 claude.ai 上建立新的雲端工作階段。工作階段複製您目前目錄的 GitHub 遠端，位於您目前的分支，因此如果您有本機提交，請先推送，因為 VM 從 GitHub 而不是您的機器複製。`--cloud` 一次適用於單一儲存庫。任務在雲端執行，而您繼續在本機工作。較舊的 `--remote` 拼寫仍然可作為 `--cloud` 的已棄用別名。670這會在 claude.ai 上建立新的雲端工作階段。工作階段複製您目前目錄的 GitHub 遠端，位於您目前的分支，因此如果您有本機提交，請先推送，因為 VM 從 GitHub 而不是您的機器複製。`--cloud` 一次適用於單一儲存庫。任務在雲端執行，而您繼續在本機工作。較舊的 `--remote` 拼寫仍然可作為 `--cloud` 的已棄用別名。

671 671

672{/* min-version: 2.1.195 */}自 v2.1.195 起，CLI 會顯示設定步驟的即時檢查清單，例如複製儲存庫和執行您的[設定指令碼](#setup-scripts)，同時雲端容器啟動。您在容器佈建時輸入的訊息會排隊，並在工作階段準備好後發送。672自 v2.1.195 起，CLI 會顯示設定步驟的即時檢查清單，例如複製儲存庫和執行您的[設定指令碼](#setup-scripts)，同時雲端容器啟動。您在容器佈建時輸入的訊息會排隊，並在工作階段準備好後發送。

673 673

674<Note>674<Note>

675 `--cloud` 建立雲端工作階段。`--remote-control` 無關：它公開本機 CLI 工作階段以從網頁進行監控。請參閱[遠端控制](/docs/zh-TW/remote-control)。675 `--cloud` 建立雲端工作階段。`--remote-control` 無關：它公開本機 CLI 工作階段以從網頁進行監控。請參閱[遠端控制](/docs/zh-TW/remote-control)。

748傳送在恢復工作階段之前檢查這些要求。如果任何要求未滿足，您會看到錯誤或被提示解決問題。748傳送在恢復工作階段之前檢查這些要求。如果任何要求未滿足，您會看到錯誤或被提示解決問題。

749 749

750| 要求 | 詳細資訊 |750| 要求 | 詳細資訊 |

751| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |751| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

752| 乾淨的 git 狀態 | 您的工作目錄必須沒有未提交的變更。如果需要，傳送會提示您隱藏變更。 |752| 乾淨的 git 狀態 | 您的工作目錄必須沒有未提交的變更。如果需要，傳送會提示您隱藏變更。 |

753| 正確的儲存庫 | 您必須從同一儲存庫的簽出執行 `--teleport`，而不是分支。{/* min-version: 2.1.199 */}自 v2.1.199 起，Claude Code 接受簽出，即使它無法將遠端解析為主機名稱，例如 SSH 主機別名（如 `git@work:owner/repo.git`）或 `insteadOf` 重寫的短形式。它首先顯示確認提示，並且僅當遠端的擁有者和儲存庫名稱與工作階段的儲存庫相符時。 |753| 正確的儲存庫 | 您必須從同一儲存庫的簽出執行 `--teleport`，而不是分支。自 v2.1.199 起，Claude Code 接受簽出，即使它無法將遠端解析為主機名稱，例如 SSH 主機別名（如 `git@work:owner/repo.git`）或 `insteadOf` 重寫的短形式。它首先顯示確認提示，並且僅當遠端的擁有者和儲存庫名稱與工作階段的儲存庫相符時。 |

754| 分支可用 | 雲端工作階段中的分支必須已推送到遠端。傳送會自動取得並簽出它。 |754| 分支可用 | 雲端工作階段中的分支必須已推送到遠端。傳送會自動取得並簽出它。 |

755| 相同帳戶 | 您必須驗證到雲端工作階段中使用的相同 claude.ai 帳戶。 |755| 相同帳戶 | 您必須驗證到雲端工作階段中使用的相同 claude.ai 帳戶。 |

756 756

772 772

773雲端工作階段支援產生文字輸出的[內建命令](/docs/zh-TW/commands)。只在終端介面中執行的命令，例如 `/plugin` 或 `/resume`，無法使用。在雲端工作階段中開啟選擇器或面板的命令行為不同：773雲端工作階段支援產生文字輸出的[內建命令](/docs/zh-TW/commands)。只在終端介面中執行的命令，例如 `/plugin` 或 `/resume`，無法使用。在雲端工作階段中開啟選擇器或面板的命令行為不同：

774 774

775* {/* min-version: 2.1.205 */}**`/model`、`/effort`、`/fast`、`/color` 和 `/rename`**：將值作為引數傳遞，例如 `/model sonnet`，而不是開啟終端選擇器或滑塊。引數形式需要工作階段環境中的 Claude Code v2.1.205 或更新版本，並遵循每個命令的[可用性說明](/docs/zh-TW/commands#all-commands)：當模型的[啟動預設努力保持](/docs/zh-TW/model-config#adjust-effort-level)生效時，`/effort` 會報告 `Not applied`，而 `/fast` 僅在以快速模式啟動的工作階段中有效。775* **`/model`、`/effort`、`/fast`、`/color` 和 `/rename`**：將值作為引數傳遞，例如 `/model sonnet`，而不是開啟終端選擇器或滑塊。引數形式需要工作階段環境中的 Claude Code v2.1.205 或更新版本，並遵循每個命令的[可用性說明](/docs/zh-TW/commands#all-commands)：當模型的[啟動預設努力保持](/docs/zh-TW/model-config#adjust-effort-level)生效時，`/effort` 會報告 `Not applied`，而 `/fast` 僅在以快速模式啟動的工作階段中有效。

776* **`/config`**：在網路上，開啟您設定的 Claude Code 部分，而不是設定值，命令後的文字（包括 `key=value`）會被忽略。若要變更雲端工作階段的設定，請使用[環境變數](#configure-your-environment)或將[設定檔案](/docs/zh-TW/settings)提交到儲存庫。776* **`/config`**：在網路上，開啟您設定的 Claude Code 部分，而不是設定值，命令後的文字（包括 `key=value`）會被忽略。若要變更雲端工作階段的設定，請使用[環境變數](#configure-your-environment)或將[設定檔案](/docs/zh-TW/settings)提交到儲存庫。

777 777

778對於上下文管理特別：778對於上下文管理特別：

claude-platform-on-aws.md +9 −9

Details

188 188

189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="claude_platform_on_aws" />} />189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="claude_platform_on_aws" />} />

190 190

191AWS 上的 Claude Platform 是 Anthropic 營運的 Claude API，具有 AWS 驗證、IAM 存取控制和 AWS Marketplace 計費。請求直接到達 Anthropic 的 API，因此您可以獲得與 [Claude API](https://platform.claude.com/docs) 相同的模型和 API 功能，並遵循相同的發佈時程表。Claude Code 透過 Anthropic 的功能旗標服務啟用的用戶端功能，例如 [`/loop` 自我調整步調](/zh-TW/scheduled-tasks#let-claude-choose-the-interval)，預設為關閉，且 [advisor 工具](/zh-TW/advisor) 無法使用。請參閱 [功能可用性矩陣](/zh-TW/feature-availability#summary-by-provider) 以取得完整清單。您使用 AWS 認證或工作區 API 金鑰進行驗證，並透過 AWS Marketplace 付款。191AWS 上的 Claude Platform 是 Anthropic 營運的 Claude API，具有 AWS 驗證、IAM 存取控制和 AWS Marketplace 計費。請求直接到達 Anthropic 的 API，因此您可以獲得與 [Claude API](https://platform.claude.com/docs) 相同的模型和 API 功能，並遵循相同的發佈時程表。Claude Code 透過 Anthropic 的功能旗標服務啟用的用戶端功能，例如 [`/loop` 自我調整步調](/docs/zh-TW/scheduled-tasks#let-claude-choose-the-interval)，預設為關閉，且 [advisor 工具](/docs/zh-TW/advisor) 無法使用。請參閱 [功能可用性矩陣](/docs/zh-TW/feature-availability#summary-by-provider) 以取得完整清單。您使用 AWS 認證或工作區 API 金鑰進行驗證，並透過 AWS Marketplace 付款。

192 192

193使用本指南將 Claude Code 指向您已透過 AWS 上的 Claude Platform 佈建的工作區。有關在此之前的 AWS 訂閱和工作區設定，請參閱 [AWS 上的 Claude Platform 文件](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)。193使用本指南將 Claude Code 指向您已透過 AWS 上的 Claude Platform 佈建的工作區。有關在此之前的 AWS 訂閱和工作區設定，請參閱 [AWS 上的 Claude Platform 文件](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)。

194 194

230 230

231對於 CI 和自動化，給予執行器具有叫用 Anthropic 服務權限的 IAM 角色，並設定 `AWS_REGION`。認證鏈會自動選取該角色。231對於 CI 和自動化，給予執行器具有叫用 Anthropic 服務權限的 IAM 角色，並設定 `AWS_REGION`。認證鏈會自動選取該角色。

232 232

233如果您的 SSO 認證在工作階段中途過期，請設定 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration)，以便 Claude Code 重新執行您的登入命令並重試，而不是失敗。AWS 上的 Claude Platform 上的自動重新整理需要 Claude Code v2.1.198 或更新版本；較早的版本會停止並提示執行 `/login`，這無法重新整理 AWS 認證。將命令新增至您的 `settings.json`：233如果您的 SSO 認證在工作階段中途過期，請設定 [`awsAuthRefresh`](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration)，以便 Claude Code 重新執行您的登入命令並重試，而不是失敗。AWS 上的 Claude Platform 上的自動重新整理需要 Claude Code v2.1.198 或更新版本；較早的版本會停止並提示執行 `/login`，這無法重新整理 AWS 認證。將命令新增至您的 `settings.json`：

234 234

235```json theme={null}235```json theme={null}

236{236{

250 250

251金鑰以 `x-api-key` 形式傳送，優先於 SigV4，因此您環境中的任何 AWS 認證都會被忽略。來自單獨 Claude Console 組織的 API 金鑰在此不起作用。251金鑰以 `x-api-key` 形式傳送，優先於 SigV4，因此您環境中的任何 AWS 認證都會被忽略。來自單獨 Claude Console 組織的 API 金鑰在此不起作用。

252 252

253將工作區 API 金鑰視為任何其他生產認證。[使用者設定檔](/zh-TW/settings) `env` 區塊是在不全域匯出的情況下將金鑰限定於您的機器的便利方式。253將工作區 API 金鑰視為任何其他生產認證。[使用者設定檔](/docs/zh-TW/settings) `env` 區塊是在不全域匯出的情況下將金鑰限定於您的機器的便利方式。

254 254

255<Note>255<Note>

256 `/login` 和 `/logout` 命令不會變更 AWS 上的 Claude Platform 驗證。驗證透過您的 AWS 認證或工作區 API 金鑰執行，而不是透過 Claude.ai 訂閱。唯一的例外是當設定 `awsAuthRefresh` 時，`/login` 顯示的 **重新整理認證** 選項，它會如上所述重新讀取您的 AWS 認證。256 `/login` 和 `/logout` 命令不會變更 AWS 上的 Claude Platform 驗證。驗證透過您的 AWS 認證或工作區 API 金鑰執行，而不是透過 Claude.ai 訂閱。唯一的例外是當設定 `awsAuthRefresh` 時，`/login` 顯示的 **重新整理認證** 選項，它會如上所述重新讀取您的 AWS 認證。

278 278

279AWS 上的 Claude Platform 使用與直接 Claude API 相同的模型 ID。279AWS 上的 Claude Platform 使用與直接 Claude API 相同的模型 ID。

280 280

281預設別名 `fable`、`opus`、`sonnet` 和 `haiku` 解析為 Claude Code 針對 AWS 上的 Claude Platform 的內建預設值，這些值可能落後於最新版本。沒有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，`opus` 別名解析為 Opus 4.8。{/* min-version: 2.1.207 */}在 v2.1.207 之前，它解析為 Opus 4.7。281預設別名 `fable`、`opus`、`sonnet` 和 `haiku` 解析為 Claude Code 針對 AWS 上的 Claude Platform 的內建預設值，這些值可能落後於最新版本。沒有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，`opus` 別名解析為 Opus 4.8。在 v2.1.207 之前，它解析為 Opus 4.7。

282 282

283如果您將 Claude Code 部署到團隊，請明確固定模型 ID，以便新版本不會一次移動所有人：283如果您將 Claude Code 部署到團隊，請明確固定模型 ID，以便新版本不會一次移動所有人：

284 284

289export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5289export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

290```290```

291 291

292有關模型 ID 和別名的完整清單，請參閱[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。有關其他模型相關變數，請參閱[模型設定](/zh-TW/model-config)。292有關模型 ID 和別名的完整清單，請參閱[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。有關其他模型相關變數，請參閱[模型設定](/docs/zh-TW/model-config)。

293 293

294[Prompt caching](/zh-TW/prompt-caching) 會自動啟用。若要要求 1 小時快取 TTL 而不是 5 分鐘預設值，請設定 `ENABLE_PROMPT_CACHING_1H=1`。API 以更高的費率計費 1 小時快取寫入。有關費率，請參閱 [prompt caching 定價](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。294[Prompt caching](/docs/zh-TW/prompt-caching) 會自動啟用。若要要求 1 小時快取 TTL 而不是 5 分鐘預設值，請設定 `ENABLE_PROMPT_CACHING_1H=1`。API 以更高的費率計費 1 小時快取寫入。有關費率，請參閱 [prompt caching 定價](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。

295 295

296<h2 id="use-the-agent-sdk">296<h2 id="use-the-agent-sdk">

297 使用 Agent SDK297 使用 Agent SDK

298</h2>298</h2>

299 299

300[Agent SDK](/zh-TW/agent-sdk/overview) 讀取與 CLI 相同的環境變數，因此任何產生 Claude Code 子程序的程式都可以透過在呼叫前匯出 `CLAUDE_CODE_USE_ANTHROPIC_AWS`、`ANTHROPIC_AWS_WORKSPACE_ID` 和 `ANTHROPIC_AWS_API_KEY` 或 AWS 認證來針對 AWS 上的 Claude Platform。300[Agent SDK](/docs/zh-TW/agent-sdk/overview) 讀取與 CLI 相同的環境變數，因此任何產生 Claude Code 子程序的程式都可以透過在呼叫前匯出 `CLAUDE_CODE_USE_ANTHROPIC_AWS`、`ANTHROPIC_AWS_WORKSPACE_ID` 和 `ANTHROPIC_AWS_API_KEY` 或 AWS 認證來針對 AWS 上的 Claude Platform。

301 301

302```typescript theme={null}302```typescript theme={null}

303import { query } from "@anthropic-ai/claude-agent-sdk";303import { query } from "@anthropic-ai/claude-agent-sdk";

311}311}

312```312```

313 313

314此範例依賴環境 AWS 認證鏈進行 SigV4。若要改用工作區 API 金鑰進行驗證，請以相同方式設定 `ANTHROPIC_AWS_API_KEY`。有關更廣泛的 Agent SDK 表面，請參閱 [Agent SDK 概述](/zh-TW/agent-sdk/overview)。314此範例依賴環境 AWS 認證鏈進行 SigV4。若要改用工作區 API 金鑰進行驗證，請以相同方式設定 `ANTHROPIC_AWS_API_KEY`。有關更廣泛的 Agent SDK 表面，請參閱 [Agent SDK 概述](/docs/zh-TW/agent-sdk/overview)。

315 315

316<h2 id="route-through-a-corporate-proxy">316<h2 id="route-through-a-corporate-proxy">

317 透過公司代理路由317 透過公司代理路由

318</h2>318</h2>

319 319

320若要透過代理或 [LLM gateway](/zh-TW/llm-gateway) 路由流量，請將 `ANTHROPIC_AWS_BASE_URL` 設定為代理的位址。Claude Code 將請求傳送至該 URL，並使用相同的工作區和驗證標頭，因此任何轉發它們不變的閘道都有效。320若要透過代理或 [LLM gateway](/docs/zh-TW/llm-gateway) 路由流量，請將 `ANTHROPIC_AWS_BASE_URL` 設定為代理的位址。Claude Code 將請求傳送至該 URL，並使用相同的工作區和驗證標頭，因此任何轉發它們不變的閘道都有效。

321 321

322```bash theme={null}322```bash theme={null}

323export CLAUDE_CODE_USE_ANTHROPIC_AWS=1323export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

cli-reference.md +68 −68

Details

25| `claude gateway` | 啟動自託管 [Claude apps gateway](/zh-TW/claude-apps-gateway) 伺服器，供在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上部署 SSO 和原則在 Claude Code 前面的管理員使用。需要 `--config` 指向 [`gateway.yaml`](/zh-TW/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更新版本中可用。 | `claude gateway --config gateway.yaml` |25| `claude gateway` | 啟動自託管 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 伺服器，供在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上部署 SSO 和原則在 Claude Code 前面的管理員使用。需要 `--config` 指向 [`gateway.yaml`](/docs/zh-TW/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更新版本中可用。 | `claude gateway --config gateway.yaml` |

27| `claude auth login` | 登入您的 Anthropic 帳戶。使用 `--email` 預先填入您的電子郵件地址，使用 `--sso` 強制進行 SSO 驗證，使用 `--console` 以 Anthropic Console 登入以進行 API 使用計費，而不是 Claude 訂閱 | `claude auth login --console` |27| `claude auth login` | 登入您的 Anthropic 帳戶。使用 `--email` 預先填入您的電子郵件地址，使用 `--sso` 強制進行 SSO 驗證，使用 `--console` 以 Anthropic Console 登入以進行 API 使用計費，而不是 Claude 訂閱 | `claude auth login --console` |

30| `claude agents` | 開啟 [agent view](/zh-TW/agent-view) 以監控和分派平行背景工作階段。使用 `--cwd <path>` 僅顯示在該目錄下啟動的工作階段，或使用 `--json` 將即時工作階段列印為 JSON 陣列以供指令碼使用（`--json --all` 也包括已完成的背景工作階段）。傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以設定 [分派工作階段的預設值](/zh-TW/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如同頂層 `claude` 命令。開啟 agent view 需要互動式終端 | `claude agents --json` |30| `claude agents` | 開啟 [agent view](/docs/zh-TW/agent-view) 以監控和分派平行背景工作階段。使用 `--cwd <path>` 僅顯示在該目錄下啟動的工作階段，或使用 `--json` 將即時工作階段列印為 JSON 陣列以供指令碼使用（`--json --all` 也包括已完成的背景工作階段）。傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以設定 [分派工作階段的預設值](/docs/zh-TW/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如同頂層 `claude` 命令。開啟 agent view 需要互動式終端 | `claude agents --json` |

32| `claude auto-mode defaults` | 以 JSON 格式列印內建的 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看您的有效設定及套用的設定。{/* min-version: 2.1.208 */}}`--label <prefix>` 列印標籤以該前綴開頭的規則，不區分大小寫匹配。需要 Claude Code v2.1.208 或更新版本 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 以 JSON 格式列印內建的 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看您的有效設定及套用的設定。}`--label <prefix>` 列印標籤以該前綴開頭的規則，不區分大小寫匹配。需要 Claude Code v2.1.208 或更新版本 | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude daemon status` | 列印背景工作階段 [supervisor](/zh-TW/agent-view#the-supervisor-process) 的狀態、版本、socket 目錄和工作者計數以進行診斷。如果 supervisor 未執行則以代碼 1 退出 | `claude daemon status` |33| `claude daemon status` | 列印背景工作階段 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 的狀態、版本、socket 目錄和工作者計數以進行診斷。如果 supervisor 未執行則以代碼 1 退出 | `claude daemon status` |

34| `claude daemon stop --any` | 停止背景工作階段 [supervisor](/zh-TW/agent-view#the-supervisor-process) 及其託管的工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行中，以便下一個 supervisor 重新連接到它們。`--any` 確認停止隨選 supervisor，這是預設值。使用此命令以從 [無回應的 supervisor](/zh-TW/agent-view#agent-view-says-the-background-service-did-not-respond) 復原 | `claude daemon stop --any --keep-workers` |34| `claude daemon stop --any` | 停止背景工作階段 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 及其託管的工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行中，以便下一個 supervisor 重新連接到它們。`--any` 確認停止隨選 supervisor，這是預設值。使用此命令以從 [無回應的 supervisor](/docs/zh-TW/agent-view#agent-view-says-the-background-service-did-not-respond) 復原 | `claude daemon stop --any --keep-workers` |

38| `claude mcp login <name>` | {/* min-version: 2.1.186 */}執行已設定的 MCP 伺服器的 OAuth 流程而不開啟互動式 `/mcp` 面板。適用於 HTTP、SSE 和 claude.ai 連接器伺服器。在 SSH 上新增 `--no-browser` 以列印授權 URL 而不是開啟瀏覽器，然後將重新導向 URL 貼回提示。需要 Claude Code v2.1.186 或更新版本。請參閱 [從命令列驗證](/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |38| `claude mcp login <name>` | 執行已設定的 MCP 伺服器的 OAuth 流程而不開啟互動式 `/mcp` 面板。適用於 HTTP、SSE 和 claude.ai 連接器伺服器。在 SSH 上新增 `--no-browser` 以列印授權 URL 而不是開啟瀏覽器，然後將重新導向 URL 貼回提示。需要 Claude Code v2.1.186 或更新版本。請參閱 [從命令列驗證](/docs/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |

39| `claude mcp logout <name>` | {/* min-version: 2.1.186 */}清除 MCP 伺服器的已儲存 OAuth 認證。需要 Claude Code v2.1.186 或更新版本 | `claude mcp logout sentry` |39| `claude mcp logout <name>` | 清除 MCP 伺服器的已儲存 OAuth 認證。需要 Claude Code v2.1.186 或更新版本 | `claude mcp logout sentry` |

40| `claude plugin` | 管理 Claude Code [plugins](/zh-TW/plugins)。別名：`claude plugins`。請參閱 [plugin 參考](/zh-TW/plugins-reference#cli-commands-reference) 以了解子命令 | `claude plugin install code-review@claude-plugins-official` |40| `claude plugin` | 管理 Claude Code [plugins](/docs/zh-TW/plugins)。別名：`claude plugins`。請參閱 [plugin 參考](/docs/zh-TW/plugins-reference#cli-commands-reference) 以了解子命令 | `claude plugin install code-review@claude-plugins-official` |

41| `claude project purge [path]` | 刪除專案的所有本機 Claude Code 狀態：文字記錄、工作清單、偵錯日誌、檔案編輯歷史記錄、提示歷史記錄行和專案在 `~/.claude.json` 中的項目。省略 `[path]` 以從互動式清單中選擇。旗標：`--dry-run` 以預覽，`-y`/`--yes` 以跳過確認，`-i`/`--interactive` 以確認每個項目，`--all` 用於每個專案。請參閱 [清除本機資料](/zh-TW/claude-directory#clear-local-data) | `claude project purge ~/work/repo --dry-run` |41| `claude project purge [path]` | 刪除專案的所有本機 Claude Code 狀態：文字記錄、工作清單、偵錯日誌、檔案編輯歷史記錄、提示歷史記錄行和專案在 `~/.claude.json` 中的項目。省略 `[path]` 以從互動式清單中選擇。旗標：`--dry-run` 以預覽，`-y`/`--yes` 以跳過確認，`-i`/`--interactive` 以確認每個項目，`--all` 用於每個專案。請參閱 [清除本機資料](/docs/zh-TW/claude-directory#clear-local-data) | `claude project purge ~/work/repo --dry-run` |

42| `claude remote-control` | 啟動 [Remote Control](/zh-TW/remote-control) 伺服器以從 Claude.ai 或 Claude 應用程式控制 Claude Code。在伺服器模式下執行（無本機互動式工作階段）。請參閱 [伺服器模式旗標](/zh-TW/remote-control#start-a-remote-control-session) | `claude remote-control --name "My Project"` |42| `claude remote-control` | 啟動 [Remote Control](/docs/zh-TW/remote-control) 伺服器以從 Claude.ai 或 Claude 應用程式控制 Claude Code。在伺服器模式下執行（無本機互動式工作階段）。請參閱 [伺服器模式旗標](/docs/zh-TW/remote-control#start-a-remote-control-session) | `claude remote-control --name "My Project"` |

43| `claude respawn <id>` | 重新啟動 [背景工作階段](/zh-TW/agent-view#manage-sessions-from-the-shell)（執行中或已停止），保持其對話完整。使用 `--all` 重新啟動每個執行中的工作階段，例如以取得更新的 Claude Code 二進位檔 | `claude respawn 7c5dcf5d` |43| `claude respawn <id>` | 重新啟動 [背景工作階段](/docs/zh-TW/agent-view#manage-sessions-from-the-shell)（執行中或已停止），保持其對話完整。使用 `--all` 重新啟動每個執行中的工作階段，例如以取得更新的 Claude Code 二進位檔 | `claude respawn 7c5dcf5d` |

47| `claude ultrareview [target]` | 非互動式執行 [ultrareview](/zh-TW/ultrareview#run-ultrareview-non-interactively)。將發現列印到標準輸出，成功時以代碼 0 退出，失敗時以代碼 1 退出。使用 `--json` 取得原始承載，使用 `--timeout <minutes>` 覆蓋 30 分鐘的預設值 | `claude ultrareview 1234 --json` |47| `claude ultrareview [target]` | 非互動式執行 [ultrareview](/docs/zh-TW/ultrareview#run-ultrareview-non-interactively)。將發現列印到標準輸出，成功時以代碼 0 退出，失敗時以代碼 1 退出。使用 `--json` 取得原始承載，使用 `--timeout <minutes>` 覆蓋 30 分鐘的預設值 | `claude ultrareview 1234 --json` |

48 48

49如果您輸入錯誤的子命令，Claude Code 會建議最接近的匹配項並退出而不啟動工作階段。例如，`claude udpate` 會列印 `Did you mean claude update?`。49如果您輸入錯誤的子命令，Claude Code 會建議最接近的匹配項並退出而不啟動工作階段。例如，`claude udpate` 會列印 `Did you mean claude update?`。

50 50

51{/* min-version: 2.1.199 */}自 v2.1.199 起，`claude --dangerously-skip-permissions daemon <subcommand>` 執行 `daemon` 子命令。較早的版本將 `daemon <subcommand>` 視為新互動式工作階段的提示，因此當旗標在前面時子命令永遠不會執行，這是 `claude` 別名為包含該旗標時的常見設定。只有前導 `--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 會以這種方式路由到 `daemon`；任何其他前導旗標仍會啟動互動式工作階段。51自 v2.1.199 起，`claude --dangerously-skip-permissions daemon <subcommand>` 執行 `daemon` 子命令。較早的版本將 `daemon <subcommand>` 視為新互動式工作階段的提示，因此當旗標在前面時子命令永遠不會執行，這是 `claude` 別名為包含該旗標時的常見設定。只有前導 `--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 會以這種方式路由到 `daemon`；任何其他前導旗標仍會啟動互動式工作階段。

52 52

53<h2 id="cli-flags">53<h2 id="cli-flags">

54 CLI 旗標54 CLI 旗標

57使用這些命令列旗標自訂 Claude Code 的行為。`claude --help` 不會列出每個旗標，因此旗標在 `--help` 中的缺失並不表示它無法使用。57使用這些命令列旗標自訂 Claude Code 的行為。`claude --help` 不會列出每個旗標，因此旗標在 `--help` 中的缺失並不表示它無法使用。

58 58

59| 旗標 | 描述 | 範例 |59| 旗標 | 描述 | 範例 |

60| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |60| :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |

61| `--add-dir` | 新增額外的工作目錄供 Claude 讀取和編輯檔案。授予檔案存取權；大多數 `.claude/` 設定 [未從這些目錄探索](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。驗證每個路徑是否存在為目錄。若要在工作階段之間持久化這些目錄，請在設定中設定 [`permissions.additionalDirectories`](/zh-TW/settings#permission-settings) | `claude --add-dir ../apps ../lib` |61| `--add-dir` | 新增額外的工作目錄供 Claude 讀取和編輯檔案。授予檔案存取權；大多數 `.claude/` 設定 [未從這些目錄探索](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。驗證每個路徑是否存在為目錄。若要在工作階段之間持久化這些目錄，請在設定中設定 [`permissions.additionalDirectories`](/docs/zh-TW/settings#permission-settings) | `claude --add-dir ../apps ../lib` |

62| `--advisor <model>` | 使用模型別名啟用此工作階段的伺服器端 [advisor tool](/zh-TW/advisor)：`opus`、`sonnet` 或 `fable`（{/* min-version: 2.1.170 */}v2.1.170+），或完整模型 ID。優先於工作階段的 `advisorModel` 設定 | `claude --advisor opus` |62| `--advisor <model>` | 使用模型別名啟用此工作階段的伺服器端 [advisor tool](/docs/zh-TW/advisor)：`opus`、`sonnet` 或 `fable`（v2.1.170+），或完整模型 ID。優先於工作階段的 `advisorModel` 設定 | `claude --advisor opus` |

64| `--agents` | 透過 JSON 動態定義自訂 subagents。使用與 subagent [frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields) 相同的欄位名稱，加上代理程式指示的 `prompt` 欄位 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |64| `--agents` | 透過 JSON 動態定義自訂 subagents。使用與 subagent [frontmatter](/docs/zh-TW/sub-agents#supported-frontmatter-fields) 相同的欄位名稱，加上代理程式指示的 `prompt` 欄位 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

65| `--allow-dangerously-skip-permissions` | 新增 `bypassPermissions` 到 `Shift+Tab` 模式循環而不立即啟動它。允許您以不同的模式（如 `plan`）開始，稍後切換到 `bypassPermissions`。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |65| `--allow-dangerously-skip-permissions` | 新增 `bypassPermissions` 到 `Shift+Tab` 模式循環而不立即啟動它。允許您以不同的模式（如 `plan`）開始，稍後切換到 `bypassPermissions`。請參閱 [permission modes](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

66| `--allowedTools`、`--allowed-tools` | 無需提示權限即可執行的工具。請參閱 [permission rule syntax](/zh-TW/settings#permission-rule-syntax) 以了解模式匹配。若要限制可用的工具，請改用 `--tools` | `"Bash(git log *)" "Bash(git diff *)" "Read"` |66| `--allowedTools`、`--allowed-tools` | 無需提示權限即可執行的工具。請參閱 [permission rule syntax](/docs/zh-TW/settings#permission-rule-syntax) 以了解模式匹配。若要限制可用的工具，請改用 `--tools` | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

67| `--append-subagent-system-prompt` | {/* min-version: 2.1.205 */}將自訂文字附加到每個 [subagent](/zh-TW/sub-agents) 系統提示的末尾，包括巢狀 subagents。僅適用於使用 `-p` 的非互動模式。需要 Claude Code v2.1.205 或更新版本 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |67| `--append-subagent-system-prompt` | 將自訂文字附加到每個 [subagent](/docs/zh-TW/sub-agents) 系統提示的末尾，包括巢狀 subagents。僅適用於使用 `-p` 的非互動模式。需要 Claude Code v2.1.205 或更新版本 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |

70| `--ax-screen-reader` | {/* min-version: 2.1.181 */}呈現螢幕閱讀器友善的輸出：平面文字，無裝飾邊框或動畫。強制使用經典渲染器，因此 [`tui`](/zh-TW/settings#available-settings) 設定在工作階段中無效；附加的 [background sessions](/zh-TW/agent-view) 仍會全螢幕呈現。優先於 [`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 和 [`axScreenReader`](/zh-TW/settings#available-settings) 設定。需要 Claude Code v2.1.181 或更新版本 | `claude --ax-screen-reader` |70| `--ax-screen-reader` | 呈現螢幕閱讀器友善的輸出：平面文字，無裝飾邊框或動畫。強制使用經典渲染器，因此 [`tui`](/docs/zh-TW/settings#available-settings) 設定在工作階段中無效；附加的 [background sessions](/docs/zh-TW/agent-view) 仍會全螢幕呈現。優先於 [`CLAUDE_AX_SCREEN_READER`](/docs/zh-TW/env-vars) 和 [`axScreenReader`](/docs/zh-TW/settings#available-settings) 設定。需要 Claude Code v2.1.181 或更新版本 | `claude --ax-screen-reader` |

71| `--bare` | 最小模式：跳過 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索，以便指令碼呼叫啟動更快。Claude 可以存取 Bash、檔案讀取和檔案編輯工具。設定 [`CLAUDE_CODE_SIMPLE`](/zh-TW/env-vars)。請參閱 [bare mode](/zh-TW/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |71| `--bare` | 最小模式：跳過 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索，以便指令碼呼叫啟動更快。Claude 可以存取 Bash、檔案讀取和檔案編輯工具。設定 [`CLAUDE_CODE_SIMPLE`](/docs/zh-TW/env-vars)。請參閱 [bare mode](/docs/zh-TW/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |

73| `--bg`、`--background` | 以 [background agent](/zh-TW/agent-view) 身份啟動工作階段並立即返回。列印工作階段 ID 和管理命令。與 `--exec` 結合以執行 shell 命令作為背景工作而不是 Claude 工作階段，或與 `--agent` 結合以執行特定 subagent。{/* min-version: 2.1.198 */}無法與 `-p`/`--print` 結合；請參閱 [error reference](/zh-TW/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |73| `--bg`、`--background` | 以 [background agent](/docs/zh-TW/agent-view) 身份啟動工作階段並立即返回。列印工作階段 ID 和管理命令。與 `--exec` 結合以執行 shell 命令作為背景工作而不是 Claude 工作階段，或與 `--agent` 結合以執行特定 subagent。無法與 `-p`/`--print` 結合；請參閱 [error reference](/docs/zh-TW/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

74| `--channels` | （研究預覽）MCP 伺服器，其 [channel](/zh-TW/channels) 通知 Claude 應在此工作階段中監聽。以空格分隔的 `plugin:<name>@<marketplace>` 項目清單。需要 Claude.ai 驗證 | `claude --channels plugin:my-notifier@my-marketplace` |74| `--channels` | （研究預覽）MCP 伺服器，其 [channel](/docs/zh-TW/channels) 通知 Claude 應在此工作階段中監聽。以空格分隔的 `plugin:<name>@<marketplace>` 項目清單。需要 Claude.ai 驗證 | `claude --channels plugin:my-notifier@my-marketplace` |

78| `--dangerously-load-development-channels` | 啟用不在核准允許清單上的 [channels](/zh-TW/channels-reference#test-during-the-research-preview)，用於本機開發。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 項目。提示確認 | `claude --dangerously-load-development-channels server:webhook` |78| `--dangerously-load-development-channels` | 啟用不在核准允許清單上的 [channels](/docs/zh-TW/channels-reference#test-during-the-research-preview)，用於本機開發。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 項目。提示確認 | `claude --dangerously-load-development-channels server:webhook` |

79| `--dangerously-skip-permissions` | 略過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) 以了解此操作會和不會略過的內容。對於以 `--bg` 啟動的工作階段，該模式 [在監督者重新啟動工作階段時持續](/zh-TW/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |79| `--dangerously-skip-permissions` | 略過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱 [permission modes](/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` |

83| `--disallowedTools`、`--disallowed-tools` | 拒絕規則。裸工具名稱會從模型的內容中移除該工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)` ）會保留工具可用，但只拒絕符合的呼叫 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |83| `--disallowedTools`、`--disallowed-tools` | 拒絕規則。裸工具名稱會從模型的內容中移除該工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)` ）會保留工具可用，但只拒絕符合的呼叫 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

84| `--effort` | 為目前工作階段設定 [effort level](/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max` 或 {/* min-version: 2.1.203 */}}`ultracode`。可用的層級取決於模型。`ultracode` 以 `xhigh` 努力開始工作階段，並啟用 [ultracode](/zh-TW/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更新版本。覆蓋此工作階段的 [`effortLevel`](/zh-TW/settings#available-settings) 設定，且不會持久化 | `claude --effort high` |84| `--effort` | 為目前工作階段設定 [effort level](/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 或更新版本。覆蓋此工作階段的 [`effortLevel`](/docs/zh-TW/settings#available-settings) 設定，且不會持久化 | `claude --effort high` |

85| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 現在預設在 `Shift+Tab` 循環中；使用 `--permission-mode auto` 以它開始 | `claude --permission-mode auto` |85| `--enable-auto-mode` | 在 v2.1.111 中移除。Auto mode 現在預設在 `Shift+Tab` 循環中；使用 `--permission-mode auto` 以它開始 | `claude --permission-mode auto` |

86| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git 狀態旗標）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |86| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git 狀態旗標）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

88| `--fallback-model` | 當主要模型過載或無法使用時啟用自動回退到指定的模型，例如已淘汰的模型。接受以逗號分隔的清單，依序嘗試。請參閱 [Fallback model chains](/zh-TW/model-config#fallback-model-chains)。若要在工作階段之間持久化鏈，請使用 [`fallbackModel` 設定](/zh-TW/settings#available-settings)，此旗標會覆蓋它 | `claude --fallback-model sonnet,haiku` |88| `--fallback-model` | 當主要模型過載或無法使用時啟用自動回退到指定的模型，例如已淘汰的模型。接受以逗號分隔的清單，依序嘗試。請參閱 [Fallback model chains](/docs/zh-TW/model-config#fallback-model-chains)。若要在工作階段之間持久化鏈，請使用 [`fallbackModel` 設定](/docs/zh-TW/settings#available-settings)，此旗標會覆蓋它 | `claude --fallback-model sonnet,haiku` |

91| `--ide` | 如果恰好有一個有效的 IDE 可用，在啟動時自動連線到 IDE | `claude --ide` |91| `--ide` | 如果恰好有一個有效的 IDE 可用，在啟動時自動連線到 IDE | `claude --ide` |

94| `--include-hook-events` | 在輸出串流中包含所有 hook 生命週期事件。`SessionStart` 和 `Setup` hook 事件始終包含，不需要此旗標。需要 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |94| `--include-hook-events` | 在輸出串流中包含所有 hook 生命週期事件。`SessionStart` 和 `Setup` hook 事件始終包含，不需要此旗標。需要 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |

95| `--include-partial-messages` | 在輸出中包含部分串流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |95| `--include-partial-messages` | 在輸出中包含部分串流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |

97| `--json-schema` | 在代理程式完成其工作流程後取得符合 JSON Schema 的驗證 JSON 輸出（僅列印模式）。請參閱 [structured outputs](/zh-TW/agent-sdk/structured-outputs)。{/* min-version: 2.1.205 */}Claude Code 在無效的 schema 上以錯誤退出，並接受 `format` 關鍵字作為註解而不進行用戶端驗證。在 v2.1.205 之前，無效的 schema 產生無結構輸出且無錯誤，使用 `format` 的 schemas 被視為無效 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |97| `--json-schema` | 在代理程式完成其工作流程後取得符合 JSON Schema 的驗證 JSON 輸出（僅列印模式）。請參閱 [structured outputs](/docs/zh-TW/agent-sdk/structured-outputs)。Claude Code 在無效的 schema 上以錯誤退出，並接受 `format` 關鍵字作為註解而不進行用戶端驗證。在 v2.1.205 之前，無效的 schema 產生無結構輸出且無錯誤，使用 `format` 的 schemas 被視為無效 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

100| `--max-turns` | 限制代理程式轉數（僅列印模式）。達到限制時以錯誤退出。預設無限制。{/* min-version: 2.1.205 */}使用 `--input-format stream-json` 時，在 Claude 工作時傳送的訊息會保持佇列狀態，並在限制結束目前轉數時作為自己的轉數執行，具有自己的限制。在 v2.1.205 之前，Claude Code 丟棄該訊息 | `claude -p --max-turns 3 "query"` |100| `--max-turns` | 限制代理程式轉數（僅列印模式）。達到限制時以錯誤退出。預設無限制。使用 `--input-format stream-json` 時，在 Claude 工作時傳送的訊息會保持佇列狀態，並在限制結束目前轉數時作為自己的轉數執行，具有自己的限制。在 v2.1.205 之前，Claude Code 丟棄該訊息 | `claude -p --max-turns 3 "query"` |

102| `--model` | 使用最新模型的別名（`sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名稱為目前工作階段設定模型。覆蓋 [`model`](/zh-TW/settings#available-settings) 設定和 [`ANTHROPIC_MODEL`](/zh-TW/model-config#environment-variables) | `claude --model claude-sonnet-5` |102| `--model` | 使用最新模型的別名（`sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名稱為目前工作階段設定模型。覆蓋 [`model`](/docs/zh-TW/settings#available-settings) 設定和 [`ANTHROPIC_MODEL`](/docs/zh-TW/model-config#environment-variables) | `claude --model claude-sonnet-5` |

103| `--name`、`-n` | 為工作階段設定顯示名稱，顯示在 `/resume` 和終端標題中。您可以使用 `claude --resume <name>` 繼續已命名的工作階段。<br /><br />[`/rename`](/zh-TW/commands) 在工作階段中途變更名稱，也會在提示列中顯示 | `claude -n "my-feature-work"` |103| `--name`、`-n` | 為工作階段設定顯示名稱，顯示在 `/resume` 和終端標題中。您可以使用 `claude --resume <name>` 繼續已命名的工作階段。<br /><br />[`/rename`](/docs/zh-TW/commands) 在工作階段中途變更名稱，也會在提示列中顯示 | `claude -n "my-feature-work"` |

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

107| `--permission-mode` | 以指定的 [permission mode](/zh-TW/permission-modes) 開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 {/* min-version: 2.1.200 */}}`manual` 作為 `default` 的別名。`manual` 別名選擇 UI 標記為「手動」的模式，需要 Claude Code v2.1.200 或更新版本；`claude --help` 會列出它以取代 `default`，兩個值都有效。覆蓋設定檔案中的 `defaultMode` | `claude --permission-mode plan` |107| `--permission-mode` | 以指定的 [permission mode](/docs/zh-TW/permission-modes) 開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 }`manual` 作為 `default` 的別名。`manual` 別名選擇 UI 標記為「手動」的模式，需要 Claude Code v2.1.200 或更新版本；`claude --help` 會列出它以取代 `default`，兩個值都有效。覆蓋設定檔案中的 `defaultMode` | `claude --permission-mode plan` |

108| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式下處理權限提示。{/* min-version: 2.1.206 */}Claude Code 會等待該工具的 MCP 伺服器連線，最多等待 [`MCP_TIMEOUT`](/zh-TW/env-vars) 啟動逾時 30 秒，然後執行第一個轉數。在 v2.1.206 之前，啟動緩慢的伺服器可能會導致執行 [以找不到 MCP 工具的錯誤退出](/zh-TW/errors#mcp-permission-prompt-tool-not-found)。<br /><br />{/* min-version: 2.1.199 */}提示工具無法核准標記為 [requiring user interaction](/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"` |108| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式下處理權限提示。Claude Code 會等待該工具的 MCP 伺服器連線，最多等待 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時 30 秒，然後執行第一個轉數。在 v2.1.206 之前，啟動緩慢的伺服器可能會導致執行 [以找不到 MCP 工具的錯誤退出](/docs/zh-TW/errors#mcp-permission-prompt-tool-not-found)。<br /><br />提示工具無法核准標記為 [requiring user interaction](/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"` |

112| `--prompt-suggestions` | 在每個轉數後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |112| `--prompt-suggestions` | 在每個轉數後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱 [Prompt suggestions](/docs/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

114| `--remote-control`、`--rc` | 啟動互動式工作階段，並啟用 [Remote Control](/zh-TW/remote-control#start-a-remote-control-session)，以便您也可以從 claude.ai 或 Claude 應用程式控制它。可選擇傳遞工作階段的名稱 | `claude --remote-control "My Project"` |114| `--remote-control`、`--rc` | 啟動互動式工作階段，並啟用 [Remote Control](/docs/zh-TW/remote-control#start-a-remote-control-session)，以便您也可以從 claude.ai 或 Claude 應用程式控制它。可選擇傳遞工作階段的名稱 | `claude --remote-control "My Project"` |

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

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

117| `--resume`、`-r` | 按 ID 或名稱繼續特定工作階段，或顯示互動式選擇器以選擇工作階段。選擇器和名稱搜尋包括使用 `/add-dir` 新增此目錄的工作階段；傳遞工作階段 ID 只搜尋目前專案目錄及其 git worktrees。自 v2.1.144 起，[background sessions](/zh-TW/agent-view) 在選擇器中出現，標記為 `bg` | `claude --resume auth-refactor` |117| `--resume`、`-r` | 按 ID 或名稱繼續特定工作階段，或顯示互動式選擇器以選擇工作階段。選擇器和名稱搜尋包括使用 `/add-dir` 新增此目錄的工作階段；傳遞工作階段 ID 只搜尋目前專案目錄及其 git worktrees。自 v2.1.144 起，[background sessions](/docs/zh-TW/agent-view) 在選擇器中出現，標記為 `bg` | `claude --resume auth-refactor` |

118| `--safe-mode` | {/* min-version: 2.1.169 */}以所有自訂項目停用的狀態啟動以排除故障的設定：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理程式、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶體不會載入。驗證、模型選擇、內建工具和權限正常運作，這與 [`--bare`](/zh-TW/headless#start-faster-with-bare-mode) 不同。受管設定原則仍然適用，包括原則設定的 hooks、狀態列和檔案建議命令；受管 plugins、受管 skills、受管 CLAUDE.md 和原則設定的 MCP 伺服器不會。用於檢查自訂項目是否觸發 [automatic fallback from Fable 5](/zh-TW/model-config#automatic-model-fallback)。設定 [`CLAUDE_CODE_SAFE_MODE`](/zh-TW/env-vars) | `claude --safe-mode` |118| `--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 伺服器不會。用於檢查自訂項目是否觸發 [automatic fallback from Fable 5](/docs/zh-TW/model-config#automatic-model-fallback)。設定 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-TW/env-vars) | `claude --safe-mode` |

121| `--settings` | 設定 JSON 檔案的路徑或內嵌 JSON 字串。您在此設定的值會覆蓋此工作階段中 `settings.json` 檔案中的相同金鑰。您省略的金鑰保留其檔案型值。請參閱 [settings precedence](/zh-TW/settings#settings-precedence) | `claude --settings ./settings.json` |121| `--settings` | 設定 JSON 檔案的路徑或內嵌 JSON 字串。您在此設定的值會覆蓋此工作階段中 `settings.json` 檔案中的相同金鑰。您省略的金鑰保留其檔案型值。請參閱 [settings precedence](/docs/zh-TW/settings#settings-precedence) | `claude --settings ./settings.json` |

126| `--teammate-mode` | 設定 [agent team](/zh-TW/agent-teams) 隊友的顯示方式：`in-process`（預設）、`auto`、`tmux` 或 {/* min-version: 2.1.186 */}}`iterm2`（在 v2.1.186 中新增）。預設在 v2.1.179 中從 `auto` 變更。覆蓋此工作階段的 [`teammateMode`](/zh-TW/settings#available-settings) 設定。請參閱 [選擇顯示模式](/zh-TW/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |126| `--teammate-mode` | 設定 [agent team](/docs/zh-TW/agent-teams) 隊友的顯示方式：`in-process`（預設）、`auto`、`tmux` 或 }`iterm2`（在 v2.1.186 中新增）。預設在 v2.1.179 中從 `auto` 變更。覆蓋此工作階段的 [`teammateMode`](/docs/zh-TW/settings#available-settings) 設定。請參閱 [選擇顯示模式](/docs/zh-TW/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |

128| `--tools` | 限制 Claude 可以使用的內建工具。使用 `""` 停用全部、`"default"` 為全部，或工具名稱如 `"Bash,Edit,Read"`。MCP 工具不受影響；若要拒絕這些工具，請改用 `--disallowedTools "mcp__*"`，或傳遞 `--strict-mcp-config` 而不使用 `--mcp-config` 以便不載入 MCP 伺服器 | `claude --tools "Bash,Edit,Read"` |128| `--tools` | 限制 Claude 可以使用的內建工具。使用 `""` 停用全部、`"default"` 為全部，或工具名稱如 `"Bash,Edit,Read"`。MCP 工具不受影響；若要拒絕這些工具，請改用 `--disallowedTools "mcp__*"`，或傳遞 `--strict-mcp-config` 而不使用 `--mcp-config` 以便不載入 MCP 伺服器 | `claude --tools "Bash,Edit,Read"` |

131| `--worktree`、`-w` | 在隔離的 [git worktree](/zh-TW/worktrees) 中啟動 Claude，位於 `<repo>/.claude/worktrees/<name>`。如果未提供名稱，則會自動產生一個。傳遞 `#<number>` 或 GitHub 提取請求 URL 以從 `origin` 擷取該 PR 並從它分支 worktree | `claude -w feature-auth` |131| `--worktree`、`-w` | 在隔離的 [git worktree](/docs/zh-TW/worktrees) 中啟動 Claude，位於 `<repo>/.claude/worktrees/<name>`。如果未提供名稱，則會自動產生一個。傳遞 `#<number>` 或 GitHub 提取請求 URL 以從 `origin` 擷取該 PR 並從它分支 worktree | `claude -w feature-auth` |

132 132

133<h3 id="system-prompt-flags">133<h3 id="system-prompt-flags">

134 系統提示旗標134 系統提示旗標

147 147

148根據 Claude Code 的預設身份是否仍適合您的工作來選擇。當 Claude 應保持編碼助手身份並同時遵循您的額外規則時，請使用附加旗標：每次呼叫的指示、輸出格式或 `-p` 指令碼的領域內容。附加會保留預設工具指導、安全指示和編碼慣例，因此您只需提供不同的部分。當表面、身份或權限模型與 Claude Code 不同時，請使用取代旗標，例如管道中沒有人監看的非編碼代理程式。取代會移除整個預設提示，包括工具指導和安全指示，因此您需要負責您的工作仍然需要的任何內容。148根據 Claude Code 的預設身份是否仍適合您的工作來選擇。當 Claude 應保持編碼助手身份並同時遵循您的額外規則時，請使用附加旗標：每次呼叫的指示、輸出格式或 `-p` 指令碼的領域內容。附加會保留預設工具指導、安全指示和編碼慣例，因此您只需提供不同的部分。當表面、身份或權限模型與 Claude Code 不同時，請使用取代旗標，例如管道中沒有人監看的非編碼代理程式。取代會移除整個預設提示，包括工具指導和安全指示，因此您需要負責您的工作仍然需要的任何內容。

149 149

150這些旗標僅適用於目前的呼叫。對於您可以在專案中切換和共享的持久人物，請使用 [output styles](/zh-TW/output-styles)。對於 Claude 應始終遵循的專案慣例，請使用 [CLAUDE.md](/zh-TW/memory)。[Agent SDK 系統提示指南](/zh-TW/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) 涵蓋了更深入的相同決策。150這些旗標僅適用於目前的呼叫。對於您可以在專案中切換和共享的持久人物，請使用 [output styles](/docs/zh-TW/output-styles)。對於 Claude 應始終遵循的專案慣例，請使用 [CLAUDE.md](/docs/zh-TW/memory)。[Agent SDK 系統提示指南](/docs/zh-TW/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) 涵蓋了更深入的相同決策。

151 151

152<h2 id="see-also">152<h2 id="see-also">

153 另請參閱153 另請參閱

154</h2>154</h2>

155 155

156* [Chrome 擴充功能](/zh-TW/chrome) - 瀏覽器自動化和網頁測試156* [Chrome 擴充功能](/docs/zh-TW/chrome) - 瀏覽器自動化和網頁測試

157* [互動模式](/zh-TW/interactive-mode) - 快捷鍵、輸入模式和互動功能157* [互動模式](/docs/zh-TW/interactive-mode) - 快捷鍵、輸入模式和互動功能

158* [快速入門指南](/zh-TW/quickstart) - Claude Code 入門158* [快速入門指南](/docs/zh-TW/quickstart) - Claude Code 入門

159* [常見工作流程](/zh-TW/common-workflows) - 進階工作流程和模式159* [常見工作流程](/docs/zh-TW/common-workflows) - 進階工作流程和模式

160* [設定](/zh-TW/settings) - 設定選項160* [設定](/docs/zh-TW/settings) - 設定選項

161* [Agent SDK 文件](/zh-TW/agent-sdk/overview) - 程式化使用和整合161* [Agent SDK 文件](/docs/zh-TW/agent-sdk/overview) - 程式化使用和整合

code-review.md +14 −14

Details

7> 設定自動化 PR 審查，使用多代理分析您的完整程式碼庫來捕捉邏輯錯誤、安全漏洞和迴歸7> 設定自動化 PR 審查，使用多代理分析您的完整程式碼庫來捕捉邏輯錯誤、安全漏洞和迴歸

8 8

9<Note>9<Note>

10 Code Review 處於研究預覽階段，適用於 [Team 和 Enterprise](https://claude.ai/admin-settings/claude-code) 訂閱。對於啟用了 [Zero Data Retention](/zh-TW/zero-data-retention) 的組織，此功能不可用。10 Code Review 處於研究預覽階段，適用於 [Team 和 Enterprise](https://claude.ai/admin-settings/claude-code) 訂閱。對於啟用了 [Zero Data Retention](/docs/zh-TW/zero-data-retention) 的組織，此功能不可用。

11</Note>11</Note>

12 12

13Code Review 分析您的 GitHub pull request，並在發現問題的程式碼行上發佈內聯評論。一群專門的代理在您完整程式碼庫的背景下檢查程式碼變更，尋找邏輯錯誤、安全漏洞、破損的邊界情況和細微的迴歸。13Code Review 分析您的 GitHub pull request，並在發現問題的程式碼行上發佈內聯評論。一群專門的代理在您完整程式碼庫的背景下檢查程式碼變更，尋找邏輯錯誤、安全漏洞、破損的邊界情況和細微的迴歸。

14 14

15發現結果按嚴重程度標記，不會批准或阻止您的 PR，因此現有的審查工作流程保持不變。您可以通過在存儲庫中添加 `CLAUDE.md` 或 `REVIEW.md` 文件來調整 Claude 標記的內容。15發現結果按嚴重程度標記，不會批准或阻止您的 PR，因此現有的審查工作流程保持不變。您可以通過在存儲庫中添加 `CLAUDE.md` 或 `REVIEW.md` 文件來調整 Claude 標記的內容。

16 16

17要在您自己的 CI 基礎設施中運行 Claude 而不是此託管服務，請參閱 [GitHub Actions](/zh-TW/github-actions) 或 [GitLab CI/CD](/zh-TW/gitlab-ci-cd)。對於自託管 GitHub 實例上的存儲庫，請參閱 [GitHub Enterprise Server](/zh-TW/github-enterprise-server)。17要在您自己的 CI 基礎設施中運行 Claude 而不是此託管服務，請參閱 [GitHub Actions](/docs/zh-TW/github-actions) 或 [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)。對於自託管 GitHub 實例上的存儲庫，請參閱 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server)。

18 18

19本頁涵蓋：19本頁涵蓋：

20 20

112 * **Issues**：讀取和寫入112 * **Issues**：讀取和寫入

113 * **Pull requests**：讀取和寫入113 * **Pull requests**：讀取和寫入

114 114

115 Code Review 使用對內容的讀取存取權限和對 pull request 的寫入存取權限。更廣泛的權限集也支持 [GitHub Actions](/zh-TW/github-actions)，如果您稍後啟用它。115 Code Review 使用對內容的讀取存取權限和對 pull request 的寫入存取權限。更廣泛的權限集也支持 [GitHub Actions](/docs/zh-TW/github-actions)，如果您稍後啟用它。

116 </Step>116 </Step>

117 117

118 <Step title="選擇存儲庫">118 <Step title="選擇存儲庫">

173 173

174Code Review 讀取您存儲庫的 `CLAUDE.md` 文件，並將新引入的違規視為 [細節級別](#severity-levels) 的發現。這是雙向工作的：如果您的 PR 以使 `CLAUDE.md` 陳述過時的方式更改程式碼，Claude 會標記文件需要更新。174Code Review 讀取您存儲庫的 `CLAUDE.md` 文件，並將新引入的違規視為 [細節級別](#severity-levels) 的發現。這是雙向工作的：如果您的 PR 以使 `CLAUDE.md` 陳述過時的方式更改程式碼，Claude 會標記文件需要更新。

175 175

176Claude 在目錄層次結構的每個級別讀取 `CLAUDE.md` 文件，因此子目錄的 `CLAUDE.md` 中的規則僅適用於該路徑下的文件。有關 `CLAUDE.md` 如何運作的更多信息，請參閱 [memory 文檔](/zh-TW/memory)。176Claude 在目錄層次結構的每個級別讀取 `CLAUDE.md` 文件，因此子目錄的 `CLAUDE.md` 中的規則僅適用於該路徑下的文件。有關 `CLAUDE.md` 如何運作的更多信息，請參閱 [memory 文檔](/docs/zh-TW/memory)。

177 177

178對於您不想應用於一般 Claude Code 會話的審查特定指導，請改用 [`REVIEW.md`](#review-md)。178對於您不想應用於一般 Claude Code 會話的審查特定指導，請改用 [`REVIEW.md`](#review-md)。

179 179

183 183

184`REVIEW.md` 是位於您存儲庫根目錄的文件，它覆蓋 Code Review 在您的存儲庫上的行為方式。其內容被注入到審查管道中每個代理的系統提示中作為最高優先級指令塊，優先於默認審查指導。184`REVIEW.md` 是位於您存儲庫根目錄的文件，它覆蓋 Code Review 在您的存儲庫上的行為方式。其內容被注入到審查管道中每個代理的系統提示中作為最高優先級指令塊，優先於默認審查指導。

185 185

186因為它是逐字粘貼的，`REVIEW.md` 是純指令：[`@` 導入語法](/zh-TW/memory#import-additional-files) 不會展開，引用的文件不會讀入提示中。將您想要強制執行的規則直接放在文件中。186因為它是逐字粘貼的，`REVIEW.md` 是純指令：[`@` 導入語法](/docs/zh-TW/memory#import-additional-files) 不會展開，引用的文件不會讀入提示中。將您想要強制執行的規則直接放在文件中。

187 187

188<h4 id="what-you-can-tune">188<h4 id="what-you-can-tune">

189 您可以調整什麼189 您可以調整什麼

310 在本地審查差異310 在本地審查差異

311</h2>311</h2>

312 312

313[`/code-review` 命令](/zh-TW/commands)在您的終端中審查差異，無需安裝 GitHub App。在任何 Claude Code 工作階段中運行它：它報告正確性錯誤和 {/* min-version: 2.1.151 */}重用、簡化和效率清理。預設情況下，本地審查涵蓋您分支相對於其上游的提交，加上工作樹中的任何未提交變更。傳遞 `--comment` 以將發現結果作為內聯 PR 評論發佈，或傳遞 `--fix` 以在審查後將發現結果應用到您的工作樹。313[`/code-review` 命令](/docs/zh-TW/commands)在您的終端中審查差異，無需安裝 GitHub App。在任何 Claude Code 工作階段中運行它：它報告正確性錯誤和重用、簡化和效率清理。預設情況下，本地審查涵蓋您分支相對於其上游的提交，加上工作樹中的任何未提交變更。傳遞 `--comment` 以將發現結果作為內聯 PR 評論發佈，或傳遞 `--fix` 以在審查後將發現結果應用到您的工作樹。

314 314

315較低的[努力級別](/zh-TW/model-config#adjust-effort-level)返回較少、更高信心的發現，而 `high` 到 `max` 提供更廣泛的覆蓋範圍，可能包括不確定的發現。沒有努力參數時，審查使用工作階段的當前努力。若要審查預設差異以外的內容，請傳遞目標：檔案路徑、PR 編號、分支名稱或參考範圍，例如 `main...my-feature`。參考範圍形式審查從 `my-feature` 到 `main` 的提取請求將包含的已提交差異，無論分支的上游如何配置。315較低的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)返回較少、更高信心的發現，而 `high` 到 `max` 提供更廣泛的覆蓋範圍，可能包括不確定的發現。沒有努力參數時，審查使用工作階段的當前努力。若要審查預設差異以外的內容，請傳遞目標：檔案路徑、PR 編號、分支名稱或參考範圍，例如 `main...my-feature`。參考範圍形式審查從 `my-feature` 到 `main` 的提取請求將包含的已提交差異，無論分支的上游如何配置。

316 316

317`/code-review ultra --fix` 在雲中運行更深入的 [ultrareview](/zh-TW/ultrareview)，然後在它們到達您的工作階段時將其發現結果應用到您的工作樹。Ultrareview 使用其自己的範圍：您的當前分支相對於儲存庫的預設分支，加上工作樹中的任何未提交和已暫存變更。317`/code-review ultra --fix` 在雲中運行更深入的 [ultrareview](/docs/zh-TW/ultrareview)，然後在它們到達您的工作階段時將其發現結果應用到您的工作樹。Ultrareview 使用其自己的範圍：您的當前分支相對於儲存庫的預設分支，加上工作樹中的任何未提交和已暫存變更。

318 318

319該命令在 v2.1.147 之前被命名為 `/simplify`，當時它預設應用修復。{/* min-version: 2.1.154 */}從 v2.1.154 開始，`/simplify` 運行單獨的僅清理審查，該審查應用修復而不尋找錯誤。如果您編寫了 `/simplify` 用於尋找錯誤，請切換到 `/code-review --fix`，它保持不變。319該命令在 v2.1.147 之前被命名為 `/simplify`，當時它預設應用修復。從 v2.1.154 開始，`/simplify` 運行單獨的僅清理審查，該審查應用修復而不尋找錯誤。如果您編寫了 `/simplify` 用於尋找錯誤，請切換到 `/code-review --fix`，它保持不變。

320 320

321<h2 id="related-resources">321<h2 id="related-resources">

322 相關資源322 相關資源

324 324

325Code Review 設計用於與 Claude Code 的其餘部分一起工作。如果您想在開啟 PR 之前在本地運行審查、需要自託管設定，或想深入了解 `CLAUDE.md` 如何在工具中塑造 Claude 的行為，這些頁面是很好的下一步：325Code Review 設計用於與 Claude Code 的其餘部分一起工作。如果您想在開啟 PR 之前在本地運行審查、需要自託管設定，或想深入了解 `CLAUDE.md` 如何在工具中塑造 Claude 的行為，這些頁面是很好的下一步：

326 326

327* [Commands](/zh-TW/commands)：在本地 Claude Code 工作階段中運行 `/code-review` 以在推送前檢查差異327* [Commands](/docs/zh-TW/commands)：在本地 Claude Code 工作階段中運行 `/code-review` 以在推送前檢查差異

328* [GitHub Actions](/zh-TW/github-actions)：在您自己的 GitHub Actions 工作流中運行 Claude，以實現超越程式碼審查的自訂自動化328* [GitHub Actions](/docs/zh-TW/github-actions)：在您自己的 GitHub Actions 工作流中運行 Claude，以實現超越程式碼審查的自訂自動化

329* [GitLab CI/CD](/zh-TW/gitlab-ci-cd)：GitLab 管道的自託管 Claude 集成329* [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)：GitLab 管道的自託管 Claude 集成

330* [Memory](/zh-TW/memory)：`CLAUDE.md` 文件如何在 Claude Code 中工作330* [Memory](/docs/zh-TW/memory)：`CLAUDE.md` 文件如何在 Claude Code 中工作

331* [Analytics](/zh-TW/analytics)：追蹤超越程式碼審查的 Claude Code 使用情況331* [Analytics](/docs/zh-TW/analytics)：追蹤超越程式碼審查的 Claude Code 使用情況

commands.md +31 −31

Details

10 10

11輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟字母以篩選。11輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟字母以篩選。

12 12

13命令只有在您的訊息開始時才會被識別。命令名稱後面的文字會作為引數傳遞給它。{/* min-version: 2.1.199 */}自 v2.1.199 起，[skills](/docs/zh-TW/skills#pass-arguments-to-skills) 是例外：skill 調用後跟更多 skills，例如 `/skill-a /skill-b do XYZ`，會載入開始時命名的每個 skill，並將尾部文字作為引數傳遞給每個 skill。最多可以鏈接六個 skills。13命令只有在您的訊息開始時才會被識別。命令名稱後面的文字會作為引數傳遞給它。自 v2.1.199 起，[skills](/docs/zh-TW/skills#pass-arguments-to-skills) 是例外：skill 調用後跟更多 skills，例如 `/skill-a /skill-b do XYZ`，會載入開始時命名的每個 skill，並將尾部文字作為引數傳遞給每個 skill。最多可以鏈接六個 skills。

14 14

15如果您在 Claude 正在回應時發送命令，它會排隊並在目前回合完成後執行。某些命令，例如 `/status`、`/tasks` 和 `/usage`，會立即執行而不會中斷回應。15如果您在 Claude 正在回應時發送命令，它會排隊並在目前回合完成後執行。某些命令，例如 `/status`、`/tasks` 和 `/usage`，會立即執行而不會中斷回應。

16 16

50</Note>50</Note>

51 51

52| 命令 | 用途 |52| 命令 | 用途 |

53| :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |53| :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

54| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。輸入部分路徑會顯示匹配的目錄建議；按 `Tab` 以接受一個。大多數 `.claude/` 配置[未從添加的目錄發現](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |54| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。輸入部分路徑會顯示匹配的目錄建議；按 `Tab` 以接受一個。大多數 `.claude/` 配置[未從添加的目錄發現](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |

55| `/advisor [model\|off]` | 啟用或停用[顧問工具](/docs/zh-TW/advisor)，它在工作期間的關鍵時刻諮詢第二個模型以獲得指導。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整的模型 ID。不帶引數時，開啟選擇器 |55| `/advisor [model\|off]` | 啟用或停用[顧問工具](/docs/zh-TW/advisor)，它在工作期間的關鍵時刻諮詢第二個模型以獲得指導。接受 `opus`、`sonnet`、`fable`（v2.1.170+）或完整的模型 ID。不帶引數時，開啟選擇器 |

56| `/agents` | {/* min-version: 2.1.198 */}自 v2.1.198 起，執行 `/agents` 會列印提醒，要求您詢問 Claude 以建立或管理 [subagents](/docs/zh-TW/sub-agents)，或直接編輯 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本上，開啟互動式介面以建立和管理 subagent 配置 |56| `/agents` | 自 v2.1.198 起，執行 `/agents` 會列印提醒，要求您詢問 Claude 以建立或管理 [subagents](/docs/zh-TW/sub-agents)，或直接編輯 `.claude/agents/` 或 `~/.claude/agents/`。在 v2.1.197 及更早版本上，開啟互動式介面以建立和管理 subagent 配置 |

57| `/autofix-pr [prompt]` | 生成一個[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests) 工作階段，監視目前分支的 PR 並在 CI 失敗或審閱者留下評論時推送修復。使用 `gh pr view` 檢測已簽出分支的開放 PR；若要監視不同的 PR，請先簽出其分支。預設情況下，遠端工作階段被告知修復每個 CI 失敗和審閱評論；傳遞提示以給予它不同的指示，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和訪問[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) |57| `/autofix-pr [prompt]` | 生成一個[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests) 工作階段，監視目前分支的 PR 並在 CI 失敗或審閱者留下評論時推送修復。使用 `gh pr view` 檢測已簽出分支的開放 PR；若要監視不同的 PR，請先簽出其分支。預設情況下，遠端工作階段被告知修復每個 CI 失敗和審閱評論；傳遞提示以給予它不同的指示，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和訪問[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) |

58| `/background [prompt]` | 分離目前的工作階段以作為[背景 agent](/docs/zh-TW/agent-view) 運行並釋放此終端機。傳遞提示以在分離前發送一個額外的指示。使用 `claude agents` 監視工作階段。別名：`/bg` |58| `/background [prompt]` | 分離目前的工作階段以作為[背景 agent](/docs/zh-TW/agent-view) 運行並釋放此終端機。傳遞提示以在分離前發送一個額外的指示。使用 `claude agents` 監視工作階段。別名：`/bg` |

59| `/batch <instruction>` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 在整個程式碼庫中並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計劃。獲得批准後，在隔離的 [git worktree](/docs/zh-TW/worktrees) 中為每個單位生成一個背景 subagent。每個 subagent 實現其單位、運行測試並開啟 pull request。需要 git 存放庫。示例：`/batch migrate src/ from Solid to React` |59| `/batch <instruction>` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 在整個程式碼庫中並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計劃。獲得批准後，在隔離的 [git worktree](/docs/zh-TW/worktrees) 中為每個單位生成一個背景 subagent。每個 subagent 實現其單位、運行測試並開啟 pull request。需要 git 存放庫。示例：`/batch migrate src/ from Solid to React` |

60| `/branch [name]` | 在此時刻建立目前對話的分支，以便您可以嘗試不同的方向而不會失去目前的對話。切換到分支並保留原始分支，您可以使用 `/resume` 返回。若要將側邊工作交給背景 subagent 而不是自己切換到副本，請使用 `/fork` |60| `/branch [name]` | 在此時刻建立目前對話的分支，以便您可以嘗試不同的方向而不會失去目前的對話。切換到分支並保留原始分支，您可以使用 `/resume` 返回。若要將側邊工作交給背景 subagent 而不是自己切換到副本，請使用 `/fork` |

62| `/cd <path>` | {/* min-version: 2.1.169 */}將此工作階段移動到新的工作目錄。對話的提示快取被保留：新目錄的 [`CLAUDE.md`](/docs/zh-TW/memory) 被附加為訊息，而不是重建系統提示。工作階段被重新定位到新目錄的專案儲存，因此 `--resume` 和 `--continue` 從那裡找到它。如果您之前未在該目錄中工作過，會提示您信任該目錄。{/* min-version: 2.1.206 */}輸入部分路徑會顯示匹配的目錄建議；按 `Tab` 以接受一個。建議需要 Claude Code v2.1.206 或更新版本。若要授予對額外目錄的存取權而不移動工作階段，請使用 `/add-dir`。使用 [`Cd` 權限規則](/docs/zh-TW/permissions#cd)限制或停用 `/cd` 目標。需要 Claude Code v2.1.169 或更新版本；較早的版本報告 `Unknown command: /cd` |62| `/cd <path>` | 將此工作階段移動到新的工作目錄。對話的提示快取被保留：新目錄的 [`CLAUDE.md`](/docs/zh-TW/memory) 被附加為訊息，而不是重建系統提示。工作階段被重新定位到新目錄的專案儲存，因此 `--resume` 和 `--continue` 從那裡找到它。如果您之前未在該目錄中工作過，會提示您信任該目錄。輸入部分路徑會顯示匹配的目錄建議；按 `Tab` 以接受一個。建議需要 Claude Code v2.1.206 或更新版本。若要授予對額外目錄的存取權而不移動工作階段，請使用 `/add-dir`。使用 [`Cd` 權限規則](/docs/zh-TW/permissions#cd)限制或停用 `/cd` 目標。需要 Claude Code v2.1.169 或更新版本；較早的版本報告 `Unknown command: /cd` |

64| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |64| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |

65| `/clear [name]` | 使用空上下文開始新對話。傳遞名稱以在 `/resume` 選擇器中標記上一個對話。若要在繼續同一對話時釋放上下文，請改用 `/compact`。使用 `/resume` 繼續上一個對話，或在同一個 Claude Code 程序中，{/* min-version: 2.1.191 */}從[倒帶選單的上一個工作階段項目](/docs/zh-TW/checkpointing#rewind-past-a-cleared-conversation)恢復它。別名：`/reset`、`/new` |65| `/clear [name]` | 使用空上下文開始新對話。傳遞名稱以在 `/resume` 選擇器中標記上一個對話。若要在繼續同一對話時釋放上下文，請改用 `/compact`。使用 `/resume` 繼續上一個對話，或在同一個 Claude Code 程序中，從[倒帶選單的上一個工作階段項目](/docs/zh-TW/checkpointing#rewind-past-a-cleared-conversation)恢復它。別名：`/reset`、`/new` |

66| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 審閱目前的差異以查找正確性錯誤並進行重用、簡化和效率清理。傳遞 `--fix` 以將發現應用到您的工作樹，傳遞 `--comment` 以將其作為內聯 GitHub PR 評論發佈，或傳遞 `ultra` 以運行深度[雲端審閱](/docs/zh-TW/ultrareview)。{/* min-version: 2.1.154 */}從 v2.1.154 開始，`/simplify` 運行單獨的僅清理審閱，應用修復而不尋找錯誤。請參閱[本地審閱差異](/docs/zh-TW/code-review#review-a-diff-locally)以了解努力程度和目標設定 |66| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 審閱目前的差異以查找正確性錯誤並進行重用、簡化和效率清理。傳遞 `--fix` 以將發現應用到您的工作樹，傳遞 `--comment` 以將其作為內聯 GitHub PR 評論發佈，或傳遞 `ultra` 以運行深度[雲端審閱](/docs/zh-TW/ultrareview)。從 v2.1.154 開始，`/simplify` 運行單獨的僅清理審閱，應用修復而不尋找錯誤。請參閱[本地審閱差異](/docs/zh-TW/code-review#review-a-diff-locally)以了解努力程度和目標設定 |

67| `/color [color\|default]` | 設定目前工作階段的提示列顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重設，或不帶引數執行以選擇隨機顏色。當[遠端控制](/docs/zh-TW/remote-control)已連接時，顏色會同步到 claude.ai/code。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用；需要 Claude Code v2.1.205 或更新版本 |67| `/color [color\|default]` | 設定目前工作階段的提示列顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重設，或不帶引數執行以選擇隨機顏色。當[遠端控制](/docs/zh-TW/remote-control)已連接時，顏色會同步到 claude.ai/code。也可在非互動模式（`-p`）中使用；需要 Claude Code v2.1.205 或更新版本 |

68| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選擇性地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、skills 和記憶體檔案](/docs/zh-TW/context-window#what-survives-compaction) |68| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選擇性地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、skills 和記憶體檔案](/docs/zh-TW/context-window#what-survives-compaction) |

69| `/config [key=value ...]` | 開啟[設定](/docs/zh-TW/settings)介面以調整主題、模型、[輸出樣式](/docs/zh-TW/output-styles)和其他偏好設定。{/* min-version: 2.1.181 */}從 v2.1.181 開始，傳遞一個或多個 `key=value` 對以直接設定設定，無需開啟介面，例如 `/config thinking=false`。{/* min-version: 2.1.182 */}從 v2.1.182 開始，也接受命名的簡寫鍵，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也適用於非互動模式（`-p`）和[遠端控制](/docs/zh-TW/remote-control)。執行 `/config --help` 以列出每個可設定的鍵及其選項。別名：`/settings` |69| `/config [key=value ...]` | 開啟[設定](/docs/zh-TW/settings)介面以調整主題、模型、[輸出樣式](/docs/zh-TW/output-styles)和其他偏好設定。從 v2.1.181 開始，傳遞一個或多個 `key=value` 對以直接設定設定，無需開啟介面，例如 `/config thinking=false`。從 v2.1.182 開始，也接受命名的簡寫鍵，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也適用於非互動模式（`-p`）和[遠端控制](/docs/zh-TW/remote-control)。執行 `/config --help` 以列出每個可設定的鍵及其選項。別名：`/settings` |

70| `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/docs/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |70| `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/docs/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |

71| `/copy [N]` | 將最後一個助手回應複製到剪貼簿。傳遞數字 `N` 以複製第 N 個最新回應：`/copy 2` 複製倒數第二個。當存在程式碼區塊時，顯示互動式選擇器以選擇個別區塊或完整回應。在選擇器中按 `w` 以將選擇寫入檔案而不是剪貼簿，這在 SSH 上很有用 |71| `/copy [N]` | 將最後一個助手回應複製到剪貼簿。傳遞數字 `N` 以複製第 N 個最新回應：`/copy 2` 複製倒數第二個。當存在程式碼區塊時，顯示互動式選擇器以選擇個別區塊或完整回應。在選擇器中按 `w` 以將選擇寫入檔案而不是剪貼簿，這在 SSH 上很有用 |

73| `/dataviz [request]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 圖表、圖形和儀表板的設計指導。Claude 為資料選擇圖表形式，按角色分配顏色，使用捆綁的指令碼驗證調色盤以確保色盲安全和對比度，並應用標記、互動和無障礙規則。使用品牌中立的佔位符調色盤，您可以用自己的調色盤替換。{/* min-version: 2.1.198 */}需要 Claude Code v2.1.198 或更新版本 |73| `/dataviz [request]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 圖表、圖形和儀表板的設計指導。Claude 為資料選擇圖表形式，按角色分配顏色，使用捆綁的指令碼驗證調色盤以確保色盲安全和對比度，並應用標記、互動和無障礙規則。使用品牌中立的佔位符調色盤，您可以用自己的調色盤替換。需要 Claude Code v2.1.198 或更新版本 |

74| `/debug [description]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 為目前工作階段啟用偵錯日誌記錄並通過讀取工作階段偵錯日誌來排除故障。除非您使用 `claude --debug` 啟動，否則偵錯日誌記錄預設為關閉，因此在工作階段中期運行 `/debug` 會從該時刻開始捕獲日誌。可選擇性地描述問題以集中分析 |74| `/debug [description]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 為目前工作階段啟用偵錯日誌記錄並通過讀取工作階段偵錯日誌來排除故障。除非您使用 `claude --debug` 啟動，否則偵錯日誌記錄預設為關閉，因此在工作階段中期運行 `/debug` 會從該時刻開始捕獲日誌。可選擇性地描述問題以集中分析 |

77| `/design-sync [hint]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 轉換您的存放庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它產生的設計使用您的真實元件。可選擇性地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型存放庫上可能需要幾個小時。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，基礎工具無法到達 claude.ai，因此命令不可用 |77| `/design-sync [hint]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 轉換您的存放庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它產生的設計使用您的真實元件。可選擇性地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型存放庫上可能需要幾個小時。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，基礎工具無法到達 claude.ai，因此命令不可用 |

79| `/diff` | 開啟互動式差異檢視器，顯示未提交的變更和每個回合的差異。使用左/右箭頭在目前的 git 差異和個別 Claude 回合之間切換，使用上/下箭頭瀏覽檔案。按 Enter 以開啟選定檔案的差異，使用上/下或 PageUp/PageDown 捲動它，按 Esc 返回檔案清單。{/* min-version: 2.1.198 */}自 v2.1.198 起，開啟的檢視器也會在存放庫的 git 狀態在工作階段外變更時自動重新整理，例如在另一個終端機中進行分支切換或提交 |79| `/diff` | 開啟互動式差異檢視器，顯示未提交的變更和每個回合的差異。使用左/右箭頭在目前的 git 差異和個別 Claude 回合之間切換，使用上/下箭頭瀏覽檔案。按 Enter 以開啟選定檔案的差異，使用上/下或 PageUp/PageDown 捲動它，按 Esc 返回檔案清單。自 v2.1.198 起，開啟的檢視器也會在存放庫的 git 狀態在工作階段外變更時自動重新整理，例如在另一個終端機中進行分支切換或提交 |

80| `/doctor` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 執行設定檢查以診斷問題並可以修復它們。檢查安裝健康狀況，包括重複或遺留的安裝、`PATH` 問題和無法解析的設定檔案。查找未使用的 skills、MCP 伺服器和 plugins 與其上下文成本，標記緩慢的 [hooks](/docs/zh-TW/hooks)，並檢查是否有更新版本在您的發行頻道上。對簽入的檔案進行本地 `CLAUDE.md` 檔案的重複資料刪除，通過削減 Claude 可以從程式碼庫衍生的內容來修剪簽入的 [`CLAUDE.md`](/docs/zh-TW/memory) 檔案，並將保留的始終載入的指導遷移到 [skills](/docs/zh-TW/skills) 和按需載入的嵌套 `CLAUDE.md` 檔案。修剪會削減目錄佈局、依賴清單和架構概述等部分，並保留與工具預設值不同的陷阱、基本原理和約定。也提供使 [auto mode](/docs/zh-TW/permissions#permission-modes) 成為您的預設值的選項，以及[預先批准](/docs/zh-TW/permissions)經常被拒絕的唯讀命令。首先報告發現並在變更任何內容之前要求確認。從終端機，`claude doctor` 列印唯讀安裝診斷而不啟動工作階段。別名：`/checkup`。{/* min-version: 2.1.206 */}`CLAUDE.md` 修剪檢查需要 Claude Code v2.1.206 或更新版本。在 v2.1.206 之前，版本檢查將 Homebrew 安裝與 `autoUpdatesChannel` 設定進行比較，而不是[已安裝的 cask 頻道](/docs/zh-TW/setup#configure-release-channel)。{/* min-version: 2.1.205 */}在 v2.1.205 之前，`/doctor` 開啟唯讀診斷螢幕，按 `f` 將報告發送給 Claude |80| `/doctor` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 執行設定檢查以診斷問題並可以修復它們。檢查安裝健康狀況，包括重複或遺留的安裝、`PATH` 問題和無法解析的設定檔案。查找未使用的 skills、MCP 伺服器和 plugins 與其上下文成本，標記緩慢的 [hooks](/docs/zh-TW/hooks)，並檢查是否有更新版本在您的發行頻道上。對簽入的檔案進行本地 `CLAUDE.md` 檔案的重複資料刪除，通過削減 Claude 可以從程式碼庫衍生的內容來修剪簽入的 [`CLAUDE.md`](/docs/zh-TW/memory) 檔案，並將保留的始終載入的指導遷移到 [skills](/docs/zh-TW/skills) 和按需載入的嵌套 `CLAUDE.md` 檔案。修剪會削減目錄佈局、依賴清單和架構概述等部分，並保留與工具預設值不同的陷阱、基本原理和約定。也提供使 [auto mode](/docs/zh-TW/permissions#permission-modes) 成為您的預設值的選項，以及[預先批准](/docs/zh-TW/permissions)經常被拒絕的唯讀命令。首先報告發現並在變更任何內容之前要求確認。從終端機，`claude doctor` 列印唯讀安裝診斷而不啟動工作階段。別名：`/checkup`。`CLAUDE.md` 修剪檢查需要 Claude Code v2.1.206 或更新版本。在 v2.1.206 之前，版本檢查將 Homebrew 安裝與 `autoUpdatesChannel` 設定進行比較，而不是[已安裝的 cask 頻道](/docs/zh-TW/setup#configure-release-channel)。在 v2.1.205 之前，`/doctor` 開啟唯讀診斷螢幕，按 `f` 將報告發送給 Claude |

81| `/effort [level\|auto]` | 設定模型[努力程度](/docs/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用的程度取決於模型，`max` 和 `ultracode` 僅限工作階段。`ultracode` 是一個 Claude Code 設定，結合 `xhigh` 推理與自動[工作流](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)協調。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用程度引數，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本。在 Fable 5、Opus 4.8 和 Opus 4.7 上，非互動 `/effort` 在[模型預設努力程度保持](/docs/zh-TW/model-config#adjust-effort-level)生效時報告 `Not applied`，因此改為在啟動時傳遞 `--effort` |81| `/effort [level\|auto]` | 設定模型[努力程度](/docs/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用的程度取決於模型，`max` 和 `ultracode` 僅限工作階段。`ultracode` 是一個 Claude Code 設定，結合 `xhigh` 推理與自動[工作流](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)協調。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成。也可在非互動模式（`-p`）中使用程度引數，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本。在 Fable 5、Opus 4.8 和 Opus 4.7 上，非互動 `/effort` 在[模型預設努力程度保持](/docs/zh-TW/model-config#adjust-effort-level)生效時報告 `Not applied`，因此改為在啟動時傳遞 `--effort` |

84| `/fast [on\|off]` | 切換[快速模式](/docs/zh-TW/fast-mode)開啟或關閉。{/* min-version: 2.1.205 */}在非互動模式（`-p`）中，`/fast` 僅在使用快速模式在其 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 值中啟動的工作階段中工作，例如 `claude -p --settings '{"fastMode": true}'`；切換然後僅適用於目前工作階段且不會儲存為您的預設值，在任何其他非互動工作階段中命令報告快速模式不可用。需要 Claude Code v2.1.205 或更新版本 |84| `/fast [on\|off]` | 切換[快速模式](/docs/zh-TW/fast-mode)開啟或關閉。在非互動模式（`-p`）中，`/fast` 僅在使用快速模式在其 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 值中啟動的工作階段中工作，例如 `claude -p --settings '{"fastMode": true}'`；切換然後僅適用於目前工作階段且不會儲存為您的預設值，在任何其他非互動工作階段中命令報告快速模式不可用。需要 Claude Code v2.1.205 或更新版本 |

86| `/fewer-permission-prompts` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 掃描您的記錄以查找常見的唯讀 Bash 和 MCP 工具呼叫，然後將優先允許清單添加到專案 `.claude/settings.json` 以減少權限提示 |86| `/fewer-permission-prompts` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 掃描您的記錄以查找常見的唯讀 Bash 和 MCP 工具呼叫，然後將優先允許清單添加到專案 `.claude/settings.json` 以減少權限提示 |

87| `/focus` | 切換焦點檢視，僅顯示您的最後一個提示、帶有編輯 diffstats 的單行工具呼叫摘要和最終回應。{/* min-version: 2.1.198 */}自 v2.1.198 起，工具呼叫摘要也會計算在回合中啟動的 subagents 數量，並將已完成的背景工作通知折疊為單一計數。選擇在工作階段之間保持；設定設定中的 [`viewMode`](/docs/zh-TW/settings#available-settings) 以覆蓋它。僅在[全螢幕渲染](/docs/zh-TW/fullscreen)中可用 |87| `/focus` | 切換焦點檢視，僅顯示您的最後一個提示、帶有編輯 diffstats 的單行工具呼叫摘要和最終回應。自 v2.1.198 起，工具呼叫摘要也會計算在回合中啟動的 subagents 數量，並將已完成的背景工作通知折疊為單一計數。選擇在工作階段之間保持；設定設定中的 [`viewMode`](/docs/zh-TW/settings#available-settings) 以覆蓋它。僅在[全螢幕渲染](/docs/zh-TW/fullscreen)中可用 |

88| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一個[分叉的 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)：一個背景 subagent，繼承完整的對話並在指令上工作，同時您繼續進行。其結果在完成時返回到您的對話。若要自己切換到對話的副本，請使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的別名 |88| `/fork <directive>` | 生成一個[分叉的 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)：一個背景 subagent，繼承完整的對話並在指令上工作，同時您繼續進行。其結果在完成時返回到您的對話。若要自己切換到對話的副本，請使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的別名 |

90| `/heapdump` | 將 JavaScript 堆快照和記憶體分解寫入 `~/Desktop`，或在沒有 Desktop 資料夾的 Linux 上寫入您的主目錄，以診斷高記憶體使用情況。`.heapsnapshot` 檔案包含您的完整對話和認證，所以不要分享它。請參閱[故障排除](/docs/zh-TW/troubleshooting#high-cpu-or-memory-usage) |90| `/heapdump` | 將 JavaScript 堆快照和記憶體分解寫入 `~/Desktop`，或在沒有 Desktop 資料夾的 Linux 上寫入您的主目錄，以診斷高記憶體使用情況。`.heapsnapshot` 檔案包含您的完整對話和認證，所以不要分享它。請參閱[故障排除](/docs/zh-TW/troubleshooting#high-cpu-or-memory-usage) |

101| `/loop [interval] [prompt]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 在工作階段保持開啟時重複執行提示。省略間隔，Claude 會在迭代之間自動調整步調。省略提示，[如果可用](/docs/zh-TW/scheduled-tasks#run-the-built-in-maintenance-prompt)Claude 運行自主維護檢查或 `.claude/loop.md` 中的提示。示例：`/loop 5m check if the deploy finished`。請參閱[按計劃運行提示](/docs/zh-TW/scheduled-tasks)。別名：`/proactive` |101| `/loop [interval] [prompt]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 在工作階段保持開啟時重複執行提示。省略間隔，Claude 會在迭代之間自動調整步調。省略提示，[如果可用](/docs/zh-TW/scheduled-tasks#run-the-built-in-maintenance-prompt)Claude 運行自主維護檢查或 `.claude/loop.md` 中的提示。示例：`/loop 5m check if the deploy finished`。請參閱[按計劃運行提示](/docs/zh-TW/scheduled-tasks)。別名：`/proactive` |

102| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 驗證。不帶引數執行以開啟互動式清單，傳遞 `reconnect <server>` 以重新連接一個已斷開連接的伺服器，或傳遞 `enable`/`disable` 與伺服器名稱或 `all` 以在不開啟對話框的情況下變更連接狀態。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用，其中不帶引數執行時列印伺服器狀態的文字摘要而不是開啟清單；需要 Claude Code v2.1.205 或更新版本 |102| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 驗證。不帶引數執行以開啟互動式清單，傳遞 `reconnect <server>` 以重新連接一個已斷開連接的伺服器，或傳遞 `enable`/`disable` 與伺服器名稱或 `all` 以在不開啟對話框的情況下變更連接狀態。也可在非互動模式（`-p`）中使用，其中不帶引數執行時列印伺服器狀態的文字摘要而不是開啟清單；需要 Claude Code v2.1.205 或更新版本 |

105| `/model [model]` | 切換 AI 模型並將其儲存為新工作階段的預設值。對於支援此功能的模型，使用左/右箭頭以[調整努力程度](/docs/zh-TW/model-config#adjust-effort-level)。不帶引數時，開啟選擇器；在列上按 `s` 以僅為目前工作階段切換。當對話有先前輸出時，選擇器會要求確認，因為下一個回應會重新讀取完整歷史記錄而不使用快取上下文。確認後，變更立即應用，無需等待目前回應完成。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用模型引數而不是選擇器，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本 |105| `/model [model]` | 切換 AI 模型並將其儲存為新工作階段的預設值。對於支援此功能的模型，使用左/右箭頭以[調整努力程度](/docs/zh-TW/model-config#adjust-effort-level)。不帶引數時，開啟選擇器；在列上按 `s` 以僅為目前工作階段切換。當對話有先前輸出時，選擇器會要求確認，因為下一個回應會重新讀取完整歷史記錄而不使用快取上下文。確認後，變更立即應用，無需等待目前回應完成。也可在非互動模式（`-p`）中使用模型引數而不是選擇器，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本 |

107| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。開啟互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄，以及檢視[最近的自動模式拒絕](/docs/zh-TW/auto-mode-config#review-denials)。別名：`/allowed-tools` |107| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。開啟互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄，以及檢視[最近的自動模式拒絕](/docs/zh-TW/auto-mode-config#review-denials)。別名：`/allowed-tools` |

109| `/plugin [subcommand]` | 管理 Claude Code [plugins](/docs/zh-TW/plugins)。不帶引數執行以開啟 plugin 選單，或傳遞子命令如 `list`、`install`、`enable` 或 `disable` 以直接執行 |109| `/plugin [subcommand]` | 管理 Claude Code [plugins](/docs/zh-TW/plugins)。不帶引數執行以開啟 plugin 選單，或傳遞子命令如 `list`、`install`、`enable` 或 `disable` 以直接執行 |

111| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。直接詢問 Claude 以查看 pull request 評論。在較早的版本上，從 GitHub pull request 擷取並顯示評論；自動偵測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |111| `/pr-comments [PR]` | 在 v2.1.91 中移除。直接詢問 Claude 以查看 pull request 評論。在較早的版本上，從 GitHub pull request 擷取並顯示評論；自動偵測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |

113| `/radio` | 在您的瀏覽器中開啟 Claude FM lo-fi 廣播。當沒有瀏覽器可用時列印串流 URL。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不可用 |113| `/radio` | 在您的瀏覽器中開啟 Claude FM lo-fi 廣播。當沒有瀏覽器可用時列印串流 URL。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不可用 |

115| `/release-notes` | 在互動式版本選擇器中檢視變更日誌。選擇特定版本以查看其發行說明，或選擇顯示所有版本。{/* min-version: 2.1.208 */}說明會在您的記錄中出現，無需進入 Claude 看到的對話。在 v2.1.208 之前，檢視的說明進入對話，包括顯示所有版本時的整個變更日誌 |115| `/release-notes` | 在互動式版本選擇器中檢視變更日誌。選擇特定版本以查看其發行說明，或選擇顯示所有版本。說明會在您的記錄中出現，無需進入 Claude 看到的對話。在 v2.1.208 之前，檢視的說明進入對話，包括顯示所有版本時的整個變更日誌 |

116| `/reload-plugins [--force]` | 重新載入所有作用中的 [plugins](/docs/zh-TW/plugins) 以套用待處理的變更，無需重新啟動。報告每個已重新載入的元件的計數，並標記任何載入錯誤。當重新載入會變更載入的 MCP 工具並使提示快取失效時，命令會警告並跳過，除非您傳遞 `--force` |116| `/reload-plugins [--force]` | 重新載入所有作用中的 [plugins](/docs/zh-TW/plugins) 以套用待處理的變更，無需重新啟動。報告每個已重新載入的元件的計數，並標記任何載入錯誤。當重新載入會變更載入的 MCP 工具並使提示快取失效時，命令會警告並跳過，除非您傳遞 `--force` |

117| `/reload-skills` | {/* min-version: 2.1.152 */}重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄，以便在工作階段期間添加或更改的 skills 在磁碟上變得可用，無需重新啟動。報告有多少 skills 可用以及添加或移除了多少 |117| `/reload-skills` | 重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄，以便在工作階段期間添加或更改的 skills 在磁碟上變得可用，無需重新啟動。報告有多少 skills 可用以及添加或移除了多少 |

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

120| `/rename [name]` | 重新命名目前的工作階段並在提示列上顯示名稱。不使用名稱時，從對話歷史記錄自動產生名稱。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用；需要 Claude Code v2.1.205 或更新版本 |120| `/rename [name]` | 重新命名目前的工作階段並在提示列上顯示名稱。不使用名稱時，從對話歷史記錄自動產生名稱。也可在非互動模式（`-p`）中使用；需要 Claude Code v2.1.205 或更新版本 |

121| `/resume [session]` | 按 ID 或名稱繼續對話，或開啟工作階段選擇器。自 v2.1.144 起，[背景工作階段](/docs/zh-TW/agent-view)會在選擇器中顯示，標記為 `bg`；仍在運行的工作階段無法在此處繼續，因此從 `claude agents` 附加到它或先在那裡停止它。別名：`/continue` |121| `/resume [session]` | 按 ID 或名稱繼續對話，或開啟工作階段選擇器。自 v2.1.144 起，[背景工作階段](/docs/zh-TW/agent-view)會在選擇器中顯示，標記為 `bg`；仍在運行的工作階段無法在此處繼續，因此從 `claude agents` 附加到它或先在那裡停止它。別名：`/continue` |

122| `/review [PR]` | {/* min-version: 2.1.202 */}按編號執行 GitHub pull request 的快速單次通過、唯讀審閱。不帶引數時，列出開放的 PR 以供選擇；PR 編號後的文字成為額外的審閱指示。從 v2.1.186 到 v2.1.201，`/review` 改為運行與 `/code-review medium` 相同的多 agent 引擎。如需選定努力程度的多 agent 審閱，請使用 [`/code-review <level> <pr#>`](/docs/zh-TW/code-review#review-a-diff-locally)；如需雲端審閱，請參閱 [`/code-review ultra`](/docs/zh-TW/ultrareview) |122| `/review [PR]` | 按編號執行 GitHub pull request 的快速單次通過、唯讀審閱。不帶引數時，列出開放的 PR 以供選擇；PR 編號後的文字成為額外的審閱指示。從 v2.1.186 到 v2.1.201，`/review` 改為運行與 `/code-review medium` 相同的多 agent 引擎。如需選定努力程度的多 agent 審閱，請使用 [`/code-review <level> <pr#>`](/docs/zh-TW/code-review#review-a-diff-locally)；如需雲端審閱，請參閱 [`/code-review ultra`](/docs/zh-TW/ultrareview) |

124| `/run` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 啟動並驅動您的專案應用程式以查看在執行中的應用程式中工作的變更，而不僅僅是在測試中。請參閱[運行並驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |124| `/run` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 啟動並驅動您的專案應用程式以查看在執行中的應用程式中工作的變更，而不僅僅是在測試中。請參閱[運行並驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app)。需要 Claude Code v2.1.145 或更新版本 |

125| `/run-skill-generator` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 通過從乾淨環境編寫每個專案的 [skill](/docs/zh-TW/skills#run-and-verify-your-app)，教導 `/run` 和 `/verify` 如何構建、啟動和驅動您的專案應用程式。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |125| `/run-skill-generator` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 通過從乾淨環境編寫每個專案的 [skill](/docs/zh-TW/skills#run-and-verify-your-app)，教導 `/run` 和 `/verify` 如何構建、啟動和驅動您的專案應用程式。需要 Claude Code v2.1.145 或更新版本 |

127| `/schedule [description]` | 建立、更新、列出或執行[例行工作](/docs/zh-TW/routines)，在 Anthropic 管理的雲端基礎設施上執行。Claude 會以對話方式引導您完成設定。別名：`/routines` |127| `/schedule [description]` | 建立、更新、列出或執行[例行工作](/docs/zh-TW/routines)，在 Anthropic 管理的雲端基礎設施上執行。Claude 會以對話方式引導您完成設定。別名：`/routines` |

128| `/scroll-speed` | 以互動方式調整滑鼠滾輪[捲動速度](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)，使用尺標，您可以在對話框開啟時捲動以預覽變更。僅在[全螢幕渲染](/docs/zh-TW/fullscreen)中可用，在 JetBrains IDE 終端機中不可用 |128| `/scroll-speed` | 以互動方式調整滑鼠滾輪[捲動速度](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)，使用尺標，您可以在對話框開啟時捲動以預覽變更。僅在[全螢幕渲染](/docs/zh-TW/fullscreen)中可用，在 JetBrains IDE 終端機中不可用 |

130| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Amazon Bedrock 使用者也可以從登入螢幕訪問此精靈 |130| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Amazon Bedrock 使用者也可以從登入螢幕訪問此精靈 |

131| `/setup-vertex` | 通過互動式精靈配置 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Google Cloud 的 Agent Platform 使用者也可以從登入螢幕訪問此精靈 |131| `/setup-vertex` | 通過互動式精靈配置 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Google Cloud 的 Agent Platform 使用者也可以從登入螢幕訪問此精靈 |

132| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/docs/zh-TW/skills#bundled-skills).** 審閱變更的程式碼以查找清理機會並應用修復。四個審閱 [agents](/docs/zh-TW/sub-agents) 並行運行，涵蓋現有幫助程式的重用、簡化、效率和變更是否位於正確的抽象層級。從 v2.1.154 開始，審閱不尋找正確性錯誤。使用 `/code-review` 查找錯誤。在較早的版本上，`/simplify` 等同於 `/code-review --fix`。傳遞路徑或 PR 參考以審閱特定目標 |132| `/simplify [target]` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 審閱變更的程式碼以查找清理機會並應用修復。四個審閱 [agents](/docs/zh-TW/sub-agents) 並行運行，涵蓋現有幫助程式的重用、簡化、效率和變更是否位於正確的抽象層級。從 v2.1.154 開始，審閱不尋找正確性錯誤。使用 `/code-review` 查找錯誤。在較早的版本上，`/simplify` 等同於 `/code-review --fix`。傳遞路徑或 PR 參考以審閱特定目標 |

133| `/skills` | 列出可用的 [skills](/docs/zh-TW/skills)。{/* min-version: 2.1.121 */}自 v2.1.121 起，輸入以按名稱篩選清單。按 `t` 按 token 計數排序。按 `Space` 以[從 Claude 或 `/` 選單隱藏 skill](/docs/zh-TW/skills#override-skill-visibility-from-settings)，然後按 `Enter` 以儲存 |133| `/skills` | 列出可用的 [skills](/docs/zh-TW/skills)。自 v2.1.121 起，輸入以按名稱篩選清單。按 `t` 按 token 計數排序。按 `Space` 以[從 Claude 或 `/` 選單隱藏 skill](/docs/zh-TW/skills#override-skill-visibility-from-settings)，然後按 `Enter` 以儲存 |

146| `/ultrareview [PR]` | 在雲端沙箱中使用 [ultrareview](/docs/zh-TW/ultrareview) 運行深度、多 agent 程式碼審閱。首選的調用現在是 `/code-review ultra`，`/ultrareview` 保留為別名。Pro 和 Max 上包括 3 次免費執行，然後需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |146| `/ultrareview [PR]` | 在雲端沙箱中使用 [ultrareview](/docs/zh-TW/ultrareview) 運行深度、多 agent 程式碼審閱。首選的調用現在是 `/code-review ultra`，`/ultrareview` 保留為別名。Pro 和 Max 上包括 3 次免費執行，然後需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

148| `/usage` | 顯示工作階段成本、方案使用限制和活動統計資訊。在 Pro、Max、Team 或 Enterprise 方案上，包括按 skill、subagent、plugin 和 MCP 伺服器的使用情況分解。請參閱[成本追蹤指南](/docs/zh-TW/costs#using-the-%2Fusage-command)以了解詳細資訊。`/cost` 和 `/stats` 是別名 |148| `/usage` | 顯示工作階段成本、方案使用限制和活動統計資訊。在 Pro、Max、Team 或 Enterprise 方案上，包括按 skill、subagent、plugin 和 MCP 伺服器的使用情況分解。請參閱[成本追蹤指南](/docs/zh-TW/costs#using-the-%2Fusage-command)以了解詳細資訊。`/cost` 和 `/stats` 是別名 |

149| `/usage-credits` | 配置使用量額度以在達到限制時繼續工作。在 Pro 和 Max 方案上，開啟[CLI 內對話框](/docs/zh-TW/costs#set-a-spend-limit-on-pro-and-max)以購買使用量額度、設定每月支出限制和配置自動重新載入；在 Claude Code v2.1.207 之前的版本和其他方案上，在您的瀏覽器中開啟使用量額度計費頁面，除了沒有計費存取權的 Team 和 Enterprise 成員改為從 CLI 向其管理員發送使用量額度請求。{/* min-version: 2.1.205 */}當沒有瀏覽器可以開啟計費頁面時，例如透過 SSH，命令改為列印要訪問的 URL；這需要 Claude Code v2.1.205 或更新版本，較早的版本在該情況下顯示任何內容。先前為 `/extra-usage` |149| `/usage-credits` | 配置使用量額度以在達到限制時繼續工作。在 Pro 和 Max 方案上，開啟[CLI 內對話框](/docs/zh-TW/costs#set-a-spend-limit-on-pro-and-max)以購買使用量額度、設定每月支出限制和配置自動重新載入；在 Claude Code v2.1.207 之前的版本和其他方案上，在您的瀏覽器中開啟使用量額度計費頁面，除了沒有計費存取權的 Team 和 Enterprise 成員改為從 CLI 向其管理員發送使用量額度請求。當沒有瀏覽器可以開啟計費頁面時，例如透過 SSH，命令改為列印要訪問的 URL；這需要 Claude Code v2.1.205 或更新版本，較早的版本在該情況下顯示任何內容。先前為 `/extra-usage` |

150| `/verify` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 通過構建您的專案應用程式、運行它並觀察結果來確認程式碼變更是否執行了應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行並驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |150| `/verify` | **[Skill](/docs/zh-TW/skills#bundled-skills).** 通過構建您的專案應用程式、運行它並觀察結果來確認程式碼變更是否執行了應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行並驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app)。需要 Claude Code v2.1.145 或更新版本 |

151| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。若要在 Vim 和一般編輯模式之間切換，請使用 `/config` → Editor mode |151| `/vim` | 在 v2.1.92 中移除。若要在 Vim 和一般編輯模式之間切換，請使用 `/config` → Editor mode |

152| `/voice [hold\|tap\|off]` | 切換[語音聽寫](/docs/zh-TW/voice-dictation)，或在特定模式下啟用它。需要 Claude.ai 帳戶 |152| `/voice [hold\|tap\|off]` | 切換[語音聽寫](/docs/zh-TW/voice-dictation)，或在特定模式下啟用它。需要 Claude.ai 帳戶 |

153| `/web-setup` | 使用您的本地 `gh` CLI 認證將您的 GitHub 帳戶連接到[網頁上的 Claude Code](/docs/zh-TW/web-quickstart#connect-from-your-terminal)。如果 GitHub 未連接，`/schedule` 會自動提示此操作 |153| `/web-setup` | 使用您的本地 `gh` CLI 認證將您的 GitHub 帳戶連接到[網頁上的 Claude Code](/docs/zh-TW/web-quickstart#connect-from-your-terminal)。如果 GitHub 未連接，`/schedule` 會自動提示此操作 |

computer-use.md +11 −11

Details

12 12

13Computer use 讓 Claude 可以開啟應用程式、控制您的螢幕，並以您的方式在您的機器上工作。從 CLI，Claude 可以編譯 Swift 應用程式、啟動它、點擊每個按鈕，並擷取結果的螢幕截圖，所有這些都在編寫程式碼的同一個對話中進行。13Computer use 讓 Claude 可以開啟應用程式、控制您的螢幕，並以您的方式在您的機器上工作。從 CLI，Claude 可以編譯 Swift 應用程式、啟動它、點擊每個按鈕，並擷取結果的螢幕截圖，所有這些都在編寫程式碼的同一個對話中進行。

14 14

~~15本頁涵蓋 computer use 在 CLI 中的運作方式。如需 Desktop 應用程式，請參閱 [Desktop 中的 computer use](/zh-TW/desktop#let-claude-use-your-computer)。~~15本頁涵蓋 computer use 在 CLI 中的運作方式。如需 Desktop 應用程式，請參閱 [Desktop 中的 computer use](/docs/zh-TW/desktop#let-claude-use-your-computer)。

16 16

17<h2 id="what-you-can-do-with-computer-use">17<h2 id="what-you-can-do-with-computer-use">

18 您可以使用 computer use 做什麼18 您可以使用 computer use 做什麼

31 31

32Claude 有多種方式與應用程式或服務互動。Computer use 是最廣泛和最慢的，因此 Claude 首先嘗試最精確的工具：32Claude 有多種方式與應用程式或服務互動。Computer use 是最廣泛和最慢的，因此 Claude 首先嘗試最精確的工具：

33 33

~~34* 如果您有該服務的 [MCP server](/zh-TW/mcp)，Claude 會使用它。~~34* 如果您有該服務的 [MCP server](/docs/zh-TW/mcp)，Claude 會使用它。

35* 如果任務是 shell 命令，Claude 會使用 Bash。35* 如果任務是 shell 命令，Claude 會使用 Bash。

~~36* 如果任務是瀏覽器工作且您已設定 [Claude in Chrome](/zh-TW/chrome)，Claude 會使用它。~~36* 如果任務是瀏覽器工作且您已設定 [Claude in Chrome](/docs/zh-TW/chrome)，Claude 會使用它。

37* 如果以上都不適用，Claude 會使用 computer use。37* 如果以上都不適用，Claude 會使用 computer use。

38 38

39螢幕控制保留用於其他工具無法到達的事物：原生應用程式、模擬器和沒有 API 的工具。39螢幕控制保留用於其他工具無法到達的事物：原生應用程式、模擬器和沒有 API 的工具。

98 98

99這些應用程式不會被封鎖。警告讓您決定任務是否值得該級別的存取。99這些應用程式不會被封鎖。警告讓您決定任務是否值得該級別的存取。

100 100

101Claude 的控制級別也因應用程式類別而異：瀏覽器和交易平台是僅檢視，終端機和 IDE 是僅點擊，其他所有內容都獲得完全控制。請參閱 [Desktop 中的應用程式權限](/zh-TW/desktop#app-permissions)以取得完整的層級細目。101Claude 的控制級別也因應用程式類別而異：瀏覽器和交易平台是僅檢視，終端機和 IDE 是僅點擊，其他所有內容都獲得完全控制。請參閱 [Desktop 中的應用程式權限](/docs/zh-TW/desktop#app-permissions)以取得完整的層級細目。

102 102

103<h2 id="how-claude-works-on-your-screen">103<h2 id="how-claude-works-on-your-screen">

104 Claude 如何在您的螢幕上工作104 Claude 如何在您的螢幕上工作

110 一次一個工作階段110 一次一個工作階段

111</h3>111</h3>

112 112

113Computer use 從第一個 computer use 操作開始持有機器範圍的鎖定，直到執行該操作的工作階段退出。{/* min-version: 2.1.195 */}自 v2.1.195 起，完成任務不會釋放鎖定；只有退出工作階段才會。如果另一個 Claude Code 工作階段已在使用您的電腦，新的嘗試會失敗，並顯示一條訊息，告訴您哪個工作階段持有鎖定。先退出該工作階段。113Computer use 從第一個 computer use 操作開始持有機器範圍的鎖定，直到執行該操作的工作階段退出。自 v2.1.195 起，完成任務不會釋放鎖定；只有退出工作階段才會。如果另一個 Claude Code 工作階段已在使用您的電腦，新的嘗試會失敗，並顯示一條訊息，告訴您哪個工作階段持有鎖定。先退出該工作階段。

114 114

115<h3 id="apps-are-hidden-while-claude-works">115<h3 id="apps-are-hidden-while-claude-works">

116 Claude 工作時應用程式被隱藏116 Claude 工作時應用程式被隱藏

141</h2>141</h2>

142 142

143<Warning>143<Warning>

144 與 [沙箱化 Bash 工具](/zh-TW/sandboxing)不同，computer use 在您的實際桌面上執行，可以存取您核准的應用程式。Claude 檢查每個操作並標記來自螢幕上內容的潛在提示注入，但信任邊界是不同的。請參閱 [computer use 安全指南](https://support.claude.com/en/articles/14128542)以了解最佳實踐。144 與 [沙箱化 Bash 工具](/docs/zh-TW/sandboxing)不同，computer use 在您的實際桌面上執行，可以存取您核准的應用程式。Claude 檢查每個操作並標記來自螢幕上內容的潛在提示注入，但信任邊界是不同的。請參閱 [computer use 安全指南](https://support.claude.com/en/articles/14128542)以了解最佳實踐。

145</Warning>145</Warning>

146 146

147內建護欄在不需要設定的情況下降低風險：147內建護欄在不需要設定的情況下降低風險：

234 234

235伺服器僅在符合條件的設定上出現。檢查：235伺服器僅在符合條件的設定上出現。檢查：

236 236

237* 您在 macOS 上。Computer use 在 CLI 中不適用於 Linux 或 Windows。在 Windows 上，請改用 [Desktop 中的 computer use](/zh-TW/desktop#let-claude-use-your-computer)。237* 您在 macOS 上。Computer use 在 CLI 中不適用於 Linux 或 Windows。在 Windows 上，請改用 [Desktop 中的 computer use](/docs/zh-TW/desktop#let-claude-use-your-computer)。

238* 您透過 claude.ai 進行身份驗證。Computer use 不適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 等第三方提供者。如果您完全透過第三方提供者存取 Claude，您需要單獨的 claude.ai 帳戶才能使用此功能。238* 您透過 claude.ai 進行身份驗證。Computer use 不適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 等第三方提供者。如果您完全透過第三方提供者存取 Claude，您需要單獨的 claude.ai 帳戶才能使用此功能。

239* 您在互動式工作階段中。Computer use 在使用 `-p` 旗標的非互動式模式中不可用。239* 您在互動式工作階段中。Computer use 在使用 `-p` 旗標的非互動式模式中不可用。

240 240

242 另請參閱242 另請參閱

243</h2>243</h2>

244 244

245* [Desktop 中的 Computer use](/zh-TW/desktop#let-claude-use-your-computer)：具有圖形設定頁面的相同功能245* [Desktop 中的 Computer use](/docs/zh-TW/desktop#let-claude-use-your-computer)：具有圖形設定頁面的相同功能

246* [Claude in Chrome](/zh-TW/chrome)：用於基於網路的任務的瀏覽器自動化246* [Claude in Chrome](/docs/zh-TW/chrome)：用於基於網路的任務的瀏覽器自動化

247* [MCP](/zh-TW/mcp)：將 Claude 連接到結構化工具和 API247* [MCP](/docs/zh-TW/mcp)：將 Claude 連接到結構化工具和 API

248* [Sandboxing](/zh-TW/sandboxing)：Claude 的 Bash 工具如何隔離檔案系統和網路存取248* [Sandboxing](/docs/zh-TW/sandboxing)：Claude 的 Bash 工具如何隔離檔案系統和網路存取

249* [Computer use 安全指南](https://support.claude.com/en/articles/14128542)：安全 computer use 的最佳實踐249* [Computer use 安全指南](https://support.claude.com/en/articles/14128542)：安全 computer use 的最佳實踐

context-window.md +13 −13

Details

1578 1578

1579該會話演示了一個現實流程，包含代表性的令牌計數：1579該會話演示了一個現實流程，包含代表性的令牌計數：

1580 1580

1581* **在您輸入任何內容之前**：CLAUDE.md、自動記憶、MCP 工具名稱和技能描述都加載到上下文中。您自己的設置可能會在此處添加更多內容，例如[輸出樣式](/zh-TW/output-styles)或來自 [`--append-system-prompt`](/zh-TW/cli-reference) 的文本，兩者都以相同方式進入系統提示。1581* **在您輸入任何內容之前**：CLAUDE.md、自動記憶、MCP 工具名稱和技能描述都加載到上下文中。您自己的設置可能會在此處添加更多內容，例如[輸出樣式](/docs/zh-TW/output-styles)或來自 [`--append-system-prompt`](/docs/zh-TW/cli-reference) 的文本，兩者都以相同方式進入系統提示。

1582* **當 Claude 工作時**：每個文件讀取都會添加到上下文中，[路徑範圍規則](/zh-TW/memory#path-specific-rules)會自動與匹配的文件一起加載，並且[PostToolUse hook](/zh-TW/hooks-guide)在每次編輯後觸發。1582* **當 Claude 工作時**：每個文件讀取都會添加到上下文中，[路徑範圍規則](/docs/zh-TW/memory#path-specific-rules)會自動與匹配的文件一起加載，並且[PostToolUse hook](/docs/zh-TW/hooks-guide)在每次編輯後觸發。

1583* **後續提示**：[子代理](/zh-TW/sub-agents)在其自己的單獨上下文視窗中處理研究，因此大型文件讀取不會進入您的視窗。只有摘要和一個小的元數據預告片返回。1583* **後續提示**：[子代理](/docs/zh-TW/sub-agents)在其自己的單獨上下文視窗中處理研究，因此大型文件讀取不會進入您的視窗。只有摘要和一個小的元數據預告片返回。

1584* **最後**：`/compact` 用結構化摘要替換對話。大多數啟動內容會自動重新加載；下表顯示每個機制會發生什麼。1584* **最後**：`/compact` 用結構化摘要替換對話。大多數啟動內容會自動重新加載；下表顯示每個機制會發生什麼。

1585 1585

1586<h2 id="what-survives-compaction">1586<h2 id="what-survives-compaction">

1587 壓縮後的存活內容1587 壓縮後的存活內容

1588</h2>1588</h2>

1589 1589

1590當長會話壓縮時，Claude Code 會總結對話歷史以適應上下文視窗。{/* min-version: 2.1.198 */}自 v2.1.198 起，總結請求會繼承您的會話的[延伸思考](/zh-TW/model-config#extended-thinking)配置，因此當您的會話啟用思考時，它會在啟用思考的情況下進行推理，否則保持關閉。思考只會影響摘要的生成方式；您的會話設定在之後保持不變。您的指令會發生什麼取決於它們的加載方式：1590當長會話壓縮時，Claude Code 會總結對話歷史以適應上下文視窗。自 v2.1.198 起，總結請求會繼承您的會話的[延伸思考](/docs/zh-TW/model-config#extended-thinking)配置，因此當您的會話啟用思考時，它會在啟用思考的情況下進行推理，否則保持關閉。思考只會影響摘要的生成方式；您的會話設定在之後保持不變。您的指令會發生什麼取決於它們的加載方式：

1591 1591

1592| 機制 | 壓縮後 |1592| 機制 | 壓縮後 |

1593| :-------------------------- | :------------------------------------------- |1593| :-------------------------- | :------------------------------------------- |

1607 當您的上下文填滿時1607 當您的上下文填滿時

1608</h2>1608</h2>

1609 1609

1610Claude Code 會在您接近限制時自動壓縮，因此完整的上下文視窗不會結束您的會話。自動傳遞的工作方式與時間線中的 `/compact` 步驟相同。請參閱[當上下文填滿時](/zh-TW/how-claude-code-works#when-context-fills-up)以了解它保留的內容。1610Claude Code 會在您接近限制時自動壓縮，因此完整的上下文視窗不會結束您的會話。自動傳遞的工作方式與時間線中的 `/compact` 步驟相同。請參閱[當上下文填滿時](/docs/zh-TW/how-claude-code-works#when-context-fills-up)以了解它保留的內容。

1611 1611

1612您也可以在自動傳遞運行之前採取行動：1612您也可以在自動傳遞運行之前採取行動：

1613 1613

1614* **使用焦點進行壓縮**：在開始長時間新任務之前，運行帶有指令的 `/compact`，例如 `/compact focus on the auth bug fix`。摘要保留您選擇的內容，而不是自動傳遞猜測的重要內容。1614* **使用焦點進行壓縮**：在開始長時間新任務之前，運行帶有指令的 `/compact`，例如 `/compact focus on the auth bug fix`。摘要保留您選擇的內容，而不是自動傳遞猜測的重要內容。

1615* **在任務之間清除**：切換到不相關的工作時運行 `/clear`。舊對話會擠出您接下來需要的文件，並在每條消息上花費令牌。1615* **在任務之間清除**：切換到不相關的工作時運行 `/clear`。舊對話會擠出您接下來需要的文件，並在每條消息上花費令牌。

1616* **委託大型讀取**：將研究發送給[子代理](/zh-TW/sub-agents)，以便文件內容保留在其上下文視窗中，而不是您的。1616* **委託大型讀取**：將研究發送給[子代理](/docs/zh-TW/sub-agents)，以便文件內容保留在其上下文視窗中，而不是您的。

1617 1617

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

1619 1619

1620<h2 id="check-your-own-session">1620<h2 id="check-your-own-session">

1621 檢查您自己的會話1621 檢查您自己的會話

1629 1629

1630有關時間線中顯示的功能的更深入覆蓋，請參閱這些頁面：1630有關時間線中顯示的功能的更深入覆蓋，請參閱這些頁面：

1631 1631

1632* [擴展 Claude Code](/zh-TW/features-overview)：何時使用 CLAUDE.md 與技能與規則與 hooks 與 MCP1632* [擴展 Claude Code](/docs/zh-TW/features-overview)：何時使用 CLAUDE.md 與技能與規則與 hooks 與 MCP

1633* [存儲指令和記憶](/zh-TW/memory)：CLAUDE.md 層次結構和自動記憶1633* [存儲指令和記憶](/docs/zh-TW/memory)：CLAUDE.md 層次結構和自動記憶

1634* [子代理](/zh-TW/sub-agents)：將研究委託給單獨的上下文視窗1634* [子代理](/docs/zh-TW/sub-agents)：將研究委託給單獨的上下文視窗

1635* [最佳實踐](/zh-TW/best-practices)：將上下文作為您的主要約束進行管理1635* [最佳實踐](/docs/zh-TW/best-practices)：將上下文作為您的主要約束進行管理

1636* [提示快取](/zh-TW/prompt-caching)：哪些操作會使緩存的前綴失效1636* [提示快取](/docs/zh-TW/prompt-caching)：哪些操作會使緩存的前綴失效

1637* [減少令牌使用](/zh-TW/costs#reduce-token-usage)：保持上下文使用低的策略1637* [減少令牌使用](/docs/zh-TW/costs#reduce-token-usage)：保持上下文使用低的策略

debug-your-config.md +32 −32

Details

8 8

9當 Claude 忽略您的指令或您設定的功能沒有出現時，通常是因為檔案沒有載入、從您預期以外的位置載入，或被另一個檔案覆蓋。本指南展示如何檢查 Claude Code 實際載入的內容，以便您縮小範圍。9當 Claude 忽略您的指令或您設定的功能沒有出現時，通常是因為檔案沒有載入、從您預期以外的位置載入，或被另一個檔案覆蓋。本指南展示如何檢查 Claude Code 實際載入的內容，以便您縮小範圍。

10 10

~~11如需安裝、驗證和連線問題的協助，請改為參閱 [Troubleshoot installation and login](/zh-TW/troubleshoot-install)。~~11如需安裝、驗證和連線問題的協助，請改為參閱 [Troubleshoot installation and login](/docs/zh-TW/troubleshoot-install)。

12 12

13<h2 id="see-what-loaded-into-context">13<h2 id="see-what-loaded-into-context">

14 查看載入到 context 的內容14 查看載入到 context 的內容

25| `/hooks` | 作用中的 hook 設定 |25| `/hooks` | 作用中的 hook 設定 |

26| `/mcp` | 已連線的 MCP servers 及其狀態 |26| `/mcp` | 已連線的 MCP servers 及其狀態 |

27| `/permissions` | 目前生效的已解析允許和拒絕規則 |27| `/permissions` | 目前生效的已解析允許和拒絕規則 |

29| `/debug [issue]` | 啟用工作階段的偵錯日誌記錄，並提示 Claude 使用日誌輸出和設定路徑進行診斷 |29| `/debug [issue]` | 啟用工作階段的偵錯日誌記錄，並提示 Claude 使用日誌輸出和設定路徑進行診斷 |

30| `/status` | 作用中的設定來源，包括是否啟用了受管設定 |30| `/status` | 作用中的設定來源，包括是否啟用了受管設定 |

31 31

32如果記憶檔案在 `/memory` 中遺失，請根據 [CLAUDE.md 檔案如何載入](/zh-TW/memory#how-claude-md-files-load) 檢查其位置。子目錄 `CLAUDE.md` 檔案在 Claude 使用 Read 工具讀取該目錄中的檔案時按需載入，而不是在工作階段開始時載入。32如果記憶檔案在 `/memory` 中遺失，請根據 [CLAUDE.md 檔案如何載入](/docs/zh-TW/memory#how-claude-md-files-load) 檢查其位置。子目錄 `CLAUDE.md` 檔案在 Claude 使用 Read 工具讀取該目錄中的檔案時按需載入，而不是在工作階段開始時載入。

33 33

34如果 `/memory` 確認檔案已載入但 Claude 仍未遵循特定指令，問題可能在於指令的編寫方式，而不是是否載入。CLAUDE.md 適用於您會給新隊友的指導類型，例如專案慣例、建置命令和檔案所在位置。34如果 `/memory` 確認檔案已載入但 Claude 仍未遵循特定指令，問題可能在於指令的編寫方式，而不是是否載入。CLAUDE.md 適用於您會給新隊友的指導類型，例如專案慣例、建置命令和檔案所在位置。

35 35

36當指令模糊到可以多種方式解釋時、當兩個檔案給出衝突的方向時，或當檔案變得足夠長以至於個別規則獲得較少關注時，遵循度會下降。[編寫有效的指令](/zh-TW/memory#write-effective-instructions) 涵蓋保持遵循度高的特異性、大小和結構模式。36當指令模糊到可以多種方式解釋時、當兩個檔案給出衝突的方向時，或當檔案變得足夠長以至於個別規則獲得較少關注時，遵循度會下降。[編寫有效的指令](/docs/zh-TW/memory#write-effective-instructions) 涵蓋保持遵循度高的特異性、大小和結構模式。

37 37

38<Note>38<Note>

39 CLAUDE.md 和 permissions 解決不同的問題。CLAUDE.md 告訴 Claude 您的專案如何運作，以便它做出良好決策。[Permissions](/zh-TW/permissions) 和 [hooks](/zh-TW/hooks) 無論 Claude 決定什麼，都會強制執行限制。使用 CLAUDE.md 表示「我們在這裡這樣做」。使用 permissions 或 hooks 表示安全邊界和任何必須永遠不會發生的事情，其中您需要保證而不是指導。39 CLAUDE.md 和 permissions 解決不同的問題。CLAUDE.md 告訴 Claude 您的專案如何運作，以便它做出良好決策。[Permissions](/docs/zh-TW/permissions) 和 [hooks](/docs/zh-TW/hooks) 無論 Claude 決定什麼，都會強制執行限制。使用 CLAUDE.md 表示「我們在這裡這樣做」。使用 permissions 或 hooks 表示安全邊界和任何必須永遠不會發生的事情，其中您需要保證而不是指導。

40</Note>40</Note>

41 41

42<h2 id="check-resolved-settings">42<h2 id="check-resolved-settings">

43 檢查已解析的設定43 檢查已解析的設定

44</h2>44</h2>

45 45

46設定在受管、使用者、專案和本機範圍之間合併。受管設定在存在時始終優先。在其餘的設定中，較近的範圍會按本機、專案、使用者的順序覆蓋較廣的範圍。某些設定也可以由命令列旗標或 [環境變數](/zh-TW/env-vars) 設定，這些變數充當另一個覆蓋層。當設定似乎不適用時，您設定的值通常被另一個範圍或環境變數覆蓋。46設定在受管、使用者、專案和本機範圍之間合併。受管設定在存在時始終優先。在其餘的設定中，較近的範圍會按本機、專案、使用者的順序覆蓋較廣的範圍。某些設定也可以由命令列旗標或 [環境變數](/docs/zh-TW/env-vars) 設定，這些變數充當另一個覆蓋層。當設定似乎不適用時，您設定的值通常被另一個範圍或環境變數覆蓋。

47 47

48執行 `/doctor` 以檢查您的設定和安裝。它會報告它發現的內容，包括無效的設定檔案、重複的安裝、未使用的擴充功能，以及 {/* min-version: 2.1.206 */}簽入的 `CLAUDE.md` 內容 Claude 可以從程式碼庫衍生，然後提議它在您確認後才會套用的修正。`CLAUDE.md` 修剪檢查需要 Claude Code v2.1.206 或更新版本。在 v2.1.205 之前，`/doctor` 會開啟唯讀診斷畫面，按 `f` 會將報告傳送給 Claude 以進行修正。48執行 `/doctor` 以檢查您的設定和安裝。它會報告它發現的內容，包括無效的設定檔案、重複的安裝、未使用的擴充功能，以及簽入的 `CLAUDE.md` 內容 Claude 可以從程式碼庫衍生，然後提議它在您確認後才會套用的修正。`CLAUDE.md` 修剪檢查需要 Claude Code v2.1.206 或更新版本。在 v2.1.205 之前，`/doctor` 會開啟唯讀診斷畫面，按 `f` 會將報告傳送給 Claude 以進行修正。

49 49

50從終端機，`claude doctor` 會列印唯讀的安裝和設定診斷，而不會啟動工作階段。50從終端機，`claude doctor` 會列印唯讀的安裝和設定診斷，而不會啟動工作階段。

51 51

52執行 `/status` 以查看哪些設定來源處於作用中，包括是否啟用了受管設定。若要瞭解給定鍵的哪個範圍優先，請參閱 [範圍如何互動](/zh-TW/settings#how-scopes-interact)。52執行 `/status` 以查看哪些設定來源處於作用中，包括是否啟用了受管設定。若要瞭解給定鍵的哪個範圍優先，請參閱 [範圍如何互動](/docs/zh-TW/settings#how-scopes-interact)。

53 53

54<h2 id="check-mcp-servers">54<h2 id="check-mcp-servers">

55 檢查 MCP servers55 檢查 MCP servers

61* 啟動失敗的 server 在 `/mcp` 中顯示為失敗。`command` 或 `args` 中的相對檔案路徑是常見原因，因為它們相對於您啟動 Claude Code 的目錄而不是 `.mcp.json` 的位置進行解析。61* 啟動失敗的 server 在 `/mcp` 中顯示為失敗。`command` 或 `args` 中的相對檔案路徑是常見原因，因為它們相對於您啟動 Claude Code 的目錄而不是 `.mcp.json` 的位置進行解析。

62* 顯示為已連線但列出零個 tools 的 server 已成功啟動但未返回 tool 清單。從 `/mcp` 選擇 **Reconnect**。如果計數保持為零，執行 `claude --debug mcp` 以查看 server 的 stderr 輸出。62* 顯示為已連線但列出零個 tools 的 server 已成功啟動但未返回 tool 清單。從 `/mcp` 選擇 **Reconnect**。如果計數保持為零，執行 `claude --debug mcp` 以查看 server 的 stderr 輸出。

63 63

~~64如需設定位置和範圍規則，請參閱 [MCP](/zh-TW/mcp)。~~64如需設定位置和範圍規則，請參閱 [MCP](/docs/zh-TW/mcp)。

65 65

66<h2 id="check-hooks">66<h2 id="check-hooks">

67 檢查 hooks67 檢查 hooks

71 71

72如果 hook 出現但不觸發，通常是 matcher 的問題。檢查它是否有這些錯誤：72如果 hook 出現但不觸發，通常是 matcher 的問題。檢查它是否有這些錯誤：

73 73

74* `matcher` 欄位是一個使用 `|` 匹配多個 tool 名稱的單一字串，例如 `"Edit|Write"`。{/* min-version: 2.1.191 */}`,` 分隔符是等效的，因此 `"Edit,Write"` 匹配相同的 tools。在 v2.1.191 之前，逗號會進入正規表達式評估，matcher 永遠不會匹配，因此如果您不在 v2.1.191 版本上，請使用 `|`。74* `matcher` 欄位是一個使用 `|` 匹配多個 tool 名稱的單一字串，例如 `"Edit|Write"`。`,` 分隔符是等效的，因此 `"Edit,Write"` 匹配相同的 tools。在 v2.1.191 之前，逗號會進入正規表達式評估，matcher 永遠不會匹配，因此如果您不在 v2.1.191 版本上，請使用 `|`。

75* 拼寫錯誤的 tool 名稱會產生一個不匹配任何內容的 matcher，因此 hook 會無聲地失敗。75* 拼寫錯誤的 tool 名稱會產生一個不匹配任何內容的 matcher，因此 hook 會無聲地失敗。

76* 陣列值是 schema 錯誤：Claude Code 顯示設定錯誤通知並拒絕整個使用者、專案或本機設定檔案，`claude doctor` 報告驗證失敗，該檔案中的任何 hook 都不會出現在 `/hooks` 中。在[受管設定](/zh-TW/settings#settings-files)中，只有無效項目被刪除，檔案的其他 hooks 仍然適用。76* 陣列值是 schema 錯誤：Claude Code 顯示設定錯誤通知並拒絕整個使用者、專案或本機設定檔案，`claude doctor` 報告驗證失敗，該檔案中的任何 hook 都不會出現在 `/hooks` 中。在[受管設定](/docs/zh-TW/settings#settings-files)中，只有無效項目被刪除，檔案的其他 hooks 仍然適用。

77 77

78對 `settings.json` 的編輯在短暫的檔案穩定延遲後在執行中的工作階段中生效。您不需要重新啟動。如果在保存後幾秒鐘 `/hooks` 仍顯示舊定義，請再次執行 `/hooks` 以重新整理檢視。78對 `settings.json` 的編輯在短暫的檔案穩定延遲後在執行中的工作階段中生效。您不需要重新啟動。如果在保存後幾秒鐘 `/hooks` 仍顯示舊定義，請再次執行 `/hooks` 以重新整理檢視。

79 79

80如果 `/hooks` 顯示 hook 但它仍然不觸發，下一步是即時監視 hook 評估。使用 `claude --debug hooks` 啟動工作階段並觸發 tool 呼叫。偵錯日誌記錄每個事件、檢查了哪些 matchers 以及 hook 的結束代碼和輸出。如需日誌格式，請參閱 [Debug hooks](/zh-TW/hooks#debug-hooks)，如需常見失敗模式，請參閱 [hooks 疑難排解](/zh-TW/hooks-guide#limitations-and-troubleshooting)。80如果 `/hooks` 顯示 hook 但它仍然不觸發，下一步是即時監視 hook 評估。使用 `claude --debug hooks` 啟動工作階段並觸發 tool 呼叫。偵錯日誌記錄每個事件、檢查了哪些 matchers 以及 hook 的結束代碼和輸出。如需日誌格式，請參閱 [Debug hooks](/docs/zh-TW/hooks#debug-hooks)，如需常見失敗模式，請參閱 [hooks 疑難排解](/docs/zh-TW/hooks-guide#limitations-and-troubleshooting)。

81 81

82<h2 id="test-against-a-clean-configuration">82<h2 id="test-against-a-clean-configuration">

83 針對乾淨的設定進行測試83 針對乾淨的設定進行測試

84</h2>84</h2>

85 85

86{/* min-version: 2.1.169 */}使用 [`claude --safe-mode`](/zh-TW/cli-reference#cli-flags) 開始，它會啟動一個工作階段，其中所有自訂項目都被停用，包括 `CLAUDE.md`、skills、plugins、hooks、MCP servers 和自訂命令與代理程式。驗證、模型選擇、內建工具和權限正常運作。如果問題在安全模式中消失，則其中一個表面是原因；使用上面的目標檢查來找出是哪一個。安全模式仍然會套用來自您組織的受管 hooks 和設定原則。受管 plugins、skills、`CLAUDE.md` 和 MCP servers 會被關閉。86使用 [`claude --safe-mode`](/docs/zh-TW/cli-reference#cli-flags) 開始，它會啟動一個工作階段，其中所有自訂項目都被停用，包括 `CLAUDE.md`、skills、plugins、hooks、MCP servers 和自訂命令與代理程式。驗證、模型選擇、內建工具和權限正常運作。如果問題在安全模式中消失，則其中一個表面是原因；使用上面的目標檢查來找出是哪一個。安全模式仍然會套用來自您組織的受管 hooks 和設定原則。受管 plugins、skills、`CLAUDE.md` 和 MCP servers 會被關閉。

87 87

88如果問題在安全模式中持續存在，或您的設定本身令人懷疑，請與不從您常用設定載入任何內容的工作階段進行比較。將 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars) 指向空目錄以略過 `~/.claude` 下的所有內容，並從沒有 `.claude` 資料夾、`.mcp.json` 或 `CLAUDE.md` 的目錄啟動，以便也跳過專案設定。88如果問題在安全模式中持續存在，或您的設定本身令人懷疑，請與不從您常用設定載入任何內容的工作階段進行比較。將 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 指向空目錄以略過 `~/.claude` 下的所有內容，並從沒有 `.claude` 資料夾、`.mcp.json` 或 `CLAUDE.md` 的目錄啟動，以便也跳過專案設定。

89 89

90```bash theme={null}90```bash theme={null}

91cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude91cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

97* 在 Linux 和 Windows 上，您將被提示再次登入，因為認證儲存在設定目錄下97* 在 Linux 和 Windows 上，您將被提示再次登入，因為認證儲存在設定目錄下

98* 在 macOS 上，認證在 Keychain 中，並會轉移到乾淨的工作階段98* 在 macOS 上，認證在 Keychain 中，並會轉移到乾淨的工作階段

99 99

100如果問題在此消失，原因在於您的真實 `~/.claude` 或專案 `.claude` 檔案中的某處。一次一個地重新引入它們，方法是將檔案複製到臨時目錄或從您的專案啟動，以找到哪一個。如果它在乾淨的工作階段中持續存在，原因在於您的使用者和專案設定之外。執行 `/status` 以檢查是否啟用了受管設定，查找影響 Claude Code 的 [環境變數](/zh-TW/env-vars)，然後參閱 [Troubleshooting](/zh-TW/troubleshooting)。100如果問題在此消失，原因在於您的真實 `~/.claude` 或專案 `.claude` 檔案中的某處。一次一個地重新引入它們，方法是將檔案複製到臨時目錄或從您的專案啟動，以找到哪一個。如果它在乾淨的工作階段中持續存在，原因在於您的使用者和專案設定之外。執行 `/status` 以檢查是否啟用了受管設定，查找影響 Claude Code 的 [環境變數](/docs/zh-TW/env-vars)，然後參閱 [Troubleshooting](/docs/zh-TW/troubleshooting)。

101 101

102<h2 id="check-common-causes">102<h2 id="check-common-causes">

103 檢查常見原因103 檢查常見原因

107 107

108| 症狀 | 原因 | 修正 |108| 症狀 | 原因 | 修正 |

109| :------------------------------------------------------- | :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |109| :------------------------------------------------------- | :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

111| Hook 永遠不觸發 | `matcher` 在 v2.1.191 之前的版本中使用 `,` 作為分隔符 | {/* min-version: 2.1.191 */}Claude Code v2.1.191 或更新版本將 `,` 視為列表分隔符，如 `\|`。較早的版本將逗號評估為字面字元，因此 `"Edit,Write"` 不匹配任何內容。改用 `\|`，或升級 Claude Code。 |111| Hook 永遠不觸發 | `matcher` 在 v2.1.191 之前的版本中使用 `,` 作為分隔符 | Claude Code v2.1.191 或更新版本將 `,` 視為列表分隔符，如 `\|`。較早的版本將逗號評估為字面字元，因此 `"Edit,Write"` 不匹配任何內容。改用 `\|`，或升級 Claude Code。 |

113| Hook 永遠不觸發 | Hooks 在獨立檔案而不是 `settings.json` 中定義 | 專案或使用者設定沒有獨立的 hooks 檔案。在 `settings.json` 中的 `"hooks"` 鍵下定義 hooks。只有 [plugins](/zh-TW/plugins-reference#hooks) 載入獨立的 `hooks/hooks.json`。請參閱 [hook 設定](/zh-TW/hooks)。 |113| Hook 永遠不觸發 | Hooks 在獨立檔案而不是 `settings.json` 中定義 | 專案或使用者設定沒有獨立的 hooks 檔案。在 `settings.json` 中的 `"hooks"` 鍵下定義 hooks。只有 [plugins](/docs/zh-TW/plugins-reference#hooks) 載入獨立的 `hooks/hooks.json`。請參閱 [hook 設定](/docs/zh-TW/hooks)。 |

114| 全域設定的 Permissions、hooks 或 env 被忽略 | 設定已新增到 `~/.claude.json` | `~/.claude.json` 保存應用程式狀態和 UI 切換。`permissions`、`hooks` 和 `env` 屬於 `~/.claude/settings.json`。這是兩個不同的檔案。 |114| 全域設定的 Permissions、hooks 或 env 被忽略 | 設定已新增到 `~/.claude.json` | `~/.claude.json` 保存應用程式狀態和 UI 切換。`permissions`、`hooks` 和 `env` 屬於 `~/.claude/settings.json`。這是兩個不同的檔案。 |

115| `settings.json` 值似乎被忽略 | 相同的鍵在 `settings.local.json` 中設定 | `settings.local.json` 覆蓋 `settings.json`，兩者都覆蓋 `~/.claude/settings.json`。請參閱 [settings 優先順序](/zh-TW/settings#how-scopes-interact)。 |115| `settings.json` 值似乎被忽略 | 相同的鍵在 `settings.local.json` 中設定 | `settings.local.json` 覆蓋 `settings.json`，兩者都覆蓋 `~/.claude/settings.json`。請參閱 [settings 優先順序](/docs/zh-TW/settings#how-scopes-interact)。 |

117| Skill 出現在 `/skills` 中但 Claude 永遠不呼叫它 | Skill 在其 frontmatter 中有 `disable-model-invocation: true`，或其描述與您表述請求的方式不符 | 檢查 `/skills` 中的徽章：「user-only」標籤表示 Claude 不會自動觸發它。請參閱 [skill 呼叫](/zh-TW/skills)。 |117| Skill 出現在 `/skills` 中但 Claude 永遠不呼叫它 | Skill 在其 frontmatter 中有 `disable-model-invocation: true`，或其描述與您表述請求的方式不符 | 檢查 `/skills` 中的徽章：「user-only」標籤表示 Claude 不會自動觸發它。請參閱 [skill 呼叫](/docs/zh-TW/skills)。 |

118| 子目錄 `CLAUDE.md` 指令似乎被忽略 | 子目錄檔案按需載入，而不是在工作階段開始時載入 | 它們在 Claude 使用 Read 工具讀取該目錄中的檔案時載入，而不是在啟動時，也不是在寫入或建立檔案時。請參閱 [CLAUDE.md 檔案如何載入](/zh-TW/memory#how-claude-md-files-load)。 |118| 子目錄 `CLAUDE.md` 指令似乎被忽略 | 子目錄檔案按需載入，而不是在工作階段開始時載入 | 它們在 Claude 使用 Read 工具讀取該目錄中的檔案時載入，而不是在啟動時，也不是在寫入或建立檔案時。請參閱 [CLAUDE.md 檔案如何載入](/docs/zh-TW/memory#how-claude-md-files-load)。 |

119| 子代理忽略 `CLAUDE.md` 指令 | 內建的 Explore 和 Plan 代理會跳過 `CLAUDE.md`。自訂子代理以與主對話相同的方式載入它 | 對於 Explore 或 Plan，在您的委派提示中重新陳述指令。對於自訂子代理，將關鍵指令放在代理檔案主體中，該主體成為代理的系統提示。請參閱 [啟動時載入的內容](/zh-TW/sub-agents#what-loads-at-startup)。 |119| 子代理忽略 `CLAUDE.md` 指令 | 內建的 Explore 和 Plan 代理會跳過 `CLAUDE.md`。自訂子代理以與主對話相同的方式載入它 | 對於 Explore 或 Plan，在您的委派提示中重新陳述指令。對於自訂子代理，將關鍵指令放在代理檔案主體中，該主體成為代理的系統提示。請參閱 [啟動時載入的內容](/docs/zh-TW/sub-agents#what-loads-at-startup)。 |

122| 新增在 `settings.json` 中的 `mcpServers` 下的 MCP servers 永遠不出現 | `settings.json` 不讀取 `mcpServers` 鍵 | 在儲存庫根目錄的 `.mcp.json` 中定義專案 servers，或執行 `claude mcp add --scope user` 以取得使用者範圍的 servers。請參閱 [MCP 設定](/zh-TW/mcp)。 |122| 新增在 `settings.json` 中的 `mcpServers` 下的 MCP servers 永遠不出現 | `settings.json` 不讀取 `mcpServers` 鍵 | 在儲存庫根目錄的 `.mcp.json` 中定義專案 servers，或執行 `claude mcp add --scope user` 以取得使用者範圍的 servers。請參閱 [MCP 設定](/docs/zh-TW/mcp)。 |

126| `Bash(rm *)` 拒絕規則不阻止 `/bin/rm` 或 `find -delete` | 前綴規則匹配字面命令字串，而不是基礎可執行檔 | 為每個變體新增明確模式，或使用 [PreToolUse hook](/zh-TW/hooks-guide) 或 [sandbox](/zh-TW/sandboxing) 以獲得硬保證。 |126| `Bash(rm *)` 拒絕規則不阻止 `/bin/rm` 或 `find -delete` | 前綴規則匹配字面命令字串，而不是基礎可執行檔 | 為每個變體新增明確模式，或使用 [PreToolUse hook](/docs/zh-TW/hooks-guide) 或 [sandbox](/docs/zh-TW/sandboxing) 以獲得硬保證。 |

127 127

128<h2 id="related-resources">128<h2 id="related-resources">

129 相關資源129 相關資源

131 131

132如需每個設定表面的完整參考，請參閱專用頁面：132如需每個設定表面的完整參考，請參閱專用頁面：

133 133

134* **[`.claude` 目錄參考](/zh-TW/claude-directory)**：每個設定檔案位置及其讀取方式134* **[`.claude` 目錄參考](/docs/zh-TW/claude-directory)**：每個設定檔案位置及其讀取方式

135* **[Settings](/zh-TW/settings)**：優先順序和完整鍵清單135* **[Settings](/docs/zh-TW/settings)**：優先順序和完整鍵清單

136* **[Hooks 參考](/zh-TW/hooks)**：事件名稱、承載和 `--debug hooks` 輸出格式136* **[Hooks 參考](/docs/zh-TW/hooks)**：事件名稱、承載和 `--debug hooks` 輸出格式

137* **[MCP](/zh-TW/mcp)**：server 設定、核准和 `/mcp` 輸出137* **[MCP](/docs/zh-TW/mcp)**：server 設定、核准和 `/mcp` 輸出

138* **[Troubleshoot installation and login](/zh-TW/troubleshoot-install)**：`command not found`、PATH 和身份驗證問題138* **[Troubleshoot installation and login](/docs/zh-TW/troubleshoot-install)**：`command not found`、PATH 和身份驗證問題

139* **[Troubleshooting](/zh-TW/troubleshooting)**：效能、掛起和搜尋問題139* **[Troubleshooting](/docs/zh-TW/troubleshooting)**：效能、掛起和搜尋問題

desktop.md +72 −72

Details

17 For x64 processors17 For x64 processors

18 </Card>18 </Card>

19 19

~~20 <Card title="Get Claude for Linux (beta)" icon="linux" href="/en/desktop-linux">~~20 <Card title="Get Claude for Linux (beta)" icon="linux" href="/docs/en/desktop-linux">

21 apt or .deb for Ubuntu and Debian21 apt or .deb for Ubuntu and Debian

22 </Card>22 </Card>

23</CardGroup>23</CardGroup>

24 24

25For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/en/desktop-linux).25For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/docs/en/desktop-linux).

26 26

27安裝後，啟動 Claude，登入，然後點擊 **Code** 標籤。第一次在 Windows 上開啟時，您需要安裝 [Git for Windows](https://git-scm.com/downloads/win)；安裝後請重新啟動應用程式。如需您第一個會話的逐步說明，請參閱[快速入門指南](/zh-TW/desktop-quickstart)。27安裝後，啟動 Claude，登入，然後點擊 **Code** 標籤。第一次在 Windows 上開啟時，您需要安裝 [Git for Windows](https://git-scm.com/downloads/win)；安裝後請重新啟動應用程式。如需您第一個會話的逐步說明，請參閱[快速入門指南](/docs/zh-TW/desktop-quickstart)。

28 28

29在 Code 標籤中，每個對話都是一個**會話**：它有自己的聊天歷史記錄、專案資料夾和程式碼變更，獨立於任何其他會話。側邊欄列出您的會話，並讓您並行執行多個會話。在會話中，您可以：29在 Code 標籤中，每個對話都是一個**會話**：它有自己的聊天歷史記錄、專案資料夾和程式碼變更，獨立於任何其他會話。側邊欄列出您的會話，並讓您並行執行多個會話。在會話中，您可以：

30 30

36* 讓 Claude [開啟應用程式並控制您的螢幕](#let-claude-use-your-computer)36* 讓 Claude [開啟應用程式並控制您的螢幕](#let-claude-use-your-computer)

37* 在您的機器上、[雲端](#run-long-running-tasks-remotely)或 [SSH](#ssh-sessions) 上執行37* 在您的機器上、[雲端](#run-long-running-tasks-remotely)或 [SSH](#ssh-sessions) 上執行

38 38

39如需[排程定期工作](/zh-TW/desktop-scheduled-tasks)、[快捷鍵](#keyboard-shortcuts)或[從您的手機傳送任務](#sessions-from-dispatch)，請參閱連結的頁面和章節。如果您已經使用基於終端機的 CLI，請參閱 [CLI 比較](#coming-from-the-cli)以了解哪些內容可以轉移。39如需[排程定期工作](/docs/zh-TW/desktop-scheduled-tasks)、[快捷鍵](#keyboard-shortcuts)或[從您的手機傳送任務](#sessions-from-dispatch)，請參閱連結的頁面和章節。如果您已經使用基於終端機的 CLI，請參閱 [CLI 比較](#coming-from-the-cli)以了解哪些內容可以轉移。

40 40

41<h2 id="start-a-session">41<h2 id="start-a-session">

42 開始會話42 開始會話

44 44

45在發送第一條訊息之前，在提示區域中配置四項內容：45在發送第一條訊息之前，在提示區域中配置四項內容：

46 46

47* **環境**：選擇 Claude 執行的位置。選擇 **Local** 用於您的機器、**Remote** 用於 Anthropic 託管的雲端會話，[**SSH 連線**](#ssh-sessions)用於您管理的遠端機器，或在 Windows 上選擇 [**WSL 發行版**](/zh-TW/desktop-wsl)。請參閱[環境配置](#environment-configuration)。47* **環境**：選擇 Claude 執行的位置。選擇 **Local** 用於您的機器、**Remote** 用於 Anthropic 託管的雲端會話，[**SSH 連線**](#ssh-sessions)用於您管理的遠端機器，或在 Windows 上選擇 [**WSL 發行版**](/docs/zh-TW/desktop-wsl)。請參閱[環境配置](#environment-configuration)。

48* **專案資料夾**：選擇 Claude 工作的資料夾或儲存庫。對於遠端會話，您可以新增[多個儲存庫](#run-long-running-tasks-remotely)。48* **專案資料夾**：選擇 Claude 工作的資料夾或儲存庫。對於遠端會話，您可以新增[多個儲存庫](#run-long-running-tasks-remotely)。

~~49* **模型**：從傳送按鈕旁的下拉式選單中選擇[模型](/zh-TW/model-config#available-models)。您可以在會話期間變更此設定。~~49* **模型**：從傳送按鈕旁的下拉式選單中選擇[模型](/docs/zh-TW/model-config#available-models)。您可以在會話期間變更此設定。

50* **權限模式**：從[模式選擇器](#choose-a-permission-mode)中選擇 Claude 擁有多少自主權。您可以在會話期間變更此設定。50* **權限模式**：從[模式選擇器](#choose-a-permission-mode)中選擇 Claude 擁有多少自主權。您可以在會話期間變更此設定。

51 51

52輸入您的任務並按 **Enter** 開始。每個會話都會追蹤自己的上下文並獨立進行變更。52輸入您的任務並按 **Enter** 開始。每個會話都會追蹤自己的上下文並獨立進行變更。

80 80

81權限模式控制 Claude 在會話期間擁有多少自主權：它是否在編輯檔案、執行命令或兩者之前詢問。您可以隨時使用傳送按鈕旁的模式選擇器切換模式。從「Manual」開始，以查看 Claude 確切執行的操作，然後隨著您變得更加熟悉，移至「Accept edits」或「Plan」。81權限模式控制 Claude 在會話期間擁有多少自主權：它是否在編輯檔案、執行命令或兩者之前詢問。您可以隨時使用傳送按鈕旁的模式選擇器切換模式。從「Manual」開始，以查看 Claude 確切執行的操作，然後隨著您變得更加熟悉，移至「Accept edits」或「Plan」。

82 82

83若要為新的本機會話設定預設模式，請將 `permissions.defaultMode` 新增到您的[設定檔](/zh-TW/settings#settings-files)。桌面應用程式讀取與 CLI 相同的設定檔。您在選擇器中選擇的模式會記住每個資料夾，並優先於該資料夾的 `defaultMode`，除了 Plan，它僅適用於目前會話。83若要為新的本機會話設定預設模式，請將 `permissions.defaultMode` 新增到您的[設定檔](/docs/zh-TW/settings#settings-files)。桌面應用程式讀取與 CLI 相同的設定檔。您在選擇器中選擇的模式會記住每個資料夾，並優先於該資料夾的 `defaultMode`，除了 Plan，它僅適用於目前會話。

84 84

85| 模式 | 設定金鑰 | 行為 |85| 模式 | 設定金鑰 | 行為 |

86| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |86| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

91| **Bypass permissions** | `bypassPermissions` | Claude 執行時不會有任何權限提示，除了由明確的[詢問規則](/zh-TW/permissions#manage-permissions)強制執行的提示、連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)、標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，或當 Claude [在外部網站上執行操作](#browse-external-sites)時由安全分類器強制執行的提示；相當於 CLI 中的 `--dangerously-skip-permissions`。在 Pro 和 Max 方案上，在您的「設定」→「Claude Code」下的「Allow bypass permissions mode」中啟用它；在 Team 和 Enterprise 方案上沒有「設定」切換開關，組織政策會改為控制它。僅在沙箱容器或虛擬機器中使用。 |91| **Bypass permissions** | `bypassPermissions` | Claude 執行時不會有任何權限提示，除了由明確的[詢問規則](/docs/zh-TW/permissions#manage-permissions)強制執行的提示、連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，或當 Claude [在外部網站上執行操作](#browse-external-sites)時由安全分類器強制執行的提示；相當於 CLI 中的 `--dangerously-skip-permissions`。在 Pro 和 Max 方案上，在您的「設定」→「Claude Code」下的「Allow bypass permissions mode」中啟用它；在 Team 和 Enterprise 方案上沒有「設定」切換開關，組織政策會改為控制它。僅在沙箱容器或虛擬機器中使用。 |

92 92

93較早版本的 Code 標籤將這些模式標記為 Ask permissions、Auto accept edits 和 Plan mode。93較早版本的 Code 標籤將這些模式標記為 Ask permissions、Auto accept edits 和 Plan mode。

94 94

~~95`dontAsk` 權限模式僅在 [CLI](/zh-TW/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 中可用。~~95`dontAsk` 權限模式僅在 [CLI](/docs/zh-TW/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 中可用。

96 96

97<span id="auto-mode-availability" />97<span id="auto-mode-availability" />

98 98

99Auto mode 在 Anthropic API 上提供給所有使用者，需要 Claude Opus 4.6 或更新版本，或 Sonnet 4.6 或更新版本。在路由 Desktop 至 Google Cloud 的 Agent Platform 的企業部署中，auto mode [預設為可用](/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)，且僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。{/* min-version: 2.1.207 */}在 Claude Code v2.1.207 之前，Google Cloud 的 Agent Platform 上的企業部署必須設定 `CLAUDE_CODE_ENABLE_AUTO_MODE` 以啟用 auto mode。99Auto mode 在 Anthropic API 上提供給所有使用者，需要 Claude Opus 4.6 或更新版本，或 Sonnet 4.6 或更新版本。在路由 Desktop 至 Google Cloud 的 Agent Platform 的企業部署中，auto mode [預設為可用](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)，且僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。在 Claude Code v2.1.207 之前，Google Cloud 的 Agent Platform 上的企業部署必須設定 `CLAUDE_CODE_ENABLE_AUTO_MODE` 以啟用 auto mode。

100 100

101<Tip title="最佳實踐">101<Tip title="最佳實踐">

102 在 Plan 中開始複雜任務，以便 Claude 在進行變更之前規劃方法。一旦您批准計畫，切換到「Accept edits」或「Manual」以執行它。有關此工作流程的更多資訊，請參閱[先探索，然後計畫，然後編碼](/zh-TW/best-practices#explore-first-then-plan-then-code)。102 在 Plan 中開始複雜任務，以便 Claude 在進行變更之前規劃方法。一旦您批准計畫，切換到「Accept edits」或「Manual」以執行它。有關此工作流程的更多資訊，請參閱[先探索，然後計畫，然後編碼](/docs/zh-TW/best-practices#explore-first-then-plan-then-code)。

103</Tip>103</Tip>

104 104

105雲端會話支援「Accept edits」、「Plan」和「Auto」。「Accept edits」對應於 `default` 模式：雲端會話預先批准檔案編輯，因此選擇器顯示「Accept edits」而不是「Manual」。「Bypass permissions」不可用，因為雲端環境已經是沙箱化的。105雲端會話支援「Accept edits」、「Plan」和「Auto」。「Accept edits」對應於 `default` 模式：雲端會話預先批准檔案編輯，因此選擇器顯示「Accept edits」而不是「Manual」。「Bypass permissions」不可用，因為雲端環境已經是沙箱化的。

143 143

144Claude 第一次在外部網站上執行操作時，會出現一張權限卡，Claude 會等待您的選擇：**Allow once**、**Always allow** 或 **Deny**。**Allow once** 批准操作而不保存任何內容。**Always allow** 在您的裝置上保存該網站的批准，您可以在「設定」中撤銷它。每個網站都需要自己的批准，包括子網域。您的本機開發伺服器和專案檔案不需要批准，因此[自動驗證](#auto-verify-changes)可以繼續進行而不會出現提示。144Claude 第一次在外部網站上執行操作時，會出現一張權限卡，Claude 會等待您的選擇：**Allow once**、**Always allow** 或 **Deny**。**Allow once** 批准操作而不保存任何內容。**Always allow** 在您的裝置上保存該網站的批准，您可以在「設定」中撤銷它。每個網站都需要自己的批准，包括子網域。您的本機開發伺服器和專案檔案不需要批准，因此[自動驗證](#auto-verify-changes)可以繼續進行而不會出現提示。

145 145

146即使在已批准的網站上，Claude 也不會在沒有您的輸入的情況下購買商品、建立帳戶或繞過 CAPTCHA。在「Browser」窗格中瀏覽使用與 [Chrome 中的 Claude 擴充功能](/zh-TW/chrome)相同的安全模型。有關 Claude 如何處理敏感網站和危險操作的資訊，請參閱[安全地使用 Chrome 中的 Claude](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)。146即使在已批准的網站上，Claude 也不會在沒有您的輸入的情況下購買商品、建立帳戶或繞過 CAPTCHA。在「Browser」窗格中瀏覽使用與 [Chrome 中的 Claude 擴充功能](/docs/zh-TW/chrome)相同的安全模型。有關 Claude 如何處理敏感網站和危險操作的資訊，請參閱[安全地使用 Chrome 中的 Claude](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)。

147 147

148<h4 id="choose-between-the-browser-and-the-chrome-extension">148<h4 id="choose-between-the-browser-and-the-chrome-extension">

149 在「Browser」和 Chrome 擴充功能之間選擇149 在「Browser」和 Chrome 擴充功能之間選擇

150</h4>150</h4>

151 151

152「Browser」窗格使用乾淨的瀏覽器設定檔，與您的個人瀏覽器分開，沒有您保存的登入或歷史記錄。使用它來建立和測試您的應用程式，以及不需要您身份的網站。當您想讓 Claude 在您的已登入會話中充當您時，請改用 [Chrome 中的 Claude 擴充功能](/zh-TW/chrome)，它會共享您瀏覽器的登入狀態。152「Browser」窗格使用乾淨的瀏覽器設定檔，與您的個人瀏覽器分開，沒有您保存的登入或歷史記錄。使用它來建立和測試您的應用程式，以及不需要您身份的網站。當您想讓 Claude 在您的已登入會話中充當您時，請改用 [Chrome 中的 Claude 擴充功能](/docs/zh-TW/chrome)，它會共享您瀏覽器的登入狀態。

153 153

154<h4 id="restrict-external-browsing-for-your-organization">154<h4 id="restrict-external-browsing-for-your-organization">

155 限制您的組織的外部瀏覽155 限制您的組織的外部瀏覽

273| `1`–`9` | 在開啟的選單中選擇項目 |273| `1`–`9` | 在開啟的選單中選擇項目 |

274 274

275這些快捷鍵僅適用於 Code 標籤。終端機型 [interactive mode 快捷鍵](/zh-TW/interactive-mode#keyboard-shortcuts)（如 `Shift+Tab` 以循環模式）不適用於 Desktop。275這些快捷鍵僅適用於 Code 標籤。終端機型 [interactive mode 快捷鍵](/docs/zh-TW/interactive-mode#keyboard-shortcuts)（如 `Shift+Tab` 以循環模式）不適用於 Desktop。

276 276

277<h3 id="check-usage">277<h3 id="check-usage">

278 檢查使用情況278 檢查使用情況

293電腦使用預設為關閉。[在設定中啟用它](#enable-computer-use)，然後 Claude 才能控制您的螢幕。在 macOS 上，您還需要授予協助工具和螢幕錄製權限。293電腦使用預設為關閉。[在設定中啟用它](#enable-computer-use)，然後 Claude 才能控制您的螢幕。在 macOS 上，您還需要授予協助工具和螢幕錄製權限。

294 294

295<Warning>295<Warning>

296 與[沙箱化 Bash 工具](/zh-TW/sandboxing)不同，電腦使用在您的實際桌面上執行，可以存取您批准的任何內容。Claude 會檢查每個操作並標記螢幕上內容的潛在提示注入，但信任邊界不同。有關最佳實踐，請參閱[電腦使用安全指南](https://support.claude.com/en/articles/14128542)。296 與[沙箱化 Bash 工具](/docs/zh-TW/sandboxing)不同，電腦使用在您的實際桌面上執行，可以存取您批准的任何內容。Claude 會檢查每個操作並標記螢幕上內容的潛在提示注入，但信任邊界不同。有關最佳實踐，請參閱[電腦使用安全指南](https://support.claude.com/en/articles/14128542)。

297</Warning>297</Warning>

298 298

299<h3 id="when-computer-use-applies">299<h3 id="when-computer-use-applies">

304 304

305* 如果您有服務的[連接器](#connect-external-tools)，Claude 會使用連接器。305* 如果您有服務的[連接器](#connect-external-tools)，Claude 會使用連接器。

306* 如果任務是 shell 命令，Claude 會使用 Bash。306* 如果任務是 shell 命令，Claude 會使用 Bash。

307* 如果任務是瀏覽器工作且您已設定[Chrome 中的 Claude](/zh-TW/chrome)，Claude 會使用它。307* 如果任務是瀏覽器工作且您已設定[Chrome 中的 Claude](/docs/zh-TW/chrome)，Claude 會使用它。

308* 如果以上都不適用，Claude 會使用電腦使用。308* 如果以上都不適用，Claude 會使用電腦使用。

309 309

310[每個應用程式的存取層級](#app-permissions)強化了這一點：瀏覽器限制為僅檢視，終端機和 IDE 限制為僅點擊，引導 Claude 使用專用工具，即使電腦使用處於活動狀態。螢幕控制保留給其他工具無法到達的內容，例如原生應用程式、硬體控制面板、行動模擬器或沒有 API 的專有工具。310[每個應用程式的存取層級](#app-permissions)強化了這一點：瀏覽器限制為僅檢視，終端機和 IDE 限制為僅點擊，引導 Claude 使用專用工具，即使電腦使用處於活動狀態。螢幕控制保留給其他工具無法到達的內容，例如原生應用程式、硬體控制面板、行動模擬器或沒有 API 的專有工具。

317 317

318<Steps>318<Steps>

319 <Step title="更新桌面應用程式">319 <Step title="更新桌面應用程式">

320 確保您有最新版本的 Claude Desktop。在 macOS 和 Windows 上，在 [claude.com/download](https://claude.com/download) 下載或更新；在 Linux 上，透過您的套件管理員更新（[說明](/zh-TW/desktop-linux)）。然後重新啟動應用程式。320 確保您有最新版本的 Claude Desktop。在 macOS 和 Windows 上，在 [claude.com/download](https://claude.com/download) 下載或更新；在 Linux 上，透過您的套件管理員更新（[說明](/docs/zh-TW/desktop-linux)）。然後重新啟動應用程式。

321 </Step>321 </Step>

322 322

323 <Step title="開啟切換">323 <Step title="開啟切換">

367 使用會話並行工作367 使用會話並行工作

368</h3>368</h3>

369 369

370點擊側邊欄中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，以並行處理多個任務。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 以循環瀏覽側邊欄中的會話。對於 Git 儲存庫，每個會話都會使用 [Git worktrees](/zh-TW/worktrees) 獲得自己的隔離專案副本，因此一個會話中的變更不會影響其他會話，直到您提交它們。370點擊側邊欄中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，以並行處理多個任務。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 以循環瀏覽側邊欄中的會話。對於 Git 儲存庫，每個會話都會使用 [Git worktrees](/docs/zh-TW/worktrees) 獲得自己的隔離專案副本，因此一個會話中的變更不會影響其他會話，直到您提交它們。

371 371

372若要同時檢視兩個會話，請在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl**，然後點擊側邊欄中的會話。會話會在您已開啟的會話旁邊的第二個窗格中開啟。當分割處於活動狀態時，點擊另一個側邊欄會話會取代具有焦點的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 以關閉焦點窗格並返回單一會話。372若要同時檢視兩個會話，請在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl**，然後點擊側邊欄中的會話。會話會在您已開啟的會話旁邊的第二個窗格中開啟。當分割處於活動狀態時，點擊另一個側邊欄會話會取代具有焦點的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 以關閉焦點窗格並返回單一會話。

373 373

374Worktrees 預設儲存在 `<project-root>/.claude/worktrees/` 中。您可以在「設定」→「Claude Code」下的「Worktree location」中將其變更為自訂目錄。您也可以設定一個分支前綴，該前綴會被加在每個 worktree 分支名稱前面，這對於保持 Claude 建立的分支井然有序很有用。若要在完成後移除 worktree，請將滑鼠懸停在側邊欄中的會話上，然後點擊存檔圖示。若要在 PR 合併或關閉後自動存檔會話，請在「設定」→「Claude Code」中開啟 **Auto-archive after PR merge or close**。自動存檔僅適用於已完成執行的本機會話。374Worktrees 預設儲存在 `<project-root>/.claude/worktrees/` 中。您可以在「設定」→「Claude Code」下的「Worktree location」中將其變更為自訂目錄。您也可以設定一個分支前綴，該前綴會被加在每個 worktree 分支名稱前面，這對於保持 Claude 建立的分支井然有序很有用。若要在完成後移除 worktree，請將滑鼠懸停在側邊欄中的會話上，然後點擊存檔圖示。若要在 PR 合併或關閉後自動存檔會話，請在「設定」→「Claude Code」中開啟 **Auto-archive after PR merge or close**。自動存檔僅適用於已完成執行的本機會話。

375 375

376若要在新 worktrees 中包含 gitignored 檔案（如 `.env`），請在您的專案根目錄中建立 [`.worktreeinclude` 檔案](/zh-TW/worktrees#copy-gitignored-files-into-worktrees)。376若要在新 worktrees 中包含 gitignored 檔案（如 `.env`），請在您的專案根目錄中建立 [`.worktreeinclude` 檔案](/docs/zh-TW/worktrees#copy-gitignored-files-into-worktrees)。

377 377

378<Note>378<Note>

379 會話隔離需要 [Git](https://git-scm.com/downloads)。大多數 Mac 預設包含 Git。在終端機中執行 `git --version` 進行檢查。在 Windows 上，Code 標籤需要 Git 才能運作：[下載 Git for Windows](https://git-scm.com/downloads/win)、安裝它，然後重新啟動應用程式。如果您遇到 Git 錯誤，請在 [Cowork 標籤](https://claude.com/product/cowork) 中詢問 Claude 以幫助排除您的設定問題。379 會話隔離需要 [Git](https://git-scm.com/downloads)。大多數 Mac 預設包含 Git。在終端機中執行 `git --version` 進行檢查。在 Windows 上，Code 標籤需要 Git 才能運作：[下載 Git for Windows](https://git-scm.com/downloads/win)、安裝它，然後重新啟動應用程式。如果您遇到 Git 錯誤，請在 [Cowork 標籤](https://claude.com/product/cowork) 中詢問 Claude 以幫助排除您的設定問題。

380</Note>380</Note>

381 381

382使用側邊欄頂部的控制項按狀態、專案或環境篩選會話，並按專案分組會話。若要重新命名會話，請點擊活動會話頂部工具列中的會話標題。若要檢查上下文使用情況，請參閱[檢查使用情況](#check-usage)。當上下文填滿時，Claude 會自動總結對話並繼續工作。您也可以輸入 `/compact` 來更早觸發總結並釋放上下文空間。有關壓縮如何運作的詳細資訊，請參閱[上下文視窗](/zh-TW/how-claude-code-works#the-context-window)。382使用側邊欄頂部的控制項按狀態、專案或環境篩選會話，並按專案分組會話。若要重新命名會話，請點擊活動會話頂部工具列中的會話標題。若要檢查上下文使用情況，請參閱[檢查使用情況](#check-usage)。當上下文填滿時，Claude 會自動總結對話並繼續工作。您也可以輸入 `/compact` 來更早觸發總結並釋放上下文空間。有關壓縮如何運作的詳細資訊，請參閱[上下文視窗](/docs/zh-TW/how-claude-code-works#the-context-window)。

383 383

384桌面應用程式會在 Code 會話完成任務且您目前未檢視該會話時傳送作業系統通知。384桌面應用程式會在 Code 會話完成任務且您目前未檢視該會話時傳送作業系統通知。

385 385

395 觀看背景任務395 觀看背景任務

396</h3>396</h3>

397 397

398任務窗格顯示在目前會話內執行的背景工作：子代理、背景 shell 命令和[動態工作流程](/zh-TW/workflows)。從 **Views** 選單開啟它或將其拖入您的佈局。398任務窗格顯示在目前會話內執行的背景工作：子代理、背景 shell 命令和[動態工作流程](/docs/zh-TW/workflows)。從 **Views** 選單開啟它或將其拖入您的佈局。

399 399

400點擊任何項目以在子代理窗格中查看其輸出或停止它。若要查看其他會話正在執行的操作，請使用[側邊欄](#work-in-parallel-with-sessions)。400點擊任何項目以在子代理窗格中查看其輸出或停止它。若要查看其他會話正在執行的操作，請使用[側邊欄](#work-in-parallel-with-sessions)。

401 401

407 407

408遠端會話也支援多個儲存庫。選擇雲端環境後，點擊儲存庫藥丸旁的 **+** 按鈕，將其他儲存庫新增到會話。每個儲存庫都有自己的分支選擇器。這對於跨越多個程式碼庫的任務很有用，例如更新共用程式庫及其使用者。408遠端會話也支援多個儲存庫。選擇雲端環境後，點擊儲存庫藥丸旁的 **+** 按鈕，將其他儲存庫新增到會話。每個儲存庫都有自己的分支選擇器。這對於跨越多個程式碼庫的任務很有用，例如更新共用程式庫及其使用者。

409 409

410有關遠端會話如何運作的更多資訊，請參閱[網路上的 Claude Code](/zh-TW/claude-code-on-the-web)。410有關遠端會話如何運作的更多資訊，請參閱[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web)。

411 411

412<h3 id="continue-in-another-surface">412<h3 id="continue-in-another-surface">

413 在另一個介面中繼續413 在另一個介面中繼續

432 432

433有關設定、配對和 Dispatch 設定，請參閱 [Dispatch 幫助文章](https://support.claude.com/en/articles/13947068)。Dispatch 需要 Pro 或 Max 計畫，在 Team 或 Enterprise 計畫上不可用。433有關設定、配對和 Dispatch 設定，請參閱 [Dispatch 幫助文章](https://support.claude.com/en/articles/13947068)。Dispatch 需要 Pro 或 Max 計畫，在 Team 或 Enterprise 計畫上不可用。

434 434

435Dispatch 是當您遠離終端機時與 Claude 合作的多種方式之一。請參閱[平台和整合](/zh-TW/platforms#work-when-you-are-away-from-your-terminal)以將其與遠端控制、頻道、Slack 和排程任務進行比較。435Dispatch 是當您遠離終端機時與 Claude 合作的多種方式之一。請參閱[平台和整合](/docs/zh-TW/platforms#work-when-you-are-away-from-your-terminal)以將其與遠端控制、頻道、Slack 和排程任務進行比較。

436 436

437<h2 id="extend-claude-code">437<h2 id="extend-claude-code">

438 擴展 Claude Code438 擴展 Claude Code

444 連接外部工具444 連接外部工具

445</h3>445</h3>

446 446

447對於本機和 [SSH](#ssh-sessions) 會話，點擊提示框旁的 **+** 按鈕，然後選擇 **Connectors** 以新增 Google Calendar、Slack、GitHub、Linear、Notion 等整合。您可以在會話之前或期間新增連接器。**+** 按鈕在雲端會話中不可用，但 [routines](/zh-TW/routines) 在 routine 建立時配置連接器。447對於本機和 [SSH](#ssh-sessions) 會話，點擊提示框旁的 **+** 按鈕，然後選擇 **Connectors** 以新增 Google Calendar、Slack、GitHub、Linear、Notion 等整合。您可以在會話之前或期間新增連接器。**+** 按鈕在雲端會話中不可用，但 [routines](/docs/zh-TW/routines) 在 routine 建立時配置連接器。

448 448

449若要管理或斷開連接器，請在桌面應用程式中前往「設定」→「Connectors」，或從提示框中的「Connectors」選單中選擇 **Manage connectors**。449若要管理或斷開連接器，請在桌面應用程式中前往「設定」→「Connectors」，或從提示框中的「Connectors」選單中選擇 **Manage connectors**。

450 450

451連接後，Claude 可以讀取您的日曆、傳送訊息、建立問題，並直接與您的工具互動。您可以詢問 Claude 在您的會話中配置了哪些連接器。451連接後，Claude 可以讀取您的日曆、傳送訊息、建立問題，並直接與您的工具互動。您可以詢問 Claude 在您的會話中配置了哪些連接器。

452 452

453連接器是 [MCP servers](/zh-TW/mcp)，具有圖形設定流程。使用它們可以快速與支援的服務整合。對於「Connectors」中未列出的整合，透過 [settings files](/zh-TW/mcp#installing-mcp-servers) 手動新增 MCP servers。您也可以 [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)。453連接器是 [MCP servers](/docs/zh-TW/mcp)，具有圖形設定流程。使用它們可以快速與支援的服務整合。對於「Connectors」中未列出的整合，透過 [settings files](/docs/zh-TW/mcp#installing-mcp-servers) 手動新增 MCP servers。您也可以 [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)。

454 454

455<h3 id="use-skills">455<h3 id="use-skills">

456 使用 skills456 使用 skills

457</h3>457</h3>

458 458

459[Skills](/zh-TW/skills) 擴展 Claude 可以執行的操作。Claude 在相關時自動載入它們，或者您可以直接呼叫一個：在提示框中輸入 `/` 或點擊 **+** 按鈕並選擇 **Slash commands** 以瀏覽可用的內容。這包括 [built-in commands](/zh-TW/commands)、您的 [custom skills](/zh-TW/skills#create-your-first-skill)、來自您程式碼庫的專案 skills，以及來自任何 [installed plugins](/zh-TW/plugins) 的 skills。選擇一個，它會在輸入欄位中突出顯示。在其後輸入您的任務並照常傳送。459[Skills](/docs/zh-TW/skills) 擴展 Claude 可以執行的操作。Claude 在相關時自動載入它們，或者您可以直接呼叫一個：在提示框中輸入 `/` 或點擊 **+** 按鈕並選擇 **Slash commands** 以瀏覽可用的內容。這包括 [built-in commands](/docs/zh-TW/commands)、您的 [custom skills](/docs/zh-TW/skills#create-your-first-skill)、來自您程式碼庫的專案 skills，以及來自任何 [installed plugins](/docs/zh-TW/plugins) 的 skills。選擇一個，它會在輸入欄位中突出顯示。在其後輸入您的任務並照常傳送。

460 460

461您可以在 Claude 正在工作時傳送命令，就像任何其他訊息一樣，會話在回合完成後會回到閒置狀態。在 v2.1.206 之前，在回合中途傳送的命令可能會導致會話顯示為執行中，而您之後傳送的訊息未被傳遞。461您可以在 Claude 正在工作時傳送命令，就像任何其他訊息一樣，會話在回合完成後會回到閒置狀態。在 v2.1.206 之前，在回合中途傳送的命令可能會導致會話顯示為執行中，而您之後傳送的訊息未被傳遞。

462 462

464 安裝 plugins464 安裝 plugins

465</h3>465</h3>

466 466

467[Plugins](/zh-TW/plugins) 是可重複使用的套件，可將 skills、agents、hooks、MCP servers 和 LSP 配置新增到 Claude Code。您可以從桌面應用程式安裝 plugins，而無需使用終端機。467[Plugins](/docs/zh-TW/plugins) 是可重複使用的套件，可將 skills、agents、hooks、MCP servers 和 LSP 配置新增到 Claude Code。您可以從桌面應用程式安裝 plugins，而無需使用終端機。

468 468

469對於本機和 [SSH](#ssh-sessions) 會話，點擊提示框旁的 **+** 按鈕，然後選擇 **Plugins** 以查看您已安裝的 plugins 及其 skills。若要新增 plugin，從子選單中選擇 **Add plugin** 以開啟 plugin 瀏覽器，它顯示來自您配置的 [marketplaces](/zh-TW/plugin-marketplaces)（包括官方 Anthropic 市場）的可用 plugins。選擇 **Manage plugins** 以啟用、停用或解除安裝 plugins。469對於本機和 [SSH](#ssh-sessions) 會話，點擊提示框旁的 **+** 按鈕，然後選擇 **Plugins** 以查看您已安裝的 plugins 及其 skills。若要新增 plugin，從子選單中選擇 **Add plugin** 以開啟 plugin 瀏覽器，它顯示來自您配置的 [marketplaces](/docs/zh-TW/plugin-marketplaces)（包括官方 Anthropic 市場）的可用 plugins。選擇 **Manage plugins** 以啟用、停用或解除安裝 plugins。

470 470

471Plugins 可以限定於您的使用者帳戶、特定專案或僅本機。如果您的組織集中管理 plugins，這些 plugins 在桌面會話中的可用方式與在 CLI 中相同。雲端會話不提供 Plugins。有關完整的 plugin 參考（包括建立您自己的 plugins），請參閱 [plugins](/zh-TW/plugins)。471Plugins 可以限定於您的使用者帳戶、特定專案或僅本機。如果您的組織集中管理 plugins，這些 plugins 在桌面會話中的可用方式與在 CLI 中相同。雲端會話不提供 Plugins。有關完整的 plugin 參考（包括建立您自己的 plugins），請參閱 [plugins](/docs/zh-TW/plugins)。

472 472

473<h3 id="configure-preview-servers">473<h3 id="configure-preview-servers">

474 配置預覽伺服器474 配置預覽伺服器

634* **Local**：在您的機器上執行，直接存取您的檔案634* **Local**：在您的機器上執行，直接存取您的檔案

635* **Remote**：在 Anthropic 的雲端基礎設施上執行。即使您關閉應用程式，會話也會繼續。635* **Remote**：在 Anthropic 的雲端基礎設施上執行。即使您關閉應用程式，會話也會繼續。

636* **SSH**：在您透過 SSH 連接的遠端機器上執行，例如您自己的伺服器、雲端虛擬機器或開發容器636* **SSH**：在您透過 SSH 連接的遠端機器上執行，例如您自己的伺服器、雲端虛擬機器或開發容器

637* **WSL** (Windows)：在您機器上的 [WSL 2 發行版](/zh-TW/desktop-wsl)內執行，使用其 Linux 工具鏈和原生路徑637* **WSL** (Windows)：在您機器上的 [WSL 2 發行版](/docs/zh-TW/desktop-wsl)內執行，使用其 Linux 工具鏈和原生路徑

638 638

639<h3 id="local-sessions">639<h3 id="local-sessions">

640 本機會話640 本機會話

642 642

643桌面應用程式並不總是繼承您的完整 shell 環境。在 macOS 上，當您從 Dock 或 Finder 啟動應用程式時，它會讀取您的 shell 設定檔（如 `~/.zshrc` 或 `~/.bashrc`）以提取 `PATH` 和一組固定的 Claude Code 變數，但您在那裡匯出的其他變數不會被拾取。在 Windows 上，應用程式繼承使用者和系統環境變數，但不讀取 PowerShell 設定檔。643桌面應用程式並不總是繼承您的完整 shell 環境。在 macOS 上，當您從 Dock 或 Finder 啟動應用程式時，它會讀取您的 shell 設定檔（如 `~/.zshrc` 或 `~/.bashrc`）以提取 `PATH` 和一組固定的 Claude Code 變數，但您在那裡匯出的其他變數不會被拾取。在 Windows 上，應用程式繼承使用者和系統環境變數，但不讀取 PowerShell 設定檔。

644 644

645若要在任何平台上為本機會話和開發伺服器設定環境變數，請在提示框中開啟環境下拉式選單，將滑鼠懸停在 **Local** 上，然後點擊齒輪圖示以開啟本機環境編輯器。您在此處儲存的變數會在您的機器上加密儲存，並適用於您啟動的每個本機會話和預覽伺服器。您也可以將變數新增到 `~/.claude/settings.json` 檔案中的 `env` 金鑰，儘管這些僅到達 Claude 會話而不是開發伺服器。有關支援的變數的完整清單，請參閱[環境變數](/zh-TW/env-vars)。645若要在任何平台上為本機會話和開發伺服器設定環境變數，請在提示框中開啟環境下拉式選單，將滑鼠懸停在 **Local** 上，然後點擊齒輪圖示以開啟本機環境編輯器。您在此處儲存的變數會在您的機器上加密儲存，並適用於您啟動的每個本機會話和預覽伺服器。您也可以將變數新增到 `~/.claude/settings.json` 檔案中的 `env` 金鑰，儘管這些僅到達 Claude 會話而不是開發伺服器。有關支援的變數的完整清單，請參閱[環境變數](/docs/zh-TW/env-vars)。

646 646

647[Extended thinking](/zh-TW/model-config#extended-thinking) 預設啟用，這改進了複雜推理任務的效能，但使用額外的 tokens。若要停用思考，請在本機環境編輯器中將 `MAX_THINKING_TOKENS` 設定為 `0`；這對 Fable 5 沒有影響，Fable 5 始終使用 extended thinking。在[第三方提供者](/zh-TW/third-party-integrations)上，`0` 會改為省略 `thinking` 參數，自適應推理模型可能仍會思考。在具有[自適應推理](/zh-TW/model-config#adjust-effort-level)的模型上，任何其他 `MAX_THINKING_TOKENS` 值都會被忽略，因為自適應推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，將 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 設定為 `1` 以使用固定思考預算；Fable 5、Sonnet 5 和 Opus 4.7 及更新版本始終使用自適應推理，沒有固定預算模式。647[Extended thinking](/docs/zh-TW/model-config#extended-thinking) 預設啟用，這改進了複雜推理任務的效能，但使用額外的 tokens。若要停用思考，請在本機環境編輯器中將 `MAX_THINKING_TOKENS` 設定為 `0`；這對 Fable 5 沒有影響，Fable 5 始終使用 extended thinking。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，`0` 會改為省略 `thinking` 參數，自適應推理模型可能仍會思考。在具有[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型上，任何其他 `MAX_THINKING_TOKENS` 值都會被忽略，因為自適應推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，將 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 設定為 `1` 以使用固定思考預算；Fable 5、Sonnet 5 和 Opus 4.7 及更新版本始終使用自適應推理，沒有固定預算模式。

648 648

649<h3 id="cloud-sessions">649<h3 id="cloud-sessions">

650 雲端會話650 雲端會話

651</h3>651</h3>

652 652

653雲端會話即使您關閉應用程式也會在背景繼續。使用情況計入您的[訂閱計畫限制](/zh-TW/costs)，沒有單獨的計算費用。653雲端會話即使您關閉應用程式也會在背景繼續。使用情況計入您的[訂閱計畫限制](/docs/zh-TW/costs)，沒有單獨的計算費用。

654 654

655您可以建立具有不同網路存取級別和環境變數的自訂雲端環境。在開始雲端會話時選擇環境下拉式選單，然後選擇 **Add environment**。有關配置網路存取和環境變數的詳細資訊，請參閱[雲端環境](/zh-TW/claude-code-on-the-web#the-cloud-environment)。655您可以建立具有不同網路存取級別和環境變數的自訂雲端環境。在開始雲端會話時選擇環境下拉式選單，然後選擇 **Add environment**。有關配置網路存取和環境變數的詳細資訊，請參閱[雲端環境](/docs/zh-TW/claude-code-on-the-web#the-cloud-environment)。

656 656

657<h3 id="ssh-sessions">657<h3 id="ssh-sessions">

658 SSH 會話658 SSH 會話

675 為您的團隊預先配置 SSH 連線675 為您的團隊預先配置 SSH 連線

676</h4>676</h4>

677 677

678管理員可以透過將 `sshConfigs` 新增到[受管設定](/zh-TW/settings#settings-precedence)檔案來將 SSH 連線分發給團隊成員。以這種方式定義的連線會自動出現在每個使用者的環境下拉式選單中，並顯示為受管，因此使用者可以選擇它們，但無法在應用程式中編輯或刪除它們。678管理員可以透過將 `sshConfigs` 新增到[受管設定](/docs/zh-TW/settings#settings-precedence)檔案來將 SSH 連線分發給團隊成員。以這種方式定義的連線會自動出現在每個使用者的環境下拉式選單中，並顯示為受管，因此使用者可以選擇它們，但無法在應用程式中編輯或刪除它們。

679 679

680以下範例預先配置了一個在遠端主機上的 `~/projects` 中開啟的單一連線：680以下範例預先配置了一個在遠端主機上的 `~/projects` 中開啟的單一連線：

681 681

700 限制使用者可以連接的 SSH 主機700 限制使用者可以連接的 SSH 主機

701</h4>701</h4>

702 702

703管理員可以透過將 `sshHostAllowlist` 新增到[受管設定](/zh-TW/settings#settings-precedence)檔案來限制 Desktop 的 SSH 會話到已核准的主機集合。設定後，使用者只能連接到其解析的主機名稱與其中一個模式相符的主機。將其設定為空陣列以完全停用 SSH 會話。703管理員可以透過將 `sshHostAllowlist` 新增到[受管設定](/docs/zh-TW/settings#settings-precedence)檔案來限制 Desktop 的 SSH 會話到已核准的主機集合。設定後，使用者只能連接到其解析的主機名稱與其中一個模式相符的主機。將其設定為空陣列以完全停用 SSH 會話。

704 704

705以下範例允許連接到 `devboxes.example.com` 下的任何主機以及單一命名的堡壘主機：705以下範例允許連接到 `devboxes.example.com` 下的任何主機以及單一命名的堡壘主機：

706 706

727這些設定透過[管理員設定主控台](https://claude.ai/admin-settings/claude-code)配置：727這些設定透過[管理員設定主控台](https://claude.ai/admin-settings/claude-code)配置：

728 728

729* **Desktop 中的 Code**：控制您組織中的使用者是否可以在桌面應用程式中存取 Claude Code729* **Desktop 中的 Code**：控制您組織中的使用者是否可以在桌面應用程式中存取 Claude Code

730* **網路上的 Code**：為您的組織啟用或停用[網路會話](/zh-TW/claude-code-on-the-web)730* **網路上的 Code**：為您的組織啟用或停用[網路會話](/docs/zh-TW/claude-code-on-the-web)

731* **遠端控制**：為您的組織啟用或停用[遠端控制](/zh-TW/remote-control)731* **遠端控制**：為您的組織啟用或停用[遠端控制](/docs/zh-TW/remote-control)

732* **停用略過權限模式**：防止您組織中的使用者啟用略過權限模式732* **停用略過權限模式**：防止您組織中的使用者啟用略過權限模式

733 733

734<h3 id="managed-settings">734<h3 id="managed-settings">

735 受管設定735 受管設定

736</h3>736</h3>

737 737

738受管設定會覆蓋專案和使用者設定，並在 Desktop 中的 Claude Code 會話時套用。您可以在您組織的[受管設定](/zh-TW/settings#settings-precedence)檔案中設定這些金鑰，或透過管理員主控台遠端推送它們。738受管設定會覆蓋專案和使用者設定，並在 Desktop 中的 Claude Code 會話時套用。您可以在您組織的[受管設定](/docs/zh-TW/settings#settings-precedence)檔案中設定這些金鑰，或透過管理員主控台遠端推送它們。

739 739

740| 金鑰 | 描述 |740| 金鑰 | 描述 |

741| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |741| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

743| `disableAutoMode` | 設定為 `"disable"` 以防止使用者啟用 [Auto](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 模式。從模式選擇器中移除 Auto。也在 `permissions` 下接受。 |743| `disableAutoMode` | 設定為 `"disable"` 以防止使用者啟用 [Auto](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 模式。從模式選擇器中移除 Auto。也在 `permissions` 下接受。 |

745| `browserExternalPageTools` | 設定為 `"disabled"` 以防止 Claude 使用工具來讀取或作用於[瀏覽器窗格](#browse-external-sites)中的外部頁面。使用者仍然可以自行瀏覽外部網站，本機開發伺服器預覽不受影響。 |745| `browserExternalPageTools` | 設定為 `"disabled"` 以防止 Claude 使用工具來讀取或作用於[瀏覽器窗格](#browse-external-sites)中的外部頁面。使用者仍然可以自行瀏覽外部網站，本機開發伺服器預覽不受影響。 |

746| `disableBrowserExternalNavigation` | 設定為 `true` 以完全關閉[瀏覽器窗格](#browse-external-sites)中的外部瀏覽。使用者和 Claude 都無法瀏覽外部網站，localhost 開發伺服器預覽不受影響。該值必須是 JSON 布林值 `true`；字串 `"true"` 會被忽略。 |746| `disableBrowserExternalNavigation` | 設定為 `true` 以完全關閉[瀏覽器窗格](#browse-external-sites)中的外部瀏覽。使用者和 Claude 都無法瀏覽外部網站，localhost 開發伺服器預覽不受影響。該值必須是 JSON 布林值 `true`；字串 `"true"` 會被忽略。 |

748| `sshHostAllowlist` | 限制 [SSH 會話](#restrict-which-ssh-hosts-users-can-connect-to)連線到已解析主機名稱符合這些模式之一的主機。空陣列會停用 SSH 會話。僅從受管設定讀取。 |748| `sshHostAllowlist` | 限制 [SSH 會話](#restrict-which-ssh-hosts-users-can-connect-to)連線到已解析主機名稱符合這些模式之一的主機。空陣列會停用 SSH 會話。僅從受管設定讀取。 |

749| `managedMcpServers` | 將 MCP 伺服器配置推送到第三方部署中的所有使用者。每個項目指定 `"http"`、`"sse"` 或 `"stdio"` 的傳輸、連線詳細資訊，以及可選的 `toolPolicy` 對應，限制該伺服器中使用者可以叫用的工具。僅在第三方 (3P) Desktop 部署中可用。透過受管設定檔案或 MDM 傳遞此金鑰，因為第三方部署不會收到管理員主控台設定。 |749| `managedMcpServers` | 將 MCP 伺服器配置推送到第三方部署中的所有使用者。每個項目指定 `"http"`、`"sse"` 或 `"stdio"` 的傳輸、連線詳細資訊，以及可選的 `toolPolicy` 對應，限制該伺服器中使用者可以叫用的工具。僅在第三方 (3P) Desktop 部署中可用。透過受管設定檔案或 MDM 傳遞此金鑰，因為第三方部署不會收到管理員主控台設定。 |

750 750

751哪些受管設定到達 Desktop 會話取決於該會話執行的位置。模型限制（例如 [`availableModels`](/zh-TW/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 會話中的強制方式與終端 CLI 相同；請參閱[表面涵蓋範圍](/zh-TW/model-config#surface-coverage)。751哪些受管設定到達 Desktop 會話取決於該會話執行的位置。模型限制（例如 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 會話中的強制方式與終端 CLI 相同；請參閱[表面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)。

752 752

753* **此機器上的本機會話**：部署到磁碟的受管設定檔案適用。透過管理員主控台推送的遠端受管設定在會話使用組織登入或直接配置的 API 金鑰向 Anthropic 的 API 進行驗證時也會到達這些會話，遵循與終端 CLI 相同的[設定優先順序](/zh-TW/settings#settings-precedence)。753* **此機器上的本機會話**：部署到磁碟的受管設定檔案適用。透過管理員主控台推送的遠端受管設定在會話使用組織登入或直接配置的 API 金鑰向 Anthropic 的 API 進行驗證時也會到達這些會話，遵循與終端 CLI 相同的[設定優先順序](/docs/zh-TW/settings#settings-precedence)。

754* **[雲端會話](#cloud-sessions)**：在 Anthropic 管理的 VM 上執行，僅接收[伺服器管理的設定](/zh-TW/server-managed-settings)。754* **[雲端會話](#cloud-sessions)**：在 Anthropic 管理的 VM 上執行，僅接收[伺服器管理的設定](/docs/zh-TW/server-managed-settings)。

755* **[SSH 會話](#ssh-sessions)**：會話從遠端主機讀取受管設定檔案。Desktop 本身在建立連線時從本機機器的受管設定讀取 `sshConfigs` 和 `sshHostAllowlist`。755* **[SSH 會話](#ssh-sessions)**：會話從遠端主機讀取受管設定檔案。Desktop 本身在建立連線時從本機機器的受管設定讀取 `sshConfigs` 和 `sshHostAllowlist`。

756 756

757`permissions.disableBypassPermissionsMode` 和 `disableAutoMode` 也在使用者和專案設定中運作，但將它們放在受管設定中可防止使用者覆蓋它們。757`permissions.disableBypassPermissionsMode` 和 `disableAutoMode` 也在使用者和專案設定中運作，但將它們放在受管設定中可防止使用者覆蓋它們。

758 758

759{/* min-version: 2.1.207 */}Claude Code 從使用者設定、`--settings` 旗標和受管設定讀取 `autoMode`，但不從 `.claude/settings.json` 或 `.claude/settings.local.json` 讀取：兩個檔案都位於儲存庫目錄中，因此複製的儲存庫或建置步驟無法注入自己的分類器規則。在 v2.1.207 之前，Claude Code 也讀取 `.claude/settings.local.json`。759Claude Code 從使用者設定、`--settings` 旗標和受管設定讀取 `autoMode`，但不從 `.claude/settings.json` 或 `.claude/settings.local.json` 讀取：兩個檔案都位於儲存庫目錄中，因此複製的儲存庫或建置步驟無法注入自己的分類器規則。在 v2.1.207 之前，Claude Code 也讀取 `.claude/settings.local.json`。

760 760

761有關受管專用設定（包括 `allowManagedPermissionRulesOnly` 和 `allowManagedHooksOnly`）的完整清單，請參閱[受管專用設定](/zh-TW/permissions#managed-only-settings)。761有關受管專用設定（包括 `allowManagedPermissionRulesOnly` 和 `allowManagedHooksOnly`）的完整清單，請參閱[受管專用設定](/docs/zh-TW/permissions#managed-only-settings)。

762 762

763<h3 id="device-management-policies">763<h3 id="device-management-policies">

764 裝置管理原則764 裝置管理原則

788*.claudemcpcontent.com788*.claudemcpcontent.com

789```789```

790 790

791流量在連接埠 443 上使用 HTTPS，除非您為 [OTLP](/zh-TW/monitoring-usage)、LLM 閘道或 MCP 伺服器配置自訂連接埠。791流量在連接埠 443 上使用 HTTPS，除非您為 [OTLP](/docs/zh-TW/monitoring-usage)、LLM 閘道或 MCP 伺服器配置自訂連接埠。

792 792

793對於代理伺服器、自訂憑證授權單位、mTLS 和獨立 CLI 需要的網域，請參閱[網路配置](/zh-TW/network-config)。793對於代理伺服器、自訂憑證授權單位、mTLS 和獨立 CLI 需要的網域，請參閱[網路配置](/docs/zh-TW/network-config)。

794 794

795若要減少防火牆萬用字元的數量，請改為允許這些 Anthropic 主機。某些子網域是動態產生的，必須保持為萬用字元。795若要減少防火牆萬用字元的數量，請改為允許這些 Anthropic 主機。某些子網域是動態產生的，必須保持為萬用字元。

796 796

818 驗證和 SSO818 驗證和 SSO

819</h3>819</h3>

820 820

821企業組織可以要求所有使用者進行 SSO。有關計畫級別的詳細資訊，請參閱[驗證](/zh-TW/authentication)，以及有關 SAML 配置，請參閱[設定 SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)；OIDC 設定涵蓋在 [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide) 中。821企業組織可以要求所有使用者進行 SSO。有關計畫級別的詳細資訊，請參閱[驗證](/docs/zh-TW/authentication)，以及有關 SAML 配置，請參閱[設定 SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)；OIDC 設定涵蓋在 [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide) 中。

822 822

823<h3 id="data-handling">823<h3 id="data-handling">

824 資料處理824 資料處理

825</h3>825</h3>

826 826

827Claude Code 在本機會話中本機處理您的程式碼，或在雲端會話中在 Anthropic 的雲端基礎設施上處理。對話和程式碼上下文會傳送到 Anthropic 的 API 進行處理。有關資料保留、隱私和合規性的詳細資訊，請參閱[資料處理](/zh-TW/data-usage)。827Claude Code 在本機會話中本機處理您的程式碼，或在雲端會話中在 Anthropic 的雲端基礎設施上處理。對話和程式碼上下文會傳送到 Anthropic 的 API 進行處理。有關資料保留、隱私和合規性的詳細資訊，請參閱[資料處理](/docs/zh-TW/data-usage)。

828 828

829<h3 id="deployment">829<h3 id="deployment">

830 部署830 部署

835* **macOS**：透過 MDM（例如 Jamf 或 Kandji）使用 `.dmg` 安裝程式分發835* **macOS**：透過 MDM（例如 Jamf 或 Kandji）使用 `.dmg` 安裝程式分發

836* **Windows**：透過 MSIX 套件部署。有關企業部署選項（包括無聲安裝），請參閱[為 Windows 部署 Claude Desktop](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows)836* **Windows**：透過 MSIX 套件部署。有關企業部署選項（包括無聲安裝），請參閱[為 Windows 部署 Claude Desktop](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows)

837 837

838有關防火牆中要允許清單的網域，請參閱上面的[網路存取需求](#network-access-requirements)。有關代理設定、自訂憑證授權單位和 LLM 閘道，請參閱[網路配置](/zh-TW/network-config)。838有關防火牆中要允許清單的網域，請參閱上面的[網路存取需求](#network-access-requirements)。有關代理設定、自訂憑證授權單位和 LLM 閘道，請參閱[網路配置](/docs/zh-TW/network-config)。

839 839

840有關完整的企業配置參考，請參閱[企業配置指南](https://support.claude.com/en/articles/12622667-enterprise-configuration)。840有關完整的企業配置參考，請參閱[企業配置指南](https://support.claude.com/en/articles/12622667-enterprise-configuration)。

841 841

865| `--dangerously-skip-permissions` | 略過權限模式。在 Pro 和 Max 方案上，在「設定」→「Claude Code」→「允許略過權限模式」中啟用它；在 Team 和 Enterprise 方案上，組織政策控制它 |865| `--dangerously-skip-permissions` | 略過權限模式。在 Pro 和 Max 方案上，在「設定」→「Claude Code」→「允許略過權限模式」中啟用它；在 Team 和 Enterprise 方案上，組織政策控制它 |

876 876

877Desktop 和 CLI 讀取相同的配置檔案，因此您的設定會轉移：877Desktop 和 CLI 讀取相同的配置檔案，因此您的設定會轉移：

878 878

879* **[CLAUDE.md](/zh-TW/memory)** 和 `CLAUDE.local.md` 檔案在您的專案中由兩者使用879* **[CLAUDE.md](/docs/zh-TW/memory)** 和 `CLAUDE.local.md` 檔案在您的專案中由兩者使用

880* **[MCP servers](/zh-TW/mcp)** 在 `~/.claude.json` 或 `.mcp.json` 中配置的在兩者中都有效880* **[MCP servers](/docs/zh-TW/mcp)** 在 `~/.claude.json` 或 `.mcp.json` 中配置的在兩者中都有效

881* **[Hooks](/zh-TW/hooks)** 和 **[skills](/zh-TW/skills)** 在設定中定義的適用於兩者881* **[Hooks](/docs/zh-TW/hooks)** 和 **[skills](/docs/zh-TW/skills)** 在設定中定義的適用於兩者

882* **[Settings](/zh-TW/settings)** 在 `~/.claude.json` 和 `~/.claude/settings.json` 中是共用的。`settings.json` 中的權限規則、允許的工具和其他設定適用於 Desktop 會話。882* **[Settings](/docs/zh-TW/settings)** 在 `~/.claude.json` 和 `~/.claude/settings.json` 中是共用的。`settings.json` 中的權限規則、允許的工具和其他設定適用於 Desktop 會話。

883* **Models**：相同的[模型](/zh-TW/model-config#available-models)在兩者中都可用。在 Desktop 中，從傳送按鈕旁的下拉式選單中選擇模型。您可以在會話期間從相同的下拉式選單變更模型。883* **Models**：相同的[模型](/docs/zh-TW/model-config#available-models)在兩者中都可用。在 Desktop 中，從傳送按鈕旁的下拉式選單中選擇模型。您可以在會話期間從相同的下拉式選單變更模型。

884 884

885<Note>885<Note>

886 **來自 Claude Desktop 聊天應用程式的 MCP servers**：Desktop 應用程式從 `claude_desktop_config.json` 將 MCP servers 載入到 Code 標籤會話中，以及來自 `~/.claude.json` 和 `.mcp.json` 的伺服器。在 `claude_desktop_config.json` 中定義的伺服器在 Desktop 聊天表面和 Code 標籤中都可用。886 **來自 Claude Desktop 聊天應用程式的 MCP servers**：Desktop 應用程式從 `claude_desktop_config.json` 將 MCP servers 載入到 Code 標籤會話中，以及來自 `~/.claude.json` 和 `.mcp.json` 的伺服器。在 `claude_desktop_config.json` 中定義的伺服器在 Desktop 聊天表面和 Code 標籤中都可用。

887 887

888 獨立 CLI 不讀取 `claude_desktop_config.json`。在 macOS 和 WSL 上，執行 `claude mcp add-from-claude-desktop` 將這些伺服器複製到 `~/.claude.json`。請參閱[從 Claude Desktop 匯入 MCP servers](/zh-TW/mcp#import-mcp-servers-from-claude-desktop)以了解匯入流程和範圍選項。888 獨立 CLI 不讀取 `claude_desktop_config.json`。在 macOS 和 WSL 上，執行 `claude mcp add-from-claude-desktop` 將這些伺服器複製到 `~/.claude.json`。請參閱[從 Claude Desktop 匯入 MCP servers](/docs/zh-TW/mcp#import-mcp-servers-from-claude-desktop)以了解匯入流程和範圍選項。

889</Note>889</Note>

890 890

891<h3 id="feature-comparison">891<h3 id="feature-comparison">

892 功能比較892 功能比較

893</h3>893</h3>

894 894

895此表比較 CLI 和 Desktop 之間的核心功能。有關 CLI 標誌的完整清單，請參閱 [CLI 參考](/zh-TW/cli-reference)。895此表比較 CLI 和 Desktop 之間的核心功能。有關 CLI 標誌的完整清單，請參閱 [CLI 參考](/docs/zh-TW/cli-reference)。

896 896

897| 功能 | CLI | Desktop |897| 功能 | CLI | Desktop |

898| ----------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |898| ----------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

901| [第三方提供者](/zh-TW/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 預設。若要進行閘道路由，請參閱[將桌面應用程式連接到閘道](/zh-TW/llm-gateway-connect#desktop-app)。若要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |901| [第三方提供者](/docs/zh-TW/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 預設。若要進行閘道路由，請參閱[將桌面應用程式連接到閘道](/docs/zh-TW/llm-gateway-connect#desktop-app)。若要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |

904| @mention 檔案 | 文字型 | 具有自動完成；本機和 SSH 會話僅 |904| @mention 檔案 | 文字型 | 具有自動完成；本機和 SSH 會話僅 |

905| 檔案附件 | 不可用 | 影像、PDF |905| 檔案附件 | 不可用 | 影像、PDF |

910| Dispatch 整合 | 不可用 | [Dispatch 會話](#sessions-from-dispatch)在側邊欄中 |910| Dispatch 整合 | 不可用 | [Dispatch 會話](#sessions-from-dispatch)在側邊欄中 |

911| 指令碼和自動化 | [`--print`](/zh-TW/cli-reference)、[Agent SDK](/zh-TW/headless) | 不可用 |911| 指令碼和自動化 | [`--print`](/docs/zh-TW/cli-reference)、[Agent SDK](/docs/zh-TW/headless) | 不可用 |

912 912

913<h3 id="what’s-not-available-in-desktop">913<h3 id="what’s-not-available-in-desktop">

914 Desktop 中不可用的內容914 Desktop 中不可用的內容

916 916

917以下功能僅在 CLI 或 VS Code 擴充功能中可用，除非另有說明：917以下功能僅在 CLI 或 VS Code 擴充功能中可用，除非另有說明：

918 918

919* **第三方提供者**：Desktop 預設連接到 Anthropic 的 API。若要透過閘道路由 Desktop，請參閱[將桌面應用程式連接到閘道](/zh-TW/llm-gateway-connect#desktop-app)。企業部署可以透過[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)配置 Google Cloud 的 Agent Platform 和閘道提供者。若要在 Amazon Bedrock 或 Microsoft Foundry 上使用 CLI，請參閱[快速入門](/zh-TW/quickstart)。作為上述部分的例外，[Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤。919* **第三方提供者**：Desktop 預設連接到 Anthropic 的 API。若要透過閘道路由 Desktop，請參閱[將桌面應用程式連接到閘道](/docs/zh-TW/llm-gateway-connect#desktop-app)。企業部署可以透過[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)配置 Google Cloud 的 Agent Platform 和閘道提供者。若要在 Amazon Bedrock 或 Microsoft Foundry 上使用 CLI，請參閱[快速入門](/docs/zh-TW/quickstart)。作為上述部分的例外，[Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤。

920* **Linux (beta)**：Linux 桌面應用程式中尚未提供電腦使用。請參閱 [Claude Desktop on Linux](/zh-TW/desktop-linux)。920* **Linux (beta)**：Linux 桌面應用程式中尚未提供電腦使用。請參閱 [Claude Desktop on Linux](/docs/zh-TW/desktop-linux)。

921* **內嵌程式碼建議**：Desktop 不提供自動完成樣式的建議。它透過對話提示和明確的程式碼變更進行工作。921* **內嵌程式碼建議**：Desktop 不提供自動完成樣式的建議。它透過對話提示和明確的程式碼變更進行工作。

922* **Agent teams**：平行 Claude Code 會話相互傳遞訊息，可在 [CLI](/zh-TW/agent-teams) 中使用，不在 Desktop 中。若要在一個會話內進行多代理工作，請使用 [dynamic workflows](/zh-TW/workflows)，它們在 Desktop 中執行。922* **Agent teams**：平行 Claude Code 會話相互傳遞訊息，可在 [CLI](/docs/zh-TW/agent-teams) 中使用，不在 Desktop 中。若要在一個會話內進行多代理工作，請使用 [dynamic workflows](/docs/zh-TW/workflows)，它們在 Desktop 中執行。

923* **Terminal-dialog 命令**：在終端機中開啟互動式面板的內建命令，在 Code 標籤中的行為不同。直接編輯[設定檔案](/zh-TW/settings)以管理權限規則和配置，或從獨立 CLI 執行命令。923* **Terminal-dialog 命令**：在終端機中開啟互動式面板的內建命令，在 Code 標籤中的行為不同。直接編輯[設定檔案](/docs/zh-TW/settings)以管理權限規則和配置，或從獨立 CLI 執行命令。

924 * 沒有引數形式的命令，例如 `/permissions`，回覆 `isn't available in this environment`。924 * 沒有引數形式的命令，例如 `/permissions`，回覆 `isn't available in this environment`。

925 * `/config` 開啟「設定」→「Claude Code」。命令後的文字被忽略，因此 `/config theme=dark` 不會設定主題。925 * `/config` 開啟「設定」→「Claude Code」。命令後的文字被忽略，因此 `/config theme=dark` 不會設定主題。

926 926

928 疑難排解928 疑難排解

929</h2>929</h2>

930 930

931下面的部分涵蓋桌面應用程式特定的問題。對於出現在聊天中的執行時 API 錯誤，例如 `API Error: 500`、`529 Overloaded`、`429` 或 `Prompt is too long`，請參閱[錯誤參考](/zh-TW/errors)。這些錯誤及其修復在 CLI、Desktop 和網路中是相同的。931下面的部分涵蓋桌面應用程式特定的問題。對於出現在聊天中的執行時 API 錯誤，例如 `API Error: 500`、`529 Overloaded`、`429` 或 `Prompt is too long`，請參閱[錯誤參考](/docs/zh-TW/errors)。這些錯誤及其修復在 CLI、Desktop 和網路中是相同的。

932 932

933<h3 id="check-your-version">933<h3 id="check-your-version">

934 檢查您的版本934 檢查您的版本

959如果應用程式開啟但顯示空白或無反應的螢幕：959如果應用程式開啟但顯示空白或無反應的螢幕：

960 960

9611. 重新啟動應用程式。9611. 重新啟動應用程式。

9622. 檢查待處理的更新。在 macOS 和 Windows 上，應用程式在啟動時自動更新；在 Linux 上，透過 apt 更新，如 [Claude Desktop on Linux](/zh-TW/desktop-linux) 中所述。9622. 檢查待處理的更新。在 macOS 和 Windows 上，應用程式在啟動時自動更新；在 Linux 上，透過 apt 更新，如 [Claude Desktop on Linux](/docs/zh-TW/desktop-linux) 中所述。

9633. 在受管理的網路上，確認您的防火牆允許[網路存取要求](#network-access-requirements)中的 CDN 主機。9633. 在受管理的網路上，確認您的防火牆允許[網路存取要求](#network-access-requirements)中的 CDN 主機。

9644. 在 Windows 上，檢查「事件檢視器」中的 **Windows 日誌 → 應用程式** 下的當機日誌。9644. 在 Windows 上，檢查「事件檢視器」中的 **Windows 日誌 → 應用程式** 下的當機日誌。

965 965

discover-plugins.md +28 −28

Details

8 8

9外掛程式透過技能、代理、hooks 和 MCP servers 擴展 Claude Code。外掛程式市場是幫助您探索和安裝這些擴展的目錄，無需自己構建它們。9外掛程式透過技能、代理、hooks 和 MCP servers 擴展 Claude Code。外掛程式市場是幫助您探索和安裝這些擴展的目錄，無需自己構建它們。

10 10

~~11想要建立和分發您自己的市場？請參閱[建立和分發外掛程式市場](/zh-TW/plugin-marketplaces)。~~11想要建立和分發您自己的市場？請參閱[建立和分發外掛程式市場](/docs/zh-TW/plugin-marketplaces)。

12 12

13<h2 id="how-marketplaces-work">13<h2 id="how-marketplaces-work">

14 市場如何運作14 市場如何運作

43如果 Claude Code 報告在任何市場中找不到外掛程式，您的市場可能遺失或已過期。執行 `/plugin marketplace update claude-plugins-official` 以重新整理它，或如果您之前未新增過，執行 `/plugin marketplace add anthropics/claude-plugins-official`。然後重試安裝。43如果 Claude Code 報告在任何市場中找不到外掛程式，您的市場可能遺失或已過期。執行 `/plugin marketplace update claude-plugins-official` 以重新整理它，或如果您之前未新增過，執行 `/plugin marketplace add anthropics/claude-plugins-official`。然後重試安裝。

44 44

45<Note>45<Note>

46 官方市場由 Anthropic 維護，包含由 Anthropic 自行決定。應用內提交表單會將外掛程式新增到[社群市場](#community-marketplace)，而不是官方市場。若要獨立分發外掛程式，請[建立您自己的市場](/zh-TW/plugin-marketplaces)並與使用者共享。46 官方市場由 Anthropic 維護，包含由 Anthropic 自行決定。應用內提交表單會將外掛程式新增到[社群市場](#community-marketplace)，而不是官方市場。若要獨立分發外掛程式，請[建立您自己的市場](/docs/zh-TW/plugin-marketplaces)並與使用者共享。

47</Note>47</Note>

48 48

49官方市場包括多個外掛程式類別：49官方市場包括多個外掛程式類別：

72 72

~~73您也可以[為其他語言建立您自己的 LSP 外掛程式](/zh-TW/plugins-reference#lsp-servers)。~~73您也可以[為其他語言建立您自己的 LSP 外掛程式](/docs/zh-TW/plugins-reference#lsp-servers)。

74 74

75<Note>75<Note>

76 如果在安裝外掛程式後在 `/plugin` Errors 標籤中看到 `Executable not found in $PATH`，請從上表安裝所需的二進位檔。76 如果在安裝外掛程式後在 `/plugin` Errors 標籤中看到 `Executable not found in $PATH`，請從上表安裝所需的二進位檔。

91 外部整合91 外部整合

92</h3>92</h3>

93 93

~~94這些外掛程式捆綁預先配置的 [MCP servers](/zh-TW/mcp)，以便您可以連接 Claude 到外部服務，無需手動設定：~~94這些外掛程式捆綁預先配置的 [MCP servers](/docs/zh-TW/mcp)，以便您可以連接 Claude 到外部服務，無需手動設定：

95 95

96* **原始碼控制**：`github`、`gitlab`96* **原始碼控制**：`github`、`gitlab`

97* **專案管理**：`atlassian`（Jira/Confluence）、`asana`、`linear`、`notion`97* **專案管理**：`atlassian`（Jira/Confluence）、`asana`、`linear`、`notion`

104 自動安全審查104 自動安全審查

105</h3>105</h3>

106 106

107`security-guidance` 外掛程式審查 Claude 進行的每項變更是否存在常見漏洞，並指示 Claude 在同一工作階段中修復發現的問題。請參閱[在 Claude 編寫程式碼時捕捉安全問題](/zh-TW/security-guidance)以了解它檢查的內容以及如何新增專案特定的規則。107`security-guidance` 外掛程式審查 Claude 進行的每項變更是否存在常見漏洞，並指示 Claude 在同一工作階段中修復發現的問題。請參閱[在 Claude 編寫程式碼時捕捉安全問題](/docs/zh-TW/security-guidance)以了解它檢查的內容以及如何新增專案特定的規則。

108 108

109<h3 id="development-workflows">109<h3 id="development-workflows">

110 開發工作流程110 開發工作流程

142/plugin install <plugin-name>@claude-community142/plugin install <plugin-name>@claude-community

143```143```

144 144

145若要將您自己的外掛程式提交到社群市場，請參閱建立外掛程式指南中的[將您的外掛程式提交到社群市場](/zh-TW/plugins#submit-your-plugin-to-the-community-marketplace)。145若要將您自己的外掛程式提交到社群市場，請參閱建立外掛程式指南中的[將您的外掛程式提交到社群市場](/docs/zh-TW/plugins#submit-your-plugin-to-the-community-marketplace)。

146 146

147<h2 id="try-it-add-the-demo-marketplace">147<h2 id="try-it-add-the-demo-marketplace">

148 試試看：新增演示市場148 試試看：新增演示市場

169 * **Marketplaces**：新增、移除或更新已新增的市場169 * **Marketplaces**：新增、移除或更新已新增的市場

170 * **Errors**：檢視任何外掛程式載入錯誤170 * **Errors**：檢視任何外掛程式載入錯誤

171 171

172 前往 **Discover** 標籤以查看您剛新增的市場中的外掛程式。{/* min-version: 2.1.154 */}當您的管理員已透過 [`pluginSuggestionMarketplaces`](/zh-TW/settings#available-settings) 受管設定將市場加入允許清單時，標記為與您目前工作目錄相關的外掛程式會釘在頂部，並帶有 **suggested for this directory** 標籤。172 前往 **Discover** 標籤以查看您剛新增的市場中的外掛程式。當您的管理員已透過 [`pluginSuggestionMarketplaces`](/docs/zh-TW/settings#available-settings) 受管設定將市場加入允許清單時，標記為與您目前工作目錄相關的外掛程式會釘在頂部，並帶有 **suggested for this directory** 標籤。

173 </Step>173 </Step>

174 174

175 <Step title="安裝外掛程式">175 <Step title="安裝外掛程式">

176 選擇外掛程式以檢視其詳細資訊。詳細資訊窗格會顯示外掛程式包含的內容及其成本：176 選擇外掛程式以檢視其詳細資訊。詳細資訊窗格會顯示外掛程式包含的內容及其成本：

177 177

178 * {/* min-version: 2.1.143 */}**Context cost** 估計，讓您可以查看外掛程式每回合會為您的[內容視窗](/zh-TW/features-overview#understand-context-costs)新增多少個 token（Claude Code v2.1.143 及更新版本）178 * **Context cost** 估計，讓您可以查看外掛程式每回合會為您的[內容視窗](/docs/zh-TW/features-overview#understand-context-costs)新增多少個 token（Claude Code v2.1.143 及更新版本）

179 * {/* min-version: 2.1.144 */}外掛程式的 **Last updated** 日期（v2.1.144 及更新版本）179 * 外掛程式的 **Last updated** 日期（v2.1.144 及更新版本）

180 * {/* min-version: 2.1.145 */}**Will install** 區段，列出外掛程式的命令、代理程式、skills、hooks 和 MCP 及 LSP 伺服器，讓您可以在安裝前檢視它新增的確切內容（v2.1.145 及更新版本）180 * **Will install** 區段，列出外掛程式的命令、代理程式、skills、hooks 和 MCP 及 LSP 伺服器，讓您可以在安裝前檢視它新增的確切內容（v2.1.145 及更新版本）

181 181

182 選擇安裝範圍：182 選擇安裝範圍：

183 183

193 /plugin install commit-commands@claude-code-plugins193 /plugin install commit-commands@claude-code-plugins

194 ```194 ```

195 195

196 請參閱[配置範圍](/zh-TW/settings#configuration-scopes)以深入瞭解範圍。196 請參閱[配置範圍](/docs/zh-TW/settings#configuration-scopes)以深入瞭解範圍。

197 </Step>197 </Step>

198 198

199 <Step title="使用您的新外掛程式">199 <Step title="使用您的新外掛程式">

293```293```

294 294

295<Note>295<Note>

296 與基於 Git 的市場相比，基於 URL 的市場有一些限制。如果在安裝外掛程式時遇到「找不到路徑」錯誤，請參閱[故障排除](/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)。296 與基於 Git 的市場相比，基於 URL 的市場有一些限制。如果在安裝外掛程式時遇到「找不到路徑」錯誤，請參閱[故障排除](/docs/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)。

297</Note>297</Note>

298 298

299<h2 id="install-plugins">299<h2 id="install-plugins">

306/plugin install plugin-name@marketplace-name306/plugin install plugin-name@marketplace-name

307```307```

308 308

309該命令會開啟該外掛程式的詳細資訊，您可以在其中選擇[安裝範圍](/zh-TW/settings#configuration-scopes)。當您執行 `/plugin`、前往 **Discover** 標籤，並在外掛程式上按 **Enter** 時，您會看到相同的選項：309該命令會開啟該外掛程式的詳細資訊，您可以在其中選擇[安裝範圍](/docs/zh-TW/settings#configuration-scopes)。當您執行 `/plugin`、前往 **Discover** 標籤，並在外掛程式上按 **Enter** 時，您會看到相同的選項：

310 310

311* **User scope**（預設）：在所有專案中為自己安裝311* **User scope**（預設）：在所有專案中為自己安裝

312* **Project scope**：為此儲存庫上的所有協作者安裝，這會將外掛程式新增到 `.claude/settings.json`312* **Project scope**：為此儲存庫上的所有協作者安裝，這會將外掛程式新增到 `.claude/settings.json`

313* **Local scope**：僅在此儲存庫中為自己安裝，不與協作者共享313* **Local scope**：僅在此儲存庫中為自己安裝，不與協作者共享

314 314

315若要在沒有互動式步驟的情況下安裝，請使用 [`claude plugin install`](/zh-TW/plugins-reference#plugin-install) shell 命令，該命令預設安裝到使用者範圍，除非您傳遞 `--scope`。315若要在沒有互動式步驟的情況下安裝，請使用 [`claude plugin install`](/docs/zh-TW/plugins-reference#plugin-install) shell 命令，該命令預設安裝到使用者範圍，除非您傳遞 `--scope`。

316 316

317您也可能看到具有 **managed** 範圍的外掛程式。這些是由管理員透過[受管設定](/zh-TW/settings#settings-files)安裝的，無法修改。317您也可能看到具有 **managed** 範圍的外掛程式。這些是由管理員透過[受管設定](/docs/zh-TW/settings#settings-files)安裝的，無法修改。

318 318

319<Warning>319<Warning>

320 在安裝外掛程式之前，請確保您信任它。Anthropic 不控制外掛程式中包含的 MCP servers、檔案或其他軟體，也無法驗證它們是否按預期工作。檢查每個外掛程式的首頁以獲取更多資訊。320 在安裝外掛程式之前，請確保您信任它。Anthropic 不控制外掛程式中包含的 MCP servers、檔案或其他軟體，也無法驗證它們是否按預期工作。檢查每個外掛程式的首頁以獲取更多資訊。

343* 您的組織管理的外掛程式或您使用 `--plugin-dir` 載入的外掛程式343* 您的組織管理的外掛程式或您使用 `--plugin-dir` 載入的外掛程式

344* 貢獻 theme、output style、monitor 或 workflow 的外掛程式，因為這些外掛程式提供價值而無需追蹤叫用344* 貢獻 theme、output style、monitor 或 workflow 的外掛程式，因為這些外掛程式提供價值而無需追蹤叫用

345 345

346當您的組織使用 [`strictKnownMarketplaces`](/zh-TW/settings#strictknownmarketplaces) 限制 marketplaces 時，**Not used recently** 標題和 **Last used** 行都會隱藏。346當您的組織使用 [`strictKnownMarketplaces`](/docs/zh-TW/settings#strictknownmarketplaces) 限制 marketplaces 時，**Not used recently** 標題和 **Last used** 行都會隱藏。

347 347

348外掛程式的 [language server](/zh-TW/plugins#add-lsp-servers-to-your-plugin) 在提供診斷或回答程式碼導覽請求時計為已使用，因此其伺服器在您的工作階段中處於活動狀態的 LSP 外掛程式不會列為未使用。在 v2.1.203 之前，無法將語言伺服器活動計為使用，因此貢獻 LSP 伺服器的外掛程式完全豁免於該群組，與 theme 和 output style 外掛程式的方式相同。348外掛程式的 [language server](/docs/zh-TW/plugins#add-lsp-servers-to-your-plugin) 在提供診斷或回答程式碼導覽請求時計為已使用，因此其伺服器在您的工作階段中處於活動狀態的 LSP 外掛程式不會列為未使用。在 v2.1.203 之前，無法將語言伺服器活動計為使用，因此貢獻 LSP 伺服器的外掛程式完全豁免於該群組，與 theme 和 output style 外掛程式的方式相同。

349 349

350計算語言伺服器活動的版本上的第一個工作階段也會重設每個尚未記錄任何使用的 LSP 外掛程式的使用記錄，因此 Claude Code 不會根據在其伺服器活動被追蹤之前記錄的資料將您較早安裝的外掛程式判斷為未使用。在 v2.1.206 之前，該第一個工作階段可能會在 **Not used recently** 下列出主動使用的 LSP 外掛程式並建議檢查它。350計算語言伺服器活動的版本上的第一個工作階段也會重設每個尚未記錄任何使用的 LSP 外掛程式的使用記錄，因此 Claude Code 不會根據在其伺服器活動被追蹤之前記錄的資料將您較早安裝的外掛程式判斷為未使用。在 v2.1.206 之前，該第一個工作階段可能會在 **Not used recently** 下列出主動使用的 LSP 外掛程式並建議檢查它。

351 351

373/plugin enable plugin-name@marketplace-name373/plugin enable plugin-name@marketplace-name

374```374```

375 375

376在這些識別碼中，`plugin-name` 是 [marketplace 項目](/zh-TW/plugin-marketplaces#plugin-entries) 中外掛程式的 `name`，可能與外掛程式自身 `plugin.json` 中的 `name` 不同。376在這些識別碼中，`plugin-name` 是 [marketplace 項目](/docs/zh-TW/plugin-marketplaces#plugin-entries) 中外掛程式的 `name`，可能與外掛程式自身 `plugin.json` 中的 `name` 不同。

377 377

378自 Claude Code v2.1.195 起，`/plugin` 介面中的 **Enable** 和 **Disable** 適用於其兩個名稱不同的外掛程式，`/plugin enable` 和 `/plugin disable` 接受任一名稱。當您在較早版本中停用此類外掛程式時，Claude Code 會報告 `already disabled` 並保持其啟用狀態。378自 Claude Code v2.1.195 起，`/plugin` 介面中的 **Enable** 和 **Disable** 適用於其兩個名稱不同的外掛程式，`/plugin enable` 和 `/plugin disable` 接受任一名稱。當您在較早版本中停用此類外掛程式時，Claude Code 會報告 `already disabled` 並保持其啟用狀態。

379 379

402 402

403Claude Code 重新載入所有活動外掛程式，並顯示外掛程式、skills、agents、hooks、外掛程式 MCP servers 和外掛程式 LSP servers 的計數。403Claude Code 重新載入所有活動外掛程式，並顯示外掛程式、skills、agents、hooks、外掛程式 MCP servers 和外掛程式 LSP servers 的計數。

404 404

405重新載入在下一個請求時會產生令牌成本：新載入的元件會在附加到對話的內容中宣佈自己，而現有歷史記錄仍然從提示快取讀取。提供 MCP servers 的外掛程式在其工具未被 [tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 延遲時成本更高：該變更會使快取失效，下一個請求會重新讀取整個對話。{/* min-version: 2.1.163 */}在該情況下 `/reload-plugins` 會顯示警告並不套用重新載入；傳遞 `--force` 以強制套用。如需詳細資訊，請參閱 [啟用或停用外掛程式](/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)。405重新載入在下一個請求時會產生令牌成本：新載入的元件會在附加到對話的內容中宣佈自己，而現有歷史記錄仍然從提示快取讀取。提供 MCP servers 的外掛程式在其工具未被 [tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 延遲時成本更高：該變更會使快取失效，下一個請求會重新讀取整個對話。在該情況下 `/reload-plugins` 會顯示警告並不套用重新載入；傳遞 `--force` 以強制套用。如需詳細資訊，請參閱 [啟用或停用外掛程式](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)。

406 406

407<h2 id="manage-marketplaces">407<h2 id="manage-marketplaces">

408 管理市場408 管理市場

466 466

467官方 Anthropic 市場預設啟用自動更新。第三方和本機開發市場預設停用自動更新。467官方 Anthropic 市場預設啟用自動更新。第三方和本機開發市場預設停用自動更新。

468 468

469管理員也可以在受管設定中的每個 [`extraKnownMarketplaces`](/zh-TW/settings#extraknownmarketplaces) 項目上設定 `"autoUpdate": true`，以為組織市場啟用自動更新，而無需每個使用者都切換它。469管理員也可以在受管設定中的每個 [`extraKnownMarketplaces`](/docs/zh-TW/settings#extraknownmarketplaces) 項目上設定 `"autoUpdate": true`，以為組織市場啟用自動更新，而無需每個使用者都切換它。

470 470

471若要完全停用 Claude Code 和所有外掛程式的所有自動更新，請設定 `DISABLE_AUTOUPDATER` 環境變數。有關詳細資訊，請參閱[自動更新](/zh-TW/setup#auto-updates)。471若要完全停用 Claude Code 和所有外掛程式的所有自動更新，請設定 `DISABLE_AUTOUPDATER` 環境變數。有關詳細資訊，請參閱[自動更新](/docs/zh-TW/setup#auto-updates)。

472 472

473若要在停用 Claude Code 自動更新的同時保持外掛程式自動更新啟用，請設定 `FORCE_AUTOUPDATE_PLUGINS=1` 以及 `DISABLE_AUTOUPDATER`：473若要在停用 Claude Code 自動更新的同時保持外掛程式自動更新啟用，請設定 `FORCE_AUTOUPDATE_PLUGINS=1` 以及 `DISABLE_AUTOUPDATER`：

474 474

502}502}

503```503```

504 504

505如需完整配置選項（包括 `extraKnownMarketplaces` 和 `enabledPlugins`），請參閱[外掛程式設定](/zh-TW/settings#plugin-settings)。505如需完整配置選項（包括 `extraKnownMarketplaces` 和 `enabledPlugins`），請參閱[外掛程式設定](/docs/zh-TW/settings#plugin-settings)。

506 506

507<h2 id="security">507<h2 id="security">

508 安全性508 安全性

509</h2>509</h2>

510 510

511外掛程式和市場是高度受信任的元件，可以使用您的使用者權限在您的機器上執行任意程式碼。僅從您信任的來源安裝外掛程式和新增市場。組織可以使用[受管市場限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)限制使用者可以新增的市場。511外掛程式和市場是高度受信任的元件，可以使用您的使用者權限在您的機器上執行任意程式碼。僅從您信任的來源安裝外掛程式和新增市場。組織可以使用[受管市場限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)限制使用者可以新增的市場。

512 512

513<h2 id="troubleshooting">513<h2 id="troubleshooting">

514 故障排除514 故障排除

5242. **更新 Claude Code**：5242. **更新 Claude Code**：

525 * **Homebrew**：`brew upgrade claude-code`，或如果您安裝了該 cask，執行 `brew upgrade claude-code@latest`525 * **Homebrew**：`brew upgrade claude-code`，或如果您安裝了該 cask，執行 `brew upgrade claude-code@latest`

526 * **npm**：`npm install -g @anthropic-ai/claude-code@latest`526 * **npm**：`npm install -g @anthropic-ai/claude-code@latest`

527 * **原生安裝程式**：從[設定](/zh-TW/setup)重新執行安裝命令527 * **原生安裝程式**：從[設定](/docs/zh-TW/setup)重新執行安裝命令

5283. **重新啟動 Claude Code**：更新後，重新啟動您的終端機並再次執行 `claude`。5283. **重新啟動 Claude Code**：更新後，重新啟動您的終端機並再次執行 `claude`。

529 529

530<h3 id="common-issues">530<h3 id="common-issues">

536* **安裝後找不到檔案**：外掛程式被複製到快取中，因此參考外掛程式目錄外檔案的路徑將無法運作536* **安裝後找不到檔案**：外掛程式被複製到快取中，因此參考外掛程式目錄外檔案的路徑將無法運作

537* **外掛程式技能未出現**：使用 `rm -rf ~/.claude/plugins/cache` 清除快取，重新啟動 Claude Code，然後重新安裝外掛程式。537* **外掛程式技能未出現**：使用 `rm -rf ~/.claude/plugins/cache` 清除快取，重新啟動 Claude Code，然後重新安裝外掛程式。

538 538

539如需詳細的故障排除和解決方案，請參閱市場指南中的[故障排除](/zh-TW/plugin-marketplaces#troubleshooting)。如需偵錯工具，請參閱[偵錯和開發工具](/zh-TW/plugins-reference#debugging-and-development-tools)。539如需詳細的故障排除和解決方案，請參閱市場指南中的[故障排除](/docs/zh-TW/plugin-marketplaces#troubleshooting)。如需偵錯工具，請參閱[偵錯和開發工具](/docs/zh-TW/plugins-reference#debugging-and-development-tools)。

540 540

541<h3 id="code-intelligence-issues">541<h3 id="code-intelligence-issues">

542 程式碼智能問題542 程式碼智能問題

550 後續步驟550 後續步驟

551</h2>551</h2>

552 552

553* **構建您自己的外掛程式**：請參閱[外掛程式](/zh-TW/plugins)以建立技能、代理和 hooks553* **構建您自己的外掛程式**：請參閱[外掛程式](/docs/zh-TW/plugins)以建立技能、代理和 hooks

554* **建立市場**：請參閱[建立外掛程式市場](/zh-TW/plugin-marketplaces)以將外掛程式分發給您的團隊或社群554* **建立市場**：請參閱[建立外掛程式市場](/docs/zh-TW/plugin-marketplaces)以將外掛程式分發給您的團隊或社群

555* **技術參考**：請參閱[外掛程式參考](/zh-TW/plugins-reference)以取得完整規格555* **技術參考**：請參閱[外掛程式參考](/docs/zh-TW/plugins-reference)以取得完整規格

env-vars.md +186 −186

Details

6 6

7> 控制 Claude Code 行為的環境變數完整參考。7> 控制 Claude Code 行為的環境變數完整參考。

8 8

9環境變數可以控制 Claude Code 的行為，例如模型選擇、驗證、請求路由和功能切換。許多相同的行為也可以透過 [settings 檔案](/zh-TW/settings) 欄位、[CLI 旗標](/zh-TW/cli-reference) 或工作階段內命令（如 `/model`）進行配置。9環境變數可以控制 Claude Code 的行為，例如模型選擇、驗證、請求路由和功能切換。許多相同的行為也可以透過 [settings 檔案](/docs/zh-TW/settings) 欄位、[CLI 旗標](/docs/zh-TW/cli-reference) 或工作階段內命令（如 `/model`）進行配置。

10 10

11本頁涵蓋如何：11本頁涵蓋如何：

12 12

79| `.claude/settings.local.json` | 您，僅在此專案中（如果您手動建立，請將其新增到您的 gitignore） |79| `.claude/settings.local.json` | 您，僅在此專案中（如果您手動建立，請將其新增到您的 gitignore） |

80| 受管 settings | 您組織中的每個人，由管理員部署 |80| 受管 settings | 您組織中的每個人，由管理員部署 |

81 81

82請參閱 [Settings 檔案](/zh-TW/settings#settings-files) 以了解每個檔案的位置，以及 [Settings 優先順序](/zh-TW/settings#settings-precedence) 以了解當多個檔案設定相同變數時它們如何結合。82請參閱 [Settings 檔案](/docs/zh-TW/settings#settings-files) 以了解每個檔案的位置，以及 [Settings 優先順序](/docs/zh-TW/settings#settings-precedence) 以了解當多個檔案設定相同變數時它們如何結合。

83 83

84<h2 id="precedence">84<h2 id="precedence">

85 優先順序85 優先順序

87 87

88當相同的行為同時具有環境變數和 settings 欄位時，環境變數優先。例如，`ANTHROPIC_MODEL` 覆蓋 `model` 設定，`CLAUDE_CODE_AUTO_CONNECT_IDE` 覆蓋 `autoConnectIde`。當環境變數未設定時，settings 欄位適用。88當相同的行為同時具有環境變數和 settings 欄位時，環境變數優先。例如，`ANTHROPIC_MODEL` 覆蓋 `model` 設定，`CLAUDE_CODE_AUTO_CONNECT_IDE` 覆蓋 `autoConnectIde`。當環境變數未設定時，settings 欄位適用。

89 89

90當相同的變數同時在您的 shell 和 settings 檔案 `env` 區塊中設定時，settings 檔案值適用。Claude Code 在啟動時將每個 `env` 項目寫入程序環境，取代從 shell 繼承的值。少數變數有特殊處理；[`env` 設定](/zh-TW/settings#available-settings)列出例外。90當相同的變數同時在您的 shell 和 settings 檔案 `env` 區塊中設定時，settings 檔案值適用。Claude Code 在啟動時將每個 `env` 項目寫入程序環境，取代從 shell 繼承的值。少數變數有特殊處理；[`env` 設定](/docs/zh-TW/settings#available-settings)列出例外。

91 91

~~92在 settings 檔案之間，`env` 值遵循 [settings 優先順序](/zh-TW/settings#settings-precedence)，因此受管理的 settings 項目覆蓋使用者或專案 settings 中的相同變數。~~92在 settings 檔案之間，`env` 值遵循 [settings 優先順序](/docs/zh-TW/settings#settings-precedence)，因此受管理的 settings 項目覆蓋使用者或專案 settings 中的相同變數。

93 93

94環境變數與 CLI 旗標和工作階段內命令的互動因功能而異：`--model` 和 `/model` 覆蓋 `ANTHROPIC_MODEL`，而 `CLAUDE_CODE_EFFORT_LEVEL` 覆蓋 `/effort`。當變數與另一個配置來源互動時，其在 [變數](#variables) 清單中的列會說明優先順序或連結到記錄它的頁面。94環境變數與 CLI 旗標和工作階段內命令的互動因功能而異：`--model` 和 `/model` 覆蓋 `ANTHROPIC_MODEL`，而 `CLAUDE_CODE_EFFORT_LEVEL` 覆蓋 `/effort`。當變數與另一個配置來源互動時，其在 [變數](#variables) 清單中的列會說明優先順序或連結到記錄它的頁面。

95 95

100</h2>100</h2>

101 101

102| 變數 | 用途 |102| 變數 | 用途 |

103| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |103| :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

104| `ANTHROPIC_API_KEY` | 作為 `X-Api-Key` 標頭發送的 API 金鑰。設定時，即使您已登入，此金鑰也會用於代替您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動式模式（`-p`）中，金鑰存在時始終使用。在互動式模式中，系統會提示您在金鑰覆蓋您的訂閱之前批准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |104| `ANTHROPIC_API_KEY` | 作為 `X-Api-Key` 標頭發送的 API 金鑰。設定時，即使您已登入，此金鑰也會用於代替您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動式模式（`-p`）中，金鑰存在時始終使用。在互動式模式中，系統會提示您在金鑰覆蓋您的訂閱之前批准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |

106| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 發送，優先於 AWS SigV4 |106| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 發送，優先於 AWS SigV4 |

107| `ANTHROPIC_AWS_BASE_URL` | 覆蓋 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。預設為 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |107| `ANTHROPIC_AWS_BASE_URL` | 覆蓋 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM gateway](/docs/zh-TW/llm-gateway) 路由。預設為 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |

108| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭發送 |108| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭發送 |

109| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。{/* min-version: 2.1.196 */}自 v2.1.196 起，當此項指向 `api.anthropic.com` 以外的主機時，[Remote Control](/zh-TW/remote-control#requirements) 會停用，符合其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為 |109| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此項指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 會停用，符合其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為 |

110| `ANTHROPIC_BEDROCK_BASE_URL` | 覆蓋 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock) |110| `ANTHROPIC_BEDROCK_BASE_URL` | 覆蓋 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點或透過 [LLM gateway](/docs/zh-TW/llm-gateway) 路由。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |

111| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆蓋 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle endpoint](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |111| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆蓋 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle endpoint](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |

112| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [service tier](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭發送。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock#service-tiers) |112| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [service tier](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭發送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |

113| `ANTHROPIC_BETAS` | 逗號分隔的其他 `anthropic-beta` 標頭值清單，以包含在 API 請求中。Claude Code 已發送其需要的 beta 標頭；使用此選項可在 Claude Code 新增原生支援之前選擇加入 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。與 [`--betas` 旗標](/zh-TW/cli-reference#cli-flags)（需要 API 金鑰驗證）不同，此變數適用於所有驗證方法，包括 Claude.ai 訂閱 |113| `ANTHROPIC_BETAS` | 逗號分隔的其他 `anthropic-beta` 標頭值清單，以包含在 API 請求中。Claude Code 已發送其需要的 beta 標頭；使用此選項可在 Claude Code 新增原生支援之前選擇加入 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。與 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)（需要 API 金鑰驗證）不同，此變數適用於所有驗證方法，包括 Claude.ai 訂閱 |

115| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此選項可使非標準或閘道特定的模型可選擇，而無需替換內建別名。請參閱 [Model configuration](/zh-TW/model-config#add-a-custom-model-option) |115| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此選項可使非標準或閘道特定的模型可選擇，而無需替換內建別名。請參閱 [Model configuration](/docs/zh-TW/model-config#add-a-custom-model-option) |

118| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |118| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

120| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |120| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

121| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |121| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

122| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |122| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

124| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |124| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

125| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |125| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

126| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |126| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

128| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |128| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

129| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |129| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

130| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |130| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

132| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |132| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

133| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |133| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

134| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |134| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

136| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | {/* min-version: 2.1.203 */}Microsoft Foundry 驗證的 Bearer 權杖，例如 Microsoft Entra 存取權杖。Claude Code 將其作為 `Authorization: Bearer` 標頭發送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 預設認證鏈。請參閱 [Microsoft Foundry](/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |136| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Foundry 驗證的 Bearer 權杖，例如 Microsoft Entra 存取權杖。Claude Code 將其作為 `Authorization: Bearer` 標頭發送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 預設認證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |

137| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如，`https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/zh-TW/microsoft-foundry)） |137| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如，`https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

138| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如，`my-resource`）。如果未設定 `ANTHROPIC_FOUNDRY_BASE_URL`，則為必需（請參閱 [Microsoft Foundry](/zh-TW/microsoft-foundry)） |138| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如，`my-resource`）。如果未設定 `ANTHROPIC_FOUNDRY_BASE_URL`，則為必需（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

141| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時覆蓋 Haiku 級別模型的 AWS 區域。在 Amazon Bedrock 上，僅當同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才生效，因為 Amazon Bedrock 否則會為背景任務使用 [default Sonnet model or the primary model](/zh-TW/amazon-bedrock#4-pin-model-versions) |141| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時覆蓋 Haiku 級別模型的 AWS 區域。在 Amazon Bedrock 上，僅當同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才生效，因為 Amazon Bedrock 否則會為背景任務使用 [default Sonnet model or the primary model](/docs/zh-TW/amazon-bedrock#4-pin-model-versions) |

142| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai) |142| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點或透過 [LLM gateway](/docs/zh-TW/llm-gateway) 路由。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |

143| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 的 GCP 專案 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 認證檔案中的專案覆蓋。請參閱 [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai) |143| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 的 GCP 專案 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 認證檔案中的專案覆蓋。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |

144| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯盟規則的範圍涵蓋多個工作區時設定此項，以便權杖交換知道要針對哪個工作區 |144| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯盟規則的範圍涵蓋多個工作區時設定此項，以便權杖交換知道要針對哪個工作區 |

145| `API_FORCE_IDLE_TIMEOUT` | {/* min-version: 2.1.169 */}覆蓋 5 分鐘的閒置逾時，該逾時會在沒有位元組到達時中止串流模型回應。設定為 `0` 以停用逾時，例如當緩慢的 [gateway](/zh-TW/llm-gateway) 或本機模型在區塊之間暫停超過 5 分鐘時。設定為 `1` 以在每個提供者上保持逾時。未設定時，逾時在直接 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 連線上無效，其中 Claude Code 自己的位元組級串流監視程式執行，在每個其他提供者上有效，包括 [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry)、[Mantle](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)、[Amazon Bedrock](/zh-TW/amazon-bedrock) 和閘道連線，因此停滯的串流會中止而不是掛起。自 v2.1.169 起 |145| `API_FORCE_IDLE_TIMEOUT` | 覆蓋 5 分鐘的閒置逾時，該逾時會在沒有位元組到達時中止串流模型回應。設定為 `0` 以停用逾時，例如當緩慢的 [gateway](/docs/zh-TW/llm-gateway) 或本機模型在區塊之間暫停超過 5 分鐘時。設定為 `1` 以在每個提供者上保持逾時。未設定時，逾時在直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線上無效，其中 Claude Code 自己的位元組級串流監視程式執行，在每個其他提供者上有效，包括 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry)、[Mantle](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 和閘道連線，因此停滯的串流會中止而不是掛起。自 v2.1.169 起 |

146| `API_TIMEOUT_MS` | API 請求的逾時（以毫秒為單位）（預設值：600000，或 10 分鐘；最大值：2147483647）。在緩慢網路上請求逾時或透過代理路由時增加此值。超過最大值的值會導致基礎計時器溢位，並導致請求立即失敗 |146| `API_TIMEOUT_MS` | API 請求的逾時（以毫秒為單位）（預設值：600000，或 10 分鐘；最大值：2147483647）。在緩慢網路上請求逾時或透過代理路由時增加此值。超過最大值的值會導致基礎計時器溢位，並導致請求立即失敗 |

147| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock API 金鑰用於驗證（請參閱 [Amazon Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |147| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock API 金鑰用於驗證（請參閱 [Amazon Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |

149| `BASH_MAX_OUTPUT_LENGTH` | bash 輸出中的最大字元數，超過此數量後完整輸出會儲存到檔案，Claude 會收到路徑加上簡短預覽。請參閱 [Bash tool behavior](/zh-TW/tools-reference#bash-tool-behavior) |149| `BASH_MAX_OUTPUT_LENGTH` | bash 輸出中的最大字元數，超過此數量後完整輸出會儲存到檔案，Claude 會收到路徑加上簡短預覽。請參閱 [Bash tool behavior](/docs/zh-TW/tools-reference#bash-tool-behavior) |

151| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --cloud`](/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 在 GitHub 存取可用時也要捆綁並上傳您的本機儲存庫 |151| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 在 GitHub 存取可用時也要捆綁並上傳您的本機儲存庫 |

152| `CLAUDECODE` | 在 Claude Code 生成的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/zh-TW/hooks) 命令、[status line](/zh-TW/statusline) 命令、stdio [MCP server](/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 生成的子程序內執行。若要檢查目前程序是否由工具呼叫或 hook 直接生成，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |152| `CLAUDECODE` | 在 Claude Code 生成的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[status line](/docs/zh-TW/statusline) 命令、stdio [MCP server](/docs/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 生成的子程序內執行。若要檢查目前程序是否由工具呼叫或 hook 直接生成，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |

153| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}在未回答的 [`AskUserQuestion`](/zh-TW/tools-reference) 對話框上自動繼續前，螢幕上倒數計時出現前的毫秒數。預設 `20000`（20 秒），上限為自動繼續逾時。除非自動繼續開啟，否則無效；請參閱 [`askUserQuestionTimeout`](/zh-TW/settings#available-settings) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |153| `CLAUDE_AFK_COUNTDOWN_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框上自動繼續前，螢幕上倒數計時出現前的毫秒數。預設 `20000`（20 秒），上限為自動繼續逾時。除非自動繼續開啟，否則無效；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings#available-settings) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |

154| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}在未回答的 [`AskUserQuestion`](/zh-TW/tools-reference) 對話框自動繼續前的閒置時間（以毫秒為單位）。{/* min-version: 2.1.200 */}自動繼續預設關閉；使用 [`askUserQuestionTimeout`](/zh-TW/settings#available-settings) 設定選擇加入。此變數是演示和自動化測試的覆蓋：設定時，它優先於該設定並開啟自動繼續，即使設定未設定或為 `never`。設定 `0` 不會關閉逾時；它會立即關閉對話框。在 v2.1.198 和 v2.1.199 中，自動繼續預設開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |154| `CLAUDE_AFK_TIMEOUT_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框自動繼續前的閒置時間（以毫秒為單位）。自動繼續預設關閉；使用 [`askUserQuestionTimeout`](/docs/zh-TW/settings#available-settings) 設定選擇加入。此變數是演示和自動化測試的覆蓋：設定時，它優先於該設定並開啟自動繼續，即使設定未設定或為 `never`。設定 `0` 不會關閉逾時；它會立即關閉對話框。在 v2.1.198 和 v2.1.199 中，自動繼續預設開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |

155| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |155| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/docs/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |

157| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 背景 subagents 的停滯逾時（以毫秒為單位）。預設 `600000`（10 分鐘）。計時器在每個串流進度事件時重設；如果在視窗內沒有進度到達，subagent 會被中止，任務會標記為失敗，將任何部分結果呈現給父級 |157| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 背景 subagents 的停滯逾時（以毫秒為單位）。預設 `600000`（10 分鐘）。計時器在每個串流進度事件時重設；如果在視窗內沒有進度到達，subagent 會被中止，任務會標記為失敗，將任何部分結果呈現給父級 |

158| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮觸發的上下文容量百分比 (1-100)。使用較低的值（如 `50`）以更早進行壓縮。此變數僅在 Claude Code 主動進行壓縮時導致更早壓縮：當設定 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 時、在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中、在沒有 [extended context](/zh-TW/model-config#extended-context) 的 Sonnet 4.6 和 Opus 4.6 上，預設在 200K 邊界進行壓縮。在 Sonnet 5 上，proactive compaction 在模型的 [default threshold](/zh-TW/model-config#sonnet-5-context-window) 處應用。在其他情況下，例如本機工作階段上的 Opus 4.8，當對話達到模型的上下文限制時，自動壓縮觸發。覆蓋只能降低閾值，因此高於預設值的值無效。適用於主要對話和 subagents |158| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮觸發的上下文容量百分比 (1-100)。使用較低的值（如 `50`）以更早進行壓縮。此變數僅在 Claude Code 主動進行壓縮時導致更早壓縮：當設定 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 時、在 [cloud sessions](/docs/zh-TW/claude-code-on-the-web) 中、在沒有 [extended context](/docs/zh-TW/model-config#extended-context) 的 Sonnet 4.6 和 Opus 4.6 上，預設在 200K 邊界進行壓縮。在 Sonnet 5 上，proactive compaction 在模型的 [default threshold](/docs/zh-TW/model-config#sonnet-5-context-window) 處應用。在其他情況下，例如本機工作階段上的 Opus 4.8，當對話達到模型的上下文限制時，自動壓縮觸發。覆蓋只能降低閾值，因此高於預設值的值無效。適用於主要對話和 subagents |

160| `CLAUDE_AX_SCREEN_READER` | {/* min-version: 2.1.181 */}設定為 `1` 以呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。設定為 `0` 以強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/zh-TW/settings#available-settings) 為 `true`。[`--ax-screen-reader`](/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |160| `CLAUDE_AX_SCREEN_READER` | 設定為 `1` 以呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。設定為 `0` 以強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings#available-settings) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |

162| `CLAUDE_CLIENT_PRESENCE_FILE` | {/* min-version: 2.1.181 */}外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立並在您鎖定螢幕時刪除的檔案路徑。檔案存在時，Claude Code 會跳過 [Remote Control mobile push notifications](/zh-TW/remote-control#mobile-push-notifications)，因此當您主動使用電腦時，您會停止收到推送。檔案不存在或無法讀取時，通知會正常發送。Claude Code 每次推送觸發事件檢查一次檔案，而不是輪詢它。需要 Claude Code v2.1.181 或更新版本 |162| `CLAUDE_CLIENT_PRESENCE_FILE` | 外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立並在您鎖定螢幕時刪除的檔案路徑。檔案存在時，Claude Code 會跳過 [Remote Control mobile push notifications](/docs/zh-TW/remote-control#mobile-push-notifications)，因此當您主動使用電腦時，您會停止收到推送。檔案不存在或無法讀取時，通知會正常發送。Claude Code 每次推送觸發事件檢查一次檔案，而不是輪詢它。需要 Claude Code v2.1.181 或更新版本 |

164| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設定為 `1` 以從使用 `--add-dir` 指定的目錄載入記憶體檔案。載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。預設情況下，其他目錄不載入記憶體檔案 |164| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設定為 `1` 以從使用 `--add-dir` 指定的目錄載入記憶體檔案。載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。預設情況下，其他目錄不載入記憶體檔案 |

165| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設定為 `1` 以在 [fullscreen rendering](/zh-TW/fullscreen) 中的每一幀上重新繪製整個螢幕，而不是發送增量更新。如果全螢幕模式顯示過時或錯位的文字片段，請使用此選項。Claude Code 在 Windows 上的背景工作階段和 [agent view](/zh-TW/agent-view) 中自動啟用此功能 |165| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設定為 `1` 以在 [fullscreen rendering](/docs/zh-TW/fullscreen) 中的每一幀上重新繪製整個螢幕，而不是發送增量更新。如果全螢幕模式顯示過時或錯位的文字片段，請使用此選項。Claude Code 在 Windows 上的背景工作階段和 [agent view](/docs/zh-TW/agent-view) 中自動啟用此功能 |

166| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設定為 `1` 以在每個請求中發送 [effort](/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 不將模型 ID 識別為支援努力的模型。在透過 [LLM gateway](/zh-TW/llm-gateway) 或第三方提供者路由時使用，該提供者在自訂識別碼下提供模型。在 API 中拒絕努力參數的模型，包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5，仍被排除，以便請求不會失敗 |166| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設定為 `1` 以在每個請求中發送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 不將模型 ID 識別為支援努力的模型。在透過 [LLM gateway](/docs/zh-TW/llm-gateway) 或第三方提供者路由時使用，該提供者在自訂識別碼下提供模型。在 API 中拒絕努力參數的模型，包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5，仍被排除，以便請求不會失敗 |

168| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 以停止 Claude Code 在發佈新 [artifact](/zh-TW/artifacts) 時自動開啟瀏覽器。重新發佈現有 artifact 無論此設定如何都不會開啟瀏覽器 |168| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 以停止 Claude Code 在發佈新 [artifact](/docs/zh-TW/artifacts) 時自動開啟瀏覽器。重新發佈現有 artifact 無論此設定如何都不會開啟瀏覽器 |

169| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |169| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/docs/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |

170| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/zh-TW/model-config#extended-context) 模型為 1M，除了 Sonnet 5，其具有自己的 [default threshold](/zh-TW/model-config#sonnet-5-context-window)。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |170| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/docs/zh-TW/model-config#extended-context) 模型為 1M，除了 Sonnet 5，其具有自己的 [default threshold](/docs/zh-TW/model-config#sonnet-5-context-window)。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |

171| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時。優先於 [`autoConnectIde`](/zh-TW/settings#global-config-settings) 全域配置設定 |171| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/docs/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時。優先於 [`autoConnectIde`](/docs/zh-TW/settings#global-config-settings) 全域配置設定 |

172| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | {/* min-version: 2.1.207 */}Claude Code 等待 AWS 預設認證提供者鏈產生認證的時間（以毫秒為單位），然後請求失敗並出現 [`AWS default-chain credential resolve timed out`](/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設值：`60000`）。當您的鏈中的步驟合法需要更長時間時提高此值，例如透過 `aws-vault` 等包裝器進行 MFA 的瀏覽器型 SSO 登入。適用於 Claude Code 使用預設鏈簽署的任何地方：[Amazon Bedrock](/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 和 [Mantle endpoint](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |172| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設認證提供者鏈產生認證的時間（以毫秒為單位），然後請求失敗並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設值：`60000`）。當您的鏈中的步驟合法需要更長時間時提高此值，例如透過 `aws-vault` 等包裝器進行 MFA 的瀏覽器型 SSO 登入。適用於 Claude Code 使用預設鏈簽署的任何地方：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和 [Mantle endpoint](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |

173| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}在工作階段具有作用中 [Remote Control](/zh-TW/remote-control) 連線時在 Bash 工具和 [hook command](/zh-TW/hooks) 子程序中自動設定，並在連線結束時移除。該值是工作階段的 ID，格式為 `session_`，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |173| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 在工作階段具有作用中 [Remote Control](/docs/zh-TW/remote-control) 連線時在 Bash 工具和 [hook command](/docs/zh-TW/hooks) 子程序中自動設定，並在連線結束時移除。該值是工作階段的 ID，格式為 `session_`，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [cloud sessions](/docs/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

174| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源逗號分隔清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區，在具有 `tls.getCACertificates` 的執行時上唯讀：原生二進位檔或 npm 安裝的 Node 22.15 或更新版本。請參閱 [CA certificate store](/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |174| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源逗號分隔清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區，在具有 `tls.getCACertificates` 的執行時上唯讀：原生二進位檔或 npm 安裝的 Node 22.15 或更新版本。請參閱 [CA certificate store](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |

175| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/zh-TW/hooks) 命令和 [status line](/zh-TW/statusline) 命令生成的子程序中設定為 `1`。不為 stdio [MCP server](/zh-TW/mcp) 子程序設定，這些是長期存在的，並且超過啟動它們的工作階段。與 `CLAUDECODE` 不同，這僅由 Claude Code 自己的生成路徑設定，而不是由 IDE 擴充功能設定，因此它可靠地區分嵌套工作階段與在 IDE 整合終端中啟動的頂層 `claude`。以這種方式啟動的嵌套互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上箭頭歷史記錄和 `claude agents` 清單中排除。非互動式 `claude -p` 工作階段仍然保留。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆蓋此排除。需要 Claude Code v2.1.172 或更新版本 |175| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令和 [status line](/docs/zh-TW/statusline) 命令生成的子程序中設定為 `1`。不為 stdio [MCP server](/docs/zh-TW/mcp) 子程序設定，這些是長期存在的，並且超過啟動它們的工作階段。與 `CLAUDECODE` 不同，這僅由 Claude Code 自己的生成路徑設定，而不是由 IDE 擴充功能設定，因此它可靠地區分嵌套工作階段與在 IDE 整合終端中啟動的頂層 `claude`。以這種方式啟動的嵌套互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上箭頭歷史記錄和 `claude agents` 清單中排除。非互動式 `claude -p` 工作階段仍然保留。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆蓋此排除。需要 Claude Code v2.1.172 或更新版本 |

179| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | {/* max-version: 2.1.185 */}在 v2.1.186 中移除，現在是無操作。先前設定串流 API 請求的連線、TLS 和回應標頭階段的逾時。使用 `API_TIMEOUT_MS` 進行每個請求的逾時 |179| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中移除，現在是無操作。先前設定串流 API 請求的連線、TLS 和回應標頭階段的逾時。使用 `API_TIMEOUT_MS` 進行每個請求的逾時 |

180| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆蓋偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而不是目錄。需要透過 `--debug`、`/debug` 或 `DEBUG` 環境變數單獨啟用偵錯模式：僅設定此變數不會啟用日誌記錄。[`--debug-file`](/zh-TW/cli-reference#cli-flags) 旗標同時執行兩者。預設為 `~/.claude/debug/<session-id>.txt` |180| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆蓋偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而不是目錄。需要透過 `--debug`、`/debug` 或 `DEBUG` 環境變數單獨啟用偵錯模式：僅設定此變數不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標同時執行兩者。預設為 `~/.claude/debug/<session-id>.txt` |

181| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷，例如完整狀態行命令輸出，或提高到 `error` 以減少雜訊 |181| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷，例如完整狀態行命令輸出，或提高到 `error` 以減少雜訊 |

182| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M context window](/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用，[Sonnet 5](/zh-TW/model-config#sonnet-5-context-window) 工作階段被視為具有 200K 視窗。對於具有合規性要求的企業環境很有用 |182| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M context window](/docs/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用，[Sonnet 5](/docs/zh-TW/model-config#sonnet-5-context-window) 工作階段被視為具有 200K 視窗。對於具有合規性要求的企業環境很有用 |

183| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 的 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。{/* min-version: 2.1.111 */}從 v2.1.111 起，對 Fable 5、Sonnet 5 或 Opus 4.7 及更新版本無效，其始終使用自適應推理 |183| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 的 [adaptive reasoning](/docs/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。從 v2.1.111 起，對 Fable 5、Sonnet 5 或 Opus 4.7 及更新版本無效，其始終使用自適應推理 |

184| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設定為 `1` 以停用 [advisor tool](/zh-TW/advisor)。`/advisor` 命令變為不可用，任何配置的 `advisorModel` 都會被忽略，`--advisor` 旗標被接受但無效，因此傳遞它的現有指令碼繼續工作而不出現錯誤 |184| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設定為 `1` 以停用 [advisor tool](/docs/zh-TW/advisor)。`/advisor` 命令變為不可用，任何配置的 `advisorModel` 都會被忽略，`--advisor` 旗標被接受但無效，因此傳遞它的現有指令碼繼續工作而不出現錯誤 |

185| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 以關閉 [background agents and agent view](/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和隨選主管。相當於 [`disableAgentView`](/zh-TW/settings#available-settings) 設定 |185| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 以關閉 [background agents and agent view](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和隨選主管。相當於 [`disableAgentView`](/docs/zh-TW/settings#available-settings) 設定 |

186| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 並使用經典主螢幕渲染器。對話保留在您終端的原生捲動回溯中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-TW/settings#available-settings) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/zh-TW/agent-view) 開啟的背景工作階段，其始終使用全螢幕渲染 |186| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [fullscreen rendering](/docs/zh-TW/fullscreen) 並使用經典主螢幕渲染器。對話保留在您終端的原生捲動回溯中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-TW/settings#available-settings) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/docs/zh-TW/agent-view) 開啟的背景工作階段，其始終使用全螢幕渲染 |

187| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 以停用 [Artifact](/zh-TW/artifacts) 工具，該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。相當於 [`disableArtifact`](/zh-TW/settings#available-settings) 設定 |187| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 以停用 [Artifact](/docs/zh-TW/artifacts) 工具，該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。相當於 [`disableArtifact`](/docs/zh-TW/settings#available-settings) 設定 |

189| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [auto memory](/zh-TW/memory#auto-memory)。設定為 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-TW/settings#available-settings) 會以其他方式停用時強制啟用自動記憶體。停用時，Claude 不會建立或載入自動記憶體檔案 |189| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [auto memory](/docs/zh-TW/memory#auto-memory)。設定為 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings#available-settings) 會以其他方式停用時強制啟用自動記憶體。停用時，Claude 不會建立或載入自動記憶體檔案 |

190| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 以停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景執行和 Ctrl+B 快捷鍵 |190| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 以停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景執行和 Ctrl+B 快捷鍵 |

191| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | {/* min-version: 2.1.208 */}設定為 `1` 以跳過檢查 [Amazon Bedrock](/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` 內容類型。沒有此變數，具有不同內容類型的回應會失敗並出現命名該內容類型的錯誤，這意味著 [gateway or proxy is transforming the response](/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。僅當閘道重寫 `Content-Type` 標頭但未修改的二進位事件串流主體通過時設定它；如果主體本身被轉換，請求會改為失敗並出現 `Truncated event message received`。需要 Claude Code v2.1.208 或更新版本 |191| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設定為 `1` 以跳過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` 內容類型。沒有此變數，具有不同內容類型的回應會失敗並出現命名該內容類型的錯誤，這意味著 [gateway or proxy is transforming the response](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。僅當閘道重寫 `Content-Type` 標頭但未修改的二進位事件串流主體通過時設定它；如果主體本身被轉換，請求會改為失敗並出現 `Truncated event message received`。需要 Claude Code v2.1.208 或更新版本 |

192| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}設定為 `1` 以停止 [background session](/zh-TW/agent-view) 的執行中背景 shell 命令、動態工作流程，{/* min-version: 2.1.198 */}以及自 v2.1.198 起的背景 subagents，當 [supervisor](/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新該工作階段的程序時，而不是將它們交給工作階段的下一個程序。僅影響該交接：使用 `←` 或 [`/background`](/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化仍會帶入進行中的工作，`CLAUDE_DISABLE_ADOPT` 會關閉兩者。需要 Claude Code v2.1.196 或更新版本 |192| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設定為 `1` 以停止 [background session](/docs/zh-TW/agent-view) 的執行中背景 shell 命令、動態工作流程，以及自 v2.1.198 起的背景 subagents，當 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新該工作階段的程序時，而不是將它們交給工作階段的下一個程序。僅影響該交接：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化仍會帶入進行中的工作，`CLAUDE_DISABLE_ADOPT` 會關閉兩者。需要 Claude Code v2.1.196 或更新版本 |

193| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}設定為 `1` 以停止 Claude Code 在作業系統報告記憶體壓力時終止 [background shell commands](/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 和 Linux 上，Claude Code 在主工作階段中啟動的背景 shell 在記憶體壓力信號上終止，一旦工作階段已閒置 30 分鐘且沒有回合或 subagent 執行。Windows 沒有記憶體壓力信號，因此此變數對其無效。需要 Claude Code v2.1.193 或更新版本 |193| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設定為 `1` 以停止 Claude Code 在作業系統報告記憶體壓力時終止 [background shell commands](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 和 Linux 上，Claude Code 在主工作階段中啟動的背景 shell 在記憶體壓力信號上終止，一旦工作階段已閒置 30 分鐘且沒有回合或 subagent 執行。Windows 沒有記憶體壓力信號，因此此變數對其無效。需要 Claude Code v2.1.193 或更新版本 |

194| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 以停用隨 Claude Code 提供的 [skills](/zh-TW/skills) 和工作流程：捆綁的 skills 和工作流程會完全移除，而內建的斜線命令（如 `/init`）保持可輸入但對模型隱藏。來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影響。相當於 [`disableBundledSkills`](/zh-TW/settings#available-settings) 設定；`0` 不會覆蓋它 |194| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 以停用隨 Claude Code 提供的 [skills](/docs/zh-TW/skills) 和工作流程：捆綁的 skills 和工作流程會完全移除，而內建的斜線命令（如 `/init`）保持可輸入但對模型隱藏。來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影響。相當於 [`disableBundledSkills`](/docs/zh-TW/settings#available-settings) 設定；`0` 不會覆蓋它 |

196| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [scheduled tasks](/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具變為不可用，任何已排程的任務停止觸發，包括已在工作階段中執行的任務 |196| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [scheduled tasks](/docs/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具變為不可用，任何已排程的任務停止觸發，包括已在工作階段中執行的任務 |

197| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和 beta 工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現「Unexpected value(s) for the `anthropic-beta` header」或「Extra inputs are not permitted」之類的錯誤時，請使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）會保留。[MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 會停用，所有 MCP 工具會提前載入，即使設定 `ENABLE_TOOL_SEARCH` |197| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和 beta 工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現「Unexpected value(s) for the `anthropic-beta` header」或「Extra inputs are not permitted」之類的錯誤時，請使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）會保留。[MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 會停用，所有 MCP 工具會提前載入，即使設定 `ENABLE_TOOL_SEARCH` |

198| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | {/* min-version: 2.1.198 */}設定為 `1` 以停用內建的 [Explore and Plan subagents](/zh-TW/sub-agents#built-in-subagents)。Claude 改為使用其搜尋工具或通用 subagent 進行探索，[plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 直接讀取檔案而不是啟動 Explore 和 Plan agents。名為 `Explore` 或 `Plan` 的自訂 subagents 不受影響。若要在 Agent SDK 或非互動式模式中移除每個內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |198| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設定為 `1` 以停用內建的 [Explore and Plan subagents](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 改為使用其搜尋工具或通用 subagent 進行探索，[plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 直接讀取檔案而不是啟動 Explore 和 Plan agents。名為 `Explore` 或 `Plan` 的自訂 subagents 不受影響。若要在 Agent SDK 或非互動式模式中移除每個內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |

200| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇加入。若要改為設定樣本速率，請使用 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/zh-TW/data-usage#session-quality-surveys) |200| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇加入。若要改為設定樣本速率，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/docs/zh-TW/data-usage#session-quality-surveys) |

201| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設定為 `1` 以停用檔案 [checkpointing](/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更 |201| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設定為 `1` 以停用檔案 [checkpointing](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更 |

202| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/zh-TW/settings#available-settings) 設定 |202| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/docs/zh-TW/settings#available-settings) 設定 |

203| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |203| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |

204| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍然有效。使用此選項可保留您終端的原生選擇複製行為 |204| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [fullscreen rendering](/docs/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍然有效。使用此選項可保留您終端的原生選擇複製行為 |

205| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | {/* min-version: 2.1.195 */}設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保留滑鼠滾輪捲動。當您想要滾輪捲動在 Claude Code 內工作但不想要點擊來定位游標、展開工具輸出或開啟連結時使用。當兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |205| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設定為 `1` 以停用 [fullscreen rendering](/docs/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保留滑鼠滾輪捲動。當您想要滾輪捲動在 Claude Code 內工作但不想要點擊來定位游標、展開工具輸出或開啟連結時使用。當兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |

206| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 相當於設定 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |206| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 相當於設定 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |

208| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | {/* min-version: 2.1.193 */}設定為 `1` 以在您在終端中輸入或聚焦時發送 `PushNotification` 工具的桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端焦點時，工具會跳過桌面通知和 [mobile push](/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此伺服器仍可在偵測到您活躍時抑制行動推送。需要 Claude Code v2.1.193 或更新版本 |208| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設定為 `1` 以在您在終端中輸入或聚焦時發送 `PushNotification` 工具的桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端焦點時，工具會跳過桌面通知和 [mobile push](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此伺服器仍可在偵測到您活躍時抑制行動推送。需要 Claude Code v2.1.193 或更新版本 |

211| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 以停用基於對話上下文的自動終端標題更新。在 Agent SDK 和 `claude -p` 工作階段中，這也會跳過產生工作階段標題的背景 Haiku 請求 |211| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 以停用基於對話上下文的自動終端標題更新。在 Agent SDK 和 `claude -p` 工作階段中，這也會跳過產生工作階段標題的背景 Haiku 請求 |

212| `CLAUDE_CODE_DISABLE_THINKING` | 設定為 `1` 以完全省略 API 請求中的 `thinking` 參數。這是代理和閘道拒絕該參數的相容性選項。該變數的行為與早期版本相同；在預設思考的模型上，省略該參數意味著模型仍可能思考。若要在 Anthropic API 上明確停用 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`，這在 Fable 5 上也無效，因為它無法關閉思考。在 [third-party providers](/zh-TW/third-party-integrations) 上，`0` 同樣省略該參數，因此兩個變數在那裡的行為相同 |212| `CLAUDE_CODE_DISABLE_THINKING` | 設定為 `1` 以完全省略 API 請求中的 `thinking` 參數。這是代理和閘道拒絕該參數的相容性選項。該變數的行為與早期版本相同；在預設思考的模型上，省略該參數意味著模型仍可能思考。若要在 Anthropic API 上明確停用 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`，這在 Fable 5 上也無效，因為它無法關閉思考。在 [third-party providers](/docs/zh-TW/third-party-integrations) 上，`0` 同樣省略該參數，因此兩個變數在那裡的行為相同 |

213| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的虛擬捲動，並呈現文字記錄中的每條訊息。如果全螢幕模式中的捲動顯示應該出現訊息的空白區域，請使用此選項 |213| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 以停用 [fullscreen rendering](/docs/zh-TW/fullscreen) 中的虛擬捲動，並呈現文字記錄中的每條訊息。如果全螢幕模式中的捲動顯示應該出現訊息的空白區域，請使用此選項 |

214| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 以停用 [workflows](/zh-TW/workflows#turn-workflows-off)。相當於 [`disableWorkflows`](/zh-TW/settings#available-settings) 設定 |214| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 以停用 [workflows](/docs/zh-TW/workflows#turn-workflows-off)。相當於 [`disableWorkflows`](/docs/zh-TW/settings#available-settings) 設定 |

215| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/zh-TW/model-config#adjust-effort-level) |215| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/docs/zh-TW/model-config#adjust-effort-level) |

216| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | {/* min-version: 2.1.205 */}設定為 `1` 以啟用將額外文字附加到每個 [subagent](/zh-TW/sub-agents) 系統提示的末尾。[`--append-subagent-system-prompt`](/zh-TW/cli-reference#cli-flags) 旗標提供附加的文字並自動設定此變數，因此您不需要自己設定它。需要 Claude Code v2.1.205 或更新版本 |216| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | 設定為 `1` 以啟用將額外文字附加到每個 [subagent](/docs/zh-TW/sub-agents) 系統提示的末尾。[`--append-subagent-system-prompt`](/docs/zh-TW/cli-reference#cli-flags) 旗標提供附加的文字並自動設定此變數，因此您不需要自己設定它。需要 Claude Code v2.1.205 或更新版本 |

217| `CLAUDE_CODE_ENABLE_AUTO_MODE` | {/* min-version: 2.1.207 */}為相容性接受，無效。Auto mode 在每個提供者上預設可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 到 v2.1.206 中，設定此項為 `1` 是在這些提供者上提供 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 所需的 |217| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為相容性接受，無效。Auto mode 在每個提供者上預設可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和已登入的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 到 v2.1.206 中，設定此項為 `1` 是在這些提供者上提供 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 所需的 |

218| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |218| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/docs/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/docs/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |

219| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](/zh-TW/prompt-caching) 失效 |219| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/docs/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](/docs/zh-TW/prompt-caching) 失效 |

220| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry collector](/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料發送到 Anthropic。在設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品反饋政策優先 |220| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry collector](/docs/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料發送到 Anthropic。在設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品反饋政策優先 |

221| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，按模型啟用，其中已部署的容器支援它。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Microsoft Foundry 和 [gateway](/zh-TW/llm-gateway) 連線上預設關閉 |221| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，按模型啟用，其中已部署的容器支援它。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Microsoft Foundry 和 [gateway](/docs/zh-TW/llm-gateway) 連線上預設關閉 |

222| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選，工作階段接收；由於 [server-managed delivery is not available on gateway configurations](/zh-TW/server-managed-settings#platform-availability)，透過 MDM 或受管設定檔案傳遞清單 |222| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/docs/zh-TW/settings#available-settings) 允許清單篩選，工作階段接收；由於 [server-managed delivery is not available on gateway configurations](/docs/zh-TW/server-managed-settings#platform-availability)，透過 MDM 或受管設定檔案傳遞清單 |

223| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {{/* max-version: 2.1.141 */}}在 v2.1.142 中移除，當 [fast mode](/zh-TW/fast-mode) 預設從 Opus 4.6 移至 Opus 4.7 時 |223| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {{/* max-version: 2.1.141 */}}在 v2.1.142 中移除，當 [fast mode](/docs/zh-TW/fast-mode) 預設從 Opus 4.6 移至 Opus 4.7 時 |

224| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |224| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/docs/zh-TW/interactive-mode#prompt-suggestions) |

225| `CLAUDE_CODE_ENABLE_TASKS` | 控制工作階段是否使用結構化 Task 工具（`TaskCreate`、`TaskUpdate`、`TaskGet`、`TaskList`）或舊版 `TodoWrite` 工具。{{/* min-version: 2.1.142 */}}自 Claude Code v2.1.142 起，Task 工具是所有模式中的預設值。設定為 `0` 以還原為 `TodoWrite`。請參閱 [Task list](/zh-TW/interactive-mode#task-list) 和 [Migrate to Task tools](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) |225| `CLAUDE_CODE_ENABLE_TASKS` | 控制工作階段是否使用結構化 Task 工具（`TaskCreate`、`TaskUpdate`、`TaskGet`、`TaskList`）或舊版 `TodoWrite` 工具。{{/* min-version: 2.1.142 */}}自 Claude Code v2.1.142 起，Task 工具是所有模式中的預設值。設定為 `0` 以還原為 `TodoWrite`。請參閱 [Task list](/docs/zh-TW/interactive-mode#task-list) 和 [Migrate to Task tools](/docs/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) |

226| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用 OpenTelemetry 資料收集以進行指標和日誌記錄。在配置 OTel 匯出器之前需要。請參閱 [Monitoring](/zh-TW/monitoring-usage) |226| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用 OpenTelemetry 資料收集以進行指標和日誌記錄。在配置 OTel 匯出器之前需要。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

229| `CLAUDE_CODE_EXTRA_BODY` | JSON 物件以合併到每個 API 請求主體的頂層。對於傳遞 Claude Code 不直接公開的提供者特定參數很有用。{/* min-version: 2.1.206 */}在您的 shell 中匯出的值也適用於您使用 `claude agents` 或 `--bg` 分派的 [background sessions](/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段忽略了 shell 匯出的值，並使用背景主管程序繼承的任何副本 |229| `CLAUDE_CODE_EXTRA_BODY` | JSON 物件以合併到每個 API 請求主體的頂層。對於傳遞 Claude Code 不直接公開的提供者特定參數很有用。在您的 shell 中匯出的值也適用於您使用 `claude agents` 或 `--bg` 分派的 [background sessions](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段忽略了 shell 匯出的值，並使用背景主管程序繼承的任何副本 |

231| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {{/* min-version: 2.1.172 */}}設定為 `1` 以強制文字記錄持久化、提示歷史記錄和 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的。在繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 Claude Code 的 Bash 工具首次啟動的 `screen` 工作階段）導致真正的頂層工作階段被誤分類為嵌套時使用。{{/* min-version: 2.1.178 */}}自 v2.1.178 起，Claude Code 會自動偵測 tmux 情況並忽略繼承的標記，因此 tmux 不再需要此變數。也在 v2.1.169 及更早版本上受尊重；對 v2.1.170 和 v2.1.171 無效，其中它覆蓋的嵌套工作階段偵測被移除 |231| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {{/* min-version: 2.1.172 */}}設定為 `1` 以強制文字記錄持久化、提示歷史記錄和 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的。在繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 Claude Code 的 Bash 工具首次啟動的 `screen` 工作階段）導致真正的頂層工作階段被誤分類為嵌套時使用。{{/* min-version: 2.1.178 */}}自 v2.1.178 起，Claude Code 會自動偵測 tmux 情況並忽略繼承的標記，因此 tmux 不再需要此變數。也在 v2.1.169 及更早版本上受尊重；對 v2.1.170 和 v2.1.171 無效，其中它覆蓋的嵌套工作階段偵測被移除 |

232| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {{/* min-version: 2.1.186 */}}設定為 `1` 以在您的終端支援但未自動偵測時強制刪除線呈現 `~~text~~`，例如透過 SSH 而未轉發 `TERM_PROGRAM`。沒有此選項，未偵測的終端會顯示文字刪除線標記而不是呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |232| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {{/* min-version: 2.1.186 */}}設定為 `1` 以在您的終端支援但未自動偵測時強制刪除線呈現 `~~text~~`，例如透過 SSH 而未轉發 `TERM_PROGRAM`。沒有此選項，未偵測的終端會顯示文字刪除線標記而不是呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |

233| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以強制啟用 DEC 私有模式 2026 [synchronized output](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)（當您的終端支援但未自動偵測時）。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效。與 `CLAUDE_CODE_NO_FLICKER` 不同，後者會切換到 [fullscreen rendering](/zh-TW/fullscreen)，這不會改變渲染器 |233| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以強制啟用 DEC 私有模式 2026 [synchronized output](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)（當您的終端支援但未自動偵測時）。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效。與 `CLAUDE_CODE_NO_FLICKER` 不同，後者會切換到 [fullscreen rendering](/docs/zh-TW/fullscreen)，這不會改變渲染器 |

234| `CLAUDE_CODE_FORK_SUBAGENT` | 設定為 `1` 以啟用 Claude 生成 [forked subagents](/zh-TW/sub-agents#fork-the-current-conversation)，或 `0` 以停用它們，覆蓋任何伺服器端推出。啟用時，Claude 可以要求 `fork` subagent 類型以生成分叉，一個繼承完整對話上下文而不是從頭開始的 subagent。沒有 subagent 類型的生成仍使用通用 subagent，所有 subagent 生成都在背景中執行。明確的 [`/fork`](/zh-TW/commands) 命令無需此變數即可工作。在互動式模式和透過 SDK 或 `claude -p` 中工作 |234| `CLAUDE_CODE_FORK_SUBAGENT` | 設定為 `1` 以啟用 Claude 生成 [forked subagents](/docs/zh-TW/sub-agents#fork-the-current-conversation)，或 `0` 以停用它們，覆蓋任何伺服器端推出。啟用時，Claude 可以要求 `fork` subagent 類型以生成分叉，一個繼承完整對話上下文而不是從頭開始的 subagent。沒有 subagent 類型的生成仍使用通用 subagent，所有 subagent 生成都在背景中執行。明確的 [`/fork`](/docs/zh-TW/commands) 命令無需此變數即可工作。在互動式模式和透過 SDK 或 `claude -p` 中工作 |

235| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔（`bash.exe`）的路徑。在 Git Bash 已安裝但不在您的 PATH 中時使用。請參閱 [Windows setup](/zh-TW/setup#set-up-on-windows) |235| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔（`bash.exe`）的路徑。在 Git Bash 已安裝但不在您的 PATH 中時使用。請參閱 [Windows setup](/docs/zh-TW/setup#set-up-on-windows) |

236| `CLAUDE_CODE_GLOB_HIDDEN` | 設定為 `false` 以在 Claude 呼叫 [Glob tool](/zh-TW/tools-reference#glob-tool-behavior) 時從結果中排除隱藏檔案。預設包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |236| `CLAUDE_CODE_GLOB_HIDDEN` | 設定為 `false` 以在 Claude 呼叫 [Glob tool](/docs/zh-TW/tools-reference#glob-tool-behavior) 時從結果中排除隱藏檔案。預設包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |

237| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設定為 `false` 以使 [Glob tool](/zh-TW/tools-reference#glob-tool-behavior) 尊重 `.gitignore` 模式。預設情況下，Glob 返回所有符合的檔案，包括 gitignored 的檔案。不影響 `@` 檔案自動完成，其具有自己的 [`respectGitignore` 設定](/zh-TW/settings#available-settings) |237| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設定為 `false` 以使 [Glob tool](/docs/zh-TW/tools-reference#glob-tool-behavior) 尊重 `.gitignore` 模式。預設情況下，Glob 返回所有符合的檔案，包括 gitignored 的檔案。不影響 `@` 檔案自動完成，其具有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings#available-settings) |

241| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設定為 `1` 以跳過 IDE 擴充功能的自動安裝。相當於將 [`autoInstallIdeExtension`](/zh-TW/settings#global-config-settings) 設定為 `false` |241| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設定為 `1` 以跳過 IDE 擴充功能的自動安裝。相當於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings#global-config-settings) 設定為 `false` |

243| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆蓋 Claude Code 假設用於作用中模型的上下文視窗大小。{{/* min-version: 2.1.193 */}}自 v2.1.193 起，直接應用於 Claude Code 不識別為 Claude 模型的模型名稱；對於識別的 Claude 模型，僅當同時設定 `DISABLE_COMPACT` 時才生效。當透過 `ANTHROPIC_BASE_URL` 路由到模型時使用，其上下文視窗與其名稱的內建大小不符 |243| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆蓋 Claude Code 假設用於作用中模型的上下文視窗大小。{{/* min-version: 2.1.193 */}}自 v2.1.193 起，直接應用於 Claude Code 不識別為 Claude 模型的模型名稱；對於識別的 Claude 模型，僅當同時設定 `DISABLE_COMPACT` 時才生效。當透過 `ANTHROPIC_BASE_URL` 路由到模型時使用，其上下文視窗與其名稱的內建大小不符 |

244| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值和上限因模型而異；請參閱 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值會減少在 [auto-compaction](/zh-TW/costs#reduce-token-usage) 觸發之前可用的有效上下文視窗 |244| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值和上限因模型而異；請參閱 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值會減少在 [auto-compaction](/docs/zh-TW/costs#reduce-token-usage) 觸發之前可用的有效上下文視窗 |

245| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設值：10）。{{/* min-version: 2.1.186 */}}自 v2.1.186 起上限為 15；{{/* min-version: 2.1.199 */}}自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要等待較長中斷的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |245| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設值：10）。{{/* min-version: 2.1.186 */}}自 v2.1.186 起上限為 15；{{/* min-version: 2.1.199 */}}自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要等待較長中斷的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |

247| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，限制代理回合的數量。相當於傳遞 [`--max-turns`](/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時會被拒絕並出現錯誤，而不是被視為無限制 |247| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，限制代理回合的數量。相當於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時會被拒絕並出現錯誤，而不是被視為無限制 |

249| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | {{/* min-version: 2.1.187 */}}MCP 工具呼叫的閒置逾時（以毫秒為單位）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai connector](/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此期間內沒有發送回應和進度通知時，工具呼叫會中止並出現錯誤，而不是等待整體 `MCP_TOOL_TIMEOUT`。覆蓋網路伺服器的每個傳輸預設值 300000（5 分鐘）和 stdio 伺服器的 1800000（30 分鐘）。設定為 `0` 以停用閒置檢查。低於 1000 的值會提高到 1 秒，該值上限為有效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中的每個伺服器 `timeout` 至少 1000 會將該伺服器的閒置視窗提高到至少 `timeout` 值。不適用於 IDE 伺服器或 SDK 進程內伺服器。需要 Claude Code v2.1.187 或更新版本。{{/* min-version: 2.1.203 */}}在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |249| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | {{/* min-version: 2.1.187 */}}MCP 工具呼叫的閒置逾時（以毫秒為單位）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai connector](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此期間內沒有發送回應和進度通知時，工具呼叫會中止並出現錯誤，而不是等待整體 `MCP_TOOL_TIMEOUT`。覆蓋網路伺服器的每個傳輸預設值 300000（5 分鐘）和 stdio 伺服器的 1800000（30 分鐘）。設定為 `0` 以停用閒置檢查。低於 1000 的值會提高到 1 秒，該值上限為有效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中的每個伺服器 `timeout` 至少 1000 會將該伺服器的閒置視窗提高到至少 `timeout` 值。不適用於 IDE 伺服器或 SDK 進程內伺服器。需要 Claude Code v2.1.187 或更新版本。{{/* min-version: 2.1.203 */}}在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |

251| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |251| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |

252| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |252| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/docs/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/docs/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |

253| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 會直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |253| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 會直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |

254| `CLAUDE_CODE_OAUTH_SCOPES` | 重新整理權杖發出時所使用的空格分隔 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必需 |254| `CLAUDE_CODE_OAUTH_SCOPES` | 重新整理權杖發出時所使用的空格分隔 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必需 |

255| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 驗證的 OAuth 存取權杖。`/login` 對於 SDK 和自動化環境的替代方案。優先於鑰匙圈儲存的認證。使用 [`claude setup-token`](/zh-TW/authentication#generate-a-long-lived-token) 產生一個 |255| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 驗證的 OAuth 存取權杖。`/login` 對於 SDK 和自動化環境的替代方案。優先於鑰匙圈儲存的認證。使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生一個 |

256| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | {{/* max-version: 2.1.159 */}}在 v2.1.160 中移除，現在是無操作。先前將 [fast mode](/zh-TW/fast-mode) 固定到 Claude Opus 4.6，而不是目前的預設值。Opus 4.6 不再支援快速模式 |256| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | {{/* max-version: 2.1.159 */}}在 v2.1.160 中移除，現在是無操作。先前將 [fast mode](/docs/zh-TW/fast-mode) 固定到 Claude Opus 4.6，而不是目前的預設值。Opus 4.6 不再支援快速模式 |

257| `CLAUDE_CODE_OTEL_DIAG_STDERR` | {{/* min-version: 2.1.179 */}}設定為 `1` 以將 OpenTelemetry 匯出器診斷錯誤寫入 stderr。預設情況下，這些錯誤僅在 `--debug` 時出現，因此配置不當的匯出器（例如 Prometheus 連接埠衝突）會以其他方式無聲失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [Monitoring](/zh-TW/monitoring-usage) |257| `CLAUDE_CODE_OTEL_DIAG_STDERR` | {{/* min-version: 2.1.179 */}}設定為 `1` 以將 OpenTelemetry 匯出器診斷錯誤寫入 stderr。預設情況下，這些錯誤僅在 `--debug` 時出現，因此配置不當的匯出器（例如 Prometheus 連接埠衝突）會以其他方式無聲失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

258| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待處理 OpenTelemetry spans 的逾時（以毫秒為單位）（預設值：5000）。請參閱 [Monitoring](/zh-TW/monitoring-usage) |258| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待處理 OpenTelemetry spans 的逾時（以毫秒為單位）（預設值：5000）。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

259| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（以毫秒為單位）（預設值：1740000 / 29 分鐘）。請參閱 [Dynamic headers](/zh-TW/monitoring-usage#dynamic-headers) |259| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（以毫秒為單位）（預設值：1740000 / 29 分鐘）。請參閱 [Dynamic headers](/docs/zh-TW/monitoring-usage#dynamic-headers) |

260| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成的逾時（以毫秒為單位）（預設值：2000）。如果指標在退出時被丟棄，請增加此值。請參閱 [Monitoring](/zh-TW/monitoring-usage) |260| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成的逾時（以毫秒為單位）（預設值：2000）。如果指標在退出時被丟棄，請增加此值。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

261| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設定為 `1` 以讓 Claude Code 在新版本可用時在背景中執行您的套件管理員的升級命令。適用於 Homebrew 和 WinGet 安裝。其他套件管理員繼續顯示升級命令而不執行它。請參閱 [Auto updates](/zh-TW/setup#auto-updates) |261| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設定為 `1` 以讓 Claude Code 在新版本可用時在背景中執行您的套件管理員的升級命令。適用於 Homebrew 和 WinGet 安裝。其他套件管理員繼續顯示升級命令而不執行它。請參閱 [Auto updates](/docs/zh-TW/setup#auto-updates) |

262| `CLAUDE_CODE_PERFORCE_MODE` | 設定為 `1` 以啟用 Perforce 感知寫入保護。設定時，如果目標檔案缺少擁有者寫入位元（Perforce 在同步的檔案上清除，直到 `p4 edit` 開啟它們），Edit、Write 和 NotebookEdit 會失敗並提示 `p4 edit <file>`。這可防止 Claude Code 繞過 Perforce 變更追蹤 |262| `CLAUDE_CODE_PERFORCE_MODE` | 設定為 `1` 以啟用 Perforce 感知寫入保護。設定時，如果目標檔案缺少擁有者寫入位元（Perforce 在同步的檔案上清除，直到 `p4 edit` 開啟它們），Edit、Write 和 NotebookEdit 會失敗並提示 `p4 edit <file>`。這可防止 Claude Code 繞過 Perforce 變更追蹤 |

264| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安裝或更新外掛程式時 git 操作的逾時（以毫秒為單位）（預設值：120000）。對於大型儲存庫或網路連線緩慢，請增加此值。請參閱 [Git operations time out](/zh-TW/plugin-marketplaces#git-operations-time-out) |264| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安裝或更新外掛程式時 git 操作的逾時（以毫秒為單位）（預設值：120000）。對於大型儲存庫或網路連線緩慢，請增加此值。請參閱 [Git operations time out](/docs/zh-TW/plugin-marketplaces#git-operations-time-out) |

265| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設定為 `1` 以在 `git pull` 失敗時保留現有的市場快取，而不是擦除並重新複製。在離線或隔離環境中很有用，其中重新複製會以相同方式失敗。請參閱 [Marketplace updates fail in offline environments](/zh-TW/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |265| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設定為 `1` 以在 `git pull` 失敗時保留現有的市場快取，而不是擦除並重新複製。在離線或隔離環境中很有用，其中重新複製會以相同方式失敗。請參閱 [Marketplace updates fail in offline environments](/docs/zh-TW/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |

266| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設定為 `1` 以透過 HTTPS 而不是 SSH 複製 GitHub `owner/repo` 外掛程式來源。在 CI 執行器、容器或任何沒有為 `github.com` 配置 SSH 金鑰的環境中很有用 |266| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設定為 `1` 以透過 HTTPS 而不是 SSH 複製 GitHub `owner/repo` 外掛程式來源。在 CI 執行器、容器或任何沒有為 `github.com` 配置 SSH 金鑰的環境中很有用 |

267| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛程式種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此選項可將預先填充的外掛程式目錄捆綁到容器映像中。Claude Code 在啟動時從這些目錄註冊市場，並使用預先快取的外掛程式而無需重新複製。請參閱 [Pre-populate plugins for containers](/zh-TW/plugin-marketplaces#pre-populate-plugins-for-containers) |267| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛程式種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此選項可將預先填充的外掛程式目錄捆綁到容器映像中。Claude Code 在啟動時從這些目錄註冊市場，並使用預先快取的外掛程式而無需重新複製。請參閱 [Pre-populate plugins for containers](/docs/zh-TW/plugin-marketplaces#pre-populate-plugins-for-containers) |

268| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在生成 PowerShell 以進行工具呼叫、hooks 和狀態行命令時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下，Claude Code 在程序範圍內繞過執行政策，以便 `.ps1` 指令碼和模組匯入在預設受限的 Windows 安裝上工作。無論此設定如何，程序範圍繞過永遠不會覆蓋群組原則 `MachinePolicy` 或 `UserPolicy` |268| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在生成 PowerShell 以進行工具呼叫、hooks 和狀態行命令時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下，Claude Code 在程序範圍內繞過執行政策，以便 `.ps1` 指令碼和模組匯入在預設受限的 Windows 安裝上工作。無論此設定如何，程序範圍繞過永遠不會覆蓋群組原則 `MachinePolicy` 或 `UserPolicy` |

269| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {{/* min-version: 2.1.182 */}}[非互動式模式](/zh-TW/headless#background-tasks-at-exit)使用 `-p` 旗標在最終回合後等待的最大時間（以毫秒為單位），用於背景 subagents 和工作流程，其結果是輸出的一部分。預設值：`600000`，或 10 分鐘。超過上限時，剩餘背景任務會被終止，程序會退出。設定為 `0` 以無限期等待。此上限與適用於純背景 shells 的 5 秒寬限期分開 |269| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {{/* min-version: 2.1.182 */}}[非互動式模式](/docs/zh-TW/headless#background-tasks-at-exit)使用 `-p` 旗標在最終回合後等待的最大時間（以毫秒為單位），用於背景 subagents 和工作流程，其結果是輸出的一部分。預設值：`600000`，或 10 分鐘。超過上限時，剩餘背景任務會被終止，程序會退出。設定為 `0` 以無限期等待。此上限與適用於純背景 shells 的 5 秒寬限期分開 |

270| `CLAUDE_CODE_PROCESS_WRAPPER` | {/* min-version: 2.1.208 */}透過包裝器可執行檔啟動 Claude Code 從其自己的二進位檔啟動的程序，指定為 argv 前綴，例如 `/opt/corp/launcher`。涵蓋託管 [agent view](/zh-TW/agent-view) 工作階段的背景服務、它生成的每個工作階段以及 Claude Code 執行自身以完成安裝更新的重新啟動。第一個權杖必須是以 `exec "$@"` 結尾的可執行檔的絕對路徑，大多數啟動器都是該單一路徑。該值是引數清單，而不是 shell 命令：空格分隔權杖，雙引號將包含空格的路徑分組，以 `[` 開頭的值會讀取為 JSON 字串陣列。在使用者或 [managed settings](/zh-TW/permissions#managed-settings) 的 `env` 區塊中設定它，而不是作為 shell 匯出，以便分離的背景服務繼承它；專案和本機設定無法設定它。VS Code 擴充功能透過其 `claudeProcessWrapper` 設定單獨配置其自己的啟動器。在 Windows 上被忽略。`CLAUDE_CODE_SHELL_PREFIX` 是一個單獨的控制：它將 Claude Code 執行的 shell 命令包裝為單個引用的字串，而此變數將 Claude Code 自己的程序包裝為 argv 前綴。請參閱 [Run Claude Code behind a corporate launcher](/zh-TW/corporate-launcher) |270| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過包裝器可執行檔啟動 Claude Code 從其自己的二進位檔啟動的程序，指定為 argv 前綴，例如 `/opt/corp/launcher`。涵蓋託管 [agent view](/docs/zh-TW/agent-view) 工作階段的背景服務、它生成的每個工作階段以及 Claude Code 執行自身以完成安裝更新的重新啟動。第一個權杖必須是以 `exec "$@"` 結尾的可執行檔的絕對路徑，大多數啟動器都是該單一路徑。該值是引數清單，而不是 shell 命令：空格分隔權杖，雙引號將包含空格的路徑分組，以 `[` 開頭的值會讀取為 JSON 字串陣列。在使用者或 [managed settings](/docs/zh-TW/permissions#managed-settings) 的 `env` 區塊中設定它，而不是作為 shell 匯出，以便分離的背景服務繼承它；專案和本機設定無法設定它。VS Code 擴充功能透過其 `claudeProcessWrapper` 設定單獨配置其自己的啟動器。在 Windows 上被忽略。`CLAUDE_CODE_SHELL_PREFIX` 是一個單獨的控制：它將 Claude Code 執行的 shell 命令包裝為單個引用的字串，而此變數將 Claude Code 自己的程序包裝為 argv 前綴。請參閱 [Run Claude Code behind a corporate launcher](/docs/zh-TW/corporate-launcher) |

271| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {{/* min-version: 2.1.152 */}}設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向自訂代理時傳播 W3C 追蹤上下文。傳播涵蓋模型和 HTTP MCP 請求上的 `traceparent` 標頭以及 Bash、PowerShell 和 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，傳播僅在直接連線到 Anthropic API 時啟用。在 v2.1.152 中新增。請參閱 [Traces (beta)](/zh-TW/monitoring-usage#traces-beta) |271| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {{/* min-version: 2.1.152 */}}設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向自訂代理時傳播 W3C 追蹤上下文。傳播涵蓋模型和 HTTP MCP 請求上的 `traceparent` 標頭以及 Bash、PowerShell 和 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，傳播僅在直接連線到 Anthropic API 時啟用。在 v2.1.152 中新增。請參閱 [Traces (beta)](/docs/zh-TW/monitoring-usage#traces-beta) |

272| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在設定檔案中被忽略，以便使用者設定無法覆蓋主機的路由。Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 的自動遙測選擇退出也會被跳過，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [Default behaviors by API provider](/zh-TW/data-usage#default-behaviors-by-api-provider) |272| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在設定檔案中被忽略，以便使用者設定無法覆蓋主機的路由。Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 的自動遙測選擇退出也會被跳過，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [Default behaviors by API provider](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |

274| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [cloud session](/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲端環境中 |274| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [cloud session](/docs/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲端環境中 |

275| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link output back to the session](/zh-TW/claude-code-on-the-web#link-output-back-to-the-session) |275| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/docs/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link output back to the session](/docs/zh-TW/claude-code-on-the-web#link-output-back-to-the-session) |

277| `CLAUDE_CODE_RESUME_PROMPT` | 覆蓋在繼續在中途結束的工作階段時注入的延續訊息。預設為 `Continue from where you left off.`。長時間執行的代理的生成指令碼可以將此設定為更具指令性的啟動訊息。空字串使用預設值 |277| `CLAUDE_CODE_RESUME_PROMPT` | 覆蓋在繼續在中途結束的工作階段時注入的延續訊息。預設為 `Continue from where you left off.`。長時間執行的代理的生成指令碼可以將此設定為更具指令性的啟動訊息。空字串使用預設值 |

278| `CLAUDE_CODE_RETRY_WATCHDOG` | {{/* min-version: 2.1.186 */}}設定為 `1` 用於無人值守工作階段，例如評估工具、CI 工作或遠端工作者。無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。監視程式在嘗試之間退避最多 5 分鐘，或直到限制在回應帶有速率限制重設時間時重設，因此達到使用限制的工作階段會等待剩餘視窗。{{/* min-version: 2.1.199 */}}自 v2.1.199 起，它也會提高其他暫時性錯誤（例如伺服器錯誤、逾時和丟棄的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。需要 Claude Code v2.1.186 或更新版本 |278| `CLAUDE_CODE_RETRY_WATCHDOG` | {{/* min-version: 2.1.186 */}}設定為 `1` 用於無人值守工作階段，例如評估工具、CI 工作或遠端工作者。無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。監視程式在嘗試之間退避最多 5 分鐘，或直到限制在回應帶有速率限制重設時間時重設，因此達到使用限制的工作階段會等待剩餘視窗。{{/* min-version: 2.1.199 */}}自 v2.1.199 起，它也會提高其他暫時性錯誤（例如伺服器錯誤、逾時和丟棄的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。需要 Claude Code v2.1.186 或更新版本 |

279| `CLAUDE_CODE_SAFE_MODE` | 設定為 `1` 以在安全模式下啟動：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態行和檔案建議命令、LSP 伺服器和自動記憶體不載入，用於對損壞的配置進行故障排除。受管設定政策仍然適用，包括政策配置的 hooks、狀態行和檔案建議命令；受管外掛程式、受管 skills、受管 CLAUDE.md 和政策配置的 MCP 伺服器不適用。相當於傳遞 [`--safe-mode`](/zh-TW/cli-reference#cli-flags)。直接生成的子程序繼承該變數 |279| `CLAUDE_CODE_SAFE_MODE` | 設定為 `1` 以在安全模式下啟動：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態行和檔案建議命令、LSP 伺服器和自動記憶體不載入，用於對損壞的配置進行故障排除。受管設定政策仍然適用，包括政策配置的 hooks、狀態行和檔案建議命令；受管外掛程式、受管 skills、受管 CLAUDE.md 和政策配置的 MCP 伺服器不適用。相當於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接生成的子程序繼承該變數 |

280| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時限制特定指令碼在每個工作階段中可被呼叫的次數。鍵是針對命令文字進行比對的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時扇出未被偵測；這是深度防禦控制 |280| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時限制特定指令碼在每個工作階段中可被呼叫的次數。鍵是針對命令文字進行比對的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時扇出未被偵測；這是深度防禦控制 |

281| `CLAUDE_CODE_SCROLL_SPEED` | 在 [fullscreen rendering](/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲動乘數。接受 1 到 20 的值，以及低於 1 的分數值（例如 `0.5`）以減慢終端上原生捲動路徑中加速的觸控板和滾輪捲動。設定為 `3` 以符合 `vim`（如果您的終端在沒有放大的情況下每個刻度發送一個滾輪事件）。在 JetBrains IDE 終端中被忽略，Claude Code 使用其自己的捲動處理 |281| `CLAUDE_CODE_SCROLL_SPEED` | 在 [fullscreen rendering](/docs/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲動乘數。接受 1 到 20 的值，以及低於 1 的分數值（例如 `0.5`）以減慢終端上原生捲動路徑中加速的觸控板和滾輪捲動。設定為 `3` 以符合 `vim`（如果您的終端在沒有放大的情況下每個刻度發送一個滾輪事件）。在 JetBrains IDE 終端中被忽略，Claude Code 使用其自己的捲動處理 |

282| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/zh-TW/hooks#sessionend) hooks 的時間預算（以毫秒為單位）。適用於工作階段退出、`/clear` 和透過互動式 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔案中配置的最高每個 hook `timeout`，最高 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |282| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/docs/zh-TW/hooks#sessionend) hooks 的時間預算（以毫秒為單位）。適用於工作階段退出、`/clear` 和透過互動式 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔案中配置的最高每個 hook `timeout`，最高 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |

283| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序、[hook command](/zh-TW/hooks) 子程序和 stdio [MCP server](/zh-TW/mcp) 子程序中自動設定為目前工作階段 ID。對於 Bash、PowerShell 和 hooks，這符合傳遞給 hook JSON 輸入的 `session_id` 欄位，並在 `/clear` 時更新。MCP 伺服器子程序保留它生成時的 ID。在 `--resume <session-id>` 上，它接收繼續的 ID，符合 hooks 和 Bash。在 `--continue` 或 `--resume` 沒有明確 ID 時，它可能接收初始啟動 ID。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |283| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序、[hook command](/docs/zh-TW/hooks) 子程序和 stdio [MCP server](/docs/zh-TW/mcp) 子程序中自動設定為目前工作階段 ID。對於 Bash、PowerShell 和 hooks，這符合傳遞給 hook JSON 輸入的 `session_id` 欄位，並在 `/clear` 時更新。MCP 伺服器子程序保留它生成時的 ID。在 `--resume <session-id>` 上，它接收繼續的 ID，符合 hooks 和 Bash。在 `--continue` 或 `--resume` 沒有明確 ID 時，它可能接收初始啟動 ID。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |

284| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shells。如果該值不是有效的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並回退到自動偵測。自動偵測在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則它會在您的 `PATH` 和標準安裝位置上選擇第一個有效的 `zsh` 然後 `bash` |284| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shells。如果該值不是有效的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並回退到自動偵測。自動偵測在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則它會在您的 `PATH` 和標準安裝位置上選擇第一個有效的 `zsh` 然後 `bash` |

285| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/zh-TW/hooks) 命令、[status line](/zh-TW/statusline) 命令和 stdio [MCP server](/zh-TW/mcp) 啟動命令。PowerShell hooks 和 exec 形式的 hooks 無需前綴執行。對於日誌記錄或稽核很有用。設定裸可執行檔路徑（例如 `/path/to/logger.sh`）會將每個命令執行為 `/path/to/logger.sh '<command>'`。包裝器在 `$1` 中接收命令行作為單個 shell 引用的引數，因此包裝器必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為裸可執行檔路徑會破壞傳遞引數的 stdio MCP 伺服器，例如 `npx -y <package>`。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組裝的完整 shell 呼叫，包括環境設定，而不僅僅是 Claude 執行的命令 |285| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[status line](/docs/zh-TW/statusline) 命令和 stdio [MCP server](/docs/zh-TW/mcp) 啟動命令。PowerShell hooks 和 exec 形式的 hooks 無需前綴執行。對於日誌記錄或稽核很有用。設定裸可執行檔路徑（例如 `/path/to/logger.sh`）會將每個命令執行為 `/path/to/logger.sh '<command>'`。包裝器在 `$1` 中接收命令行作為單個 shell 引用的引數，因此包裝器必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為裸可執行檔路徑會破壞傳遞引數的 stdio MCP 伺服器，例如 `npx -y <package>`。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組裝的完整 shell 呼叫，包括環境設定，而不僅僅是 Claude 執行的命令 |

286| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。OAuth 權杖和鑰匙圈認證不會被讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。相當於傳遞 [`--bare`](/zh-TW/headless#start-faster-with-bare-mode) |286| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。OAuth 權杖和鑰匙圈認證不會被讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。相當於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |

287| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具描述。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器配置會以其他方式啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 探索保持啟用 |287| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具描述。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器配置會以其他方式啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 探索保持啟用 |

288| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳過 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 的用戶端驗證，用於自行簽署請求的閘道 |288| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端驗證，用於自行簽署請求的閘道 |

289| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | {/* min-version: 2.1.207 */}設定為 `1` 以關閉 AWS 預設認證提供者鏈解析的認證進程內快取，以便 Claude Code 在每個 API 請求上解析鏈。關閉快取時，由 SSO 支援的設定檔會在每個請求時從 IAM Identity Center 要求認證。請參閱 [credential caching and resolution timeout](/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |289| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設定為 `1` 以關閉 AWS 預設認證提供者鏈解析的認證進程內快取，以便 Claude Code 在每個 API 請求上解析鏈。關閉快取時，由 SSO 支援的設定檔會在每個請求時從 IAM Identity Center 要求認證。請參閱 [credential caching and resolution timeout](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

291| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳過 Microsoft Foundry 的 Azure 驗證，用於代理或閘道，該代理或閘道注入其自己的 `Authorization` 標頭。Claude Code 發送沒有 Azure 認證的請求，並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS`。當設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時被忽略。{{/* min-version: 2.1.203 */}}在 v2.1.203 之前，此變數使 Microsoft Foundry 用戶端無法發送請求，除非同時設定了 API 金鑰 |291| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳過 Microsoft Foundry 的 Azure 驗證，用於代理或閘道，該代理或閘道注入其自己的 `Authorization` 標頭。Claude Code 發送沒有 Azure 認證的請求，並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS`。當設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時被忽略。{{/* min-version: 2.1.203 */}}在 v2.1.203 之前，此變數使 Microsoft Foundry 用戶端無法發送請求，除非同時設定了 API 金鑰 |

293| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於臨時指令碼化工作階段很有用 |293| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於臨時指令碼化工作階段很有用 |

295| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/zh-TW/hooks#stop) 或 [SubagentStop](/zh-TW/hooks#subagentstop) hook 可能連續阻止回合結束的最大次數，然後 Claude Code 覆蓋它並無論如何結束回合（預設值：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |295| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可能連續阻止回合結束的最大次數，然後 Claude Code 覆蓋它並無論如何結束回合（預設值：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |

296| `CLAUDE_CODE_SUBAGENT_MODEL` | 請參閱 [Model configuration](/zh-TW/model-config)。{{/* min-version: 2.1.196 */}}自 v2.1.196 起，將其設定為 `inherit` 與不設定相同；較早版本將 `inherit` 視為覆蓋，強制每個 subagent 進入主對話的模型 |296| `CLAUDE_CODE_SUBAGENT_MODEL` | 請參閱 [Model configuration](/docs/zh-TW/model-config)。{{/* min-version: 2.1.196 */}}自 v2.1.196 起，將其設定為 `inherit` 與不設定相同；較早版本將 `inherit` 視為覆蓋，強制每個 subagent 進入主對話的模型 |

297| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除 Anthropic 和雲端提供者認證（Bash 工具、hooks、MCP stdio 伺服器）。父 Claude 程序保留這些認證以進行 API 呼叫，但子程序無法讀取它們，減少了嘗試透過 shell 擴展來竊取機密的提示注入攻擊的暴露。在 Linux 上，這也會在隔離的 PID 命名空間中執行 Bash 子程序，以便它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。配置 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此項 |297| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除 Anthropic 和雲端提供者認證（Bash 工具、hooks、MCP stdio 伺服器）。父 Claude 程序保留這些認證以進行 API 呼叫，但子程序無法讀取它們，減少了嘗試透過 shell 擴展來竊取機密的提示注入攻擊的暴露。在 Linux 上，這也會在隔離的 PID 命名空間中執行 Bash 子程序，以便它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。配置 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此項 |

298| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動式模式（`-p` 旗標）中設定為 `1` 以等待外掛程式安裝完成，然後再進行第一個查詢。沒有此選項，外掛程式會在背景中安裝，可能在第一個回合時不可用。與 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 結合以限制等待時間 |298| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動式模式（`-p` 旗標）中設定為 `1` 以等待外掛程式安裝完成，然後再進行第一個查詢。沒有此選項，外掛程式會在背景中安裝，可能在第一個回合時不可用。與 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 結合以限制等待時間 |

299| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛程式安裝的逾時（以毫秒為單位）。超過時，Claude Code 會在沒有外掛程式的情況下繼續並記錄錯誤。無預設值：沒有此變數，同步安裝會等待直到完成 |299| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛程式安裝的逾時（以毫秒為單位）。超過時，Claude Code 會在沒有外掛程式的情況下繼續並記錄錯誤。無預設值：沒有此變數，同步安裝會等待直到完成 |

300| `CLAUDE_CODE_SYNC_SKILLS` | 設定為 `1` 以在第一個查詢之前將您啟用的 claude.ai skills 下載到 `~/.claude/skills/`，並每 10 分鐘重新同步一次。僅適用於非互動式模式，使用 `-p` 旗標。需要 claude.ai 驗證。[Claude Code on the web](/zh-TW/claude-code-on-the-web) 工作階段會自動接收您啟用的 claude.ai skills；您不需要在那裡設定此項 |300| `CLAUDE_CODE_SYNC_SKILLS` | 設定為 `1` 以在第一個查詢之前將您啟用的 claude.ai skills 下載到 `~/.claude/skills/`，並每 10 分鐘重新同步一次。僅適用於非互動式模式，使用 `-p` 旗標。需要 claude.ai 驗證。[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 工作階段會自動接收您啟用的 claude.ai skills；您不需要在那裡設定此項 |

301| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，中途工作階段 skills 重新同步的逾時（以毫秒為單位）（預設值：30000）。限制在主機要求 skill 重新載入期間觸發的下載。超過時，重新同步停止，其餘下載在背景中繼續 |301| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，中途工作階段 skills 重新同步的逾時（以毫秒為單位）（預設值：30000）。限制在主機要求 skill 重新載入期間觸發的下載。超過時，重新同步停止，其餘下載在背景中繼續 |

302| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skills 同步的逾時（以毫秒為單位）（預設值：5000）。超過時，查詢會繼續進行，其餘 skill 下載會在背景中繼續 |302| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skills 同步的逾時（以毫秒為單位）（預設值：5000）。超過時，查詢會繼續進行，其餘 skill 下載會在背景中繼續 |

303| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設定為 `false` 以停用 diff 輸出中的語法醒目提示。當顏色干擾您的終端設定時很有用。若要也停用程式碼區塊和檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/zh-TW/settings) 設定 |303| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設定為 `false` 以停用 diff 輸出中的語法醒目提示。當顏色干擾您的終端設定時很有用。若要也停用程式碼區塊和檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings) 設定 |

304| `CLAUDE_CODE_TASK_LIST_ID` | 跨工作階段共享任務清單。在多個 Claude Code 實例中設定相同的 ID 以協調共享任務清單。請參閱 [Task list](/zh-TW/interactive-mode#task-list) |304| `CLAUDE_CODE_TASK_LIST_ID` | 跨工作階段共享任務清單。在多個 Claude Code 實例中設定相同的 ID 以協調共享任務清單。請參閱 [Task list](/docs/zh-TW/interactive-mode#task-list) |

306| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | {/* min-version: 2.1.206 */}覆蓋，以毫秒為單位，非互動式工作階段在退出時等待其 [agent team](/zh-TW/agent-teams) 完成拆卸的時間。接受 1000 到 60000；超出範圍的值被忽略，預設值 10000 適用。需要 Claude Code v2.1.206 或更新版本 |306| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆蓋，以毫秒為單位，非互動式工作階段在退出時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆卸的時間。接受 1000 到 60000；超出範圍的值被忽略，預設值 10000 適用。需要 Claude Code v2.1.206 或更新版本 |

307| `CLAUDE_CODE_TMPDIR` | 覆蓋用於內部臨時檔案的臨時目錄。Claude Code 將 `/claude-{uid}/`（Unix）或 `/claude/`（Windows）附加到此路徑。預設值：macOS 上的 `/tmp`、Linux/Windows 上的 `os.tmpdir()`。{{/* min-version: 2.1.161 */}}自 v2.1.161 起，在 macOS 和 Linux 上，當您的覆蓋是長路徑時，[sandboxed](/zh-TW/sandboxing) Bash 子程序會在系統預設下收到簡短的回退 `$TMPDIR`，因為某些工具在臨時路徑變得太長時會失敗。未沙箱化的 Bash 命令繼承您的 shell 的 `$TMPDIR` 不變。Claude Code 自己的臨時檔案始終使用您的覆蓋 |307| `CLAUDE_CODE_TMPDIR` | 覆蓋用於內部臨時檔案的臨時目錄。Claude Code 將 `/claude-{uid}/`（Unix）或 `/claude/`（Windows）附加到此路徑。預設值：macOS 上的 `/tmp`、Linux/Windows 上的 `os.tmpdir()`。{{/* min-version: 2.1.161 */}}自 v2.1.161 起，在 macOS 和 Linux 上，當您的覆蓋是長路徑時，[sandboxed](/docs/zh-TW/sandboxing) Bash 子程序會在系統預設下收到簡短的回退 `$TMPDIR`，因為某些工具在臨時路徑變得太長時會失敗。未沙箱化的 Bash 命令繼承您的 shell 的 `$TMPDIR` 不變。Claude Code 自己的臨時檔案始終使用您的覆蓋 |

308| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設定為 `1` 以允許 tmux 內的 24 位真彩色輸出。預設情況下，當設定 `$TMUX` 時，Claude Code 會限制為 256 色，因為 tmux 不會通過真彩色逃逸序列，除非配置為這樣做。在將 `set -ga terminal-overrides ',*:Tc'` 新增到您的 `~/.tmux.conf` 後設定此項。請參閱 [Terminal configuration](/zh-TW/terminal-config) 以取得其他 tmux 設定 |308| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設定為 `1` 以允許 tmux 內的 24 位真彩色輸出。預設情況下，當設定 `$TMUX` 時，Claude Code 會限制為 256 色，因為 tmux 不會通過真彩色逃逸序列，除非配置為這樣做。在將 `set -ga terminal-overrides ',*:Tc'` 新增到您的 `~/.tmux.conf` 後設定此項。請參閱 [Terminal configuration](/docs/zh-TW/terminal-config) 以取得其他 tmux 設定 |

313| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而不是 ripgrep 來探索自訂命令、subagents 和輸出樣式。如果捆綁的 ripgrep 二進位檔案在您的環境中不可用或被阻止，請設定此項。不影響 Grep 或檔案搜尋工具 |313| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而不是 ripgrep 來探索自訂命令、subagents 和輸出樣式。如果捆綁的 ripgrep 二進位檔案在您的環境中不可用或被阻止，請設定此項。不影響 Grep 或檔案搜尋工具 |

314| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具會自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具正在逐步推出：設定為 `1` 以選擇加入或 `0` 以選擇退出。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上有 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) |314| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具會自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具正在逐步推出：設定為 `1` 以選擇加入或 `0` 以選擇退出。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上有 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell tool](/docs/zh-TW/tools-reference#powershell-tool) |

316| `CLAUDE_CONFIG_DIR` | 覆蓋配置目錄（預設值：`~/.claude`）。所有設定、認證、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |316| `CLAUDE_CONFIG_DIR` | 覆蓋配置目錄（預設值：`~/.claude`）。所有設定、認證、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

317| `CLAUDE_DISABLE_ADOPT` | {{/* min-version: 2.1.195 */}}設定為 `1` 以停止進行中的背景工作，而不是在您按 `←` 或使用 [`/background`](/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化時帶入它。Claude Code 會要求您在背景化前確認，然後停止會以其他方式帶入的任務。需要 Claude Code v2.1.195 或更新版本 |317| `CLAUDE_DISABLE_ADOPT` | {{/* min-version: 2.1.195 */}}設定為 `1` 以停止進行中的背景工作，而不是在您按 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化時帶入它。Claude Code 會要求您在背景化前確認，然後停止會以其他方式帶入的任務。需要 Claude Code v2.1.195 或更新版本 |

318| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為該回合的作用中 [effort level](/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。符合傳遞給 [hooks](/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援努力參數時設定 |318| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為該回合的作用中 [effort level](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。符合傳遞給 [hooks](/docs/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援努力參數時設定 |

319| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 連線啟用。位元監視程式會在 180 秒內沒有位元組到達線路時中止連線（直接 Anthropic API 連線上預設為 180 秒，Claude Platform on AWS 和其他提供者上為 300 秒），或在設定 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 時為該值，該值被限制為最少 5 分鐘，獨立於事件級監視程式 |319| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線啟用。位元監視程式會在 180 秒內沒有位元組到達線路時中止連線（直接 Anthropic API 連線上預設為 180 秒，Claude Platform on AWS 和其他提供者上為 300 秒），或在設定 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 時為該值，該值被限制為最少 5 分鐘，獨立於事件級監視程式 |

320| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元級串流閒置監視程式。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |320| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元級串流閒置監視程式。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

321| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `1` 以強制啟用事件級串流閒置監視程式，或設定為 `0` 以強制停用它。{{/* min-version: 2.1.196 */}}未設定時，監視程式預設對所有提供者啟用。在 v2.1.196 之前，未設定的預設值由伺服器在直接 Anthropic API 上控制，在其他提供者上關閉。{{/* min-version: 2.1.169 */}}自 v2.1.169 起，直接 Anthropic API 和 Claude Platform on AWS 以外的提供者也有預設開啟的 5 分鐘主體閒置逾時，獨立於此變數；請參閱 `API_FORCE_IDLE_TIMEOUT`。在 Amazon Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 啟用獨立的位元級監視程式；當兩者都設定時，它們一起執行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |321| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `1` 以強制啟用事件級串流閒置監視程式，或設定為 `0` 以強制停用它。{{/* min-version: 2.1.196 */}}未設定時，監視程式預設對所有提供者啟用。在 v2.1.196 之前，未設定的預設值由伺服器在直接 Anthropic API 上控制，在其他提供者上關閉。{{/* min-version: 2.1.169 */}}自 v2.1.169 起，直接 Anthropic API 和 Claude Platform on AWS 以外的提供者也有預設開啟的 5 分鐘主體閒置逾時，獨立於此變數；請參閱 `API_FORCE_IDLE_TIMEOUT`。在 Amazon Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 啟用獨立的位元級監視程式；當兩者都設定時，它們一起執行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

322| `CLAUDE_ENV_FILE` | Claude Code 在每個 Bash 命令之前在同一 shell 程序中執行的 shell 指令碼的路徑，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/zh-TW/hooks#persist-environment-variables)、[Setup](/zh-TW/hooks#setup)、[CwdChanged](/zh-TW/hooks#cwdchanged) 和 [FileChanged](/zh-TW/hooks#filechanged) hooks 動態填充 |322| `CLAUDE_ENV_FILE` | Claude Code 在每個 Bash 命令之前在同一 shell 程序中執行的 shell 指令碼的路徑，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 和 [FileChanged](/docs/zh-TW/hooks#filechanged) hooks 動態填充 |

323| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/zh-TW/remote-control) 工作階段名稱的前綴。預設為您的機器主機名稱，產生名稱如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |323| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您的機器主機名稱，產生名稱如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |

324| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 串流閒置監視程式在關閉停滯連線之前的逾時（以毫秒為單位）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會無聲地限制以吸收延伸思考暫停和代理緩衝。未設定時，事件級監視程式預設為 300 秒，位元級監視程式在直接 Anthropic API 連線上預設為 180 秒（Claude Platform on AWS 和其他提供者上為 300 秒）。未設定的 180 秒位元監視程式預設是一個單獨的值，不受 5 分鐘限制。`API_FORCE_IDLE_TIMEOUT` 下描述的主體閒置逾時獨立適用。在 Amazon Bedrock 上，也適用於 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |324| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 串流閒置監視程式在關閉停滯連線之前的逾時（以毫秒為單位）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會無聲地限制以吸收延伸思考暫停和代理緩衝。未設定時，事件級監視程式預設為 300 秒，位元級監視程式在直接 Anthropic API 連線上預設為 180 秒（Claude Platform on AWS 和其他提供者上為 300 秒）。未設定的 180 秒位元監視程式預設是一個單獨的值，不受 5 分鐘限制。`API_FORCE_IDLE_TIMEOUT` 下描述的主體閒置逾時獨立適用。在 Amazon Bedrock 上，也適用於 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |

325| `DEBUG` | 設定為 `1` 以啟用偵錯模式，相當於使用 [`--debug`](/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。僅真值 `1`、`true`、`yes` 和 `on` 啟用偵錯模式，因此為其他工具設定的命名空間模式（如 `DEBUG=express:*`）不會觸發它 |325| `DEBUG` | 設定為 `1` 以啟用偵錯模式，相當於使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。僅真值 `1`、`true`、`yes` 和 `on` 啟用偵錯模式，因此為其他工具設定的命名空間模式（如 `DEBUG=express:*`）不會觸發它 |

330| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 以隱藏 [`/doctor`](/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。對於使用者不應執行安裝診斷的受管部署很有用。不影響 `claude doctor` 終端命令。{{/* min-version: 2.1.205 */}}在 v2.1.205 之前，此變數隱藏了 `/doctor` 診斷螢幕命令 |330| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 以隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。對於使用者不應執行安裝診斷的受管部署很有用。不影響 `claude doctor` 終端命令。{{/* min-version: 2.1.205 */}}在 v2.1.205 之前，此變數隱藏了 `/doctor` 診斷螢幕命令 |

346| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的管道分發 Claude Code 且使用者不應自行更新時使用 |346| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的管道分發 Claude Code 且使用者不應自行更新時使用 |

349| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用。若要按專案或按組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/zh-TW/settings#available-settings) |349| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用。若要按專案或按組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings#available-settings) |

350| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |350| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |

352| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search)。未設定：預設所有 MCP 工具延遲，但在 Google Cloud's Agent Platform 上或當 `ANTHROPIC_BASE_URL` 指向非第一方主機時提前載入。值：`true`（始終延遲並發送 beta 標頭，在 Google Cloud's Agent Platform 或不支援 `tool_reference` 的代理上請求失敗）、`auto`（閾值模式：如果工具符合上下文的 10% 內則提前載入）、`auto:N`（自訂閾值，例如 `auto:5` 表示 5%）、`false`（提前載入全部）。當設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時被忽略，這會強制所有工具提前載入 |352| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定：預設所有 MCP 工具延遲，但在 Google Cloud's Agent Platform 上或當 `ANTHROPIC_BASE_URL` 指向非第一方主機時提前載入。值：`true`（始終延遲並發送 beta 標頭，在 Google Cloud's Agent Platform 或不支援 `tool_reference` 的代理上請求失敗）、`auto`（閾值模式：如果工具符合上下文的 10% 內則提前載入）、`auto:N`（自訂閾值，例如 `auto:5` 表示 5%）、`false`（提前載入全部）。當設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時被忽略，這會強制所有工具提前載入 |

353| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值以在任何主要模型上重複過載錯誤後觸發回退。{{/* min-version: 2.1.160 */}}自 v2.1.160 起，配置的 [fallback model chain](/zh-TW/model-config#fallback-model-chains) 會在任何主要模型的重複過載錯誤時觸發，因此此變數不影響切換到回退模型 |353| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值以在任何主要模型上重複過載錯誤後觸發回退。{{/* min-version: 2.1.160 */}}自 v2.1.160 起，配置的 [fallback model chain](/docs/zh-TW/model-config#fallback-model-chains) 會在任何主要模型的重複過載錯誤時觸發，因此此變數不影響切換到回退模型 |

360| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數。Claude Code 在輸出超過 10,000 token 時顯示警告。宣告 [`anthropic/maxResultSizeChars`](/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具對文字內容使用該字元限制，但來自這些工具的影像內容仍受此變數限制（預設值：25000） |360| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數。Claude Code 在輸出超過 10,000 token 時顯示警告。宣告 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具對文字內容使用該字元限制，但來自這些工具的影像內容仍受此變數限制（預設值：25000） |

361| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法驗證非互動式模式（`-p` 旗標）中的 [`--json-schema`](/zh-TW/cli-reference#cli-flags) 時重試的次數。預設為 5 |361| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法驗證非互動式模式（`-p` 旗標）中的 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 時重試的次數。預設為 5 |

362| `MAX_THINKING_TOKENS` | 覆蓋 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token 預算。上限是模型的 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 減一。設定為 `0` 以在 Anthropic API 上停用思考，除了 Fable 5，它無法關閉思考。在 [third-party providers](/zh-TW/third-party-integrations) 上，`0` 同樣省略該參數，具有 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level) 的模型仍可能思考。對於自適應推理模型上的非零值，預算會被忽略，除非透過 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 停用自適應推理 |362| `MAX_THINKING_TOKENS` | 覆蓋 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token 預算。上限是模型的 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 減一。設定為 `0` 以在 Anthropic API 上停用思考，除了 Fable 5，它無法關閉思考。在 [third-party providers](/docs/zh-TW/third-party-integrations) 上，`0` 同樣省略該參數，具有 [adaptive reasoning](/docs/zh-TW/model-config#adjust-effort-level) 的模型仍可能思考。對於自適應推理模型上的非零值，預算會被忽略，除非透過 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 停用自適應推理 |

363| `MCP_CLIENT_SECRET` | 需要 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端密碼。在使用 `--client-secret` 新增伺服器時避免互動式提示 |363| `MCP_CLIENT_SECRET` | 需要 [pre-configured credentials](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端密碼。在使用 `--client-secret` 新增伺服器時避免互動式提示 |

364| `MCP_CONNECTION_NONBLOCKING` | 控制啟動是否在第一個查詢之前等待 MCP 伺服器連線。{{/* min-version: 2.1.142 */}}自 Claude Code v2.1.142 起，MCP 啟動預設為非阻止：伺服器在背景中連線，其工具在完成時變為可用。設定為 `0` 以還原阻止 5 秒連線等待。配置 [`alwaysLoad: true`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器仍會阻止啟動，無論如何，因為其工具必須在建立第一個提示時存在 |364| `MCP_CONNECTION_NONBLOCKING` | 控制啟動是否在第一個查詢之前等待 MCP 伺服器連線。{{/* min-version: 2.1.142 */}}自 Claude Code v2.1.142 起，MCP 啟動預設為非阻止：伺服器在背景中連線，其工具在完成時變為可用。設定為 `0` 以還原阻止 5 秒連線等待。配置 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器仍會阻止啟動，無論如何，因為其工具必須在建立第一個提示時存在 |

365| `MCP_CONNECT_TIMEOUT_MS` | 阻止 MCP 啟動等待連線批次的時間（以毫秒為單位），然後拍攝工具清單快照（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 或標記為 [`alwaysLoad: true`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。在截止時間時仍待處理的伺服器會在背景中繼續連線，但在下一個查詢之前不會出現。與 `MCP_TIMEOUT` 不同，後者限制個別伺服器的連線嘗試 |365| `MCP_CONNECT_TIMEOUT_MS` | 阻止 MCP 啟動等待連線批次的時間（以毫秒為單位），然後拍攝工具清單快照（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 或標記為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。在截止時間時仍待處理的伺服器會在背景中繼續連線，但在下一個查詢之前不會出現。與 `MCP_TIMEOUT` 不同，後者限制個別伺服器的連線嘗試 |

366| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，作為在使用 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |366| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，作為在使用 [pre-configured credentials](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |

370| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（以毫秒為單位）（預設值：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai connector 伺服器，每個請求也預設在 60 秒後逾時；設定此變數或每個伺服器 `timeout` 超過 60000 以提高該每個請求限制。較低的值仍會縮短整體工具執行逾時，但將每個請求限制保留在 60 秒。Stdio 和 WebSocket 伺服器沒有每個請求計時器。`.mcp.json` 中的每個伺服器 `timeout` 欄位會覆蓋該伺服器的此值。{/* min-version: 2.1.203 */}每個伺服器 `timeout` 至少 1000 也會設定該伺服器的工具呼叫的最小閒置視窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永遠不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會下限為 1 秒；對於每個伺服器欄位，低於 1000 的值會被忽略 |370| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（以毫秒為單位）（預設值：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai connector 伺服器，每個請求也預設在 60 秒後逾時；設定此變數或每個伺服器 `timeout` 超過 60000 以提高該每個請求限制。較低的值仍會縮短整體工具執行逾時，但將每個請求限制保留在 60 秒。Stdio 和 WebSocket 伺服器沒有每個請求計時器。`.mcp.json` 中的每個伺服器 `timeout` 欄位會覆蓋該伺服器的此值。每個伺服器 `timeout` 至少 1000 也會設定該伺服器的工具呼叫的最小閒置視窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永遠不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會下限為 1 秒；對於每個伺服器欄位，低於 1000 的值會被忽略 |

372| `OTEL_LOG_ASSISTANT_RESPONSES` | {{/* min-version: 2.1.193 */}}設定為 `1` 以在 `assistant_response` OpenTelemetry 日誌事件上包含模型的回應文字。未設定時，使用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 以保持回應編輯，即使設定 `OTEL_LOG_USER_PROMPTS`。需要 Claude Code v2.1.193 或更新版本。請參閱 [Monitoring](/zh-TW/monitoring-usage#assistant-response-event) |372| `OTEL_LOG_ASSISTANT_RESPONSES` | {{/* min-version: 2.1.193 */}}設定為 `1` 以在 `assistant_response` OpenTelemetry 日誌事件上包含模型的回應文字。未設定時，使用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 以保持回應編輯，即使設定 `OTEL_LOG_USER_PROMPTS`。需要 Claude Code v2.1.193 或更新版本。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage#assistant-response-event) |

373| `OTEL_LOG_RAW_API_BODIES` | 設定為 `1` 以將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（在 60 KB 處截斷），或 `file:<dir>` 以將未截斷的主體寫入磁碟並發出 `body_ref` 路徑。預設停用；主體包括整個對話歷史記錄。請參閱 [Monitoring](/zh-TW/monitoring-usage#api-request-body-event) |373| `OTEL_LOG_RAW_API_BODIES` | 設定為 `1` 以將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（在 60 KB 處截斷），或 `file:<dir>` 以將未截斷的主體寫入磁碟並發出 `body_ref` 路徑。預設停用；主體包括整個對話歷史記錄。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage#api-request-body-event) |

374| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 以在 OpenTelemetry span 事件中包含工具輸入和輸出內容。預設停用以保護敏感資料。請參閱 [Monitoring](/zh-TW/monitoring-usage) |374| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 以在 OpenTelemetry span 事件中包含工具輸入和輸出內容。預設停用以保護敏感資料。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

375| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含工具輸入引數、MCP 伺服器名稱、工具失敗時的原始錯誤字串、`api_refusal` 事件上的拒絕 `category` 和其他工具詳細資訊。預設停用以保護個人識別資訊。請參閱 [Monitoring](/zh-TW/monitoring-usage) |375| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含工具輸入引數、MCP 伺服器名稱、工具失敗時的原始錯誤字串、`api_refusal` 事件上的拒絕 `category` 和其他工具詳細資訊。預設停用以保護個人識別資訊。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

376| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含使用者提示文字。預設停用（提示被編輯）。請參閱 [Monitoring](/zh-TW/monitoring-usage) |376| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含使用者提示文字。預設停用（提示被編輯）。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

378| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | {{/* min-version: 2.1.152 */}}設定為 `true` 以在指標屬性中包含工作階段進入點（預設值：排除）。在 v2.1.152 中新增。請參閱 [Monitoring](/zh-TW/monitoring-usage) |378| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | {{/* min-version: 2.1.152 */}}設定為 `true` 以在指標屬性中包含工作階段進入點（預設值：排除）。在 v2.1.152 中新增。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

379| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | {{/* min-version: 2.1.161 */}}自 v2.1.161 起，Claude Code 將 `OTEL_RESOURCE_ATTRIBUTES` 金鑰附加到指標資料點標籤。設定為 `false` 以排除它們（預設值：包含）。請參閱 [Monitoring](/zh-TW/monitoring-usage#multi-team-organization-support) |379| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | {{/* min-version: 2.1.161 */}}自 v2.1.161 起，Claude Code 將 `OTEL_RESOURCE_ATTRIBUTES` 金鑰附加到指標資料點標籤。設定為 `false` 以排除它們（預設值：包含）。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |

381| `OTEL_METRICS_INCLUDE_VERSION` | 設定為 `true` 以在指標屬性中包含 Claude Code 版本（預設值：排除）。請參閱 [Monitoring](/zh-TW/monitoring-usage) |381| `OTEL_METRICS_INCLUDE_VERSION` | 設定為 `true` 以在指標屬性中包含 Claude Code 版本（預設值：排除）。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |

382| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆蓋顯示給 [Skill tool](/zh-TW/skills#control-who-invokes-a-skill) 的 skill 中繼資料的字元預算。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 個字元。為了向後相容性保留舊名稱 |382| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆蓋顯示給 [Skill tool](/docs/zh-TW/skills#control-who-invokes-a-skill) 的 skill 中繼資料的字元預算。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 個字元。為了向後相容性保留舊名稱 |

383| `TASK_MAX_OUTPUT_LENGTH` | [subagent](/zh-TW/sub-agents) 輸出在截斷前的最大字元數（預設值：32000，最大值：160000）。截斷時，完整輸出會儲存到磁碟，路徑會包含在截斷的回應中 |383| `TASK_MAX_OUTPUT_LENGTH` | [subagent](/docs/zh-TW/sub-agents) 輸出在截斷前的最大字元數（預設值：32000，最大值：160000）。截斷時，完整輸出會儲存到磁碟，路徑會包含在截斷的回應中 |

398| `VERTEX_REGION_CLAUDE_FABLE_5` | {{/* min-version: 2.1.170 */}}使用 Google Cloud's Agent Platform 時覆蓋 Claude Fable 5 的區域。在 v2.1.170 中新增 |398| `VERTEX_REGION_CLAUDE_FABLE_5` | {{/* min-version: 2.1.170 */}}使用 Google Cloud's Agent Platform 時覆蓋 Claude Fable 5 的區域。在 v2.1.170 中新增 |

400 400

401標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信號特定變體）也受支援。請參閱 [Monitoring](/zh-TW/monitoring-usage) 以取得配置詳細資訊。401標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信號特定變體）也受支援。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) 以取得配置詳細資訊。

402 402

403<h2 id="see-also">403<h2 id="see-also">

404 另請參閱404 另請參閱

405</h2>405</h2>

406 406

407* [Settings](/zh-TW/settings)：所有 `settings.json` 配置，包括 `env` 鍵407* [Settings](/docs/zh-TW/settings)：所有 `settings.json` 配置，包括 `env` 鍵

408* [CLI reference](/zh-TW/cli-reference)：啟動時旗標408* [CLI reference](/docs/zh-TW/cli-reference)：啟動時旗標

409* [Network configuration](/zh-TW/network-config)：代理和 TLS 設定409* [Network configuration](/docs/zh-TW/network-config)：代理和 TLS 設定

410* [Monitoring](/zh-TW/monitoring-usage)：OpenTelemetry 配置410* [Monitoring](/docs/zh-TW/monitoring-usage)：OpenTelemetry 配置

errors.md +148 −148

Details

6 6

7> 查詢 Claude Code 執行時錯誤訊息，了解每個錯誤的含義及修復方法。7> 查詢 Claude Code 執行時錯誤訊息，了解每個錯誤的含義及修復方法。

8 8

9本頁列出 Claude Code 顯示的執行時錯誤及如何從每個錯誤中恢復，以及當回應似乎有問題但沒有錯誤時要檢查的內容。如需安裝錯誤（例如 `command not found` 或設定期間的 TLS 失敗），請參閱 [Troubleshoot installation and login](/zh-TW/troubleshoot-install)。9本頁列出 Claude Code 顯示的執行時錯誤及如何從每個錯誤中恢復，以及當回應似乎有問題但沒有錯誤時要檢查的內容。如需安裝錯誤（例如 `command not found` 或設定期間的 TLS 失敗），請參閱 [Troubleshoot installation and login](/docs/zh-TW/troubleshoot-install)。

10 10

11這些錯誤和恢復命令適用於 CLI、[Desktop app](/zh-TW/desktop) 和 [Claude Code on the web](/zh-TW/claude-code-on-the-web)，因為這三者都包裝相同的 Claude Code CLI。如需特定表面的問題，請參閱該表面頁面上的疑難排解部分。11這些錯誤和恢復命令適用於 CLI、[Desktop app](/docs/zh-TW/desktop) 和 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)，因為這三者都包裝相同的 Claude Code CLI。如需特定表面的問題，請參閱該表面頁面上的疑難排解部分。

12 12

13<Note>13<Note>

14 Claude Code 呼叫 Claude API 以取得模型回應，因此大多數執行時錯誤對應到基礎 API 錯誤代碼。本頁涵蓋每個錯誤在 Claude Code 中的含義及如何恢復。如需原始 HTTP 狀態代碼定義，請參閱 [Claude Platform error reference](https://platform.claude.com/docs/en/api/errors)。14 Claude Code 呼叫 Claude API 以取得模型回應，因此大多數執行時錯誤對應到基礎 API 錯誤代碼。本頁涵蓋每個錯誤在 Claude Code 中的含義及如何恢復。如需原始 HTTP 狀態代碼定義，請參閱 [Claude Platform error reference](https://platform.claude.com/docs/en/api/errors)。

97 自動重試97 自動重試

98</h2>98</h2>

99 99

100Claude Code 在向您顯示錯誤之前會重試暫時性失敗。伺服器錯誤、過載回應、請求逾時、臨時 429 節流和中斷的連線都會以指數退避方式重試最多 10 次。{/* min-version: 2.1.198 */}自 v2.1.198 起，這涵蓋在任何可見輸出串流之前在回應中途中斷的連線：Claude Code 使用相同的退避重新發出請求，轉向繼續而不是停止並出現連線錯誤。{/* min-version: 2.1.199 */}自 v2.1.199 起，不帶您計畫配額標頭的臨時 429 節流在您使用 claude.ai 訂閱登入時也會重試；較早的版本僅針對 API 金鑰和 Enterprise 登入重試它們。100Claude Code 在向您顯示錯誤之前會重試暫時性失敗。伺服器錯誤、過載回應、請求逾時、臨時 429 節流和中斷的連線都會以指數退避方式重試最多 10 次。自 v2.1.198 起，這涵蓋在任何可見輸出串流之前在回應中途中斷的連線：Claude Code 使用相同的退避重新發出請求，轉向繼續而不是停止並出現連線錯誤。自 v2.1.199 起，不帶您計畫配額標頭的臨時 429 節流在您使用 claude.ai 訂閱登入時也會重試；較早的版本僅針對 API 金鑰和 Enterprise 登入重試它們。

101 101

102有些失敗類別不會重試，因為重試無法成功：102有些失敗類別不會重試，因為重試無法成功：

103 103

104* {/* min-version: 2.1.199 */}自 v2.1.199 起，TLS 憑證驗證失敗（例如 TLS 檢查代理、遺失的 `NODE_EXTRA_CA_CERTS` 套件或過期的憑證）在第一次嘗試時失敗，因此修復會立即出現，而不是在完整重試預算之後。請參閱 [SSL 憑證錯誤](#ssl-certificate-errors)。暫時性 TLS 條件（例如握手逾時）仍會重試。104* 自 v2.1.199 起，TLS 憑證驗證失敗（例如 TLS 檢查代理、遺失的 `NODE_EXTRA_CA_CERTS` 套件或過期的憑證）在第一次嘗試時失敗，因此修復會立即出現，而不是在完整重試預算之後。請參閱 [SSL 憑證錯誤](#ssl-certificate-errors)。暫時性 TLS 條件（例如握手逾時）仍會重試。

105* {/* min-version: 2.1.199 */}自 v2.1.199 起，在 Claude 已經串流可見輸出後到達的伺服器錯誤會保留部分回應並附加 [不完整回應通知](#the-response-above-may-be-incomplete)，而不是重試，因為重新執行請求可能會執行相同的工具兩次。較早的版本會捨棄部分輸出並將轉向報告為錯誤。105* 自 v2.1.199 起，在 Claude 已經串流可見輸出後到達的伺服器錯誤會保留部分回應並附加 [不完整回應通知](#the-response-above-may-be-incomplete)，而不是重試，因為重新執行請求可能會執行相同的工具兩次。較早的版本會捨棄部分輸出並將轉向報告為錯誤。

106* {/* min-version: 2.1.208 */}[Amazon Bedrock 串流回應具有非預期的內容類型](#bedrock-streaming-response-has-an-unexpected-content-type)在第一次嘗試時失敗，因為重寫回應的閘道或代理會以相同方式重寫重試。需要 Claude Code v2.1.208 或更新版本。106* [Amazon Bedrock 串流回應具有非預期的內容類型](#bedrock-streaming-response-has-an-unexpected-content-type)在第一次嘗試時失敗，因為重寫回應的閘道或代理會以相同方式重寫重試。需要 Claude Code v2.1.208 或更新版本。

107 107

108重試時，微調器會在錯誤標籤後顯示 `Retrying in Ns · attempt x/y` 倒數計時。標籤命名第一次嘗試的特定原因，以便您可以立即採取行動的失敗：網路已關閉、TLS 握手失敗或您達到速率限制。對於其他錯誤，它最初讀取 `API error`。{/* min-version: 2.1.198 */}自 v2.1.198 起，它會切換到第三次嘗試的特定原因，或在 `CLAUDE_CODE_MAX_RETRIES` 允許少於三次時的最後一次嘗試；較早的版本僅在最後一次嘗試時切換。108重試時，微調器會在錯誤標籤後顯示 `Retrying in Ns · attempt x/y` 倒數計時。標籤命名第一次嘗試的特定原因，以便您可以立即採取行動的失敗：網路已關閉、TLS 握手失敗或您達到速率限制。對於其他錯誤，它最初讀取 `API error`。自 v2.1.198 起，它會切換到第三次嘗試的特定原因，或在 `CLAUDE_CODE_MAX_RETRIES` 允許少於三次時的最後一次嘗試；較早的版本僅在最後一次嘗試時切換。

109 109

110{/* min-version: 2.1.198 */}自 v2.1.198 起，通常的微調器提示在重試期間被抑制。一旦錯誤原因被揭示，如果失敗是 529 過載，倒數計時下方的行也會命名檢查服務狀態的位置：Anthropic API 上的 `status.claude.com`，或其他配置上提供者或閘道主機命名的位置。110自 v2.1.198 起，通常的微調器提示在重試期間被抑制。一旦錯誤原因被揭示，如果失敗是 529 過載，倒數計時下方的行也會命名檢查服務狀態的位置：Anthropic API 上的 `status.claude.com`，或其他配置上提供者或閘道主機命名的位置。

111 111

112{/* min-version: 2.1.185 */}如果在請求仍待處理時，回應串流上 20 秒內沒有資料到達，微調器會在任何重試開始之前顯示 `Waiting for API response · will retry in … · check your network`。請求尚未失敗：倒數計時會執行到 Claude Code 中止停滯連線並重試的位置，因此一旦資料恢復或重試成功，橫幅就會自動清除。自 v2.1.185 起，閾值為 20 秒；較早的版本會在 10 秒後顯示橫幅，措辭不同。如果它在每次嘗試時都重新出現，請將其視為[網路問題](#unable-to-connect-to-api)。112如果在請求仍待處理時，回應串流上 20 秒內沒有資料到達，微調器會在任何重試開始之前顯示 `Waiting for API response · will retry in … · check your network`。請求尚未失敗：倒數計時會執行到 Claude Code 中止停滯連線並重試的位置，因此一旦資料恢復或重試成功，橫幅就會自動清除。自 v2.1.185 起，閾值為 20 秒；較早的版本會在 10 秒後顯示橫幅，措辭不同。如果它在每次嘗試時都重新出現，請將其視為[網路問題](#unable-to-connect-to-api)。

113 113

114當您看到本頁上的其中一個錯誤時，這些重試已經用盡，除非它屬於不會重試的類別，例如憑證驗證失敗。您可以使用這些環境變數調整行為：114當您看到本頁上的其中一個錯誤時，這些重試已經用盡，除非它屬於不會重試的類別，例如憑證驗證失敗。您可以使用這些環境變數調整行為：

115 115

116| 變數 | 預設值 | 效果 |116| 變數 | 預設值 | 效果 |

117| :---------------------------------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |117| :---------------------------------------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

118| [`CLAUDE_CODE_MAX_RETRIES`](/zh-TW/env-vars) | 10 | 重試次數。{/* min-version: 2.1.186 */}自 v2.1.186 起上限為 15；{/* min-version: 2.1.199 */}自 v2.1.199 起 `CLAUDE_CODE_RETRY_WATCHDOG` 提高預設值並移除上限。降低它以在指令碼中更快地顯示失敗。 |118| [`CLAUDE_CODE_MAX_RETRIES`](/docs/zh-TW/env-vars) | 10 | 重試次數。自 v2.1.186 起上限為 15；自 v2.1.199 起 `CLAUDE_CODE_RETRY_WATCHDOG` 提高預設值並移除上限。降低它以在指令碼中更快地顯示失敗。 |

119| [`CLAUDE_CODE_RETRY_WATCHDOG`](/zh-TW/env-vars) | 未設定 | 在 CI 工作等無人值守的工作階段中設定為 `1`，以無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。{/* min-version: 2.1.199 */}自 v2.1.199 起，它也提高了其他暫時性錯誤（例如伺服器錯誤、逾時和中斷的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。 |119| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-TW/env-vars) | 未設定 | 在 CI 工作等無人值守的工作階段中設定為 `1`，以無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。自 v2.1.199 起，它也提高了其他暫時性錯誤（例如伺服器錯誤、逾時和中斷的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。 |

120| [`API_TIMEOUT_MS`](/zh-TW/env-vars) | 600000 | 每個請求的逾時（毫秒）。為慢速網路或代理提高它。 |120| [`API_TIMEOUT_MS`](/docs/zh-TW/env-vars) | 600000 | 每個請求的逾時（毫秒）。為慢速網路或代理提高它。 |

121 121

122<h2 id="server-errors">122<h2 id="server-errors">

123 伺服器錯誤123 伺服器錯誤

196API Error: Response stalled mid-stream. The response above may be incomplete.196API Error: Response stalled mid-stream. The response above may be incomplete.

197```197```

198 198

199* {/* min-version: 2.1.199 */}}`Server error mid-response`：中途串流超載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更新版本；在此之前，該情況會捨棄部分輸出並將整個輪次報告為錯誤。199* }`Server error mid-response`：中途串流超載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更新版本；在此之前，該情況會捨棄部分輸出並將整個輪次報告為錯誤。

200* `Connection closed mid-response`：連線中斷。200* `Connection closed mid-response`：連線中斷。

201* `Response stalled mid-stream`：串流停止傳送資料。201* `Response stalled mid-stream`：串流停止傳送資料。

202 202

210 自動模式無法判斷動作的安全性210 自動模式無法判斷動作的安全性

211</h3>211</h3>

212 212

213[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)用來分類動作的模型無法做出決定，所以自動模式沒有自動批准該動作。您看到的訊息取決於分類器失敗的原因。213[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)用來分類動作的模型無法做出決定，所以自動模式沒有自動批准該動作。您看到的訊息取決於分類器失敗的原因。

214 214

215在您的工作目錄內的讀取、搜尋和編輯會跳過分類器，所以它們在所有這些情況下都能繼續工作。215在您的工作目錄內的讀取、搜尋和編輯會跳過分類器，所以它們在所有這些情況下都能繼續工作。

216 216

224 224

225* 幾秒鐘後重試；Claude 會看到相同的訊息，通常會自動重試225* 幾秒鐘後重試；Claude 會看到相同的訊息，通常會自動重試

226* 如果重試持續失敗，請繼續執行唯讀任務，稍後再回到被阻止的動作226* 如果重試持續失敗，請繼續執行唯讀任務，稍後再回到被阻止的動作

227* 這是暫時的，與[自動模式資格](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)無關；您不需要變更設定227* 這是暫時的，與[自動模式資格](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)無關；您不需要變更設定

228 228

229當分類器傳回無法解析的回應時：229當分類器傳回無法解析的回應時：

230 230

247 247

248* 這不是關於您的動作的決定。您對話中已有的內容在自動模式將對話傳送給分類器時觸發了 API 上的安全篩選器248* 這不是關於您的動作的決定。您對話中已有的內容在自動模式將對話傳送給分類器時觸發了 API 上的安全篩選器

249* 重試無法幫助；相同的對話內容會再次觸發篩選器249* 重試無法幫助；相同的對話內容會再次觸發篩選器

250* 切換到不同的[權限模式](/zh-TW/permission-modes)，以便在出現提示時批准該動作，或開始一個沒有觸發內容的新對話250* 切換到不同的[權限模式](/docs/zh-TW/permission-modes)，以便在出現提示時批准該動作，或開始一個沒有觸發內容的新對話

251 251

252當對話大小超過分類器的上下文視窗時：252當對話大小超過分類器的上下文視窗時：

253 253

255Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)255Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

256```256```

257 257

258在互動式工作階段中，自動模式會為該動作回退到正常的權限提示，以便您可以手動批准或拒絕它。在[非互動式模式](/zh-TW/headless)中，執行會中止，因為文字記錄只會增長，重試無法成功。258在互動式工作階段中，自動模式會為該動作回退到正常的權限提示，以便您可以手動批准或拒絕它。在[非互動式模式](/docs/zh-TW/headless)中，執行會中止，因為文字記錄只會增長，重試無法成功。

259 259

260**該怎麼做：**260**該怎麼做：**

261 261

266 代理因 API 錯誤而提前終止266 代理因 API 錯誤而提前終止

267</h3>267</h3>

268 268

269{/* min-version: 2.1.199 */}[子代理](/zh-TW/sub-agents)的 API 請求終止失敗，例如因為達到使用限制或伺服器錯誤的重試用盡，所以子代理在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更新版本；在此之前，API 錯誤文字被傳回給 Claude，就像它是子代理的結果一樣。269[子代理](/docs/zh-TW/sub-agents)的 API 請求終止失敗，例如因為達到使用限制或伺服器錯誤的重試用盡，所以子代理在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更新版本；在此之前，API 錯誤文字被傳回給 Claude，就像它是子代理的結果一樣。

270 270

271```text theme={null}271```text theme={null}

272Agent terminated early due to an API error: <error detail>272Agent terminated early due to an API error: <error detail>

275**該怎麼做：**275**該怎麼做：**

276 276

277* 將冒號後的錯誤詳細資訊與此頁面上的自己的部分相符，例如[使用限制](#usage-limits)或[伺服器錯誤](#server-errors)，並遵循該部分的步驟277* 將冒號後的錯誤詳細資訊與此頁面上的自己的部分相符，例如[使用限制](#usage-limits)或[伺服器錯誤](#server-errors)，並遵循該部分的步驟

278* 一旦基礎錯誤清除，請要求 Claude 重試任務或[恢復子代理](/zh-TW/sub-agents#resume-subagents)278* 一旦基礎錯誤清除，請要求 Claude 重試任務或[恢復子代理](/docs/zh-TW/sub-agents#resume-subagents)

279 279

280當速率限制、超載或伺服器錯誤中斷已經產生文字輸出的前景子代理時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。{/* min-version: 2.1.200 */}只有工具呼叫輸出的子代理也會收到此錯誤；在 v2.1.199 中，該形狀改為傳回空的部分結果。請參閱[子代理中的 API 錯誤](/zh-TW/sub-agents#api-errors-in-subagents)。280當速率限制、超載或伺服器錯誤中斷已經產生文字輸出的前景子代理時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。只有工具呼叫輸出的子代理也會收到此錯誤；在 v2.1.199 中，該形狀改為傳回空的部分結果。請參閱[子代理中的 API 錯誤](/docs/zh-TW/sub-agents#api-errors-in-subagents)。

281 281

282<h2 id="usage-limits">282<h2 id="usage-limits">

283 使用限制283 使用限制

309* 執行 `/usage-credits` 以在 Pro 和 Max 上購買額外使用額度，或在 Team 和 Enterprise 上向您的管理員請求。請參閱[付費方案的使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)以了解如何計費。309* 執行 `/usage-credits` 以在 Pro 和 Max 上購買額外使用額度，或在 Team 和 Enterprise 上向您的管理員請求。請參閱[付費方案的使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)以了解如何計費。

310* 若要升級您的方案以獲得更高的基本限制，請參閱 [claude.com/pricing](https://claude.com/pricing)310* 若要升級您的方案以獲得更高的基本限制，請參閱 [claude.com/pricing](https://claude.com/pricing)

311 311

312若要在達到限制之前監控您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態列](/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/zh-TW/desktop#check-usage)。312若要在達到限制之前監控您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態列](/docs/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/docs/zh-TW/desktop#check-usage)。

313 313

314<h3 id="usage-credits-required-for-1m-context">314<h3 id="usage-credits-required-for-1m-context">

315 1M 上下文需要使用額度315 1M 上下文需要使用額度

321API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context321API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

322```322```

323 323

324這是一項權利檢查，而不是配額耗盡。即使您的工作階段和每週額度仍有容量，它也會觸發。請參閱[擴展上下文](/zh-TW/model-config#extended-context)以了解哪些方案直接包含 1M 上下文，哪些需要使用額度。324這是一項權利檢查，而不是配額耗盡。即使您的工作階段和每週額度仍有容量，它也會觸發。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解哪些方案直接包含 1M 上下文，哪些需要使用額度。

325 325

326{/* min-version: 2.1.172 */}當此錯誤在對話中途出現，因為上下文增長超過 200K 令牌時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並在之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 `/compact`）上重複出現；在這些版本上執行 `/clear` 以恢復。以下步驟適用於您明確選擇 `[1m]` 模型的情況。326當此錯誤在對話中途出現，因為上下文增長超過 200K 令牌時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並在之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 `/compact`）上重複出現；在這些版本上執行 `/clear` 以恢復。以下步驟適用於您明確選擇 `[1m]` 模型的情況。

327 327

328**該怎麼做：**328**該怎麼做：**

329 329

330* 執行 `/model` 並選擇不帶 `[1m]` 後綴的變體以回退到標準上下文視窗330* 執行 `/model` 並選擇不帶 `[1m]` 後綴的變體以回退到標準上下文視窗

331* 執行 `/usage-credits` 以在 Pro 和 Max 上開啟 1M 變體的計量計費，或在 Team 和 Enterprise 上向您的管理員請求331* 執行 `/usage-credits` 以在 Pro 和 Max 上開啟 1M 變體的計量計費，或在 Team 和 Enterprise 上向您的管理員請求

332* 如果 `/model` 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱[選定的模型有問題](#theres-an-issue-with-the-selected-model)以按優先順序檢查配置位置。332* 如果 `/model` 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱[選定的模型有問題](#theres-an-issue-with-the-selected-model)以按優先順序檢查配置位置。

333* 若要從模型選擇器中完全移除 1M 變體，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/zh-TW/env-vars)333* 若要從模型選擇器中完全移除 1M 變體，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars)

334 334

335<h3 id="server-is-temporarily-limiting-requests">335<h3 id="server-is-temporarily-limiting-requests">

336 伺服器暫時限制請求336 伺服器暫時限制請求

342API Error: Server is temporarily limiting requests (not your usage limit)342API Error: Server is temporarily limiting requests (not your usage limit)

343```343```

344 344

345Claude Code 透過真實限制回應所攜帶的統一配額標頭的缺失來區分這些與您的方案限制。{/* min-version: 2.1.199 */}自 v2.1.199 起，無論您如何驗證，這都會[自動重試](#automatic-retries)並進行退避，然後才會顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗；只有 API 金鑰和 Enterprise 登入會重試它。345Claude Code 透過真實限制回應所攜帶的統一配額標頭的缺失來區分這些與您的方案限制。自 v2.1.199 起，無論您如何驗證，這都會[自動重試](#automatic-retries)並進行退避，然後才會顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗；只有 API 金鑰和 Enterprise 登入會重試它。

346 346

347**該怎麼做：**347**該怎麼做：**

348 348

366* 執行 `/status` 並確認作用中的認證是您預期的認證。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱來路由請求。366* 執行 `/status` 並確認作用中的認證是您預期的認證。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱來路由請求。

367* 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級367* 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級

368* 對於 Anthropic API 金鑰，請參閱[速率限制參考](https://platform.claude.com/docs/en/api/rate-limits)以了解層級如何運作以及如何設定每個工作區的上限368* 對於 Anthropic API 金鑰，請參閱[速率限制參考](https://platform.claude.com/docs/en/api/rate-limits)以了解層級如何運作以及如何設定每個工作區的上限

369* 降低並行性：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/zh-TW/env-vars)、避免執行許多平行子代理，或使用 `/model` 切換到較小的模型以進行大量指令碼執行369* 降低並行性：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-TW/env-vars)、避免執行許多平行子代理，或使用 `/model` 切換到較小的模型以進行大量指令碼執行

370 370

371<h3 id="credit-balance-is-too-low">371<h3 id="credit-balance-is-too-low">

372 信用額度餘額過低372 信用額度餘額過低

382 382

383* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 新增信用額度，並考慮在那裡啟用自動重新載入，以便在餘額達到零之前進行補充383* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 新增信用額度，並考慮在那裡啟用自動重新載入，以便在餘額達到零之前進行補充

384* 如果您有 Pro、Max、Team 或 Enterprise 方案，請使用 `/login` 切換到訂閱驗證384* 如果您有 Pro、Max、Team 或 Enterprise 方案，請使用 `/login` 切換到訂閱驗證

385* 在 Console 中設定每個工作區的支出上限，以防止單一專案耗盡組織餘額。請參閱[有效管理成本](/zh-TW/costs)。385* 在 Console 中設定每個工作區的支出上限，以防止單一專案耗盡組織餘額。請參閱[有效管理成本](/docs/zh-TW/costs)。

386 386

387<h2 id="authentication-errors">387<h2 id="authentication-errors">

388 驗證錯誤388 驗證錯誤

404 404

405* 執行 `/login` 以使用您的 Claude 訂閱或 Console 帳戶進行驗證405* 執行 `/login` 以使用您的 Claude 訂閱或 Console 帳戶進行驗證

406* 如果您預期使用環境變數進行驗證，請確認 `ANTHROPIC_API_KEY` 已在啟動 `claude` 的 shell 中設定並匯出406* 如果您預期使用環境變數進行驗證，請確認 `ANTHROPIC_API_KEY` 已在啟動 `claude` 的 shell 中設定並匯出

407* 對於無法進行互動式登入的 CI 或自動化環境，請設定一個 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼，在啟動時取得金鑰407* 對於無法進行互動式登入的 CI 或自動化環境，請設定一個 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 指令碼，在啟動時取得金鑰

408* 請參閱[驗證優先順序](/zh-TW/authentication#authentication-precedence)以了解當存在多個認證方式時，Claude Code 使用哪一個408* 請參閱[驗證優先順序](/docs/zh-TW/authentication#authentication-precedence)以了解當存在多個認證方式時，Claude Code 使用哪一個

409 409

410如果系統反覆提示您登入，請參閱[未登入或權杖已過期](/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)以取得系統時鐘和 macOS Keychain 的修復方法。410如果系統反覆提示您登入，請參閱[未登入或權杖已過期](/docs/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)以取得系統時鐘和 macOS Keychain 的修復方法。

411 411

412<h3 id="could-not-resolve-authentication-method">412<h3 id="could-not-resolve-authentication-method">

413 無法解析驗證方法413 無法解析驗證方法

414</h3>414</h3>

415 415

416工作階段到達 API 用戶端時沒有任何認證方式。這會出現在[背景工作階段](/zh-TW/agent-view)、雲端工作階段和 Agent SDK 環境中，其中互動式登入檢查在第一個請求之前不會執行。416工作階段到達 API 用戶端時沒有任何認證方式。這會出現在[背景工作階段](/docs/zh-TW/agent-view)、雲端工作階段和 Agent SDK 環境中，其中互動式登入檢查在第一個請求之前不會執行。

417 417

418```text theme={null}418```text theme={null}

419Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted419Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

420```420```

421 421

422{/* min-version: 2.1.174 */}在 v2.1.174 之前，指派給閒置預初始化背景工作程序的背景或雲端工作階段即使已設定有效認證方式也可能以此方式失敗。請升級以恢復。在目前版本中，此錯誤表示背景工作程序沒有可用的認證方式。422在 v2.1.174 之前，指派給閒置預初始化背景工作程序的背景或雲端工作階段即使已設定有效認證方式也可能以此方式失敗。請升級以恢復。在目前版本中，此錯誤表示背景工作程序沒有可用的認證方式。

423 423

424**應該怎麼做：**424**應該怎麼做：**

425 425

426* 如果此錯誤出現在背景或雲端工作階段中且您的認證方式已設定，請升級至 v2.1.174 或更新版本426* 如果此錯誤出現在背景或雲端工作階段中且您的認證方式已設定，請升級至 v2.1.174 或更新版本

427* 確認 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的雲端提供者認證方式已在啟動背景工作程序的環境中設定，而不僅在您的互動式 shell 中427* 確認 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的雲端提供者認證方式已在啟動背景工作程序的環境中設定，而不僅在您的互動式 shell 中

428* 對於 Agent SDK，請參閱[驗證設定](/zh-TW/agent-sdk/overview#get-started)428* 對於 Agent SDK，請參閱[驗證設定](/docs/zh-TW/agent-sdk/overview#get-started)

429* 在相同環境中的互動式工作階段中執行 `/status` 以確認哪個認證方式來源可以解析429* 在相同環境中的互動式工作階段中執行 `/status` 以確認哪個認證方式來源可以解析

430 430

431<h3 id="invalid-api-key">431<h3 id="invalid-api-key">

443* 檢查是否有拼寫錯誤，並確認該金鑰未在 [Console](https://platform.claude.com/settings/keys) 中被撤銷443* 檢查是否有拼寫錯誤，並確認該金鑰未在 [Console](https://platform.claude.com/settings/keys) 中被撤銷

444* 在相同的 shell 中執行 `env | grep ANTHROPIC`。direnv、dotenv shell 外掛程式和 IDE 終端等工具可能會從您專案中的 `.env` 檔案載入過時的金鑰，而您並未明確設定它444* 在相同的 shell 中執行 `env | grep ANTHROPIC`。direnv、dotenv shell 外掛程式和 IDE 終端等工具可能會從您專案中的 `.env` 檔案載入過時的金鑰，而您並未明確設定它

445* 取消設定 `ANTHROPIC_API_KEY` 並執行 `/login` 以改用訂閱驗證445* 取消設定 `ANTHROPIC_API_KEY` 並執行 `/login` 以改用訂閱驗證

446* 如果金鑰來自 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼，請直接執行該指令碼以確認它在 stdout 上列印有效的金鑰446* 如果金鑰來自 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 指令碼，請直接執行該指令碼以確認它在 stdout 上列印有效的金鑰

447* 執行 `/status` 以確認 Claude Code 實際使用的認證方式來源447* 執行 `/status` 以確認 Claude Code 實際使用的認證方式來源

448 448

449<h3 id="your-apikeyhelper-script-is-failing">449<h3 id="your-apikeyhelper-script-is-failing">

450 您的 apiKeyHelper 指令碼失敗450 您的 apiKeyHelper 指令碼失敗

451</h3>451</h3>

452 452

453在 [`apiKeyHelper`](/zh-TW/settings#available-settings) 設定中設定的命令已結束並出現錯誤、逾時或未在 stdout 上列印任何內容。如果沒有來自指令碼的金鑰，請求會到達 API 並使用預留位置認證方式，API 會以 `401` 拒絕它。453在 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 設定中設定的命令已結束並出現錯誤、逾時或未在 stdout 上列印任何內容。如果沒有來自指令碼的金鑰，請求會到達 API 並使用預留位置認證方式，API 會以 `401` 拒絕它。

454 454

455```text theme={null}455```text theme={null}

456Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output456Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

457```457```

458 458

459Claude Code 會重新執行指令碼並在顯示此訊息之前最多重試兩次請求，因此失敗會在三次嘗試內出現。{/* min-version: 2.1.208 */}在 v2.1.208 之前，Claude Code 花費完整的[重試預算](#automatic-retries)使用預留位置認證方式重新傳送請求，然後報告通用的 `401` 驗證錯誤而不是指令碼失敗。459Claude Code 會重新執行指令碼並在顯示此訊息之前最多重試兩次請求，因此失敗會在三次嘗試內出現。在 v2.1.208 之前，Claude Code 花費完整的[重試預算](#automatic-retries)使用預留位置認證方式重新傳送請求，然後報告通用的 `401` 驗證錯誤而不是指令碼失敗。

460 460

461執行 `/login` 在此無法幫助：只要設定存在，協助程式的輸出[優先於](/zh-TW/authentication#authentication-precedence)已儲存的登入。461執行 `/login` 在此無法幫助：只要設定存在，協助程式的輸出[優先於](/docs/zh-TW/authentication#authentication-precedence)已儲存的登入。

462 462

463**應該怎麼做：**463**應該怎麼做：**

464 464

465* 在您的 shell 中直接執行在 `apiKeyHelper` 中設定的命令以重現失敗465* 在您的 shell 中直接執行在 `apiKeyHelper` 中設定的命令以重現失敗

466* 如果命令報告工作階段已過期，請使用您的認證方式提供者重新驗證，例如再次登入您的 SSO 或機密保管庫466* 如果命令報告工作階段已過期，請使用您的認證方式提供者重新驗證，例如再次登入您的 SSO 或機密保管庫

467* 修復命令以便它將金鑰列印到 stdout 並以代碼 0 結束。請參閱[使用 apiKeyHelper 輪換認證方式](/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper)以取得有效的設定。467* 修復命令以便它將金鑰列印到 stdout 並以代碼 0 結束。請參閱[使用 apiKeyHelper 輪換認證方式](/docs/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper)以取得有效的設定。

468* 執行 `/status` 以確認 `apiKeyHelper` 是使用中的認證方式來源。每次命令失敗時，其結束代碼和錯誤輸出會出現在終端中的 `Cloud authentication` 面板中。468* 執行 `/status` 以確認 `apiKeyHelper` 是使用中的認證方式來源。每次命令失敗時，其結束代碼和錯誤輸出會出現在終端中的 `Cloud authentication` 面板中。

469 469

470<h3 id="this-organization-has-been-disabled">470<h3 id="this-organization-has-been-disabled">

499Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account499Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

500```500```

501 501

502環境變數和 `apiKeyHelper` 優先於 `/login`，因此當其中任一個仍在提供金鑰時，單獨執行 `/login` 無法幫助。請參閱[驗證優先順序](/zh-TW/authentication#authentication-precedence)。502環境變數和 `apiKeyHelper` 優先於 `/login`，因此當其中任一個仍在提供金鑰時，單獨執行 `/login` 無法幫助。請參閱[驗證優先順序](/docs/zh-TW/authentication#authentication-precedence)。

503 503

504**應該怎麼做：**504**應該怎麼做：**

505 505

506* 如果訊息提及 `ANTHROPIC_API_KEY`，請在目前 shell 中取消設定它，並從您的 shell 設定檔或 `.env` 檔案中移除它，然後重新啟動 `claude`506* 如果訊息提及 `ANTHROPIC_API_KEY`，請在目前 shell 中取消設定它，並從您的 shell 設定檔或 `.env` 檔案中移除它，然後重新啟動 `claude`

507* 如果訊息提及 `apiKeyHelper`，請從您的 `settings.json` 中移除 [`apiKeyHelper`](/zh-TW/settings#available-settings) 設定507* 如果訊息提及 `apiKeyHelper`，請從您的 `settings.json` 中移除 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 設定

508* 執行 `/login` 以使用您的 claude.ai 帳戶登入508* 執行 `/login` 以使用您的 claude.ai 帳戶登入

509* 之後執行 `/status` 以確認使用中的認證方式是您的訂閱而不是 API 金鑰509* 之後執行 `/status` 以確認使用中的認證方式是您的訂閱而不是 API 金鑰

510* 如果您需要 API 金鑰驗證進行自動化，請要求您的組織管理員在 Console 中重新啟用它510* 如果您需要 API 金鑰驗證進行自動化，請要求您的組織管理員在 Console 中重新啟用它

526**應該怎麼做：**526**應該怎麼做：**

527 527

528* 要求您的管理員為您的組織啟用 Claude Code 存取528* 要求您的管理員為您的組織啟用 Claude Code 存取

529* 使用 Console API 金鑰而不是您的訂閱進行驗證。請參閱 [Claude Console 驗證](/zh-TW/authentication#claude-console-authentication)以進行設定。529* 使用 Console API 金鑰而不是您的訂閱進行驗證。請參閱 [Claude Console 驗證](/docs/zh-TW/authentication#claude-console-authentication)以進行設定。

530* 如果您是管理員且看不到啟用存取的選項，請聯絡 [Anthropic 支援](https://support.claude.com)530* 如果您是管理員且看不到啟用存取的選項，請聯絡 [Anthropic 支援](https://support.claude.com)

531 531

532<h3 id="routines-are-disabled-by-your-organizations-policy">532<h3 id="routines-are-disabled-by-your-organizations-policy">

533 例行工作已被您的組織政策停用533 例行工作已被您的組織政策停用

534</h3>534</h3>

535 535

536您的 Team 或 Enterprise 組織中的擁有者已在組織層級關閉例行工作。當您嘗試建立或執行例行工作時（包括從 `/schedule` 和 claude.ai/code 上的[例行工作](/zh-TW/routines) UI），會出現此錯誤。536您的 Team 或 Enterprise 組織中的擁有者已在組織層級關閉例行工作。當您嘗試建立或執行例行工作時（包括從 `/schedule` 和 claude.ai/code 上的[例行工作](/docs/zh-TW/routines) UI），會出現此錯誤。

537 537

538```text theme={null}538```text theme={null}

539Routines are disabled by your organization's policy.539Routines are disabled by your organization's policy.

544**應該怎麼做：**544**應該怎麼做：**

545 545

546* 要求您的組織中的擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用**例行工作**切換546* 要求您的組織中的擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用**例行工作**切換

547* 對於不需要組織層級例行工作的一次性排程工作，請參閱[排程工作](/zh-TW/scheduled-tasks)547* 對於不需要組織層級例行工作的一次性排程工作，請參閱[排程工作](/docs/zh-TW/scheduled-tasks)

548 548

549<h3 id="remote-control-requires-the-anthropic-api">549<h3 id="remote-control-requires-the-anthropic-api">

550 Remote Control 需要 Anthropic API550 Remote Control 需要 Anthropic API

551</h3>551</h3>

552 552

553工作階段未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端供 [Remote Control](/zh-TW/remote-control) 配對。553工作階段未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端供 [Remote Control](/docs/zh-TW/remote-control) 配對。

554 554

555```text theme={null}555```text theme={null}

556Remote Control is only available when using Claude via api.anthropic.com.556Remote Control is only available when using Claude via api.anthropic.com.

557```557```

558 558

559這會出現在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}從 v2.1.196 開始，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機（例如 [LLM 閘道](/zh-TW/llm-gateway)或代理）時，即使您使用 claude.ai 登入，也會出現此訊息。559這會出現在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。從 v2.1.196 開始，當 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)或代理）時，即使您使用 claude.ai 登入，也會出現此訊息。

560 560

561**應該怎麼做：**561**應該怎麼做：**

562 562

563* 取消設定 `ANTHROPIC_BASE_URL` 並重新啟動工作階段，或從直接與 Anthropic API 通訊的工作階段啟動 Remote Control563* 取消設定 `ANTHROPIC_BASE_URL` 並重新啟動工作階段，或從直接與 Anthropic API 通訊的工作階段啟動 Remote Control

564* 對於此訊息和其他 Remote Control 啟動訊息，請參閱[疑難排解 Remote Control](/zh-TW/remote-control#troubleshooting)564* 對於此訊息和其他 Remote Control 啟動訊息，請參閱[疑難排解 Remote Control](/docs/zh-TW/remote-control#troubleshooting)

565 565

566<h3 id="oauth-token-revoked-or-expired">566<h3 id="oauth-token-revoked-or-expired">

567 OAuth 權杖已撤銷或已過期567 OAuth 權杖已撤銷或已過期

581 581

582* 執行 `/login` 以重新登入582* 執行 `/login` 以重新登入

583* 如果在同一工作階段中重新驗證後錯誤仍然出現，請先執行 `/logout` 以完全清除儲存的權杖，然後執行 `/login`583* 如果在同一工作階段中重新驗證後錯誤仍然出現，請先執行 `/logout` 以完全清除儲存的權杖，然後執行 `/login`

584* 對於跨啟動的重複登入提示，請參閱[疑難排解](/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)中的系統時鐘和 macOS Keychain 檢查584* 對於跨啟動的重複登入提示，請參閱[疑難排解](/docs/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)中的系統時鐘和 macOS Keychain 檢查

585* 對於其他失敗（包括 `403 Forbidden` 和 OAuth 瀏覽器問題），請參閱[登入和驗證](/zh-TW/troubleshoot-install#login-and-authentication)585* 對於其他失敗（包括 `403 Forbidden` 和 OAuth 瀏覽器問題），請參閱[登入和驗證](/docs/zh-TW/troubleshoot-install#login-and-authentication)

586 586

587<h3 id="login-expired">587<h3 id="login-expired">

588 登入已過期588 登入已過期

589</h3>589</h3>

590 590

591Claude Code 嘗試更新您儲存的 claude.ai 或 Claude Console 登入，OAuth 服務拒絕了儲存的重新整理權杖，因此 Claude Code 清除了儲存的認證方式。之後，每個請求在到達 API 之前都會在本機停止，因為只有 `/login` 可以建立新的認證方式。{/* min-version: 2.1.206 */}在 v2.1.206 之前，Claude Code 無論如何都會傳送請求，並使用環境中剩餘的任何認證方式，然後每個模型都會失敗並出現[所選模型有問題](#theres-an-issue-with-the-selected-model)或 401 而不是登入提示。591Claude Code 嘗試更新您儲存的 claude.ai 或 Claude Console 登入，OAuth 服務拒絕了儲存的重新整理權杖，因此 Claude Code 清除了儲存的認證方式。之後，每個請求在到達 API 之前都會在本機停止，因為只有 `/login` 可以建立新的認證方式。在 v2.1.206 之前，Claude Code 無論如何都會傳送請求，並使用環境中剩餘的任何認證方式，然後每個模型都會失敗並出現[所選模型有問題](#theres-an-issue-with-the-selected-model)或 401 而不是登入提示。

592 592

593```text theme={null}593```text theme={null}

594Login expired · Please run /login594Login expired · Please run /login

595```595```

596 596

597在[非互動模式](/zh-TW/headless)(`-p`) 和 [Agent SDK](/zh-TW/agent-sdk/overview) 中，訊息如下所示，結構化錯誤代碼為 `authentication_failed`：597在[非互動模式](/docs/zh-TW/headless)(`-p`) 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中，訊息如下所示，結構化錯誤代碼為 `authentication_failed`：

598 598

599```text theme={null}599```text theme={null}

600Failed to authenticate: OAuth session expired and could not be refreshed600Failed to authenticate: OAuth session expired and could not be refreshed

602 602

603這與[OAuth 權杖已撤銷或已過期](#oauth-token-revoked-or-expired)的狀態不同。這些訊息報告 API 傳回的 401。Claude Code 本身為已失敗更新的登入產生 `Login expired`，因此它不傳送任何請求。603這與[OAuth 權杖已撤銷或已過期](#oauth-token-revoked-or-expired)的狀態不同。這些訊息報告 API 傳回的 401。Claude Code 本身為已失敗更新的登入產生 `Login expired`，因此它不傳送任何請求。

604 604

605使用 API 金鑰、[`CLAUDE_CODE_OAUTH_TOKEN`](/zh-TW/env-vars) 或第三方提供者驗證的工作階段不使用儲存的登入，永遠不會看到此訊息。605使用 API 金鑰、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-TW/env-vars) 或第三方提供者驗證的工作階段不使用儲存的登入，永遠不會看到此訊息。

606 606

607**應該怎麼做：**607**應該怎麼做：**

608 608

609* 執行 `/login` 以重新登入。在不登入的情況下重試會在每個請求上顯示相同的訊息。609* 執行 `/login` 以重新登入。在不登入的情況下重試會在每個請求上顯示相同的訊息。

610* 在非互動模式中，在相同環境中執行 `claude`，完成 `/login`，然後重新執行您的命令。對於無法互動式登入的自動化，請使用 `ANTHROPIC_API_KEY` 進行驗證或[使用 `claude setup-token` 產生長期權杖](/zh-TW/authentication#generate-a-long-lived-token)。610* 在非互動模式中，在相同環境中執行 `claude`，完成 `/login`，然後重新執行您的命令。對於無法互動式登入的自動化，請使用 `ANTHROPIC_API_KEY` 進行驗證或[使用 `claude setup-token` 產生長期權杖](/docs/zh-TW/authentication#generate-a-long-lived-token)。

611* 如果登入持續失敗，請參閱[登入和驗證](/zh-TW/troubleshoot-install#login-and-authentication)611* 如果登入持續失敗，請參閱[登入和驗證](/docs/zh-TW/troubleshoot-install#login-and-authentication)

612 612

613<h3 id="oauth-scope-requirement">613<h3 id="oauth-scope-requirement">

614 OAuth 範圍要求614 OAuth 範圍要求

628 AWS 認證方式已過期或無效628 AWS 認證方式已過期或無效

629</h3>629</h3>

630 630

631{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 工作階段權杖已過期或被拒絕，Claude Code 已執行的自動重新整理未產生 API 接受的認證方式。它會出現在來自 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 的 401 上，這是這些提供者報告過期安全權杖的方式。631此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 [`awsAuthRefresh`](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 工作階段權杖已過期或被拒絕，Claude Code 已執行的自動重新整理未產生 API 接受的認證方式。它會出現在來自 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 的 401 上，這是這些提供者報告過期安全權杖的方式。

632 632

633中間的動作提示會命名您設定中的 `awsAuthRefresh` 命令，因此會有所不同。穩定的部分是前導的 `AWS credentials expired or invalid`：633中間的動作提示會命名您設定中的 `awsAuthRefresh` 命令，因此會有所不同。穩定的部分是前導的 `AWS credentials expired or invalid`：

634 634

641**應該怎麼做：**641**應該怎麼做：**

642 642

643* 在另一個終端中執行訊息中命名的 `awsAuthRefresh` 命令（例如 `aws sso login --profile myprofile`）並完成瀏覽器登入，然後重試643* 在另一個終端中執行訊息中命名的 `awsAuthRefresh` 命令（例如 `aws sso login --profile myprofile`）並完成瀏覽器登入，然後重試

644* 在互動式工作階段中，執行 `/login`，選擇 **3rd-party platform**，然後在 **Using 3rd-party platforms** 下選擇 **Claude Platform on AWS · refresh credentials** 以執行相同的命令而無需重新啟動 Claude Code。請參閱[設定 AWS 認證方式](/zh-TW/claude-platform-on-aws#1-configure-aws-credentials)644* 在互動式工作階段中，執行 `/login`，選擇 **3rd-party platform**，然後在 **Using 3rd-party platforms** 下選擇 **Claude Platform on AWS · refresh credentials** 以執行相同的命令而無需重新啟動 Claude Code。請參閱[設定 AWS 認證方式](/docs/zh-TW/claude-platform-on-aws#1-configure-aws-credentials)

645* 如果重新整理命令成功後錯誤仍然重複出現，請在相同的 shell 和設定檔中使用 `aws sts get-caller-identity` 確認身份在 Claude Code 外部有效645* 如果重新整理命令成功後錯誤仍然重複出現，請在相同的 shell 和設定檔中使用 `aws sts get-caller-identity` 確認身份在 Claude Code 外部有效

646 646

647<h3 id="aws-authentication-failed">647<h3 id="aws-authentication-failed">

648 AWS 驗證失敗648 AWS 驗證失敗

649</h3>649</h3>

650 650

651{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 提供者傳回了 403，或 [Amazon Bedrock](/zh-TW/amazon-bedrock) 傳回了 401。651此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 [`awsAuthRefresh`](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 提供者傳回了 403，或 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 傳回了 401。

652 652

653Claude Code 無法判斷您遇到了哪個原因。Amazon Bedrock 將過期的安全權杖報告為 403，但 403 也是它報告授權拒絕的方式，例如來自遺失 IAM 權限或未為您的帳戶啟用的模型的 `AccessDeniedException`。653Claude Code 無法判斷您遇到了哪個原因。Amazon Bedrock 將過期的安全權杖報告為 403，但 403 也是它報告授權拒絕的方式，例如來自遺失 IAM 權限或未為您的帳戶啟用的模型的 `AccessDeniedException`。

654 654

665**應該怎麼做：**665**應該怎麼做：**

666 666

667* 執行訊息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防過期的認證方式是原因667* 執行訊息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防過期的認證方式是原因

668* 如果您的認證方式是最新的，請確認 [IAM 配置](/zh-TW/amazon-bedrock#iam-configuration) 中的 IAM 權限已附加到您使用的身份，且所選模型已為您的帳戶和區域啟用668* 如果您的認證方式是最新的，請確認 [IAM 配置](/docs/zh-TW/amazon-bedrock#iam-configuration) 中的 IAM 權限已附加到您使用的身份，且所選模型已為您的帳戶和區域啟用

669* 執行 `aws sts get-caller-identity` 以確認您的請求使用哪個身份；過時的 `AWS_PROFILE` 或預設設定檔是權限不匹配的常見原因669* 執行 `aws sts get-caller-identity` 以確認您的請求使用哪個身份；過時的 `AWS_PROFILE` 或預設設定檔是權限不匹配的常見原因

670 670

671<h3 id="aws-default-chain-credential-resolve-timed-out">671<h3 id="aws-default-chain-credential-resolve-timed-out">

672 AWS 預設鏈認證方式解析逾時672 AWS 預設鏈認證方式解析逾時

673</h3>673</h3>

674 674

675AWS 預設認證方式提供者鏈在 60 秒內未產生認證方式，因此 Claude Code 停止了解析並使請求失敗。失敗是本機認證方式解析：請求永遠未到達 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。Claude Code 在此錯誤出現之前會清除其[認證方式快取](/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)並在重複嘗試後重試，因此當您看到它時鏈已在重複嘗試上停滯。675AWS 預設認證方式提供者鏈在 60 秒內未產生認證方式，因此 Claude Code 停止了解析並使請求失敗。失敗是本機認證方式解析：請求永遠未到達 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。Claude Code 在此錯誤出現之前會清除其[認證方式快取](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)並在重複嘗試後重試，因此當您看到它時鏈已在重複嘗試上停滯。

676 676

677```text theme={null}677```text theme={null}

678API Error: AWS default-chain credential resolve timed out678API Error: AWS default-chain credential resolve timed out

679```679```

680 680

681常見原因是您的 AWS 設定檔中的 `credential_process` 命令等待它無法接收的輸入，以及容器或 VM 的執行個體中繼資料服務 (IMDS) 永遠不會回答鏈的探測。{/* min-version: 2.1.207 */}在 v2.1.207 之前，停滯的鏈會讓請求無限期等待，而不是以此訊息失敗。681常見原因是您的 AWS 設定檔中的 `credential_process` 命令等待它無法接收的輸入，以及容器或 VM 的執行個體中繼資料服務 (IMDS) 永遠不會回答鏈的探測。在 v2.1.207 之前，停滯的鏈會讓請求無限期等待，而不是以此訊息失敗。

682 682

683**應該怎麼做：**683**應該怎麼做：**

684 684

685* 在相同的 shell 中使用相同的 `AWS_PROFILE` 執行 `aws sts get-caller-identity`。如果它也掛起，請修復設定檔；互動式提示的 `credential_process` 命令是常見原因。685* 在相同的 shell 中使用相同的 `AWS_PROFILE` 執行 `aws sts get-caller-identity`。如果它也掛起，請修復設定檔；互動式提示的 `credential_process` 命令是常見原因。

686* 在啟動 Claude Code 之前完成登入步驟，例如 `aws sso login --profile myprofile`，以便鏈從本機 SSO 快取解析而不是等待瀏覽器流程686* 在啟動 Claude Code 之前完成登入步驟，例如 `aws sso login --profile myprofile`，以便鏈從本機 SSO 快取解析而不是等待瀏覽器流程

687* 如果您的鏈執行合法需要超過 60 秒的互動式登入，例如透過 `aws-vault` 等包裝程式的 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/zh-TW/env-vars) 以毫秒為單位提高限制687* 如果您的鏈執行合法需要超過 60 秒的互動式登入，例如透過 `aws-vault` 等包裝程式的 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制

688 688

689<h2 id="network-and-connection-errors">689<h2 id="network-and-connection-errors">

690 網路和連線錯誤690 網路和連線錯誤

712**該怎麼做：**712**該怎麼做：**

713 713

714* 透過在同一個 shell 中執行 `curl -I https://api.anthropic.com` 來確認您可以到達 API 主機。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以免使用內建的 `Invoke-WebRequest` 別名。714* 透過在同一個 shell 中執行 `curl -I https://api.anthropic.com` 來確認您可以到達 API 主機。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以免使用內建的 `Invoke-WebRequest` 別名。

715* 如果您在公司代理伺服器後面，請在啟動 Claude Code 前設定 `HTTPS_PROXY`，並參閱[網路設定](/zh-TW/network-config)715* 如果您在公司代理伺服器後面，請在啟動 Claude Code 前設定 `HTTPS_PROXY`，並參閱[網路設定](/docs/zh-TW/network-config)

716* 如果您透過 LLM 閘道或中繼站路由，請將 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 設定為其位址。請參閱[將 Claude Code 連線到 LLM 閘道](/zh-TW/llm-gateway-connect)以取得設定說明。716* 如果您透過 LLM 閘道或中繼站路由，請將 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 設定為其位址。請參閱[將 Claude Code 連線到 LLM 閘道](/docs/zh-TW/llm-gateway-connect)以取得設定說明。

717* 確保您的防火牆允許[網路存取需求](/zh-TW/network-config#network-access-requirements)中列出的主機717* 確保您的防火牆允許[網路存取需求](/docs/zh-TW/network-config#network-access-requirements)中列出的主機

718* 間歇性故障會[自動重試](#automatic-retries)；持續性故障指向本機網路問題718* 間歇性故障會[自動重試](#automatic-retries)；持續性故障指向本機網路問題

719 719

720如果 `curl` 成功但 Claude Code 仍然失敗，原因通常是執行時間和網路之間的某些東西，而不是網路本身：720如果 `curl` 成功但 Claude Code 仍然失敗，原因通常是執行時間和網路之間的某些東西，而不是網路本身：

727 Bedrock 串流回應有非預期的 content-type727 Bedrock 串流回應有非預期的 content-type

728</h3>728</h3>

729 729

730Claude Code 和 [Amazon Bedrock](/zh-TW/amazon-bedrock) 之間的閘道或代理伺服器正在轉換串流回應本體或其 `Content-Type` 標頭。Amazon Bedrock 將回應串流為 `application/vnd.amazon.eventstream`，而 Claude Code 會拒絕報告不同 content-type 的成功串流回應，而不是解碼它無法讀取的本體。該請求不會重試。730Claude Code 和 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 之間的閘道或代理伺服器正在轉換串流回應本體或其 `Content-Type` 標頭。Amazon Bedrock 將回應串流為 `application/vnd.amazon.eventstream`，而 Claude Code 會拒絕報告不同 content-type 的成功串流回應，而不是解碼它無法讀取的本體。該請求不會重試。

731 731

732```text theme={null}732```text theme={null}

733Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.733Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.

734```734```

735 735

736{/* min-version: 2.1.208 */}在 v2.1.208 之前，相同的設定錯誤會在整個回應被緩衝後顯示為 `API Error: Truncated event message received`。736在 v2.1.208 之前，相同的設定錯誤會在整個回應被緩衝後顯示為 `API Error: Truncated event message received`。

737 737

738**該怎麼做：**738**該怎麼做：**

739 739

740* 設定閘道以不修改地傳遞 `InvokeModelWithResponseStream` 回應本體及其 `Content-Type` 標頭。將串流重新發出為伺服器傳送事件的中介是常見原因。740* 設定閘道以不修改地傳遞 `InvokeModelWithResponseStream` 回應本體及其 `Content-Type` 標頭。將串流重新發出為伺服器傳送事件的中介是常見原因。

741* 如果閘道只重寫標頭並完整傳遞二進位本體，請設定 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/zh-TW/env-vars) 以在閘道修復前跳過檢查。請參閱[閘道或代理伺服器後的串流錯誤](/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。741* 如果閘道只重寫標頭並完整傳遞二進位本體，請設定 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/docs/zh-TW/env-vars) 以在閘道修復前跳過檢查。請參閱[閘道或代理伺服器後的串流錯誤](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。

742 742

743<h3 id="ssl-certificate-errors">743<h3 id="ssl-certificate-errors">

744 SSL 憑證錯誤744 SSL 憑證錯誤

751Unable to connect to API: Self-signed certificate detected751Unable to connect to API: Self-signed certificate detected

752```752```

753 753

754{/* min-version: 2.1.199 */}自 v2.1.199 起，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整[重試預算](#automatic-retries)後出現。較早的版本在顯示它之前會花費幾分鐘重試。暫時性 TLS 條件（例如握手逾時）仍會重試。754自 v2.1.199 起，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整[重試預算](#automatic-retries)後出現。較早的版本在顯示它之前會花費幾分鐘重試。暫時性 TLS 條件（例如握手逾時）仍會重試。

755 755

756在 `/login` 和啟動連線檢查期間，同樣的失敗會以 OpenSSL 代碼和內聯修復報告：756在 `/login` 和啟動連線檢查期間，同樣的失敗會以 OpenSSL 代碼和內聯修復報告：

757 757

762**該怎麼做：**762**該怎麼做：**

763 763

764* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 將 Claude Code 指向它764* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 將 Claude Code 指向它

765* 請參閱[網路設定](/zh-TW/network-config#custom-ca-certificates)以取得完整設定說明765* 請參閱[網路設定](/docs/zh-TW/network-config#custom-ca-certificates)以取得完整設定說明

766* 不要設定 `NODE_TLS_REJECT_UNAUTHORIZED=0`，這會完全停用憑證驗證766* 不要設定 `NODE_TLS_REJECT_UNAUTHORIZED=0`，這會完全停用憑證驗證

767 767

768<h3 id="host-not-allowed-in-a-cloud-session">768<h3 id="host-not-allowed-in-a-cloud-session">

778 778

779您也可能看到與目的地實際憑證不符的 TLS 憑證。雲端環境透過代理伺服器路由出站流量以強制執行網路政策，因此不符的憑證表示代理伺服器終止了連線，而不是目的地。779您也可能看到與目的地實際憑證不符的 TLS 憑證。雲端環境透過代理伺服器路由出站流量以強制執行網路政策，因此不符的憑證表示代理伺服器終止了連線，而不是目的地。

780 780

781這不是用戶端網路問題。雲端工作階段和[例行程序](/zh-TW/routines)在沙箱環境內執行，其出站流量被篩選到環境的允許清單。**預設**環境使用**信任**存取，允許[預設允許清單](/zh-TW/claude-code-on-the-web#default-allowed-domains)的套件登錄、雲端提供者 API、容器登錄和常見開發網域，但阻止其他所有內容。781這不是用戶端網路問題。雲端工作階段和[例行程序](/docs/zh-TW/routines)在沙箱環境內執行，其出站流量被篩選到環境的允許清單。**預設**環境使用**信任**存取，允許[預設允許清單](/docs/zh-TW/claude-code-on-the-web#default-allowed-domains)的套件登錄、雲端提供者 API、容器登錄和常見開發網域，但阻止其他所有內容。

782 782

783**該怎麼做：**783**該怎麼做：**

784 784

785* 開啟例行程序進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱（例如**預設**）的雲端圖示以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。785* 開啟例行程序進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱（例如**預設**）的雲端圖示以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。

786* 在**更新雲端環境**對話方塊中，將**網路存取**從**信任**變更為**自訂**，然後將被阻止的網域新增到**允許的網域**。每行輸入一個網域。勾選**也包含常見套件管理員的預設清單**以在自訂網域旁保留[預設允許清單](/zh-TW/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇**完整**。786* 在**更新雲端環境**對話方塊中，將**網路存取**從**信任**變更為**自訂**，然後將被阻止的網域新增到**允許的網域**。每行輸入一個網域。勾選**也包含常見套件管理員的預設清單**以在自訂網域旁保留[預設允許清單](/docs/zh-TW/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇**完整**。

787* 按一下**儲存變更**。下一次執行會使用更新的允許清單。787* 按一下**儲存變更**。下一次執行會使用更新的允許清單。

788 788

789請參閱[網路存取](/zh-TW/claude-code-on-the-web#network-access)以取得存取層級和預設允許清單。本機 CLI 工作階段不受此政策影響。789請參閱[網路存取](/docs/zh-TW/claude-code-on-the-web#network-access)以取得存取層級和預設允許清單。本機 CLI 工作階段不受此政策影響。

790 790

791<h3 id="couldnt-reconnect-to-your-remote-control-session">791<h3 id="couldnt-reconnect-to-your-remote-control-session">

792 無法重新連線到您的遠端控制工作階段792 無法重新連線到您的遠端控制工作階段

796Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.796Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

797```797```

798 798

799使用 `claude --resume` 或 `claude --continue` 恢復會重新連線到該對話中記錄的[遠端控制](/zh-TW/remote-control)工作階段。此訊息表示重新連線因可能是暫時性的原因（例如網路中斷或伺服器錯誤）而失敗，因此 Claude Code 無法確認遠端工作階段是否仍然存在。您的本機工作階段會繼續執行，但不使用遠端控制。799使用 `claude --resume` 或 `claude --continue` 恢復會重新連線到該對話中記錄的[遠端控制](/docs/zh-TW/remote-control)工作階段。此訊息表示重新連線因可能是暫時性的原因（例如網路中斷或伺服器錯誤）而失敗，因此 Claude Code 無法確認遠端工作階段是否仍然存在。您的本機工作階段會繼續執行，但不使用遠端控制。

800 800

801**該怎麼做：**801**該怎麼做：**

802 802

803* 執行 `/remote-control` 以重試連線803* 執行 `/remote-control` 以重試連線

804* 啟動 Claude Code 時不使用 `--resume` 以建立新的遠端控制工作階段804* 啟動 Claude Code 時不使用 `--resume` 以建立新的遠端控制工作階段

805* 如需其他遠端控制啟動訊息，請參閱[遠端控制疑難排解](/zh-TW/remote-control#troubleshooting)805* 如需其他遠端控制啟動訊息，請參閱[遠端控制疑難排解](/docs/zh-TW/remote-control#troubleshooting)

806 806

807當伺服器確認前一個工作階段不再存在時，您不會看到此訊息；Claude Code 在這種情況下會建立一個新的工作階段。{/* min-version: 2.1.200 */}在 v2.1.200 之前，任何重新連線失敗都會建立新的遠端控制工作階段，這在 claude.ai/code 的工作階段清單中留下額外的工作階段。807當伺服器確認前一個工作階段不再存在時，您不會看到此訊息；Claude Code 在這種情況下會建立一個新的工作階段。在 v2.1.200 之前，任何重新連線失敗都會建立新的遠端控制工作階段，這在 claude.ai/code 的工作階段清單中留下額外的工作階段。

808 808

809<h2 id="request-errors">809<h2 id="request-errors">

810 請求錯誤810 請求錯誤

827* 執行 `/compact` 來總結早期的回合並釋放空間，或執行 `/clear` 來重新開始827* 執行 `/compact` 來總結早期的回合並釋放空間，或執行 `/clear` 來重新開始

828* 執行 `/context` 來查看視窗消耗的詳細分解：系統提示詞、工具、記憶檔案和訊息828* 執行 `/context` 來查看視窗消耗的詳細分解：系統提示詞、工具、記憶檔案和訊息

829* 使用 `/mcp disable <name>` 停用您未使用的 MCP 伺服器，以從上下文中移除其工具定義829* 使用 `/mcp disable <name>` 停用您未使用的 MCP 伺服器，以從上下文中移除其工具定義

830* 修剪大型 `CLAUDE.md` 記憶檔案，或將指令移至[路徑範圍規則](/zh-TW/memory#path-specific-rules)，這些規則只在相關時載入830* 修剪大型 `CLAUDE.md` 記憶檔案，或將指令移至[路徑範圍規則](/docs/zh-TW/memory#path-specific-rules)，這些規則只在相關時載入

831* 子代理繼承父工作階段中的每個 MCP 工具定義，這可能會在第一個回合之前填滿其上下文視窗。在生成子代理之前停用您未使用的 MCP 伺服器。831* 子代理繼承父工作階段中的每個 MCP 工具定義，這可能會在第一個回合之前填滿其上下文視窗。在生成子代理之前停用您未使用的 MCP 伺服器。

832* 自動壓縮預設為開啟，通常可防止此錯誤。如果您已設定 [`DISABLE_AUTO_COMPACT`](/zh-TW/env-vars)，請重新啟用它或在視窗填滿之前手動執行 `/compact`。832* 自動壓縮預設為開啟，通常可防止此錯誤。如果您已設定 [`DISABLE_AUTO_COMPACT`](/docs/zh-TW/env-vars)，請重新啟用它或在視窗填滿之前手動執行 `/compact`。

833 833

834請參閱[探索上下文視窗](/zh-TW/context-window)以取得上下文如何填滿的互動式檢視。834請參閱[探索上下文視窗](/docs/zh-TW/context-window)以取得上下文如何填滿的互動式檢視。

835 835

836<h3 id="error-during-compaction-conversation-too-long">836<h3 id="error-during-compaction-conversation-too-long">

837 壓縮期間出錯：對話過長837 壓縮期間出錯：對話過長

879API Error: 400 ... image dimensions exceed max allowed size879API Error: 400 ... image dimensions exceed max allowed size

880```880```

881 881

882{/* min-version: 2.1.142 */}Claude Code 將無法處理的影像替換為文字佔位符並重試，因此後續訊息會成功。在 2.1.142 之前的版本上，貼上的影像可能會保留在對話中，並在每個後續訊息上重複相同的錯誤。若要在這些版本上恢復，請按 Esc 兩次並回溯到添加影像的回合之前。882Claude Code 將無法處理的影像替換為文字佔位符並重試，因此後續訊息會成功。在 2.1.142 之前的版本上，貼上的影像可能會保留在對話中，並在每個後續訊息上重複相同的錯誤。若要在這些版本上恢復，請按 Esc 兩次並回溯到添加影像的回合之前。

883 883

884**該怎麼做：**884**該怎麼做：**

885 885

939 939

940**該怎麼做：**940**該怎麼做：**

941 941

942* 配置您的閘道以轉發 `anthropic-beta` 標頭。請參閱[功能傳遞](/zh-TW/llm-gateway-protocol#feature-pass-through)以了解閘道必須轉發的內容。942* 配置您的閘道以轉發 `anthropic-beta` 標頭。請參閱[功能傳遞](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)以了解閘道必須轉發的內容。

943* 作為備選方案，在啟動前設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-TW/env-vars)。這會停用需要測試版標頭的功能，以便請求通過無法轉發它的閘道成功。943* 作為備選方案，在啟動前設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-TW/env-vars)。這會停用需要測試版標頭的功能，以便請求通過無法轉發它的閘道成功。

944 944

945<h3 id="theres-an-issue-with-the-selected-model">945<h3 id="theres-an-issue-with-the-selected-model">

946 選定的模型有問題946 選定的模型有問題

955**該怎麼做：**955**該怎麼做：**

956 956

957* **互動式 CLI**：執行 `/model` 以從您帳戶可用的模型中選擇。957* **互動式 CLI**：執行 `/model` 以從您帳戶可用的模型中選擇。

958* **非互動模式 (`-p`)**：使用有效的別名或 ID 傳遞 `--model`，或設定 [`ANTHROPIC_MODEL`](/zh-TW/env-vars)。錯誤文字在此表面上顯示 `Run --model`。958* **非互動模式 (`-p`)**：使用有效的別名或 ID 傳遞 `--model`，或設定 [`ANTHROPIC_MODEL`](/docs/zh-TW/env-vars)。錯誤文字在此表面上顯示 `Run --model`。

959* **Agent SDK**：錯誤文字省略提示，因為模型是以程式設計方式設定的。在 TypeScript 中設定 [`Options` 上的 `model`](/zh-TW/agent-sdk/typescript#options)，或在 Python 中設定 [`ClaudeAgentOptions(model=...)`](/zh-TW/agent-sdk/python#claudeagentoptions)，並處理結構化的 `model_not_found` 錯誤以呈現您自己的重試或模型選擇器。959* **Agent SDK**：錯誤文字省略提示，因為模型是以程式設計方式設定的。在 TypeScript 中設定 [`Options` 上的 `model`](/docs/zh-TW/agent-sdk/typescript#options)，或在 Python 中設定 [`ClaudeAgentOptions(model=...)`](/docs/zh-TW/agent-sdk/python#claudeagentoptions)，並處理結構化的 `model_not_found` 錯誤以呈現您自己的重試或模型選擇器。

960* 使用別名（例如 `sonnet` 或 `opus`）而不是完整的版本化 ID。別名解析為維護的預設值，因此不會過時。請參閱[模型配置](/zh-TW/model-config)。960* 使用別名（例如 `sonnet` 或 `opus`）而不是完整的版本化 ID。別名解析為維護的預設值，因此不會過時。請參閱[模型配置](/docs/zh-TW/model-config)。

961* 如果 CLI 中一直出現錯誤的模型，則某處設定了過時的 ID。按[優先順序](/zh-TW/model-config#setting-your-model)檢查：`--model` 標誌、`ANTHROPIC_MODEL` 環境變數，然後是 `.claude/settings.local.json` 中的 `model` 欄位、您專案的 `.claude/settings.json` 和 `~/.claude/settings.json`。移除過時的值，Claude Code 會回退到您的帳戶預設值。961* 如果 CLI 中一直出現錯誤的模型，則某處設定了過時的 ID。按[優先順序](/docs/zh-TW/model-config#setting-your-model)檢查：`--model` 標誌、`ANTHROPIC_MODEL` 環境變數，然後是 `.claude/settings.local.json` 中的 `model` 欄位、您專案的 `.claude/settings.json` 和 `~/.claude/settings.json`。移除過時的值，Claude Code 會回退到您的帳戶預設值。

962* {/* min-version: 2.1.206 */}Claude Code 將過期的 claude.ai 登入報告為[登入已過期](#login-expired)，而不是此錯誤。在 v2.1.206 之前，無法再刷新的過期登入在每個模型上都失敗，出現此錯誤；如果您在較舊版本上看到此情況，請執行 `/login`。962* Claude Code 將過期的 claude.ai 登入報告為[登入已過期](#login-expired)，而不是此錯誤。在 v2.1.206 之前，無法再刷新的過期登入在每個模型上都失敗，出現此錯誤；如果您在較舊版本上看到此情況，請執行 `/login`。

963* 對於 Google Cloud 的 Agent Platform 部署，請參閱 [Google Cloud 的 Agent Platform 故障排除](/zh-TW/google-vertex-ai#troubleshooting)。963* 對於 Google Cloud 的 Agent Platform 部署，請參閱 [Google Cloud 的 Agent Platform 故障排除](/docs/zh-TW/google-vertex-ai#troubleshooting)。

964 964

965<h3 id="model-is-not-a-recognized-model-id">965<h3 id="model-is-not-a-recognized-model-id">

966 模型不是公認的模型 ID966 模型不是公認的模型 ID

974 974

975尾部提示命名最接近的匹配別名或模型 ID。當沒有足夠接近的內容時，它會改為讀取 `Run /model to see available models.`。975尾部提示命名最接近的匹配別名或模型 ID。當沒有足夠接近的內容時，它會改為讀取 `Run /model to see available models.`。

976 976

977Claude Code 在請求切換時在本地產生此錯誤，在發出任何 API 請求之前。它適用於通過 [Agent SDK](/zh-TW/agent-sdk/typescript) `setModel()` 方法或為您執行 Claude Code CLI 的應用程式（例如 [Desktop 應用程式](/zh-TW/desktop)）設定模型的情況。977Claude Code 在請求切換時在本地產生此錯誤，在發出任何 API 請求之前。它適用於通過 [Agent SDK](/docs/zh-TW/agent-sdk/typescript) `setModel()` 方法或為您執行 Claude Code CLI 的應用程式（例如 [Desktop 應用程式](/docs/zh-TW/desktop)）設定模型的情況。

978 978

979**該怎麼做：**979**該怎麼做：**

980 980

981* 執行不帶引數的 `/model` 以開啟選擇器並從您帳戶可用的模型中選擇，然後傳遞那裡顯示的別名或 ID981* 執行不帶引數的 `/model` 以開啟選擇器並從您帳戶可用的模型中選擇，然後傳遞那裡顯示的別名或 ID

982* 如果您使用了較新 Claude Code 版本支援的別名，請執行 `claude update`。以 `claude-` 開頭的完整 ID 即使模型比您的 Claude Code 版本更新，也會通過此檢查，因此不需要升級。982* 如果您使用了較新 Claude Code 版本支援的別名，請執行 `claude update`。以 `claude-` 開頭的完整 ID 即使模型比您的 Claude Code 版本更新，也會通過此檢查，因此不需要升級。

983* v2.1.200 之前儲存的模型不會被此檢查修復。如果過時的值一直出現，請從[選定的模型有問題](#theres-an-issue-with-the-selected-model)下列出的位置移除它。983* v2.1.200 之前儲存的模型不會被此檢查修復。如果過時的值一直出現，請從[選定的模型有問題](#theres-an-issue-with-the-selected-model)下列出的位置移除它。

984* 檢查僅在 Anthropic API 上執行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 和 [LLM 閘道](/zh-TW/llm-gateway)後面或自訂 `ANTHROPIC_BASE_URL`，您的提供者或閘道定義模型名稱，因此 Claude Code 接受任何字串並將其傳遞。984* 檢查僅在 Anthropic API 上執行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 和 [LLM 閘道](/docs/zh-TW/llm-gateway)後面或自訂 `ANTHROPIC_BASE_URL`，您的提供者或閘道定義模型名稱，因此 Claude Code 接受任何字串並將其傳遞。

985 985

986<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">986<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

987 Claude Opus 不適用於 Claude Pro 方案987 Claude Opus 不適用於 Claude Pro 方案

1003 模型受您組織的設定限制1003 模型受您組織的設定限制

1004</h3>1004</h3>

1005 1005

1006您的組織管理員已在 claude.ai 管理控制台中停用此模型，或它被託管設定中的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單排除。當使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 設定設定受限制的模型時，Claude Code 會替換為允許的模型並繼續。為受限制的模型鍵入 `/model <name>` 會被拒絕，顯示 `Run /model to choose a different model.`，工作階段保持其目前模型。1006您的組織管理員已在 claude.ai 管理控制台中停用此模型，或它被託管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除。當使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 設定設定受限制的模型時，Claude Code 會替換為允許的模型並繼續。為受限制的模型鍵入 `/model <name>` 會被拒絕，顯示 `Run /model to choose a different model.`，工作階段保持其目前模型。

1007 1007

1008```text theme={null}1008```text theme={null}

1009Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.1009Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

1010```1010```

1011 1011

1012Claude Code 將模型系列別名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）視為對該系列的請求，而不是對其最新版本的請求。在 Anthropic API 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上，受限制的系列別名解析為您的組織和 `availableModels` 允許清單允許的系列的最新版本，替換通知命名該版本。Claude Code 僅在系列的每個版本都受限制時才拒絕 `/model <alias>`。在 v2.1.205 之前，系列別名是根據其最新版本單獨替換或拒絕的，即使同一系列的較舊版本被允許。1012Claude Code 將模型系列別名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）視為對該系列的請求，而不是對其最新版本的請求。在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 上，受限制的系列別名解析為您的組織和 `availableModels` 允許清單允許的系列的最新版本，替換通知命名該版本。Claude Code 僅在系列的每個版本都受限制時才拒絕 `/model <alias>`。在 v2.1.205 之前，系列別名是根據其最新版本單獨替換或拒絕的，即使同一系列的較舊版本被允許。

1013 1013

1014**該怎麼做：**1014**該怎麼做：**

1015 1015

1016* 執行 `/model` 以從您的組織允許的模型中選擇。受限制的模型在選擇器中隱藏。1016* 執行 `/model` 以從您的組織允許的模型中選擇。受限制的模型在選擇器中隱藏。

1017* 如果受限制的模型是在 `--model`、`ANTHROPIC_MODEL` 或設定檔案的 `model` 欄位中設定的，請移除或更新該值，以便通知不會在每次啟動時重複出現1017* 如果受限制的模型是在 `--model`、`ANTHROPIC_MODEL` 或設定檔案的 `model` 欄位中設定的，請移除或更新該值，以便通知不會在每次啟動時重複出現

1018* 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱[組織模型限制](/zh-TW/model-config#organization-model-restrictions)。1018* 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱[組織模型限制](/docs/zh-TW/model-config#organization-model-restrictions)。

1019 1019

1020<h3 id="thinking-type-enabled-is-not-supported-for-this-model">1020<h3 id="thinking-type-enabled-is-not-supported-for-this-model">

1021 此模型不支援 thinking.type.enabled1021 此模型不支援 thinking.type.enabled

1031 1031

1032* 執行 `claude update` 並重新啟動 Claude Code。Opus 4.7 需要 v2.1.111 或更新版本。Opus 4.8 需要 v2.1.154 或更新版本。Sonnet 5 需要 v2.1.197 或更新版本1032* 執行 `claude update` 並重新啟動 Claude Code。Opus 4.7 需要 v2.1.111 或更新版本。Opus 4.8 需要 v2.1.154 或更新版本。Sonnet 5 需要 v2.1.197 或更新版本

1033* 如果您無法升級，請執行 `/model` 並改為選擇 Opus 4.6 或 Sonnet 4.61033* 如果您無法升級，請執行 `/model` 並改為選擇 Opus 4.6 或 Sonnet 4.6

1034* {/* min-version: agent-sdk@0.3.197 */}如果您在 [Agent SDK](/zh-TW/agent-sdk/overview) 中遇到此問題，請改為升級 SDK 套件。Opus 4.8 需要 TypeScript SDK v0.3.154 或更新版本和 Python SDK v0.2.88 或更新版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更新版本1034* 如果您在 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中遇到此問題，請改為升級 SDK 套件。Opus 4.8 需要 TypeScript SDK v0.3.154 或更新版本和 Python SDK v0.2.88 或更新版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更新版本

1035 1035

1036<h3 id="thinking-budget-exceeds-output-limit">1036<h3 id="thinking-budget-exceeds-output-limit">

1037 思考預算超過輸出限制1037 思考預算超過輸出限制

1043API Error: 400 ... max_tokens must be greater than thinking.budget_tokens1043API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

1044```1044```

1045 1045

1046Claude Code 在 Anthropic API 上自動調整這些值。當 [`MAX_THINKING_TOKENS`](/zh-TW/env-vars) 設定高於提供者的輸出限制時，或當計畫模式提高思考預算時，您通常會在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此錯誤。1046Claude Code 在 Anthropic API 上自動調整這些值。當 [`MAX_THINKING_TOKENS`](/docs/zh-TW/env-vars) 設定高於提供者的輸出限制時，或當計畫模式提高思考預算時，您通常會在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此錯誤。

1047 1047

1048**該怎麼做：**1048**該怎麼做：**

1049 1049

1050* 降低 `MAX_THINKING_TOKENS`，或將 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-TW/env-vars) 提高到思考預算之上1050* 降低 `MAX_THINKING_TOKENS`，或將 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/zh-TW/env-vars) 提高到思考預算之上

1051* 請參閱[擴展思考](/zh-TW/model-config#extended-thinking)以了解預算如何與輸出長度互動1051* 請參閱[擴展思考](/docs/zh-TW/model-config#extended-thinking)以了解預算如何與輸出長度互動

1052 1052

1053<h3 id="tool-use-or-thinking-block-mismatch">1053<h3 id="tool-use-or-thinking-block-mismatch">

1054 工具使用或思考區塊不匹配1054 工具使用或思考區塊不匹配

1066 1066

1067**該怎麼做：**1067**該怎麼做：**

1068 1068

1069* {/* max-version: 2.1.155 */}如果您使用的是 Opus 4.7 或 Opus 4.8，請先執行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期間觸發此錯誤，而 `/rewind` 不會清除它。1069* 如果您使用的是 Opus 4.7 或 Opus 4.8，請先執行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期間觸發此錯誤，而 `/rewind` 不會清除它。

1070* 執行 `/rewind` 或按 Esc 兩次，以回溯到損壞回合之前的檢查點並從那裡繼續。請參閱[檢查點](/zh-TW/checkpointing)以了解如何建立和恢復檢查點。1070* 執行 `/rewind` 或按 Esc 兩次，以回溯到損壞回合之前的檢查點並從那裡繼續。請參閱[檢查點](/docs/zh-TW/checkpointing)以了解如何建立和恢復檢查點。

1071 1071

1072<h3 id="usage-policy-refusal">1072<h3 id="usage-policy-refusal">

1073 使用政策拒絕1073 使用政策拒絕

1079API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.1079API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

1080```1080```

1081 1081

1082檢查評估完整對話，而不僅是您的最新提示，因此在同一工作階段中發送新訊息通常會重新觸發相同的拒絕。在使用 `--continue` 或 `--resume` 退出並重新開啟工作階段後也是如此，因為磁碟上的文字記錄仍然包含觸發內容。在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上，此訊息也涵蓋模型的安全措施標記為網路安全主題的請求。請參閱[安全措施標記了網路安全主題](#safety-measures-flagged-a-cybersecurity-topic)。1082檢查評估完整對話，而不僅是您的最新提示，因此在同一工作階段中發送新訊息通常會重新觸發相同的拒絕。在使用 `--continue` 或 `--resume` 退出並重新開啟工作階段後也是如此，因為磁碟上的文字記錄仍然包含觸發內容。在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，此訊息也涵蓋模型的安全措施標記為網路安全主題的請求。請參閱[安全措施標記了網路安全主題](#safety-measures-flagged-a-cybersecurity-topic)。

1083 1083

1084**該怎麼做：**1084**該怎麼做：**

1085 1085

1086* 按 Esc 兩次或執行 `/rewind` 以回溯到觸發拒絕的回合之前的檢查點，然後重新表述或採取不同的方法。請參閱[檢查點](/zh-TW/checkpointing)。1086* 按 Esc 兩次或執行 `/rewind` 以回溯到觸發拒絕的回合之前的檢查點，然後重新表述或採取不同的方法。請參閱[檢查點](/docs/zh-TW/checkpointing)。

1087* 如果您無法識別哪個回合導致了它，請執行 `/clear` 以在同一專案中開始新的對話。您之前的對話會保留在磁碟上，並在 `/resume` 中保持可用。1087* 如果您無法識別哪個回合導致了它，請執行 `/clear` 以在同一專案中開始新的對話。您之前的對話會保留在磁碟上，並在 `/resume` 中保持可用。

1088* 在[非互動模式](/zh-TW/headless)(`-p`) 中，其中無法進行倒帶，請在沒有 `--continue` 的新工作階段中使用重新表述的提示重試。政策檢查因模型而異，因此使用 `--model` 切換到不同的模型也可能在某些情況下解決拒絕。1088* 在[非互動模式](/docs/zh-TW/headless)(`-p`) 中，其中無法進行倒帶，請在沒有 `--continue` 的新工作階段中使用重新表述的提示重試。政策檢查因模型而異，因此使用 `--model` 切換到不同的模型也可能在某些情況下解決拒絕。

1089 1089

1090<h3 id="safety-measures-flagged-a-cybersecurity-topic">1090<h3 id="safety-measures-flagged-a-cybersecurity-topic">

1091 安全措施標記了網路安全主題1091 安全措施標記了網路安全主題

1103 1103

1104您看到的內容取決於您的提供者和模式：1104您看到的內容取決於您的提供者和模式：

1105 1105

1106* 在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上，網路安全標記會產生[使用政策拒絕](#usage-policy-refusal)訊息。1106* 在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，網路安全標記會產生[使用政策拒絕](#usage-policy-refusal)訊息。

1107* [非互動模式](/zh-TW/headless)省略 `/feedback` 句子。1107* [非互動模式](/docs/zh-TW/headless)省略 `/feedback` 句子。

1108 1108

1109{/* max-version: 2.1.202 */}在 v2.1.203 之前，訊息讀取 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` 後跟豁免表單連結。1109在 v2.1.203 之前，訊息讀取 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` 後跟豁免表單連結。

1110 1110

1111**該怎麼做：**1111**該怎麼做：**

1112 1112

1113* 如果您的工作需要此內容，請通過[網路安全驗證計畫](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)申請存取權限1113* 如果您的工作需要此內容，請通過[網路安全驗證計畫](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)申請存取權限

1114* 如果您的請求不是關於網路安全主題，請執行 `/feedback` 以報告誤報1114* 如果您的請求不是關於網路安全主題，請執行 `/feedback` 以報告誤報

1115* 若要在同一工作階段中繼續工作，請按 Esc 兩次或執行 `/rewind` 以回溯到觸發標記的回合之前的檢查點，然後採取不同的方法。請參閱[檢查點](/zh-TW/checkpointing)。1115* 若要在同一工作階段中繼續工作，請按 Esc 兩次或執行 `/rewind` 以回溯到觸發標記的回合之前的檢查點，然後採取不同的方法。請參閱[檢查點](/docs/zh-TW/checkpointing)。

1116 1116

1117<h2 id="installation-errors">1117<h2 id="installation-errors">

1118 安裝錯誤1118 安裝錯誤

1119</h2>1119</h2>

1120 1120

1121這些錯誤會在安裝或更新 Claude Code 時出現，來自 [安裝指令碼](/zh-TW/setup#install-claude-code)、`claude install` 或 `claude update`。如需 `command not found`、PATH、權限和設定期間的 TLS 問題，請參閱 [疑難排解安裝和登入](/zh-TW/troubleshoot-install)。1121這些錯誤會在安裝或更新 Claude Code 時出現，來自 [安裝指令碼](/docs/zh-TW/setup#install-claude-code)、`claude install` 或 `claude update`。如需 `command not found`、PATH、權限和設定期間的 TLS 問題，請參閱 [疑難排解安裝和登入](/docs/zh-TW/troubleshoot-install)。

1122 1122

1123<h3 id="installation-was-killed-before-it-could-finish">1123<h3 id="installation-was-killed-before-it-could-finish">

1124 安裝在完成前被中止1124 安裝在完成前被中止

1136**該怎麼做：**1136**該怎麼做：**

1137 1137

1138* 停止其他程序以釋放記憶體，然後重新執行安裝程式1138* 停止其他程序以釋放記憶體，然後重新執行安裝程式

1139* 新增交換空間或移至更大的執行個體。請參閱 [在低記憶體 Linux 伺服器上安裝被中止](/zh-TW/troubleshoot-install#install-killed-on-low-memory-linux-servers) 以取得交換檔案命令。1139* 新增交換空間或移至更大的執行個體。請參閱 [在低記憶體 Linux 伺服器上安裝被中止](/docs/zh-TW/troubleshoot-install#install-killed-on-low-memory-linux-servers) 以取得交換檔案命令。

1140 1140

1141<h3 id="the-connection-dropped-while-downloading-the-update">1141<h3 id="the-connection-dropped-while-downloading-the-update">

1142 下載更新時連線中斷1142 下載更新時連線中斷

1143</h3>1143</h3>

1144 1144

1145當 `claude install`、`claude update` 或 [自動更新程式](/zh-TW/setup#auto-updates) 正在擷取 Claude Code 二進位檔案時，與下載伺服器的連線已關閉，且重試未能恢復。當連線中斷、傳輸停滯或下載的檔案未通過校驗和時，Claude Code 會重試下載，最多嘗試三次。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。{/* min-version: 2.1.202 */}在 v2.1.202 之前，單一連線中斷會立即導致下載失敗，並顯示裸錯誤 `aborted`，而不是重試。1145當 `claude install`、`claude update` 或 [自動更新程式](/docs/zh-TW/setup#auto-updates) 正在擷取 Claude Code 二進位檔案時，與下載伺服器的連線已關閉，且重試未能恢復。當連線中斷、傳輸停滯或下載的檔案未通過校驗和時，Claude Code 會重試下載，最多嘗試三次。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。在 v2.1.202 之前，單一連線中斷會立即導致下載失敗，並顯示裸錯誤 `aborted`，而不是重試。

1146 1146

1147```text theme={null}1147```text theme={null}

1148The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.1148The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

1157**該怎麼做：**1157**該怎麼做：**

1158 1158

1159* 再次執行 `claude update`。在網路狀況良好的情況下，下載通常在下次執行時成功。對於逾時訊息，請從更快或限制較少的網路重新執行。1159* 再次執行 `claude update`。在網路狀況良好的情況下，下載通常在下次執行時成功。對於逾時訊息，請從更快或限制較少的網路重新執行。

1160* 如果您的網路需要代理，請在執行安裝程式或 `claude update` 之前設定 `HTTPS_PROXY`。請參閱 [檢查網路連線](/zh-TW/troubleshoot-install#check-network-connectivity)。1160* 如果您的網路需要代理，請在執行安裝程式或 `claude update` 之前設定 `HTTPS_PROXY`。請參閱 [檢查網路連線](/docs/zh-TW/troubleshoot-install#check-network-connectivity)。

1161* 如果公司代理持續關閉傳輸，請要求您的網路團隊允許從 `downloads.claude.ai` 進行完整下載。請參閱 [網路存取需求](/zh-TW/network-config#network-access-requirements)。1161* 如果公司代理持續關閉傳輸，請要求您的網路團隊允許從 `downloads.claude.ai` 進行完整下載。請參閱 [網路存取需求](/docs/zh-TW/network-config#network-access-requirements)。

1162* 從您的 shell 執行 `claude doctor` 以進行安裝診斷1162* 從您的 shell 執行 `claude doctor` 以進行安裝診斷

1163 1163

1164<h2 id="command-line-errors">1164<h2 id="command-line-errors">

1171 \--bg 和 --print 之間的衝突1171 \--bg 和 --print 之間的衝突

1172</h3>1172</h3>

1173 1173

1174此訊息需要 Claude Code v2.1.198 或更新版本。您在同一個 `claude` 呼叫中結合了 `--bg` 與 `-p` 或 `--print`。`--bg` 啟動一個[背景工作階段](/zh-TW/agent-view#from-your-shell)，您稍後可以使用 `claude agents` 附加到該工作階段，而 `--print` 以[非互動模式](/zh-TW/headless)執行，永遠不會啟動 `claude agents` 附加到的互動工作階段。在 v2.1.198 之前，此組合會無聲地建立一個永遠無法附加的背景工作。1174此訊息需要 Claude Code v2.1.198 或更新版本。您在同一個 `claude` 呼叫中結合了 `--bg` 與 `-p` 或 `--print`。`--bg` 啟動一個[背景工作階段](/docs/zh-TW/agent-view#from-your-shell)，您稍後可以使用 `claude agents` 附加到該工作階段，而 `--print` 以[非互動模式](/docs/zh-TW/headless)執行，永遠不會啟動 `claude agents` 附加到的互動工作階段。在 v2.1.198 之前，此組合會無聲地建立一個永遠無法附加的背景工作。

1175 1175

1176```text theme={null}1176```text theme={null}

1177--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.1177--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

1179 1179

1180**該怎麼做：**1180**該怎麼做：**

1181 1181

1182* 移除 `-p` 或 `--print`。`--bg` 將提示作為其位置引數，所以 `claude --bg "<task>"` 是完整的命令。請參閱[從您的 shell 分派新代理](/zh-TW/agent-view#from-your-shell)。1182* 移除 `-p` 或 `--print`。`--bg` 將提示作為其位置引數，所以 `claude --bg "<task>"` 是完整的命令。請參閱[從您的 shell 分派新代理](/docs/zh-TW/agent-view#from-your-shell)。

1183* 若要以非互動模式執行提示並列印結果而不是建立背景工作階段，請移除 `--bg` 並執行 `claude -p "<task>"`1183* 若要以非互動模式執行提示並列印結果而不是建立背景工作階段，請移除 `--bg` 並執行 `claude -p "<task>"`

1184 1184

1185<h3 id="the-json-schema-value-is-not-a-valid-json-schema">1185<h3 id="the-json-schema-value-is-not-a-valid-json-schema">

1186 \--json-schema 值不是有效的 JSON Schema1186 \--json-schema 值不是有效的 JSON Schema

1187</h3>1187</h3>

1188 1188

1189您傳遞給[`--json-schema`](/zh-TW/cli-reference#cli-flags)的結構描述在[非互動模式](/zh-TW/headless#get-structured-output)中未能通過 JSON Schema 編譯，所以 `claude` 以代碼 1 結束而不是執行提示。在 v2.1.205 之前，無效的結構描述會產生無結構的輸出且沒有錯誤，任何使用 `format` 關鍵字的結構描述都被視為無效。1189您傳遞給[`--json-schema`](/docs/zh-TW/cli-reference#cli-flags)的結構描述在[非互動模式](/docs/zh-TW/headless#get-structured-output)中未能通過 JSON Schema 編譯，所以 `claude` 以代碼 1 結束而不是執行提示。在 v2.1.205 之前，無效的結構描述會產生無結構的輸出且沒有錯誤，任何使用 `format` 關鍵字的結構描述都被視為無效。

1190 1190

1191```text theme={null}1191```text theme={null}

1192Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values1192Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

1200 1200

1201* 修復診斷命名的結構描述部分，然後重新執行命令1201* 修復診斷命名的結構描述部分，然後重新執行命令

1202* 如果診斷是 `schema too large`，請減少結構描述的巢狀和 `$ref` 重複使用1202* 如果診斷是 `schema too large`，請減少結構描述的巢狀和 `$ref` 重複使用

1203* 請參閱[取得結構化輸出](/zh-TW/headless#get-structured-output)以取得有效的結構描述和命令1203* 請參閱[取得結構化輸出](/docs/zh-TW/headless#get-structured-output)以取得有效的結構描述和命令

1204 1204

1205<h3 id="could-not-import-a-server-from-claude-desktop">1205<h3 id="could-not-import-a-server-from-claude-desktop">

1206 無法從 Claude Desktop 匯入伺服器1206 無法從 Claude Desktop 匯入伺服器

1212Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.1212Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

1213```1213```

1214 1214

1215伺服器名稱之後的文字是原因。最常見的是名稱檢查：Claude Desktop 允許伺服器名稱中的字元（例如空格和句號），而 `claude mcp` 限制為字母、數字、連字號和底線。其他原因包括無法通過驗證的伺服器配置，以及被您組織的 [MCP 原則](/zh-TW/managed-mcp)阻止的伺服器。1215伺服器名稱之後的文字是原因。最常見的是名稱檢查：Claude Desktop 允許伺服器名稱中的字元（例如空格和句號），而 `claude mcp` 限制為字母、數字、連字號和底線。其他原因包括無法通過驗證的伺服器配置，以及被您組織的 [MCP 原則](/docs/zh-TW/managed-mcp)阻止的伺服器。

1216 1216

1217**該怎麼做：**1217**該怎麼做：**

1218 1218

1219* 在 `claude_desktop_config.json` 中重新命名伺服器，僅使用字母、數字、連字號和底線，然後再次執行 `claude mcp add-from-claude-desktop`1219* 在 `claude_desktop_config.json` 中重新命名伺服器，僅使用字母、數字、連字號和底線，然後再次執行 `claude mcp add-from-claude-desktop`

1220* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名稱下直接新增該伺服器。請參閱[從 Claude Desktop 匯入 MCP 伺服器](/zh-TW/mcp#import-mcp-servers-from-claude-desktop)。1220* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名稱下直接新增該伺服器。請參閱[從 Claude Desktop 匯入 MCP 伺服器](/docs/zh-TW/mcp#import-mcp-servers-from-claude-desktop)。

1221 1221

1222<h3 id="mcp-permission-prompt-tool-not-found">1222<h3 id="mcp-permission-prompt-tool-not-found">

1223 找不到 MCP 權限提示工具1223 找不到 MCP 權限提示工具

1224</h3>1224</h3>

1225 1225

1226您傳遞給 [`--permission-prompt-tool`](/zh-TW/cli-reference#cli-flags) 的工具在執行首次需要權限決定時不在連接的 MCP 工具中，原因可能是其伺服器從未連接，或者沒有連接的伺服器公開該名稱的工具。Claude Code 仍會傳送您的提示：[非互動](/zh-TW/headless)執行在第一個需要批准的工具呼叫時以此錯誤和結束代碼 1 結束，因此即使請求已發出也不會產生答案。在第一個提示之前，Claude Code 會等待最多由 [`MCP_TIMEOUT`](/zh-TW/env-vars) 設定的每個伺服器連接逾時 30 秒，以便該伺服器連接。{/* min-version: 2.1.206 */}在 v2.1.206 之前，啟動不會等待伺服器完成連接，所以啟動緩慢但健康的伺服器也會產生此錯誤。1226您傳遞給 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 的工具在執行首次需要權限決定時不在連接的 MCP 工具中，原因可能是其伺服器從未連接，或者沒有連接的伺服器公開該名稱的工具。Claude Code 仍會傳送您的提示：[非互動](/docs/zh-TW/headless)執行在第一個需要批准的工具呼叫時以此錯誤和結束代碼 1 結束，因此即使請求已發出也不會產生答案。在第一個提示之前，Claude Code 會等待最多由 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 設定的每個伺服器連接逾時 30 秒，以便該伺服器連接。在 v2.1.206 之前，啟動不會等待伺服器完成連接，所以啟動緩慢但健康的伺服器也會產生此錯誤。

1227 1227

1228```text theme={null}1228```text theme={null}

1229Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none1229Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

1235 1235

1236* 檢查伺服器是否啟動並保持連接：在同一目錄中執行 `claude mcp list`，並確認伺服器列為已連接1236* 檢查伺服器是否啟動並保持連接：在同一目錄中執行 `claude mcp list`，並確認伺服器列為已連接

1237* 確認工具名稱與伺服器公開的 `mcp__<server>__<tool>` 名稱相符1237* 確認工具名稱與伺服器公開的 `mcp__<server>__<tool>` 名稱相符

1238* 如果伺服器需要超過 30 秒才能啟動，請提高 [`MCP_TIMEOUT`](/zh-TW/env-vars)1238* 如果伺服器需要超過 30 秒才能啟動，請提高 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars)

1239 1239

1240<h2 id="plugin-errors">1240<h2 id="plugin-errors">

1241 外掛程式錯誤1241 外掛程式錯誤

1242</h2>1242</h2>

1243 1243

1244這些錯誤來自 [外掛程式](/zh-TW/plugins) 和 [市集](/zh-TW/plugin-marketplaces) 設定。對於不會產生此頁面上其中一則訊息的外掛程式問題，例如無法載入的市集 URL 或已安裝但未出現的外掛程式，請參閱 [外掛程式疑難排解](/zh-TW/discover-plugins#troubleshooting)。1244這些錯誤來自 [外掛程式](/docs/zh-TW/plugins) 和 [市集](/docs/zh-TW/plugin-marketplaces) 設定。對於不會產生此頁面上其中一則訊息的外掛程式問題，例如無法載入的市集 URL 或已安裝但未出現的外掛程式，請參閱 [外掛程式疑難排解](/docs/zh-TW/discover-plugins#troubleshooting)。

1245 1245

1246<h3 id="marketplace-is-registered-from-an-untrusted-source">1246<h3 id="marketplace-is-registered-from-an-untrusted-source">

1247 市集是從不受信任的來源註冊的1247 市集是從不受信任的來源註冊的

1248</h3>1248</h3>

1249 1249

1250市集是以 [為官方 Anthropic 市集保留的名稱](/zh-TW/plugin-marketplaces#marketplace-schema) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理市集時都會重新檢查保留的名稱，因此市集和從中安裝的外掛程式會停止載入。在 v2.1.205 之前，只有在新增市集時才會檢查名稱，因此在名稱變成保留名稱之前註冊的項目會繼續載入。1250市集是以 [為官方 Anthropic 市集保留的名稱](/docs/zh-TW/plugin-marketplaces#marketplace-schema) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理市集時都會重新檢查保留的名稱，因此市集和從中安裝的外掛程式會停止載入。在 v2.1.205 之前，只有在新增市集時才會檢查名稱，因此在名稱變成保留名稱之前註冊的項目會繼續載入。

1251 1251

1252```text theme={null}1252```text theme={null}

1253Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.1253Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

1257 1257

1258* 執行 `claude plugin marketplace remove <name>`，然後從官方 `github.com/anthropics` 儲存庫重新新增市集1258* 執行 `claude plugin marketplace remove <name>`，然後從官方 `github.com/anthropics` 儲存庫重新新增市集

1259* 如果您發佈了在名稱變成保留名稱之前使用該名稱的第三方市集，請重新命名它並要求使用者從您的來源重新新增它1259* 如果您發佈了在名稱變成保留名稱之前使用該名稱的第三方市集，請重新命名它並要求使用者從您的來源重新新增它

1260* 請參閱 [市集結構描述](/zh-TW/plugin-marketplaces#marketplace-schema) 下的保留名稱清單1260* 請參閱 [市集結構描述](/docs/zh-TW/plugin-marketplaces#marketplace-schema) 下的保留名稱清單

1261 1261

1262<h3 id="plugin-command-references-user-config">1262<h3 id="plugin-command-references-user-config">

1263 外掛程式命令在 shell 命令中參考 user\_config1263 外掛程式命令在 shell 命令中參考 user\_config

1264</h3>1264</h3>

1265 1265

1266外掛程式 hook、[monitor](/zh-TW/plugins-reference#monitors) 或 MCP [`headersHelper`](/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 命令參考 `${user_config.KEY}` [外掛程式選項](/zh-TW/plugins-reference#user-configuration)，而替換後的字串會被傳遞到 shell。設定的值包含 `$(...)` 、反引號或 `;` 會在該處作為程式碼執行，因此 Claude Code 拒絕啟動元件而不是替換該值。檢查在命令範本上執行，因此即使尚未設定任何值，錯誤也會出現。在 v2.1.207 之前，該值被替換到 shell 命令中。1266外掛程式 hook、[monitor](/docs/zh-TW/plugins-reference#monitors) 或 MCP [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 命令參考 `${user_config.KEY}` [外掛程式選項](/docs/zh-TW/plugins-reference#user-configuration)，而替換後的字串會被傳遞到 shell。設定的值包含 `$(...)` 、反引號或 `;` 會在該處作為程式碼執行，因此 Claude Code 拒絕啟動元件而不是替換該值。檢查在命令範本上執行，因此即使尚未設定任何值，錯誤也會出現。在 v2.1.207 之前，該值被替換到 shell 命令中。

1267 1267

1268措辭取決於哪個介面參考了該選項。shell 形式的 hook 會報告：1268措辭取決於哪個介面參考了該選項。shell 形式的 hook 會報告：

1269 1269

1285 1285

1286**該怎麼做：**1286**該怎麼做：**

1287 1287

1288* 對於 hook，新增 `args` 陣列使其以 [exec 形式](/zh-TW/hooks#exec-form-and-shell-form) 執行，其中每個 `${user_config.KEY}` 變成一個引數，中間沒有 shell。或者移除參考並在指令碼內讀取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數1288* 對於 hook，新增 `args` 陣列使其以 [exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form) 執行，其中每個 `${user_config.KEY}` 變成一個引數，中間沒有 shell。或者移除參考並在指令碼內讀取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數

1289* 對於 monitor，移除參考並讓 monitor 指令碼從設定檔讀取該值1289* 對於 monitor，移除參考並讓 monitor 指令碼從設定檔讀取該值

1290* 對於 `headersHelper`，將 `${user_config.KEY}` 移到伺服器的 `headers` 欄位（不會進行 shell 解析），或在 helper 指令碼內讀取該值1290* 對於 `headersHelper`，將 `${user_config.KEY}` 移到伺服器的 `headers` 欄位（不會進行 shell 解析），或在 helper 指令碼內讀取該值

1291 1291

1299 Agent would be spawned with zero tools1299 Agent would be spawned with zero tools

1300</h3>1300</h3>

1301 1301

1302[子代理的 `tools` 清單](/zh-TW/sub-agents#supported-frontmatter-fields)中沒有任何內容解析為工具，因此 Claude Code 拒絕啟動子代理，而不是啟動無法執行操作的代理。該訊息按它們未解析的原因對條目進行分組：未被識別的工具、不適用於子代理的工具，或已識別但與目前工作階段中的任何工具都不匹配。省略 `tools` 欄位永遠不會觸發此拒絕。MCP 伺服器模式（例如 `mcp__github__*`）不在豁免範圍內：當該伺服器沒有連接的工具時，啟動會被拒絕，並在不匹配的群組中顯示該模式。在 v2.1.208 之前，子代理會以零個工具啟動並返回空的或令人困惑的結果。1302[子代理的 `tools` 清單](/docs/zh-TW/sub-agents#supported-frontmatter-fields)中沒有任何內容解析為工具，因此 Claude Code 拒絕啟動子代理，而不是啟動無法執行操作的代理。該訊息按它們未解析的原因對條目進行分組：未被識別的工具、不適用於子代理的工具，或已識別但與目前工作階段中的任何工具都不匹配。省略 `tools` 欄位永遠不會觸發此拒絕。MCP 伺服器模式（例如 `mcp__github__*`）不在豁免範圍內：當該伺服器沒有連接的工具時，啟動會被拒絕，並在不匹配的群組中顯示該模式。在 v2.1.208 之前，子代理會以零個工具啟動並返回空的或令人困惑的結果。

1303 1303

1304```text theme={null}1304```text theme={null}

1305Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.1305Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.

1307 1307

1308**應該怎麼做：**1308**應該怎麼做：**

1309 1309

1310* 根據[子代理可用的工具](/zh-TW/sub-agents#available-tools)更正錯誤命名的每個條目1310* 根據[子代理可用的工具](/docs/zh-TW/sub-agents#available-tools)更正錯誤命名的每個條目

1311* 移除工作階段沒有的工具條目，例如來自未連接伺服器的 MCP 工具1311* 移除工作階段沒有的工具條目，例如來自未連接伺服器的 MCP 工具

1312* 若要讓子代理擁有父代理的所有工具，請刪除 `tools` 欄位，而不是列出工具1312* 若要讓子代理擁有父代理的所有工具，請刪除 `tools` 欄位，而不是列出工具

1313 1313

1315 File is covered by a Read deny rule1315 File is covered by a Read deny rule

1316</h3>1316</h3>

1317 1317

1318Edit 工具在與 [`Read` 拒絕規則](/zh-TW/permissions#read-and-edit)相符的路徑上被呼叫，包括在該路徑建立新檔案。編輯會重寫 Claude 必須能夠讀回的內容，因此呼叫在任何檔案存取之前被拒絕。該規則僅阻止 Edit 工具：Write 和 NotebookEdit 不受 `Read` 拒絕規則涵蓋。在 v2.1.208 之前，只有 `Edit` 拒絕規則會阻止編輯，而 `Read` 拒絕規則單獨不會。1318Edit 工具在與 [`Read` 拒絕規則](/docs/zh-TW/permissions#read-and-edit)相符的路徑上被呼叫，包括在該路徑建立新檔案。編輯會重寫 Claude 必須能夠讀回的內容，因此呼叫在任何檔案存取之前被拒絕。該規則僅阻止 Edit 工具：Write 和 NotebookEdit 不受 `Read` 拒絕規則涵蓋。在 v2.1.208 之前，只有 `Edit` 拒絕規則會阻止編輯，而 `Read` 拒絕規則單獨不會。

1319 1319

1320```text theme={null}1320```text theme={null}

1321File is covered by a Read deny rule in your permission settings and cannot be edited.1321File is covered by a Read deny rule in your permission settings and cannot be edited.

1323 1323

1324**應該怎麼做：**1324**應該怎麼做：**

1325 1325

1326* 如果 Claude 應該能夠編輯該檔案，請在 `/permissions` 或[設定](/zh-TW/settings#permission-settings)中移除或縮小 `Read` 拒絕規則1326* 如果 Claude 應該能夠編輯該檔案，請在 `/permissions` 或[設定](/docs/zh-TW/settings#permission-settings)中移除或縮小 `Read` 拒絕規則

1327* 如果檔案必須保持未觸及狀態，請保留該規則並為相同路徑新增 `Edit` 拒絕規則，以便 Write 和 NotebookEdit 工具也被阻止1327* 如果檔案必須保持未觸及狀態，請保留該規則並為相同路徑新增 `Edit` 拒絕規則，以便 Write 和 NotebookEdit 工具也被阻止

1328 1328

1329<h2 id="background-session-errors">1329<h2 id="background-session-errors">

1330 背景工作階段錯誤1330 背景工作階段錯誤

1331</h2>1331</h2>

1332 1332

1333[背景工作階段](/zh-TW/agent-view)在沒有互動式終端的情況下執行，因此需要終端的命令在那裡的行為會有所不同。這些訊息會出現在背景工作階段的文字記錄中，在代理檢視中或附加後。1333[背景工作階段](/docs/zh-TW/agent-view)在沒有互動式終端的情況下執行，因此需要終端的命令在那裡的行為會有所不同。這些訊息會出現在背景工作階段的文字記錄中，在代理檢視中或附加後。

1334 1334

1335<h3 id="commands-refused-in-a-background-session">1335<h3 id="commands-refused-in-a-background-session">

1336 背景工作階段中被拒絕的命令1336 背景工作階段中被拒絕的命令

1337</h3>1337</h3>

1338 1338

1339在背景工作階段中，開啟互動式對話框的命令會被拒絕，並顯示一條訊息，說明在該處有效的表單或告訴您從常規終端執行命令。`/install-github-app`、`/mcp` 設定清單和 MCP 伺服器選單中的驗證操作都以這種方式被拒絕。在 v2.1.208 之前，它們在背景工作階段內開啟了對話框。1339在背景工作階段中，開啟互動式對話框的命令會被拒絕，並顯示一條訊息，說明在該處有效的表單或告訴您從常規終端執行命令。`/install-github-app`、`/mcp` 設定清單和 MCP 伺服器選單中的驗證操作都以這種方式被拒絕。在 v2.1.208 之前，它們在背景工作階段內開啟了對話框。

1340{/* max-version: 2.1.208 */}在 v2.1.208 中，`/model` 選擇器也在背景工作階段中被拒絕，`/upgrade` 列印升級 URL 而不是開啟瀏覽器。1340在 v2.1.208 中，`/model` 選擇器也在背景工作階段中被拒絕，`/upgrade` 列印升級 URL 而不是開啟瀏覽器。

1341 1341

1342措辭會說明被拒絕的命令。`/mcp` 設定清單報告：1342措辭會說明被拒絕的命令。`/mcp` 設定清單報告：

1343 1343

1354 CLAUDE\_CODE\_PROCESS\_WRAPPER 啟動器錯誤1354 CLAUDE\_CODE\_PROCESS\_WRAPPER 啟動器錯誤

1355</h3>1355</h3>

1356 1356

1357[`CLAUDE_CODE_PROCESS_WRAPPER`](/zh-TW/corporate-launcher) 已設定，但其值無法使用，因此 Claude Code 拒絕啟動受影響的程序，而不是在沒有啟動器的情況下執行它。配置問題會報告為以變數名稱開頭並說明原因的訊息，例如：1357[`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/zh-TW/corporate-launcher) 已設定，但其值無法使用，因此 Claude Code 拒絕啟動受影響的程序，而不是在沒有啟動器的情況下執行它。配置問題會報告為以變數名稱開頭並說明原因的訊息，例如：

1358 1358

1359```text theme={null}1359```text theme={null}

1360CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file1360CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file

1364 1364

1365**該怎麼做：**1365**該怎麼做：**

1366 1366

1367* 將變數設定為可執行檔的絕對路徑，該路徑以呼叫 `exec "$@"` 結尾。請參閱[啟動器合約](/zh-TW/corporate-launcher#the-launcher-contract)以了解完整合約1367* 將變數設定為可執行檔的絕對路徑，該路徑以呼叫 `exec "$@"` 結尾。請參閱[啟動器合約](/docs/zh-TW/corporate-launcher#the-launcher-contract)以了解完整合約

1368* 檢查 `/status`，它在其 Self-exec 項目中顯示已解析的啟動命令，並在執行中的背景服務不符合時發出警告，或從 shell 執行 `claude daemon status`1368* 檢查 `/status`，它在其 Self-exec 項目中顯示已解析的啟動命令，並在執行中的背景服務不符合時發出警告，或從 shell 執行 `claude daemon status`

1369* 在修復 [settings](/zh-TW/corporate-launcher#set-up-the-launcher) 的 `env` 區塊中的值後，使用 `claude daemon stop --any` 重新啟動背景服務，以便下一次分派啟動包裝的服務1369* 在修復 [settings](/docs/zh-TW/corporate-launcher#set-up-the-launcher) 的 `env` 區塊中的值後，使用 `claude daemon stop --any` 重新啟動背景服務，以便下一次分派啟動包裝的服務

1370 1370

1371<h2 id="configuration-warnings">1371<h2 id="configuration-warnings">

1372 設定警告1372 設定警告

1378 工作區尚未受信任1378 工作區尚未受信任

1379</h3>1379</h3>

1380 1380

1381Claude Code 在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到了 `permissions.allow` 規則或 `permissions.additionalDirectories` 項目，但未應用它們，因為[來自專案設定的允許規則需要工作區信任](/zh-TW/permissions#project-allow-rules-and-workspace-trust)。訊息中的計數、設定名稱和檔案名稱會根據您的設定而變化。`deny` 和 `ask` 規則不受影響。1381Claude Code 在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到了 `permissions.allow` 規則或 `permissions.additionalDirectories` 項目，但未應用它們，因為[來自專案設定的允許規則需要工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)。訊息中的計數、設定名稱和檔案名稱會根據您的設定而變化。`deny` 和 `ask` 規則不受影響。

1382 1382

1383```text theme={null}1383```text theme={null}

1384Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.1384Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

1386 1386

1387**該怎麼做：**1387**該怎麼做：**

1388 1388

1389* 在目錄中執行 `claude` 並接受信任對話框。{/* min-version: 2.1.200 */}即使父目錄已經受信任，對話框仍會出現，列出被保留的規則，並讓您可以拒絕並繼續工作而不使用這些規則。在 v2.1.200 之前，在這種情況下不會出現對話框，因此無法在那裡完成此步驟。1389* 在目錄中執行 `claude` 並接受信任對話框。即使父目錄已經受信任，對話框仍會出現，列出被保留的規則，並讓您可以拒絕並繼續工作而不使用這些規則。在 v2.1.200 之前，在這種情況下不會出現對話框，因此無法在那裡完成此步驟。

1390* 在[非互動模式](/zh-TW/headless)中使用 `-p` 時不會顯示對話框。使用訊息列印的確切 `projects` 金鑰在 `~/.claude.json` 中設定 `hasTrustDialogAccepted` 項目。1390* 在[非互動模式](/docs/zh-TW/headless)中使用 `-p` 時不會顯示對話框。使用訊息列印的確切 `projects` 金鑰在 `~/.claude.json` 中設定 `hasTrustDialogAccepted` 項目。

1391* {/* min-version: 2.1.200 */}如果訊息命名 `.claude/settings.local.json` 且您在 git 儲存庫外或在主目錄中啟動 Claude Code，請更新至 v2.1.200 或更新版本。版本 2.1.196 至 2.1.199 在這些工作區中將您自己的 `.claude/settings.local.json` 視為儲存庫提供的。{/* min-version: 2.1.207 */}在 v2.1.207 及更新版本上，如果您尚未信任該資料夾，在 git 儲存庫外更新是不夠的：判斷資料夾是否在儲存庫內會執行 git，而 Claude Code 只在您接受信任對話框後才執行該檢查，因此請使用第一步。您的主目錄和任何其他[設定主目錄](/zh-TW/permissions#project-allow-rules-and-workspace-trust)都被豁免，不需要等待對話框。請參閱[專案允許規則和工作區信任](/zh-TW/permissions#project-allow-rules-and-workspace-trust)。1391* 如果訊息命名 `.claude/settings.local.json` 且您在 git 儲存庫外或在主目錄中啟動 Claude Code，請更新至 v2.1.200 或更新版本。版本 2.1.196 至 2.1.199 在這些工作區中將您自己的 `.claude/settings.local.json` 視為儲存庫提供的。在 v2.1.207 及更新版本上，如果您尚未信任該資料夾，在 git 儲存庫外更新是不夠的：判斷資料夾是否在儲存庫內會執行 git，而 Claude Code 只在您接受信任對話框後才執行該檢查，因此請使用第一步。您的主目錄和任何其他[設定主目錄](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)都被豁免，不需要等待對話框。請參閱[專案允許規則和工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)。

1392 1392

1393<h2 id="responses-seem-lower-quality-than-usual">1393<h2 id="responses-seem-lower-quality-than-usual">

1394 回應品質似乎低於預期1394 回應品質似乎低於預期

1396 1396

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

1398 1398

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

1400* Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用1400* Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用

1401* [自動模型備用](/zh-TW/model-config#automatic-model-fallback)在 Fable 5 上將工作階段移至預設 Opus 模型，並在文字記錄中顯示通知1401* [自動模型備用](/docs/zh-TW/model-config#automatic-model-fallback)在 Fable 5 上將工作階段移至預設 Opus 模型，並在文字記錄中顯示通知

1402 1402

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

1404 1404

1405首先檢查這些項目：1405首先檢查這些項目：

1406 1406

1407* **模型選擇**：執行 `/model` 以確認您使用的是預期的模型。先前的 `/model` 選擇或 `ANTHROPIC_MODEL` 環境變數可能使您使用的模型比預期的要小。1407* **模型選擇**：執行 `/model` 以確認您使用的是預期的模型。先前的 `/model` 選擇或 `ANTHROPIC_MODEL` 環境變數可能使您使用的模型比預期的要小。

1408* **努力程度**：執行 `/effort` 以檢查目前的推理級別，並針對困難的除錯或設計工作提高它。預設值因模型而異，因此在假設您低於最大值之前請先檢查。請參閱[調整努力程度](/zh-TW/model-config#adjust-effort-level)以了解每個模型的預設值和 `ultrathink` 快捷方式。1408* **努力程度**：執行 `/effort` 以檢查目前的推理級別，並針對困難的除錯或設計工作提高它。預設值因模型而異，因此在假設您低於最大值之前請先檢查。請參閱[調整努力程度](/docs/zh-TW/model-config#adjust-effort-level)以了解每個模型的預設值和 `ultrathink` 快捷方式。

1409* **上下文壓力**：執行 `/context` 以查看視窗的滿度。如果接近容量，請在自然中斷點執行 `/compact` 或執行 `/clear` 以重新開始。請參閱[探索上下文視窗](/zh-TW/context-window)以了解自動壓縮如何影響較早的輪次。1409* **上下文壓力**：執行 `/context` 以查看視窗的滿度。如果接近容量，請在自然中斷點執行 `/compact` 或執行 `/clear` 以重新開始。請參閱[探索上下文視窗](/docs/zh-TW/context-window)以了解自動壓縮如何影響較早的輪次。

1410* **過時的指示**：大型或過時的 `CLAUDE.md` 檔案和 MCP 工具定義會消耗上下文，並可能引導回應。{/* min-version: 2.1.205 */}`/doctor` 檢查會標記超大記憶體檔案和未使用的擴充功能，而 `/context` 會顯示 MCP 工具令牌使用情況。在 v2.1.205 之前，`/doctor` 開啟診斷畫面，標記超大記憶體檔案和子代理定義。1410* **過時的指示**：大型或過時的 `CLAUDE.md` 檔案和 MCP 工具定義會消耗上下文，並可能引導回應。`/doctor` 檢查會標記超大記憶體檔案和未使用的擴充功能，而 `/context` 會顯示 MCP 工具令牌使用情況。在 v2.1.205 之前，`/doctor` 開啟診斷畫面，標記超大記憶體檔案和子代理定義。

1411 1411

1412當回應出錯時，回溯通常比用更正回覆效果更好。按 Esc 兩次或執行 `/rewind` 以回到不良輪次之前，然後用更具體的內容重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後續答案錨定到它。請參閱[檢查點](/zh-TW/checkpointing)。1412當回應出錯時，回溯通常比用更正回覆效果更好。按 Esc 兩次或執行 `/rewind` 以回到不良輪次之前，然後用更具體的內容重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後續答案錨定到它。請參閱[檢查點](/docs/zh-TW/checkpointing)。

1413 1413

1414如果在檢查上述項目後品質仍然似乎不對，請執行 `/feedback` 並描述您預期的內容與您得到的內容。以這種方式提交的回饋包括對話文字記錄，這是 Anthropic 診斷真實回歸的最快方式。如果 `/feedback` 在您的環境中不可用，請參閱[報告錯誤](#report-an-error)。1414如果在檢查上述項目後品質仍然似乎不對，請執行 `/feedback` 並描述您預期的內容與您得到的內容。以這種方式提交的回饋包括對話文字記錄，這是 Anthropic 診斷真實回歸的最快方式。如果 `/feedback` 在您的環境中不可用，請參閱[報告錯誤](#report-an-error)。

1415 1415

1416如果 Claude 警告懷疑提示注入，或因懷疑注入而拒絕請求，而警告命名的文字是 Claude Code 自動添加到對話中的上下文而非檔案或網路內容，請執行 `claude update` 並重試。如果更新後警告重複出現，請[報告它](#report-an-error)而不是將標記的內容貼回提示中。{/* min-version: 2.1.201 */}在 v2.1.201 之前，Sonnet 5 以相同方式拒絕了某些請求。1416如果 Claude 警告懷疑提示注入，或因懷疑注入而拒絕請求，而警告命名的文字是 Claude Code 自動添加到對話中的上下文而非檔案或網路內容，請執行 `claude update` 並重試。如果更新後警告重複出現，請[報告它](#report-an-error)而不是將標記的內容貼回提示中。在 v2.1.201 之前，Sonnet 5 以相同方式拒絕了某些請求。

1417 1417

1418<h2 id="report-an-error">1418<h2 id="report-an-error">

1419 回報錯誤1419 回報錯誤

1421 1421

1422如需了解此頁面未涵蓋的元件錯誤，請參閱相關指南：1422如需了解此頁面未涵蓋的元件錯誤，請參閱相關指南：

1423 1423

1424* MCP 伺服器連線或驗證失敗：[MCP](/zh-TW/mcp)1424* MCP 伺服器連線或驗證失敗：[MCP](/docs/zh-TW/mcp)

1425* Hook 指令碼失敗或阻止了工具：[Debug hooks](/zh-TW/hooks#debug-hooks)1425* Hook 指令碼失敗或阻止了工具：[Debug hooks](/docs/zh-TW/hooks#debug-hooks)

1426* 安裝期間權限被拒或檔案系統錯誤：[Troubleshoot installation and login](/zh-TW/troubleshoot-install)1426* 安裝期間權限被拒或檔案系統錯誤：[Troubleshoot installation and login](/docs/zh-TW/troubleshoot-install)

1427 1427

1428如果此處未列出錯誤或建議的修正方法無法幫助：1428如果此處未列出錯誤或建議的修正方法無法幫助：

1429 1429

1430* 在 Claude Code 內執行 `/feedback` 以將文字記錄和說明傳送給 Anthropic。該命令也提供開啟預先填入的 GitHub issue 的選項。傳送給 Anthropic 需要[驗證](/zh-TW/authentication)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供者上，或當未設定 Anthropic 認證時，`/feedback` 會儲存本機封存，您可以改為傳送給您的 Anthropic 帳戶代表。1430* 在 Claude Code 內執行 `/feedback` 以將文字記錄和說明傳送給 Anthropic。該命令也提供開啟預先填入的 GitHub issue 的選項。傳送給 Anthropic 需要[驗證](/docs/zh-TW/authentication)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供者上，或當未設定 Anthropic 認證時，`/feedback` 會儲存本機封存，您可以改為傳送給您的 Anthropic 帳戶代表。

1431* 從您的 shell 執行 `claude doctor` 以進行安裝的唯讀診斷，或在 Claude Code 內執行 `/doctor` 檢查以尋找並修正設定問題1431* 從您的 shell 執行 `claude doctor` 以進行安裝的唯讀診斷，或在 Claude Code 內執行 `/doctor` 檢查以尋找並修正設定問題

1432* 檢查 [status.claude.com](https://status.claude.com) 以了解活躍的事件1432* 檢查 [status.claude.com](https://status.claude.com) 以了解活躍的事件

1433* 在 GitHub 上搜尋[現有 issue](https://github.com/anthropics/claude-code/issues)1433* 在 GitHub 上搜尋[現有 issue](https://github.com/anthropics/claude-code/issues)

fast-mode.md +11 −11

Details

32透過以下任一方式切換快速模式：32透過以下任一方式切換快速模式：

33 33

34* 輸入 `/fast` 並按 Tab 鍵切換開啟或關閉34* 輸入 `/fast` 並按 Tab 鍵切換開啟或關閉

~~35* 在您的[使用者設定檔案](/zh-TW/settings)中設定 `"fastMode": true`~~35* 在您的[使用者設定檔案](/docs/zh-TW/settings)中設定 `"fastMode": true`

36 36

37預設情況下，在互動式工作階段中開啟的快速模式會在工作階段之間保持。{/* min-version: 2.1.205 */}在[非互動式模式](/zh-TW/headless)中，使用 `-p` 旗標時，`/fast` 僅在使用快速模式在其 [`--settings`](/zh-TW/cli-reference#cli-flags) 值中啟動的工作階段中運作，例如 `claude -p --settings '{"fastMode": true}'`；切換則僅適用於該工作階段，不會儲存為您的預設值，在任何其他非互動式工作階段中，該命令會報告快速模式不可用。您可以配置快速模式在每個工作階段重設。詳見[要求每個工作階段選擇加入](#require-per-session-opt-in)以了解詳情。37預設情況下，在互動式工作階段中開啟的快速模式會在工作階段之間保持。在[非互動式模式](/docs/zh-TW/headless)中，使用 `-p` 旗標時，`/fast` 僅在使用快速模式在其 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 值中啟動的工作階段中運作，例如 `claude -p --settings '{"fastMode": true}'`；切換則僅適用於該工作階段，不會儲存為您的預設值，在任何其他非互動式工作階段中，該命令會報告快速模式不可用。您可以配置快速模式在每個工作階段重設。詳見[要求每個工作階段選擇加入](#require-per-session-opt-in)以了解詳情。

38 38

39為了獲得最佳成本效率，在工作階段開始時啟用快速模式，而不是在對話中途切換。詳見[了解成本權衡](#understand-the-cost-tradeoff)以了解詳情。39為了獲得最佳成本效率，在工作階段開始時啟用快速模式，而不是在對話中途切換。詳見[了解成本權衡](#understand-the-cost-tradeoff)以了解詳情。

40 40

47 47

48當您再次使用 `/fast` 關閉快速模式時，您仍保持在 Opus 上。模型不會還原到您之前的模型。要切換到不同的模型，請使用 `/model`。48當您再次使用 `/fast` 關閉快速模式時，您仍保持在 Opus 上。模型不會還原到您之前的模型。要切換到不同的模型，請使用 `/model`。

49 49

50切換到不支援快速模式的模型會關閉快速模式。{/* min-version: 2.1.208 */}切換回支援的 Opus 模型時，當您儲存的快速模式偏好設定為開啟時，它會再次開啟，這與新工作階段預設啟動的偏好設定相同。配置了[每個工作階段選擇加入](#require-per-session-opt-in)時，切換回去不會再次開啟快速模式；執行 `/fast` 以重新啟用它。對於儲存偏好設定為關閉的工作階段，快速模式永遠不會開啟，`↯` 圖示和「Fast mode ON」確認會在它啟動時出現。在 v2.1.208 之前，快速模式在您切換回去後會保持關閉，直到您再次執行 `/fast`。50切換到不支援快速模式的模型會關閉快速模式。切換回支援的 Opus 模型時，當您儲存的快速模式偏好設定為開啟時，它會再次開啟，這與新工作階段預設啟動的偏好設定相同。配置了[每個工作階段選擇加入](#require-per-session-opt-in)時，切換回去不會再次開啟快速模式；執行 `/fast` 以重新啟用它。對於儲存偏好設定為關閉的工作階段，快速模式永遠不會開啟，`↯` 圖示和「Fast mode ON」確認會在它啟動時出現。在 v2.1.208 之前，快速模式在您切換回去後會保持關閉，直到您再次執行 `/fast`。

51 51

52Opus 4.8 是 Claude Code v2.1.154 及更新版本中的快速模式預設值。在 v2.1.142 至 v2.1.153 版本上，快速模式預設為 Opus 4.7。52Opus 4.8 是 Claude Code v2.1.154 及更新版本中的快速模式預設值。在 v2.1.142 至 v2.1.153 版本上，快速模式預設為 Opus 4.7。

53 53

64 64

65快速模式定價在整個 1M token 上下文視窗中是固定的。如需與標準 Opus 費率進行比較，請參閱 [Claude 定價參考](https://platform.claude.com/docs/zh-TW/about-claude/pricing)。65快速模式定價在整個 1M token 上下文視窗中是固定的。如需與標準 Opus 費率進行比較，請參閱 [Claude 定價參考](https://platform.claude.com/docs/zh-TW/about-claude/pricing)。

66 66

67當您在對話中首次啟用快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。對話進行得越深入，成本就越高，因此從一開始就啟用快速模式會更便宜。成本每個對話只適用一次，因此稍後關閉並再次開啟快速模式不會重複計費。如需了解機制，請參閱[快速模式如何與 prompt cache 互動](/zh-TW/prompt-caching#turning-on-fast-mode)。67當您在對話中首次啟用快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。對話進行得越深入，成本就越高，因此從一開始就啟用快速模式會更便宜。成本每個對話只適用一次，因此稍後關閉並再次開啟快速模式不會重複計費。如需了解機制，請參閱[快速模式如何與 prompt cache 互動](/docs/zh-TW/prompt-caching#turning-on-fast-mode)。

68 68

69<h2 id="decide-when-to-use-fast-mode">69<h2 id="decide-when-to-use-fast-mode">

70 決定何時使用快速模式70 決定何時使用快速模式

93| **快速模式** | 相同的模型品質、更低的延遲、更高的成本 |93| **快速模式** | 相同的模型品質、更低的延遲、更高的成本 |

94| **較低的努力等級** | 較少的思考時間、更快的回應、複雜任務上可能品質較低 |94| **較低的努力等級** | 較少的思考時間、更快的回應、複雜任務上可能品質較低 |

95 95

~~96您可以結合兩者：在直接任務上使用快速模式搭配較低的[努力等級](/zh-TW/model-config#adjust-effort-level)以獲得最大速度。~~96您可以結合兩者：在直接任務上使用快速模式搭配較低的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)以獲得最大速度。

97 97

98<h2 id="requirements">98<h2 id="requirements">

99 要求99 要求

111* **Team 和 Enterprise 的管理員啟用**：快速模式預設對 Team 和 Enterprise 組織禁用。管理員必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。111* **Team 和 Enterprise 的管理員啟用**：快速模式預設對 Team 和 Enterprise 組織禁用。管理員必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。

112 112

113<Note>113<Note>

114 如果您的管理員尚未為您的組織啟用快速模式，`/fast` 命令將顯示「Fast mode has been disabled by your organization.」如果您組織的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單排除了快速模式 Opus 模型，`/fast` 會被拒絕，顯示「is not in your organization's allowed models」。例外情況是已在允許的 Opus 模型上執行的工作階段，該模型支援快速模式：`/fast` 則在您目前的模型上啟用快速模式，而不是切換模型。114 如果您的管理員尚未為您的組織啟用快速模式，`/fast` 命令將顯示「Fast mode has been disabled by your organization.」如果您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除了快速模式 Opus 模型，`/fast` 會被拒絕，顯示「is not in your organization's allowed models」。例外情況是已在允許的 Opus 模型上執行的工作階段，該模型支援快速模式：`/fast` 則在您目前的模型上啟用快速模式，而不是切換模型。

115</Note>115</Note>

116 116

117<h3 id="enable-fast-mode-for-your-organization">117<h3 id="enable-fast-mode-for-your-organization">

123* **Console**（API 客戶）：管理員在 [Claude Code 偏好設定](https://platform.claude.com/claude-code/preferences)中啟用它123* **Console**（API 客戶）：管理員在 [Claude Code 偏好設定](https://platform.claude.com/claude-code/preferences)中啟用它

124* **Claude AI**（Team 和 Enterprise）：管理員在 [管理員設定 > Claude Code](https://claude.ai/admin-settings/claude-code)中啟用它124* **Claude AI**（Team 和 Enterprise）：管理員在 [管理員設定 > Claude Code](https://claude.ai/admin-settings/claude-code)中啟用它

125 125

126另一個完全禁用快速模式的選項是設定 `CLAUDE_CODE_DISABLE_FAST_MODE=1`。詳見[環境變數](/zh-TW/env-vars)。126另一個完全禁用快速模式的選項是設定 `CLAUDE_CODE_DISABLE_FAST_MODE=1`。詳見[環境變數](/docs/zh-TW/env-vars)。

127 127

128<h3 id="require-per-session-opt-in">128<h3 id="require-per-session-opt-in">

129 要求每個工作階段選擇加入129 要求每個工作階段選擇加入

130</h3>130</h3>

131 131

132預設情況下，快速模式在工作階段之間保持：使用者在互動式工作階段中啟用的快速模式會在未來工作階段中保持開啟。若要變更此行為，在任何[設定檔](/zh-TW/settings#settings-files)中將 `fastModePerSessionOptIn` 設定為 `true`，這會導致每個工作階段以快速模式關閉開始，並要求使用者使用 `/fast` 明確啟用它。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 方案上的擁有者可以透過[伺服器受管設定](/zh-TW/server-managed-settings)在組織範圍內部署它。132預設情況下，快速模式在工作階段之間保持：使用者在互動式工作階段中啟用的快速模式會在未來工作階段中保持開啟。若要變更此行為，在任何[設定檔](/docs/zh-TW/settings#settings-files)中將 `fastModePerSessionOptIn` 設定為 `true`，這會導致每個工作階段以快速模式關閉開始，並要求使用者使用 `/fast` 明確啟用它。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 方案上的擁有者可以透過[伺服器受管設定](/docs/zh-TW/server-managed-settings)在組織範圍內部署它。

133 133

134```json theme={null}134```json theme={null}

135{135{

168 另請參閱168 另請參閱

169</h2>169</h2>

170 170

171* [模型配置](/zh-TW/model-config)：切換模型和調整努力等級171* [模型配置](/docs/zh-TW/model-config)：切換模型和調整努力等級

172* [有效管理成本](/zh-TW/costs)：追蹤 token 使用量並降低成本172* [有效管理成本](/docs/zh-TW/costs)：追蹤 token 使用量並降低成本

173* [狀態行配置](/zh-TW/statusline)：顯示模型和上下文資訊173* [狀態行配置](/docs/zh-TW/statusline)：顯示模型和上下文資訊

feature-availability.md +79 −79

Details

6 6

7> 比較 Claude Code 功能在 Anthropic 訂閱計畫、Anthropic Console、Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 和 Microsoft Foundry 中的可用性。7> 比較 Claude Code 功能在 Anthropic 訂閱計畫、Anthropic Console、Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 和 Microsoft Foundry 中的可用性。

8 8

9Claude Code CLI 和所有在本地執行的功能在每個提供者上的運作方式完全相同。如需每個提供者的設定說明，請參閱[企業部署概述](/zh-TW/third-party-integrations)。若要直接跳到您的提供者上缺少的功能，請參閱[按提供者摘要](#summary-by-provider)標籤。9Claude Code CLI 和所有在本地執行的功能在每個提供者上的運作方式完全相同。如需每個提供者的設定說明，請參閱[企業部署概述](/docs/zh-TW/third-party-integrations)。若要直接跳到您的提供者上缺少的功能，請參閱[按提供者摘要](#summary-by-provider)標籤。

10 10

11在下表中，✓ 表示可用，✗ 表示不可用，「請參閱備註」連結到部分支援的註腳。✓ 後面的限定詞會將可用性縮小到該子集，「管理員啟用」表示該功能處於關閉狀態，直到組織管理員將其開啟。11在下表中，✓ 表示可用，✗ 表示不可用，「請參閱備註」連結到部分支援的註腳。✓ 後面的限定詞會將可用性縮小到該子集，「管理員啟用」表示該功能處於關閉狀態，直到組織管理員將其開啟。

12 12

18 18

19* **Claude 訂閱**：您使用 claude.ai 帳戶登入 Pro、Max、Team 或 Enterprise 計畫19* **Claude 訂閱**：您使用 claude.ai 帳戶登入 Pro、Max、Team 或 Enterprise 計畫

20* **Anthropic Console**：您使用 Anthropic API 金鑰進行驗證20* **Anthropic Console**：您使用 Anthropic API 金鑰進行驗證

21* **Amazon Bedrock**：您使用 Amazon Bedrock 模型目錄中的 Claude 模型並設定 `CLAUDE_CODE_USE_BEDROCK`。[Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)（`CLAUDE_CODE_USE_MANTLE`）由此欄涵蓋21* **Amazon Bedrock**：您使用 Amazon Bedrock 模型目錄中的 Claude 模型並設定 `CLAUDE_CODE_USE_BEDROCK`。[Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)（`CLAUDE_CODE_USE_MANTLE`）由此欄涵蓋

22* **AWS 上的 Claude Platform**：您透過 AWS Marketplace 購買了 Claude，但呼叫 Anthropic API，並設定 `CLAUDE_CODE_USE_ANTHROPIC_AWS`22* **AWS 上的 Claude Platform**：您透過 AWS Marketplace 購買了 Claude，但呼叫 Anthropic API，並設定 `CLAUDE_CODE_USE_ANTHROPIC_AWS`

23* **Google Cloud's Agent Platform**：由 Google 營運；您設定 `CLAUDE_CODE_USE_VERTEX`23* **Google Cloud's Agent Platform**：由 Google 營運；您設定 `CLAUDE_CODE_USE_VERTEX`

24* **Microsoft Foundry**：由 Anthropic 在 Azure 上營運；您設定 `CLAUDE_CODE_USE_FOUNDRY`24* **Microsoft Foundry**：由 Anthropic 在 Azure 上營運；您設定 `CLAUDE_CODE_USE_FOUNDRY`

29 29

30這些在每個提供者上的運作方式完全相同：30這些在每個提供者上的運作方式完全相同：

31 31

~~32* [CLI](/zh-TW/quickstart) 和 [Agent SDK](/zh-TW/agent-sdk/overview)~~32* [CLI](/docs/zh-TW/quickstart) 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview)

~~33* [VS Code](/zh-TW/vs-code) 和 [JetBrains](/zh-TW/jetbrains) 擴充功能~~33* [VS Code](/docs/zh-TW/vs-code) 和 [JetBrains](/docs/zh-TW/jetbrains) 擴充功能

~~34* [Subagents](/zh-TW/sub-agents)、[hooks](/zh-TW/hooks-guide)、[commands](/zh-TW/commands) 和 [skills](/zh-TW/skills)~~34* [Subagents](/docs/zh-TW/sub-agents)、[hooks](/docs/zh-TW/hooks-guide)、[commands](/docs/zh-TW/commands) 和 [skills](/docs/zh-TW/skills)

~~35* [CLAUDE.md 記憶](/zh-TW/memory)、[plugins](/zh-TW/plugins) 和 [MCP servers](/zh-TW/mcp)~~35* [CLAUDE.md 記憶](/docs/zh-TW/memory)、[plugins](/docs/zh-TW/plugins) 和 [MCP servers](/docs/zh-TW/mcp)

~~36* [Checkpoints](/zh-TW/checkpointing)、[sandboxing](/zh-TW/sandboxing) 和 [Workflows](/zh-TW/workflows)~~36* [Checkpoints](/docs/zh-TW/checkpointing)、[sandboxing](/docs/zh-TW/sandboxing) 和 [Workflows](/docs/zh-TW/workflows)

~~37* [OpenTelemetry 指標](/zh-TW/monitoring-usage)和[受管設定檔](/zh-TW/settings#settings-files)~~37* [OpenTelemetry 指標](/docs/zh-TW/monitoring-usage)和[受管設定檔](/docs/zh-TW/settings#settings-files)

38 38

39這三個功能有提供者特定的差異：39這三個功能有提供者特定的差異：

40 40

41* **MCP servers**：[來自 claude.ai 的連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)僅在您的 claude.ai 訂閱是作用中驗證方法時才會載入，而[工具搜尋](/zh-TW/mcp#configure-tool-search)在 Google Cloud's Agent Platform 上預設為關閉，當 `ANTHROPIC_BASE_URL` 指向非第一方主機時也是如此41* **MCP servers**：[來自 claude.ai 的連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)僅在您的 claude.ai 訂閱是作用中驗證方法時才會載入，而[工具搜尋](/docs/zh-TW/mcp#configure-tool-search)在 Google Cloud's Agent Platform 上預設為關閉，當 `ANTHROPIC_BASE_URL` 指向非第一方主機時也是如此

42* **Subagents**：內建的 [Explore subagent](/zh-TW/sub-agents#built-in-subagents) 在 Claude API 上將其繼承的模型上限設為 Opus，在任何其他提供者（包括 AWS 上的 Claude Platform）上直接繼承主要對話的模型42* **Subagents**：內建的 [Explore subagent](/docs/zh-TW/sub-agents#built-in-subagents) 在 Claude API 上將其繼承的模型上限設為 Opus，在任何其他提供者（包括 AWS 上的 Claude Platform）上直接繼承主要對話的模型

43* **[Commands](/zh-TW/commands#all-commands)**：`/design-sync` 和 `/radio` 在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上不可用，而 `/voice` 需要 claude.ai 帳戶43* **[Commands](/docs/zh-TW/commands#all-commands)**：`/design-sync` 和 `/radio` 在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上不可用，而 `/voice` 需要 claude.ai 帳戶

44 44

45<h3 id="features-that-require-a-claude-subscription">45<h3 id="features-that-require-a-claude-subscription">

46 需要 Claude 訂閱的功能46 需要 Claude 訂閱的功能

48 48

49這些需要使用 claude.ai 帳戶登入，無法透過 Anthropic Console API 金鑰或第三方提供者存取：49這些需要使用 claude.ai 帳戶登入，無法透過 Anthropic Console API 金鑰或第三方提供者存取：

50 50

~~51* [網頁上的 Claude Code](/zh-TW/claude-code-on-the-web)、行動裝置上的 Claude Code 和 [Slack 中的 Claude Code](/zh-TW/slack)~~51* [網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web)、行動裝置上的 Claude Code 和 [Slack 中的 Claude Code](/docs/zh-TW/slack)

~~52* [Claude Code Desktop](/zh-TW/desktop)~~52* [Claude Code Desktop](/docs/zh-TW/desktop)

~~53* [Routines](/zh-TW/routines)（`/schedule`）~~53* [Routines](/docs/zh-TW/routines)（`/schedule`）

~~54* [Ultraplan](/zh-TW/ultraplan) 和 [Ultrareview](/zh-TW/ultrareview)~~54* [Ultraplan](/docs/zh-TW/ultraplan) 和 [Ultrareview](/docs/zh-TW/ultrareview)

~~55* [Code Review](/zh-TW/code-review)：Team 和 Enterprise 計畫~~55* [Code Review](/docs/zh-TW/code-review)：Team 和 Enterprise 計畫

~~56* [Remote Control](/zh-TW/remote-control)~~56* [Remote Control](/docs/zh-TW/remote-control)

~~57* [Chrome 擴充功能](/zh-TW/chrome)~~57* [Chrome 擴充功能](/docs/zh-TW/chrome)

~~58* [Computer use](/zh-TW/computer-use)：Pro 和 Max 計畫~~58* [Computer use](/docs/zh-TW/computer-use)：Pro 和 Max 計畫

~~59* [Artifacts](/zh-TW/artifacts)：Pro、Max、Team 和 Enterprise 計畫~~59* [Artifacts](/docs/zh-TW/artifacts)：Pro、Max、Team 和 Enterprise 計畫

~~60* [Voice dictation](/zh-TW/voice-dictation)~~60* [Voice dictation](/docs/zh-TW/voice-dictation)

61 61

62Desktop 是部分例外：[閘道路由可以在應用程式中或由管理員配置](/zh-TW/llm-gateway-connect#desktop-app)、Enterprise 部署可以透過[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)將 Desktop 路由到 Google Cloud's Agent Platform 或閘道提供者，而[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤。如需這些功能的按計畫可用性，請參閱[按訂閱計畫的可用性](#availability-by-subscription-plan)。62Desktop 是部分例外：[閘道路由可以在應用程式中或由管理員配置](/docs/zh-TW/llm-gateway-connect#desktop-app)、Enterprise 部署可以透過[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)將 Desktop 路由到 Google Cloud's Agent Platform 或閘道提供者，而[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤。如需這些功能的按計畫可用性，請參閱[按訂閱計畫的可用性](#availability-by-subscription-plan)。

63 63

64<h3 id="cli-capabilities-that-vary-by-provider">64<h3 id="cli-capabilities-that-vary-by-provider">

65 按提供者變化的 CLI 功能65 按提供者變化的 CLI 功能

82 82

83 <tbody>83 <tbody>

84 <tr>84 <tr>

~~85 <td>[Web search](/zh-TW/tools-reference#websearch-tool-behavior)</td>~~85 <td>[Web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)</td>

86 <td>✓</td>86 <td>✓</td>

87 <td>✓</td>87 <td>✓</td>

88 <td>✗</td>88 <td>✗</td>

92 </tr>92 </tr>

93 93

94 <tr>94 <tr>

~~95 <td>[Fast mode](/zh-TW/fast-mode)</td>~~95 <td>[Fast mode](/docs/zh-TW/fast-mode)</td>

96 <td>✓</td>96 <td>✓</td>

97 <td>✓</td>97 <td>✓</td>

98 <td>✗</td>98 <td>✗</td>

102 </tr>102 </tr>

103 103

104 <tr>104 <tr>

105 <td>[Auto mode](/zh-TW/auto-mode-config)</td>105 <td>[Auto mode](/docs/zh-TW/auto-mode-config)</td>

106 <td>✓</td>106 <td>✓</td>

107 <td>✓</td>107 <td>✓</td>

108 <td>請參閱備註 <sup><a href="#fn2">2</a></sup></td>108 <td>請參閱備註 <sup><a href="#fn2">2</a></sup></td>

112 </tr>112 </tr>

113 113

114 <tr>114 <tr>

115 <td>[Advisor](/zh-TW/advisor)</td>115 <td>[Advisor](/docs/zh-TW/advisor)</td>

116 <td>✓</td>116 <td>✓</td>

117 <td>✓</td>117 <td>✓</td>

118 <td>✗</td>118 <td>✗</td>

122 </tr>122 </tr>

123 123

124 <tr>124 <tr>

125 <td>[Channels](/zh-TW/channels)</td>125 <td>[Channels](/docs/zh-TW/channels)</td>

126 <td>✓</td>126 <td>✓</td>

127 <td>✓</td>127 <td>✓</td>

128 <td>✗</td>128 <td>✗</td>

132 </tr>132 </tr>

133 133

134 <tr>134 <tr>

135 <td>[`/loop` 排程任務](/zh-TW/scheduled-tasks)</td>135 <td>[`/loop` 排程任務](/docs/zh-TW/scheduled-tasks)</td>

136 <td>✓</td>136 <td>✓</td>

137 <td>✓</td>137 <td>✓</td>

138 <td>請參閱備註 <sup><a href="#fn3">3</a></sup></td>138 <td>請參閱備註 <sup><a href="#fn3">3</a></sup></td>

142 </tr>142 </tr>

143 143

144 <tr>144 <tr>

145 <td>[GitHub Actions](/zh-TW/github-actions) 和 [GitLab CI/CD](/zh-TW/gitlab-ci-cd)</td>145 <td>[GitHub Actions](/docs/zh-TW/github-actions) 和 [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)</td>

146 <td>✓</td>146 <td>✓</td>

147 <td>✓</td>147 <td>✓</td>

148 <td>✓</td>148 <td>✓</td>

174 174

175 <tbody>175 <tbody>

176 <tr>176 <tr>

177 <td>[分析儀表板和 API](/zh-TW/analytics)</td>177 <td>[分析儀表板和 API](/docs/zh-TW/analytics)</td>

178 <td>✓ (儀表板：Team 和 Enterprise；API：Enterprise)</td>178 <td>✓ (儀表板：Team 和 Enterprise；API：Enterprise)</td>

179 <td>✓ <sup><a href="#fn5">5</a></sup></td>179 <td>✓ <sup><a href="#fn5">5</a></sup></td>

180 <td>✗</td>180 <td>✗</td>

184 </tr>184 </tr>

185 185

186 <tr>186 <tr>

187 <td>[伺服器管理的設定](/zh-TW/server-managed-settings)</td>187 <td>[伺服器管理的設定](/docs/zh-TW/server-managed-settings)</td>

188 <td>✓ (Team 和 Enterprise)</td>188 <td>✓ (Team 和 Enterprise)</td>

189 <td>✓ (Team 和 Enterprise)</td>189 <td>✓ (Team 和 Enterprise)</td>

190 <td>✗</td>190 <td>✗</td>

194 </tr>194 </tr>

195 195

196 <tr>196 <tr>

197 <td>[Zero Data Retention](/zh-TW/zero-data-retention)</td>197 <td>[Zero Data Retention](/docs/zh-TW/zero-data-retention)</td>

198 <td>✓ (符合條件的 Enterprise 帳戶)</td>198 <td>✓ (符合條件的 Enterprise 帳戶)</td>

199 <td>✓ (符合條件的帳戶)</td>199 <td>✓ (符合條件的帳戶)</td>

200 <td>請參閱備註 <sup><a href="#fn4">4</a></sup></td>200 <td>請參閱備註 <sup><a href="#fn4">4</a></sup></td>

206</table>206</table>

207 207

208<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 適用於 Claude 4 模型及更新版本。<br />208<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 適用於 Claude 4 模型及更新版本。<br />

209<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 在這些提供者上，auto mode 僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。請參閱 [Auto mode 配置](/zh-TW/auto-mode-config)。{/* min-version: 2.1.207 */}在 v2.1.158 到 v2.1.206 中，這些提供者上的 auto mode 也需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了此要求。<br />209<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 在這些提供者上，auto mode 僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。請參閱 [Auto mode 配置](/docs/zh-TW/auto-mode-config)。在 v2.1.158 到 v2.1.206 中，這些提供者上的 auto mode 也需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了此要求。<br />

210<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 明確的間隔（例如 `/loop every 2 hours`）在每個提供者上都有效。在 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud's Agent Platform 和 Microsoft Foundry 上，`/loop` 無法選擇自己的間隔或提供預設維護提示，因此沒有間隔的提示每 10 分鐘執行一次，沒有引數的 `/loop` 顯示使用訊息。請參閱[排程任務](/zh-TW/scheduled-tasks)。<br />210<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 明確的間隔（例如 `/loop every 2 hours`）在每個提供者上都有效。在 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud's Agent Platform 和 Microsoft Foundry 上，`/loop` 無法選擇自己的間隔或提供預設維護提示，因此沒有間隔的提示每 10 分鐘執行一次，沒有引數的 `/loop` 顯示使用訊息。請參閱[排程任務](/docs/zh-TW/scheduled-tasks)。<br />

211<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 受您與雲端提供者的協議約束。<br />211<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 受您與雲端提供者的協議約束。<br />

212<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 僅限儀表板和 API。[貢獻指標](/zh-TW/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 組織。212<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 僅限儀表板和 API。[貢獻指標](/docs/zh-TW/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 組織。

213 213

214<Note>214<Note>

215 如果您透過 [LLM 閘道](/zh-TW/llm-gateway)進行驗證，功能可用性與閘道轉發到的基礎提供者相符。某些僅限 Anthropic 的功能（例如 [Advisor](/zh-TW/advisor)）只有在閘道將請求完整轉發到 Anthropic API 時才能運作。215 如果您透過 [LLM 閘道](/docs/zh-TW/llm-gateway)進行驗證，功能可用性與閘道轉發到的基礎提供者相符。某些僅限 Anthropic 的功能（例如 [Advisor](/docs/zh-TW/advisor)）只有在閘道將請求完整轉發到 Anthropic API 時才能運作。

216</Note>216</Note>

217 217

218<h3 id="summary-by-provider">218<h3 id="summary-by-provider">

219 按提供者摘要219 按提供者摘要

220</h3>220</h3>

221 221

222每個標籤列出該提供者上不可用或部分支援的功能，以及存在替代方案的地方。未列出的所有功能在 Claude 訂閱上的運作方式相同，除了上述[每個提供者上都可用的功能](#features-available-on-every-provider)中提到的提供者特定差異。在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上，向 Anthropic 的錯誤報告和遙測預設為關閉。請參閱[按 API 提供者的預設行為](/zh-TW/data-usage#default-behaviors-by-api-provider)，了解哪些流量仍會到達 Anthropic 以及如何選擇退出。222每個標籤列出該提供者上不可用或部分支援的功能，以及存在替代方案的地方。未列出的所有功能在 Claude 訂閱上的運作方式相同，除了上述[每個提供者上都可用的功能](#features-available-on-every-provider)中提到的提供者特定差異。在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上，向 Anthropic 的錯誤報告和遙測預設為關閉。請參閱[按 API 提供者的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider)，了解哪些流量仍會到達 Anthropic 以及如何選擇退出。

223 223

224<Tabs>224<Tabs>

225 <Tab title="Amazon Bedrock">225 <Tab title="Amazon Bedrock">

226 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [web search](/zh-TW/tools-reference#websearch-tool-behavior)、[fast mode](/zh-TW/fast-mode)、[Advisor](/zh-TW/advisor)、[Channels](/zh-TW/channels)、[分析儀表板](/zh-TW/analytics)、[伺服器管理的設定](/zh-TW/server-managed-settings) 和 [`/design-sync` 和 `/radio` 命令](/zh-TW/commands#all-commands)。226 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)、[fast mode](/docs/zh-TW/fast-mode)、[Advisor](/docs/zh-TW/advisor)、[Channels](/docs/zh-TW/channels)、[分析儀表板](/docs/zh-TW/analytics)、[伺服器管理的設定](/docs/zh-TW/server-managed-settings) 和 [`/design-sync` 和 `/radio` 命令](/docs/zh-TW/commands#all-commands)。

227 227

228 **部分支援：**228 **部分支援：**

229 229

230 * [Desktop](/zh-TW/desktop)：僅透過[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)230 * [Desktop](/docs/zh-TW/desktop)：僅透過[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)

231 * [Auto mode](/zh-TW/auto-mode-config)：Sonnet 5、Opus 4.7 和 Opus 4.8 僅限231 * [Auto mode](/docs/zh-TW/auto-mode-config)：Sonnet 5、Opus 4.7 和 Opus 4.8 僅限

232 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔232 * [`/loop`](/docs/zh-TW/scheduled-tasks)：僅限明確間隔

233 * [Zero Data Retention](/zh-TW/zero-data-retention)：受您的 AWS 協議約束233 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 AWS 協議約束

234 234

235 **替代方案：** 對於排程，使用具有明確間隔的 [`/loop`](/zh-TW/scheduled-tasks) 而不是 `/schedule`。對於雲端工作階段，使用 [GitHub Actions](/zh-TW/github-actions) 或 [GitLab CI/CD](/zh-TW/gitlab-ci-cd)。對於網頁查詢，使用 [WebFetch 工具](/zh-TW/tools-reference#webfetch-tool-behavior)搭配特定 URL。235 **替代方案：** 對於排程，使用具有明確間隔的 [`/loop`](/docs/zh-TW/scheduled-tasks) 而不是 `/schedule`。對於雲端工作階段，使用 [GitHub Actions](/docs/zh-TW/github-actions) 或 [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)。對於網頁查詢，使用 [WebFetch 工具](/docs/zh-TW/tools-reference#webfetch-tool-behavior)搭配特定 URL。

236 </Tab>236 </Tab>

237 237

238 <Tab title="AWS 上的 Claude Platform">238 <Tab title="AWS 上的 Claude Platform">

239 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/zh-TW/fast-mode)、[Advisor](/zh-TW/advisor)、[Channels](/zh-TW/channels)、[分析儀表板](/zh-TW/analytics)、[伺服器管理的設定](/zh-TW/server-managed-settings) 和 [`/design-sync` 和 `/radio` 命令](/zh-TW/commands#all-commands)。239 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/docs/zh-TW/fast-mode)、[Advisor](/docs/zh-TW/advisor)、[Channels](/docs/zh-TW/channels)、[分析儀表板](/docs/zh-TW/analytics)、[伺服器管理的設定](/docs/zh-TW/server-managed-settings) 和 [`/design-sync` 和 `/radio` 命令](/docs/zh-TW/commands#all-commands)。

240 240

241 **在 Amazon Bedrock 不可用的地方可用：** [web search](/zh-TW/tools-reference#websearch-tool-behavior)。241 **在 Amazon Bedrock 不可用的地方可用：** [web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)。

242 242

243 **部分支援：**243 **部分支援：**

244 244

245 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔245 * [`/loop`](/docs/zh-TW/scheduled-tasks)：僅限明確間隔

246 246

247 **替代方案：** 對於排程，使用具有明確間隔的 [`/loop`](/zh-TW/scheduled-tasks) 而不是 `/schedule`。對於雲端工作階段，使用 [GitHub Actions](/zh-TW/github-actions) 或 [GitLab CI/CD](/zh-TW/gitlab-ci-cd)。247 **替代方案：** 對於排程，使用具有明確間隔的 [`/loop`](/docs/zh-TW/scheduled-tasks) 而不是 `/schedule`。對於雲端工作階段，使用 [GitHub Actions](/docs/zh-TW/github-actions) 或 [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)。

248 </Tab>248 </Tab>

249 249

250 <Tab title="Google Cloud's Agent Platform">250 <Tab title="Google Cloud's Agent Platform">

251 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/zh-TW/fast-mode)、[Advisor](/zh-TW/advisor)、[Channels](/zh-TW/channels)、[分析儀表板](/zh-TW/analytics)、[伺服器管理的設定](/zh-TW/server-managed-settings) 和 [`/design-sync` 和 `/radio` 命令](/zh-TW/commands#all-commands)。251 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/docs/zh-TW/fast-mode)、[Advisor](/docs/zh-TW/advisor)、[Channels](/docs/zh-TW/channels)、[分析儀表板](/docs/zh-TW/analytics)、[伺服器管理的設定](/docs/zh-TW/server-managed-settings) 和 [`/design-sync` 和 `/radio` 命令](/docs/zh-TW/commands#all-commands)。

252 252

253 **部分支援：**253 **部分支援：**

254 254

255 * [Desktop](/zh-TW/desktop)：透過[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)255 * [Desktop](/docs/zh-TW/desktop)：透過[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

256 * [Web search](/zh-TW/tools-reference#websearch-tool-behavior)：Claude 4 模型及更新版本256 * [Web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)：Claude 4 模型及更新版本

257 * [Auto mode](/zh-TW/auto-mode-config)：Sonnet 5、Opus 4.7 和 Opus 4.8 僅限257 * [Auto mode](/docs/zh-TW/auto-mode-config)：Sonnet 5、Opus 4.7 和 Opus 4.8 僅限

258 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔258 * [`/loop`](/docs/zh-TW/scheduled-tasks)：僅限明確間隔

259 * [Zero Data Retention](/zh-TW/zero-data-retention)：受您的 Google Cloud 協議約束259 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 Google Cloud 協議約束

260 260

261 **替代方案：** 對於排程，使用具有明確間隔的 [`/loop`](/zh-TW/scheduled-tasks) 而不是 `/schedule`。對於雲端工作階段，使用 [GitHub Actions](/zh-TW/github-actions) 或 [GitLab CI/CD](/zh-TW/gitlab-ci-cd)。261 **替代方案：** 對於排程，使用具有明確間隔的 [`/loop`](/docs/zh-TW/scheduled-tasks) 而不是 `/schedule`。對於雲端工作階段，使用 [GitHub Actions](/docs/zh-TW/github-actions) 或 [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)。

262 </Tab>262 </Tab>

263 263

264 <Tab title="Microsoft Foundry">264 <Tab title="Microsoft Foundry">

265 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/zh-TW/fast-mode)、[Advisor](/zh-TW/advisor)、[Channels](/zh-TW/channels)、[GitHub Actions](/zh-TW/github-actions) 和 [GitLab CI/CD](/zh-TW/gitlab-ci-cd)、[分析儀表板](/zh-TW/analytics)、[伺服器管理的設定](/zh-TW/server-managed-settings) 和 [`/design-sync` 和 `/radio` 命令](/zh-TW/commands#all-commands)。265 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/docs/zh-TW/fast-mode)、[Advisor](/docs/zh-TW/advisor)、[Channels](/docs/zh-TW/channels)、[GitHub Actions](/docs/zh-TW/github-actions) 和 [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)、[分析儀表板](/docs/zh-TW/analytics)、[伺服器管理的設定](/docs/zh-TW/server-managed-settings) 和 [`/design-sync` 和 `/radio` 命令](/docs/zh-TW/commands#all-commands)。

266 266

267 **部分支援：**267 **部分支援：**

268 268

269 * [Desktop](/zh-TW/desktop)：僅透過[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)269 * [Desktop](/docs/zh-TW/desktop)：僅透過[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)

270 * [Auto mode](/zh-TW/auto-mode-config)：Sonnet 5、Opus 4.7 和 Opus 4.8 僅限270 * [Auto mode](/docs/zh-TW/auto-mode-config)：Sonnet 5、Opus 4.7 和 Opus 4.8 僅限

271 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔271 * [`/loop`](/docs/zh-TW/scheduled-tasks)：僅限明確間隔

272 * [Zero Data Retention](/zh-TW/zero-data-retention)：受您的 Azure 協議約束272 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 Azure 協議約束

273 273

274 **替代方案：** 對於排程，使用具有明確間隔的 [`/loop`](/zh-TW/scheduled-tasks) 而不是 `/schedule`。274 **替代方案：** 對於排程，使用具有明確間隔的 [`/loop`](/docs/zh-TW/scheduled-tasks) 而不是 `/schedule`。

275 </Tab>275 </Tab>

276 276

277 <Tab title="Anthropic Console">277 <Tab title="Anthropic Console">

278 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)。278 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)。

279 279

280 [按提供者變化的 CLI 功能](#cli-capabilities-that-vary-by-provider)中的所有功能都可用，當 API 金鑰屬於 Team 或 Enterprise 組織時，[伺服器管理的設定](/zh-TW/server-managed-settings)也可用。280 [按提供者變化的 CLI 功能](#cli-capabilities-that-vary-by-provider)中的所有功能都可用，當 API 金鑰屬於 Team 或 Enterprise 組織時，[伺服器管理的設定](/docs/zh-TW/server-managed-settings)也可用。

281 </Tab>281 </Tab>

282</Tabs>282</Tabs>

283 283

289 289

290| 功能 | Pro | Max | Team | Enterprise |290| 功能 | Pro | Max | Team | Enterprise |

291| :-------------------------------------------------------------------------- | :-- | :-- | :---- | :-------------------------------- |291| :-------------------------------------------------------------------------- | :-- | :-- | :---- | :-------------------------------- |

292| [網頁上的 Claude Code](/zh-TW/claude-code-on-the-web) | ✓ | ✓ | ✓ | ✓ <sup><a href="#fn6">6</a></sup> |292| [網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) | ✓ | ✓ | ✓ | ✓ <sup><a href="#fn6">6</a></sup> |

293| [Routines](/zh-TW/routines) | ✓ | ✓ | ✓ | ✓ |293| [Routines](/docs/zh-TW/routines) | ✓ | ✓ | ✓ | ✓ |

294| [Remote Control](/zh-TW/remote-control) | ✓ | ✓ | 管理員啟用 | 管理員啟用 |294| [Remote Control](/docs/zh-TW/remote-control) | ✓ | ✓ | 管理員啟用 | 管理員啟用 |

295| [Channels](/zh-TW/channels) | ✓ | ✓ | 管理員啟用 | 管理員啟用 |295| [Channels](/docs/zh-TW/channels) | ✓ | ✓ | 管理員啟用 | 管理員啟用 |

296| [Computer use](/zh-TW/computer-use) | ✓ | ✓ | ✗ | ✗ |296| [Computer use](/docs/zh-TW/computer-use) | ✓ | ✓ | ✗ | ✗ |

297| Dispatch ([Desktop](/zh-TW/desktop#sessions-from-dispatch)) | ✓ | ✓ | ✗ | ✗ |297| Dispatch ([Desktop](/docs/zh-TW/desktop#sessions-from-dispatch)) | ✓ | ✓ | ✗ | ✗ |

298| [Code Review](/zh-TW/code-review) | ✗ | ✗ | ✓ | ✓ |298| [Code Review](/docs/zh-TW/code-review) | ✗ | ✗ | ✓ | ✓ |

299| [Artifacts](/zh-TW/artifacts) | ✓ | ✓ | ✓ | 管理員啟用 |299| [Artifacts](/docs/zh-TW/artifacts) | ✓ | ✓ | ✓ | 管理員啟用 |

300| [分析儀表板和貢獻指標](/zh-TW/analytics) | ✗ | ✗ | ✓ | ✓ |300| [分析儀表板和貢獻指標](/docs/zh-TW/analytics) | ✗ | ✗ | ✓ | ✓ |

301| [Enterprise Analytics API](/zh-TW/analytics#access-data-programmatically) | ✗ | ✗ | ✗ | ✓ |301| [Enterprise Analytics API](/docs/zh-TW/analytics#access-data-programmatically) | ✗ | ✗ | ✗ | ✓ |

302| [伺服器管理的設定](/zh-TW/server-managed-settings) | ✗ | ✗ | ✓ | ✓ |302| [伺服器管理的設定](/docs/zh-TW/server-managed-settings) | ✗ | ✗ | ✓ | ✓ |

303| [SSO](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) | ✗ | ✗ | ✓ | ✓ |303| [SSO](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) | ✗ | ✗ | ✓ | ✓ |

304| SCIM | ✗ | ✗ | ✗ | ✓ |304| SCIM | ✗ | ✗ | ✗ | ✓ |

305| [Compliance API](https://platform.claude.com/docs/en/api/compliance) | ✗ | ✗ | ✗ | ✓ |305| [Compliance API](https://platform.claude.com/docs/en/api/compliance) | ✗ | ✗ | ✗ | ✓ |

306| [Zero Data Retention](/zh-TW/zero-data-retention) | ✗ | ✗ | ✗ | ✓ <sup><a href="#fn7">7</a></sup> |306| [Zero Data Retention](/docs/zh-TW/zero-data-retention) | ✗ | ✗ | ✗ | ✓ <sup><a href="#fn7">7</a></sup> |

307 307

308<span id="fn6" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>6</sup> 在 Enterprise 上，需要進階座位或 Chat + Claude Code 座位。請參閱[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web)。<br />308<span id="fn6" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>6</sup> 在 Enterprise 上，需要進階座位或 Chat + Claude Code 座位。請參閱[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web)。<br />

309<span id="fn7" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>7</sup> 不包含在標準 Enterprise 計畫中。需要 Anthropic 為符合條件的帳戶進行單獨啟用。請參閱 [Zero Data Retention](/zh-TW/zero-data-retention)。309<span id="fn7" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>7</sup> 不包含在標準 Enterprise 計畫中。需要 Anthropic 為符合條件的帳戶進行單獨啟用。請參閱 [Zero Data Retention](/docs/zh-TW/zero-data-retention)。

310 310

311如需定價和完整計畫比較，請參閱 [Team 計畫](https://support.claude.com/en/articles/9266767-what-is-the-team-plan)和 [Enterprise 計畫](https://support.claude.com/en/articles/9797531-what-is-the-enterprise-plan)。311如需定價和完整計畫比較，請參閱 [Team 計畫](https://support.claude.com/en/articles/9266767-what-is-the-team-plan)和 [Enterprise 計畫](https://support.claude.com/en/articles/9797531-what-is-the-enterprise-plan)。

312 312

314 模型可用性314 模型可用性

315</h2>315</h2>

316 316

317如需每個提供者和地區可用的 Claude 模型和內容視窗大小，請參閱[模型配置](/zh-TW/model-config)和[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。Vision、PDF 輸入和擴展思考是模型功能而非 Claude Code 功能，在提供該模型的每個提供者上都有效。[Prompt caching](/zh-TW/prompt-caching) 在大多數提供者上的運作方式相同；在 Amazon Bedrock 上，支援因模型而異。317如需每個提供者和地區可用的 Claude 模型和內容視窗大小，請參閱[模型配置](/docs/zh-TW/model-config)和[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。Vision、PDF 輸入和擴展思考是模型功能而非 Claude Code 功能，在提供該模型的每個提供者上都有效。[Prompt caching](/docs/zh-TW/prompt-caching) 在大多數提供者上的運作方式相同；在 Amazon Bedrock 上，支援因模型而異。

318 318

319<h2 id="related-resources">319<h2 id="related-resources">

320 相關資源320 相關資源

321</h2>321</h2>

322 322

323* [企業部署概述](/zh-TW/third-party-integrations)：比較提供者之間的驗證、計費和地區323* [企業部署概述](/docs/zh-TW/third-party-integrations)：比較提供者之間的驗證、計費和地區

324* 提供者設定指南：[Amazon Bedrock](/zh-TW/amazon-bedrock)、[AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry)324* 提供者設定指南：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry)

325* [平台和整合](/zh-TW/platforms)：Claude Code 執行的位置，包括 CLI、Desktop、IDE 擴充功能、網頁、行動和 CI/CD325* [平台和整合](/docs/zh-TW/platforms)：Claude Code 執行的位置，包括 CLI、Desktop、IDE 擴充功能、網頁、行動和 CI/CD

fullscreen.md +14 −14

Details

22 啟用全螢幕渲染22 啟用全螢幕渲染

23</h2>23</h2>

24 24

25在任何 Claude Code 對話中執行 `/tui fullscreen`。CLI 會儲存 [`tui` 設定](/zh-TW/settings#available-settings)並重新啟動進入全螢幕模式，您的對話保持完整，因此您可以在工作階段中途切換而不會失去上下文。執行 `/tui default` 以切換回經典渲染器，或執行 `/tui` 不帶任何引數以列印哪個渲染器處於活動狀態。25在任何 Claude Code 對話中執行 `/tui fullscreen`。CLI 會儲存 [`tui` 設定](/docs/zh-TW/settings#available-settings)並重新啟動進入全螢幕模式，您的對話保持完整，因此您可以在工作階段中途切換而不會失去上下文。執行 `/tui default` 以切換回經典渲染器，或執行 `/tui` 不帶任何引數以列印哪個渲染器處於活動狀態。

26 26

27重新啟動的工作階段會保持對話在螢幕上顯示的樣子。如果您在工作階段中較早執行過 [`/rewind`](/zh-TW/checkpointing#rewind-and-summarize)，重新啟動會從倒帶點而不是儲存在磁碟上的較長文字記錄繼續。在 v2.1.207 之前，在倒帶後切換渲染器會還原倒帶已移除的對話。27重新啟動的工作階段會保持對話在螢幕上顯示的樣子。如果您在工作階段中較早執行過 [`/rewind`](/docs/zh-TW/checkpointing#rewind-and-summarize)，重新啟動會從倒帶點而不是儲存在磁碟上的較長文字記錄繼續。在 v2.1.207 之前，在倒帶後切換渲染器會還原倒帶已移除的對話。

28 28

29您也可以在啟動 Claude Code 之前設定 `CLAUDE_CODE_NO_FLICKER` 環境變數：29您也可以在啟動 Claude Code 之前設定 `CLAUDE_CODE_NO_FLICKER` 環境變數：

30 30

58 58

59* **在提示輸入中點擊**以在您輸入的文字中的任何位置定位游標。59* **在提示輸入中點擊**以在您輸入的文字中的任何位置定位游標。

60* **點擊 `/` 命令或 `@` 檔案清單中的建議**以接受它。懸停會突顯游標下的列。60* **點擊 `/` 命令或 `@` 檔案清單中的建議**以接受它。懸停會突顯游標下的列。

61* **點擊選擇功能表中的選項**以選擇它。這涵蓋權限提示、`/model`、`/config` 和其他顯示選項清單的對話框。懸停會在游標下的列上顯示指標。{/* min-version: 2.1.187 */}需要 Claude Code v2.1.187 或更新版本。61* **點擊選擇功能表中的選項**以選擇它。這涵蓋權限提示、`/model`、`/config` 和其他顯示選項清單的對話框。懸停會在游標下的列上顯示指標。需要 Claude Code v2.1.187 或更新版本。

62* **點擊多選功能表中的選項**以切換它，然後點擊提交按鈕以確認您的選擇。點擊自由文字列（例如多選題中的 `Other` 列）會聚焦其輸入欄位，以便您可以輸入答案。{/* min-version: 2.1.208 */}需要 Claude Code v2.1.208 或更新版本。62* **點擊多選功能表中的選項**以切換它，然後點擊提交按鈕以確認您的選擇。點擊自由文字列（例如多選題中的 `Other` 列）會聚焦其輸入欄位，以便您可以輸入答案。需要 Claude Code v2.1.208 或更新版本。

63* **點擊摺疊的工具結果**以展開它並查看完整輸出。再次點擊以摺疊。工具呼叫及其結果一起展開。只有有更多內容要顯示的訊息才可點擊。63* **點擊摺疊的工具結果**以展開它並查看完整輸出。再次點擊以摺疊。工具呼叫及其結果一起展開。只有有更多內容要顯示的訊息才可點擊。

64* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然後點擊 URL 或檔案路徑**以開啟它。工具輸出中的檔案路徑（例如在 Edit 或 Write 後列印的路徑）在您的預設應用程式中開啟。純 `http://` 和 `https://` URL 在您的瀏覽器中開啟。{/* min-version: 2.1.181 */}自 v2.1.181 起，不按住 `Cmd` 或 `Ctrl` 的純點擊不再開啟連結，符合原生終端行為。某些 macOS 終端會將 `Cmd`+點擊轉發給執行中的應用程式，而不是自己開啟連結，且終端滑鼠協議無法編碼 `Cmd` 鍵，所以 Claude Code 將其接收為純點擊。在 Ghostty 中，以及{/* min-version: 2.1.198 */}自 v2.1.198 起在 macOS 上的 Warp 中，Claude Code 偵測到這一點並讓純點擊連結開啟它，按住 `Cmd` 仍然有效。在 VS Code 整合終端和類似的基於 xterm.js 的終端中，Claude Code 遵從終端自己的連結處理程式，該處理程式使用相同的手勢。64* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然後點擊 URL 或檔案路徑**以開啟它。工具輸出中的檔案路徑（例如在 Edit 或 Write 後列印的路徑）在您的預設應用程式中開啟。純 `http://` 和 `https://` URL 在您的瀏覽器中開啟。自 v2.1.181 起，不按住 `Cmd` 或 `Ctrl` 的純點擊不再開啟連結，符合原生終端行為。某些 macOS 終端會將 `Cmd`+點擊轉發給執行中的應用程式，而不是自己開啟連結，且終端滑鼠協議無法編碼 `Cmd` 鍵，所以 Claude Code 將其接收為純點擊。在 Ghostty 中，以及自 v2.1.198 起在 macOS 上的 Warp 中，Claude Code 偵測到這一點並讓純點擊連結開啟它，按住 `Cmd` 仍然有效。在 VS Code 整合終端和類似的基於 xterm.js 的終端中，Claude Code 遵從終端自己的連結處理程式，該處理程式使用相同的手勢。

65* **點擊並拖曳**以在對話中的任何位置選擇文字。雙擊選擇一個單詞，符合 iTerm2 的單詞邊界，因此檔案路徑選擇為一個單位。{/* min-version: 2.1.198 */}自 v2.1.198 起，雙擊 URL 會選擇整個 URL，包括配置。三擊選擇該行。65* **點擊並拖曳**以在對話中的任何位置選擇文字。雙擊選擇一個單詞，符合 iTerm2 的單詞邊界，因此檔案路徑選擇為一個單位。自 v2.1.198 起，雙擊 URL 會選擇整個 URL，包括配置。三擊選擇該行。

66* **使用滑鼠滾輪捲動**以在對話中移動。66* **使用滑鼠滾輪捲動**以在對話中移動。

67 67

68選定的文字在滑鼠釋放時自動複製到您的剪貼簿。若要關閉此功能，請在 `/config` 中切換「選擇時複製」。68選定的文字在滑鼠釋放時自動複製到您的剪貼簿。若要關閉此功能，請在 `/config` 中切換「選擇時複製」。

90* 使用滑鼠滾輪捲動到底部以恢復跟隨。90* 使用滑鼠滾輪捲動到底部以恢復跟隨。

91* 將 `scroll:bottom` 重新繫結到您的鍵盤可以傳送的快捷鍵。91* 將 `scroll:bottom` 重新繫結到您的鍵盤可以傳送的快捷鍵。

92 92

~~93這些動作是可重新繫結的。請參閱[捲動動作](/zh-TW/keybindings#scroll-actions)以取得完整的動作名稱清單，包括沒有預設繫結的半頁和整頁變體。~~93這些動作是可重新繫結的。請參閱[捲動動作](/docs/zh-TW/keybindings#scroll-actions)以取得完整的動作名稱清單，包括沒有預設繫結的半頁和整頁變體。

94 94

95<h3 id="auto-follow">95<h3 id="auto-follow">

96 自動跟隨96 自動跟隨

100 100

101自動跟隨暫停時，當回應完成串流時，檢視也會保持在您捲動的位置。在 v2.1.207 之前，當長回應完成串流時，檢視可能會跳到答案開始之上。101自動跟隨暫停時，當回應完成串流時，檢視也會保持在您捲動的位置。在 v2.1.207 之前，當長回應完成串流時，檢視可能會跳到答案開始之上。

102 102

103按鈕的鍵盤提示反映您的鍵盤可以傳送的內容。在 macOS 上，它建議點擊或 `Fn+↓` 來捲動，因為 `Ctrl+End` 無法從 Mac 鍵盤到達 Claude Code。重新繫結 [`scroll:bottom`](/zh-TW/keybindings#scroll-actions)，按鈕會在每個平台上顯示您的快捷鍵。在 v2.1.206 之前，按鈕在 macOS 上建議 `Ctrl+End`。103按鈕的鍵盤提示反映您的鍵盤可以傳送的內容。在 macOS 上，它建議點擊或 `Fn+↓` 來捲動，因為 `Ctrl+End` 無法從 Mac 鍵盤到達 Claude Code。重新繫結 [`scroll:bottom`](/docs/zh-TW/keybindings#scroll-actions)，按鈕會在每個平台上顯示您的快捷鍵。在 v2.1.206 之前，按鈕在 macOS 上建議 `Ctrl+End`。

104 104

105在終端太窄而無法容納完整標籤的情況下，按鈕會縮短提示，而不是換行到下面的文字記錄行。在 v2.1.206 之前，長標籤可能會換行到文字記錄上。105在終端太窄而無法容納完整標籤的情況下，按鈕會縮短提示，而不是換行到下面的文字記錄行。在 v2.1.206 之前，長標籤可能會換行到文字記錄上。

106 106

126 126

127該命令寫入與 `CLAUDE_CODE_SCROLL_SPEED` 環境變數設定相同的值，持久化到 `~/.claude/settings.json`。該命令在 JetBrains IDE 終端中不可用。127該命令寫入與 `CLAUDE_CODE_SCROLL_SPEED` 環境變數設定相同的值，持久化到 `~/.claude/settings.json`。該命令在 JetBrains IDE 終端中不可用。

128 128

129另外，Claude Code 會在您快速旋轉滾輪時加速捲動速率，因此快速旋轉覆蓋的距離比相同數量的慢凹口更遠。{/* min-version: 2.1.174 */}若要關閉加速並保持每個凹口的恆定速率，請在 [`settings.json`](/zh-TW/settings#available-settings) 中將 `wheelScrollAccelerationEnabled` 設定為 `false`。此設定需要 Claude Code v2.1.174 或更新版本。129另外，Claude Code 會在您快速旋轉滾輪時加速捲動速率，因此快速旋轉覆蓋的距離比相同數量的慢凹口更遠。若要關閉加速並保持每個凹口的恆定速率，請在 [`settings.json`](/docs/zh-TW/settings#available-settings) 中將 `wheelScrollAccelerationEnabled` 設定為 `false`。此設定需要 Claude Code v2.1.174 或更新版本。

130 130

131<h3 id="scroll-in-the-jetbrains-ide-terminal">131<h3 id="scroll-in-the-jetbrains-ide-terminal">

132 JetBrains IDE 終端中的捲動132 JetBrains IDE 終端中的捲動

187 187

188並非每個 tmux 版本都會套用應用程式的同步輸出，因此在 tmux 下重繪期間您可能會看到比直接在終端中執行 Claude Code 時更多的閃爍。如果閃爍明顯，特別是在 SSH 上，請升級到最新的 tmux 或在 tmux 外的自己的終端標籤中執行 Claude Code。使用 `tmux -V` 檢查您的 tmux 版本。188並非每個 tmux 版本都會套用應用程式的同步輸出，因此在 tmux 下重繪期間您可能會看到比直接在終端中執行 Claude Code 時更多的閃爍。如果閃爍明顯，特別是在 SSH 上，請升級到最新的 tmux 或在 tmux 外的自己的終端標籤中執行 Claude Code。使用 `tmux -V` 檢查您的 tmux 版本。

189 189

190{/* min-version: 2.1.200 */}Claude Code 在偵測到來自 `TERM_PROGRAM_VERSION` 變數的 tmux 3.4 或更新版本時會自動開啟同步輸出，當無法判斷版本時會回退到直接查詢終端以取得同步輸出支援。重繪是否實際上變成原子操作取決於您的 tmux 版本是否遵守同步輸出；如果您在 tmux 3.4 或更新版本下仍然看到閃爍，請升級到最新的 tmux。此偵測需要 Claude Code v2.1.200 或更新版本。190Claude Code 在偵測到來自 `TERM_PROGRAM_VERSION` 變數的 tmux 3.4 或更新版本時會自動開啟同步輸出，當無法判斷版本時會回退到直接查詢終端以取得同步輸出支援。重繪是否實際上變成原子操作取決於您的 tmux 版本是否遵守同步輸出；如果您在 tmux 3.4 或更新版本下仍然看到閃爍，請升級到最新的 tmux。此偵測需要 Claude Code v2.1.200 或更新版本。

191 191

192<h2 id="keep-native-text-selection">192<h2 id="keep-native-text-selection">

193 保持原生文字選擇193 保持原生文字選擇

203 203

204在 tmux 內，它也寫入 tmux 貼上緩衝區。在 SSH 上，它回退到 OSC 52 逃逸序列。Claude Code 在每次複製後列印一個快顯通知，告訴您它使用了哪個路徑。204在 tmux 內，它也寫入 tmux 貼上緩衝區。在 SSH 上，它回退到 OSC 52 逃逸序列。Claude Code 在每次複製後列印一個快顯通知，告訴您它使用了哪個路徑。

205 205

206某些終端預設會阻止 OSC 52。iTerm2 會阻止它，直到您開啟 Settings → General → Selection → Applications in terminal may access clipboard；在 iTerm2 中執行 [`/terminal-setup`](/zh-TW/terminal-config) 會為您啟用此功能。206某些終端預設會阻止 OSC 52。iTerm2 會阻止它，直到您開啟 Settings → General → Selection → Applications in terminal may access clipboard；在 iTerm2 中執行 [`/terminal-setup`](/docs/zh-TW/terminal-config) 會為您啟用此功能。

207 207

208如果您想進行一次性的原生選擇，要使用的按鍵取決於您的終端：208如果您想進行一次性的原生選擇，要使用的按鍵取決於您的終端：

209 209

238 238

239全螢幕渲染只會傳送幀之間變更的儲存格。某些終端機（最常見的是 Windows Terminal 和其他 ConPTY 支援的主機）會不正確地合併這些定位寫入，並在您調整視窗大小之前，在螢幕上留下較早輸出的片段。239全螢幕渲染只會傳送幀之間變更的儲存格。某些終端機（最常見的是 Windows Terminal 和其他 ConPTY 支援的主機）會不正確地合併這些定位寫入，並在您調整視窗大小之前，在螢幕上留下較早輸出的片段。

240 240

241設定 [`CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1`](/zh-TW/env-vars) 以在每一幀上重新繪製每個儲存格，而不是傳送增量更新。241設定 [`CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1`](/docs/zh-TW/env-vars) 以在每一幀上重新繪製每個儲存格，而不是傳送增量更新。

242 242

243在 Windows PowerShell 上：243在 Windows PowerShell 上：

244 244

253CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1 claude253CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1 claude

254```254```

255 255

256在 Windows 上，Claude Code 已自動為背景工作階段和 [agent view](/zh-TW/agent-view) 啟用完整重繪，因此您只需要為直接啟動的互動式全螢幕工作階段設定該變數。256在 Windows 上，Claude Code 已自動為背景工作階段和 [agent view](/docs/zh-TW/agent-view) 啟用完整重繪，因此您只需要為直接啟動的互動式全螢幕工作階段設定該變數。

257 257

258<h2 id="research-preview">258<h2 id="research-preview">

259 研究預覽259 研究預覽

265 265

266若要關閉全螢幕渲染，請執行 `/tui default`，或如果您以該方式啟用它，請取消設定 `CLAUDE_CODE_NO_FLICKER`。若要不論已儲存的 `tui` 設定為何都強制使用經典渲染器，請設定 `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`。經典渲染器將對話保留在您終端的原生捲軸中，因此 `Cmd+f` 和 tmux 複製模式可以照常運作。266若要關閉全螢幕渲染，請執行 `/tui default`，或如果您以該方式啟用它，請取消設定 `CLAUDE_CODE_NO_FLICKER`。若要不論已儲存的 `tui` 設定為何都強制使用經典渲染器，請設定 `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`。經典渲染器將對話保留在您終端的原生捲軸中，因此 `Cmd+f` 和 tmux 複製模式可以照常運作。

267 267

268從 [agent view](/zh-TW/agent-view) 或 `claude attach` 開啟的背景工作階段始終使用全螢幕渲染。附加終端進入替代螢幕緩衝區以顯示工作階段，經典渲染器在那裡沒有捲軸或滑鼠處理，因此 `tui` 設定和 `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` 不適用於它們。268從 [agent view](/docs/zh-TW/agent-view) 或 `claude attach` 開啟的背景工作階段始終使用全螢幕渲染。附加終端進入替代螢幕緩衝區以顯示工作階段，經典渲染器在那裡沒有捲軸或滑鼠處理，因此 `tui` 設定和 `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` 不適用於它們。

google-vertex-ai.md +9 −9

Details

108 </Step>108 </Step>

109 109

110 <Step title="遵循精靈提示">110 <Step title="遵循精靈提示">

111 選擇您如何向 Google Cloud 進行驗證：來自 `gcloud` 的應用程式預設認證、服務帳戶金鑰檔案，或已在您的環境中的認證。精靈會偵測您的專案和區域，驗證您的專案可以呼叫哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的[使用者設定檔](/zh-TW/settings)的 `env` 區塊，因此您不需要自己匯出環境變數。111 選擇您如何向 Google Cloud 進行驗證：來自 `gcloud` 的應用程式預設認證、服務帳戶金鑰檔案，或已在您的環境中的認證。精靈會偵測您的專案和區域，驗證您的專案可以呼叫哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的[使用者設定檔](/docs/zh-TW/settings)的 `env` 區塊，因此您不需要自己匯出環境變數。

112 </Step>112 </Step>

113</Steps>113</Steps>

114 114

115登入後，您可以隨時執行 `/setup-vertex` 以重新開啟精靈並變更您的認證、專案、區域或模型固定。模型固定步驟會從您目前固定的模型開始。精靈會寫入 `~/.claude/settings.json`，或在設定 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars#variables) 時寫入 `$CLAUDE_CONFIG_DIR/settings.json`。115登入後，您可以隨時執行 `/setup-vertex` 以重新開啟精靈並變更您的認證、專案、區域或模型固定。模型固定步驟會從您目前固定的模型開始。精靈會寫入 `~/.claude/settings.json`，或在設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars#variables) 時寫入 `$CLAUDE_CONFIG_DIR/settings.json`。

116 116

117<h2 id="region-configuration">117<h2 id="region-configuration">

118 區域設定118 區域設定

212export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1212export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

213```213```

214 214

215大多數模型版本都有對應的 `VERTEX_REGION_CLAUDE_*` 變數。如需完整清單，請參閱[環境變數參考](/zh-TW/env-vars)。檢查 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以確定哪些模型支援全球端點與僅限區域端點。215大多數模型版本都有對應的 `VERTEX_REGION_CLAUDE_*` 變數。如需完整清單，請參閱[環境變數參考](/docs/zh-TW/env-vars)。檢查 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以確定哪些模型支援全球端點與僅限區域端點。

216 216

217[Prompt caching](/zh-TW/prompt-caching) 會自動啟用。若要停用它，請設定 `DISABLE_PROMPT_CACHING=1`。若要要求 1 小時 cache TTL 而不是 5 分鐘預設值，請設定 `ENABLE_PROMPT_CACHING_1H=1`；具有 1 小時 TTL 的 cache 寫入會以更高費率計費。如需提高速率限制，請聯絡 Google Cloud 支援。使用 Google Cloud 的 Agent Platform 時，`/logout` 命令會被停用，因為驗證是透過 Google Cloud 認證處理的。217[Prompt caching](/docs/zh-TW/prompt-caching) 會自動啟用。若要停用它，請設定 `DISABLE_PROMPT_CACHING=1`。若要要求 1 小時 cache TTL 而不是 5 分鐘預設值，請設定 `ENABLE_PROMPT_CACHING_1H=1`；具有 1 小時 TTL 的 cache 寫入會以更高費率計費。如需提高速率限制，請聯絡 Google Cloud 支援。使用 Google Cloud 的 Agent Platform 時，`/logout` 命令會被停用，因為驗證是透過 Google Cloud 認證處理的。

218 218

219Claude Code 在 Google Cloud 的 Agent Platform 上預設停用 [MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search)，因此 MCP 工具定義會預先載入。Google Cloud 的 Agent Platform 支援 Claude Sonnet 4.5 及更新版本以及 Claude Opus 4.5 及更新版本的工具搜尋。設定 `ENABLE_TOOL_SEARCH=true` 以在這些模型上啟用它。Google Cloud 的 Agent Platform 上的較早模型不接受所需的 beta 標頭，如果您使用它們啟用工具搜尋，要求會失敗。219Claude Code 在 Google Cloud 的 Agent Platform 上預設停用 [MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)，因此 MCP 工具定義會預先載入。Google Cloud 的 Agent Platform 支援 Claude Sonnet 4.5 及更新版本以及 Claude Opus 4.5 及更新版本的工具搜尋。設定 `ENABLE_TOOL_SEARCH=true` 以在這些模型上啟用它。Google Cloud 的 Agent Platform 上的較早模型不接受所需的 beta 標頭，如果您使用它們啟用工具搜尋，要求會失敗。

220 220

221<h3 id="5-pin-model-versions">221<h3 id="5-pin-model-versions">

222 5. 固定模型版本222 5. 固定模型版本

236export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'236export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

237```237```

238 238

239如需目前和舊版模型 ID，請參閱[模型概覽](https://platform.claude.com/docs/en/about-claude/models/overview)。如需完整的環境變數清單，請參閱[模型設定](/zh-TW/model-config#pin-models-for-third-party-deployments)。239如需目前和舊版模型 ID，請參閱[模型概覽](https://platform.claude.com/docs/en/about-claude/models/overview)。如需完整的環境變數清單，請參閱[模型設定](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)。

240 240

241Claude Code 使用這些預設模型，當未設定固定變數時：241Claude Code 使用這些預設模型，當未設定固定變數時：

242 242

254 Opus 模型的每個 token 價格高於 Sonnet 模型，因此不固定主要模型的部署在更新到 v2.1.207 或更新版本後會以 Opus 費率計費。若要保持 Sonnet 4.5 作為主要模型，請將 `ANTHROPIC_MODEL` 設定為其完整模型 ID。使用 `ANTHROPIC_DEFAULT_SONNET_MODEL` 引導預設值且未設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 的部署會保持其引導的 Sonnet 模型作為預設值。254 Opus 模型的每個 token 價格高於 Sonnet 模型，因此不固定主要模型的部署在更新到 v2.1.207 或更新版本後會以 Opus 費率計費。若要保持 Sonnet 4.5 作為主要模型，請將 `ANTHROPIC_MODEL` 設定為其完整模型 ID。使用 `ANTHROPIC_DEFAULT_SONNET_MODEL` 引導預設值且未設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 的部署會保持其引導的 Sonnet 模型作為預設值。

255</Warning>255</Warning>

256 256

257{/* min-version: 2.1.207 */}在 v2.1.207 之前，Google Cloud 的 Agent Platform 上的主要模型預設為 Sonnet 4.5，`opus` 別名解析為 Opus 4.6，背景工作始終使用主要模型。257在 v2.1.207 之前，Google Cloud 的 Agent Platform 上的主要模型預設為 Sonnet 4.5，`opus` 別名解析為 Opus 4.6，背景工作始終使用主要模型。

258 258

259若要進一步自訂模型：259若要進一步自訂模型：

260 260

269 269

270當 Claude Code 以 Google Cloud 的 Agent Platform 設定啟動時，它會驗證它打算使用的模型在您的專案中是否可存取。270當 Claude Code 以 Google Cloud 的 Agent Platform 設定啟動時，它會驗證它打算使用的模型在您的專案中是否可存取。

271 271

272如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的專案可以呼叫較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的[使用者設定檔](/zh-TW/settings)並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。272如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的專案可以呼叫較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的[使用者設定檔](/docs/zh-TW/settings)並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。

273 273

274如果您尚未固定模型，且目前預設值在您的專案中無法使用，Claude Code 會在目前工作階段中回退並顯示通知。它會先嘗試預設模型的較早版本，當預設為 Opus 模型且沒有可用的 Opus 版本時，會回退到預設 Sonnet 模型。回退不會被保留。在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中啟用較新模型或[固定版本](#5-pin-model-versions)以使選擇永久化。274如果您尚未固定模型，且目前預設值在您的專案中無法使用，Claude Code 會在目前工作階段中回退並顯示通知。它會先嘗試預設模型的較早版本，當預設為 Opus 模型且沒有可用的 Opus 版本時，會回退到預設 Sonnet 模型。回退不會被保留。在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中啟用較新模型或[固定版本](#5-pin-model-versions)以使選擇永久化。

275 275

297 297

298Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Google Cloud 的 Agent Platform 上支援 [1M token context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#context-window-sizes-by-model)。Sonnet 5 始終以 1M 視窗執行，沒有 `[1m]` 變體可選擇。對於其他模型，Claude Code 會在您選擇 1M 模型變體時自動啟用擴展 context window。298Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Google Cloud 的 Agent Platform 上支援 [1M token context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#context-window-sizes-by-model)。Sonnet 5 始終以 1M 視窗執行，沒有 `[1m]` 變體可選擇。對於其他模型，Claude Code 會在您選擇 1M 模型變體時自動啟用擴展 context window。

299 299

300[設定精靈](#sign-in-with-agent-platform)在固定模型時提供 1M context 選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。如需詳細資訊，請參閱[為第三方部署固定模型](/zh-TW/model-config#pin-models-for-third-party-deployments)。300[設定精靈](#sign-in-with-agent-platform)在固定模型時提供 1M context 選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。如需詳細資訊，請參閱[為第三方部署固定模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)。

301 301

302<h2 id="troubleshooting">302<h2 id="troubleshooting">

303 故障排除303 故障排除

headless.md +23 −23

Details

6 6

7> 使用 Agent SDK 從 CLI、Python 或 TypeScript 以程式方式執行 Claude Code。7> 使用 Agent SDK 從 CLI、Python 或 TypeScript 以程式方式執行 Claude Code。

8 8

9[Agent SDK](/zh-TW/agent-sdk/overview) 提供與 Claude Code 相同的工具、agent 迴圈和上下文管理。它可作為 CLI 用於指令碼和 CI/CD，或作為 [Python](/zh-TW/agent-sdk/python) 和 [TypeScript](/zh-TW/agent-sdk/typescript) 套件供完整的程式控制。9[Agent SDK](/docs/zh-TW/agent-sdk/overview) 提供與 Claude Code 相同的工具、agent 迴圈和上下文管理。它可作為 CLI 用於指令碼和 CI/CD，或作為 [Python](/docs/zh-TW/agent-sdk/python) 和 [TypeScript](/docs/zh-TW/agent-sdk/typescript) 套件供完整的程式控制。

10 10

~~11若要以非互動模式執行 Claude Code，請傳遞 `-p` 和您的提示以及任何 [CLI 選項](/zh-TW/cli-reference)：~~11若要以非互動模式執行 Claude Code，請傳遞 `-p` 和您的提示以及任何 [CLI 選項](/docs/zh-TW/cli-reference)：

12 12

13```bash theme={null}13```bash theme={null}

14claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"14claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

15```15```

16 16

17本頁涵蓋透過 CLI (`claude -p`) 使用 Agent SDK。如需具有結構化輸出、工具核准回呼和原生訊息物件的 Python 和 TypeScript SDK 套件，請參閱 [完整 Agent SDK 文件](/zh-TW/agent-sdk/overview)。17本頁涵蓋透過 CLI (`claude -p`) 使用 Agent SDK。如需具有結構化輸出、工具核准回呼和原生訊息物件的 Python 和 TypeScript SDK 套件，請參閱 [完整 Agent SDK 文件](/docs/zh-TW/agent-sdk/overview)。

18 18

19<h2 id="basic-usage">19<h2 id="basic-usage">

20 基本用法20 基本用法

21</h2>21</h2>

22 22

~~23將 `-p`（或 `--print`）旗標新增至任何 `claude` 命令以非互動方式執行它。所有 [CLI 選項](/zh-TW/cli-reference) 都適用於 `-p`，包括：~~23將 `-p`（或 `--print`）旗標新增至任何 `claude` 命令以非互動方式執行它。所有 [CLI 選項](/docs/zh-TW/cli-reference) 都適用於 `-p`，包括：

24 24

25* `--continue` 用於 [繼續對話](#continue-conversations)25* `--continue` 用於 [繼續對話](#continue-conversations)

26* `--allowedTools` 用於 [自動核准工具](#auto-approve-tools)26* `--allowedTools` 用於 [自動核准工具](#auto-approve-tools)

36 使用裸機模式加快速度36 使用裸機模式加快速度

37</h3>37</h3>

38 38

39新增 `--bare` 以跳過 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索來減少啟動時間。沒有它，`claude -p` 會載入互動式工作階段會載入的相同 [上下文](/zh-TW/how-claude-code-works#the-context-window)，包括在工作目錄或 `~/.claude` 中設定的任何內容。39新增 `--bare` 以跳過 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索來減少啟動時間。沒有它，`claude -p` 會載入互動式工作階段會載入的相同 [上下文](/docs/zh-TW/how-claude-code-works#the-context-window)，包括在工作目錄或 `~/.claude` 中設定的任何內容。

40 40

41裸機模式對於 CI 和指令碼很有用，您需要在每台機器上獲得相同的結果。隊友 `~/.claude` 中的 hook 或專案的 `.mcp.json` 中的 MCP 伺服器不會執行，因為裸機模式永遠不會讀取它們。只有您明確傳遞的旗標才會生效。41裸機模式對於 CI 和指令碼很有用，您需要在每台機器上獲得相同的結果。隊友 `~/.claude` 中的 hook 或專案的 `.mcp.json` 中的 MCP 伺服器不會執行，因為裸機模式永遠不會讀取它們。只有您明確傳遞的旗標才會生效。

42 42

66 結束時的背景工作66 結束時的背景工作

67</h3>67</h3>

68 68

69如果 Claude 在 `claude -p` 執行期間啟動 [背景 Bash 工作](/zh-TW/tools-reference#bash-tool-behavior)，例如開發伺服器或監視組建，該工作將在 Claude 傳回其最終結果且 stdin 已關閉後約五秒鐘終止。寬限期允許在結果之後立即完成的工作仍然傳遞其輸出。在 v2.1.163 之前，永不退出的背景程序會無限期地保持 `claude -p` 呼叫開啟。69如果 Claude 在 `claude -p` 執行期間啟動 [背景 Bash 工作](/docs/zh-TW/tools-reference#bash-tool-behavior)，例如開發伺服器或監視組建，該工作將在 Claude 傳回其最終結果且 stdin 已關閉後約五秒鐘終止。寬限期允許在結果之後立即完成的工作仍然傳遞其輸出。在 v2.1.163 之前，永不退出的背景程序會無限期地保持 `claude -p` 呼叫開啟。

70 70

71背景 [subagents](/zh-TW/sub-agents) 和工作流程不受五秒寬限期的限制，因為它們的結果是最終輸出的一部分，所以 `claude -p` 會等待它們完成。從 v2.1.182 開始，該等待預設上限為十分鐘，因此卡住的背景 agent 無法無限期地保持程序開啟。使用 [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/zh-TW/env-vars) 調整上限，或將其設定為 `0` 以無限制地等待。71背景 [subagents](/docs/zh-TW/sub-agents) 和工作流程不受五秒寬限期的限制，因為它們的結果是最終輸出的一部分，所以 `claude -p` 會等待它們完成。從 v2.1.182 開始，該等待預設上限為十分鐘，因此卡住的背景 agent 無法無限期地保持程序開啟。使用 [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/docs/zh-TW/env-vars) 調整上限，或將其設定為 `0` 以無限制地等待。

72 72

73<h2 id="examples">73<h2 id="examples">

74 範例74 範例

88cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt88cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

89```89```

90 90

91使用 `--output-format json`，回應承載包括 `total_cost_usd` 和每個模型的成本明細，因此指令碼呼叫者可以追蹤每次叫用的支出，而無需查詢 [使用儀表板](/zh-TW/costs)。91使用 `--output-format json`，回應承載包括 `total_cost_usd` 和每個模型的成本明細，因此指令碼呼叫者可以追蹤每次叫用的支出，而無需查詢 [使用儀表板](/docs/zh-TW/costs)。

92 92

93<Note>93<Note>

94 自 Claude Code v2.1.128 起，管道傳送的 stdin 上限為 10MB。如果超過上限，Claude Code 會以清晰的錯誤和非零狀態代碼退出。若要處理更大的輸入，請將內容寫入檔案，並在提示中參考檔案路徑，而不是管道傳送它。94 自 Claude Code v2.1.128 起，管道傳送的 stdin 上限為 10MB。如果超過上限，Claude Code 會以清晰的錯誤和非零狀態代碼退出。若要處理更大的輸入，請將內容寫入檔案，並在提示中參考檔案路徑，而不是管道傳送它。

163claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages163claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

164```164```

165 165

166串流的最後一行是包含最終回應文字、成本和工作階段中繼資料的 `result` 訊息。{/* min-version: 2.1.208 */}在 v2.1.208 之前，管道傳送大型回應可能會截斷最後一行並省略 `result` 訊息。166串流的最後一行是包含最終回應文字、成本和工作階段中繼資料的 `result` 訊息。在 v2.1.208 之前，管道傳送大型回應可能會截斷最後一行並省略 `result` 訊息。

167 167

168下列範例使用 [jq](https://jqlang.github.io/jq/) 篩選文字差異並僅顯示串流文字。`-r` 旗標輸出原始字串（無引號），`-j` 不帶換行符號的聯結，因此令牌會連續串流：168下列範例使用 [jq](https://jqlang.github.io/jq/) 篩選文字差異並僅顯示串流文字。`-r` 旗標輸出原始字串（無引號），`-j` 不帶換行符號的聯結，因此令牌會連續串流：

169 169

188 188

189`system/init` 事件報告工作階段中繼資料，包括模型、工具、MCP 伺服器和載入的外掛程式。除非設定了啟動事件，否則它是串流中的第一個事件：189`system/init` 事件報告工作階段中繼資料，包括模型、工具、MCP 伺服器和載入的外掛程式。除非設定了啟動事件，否則它是串流中的第一個事件：

190 190

191* `plugin_install` 事件，當設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars) 時。191* `plugin_install` 事件，當設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/zh-TW/env-vars) 時。

192* {/* min-version: 2.1.204 */}[`hook_started`、`hook_progress` 和 `hook_response` 事件](/zh-TW/agent-sdk/typescript#sdkhookstartedmessage)，當設定的 [`SessionStart`](/zh-TW/hooks#sessionstart) 或 [`Setup`](/zh-TW/hooks#setup) hook 執行時。這些會在 hook 產生時串流。Claude Code v2.1.169 至 v2.1.203 在 hook 完成後以一個批次傳遞它們，仍在 `system/init` 之前；v2.1.204 恢復了即時傳遞。192* [`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 恢復了即時傳遞。

193 193

194該事件也包含一個選用的 `capabilities` 字串陣列，命名此 Claude Code 版本實施的協定行為，例如 `interrupt_receipt_v1`。檢查它以進行功能偵測，而不是比較版本字串，並忽略您不認識的值。該欄位需要 Claude Code v2.1.205 或更新版本，在較早版本中不存在。請參閱 [`SDKSystemMessage`](/zh-TW/agent-sdk/typescript#sdksystemmessage) 以取得功能清單。194該事件也包含一個選用的 `capabilities` 字串陣列，命名此 Claude Code 版本實施的協定行為，例如 `interrupt_receipt_v1`。檢查它以進行功能偵測，而不是比較版本字串，並忽略您不認識的值。該欄位需要 Claude Code v2.1.205 或更新版本，在較早版本中不存在。請參閱 [`SDKSystemMessage`](/docs/zh-TW/agent-sdk/typescript#sdksystemmessage) 以取得功能清單。

195 195

196使用外掛程式欄位在外掛程式未載入時使 CI 失敗：196使用外掛程式欄位在外掛程式未載入時使 CI 失敗：

197 197

200| `plugins` | 陣列 | 成功載入的外掛程式，每個都有 `name` 和 `path` |200| `plugins` | 陣列 | 成功載入的外掛程式，每個都有 `name` 和 `path` |

201| `plugin_errors` | 陣列 | 外掛程式載入時間錯誤，每個都有 `plugin`、`type` 和 `message`。包括不滿足的相依性版本和 `--plugin-dir` 載入失敗，例如遺失的路徑或無效的封存。受影響的外掛程式被降級並從 `plugins` 中缺失。當沒有錯誤時，金鑰被省略 |201| `plugin_errors` | 陣列 | 外掛程式載入時間錯誤，每個都有 `plugin`、`type` 和 `message`。包括不滿足的相依性版本和 `--plugin-dir` 載入失敗，例如遺失的路徑或無效的封存。受影響的外掛程式被降級並從 `plugins` 中缺失。當沒有錯誤時，金鑰被省略 |

202 202

203當設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars) 時，Claude Code 在第一次轉換前發出 `system/plugin_install` 事件，同時市場外掛程式安裝。使用這些在您自己的 UI 中顯示安裝進度。203當設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/zh-TW/env-vars) 時，Claude Code 在第一次轉換前發出 `system/plugin_install` 事件，同時市場外掛程式安裝。使用這些在您自己的 UI 中顯示安裝進度。

204 204

205| 欄位 | 類型 | 描述 |205| 欄位 | 類型 | 描述 |

206| ------------ | ---------------------------------------------------- | ------------------------------------------------------------ |206| ------------ | ---------------------------------------------------- | ------------------------------------------------------------ |

212| `uuid` | 字串 | 唯一事件識別碼 |212| `uuid` | 字串 | 唯一事件識別碼 |

213| `session_id` | 字串 | 事件所屬的工作階段 |213| `session_id` | 字串 | 事件所屬的工作階段 |

214 214

215如需具有回呼和訊息物件的程式化串流，請參閱 Agent SDK 文件中的 [即時串流回應](/zh-TW/agent-sdk/streaming-output)。215如需具有回呼和訊息物件的程式化串流，請參閱 Agent SDK 文件中的 [即時串流回應](/docs/zh-TW/agent-sdk/streaming-output)。

216 216

217<h3 id="auto-approve-tools">217<h3 id="auto-approve-tools">

218 自動核准工具218 自動核准工具

225 --allowedTools "Bash,Read,Edit"225 --allowedTools "Bash,Read,Edit"

226```226```

227 227

228若要為整個工作階段設定基準而不是列出個別工具，請傳遞 [權限模式](/zh-TW/permission-modes)。`dontAsk` 拒絕 `permissions.allow` 規則或 [唯讀命令集](/zh-TW/permissions#read-only-commands) 中未包含的任何內容，這對於鎖定的 CI 執行很有用。`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使當允許規則符合時也被拒絕。228若要為整個工作階段設定基準而不是列出個別工具，請傳遞 [權限模式](/docs/zh-TW/permission-modes)。`dontAsk` 拒絕 `permissions.allow` 規則或 [唯讀命令集](/docs/zh-TW/permissions#read-only-commands) 中未包含的任何內容，這對於鎖定的 CI 執行很有用。`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使當允許規則符合時也被拒絕。

229 229

230`acceptEdits` 讓 Claude 寫入檔案而無需提示，也自動核准常見的檔案系統命令，例如 `mkdir`、`touch`、`mv` 和 `cp`。其他 shell 命令和網路請求仍然需要 `--allowedTools` 項目或 `permissions.allow` 規則，否則當嘗試執行時執行會中止：230`acceptEdits` 讓 Claude 寫入檔案而無需提示，也自動核准常見的檔案系統命令，例如 `mkdir`、`touch`、`mv` 和 `cp`。其他 shell 命令和網路請求仍然需要 `--allowedTools` 項目或 `permissions.allow` 規則，否則當嘗試執行時執行會中止：

231 231

244 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"244 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

245```245```

246 246

247`--allowedTools` 旗標使用 [權限規則語法](/zh-TW/settings#permission-rule-syntax)。尾部的 ` *` 啟用前綴匹配，因此 `Bash(git diff *)` 允許任何以 `git diff` 開頭的命令。空格在 `*` 之前很重要：沒有它，`Bash(git diff*)` 也會符合 `git diff-index`。247`--allowedTools` 旗標使用 [權限規則語法](/docs/zh-TW/settings#permission-rule-syntax)。尾部的 ` *` 啟用前綴匹配，因此 `Bash(git diff *)` 允許任何以 `git diff` 開頭的命令。空格在 `*` 之前很重要：沒有它，`Bash(git diff*)` 也會符合 `git diff-index`。

248 248

249<Note>249<Note>

250 使用者叫用的 [skills](/zh-TW/skills) 和自訂命令在 `-p` 模式中運作：在提示字串中包含 `/skill-name`，Claude Code 會在執行前展開它。開啟互動對話的內建命令，例如 `/login`，在 `-p` 模式中不可用。{/* min-version: 2.1.205 */}`/model`、`/effort`、`/fast`、`/color` 和 `/rename` 接受值作為引數，例如 `/model sonnet`，`/mcp` 不帶引數會列印伺服器狀態的文字摘要；這些形式需要 Claude Code v2.1.205 或更新版本，並遵循每個命令的 [可用性注意事項](/zh-TW/commands#all-commands)。{/* min-version: 2.1.181 */}若要從 `-p` 叫用變更設定，請將 `key=value` 傳遞至 `/config`，例如 `/config thinking=false`。250 使用者叫用的 [skills](/docs/zh-TW/skills) 和自訂命令在 `-p` 模式中運作：在提示字串中包含 `/skill-name`，Claude Code 會在執行前展開它。開啟互動對話的內建命令，例如 `/login`，在 `-p` 模式中不可用。`/model`、`/effort`、`/fast`、`/color` 和 `/rename` 接受值作為引數，例如 `/model sonnet`，`/mcp` 不帶引數會列印伺服器狀態的文字摘要；這些形式需要 Claude Code v2.1.205 或更新版本，並遵循每個命令的 [可用性注意事項](/docs/zh-TW/commands#all-commands)。若要從 `-p` 叫用變更設定，請將 `key=value` 傳遞至 `/config`，例如 `/config thinking=false`。

251</Note>251</Note>

252 252

253<h3 id="customize-the-system-prompt">253<h3 id="customize-the-system-prompt">

262 --output-format json262 --output-format json

263```263```

264 264

265請參閱 [系統提示旗標](/zh-TW/cli-reference#system-prompt-flags) 以取得更多選項，包括 `--system-prompt` 以完全取代預設提示。265請參閱 [系統提示旗標](/docs/zh-TW/cli-reference#system-prompt-flags) 以取得更多選項，包括 `--system-prompt` 以完全取代預設提示。

266 266

267<h3 id="continue-conversations">267<h3 id="continue-conversations">

268 繼續對話268 繼續對話

286claude -p "Continue that review" --resume "$session_id"286claude -p "Continue that review" --resume "$session_id"

287```287```

288 288

289從同一目錄執行兩個命令：工作階段 ID 查詢的範圍限於目前專案目錄及其 git worktrees。請參閱 [繼續工作階段](/zh-TW/sessions#resume-a-session) 以取得完整的範圍規則。289從同一目錄執行兩個命令：工作階段 ID 查詢的範圍限於目前專案目錄及其 git worktrees。請參閱 [繼續工作階段](/docs/zh-TW/sessions#resume-a-session) 以取得完整的範圍規則。

290 290

291<h2 id="next-steps">291<h2 id="next-steps">

292 後續步驟292 後續步驟

293</h2>293</h2>

294 294

295* [Agent SDK 快速入門](/zh-TW/agent-sdk/quickstart)：使用 Python 或 TypeScript 建立您的第一個 agent295* [Agent SDK 快速入門](/docs/zh-TW/agent-sdk/quickstart)：使用 Python 或 TypeScript 建立您的第一個 agent

296* [CLI 參考](/zh-TW/cli-reference)：所有 CLI 旗標和選項296* [CLI 參考](/docs/zh-TW/cli-reference)：所有 CLI 旗標和選項

297* [GitHub Actions](/zh-TW/github-actions)：在 GitHub 工作流程中使用 Agent SDK297* [GitHub Actions](/docs/zh-TW/github-actions)：在 GitHub 工作流程中使用 Agent SDK

298* [GitLab CI/CD](/zh-TW/gitlab-ci-cd)：在 GitLab 管道中使用 Agent SDK298* [GitLab CI/CD](/docs/zh-TW/gitlab-ci-cd)：在 GitLab 管道中使用 Agent SDK

hooks.md +9 −9

Details

326 326

327所有匹配的 hooks 並行執行，相同的處理程式會自動去重。命令 hooks 按命令字串和 `args` 去重，HTTP hooks 按 URL 去重。327所有匹配的 hooks 並行執行，相同的處理程式會自動去重。命令 hooks 按命令字串和 `args` 去重，HTTP hooks 按 URL 去重。

328 328

329處理程式在目前目錄中執行，使用 Claude Code 的環境。在遠端網路環境中，`$CLAUDE_CODE_REMOTE` 環境變數設定為 `"true"`，在本機 CLI 中未設定。{/* min-version: 2.1.199 */}自 v2.1.199 起，[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/zh-TW/env-vars) 設定為 [Remote Control](/docs/zh-TW/remote-control) 工作階段 ID，而本機工作階段具有活動的 Remote Control 連接。329處理程式在目前目錄中執行，使用 Claude Code 的環境。在遠端網路環境中，`$CLAUDE_CODE_REMOTE` 環境變數設定為 `"true"`，在本機 CLI 中未設定。自 v2.1.199 起，[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/zh-TW/env-vars) 設定為 [Remote Control](/docs/zh-TW/remote-control) 工作階段 ID，而本機工作階段具有活動的 Remote Control 連接。

330 330

331<h4 id="common-fields">331<h4 id="common-fields">

332 通用欄位332 通用欄位

644| 欄位 | 描述 |644| 欄位 | 描述 |

645| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |645| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

647| `prompt_id` | UUID 識別目前正在處理的使用者提示。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/docs/zh-TW/monitoring-usage#event-correlation-attributes) 相符，因此您可以將 hook 輸出與單一提示的遙測相關聯。在第一個使用者輸入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本 |647| `prompt_id` | UUID 識別目前正在處理的使用者提示。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/docs/zh-TW/monitoring-usage#event-correlation-attributes) 相符，因此您可以將 hook 輸出與單一提示的遙測相關聯。在第一個使用者輸入之前不存在。需要 Claude Code v2.1.196 或更新版本 |

648| `transcript_path` | 對話 JSON 的路徑。成績單檔案以非同步方式寫入，可能滯後於記憶體中的對話，因此當 hook 觸發時，它可能尚未包含目前回合的最新訊息。需要目前回合最後助手文字的 Hooks 應在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是讀取成績單 |648| `transcript_path` | 對話 JSON 的路徑。成績單檔案以非同步方式寫入，可能滯後於記憶體中的對話，因此當 hook 觸發時，它可能尚未包含目前回合的最新訊息。需要目前回合最後助手文字的 Hooks 應在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是讀取成績單 |

649| `cwd` | 叫用 hook 時的目前工作目錄 |649| `cwd` | 叫用 hook 時的目前工作目錄 |

650| `permission_mode` | 目前 [權限模式](/docs/zh-TW/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。標記為**手動**的模式以 `"default"` 到達，永遠不會以 `"manual"` 到達，因此匹配 `"default"` 的指令碼繼續工作。並非所有事件都接收此欄位。檢查每個 [hook 事件](#hook-events) 部分中的 JSON 範例 |650| `permission_mode` | 目前 [權限模式](/docs/zh-TW/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。標記為**手動**的模式以 `"default"` 到達，永遠不會以 `"manual"` 到達，因此匹配 `"default"` 的指令碼繼續工作。並非所有事件都接收此欄位。檢查每個 [hook 事件](#hook-events) 部分中的 JSON 範例 |

1569在 `PostToolUse` 中，已完成的 Agent 呼叫的 `tool_response` 攜帶 subagent 的最終文字以及使用量遙測。讀取這些欄位以從 hook 記錄每個 subagent 的成本：1569在 `PostToolUse` 中，已完成的 Agent 呼叫的 `tool_response` 攜帶 subagent 的最終文字以及使用量遙測。讀取這些欄位以從 hook 記錄每個 subagent 的成本：

1570 1570

1571| 欄位 | 類型 | 範例 | 描述 |1571| 欄位 | 類型 | 範例 | 描述 |

1572| :------------------ | :- | :---------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1572| :------------------ | :- | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |

1573| `status` | 字串 | `"completed"` | 前景 subagents 為 `"completed"`，背景 subagents 為 `"async_launched"`。{/* min-version: 2.1.198 */}從 v2.1.198 開始，subagents 預設在背景執行，因此省略的 `run_in_background` 也會產生 `"async_launched"` |1573| `status` | 字串 | `"completed"` | 前景 subagents 為 `"completed"`，背景 subagents 為 `"async_launched"`。從 v2.1.198 開始，subagents 預設在背景執行，因此省略的 `run_in_background` 也會產生 `"async_launched"` |

1575| `content` | 陣列 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent 的最終文字塊 |1575| `content` | 陣列 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent 的最終文字塊 |

1576| `resolvedModel` | 字串 | `"claude-sonnet-4-5"` | subagent 執行的模型，可能與請求的模型不同。{/* min-version: 2.1.174 */}需要 Claude Code v2.1.174 或更高版本 |1576| `resolvedModel` | 字串 | `"claude-sonnet-4-5"` | subagent 執行的模型，可能與請求的模型不同。需要 Claude Code v2.1.174 或更高版本 |

1577| `totalTokens` | 數字 | `12450` | 在 subagent 轉向中計費的總令牌數 |1577| `totalTokens` | 數字 | `12450` | 在 subagent 轉向中計費的總令牌數 |

1578| `totalDurationMs` | 數字 | `48211` | subagent 執行的掛鐘時間 |1578| `totalDurationMs` | 數字 | `48211` | subagent 執行的掛鐘時間 |

1579| `totalToolUseCount` | 數字 | `7` | subagent 進行的工具呼叫計數 |1579| `totalToolUseCount` | 數字 | `7` | subagent 進行的工具呼叫計數 |

1603呈現一個計劃並要求使用者在 Claude 離開 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在呼叫工具之前將計劃寫入磁碟上的檔案，因此模型的字面 `tool_input` 通常為空。Claude Code 在將輸入傳遞給 hooks 之前注入計劃內容和檔案路徑。1603呈現一個計劃並要求使用者在 Claude 離開 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在呼叫工具之前將計劃寫入磁碟上的檔案，因此模型的字面 `tool_input` 通常為空。Claude Code 在將輸入傳遞給 hooks 之前注入計劃內容和檔案路徑。

1604 1604

1605| 欄位 | 類型 | 範例 | 描述 |1605| 欄位 | 類型 | 範例 | 描述 |

1606| :--------------- | :- | :------------------------------------------ | :-------------------------------------------------------------------------------------------- |1606| :--------------- | :- | :------------------------------------------ | :---------------------------------------------------------------- |

1609| `allowedPrompts` | 陣列 | `[{"tool": "Bash", "prompt": "run tests"}]` | {/* min-version: 2.1.205 */}已棄用。Claude Code 接受該欄位但忽略它。在 v2.1.205 之前，它攜帶 Claude 要求實施計劃的基於提示的權限 |1609| `allowedPrompts` | 陣列 | `[{"tool": "Bash", "prompt": "run tests"}]` | 已棄用。Claude Code 接受該欄位但忽略它。在 v2.1.205 之前，它攜帶 Claude 要求實施計劃的基於提示的權限 |

1610 1610

1611在 `PostToolUse` 中，`tool_response` 是一個物件，其中包含 `plan` 和 `filePath` 欄位，保存批准的計劃，加上內部狀態標誌。讀取 `tool_response.plan` 以獲取計劃內容，而不是從磁碟重新讀取檔案。1611在 `PostToolUse` 中，`tool_response` 是一個物件，其中包含 `plan` 和 `filePath` 欄位，保存批准的計劃，加上內部狀態標誌。讀取 `tool_response.plan` 以獲取計劃內容，而不是從磁碟重新讀取檔案。

1612 1612

1763`updatedPermissions` 輸出欄位和 [`permission_suggestions` 輸入欄位](#permissionrequest-input) 都使用相同的項目物件陣列。每個項目都有一個 `type` 決定其他欄位，以及一個 `destination` 控制變更寫入位置。1763`updatedPermissions` 輸出欄位和 [`permission_suggestions` 輸入欄位](#permissionrequest-input) 都使用相同的項目物件陣列。每個項目都有一個 `type` 決定其他欄位，以及一個 `destination` 控制變更寫入位置。

1764 1764

1765| `type` | 欄位 | 效果 |1765| `type` | 欄位 | 效果 |

1766| :------------------ | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1766| :------------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |

1767| `addRules` | `rules`、`behavior`、`destination` | 新增權限規則。`rules` 是 `{toolName, ruleContent?}` 物件的陣列。省略 `ruleContent` 以匹配整個工具。`behavior` 是 `"allow"`、`"deny"` 或 `"ask"` |1767| `addRules` | `rules`、`behavior`、`destination` | 新增權限規則。`rules` 是 `{toolName, ruleContent?}` 物件的陣列。省略 `ruleContent` 以匹配整個工具。`behavior` 是 `"allow"`、`"deny"` 或 `"ask"` |

1770| `setMode` | `mode`、`destination` | 變更權限模式。有效模式為 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan` 和 {/* min-version: 2.1.200 */}`manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本 |1770| `setMode` | `mode`、`destination` | 變更權限模式。有效模式為 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan` 和 `manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本 |

1773 1773

interactive-mode.md +43 −43

Details

11</h2>11</h2>

12 12

13<Note>13<Note>

~~14 鍵盤快捷鍵可能因平台和終端而異。在[全螢幕渲染](/zh-TW/fullscreen)中，在文字記錄檢視器中按 `?` 以查看可用的快捷鍵。~~14 鍵盤快捷鍵可能因平台和終端而異。在[全螢幕渲染](/docs/zh-TW/fullscreen)中，在文字記錄檢視器中按 `?` 以查看可用的快捷鍵。

15 15

16 **macOS 使用者**：Option/Alt 鍵快捷鍵（`Alt+B`、`Alt+F`、`Alt+Y`、`Alt+M`、`Alt+P`）需要在終端中將 Option 配置為 Meta：16 **macOS 使用者**：Option/Alt 鍵快捷鍵（`Alt+B`、`Alt+F`、`Alt+Y`、`Alt+M`、`Alt+P`）需要在終端中將 Option 配置為 Meta：

17 17

19 * **Apple Terminal**：設定 → Profiles → Keyboard → 勾選「Use Option as Meta Key」19 * **Apple Terminal**：設定 → Profiles → Keyboard → 勾選「Use Option as Meta Key」

20 * **VS Code**：在 VS Code 設定中設定 `"terminal.integrated.macOptionIsMeta": true`20 * **VS Code**：在 VS Code 設定中設定 `"terminal.integrated.macOptionIsMeta": true`

21 21

~~22 詳見[終端配置](/zh-TW/terminal-config)。~~22 詳見[終端配置](/docs/zh-TW/terminal-config)。

23</Note>23</Note>

24 24

25<h3 id="general-controls">25<h3 id="general-controls">

27</h3>27</h3>

28 28

29| 快捷鍵 | 說明 | 上下文 |29| 快捷鍵 | 說明 | 上下文 |

30| :------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |30| :------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |

34| `Ctrl+G` 或 `Ctrl+X Ctrl+E` | 在預設文字編輯器中開啟 | 在預設文字編輯器中編輯您的提示或自訂回應。`Ctrl+X Ctrl+E` 是 readline 原生繫結。在 `/config` 中開啟「在外部編輯器中顯示最後回應」，以在您的提示上方將 Claude 的先前回覆作為 `#` 註解上下文預先加入；當您儲存時，註解區塊會被移除 |34| `Ctrl+G` 或 `Ctrl+X Ctrl+E` | 在預設文字編輯器中開啟 | 在預設文字編輯器中編輯您的提示或自訂回應。`Ctrl+X Ctrl+E` 是 readline 原生繫結。在 `/config` 中開啟「在外部編輯器中顯示最後回應」，以在您的提示上方將 Claude 的先前回覆作為 `#` 註解上下文預先加入；當您儲存時，註解區塊會被移除 |

42| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移動游標或導航命令歷史 | 當輸入跨越多個視覺行時，無論是換行還是多行，首先在提示內移動游標。一旦游標已在第一個或最後一個視覺行，再次按下會導航命令歷史。{/* min-version: 2.1.169 */}自 v2.1.169 起，換行的單行輸入行為與多行相同 |42| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移動游標或導航命令歷史 | 當輸入跨越多個視覺行時，無論是換行還是多行，首先在提示內移動游標。一旦游標已在第一個或最後一個視覺行，再次按下會導航命令歷史。自 v2.1.169 起，換行的單行輸入行為與多行相同 |

43| `Esc` | 中斷 Claude，或關閉對話框 | 停止目前回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作。當對話框（例如權限提示）開啟時，`Esc` 會關閉對話框，而不是中斷 Claude。{/* min-version: 2.1.202 */}在 v2.1.202 之前，某些對話框上的 `Esc` 會中斷 Claude 並保持對話框開啟 |43| `Esc` | 中斷 Claude，或關閉對話框 | 停止目前回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作。當對話框（例如權限提示）開啟時，`Esc` 會關閉對話框，而不是中斷 Claude。在 v2.1.202 之前，某些對話框上的 `Esc` 會中斷 Claude 並保持對話框開啟 |

45| `Shift+Tab` 或 `Alt+M`（某些配置） | 循環權限模式 | 在 `default`（在模式指示器中標記為 Manual）、`acceptEdits`、`plan` 和您啟用的任何模式（例如 `auto` 或 `bypassPermissions`）之間循環。詳見[權限模式](/zh-TW/permission-modes)。 |45| `Shift+Tab` 或 `Alt+M`（某些配置） | 循環權限模式 | 在 `default`（在模式指示器中標記為 Manual）、`acceptEdits`、`plan` 和您啟用的任何模式（例如 `auto` 或 `bypassPermissions`）之間循環。詳見[權限模式](/docs/zh-TW/permission-modes)。 |

47| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切換擴展思考 | 啟用或停用擴展思考模式。在 Fable 5 上無效，其始終使用擴展思考。{/* min-version: 2.1.132 */}自 v2.1.132 起，此快捷鍵在 macOS 上無需配置 Option 為 Meta 即可運作 |47| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切換擴展思考 | 啟用或停用擴展思考模式。在 Fable 5 上無效，其始終使用擴展思考。自 v2.1.132 起，此快捷鍵在 macOS 上無需配置 Option 為 Meta 即可運作 |

49 49

50<h3 id="text-editing">50<h3 id="text-editing">

51 文字編輯51 文字編輯

78| 方法 | 快捷鍵 | 上下文 |78| 方法 | 快捷鍵 | 上下文 |

79| :---------- | :------------- | :------------------------------------------------------------------------------------------- |79| :---------- | :------------- | :------------------------------------------------------------------------------------------- |

93 93

94| 快捷鍵 | 說明 | 備註 |94| 快捷鍵 | 說明 | 備註 |

95| :------ | :-------- | :----------------------------------------- |95| :------ | :-------- | :----------------------------------------- |

~~96| `/` 在開始 | 命令或 skill | 詳見[命令](#commands)和 [skills](/zh-TW/skills) |~~96| `/` 在開始 | 命令或 skill | 詳見[命令](#commands)和 [skills](/docs/zh-TW/skills) |

97| `!` 在開始 | Bash 模式 | 直接執行命令並將執行輸出新增到會話 |97| `!` 在開始 | Bash 模式 | 直接執行命令並將執行輸出新增到會話 |

98| `@` | 檔案路徑提及 | 觸發檔案路徑自動完成 |98| `@` | 檔案路徑提及 | 觸發檔案路徑自動完成 |

99 99

101 文字記錄檢視器101 文字記錄檢視器

102</h3>102</h3>

103 103

104當文字記錄檢視器開啟時（使用 `Ctrl+O` 切換），這些快捷鍵可用。在[全螢幕渲染](/zh-TW/fullscreen)中，按 `?` 以在檢視器內顯示完整的快捷鍵參考面板。`Ctrl+E` 可以透過 [`transcript:toggleShowAll`](/zh-TW/keybindings) 重新繫結。104當文字記錄檢視器開啟時（使用 `Ctrl+O` 切換），這些快捷鍵可用。在[全螢幕渲染](/docs/zh-TW/fullscreen)中，按 `?` 以在檢視器內顯示完整的快捷鍵參考面板。`Ctrl+E` 可以透過 [`transcript:toggleShowAll`](/docs/zh-TW/keybindings) 重新繫結。

105 105

106| 快捷鍵 | 說明 |106| 快捷鍵 | 說明 |

107| :----------------- | :---------------------------------------------------------------------------------------------------------------- |107| :----------------- | :---------------------------------------------------------------------------------------------------------------- |

108| `?` | 切換鍵盤快捷鍵說明面板。需要[全螢幕渲染](/zh-TW/fullscreen) |108| `?` | 切換鍵盤快捷鍵說明面板。需要[全螢幕渲染](/docs/zh-TW/fullscreen) |

109| `{` / `}` | 跳至上一個或下一個使用者提示，類似 vim 段落動作。需要[全螢幕渲染](/zh-TW/fullscreen) |109| `{` / `}` | 跳至上一個或下一個使用者提示，類似 vim 段落動作。需要[全螢幕渲染](/docs/zh-TW/fullscreen) |

111| `[` | 將完整對話寫入終端的原生滾動回溯，以便 `Cmd+F`、tmux 複製模式和其他原生工具可以搜尋它。需要[全螢幕渲染](/zh-TW/fullscreen#search-and-review-the-conversation) |111| `[` | 將完整對話寫入終端的原生滾動回溯，以便 `Cmd+F`、tmux 複製模式和其他原生工具可以搜尋它。需要[全螢幕渲染](/docs/zh-TW/fullscreen#search-and-review-the-conversation) |

112| `v` | 將對話寫入臨時檔案並在 `$VISUAL` 或 `$EDITOR` 中開啟它。需要[全螢幕渲染](/zh-TW/fullscreen) |112| `v` | 將對話寫入臨時檔案並在 `$VISUAL` 或 `$EDITOR` 中開啟它。需要[全螢幕渲染](/docs/zh-TW/fullscreen) |

114 114

115<h3 id="voice-input">115<h3 id="voice-input">

116 語音輸入116 語音輸入

118 118

119| 快捷鍵 | 說明 | 備註 |119| 快捷鍵 | 說明 | 備註 |

120| :------------ | :--- | :------------------------------------------------------------------------------------------------------------------------- |120| :------------ | :--- | :------------------------------------------------------------------------------------------------------------------------- |

122 122

123<h2 id="commands">123<h2 id="commands">

124 命令124 命令

125</h2>125</h2>

126 126

127在 Claude Code 中輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟任何字母以篩選。`/` 選單顯示您可以呼叫的所有內容：內建命令、捆綁和使用者撰寫的 [skills](/zh-TW/skills)，以及由 [plugins](/zh-TW/plugins) 和 [MCP servers](/zh-TW/mcp#use-mcp-prompts-as-commands) 貢獻的命令。並非所有內建命令對每個使用者都可見，因為某些命令取決於您的平台或計畫。127在 Claude Code 中輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟任何字母以篩選。`/` 選單顯示您可以呼叫的所有內容：內建命令、捆綁和使用者撰寫的 [skills](/docs/zh-TW/skills)，以及由 [plugins](/docs/zh-TW/plugins) 和 [MCP servers](/docs/zh-TW/mcp#use-mcp-prompts-as-commands) 貢獻的命令。並非所有內建命令對每個使用者都可見，因為某些命令取決於您的平台或計畫。

128 128

129在[全螢幕呈現](/zh-TW/fullscreen#use-the-mouse)中，`/` 命令和 `@` 檔案建議清單也會回應滑鼠：懸停會反白顯示一列，點擊會接受它。129在[全螢幕呈現](/docs/zh-TW/fullscreen#use-the-mouse)中，`/` 命令和 `@` 檔案建議清單也會回應滑鼠：懸停會反白顯示一列，點擊會接受它。

130 130

131詳見[命令參考](/zh-TW/commands)以取得 Claude Code 中包含的命令的完整清單。131詳見[命令參考](/docs/zh-TW/commands)以取得 Claude Code 中包含的命令的完整清單。

132 132

133<h2 id="vim-editor-mode">133<h2 id="vim-editor-mode">

134 Vim 編輯器模式134 Vim 編輯器模式

156 重新對應 INSERT 模式快捷鍵序列156 重新對應 INSERT 模式快捷鍵序列

157</h3>157</h3>

158 158

159[`vimInsertModeRemaps`](/zh-TW/settings#available-settings) 設定會將兩個按鍵的 INSERT 模式序列對應到 Escape，因此像 `jj` 這樣的對應會讓您回到 NORMAL 模式。{/* min-version: 2.1.208 */}需要 Claude Code v2.1.208 或更新版本。159[`vimInsertModeRemaps`](/docs/zh-TW/settings#available-settings) 設定會將兩個按鍵的 INSERT 模式序列對應到 Escape，因此像 `jj` 這樣的對應會讓您回到 NORMAL 模式。需要 Claude Code v2.1.208 或更新版本。

160 160

161以下 `~/.claude/settings.json` 範例會開啟 vim 模式並將 `jj` 對應到 Escape：161以下 `~/.claude/settings.json` 範例會開啟 vim 模式並將 `jj` 對應到 Escape：

162 162

171 171

172輸入序列的第一個字元會正常插入。在一秒內按下第二個字元會移除該待處理字元並切換到 NORMAL 模式，在您的輸入中不留下任何字元。在一秒視窗之後，或如果按下不同的鍵，兩個字元都會保留為字面文字，因此您仍然可以透過在兩個鍵之間暫停來輸入包含該序列的單字。172輸入序列的第一個字元會正常插入。在一秒內按下第二個字元會移除該待處理字元並切換到 NORMAL 模式，在您的輸入中不留下任何字元。在一秒視窗之後，或如果按下不同的鍵，兩個字元都會保留為字面文字，因此您仍然可以透過在兩個鍵之間暫停來輸入包含該序列的單字。

173 173

174Claude Code 只會從您的使用者設定檔案、`--settings` 旗標和[受管設定](/zh-TW/permissions#managed-settings)讀取此設定。專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目會被忽略，因此簽出的儲存庫無法重新對應您的按鍵。174Claude Code 只會從您的使用者設定檔案、`--settings` 旗標和[受管設定](/docs/zh-TW/permissions#managed-settings)讀取此設定。專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目會被忽略，因此簽出的儲存庫無法重新對應您的按鍵。

175 175

176<h3 id="navigation-normal-mode">176<h3 id="navigation-normal-mode">

177 導航（NORMAL 模式）177 導航（NORMAL 模式）

178</h3>178</h3>

179 179

180| 命令 | 動作 |180| 命令 | 動作 |

181| :-------------- | :------------------------------------------------------------------------------------------------------- |181| :-------------- | :--------------------------------------------------------------------------- |

184| `w` | 下一個單字 |184| `w` | 下一個單字 |

195| `T{char}` | 跳到上一個字元出現位置之後 |195| `T{char}` | 跳到上一個字元出現位置之後 |

196| `;` | 重複上一個 f/F/t/T 動作 |196| `;` | 重複上一個 f/F/t/T 動作 |

197| `,` | 反向重複上一個 f/F/t/T 動作 |197| `,` | 反向重複上一個 f/F/t/T 動作 |

198| `/` | 開啟反向歷史搜尋，與 `Ctrl+R` 相同。{/* min-version: 2.1.191 */}自 v2.1.191 起，空搜尋提示會顯示提示：按 `Esc` 然後 `i` 然後 `/` 以開啟命令選單 |198| `/` | 開啟反向歷史搜尋，與 `Ctrl+R` 相同。自 v2.1.191 起，空搜尋提示會顯示提示：按 `Esc` 然後 `i` 然後 `/` 以開啟命令選單 |

199 199

200<Note>200<Note>

201 在 vim 正常模式中，如果游標位於輸入的開始或結尾且無法進一步移動，`j`/`k` 和箭頭鍵將導航命令歷史。201 在 vim 正常模式中，如果游標位於輸入的開始或結尾且無法進一步移動，`j`/`k` 和箭頭鍵將導航命令歷史。

316 316

317* 輸出被寫入檔案，Claude 可以使用 Read 工具檢索它317* 輸出被寫入檔案，Claude 可以使用 Read 工具檢索它

318* 背景工作有唯一的 ID 用於追蹤和輸出檢索318* 背景工作有唯一的 ID 用於追蹤和輸出檢索

319* 背景工作在 Claude Code 退出時會自動清理。將工作階段背景執行而不是退出會將它們交給背景工作階段，它們會繼續執行。請參閱[背景執行執行中的工作階段](/zh-TW/agent-view#from-inside-a-session)319* 背景工作在 Claude Code 退出時會自動清理。將工作階段背景執行而不是退出會將它們交給背景工作階段，它們會繼續執行。請參閱[背景執行執行中的工作階段](/docs/zh-TW/agent-view#from-inside-a-session)

320* 如果輸出超過 5GB，背景工作會自動終止，stderr 中會有說明原因的備註320* 如果輸出超過 5GB，背景工作會自動終止，stderr 中會有說明原因的備註

321* {/* min-version: 2.1.193 */}自 v2.1.193 起，在 macOS 和 Linux 上，當作業系統發出記憶體壓力信號時，執行中的背景工作會被終止，前提是工作階段已閒置至少 30 分鐘，沒有任何轉換或子代理執行。將 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/zh-TW/env-vars) 設定為 `1` 以關閉此功能321* 自 v2.1.193 起，在 macOS 和 Linux 上，當作業系統發出記憶體壓力信號時，執行中的背景工作會被終止，前提是工作階段已閒置至少 30 分鐘，沒有任何轉換或子代理執行。將 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/zh-TW/env-vars) 設定為 `1` 以關閉此功能

322 322

323若要停用所有背景工作功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。詳見[環境變數](/zh-TW/env-vars)。323若要停用所有背景工作功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。詳見[環境變數](/docs/zh-TW/env-vars)。

324 324

325**常見的背景執行命令：**325**常見的背景執行命令：**

326 326

349* 支援相同的 `Ctrl+B` 背景執行，用於長時間執行的命令349* 支援相同的 `Ctrl+B` 背景執行，用於長時間執行的命令

350* 不需要 Claude 解釋或批准命令350* 不需要 Claude 解釋或批准命令

351* 支援基於歷史的自動完成：輸入部分命令並按 `Tab` 以從目前專案中的先前 `!` 命令完成351* 支援基於歷史的自動完成：輸入部分命令並按 `Tab` 以從目前專案中的先前 `!` 命令完成

352* {/* min-version: 2.1.193 */}自 v2.1.193 起在所有平台上支援即時檔案路徑自動完成：輸入包含正斜線的權杖，例如 `./src/` 或 `~/`，以查看符合的檔案和目錄的下拉清單，然後按 `Tab` 以接受。在 Windows 上也使用正斜線；下拉清單由 `/` 觸發，而不是 `\`352* 自 v2.1.193 起在所有平台上支援即時檔案路徑自動完成：輸入包含正斜線的權杖，例如 `./src/` 或 `~/`，以查看符合的檔案和目錄的下拉清單，然後按 `Tab` 以接受。在 Windows 上也使用正斜線；下拉清單由 `/` 觸發，而不是 `\`

353* 在空提示上使用 `Escape`、`Backspace` 或 `Ctrl+U` 退出353* 在空提示上使用 `Escape`、`Backspace` 或 `Ctrl+U` 退出

354* 將以 `!` 開頭的貼上文字貼到空提示中會自動進入 shell 模式，符合輸入的 `!` 行為354* 將以 `!` 開頭的貼上文字貼到空提示中會自動進入 shell 模式，符合輸入的 `!` 行為

355 355

356自 v2.1.186 起，Claude 會在命令輸出進入文字記錄後自動回應，因此您可以執行 `! npm test` 並獲得失敗的說明，無需第二個提示。回應成本與傳送一般提示相同。若要恢復先前的行為，其中輸出被新增到上下文而不進行回應，請在 `settings.json` 中將 [`respondToBashCommands`](/zh-TW/settings#available-settings) 設定為 `false`。在 v2.1.186 之前，shell 模式始終將輸出新增到上下文而不進行回應。356自 v2.1.186 起，Claude 會在命令輸出進入文字記錄後自動回應，因此您可以執行 `! npm test` 並獲得失敗的說明，無需第二個提示。回應成本與傳送一般提示相同。若要恢復先前的行為，其中輸出被新增到上下文而不進行回應，請在 `settings.json` 中將 [`respondToBashCommands`](/docs/zh-TW/settings#available-settings) 設定為 `false`。在 v2.1.186 之前，shell 模式始終將輸出新增到上下文而不進行回應。

357 357

358這對於快速 shell 操作同時維護對話上下文很有用。358這對於快速 shell 操作同時維護對話上下文很有用。

359 359

370 370

371建議作為背景請求執行，該請求重複使用父對話的提示快取，因此額外成本最少。當快取冷時，Claude Code 會跳過建議生成以避免不必要的成本。371建議作為背景請求執行，該請求重複使用父對話的提示快取，因此額外成本最少。當快取冷時，Claude Code 會跳過建議生成以避免不必要的成本。

372 372

373在對話的第一輪之後以及在 Plan Mode 中，建議會自動跳過。在列印模式中，預設情況下它們是關閉的。傳遞 [`--prompt-suggestions`](/zh-TW/cli-reference#cli-flags) 搭配 `--output-format stream-json --verbose` 以在每一輪之後改為發出 `prompt_suggestion` 訊息。373在對話的第一輪之後以及在 Plan Mode 中，建議會自動跳過。在列印模式中，預設情況下它們是關閉的。傳遞 [`--prompt-suggestions`](/docs/zh-TW/cli-reference#cli-flags) 搭配 `--output-format stream-json --verbose` 以在每一輪之後改為發出 `prompt_suggestion` 訊息。

374 374

375若要完全停用提示建議，請設定環境變數或在 `/config` 中切換設定：375若要完全停用提示建議，請設定環境變數或在 `/config` 中切換設定：

376 376

398答案出現後，覆蓋層接受這些按鍵。來自同一會話的較早側面問題會顯示為目前答案上方的淡色列表；它們保持在對話歷史之外，但在覆蓋層中保持可見，直到您清除它們。398答案出現後，覆蓋層接受這些按鍵。來自同一會話的較早側面問題會顯示為目前答案上方的淡色列表；它們保持在對話歷史之外，但在覆蓋層中保持可見，直到您清除它們。

399 399

400| 按鍵 | 動作 |400| 按鍵 | 動作 |

401| :----------------------- | :------------------------------------------------------------------------------------------------------------------- |401| :----------------------- | :------------------------------------------------------------------------------------------------ |

404| `Left` / `Right` | {/* min-version: 2.1.187 */}在此答案和您來自會話的較早 `/btw` 答案之間切換。`Left` 移至較舊的答案，`Right` 返回目前的答案。需要 Claude Code v2.1.187 或更新版本 |404| `Left` / `Right` | 在此答案和您來自會話的較早 `/btw` 答案之間切換。`Left` 移至較舊的答案，`Right` 返回目前的答案。需要 Claude Code v2.1.187 或更新版本 |

405| `c` | 將答案複製到您的剪貼簿作為原始 Markdown。使用此方式而不是滑鼠選取，後者會擷取硬換行的終端機呈現而非原始文字 |405| `c` | 將答案複製到您的剪貼簿作為原始 Markdown。使用此方式而不是滑鼠選取，後者會擷取硬換行的終端機呈現而非原始文字 |

406| `f` | 分支到新會話。分支繼承父對話加上此問題和答案作為真實文字記錄輪次，因此您可以繼續進行完整工具存取。原始會話保留在 [`/resume`](/zh-TW/commands) 下。僅在本機會話中可用 |406| `f` | 分支到新會話。分支繼承父對話加上此問題和答案作為真實文字記錄輪次，因此您可以繼續進行完整工具存取。原始會話保留在 [`/resume`](/docs/zh-TW/commands) 下。僅在本機會話中可用 |

407| `x` | 清除目前答案上方顯示的較早 `/btw` 交換列表 |407| `x` | 清除目前答案上方顯示的較早 `/btw` 交換列表 |

408 408

409`/btw` 是 [subagent](/zh-TW/sub-agents) 的反面：它看到您的完整對話但沒有工具，而 subagent 有完整工具但以空上下文開始。使用 `/btw` 詢問 Claude 從此會話已知的內容；使用 subagent 去發現新的東西。409`/btw` 是 [subagent](/docs/zh-TW/sub-agents) 的反面：它看到您的完整對話但沒有工具，而 subagent 有完整工具但以空上下文開始。使用 `/btw` 詢問 Claude 從此會話已知的內容；使用 subagent 去發現新的東西。

410 410

411<h2 id="task-list">411<h2 id="task-list">

412 工作清單412 工作清單

413</h2>413</h2>

414 414

415工作清單是 Claude 的待辦事項檢查清單：Claude 建立的項目用於規劃多步驟工作，並有指示器顯示待處理、進行中或完成的內容。它與背景工作檢視分開。若要查看執行中的 shell 和子代理，請改用 [`/tasks`](/zh-TW/commands)。415工作清單是 Claude 的待辦事項檢查清單：Claude 建立的項目用於規劃多步驟工作，並有指示器顯示待處理、進行中或完成的內容。它與背景工作檢視分開。若要查看執行中的 shell 和子代理，請改用 [`/tasks`](/docs/zh-TW/commands)。

416 416

417* 按 `Ctrl+T` 以切換工作清單檢視。顯示一次最多五個工作。當 Claude 尚未建立任何檢查清單項目時，切換沒有可見效果，因為沒有任何內容可顯示417* 按 `Ctrl+T` 以切換工作清單檢視。顯示一次最多五個工作。當 Claude 尚未建立任何檢查清單項目時，切換沒有可見效果，因為沒有任何內容可顯示

418* 若要查看所有工作或清除它們，直接詢問 Claude：「show me all tasks」或「clear all tasks」418* 若要查看所有工作或清除它們，直接詢問 Claude：「show me all tasks」或「clear all tasks」

450 另請參閱450 另請參閱

451</h2>451</h2>

452 452

453* [Skills](/zh-TW/skills) - 自訂提示和工作流程453* [Skills](/docs/zh-TW/skills) - 自訂提示和工作流程

454* [Checkpointing](/zh-TW/checkpointing) - 回溯 Claude 的編輯並恢復先前的狀態454* [Checkpointing](/docs/zh-TW/checkpointing) - 回溯 Claude 的編輯並恢復先前的狀態

455* [CLI 參考](/zh-TW/cli-reference) - 命令列旗標和選項455* [CLI 參考](/docs/zh-TW/cli-reference) - 命令列旗標和選項

456* [設定](/zh-TW/settings) - 配置選項456* [設定](/docs/zh-TW/settings) - 配置選項

457* [記憶體管理](/zh-TW/memory) - 管理 CLAUDE.md 檔案457* [記憶體管理](/docs/zh-TW/memory) - 管理 CLAUDE.md 檔案

keybindings.md +12 −12

Details

68| `Plugin` | Plugin 對話框（瀏覽、探索、管理） |68| `Plugin` | Plugin 對話框（瀏覽、探索、管理） |

69| `Scroll` | 對話滾動和全螢幕模式中的文字選擇 |69| `Scroll` | 對話滾動和全螢幕模式中的文字選擇 |

70 70

~~71{/* max-version: 2.1.204 */}在 v2.1.205 之前，`/doctor` 診斷螢幕存在 `Doctor` 上下文和 `doctor:fix` 動作。~~71在 v2.1.205 之前，`/doctor` 診斷螢幕存在 `Doctor` 上下文和 `doctor:fix` 動作。

72 72

73<h2 id="available-actions">73<h2 id="available-actions">

74 可用動作74 可用動作

89| `app:redraw` | (未繫結) | 強制終端機重新繪製 |89| `app:redraw` | (未繫結) | 強制終端機重新繪製 |

92 92

93<h3 id="history-actions">93<h3 id="history-actions">

111| 動作 | 預設值 | 說明 |111| 動作 | 預設值 | 說明 |

112| :-------------------- | :------------------------------ | :---------------------------------------------------------------------------------------- |112| :-------------------- | :------------------------------ | :---------------------------------------------------------------------------------------- |

156| `confirm:previousField` | (未繫結) | 上一個欄位 |156| `confirm:previousField` | (未繫結) | 上一個欄位 |

160 160

161<h3 id="permission-actions">161<h3 id="permission-actions">

162 權限動作162 權限動作

200在 `Task` 上下文中可用的動作：200在 `Task` 上下文中可用的動作：

201 201

202| 動作 | 預設值 | 說明 |202| 動作 | 預設值 | 說明 |

203| :---------------- | :-------------------- | :------------------------------------------------------------------------------------ |203| :---------------- | :-------------------- | :-------------------------------------------------------- |

204| `task:background` | Ctrl+B, Ctrl+X Ctrl+B | 背景執行目前工作。{/* min-version: 2.1.169 */}Ctrl+X Ctrl+B 快捷鍵需要 v2.1.169 或更新版本，並避免 tmux 前綴衝突 |204| `task:background` | Ctrl+B, Ctrl+X Ctrl+B | 背景執行目前工作。Ctrl+X Ctrl+B 快捷鍵需要 v2.1.169 或更新版本，並避免 tmux 前綴衝突 |

205 205

206<h3 id="theme-actions">206<h3 id="theme-actions">

207 主題動作207 主題動作

357 語音動作357 語音動作

358</h3>358</h3>

359 359

360在啟用[語音聽寫](/zh-TW/voice-dictation)時，在 `Chat` 上下文中可用的動作：360在啟用[語音聽寫](/docs/zh-TW/voice-dictation)時，在 `Chat` 上下文中可用的動作：

361 361

362| 動作 | 預設值 | 說明 |362| 動作 | 預設值 | 說明 |

363| :----------------- | :---- | :----------------------- |363| :----------------- | :---- | :----------------------- |

367 滾動動作367 滾動動作

368</h3>368</h3>

369 369

370在啟用[全螢幕渲染](/zh-TW/fullscreen)時，在 `Scroll` 上下文中可用的動作：370在啟用[全螢幕渲染](/docs/zh-TW/fullscreen)時，在 `Scroll` 上下文中可用的動作：

371 371

372| 動作 | 預設值 | 說明 |372| 動作 | 預設值 | 說明 |

373| :-------------------------- | :------------------- | :--------------------------------------------------- |373| :-------------------------- | :------------------- | :--------------------------------------------------- |

526* **快捷鍵**在元件層級處理動作（切換待辦事項、提交等）526* **快捷鍵**在元件層級處理動作（切換待辦事項、提交等）

527* vim 模式中的 Escape 鍵從 INSERT 切換到 NORMAL 模式；它不會觸發 `chat:cancel`527* vim 模式中的 Escape 鍵從 INSERT 切換到 NORMAL 模式；它不會觸發 `chat:cancel`

528* 大多數 Ctrl+鍵快捷鍵通過 vim 模式傳遞到快捷鍵系統528* 大多數 Ctrl+鍵快捷鍵通過 vim 模式傳遞到快捷鍵系統

529* Vim 鍵無法透過快捷鍵檔案重新對應。若要對應兩鍵 INSERT 模式序列（例如 `jj`）至 Escape，請使用 [`vimInsertModeRemaps`](/zh-TW/interactive-mode#remap-insert-mode-key-sequences) 設定529* Vim 鍵無法透過快捷鍵檔案重新對應。若要對應兩鍵 INSERT 模式序列（例如 `jj`）至 Escape，請使用 [`vimInsertModeRemaps`](/docs/zh-TW/interactive-mode#remap-insert-mode-key-sequences) 設定

530* 在 vim NORMAL 模式中，`?` 顯示說明選單（vim 行為）530* 在 vim NORMAL 模式中，`?` 顯示說明選單（vim 行為）

531* 在 vim NORMAL 模式中，`/` 開啟歷史搜尋，與標準模式中的 Ctrl+R 相同531* 在 vim NORMAL 模式中，`/` 開啟歷史搜尋，與標準模式中的 Ctrl+R 相同

532 532

542* 終端機多工器衝突542* 終端機多工器衝突

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

544 544

545Claude Code 在檔案載入時報告警告，並將每個警告寫入偵錯日誌。使用 [`--debug`](/zh-TW/cli-reference#cli-flags) 啟動 Claude Code 以查看詳細資訊。545Claude Code 在檔案載入時報告警告，並將每個警告寫入偵錯日誌。使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動 Claude Code 以查看詳細資訊。

llm-gateway-connect.md +36 −36

Details

6 6

7> 將 Claude Code 指向您組織的 LLM 閘道。檢查您的管理員是否已配置它，或自行設定基礎 URL 和認證，然後驗證連接並修復閘道錯誤。7> 將 Claude Code 指向您組織的 LLM 閘道。檢查您的管理員是否已配置它，或自行設定基礎 URL 和認證，然後驗證連接並修復閘道錯誤。

8 8

9[LLM 閘道](/zh-TW/llm-gateway)是您的組織在 Claude Code 和模型提供者之間運行的代理。當您的組織使用閘道時，Claude Code 使用您的組織簽發的認證向閘道進行身份驗證，而不是使用您個人的 claude.ai 登入。9[LLM 閘道](/docs/zh-TW/llm-gateway)是您的組織在 Claude Code 和模型提供者之間運行的代理。當您的組織使用閘道時，Claude Code 使用您的組織簽發的認證向閘道進行身份驗證，而不是使用您個人的 claude.ai 登入。

10 10

11本頁面適用於通過其組織運行的閘道運行 Claude Code 的開發人員。它涵蓋兩個路徑：[檢查您的管理員是否已為您配置它](#check-for-an-existing-configuration)，以及[在他們未配置時自行配置](#configure-claude-code-yourself)。11本頁面適用於通過其組織運行的閘道運行 Claude Code 的開發人員。它涵蓋兩個路徑：[檢查您的管理員是否已為您配置它](#check-for-an-existing-configuration)，以及[在他們未配置時自行配置](#configure-claude-code-yourself)。

12 12

13<Note>13<Note>

~~14 * 要為您的組織部署閘道，請參閱[推出 LLM 閘道](/zh-TW/llm-gateway-rollout)~~14 * 要為您的組織部署閘道，請參閱[推出 LLM 閘道](/docs/zh-TW/llm-gateway-rollout)

~~15 * 有關 Claude Code 發送到閘道的內容，請參閱[閘道協議參考](/zh-TW/llm-gateway-protocol)~~15 * 有關 Claude Code 發送到閘道的內容，請參閱[閘道協議參考](/docs/zh-TW/llm-gateway-protocol)

16</Note>16</Note>

17 17

18<h2 id="check-for-an-existing-configuration">18<h2 id="check-for-an-existing-configuration">

19 檢查現有配置19 檢查現有配置

20</h2>20</h2>

21 21

22管理員可以通過[受管設定](/zh-TW/settings#settings-files)、裝置管理或 [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) 分發閘道地址和認證，因此 Claude Code 在啟動時會自動獲取它們，無需您進行任何設定。要檢查您的組織是否已執行此操作：22管理員可以通過[受管設定](/docs/zh-TW/settings#settings-files)、裝置管理或 [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) 分發閘道地址和認證，因此 Claude Code 在啟動時會自動獲取它們，無需您進行任何設定。要檢查您的組織是否已執行此操作：

23 23

24<Steps>24<Steps>

25 <Step title="啟動 Claude Code">25 <Step title="啟動 Claude Code">

107 在設定檔案中設定107 在設定檔案中設定

108</h4>108</h4>

109 109

110要使配置在 Claude Code 運行的任何地方應用而不依賴於您的 shell，請在[設定檔案](/zh-TW/settings)的 `env` 區塊中設定變數。設定檔案有不同的範圍：110要使配置在 Claude Code 運行的任何地方應用而不依賴於您的 shell，請在[設定檔案](/docs/zh-TW/settings)的 `env` 區塊中設定變數。設定檔案有不同的範圍：

111 111

112* `~/.claude/settings.json` 適用於您的所有專案。在 Windows 上，路徑是 `%USERPROFILE%\.claude\settings.json`112* `~/.claude/settings.json` 適用於您的所有專案。在 Windows 上，路徑是 `%USERPROFILE%\.claude\settings.json`

113* `.claude/settings.local.json` 適用於一個專案。Claude Code 在建立檔案時將其添加到您的 gitignore；如果您自己建立它，請先手動將其添加到 gitignore，以免您不小心提交您的認證113* `.claude/settings.local.json` 適用於一個專案。Claude Code 在建立檔案時將其添加到您的 gitignore；如果您自己建立它，請先手動將其添加到 gitignore，以免您不小心提交您的認證

194 VS Code 擴充功能194 VS Code 擴充功能

195</h3>195</h3>

196 196

197在 VS Code 自己的使用者設定中的 `claudeCode.environmentVariables` 中為 [VS Code 擴充功能](/zh-TW/vs-code)設定閘道變數，使用**偏好設定：開啟使用者設定 (JSON)** 命令打開。擴充功能在啟動前檢查此設定中的認證，因此這是閘道認證的可靠位置；`~/.claude/settings.json` 中的值到達生成的程序但不到達擴充功能自己的登入檢查。197在 VS Code 自己的使用者設定中的 `claudeCode.environmentVariables` 中為 [VS Code 擴充功能](/docs/zh-TW/vs-code)設定閘道變數，使用**偏好設定：開啟使用者設定 (JSON)** 命令打開。擴充功能在啟動前檢查此設定中的認證，因此這是閘道認證的可靠位置；`~/.claude/settings.json` 中的值到達生成的程序但不到達擴充功能自己的登入檢查。

198 198

199```json theme={null}199```json theme={null}

200{200{

211 211

212桌面應用程式從其[第三方推論配置](https://claude.com/docs/third-party/claude-desktop/gateway)讀取閘道路由，而不是從 `ANTHROPIC_BASE_URL` 或 `settings.json`。該配置可以來自您的組織或來自應用程式本身的表單：212桌面應用程式從其[第三方推論配置](https://claude.com/docs/third-party/claude-desktop/gateway)讀取閘道路由，而不是從 `ANTHROPIC_BASE_URL` 或 `settings.json`。該配置可以來自您的組織或來自應用程式本身的表單：

213 213

214* **由管理員分發**：如果您的組織已[部署配置](/zh-TW/llm-gateway-rollout#distribute-through-managed-settings)，桌面應用程式通過閘道路由，無需您進行任何設定214* **由管理員分發**：如果您的組織已[部署配置](/docs/zh-TW/llm-gateway-rollout#distribute-through-managed-settings)，桌面應用程式通過閘道路由，無需您進行任何設定

215* **本地配置**：對於沒有管理員分發配置的裝置，打開說明 → 疑難排解 → 啟用開發人員模式，這會使用開發人員功能表重新啟動應用程式。然後打開開發人員 → 配置第三方推論並輸入您的閘道基礎 URL。管理員分發的配置優先，並使此表單為唯讀215* **本地配置**：對於沒有管理員分發配置的裝置，打開說明 → 疑難排解 → 啟用開發人員模式，這會使用開發人員功能表重新啟動應用程式。然後打開開發人員 → 配置第三方推論並輸入您的閘道基礎 URL。管理員分發的配置優先，並使此表單為唯讀

216 216

217啟用閘道配置後，桌面應用程式僅在您的本機上運行會話：環境選擇器不提供 SSH 會話或 Anthropic 託管的雲端環境，[遠端控制](/zh-TW/remote-control)不可用。若要通過閘道在遠端主機上使用 Claude Code，請在該主機上運行 CLI，並在那裡設定[`ANTHROPIC_BASE_URL` 和閘道認證](#set-the-base-url-and-credential)。217啟用閘道配置後，桌面應用程式僅在您的本機上運行會話：環境選擇器不提供 SSH 會話或 Anthropic 託管的雲端環境，[遠端控制](/docs/zh-TW/remote-control)不可用。若要通過閘道在遠端主機上使用 Claude Code，請在該主機上運行 CLI，並在那裡設定[`ANTHROPIC_BASE_URL` 和閘道認證](#set-the-base-url-and-credential)。

218 218

219如果桌面應用程式顯示 `Gateway was unreachable`，應用程式在啟動時無法到達配置的基礎 URL；使用上面的 [curl 測試](#verify-the-connection)檢查 URL 和網路路徑。219如果桌面應用程式顯示 `Gateway was unreachable`，應用程式在啟動時無法到達配置的基礎 URL；使用上面的 [curl 測試](#verify-the-connection)檢查 URL 和網路路徑。

220 220

222 GitHub Actions222 GitHub Actions

223</h3>223</h3>

224 224

225[Claude Code GitHub Actions](/zh-TW/github-actions) 從工作流程的 `env` 區塊讀取 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_CUSTOM_HEADERS`。將認證作為操作的 `anthropic_api_key` 輸入傳遞；操作將其設定為 `ANTHROPIC_API_KEY`，因此它到達 `x-api-key` 標頭中的閘道。225[Claude Code GitHub Actions](/docs/zh-TW/github-actions) 從工作流程的 `env` 區塊讀取 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_CUSTOM_HEADERS`。將認證作為操作的 `anthropic_api_key` 輸入傳遞；操作將其設定為 `ANTHROPIC_API_KEY`，因此它到達 `x-api-key` 標頭中的閘道。

226 226

227對於 `x-api-key` 閘道，在 `env` 中設定基礎 URL 並將閘道金鑰作為輸入傳遞：227對於 `x-api-key` 閘道，在 `env` 中設定基礎 URL 並將閘道金鑰作為輸入傳遞：

228 228

249 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}249 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

250```250```

251 251

252有關操作的其他身份驗證選項，包括 `CLAUDE_CODE_OAUTH_TOKEN` 和工作負載身份聯合，請參閱 [Claude Code GitHub Actions](/zh-TW/github-actions) 和操作的 [README](https://github.com/anthropics/claude-code-action#readme)。252有關操作的其他身份驗證選項，包括 `CLAUDE_CODE_OAUTH_TOKEN` 和工作負載身份聯合，請參閱 [Claude Code GitHub Actions](/docs/zh-TW/github-actions) 和操作的 [README](https://github.com/anthropics/claude-code-action#readme)。

253 253

254<h3 id="agent-sdk">254<h3 id="agent-sdk">

255 Agent SDK255 Agent SDK

256</h3>256</h3>

257 257

258[Agent SDK](/zh-TW/agent-sdk/overview) 沒有閘道特定的選項；它將環境變數傳遞給它生成的 Claude Code 程序。每個 SDK 接受一個 `env` 選項，用於設定生成的程序的環境，TypeScript 和 Python SDK 以不同的方式處理它：258[Agent SDK](/docs/zh-TW/agent-sdk/overview) 沒有閘道特定的選項；它將環境變數傳遞給它生成的 Claude Code 程序。每個 SDK 接受一個 `env` 選項，用於設定生成的程序的環境，TypeScript 和 Python SDK 以不同的方式處理它：

259 259

260* TypeScript：生成的程序預設繼承父環境，但設定 `options.env` 會完全替換環境。將 `process.env` 擴展到其中以保留您的閘道變數。260* TypeScript：生成的程序預設繼承父環境，但設定 `options.env` 會完全替換環境。將 `process.env` 擴展到其中以保留您的閘道變數。

261* Python：`ClaudeAgentOptions(env=...)` 合併到繼承的環境之上，因此在父程序中設定的閘道變數無需擴展即可通過。261* Python：`ClaudeAgentOptions(env=...)` 合併到繼承的環境之上，因此在父程序中設定的閘道變數無需擴展即可通過。

288 Slack、網頁和遠端控制288 Slack、網頁和遠端控制

289</h3>289</h3>

290 290

291[Slack 中的 Claude Code](/zh-TW/slack) 和[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web) 是 Anthropic 託管的產品，始終使用 Anthropic 的 API；它們不是閘道部署的一部分。在雲端會話的環境配置中設定的閘道變數不適用。如果您的流量必須保留在閘道上，請不要為這些使用者啟用這些介面。291[Slack 中的 Claude Code](/docs/zh-TW/slack) 和[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 是 Anthropic 託管的產品，始終使用 Anthropic 的 API；它們不是閘道部署的一部分。在雲端會話的環境配置中設定的閘道變數不適用。如果您的流量必須保留在閘道上，請不要為這些使用者啟用這些介面。

292 292

293[遠端控制](/zh-TW/remote-control)和[語音聽寫](/zh-TW/voice-dictation)都依賴於 claude.ai 身份：遠端控制將實時會話與您的帳戶配對，語音聽寫到達 claude.ai 轉錄端點。當 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 處於活動狀態時，它們不可用。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主機時，遠端控制也被禁用，因此僅使用 claude.ai 登入本身是不夠的。293[遠端控制](/docs/zh-TW/remote-control)和[語音聽寫](/docs/zh-TW/voice-dictation)都依賴於 claude.ai 身份：遠端控制將實時會話與您的帳戶配對，語音聽寫到達 claude.ai 轉錄端點。當 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 處於活動狀態時，它們不可用。自 v2.1.196 起，當 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主機時，遠端控制也被禁用，因此僅使用 claude.ai 登入本身是不夠的。

294 294

295若要還原任一功能，請使用 claude.ai 登入並取消設定它檢查的閘道變數。`claude doctor` 的遠端控制部分命名要取消設定的認證變數。295若要還原任一功能，請使用 claude.ai 登入並取消設定它檢查的閘道變數。`claude doctor` 的遠端控制部分命名要取消設定的認證變數。

296 296

307 發送其他標頭307 發送其他標頭

308</h3>308</h3>

309 309

310某些閘道使用除認證外的自訂標頭路由或標記請求，例如租戶識別碼或路由金鑰。要發送一個，請設定 [`ANTHROPIC_CUSTOM_HEADERS`](/zh-TW/env-vars)，每行一個 `Name: Value` 對。下面的示例添加了一個名為 `X-Org-Route` 的路由標頭：310某些閘道使用除認證外的自訂標頭路由或標記請求，例如租戶識別碼或路由金鑰。要發送一個，請設定 [`ANTHROPIC_CUSTOM_HEADERS`](/docs/zh-TW/env-vars)，每行一個 `Name: Value` 對。下面的示例添加了一個名為 `X-Org-Route` 的路由標頭：

311 311

312<Tabs>312<Tabs>

313 <Tab title="Bash or Zsh">313 <Tab title="Bash or Zsh">

341 341

342如果您的閘道提供不在 Claude Code 內置列表中的模型名稱，並且您想從選擇器中選擇它們，請啟用它。如果內置模型是您使用的，您不需要發現；您的管理員也可能已通過受管設定啟用它。342如果您的閘道提供不在 Claude Code 內置列表中的模型名稱，並且您想從選擇器中選擇它們，請啟用它。如果內置模型是您使用的，您不需要發現；您的管理員也可能已通過受管設定啟用它。

343 343

344要啟用它，請在您的 shell 或 `~/.claude/settings.json` 的 `env` 區塊中設定 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`。發現需要 Claude Code v2.1.129 或更高版本。{/* min-version: 2.1.129 */}344要啟用它，請在您的 shell 或 `~/.claude/settings.json` 的 `env` 區塊中設定 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`。發現需要 Claude Code v2.1.129 或更高版本。

345 345

346發現的模型顯示為標記為 `From gateway` 的其他 `/model` 項目。要確認發現已執行，請啟動 `claude --debug` 並查找 `[gatewayDiscovery]` 行：成功記錄了多少模型被緩存，`404`、超時或重定向也被記錄在那裡。有關發現何時執行、它過濾什麼以及閘道提供的回應格式，請參閱[模型發現參考](/zh-TW/llm-gateway-protocol#model-discovery)。346發現的模型顯示為標記為 `From gateway` 的其他 `/model` 項目。要確認發現已執行，請啟動 `claude --debug` 並查找 `[gatewayDiscovery]` 行：成功記錄了多少模型被緩存，`404`、超時或重定向也被記錄在那裡。有關發現何時執行、它過濾什麼以及閘道提供的回應格式，請參閱[模型發現參考](/docs/zh-TW/llm-gateway-protocol#model-discovery)。

347 347

348<h3 id="rotate-credentials-with-apikeyhelper">348<h3 id="rotate-credentials-with-apikeyhelper">

349 使用 apiKeyHelper 輪換認證349 使用 apiKeyHelper 輪換認證

353 353

354當認證按計劃過期、來自保管庫或 SSO 命令，或您的管理員告訴您配置一個時，使用幫助程式。如果您的認證是您設定一次的固定字符串，[認證變數](#set-the-credential-variable)就是您需要的全部，您可以跳過本部分。354當認證按計劃過期、來自保管庫或 SSO 命令，或您的管理員告訴您配置一個時，使用幫助程式。如果您的認證是您設定一次的固定字符串，[認證變數](#set-the-credential-variable)就是您需要的全部，您可以跳過本部分。

355 355

356幫助程式是任何將當前認證列印到 stdout 的 shell 命令。Claude Code 通過您的系統 shell 運行它，因此在 Windows 上它可以是可執行檔案或 PowerShell 調用。編寫指令碼，使其可執行，並從您的[設定檔案](/zh-TW/settings)中的 `apiKeyHelper` 參考它：356幫助程式是任何將當前認證列印到 stdout 的 shell 命令。Claude Code 通過您的系統 shell 運行它，因此在 Windows 上它可以是可執行檔案或 PowerShell 調用。編寫指令碼，使其可執行，並從您的[設定檔案](/docs/zh-TW/settings)中的 `apiKeyHelper` 參考它：

357 357

358<Tabs>358<Tabs>

359 <Tab title="Bash or Zsh">359 <Tab title="Bash or Zsh">

419設定變數具有以下效果和限制：419設定變數具有以下效果和限制：

420 420

421* 它禁用自動更新，因此請計劃另一個更新路徑，例如您的套件管理器或受管分發。421* 它禁用自動更新，因此請計劃另一個更新路徑，例如您的套件管理器或受管分發。

422* 它抑制[快速模式](/zh-TW/fast-mode)可用性檢查。除非之前的檢查已在機器上啟用快速模式，否則 `/fast` 報告快速模式不可用。422* 它抑制[快速模式](/docs/zh-TW/fast-mode)可用性檢查。除非之前的檢查已在機器上啟用快速模式，否則 `/fast` 報告快速模式不可用。

423* 它關閉[閘道模型發現](#add-gateway-models-to-the-model-picker)，儘管發現查詢閘道本身。之前發現的模型仍可從本地緩存獲得，但列表不會刷新。423* 它關閉[閘道模型發現](#add-gateway-models-to-the-model-picker)，儘管發現查詢閘道本身。之前發現的模型仍可從本地緩存獲得，但列表不會刷新。

424* WebFetch 工具的[域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)不受影響，仍會呼叫 `api.anthropic.com`。如果您的網路阻止該主機，請在[設定](/zh-TW/settings)中使用 `skipWebFetchPreflight: true` 單獨關閉它。424* WebFetch 工具的[域安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check)不受影響，仍會呼叫 `api.anthropic.com`。如果您的網路阻止該主機，請在[設定](/docs/zh-TW/settings)中使用 `skipWebFetchPreflight: true` 單獨關閉它。

425* 對於每個遙測流和控制它的變數，請參閱[遙測服務](/zh-TW/data-usage#telemetry-services)。425* 對於每個遙測流和控制它的變數，請參閱[遙測服務](/docs/zh-TW/data-usage#telemetry-services)。

426 426

427<h3 id="route-to-a-cloud-provider-through-a-gateway">427<h3 id="route-to-a-cloud-provider-through-a-gateway">

428 通過閘道路由到雲端提供者428 通過閘道路由到雲端提供者

432 432

433僅在您的閘道團隊特別命名 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 時使用一個。如果上面的[驗證請求](#verify-the-connection)返回 JSON，您可以跳過本部分。433僅在您的閘道團隊特別命名 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 時使用一個。如果上面的[驗證請求](#verify-the-connection)返回 JSON，您可以跳過本部分。

434 434

435為您的閘道團隊命名的提供者設定區塊。跳過身份驗證變數告訴 Claude Code 不要使用提供者認證簽署請求，因為閘道持有這些。如果閘道需要自己的令牌，請在區塊後添加 `ANTHROPIC_AUTH_TOKEN`，除了 Microsoft Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。{/* min-version: 2.1.203 */}期望持有人令牌的 Microsoft Foundry 閘道可以改用 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/zh-TW/env-vars)；當兩者都設定時，它優先於 `ANTHROPIC_FOUNDRY_API_KEY`。`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 需要 Claude Code v2.1.203 或更高版本。435為您的閘道團隊命名的提供者設定區塊。跳過身份驗證變數告訴 Claude Code 不要使用提供者認證簽署請求，因為閘道持有這些。如果閘道需要自己的令牌，請在區塊後添加 `ANTHROPIC_AUTH_TOKEN`，除了 Microsoft Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。期望持有人令牌的 Microsoft Foundry 閘道可以改用 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/docs/zh-TW/env-vars)；當兩者都設定時，它優先於 `ANTHROPIC_FOUNDRY_API_KEY`。`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 需要 Claude Code v2.1.203 或更高版本。

436 436

437<h4 id="amazon-bedrock">437<h4 id="amazon-bedrock">

438 Amazon Bedrock438 Amazon Bedrock

486 Microsoft Foundry486 Microsoft Foundry

487</h4>487</h4>

488 488

489將閘道的認證放在 `ANTHROPIC_FOUNDRY_API_KEY` 中；它作為 `x-api-key` 標頭發送到閘道。{/* min-version: 2.1.203 */}期望持有人令牌的閘道可以改用 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/zh-TW/env-vars)。Claude Code 將該值作為 `Authorization: Bearer` 標頭發送，當兩者都設定時，它優先於 `ANTHROPIC_FOUNDRY_API_KEY`。需要 Claude Code v2.1.203 或更高版本。489將閘道的認證放在 `ANTHROPIC_FOUNDRY_API_KEY` 中；它作為 `x-api-key` 標頭發送到閘道。期望持有人令牌的閘道可以改用 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/docs/zh-TW/env-vars)。Claude Code 將該值作為 `Authorization: Bearer` 標頭發送，當兩者都設定時，它優先於 `ANTHROPIC_FOUNDRY_API_KEY`。需要 Claude Code v2.1.203 或更高版本。

490 490

491對於注入自己的 `Authorization` 標頭的閘道，設定 `CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1` 並將兩個認證變數都保留為未設定。Claude Code 然後發送沒有 Azure 認證的請求，並保留您提供的 `Authorization` 標頭，例如通過 `ANTHROPIC_CUSTOM_HEADERS`。{/* min-version: 2.1.203 */}在 v2.1.203 之前，`CLAUDE_CODE_SKIP_FOUNDRY_AUTH` 沒有 API 金鑰使 Microsoft Foundry 客戶端無法發送請求。491對於注入自己的 `Authorization` 標頭的閘道，設定 `CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1` 並將兩個認證變數都保留為未設定。Claude Code 然後發送沒有 Azure 認證的請求，並保留您提供的 `Authorization` 標頭，例如通過 `ANTHROPIC_CUSTOM_HEADERS`。在 v2.1.203 之前，`CLAUDE_CODE_SKIP_FOUNDRY_AUTH` 沒有 API 金鑰使 Microsoft Foundry 客戶端無法發送請求。

492 492

493<Tabs>493<Tabs>

494 <Tab title="Bash or Zsh">494 <Tab title="Bash or Zsh">

512 AWS 上的 Claude Platform512 AWS 上的 Claude Platform

513</h4>513</h4>

514 514

515有關工作區 ID，請參閱 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws)。515有關工作區 ID，請參閱 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)。

516 516

517<Tabs>517<Tabs>

518 <Tab title="Bash or Zsh">518 <Tab title="Bash or Zsh">

544| :------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |544| :------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

545| 啟動警告命名兩個認證來源並以 `auth may not work as expected` 結尾。較舊的版本顯示 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` 代替。 | 閘道認證和已保存的登入都處於活動狀態；變數用於請求，但過時的登入可能導致意外的身份驗證行為 | 取消設定變數以使用已保存的登入，或執行 `/logout` 以使用閘道認證 |545| 啟動警告命名兩個認證來源並以 `auth may not work as expected` 結尾。較舊的版本顯示 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` 代替。 | 閘道認證和已保存的登入都處於活動狀態；變數用於請求，但過時的登入可能導致意外的身份驗證行為 | 取消設定變數以使用已保存的登入，或執行 `/logout` 以使用閘道認證 |

547| `Your apiKeyHelper script is failing` | [`apiKeyHelper`](/zh-TW/settings#available-settings) 設定中的命令以錯誤結束、逾時或未列印任何內容，因此請求帶有預留位置金鑰 | 直接執行命令以查看失敗原因，並在認證提供者報告過期會話時重新驗證；請參閱[錯誤參考](/zh-TW/errors#your-apikeyhelper-script-is-failing) |547| `Your apiKeyHelper script is failing` | [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 設定中的命令以錯誤結束、逾時或未列印任何內容，因此請求帶有預留位置金鑰 | 直接執行命令以查看失敗原因，並在認證提供者報告過期會話時重新驗證；請參閱[錯誤參考](/docs/zh-TW/errors#your-apikeyhelper-script-is-failing) |

548| `Unable to connect to API (ConnectionRefused)`，或來自 npm 安裝的 `(ECONNREFUSED)`，通常在 Claude Code [使用退避重試](/zh-TW/errors#automatic-retries)時無聲暫停後 | 沒有任何東西在基礎 URL 應答：地址錯誤，或 VPN 或防火牆阻止了到閘道的路徑 | 執行上面的 [curl 測試](#verify-the-connection)，它立即以相同的原因失敗，並與您的閘道團隊確認 URL 和網路路徑 |548| `Unable to connect to API (ConnectionRefused)`，或來自 npm 安裝的 `(ECONNREFUSED)`，通常在 Claude Code [使用退避重試](/docs/zh-TW/errors#automatic-retries)時無聲暫停後 | 沒有任何東西在基礎 URL 應答：地址錯誤，或 VPN 或防火牆阻止了到閘道的路徑 | 執行上面的 [curl 測試](#verify-the-connection)，它立即以相同的原因失敗，並與您的閘道團隊確認 URL 和網路路徑 |

550| `400` 錯誤命名 `context_management`、`Extra inputs are not permitted` 或其他無法識別的欄位 | 閘道將請求轉發到上游，該上游拒絕 Claude Code 發送到 Anthropic 格式端點的欄位 | 設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，它抑制大多數預發佈欄位；請參閱[功能傳遞](/zh-TW/llm-gateway-protocol#feature-pass-through)。某些 beta 不受此標誌限制；對於那些，設定匹配的 `CLAUDE_CODE_USE_*` 提供者變數，以便 Claude Code 僅發送該提供者接受的內容 |550| `400` 錯誤命名 `context_management`、`Extra inputs are not permitted` 或其他無法識別的欄位 | 閘道將請求轉發到上游，該上游拒絕 Claude Code 發送到 Anthropic 格式端點的欄位 | 設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，它抑制大多數預發佈欄位；請參閱[功能傳遞](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)。某些 beta 不受此標誌限制；對於那些，設定匹配的 `CLAUDE_CODE_USE_*` 提供者變數，以便 Claude Code 僅發送該提供者接受的內容 |

551| `400` 錯誤命名 `thinking` 或 `adaptive`，例如 `Input tag 'adaptive' found` | 上游模型構建不接受自適應推理，Claude Code 為 Claude 4.6 及更高版本的模型請求 | 升級閘道的上游。在 Opus 4.6 和 Sonnet 4.6 上，`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 改為有效。[模型配置](/zh-TW/model-config)功能變數僅適用於提供者配置（例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`），不在 `ANTHROPIC_BASE_URL` 閘道後面 |551| `400` 錯誤命名 `thinking` 或 `adaptive`，例如 `Input tag 'adaptive' found` | 上游模型構建不接受自適應推理，Claude Code 為 Claude 4.6 及更高版本的模型請求 | 升級閘道的上游。在 Opus 4.6 和 Sonnet 4.6 上，`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 改為有效。[模型配置](/docs/zh-TW/model-config)功能變數僅適用於提供者配置（例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`），不在 `ANTHROPIC_BASE_URL` 閘道後面 |

552| `400` 錯誤陳述閘道自己的詞語中的上下文或令牌限制，例如 `ContextWindowExceededError` 或 `prompt token count of N exceeds the limit of M` | 閘道強制執行比模型的本機視窗更小的上下文，並重寫上游錯誤，因此自動壓縮和重試（與 Anthropic 的 `prompt is too long` 措辭匹配）不會觸發 | 執行 `/compact` 以恢復會話。要防止它，請將 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 設定為閘道的限制；該值被限制在至少 100,000 令牌和最多模型的上下文視窗，因此低於 100,000 的閘道限制無法匹配，`/compact` 在那裡仍然是恢復。還要將 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 設定為低於閘道模型的輸出限制 |552| `400` 錯誤陳述閘道自己的詞語中的上下文或令牌限制，例如 `ContextWindowExceededError` 或 `prompt token count of N exceeds the limit of M` | 閘道強制執行比模型的本機視窗更小的上下文，並重寫上游錯誤，因此自動壓縮和重試（與 Anthropic 的 `prompt is too long` 措辭匹配）不會觸發 | 執行 `/compact` 以恢復會話。要防止它，請將 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 設定為閘道的限制；該值被限制在至少 100,000 令牌和最多模型的上下文視窗，因此低於 100,000 的閘道限制無法匹配，`/compact` 在那裡仍然是恢復。還要將 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 設定為低於閘道模型的輸出限制 |

554| Claude Code 要求您登入，儘管 [curl 測試](#verify-the-connection)成功 | CLI 沒有自己的認證：可達的基礎 URL 不是一個，專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 區塊僅在首次執行嚮導和信任提示後應用 | 在 Claude Code 在首次執行設定之前讀取的位置設定 `ANTHROPIC_AUTH_TOKEN`：shell 匯出、`~/.claude/settings.json` 中的 `env` 區塊或受管設定 |554| Claude Code 要求您登入，儘管 [curl 測試](#verify-the-connection)成功 | CLI 沒有自己的認證：可達的基礎 URL 不是一個，專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 區塊僅在首次執行嚮導和信任提示後應用 | 在 Claude Code 在首次執行設定之前讀取的位置設定 `ANTHROPIC_AUTH_TOKEN`：shell 匯出、`~/.claude/settings.json` 中的 `env` 區塊或受管設定 |

556| `This machine's managed settings require a first-party login` | 受管設定包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，在 Claude Code v2.1.146 及更高版本上不能與 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理員必須從受管設定中移除 `forceLoginMethod` 和 `forceLoginOrgUUID` 以使用閘道認證，或移除閘道認證以使用第一方登入。兩者無法結合 |556| `This machine's managed settings require a first-party login` | 受管設定包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，在 Claude Code v2.1.146 及更高版本上不能與 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理員必須從受管設定中移除 `forceLoginMethod` 和 `forceLoginOrgUUID` 以使用閘道認證，或移除閘道認證以使用第一方登入。兩者無法結合 |

557| `403` 帶有 HTML 正文，例如 `403 Forbidden`，當閘道自己的日誌顯示未收到請求時 | 閘道前面的網頁應用程式防火牆或反向代理在到達閘道之前阻止了請求正文。Claude Code 提示包括 XML 樣式標籤和與跨站點指令碼正文規則匹配的原始程式碼，因此短 curl 測試通過而實際會話不通過 | 豁免閘道的 `/v1/messages` 路徑免受請求正文檢查。在 AWS WAF 上，這是 `CrossSiteScripting_Body` 受管規則；在帶有 ModSecurity 的 nginx 上，它是等效的 OWASP CRS 正文規則 |557| `403` 帶有 HTML 正文，例如 `403 Forbidden`，當閘道自己的日誌顯示未收到請求時 | 閘道前面的網頁應用程式防火牆或反向代理在到達閘道之前阻止了請求正文。Claude Code 提示包括 XML 樣式標籤和與跨站點指令碼正文規則匹配的原始程式碼，因此短 curl 測試通過而實際會話不通過 | 豁免閘道的 `/v1/messages` 路徑免受請求正文檢查。在 AWS WAF 上，這是 `CrossSiteScripting_Body` 受管規則；在帶有 ModSecurity 的 nginx 上，它是等效的 OWASP CRS 正文規則 |

558| 憑證或 TLS 錯誤，例如 `SSL certificate verification failed` 或 `Self-signed certificate detected`，當 [curl 測試](#verify-the-connection)成功時 | Claude Code 的執行時不信任 `curl` 使用的相同憑證授權。在公司 TLS 檢查代理後面很常見 | 將 `NODE_EXTRA_CA_CERTS` 設定為 CA 束路徑；請參閱 [CA 憑證存儲](/zh-TW/network-config#ca-certificate-store) |558| 憑證或 TLS 錯誤，例如 `SSL certificate verification failed` 或 `Self-signed certificate detected`，當 [curl 測試](#verify-the-connection)成功時 | Claude Code 的執行時不信任 `curl` 使用的相同憑證授權。在公司 TLS 檢查代理後面很常見 | 將 `NODE_EXTRA_CA_CERTS` 設定為 CA 束路徑；請參閱 [CA 憑證存儲](/docs/zh-TW/network-config#ca-certificate-store) |

559 559

560如果 Claude Code 在移除閘道配置後重複提示您登入，原因通常是認證存儲而不是閘道；請參閱[身份驗證錯誤](/zh-TW/errors#authentication-errors)。560如果 Claude Code 在移除閘道配置後重複提示您登入，原因通常是認證存儲而不是閘道；請參閱[身份驗證錯誤](/docs/zh-TW/errors#authentication-errors)。

561 561

562<h2 id="related-resources">562<h2 id="related-resources">

563 相關資源563 相關資源

564</h2>564</h2>

565 565

566* [LLM 閘道概述](/zh-TW/llm-gateway)：什麼是閘道以及它如何與 claude.ai 訂閱互動566* [LLM 閘道概述](/docs/zh-TW/llm-gateway)：什麼是閘道以及它如何與 claude.ai 訂閱互動

567* [為您的組織推出 LLM 閘道](/zh-TW/llm-gateway-rollout)：部署和分發閘道配置的面向管理員的檢查清單567* [為您的組織推出 LLM 閘道](/docs/zh-TW/llm-gateway-rollout)：部署和分發閘道配置的面向管理員的檢查清單

568* [閘道協議參考](/zh-TW/llm-gateway-protocol)：Claude Code 發送到閘道的內容，包括閘道必須轉發的標頭和欄位568* [閘道協議參考](/docs/zh-TW/llm-gateway-protocol)：Claude Code 發送到閘道的內容，包括閘道必須轉發的標頭和欄位

569* [設定](/zh-TW/settings)：設定檔案的位置以及如何讀取 `env` 區塊569* [設定](/docs/zh-TW/settings)：設定檔案的位置以及如何讀取 `env` 區塊

570* [身份驗證](/zh-TW/authentication)：認證變數、`apiKeyHelper` 和 OAuth 登入如何互動570* [身份驗證](/docs/zh-TW/authentication)：認證變數、`apiKeyHelper` 和 OAuth 登入如何互動

llm-gateway-protocol.md +24 −24

Details

8 8

9本頁面記錄了 Claude Code 發送給 gateway 的請求，包括它呼叫的端點、gateway 必須轉發的標頭和請求體欄位，以及當 gateway 不這樣做時哪些功能會停止運作。本文件是為配置 gateway 產品以與 Claude Code 搭配運作的操作人員編寫的。9本頁面記錄了 Claude Code 發送給 gateway 的請求，包括它呼叫的端點、gateway 必須轉發的標頭和請求體欄位，以及當 gateway 不這樣做時哪些功能會停止運作。本文件是為配置 gateway 產品以與 Claude Code 搭配運作的操作人員編寫的。

10 10

11執行中的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 在 `GET /protocol` 提供此契約的機器可讀版本，涵蓋相同的轉發要求以及 Claude apps gateway 特定的端點，用於 SSO 登入、受管設定傳遞和遙測。Claude apps gateway 從與 CLI 相同的 `claude` 二進位檔案執行，因此 [Claude apps gateway 快速入門](/zh-TW/claude-apps-gateway#quickstart) 是取得您可以從中擷取規格的執行中實例的最短路徑。11執行中的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 在 `GET /protocol` 提供此契約的機器可讀版本，涵蓋相同的轉發要求以及 Claude apps gateway 特定的端點，用於 SSO 登入、受管設定傳遞和遙測。Claude apps gateway 從與 CLI 相同的 `claude` 二進位檔案執行，因此 [Claude apps gateway 快速入門](/docs/zh-TW/claude-apps-gateway#quickstart) 是取得您可以從中擷取規格的執行中實例的最短路徑。

12 12

13<Note>13<Note>

~~14 * 若要為您的組織推出現有或第三方 gateway，請參閱[推出 LLM gateway](/zh-TW/llm-gateway-rollout)~~14 * 若要為您的組織推出現有或第三方 gateway，請參閱[推出 LLM gateway](/docs/zh-TW/llm-gateway-rollout)

~~15 * 如果您是使用提供給您的認證向 gateway 驗證 Claude Code 的個人開發人員，請參閱[將 Claude Code 連接到 LLM gateway](/zh-TW/llm-gateway-connect)~~15 * 如果您是使用提供給您的認證向 gateway 驗證 Claude Code 的個人開發人員，請參閱[將 Claude Code 連接到 LLM gateway](/docs/zh-TW/llm-gateway-connect)

16</Note>16</Note>

17 17

18本頁面涵蓋：18本頁面涵蓋：

46 Foundry 和 AWS 上的 Claude Platform46 Foundry 和 AWS 上的 Claude Platform

47</h3>47</h3>

48 48

49Microsoft Foundry 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 實現了 Anthropic Messages 格式。Claude Code 通過它們自己的變數 `ANTHROPIC_FOUNDRY_BASE_URL` 和 `ANTHROPIC_AWS_BASE_URL` 路由到它們，但 gateway 在任一前面實現上述 Anthropic Messages 列。在 AWS 上的 Claude Platform 前面的 gateway 還必須轉發 `anthropic-workspace-id` 標頭，[該平台在每個請求上都需要](/zh-TW/claude-platform-on-aws)。49Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 實現了 Anthropic Messages 格式。Claude Code 通過它們自己的變數 `ANTHROPIC_FOUNDRY_BASE_URL` 和 `ANTHROPIC_AWS_BASE_URL` 路由到它們，但 gateway 在任一前面實現上述 Anthropic Messages 列。在 AWS 上的 Claude Platform 前面的 gateway 還必須轉發 `anthropic-workspace-id` 標頭，[該平台在每個請求上都需要](/docs/zh-TW/claude-platform-on-aws)。

50 50

51<h3 id="optional-endpoints-and-startup-traffic">51<h3 id="optional-endpoints-and-startup-traffic">

52 可選端點和啟動流量52 可選端點和啟動流量

77 請求標頭77 請求標頭

78</h2>78</h2>

79 79

80Claude Code 在 API 請求上包含這些標頭。標頭名稱在線路上不區分大小寫。轉發 `anthropic-version` 和 `anthropic-beta` 不變，加上當上游是 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 時的 `anthropic-workspace-id`；其餘的 gateway 可以使用以進行路由、歸屬和追蹤，不需要轉發。80Claude Code 在 API 請求上包含這些標頭。標頭名稱在線路上不區分大小寫。轉發 `anthropic-version` 和 `anthropic-beta` 不變，加上當上游是 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 時的 `anthropic-workspace-id`；其餘的 gateway 可以使用以進行路由、歸屬和追蹤，不需要轉發。

81 81

82| 標頭 | 描述 |82| 標頭 | 描述 |

83| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |83| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

84| `Authorization`、`x-api-key` | 開發人員的 gateway 認證，根據他們設定的[認證變數](/zh-TW/llm-gateway-connect#set-the-credential-variable)在一個或兩個標頭中 |84| `Authorization`、`x-api-key` | 開發人員的 gateway 認證，根據他們設定的[認證變數](/docs/zh-TW/llm-gateway-connect#set-the-credential-variable)在一個或兩個標頭中 |

85| `anthropic-version` | API 版本，目前為 `2023-06-01`。Amazon Bedrock 和 Google Cloud 的 Agent Platform 格式請求也攜帶 `anthropic_version` 請求體欄位，其值是提供者方言字串，而不是此標頭的值 |85| `anthropic-version` | API 版本，目前為 `2023-06-01`。Amazon Bedrock 和 Google Cloud 的 Agent Platform 格式請求也攜帶 `anthropic_version` 請求體欄位，其值是提供者方言字串，而不是此標頭的值 |

86| `anthropic-beta` | 請求的逗號分隔功能值。逐字轉發標頭；不要將個別值列入允許清單，因為該集合隨 Claude Code 版本而變化。當開發人員使用 claude.ai 登入進行驗證時（當設定 `ANTHROPIC_BASE_URL` 而沒有 gateway 認證變數時可能），此標頭也會攜帶上游需要的 OAuth 功能，移除它會導致這些請求失敗並出現 `401` |86| `anthropic-beta` | 請求的逗號分隔功能值。逐字轉發標頭；不要將個別值列入允許清單，因為該集合隨 Claude Code 版本而變化。當開發人員使用 claude.ai 登入進行驗證時（當設定 `ANTHROPIC_BASE_URL` 而沒有 gateway 認證變數時可能），此標頭也會攜帶上游需要的 OAuth 功能，移除它會導致這些請求失敗並出現 `401` |

88| `x-claude-code-agent-id` | 發出請求的[子代理](/zh-TW/sub-agents)的識別碼，僅在來自 Claude Code 在工作階段內生成的代理的請求上存在。將其與工作階段 ID 一起使用以將成本歸屬於平行代理 |88| `x-claude-code-agent-id` | 發出請求的[子代理](/docs/zh-TW/sub-agents)的識別碼，僅在來自 Claude Code 在工作階段內生成的代理的請求上存在。將其與工作階段 ID 一起使用以將成本歸屬於平行代理 |

90 90

91子代理 ID 在每次生成時都會新生成。隊友代理（[代理團隊](/zh-TW/agent-teams)的命名成員）在重新連接時重複使用穩定的基於名稱的 ID。在兩種情況下，ID 都識別一個代理，而不是一個人或設備，因此不要將代理 ID 標頭視為使用者識別碼。91子代理 ID 在每次生成時都會新生成。隊友代理（[代理團隊](/docs/zh-TW/agent-teams)的命名成員）在重新連接時重複使用穩定的基於名稱的 ID。在兩種情況下，ID 都識別一個代理，而不是一個人或設備，因此不要將代理 ID 標頭視為使用者識別碼。

92 92

93如果您的開發人員設定了 `ANTHROPIC_CUSTOM_HEADERS`，這些標頭也會出現在請求上。93如果您的開發人員設定了 `ANTHROPIC_CUSTOM_HEADERS`，這些標頭也會出現在請求上。

94 94

112 112

113* 完全按照接收的方式轉發 `system` 陣列，將區塊保持在最前面：在前面加上另一個系統區塊、重新排序陣列或將其轉換為單一字串會破壞移除，區塊隨後會到達模型和提示快取鍵。113* 完全按照接收的方式轉發 `system` 陣列，將區塊保持在最前面：在前面加上另一個系統區塊、重新排序陣列或將其轉換為單一字串會破壞移除，區塊隨後會到達模型和提示快取鍵。

114* 將區塊保持在自己的陣列項目中：端點將以歸屬標頭開頭的合併區塊視為完整的歸屬並刪除合併到其中的所有內容，包括系統提示的其餘部分。114* 將區塊保持在自己的陣列項目中：端點將以歸屬標頭開頭的合併區塊視為完整的歸屬並刪除合併到其中的所有內容，包括系統提示的其餘部分。

115* 如果您的 gateway 必須重新塑造系統內容，請設定 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-TW/env-vars) 以便 Claude Code 省略該區塊。Anthropic 和雲提供者的 Claude 端點讀取該區塊以進行歸屬，因此要省略它，請在用戶端而不是在 gateway 中移除或移動它。115* 如果您的 gateway 必須重新塑造系統內容，請設定 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/docs/zh-TW/env-vars) 以便 Claude Code 省略該區塊。Anthropic 和雲提供者的 Claude 端點讀取該區塊以進行歸屬，因此要省略它，請在用戶端而不是在 gateway 中移除或移動它。

116 116

117未經修改到達端點的請求不受影響。117未經修改到達端點的請求不受影響。

118 118

119{/* min-version: 2.1.181 */}從 Claude Code v2.1.181 開始，當請求通過自訂基礎 URL 路由時，該區塊在對話的生命週期內是穩定的，因此以完整請求體為鍵的 gateway 端提示快取可以在不禁用它的情況下工作。在 v2.1.181 之前，該區塊包含每個請求的令牌；在這些版本上，如果您的 gateway 實現了這樣的快取，請設定 `CLAUDE_CODE_ATTRIBUTION_HEADER=0`。119從 Claude Code v2.1.181 開始，當請求通過自訂基礎 URL 路由時，該區塊在對話的生命週期內是穩定的，因此以完整請求體為鍵的 gateway 端提示快取可以在不禁用它的情況下工作。在 v2.1.181 之前，該區塊包含每個請求的令牌；在這些版本上，如果您的 gateway 實現了這樣的快取，請設定 `CLAUDE_CODE_ATTRIBUTION_HEADER=0`。

120 120

121<h2 id="feature-pass-through">121<h2 id="feature-pass-through">

122 功能傳遞122 功能傳遞

126 126

127添加請求體欄位的功能將它們與測試版標頭配對，該對一起傳遞。移除標頭同時傳遞請求體的 gateway，或將 Anthropic 格式請求體轉發到具有不同架構的上游，會產生硬 `400` 錯誤；只有當兩個部分一起不存在時，功能才會安靜地關閉。重寫或編輯請求體以進行內容檢查的 gateway 會以與移除相同的方式破壞配對，因此請在不修改的情況下檢查。該表注意了功能偏離配對的位置。127添加請求體欄位的功能將它們與測試版標頭配對，該對一起傳遞。移除標頭同時傳遞請求體的 gateway，或將 Anthropic 格式請求體轉發到具有不同架構的上游，會產生硬 `400` 錯誤；只有當兩個部分一起不存在時，功能才會安靜地關閉。重寫或編輯請求體以進行內容檢查的 gateway 會以與移除相同的方式破壞配對，因此請在不修改的情況下檢查。該表注意了功能偏離配對的位置。

128 128

129細粒度工具串流是直接連接預設值之一：每當請求通過自訂基礎 URL 路由時，它預設為關閉，當開發人員設定 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/zh-TW/env-vars) 時，gateway 會接收它。129細粒度工具串流是直接連接預設值之一：每當請求通過自訂基礎 URL 路由時，它預設為關閉，當開發人員設定 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/docs/zh-TW/env-vars) 時，gateway 會接收它。

130 130

131| 功能 | 標頭和請求體對 | 破壞時的症狀 | 補救 |131| 功能 | 標頭和請求體對 | 破壞時的症狀 | 補救 |

132| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------- |132| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------- |

133| [自適應推理](/zh-TW/model-config#adjust-effort-level) | 無測試版標頭。Claude Code 為 Claude 4.6 及更新版本發送 `thinking: {"type": "adaptive"}`，並將它不識別的模型名稱（如 gateway 別名）視為接收該欄位的目前模型 | 當上游模型組建不接受它時，命名 `thinking` 欄位或 `adaptive` 標籤的 `400` | 升級上游。在 Opus 4.6 和 Sonnet 4.6 上，開發人員可以改為設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |133| [自適應推理](/docs/zh-TW/model-config#adjust-effort-level) | 無測試版標頭。Claude Code 為 Claude 4.6 及更新版本發送 `thinking: {"type": "adaptive"}`，並將它不識別的模型名稱（如 gateway 別名）視為接收該欄位的目前模型 | 當上游模型組建不接受它時，命名 `thinking` 欄位或 `adaptive` 標籤的 `400` | 升級上游。在 Opus 4.6 和 Sonnet 4.6 上，開發人員可以改為設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |

134| [上下文管理](https://platform.claude.com/docs/en/build-with-claude/context-management) | 上下文管理測試版標頭與 `context_management` 請求體欄位配對 | `400` 搭配 `Extra inputs are not permitted`。常見於 gateway 接受 Anthropic 格式請求但將其轉發到 Amazon Bedrock 時 | 轉發兩者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-TW/env-vars) |134| [上下文管理](https://platform.claude.com/docs/en/build-with-claude/context-management) | 上下文管理測試版標頭與 `context_management` 請求體欄位配對 | `400` 搭配 `Extra inputs are not permitted`。常見於 gateway 接受 Anthropic 格式請求但將其轉發到 Amazon Bedrock 時 | 轉發兩者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-TW/env-vars) |

135| [擴展上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)和[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 僅測試版標頭，無請求體欄位 | 當標頭被移除時無聲地不可用；上游永遠不會看到功能請求 | 逐字轉發 `anthropic-beta` |135| [擴展上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)和[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 僅測試版標頭，無請求體欄位 | 當標頭被移除時無聲地不可用；上游永遠不會看到功能請求 | 逐字轉發 `anthropic-beta` |

136| 測試版[工具欄位](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相關的測試版標頭與工具架構欄位（如 `strict` 和 `defer_loading`）配對 | 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具架構欄位的 `400` | 轉發兩者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |136| 測試版[工具欄位](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相關的測試版標頭與工具架構欄位（如 `strict` 和 `defer_loading`）配對 | 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具架構欄位的 `400` | 轉發兩者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |

137| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[結構化輸出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 請求體欄位攜帶努力、結構化輸出格式和任務預算設定；每個都與其自己的測試版標頭配對 | 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起轉發欄位及其標頭 |137| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[結構化輸出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 請求體欄位攜帶努力、結構化輸出格式和任務預算設定；每個都與其自己的測試版標頭配對 | 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起轉發欄位及其標頭 |

139 139

140`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [變數](/zh-TW/model-config)僅在提供者配置中聲明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。它們在 `ANTHROPIC_BASE_URL` gateway 後面沒有效果。140`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [變數](/docs/zh-TW/model-config)僅在提供者配置中聲明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。它們在 `ANTHROPIC_BASE_URL` gateway 後面沒有效果。

141 141

142<h3 id="automatic-retry-and-error-forwarding">142<h3 id="automatic-retry-and-error-forwarding">

143 自動重試和錯誤轉發143 自動重試和錯誤轉發

161 161

162當 `ANTHROPIC_BASE_URL` 指向公開 Anthropic Messages 格式的 gateway 時，Claude Code 可以在啟動時查詢 gateway 的 `/v1/models` 端點，並將返回的模型添加到 `/model` 選擇器。162當 `ANTHROPIC_BASE_URL` 指向公開 Anthropic Messages 格式的 gateway 時，Claude Code 可以在啟動時查詢 gateway 的 `/v1/models` 端點，並將返回的模型添加到 `/model` 選擇器。

163 163

164開發人員通過在自己的環境中或通過受管設定設定 [`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`](/zh-TW/env-vars) 來啟用它。預設情況下發現是關閉的，以便由共享 API 金鑰支持的 gateway 不會向每個使用者公開金鑰可以存取的每個模型。這需要 Claude Code v2.1.129 或更新版本。164開發人員通過在自己的環境中或通過受管設定設定 [`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`](/docs/zh-TW/env-vars) 來啟用它。預設情況下發現是關閉的，以便由共享 API 金鑰支持的 gateway 不會向每個使用者公開金鑰可以存取的每個模型。這需要 Claude Code v2.1.129 或更新版本。

165 165

166<h3 id="when-discovery-runs">166<h3 id="when-discovery-runs">

167 發現何時運行167 發現何時運行

171 171

172* 設定了任何 `CLAUDE_CODE_USE_*` 提供者變數，即使也設定了 `ANTHROPIC_BASE_URL`172* 設定了任何 `CLAUDE_CODE_USE_*` 提供者變數，即使也設定了 `ANTHROPIC_BASE_URL`

173* `ANTHROPIC_BASE_URL` 未設定或指向 `api.anthropic.com`173* `ANTHROPIC_BASE_URL` 未設定或指向 `api.anthropic.com`

174* 非必要流量被禁用，通過 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/zh-TW/env-vars) 或組織政策174* 非必要流量被禁用，通過 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 或組織政策

175 175

176<h3 id="request-and-response">176<h3 id="request-and-response">

177 請求和回應177 請求和回應

182發現請求恰好發送一個認證標頭：182發現請求恰好發送一個認證標頭：

183 183

184* 設定時 `ANTHROPIC_AUTH_TOKEN` 作為持有人令牌184* 設定時 `ANTHROPIC_AUTH_TOKEN` 作為持有人令牌

185* 否則解析的 API 金鑰，包括 [`apiKeyHelper`](/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 值，在 `x-api-key` 標頭中185* 否則解析的 API 金鑰，包括 [`apiKeyHelper`](/docs/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 值，在 `x-api-key` 標頭中

186 186

187這與推理請求不同，後者在兩個標頭中發送幫助程式值。驗證 `/v1/models` 的 gateway 必須為幫助程式部署接受 `x-api-key`。`ANTHROPIC_CUSTOM_HEADERS` 中的任何標頭也包括在內。187這與推理請求不同，後者在兩個標頭中發送幫助程式值。驗證 `/v1/models` 的 gateway 必須為幫助程式部署接受 `x-api-key`。`ANTHROPIC_CUSTOM_HEADERS` 中的任何標頭也包括在內。

188 188

201 選擇器條目和快取201 選擇器條目和快取

202</h3>202</h3>

203 203

204選擇器是當開發人員在 Claude Code 中運行 `/model` 時打開的互動式模型清單。每個發現的條目都標記為「來自 gateway」，並在提供時使用 `display_name`。[`availableModels` 受管設定](/zh-TW/settings#available-settings)限制發現可以添加的內容。204選擇器是當開發人員在 Claude Code 中運行 `/model` 時打開的互動式模型清單。每個發現的條目都標記為「來自 gateway」，並在提供時使用 `display_name`。[`availableModels` 受管設定](/docs/zh-TW/settings#available-settings)限制發現可以添加的內容。

205 205

206發現的 ID 僅在它完全匹配選擇器中已有的列，或當發現的和現有的 ID 都解析為 [Fable](/zh-TW/model-config#work-with-fable-5) 時才被跳過。{/* min-version: 2.1.197 */}自 Claude Code v2.1.197 起，發現的明確 ID 在兩者都解析為同一模型時也會折疊到內建條目中。內建列由別名（如 `sonnet`）鍵入，因此發現的明確 ID（如該別名目前解析到的模型 `claude-sonnet-5`）會折疊到 `sonnet` 列中，而別名不解析到的 ID（如 `claude-sonnet-4-6`）仍會在內建條目旁邊添加其自己的「來自 gateway」列。206發現的 ID 僅在它完全匹配選擇器中已有的列，或當發現的和現有的 ID 都解析為 [Fable](/docs/zh-TW/model-config#work-with-fable-5) 時才被跳過。自 Claude Code v2.1.197 起，發現的明確 ID 在兩者都解析為同一模型時也會折疊到內建條目中。內建列由別名（如 `sonnet`）鍵入，因此發現的明確 ID（如該別名目前解析到的模型 `claude-sonnet-5`）會折疊到 `sonnet` 列中，而別名不解析到的 ID（如 `claude-sonnet-4-6`）仍會在內建條目旁邊添加其自己的「來自 gateway」列。

207 207

208結果被快取到 `~/.claude/cache/gateway-models.json`，或在 Windows 上 `%USERPROFILE%\.claude\cache\gateway-models.json`，並在每次啟動時刷新。如果請求失敗或 gateway 未實現 `/v1/models`，選擇器會回退到上次啟動的快取清單或內建模型清單。如果您的 gateway 在不匹配發現篩選器的別名下提供 Claude 模型，開發人員可以使用[模型配置](/zh-TW/model-config)變數手動添加這些別名。208結果被快取到 `~/.claude/cache/gateway-models.json`，或在 Windows 上 `%USERPROFILE%\.claude\cache\gateway-models.json`，並在每次啟動時刷新。如果請求失敗或 gateway 未實現 `/v1/models`，選擇器會回退到上次啟動的快取清單或內建模型清單。如果您的 gateway 在不匹配發現篩選器的別名下提供 Claude 模型，開發人員可以使用[模型配置](/docs/zh-TW/model-config)變數手動添加這些別名。

209 209

210<h2 id="related-resources">210<h2 id="related-resources">

211 相關資源211 相關資源

213 213

214有關 gateway 文件集的其餘部分和基礎 API 參考：214有關 gateway 文件集的其餘部分和基礎 API 參考：

215 215

216* [Gateway 概述](/zh-TW/gateways)：什麼是 gateway 以及如何在 Claude 應用程式 gateway 和其他產品之間進行選擇216* [Gateway 概述](/docs/zh-TW/gateways)：什麼是 gateway 以及如何在 Claude 應用程式 gateway 和其他產品之間進行選擇

217* [其他 LLM gateway](/zh-TW/llm-gateway)：如何推出您的組織執行的 gateway 以及它如何與 claude.ai 訂閱互動217* [其他 LLM gateway](/docs/zh-TW/llm-gateway)：如何推出您的組織執行的 gateway 以及它如何與 claude.ai 訂閱互動

218* [為您的組織推出 LLM gateway](/zh-TW/llm-gateway-rollout)：使用此契約的管理員檢查清單218* [為您的組織推出 LLM gateway](/docs/zh-TW/llm-gateway-rollout)：使用此契約的管理員檢查清單

219* [將 Claude Code 連接到 LLM gateway](/zh-TW/llm-gateway-connect)：每個開發人員的配置和故障排除表219* [將 Claude Code 連接到 LLM gateway](/docs/zh-TW/llm-gateway-connect)：每個開發人員的配置和故障排除表

220* [測試版標頭參考](https://platform.claude.com/docs/en/api/beta-headers)：目前的 `anthropic-beta` 值集合220* [測試版標頭參考](https://platform.claude.com/docs/en/api/beta-headers)：目前的 `anthropic-beta` 值集合

221* [Messages API](https://platform.claude.com/docs/en/api/messages)：Anthropic 格式 gateway 實現的 API 格式221* [Messages API](https://platform.claude.com/docs/en/api/messages)：Anthropic 格式 gateway 實現的 API 格式

llm-gateway-rollout.md +30 −30

Details

9本頁面引導管理員為 Claude Code 推出 LLM 閘道。它假設您已部署符合[閘道要求](#gateway-requirements)的閘道產品。本頁面不涵蓋部署或操作任何特定產品；請按照您的供應商文件部署您的產品。9本頁面引導管理員為 Claude Code 推出 LLM 閘道。它假設您已部署符合[閘道要求](#gateway-requirements)的閘道產品。本頁面不涵蓋部署或操作任何特定產品；請按照您的供應商文件部署您的產品。

10 10

11<Note>11<Note>

~~12 * 若要將您自己機器上的 Claude Code 連接到現有閘道，請參閱[將 Claude Code 連接到 LLM 閘道](/zh-TW/llm-gateway-connect)~~12 * 若要將您自己機器上的 Claude Code 連接到現有閘道，請參閱[將 Claude Code 連接到 LLM 閘道](/docs/zh-TW/llm-gateway-connect)

~~13 * 若要了解 Claude Code 發送到閘道的內容以及要轉發的內容，請參閱[閘道協議參考](/zh-TW/llm-gateway-protocol)~~13 * 若要了解 Claude Code 發送到閘道的內容以及要轉發的內容，請參閱[閘道協議參考](/docs/zh-TW/llm-gateway-protocol)

14</Note>14</Note>

15 15

16<h2 id="prerequisites">16<h2 id="prerequisites">

22* 在您的基礎設施上部署的閘道，在您將分發給開發者的確切位址上提供 HTTPS，而不是重定向到它的位址，並配置為將 Claude 模型名稱路由到您的提供者22* 在您的基礎設施上部署的閘道，在您將分發給開發者的確切位址上提供 HTTPS，而不是重定向到它的位址，並配置為將 Claude 模型名稱路由到您的提供者

23* 閘道轉發的提供者認證：23* 閘道轉發的提供者認證：

24 * 對於 Anthropic API：來自 [Claude 控制台](https://platform.claude.com/settings/keys)的 API 金鑰24 * 對於 Anthropic API：來自 [Claude 控制台](https://platform.claude.com/settings/keys)的 API 金鑰

25 * 對於雲端提供者：具有模型存取權限的雲端認證。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock#prerequisites)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai#prerequisites) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry#prerequisites) 頁面上的先決條件25 * 對於雲端提供者：具有模型存取權限的雲端認證。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#prerequisites)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai#prerequisites) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry#prerequisites) 頁面上的先決條件

26* 一種將設定檔案傳遞到開發者機器的方式，例如 MDM 或配置管理26* 一種將設定檔案傳遞到開發者機器的方式，例如 MDM 或配置管理

~~27 * 如果您還沒有，[設定如何到達裝置](/zh-TW/admin-setup#decide-how-settings-reach-devices)會比較各選項~~27 * 如果您還沒有，[設定如何到達裝置](/docs/zh-TW/admin-setup#decide-how-settings-reach-devices)會比較各選項

28 28

29<h3 id="gateway-requirements">29<h3 id="gateway-requirements">

30 閘道要求30 閘道要求

32 32

33無論哪個產品提供閘道，它必須：33無論哪個產品提供閘道，它必須：

34 34

35* **接受支援的 API 格式**：[API 格式表](/zh-TW/llm-gateway-protocol#api-formats)中的格式之一。下面的推出步驟假設 Anthropic Messages API 位於 `POST /v1/messages`，大多數閘道都提供此格式35* **接受支援的 API 格式**：[API 格式表](/docs/zh-TW/llm-gateway-protocol#api-formats)中的格式之一。下面的推出步驟假設 Anthropic Messages API 位於 `POST /v1/messages`，大多數閘道都提供此格式

36* **串流回應**：按到達時傳遞伺服器發送的事件，而不是緩衝整個回應36* **串流回應**：按到達時傳遞伺服器發送的事件，而不是緩衝整個回應

37* **路由 Claude 模型名稱**：將開發者使用的每個名稱對應到上游模型。Claude Code 在每個請求中發送模型名稱，例如 `claude-sonnet-4-6`；在大多數閘道產品中，對應是閘道自己配置中的模型清單或路由表37* **路由 Claude 模型名稱**：將開發者使用的每個名稱對應到上游模型。Claude Code 在每個請求中發送模型名稱，例如 `claude-sonnet-4-6`；在大多數閘道產品中，對應是閘道自己配置中的模型清單或路由表

38* **轉發標頭和正文不變**：在兩個方向上傳遞 `anthropic-beta`、`anthropic-version` 和請求正文；[功能傳遞表](/zh-TW/llm-gateway-protocol#feature-pass-through)將每個對應到沒有它就會中斷的功能38* **轉發標頭和正文不變**：在兩個方向上傳遞 `anthropic-beta`、`anthropic-version` 和請求正文；[功能傳遞表](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)將每個對應到沒有它就會中斷的功能

39* **返回未修改的上游錯誤**：Claude Code 的自動恢復與錯誤措辭相符，因此在閘道自己的信封中包裝錯誤會破壞它39* **返回未修改的上游錯誤**：Claude Code 的自動恢復與錯誤措辭相符，因此在閘道自己的信封中包裝錯誤會破壞它

40* **豁免路徑免受請求正文 WAF 檢查**：Claude Code 提示包含原始程式碼和 XML 樣式標籤，與跨網站指令碼正文規則相符；閘道前面的 WAF 在真實工作階段上返回 `403`，而短測試請求通過40* **豁免路徑免受請求正文 WAF 檢查**：Claude Code 提示包含原始程式碼和 XML 樣式標籤，與跨網站指令碼正文規則相符；閘道前面的 WAF 在真實工作階段上返回 `403`，而短測試請求通過

41 41

~~42可選地，提供 `GET /v1/models` 以便 Claude Code 可以使用[模型發現](/zh-TW/llm-gateway-protocol#model-discovery)從您的閘道填充模型選擇器。{/* min-version: 2.1.129 */}~~42可選地，提供 `GET /v1/models` 以便 Claude Code 可以使用[模型發現](/docs/zh-TW/llm-gateway-protocol#model-discovery)從您的閘道填充模型選擇器。

43 43

44<h2 id="rollout-steps">44<h2 id="rollout-steps">

45 推出步驟45 推出步驟

96針對您的閘道路由配置中的每個 Claude 模型名稱重複請求一次。閘道未路由的名稱會向選擇它的任何開發者返回 `404`，因此在推出前測試每個名稱。96針對您的閘道路由配置中的每個 Claude 模型名稱重複請求一次。閘道未路由的名稱會向選擇它的任何開發者返回 `404`，因此在推出前測試每個名稱。

97 97

98<Note>98<Note>

99 避免在重定向後提供閘道。重定向可能會在推理請求上丟棄請求正文或去除認證標頭，[模型發現](/zh-TW/llm-gateway-protocol#model-discovery)將任何重定向視為失敗，因此認證無法洩露到重定向目標。99 避免在重定向後提供閘道。重定向可能會在推理請求上丟棄請求正文或去除認證標頭，[模型發現](/docs/zh-TW/llm-gateway-protocol#model-discovery)將任何重定向視為失敗，因此認證無法洩露到重定向目標。

100</Note>100</Note>

101 101

102<h3 id="issue-developer-credentials">102<h3 id="issue-developer-credentials">

130 130

131**檢查點**：帶有 `content` 欄位的 `200` 表示開發者金鑰到達閘道，閘道轉發它。當[前一步](#confirm-the-gateway-routes-your-models)成功時，此處的 `401` 表示開發者金鑰有誤或尚未在閘道上生效。131**檢查點**：帶有 `content` 欄位的 `200` 表示開發者金鑰到達閘道，閘道轉發它。當[前一步](#confirm-the-gateway-routes-your-models)成功時，此處的 `401` 表示開發者金鑰有誤或尚未在閘道上生效。

132 132

133為每個開發者發放一個金鑰而不是共用金鑰是使每個開發者的使用歸因和個別離職工作的原因。持有金鑰的環境變數取決於閘道讀取的標頭。對於在 `Authorization: Bearer` 標頭中檢查認證的閘道，開發者在 `ANTHROPIC_AUTH_TOKEN` 中設定他們的金鑰。對於從 `x-api-key` 標頭讀取金鑰的閘道，開發者改為設定 `ANTHROPIC_API_KEY`；[認證表](/zh-TW/llm-gateway-connect#set-the-credential-variable)涵蓋對應。133為每個開發者發放一個金鑰而不是共用金鑰是使每個開發者的使用歸因和個別離職工作的原因。持有金鑰的環境變數取決於閘道讀取的標頭。對於在 `Authorization: Bearer` 標頭中檢查認證的閘道，開發者在 `ANTHROPIC_AUTH_TOKEN` 中設定他們的金鑰。對於從 `x-api-key` 標頭讀取金鑰的閘道，開發者改為設定 `ANTHROPIC_API_KEY`；[認證表](/docs/zh-TW/llm-gateway-connect#set-the-credential-variable)涵蓋對應。

134 134

135<h3 id="test-claude-code-against-the-gateway">135<h3 id="test-claude-code-against-the-gateway">

136 針對閘道測試 Claude Code136 針對閘道測試 Claude Code

165* `Not logged in`：檢查閘道日誌以區分兩個原因。如果它是空的，沒有認證到達工作階段，沒有請求離開機器；在您測試的殼層中重新執行匯出。如果它顯示被拒絕的請求，在 `401` 正文中有 `x-api-key`，閘道期望金鑰在該標頭中；改為切換到 `ANTHROPIC_API_KEY`165* `Not logged in`：檢查閘道日誌以區分兩個原因。如果它是空的，沒有認證到達工作階段，沒有請求離開機器；在您測試的殼層中重新執行匯出。如果它顯示被拒絕的請求，在 `401` 正文中有 `x-api-key`，閘道期望金鑰在該標頭中；改為切換到 `ANTHROPIC_API_KEY`

166* `Failed to authenticate. API Error: 401` 表示認證已發送並被拒絕，閘道日誌說明位置：命名 `api.anthropic.com` 或您的提供者端點的 `401` 表示閘道到達上游但其提供者認證被拒絕，因此開發者金鑰有效，閘道持有的提供者認證有誤或是佔位符166* `Failed to authenticate. API Error: 401` 表示認證已發送並被拒絕，閘道日誌說明位置：命名 `api.anthropic.com` 或您的提供者端點的 `401` 表示閘道到達上游但其提供者認證被拒絕，因此開發者金鑰有效，閘道持有的提供者認證有誤或是佔位符

167 167

168錯誤或無法到達的基本 URL 會產生不同的症狀：Claude Code [以退避方式重試連接](/zh-TW/errors#automatic-retries)，在報告錯誤之前可能會坐著沒有輸出幾分鐘。如果命令似乎掛起，請檢查閘道日誌而不是等待；沒有到達的請求表示 `ANTHROPIC_BASE_URL` 未指向閘道。168錯誤或無法到達的基本 URL 會產生不同的症狀：Claude Code [以退避方式重試連接](/docs/zh-TW/errors#automatic-retries)，在報告錯誤之前可能會坐著沒有輸出幾分鐘。如果命令似乎掛起，請檢查閘道日誌而不是等待；沒有到達的請求表示 `ANTHROPIC_BASE_URL` 未指向閘道。

169 169

170<h3 id="distribute-the-configuration">170<h3 id="distribute-the-configuration">

171 分發配置171 分發配置

172</h3>172</h3>

173 173

174每個開發者機器都需要閘道位址和認證。您可以透過[受管設定](/zh-TW/settings#settings-files)集中分發它們，因此開發者無需配置任何內容，或者將值交給開發者自己設定。174每個開發者機器都需要閘道位址和認證。您可以透過[受管設定](/docs/zh-TW/settings#settings-files)集中分發它們，因此開發者無需配置任何內容，或者將值交給開發者自己設定。

175 175

176<h4 id="what-to-distribute">176<h4 id="what-to-distribute">

177 要分發的內容177 要分發的內容

188| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 停止 Claude Code 發送預發行功能標頭和正文欄位 | 您的閘道轉發到拒絕測試版欄位的 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游；請參閱[閘道要求](#gateway-requirements) |188| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 停止 Claude Code 發送預發行功能標頭和正文欄位 | 您的閘道轉發到拒絕測試版欄位的 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游；請參閱[閘道要求](#gateway-requirements) |

189| `ANTHROPIC_MODEL` 或 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-TW/model-config) | 設定 Claude Code 為主工作階段和背景流量請求的模型名稱 | 您的閘道路由與 Claude Code 預設值不符的模型名稱，或您將[背景功能](/zh-TW/costs#background-token-usage)路由到不同的模型。在閘道上路由覆蓋名稱和 Claude Code 的預設名稱，因為某些子呼叫可以請求預設名稱，無論覆蓋如何；[模型配置](/zh-TW/model-config)涵蓋工作階段的每個部分使用哪個模型 |189| `ANTHROPIC_MODEL` 或 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/zh-TW/model-config) | 設定 Claude Code 為主工作階段和背景流量請求的模型名稱 | 您的閘道路由與 Claude Code 預設值不符的模型名稱，或您將[背景功能](/docs/zh-TW/costs#background-token-usage)路由到不同的模型。在閘道上路由覆蓋名稱和 Claude Code 的預設名稱，因為某些子呼叫可以請求預設名稱，無論覆蓋如何；[模型配置](/docs/zh-TW/model-config)涵蓋工作階段的每個部分使用哪個模型 |

190| `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`、`ANTHROPIC_FOUNDRY_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 以及[該提供者的變數](/zh-TW/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | 透過提供者特定的基本 URL 將 Claude Code 指向閘道。Amazon Bedrock 和 Google Cloud 的 Agent Platform 也切換到這些提供者的原生請求格式 | 您的閘道前置 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude 平台；請參閱 [API 格式](/zh-TW/llm-gateway-protocol#api-formats) |190| `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`、`ANTHROPIC_FOUNDRY_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 以及[該提供者的變數](/docs/zh-TW/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | 透過提供者特定的基本 URL 將 Claude Code 指向閘道。Amazon Bedrock 和 Google Cloud 的 Agent Platform 也切換到這些提供者的原生請求格式 | 您的閘道前置 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude 平台；請參閱 [API 格式](/docs/zh-TW/llm-gateway-protocol#api-formats) |

191 191

192<h4 id="distribute-through-managed-settings">192<h4 id="distribute-through-managed-settings">

193 透過受管設定分發193 透過受管設定分發

194</h4>194</h4>

195 195

196透過由 MDM、登錄原則或配置管理推送的[受管設定檔案](/zh-TW/settings#settings-files)的 `env` 區塊傳遞變數：196透過由 MDM、登錄原則或配置管理推送的[受管設定檔案](/docs/zh-TW/settings#settings-files)的 `env` 區塊傳遞變數：

197 197

198```json theme={null}198```json theme={null}

199{199{

206 206

207將表中的條件變數新增到相同的 `env` 區塊。受管 `ANTHROPIC_BASE_URL` 被強制執行，無法被開發者的殼層匯出覆蓋，因為 Claude Code 在程序環境和較低優先順序設定上應用它。207將表中的條件變數新增到相同的 `env` 區塊。受管 `ANTHROPIC_BASE_URL` 被強制執行，無法被開發者的殼層匯出覆蓋，因為 Claude Code 在程序環境和較低優先順序設定上應用它。

208 208

209不要在受管設定中包括 `forceLoginMethod` 或 `forceLoginOrgUUID` 以及閘道認證。在 Claude Code v2.1.146 及更新版本上，任一金鑰在啟動時阻止 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 和 `apiKeyHelper`，因此開發者看到 `This machine's managed settings require a first-party login` 並無法繼續。{/* min-version: 2.1.146 */}209不要在受管設定中包括 `forceLoginMethod` 或 `forceLoginOrgUUID` 以及閘道認證。在 Claude Code v2.1.146 及更新版本上，任一金鑰在啟動時阻止 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 和 `apiKeyHelper`，因此開發者看到 `This machine's managed settings require a first-party login` 並無法繼續。

210 210

211[伺服器受管設定](/zh-TW/server-managed-settings#platform-availability)傳遞需要直接連接到 `api.anthropic.com`，因此無法到達閘道路由的工作階段。閘道部署使用此檔案型受管設定路徑，它強制執行相同的金鑰。211[伺服器受管設定](/docs/zh-TW/server-managed-settings#platform-availability)傳遞需要直接連接到 `api.anthropic.com`，因此無法到達閘道路由的工作階段。閘道部署使用此檔案型受管設定路徑，它強制執行相同的金鑰。

212 212

213對於認證，在受管設定檔案中分發一個 [`apiKeyHelper`](/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 命令，如上所示；該命令作為本地開發者驗證到您的秘密存放區，因此每個機器接收自己的金鑰。或者，透過您現有的秘密程序向每個開發者傳遞他們的金鑰，並讓他們自己設定 `ANTHROPIC_AUTH_TOKEN`。213對於認證，在受管設定檔案中分發一個 [`apiKeyHelper`](/docs/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 命令，如上所示；該命令作為本地開發者驗證到您的秘密存放區，因此每個機器接收自己的金鑰。或者，透過您現有的秘密程序向每個開發者傳遞他們的金鑰，並讓他們自己設定 `ANTHROPIC_AUTH_TOKEN`。

214 214

215某些環境需要單獨的傳遞：215某些環境需要單獨的傳遞：

216 216

217* 桌面應用程式僅從其 MDM 傳遞的第三方推理配置讀取閘道路由；部署該檔案以及受管設定，以便桌面工作階段也透過閘道路由。請參閱[桌面第三方配置文件](https://claude.com/docs/third-party/claude-desktop/configuration)和[桌面閘道文件](https://claude.com/docs/third-party/claude-desktop/gateway)217* 桌面應用程式僅從其 MDM 傳遞的第三方推理配置讀取閘道路由；部署該檔案以及受管設定，以便桌面工作階段也透過閘道路由。請參閱[桌面第三方配置文件](https://claude.com/docs/third-party/claude-desktop/configuration)和[桌面閘道文件](https://claude.com/docs/third-party/claude-desktop/gateway)

218* CI 執行器需要在[執行器的環境](/zh-TW/llm-gateway-connect#configure-each-surface)中設定 `ANTHROPIC_BASE_URL` 和認證218* CI 執行器需要在[執行器的環境](/docs/zh-TW/llm-gateway-connect#configure-each-surface)中設定 `ANTHROPIC_BASE_URL` 和認證

219* 受管 Windows 機器上的 WSL 僅在 [`wslInheritsWindowsSettings`](/zh-TW/settings#available-settings) 為 `true` 時讀取 Windows 受管設定219* 受管 Windows 機器上的 WSL 僅在 [`wslInheritsWindowsSettings`](/docs/zh-TW/settings#available-settings) 為 `true` 時讀取 Windows 受管設定

220 220

221<h4 id="hand-developers-the-values-to-set-themselves">221<h4 id="hand-developers-the-values-to-set-themselves">

222 將值交給開發者自己設定222 將值交給開發者自己設定

223</h4>223</h4>

224 224

225如果您沒有受管設定分發，請向每個開發者發送他們需要的內容，以遵循[連接頁面](/zh-TW/llm-gateway-connect#configure-claude-code-yourself)：225如果您沒有受管設定分發，請向每個開發者發送他們需要的內容，以遵循[連接頁面](/docs/zh-TW/llm-gateway-connect#configure-claude-code-yourself)：

226 226

227* 閘道 URL227* 閘道 URL

228* 他們的個人認證228* 他們的個人認證

229* **將認證放在哪個變數中**：對於承載令牌閘道為 `ANTHROPIC_AUTH_TOKEN`，或對於 `x-api-key` 閘道為 `ANTHROPIC_API_KEY`。告訴開發者哪一個可以節省他們在[連接頁面](/zh-TW/llm-gateway-connect#set-the-credential-variable)上描述的試錯229* **將認證放在哪個變數中**：對於承載令牌閘道為 `ANTHROPIC_AUTH_TOKEN`，或對於 `x-api-key` 閘道為 `ANTHROPIC_API_KEY`。告訴開發者哪一個可以節省他們在[連接頁面](/docs/zh-TW/llm-gateway-connect#set-the-credential-variable)上描述的試錯

230* [要分發的內容表](#what-to-distribute)中的任何條件變數，以及它們的值230* [要分發的內容表](#what-to-distribute)中的任何條件變數，以及它們的值

231 231

232[連接頁面](/zh-TW/llm-gateway-connect#configure-claude-code-yourself)引導開發者設定每一個。232[連接頁面](/docs/zh-TW/llm-gateway-connect#configure-claude-code-yourself)引導開發者設定每一個。

233 233

234**檢查點**：在開發者機器上，`claude` 啟動工作階段而不顯示登入畫面，因為分發的認證滿足身份驗證。然後執行 `/status` 並開啟 **Status** 標籤：`Anthropic base URL` 行顯示閘道位址，對於受管分發，`Setting sources` 行包括受管設定。登入畫面或缺少 `Anthropic base URL` 行表示配置未到達機器。234**檢查點**：在開發者機器上，`claude` 啟動工作階段而不顯示登入畫面，因為分發的認證滿足身份驗證。然後執行 `/status` 並開啟 **Status** 標籤：`Anthropic base URL` 行顯示閘道位址，對於受管分發，`Setting sources` 行包括受管設定。登入畫面或缺少 `Anthropic base URL` 行表示配置未到達機器。

235 235

270* `Failed to authenticate` 錯誤表示閘道拒絕請求；其日誌說明哪個認證失敗。閘道自己記錄的拒絕命名開發者金鑰，而來自 `api.anthropic.com` 或您的提供者端點的 `401` 表示閘道持有的提供者認證被拒絕270* `Failed to authenticate` 錯誤表示閘道拒絕請求；其日誌說明哪個認證失敗。閘道自己記錄的拒絕命名開發者金鑰，而來自 `api.anthropic.com` 或您的提供者端點的 `401` 表示閘道持有的提供者認證被拒絕

271* 當閘道期望金鑰在 `x-api-key` 標頭中時，首次使用時的一次性核准提示是預期的，設定為 `ANTHROPIC_API_KEY`。使用 `ANTHROPIC_AUTH_TOKEN`，不會出現提示，變數會無聲地接管；先前保存的 claude.ai 登入對該工作階段無效271* 當閘道期望金鑰在 `x-api-key` 標頭中時，首次使用時的一次性核准提示是預期的，設定為 `ANTHROPIC_API_KEY`。使用 `ANTHROPIC_AUTH_TOKEN`，不會出現提示，變數會無聲地接管；先前保存的 claude.ai 登入對該工作階段無效

272 272

273最後，檢查閘道的日誌以查看您發送的訊息：認證識別開發者，[`x-claude-code-session-id` 標頭](/zh-TW/llm-gateway-protocol#request-headers)按工作階段分組請求。如果功能因[故障排除症狀](/zh-TW/llm-gateway-connect#troubleshoot-gateway-errors)而失敗，閘道正在去除標頭或重寫錯誤；請參閱上面的[閘道要求](#gateway-requirements)。273最後，檢查閘道的日誌以查看您發送的訊息：認證識別開發者，[`x-claude-code-session-id` 標頭](/docs/zh-TW/llm-gateway-protocol#request-headers)按工作階段分組請求。如果功能因[故障排除症狀](/docs/zh-TW/llm-gateway-connect#troubleshoot-gateway-errors)而失敗，閘道正在去除標頭或重寫錯誤；請參閱上面的[閘道要求](#gateway-requirements)。

274 274

275<h2 id="maintain-the-gateway">275<h2 id="maintain-the-gateway">

276 維護閘道276 維護閘道

280 280

281| 變更 | 當閘道未跟上時的症狀 | 行動 |281| 變更 | 當閘道未跟上時的症狀 | 行動 |

282| :-------------------------------------------- | :------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- |282| :-------------------------------------------- | :------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- |

283| 新的 Claude Code 版本新增 `anthropic-beta` 值和請求正文欄位 | 開發者在更新 Claude Code 後報告 `400` 錯誤，命名新欄位；請參閱[功能傳遞](/zh-TW/llm-gateway-protocol#feature-pass-through) | 逐字轉發 `anthropic-*` 標頭和請求正文，而不是允許清單；在新 Claude Code 版本到達開發者之前針對閘道測試它們 |283| 新的 Claude Code 版本新增 `anthropic-beta` 值和請求正文欄位 | 開發者在更新 Claude Code 後報告 `400` 錯誤，命名新欄位；請參閱[功能傳遞](/docs/zh-TW/llm-gateway-protocol#feature-pass-through) | 逐字轉發 `anthropic-*` 標頭和請求正文，而不是允許清單；在新 Claude Code 版本到達開發者之前針對閘道測試它們 |

284| 新的 Claude 模型變得可用 | 開發者選擇新模型名稱時得到 `404`；`/model` 選擇器未列出它 | 將模型名稱新增到閘道的路由配置，然後重新執行[路由檢查](#confirm-the-gateway-routes-your-models)。如果您分發 `ANTHROPIC_MODEL` 或預設模型變數，請更新受管設定 |284| 新的 Claude 模型變得可用 | 開發者選擇新模型名稱時得到 `404`；`/model` 選擇器未列出它 | 將模型名稱新增到閘道的路由配置，然後重新執行[路由檢查](#confirm-the-gateway-routes-your-models)。如果您分發 `ANTHROPIC_MODEL` 或預設模型變數，請更新受管設定 |

285| 認證過期或需要輪換 | 所有開發者請求開始因來自上游的 `401` 而失敗 | 按照自己的時間表輪換閘道的提供者認證；開發者金鑰在閘道上輪換，[`apiKeyHelper`](/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 處理每個開發者的輪換，無需重新分發設定 |285| 認證過期或需要輪換 | 所有開發者請求開始因來自上游的 `401` 而失敗 | 按照自己的時間表輪換閘道的提供者認證；開發者金鑰在閘道上輪換，[`apiKeyHelper`](/docs/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 處理每個開發者的輪換，無需重新分發設定 |

286 286

287在調整每個金鑰的速率限制時，考慮用戶端[重試暫時性失敗](/zh-TW/errors#automatic-retries)，包括 `429` 回應，最多 10 次，帶有退避，尊重 `Retry-After`。將[協議參考](/zh-TW/llm-gateway-protocol)保持為每個 Claude Code 版本發送內容的合約。287在調整每個金鑰的速率限制時，考慮用戶端[重試暫時性失敗](/docs/zh-TW/errors#automatic-retries)，包括 `429` 回應，最多 10 次，帶有退避，尊重 `Retry-After`。將[協議參考](/docs/zh-TW/llm-gateway-protocol)保持為每個 Claude Code 版本發送內容的合約。

288 288

289<h2 id="related-resources">289<h2 id="related-resources">

290 相關資源290 相關資源

291</h2>291</h2>

292 292

293* [將 Claude Code 連接到 LLM 閘道](/zh-TW/llm-gateway-connect)：開發者面向的設定步驟，具有每個表面的配置和故障排除表，您可以交給開發者293* [將 Claude Code 連接到 LLM 閘道](/docs/zh-TW/llm-gateway-connect)：開發者面向的設定步驟，具有每個表面的配置和故障排除表，您可以交給開發者

294* [閘道協議參考](/zh-TW/llm-gateway-protocol)：閘道操作員的有線合約，涵蓋端點、要轉發的標頭和功能傳遞表294* [閘道協議參考](/docs/zh-TW/llm-gateway-protocol)：閘道操作員的有線合約，涵蓋端點、要轉發的標頭和功能傳遞表

295* [設定檔案和優先順序](/zh-TW/settings#settings-files)：受管、專案和使用者設定如何組合，以及受管檔案在每個平台上的位置295* [設定檔案和優先順序](/docs/zh-TW/settings#settings-files)：受管、專案和使用者設定如何組合，以及受管檔案在每個平台上的位置

296* [為您的組織設定 Claude Code](/zh-TW/admin-setup)：此閘道是其中一部分的更廣泛推出，包括原則強制執行、使用可見性和資料處理296* [為您的組織設定 Claude Code](/docs/zh-TW/admin-setup)：此閘道是其中一部分的更廣泛推出，包括原則強制執行、使用可見性和資料處理

managed-mcp.md +24 −24

Details

6 6

7> 使用受管配置檔案、允許清單和拒絕清單限制使用者可以新增或連接的 MCP 伺服器。7> 使用受管配置檔案、允許清單和拒絕清單限制使用者可以新增或連接的 MCP 伺服器。

8 8

9根據預設，任何執行 Claude Code 的人都可以連接他們選擇的任何 [MCP 伺服器](/zh-TW/mcp)。Anthropic 在將連接器新增到 [Anthropic Directory](https://claude.ai/directory) 之前會根據其 [列表標準](https://claude.com/docs/connectors/building/review-criteria) 審查連接器，但不會對任何 MCP 伺服器進行安全審計或管理。作為管理員，您可以限制在組織中執行的伺服器，從部署固定的已批准集合到完全停用 MCP。9根據預設，任何執行 Claude Code 的人都可以連接他們選擇的任何 [MCP 伺服器](/docs/zh-TW/mcp)。Anthropic 在將連接器新增到 [Anthropic Directory](https://claude.ai/directory) 之前會根據其 [列表標準](https://claude.com/docs/connectors/building/review-criteria) 審查連接器，但不會對任何 MCP 伺服器進行安全審計或管理。作為管理員，您可以限制在組織中執行的伺服器，從部署固定的已批准集合到完全停用 MCP。

10 10

11本頁涵蓋如何：11本頁涵蓋如何：

12 12

17* [監控您的組織實際使用的伺服器](#monitor-mcp-usage)17* [監控您的組織實際使用的伺服器](#monitor-mcp-usage)

18 18

19<Note>19<Note>

20 [安全](/zh-TW/security) 頁面涵蓋 MCP 威脅模型以及如何在批准伺服器之前評估它。[決定要強制執行的內容](/zh-TW/admin-setup#decide-what-to-enforce) 涵蓋 MCP 限制以及其他管理控制。20 [安全](/docs/zh-TW/security) 頁面涵蓋 MCP 威脅模型以及如何在批准伺服器之前評估它。[決定要強制執行的內容](/docs/zh-TW/admin-setup#decide-what-to-enforce) 涵蓋 MCP 限制以及其他管理控制。

21</Note>21</Note>

22 22

23<h2 id="choose-a-pattern">23<h2 id="choose-a-pattern">

37| **無限制** | 使用者新增任何內容 | 不部署任何受管 MCP 配置 |37| **無限制** | 使用者新增任何內容 | 不部署任何受管 MCP 配置 |

38 38

39<Note>39<Note>

40 Claude Code 沒有內建的 MCP 伺服器登錄表，使用者可以從中瀏覽和安裝。對於已批准目錄模式，在使用者會找到的地方（例如內部 wiki）共享已批准清單及其 `claude mcp add` 命令，或通過 [受管外掛程式市場](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) 將伺服器作為外掛程式分發，以便使用者可以從 `/plugin` 瀏覽和安裝它們。40 Claude Code 沒有內建的 MCP 伺服器登錄表，使用者可以從中瀏覽和安裝。對於已批准目錄模式，在使用者會找到的地方（例如內部 wiki）共享已批准清單及其 `claude mcp add` 命令，或通過 [受管外掛程式市場](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) 將伺服器作為外掛程式分發，以便使用者可以從 `/plugin` 瀏覽和安裝它們。

41</Note>41</Note>

42 42

43<h2 id="exclusive-control-with-managed-mcp-json">43<h2 id="exclusive-control-with-managed-mcp-json">

53 53

54有關檢查的完整順序，請參閱 [伺服器如何被評估](#how-a-server-is-evaluated)。54有關檢查的完整順序，請參閱 [伺服器如何被評估](#how-a-server-is-evaluated)。

55 55

56`managed-mcp.json` 是一個獨立檔案，因此無法通過 [伺服器受管設定](/zh-TW/server-managed-settings) 傳遞。任何可以寫入具有管理員權限的系統路徑的程序都可以部署它。在大規模部署中，通常通過裝置管理工具進行，例如 macOS 上的 Jamf 或配置檔案、Windows 上的群組原則或 Intune，或 Linux 上您選擇的艦隊管理。Claude Code 在以下路徑之一查找該檔案：56`managed-mcp.json` 是一個獨立檔案，因此無法通過 [伺服器受管設定](/docs/zh-TW/server-managed-settings) 傳遞。任何可以寫入具有管理員權限的系統路徑的程序都可以部署它。在大規模部署中，通常通過裝置管理工具進行，例如 macOS 上的 Jamf 或配置檔案、Windows 上的群組原則或 Intune，或 Linux 上您選擇的艦隊管理。Claude Code 在以下路徑之一查找該檔案：

57 57

58| 平台 | 路徑 |58| 平台 | 路徑 |

59| :---------- | :--------------------------------------------------------- |59| :---------- | :--------------------------------------------------------- |

61| Linux 和 WSL | `/etc/claude-code/managed-mcp.json` |61| Linux 和 WSL | `/etc/claude-code/managed-mcp.json` |

62| Windows | `C:\Program Files\ClaudeCode\managed-mcp.json` |62| Windows | `C:\Program Files\ClaudeCode\managed-mcp.json` |

63 63

~~64該檔案使用與專案 [`.mcp.json`](/zh-TW/mcp#project-scope) 檔案相同的格式：~~64該檔案使用與專案 [`.mcp.json`](/docs/zh-TW/mcp#project-scope) 檔案相同的格式：

65 65

66```json theme={null}66```json theme={null}

67{67{

92 92

93機器上的任何使用者都可以讀取此檔案，因此不要在 `env` 區塊中儲存 API 金鑰或其他認證。改用以下其中一種方式傳遞每個使用者的認證：93機器上的任何使用者都可以讀取此檔案，因此不要在 `env` 區塊中儲存 API 金鑰或其他認證。改用以下其中一種方式傳遞每個使用者的認證：

94 94

~~95* [`${VAR}` 擴展](/zh-TW/mcp#environment-variable-expansion-in-mcp-json) 從每個使用者的環境中讀取機密。~~95* [`${VAR}` 擴展](/docs/zh-TW/mcp#environment-variable-expansion-in-mcp-json) 從每個使用者的環境中讀取機密。

~~96* [OAuth 或每個使用者的標頭](/zh-TW/mcp#authenticate-with-remote-mcp-servers) 以便每個使用者以自己的身份進行身份驗證。~~96* [OAuth 或每個使用者的標頭](/docs/zh-TW/mcp#authenticate-with-remote-mcp-servers) 以便每個使用者以自己的身份進行身份驗證。

~~97* [`headersHelper`](/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 在連接時生成認證。~~97* [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 在連接時生成認證。

98 98

99<h3 id="validate-the-configuration">99<h3 id="validate-the-configuration">

100 驗證配置100 驗證配置

123 允許 claude.ai 連接器與受管集合並存123 允許 claude.ai 連接器與受管集合並存

124</h3>124</h3>

125 125

126部署 `managed-mcp.json` 預設會抑制 [claude.ai 連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)，包括管理員在 claude.ai 管理控制台中為組織配置的連接器。要將這些連接器與 `managed-mcp.json` 中的伺服器一起載入，請在 [受管設定來源](/zh-TW/admin-setup#decide-how-settings-reach-devices) 中設定 `"allowAllClaudeAiMcps": true`。需要 Claude Code v2.1.149 或更新版本。126部署 `managed-mcp.json` 預設會抑制 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)，包括管理員在 claude.ai 管理控制台中為組織配置的連接器。要將這些連接器與 `managed-mcp.json` 中的伺服器一起載入，請在 [受管設定來源](/docs/zh-TW/admin-setup#decide-how-settings-reach-devices) 中設定 `"allowAllClaudeAiMcps": true`。需要 Claude Code v2.1.149 或更新版本。

127 127

128啟用此設定後，Claude Code 會載入與未部署 `managed-mcp.json` 時相同的 claude.ai 連接器。[允許清單和拒絕清單](#policy-based-control-with-allowlists-and-denylists) 仍然適用於這些連接器，因此您可以使用 `deniedMcpServers` 阻止特定連接器。此設定僅影響 claude.ai 連接器；外掛程式提供的伺服器保持被抑制。128啟用此設定後，Claude Code 會載入與未部署 `managed-mcp.json` 時相同的 claude.ai 連接器。[允許清單和拒絕清單](#policy-based-control-with-allowlists-and-denylists) 仍然適用於這些連接器，因此您可以使用 `deniedMcpServers` 阻止特定連接器。此設定僅影響 claude.ai 連接器；外掛程式提供的伺服器保持被抑制。

129 129

133 使用允許清單和拒絕清單進行基於原則的控制133 使用允許清單和拒絕清單進行基於原則的控制

134</h2>134</h2>

135 135

136允許清單和拒絕清單篩選允許載入的已配置伺服器。它們不是登錄表：伺服器仍然必須由使用者、外掛程式或 `managed-mcp.json` 新增，然後允許清單或拒絕清單才會應用於它。要將伺服器部署給使用者，請使用 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json)。兩個清單也會篩選使用 [`--mcp-config` CLI 旗標](/zh-TW/cli-reference#cli-flags) 傳遞的伺服器；`--strict-mcp-config` 限制載入的配置檔案，不會繞過任一清單。136允許清單和拒絕清單篩選允許載入的已配置伺服器。它們不是登錄表：伺服器仍然必須由使用者、外掛程式或 `managed-mcp.json` 新增，然後允許清單或拒絕清單才會應用於它。要將伺服器部署給使用者，請使用 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json)。兩個清單也會篩選使用 [`--mcp-config` CLI 旗標](/docs/zh-TW/cli-reference#cli-flags) 傳遞的伺服器；`--strict-mcp-config` 限制載入的配置檔案，不會繞過任一清單。

137 137

138要使允許清單具有權威性，請在 [受管設定來源](/zh-TW/admin-setup#decide-how-settings-reach-devices)（例如伺服器受管設定或已部署的 `managed-settings.json` 檔案）中一起設定 `allowedMcpServers` 和 `allowManagedMcpServersOnly: true`。[將允許清單限制為僅受管設定](#restrict-the-allowlist-to-managed-settings-only) 顯示配置。沒有 `allowManagedMcpServersOnly`，來自每個設定來源的允許清單會合併，包括使用者自己的 `~/.claude/settings.json`，因此使用者可以擴展您的允許清單允許的內容。拒絕清單無論如何都會從每個來源合併。138要使允許清單具有權威性，請在 [受管設定來源](/docs/zh-TW/admin-setup#decide-how-settings-reach-devices)（例如伺服器受管設定或已部署的 `managed-settings.json` 檔案）中一起設定 `allowedMcpServers` 和 `allowManagedMcpServersOnly: true`。[將允許清單限制為僅受管設定](#restrict-the-allowlist-to-managed-settings-only) 顯示配置。沒有 `allowManagedMcpServersOnly`，來自每個設定來源的允許清單會合併，包括使用者自己的 `~/.claude/settings.json`，因此使用者可以擴展您的允許清單允許的內容。拒絕清單無論如何都會從每個來源合併。

139 139

140<Note>140<Note>

141 `allowManagedMcpServersOnly` 與 `allowManagedPermissionRulesOnly` 分開，後者鎖定 [權限規則](/zh-TW/permissions#managed-settings) 只。設定該標誌不會強制執行 MCP 允許清單。141 `allowManagedMcpServersOnly` 與 `allowManagedPermissionRulesOnly` 分開，後者鎖定 [權限規則](/docs/zh-TW/permissions#managed-settings) 只。設定該標誌不會強制執行 MCP 允許清單。

142</Note>142</Note>

143 143

144<h3 id="match-servers-by-url-command-or-name">144<h3 id="match-servers-by-url-command-or-name">

162 162

163請參閱 [受管設定中的無效條目](/zh-TW/settings#invalid-entries-in-managed-settings) 以了解當條目無法通過結構描述驗證時會發生什麼。163請參閱 [受管設定中的無效條目](/docs/zh-TW/settings#invalid-entries-in-managed-settings) 以了解當條目無法通過結構描述驗證時會發生什麼。

164 164

165<Warning>165<Warning>

166 `serverName` 條目（在任一清單中）不是安全控制。名稱是使用者在執行 `claude mcp add` 或編輯配置檔案時指派的標籤，而不是基礎伺服器，因此使用者可以呼叫任何伺服器 `github`。對於 claude.ai 連接器，名稱是 claude.ai 傳回的顯示名稱，可能會變更。要強制執行實際執行的伺服器，請新增 `serverCommand` 或 `serverUrl` 條目。166 `serverName` 條目（在任一清單中）不是安全控制。名稱是使用者在執行 `claude mcp add` 或編輯配置檔案時指派的標籤，而不是基礎伺服器，因此使用者可以呼叫任何伺服器 `github`。對於 claude.ai 連接器，名稱是 claude.ai 傳回的顯示名稱，可能會變更。要強制執行實際執行的伺服器，請新增 `serverCommand` 或 `serverUrl` 條目。

168 168

169`serverName` 驗證在兩個清單之間有所不同：169`serverName` 驗證在兩個清單之間有所不同：

170 170

171* {/* min-version: 2.1.182 */}在 `deniedMcpServers` 中，`serverName` 接受任何非空字串，因此您可以按顯示名稱阻止 [claude.ai 連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。例如，`{ "serverName": "claude.ai Slack" }` 阻止 Slack 連接器。當您需要拒絕對重新命名具有魯棒性時，或當連接器名稱衝突並獲得 ` (N)` 尾碼時，優先使用 `serverUrl` 條目。171* 在 `deniedMcpServers` 中，`serverName` 接受任何非空字串，因此您可以按顯示名稱阻止 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。例如，`{ "serverName": "claude.ai Slack" }` 阻止 Slack 連接器。當您需要拒絕對重新命名具有魯棒性時，或當連接器名稱衝突並獲得 ` (N)` 尾碼時，優先使用 `serverUrl` 條目。

172* 在 `allowedMcpServers` 中，`serverName` 限制為字母、數字、連字號和底線。使用 `serverUrl` 來允許列出 claude.ai 連接器。172* 在 `allowedMcpServers` 中，`serverName` 限制為字母、數字、連字號和底線。使用 `serverUrl` 來允許列出 claude.ai 連接器。

173 173

174要關閉所有 claude.ai 連接器，請參閱 [`disableClaudeAiConnectors`](/zh-TW/mcp#disable-claude-ai-connectors)。174要關閉所有 claude.ai 連接器，請參閱 [`disableClaudeAiConnectors`](/docs/zh-TW/mcp#disable-claude-ai-connectors)。

175 175

176<h3 id="how-a-server-is-evaluated">176<h3 id="how-a-server-is-evaluated">

177 伺服器如何被評估177 伺服器如何被評估

191這些檢查中適用三個匹配規則：191這些檢查中適用三個匹配規則：

192 192

193* **命令精確匹配。** 每個引數，按順序。`["npx", "-y", "server"]` 不匹配 `["npx", "server"]` 或 `["npx", "-y", "server", "--flag"]`。193* **命令精確匹配。** 每個引數，按順序。`["npx", "-y", "server"]` 不匹配 `["npx", "server"]` 或 `["npx", "-y", "server", "--flag"]`。

194* **`serverCommand` 和 `serverUrl` 值在匹配前展開。** 原則條目和伺服器的配置值都會經過與 `.mcp.json` 相同的 [`${VAR}` 和 `${VAR:-default}` 展開](/zh-TW/mcp#environment-variable-expansion-in-mcp-json)，因此寫成 `["${HOME}/bin/server"]` 的條目會匹配使用相同參考或展開路徑的伺服器配置。在 Windows 上，參考在那裡設定的環境變數，例如 `${USERPROFILE}` 而不是 `${HOME}`。`serverName` 值按字面匹配，永遠不展開。194* **`serverCommand` 和 `serverUrl` 值在匹配前展開。** 原則條目和伺服器的配置值都會經過與 `.mcp.json` 相同的 [`${VAR}` 和 `${VAR:-default}` 展開](/docs/zh-TW/mcp#environment-variable-expansion-in-mcp-json)，因此寫成 `["${HOME}/bin/server"]` 的條目會匹配使用相同參考或展開路徑的伺服器配置。在 Windows 上，參考在那裡設定的環境變數，例如 `${USERPROFILE}` 而不是 `${HOME}`。`serverName` 值按字面匹配，永遠不展開。

195* **URL 支援 `*` 萬用字元** 在模式中的任何地方，包括方案。主機名匹配不區分大小寫，忽略尾部 FQDN 點，因此 `https://Mcp.Example.com/*` 匹配 `https://mcp.example.com/api`。路徑保持區分大小寫。195* **URL 支援 `*` 萬用字元** 在模式中的任何地方，包括方案。主機名匹配不區分大小寫，忽略尾部 FQDN 點，因此 `https://Mcp.Example.com/*` 匹配 `https://mcp.example.com/api`。路徑保持區分大小寫。

196 196

197| 模式 | 允許 |197| 模式 | 允許 |

363 監控 MCP 使用363 監控 MCP 使用

364</h2>364</h2>

365 365

366當 [OpenTelemetry 匯出](/zh-TW/monitoring-usage) 配置時，Claude Code 可以記錄使用者呼叫的 MCP 伺服器和工具。設定 `OTEL_LOG_TOOL_DETAILS=1` 以在工具事件中包含 MCP 伺服器和工具名稱，然後在您的收集器中聚合它們以查看您的使用者實際連接到的伺服器。請參閱 [監控](/zh-TW/monitoring-usage) 以設定匯出器和完整事件架構。366當 [OpenTelemetry 匯出](/docs/zh-TW/monitoring-usage) 配置時，Claude Code 可以記錄使用者呼叫的 MCP 伺服器和工具。設定 `OTEL_LOG_TOOL_DETAILS=1` 以在工具事件中包含 MCP 伺服器和工具名稱，然後在您的收集器中聚合它們以查看您的使用者實際連接到的伺服器。請參閱 [監控](/docs/zh-TW/monitoring-usage) 以設定匯出器和完整事件架構。

367 367

368<h2 id="configuration-summary">368<h2 id="configuration-summary">

369 配置摘要369 配置摘要

374| 表面 | 控制的內容 | 位置 | 傳遞方式 |374| 表面 | 控制的內容 | 位置 | 傳遞方式 |

375| :--------------------------- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |375| :--------------------------- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |

377| `allowedMcpServers` | 允許的伺服器允許清單 | 任何 [設定檔案](/zh-TW/settings#settings-files)；來自每個來源的條目合併，除非設定了 `allowManagedMcpServersOnly` | 為了強制執行，[受管設定來源](/zh-TW/admin-setup#decide-how-settings-reach-devices)：伺服器受管設定、`managed-settings.json`、MDM 設定檔或登錄 |377| `allowedMcpServers` | 允許的伺服器允許清單 | 任何 [設定檔案](/docs/zh-TW/settings#settings-files)；來自每個來源的條目合併，除非設定了 `allowManagedMcpServersOnly` | 為了強制執行，[受管設定來源](/docs/zh-TW/admin-setup#decide-how-settings-reach-devices)：伺服器受管設定、`managed-settings.json`、MDM 設定檔或登錄 |

383 相關資源383 相關資源

384</h2>384</h2>

385 385

386* [決定要強制執行的內容](/zh-TW/admin-setup#decide-what-to-enforce)：MCP 限制以及權限規則、沙箱和其他管理控制386* [決定要強制執行的內容](/docs/zh-TW/admin-setup#decide-what-to-enforce)：MCP 限制以及權限規則、沙箱和其他管理控制

387* [通過 MCP 將 Claude Code 連接到工具](/zh-TW/mcp)：完整的 MCP 參考，包括傳輸、範圍和身份驗證387* [通過 MCP 將 Claude Code 連接到工具](/docs/zh-TW/mcp)：完整的 MCP 參考，包括傳輸、範圍和身份驗證

388* [設定](/zh-TW/settings)：設定層次結構以及受管設定如何優先388* [設定](/docs/zh-TW/settings)：設定層次結構以及受管設定如何優先

389* [伺服器受管設定](/zh-TW/server-managed-settings)：從 Claude.ai 管理控制台傳遞 `allowedMcpServers` 和 `deniedMcpServers`389* [伺服器受管設定](/docs/zh-TW/server-managed-settings)：從 Claude.ai 管理控制台傳遞 `allowedMcpServers` 和 `deniedMcpServers`

390* [安全](/zh-TW/security)：這些控制防禦的威脅模型390* [安全](/docs/zh-TW/security)：這些控制防禦的威脅模型

391* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、座位管理和推出劇本391* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、座位管理和推出劇本

mcp.md +36 −36

Details

10 10

11當您發現自己從另一個工具（例如問題追蹤器或監控儀表板）複製資料到聊天中時，請連接一個 server。連接後，Claude 可以直接讀取和操作該系統，而不是根據您貼上的內容進行工作。11當您發現自己從另一個工具（例如問題追蹤器或監控儀表板）複製資料到聊天中時，請連接一個 server。連接後，Claude 可以直接讀取和操作該系統，而不是根據您貼上的內容進行工作。

12 12

~~13如果您是第一次連接 server，請從 [MCP 快速入門](/zh-TW/mcp-quickstart) 開始，以取得逐步說明。本頁面是完整參考。~~13如果您是第一次連接 server，請從 [MCP 快速入門](/docs/zh-TW/mcp-quickstart) 開始，以取得逐步說明。本頁面是完整參考。

14 14

15<h2 id="what-you-can-do-with-mcp">15<h2 id="what-you-can-do-with-mcp">

16 使用 MCP 可以做什麼16 使用 MCP 可以做什麼

23* **查詢資料庫**："根據我們的 PostgreSQL 資料庫，找到 10 個使用功能 ENG-4521 的隨機使用者的電子郵件。"23* **查詢資料庫**："根據我們的 PostgreSQL 資料庫，找到 10 個使用功能 ENG-4521 的隨機使用者的電子郵件。"

24* **整合設計**："根據在 Slack 中發佈的新 Figma 設計更新我們的標準電子郵件範本"24* **整合設計**："根據在 Slack 中發佈的新 Figma 設計更新我們的標準電子郵件範本"

25* **自動化工作流程**："建立 Gmail 草稿，邀請這 10 個使用者參加關於新功能的回饋會議。"25* **自動化工作流程**："建立 Gmail 草稿，邀請這 10 個使用者參加關於新功能的回饋會議。"

26* **回應外部事件**：MCP server 也可以充當 [channel](/zh-TW/channels)，將訊息推送到您的 session 中，因此當您不在時，Claude 可以回應 Telegram 訊息、Discord 聊天或 webhook 事件。26* **回應外部事件**：MCP server 也可以充當 [channel](/docs/zh-TW/channels)，將訊息推送到您的 session 中，因此當您不在時，Claude 可以回應 Telegram 訊息、Discord 聊天或 webhook 事件。

27 27

28<h2 id="find-and-build-mcp-servers">28<h2 id="find-and-build-mcp-servers">

29 尋找並建立 MCP servers29 尋找並建立 MCP servers

32在 [Anthropic Directory](https://claude.ai/directory) 中瀏覽已審核的連接器。Directory 連接器使用與 Claude Code 相同的 MCP 基礎設施，因此您可以使用 `claude mcp add` 新增任何列在其中的遠端伺服器。32在 [Anthropic Directory](https://claude.ai/directory) 中瀏覽已審核的連接器。Directory 連接器使用與 Claude Code 相同的 MCP 基礎設施，因此您可以使用 `claude mcp add` 新增任何列在其中的遠端伺服器。

33 33

34<Warning>34<Warning>

~~35 在連接伺服器之前，請驗證您信任每個伺服器。取得外部內容的伺服器可能會使您面臨[提示注入風險](/zh-TW/security#protect-against-prompt-injection)。~~35 在連接伺服器之前，請驗證您信任每個伺服器。取得外部內容的伺服器可能會使您面臨[提示注入風險](/docs/zh-TW/security#protect-against-prompt-injection)。

36</Warning>36</Warning>

37 37

38若要建立您自己的伺服器，請參閱 [MCP server 指南](https://modelcontextprotocol.io/docs/develop/build-server) 以了解協議基礎知識，以及 [Claude 連接器建立文件](https://claude.com/docs/connectors/building) 以了解身份驗證、測試和 Directory 提交。38若要建立您自己的伺服器，請參閱 [MCP server 指南](https://modelcontextprotocol.io/docs/develop/build-server) 以了解協議基礎知識，以及 [Claude 連接器建立文件](https://claude.com/docs/connectors/building) 以了解身份驗證、測試和 Directory 提交。

115 115

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

117 117

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

119 119

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

121 121

180 180

181來自 `.mcp.json` 的專案範圍 servers 等待您的批准時，會在 `claude mcp list` 中顯示為 `⏸ Pending approval`。執行 `claude` 互動式命令以檢查和批准它們。`claude mcp get <name>` 將待處理的 servers 顯示為 `⏸ Pending approval`，將被拒絕的 servers 顯示為 `✗ Rejected`。181來自 `.mcp.json` 的專案範圍 servers 等待您的批准時，會在 `claude mcp list` 中顯示為 `⏸ Pending approval`。執行 `claude` 互動式命令以檢查和批准它們。`claude mcp get <name>` 將待處理的 servers 顯示為 `⏸ Pending approval`，將被拒絕的 servers 顯示為 `✗ Rejected`。

182 182

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

184 184

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

186 186

188* 受管設定188* 受管設定

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

190 190

191未追蹤的 `.claude/settings.local.json` 中的批准也適用，但僅在您接受該資料夾或其父目錄之一的信任對話框後：Claude Code 執行 git 以檢查檔案是否被追蹤，並且僅在受信任的資料夾中執行該檢查。在您從未信任的資料夾中，檔案的批准會等待信任對話框，除非該資料夾是您自己的配置主目錄：您的主目錄，或您已設定為 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars) 的 `.claude` 的目錄。在 v2.1.207 之前，未追蹤的 `.claude/settings.local.json` 在您從未信任的資料夾中批准了 servers。191未追蹤的 `.claude/settings.local.json` 中的批准也適用，但僅在您接受該資料夾或其父目錄之一的信任對話框後：Claude Code 執行 git 以檢查檔案是否被追蹤，並且僅在受信任的資料夾中執行該檢查。在您從未信任的資料夾中，檔案的批准會等待信任對話框，除非該資料夾是您自己的配置主目錄：您的主目錄，或您已設定為 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 的 `.claude` 的目錄。在 v2.1.207 之前，未追蹤的 `.claude/settings.local.json` 在您從未信任的資料夾中批准了 servers。

192 192

193任何設定檔案中的 `disabledMcpjsonServers` 項目仍然會拒絕 server。193任何設定檔案中的 `disabledMcpjsonServers` 項目仍然會拒絕 server。

194 194

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

196 196

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

198 198

199如果您的請求需要來自仍在背景連接的 server 的工具，Claude 會在繼續之前等待該 server。啟用 [tool search](#scale-with-mcp-tool-search)（預設啟用）後，等待會在 `ToolSearch` 呼叫內進行。在沒有工具搜尋的配置中，例如 Google Cloud 的 Agent Platform、自訂 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`，Claude 會改用 `WaitForMcpServers` 工具。199如果您的請求需要來自仍在背景連接的 server 的工具，Claude 會在繼續之前等待該 server。啟用 [tool search](#scale-with-mcp-tool-search)（預設啟用）後，等待會在 `ToolSearch` 呼叫內進行。在沒有工具搜尋的配置中，例如 Google Cloud 的 Agent Platform、自訂 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`，Claude 會改用 `WaitForMcpServers` 工具。

200 200

201某些 server 名稱保留供 Claude Code 的內建 servers 使用：`workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定義了具有保留名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。`claude mcp add` 會以錯誤拒絕保留名稱。201某些 server 名稱保留供 Claude Code 的內建 servers 使用：`workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定義了具有保留名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。`claude mcp add` 會以錯誤拒絕保留名稱。

202 202

203`Claude Preview` 和 `Claude Browser` 都命名了 [Claude Code 桌面應用程式的預覽窗格](/zh-TW/desktop#preview-your-app)使用的內建 server。在 v2.1.205 之前，`Claude Browser` 未被保留，因此使用者配置的 server 可以在該名稱下註冊。203`Claude Preview` 和 `Claude Browser` 都命名了 [Claude Code 桌面應用程式的預覽窗格](/docs/zh-TW/desktop#preview-your-app)使用的內建 server。在 v2.1.205 之前，`Claude Browser` 未被保留，因此使用者配置的 server 可以在該名稱下註冊。

204 204

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

206 動態工具更新206 動態工具更新

224 使用 channels 推送訊息224 使用 channels 推送訊息

225</h3>225</h3>

226 226

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

228 228

229<Tip>229<Tip>

230 提示：230 提示：

241 * 使用 `/mcp` 向需要 OAuth 2.0 驗證的遠端 servers 進行驗證241 * 使用 `/mcp` 向需要 OAuth 2.0 驗證的遠端 servers 進行驗證

242</Tip>242</Tip>

243 243

244每個 server 的 `timeout` 是每個工具呼叫的硬牆鐘限制，來自 server 的進度通知不會延長它。低於 1000 的值會被忽略並落回到 `MCP_TOOL_TIMEOUT`，或在該變數未設定時落回到其預設值約 28 小時。對於 HTTP、SSE 或 [claude.ai connector](/zh-TW/mcp#use-mcp-servers-from-claude-ai) server，還有第二個每個請求的計時器，涵蓋每個請求直到 server 的第一個回應位元組。該計時器為 60 秒，除非您設定每個 server 的 `timeout` 或 `MCP_TOOL_TIMEOUT`；將任一設定為 60 秒或更高會將每個請求的計時器提高到該值，較低的值不會縮短它，未設定的 `MCP_TOOL_TIMEOUT` 的 28 小時預設值永遠不會提供給它。Stdio 和 WebSocket servers 沒有每個請求的計時器。{/* min-version: 2.1.162 */}在 v2.1.162 之前，低於 1000 的值被調整為一秒。244每個 server 的 `timeout` 是每個工具呼叫的硬牆鐘限制，來自 server 的進度通知不會延長它。低於 1000 的值會被忽略並落回到 `MCP_TOOL_TIMEOUT`，或在該變數未設定時落回到其預設值約 28 小時。對於 HTTP、SSE 或 [claude.ai connector](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) server，還有第二個每個請求的計時器，涵蓋每個請求直到 server 的第一個回應位元組。該計時器為 60 秒，除非您設定每個 server 的 `timeout` 或 `MCP_TOOL_TIMEOUT`；將任一設定為 60 秒或更高會將每個請求的計時器提高到該值，較低的值不會縮短它，未設定的 `MCP_TOOL_TIMEOUT` 的 28 小時預設值永遠不會提供給它。Stdio 和 WebSocket servers 沒有每個請求的計時器。在 v2.1.162 之前，低於 1000 的值被調整為一秒。

245 245

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

247 247

248對遠端 MCP server 的工具呼叫如果在閒置視窗內沒有傳送回應和進度通知，會以錯誤中止，而不是等待牆鐘限制。閒置逾時需要 Claude Code v2.1.187 或更新版本。{/* min-version: 2.1.203 */}它適用於除 IDE servers 和 SDK 進程內 servers 之外的每種 server 類型。HTTP、SSE、WebSocket 和 [claude.ai connector](#use-mcp-servers-from-claude-ai) servers 的閒置視窗預設為五分鐘，stdio servers 的預設為 30 分鐘。在 v2.1.203 之前，stdio servers 不受閒置逾時限制。248對遠端 MCP server 的工具呼叫如果在閒置視窗內沒有傳送回應和進度通知，會以錯誤中止，而不是等待牆鐘限制。閒置逾時需要 Claude Code v2.1.187 或更新版本。它適用於除 IDE servers 和 SDK 進程內 servers 之外的每種 server 類型。HTTP、SSE、WebSocket 和 [claude.ai connector](#use-mcp-servers-from-claude-ai) servers 的閒置視窗預設為五分鐘，stdio servers 的預設為 30 分鐘。在 v2.1.203 之前，stdio servers 不受閒置逾時限制。

249 249

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

251 251

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

253 Plugin 提供的 MCP servers253 Plugin 提供的 MCP servers

254</h3>254</h3>

255 255

256[Plugins](/zh-TW/plugins) 可以捆綁 MCP servers，在啟用 plugin 時自動提供工具和整合。Plugin MCP servers 的工作方式與使用者配置的 servers 相同。256[Plugins](/docs/zh-TW/plugins) 可以捆綁 MCP servers，在啟用 plugin 時自動提供工具和整合。Plugin MCP servers 的工作方式與使用者配置的 servers 相同。

257 257

258**Plugin MCP servers 的工作方式**：258**Plugin MCP servers 的工作方式**：

259 259

297**Plugin MCP 功能**：297**Plugin MCP 功能**：

298 298

299* **自動生命週期**：在 session 啟動時，已啟用 plugins 的 servers 會自動連接。如果您在 session 期間啟用或停用 plugin，請執行 `/reload-plugins` 以連接或斷開其 MCP servers299* **自動生命週期**：在 session 啟動時，已啟用 plugins 的 servers 會自動連接。如果您在 session 期間啟用或停用 plugin，請執行 `/reload-plugins` 以連接或斷開其 MCP servers

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

301 * `stdio` servers：`command`、`args`、`env`301 * `stdio` servers：`command`、`args`、`env`

302 * `http`、`sse` 和 `ws` servers：`url`、`headers` 和 `headersHelper`。{/* min-version: 2.1.195 */}在 v2.1.195 之前，`headersHelper` 將佔位符作為字面字符串傳遞302 * `http`、`sse` 和 `ws` servers：`url`、`headers` 和 `headersHelper`。在 v2.1.195 之前，`headersHelper` 將佔位符作為字面字符串傳遞

303* **使用者環境存取**：存取與手動配置的 servers 相同的環境變數303* **使用者環境存取**：存取與手動配置的 servers 相同的環境變數

304* **多種傳輸類型**：支援 stdio、SSE、HTTP 和 WebSocket 傳輸，傳輸支援可能因 server 而異304* **多種傳輸類型**：支援 stdio、SSE、HTTP 和 WebSocket 傳輸，傳輸支援可能因 server 而異

305 305

320mcp__plugin_my-plugin_database-tools__query320mcp__plugin_my-plugin_database-tools__query

321```321```

322 322

323在 [permission rules](/zh-TW/permissions)、skill 的 `allowed-tools` 列表、[subagent 的 `tools` 欄位](/zh-TW/sub-agents#available-tools) 或 [hook matcher](/zh-TW/hooks#match-mcp-tools) 中參考工具時，請使用此完整名稱。針對裸 server 金鑰（例如 `mcp__database-tools__.*`）編寫的 hook matcher 永遠不會針對 plugin 捆綁的 server 觸發。323在 [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 觸發。

324 324

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

326 326

327**Plugin MCP servers 的優點**：327**Plugin MCP servers 的優點**：

328 328

330* **自動設定**：無需手動 MCP 配置330* **自動設定**：無需手動 MCP 配置

331* **團隊一致性**：安裝 plugin 時，每個人都會獲得相同的工具331* **團隊一致性**：安裝 plugin 時，每個人都會獲得相同的工具

332 332

333請參閱 [plugin 元件參考](/zh-TW/plugins-reference#mcp-servers)，了解有關使用 plugins 捆綁 MCP servers 的詳細資訊。333請參閱 [plugin 元件參考](/docs/zh-TW/plugins-reference#mcp-servers)，了解有關使用 plugins 捆綁 MCP servers 的詳細資訊。

334 334

335<h2 id="mcp-installation-scopes">335<h2 id="mcp-installation-scopes">

336 MCP 安裝範圍336 MCP 安裝範圍

351Local scope 是預設值。本機範圍的 server 僅在您新增它的專案中載入，並對您保持私密。Claude Code 將其儲存在 `~/.claude.json` 中該專案的路徑下，因此相同的 server 不會出現在您的其他專案中。使用本機範圍進行個人開發 servers、實驗配置或包含您不想在版本控制中的認證的 servers。351Local scope 是預設值。本機範圍的 server 僅在您新增它的專案中載入，並對您保持私密。Claude Code 將其儲存在 `~/.claude.json` 中該專案的路徑下，因此相同的 server 不會出現在您的其他專案中。使用本機範圍進行個人開發 servers、實驗配置或包含您不想在版本控制中的認證的 servers。

352 352

353<Note>353<Note>

354 MCP servers 的「local scope」術語與一般本機設定不同。MCP 本機範圍的 servers 儲存在 `~/.claude.json` (您的主目錄) 中，而一般本機設定使用 `.claude/settings.local.json` (在專案目錄中)。請參閱 [Settings](/zh-TW/settings#settings-files) 了解設定檔案位置的詳細資訊。354 MCP servers 的「local scope」術語與一般本機設定不同。MCP 本機範圍的 servers 儲存在 `~/.claude.json` (您的主目錄) 中，而一般本機設定使用 `.claude/settings.local.json` (在專案目錄中)。請參閱 [Settings](/docs/zh-TW/settings#settings-files) 了解設定檔案位置的詳細資訊。

355</Note>355</Note>

356 356

357```bash theme={null}357```bash theme={null}

4261. Local scope4261. Local scope

4272. Project scope4272. Project scope

4283. User scope4283. User scope

4294. [Plugin-provided servers](/zh-TW/plugins)4294. [Plugin-provided servers](/docs/zh-TW/plugins)

4305. [claude.ai connectors](#use-mcp-servers-from-claude-ai)4305. [claude.ai connectors](#use-mcp-servers-from-claude-ai)

431 431

432三個範圍按名稱符合重複項。Plugins 和 connectors 按端點符合，因此指向與上述 server 相同 URL 或命令的端點被視為重複項。432三個範圍按名稱符合重複項。Plugins 和 connectors 按端點符合，因此指向與上述 server 相同 URL 或命令的端點被視為重複項。

805| :---------------------------- | :------------------------------------------------------------------- |805| :---------------------------- | :------------------------------------------------------------------- |

809 809

810使用這些來編寫為多個 MCP servers 服務的單一 helper 指令碼。810使用這些來編寫為多個 MCP servers 服務的單一 helper 指令碼。

811 811

812對於外掛程式提供的 server，helper 也會在其工作目錄設定為外掛程式根目錄的情況下執行，因此相對 `headersHelper` 路徑會在外掛程式目錄內解析，而不是針對 session 的工作目錄。需要 Claude Code v2.1.195 或更新版本。812對於外掛程式提供的 server，helper 也會在其工作目錄設定為外掛程式根目錄的情況下執行，因此相對 `headersHelper` 路徑會在外掛程式目錄內解析，而不是針對 session 的工作目錄。需要 Claude Code v2.1.195 或更新版本。

813 813

814外掛程式提供的 `headersHelper` 無法參考外掛程式的 [`${user_config.*}`](/zh-TW/plugins-reference#user-configuration) 值，因為命令透過 shell 執行。Claude Code 會報告 server 為配置錯誤，並顯示[錯誤](/zh-TW/errors#plugin-command-references-user-config)，且不會替換該值。改為將 `${user_config.KEY}` 放在 server 的 `headers` 欄位中，該欄位不會進行 shell 解析，或讓 helper 指令碼從其自己的環境或配置檔案中讀取該值。在 v2.1.207 之前，`headersHelper` 替換了 `${user_config.*}` 值。814外掛程式提供的 `headersHelper` 無法參考外掛程式的 [`${user_config.*}`](/docs/zh-TW/plugins-reference#user-configuration) 值，因為命令透過 shell 執行。Claude Code 會報告 server 為配置錯誤，並顯示[錯誤](/docs/zh-TW/errors#plugin-command-references-user-config)，且不會替換該值。改為將 `${user_config.KEY}` 放在 server 的 `headers` 欄位中，該欄位不會進行 shell 解析，或讓 helper 指令碼從其自己的環境或配置檔案中讀取該值。在 v2.1.207 之前，`headersHelper` 替換了 `${user_config.*}` 值。

815 815

816<Note>816<Note>

817 `headersHelper` 執行任意 shell 命令。在專案或本機範圍定義時，它僅在您接受工作區信任對話框後執行。817 `headersHelper` 執行任意 shell 命令。在專案或本機範圍定義時，它僅在您接受工作區信任對話框後執行。

920 920

921從 v2.1.161 開始，您從未登入過的 connectors 會在 claude.ai 部分末尾的 `Show unused connectors` 列後面摺疊，因此組織佈建的列表不會填滿面板。選擇該列以展開它們。您之前登入過的 connector 即使目前需要重新驗證，也會保持可見。921從 v2.1.161 開始，您從未登入過的 connectors 會在 claude.ai 部分末尾的 `Show unused connectors` 列後面摺疊，因此組織佈建的列表不會填滿面板。選擇該列以展開它們。您之前登入過的 connector 即使目前需要重新驗證，也會保持可見。

922 922

923Claude.ai connectors 只有在您的活躍[驗證方法](/zh-TW/authentication#authentication-precedence)是您的 claude.ai 訂閱時才會被取得。當 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`apiKeyHelper` 或第三方提供者（例如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）處於活躍狀態時，它們不會被載入，即使您之前執行過 `/login`。如果 `/mcp` 沒有列出您新增的 connector，請執行 `/status` 以確認哪個驗證方法處於活躍狀態，取消設定該環境變數或移除 `apiKeyHelper` 設定，然後執行 `/login` 以選擇您的 claude.ai 帳戶。923Claude.ai connectors 只有在您的活躍[驗證方法](/docs/zh-TW/authentication#authentication-precedence)是您的 claude.ai 訂閱時才會被取得。當 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`apiKeyHelper` 或第三方提供者（例如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）處於活躍狀態時，它們不會被載入，即使您之前執行過 `/login`。如果 `/mcp` 沒有列出您新增的 connector，請執行 `/status` 以確認哪個驗證方法處於活躍狀態，取消設定該環境變數或移除 `apiKeyHelper` 設定，然後執行 `/login` 以選擇您的 claude.ai 帳戶。

924 924

925您在 Claude Code 中新增的 server 優先於指向相同 URL 的 claude.ai connector。發生這種情況時，`/mcp` 會將 connector 列為隱藏，並顯示如何移除重複項（如果您寧願使用 connector）。925您在 Claude Code 中新增的 server 優先於指向相同 URL 的 claude.ai connector。發生這種情況時，`/mcp` 會將 connector 列為隱藏，並顯示如何移除重複項（如果您寧願使用 connector）。

926 926

932 932

933您的組織可以在 [claude.ai connectors](https://claude.com/docs/connectors) 上設定每個工具的控制。Claude Code 在啟動時讀取這些設定並在本機強制執行。執行 `/mcp` 以查看哪個設定適用於 connector 上的每個工具。933您的組織可以在 [claude.ai connectors](https://claude.com/docs/connectors) 上設定每個工具的控制。Claude Code 在啟動時讀取這些設定並在本機強制執行。執行 `/mcp` 以查看哪個設定適用於 connector 上的每個工具。

934 934

935* **工具設定為 `ask`**：Claude Code 會在每次呼叫時提示，原因為 `Your organization requires approval for this tool`。即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [權限模式](/zh-TW/permissions#permission-modes)中，提示也會出現，並且永遠不會提供記住您選擇的選項。符合該工具的[允許規則](/zh-TW/permissions)也不會跳過提示。在 `dontAsk` 模式中（永遠不提示），Claude Code 會改為拒絕呼叫。935* **工具設定為 `ask`**：Claude Code 會在每次呼叫時提示，原因為 `Your organization requires approval for this tool`。即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [權限模式](/docs/zh-TW/permissions#permission-modes)中，提示也會出現，並且永遠不會提供記住您選擇的選項。符合該工具的[允許規則](/docs/zh-TW/permissions)也不會跳過提示。在 `dontAsk` 模式中（永遠不提示），Claude Code 會改為拒絕呼叫。

936* **工具設定為 `blocked`**：Claude Code 在 Claude 看到之前會過濾掉該工具，因此它永遠不會出現在工具列表中。936* **工具設定為 `blocked`**：Claude Code 在 Claude 看到之前會過濾掉該工具，因此它永遠不會出現在工具列表中。

937 937

938強制執行這些控制需要 Claude Code v2.1.129 或更新版本。較早的版本會忽略設定並應用標準權限流程。938強制執行這些控制需要 Claude Code v2.1.129 或更新版本。較早的版本會忽略設定並應用標準權限流程。

941 停用 claude.ai connectors941 停用 claude.ai connectors

942</h3>942</h3>

943 943

944若要在 Claude Code 中停用 claude.ai MCP servers，請將 [`disableClaudeAiConnectors`](/zh-TW/settings#available-settings) 設定為 `true`（在任何設定範圍中）：944若要在 Claude Code 中停用 claude.ai MCP servers，請將 [`disableClaudeAiConnectors`](/docs/zh-TW/settings#available-settings) 設定為 `true`（在任何設定範圍中）：

945 945

946```json theme={null}946```json theme={null}

947{947{

957ENABLE_CLAUDEAI_MCP_SERVERS=false claude957ENABLE_CLAUDEAI_MCP_SERVERS=false claude

958```958```

959 959

960若要阻止個別 claude.ai connectors 而不是全部，請按名稱或 URL 模式將它們新增至 [`deniedMcpServers`](/zh-TW/managed-mcp)。例如，`serverName` 項目 `"claude.ai Slack"` 會阻止 Slack connector。若要僅針對目前專案切換 connector 的開啟或關閉，請使用 `/mcp` 面板。960若要阻止個別 claude.ai connectors 而不是全部，請按名稱或 URL 模式將它們新增至 [`deniedMcpServers`](/docs/zh-TW/managed-mcp)。例如，`serverName` 項目 `"claude.ai Slack"` 會阻止 Slack connector。若要僅針對目前專案切換 connector 的開啟或關閉，請使用 `/mcp` 面板。

961 961

962<Note>962<Note>

963 這些用戶端設定管理本機 Claude Code 工作階段。在 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 工作階段中，claude.ai connectors 由遠端主機佈建，並作為明確的 `--mcp-config` 項目到達，因此 `disableClaudeAiConnectors` 不適用於此處。Connector URL 也會透過工作階段代理重寫，因此針對廠商 URL 的 `deniedMcpServers` `serverUrl` 模式將不會符合。從您的 claude.ai 組織設定管理雲端工作階段可以使用哪些 connectors。963 這些用戶端設定管理本機 Claude Code 工作階段。在 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 工作階段中，claude.ai connectors 由遠端主機佈建，並作為明確的 `--mcp-config` 項目到達，因此 `disableClaudeAiConnectors` 不適用於此處。Connector URL 也會透過工作階段代理重寫，因此針對廠商 URL 的 `deniedMcpServers` `serverUrl` 模式將不會符合。從您的 claude.ai 組織設定管理雲端工作階段可以使用哪些 connectors。

964</Note>964</Note>

965 965

966<h2 id="use-claude-code-as-an-mcp-server">966<h2 id="use-claude-code-as-an-mcp-server">

1093 1093

1094如果您正在建立 MCP server，您可以透過在工具的 `tools/list` 回應項目中將 `_meta["anthropic/requiresUserInteraction"]` 設定為 `true` 來標記工具為在每次呼叫時需要明確批准。該值必須是 JSON 布林值 `true`；任何其他值都會被忽略。1094如果您正在建立 MCP server，您可以透過在工具的 `tools/list` 回應項目中將 `_meta["anthropic/requiresUserInteraction"]` 設定為 `true` 來標記工具為在每次呼叫時需要明確批准。該值必須是 JSON 布林值 `true`；任何其他值都會被忽略。

1095 1095

1096Claude Code 在每次呼叫時顯示該工具的權限提示，即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [permission modes](/zh-TW/permissions#permission-modes) 中，並且不提供「不再詢問」選項。[Allow rules](/zh-TW/permissions#permission-rule-syntax) 符合該工具的也不會跳過提示。在 `dontAsk` 模式中（從不提示），Claude Code 會改為拒絕呼叫。1096Claude Code 在每次呼叫時顯示該工具的權限提示，即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [permission modes](/docs/zh-TW/permissions#permission-modes) 中，並且不提供「不再詢問」選項。[Allow rules](/docs/zh-TW/permissions#permission-rule-syntax) 符合該工具的也不會跳過提示。在 `dontAsk` 模式中（從不提示），Claude Code 會改為拒絕呼叫。

1097 1097

1098提示必須到達一個人。在非互動模式下使用 [`--permission-prompt-tool`](/zh-TW/cli-reference#cli-flags)，來自提示工具的 `allow` 結果對於標記的工具會轉換為拒絕，訊息為 `MCP tool requires user interaction; not supported via --permission-prompt-tool`。Agent SDK 的 [`canUseTool` 回呼](/zh-TW/agent-sdk/permissions) 確實會接收這些呼叫並可以批准它們，因為 SDK 主機應該向使用者顯示它們。1098提示必須到達一個人。在非互動模式下使用 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags)，來自提示工具的 `allow` 結果對於標記的工具會轉換為拒絕，訊息為 `MCP tool requires user interaction; not supported via --permission-prompt-tool`。Agent SDK 的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/permissions) 確實會接收這些呼叫並可以批准它們，因為 SDK 主機應該向使用者顯示它們。

1099 1099

1100將此用於其權限提示本身就是重點的工具，例如同意或存取授予步驟，其中自動批准意味著沒有人類曾經同意。來自同一 server 的其他工具保持其正常權限行為。1100將此用於其權限提示本身就是重點的工具，例如同意或存取授予步驟，其中自動批准意味著沒有人類曾經同意。來自同一 server 的其他工具保持其正常權限行為。

1101 1101

1113 1113

1114`anthropic/requiresUserInteraction` 註解需要 Claude Code v2.1.199 或更新版本。較早的版本會忽略它並應用標準權限流程。1114`anthropic/requiresUserInteraction` 註解需要 Claude Code v2.1.199 或更新版本。較早的版本會忽略它並應用標準權限流程。

1115 1115

1116當 session 連接到 [Remote Control](/zh-TW/remote-control) 或 SDK 主機時，Claude Code 會將權限請求標記為需要使用者互動，因此用戶端會向您顯示工具的權限提示，而不是單點擊批准操作。1116當 session 連接到 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機時，Claude Code 會將權限請求標記為需要使用者互動，因此用戶端會向您顯示工具的權限提示，而不是單點擊批准操作。

1117 1117

1118<h2 id="respond-to-mcp-elicitation-requests">1118<h2 id="respond-to-mcp-elicitation-requests">

1119 回應 MCP 引發請求1119 回應 MCP 引發請求

1126* **表單模式**：Claude Code 顯示一個對話框，其中包含 server 定義的表單欄位 (例如，使用者名稱和密碼提示)。填入欄位並提交。1126* **表單模式**：Claude Code 顯示一個對話框，其中包含 server 定義的表單欄位 (例如，使用者名稱和密碼提示)。填入欄位並提交。

1127* **URL 模式**：Claude Code 開啟瀏覽器 URL 以進行驗證或批准。在瀏覽器中完成流程，然後在 CLI 中確認。1127* **URL 模式**：Claude Code 開啟瀏覽器 URL 以進行驗證或批准。在瀏覽器中完成流程，然後在 CLI 中確認。

1128 1128

1129若要自動回應引發請求而不顯示對話框，請使用 [`Elicitation` hook](/zh-TW/hooks#elicitation)。1129若要自動回應引發請求而不顯示對話框，請使用 [`Elicitation` hook](/docs/zh-TW/hooks#elicitation)。

1130 1130

1131如果您正在建立使用引發的 MCP server，請參閱 [MCP 引發規格](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation)，了解協議詳細資訊和架構範例。1131如果您正在建立使用引發的 MCP server，請參閱 [MCP 引發規格](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation)，了解協議詳細資訊和架構範例。

1132 1132

1193 對於 MCP server 作者1193 對於 MCP server 作者

1194</h3>1194</h3>

1195 1195

1196如果您正在建立 MCP server，啟用 Tool Search 時 server 指示欄位會變得更有用。Server 指示可幫助 Claude 了解何時搜尋您的工具，類似於 [skills](/zh-TW/skills) 的工作方式。1196如果您正在建立 MCP server，啟用 Tool Search 時 server 指示欄位會變得更有用。Server 指示可幫助 Claude 了解何時搜尋您的工具，類似於 [skills](/docs/zh-TW/skills) 的工作方式。

1197 1197

1198新增清晰、描述性的 server 指示，說明：1198新增清晰、描述性的 server 指示，說明：

1199 1199

1209 1209

1210Tool search 預設啟用：MCP 工具被延遲並按需探索。Claude Code 在 Google Cloud 的 Agent Platform 上預設停用它。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，它也被停用，因為大多數代理不轉發 `tool_reference` 區塊。設定 `ENABLE_TOOL_SEARCH` 明確以覆蓋任一回退。1210Tool search 預設啟用：MCP 工具被延遲並按需探索。Claude Code 在 Google Cloud 的 Agent Platform 上預設停用它。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，它也被停用，因為大多數代理不轉發 `tool_reference` 區塊。設定 `ENABLE_TOOL_SEARCH` 明確以覆蓋任一回退。

1211 1211

1212設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/zh-TW/env-vars) 保持 tool search 關閉，且 `ENABLE_TOOL_SEARCH` 無法覆蓋它。該變數會移除 `defer_loading` 工具定義和 `tool_reference` 內容區塊所需的 beta 標頭。1212設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/env-vars) 保持 tool search 關閉，且 `ENABLE_TOOL_SEARCH` 無法覆蓋它。該變數會移除 `defer_loading` 工具定義和 `tool_reference` 內容區塊所需的 beta 標頭。

1213 1213

1214Tool search 需要支援 `tool_reference` 區塊的模型：Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 及更新版本。請參閱 [API 文件中的模型相容性](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#model-compatibility) 以取得目前清單。在 Google Cloud 的 Agent Platform 上，tool search 支援 Claude Sonnet 4.5 及更新版本和 Claude Opus 4.5 及更新版本。1214Tool search 需要支援 `tool_reference` 區塊的模型：Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 及更新版本。請參閱 [API 文件中的模型相容性](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#model-compatibility) 以取得目前清單。在 Google Cloud 的 Agent Platform 上，tool search 支援 Claude Sonnet 4.5 及更新版本和 Claude Opus 4.5 及更新版本。

1215 1215

1231ENABLE_TOOL_SEARCH=false claude1231ENABLE_TOOL_SEARCH=false claude

1232```1232```

1233 1233

1234或在您的 [settings.json `env` 欄位](/zh-TW/settings#available-settings) 中設定值。1234或在您的 [settings.json `env` 欄位](/docs/zh-TW/settings#available-settings) 中設定值。

1235 1235

1236您也可以特別停用 `ToolSearch` 工具：1236您也可以特別停用 `ToolSearch` 工具：

1237 1237

1265 1265

1266`alwaysLoad` 欄位在所有伺服器類型上可用，需要 Claude Code v2.1.121 或更新版本。MCP 伺服器也可以透過在工具的 `_meta` 物件中包含 `"anthropic/alwaysLoad": true` 來標記個別工具為始終載入，這對該工具只有相同的效果。1266`alwaysLoad` 欄位在所有伺服器類型上可用，需要 Claude Code v2.1.121 或更新版本。MCP 伺服器也可以透過在工具的 `_meta` 物件中包含 `"anthropic/alwaysLoad": true` 來標記個別工具為始終載入，這對該工具只有相同的效果。

1267 1267

1268設定 `alwaysLoad: true` 也會阻止啟動直到伺服器連線，上限為標準 5 秒連線逾時。即使 MCP 啟動在其他方面[預設為非阻塞](/zh-TW/env-vars)，這也適用，因為工具必須在建立第一個提示時存在。其他伺服器繼續在背景中連線。1268設定 `alwaysLoad: true` 也會阻止啟動直到伺服器連線，上限為標準 5 秒連線逾時。即使 MCP 啟動在其他方面[預設為非阻塞](/docs/zh-TW/env-vars)，這也適用，因為工具必須在建立第一個提示時存在。其他伺服器繼續在背景中連線。

1269 1269

1270<h2 id="use-mcp-prompts-as-commands">1270<h2 id="use-mcp-prompts-as-commands">

1271 使用 MCP 提示作為命令1271 使用 MCP 提示作為命令

1314 受管理的 MCP 配置1314 受管理的 MCP 配置

1315</h2>1315</h2>

1316 1316

1317對於需要對使用者可以連接的 MCP servers 進行集中控制的組織，請參閱 [受管理的 MCP 配置](/zh-TW/managed-mcp)。它涵蓋使用 `managed-mcp.json` 部署固定的 server 集合、使用 `allowedMcpServers` 和 `deniedMcpServers` 限制 servers，以及當 server 被阻止時使用者看到的內容。1317對於需要對使用者可以連接的 MCP servers 進行集中控制的組織，請參閱 [受管理的 MCP 配置](/docs/zh-TW/managed-mcp)。它涵蓋使用 `managed-mcp.json` 部署固定的 server 集合、使用 `allowedMcpServers` 和 `deniedMcpServers` 限制 servers，以及當 server 被阻止時使用者看到的內容。

memory.md +23 −23

Details

22 CLAUDE.md 與自動記憶22 CLAUDE.md 與自動記憶

23</h2>23</h2>

24 24

25Claude Code 有兩個互補的記憶系統。兩者都在每次對話開始時載入。Claude 將它們視為上下文，而不是強制配置。若要阻止某個動作（無論 Claude 決定什麼），請改用 [PreToolUse hook](/zh-TW/hooks-guide)。您的指令越具體和簡潔，Claude 遵循它們的一致性就越高。25Claude Code 有兩個互補的記憶系統。兩者都在每次對話開始時載入。Claude 將它們視為上下文，而不是強制配置。若要阻止某個動作（無論 Claude 決定什麼），請改用 [PreToolUse hook](/docs/zh-TW/hooks-guide)。您的指令越具體和簡潔，Claude 遵循它們的一致性就越高。

26 26

27| | CLAUDE.md 檔案 | 自動記憶 |27| | CLAUDE.md 檔案 | 自動記憶 |

28| :------- | :------------- | :--------------------- |28| :------- | :------------- | :--------------------- |

34 34

35當您想引導 Claude 的行為時，使用 CLAUDE.md 檔案。自動記憶讓 Claude 從您的更正中學習，無需手動操作。35當您想引導 Claude 的行為時，使用 CLAUDE.md 檔案。自動記憶讓 Claude 從您的更正中學習，無需手動操作。

36 36

~~37Subagents 也可以維護自己的自動記憶。有關詳細資訊，請參閱 [subagent 配置](/zh-TW/sub-agents#enable-persistent-memory)。~~37Subagents 也可以維護自己的自動記憶。有關詳細資訊，請參閱 [subagent 配置](/docs/zh-TW/sub-agents#enable-persistent-memory)。

38 38

39<h2 id="claude-md-files">39<h2 id="claude-md-files">

40 CLAUDE.md 檔案40 CLAUDE.md 檔案

53* 您在聊天中輸入的相同更正或澄清是您上個工作階段輸入的53* 您在聊天中輸入的相同更正或澄清是您上個工作階段輸入的

54* 新的團隊成員需要相同的上下文才能提高生產力54* 新的團隊成員需要相同的上下文才能提高生產力

55 55

56將其保持為 Claude 應該在每個工作階段中保留的事實：建置命令、慣例、專案佈局、「始終執行 X」規則。如果一個條目是多步驟程序或僅對程式碼庫的一部分重要，請將其移到 [skill](/zh-TW/skills) 或 [路徑範圍規則](#organize-rules-with-claude/rules/) 代替。[擴展概述](/zh-TW/features-overview#build-your-setup-over-time)涵蓋何時使用每個機制。56將其保持為 Claude 應該在每個工作階段中保留的事實：建置命令、慣例、專案佈局、「始終執行 X」規則。如果一個條目是多步驟程序或僅對程式碼庫的一部分重要，請將其移到 [skill](/docs/zh-TW/skills) 或 [路徑範圍規則](#organize-rules-with-claude/rules/) 代替。[擴展概述](/docs/zh-TW/features-overview#build-your-setup-over-time)涵蓋何時使用每個機制。

57 57

58<h3 id="choose-where-to-put-claude-md-files">58<h3 id="choose-where-to-put-claude-md-files">

59 選擇 CLAUDE.md 檔案的位置59 選擇 CLAUDE.md 檔案的位置

88 編寫有效的指令88 編寫有效的指令

89</h3>89</h3>

90 90

91CLAUDE.md 檔案在每個工作階段開始時載入到 context window 中，與您的對話一起消耗令牌。[context window 視覺化](/zh-TW/context-window)顯示 CLAUDE.md 相對於其餘啟動上下文的載入位置。因為它們是上下文而不是強制配置，您編寫指令的方式會影響 Claude 遵循它們的可靠性。具體、簡潔、結構良好的指令效果最好。91CLAUDE.md 檔案在每個工作階段開始時載入到 context window 中，與您的對話一起消耗令牌。[context window 視覺化](/docs/zh-TW/context-window)顯示 CLAUDE.md 相對於其餘啟動上下文的載入位置。因為它們是上下文而不是強制配置，您編寫指令的方式會影響 Claude 遵循它們的可靠性。具體、簡潔、結構良好的指令效果最好。

92 92

93**大小**：目標是每個 CLAUDE.md 檔案少於 200 行。較長的檔案消耗更多上下文並降低遵守度。如果您的指令變得很大，請使用 [路徑範圍規則](#path-specific-rules) 以便指令只在 Claude 處理匹配檔案時載入。您也可以將內容分割成 [匯入](#import-additional-files) 以進行組織，儘管匯入的檔案仍然會載入並在啟動時進入 context window。93**大小**：目標是每個 CLAUDE.md 檔案少於 200 行。較長的檔案消耗更多上下文並降低遵守度。如果您的指令變得很大，請使用 [路徑範圍規則](#path-specific-rules) 以便指令只在 Claude 處理匹配檔案時載入。您也可以將內容分割成 [匯入](#import-additional-files) 以進行組織，儘管匯入的檔案仍然會載入並在啟動時進入 context window。

94 94

158 158

159在 Windows 上，建立符號連結需要系統管理員權限或開發人員模式，因此請改用 `@AGENTS.md` 匯入。159在 Windows 上，建立符號連結需要系統管理員權限或開發人員模式，因此請改用 `@AGENTS.md` 匯入。

160 160

161在已經有 `AGENTS.md` 的儲存庫中執行 [`/init`](/zh-TW/commands) 會讀取它並將相關部分合併到產生的 `CLAUDE.md` 中。它也會讀取其他工具配置，如 `.cursorrules`、`.devin/rules/` 和 `.windsurfrules`。161在已經有 `AGENTS.md` 的儲存庫中執行 [`/init`](/docs/zh-TW/commands) 會讀取它並將相關部分合併到產生的 `CLAUDE.md` 中。它也會讀取其他工具配置，如 `.cursorrules`、`.devin/rules/` 和 `.windsurfrules`。

162 162

163<h3 id="how-claude-md-files-load">163<h3 id="how-claude-md-files-load">

164 CLAUDE.md 檔案如何載入164 CLAUDE.md 檔案如何載入

170 170

171Claude 也會在您目前工作目錄下的子目錄中發現 `CLAUDE.md` 和 `CLAUDE.local.md` 檔案。它們不是在啟動時載入，而是在 Claude 讀取這些子目錄中的檔案時包含。171Claude 也會在您目前工作目錄下的子目錄中發現 `CLAUDE.md` 和 `CLAUDE.local.md` 檔案。它們不是在啟動時載入，而是在 Claude 讀取這些子目錄中的檔案時包含。

172 172

173如果您在大型 monorepo 中工作，其中其他團隊的 CLAUDE.md 檔案被拾取，請使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳過它們。對於根目錄和每個目錄 CLAUDE.md 檔案和規則的完整佈局，請參閱 [Monorepos 和大型儲存庫](/zh-TW/large-codebases)。173如果您在大型 monorepo 中工作，其中其他團隊的 CLAUDE.md 檔案被拾取，請使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳過它們。對於根目錄和每個目錄 CLAUDE.md 檔案和規則的完整佈局，請參閱 [Monorepos 和大型儲存庫](/docs/zh-TW/large-codebases)。

174 174

175CLAUDE.md 檔案中的區塊級 HTML 註解（``）在內容被注入到 Claude 的上下文之前會被移除。使用它們為人類維護者留下筆記，而不會在令牌上花費上下文。程式碼區塊內的註解會被保留。當您直接使用 Read 工具開啟 CLAUDE.md 檔案時，註解保持可見。175CLAUDE.md 檔案中的區塊級 HTML 註解（``）在內容被注入到 Claude 的上下文之前會被移除。使用它們為人類維護者留下筆記，而不會在令牌上花費上下文。程式碼區塊內的註解會被保留。當您直接使用 Read 工具開啟 CLAUDE.md 檔案時，註解保持可見。

176 176

186CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config186CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

187```187```

188 188

189這會從其他目錄載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。如果您從 [`--setting-sources`](/zh-TW/cli-reference) 排除 `local`，則會跳過 `CLAUDE.local.md`。189這會從其他目錄載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。如果您從 [`--setting-sources`](/docs/zh-TW/cli-reference) 排除 `local`，則會跳過 `CLAUDE.local.md`。

190 190

191<h3 id="organize-rules-with-claude/rules/">191<h3 id="organize-rules-with-claude/rules/">

192 使用 `.claude/rules/` 組織規則192 使用 `.claude/rules/` 組織規則

195對於較大的專案，您可以使用 `.claude/rules/` 目錄將指令組織成多個檔案。這使指令保持模組化，更容易讓團隊維護。規則也可以 [範圍限定於特定檔案路徑](#path-specific-rules)，因此它們只在 Claude 處理匹配檔案時載入到上下文中，減少雜訊並節省上下文空間。195對於較大的專案，您可以使用 `.claude/rules/` 目錄將指令組織成多個檔案。這使指令保持模組化，更容易讓團隊維護。規則也可以 [範圍限定於特定檔案路徑](#path-specific-rules)，因此它們只在 Claude 處理匹配檔案時載入到上下文中，減少雜訊並節省上下文空間。

196 196

197<Note>197<Note>

198 規則在每個工作階段或開啟匹配檔案時載入到上下文中。對於不需要始終在上下文中的任務特定指令，請改用 [skills](/zh-TW/skills)，它們只在您呼叫它們或 Claude 確定它們與您的提示相關時載入。198 規則在每個工作階段或開啟匹配檔案時載入到上下文中。對於不需要始終在上下文中的任務特定指令，請改用 [skills](/docs/zh-TW/skills)，它們只在您呼叫它們或 Claude 確定它們與您的提示相關時載入。

199</Note>199</Note>

200 200

201<h4 id="set-up-rules">201<h4 id="set-up-rules">

235- 包括 OpenAPI 文件註解235- 包括 OpenAPI 文件註解

236```236```

237 237

238沒有 `paths` 欄位的規則無條件載入並適用於所有檔案。路徑範圍規則在 Claude 讀取與模式匹配的檔案時觸發，而不是在每次工具使用時觸發。{/* min-version: 2.1.198 */}截至 v2.1.198，匹配也適用於 Claude 透過專案目錄的符號連結路徑到達檔案時，例如在符號連結簽出中。238沒有 `paths` 欄位的規則無條件載入並適用於所有檔案。路徑範圍規則在 Claude 讀取與模式匹配的檔案時觸發，而不是在每次工具使用時觸發。截至 v2.1.198，匹配也適用於 Claude 透過專案目錄的符號連結路徑到達檔案時，例如在符號連結簽出中。

239 239

240在 `paths` 欄位中使用 glob 模式，按副檔名、目錄或任何組合匹配檔案：240在 `paths` 欄位中使用 glob 模式，按副檔名、目錄或任何組合匹配檔案：

241 241

257---257---

258```258```

259 259

260Glob 語法將 `[` 視為括號表達式的開始，例如 `[abc]`。無法讀取為括號表達式的帶有 `[` 的模式，例如 `photos [2024/**`，是無效的：它不匹配任何內容，規則的其他模式繼續工作。要匹配檔案名稱中的字面 `[`，請將其轉義為 `photos \[2024/**`。{/* min-version: 2.1.207 */}在 v2.1.207 之前，一個無效的模式會導致 Read 工具對規則被評估的每個檔案失敗，而不是不匹配任何內容。260Glob 語法將 `[` 視為括號表達式的開始，例如 `[abc]`。無法讀取為括號表達式的帶有 `[` 的模式，例如 `photos [2024/**`，是無效的：它不匹配任何內容，規則的其他模式繼續工作。要匹配檔案名稱中的字面 `[`，請將其轉義為 `photos \[2024/**`。在 v2.1.207 之前，一個無效的模式會導致 Read 工具對規則被評估的每個檔案失敗，而不是不匹配任何內容。

261 261

262<h4 id="share-rules-across-projects-with-symlinks">262<h4 id="share-rules-across-projects-with-symlinks">

263 使用符號連結跨專案共享規則263 使用符號連結跨專案共享規則

306 </Step>306 </Step>

307 307

308 <Step title="使用您的配置管理系統進行部署">308 <Step title="使用您的配置管理系統進行部署">

309 使用 MDM、群組原則、Ansible 或類似工具在開發人員機器上分發檔案。有關其他組織範圍配置選項，請參閱 [受管理的設定](/zh-TW/permissions#managed-settings)。309 使用 MDM、群組原則、Ansible 或類似工具在開發人員機器上分發檔案。有關其他組織範圍配置選項，請參閱 [受管理的設定](/docs/zh-TW/permissions#managed-settings)。

310 </Step>310 </Step>

311</Steps>311</Steps>

312 312

326}326}

327```327```

328 328

329受管理的 CLAUDE.md 和 [受管理的設定](/zh-TW/settings#settings-files) 有不同的用途。使用設定進行技術強制執行，使用 CLAUDE.md 進行行為指導：329受管理的 CLAUDE.md 和 [受管理的設定](/docs/zh-TW/settings#settings-files) 有不同的用途。使用設定進行技術強制執行，使用 CLAUDE.md 進行行為指導：

330 330

331| 關注 | 配置在 |331| 關注 | 配置在 |

332| :-------------- | :-------------------------------------------- |332| :-------------- | :-------------------------------------------- |

357}357}

358```358```

359 359

360模式使用 glob 語法與絕對檔案路徑匹配。您可以在任何 [設定層](/zh-TW/settings#settings-files)：使用者、專案、本地或受管理的原則配置 `claudeMdExcludes`。陣列跨層合併。360模式使用 glob 語法與絕對檔案路徑匹配。您可以在任何 [設定層](/docs/zh-TW/settings#settings-files)：使用者、專案、本地或受管理的原則配置 `claudeMdExcludes`。陣列跨層合併。

361 361

362受管理的原則 CLAUDE.md 檔案無法被排除。這確保組織範圍的指令始終適用，無論個人設定如何。362受管理的原則 CLAUDE.md 檔案無法被排除。這確保組織範圍的指令始終適用，無論個人設定如何。

363 363

387 387

388每個專案在 `~/.claude/projects/<project>/memory/` 獲得自己的記憶目錄。`<project>` 路徑源自 git 儲存庫，因此同一儲存庫內的所有 worktrees 和子目錄共享一個自動記憶目錄。在 git 儲存庫外，改用專案根目錄。388每個專案在 `~/.claude/projects/<project>/memory/` 獲得自己的記憶目錄。`<project>` 路徑源自 git 儲存庫，因此同一儲存庫內的所有 worktrees 和子目錄共享一個自動記憶目錄。在 git 儲存庫外，改用專案根目錄。

389 389

390要將自動記憶儲存在不同位置，請在您的 `settings.json` 中設定 `autoMemoryDirectory`。它從任何[設定範圍](/zh-TW/settings#settings-precedence)讀取：使用者、專案、本地、原則或 `--settings`。390要將自動記憶儲存在不同位置，請在您的 `settings.json` 中設定 `autoMemoryDirectory`。它從任何[設定範圍](/docs/zh-TW/settings#settings-precedence)讀取：使用者、專案、本地、原則或 `--settings`。

391 391

392```json theme={null}392```json theme={null}

393{393{

456* 使指令更具體。「使用 2 空格縮排」比「正確格式化程式碼」效果更好。456* 使指令更具體。「使用 2 空格縮排」比「正確格式化程式碼」效果更好。

457* 查找跨 CLAUDE.md 檔案的衝突指令。如果兩個檔案為相同行為提供不同的指導，Claude 可能會任意選擇一個。457* 查找跨 CLAUDE.md 檔案的衝突指令。如果兩個檔案為相同行為提供不同的指導，Claude 可能會任意選擇一個。

458 458

459如果指令是必須在特定時間點執行的內容，例如在每次提交前或每次檔案編輯後，請改為將其寫成 [hook](/zh-TW/hooks-guide)。Hooks 在固定的生命週期事件中作為 shell 命令執行，並且無論 Claude 決定做什麼都適用。459如果指令是必須在特定時間點執行的內容，例如在每次提交前或每次檔案編輯後，請改為將其寫成 [hook](/docs/zh-TW/hooks-guide)。Hooks 在固定的生命週期事件中作為 shell 命令執行，並且無論 Claude 決定做什麼都適用。

460 460

461對於您想要在系統提示級別的指令，請使用 [`--append-system-prompt`](/zh-TW/cli-reference#system-prompt-flags)。這必須在每次呼叫時傳遞，因此它更適合指令碼和自動化，而不是互動式使用。461對於您想要在系統提示級別的指令，請使用 [`--append-system-prompt`](/docs/zh-TW/cli-reference#system-prompt-flags)。這必須在每次呼叫時傳遞，因此它更適合指令碼和自動化，而不是互動式使用。

462 462

463<Tip>463<Tip>

464 使用 [`InstructionsLoaded` hook](/zh-TW/hooks#instructionsloaded) 記錄確切載入的指令檔案、何時載入以及為什麼。這對於除錯路徑特定規則或子目錄中的延遲載入檔案很有用。464 使用 [`InstructionsLoaded` hook](/docs/zh-TW/hooks#instructionsloaded) 記錄確切載入的指令檔案、何時載入以及為什麼。這對於除錯路徑特定規則或子目錄中的延遲載入檔案很有用。

465</Tip>465</Tip>

466 466

467<h3 id="i-don’t-know-what-auto-memory-saved">467<h3 id="i-don’t-know-what-auto-memory-saved">

476 476

477超過 200 行的檔案消耗更多上下文，可能會降低遵守度。使用 [路徑範圍規則](#path-specific-rules) 僅在 Claude 處理符合的檔案時載入指令，或修剪不是每個工作階段都需要的內容。分割成 [`@path` 匯入](#import-additional-files) 有助於組織，但不會減少上下文，因為匯入的檔案在啟動時載入。477超過 200 行的檔案消耗更多上下文，可能會降低遵守度。使用 [路徑範圍規則](#path-specific-rules) 僅在 Claude 處理符合的檔案時載入指令，或修剪不是每個工作階段都需要的內容。分割成 [`@path` 匯入](#import-additional-files) 有助於組織，但不會減少上下文，因為匯入的檔案在啟動時載入。

478 478

479[`/doctor`](/zh-TW/commands#all-commands) 檢查會為已簽入的 CLAUDE.md 提出修剪建議：它會刪除 Claude 可以從程式碼庫衍生的內容，例如目錄配置、相依性清單和架構概述，並保留與工具預設值不同的陷阱、基本原理和慣例。修剪檢查需要 Claude Code v2.1.206 或更新版本。479[`/doctor`](/docs/zh-TW/commands#all-commands) 檢查會為已簽入的 CLAUDE.md 提出修剪建議：它會刪除 Claude 可以從程式碼庫衍生的內容，例如目錄配置、相依性清單和架構概述，並保留與工具預設值不同的陷阱、基本原理和慣例。修剪檢查需要 Claude Code v2.1.206 或更新版本。

480 480

481<h3 id="instructions-seem-lost-after-/compact">481<h3 id="instructions-seem-lost-after-/compact">

482 指令在 `/compact` 後似乎丟失了482 指令在 `/compact` 後似乎丟失了

484 484

485專案根目錄 CLAUDE.md 在壓縮中倖存：在 `/compact` 之後，Claude 從磁碟重新讀取它並將其重新注入到工作階段中。子目錄中的巢狀 CLAUDE.md 檔案不會自動重新注入；它們在 Claude 下次讀取該子目錄中的檔案時重新載入。485專案根目錄 CLAUDE.md 在壓縮中倖存：在 `/compact` 之後，Claude 從磁碟重新讀取它並將其重新注入到工作階段中。子目錄中的巢狀 CLAUDE.md 檔案不會自動重新注入；它們在 Claude 下次讀取該子目錄中的檔案時重新載入。

486 486

487如果指令在壓縮後消失，它要麼只在對話中給出，要麼位於尚未重新載入的巢狀 CLAUDE.md 中。將對話專用指令新增到 CLAUDE.md 以使其持久化。有關完整的細目，請參閱 [壓縮後倖存的內容](/zh-TW/context-window#what-survives-compaction)。487如果指令在壓縮後消失，它要麼只在對話中給出，要麼位於尚未重新載入的巢狀 CLAUDE.md 中。將對話專用指令新增到 CLAUDE.md 以使其持久化。有關完整的細目，請參閱 [壓縮後倖存的內容](/docs/zh-TW/context-window#what-survives-compaction)。

488 488

489請參閱 [編寫有效的指令](#write-effective-instructions) 以取得有關大小、結構和具體性的指導。489請參閱 [編寫有效的指令](#write-effective-instructions) 以取得有關大小、結構和具體性的指導。

490 490

492 相關資源492 相關資源

493</h2>493</h2>

494 494

495* [除錯您的配置](/zh-TW/debug-your-config)：診斷為什麼 CLAUDE.md 或設定未生效495* [除錯您的配置](/docs/zh-TW/debug-your-config)：診斷為什麼 CLAUDE.md 或設定未生效

496* [Skills](/zh-TW/skills)：封裝按需載入的可重複工作流程496* [Skills](/docs/zh-TW/skills)：封裝按需載入的可重複工作流程

497* [設定](/zh-TW/settings)：使用設定檔案配置 Claude Code 行為497* [設定](/docs/zh-TW/settings)：使用設定檔案配置 Claude Code 行為

498* [Subagent 記憶](/zh-TW/sub-agents#enable-persistent-memory)：讓 subagents 維護自己的自動記憶498* [Subagent 記憶](/docs/zh-TW/sub-agents#enable-persistent-memory)：讓 subagents 維護自己的自動記憶

microsoft-foundry.md +3 −3

Details

139 139

140**選項 C：Bearer 權杖驗證**140**選項 C：Bearer 權杖驗證**

141 141

142{/* min-version: 2.1.203 */}Claude Code 在每個請求上將 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 的值作為 `Authorization: Bearer` 標頭傳送。當另一個程序（例如主應用程式或登入指令碼）已為您取得存取權杖時，請使用此選項。需要 Claude Code v2.1.203 或更新版本。142Claude Code 在每個請求上將 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 的值作為 `Authorization: Bearer` 標頭傳送。當另一個程序（例如主應用程式或登入指令碼）已為您取得存取權杖時，請使用此選項。需要 Claude Code v2.1.203 或更新版本。

143 143

144將變數設定為 Microsoft Entra ID 為您的資源簽發的 Bearer 權杖：144將變數設定為 Microsoft Entra ID 為您的資源簽發的 Bearer 權杖：

145 145

189 189

190背景工作（例如工作階段標題生成）使用小型/快速模型，通常是 Haiku 級別的模型。在 Microsoft Foundry 上，Claude Code 預設使用主要模型，因為並非每個帳戶都有 Haiku 部署。若要為背景工作使用 Haiku，請將 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 設定為您帳戶中可用的 Haiku 部署，如上所示。190背景工作（例如工作階段標題生成）使用小型/快速模型，通常是 Haiku 級別的模型。在 Microsoft Foundry 上，Claude Code 預設使用主要模型，因為並非每個帳戶都有 Haiku 部署。若要為背景工作使用 Haiku，請將 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 設定為您帳戶中可用的 Haiku 部署，如上所示。

191 191

192如需目前和舊版模型 ID，請參閱[模型概覽](https://platform.claude.com/docs/en/about-claude/models/overview)。如需完整的環境變數清單，請參閱[模型配置](/zh-TW/model-config#pin-models-for-third-party-deployments)。192如需目前和舊版模型 ID，請參閱[模型概覽](https://platform.claude.com/docs/en/about-claude/models/overview)。如需完整的環境變數清單，請參閱[模型配置](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)。

193 193

194[Prompt caching](/zh-TW/prompt-caching) 會自動啟用。若要要求 1 小時的快取 TTL 而不是 5 分鐘的預設值，請設定下列變數；具有 1 小時 TTL 的快取寫入會以更高的費率計費：194[Prompt caching](/docs/zh-TW/prompt-caching) 會自動啟用。若要要求 1 小時的快取 TTL 而不是 5 分鐘的預設值，請設定下列變數；具有 1 小時 TTL 的快取寫入會以更高的費率計費：

195 195

196```bash theme={null}196```bash theme={null}

197export ENABLE_PROMPT_CACHING_1H=1197export ENABLE_PROMPT_CACHING_1H=1

model-config.md +73 −77

Details

22如需有關哪個模型和努力程度適合不同類型工作的指導，請參閱部落格上的 [Choosing a Claude model and effort level in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code)。22如需有關哪個模型和努力程度適合不同類型工作的指導，請參閱部落格上的 [Choosing a Claude model and effort level in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code)。

23 23

24<Note>24<Note>

~~25 `ANTHROPIC_BASE_URL` 改變請求的發送位置，而不是哪個模型回答它們。若要透過 LLM 閘道路由 Claude，請參閱 [LLM 閘道](/zh-TW/llm-gateway)。~~25 `ANTHROPIC_BASE_URL` 改變請求的發送位置，而不是哪個模型回答它們。若要透過 LLM 閘道路由 Claude，請參閱 [LLM 閘道](/docs/zh-TW/llm-gateway)。

26</Note>26</Note>

27 27

28<h3 id="model-aliases">28<h3 id="model-aliases">

42| **`sonnet[1m]`** | 使用 Sonnet 搭配[100 萬個 token 的 context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#context-window-sizes-by-model)進行長時間會話。當 `sonnet` 已解析為具有原生 1M window 的 Sonnet 5 時無效；在 [LLM 閘道](/zh-TW/llm-gateway)後方時，會為 Sonnet 5 選擇 1M window |42| **`sonnet[1m]`** | 使用 Sonnet 搭配[100 萬個 token 的 context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#context-window-sizes-by-model)進行長時間會話。當 `sonnet` 已解析為具有原生 1M window 的 Sonnet 5 時無效；在 [LLM 閘道](/docs/zh-TW/llm-gateway)後方時，會為 Sonnet 5 選擇 1M window |

43| **`opus[1m]`** | 使用 Opus 搭配[100 萬個 token 的 context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#context-window-sizes-by-model)進行長時間會話 |43| **`opus[1m]`** | 使用 Opus 搭配[100 萬個 token 的 context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#context-window-sizes-by-model)進行長時間會話 |

45 45

48| 提供者 | `opus` | `sonnet` |48| 提供者 | `opus` | `sonnet` |

49| :------------------------------------------------------ | :------- | :--------- |49| :------------------------------------------------------ | :------- | :--------- |

54 54

55當別名解析為較舊的模型時，透過明確選擇完整模型名稱或設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL`，可以使用較新的模型。55當別名解析為較舊的模型時，透過明確選擇完整模型名稱或設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL`，可以使用較新的模型。

56 56

~~57{/* min-version: 2.1.207 */}在 v2.1.207 之前，`opus` 在 AWS 上的 Claude Platform 上解析為 Opus 4.7，在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析為 Opus 4.6。~~57在 v2.1.207 之前，`opus` 在 AWS 上的 Claude Platform 上解析為 Opus 4.7，在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析為 Opus 4.6。

58 58

59別名指向您提供者的推薦版本，並隨著時間推移而更新。若要固定到特定版本，請使用完整模型名稱（例如 `claude-opus-4-8`），或設定相應的環境變數，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。59別名指向您提供者的推薦版本，並隨著時間推移而更新。若要固定到特定版本，請使用完整模型名稱（例如 `claude-opus-4-8`），或設定相應的環境變數，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。

60 60

72 72

73若要充分利用 Fable 5：73若要充分利用 Fable 5：

74 74

~~75* **描述結果，而不是步驟**：給它您想要的結果，讓它規劃路徑。若要讓它持續工作直到該結果成立，[設定目標](/zh-TW/goal)。~~75* **描述結果，而不是步驟**：給它您想要的結果，讓它規劃路徑。若要讓它持續工作直到該結果成立，[設定目標](/docs/zh-TW/goal)。

76* **交給它模糊的問題**：根本原因調查、中斷除錯和架構決策是額外調查和驗證發揮作用的地方。76* **交給它模糊的問題**：根本原因調查、中斷除錯和架構決策是額外調查和驗證發揮作用的地方。

77* **跳過驗證提醒**：它以較少的提示驗證自己的工作，所以測試或檢查的提醒通常是不必要的。77* **跳過驗證提醒**：它以較少的提示驗證自己的工作，所以測試或檢查的提醒通常是不必要的。

78* **規劃更大的任務**：給它您通常會分成多個部分的工作。它能維持長時間的會話而不失去思路。78* **規劃更大的任務**：給它您通常會分成多個部分的工作。它能維持長時間的會話而不失去思路。

79 79

80<Note>80<Note>

81 Fable 5 需要 Claude Code v2.1.170 或更新版本。較舊的版本不會在模型選擇器中顯示 Fable 5，也無法選擇它。執行 `claude update` 以升級。Fable 5 在[零資料保留](/zh-TW/zero-data-retention)下不可用，其中 `/model` 選擇器要麼省略它，要麼將其顯示為已停用。81 Fable 5 需要 Claude Code v2.1.170 或更新版本。較舊的版本不會在模型選擇器中顯示 Fable 5，也無法選擇它。執行 `claude update` 以升級。Fable 5 在[零資料保留](/docs/zh-TW/zero-data-retention)下不可用，其中 `/model` 選擇器要麼省略它，要麼將其顯示為已停用。

82</Note>82</Note>

83 83

84<h3 id="setting-your-model">84<h3 id="setting-your-model">

97* `Enter`：切換模型並儲存為您的預設值97* `Enter`：切換模型並儲存為您的預設值

98* `s`：僅針對此會話切換模型98* `s`：僅針對此會話切換模型

99 99

100直接輸入 `/model <name>` 的行為類似於 `Enter`。{/* min-version: 2.1.205 */}在[非互動模式](/zh-TW/headless)中使用 `/model` 設定的模型，搭配 `-p` 旗標，僅適用於目前會話，不會儲存為您的預設值。專案和受管設定仍然優先，並在下次啟動時重新應用。{/* min-version: 2.1.196 */}您的管理員配置的[組織預設模型](#organization-default-model)也會在下次啟動時重新應用。100直接輸入 `/model <name>` 的行為類似於 `Enter`。在[非互動模式](/docs/zh-TW/headless)中使用 `/model` 設定的模型，搭配 `-p` 旗標，僅適用於目前會話，不會儲存為您的預設值。專案和受管設定仍然優先，並在下次啟動時重新應用。您的管理員配置的[組織預設模型](#organization-default-model)也會在下次啟動時重新應用。

101 101

102在 v2.1.144 至 v2.1.152 中，`/model` 僅適用於目前會話，選擇器中的 `d` 儲存預設值。102在 v2.1.144 至 v2.1.152 中，`/model` 僅適用於目前會話，選擇器中的 `d` 儲存預設值。

103 103

104`--model` 旗標和 `ANTHROPIC_MODEL` 環境變數僅適用於您啟動它們的會話。若要同時在不同終端中執行不同的模型，請使用各自的 `--model` 旗標啟動每個終端，而不是使用 `/model` 切換。104`--model` 旗標和 `ANTHROPIC_MODEL` 環境變數僅適用於您啟動它們的會話。若要同時在不同終端中執行不同的模型，請使用各自的 `--model` 旗標啟動每個終端，而不是使用 `/model` 切換。

105 105

106當 Claude Code 與 Anthropic API 通訊時，`/model` 選擇器中的價格會出現，直接或透過代理它的 [LLM 閘道](/zh-TW/llm-gateway)，而一列上的價格是該列選擇的模型的價格。在 [Amazon Bedrock](/zh-TW/third-party-integrations) 等第三方提供者上，以及在 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)上，您的提供者或閘道決定您支付的費用，所以選擇器列不顯示價格。價格僅是顯示標籤；它不會影響一列選擇哪個模型或您的提供者計費的內容。在 v2.1.206 之前，[AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 和閘道會話顯示 Anthropic 列表價格，一列可能顯示與其選擇的模型不同的模型的價格。106當 Claude Code 與 Anthropic API 通訊時，`/model` 選擇器中的價格會出現，直接或透過代理它的 [LLM 閘道](/docs/zh-TW/llm-gateway)，而一列上的價格是該列選擇的模型的價格。在 [Amazon Bedrock](/docs/zh-TW/third-party-integrations) 等第三方提供者上，以及在 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)上，您的提供者或閘道決定您支付的費用，所以選擇器列不顯示價格。價格僅是顯示標籤；它不會影響一列選擇哪個模型或您的提供者計費的內容。在 v2.1.206 之前，[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 和閘道會話顯示 Anthropic 列表價格，一列可能顯示與其選擇的模型不同的模型的價格。

107 107

108使用 `claude --resume`、`--continue` 或 `/resume` 選擇器啟動的已恢復會話會保持它們在儲存文字記錄時使用的模型，無論目前的 `model` 設定如何。如果該模型已被淘汰或被 [`availableModels`](#restrict-model-selection) 排除，會話會回到正常的優先順序。這可防止另一個會話的 `/model` 選擇在恢復時改變模型。108使用 `claude --resume`、`--continue` 或 `/resume` 選擇器啟動的已恢復會話會保持它們在儲存文字記錄時使用的模型，無論目前的 `model` 設定如何。如果該模型已被淘汰或被 [`availableModels`](#restrict-model-selection) 排除，會話會回到正常的優先順序。這可防止另一個會話的 `/model` 選擇在恢復時改變模型。

109 109

110您在新啟動時使用 `--model` 或 `ANTHROPIC_MODEL` 選擇的模型仍然優先於還原的模型。{/* min-version: 2.1.195 */}自 v2.1.195 起，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列變數也是如此。110您在新啟動時使用 `--model` 或 `ANTHROPIC_MODEL` 選擇的模型仍然優先於還原的模型。自 v2.1.195 起，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列變數也是如此。

111 111

112當啟動時的活動模型來自專案或受管設定而非您自己的選擇時，啟動標題會顯示哪個設定檔設定了它。執行 `/model` 以覆蓋；專案或受管設定會在下次啟動時重新應用。112當啟動時的活動模型來自專案或受管設定而非您自己的選擇時，啟動標題會顯示哪個設定檔設定了它。執行 `/model` 以覆蓋；專案或受管設定會在下次啟動時重新應用。

113 113

114當透過 [Agent SDK](/zh-TW/agent-sdk/overview) `setModel()` 方法或由執行 Claude Code CLI 的應用程式（例如 [Desktop app](/zh-TW/desktop)）要求模型切換時，Claude Code 會檢查該字串是否為它識別的字串，然後再儲存它。此檢查需要 Claude Code v2.1.200 或更新版本。在 Anthropic API 上，Claude Code 識別：114當透過 [Agent SDK](/docs/zh-TW/agent-sdk/overview) `setModel()` 方法或由執行 Claude Code CLI 的應用程式（例如 [Desktop app](/docs/zh-TW/desktop)）要求模型切換時，Claude Code 會檢查該字串是否為它識別的字串，然後再儲存它。此檢查需要 Claude Code v2.1.200 或更新版本。在 Anthropic API 上，Claude Code 識別：

115 115

116* 一個模型別名116* 一個模型別名

117* 來自 `/model` 選擇器的項目117* 來自 `/model` 選擇器的項目

118* 任何以 `claude-` 開頭的名稱118* 任何以 `claude-` 開頭的名稱

119* 您自己配置為[自訂模型選項](#add-a-custom-model-option)或在 [`modelOverrides`](#override-model-ids-per-version) 中的值119* 您自己配置為[自訂模型選項](#add-a-custom-model-option)或在 [`modelOverrides`](#override-model-ids-per-version) 中的值

120 120

121Claude Code 會以 `Model "<name>" is not a recognized model id.` 拒絕無法識別的字串，會話會保持其目前的模型，而不是儲存該字串並在下一個請求時失敗。請參閱[錯誤參考](/zh-TW/errors#model-is-not-a-recognized-model-id)以了解復原步驟。121Claude Code 會以 `Model "<name>" is not a recognized model id.` 拒絕無法識別的字串，會話會保持其目前的模型，而不是儲存該字串並在下一個請求時失敗。請參閱[錯誤參考](/docs/zh-TW/errors#model-is-not-a-recognized-model-id)以了解復原步驟。

122 122

123檢查僅在 Anthropic API 上執行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 和 [LLM 閘道](/zh-TW/llm-gateway)後方或自訂 `ANTHROPIC_BASE_URL` 後方，您的提供者或閘道定義模型名稱，所以 Claude Code 會不檢查地傳遞任何字串。檢查也不涵蓋 `--model` 旗標、`ANTHROPIC_MODEL` 環境變數或 `model` 設定；在那裡輸入錯誤的值會在第一個請求時產生[所選模型有問題](/zh-TW/errors#theres-an-issue-with-the-selected-model)。123檢查僅在 Anthropic API 上執行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 和 [LLM 閘道](/docs/zh-TW/llm-gateway)後方或自訂 `ANTHROPIC_BASE_URL` 後方，您的提供者或閘道定義模型名稱，所以 Claude Code 會不檢查地傳遞任何字串。檢查也不涵蓋 `--model` 旗標、`ANTHROPIC_MODEL` 環境變數或 `model` 設定；在那裡輸入錯誤的值會在第一個請求時產生[所選模型有問題](/docs/zh-TW/errors#theres-an-issue-with-the-selected-model)。

124 124

125當請求的模型有排定的淘汰日期或自動重新對應到較新版本時，Claude Code 會顯示一個警告，其中命名了請求的模型。互動式會話會將其顯示為啟動通知。從 v2.1.182 起，當使用預設文字輸出格式時，相同的警告會在[非互動模式](/zh-TW/headless)中寫入 stderr。檢查也涵蓋在[子代理 frontmatter](/zh-TW/sub-agents) 中設定的 `model`。對於 `--output-format json` 和 `stream-json`，stderr 警告會被抑制；改為從[結果訊息](/zh-TW/headless#get-structured-output)的 `modelUsage` 欄位讀取實際模型。125當請求的模型有排定的淘汰日期或自動重新對應到較新版本時，Claude Code 會顯示一個警告，其中命名了請求的模型。互動式會話會將其顯示為啟動通知。從 v2.1.182 起，當使用預設文字輸出格式時，相同的警告會在[非互動模式](/docs/zh-TW/headless)中寫入 stderr。檢查也涵蓋在[子代理 frontmatter](/docs/zh-TW/sub-agents) 中設定的 `model`。對於 `--output-format json` 和 `stream-json`，stderr 警告會被抑制；改為從[結果訊息](/docs/zh-TW/headless#get-structured-output)的 `modelUsage` 欄位讀取實際模型。

126 126

127使用範例：127使用範例：

128 128

149 限制模型選擇149 限制模型選擇

150</h2>150</h2>

151 151

152企業管理員可以在[受管理或政策設定](/zh-TW/settings#settings-files)中使用 `availableModels` 來限制使用者可以選擇的模型。項目符合模型系列（例如 `sonnet`）、版本前綴（例如 `claude-sonnet-4-5`）或完整模型 ID（例如 `claude-sonnet-4-5-20250929`）。152企業管理員可以在[受管理或政策設定](/docs/zh-TW/settings#settings-files)中使用 `availableModels` 來限制使用者可以選擇的模型。項目符合模型系列（例如 `sonnet`）、版本前綴（例如 `claude-sonnet-4-5`）或完整模型 ID（例如 `claude-sonnet-4-5-20250929`）。

153 153

154設定 `availableModels` 後，允許清單適用於使用者可以指定模型的每個位置：154設定 `availableModels` 後，允許清單適用於使用者可以指定模型的每個位置：

155 155

156* **主要會話模型**：`/model`、`--model` 旗標、`ANTHROPIC_MODEL` 環境變數、`model` 設定，以及[恢復會話](#setting-your-model)時還原的模型156* **主要會話模型**：`/model`、`--model` 旗標、`ANTHROPIC_MODEL` 環境變數、`model` 設定，以及[恢復會話](#setting-your-model)時還原的模型

157* **別名解析**：{/* min-version: 2.1.176 */}`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_DEFAULT_FABLE_MODEL` 環境變數無法將允許的別名重新導向到清單外的模型157* **別名解析**：`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_DEFAULT_FABLE_MODEL` 環境變數無法將允許的別名重新導向到清單外的模型

158* **快速模式**：{/* min-version: 2.1.176 */}`/fast` 在隱含切換到清單外的 Opus 模型時拒絕切換，並顯示訊息「不在您組織的允許模型中」158* **快速模式**：`/fast` 在隱含切換到清單外的 Opus 模型時拒絕切換，並顯示訊息「不在您組織的允許模型中」

159* **子代理模型**：[子代理](/zh-TW/sub-agents#choose-a-model) frontmatter 中的 `model` 欄位、Agent 工具的 `model` 參數、`CLAUDE_CODE_SUBAGENT_MODEL`，以及在 v2.1.197 及更早版本上，`/agents` 精靈中的模型選擇器{/* max-version: 2.1.197 */}159* **子代理模型**：[子代理](/docs/zh-TW/sub-agents#choose-a-model) frontmatter 中的 `model` 欄位、Agent 工具的 `model` 參數、`CLAUDE_CODE_SUBAGENT_MODEL`，以及在 v2.1.197 及更早版本上，`/agents` 精靈中的模型選擇器

160* **技能和命令模型**：[技能和命令](/zh-TW/skills)中的 `model` frontmatter160* **技能和命令模型**：[技能和命令](/docs/zh-TW/skills)中的 `model` frontmatter

161* **顧問模型**：已設定的 [`advisorModel`](/zh-TW/advisor) 設定和 `--advisor` 旗標161* **顧問模型**：已設定的 [`advisorModel`](/docs/zh-TW/advisor) 設定和 `--advisor` 旗標

162* **背景代理模型**：在[分派選擇器](/zh-TW/agent-view)中選擇的模型162* **背景代理模型**：在[分派選擇器](/docs/zh-TW/agent-view)中選擇的模型

163 163

164在 Anthropic API 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上，模型系列別名 `opus`、`sonnet`、`haiku` 或 `fable` 解析為允許清單允許的其系列的最新版本。當允許清單固定特定版本時，例如 `["sonnet", "claude-opus-4-6"]`，`/model opus` 和 `--model opus` 都會選擇 Claude Opus 4.6（最新允許的 Opus），並顯示一個通知，命名所要求和替代的模型。在 v2.1.205 之前，其最新發佈版本在清單外的別名會被拒絕或替換，就像任何其他被阻止的選擇一樣，即使清單允許較舊版本。164在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 上，模型系列別名 `opus`、`sonnet`、`haiku` 或 `fable` 解析為允許清單允許的其系列的最新版本。當允許清單固定特定版本時，例如 `["sonnet", "claude-opus-4-6"]`，`/model opus` 和 `--model opus` 都會選擇 Claude Opus 4.6（最新允許的 Opus），並顯示一個通知，命名所要求和替代的模型。在 v2.1.205 之前，其最新發佈版本在清單外的別名會被拒絕或替換，就像任何其他被阻止的選擇一樣，即使清單允許較舊版本。

165 165

166Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [Mantle](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 使用提供者特定的部署 ID 而不是 Anthropic 模型 ID，因此被阻止的別名在那裡遵循下面的拒絕和替換行為。166Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [Mantle](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 使用提供者特定的部署 ID 而不是 Anthropic 模型 ID，因此被阻止的別名在那裡遵循下面的拒絕和替換行為。

167 167

168Claude Code 根據模型的設定位置處理任何其他被阻止的選擇：168Claude Code 根據模型的設定位置處理任何其他被阻止的選擇：

169 169

173* **`advisorModel` 設定**：該會話的顧問被停用173* **`advisorModel` 設定**：該會話的顧問被停用

174* **`--advisor` 旗標**：Claude Code 在啟動時以錯誤退出174* **`--advisor` 旗標**：Claude Code 在啟動時以錯誤退出

175 175

176排除的模型會從 `/model` 選擇器中隱藏。{/* min-version: 2.1.199 */}清單中沒有內建選擇器列的完整模型 ID（例如清單固定的較舊版本）會在 `/model` 選擇器中顯示為其自己的標記列。在 v2.1.199 之前，此類 ID 只能透過輸入 `/model <id>` 選擇。176排除的模型會從 `/model` 選擇器中隱藏。清單中沒有內建選擇器列的完整模型 ID（例如清單固定的較舊版本）會在 `/model` 選擇器中顯示為其自己的標記列。在 v2.1.199 之前，此類 ID 只能透過輸入 `/model <id>` 選擇。

177 177

178Claude Code 代表您進行的模型變更會以相同方式檢查：178Claude Code 代表您進行的模型變更會以相同方式檢查：

179 179

180* **[後備模型鏈](#fallback-model-chains)**：清單外的元素會被捨棄180* **[後備模型鏈](#fallback-model-chains)**：清單外的元素會被捨棄

181* **Plan Mode 升級**：在 Anthropic API 和 AWS 上的 Claude Platform 上，升級（例如 [`opusplan`](#opusplan-model-setting)）到排除的模型會使用升級系列的最新允許版本。在具有提供者特定模型 ID 的提供者上，以及當沒有版本被允許時，升級會被跳過，計畫會在會話的模型上繼續181* **Plan Mode 升級**：在 Anthropic API 和 AWS 上的 Claude Platform 上，升級（例如 [`opusplan`](#opusplan-model-setting)）到排除的模型會使用升級系列的最新允許版本。在具有提供者特定模型 ID 的提供者上，以及當沒有版本被允許時，升級會被跳過，計畫會在會話的模型上繼續

182* **[自動模型後備](#automatic-model-fallback)**：目標被排除的後備不會執行，因此標記的請求會以拒絕結束182* **[自動模型後備](#automatic-model-fallback)**：目標被排除的後備不會執行，因此標記的請求會以拒絕結束

183* **[快速模式](/zh-TW/fast-mode)**：當會話之後執行的模型在允許清單外時，啟用快速模式會被拒絕183* **[快速模式](/docs/zh-TW/fast-mode)**：當會話之後執行的模型在允許清單外時，啟用快速模式會被拒絕

184 184

185```json theme={null}185```json theme={null}

186{186{

196 196

198| :------------------------------------------------- | :-------- | :----- | :---------- | :-------------- | :-------- |198| :------------------------------------------------- | :-------- | :----- | :---------- | :-------------- | :-------- |

201 201

202* 雲端會話在[網路上的 Claude Code](/zh-TW/claude-code-on-the-web) 或桌面應用程式中執行，在 Anthropic 管理的 VM 上執行：部署到您的裝置的設定無法到達它們，因此請透過伺服器管理設定傳遞允許清單。雲端會話中的中途會話模型切換在要求的模型被允許清單排除時被拒絕。會話建立時的伺服器端拒絕適用於[組織模型限制](#organization-model-restrictions)，而不是 `availableModels` 設定鍵。202* 雲端會話在[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 或桌面應用程式中執行，在 Anthropic 管理的 VM 上執行：部署到您的裝置的設定無法到達它們，因此請透過伺服器管理設定傳遞允許清單。雲端會話中的中途會話模型切換在要求的模型被允許清單排除時被拒絕。會話建立時的伺服器端拒絕適用於[組織模型限制](#organization-model-restrictions)，而不是 `availableModels` 設定鍵。

203* Cowork 是 Claude 桌面應用程式中的代理工作標籤，不是 Claude Code 表面，根據設計不接收伺服器管理設定。受管理設定檔在會話執行的位置存在時適用於 Cowork 會話；遠端 Cowork 會話在 Anthropic 管理的 VM 上執行，其中不存在裝置部署的檔案。203* Cowork 是 Claude 桌面應用程式中的代理工作標籤，不是 Claude Code 表面，根據設計不接收伺服器管理設定。受管理設定檔在會話執行的位置存在時適用於 Cowork 會話；遠端 Cowork 會話在 Anthropic 管理的 VM 上執行，其中不存在裝置部署的檔案。

204* [第三方提供者](/zh-TW/server-managed-settings#platform-availability)（例如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws)）上的會話不接收伺服器管理設定，因此請在那裡透過 MDM 或受管理設定檔傳遞允許清單。204* [第三方提供者](/docs/zh-TW/server-managed-settings#platform-availability)（例如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)）上的會話不接收伺服器管理設定，因此請在那裡透過 MDM 或受管理設定檔傳遞允許清單。

205* 伺服器管理傳遞也需要會話使用組織登入或直接設定的 API 金鑰進行驗證。只透過 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼產生金鑰的艦隊應透過 MDM 或受管理設定檔傳遞允許清單。205* 伺服器管理傳遞也需要會話使用組織登入或直接設定的 API 金鑰進行驗證。只透過 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 指令碼產生金鑰的艦隊應透過 MDM 或受管理設定檔傳遞允許清單。

206* 桌面代碼標籤也裝載 [SSH 會話](/zh-TW/desktop#ssh-sessions)，它們從執行所在的遠端主機讀取受管理設定檔。請參閱[桌面受管理設定](/zh-TW/desktop#managed-settings)。206* 桌面代碼標籤也裝載 [SSH 會話](/docs/zh-TW/desktop#ssh-sessions)，它們從執行所在的遠端主機讀取受管理設定檔。請參閱[桌面受管理設定](/docs/zh-TW/desktop#managed-settings)。

207* claude.ai 和桌面應用程式中的模型選擇器會隱藏或灰顯您組織的允許清單排除的模型。選擇器狀態是使用者的便利；強制執行發生在會話中。207* claude.ai 和桌面應用程式中的模型選擇器會隱藏或灰顯您組織的允許清單排除的模型。選擇器狀態是使用者的便利；強制執行發生在會話中。

208 208

209<h3 id="default-model-behavior">209<h3 id="default-model-behavior">

231 231

232當 `availableModels` 未設定或為空時，`enforceAvailableModels` 無效：使用 `availableModels: []` 時，帳戶類型的「預設」模型保持可用，因此該設定無法將使用者鎖定在每個模型之外。當 `availableModels` 非空但沒有項目解析為允許的、可用的模型時，強制執行會降級，「預設」會回退到帳戶類型預設值，警告僅在 `--debug` 下可見。在清單中保留至少一個保證可用的項目以避免這種情況。232當 `availableModels` 未設定或為空時，`enforceAvailableModels` 無效：使用 `availableModels: []` 時，帳戶類型的「預設」模型保持可用，因此該設定無法將使用者鎖定在每個模型之外。當 `availableModels` 非空但沒有項目解析為允許的、可用的模型時，強制執行會降級，「預設」會回退到帳戶類型預設值，警告僅在 `--debug` 下可見。在清單中保留至少一個保證可用的項目以避免這種情況。

233 233

234在[最高優先順序受管理來源](/zh-TW/settings#settings-precedence)中部署兩個鍵：管理員部署的受管理來源不會合併，因此放在受管理設定檔中的一對在管理員主控台傳遞任何設定時會被忽略。234在[最高優先順序受管理來源](/docs/zh-TW/settings#settings-precedence)中部署兩個鍵：管理員部署的受管理來源不會合併，因此放在受管理設定檔中的一對在管理員主控台傳遞任何設定時會被忽略。

235 235

236<h3 id="control-the-model-users-run-on">236<h3 id="control-the-model-users-run-on">

237 控制使用者執行的模型237 控制使用者執行的模型

265 合併行為265 合併行為

266</h3>266</h3>

267 267

268當[最高優先順序受管理設定來源](/zh-TW/server-managed-settings#settings-precedence)定義 `availableModels` 時，該清單單獨適用：使用者、專案或本機設定中的項目無法擴展它，而管理員部署的受管理來源不會彼此合併，因此在伺服器管理設定傳遞任何鍵時，部署在受管理設定檔中的清單會被忽略。否則，來自使用者、專案和本機設定的清單會像其他陣列設定一樣[連接和去重](/zh-TW/settings#settings-precedence)。{/* min-version: 2.1.175 */}自 Claude Code v2.1.175 起，受管理清單會取代較低優先順序的項目；較早版本會合併它們。268當[最高優先順序受管理設定來源](/docs/zh-TW/server-managed-settings#settings-precedence)定義 `availableModels` 時，該清單單獨適用：使用者、專案或本機設定中的項目無法擴展它，而管理員部署的受管理來源不會彼此合併，因此在伺服器管理設定傳遞任何鍵時，部署在受管理設定檔中的清單會被忽略。否則，來自使用者、專案和本機設定的清單會像其他陣列設定一樣[連接和去重](/docs/zh-TW/settings#settings-precedence)。自 Claude Code v2.1.175 起，受管理清單會取代較低優先順序的項目；較早版本會合併它們。

269 269

270在有效清單中，命名系列中特定模型的項目（無論是版本前綴還是完整模型 ID）會停用該系列的萬用字元項目：`["sonnet", "claude-sonnet-4-5"]` 只允許 Sonnet 4.5 版本，而不是每個 Sonnet 模型。270在有效清單中，命名系列中特定模型的項目（無論是版本前綴還是完整模型 ID）會停用該系列的萬用字元項目：`["sonnet", "claude-sonnet-4-5"]` 只允許 Sonnet 4.5 版本，而不是每個 Sonnet 模型。

271 271

273 Mantle 模型 ID273 Mantle 模型 ID

274</h3>274</h3>

275 275

276當[Amazon Bedrock Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)啟用時，`availableModels` 中以 `anthropic.` 開頭的項目會作為自訂選項新增到 `/model` 選擇器，並路由到 Mantle 端點。這是[為第三方部署固定模型](#pin-models-for-third-party-deployments)中描述的別名符合的例外。該設定仍然將選擇器限制為列出的項目，而 Mantle ID 嵌入系列名稱，因此它計為特定項目並停用該系列的萬用字元：在任何 Mantle ID 旁邊，列出您想要保持可選擇的版本前綴或完整 ID。請參閱[合併行為](#merge-behavior)。276當[Amazon Bedrock Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)啟用時，`availableModels` 中以 `anthropic.` 開頭的項目會作為自訂選項新增到 `/model` 選擇器，並路由到 Mantle 端點。這是[為第三方部署固定模型](#pin-models-for-third-party-deployments)中描述的別名符合的例外。該設定仍然將選擇器限制為列出的項目，而 Mantle ID 嵌入系列名稱，因此它計為特定項目並停用該系列的萬用字元：在任何 Mantle ID 旁邊，列出您想要保持可選擇的版本前綴或完整 ID。請參閱[合併行為](#merge-behavior)。

277 277

278<h3 id="organization-model-restrictions">278<h3 id="organization-model-restrictions">

279 組織模型限制279 組織模型限制

283 283

284當成員登入或使用自己的 API 金鑰時，限制適用。組織範圍的認證（例如組織服務金鑰）未與使用者相關聯，因此限制不適用於它們。284當成員登入或使用自己的 API 金鑰時，限制適用。組織範圍的認證（例如組織服務金鑰）未與使用者相關聯，因此限制不適用於它們。

285 285

286Claude Console 沒有模型限制控制。沒有 Claude Enterprise 計畫的組織（包括其成員透過 Anthropic API 進行驗證的組織）改為在[受管理設定](/zh-TW/settings#settings-files)中使用 [`availableModels`](#restrict-model-selection) 限制模型，新增 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 以涵蓋「預設」選項。這些設定由 Claude Code 本身強制執行，而不是由伺服器強制執行。286Claude Console 沒有模型限制控制。沒有 Claude Enterprise 計畫的組織（包括其成員透過 Anthropic API 進行驗證的組織）改為在[受管理設定](/docs/zh-TW/settings#settings-files)中使用 [`availableModels`](#restrict-model-selection) 限制模型，新增 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 以涵蓋「預設」選項。這些設定由 Claude Code 本身強制執行，而不是由伺服器強制執行。

287 287

288受限制的模型會從 `/model` 選擇器中隱藏。使用 `--model`、`ANTHROPIC_MODEL` 環境變數或 `model` 設定按名稱選擇它會顯示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，會話會在允許的模型上啟動。為受限制的模型輸入 `/model <name>` 會被拒絕，並顯示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，會話會保持其目前模型。288受限制的模型會從 `/model` 選擇器中隱藏。使用 `--model`、`ANTHROPIC_MODEL` 環境變數或 `model` 設定按名稱選擇它會顯示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，會話會在允許的模型上啟動。為受限制的模型輸入 `/model <name>` 會被拒絕，並顯示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，會話會保持其目前模型。

289 289

296* Haiku 模型始終可用，無法停用，因此每個成員至少保留一個可用模型。296* Haiku 模型始終可用，無法停用，因此每個成員至少保留一個可用模型。

297* 存取變更在約一分鐘內對新請求生效；`/model` 選擇器在下次會話啟動時反映它。297* 存取變更在約一分鐘內對新請求生效；`/model` 選擇器在下次會話啟動時反映它。

298 298

299這兩個限制組合：只有當模型被 `availableModels` 允許且未被組織限制時，它才可選擇。組織限制會傳遞到 Anthropic API 和 [LLM 閘道](/zh-TW/llm-gateway)部署上的會話。Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上的會話不接收它們，因此請改為在這些提供者上使用 `availableModels`。299這兩個限制組合：只有當模型被 `availableModels` 允許且未被組織限制時，它才可選擇。組織限制會傳遞到 Anthropic API 和 [LLM 閘道](/docs/zh-TW/llm-gateway)部署上的會話。Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上的會話不接收它們，因此請改為在這些提供者上使用 `availableModels`。

300 300

301<h2 id="organization-default-model">301<h2 id="organization-default-model">

302 組織預設模型302 組織預設模型

303</h2>303</h2>

304 304

305{/* plan-availability: feature=org-default-model plans=enterprise */}

~~306~~

307Claude Enterprise 計畫上的組織管理員可以從 claude.ai 管理員主控台為 Claude Code 成員設定預設模型，適用於整個組織或按自訂角色。設定後，「預設」選項會解析為該模型，而不是[帳戶類型預設](#default-model-setting)。需要 Claude Code v2.1.196 或更新版本。305Claude Enterprise 計畫上的組織管理員可以從 claude.ai 管理員主控台為 Claude Code 成員設定預設模型，適用於整個組織或按自訂角色。設定後，「預設」選項會解析為該模型，而不是[帳戶類型預設](#default-model-setting)。需要 Claude Code v2.1.196 或更新版本。

308 306

309`/model` 選擇器中的「預設」列會顯示組織預設值的名稱，標籤為「Org default」。無論管理員是為整個組織還是為您的角色設定預設值，標籤都會讀取「Org default」。角色預設值涵蓋該自訂角色的成員，並優先於組織範圍的預設值；當您的多個角色設定不同的預設值時，最強大的模型適用。307`/model` 選擇器中的「預設」列會顯示組織預設值的名稱，標籤為「Org default」。無論管理員是為整個組織還是為您的角色設定預設值，標籤都會讀取「Org default」。角色預設值涵蓋該自訂角色的成員，並優先於組織範圍的預設值；當您的多個角色設定不同的預設值時，最強大的模型適用。

311組織預設值是起點，而非限制，任何其他模型選擇都優先於它：309組織預設值是起點，而非限制，任何其他模型選擇都優先於它：

312 310

313* `--model` 旗標和 `ANTHROPIC_MODEL` 環境變數311* `--model` 旗標和 `ANTHROPIC_MODEL` 環境變數

314* [受管理設定](/zh-TW/settings#settings-files)中的 `model` 值或透過 `--settings` 提供312* [受管理設定](/docs/zh-TW/settings#settings-files)中的 `model` 值或透過 `--settings` 提供

315* 您的使用者、專案或本機設定中的 `model` 值，包括您使用 `/model` 儲存的模型313* 您的使用者、專案或本機設定中的 `model` 值，包括您使用 `/model` 儲存的模型

316 314

317管理員也可以配置組織預設值以覆蓋使用者選擇。啟用覆蓋後，它優先於使用者、專案和本機設定中的 `model` 值，因此您使用 `/model` 儲存的模型適用於目前會話，組織預設值在下次啟動時返回。當您的選擇不同時，`/model` 會顯示 `Your organization's default (<model>) applies on restart`。`--model` 旗標、`ANTHROPIC_MODEL`、受管理設定和 `--settings` 即使啟用覆蓋也仍然優先。覆蓋可用於有限的組織集合；詢問您的 Anthropic 帳戶團隊有關可用性。315管理員也可以配置組織預設值以覆蓋使用者選擇。啟用覆蓋後，它優先於使用者、專案和本機設定中的 `model` 值，因此您使用 `/model` 儲存的模型適用於目前會話，組織預設值在下次啟動時返回。當您的選擇不同時，`/model` 會顯示 `Your organization's default (<model>) applies on restart`。`--model` 旗標、`ANTHROPIC_MODEL`、受管理設定和 `--settings` 即使啟用覆蓋也仍然優先。覆蓋可用於有限的組織集合；詢問您的 Anthropic 帳戶團隊有關可用性。

326 324

327* [`availableModels`](#restrict-model-selection) 本身永遠不會限制「預設」選項，因此允許清單外的組織預設值仍然適用。當也設定了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 時，允許清單外的組織預設值會重新對應到第一個允許清單項目，就像任何其他「預設」一樣325* [`availableModels`](#restrict-model-selection) 本身永遠不會限制「預設」選項，因此允許清單外的組織預設值仍然適用。當也設定了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 時，允許清單外的組織預設值會重新對應到第一個允許清單項目，就像任何其他「預設」一樣

328* [組織模型限制](#organization-model-restrictions)拒絕的組織預設值會被替換為其系列中最新的允許模型，或當該系列的每個版本都被限制時被替換為較低成本的系列326* [組織模型限制](#organization-model-restrictions)拒絕的組織預設值會被替換為其系列中最新的允許模型，或當該系列的每個版本都被限制時被替換為較低成本的系列

329* 對您的帳戶完全不可用的組織預設值，例如[零資料保留](/zh-TW/zero-data-retention)下的 Fable 5，會被跳過，「預設」選項會解析為帳戶類型預設值327* 對您的帳戶完全不可用的組織預設值，例如[零資料保留](/docs/zh-TW/zero-data-retention)下的 Fable 5，會被跳過，「預設」選項會解析為帳戶類型預設值

330 328

331自 v2.1.199 起，當組織預設值是與您帳戶類型的常用預設值不同的模型系列時，`/model` 選擇器會為該常用系列保留一個單獨的列，因此您仍然可以為會話切換到它。在 v2.1.196 至 v2.1.198 中，該列在選擇器中缺失。329自 v2.1.199 起，當組織預設值是與您帳戶類型的常用預設值不同的模型系列時，`/model` 選擇器會為該常用系列保留一個單獨的列，因此您仍然可以為會話切換到它。在 v2.1.196 至 v2.1.198 中，該列在選擇器中缺失。

332 330

333組織預設值會傳遞到使用 Anthropic API 進行驗證的會話。[LLM 閘道](/zh-TW/llm-gateway)部署、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上的會話不接收它。若要在這些部署上設定預設值，請改用[受管理設定](/zh-TW/settings#settings-files)中的 `model` 鍵。331組織預設值會傳遞到使用 Anthropic API 進行驗證的會話。[LLM 閘道](/docs/zh-TW/llm-gateway)部署、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 上的會話不接收它。若要在這些部署上設定預設值，請改用[受管理設定](/docs/zh-TW/settings#settings-files)中的 `model` 鍵。

334 332

335<h2 id="organization-effort-limits">333<h2 id="organization-effort-limits">

336 組織努力限制334 組織努力限制

337</h2>335</h2>

338 336

339{/* plan-availability: feature=org-effort-limits plans=enterprise */}

~~340~~

341Claude Enterprise 計畫上的組織管理員可以為每個自訂角色設定每個模型的最大[努力等級](#adjust-effort-level)，以及角色級別[組織模型限制](#organization-model-restrictions)。超過上限的等級不會在 `/effort` 選擇器中提供，使用 `--effort` 或 `/effort` 命名更高等級會改為在上限處執行。在互動式會話和純文字 `--print` 執行中，警告會命名所要求和應用的等級；使用 `json` 或 `stream-json` 輸出或在背景代理中，限制會無聲地應用。上限是按模型的，因此切換模型可以改變哪些等級可用。當您的多個角色授予相同的模型時，最寬鬆的上限適用。需要 Claude Code v2.1.195 或更新版本。337Claude Enterprise 計畫上的組織管理員可以為每個自訂角色設定每個模型的最大[努力等級](#adjust-effort-level)，以及角色級別[組織模型限制](#organization-model-restrictions)。超過上限的等級不會在 `/effort` 選擇器中提供，使用 `--effort` 或 `/effort` 命名更高等級會改為在上限處執行。在互動式會話和純文字 `--print` 執行中，警告會命名所要求和應用的等級；使用 `json` 或 `stream-json` 輸出或在背景代理中，限制會無聲地應用。上限是按模型的，因此切換模型可以改變哪些等級可用。當您的多個角色授予相同的模型時，最寬鬆的上限適用。需要 Claude Code v2.1.195 或更新版本。

342 338

343努力限制與[組織模型限制](#organization-model-restrictions)一起傳遞，並遵循相同的提供者可用性：Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上的會話不接收它們。339努力限制與[組織模型限制](#organization-model-restrictions)一起傳遞，並遵循相同的提供者可用性：Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 上的會話不接收它們。

344 340

345<h2 id="special-model-behavior">341<h2 id="special-model-behavior">

346 特殊模型行為342 特殊模型行為

359 355

360Enterprise 隨用隨付是指按使用量計費而非按訂閱席位計費的 Enterprise 組織。356Enterprise 隨用隨付是指按使用量計費而非按訂閱席位計費的 Enterprise 組織。

361 357

362{/* min-version: 2.1.207 */}在 v2.1.207 之前，`default` 在 AWS 上的 Claude Platform 上解析為 Opus 4.7，在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析為 Sonnet 4.5。358在 v2.1.207 之前，`default` 在 AWS 上的 Claude Platform 上解析為 Opus 4.7，在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析為 Sonnet 4.5。

363 359

364當管理員設定了[組織預設模型](#organization-default-model)時，`default` 會解析為該模型，而不是上述帳戶類型預設值。需要 Claude Code v2.1.196 或更新版本。360當管理員設定了[組織預設模型](#organization-default-model)時，`default` 會解析為該模型，而不是上述帳戶類型預設值。需要 Claude Code v2.1.196 或更新版本。

365 361

382 378

383當 [`availableModels`](#restrict-model-selection) 排除最新的 Opus 但允許較舊版本時，例如 `["sonnet", "claude-opus-4-6"]`，`opusplan` 會為計畫使用最新允許的 Opus，並且僅在排除每個 Opus 時才保持在 Sonnet 上。通常會在 Plan Mode 中升級到 Sonnet 的 Haiku 會話同樣會使用最新允許的 Sonnet，並且僅在排除每個 Sonnet 時才保持在 Haiku 上。在 v2.1.205 之前，當排除升級系列的最新版本時，Plan Mode 會保持在會話的模型上，即使允許清單允許較舊版本。379當 [`availableModels`](#restrict-model-selection) 排除最新的 Opus 但允許較舊版本時，例如 `["sonnet", "claude-opus-4-6"]`，`opusplan` 會為計畫使用最新允許的 Opus，並且僅在排除每個 Opus 時才保持在 Sonnet 上。通常會在 Plan Mode 中升級到 Sonnet 的 Haiku 會話同樣會使用最新允許的 Sonnet，並且僅在排除每個 Sonnet 時才保持在 Haiku 上。在 v2.1.205 之前，當排除升級系列的最新版本時，Plan Mode 會保持在會話的模型上，即使允許清單允許較舊版本。

384 380

385較舊允許版本的替換適用於 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Mantle 上，其部署使用提供者特定的模型 ID，當升級模型被排除時，Plan Mode 會保持在會話的模型上。381較舊允許版本的替換適用於 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Mantle 上，其部署使用提供者特定的模型 ID，當升級模型被排除時，Plan Mode 會保持在會話的模型上。

386 382

387如需混合方法，其中 Claude 在任務中途決定何時諮詢第二個模型，而不是在計畫邊界處切換，請參閱 [advisor tool](/zh-TW/advisor)。383如需混合方法，其中 Claude 在任務中途決定何時諮詢第二個模型，而不是在計畫邊界處切換，請參閱 [advisor tool](/docs/zh-TW/advisor)。

388 384

389<h3 id="fallback-model-chains">385<h3 id="fallback-model-chains">

390 回退模型鏈386 回退模型鏈

400claude --fallback-model sonnet,haiku396claude --fallback-model sonnet,haiku

401```397```

402 398

403若要在會話間持續保存鏈，請在 [settings](/zh-TW/settings) 中設定 `fallbackModel` 為陣列：399若要在會話間持續保存鏈，請在 [settings](/docs/zh-TW/settings) 中設定 `fallbackModel` 為陣列：

404 400

405```json theme={null}401```json theme={null}

406{402{

421 417

422本節涵蓋來自 Fable 5 的基於內容的回退。如需模型過載或不可用時的基於可用性的回退，請參閱 [Fallback model chains](#fallback-model-chains)。418本節涵蓋來自 Fable 5 的基於內容的回退。如需模型過載或不可用時的基於可用性的回退，請參閱 [Fallback model chains](#fallback-model-chains)。

423 419

424Fable 5 使用網路安全和生物學內容的安全分類器執行。當分類器標記請求時，Claude Code 會在您提供者的預設 Opus 模型上重新執行該請求，並在記錄中顯示通知。在 Anthropic API、[LLM gateway](/zh-TW/llm-gateway) 部署和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 上，該模型是 Opus 4.8。在 [Claude apps gateway](/zh-TW/claude-apps-gateway) 上，它是 Opus 4.7，除非您將 [`opus` 別名](#environment-variables)指向另一個模型。420Fable 5 使用網路安全和生物學內容的安全分類器執行。當分類器標記請求時，Claude Code 會在您提供者的預設 Opus 模型上重新執行該請求，並在記錄中顯示通知。在 Anthropic API、[LLM gateway](/docs/zh-TW/llm-gateway) 部署和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 上，該模型是 Opus 4.8。在 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 上，它是 Opus 4.7，除非您將 [`opus` 別名](#environment-variables)指向另一個模型。

425 421

426會話隨後在該 Opus 模型上繼續。若要返回 Fable 5，請執行 `/model fable`。422會話隨後在該 Opus 模型上繼續。若要返回 Fable 5，請執行 `/model fable`。

427 423

444某些情況的行為不同：440某些情況的行為不同：

445 441

446* 如果兩個模型都標記相同的請求，您可以編輯提示並重試，或啟動新會話。442* 如果兩個模型都標記相同的請求，您可以編輯提示並重試，或啟動新會話。

447* 在行動裝置 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 會話上，不支援編輯和重試。切換模型，或從桌面瀏覽器或桌面應用程式繼續會話。443* 在行動裝置 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 會話上，不支援編輯和重試。切換模型，或從桌面瀏覽器或桌面應用程式繼續會話。

448* 在 [non-interactive mode](/zh-TW/cli-reference#cli-flags) 和無法顯示提示的 SDK 整合中，標記的請求以拒絕結束輪次。444* 在 [non-interactive mode](/docs/zh-TW/cli-reference#cli-flags) 和無法顯示提示的 SDK 整合中，標記的請求以拒絕結束輪次。

449* 當回退目標被 [`availableModels`](#restrict-model-selection) 阻止時，不會顯示提示。標記的請求以拒絕結束，與目標被阻止時的自動回退相同。445* 當回退目標被 [`availableModels`](#restrict-model-selection) 阻止時，不會顯示提示。標記的請求以拒絕結束，與目標被阻止時的自動回退相同。

450 446

451<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">447<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">

452 在 Bedrock、Agent Platform 和 Foundry 上啟用回退448 在 Bedrock、Agent Platform 和 Foundry 上啟用回退

453</h4>449</h4>

454 450

455在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上，模型 ID 是提供者特定的，因此自動回退僅在 Claude Code 可以識別涉及的兩個模型時運作：451在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，模型 ID 是提供者特定的，因此自動回退僅在 Claude Code 可以識別涉及的兩個模型時運作：

456 452

457* Claude Code 必須將目前模型識別為 Fable 5：模型 ID 包含 `claude-fable-5`、符合 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值，或使用 [`modelOverrides`](#override-model-ids-per-version) 對應。453* Claude Code 必須將目前模型識別為 Fable 5：模型 ID 包含 `claude-fable-5`、符合 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值，或使用 [`modelOverrides`](#override-model-ids-per-version) 對應。

458* 回退目標必須解析為 Opus 模型：`ANTHROPIC_DEFAULT_OPUS_MODEL` 的值（如果設定），否則提供者模型清單中的 Opus 4.8 項目。454* 回退目標必須解析為 Opus 模型：`ANTHROPIC_DEFAULT_OPUS_MODEL` 的值（如果設定），否則提供者模型清單中的 Opus 4.8 項目。

485 481

486Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的預設努力為 `high`，Opus 4.7 上的預設努力為 `xhigh`。482Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的預設努力為 `high`，Opus 4.7 上的預設努力為 `xhigh`。

487 483

488當您首次執行 Fable 5、Opus 4.8 或 Opus 4.7 時，Claude Code 會應用該模型的預設努力，即使您之前為另一個模型設定了不同的等級：Fable 5 和 Opus 4.8 上的 `high`，以及 Opus 4.7 上的 `xhigh`。執行 `/effort` 以在切換後選擇不同的等級。該預設值在會話間保持，直到您進行明確的努力選擇，例如在互動式會話中執行 `/effort` 或使用 `--effort` 啟動。{/* min-version: 2.1.205 */}在 [non-interactive mode](/zh-TW/headless) 中使用 `/effort` 設定的等級，使用 `-p` 旗標，僅適用於目前會話，不會儲存為您的預設值。非互動式 `/effort` 也無法釋放上述模型預設值保持：在 Fable 5、Opus 4.8 和 Opus 4.7 上，它報告 `Not applied`，會話保持在模型的預設努力，因此改為在啟動時傳遞 `--effort`。`max` 提供最深入的推理，對 token 支出沒有限制，並且僅適用於目前會話，除非透過 `CLAUDE_CODE_EFFORT_LEVEL` 環境變數設定。484當您首次執行 Fable 5、Opus 4.8 或 Opus 4.7 時，Claude Code 會應用該模型的預設努力，即使您之前為另一個模型設定了不同的等級：Fable 5 和 Opus 4.8 上的 `high`，以及 Opus 4.7 上的 `xhigh`。執行 `/effort` 以在切換後選擇不同的等級。該預設值在會話間保持，直到您進行明確的努力選擇，例如在互動式會話中執行 `/effort` 或使用 `--effort` 啟動。在 [non-interactive mode](/docs/zh-TW/headless) 中使用 `/effort` 設定的等級，使用 `-p` 旗標，僅適用於目前會話，不會儲存為您的預設值。非互動式 `/effort` 也無法釋放上述模型預設值保持：在 Fable 5、Opus 4.8 和 Opus 4.7 上，它報告 `Not applied`，會話保持在模型的預設努力，因此改為在啟動時傳遞 `--effort`。`max` 提供最深入的推理，對 token 支出沒有限制，並且僅適用於目前會話，除非透過 `CLAUDE_CODE_EFFORT_LEVEL` 環境變數設定。

489 485

490`/effort` 選單也提供 `ultracode`。Ultracode 是 Claude Code 設定而非模型努力等級：它向模型發送 `xhigh`，並額外讓 Claude 為實質性任務協調[動態工作流程](/zh-TW/workflows)。它僅適用於目前會話。486`/effort` 選單也提供 `ultracode`。Ultracode 是 Claude Code 設定而非模型努力等級：它向模型發送 `xhigh`，並額外讓 Claude 為實質性任務協調[動態工作流程](/docs/zh-TW/workflows)。它僅適用於目前會話。

491 487

492您可以透過以下任何方式開啟 ultracode：488您可以透過以下任何方式開啟 ultracode：

493 489

494* **`/effort`**：執行 `/effort ultracode`，或從選單中選擇它490* **`/effort`**：執行 `/effort ultracode`，或從選單中選擇它

495* **`--effort` 旗標**：使用 `claude --effort ultracode` 啟動，這會以 `xhigh` 努力和 ultracode 開啟會話491* **`--effort` 旗標**：使用 `claude --effort ultracode` 啟動，這會以 `xhigh` 努力和 ultracode 開啟會話

496* **`--settings` 或 Agent SDK 控制請求**：傳遞 `"ultracode": true`。[`applyFlagSettings()`](/zh-TW/agent-sdk/typescript#applyflagsettings) 請求也接受 `effortLevel: "ultracode"`492* **`--settings` 或 Agent SDK 控制請求**：傳遞 `"ultracode": true`。[`applyFlagSettings()`](/docs/zh-TW/agent-sdk/typescript#applyflagsettings) 請求也接受 `effortLevel: "ultracode"`

497 493

498將 `ultracode` 傳遞給 `--effort` 旗標或 Agent SDK `effortLevel` 值需要 Claude Code v2.1.203 或更新版本。在 v2.1.203 之前，`--effort ultracode` 列印 `Unknown --effort value 'ultracode'`，會話以預設努力啟動。494將 `ultracode` 傳遞給 `--effort` 旗標或 Agent SDK `effortLevel` 值需要 Claude Code v2.1.203 或更新版本。在 v2.1.203 之前，`--effort ultracode` 列印 `Unknown --effort value 'ultracode'`，會話以預設努力啟動。

499 495

500持續的 `effortLevel` 設定和 `CLAUDE_CODE_EFFORT_LEVEL` 環境變數不接受 `ultracode`。496持續的 `effortLevel` 設定和 `CLAUDE_CODE_EFFORT_LEVEL` 環境變數不接受 `ultracode`。

501 497

502當 ultracode 不可用時，例如當[工作流程被關閉](/zh-TW/workflows#turn-workflows-off)時，`--effort ultracode` 僅設定 `xhigh` 努力。498當 ultracode 不可用時，例如當[工作流程被關閉](/docs/zh-TW/workflows#turn-workflows-off)時，`--effort ultracode` 僅設定 `xhigh` 努力。

503 499

504<h4 id="choose-an-effort-level">500<h4 id="choose-an-effort-level">

505 選擇努力等級501 選擇努力等級

516| `max` | 可以改善困難任務的效能，但可能顯示遞減回報，容易過度思考。在廣泛採用前進行測試 |512| `max` | 可以改善困難任務的效能，但可能顯示遞減回報，容易過度思考。在廣泛採用前進行測試 |

518 514

519努力量表按模型進行校準，因此相同的等級名稱在模型之間不代表相同的基礎值。515努力量表按模型進行校準，因此相同的等級名稱在模型之間不代表相同的基礎值。

520 516

535* **`--effort` 旗標**：在啟動 Claude Code 時傳遞等級名稱以為單一會話設定531* **`--effort` 旗標**：在啟動 Claude Code 時傳遞等級名稱以為單一會話設定

536* **環境變數**：設定 `CLAUDE_CODE_EFFORT_LEVEL` 為等級名稱或 `auto`532* **環境變數**：設定 `CLAUDE_CODE_EFFORT_LEVEL` 為等級名稱或 `auto`

537* **設定**：在設定檔中設定 `effortLevel` 為 `low`、`medium`、`high` 或 `xhigh`。`max` 和 `ultracode` 是[僅限會話](#adjust-effort-level)，此處不接受533* **設定**：在設定檔中設定 `effortLevel` 為 `low`、`medium`、`high` 或 `xhigh`。`max` 和 `ultracode` 是[僅限會話](#adjust-effort-level)，此處不接受

538* **Skill 和 subagent frontmatter**：在 [skill](/zh-TW/skills#frontmatter-reference) 或 [subagent](/zh-TW/sub-agents#supported-frontmatter-fields) markdown 檔案中設定 `effort` 以在該 skill 或 subagent 執行時覆蓋努力等級534* **Skill 和 subagent frontmatter**：在 [skill](/docs/zh-TW/skills#frontmatter-reference) 或 [subagent](/docs/zh-TW/sub-agents#supported-frontmatter-fields) markdown 檔案中設定 `effort` 以在該 skill 或 subagent 執行時覆蓋努力等級

539 535

540環境變數優先於所有其他方法，然後是您配置的等級，然後是模型預設值。Frontmatter 努力在該 skill 或 subagent 活動時適用，覆蓋會話等級但不覆蓋環境變數。536環境變數優先於所有其他方法，然後是您配置的等級，然後是模型預設值。Frontmatter 努力在該 skill 或 subagent 活動時適用，覆蓋會話等級但不覆蓋環境變數。

541 537

549 545

550Fable 5、Sonnet 5 和 Opus 4.7 及更新版本始終使用自適應推理。固定思考預算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不適用於它們。546Fable 5、Sonnet 5 和 Opus 4.7 及更新版本始終使用自適應推理。固定思考預算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不適用於它們。

551 547

552在 Opus 4.6 和 Sonnet 4.6 上，您可以設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢復到由 `MAX_THINKING_TOKENS` 控制的先前固定思考預算。請參閱[環境變數](/zh-TW/env-vars)。548在 Opus 4.6 和 Sonnet 4.6 上，您可以設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢復到由 `MAX_THINKING_TOKENS` 控制的先前固定思考預算。請參閱[環境變數](/docs/zh-TW/env-vars)。

553 549

554<h3 id="extended-thinking">550<h3 id="extended-thinking">

555 擴展思考551 擴展思考

561| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |557| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

564| 無論努力如何禁用 | 設定 [`MAX_THINKING_TOKENS=0`](/zh-TW/env-vars)，這會在 Anthropic API 上關閉思考，除了 Fable 5。在[第三方提供者](/zh-TW/third-party-integrations)上，這會改為省略 `thinking` 參數，自適應推理模型可能仍然思考。其他值僅適用於[固定思考預算](#adaptive-reasoning-and-fixed-thinking-budgets) |560| 無論努力如何禁用 | 設定 [`MAX_THINKING_TOKENS=0`](/docs/zh-TW/env-vars)，這會在 Anthropic API 上關閉思考，除了 Fable 5。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，這會改為省略 `thinking` 參數，自適應推理模型可能仍然思考。其他值僅適用於[固定思考預算](#adaptive-reasoning-and-fixed-thinking-budgets) |

565 561

566思考無法在 Fable 5 上關閉。會話切換、`alwaysThinkingEnabled` 和 `MAX_THINKING_TOKENS=0` 在那裡沒有效果，Fable 5 根據努力等級決定每一步思考多少。562思考無法在 Fable 5 上關閉。會話切換、`alwaysThinkingEnabled` 和 `MAX_THINKING_TOKENS=0` 在那裡沒有效果，Fable 5 根據努力等級決定每一步思考多少。

567 563

568思考輸出預設為摺疊。按 `Ctrl+O` 以切換詳細模式並將推理視為灰色斜體文本。Anthropic API 上的互動式會話預設會收到編輯的思考區塊，因此如果您想要在展開時可用的完整摘要，請在[設定](/zh-TW/settings)中設定 `showThinkingSummaries: true`。您需要為所有生成的思考 token 付費，即使它們被摺疊或編輯。564思考輸出預設為摺疊。按 `Ctrl+O` 以切換詳細模式並將推理視為灰色斜體文本。Anthropic API 上的互動式會話預設會收到編輯的思考區塊，因此如果您想要在展開時可用的完整摘要，請在[設定](/docs/zh-TW/settings)中設定 `showThinkingSummaries: true`。您需要為所有生成的思考 token 付費，即使它們被摺疊或編輯。

569 565

570<h3 id="extended-context">566<h3 id="extended-context">

571 擴展 context567 擴展 context

581| Pro | 需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) | 需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |577| Pro | 需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) | 需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

583 579

584若要完全禁用 1M context，請設定 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。這會從模型選擇器中移除 1M 模型變體。請參閱[環境變數](/zh-TW/env-vars)。580若要完全禁用 1M context，請設定 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。這會從模型選擇器中移除 1M 模型變體。請參閱[環境變數](/docs/zh-TW/env-vars)。

585 581

5861M context window 使用標準模型定價，超過 200K 的 token 無需額外費用。對於訂閱中包含擴展 context 的計畫，使用量仍由您的訂閱涵蓋。對於透過使用額度存取擴展 context 的計畫，token 會計入使用額度。5821M context window 使用標準模型定價，超過 200K 的 token 無需額外費用。對於訂閱中包含擴展 context 的計畫，使用量仍由您的訂閱涵蓋。對於透過使用額度存取擴展 context 的計畫，token 會計入使用額度。

587 583

602 Sonnet 5 context window598 Sonnet 5 context window

603</h4>599</h4>

604 600

605在 Anthropic API 上，Sonnet 5 始終使用 1M context window 執行。沒有 200K 變體，沒有可選擇的 `[1m]` 後綴，任何計畫都不需要使用額度。會話會在 window 填滿前自動壓縮，預設約在 967K 個 token 時；設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/zh-TW/env-vars) 以選擇不同的閾值。601在 Anthropic API 上，Sonnet 5 始終使用 1M context window 執行。沒有 200K 變體，沒有可選擇的 `[1m]` 後綴，任何計畫都不需要使用額度。會話會在 window 填滿前自動壓縮，預設約在 967K 個 token 時；設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-TW/env-vars) 以選擇不同的閾值。

606 602

607兩種配置會改為以 200K 計算 window，並在該邊界自動壓縮：603兩種配置會改為以 200K 計算 window，並在該邊界自動壓縮：

608 604

609* **LLM gateway**：當 `ANTHROPIC_BASE_URL` 指向[gateway](/zh-TW/llm-gateway)時，Claude Code 無法驗證 1M 支援。若要使用完整的 window，請在模型選擇器中選擇 Sonnet 5 (1M context)，它會對應到 `sonnet[1m]`。605* **LLM gateway**：當 `ANTHROPIC_BASE_URL` 指向[gateway](/docs/zh-TW/llm-gateway)時，Claude Code 無法驗證 1M 支援。若要使用完整的 window，請在模型選擇器中選擇 Sonnet 5 (1M context)，它會對應到 `sonnet[1m]`。

610* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：將 Sonnet 5 會話視為具有 200K window，適用於需要限制 context 的部署。606* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：將 Sonnet 5 會話視為具有 200K window，適用於需要限制 context 的部署。

611 607

612<h2 id="checking-your-current-model">608<h2 id="checking-your-current-model">

615 611

616您可以在兩個地方查看您目前使用的模型：612您可以在兩個地方查看您目前使用的模型：

617 613

618* 在[狀態行](/zh-TW/statusline)中（如果已配置）614* 在[狀態行](/docs/zh-TW/statusline)中（如果已配置）

619* 在 `/status` 中，它也會顯示您的帳戶資訊615* 在 `/status` 中，它也會顯示您的帳戶資訊

620 616

621<h2 id="add-a-custom-model-option">617<h2 id="add-a-custom-model-option">

622 新增自訂模型選項618 新增自訂模型選項

623</h2>619</h2>

624 620

625使用 `ANTHROPIC_CUSTOM_MODEL_OPTION` 將單一自訂項目新增到 `/model` 選擇器，而無需取代內建別名。這對於測試 Claude Code 預設不列出的模型 ID 很有用。對於 LLM 閘道部署，當設定 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 時，Claude Code 可以從閘道的 `/v1/models` 端點填入選擇器，因此只有在探索被停用或未傳回您想要的模型時，才需要此變數。請參閱 [gateway model discovery](/zh-TW/llm-gateway-protocol#model-discovery)。621使用 `ANTHROPIC_CUSTOM_MODEL_OPTION` 將單一自訂項目新增到 `/model` 選擇器，而無需取代內建別名。這對於測試 Claude Code 預設不列出的模型 ID 很有用。對於 LLM 閘道部署，當設定 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 時，Claude Code 可以從閘道的 `/v1/models` 端點填入選擇器，因此只有在探索被停用或未傳回您想要的模型時，才需要此變數。請參閱 [gateway model discovery](/docs/zh-TW/llm-gateway-protocol#model-discovery)。

626 622

627此範例設定所有三個變數以使閘道路由的 Opus 部署可選擇：623此範例設定所有三個變數以使閘道路由的 Opus 部署可選擇：

628 624

647| `ANTHROPIC_DEFAULT_FABLE_MODEL` | 用於 `fable` 的模型，以及 Claude Code 識別為 Fable 5 的模型 ID，用於第三方提供者上的[自動模型回退](#automatic-model-fallback) |643| `ANTHROPIC_DEFAULT_FABLE_MODEL` | 用於 `fable` 的模型，以及 Claude Code 識別為 Fable 5 的模型 ID，用於第三方提供者上的[自動模型回退](#automatic-model-fallback) |

651| `CLAUDE_CODE_SUBAGENT_MODEL` | 用於所有 [subagents](/zh-TW/sub-agents#choose-a-model)、[agent teams](/zh-TW/agent-teams) 和 [workflow](/zh-TW/workflows) 執行的代理的模型。接受別名（例如 `haiku`）或完整模型名稱，並覆蓋每次調用的 `model` 參數和 subagent 定義的 `model` frontmatter。設定為 `inherit` 以改用一般模型解析 |647| `CLAUDE_CODE_SUBAGENT_MODEL` | 用於所有 [subagents](/docs/zh-TW/sub-agents#choose-a-model)、[agent teams](/docs/zh-TW/agent-teams) 和 [workflow](/docs/zh-TW/workflows) 執行的代理的模型。接受別名（例如 `haiku`）或完整模型名稱，並覆蓋每次調用的 `model` 參數和 subagent 定義的 `model` frontmatter。設定為 `inherit` 以改用一般模型解析 |

652 648

653注意：`ANTHROPIC_SMALL_FAST_MODEL` 已棄用，改用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。649注意：`ANTHROPIC_SMALL_FAST_MODEL` 已棄用，改用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。

654 650

656 為第三方部署固定模型652 為第三方部署固定模型

657</h3>653</h3>

658 654

659當透過 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 部署 Claude Code 時，在向使用者推出前固定模型版本。655當透過 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 或 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 部署 Claude Code 時，在向使用者推出前固定模型版本。

660 656

661不固定模型時，Claude Code 使用模型別名（例如 `fable`、`opus`、`sonnet` 和 `haiku`），這些別名會解析為每個提供者的內建預設模型 ID。該預設值可能落後於最新的 Anthropic 版本，而且它指向的模型可能尚未在使用者的帳戶中啟用。當預設值不可用時，Amazon Bedrock 和 Google Cloud's Agent Platform 使用者會看到通知並回退到該會話的先前版本，或當預設值是 Opus 模型且沒有 Opus 版本可用時回退到預設 Sonnet 模型。Microsoft Foundry 使用者會看到錯誤，因為 Microsoft Foundry 沒有等效的啟動檢查。657不固定模型時，Claude Code 使用模型別名（例如 `fable`、`opus`、`sonnet` 和 `haiku`），這些別名會解析為每個提供者的內建預設模型 ID。該預設值可能落後於最新的 Anthropic 版本，而且它指向的模型可能尚未在使用者的帳戶中啟用。當預設值不可用時，Amazon Bedrock 和 Google Cloud's Agent Platform 使用者會看到通知並回退到該會話的先前版本，或當預設值是 Opus 模型且沒有 Opus 版本可用時回退到預設 Sonnet 模型。Microsoft Foundry 使用者會看到錯誤，因為 Microsoft Foundry 沒有等效的啟動檢查。

662 658

687* 後綴是按變數讀取的，而不是按模型讀取的。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，一個變數中沒有 `[1m]` 的模型 ID 會使用 200K context，即使另一個變數設定相同的模型並帶有後綴。Sonnet 5 在這些提供者上始終以 1M window 執行，永遠不需要後綴。683* 後綴是按變數讀取的，而不是按模型讀取的。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，一個變數中沒有 `[1m]` 的模型 ID 會使用 200K context，即使另一個變數設定相同的模型並帶有後綴。Sonnet 5 在這些提供者上始終以 1M window 執行，永遠不需要後綴。

688 684

689<Note>685<Note>

690 使用第三方提供者時，透過 [MDM 或受管設定檔](/zh-TW/settings#settings-files) 傳遞的 `availableModels` 允許清單仍然適用；[伺服器管理的設定不會在那裡傳遞](/zh-TW/server-managed-settings#platform-availability)。篩選會根據模型別名（例如 `opus`）、版本前綴（例如 `claude-opus-4-8`）或完整提供者形式模型 ID 進行匹配。提供者特定的前綴（例如 `us.anthropic.`）不會被移除，因此若要允許特定模型，請列出選擇器顯示的相同提供者形式 ID，或透過 [`modelOverrides`](#override-model-ids-per-version) 對應它。任何 `[1m]` 後綴會從允許清單項目和請求的模型中移除，然後進行匹配。686 使用第三方提供者時，透過 [MDM 或受管設定檔](/docs/zh-TW/settings#settings-files) 傳遞的 `availableModels` 允許清單仍然適用；[伺服器管理的設定不會在那裡傳遞](/docs/zh-TW/server-managed-settings#platform-availability)。篩選會根據模型別名（例如 `opus`）、版本前綴（例如 `claude-opus-4-8`）或完整提供者形式模型 ID 進行匹配。提供者特定的前綴（例如 `us.anthropic.`）不會被移除，因此若要允許特定模型，請列出選擇器顯示的相同提供者形式 ID，或透過 [`modelOverrides`](#override-model-ids-per-version) 對應它。任何 `[1m]` 後綴會從允許清單項目和請求的模型中移除，然後進行匹配。

691</Note>687</Note>

692 688

693<h3 id="customize-pinned-model-display-and-capabilities">689<h3 id="customize-pinned-model-display-and-capabilities">

696 692

697當您在第三方提供者上固定模型時，提供者特定的 ID 會按原樣出現在 `/model` 選擇器中，Claude Code 可能無法識別模型支援的功能。您可以使用每個固定模型的伴隨環境變數覆蓋顯示名稱並宣告能力。693當您在第三方提供者上固定模型時，提供者特定的 ID 會按原樣出現在 `/model` 選擇器中，Claude Code 可能無法識別模型支援的功能。您可以使用每個固定模型的伴隨環境變數覆蓋顯示名稱並宣告能力。

698 694

699這些變數在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 等第三方提供者上生效。`_NAME` 和 `_DESCRIPTION` 變數在 `ANTHROPIC_BASE_URL` 指向 [LLM gateway](/zh-TW/llm-gateway) 時也會生效。當直接連接到 `api.anthropic.com` 時無效。695這些變數在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 等第三方提供者上生效。`_NAME` 和 `_DESCRIPTION` 變數在 `ANTHROPIC_BASE_URL` 指向 [LLM gateway](/docs/zh-TW/llm-gateway) 時也會生效。當直接連接到 `api.anthropic.com` 時無效。

700 696

701| 環境變數 | 描述 |697| 環境變數 | 描述 |

702| ----------------------------------------------------- | -------------------------------------------------------- |698| ----------------------------------------------------- | -------------------------------------------------------- |

711| 能力值 | 啟用 |707| 能力值 | 啟用 |

712| ---------------------- | ------------------------------------------ |708| ---------------------- | ------------------------------------------ |

714| `xhigh_effort` | {/* min-version: 2.1.111 */}`xhigh` 努力等級 |710| `xhigh_effort` | `xhigh` 努力等級 |

738 734

739這讓企業管理員可以將每個模型版本路由到特定的 Amazon Bedrock 推論設定檔 ARN、Google Cloud's Agent Platform 版本名稱或 Microsoft Foundry 部署名稱，以進行治理、成本分配或區域路由。735這讓企業管理員可以將每個模型版本路由到特定的 Amazon Bedrock 推論設定檔 ARN、Google Cloud's Agent Platform 版本名稱或 Microsoft Foundry 部署名稱，以進行治理、成本分配或區域路由。

740 736

741在您的[設定檔](/zh-TW/settings#settings-files)中設定 `modelOverrides`：737在您的[設定檔](/docs/zh-TW/settings#settings-files)中設定 `modelOverrides`：

742 738

743```json theme={null}739```json theme={null}

744{740{

754 750

755覆蓋會取代支援 `/model` 選擇器中每個項目的內建模型 ID。在 Amazon Bedrock 上，`modelOverrides` 項目優先於 Claude Code 在啟動時自動發現的任何推論設定檔。Claude Code 會將已經是提供者原生的值（例如 Amazon Bedrock 推論設定檔 ARN 或 Microsoft Foundry 部署名稱）按原樣傳遞給提供者。751覆蓋會取代支援 `/model` 選擇器中每個項目的內建模型 ID。在 Amazon Bedrock 上，`modelOverrides` 項目優先於 Claude Code 在啟動時自動發現的任何推論設定檔。Claude Code 會將已經是提供者原生的值（例如 Amazon Bedrock 推論設定檔 ARN 或 Microsoft Foundry 部署名稱）按原樣傳遞給提供者。

756 752

757{/* min-version: 2.1.200 */}當您直接透過 `--model`、`ANTHROPIC_MODEL` 環境變數或 `ANTHROPIC_DEFAULT_*_MODEL` 環境變數傳遞 Anthropic 模型 ID 時，覆蓋也會適用。在 Amazon Bedrock、Google Cloud's Agent Platform 和 [Mantle](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 上，沒有 `modelOverrides` 項目的 Anthropic 模型 ID 會解析為與該版本的 `/model` 選擇器列相同的提供者特定 ID（當提供者支援該版本時）。Mantle 支援版本的子集。對於該子集之外的 Anthropic 模型 ID，Claude Code 會將原始 ID 發送到 Mantle 而不進行對應，除非 `modelOverrides` 項目涵蓋它。在 v2.1.200 之前，`--model` 和環境變數值會按原樣到達提供者，不會通過覆蓋對應。753當您直接透過 `--model`、`ANTHROPIC_MODEL` 環境變數或 `ANTHROPIC_DEFAULT_*_MODEL` 環境變數傳遞 Anthropic 模型 ID 時，覆蓋也會適用。在 Amazon Bedrock、Google Cloud's Agent Platform 和 [Mantle](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 上，沒有 `modelOverrides` 項目的 Anthropic 模型 ID 會解析為與該版本的 `/model` 選擇器列相同的提供者特定 ID（當提供者支援該版本時）。Mantle 支援版本的子集。對於該子集之外的 Anthropic 模型 ID，Claude Code 會將原始 ID 發送到 Mantle 而不進行對應，除非 `modelOverrides` 項目涵蓋它。在 v2.1.200 之前，`--model` 和環境變數值會按原樣到達提供者，不會通過覆蓋對應。

758 754

759`modelOverrides` 與 `availableModels` 一起運作。允許清單會根據 Anthropic 模型 ID 進行評估，而不是覆蓋值，因此 `availableModels` 中的項目（如 `"opus"`）即使 Opus 版本對應到 ARN 時仍會繼續匹配。當在受管設定中設定 `enforceAvailableModels` 時，強制執行的預設值會從[最高優先順序受管來源](/zh-TW/server-managed-settings#settings-precedence)透過 `modelOverrides` 解析。管理員的對應（例如固定到推論設定檔 ARN 的版本）會在強制執行的預設值中受到尊重。來自使用者或專案設定的覆蓋不會影響它。755`modelOverrides` 與 `availableModels` 一起運作。允許清單會根據 Anthropic 模型 ID 進行評估，而不是覆蓋值，因此 `availableModels` 中的項目（如 `"opus"`）即使 Opus 版本對應到 ARN 時仍會繼續匹配。當在受管設定中設定 `enforceAvailableModels` 時，強制執行的預設值會從[最高優先順序受管來源](/docs/zh-TW/server-managed-settings#settings-precedence)透過 `modelOverrides` 解析。管理員的對應（例如固定到推論設定檔 ARN 的版本）會在強制執行的預設值中受到尊重。來自使用者或專案設定的覆蓋不會影響它。

760 756

761{/* min-version: 2.1.200 */}當 `availableModels` 在[受管設定](/zh-TW/settings#settings-files)中設定時，只有來自該受管來源的 `modelOverrides` 適用於直接透過 `--model` 或上述環境變數傳遞的 Anthropic 模型 ID。Claude Code 會忽略來自使用者或專案設定的這些 ID 的覆蓋，並且永遠不會透過來自任何設定來源的 `modelOverrides` 解析受管清單排除的 ID。此受管來源限制需要 Claude Code v2.1.200 或更新版本。請參閱[限制模型選擇](#restrict-model-selection)以瞭解如何處理被阻止的 ID。757當 `availableModels` 在[受管設定](/docs/zh-TW/settings#settings-files)中設定時，只有來自該受管來源的 `modelOverrides` 適用於直接透過 `--model` 或上述環境變數傳遞的 Anthropic 模型 ID。Claude Code 會忽略來自使用者或專案設定的這些 ID 的覆蓋，並且永遠不會透過來自任何設定來源的 `modelOverrides` 解析受管清單排除的 ID。此受管來源限制需要 Claude Code v2.1.200 或更新版本。請參閱[限制模型選擇](#restrict-model-selection)以瞭解如何處理被阻止的 ID。

762 758

763<h3 id="prompt-caching-configuration">759<h3 id="prompt-caching-configuration">

764 Prompt caching 配置760 Prompt caching 配置

765</h3>761</h3>

766 762

767Claude Code 自動使用 [prompt caching](/zh-TW/prompt-caching) 來優化效能並降低成本。您可以全域禁用 prompt caching 或針對特定模型層級禁用：763Claude Code 自動使用 [prompt caching](/docs/zh-TW/prompt-caching) 來優化效能並降低成本。您可以全域禁用 prompt caching 或針對特定模型層級禁用：

768 764

769| 環境變數 | 描述 |765| 環境變數 | 描述 |

770| ------------------------------- | ------------------------------------------ |766| ------------------------------- | ------------------------------------------ |

776 772

777若要變更快取 TTL 或瞭解什麼會觸發快取未命中，請參閱 [Claude Code 如何使用 prompt caching](/zh-TW/prompt-caching)。773若要變更快取 TTL 或瞭解什麼會觸發快取未命中，請參閱 [Claude Code 如何使用 prompt caching](/docs/zh-TW/prompt-caching)。

monitoring-usage.md +26 −26

Details

47 管理員配置47 管理員配置

48</h2>48</h2>

49 49

50管理員可以透過[受管設定檔](/zh-TW/settings#settings-files)為所有使用者配置 OpenTelemetry 設定。這允許在整個組織中集中控制遙測設定。請參閱[設定優先順序](/zh-TW/settings#settings-precedence)以了解有關如何應用設定的更多資訊。50管理員可以透過[受管設定檔](/docs/zh-TW/settings#settings-files)為所有使用者配置 OpenTelemetry 設定。這允許在整個組織中集中控制遙測設定。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)以了解有關如何應用設定的更多資訊。

51 51

52受管設定配置範例：52受管設定配置範例：

53 53

93| `OTEL_METRIC_EXPORT_INTERVAL` | 匯出間隔（毫秒）（預設：60000） | `5000`、`60000` |93| `OTEL_METRIC_EXPORT_INTERVAL` | 匯出間隔（毫秒）（預設：60000） | `5000`、`60000` |

94| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |94| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |

95| `OTEL_LOG_USER_PROMPTS` | 啟用使用者提示內容的日誌記錄（預設：停用） | `1` 以啟用 |95| `OTEL_LOG_USER_PROMPTS` | 啟用使用者提示內容的日誌記錄（預設：停用） | `1` 以啟用 |

96| `OTEL_LOG_ASSISTANT_RESPONSES` | 啟用在 `assistant_response` 事件上記錄助手回應文字的日誌（預設：停用）。未設定時，會回退到 `OTEL_LOG_USER_PROMPTS` 的值。{/* min-version: 2.1.193 */}需要 Claude Code v2.1.193 或更新版本 | `1` 以啟用，`0` 以保持編輯 |96| `OTEL_LOG_ASSISTANT_RESPONSES` | 啟用在 `assistant_response` 事件上記錄助手回應文字的日誌（預設：停用）。未設定時，會回退到 `OTEL_LOG_USER_PROMPTS` 的值。需要 Claude Code v2.1.193 或更新版本 | `1` 以啟用，`0` 以保持編輯 |

97| `OTEL_LOG_TOOL_DETAILS` | 啟用在工具事件和追蹤跨度屬性中記錄工具參數和輸入引數的日誌：Bash 命令、MCP 伺服器和工具名稱、Skill 名稱、使用者撰寫的工作流程名稱和工具輸入。也在 `user_prompt` 事件上啟用自訂、plugin 和 MCP 命令名稱（預設：停用） | `1` 以啟用 |97| `OTEL_LOG_TOOL_DETAILS` | 啟用在工具事件和追蹤跨度屬性中記錄工具參數和輸入引數的日誌：Bash 命令、MCP 伺服器和工具名稱、Skill 名稱、使用者撰寫的工作流程名稱和工具輸入。也在 `user_prompt` 事件上啟用自訂、plugin 和 MCP 命令名稱（預設：停用） | `1` 以啟用 |

98| `OTEL_LOG_TOOL_CONTENT` | 啟用在跨度事件中記錄工具輸入和輸出內容的日誌（預設：停用）。需要[追蹤](#traces-beta)。內容在 60 KB 處截斷 | `1` 以啟用 |98| `OTEL_LOG_TOOL_CONTENT` | 啟用在跨度事件中記錄工具輸入和輸出內容的日誌（預設：停用）。需要[追蹤](#traces-beta)。內容在 60 KB 處截斷 | `1` 以啟用 |

99| `OTEL_LOG_RAW_API_BODIES` | 將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（預設：停用）。主體包括整個對話歷史記錄。啟用此選項意味著同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 會揭露的所有內容 | `1` 用於在 60 KB 處截斷的內聯主體，或 `file:<dir>` 用於磁碟上未截斷的主體，事件中有 `body_ref` 指標 |99| `OTEL_LOG_RAW_API_BODIES` | 將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（預設：停用）。主體包括整個對話歷史記錄。啟用此選項意味著同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 會揭露的所有內容 | `1` 用於在 60 KB 處截斷的內聯主體，或 `file:<dir>` 用於磁碟上未截斷的主體，事件中有 `body_ref` 指標 |

108 108

109| 協議 | 用戶端憑證變數 | 信任收集器的 CA |109| 協議 | 用戶端憑證變數 | 信任收集器的 CA |

110| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |110| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |

111| `http/protobuf`、`http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和可選的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。請參閱[網路配置](/zh-TW/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |111| `http/protobuf`、`http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和可選的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。請參閱[網路配置](/docs/zh-TW/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |

112| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或每個訊號的變體，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以針對每個訊號使用不同的憑證 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |112| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或每個訊號的變體，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以針對每個訊號使用不同的憑證 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |

113 113

114對於 `grpc`，OpenTelemetry SDK 直接讀取標準 OTLP 變數，因此設定每個訊號指標變數的現有配置會繼續運作。114對於 `grpc`，OpenTelemetry SDK 直接讀取標準 OTLP 變數，因此設定每個訊號指標變數的現有配置會繼續運作。

314如果協助程式失敗或列印不符合這些要求的輸出，Claude Code 會在以下位置報告錯誤：314如果協助程式失敗或列印不符合這些要求的輸出，Claude Code 會在以下位置報告錯誤：

315 315

316* `/status` 輸出316* `/status` 輸出

317* 使用 [`--debug`](/zh-TW/cli-reference#cli-flags) 執行或在工作階段中執行 `/debug` 後的除錯日誌317* 使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 執行或在工作階段中執行 `/debug` 後的除錯日誌

318* stderr，在以 `-p` 啟動的非互動式工作階段中318* stderr，在以 `-p` 啟動的非互動式工作階段中

319 319

320<h4 id="refresh-behavior">320<h4 id="refresh-behavior">

442| Keys from `OTEL_RESOURCE_ATTRIBUTES` | 您設定的自訂屬性，例如 `department` 或 `team.id`。詳見[多團隊組織支援](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（預設：true） |442| Keys from `OTEL_RESOURCE_ATTRIBUTES` | 您設定的自訂屬性，例如 `department` 或 `team.id`。詳見[多團隊組織支援](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（預設：true） |

443 443

444當 Claude Code 登入到 [Claude apps gateway](/zh-TW/claude-apps-gateway) 時，CLI 會使用來自閘道工作階段的已驗證身份戳記匯出：`user.id` 是 IdP 主體而不是匿名安裝識別碼，`user.email` 是已登入的電子郵件，`user.groups` 以逗號分隔的字串形式帶有 IdP 群組成員資格。每個匯出還帶有 `identity.source: gateway-oidc`。閘道身份最後應用，因此透過 `OTEL_RESOURCE_ATTRIBUTES` 設定的 `user.*` 和 `identity.*` 鍵在閘道工作階段上被忽略。444當 Claude Code 登入到 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 時，CLI 會使用來自閘道工作階段的已驗證身份戳記匯出：`user.id` 是 IdP 主體而不是匿名安裝識別碼，`user.email` 是已登入的電子郵件，`user.groups` 以逗號分隔的字串形式帶有 IdP 群組成員資格。每個匯出還帶有 `identity.source: gateway-oidc`。閘道身份最後應用，因此透過 `OTEL_RESOURCE_ATTRIBUTES` 設定的 `user.*` 和 `identity.*` 鍵在閘道工作階段上被忽略。

445 445

446事件另外包含以下屬性。這些永遠不會附加到指標，因為它們會導致無限制的基數：446事件另外包含以下屬性。這些永遠不會附加到指標，因為它們會導致無限制的基數：

447 447

448* `prompt.id`：UUID 將使用者提示與所有後續事件關聯到下一個提示。請參閱[事件關聯屬性](#event-correlation-attributes)。448* `prompt.id`：UUID 將使用者提示與所有後續事件關聯到下一個提示。請參閱[事件關聯屬性](#event-correlation-attributes)。

449* `workspace.host_paths`：在桌面應用程式中選擇的主機工作區目錄，作為字串陣列449* `workspace.host_paths`：在桌面應用程式中選擇的主機工作區目錄，作為字串陣列

450* `workflow.run_id`：執行識別碼，前綴為 `wf_`，在 API 和工具事件上發出，由屬於 [Workflow](/zh-TW/workflows) 工具執行的代理發出。按一個 `workflow.run_id` 篩選事件會重建該執行的 API 請求和工具結果。識別碼涵蓋工作流程指令碼衍生的代理以及這些代理依次衍生的任何代理，例如 skill 叫用。它符合在 Workflow 工具結果中報告的執行識別碼。在所有其他事件上不存在。{/* min-version: 2.1.202 */}需要 Claude Code v2.1.202 或更新版本450* `workflow.run_id`：執行識別碼，前綴為 `wf_`，在 API 和工具事件上發出，由屬於 [Workflow](/docs/zh-TW/workflows) 工具執行的代理發出。按一個 `workflow.run_id` 篩選事件會重建該執行的 API 請求和工具結果。識別碼涵蓋工作流程指令碼衍生的代理以及這些代理依次衍生的任何代理，例如 skill 叫用。它符合在 Workflow 工具結果中報告的執行識別碼。在所有其他事件上不存在。需要 Claude Code v2.1.202 或更新版本

451* `workflow.name`：工作流程的名稱，其指令碼的 `meta.name`，與 `workflow.run_id` 一起發出。內建工作流程名稱在執行未修改的內建指令碼時按原樣出現。使用者撰寫的名稱（包括內建指令碼的編輯副本）被替換為 `custom`，除非設定 `OTEL_LOG_TOOL_DETAILS=1`。{/* min-version: 2.1.202 */}需要 Claude Code v2.1.202 或更新版本451* `workflow.name`：工作流程的名稱，其指令碼的 `meta.name`，與 `workflow.run_id` 一起發出。內建工作流程名稱在執行未修改的內建指令碼時按原樣出現。使用者撰寫的名稱（包括內建指令碼的編輯副本）被替換為 `custom`，除非設定 `OTEL_LOG_TOOL_DETAILS=1`。需要 Claude Code v2.1.202 或更新版本

452 452

453<h3 id="metrics">453<h3 id="metrics">

454 指標454 指標

528* `model`：模型識別碼（例如，"claude-sonnet-5"）528* `model`：模型識別碼（例如，"claude-sonnet-5"）

529* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一529* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

530* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在530* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

531* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。531* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。

532* `agent.name`：發出請求的子代理類型。內建代理名稱和官方市場 plugin 的代理按原樣出現。其他使用者定義的代理名稱被替換為 `"custom"`。當請求不是由命名的子代理類型發出時不存在。532* `agent.name`：發出請求的子代理類型。內建代理名稱和官方市場 plugin 的代理按原樣出現。其他使用者定義的代理名稱被替換為 `"custom"`。當請求不是由命名的子代理類型發出時不存在。

533* `skill.name`：對請求有效的 Skill，由 Skill 工具、`/` 命令設定或由衍生的子代理繼承。內建、捆綁、使用者定義和官方市場 plugin skill 名稱按原樣出現。第三方 plugin skill 名稱被替換為 `"third-party"`。當沒有 skill 有效時不存在。533* `skill.name`：對請求有效的 Skill，由 Skill 工具、`/` 命令設定或由衍生的子代理繼承。內建、捆綁、使用者定義和官方市場 plugin skill 名稱按原樣出現。第三方 plugin skill 名稱被替換為 `"third-party"`。當沒有 skill 有效時不存在。

534* `plugin.name`：當活躍 skill 或子代理由 plugin 提供時的擁有 plugin。官方市場 plugin 名稱按原樣出現。第三方 plugin 名稱被替換為 `"third-party"`。當 skill 和子代理都沒有擁有 plugin 時不存在。534* `plugin.name`：當活躍 skill 或子代理由 plugin 提供時的擁有 plugin。官方市場 plugin 名稱按原樣出現。第三方 plugin 名稱被替換為 `"third-party"`。當 skill 和子代理都沒有擁有 plugin 時不存在。

549* `model`：模型識別碼（例如，"claude-sonnet-5"）549* `model`：模型識別碼（例如，"claude-sonnet-5"）

550* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一550* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

551* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在551* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

552* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)。詳見[成本計數器](#cost-counter)以了解詳情。552* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。詳見[成本計數器](#cost-counter)以了解詳情。

553* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。553* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。

554 554

555<h4 id="code-edit-tool-decision-counter">555<h4 id="code-edit-tool-decision-counter">

622 助手回應事件622 助手回應事件

623</h4>623</h4>

624 624

625在每個 API 請求傳回來自模型的文字內容後記錄。僅包含回應的文字區塊；思考區塊和工具使用區塊被排除。{/* min-version: 2.1.193 */}需要 Claude Code v2.1.193 或更新版本。625在每個 API 請求傳回來自模型的文字內容後記錄。僅包含回應的文字區塊；思考區塊和工具使用區塊被排除。需要 Claude Code v2.1.193 或更新版本。

626 626

627**事件名稱**：`claude_code.assistant_response`627**事件名稱**：`claude_code.assistant_response`

628 628

695* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。695* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。

696* `speed`：`"fast"` 或 `"normal"`，指示是否啟用了快速模式696* `speed`：`"fast"` 或 `"normal"`，指示是否啟用了快速模式

697* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱697* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱

698* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。698* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。

699* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。699* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。

700 700

701<h4 id="api-error-event">701<h4 id="api-error-event">

720* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。720* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。

721* `speed`：`"fast"` 或 `"normal"`，指示是否啟用了快速模式721* `speed`：`"fast"` 或 `"normal"`，指示是否啟用了快速模式

722* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱722* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱

723* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)。當模型不支援努力時不存在。723* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。當模型不支援努力時不存在。

724* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。724* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。

725 725

726<h4 id="api-refusal-event">726<h4 id="api-refusal-event">

740* `model`：來自請求的模型識別碼740* `model`：來自請求的模型識別碼

741* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。741* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。

742* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱。詳見[`api_request`](#api-request-event)以了解定義。742* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱。詳見[`api_request`](#api-request-event)以了解定義。

743* `speed`：當[快速模式](/zh-TW/fast-mode)啟用時為 `"fast"`，或 `"normal"`743* `speed`：當[快速模式](/docs/zh-TW/fast-mode)啟用時為 `"fast"`，或 `"normal"`

744* `attempt`：重試嘗試編號。第一次嘗試是 `1`。744* `attempt`：重試嘗試編號。第一次嘗試是 `1`。

745* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)。當模型不支援努力時不存在。745* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。當模型不支援努力時不存在。

746* `server_fallback_hop`：當 API 的伺服器端模型後備已在不同模型上重試此拒絕時為 `true`，因此使用者沒有看到此特定拒絕。當請求以拒絕結束時為 `false`。單個轉換可以發出 `true` hop 事件和稍後的 `false` 最終事件，當後備模型也拒絕時。746* `server_fallback_hop`：當 API 的伺服器端模型後備已在不同模型上重試此拒絕時為 `true`，因此使用者沒有看到此特定拒絕。當請求以拒絕結束時為 `false`。單個轉換可以發出 `true` hop 事件和稍後的 `false` 最終事件，當後備模型也拒絕時。

747* `has_category`：當 API 回應帶有 `stop_details.category` 為 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 時為 `true`。當回應沒有類別或值在該集合之外時為 `false`。當 `server_fallback_hop` 為 `true` 時不存在，因為 hop 區塊不帶 `stop_details`。747* `has_category`：當 API 回應帶有 `stop_details.category` 為 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 時為 `true`。當回應沒有類別或值在該集合之外時為 `false`。當 `server_fallback_hop` 為 `true` 時不存在，因為 hop 區塊不帶 `stop_details`。

748* `has_explanation`：當 API 回應帶有 `stop_details.explanation` 時為 `true`，否則為 `false`。當 `server_fallback_hop` 為 `true` 時不存在。748* `has_explanation`：當 API 回應帶有 `stop_details.explanation` 時為 `true`，否則為 `false`。當 `server_fallback_hop` 為 `true` 時不存在。

945* `plugin_id_hash`：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算整個環境中載入了多少個不同的第三方 plugin，而無需記錄其名稱945* `plugin_id_hash`：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算整個環境中載入了多少個不同的第三方 plugin，而無需記錄其名稱

946* `has_hooks`：plugin 是否貢獻 hooks946* `has_hooks`：plugin 是否貢獻 hooks

947* `has_mcp`：plugin 是否貢獻 MCP 伺服器947* `has_mcp`：plugin 是否貢獻 MCP 伺服器

948* `host_owned_mcp`：當 SDK 主機管理此 plugin 的 MCP 連線且 Claude Code 跳過讀取 plugin 的 MCP 伺服器配置時為 `true`，否則為 `false`。{/* min-version: 2.1.172 */}需要 Claude Code v2.1.172 或更新版本948* `host_owned_mcp`：當 SDK 主機管理此 plugin 的 MCP 連線且 Claude Code 跳過讀取 plugin 的 MCP 伺服器配置時為 `true`，否則為 `false`。需要 Claude Code v2.1.172 或更新版本

949* `skill_path_count`：plugin 宣告的 skill 目錄數949* `skill_path_count`：plugin 宣告的 skill 目錄數

950* `command_path_count`：plugin 宣告的命令目錄數950* `command_path_count`：plugin 宣告的命令目錄數

951* `agent_path_count`：plugin 宣告的代理目錄數951* `agent_path_count`：plugin 宣告的代理目錄數

952* `safe_mode`：當工作階段以 [`--safe-mode`](/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。在安全模式下，此事件僅報告配置的清單；plugin 的命令、skill、hooks 和 MCP 伺服器不會載入。{/* min-version: 2.1.169 */}需要 Claude Code v2.1.169 或更新版本952* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。在安全模式下，此事件僅報告配置的清單；plugin 的命令、skill、hooks 和 MCP 伺服器不會載入。需要 Claude Code v2.1.169 或更新版本

953 953

954<h4 id="skill-activated-event">954<h4 id="skill-activated-event">

955 Skill 已啟動事件955 Skill 已啟動事件

1027* `hook_event`：hook 事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`1027* `hook_event`：hook 事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`

1028* `hook_type`：hook 實作類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`1028* `hook_type`：hook 實作類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`

1029* `hook_source`：hook 的定義位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`1029* `hook_source`：hook 的定義位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`

1030* `safe_mode`：當工作階段以 [`--safe-mode`](/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。{/* min-version: 2.1.169 */}需要 Claude Code v2.1.169 或更新版本1030* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1031* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：hook 配置中的匹配器字串（如果已設定）1031* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：hook 配置中的匹配器字串（如果已設定）

1032* `plugin.name`（當 `hook_source` 是 `"pluginHook"` 時）：貢獻 plugin 的名稱。對於官方市場和內建捆綁之外的 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`1032* `plugin.name`（當 `hook_source` 是 `"pluginHook"` 時）：貢獻 plugin 的名稱。對於官方市場和內建捆綁之外的 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`

1033* `plugin_id_hash`（當 `hook_source` 是 `"pluginHook"` 時）：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算不同的貢獻 plugin，而無需記錄其名稱1033* `plugin_id_hash`（當 `hook_source` 是 `"pluginHook"` 時）：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算不同的貢獻 plugin，而無需記錄其名稱

1051* `num_hooks`：匹配 hook 命令的數量1051* `num_hooks`：匹配 hook 命令的數量

1052* `managed_only`：當僅允許受管原則 hook 時為 `"true"`1052* `managed_only`：當僅允許受管原則 hook 時為 `"true"`

1053* `hook_source`：`"policySettings"` 或 `"merged"`1053* `hook_source`：`"policySettings"` 或 `"merged"`

1054* `safe_mode`：當工作階段以 [`--safe-mode`](/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。{/* min-version: 2.1.169 */}需要 Claude Code v2.1.169 或更新版本1054* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1055* `hook_definitions`：JSON 序列化的 hook 配置。僅當詳細 beta 追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 都啟用時才包含1055* `hook_definitions`：JSON 序列化的 hook 配置。僅當詳細 beta 追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 都啟用時才包含

1056 1056

1057<h4 id="hook-execution-complete-event">1057<h4 id="hook-execution-complete-event">

1078* `total_duration_ms`：所有匹配 hook 的牆上時間持續時間1078* `total_duration_ms`：所有匹配 hook 的牆上時間持續時間

1079* `managed_only`：當僅允許受管原則 hook 時為 `"true"`1079* `managed_only`：當僅允許受管原則 hook 時為 `"true"`

1080* `hook_source`：`"policySettings"` 或 `"merged"`1080* `hook_source`：`"policySettings"` 或 `"merged"`

1081* `safe_mode`：當工作階段以 [`--safe-mode`](/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。{/* min-version: 2.1.169 */}需要 Claude Code v2.1.169 或更新版本1081* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1082* `hook_definitions`：JSON 序列化的 hook 配置。僅當詳細 beta 追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 都啟用時才包含1082* `hook_definitions`：JSON 序列化的 hook 配置。僅當詳細 beta 追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 都啟用時才包含

1083 1083

1084<h4 id="hook-plugin-metrics-event">1084<h4 id="hook-plugin-metrics-event">

1119* `pre_tokens`：壓縮前的近似權杖計數1119* `pre_tokens`：壓縮前的近似權杖計數

1120* `post_tokens`：壓縮後的近似權杖計數1120* `post_tokens`：壓縮後的近似權杖計數

1121* `error`：壓縮失敗時的錯誤訊息1121* `error`：壓縮失敗時的錯誤訊息

1122* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可以在內容視窗填滿之前在背景中準備摘要，此屬性記錄 `/compact` 是否重複使用該準備的摘要。`"hit"` 表示它被重複使用；`"miss_custom_instructions"`、`"miss_hook"` 和 `"miss_not_ready"` 給出改為計算新摘要的原因。{/* min-version: 2.1.153 */}需要 Claude Code v2.1.153 或更新版本1122* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可以在內容視窗填滿之前在背景中準備摘要，此屬性記錄 `/compact` 是否重複使用該準備的摘要。`"hit"` 表示它被重複使用；`"miss_custom_instructions"`、`"miss_hook"` 和 `"miss_not_ready"` 給出改為計算新摘要的原因。需要 Claude Code v2.1.153 或更新版本

1123 1123

1124<h4 id="feedback-survey-event">1124<h4 id="feedback-survey-event">

1125 回饋調查事件1125 回饋調查事件

1126</h4>1126</h4>

1127 1127

1128當顯示或回答工作階段品質調查時記錄。詳見[工作階段品質調查](/zh-TW/data-usage#session-quality-surveys)以了解調查收集的內容以及如何控制它們。1128當顯示或回答工作階段品質調查時記錄。詳見[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys)以了解調查收集的內容以及如何控制它們。

1129 1129

1130**事件名稱**：`claude_code.feedback_survey`1130**事件名稱**：`claude_code.feedback_survey`

1131 1131

1139* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件1139* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件

1140* `survey_type`：哪個調查產生了事件。`"session"` 是「Claude 表現如何？」評分提示1140* `survey_type`：哪個調查產生了事件。`"session"` 是「Claude 表現如何？」評分提示

1141* `response`：使用者在 `responded` 事件上的選擇1141* `response`：使用者在 `responded` 事件上的選擇

1142* `enabled_via_override`：當設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/zh-TW/env-vars) 時為 `true`。作為布林值而非字串發出。存在於 `session` 調查事件上。篩選此屬性以確認覆蓋在整個環境中應用1142* `enabled_via_override`：當設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。作為布林值而非字串發出。存在於 `session` 調查事件上。篩選此屬性以確認覆蓋在整個環境中應用

1143 1143

1144<h2 id="interpret-metrics-and-events-data">1144<h2 id="interpret-metrics-and-events-data">

1145 解釋指標和事件資料1145 解釋指標和事件資料

1219 將屬性操作歸因於使用者1219 將屬性操作歸因於使用者

1220</h3>1220</h3>

1221 1221

1222每個事件上的[標準屬性](#standard-attributes)包括已驗證使用者的身份：使用 Claude 帳戶登入時的 `user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`，加上 `user.id` 和每個工作階段的 `session.id`。`user.id` 是安裝範圍的識別碼，除了在 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上，其中它是來自閘道簽發令牌的 IdP 主體。1222每個事件上的[標準屬性](#standard-attributes)包括已驗證使用者的身份：使用 Claude 帳戶登入時的 `user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`，加上 `user.id` 和每個工作階段的 `session.id`。`user.id` 是安裝範圍的識別碼，除了在 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段上，其中它是來自閘道簽發令牌的 IdP 主體。

1223 1223

1224MCP 工具呼叫、Bash 命令和檔案編輯因此歸因於啟動工作階段的開發人員。Claude Code 不在單獨的服務帳戶下運作；每個事件上記錄的身份是開發人員自己的 Claude 帳戶，或開發人員在 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上的 IdP 身份。1224MCP 工具呼叫、Bash 命令和檔案編輯因此歸因於啟動工作階段的開發人員。Claude Code 不在單獨的服務帳戶下運作；每個事件上記錄的身份是開發人員自己的 Claude 帳戶，或開發人員在 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段上的 IdP 身份。

1225 1225

1226當 Claude Code 使用直接 API 金鑰進行身份驗證，或針對 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 進行身份驗證時，工作階段中沒有 Claude 帳戶，僅填充 `user.id` 和 `session.id`。在這些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自行附加使用者身份，透過[受管設定](#administrator-configuration)檔案或啟動包裝器按使用者設定。Claude apps gateway 工作階段不需要任何這些：CLI 會自動標記 IdP 身份，如[標準屬性](#standard-attributes)中所述。1226當 Claude Code 使用直接 API 金鑰進行身份驗證，或針對 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 進行身份驗證時，工作階段中沒有 Claude 帳戶，僅填充 `user.id` 和 `session.id`。在這些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自行附加使用者身份，透過[受管設定](#administrator-configuration)檔案或啟動包裝器按使用者設定。Claude apps gateway 工作階段不需要任何這些：CLI 會自動標記 IdP 身份，如[標準屬性](#standard-attributes)中所述。

1227 1227

1341 安全性和隱私1341 安全性和隱私

1342</h2>1342</h2>

1343 1343

1344* OpenTelemetry 匯出到您的後端是選擇加入的，需要明確配置。如需了解 Anthropic 的獨立營運遙測以及如何停用它，請參閱[資料使用](/zh-TW/data-usage#telemetry-services)1344* OpenTelemetry 匯出到您的後端是選擇加入的，需要明確配置。如需了解 Anthropic 的獨立營運遙測以及如何停用它，請參閱[資料使用](/docs/zh-TW/data-usage#telemetry-services)

1345* 原始檔案內容和程式碼片段不包含在指標或事件中。追蹤跨度是單獨的資料路徑：請參閱下面的 `OTEL_LOG_TOOL_CONTENT` 項目1345* 原始檔案內容和程式碼片段不包含在指標或事件中。追蹤跨度是單獨的資料路徑：請參閱下面的 `OTEL_LOG_TOOL_CONTENT` 項目

1346* 透過 OAuth 驗證時，`user.email` 包含在遙測屬性中。如果這對您的組織是個問題，請與您的遙測後端合作以篩選或編輯此欄位1346* 透過 OAuth 驗證時，`user.email` 包含在遙測屬性中。如果這對您的組織是個問題，請與您的遙測後端合作以篩選或編輯此欄位

1347* 預設不收集使用者提示內容。僅記錄提示長度。若要包含提示內容，請設定 `OTEL_LOG_USER_PROMPTS=1`1347* 預設不收集使用者提示內容。僅記錄提示長度。若要包含提示內容，請設定 `OTEL_LOG_USER_PROMPTS=1`

network-config.md +15 −15

Details

9Claude Code 透過環境變數支援各種企業網路和安全設定。這包括透過公司代理伺服器路由流量、信任自訂憑證授權單位 (CA)，以及使用相互傳輸層安全性 (mTLS) 憑證進行驗證以增強安全性。9Claude Code 透過環境變數支援各種企業網路和安全設定。這包括透過公司代理伺服器路由流量、信任自訂憑證授權單位 (CA)，以及使用相互傳輸層安全性 (mTLS) 憑證進行驗證以增強安全性。

10 10

11<Note>11<Note>

~~12 本頁面顯示的所有環境變數也可以在 [`settings.json`](/zh-TW/settings) 中設定。~~12 本頁面顯示的所有環境變數也可以在 [`settings.json`](/docs/zh-TW/settings) 中設定。

13</Note>13</Note>

14 14

15<h2 id="proxy-configuration">15<h2 id="proxy-configuration">

126| `mcp-proxy.anthropic.com` | [來自 claude.ai 的 MCP 連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)，包括組織管理員設定的連接器。連接器流量會透過此代理路由；對於 claude.ai 驗證的使用者，連接器預設為啟用。若要停用，請設定 [`ENABLE_CLAUDEAI_MCP_SERVERS=false`](/zh-TW/env-vars) 或 [`disableClaudeAiConnectors`](/zh-TW/settings#available-settings) 設定 |126| `mcp-proxy.anthropic.com` | [來自 claude.ai 的 MCP 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)，包括組織管理員設定的連接器。連接器流量會透過此代理路由；對於 claude.ai 驗證的使用者，連接器預設為啟用。若要停用，請設定 [`ENABLE_CLAUDEAI_MCP_SERVERS=false`](/docs/zh-TW/env-vars) 或 [`disableClaudeAiConnectors`](/docs/zh-TW/settings#available-settings) 設定 |

128| `storage.googleapis.com` | 在 `/plugin` 中顯示的安裝計數和外掛程式中繼資料。已簽署的[成品](/zh-TW/artifacts)上傳會先嘗試此主機；當 `api.anthropic.com` 被阻止時，發佈會回退到 `api.anthropic.com` |128| `storage.googleapis.com` | 在 `/plugin` 中顯示的安裝計數和外掛程式中繼資料。已簽署的[成品](/docs/zh-TW/artifacts)上傳會先嘗試此主機；當 `api.anthropic.com` 被阻止時，發佈會回退到 `api.anthropic.com` |

129| `storage.googleapis.com` | {/* max-version: 2.1.115 */}2.1.116 版本之前的原生安裝程式和原生自動更新程式 |129| `storage.googleapis.com` | 2.1.116 版本之前的原生安裝程式和原生自動更新程式 |

133 133

134如果您透過 npm 安裝 Claude Code 或管理自己的二進位分發，終端使用者不需要原生安裝程式，自動更新程式不需要使用 `downloads.claude.ai`。表格中的其他用途無論安裝方法為何都適用。134如果您透過 npm 安裝 Claude Code 或管理自己的二進位分發，終端使用者不需要原生安裝程式，自動更新程式不需要使用 `downloads.claude.ai`。表格中的其他用途無論安裝方法為何都適用。

135 135

136Claude Code 預設也會傳送選用的操作遙測，您可以使用環境變數停用此功能。請參閱[遙測服務](/zh-TW/data-usage#telemetry-services)以了解如何在完成允許清單之前停用它。136Claude Code 預設也會傳送選用的操作遙測，您可以使用環境變數停用此功能。請參閱[遙測服務](/docs/zh-TW/data-usage#telemetry-services)以了解如何在完成允許清單之前停用它。

137 137

138使用 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 或已登入的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)工作階段時，模型流量和驗證會傳送到您的提供者或閘道，而不是 `api.anthropic.com`、`claude.ai` 或 `platform.claude.com`。WebFetch 工具仍會呼叫 `api.anthropic.com` 進行其[網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，除非您在[設定](/zh-TW/settings)中設定 `skipWebFetchPreflight: true`。138使用 [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)工作階段時，模型流量和驗證會傳送到您的提供者或閘道，而不是 `api.anthropic.com`、`claude.ai` 或 `platform.claude.com`。WebFetch 工具仍會呼叫 `api.anthropic.com` 進行其[網域安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check)，除非您在[設定](/docs/zh-TW/settings)中設定 `skipWebFetchPreflight: true`。

139 139

140[Claude Code on the web](/zh-TW/claude-code-on-the-web) 和 [Code Review](/zh-TW/code-review) 從 Anthropic 管理的基礎設施連線到您的儲存庫。如果您的 GitHub Enterprise Cloud 組織按 IP 位址限制存取，請啟用[已安裝 GitHub Apps 的 IP 允許清單繼承](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)。Claude GitHub App 會註冊其 IP 範圍，因此啟用此設定可允許存取而無需手動設定。若要[手動將範圍新增到允許清單](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)，或設定其他防火牆，請參閱 [Anthropic API IP 位址](https://platform.claude.com/docs/en/api/ip-addresses)。140[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 和 [Code Review](/docs/zh-TW/code-review) 從 Anthropic 管理的基礎設施連線到您的儲存庫。如果您的 GitHub Enterprise Cloud 組織按 IP 位址限制存取，請啟用[已安裝 GitHub Apps 的 IP 允許清單繼承](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)。Claude GitHub App 會註冊其 IP 範圍，因此啟用此設定可允許存取而無需手動設定。若要[手動將範圍新增到允許清單](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)，或設定其他防火牆，請參閱 [Anthropic API IP 位址](https://platform.claude.com/docs/en/api/ip-addresses)。

141 141

142對於防火牆後的自託管 [GitHub Enterprise Server](/zh-TW/github-enterprise-server) 執行個體，請將相同的 [Anthropic API IP 位址](https://platform.claude.com/docs/en/api/ip-addresses) 列入允許清單，以便 Anthropic 基礎設施可以連線到您的 GHES 主機以複製儲存庫並發佈審查評論。142對於防火牆後的自託管 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體，請將相同的 [Anthropic API IP 位址](https://platform.claude.com/docs/en/api/ip-addresses) 列入允許清單，以便 Anthropic 基礎設施可以連線到您的 GHES 主機以複製儲存庫並發佈審查評論。

143 143

144<h3 id="desktop-and-claude-ai">144<h3 id="desktop-and-claude-ai">

145 Desktop 和 claude.ai145 Desktop 和 claude.ai

146</h3>146</h3>

147 147

148前面的表格主要涵蓋獨立 CLI。Claude Desktop 應用程式和瀏覽器中的 claude.ai 會從其他 Anthropic CDN 主機載入其應用程式代碼，包括 `assets-proxy.anthropic.com`。允許 `claude.ai` 但阻止這些主機會產生空白頁面而不是錯誤。請參閱 Desktop 頁面上的[網路存取需求](/zh-TW/desktop#network-access-requirements)。148前面的表格主要涵蓋獨立 CLI。Claude Desktop 應用程式和瀏覽器中的 claude.ai 會從其他 Anthropic CDN 主機載入其應用程式代碼，包括 `assets-proxy.anthropic.com`。允許 `claude.ai` 但阻止這些主機會產生空白頁面而不是錯誤。請參閱 Desktop 頁面上的[網路存取需求](/docs/zh-TW/desktop#network-access-requirements)。

149 149

150<h2 id="additional-resources">150<h2 id="additional-resources">

151 其他資源151 其他資源

152</h2>152</h2>

153 153

154* [Claude Code 設定](/zh-TW/settings)154* [Claude Code 設定](/docs/zh-TW/settings)

155* [環境變數參考](/zh-TW/env-vars)155* [環境變數參考](/docs/zh-TW/env-vars)

156* [疑難排解指南](/zh-TW/troubleshooting)156* [疑難排解指南](/docs/zh-TW/troubleshooting)

output-styles.md +15 −15

Details

10 10

11自訂輸出樣式將您的指令添加到系統提示，並讓您選擇是否保留 Claude Code 的內建軟體工程指令。當您改變 Claude 的溝通方式但仍在編碼時（例如始終用圖表回答），請保留它們。當 Claude 根本不進行軟體工程時（例如寫作助手或數據分析師），請省略它們。11自訂輸出樣式將您的指令添加到系統提示，並讓您選擇是否保留 Claude Code 的內建軟體工程指令。當您改變 Claude 的溝通方式但仍在編碼時（例如始終用圖表回答），請保留它們。當 Claude 根本不進行軟體工程時（例如寫作助手或數據分析師），請省略它們。

12 12

~~13有關您的專案、慣例或程式碼庫的說明，請改用 [CLAUDE.md](/zh-TW/memory)。~~13有關您的專案、慣例或程式碼庫的說明，請改用 [CLAUDE.md](/docs/zh-TW/memory)。

14 14

15<h2 id="built-in-output-styles">15<h2 id="built-in-output-styles">

16 內建輸出樣式16 內建輸出樣式

20 20

21還有三種額外的內建輸出樣式：21還有三種額外的內建輸出樣式：

22 22

23* **Proactive**：Claude 立即執行，做出合理的假設而不是暫停進行例行決策，並偏好行動而非規劃。這比[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)提供更強的自主執行指導，且無需改變您的權限模式，因此您在工具運行前仍會看到權限提示。23* **Proactive**：Claude 立即執行，做出合理的假設而不是暫停進行例行決策，並偏好行動而非規劃。這比[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)提供更強的自主執行指導，且無需改變您的權限模式，因此您在工具運行前仍會看到權限提示。

24 24

25* **Explanatory**：在幫助您完成軟體工程任務的同時提供教育性的「Insights」。幫助您理解實現選擇和程式碼庫模式。25* **Explanatory**：在幫助您完成軟體工程任務的同時提供教育性的「Insights」。幫助您理解實現選擇和程式碼庫模式。

26 26

30 變更您的輸出樣式30 變更您的輸出樣式

31</h2>31</h2>

32 32

~~33執行 `/config` 並選擇**輸出樣式**以從選單中選擇樣式。您的選擇會儲存到[本地專案層級](/zh-TW/settings)的 `.claude/settings.local.json`。~~33執行 `/config` 並選擇**輸出樣式**以從選單中選擇樣式。您的選擇會儲存到[本地專案層級](/docs/zh-TW/settings)的 `.claude/settings.local.json`。

34 34

~~35<Note>{/* max-version: 2.1.90 */}獨立的 `/output-style` 命令已在 v2.1.73 中棄用，並在 v2.1.91 中移除。請使用 `/config` 或直接編輯 `outputStyle` 設定。</Note>~~35<Note>獨立的 `/output-style` 命令已在 v2.1.73 中棄用，並在 v2.1.91 中移除。請使用 `/config` 或直接編輯 `outputStyle` 設定。</Note>

36 36

37若要在不使用選單的情況下設定樣式，請直接編輯設定檔中的 `outputStyle` 欄位：37若要在不使用選單的情況下設定樣式，請直接編輯設定檔中的 `outputStyle` 欄位：

38 38

42}42}

43```43```

44 44

45輸出樣式是系統提示的一部分，Claude Code 在工作階段開始時會讀取一次。變更會在執行 `/clear` 或新工作階段後生效。請參閱[Claude Code 如何使用 prompt caching](/zh-TW/prompt-caching#changing-output-style)以了解輸出樣式變更對快取的影響。45輸出樣式是系統提示的一部分，Claude Code 在工作階段開始時會讀取一次。變更會在執行 `/clear` 或新工作階段後生效。請參閱[Claude Code 如何使用 prompt caching](/docs/zh-TW/prompt-caching#changing-output-style)以了解輸出樣式變更對快取的影響。

46 46

47<h2 id="create-a-custom-output-style">47<h2 id="create-a-custom-output-style">

48 建立自訂輸出樣式48 建立自訂輸出樣式

56 56

57 * 使用者：`~/.claude/output-styles`57 * 使用者：`~/.claude/output-styles`

58 * 專案：`.claude/output-styles`58 * 專案：`.claude/output-styles`

~~59 * 受管原則：[受管設定目錄](/zh-TW/settings#settings-files)內的 `.claude/output-styles`~~59 * 受管原則：[受管設定目錄](/docs/zh-TW/settings#settings-files)內的 `.claude/output-styles`

60 60

61 專案輸出樣式會從工作目錄和儲存庫根目錄之間的每個 `.claude/output-styles/` 載入。{/* min-version: 2.1.178 */}自 v2.1.178 起，當多個這些巢狀目錄定義同名樣式時，Claude Code 會使用最接近工作目錄的那個。61 專案輸出樣式會從工作目錄和儲存庫根目錄之間的每個 `.claude/output-styles/` 載入。自 v2.1.178 起，當多個這些巢狀目錄定義同名樣式時，Claude Code 會使用最接近工作目錄的那個。

62 </Step>62 </Step>

63 63

64 <Step title="添加 frontmatter 和指令">64 <Step title="添加 frontmatter 和指令">

86 </Step>86 </Step>

87</Steps>87</Steps>

88 88

~~89[Plugins](/zh-TW/plugins-reference) 也可以在 `output-styles/` 目錄中提供輸出樣式。~~89[Plugins](/docs/zh-TW/plugins-reference) 也可以在 `output-styles/` 目錄中提供輸出樣式。

90 90

91<h3 id="frontmatter">91<h3 id="frontmatter">

92 Frontmatter92 Frontmatter

122| 功能 | 工作原理 | 使用時機 |122| 功能 | 工作原理 | 使用時機 |

123| :-------------------------- | :------------------- | :-------------------------- |123| :-------------------------- | :------------------- | :-------------------------- |

129 129

130<h2 id="related-resources">130<h2 id="related-resources">

131 相關資源131 相關資源

132</h2>132</h2>

133 133

134* [Settings](/zh-TW/settings)：`outputStyle` 欄位所在位置以及設定優先順序的工作原理134* [Settings](/docs/zh-TW/settings)：`outputStyle` 欄位所在位置以及設定優先順序的工作原理

135* [Permission modes](/zh-TW/permission-modes)：Proactive 樣式與自動模式的比較方式135* [Permission modes](/docs/zh-TW/permission-modes)：Proactive 樣式與自動模式的比較方式

136* [Plugins](/zh-TW/plugins)：與 skills、hooks 和 agents 一起打包和分發輸出樣式136* [Plugins](/docs/zh-TW/plugins)：與 skills、hooks 和 agents 一起打包和分發輸出樣式

137* [Debug your configuration](/zh-TW/debug-your-config)：診斷為什麼輸出樣式沒有生效137* [Debug your configuration](/docs/zh-TW/debug-your-config)：診斷為什麼輸出樣式沒有生效

permission-modes.md +66 −66

Details

27 27

28在除了 `bypassPermissions` 之外的每種模式中，寫入[受保護的路徑](#protected-paths)永遠不會自動批准，以防止儲存庫狀態和 Claude 自身設定遭到意外損毀。28在除了 `bypassPermissions` 之外的每種模式中，寫入[受保護的路徑](#protected-paths)永遠不會自動批准，以防止儲存庫狀態和 Claude 自身設定遭到意外損毀。

29 29

30模式設定基準。在頂部分層[權限規則](/zh-TW/permissions#manage-permissions)以預先批准或阻止特定工具。拒絕規則、明確詢問規則、[連接器工具上的組織 `ask` 設定](/zh-TW/mcp#organization-controls-on-connector-tools)和 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 標記適用於每種模式，包括 `bypassPermissions`。允許規則在該模式中無效，因為其他所有操作都已經被批准。30模式設定基準。在頂部分層[權限規則](/docs/zh-TW/permissions#manage-permissions)以預先批准或阻止特定工具。拒絕規則、明確詢問規則、[連接器工具上的組織 `ask` 設定](/docs/zh-TW/mcp#organization-controls-on-connector-tools)和 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 標記適用於每種模式，包括 `bypassPermissions`。允許規則在該模式中無效，因為其他所有操作都已經被批准。

31 31

32<h2 id="switch-permission-modes">32<h2 id="switch-permission-modes">

33 切換權限模式33 切換權限模式

37 37

38<Tabs>38<Tabs>

39 <Tab title="CLI">39 <Tab title="CLI">

40 **在工作階段期間**：按 `Shift+Tab` 循環切換 `default` → `acceptEdits` → `plan`。目前模式會顯示在狀態列中。{/* min-version: 2.1.203 */}手動模式（該循環中的 `default`）會顯示灰色的 `⏸ manual mode on` 徽章。在 v2.1.203 之前，狀態列在手動模式中不顯示徽章。40 **在工作階段期間**：按 `Shift+Tab` 循環切換 `default` → `acceptEdits` → `plan`。目前模式會顯示在狀態列中。手動模式（該循環中的 `default`）會顯示灰色的 `⏸ manual mode on` 徽章。在 v2.1.203 之前，狀態列在手動模式中不顯示徽章。

41 41

42 並非每個模式都在預設循環中：42 並非每個模式都在預設循環中：

43 43

53 claude --permission-mode plan53 claude --permission-mode plan

54 ```54 ```

55 55

~~56 **作為預設值**：在 [settings](/zh-TW/settings#settings-files) 中設定 `defaultMode`。~~56 **作為預設值**：在 [settings](/docs/zh-TW/settings#settings-files) 中設定 `defaultMode`。

57 57

58 ```json theme={null}58 ```json theme={null}

59 {59 {

63 }63 }

64 ```64 ```

65 65

~~66 相同的 `--permission-mode` 旗標適用於 `-p` 用於 [非互動式執行](/zh-TW/headless)。~~66 相同的 `--permission-mode` 旗標適用於 `-p` 用於 [非互動式執行](/docs/zh-TW/headless)。

67 </Tab>67 </Tab>

68 68

69 <Tab title="VS Code">69 <Tab title="VS Code">

83 83

84 在 v2.1.205 之前，擴充功能將 `plan` 標記為 Plan mode，將 `auto` 標記為 Auto mode。84 在 v2.1.205 之前，擴充功能將 `plan` 標記為 Plan mode，將 `auto` 標記為 Auto mode。

85 85

86 當您的帳戶符合 [auto 模式部分](#eliminate-prompts-with-auto-mode) 中列出的每項要求時，Auto 模式會在模式指示器中出現。`claudeCode.initialPermissionMode` 設定不接受 `auto`。若要預設以 auto 模式啟動，請改為在您的 [使用者設定](/zh-TW/settings#settings-files) 中設定 `defaultMode`。Claude Code 會忽略專案和本機設定中的 `defaultMode: "auto"`。86 當您的帳戶符合 [auto 模式部分](#eliminate-prompts-with-auto-mode) 中列出的每項要求時，Auto 模式會在模式指示器中出現。`claudeCode.initialPermissionMode` 設定不接受 `auto`。若要預設以 auto 模式啟動，請改為在您的 [使用者設定](/docs/zh-TW/settings#settings-files) 中設定 `defaultMode`。Claude Code 會忽略專案和本機設定中的 `defaultMode: "auto"`。

87 87

88 略過權限需要擴充功能設定中的 **Allow dangerously skip permissions** 切換，才能在模式指示器中出現。88 略過權限需要擴充功能設定中的 **Allow dangerously skip permissions** 切換，才能在模式指示器中出現。

89 89

~~90 請參閱 [VS Code 指南](/zh-TW/vs-code) 以取得擴充功能特定的詳細資訊。~~90 請參閱 [VS Code 指南](/docs/zh-TW/vs-code) 以取得擴充功能特定的詳細資訊。

91 </Tab>91 </Tab>

92 92

93 <Tab title="JetBrains">93 <Tab title="JetBrains">

100 * **Auto**：當您的帳戶符合 [auto 模式要求](#eliminate-prompts-with-auto-mode) 時出現100 * **Auto**：當您的帳戶符合 [auto 模式要求](#eliminate-prompts-with-auto-mode) 時出現

101 * **Bypass permissions**：在 Pro 和 Max 方案上需要桌面設定中的 **Allow bypass permissions mode** 切換；在 Team 和 Enterprise 方案上，組織政策會改為控制它101 * **Bypass permissions**：在 Pro 和 Max 方案上需要桌面設定中的 **Allow bypass permissions mode** 切換；在 Team 和 Enterprise 方案上，組織政策會改為控制它

102 102

103 如需桌面特定的詳細資訊，請參閱桌面指南中的 [選擇權限模式](/zh-TW/desktop#choose-a-permission-mode)。103 如需桌面特定的詳細資訊，請參閱桌面指南中的 [選擇權限模式](/docs/zh-TW/desktop#choose-a-permission-mode)。

104 104

105 **作為預設值**：在 [settings](/zh-TW/settings#settings-files) 中設定 `defaultMode`。桌面應用程式讀取與 CLI 相同的設定檔，並將模式套用到新的本機工作階段。105 **作為預設值**：在 [settings](/docs/zh-TW/settings#settings-files) 中設定 `defaultMode`。桌面應用程式讀取與 CLI 相同的設定檔，並將模式套用到新的本機工作階段。

106 106

107 您在模式選擇器中選擇的模式會按資料夾記住，並優先於該資料夾的 `defaultMode`。Plan 是例外：選擇它只會套用到目前工作階段。107 您在模式選擇器中選擇的模式會按資料夾記住，並優先於該資料夾的 `defaultMode`。Plan 是例外：選擇它只會套用到目前工作階段。

108 108

120 <Tab title="Web and mobile">120 <Tab title="Web and mobile">

121 在 [claude.ai/code](https://claude.ai/code) 或行動應用程式中使用提示框旁邊的模式下拉式選單。權限提示會在 claude.ai 中出現以供核准。出現的模式取決於工作階段在何處執行：121 在 [claude.ai/code](https://claude.ai/code) 或行動應用程式中使用提示框旁邊的模式下拉式選單。權限提示會在 claude.ai 中出現以供核准。出現的模式取決於工作階段在何處執行：

122 122

123 * **Cloud sessions** 在 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 上：接受編輯、Plan 和 Auto。接受編輯對應於 `default` 模式：雲端環境預先核准檔案編輯，無論模式為何，因此下拉式選單會顯示接受編輯而不是手動。雲端工作階段仍然遵守設定中的 `defaultMode: "acceptEdits"`。Auto 模式僅在您的組織允許且選定的模型支援時出現。略過權限不可用。123 * **Cloud sessions** 在 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 上：接受編輯、Plan 和 Auto。接受編輯對應於 `default` 模式：雲端環境預先核准檔案編輯，無論模式為何，因此下拉式選單會顯示接受編輯而不是手動。雲端工作階段仍然遵守設定中的 `defaultMode: "acceptEdits"`。Auto 模式僅在您的組織允許且選定的模型支援時出現。略過權限不可用。

124 * **[Remote Control](/zh-TW/remote-control) sessions** 在您的本機機器上：手動、接受編輯和 Plan。您無法從應用程式選擇 Auto 或 Bypass permissions。{/* min-version: 2.1.202 */}下拉式選單顯示本機工作階段所在的模式，包括從終端設定的模式，並在應用程式或終端中模式變更時更新。唯一的例外是 Bypass permissions：工作階段永遠不會向 claude.ai 報告該模式，因此從終端切換到它不會變更下拉式選單顯示的內容。在 v2.1.202 之前，使用 `/remote-control` 或 `claude --remote-control` 連線的工作階段根本不報告其模式，因此 claude.ai 和行動應用程式可能會顯示工作階段不在的模式。不匹配只影響標籤：Claude Code 從工作階段的實際模式產生權限提示，它們仍然在應用程式中出現以供核准。124 * **[Remote Control](/docs/zh-TW/remote-control) sessions** 在您的本機機器上：手動、接受編輯和 Plan。您無法從應用程式選擇 Auto 或 Bypass permissions。下拉式選單顯示本機工作階段所在的模式，包括從終端設定的模式，並在應用程式或終端中模式變更時更新。唯一的例外是 Bypass permissions：工作階段永遠不會向 claude.ai 報告該模式，因此從終端切換到它不會變更下拉式選單顯示的內容。在 v2.1.202 之前，使用 `/remote-control` 或 `claude --remote-control` 連線的工作階段根本不報告其模式，因此 claude.ai 和行動應用程式可能會顯示工作階段不在的模式。不匹配只影響標籤：Claude Code 從工作階段的實際模式產生權限提示，它們仍然在應用程式中出現以供核准。

125 125

126 對於 Remote Control，您也可以在啟動主機時設定起始模式：126 對於 Remote Control，您也可以在啟動主機時設定起始模式：

127 127

137 137

138`acceptEdits` 模式讓 Claude 在您的工作目錄中建立和編輯檔案，無需提示。當此模式處於活動狀態時，狀態列會顯示 `⏵⏵ accept edits on`。138`acceptEdits` 模式讓 Claude 在您的工作目錄中建立和編輯檔案，無需提示。當此模式處於活動狀態時，狀態列會顯示 `⏵⏵ accept edits on`。

139 139

140除了檔案編輯外，`acceptEdits` 模式還會自動批准常見的檔案系統 Bash 命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp` 和 `sed`。當這些命令以安全環境變數（例如 `LANG=C` 或 `NO_COLOR=1`）或程序包裝器（例如 `timeout`、`nice` 或 `nohup`）作為前綴時，也會自動批准。與檔案編輯一樣，自動批准僅適用於工作目錄或 `additionalDirectories` 內的路徑。超出該範圍的路徑、寫入[受保護路徑](#protected-paths)以及所有其他 Bash 命令（除了[內建唯讀集合](/zh-TW/permissions#read-only-commands)）仍會提示。140除了檔案編輯外，`acceptEdits` 模式還會自動批准常見的檔案系統 Bash 命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp` 和 `sed`。當這些命令以安全環境變數（例如 `LANG=C` 或 `NO_COLOR=1`）或程序包裝器（例如 `timeout`、`nice` 或 `nohup`）作為前綴時，也會自動批准。與檔案編輯一樣，自動批准僅適用於工作目錄或 `additionalDirectories` 內的路徑。超出該範圍的路徑、寫入[受保護路徑](#protected-paths)以及所有其他 Bash 命令（除了[內建唯讀集合](/docs/zh-TW/permissions#read-only-commands)）仍會提示。

141 141

142當[PowerShell 工具](/zh-TW/tools-reference#powershell-tool)啟用時，`acceptEdits` 模式也會自動批准 `Set-Content`、`Add-Content`、`Clear-Content` 和 `Remove-Item` 在範圍內的路徑上，以及它們的常見別名。相同的範圍和受保護路徑規則適用。142當[PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)啟用時，`acceptEdits` 模式也會自動批准 `Set-Content`、`Add-Content`、`Clear-Content` 和 `Remove-Item` 在範圍內的路徑上，以及它們的常見別名。相同的範圍和受保護路徑規則適用。

143 143

144當您想在編輯器中或透過 `git diff` 事後檢查變更，而不是逐個批准每個編輯時，請使用 `acceptEdits`。144當您想在編輯器中或透過 `git diff` 事後檢查變更，而不是逐個批准每個編輯時，請使用 `acceptEdits`。

145 145

153 使用計畫模式在編輯前進行分析153 使用計畫模式在編輯前進行分析

154</h2>154</h2>

155 155

156計畫模式會告訴 Claude 在進行變更前先研究並提出建議。Claude 會讀取檔案、執行 shell 命令進行探索，並撰寫計畫，但不會編輯您的原始碼。權限提示的應用方式與手動模式相同，除非 [自動模式](/zh-TW/auto-mode-config) 可用且 `useAutoModeDuringPlan` 已開啟（預設為開啟）。啟用自動模式後，分類器會核准搜尋和檔案讀取等唯讀命令，無需提示。無論如何，編輯都會保持被阻止，直到您核准計畫為止。156計畫模式會告訴 Claude 在進行變更前先研究並提出建議。Claude 會讀取檔案、執行 shell 命令進行探索，並撰寫計畫，但不會編輯您的原始碼。權限提示的應用方式與手動模式相同，除非 [自動模式](/docs/zh-TW/auto-mode-config) 可用且 `useAutoModeDuringPlan` 已開啟（預設為開啟）。啟用自動模式後，分類器會核准搜尋和檔案讀取等唯讀命令，無需提示。無論如何，編輯都會保持被阻止，直到您核准計畫為止。

157 157

158按下 `Shift+Tab` 或在單一提示前加上 `/plan` 即可進入計畫模式。您也可以從 CLI 開始使用計畫模式：158按下 `Shift+Tab` 或在單一提示前加上 `/plan` 即可進入計畫模式。您也可以從 CLI 開始使用計畫模式：

159 159

173* 核准並接受編輯173* 核准並接受編輯

174* 核准並手動檢視每項編輯174* 核准並手動檢視每項編輯

175* 透過回饋繼續規劃175* 透過回饋繼續規劃

176* 使用 [Ultraplan](/zh-TW/ultraplan) 進行瀏覽器型檢視以進行精煉176* 使用 [Ultraplan](/docs/zh-TW/ultraplan) 進行瀏覽器型檢視以進行精煉

177 177

178核准計畫會退出計畫模式，並將工作階段切換至每個核准選項所描述的權限模式，以便 Claude 開始編輯。若要再次規劃，請使用 `Shift+Tab` 循環回到計畫模式，或在下一個提示前加上 `/plan`。178核准計畫會退出計畫模式，並將工作階段切換至每個核准選項所描述的權限模式，以便 Claude 開始編輯。若要再次規劃，請使用 `Shift+Tab` 循環回到計畫模式，或在下一個提示前加上 `/plan`。

179 179

180按下 `Ctrl+G` 即可在預設文字編輯器中開啟提議的計畫並直接編輯，然後 Claude 才會繼續進行。當啟用 [`showClearContextOnPlanAccept`](/zh-TW/settings#available-settings) 時，每個核准選項也會提供在核准計畫前清除規劃上下文的選項。180按下 `Ctrl+G` 即可在預設文字編輯器中開啟提議的計畫並直接編輯，然後 Claude 才會繼續進行。當啟用 [`showClearContextOnPlanAccept`](/docs/zh-TW/settings#available-settings) 時，每個核准選項也會提供在核准計畫前清除規劃上下文的選項。

181 181

182接受計畫也會根據計畫內容自動為工作階段命名，除非您已使用 `--name` 或 `/rename` 設定名稱。182接受計畫也會根據計畫內容自動為工作階段命名，除非您已使用 `--name` 或 `/rename` 設定名稱。

183 183

199 使用自動模式消除權限提示199 使用自動模式消除權限提示

200</h2>200</h2>

201 201

202自動模式讓 Claude 無需例行權限提示即可執行。一個獨立的分類器模型在操作執行前進行審查，阻止任何超出您請求範圍、針對無法識別的基礎設施或似乎由 Claude 讀取的惡意內容驅動的操作。明確的[詢問規則](/zh-TW/permissions#manage-permissions)仍會強制提示。202自動模式讓 Claude 無需例行權限提示即可執行。一個獨立的分類器模型在操作執行前進行審查，阻止任何超出您請求範圍、針對無法識別的基礎設施或似乎由 Claude 讀取的惡意內容驅動的操作。明確的[詢問規則](/docs/zh-TW/permissions#manage-permissions)仍會強制提示。

203 203

204針對檔案系統根目錄或主目錄的移除，例如 `rm -rf /` 和 `rm -rf ~`，會提示批准而不是進入分類器。{/* min-version: 2.1.208 */}當命令包含使用 `$(...)` 或反引號的命令替換，或使用 `<(...)` 的程序替換時，此提示也會觸發，無論移除是在替換內部（如 `echo "$(rm -rf ~)"`），還是在同一命令的其他地方。在 v2.1.208 之前，包含這些形式的命令進入分類器而不是提示。204針對檔案系統根目錄或主目錄的移除，例如 `rm -rf /` 和 `rm -rf ~`，會提示批准而不是進入分類器。當命令包含使用 `$(...)` 或反引號的命令替換，或使用 `<(...)` 的程序替換時，此提示也會觸發，無論移除是在替換內部（如 `echo "$(rm -rf ~)"`），還是在同一命令的其他地方。在 v2.1.208 之前，包含這些形式的命令進入分類器而不是提示。

205 205

206自動模式也會促使 Claude 繼續工作而不停下來提出澄清問題，儘管當您的提示或技能明確依賴時 Claude 仍會詢問。為了在保持權限提示的同時獲得更強的自主行為，請改為設定[主動輸出風格](/zh-TW/output-styles)。206自動模式也會促使 Claude 繼續工作而不停下來提出澄清問題，儘管當您的提示或技能明確依賴時 Claude 仍會詢問。為了在保持權限提示的同時獲得更強的自主行為，請改為設定[主動輸出風格](/docs/zh-TW/output-styles)。

207 207

208<Warning>208<Warning>

209 自動模式減少了權限提示，但不保證安全性。將其用於您信任一般方向的任務，而不是作為敏感操作審查的替代品。209 自動模式減少了權限提示，但不保證安全性。將其用於您信任一般方向的任務，而不是作為敏感操作審查的替代品。

212自動模式僅在您的帳戶滿足以下所有要求時才可用：212自動模式僅在您的帳戶滿足以下所有要求時才可用：

213 213

214* **方案**：所有方案。214* **方案**：所有方案。

215* **擁有者**：在 Team 和 Enterprise 上，擁有者必須在 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)中啟用它，使用者才能開啟。管理員也可以通過在[受管設定](/zh-TW/permissions#managed-settings)中將 `permissions.disableAutoMode` 設定為 `"disable"` 來關閉自動模式。對於桌面應用程式的 Code 標籤，`disableAutoMode` 是組織級控制，管理員設定切換不適用。215* **擁有者**：在 Team 和 Enterprise 上，擁有者必須在 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)中啟用它，使用者才能開啟。管理員也可以通過在[受管設定](/docs/zh-TW/permissions#managed-settings)中將 `permissions.disableAutoMode` 設定為 `"disable"` 來關閉自動模式。對於桌面應用程式的 Code 標籤，`disableAutoMode` 是組織級控制，管理員設定切換不適用。

216* **模型**：在 Anthropic API 上，Claude Opus 4.6 或更新版本，或 Sonnet 4.6 或更新版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)工作階段上，僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。較舊的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供者上都不受支援。216* **模型**：在 Anthropic API 上，Claude Opus 4.6 或更新版本，或 Sonnet 4.6 或更新版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段上，僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。較舊的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供者上都不受支援。

217* **提供者**：在 Anthropic API、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 Claude 應用程式閘道工作階段上預設可用。{/* min-version: 2.1.207 */}在 v2.1.158 到 v2.1.206 中，自動模式在除了 Anthropic API 之外的所有這些提供者上都是關閉的，直到您設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了該要求。217* **提供者**：在 Anthropic API、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 Claude 應用程式閘道工作階段上預設可用。在 v2.1.158 到 v2.1.206 中，自動模式在除了 Anthropic API 之外的所有這些提供者上都是關閉的，直到您設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了該要求。

218 218

219如果 Claude Code 報告自動模式不可用，則其中一項要求未滿足；這不是暫時性中斷。一個單獨的訊息，命名一個模型並說自動模式「無法確定」操作的安全性，是暫時性分類器中斷；請參閱[錯誤參考](/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)。219如果 Claude Code 報告自動模式不可用，則其中一項要求未滿足；這不是暫時性中斷。一個單獨的訊息，命名一個模型並說自動模式「無法確定」操作的安全性，是暫時性分類器中斷；請參閱[錯誤參考](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)。

220 220

221如果您在[設定](/zh-TW/settings#available-settings)中設定 `defaultMode: "auto"`，且工作階段以 `default` 模式啟動且沒有錯誤，該設定可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。Claude Code v2.1.142 及更新版本會忽略來自這些檔案的 `auto`，因此儲存庫無法授予自己自動模式。將其移至 `~/.claude/settings.json`。221如果您在[設定](/docs/zh-TW/settings#available-settings)中設定 `defaultMode: "auto"`，且工作階段以 `default` 模式啟動且沒有錯誤，該設定可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。Claude Code v2.1.142 及更新版本會忽略來自這些檔案的 `auto`，因此儲存庫無法授予自己自動模式。將其移至 `~/.claude/settings.json`。

222 222

223<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">223<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">

224 Bedrock、Agent Platform 或 Foundry 上的自動模式224 Bedrock、Agent Platform 或 Foundry 上的自動模式

225</h3>225</h3>

226 226

227在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 和已登入的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)工作階段上，自動模式預設會出現在 `Shift+Tab` 循環中。出現在循環中不會改變工作階段啟動的模式：工作階段仍會以您的 [`defaultMode`](/zh-TW/settings#available-settings)啟動，除非您更改，否則為 Manual。這些提供者上僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。227在 [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)工作階段上，自動模式預設會出現在 `Shift+Tab` 循環中。出現在循環中不會改變工作階段啟動的模式：工作階段仍會以您的 [`defaultMode`](/docs/zh-TW/settings#available-settings)啟動，除非您更改，否則為 Manual。這些提供者上僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。

228 228

229要使自動模式成為預設啟動模式，請在使用者或受管設定中設定 `"permissions": {"defaultMode": "auto"}`。229要使自動模式成為預設啟動模式，請在使用者或受管設定中設定 `"permissions": {"defaultMode": "auto"}`。

230 230

231要防止開發人員使用自動模式，請在[受管設定](/zh-TW/permissions#managed-settings)中將 `disableAutoMode` 設定為 `"disable"`。這會從 `Shift+Tab` 循環中移除 `auto`，並在啟動時拒絕 `--permission-mode auto`。231要防止開發人員使用自動模式，請在[受管設定](/docs/zh-TW/permissions#managed-settings)中將 `disableAutoMode` 設定為 `"disable"`。這會從 `Shift+Tab` 循環中移除 `auto`，並在啟動時拒絕 `--permission-mode auto`。

232 232

233在 v2.1.158 到 v2.1.206 中，自動模式在這些提供者上是關閉的，直到您設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，且 Claude Code 在這些提供者上忽略 `defaultMode: "auto"`，除非也設定了該變數。該變數仍被接受以保持相容性，從 v2.1.207 開始沒有效果。233在 v2.1.158 到 v2.1.206 中，自動模式在這些提供者上是關閉的，直到您設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，且 Claude Code 在這些提供者上忽略 `defaultMode: "auto"`，除非也設定了該變數。該變數仍被接受以保持相容性，從 v2.1.207 開始沒有效果。

234 234

236 分類器預設阻止的內容236 分類器預設阻止的內容

237</h3>237</h3>

238 238

239分類器信任您的工作目錄和為其配置的遠端，這些遠端是在工作階段啟動時配置的。{/* min-version: 2.1.200 */}使用 `git remote add` 或 `git remote set-url` 在工作階段期間新增或重新指向的遠端不受信任，其他所有內容都被視為外部，直到您[配置受信任的基礎設施](/zh-TW/auto-mode-config)。在 v2.1.200 之前，中途新增的遠端也受信任。239分類器信任您的工作目錄和為其配置的遠端，這些遠端是在工作階段啟動時配置的。使用 `git remote add` 或 `git remote set-url` 在工作階段期間新增或重新指向的遠端不受信任，其他所有內容都被視為外部，直到您[配置受信任的基礎設施](/docs/zh-TW/auto-mode-config)。在 v2.1.200 之前，中途新增的遠端也受信任。

240 240

241**預設阻止**：241**預設阻止**：

242 242

248* 修改共享基礎設施248* 修改共享基礎設施

249* 不可逆地銷毀工作階段前存在的檔案249* 不可逆地銷毀工作階段前存在的檔案

250* 強制推送250* 強制推送

251* {/* min-version: 2.1.203 */}當推送包含敏感內容（如祕密或個人或受託資料）、包含相對於您要求的隱藏或誤述的變更、包含從儲存庫外部移植或首次讀取的內容，或繞過您要求的拉取請求、審查或檢查時，推送到儲存庫的預設分支。純粹推送到預設分支本身不會被阻止，清除標記的推送需要命名標記的內容或繞過的審查，而不僅僅是推送。分類器是一層：[`permissions.deny` 規則](/zh-TW/permissions#manage-permissions)適用於每種模式，可以完全阻止推送到預設分支，遠端自己的分支保護仍然適用。在 v2.1.203 之前，任何直接推送到預設分支都被阻止251* 當推送包含敏感內容（如祕密或個人或受託資料）、包含相對於您要求的隱藏或誤述的變更、包含從儲存庫外部移植或首次讀取的內容，或繞過您要求的拉取請求、審查或檢查時，推送到儲存庫的預設分支。純粹推送到預設分支本身不會被阻止，清除標記的推送需要命名標記的內容或繞過的審查，而不僅僅是推送。分類器是一層：[`permissions.deny` 規則](/docs/zh-TW/permissions#manage-permissions)適用於每種模式，可以完全阻止推送到預設分支，遠端自己的分支保護仍然適用。在 v2.1.203 之前，任何直接推送到預設分支都被阻止

252* {/* min-version: 2.1.182 */}`git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分類器假設會丟棄未提交的變更252* `git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分類器假設會丟棄未提交的變更

253* 當 HEAD 的提交不是在此工作階段中建立時的 `git commit --amend`253* 當 HEAD 的提交不是在此工作階段中建立時的 `git commit --amend`

254* {/* min-version: 2.1.198 */}從 v2.1.198 開始，當 HEAD 的提交已經被推送時的 `git commit --amend`。僅訊息重述不被阻止：`--amend -m` 沒有新暫存的內容，在 Claude 在此工作階段期間建立的提交上254* 從 v2.1.198 開始，當 HEAD 的提交已經被推送時的 `git commit --amend`。僅訊息重述不被阻止：`--amend -m` 沒有新暫存的內容，在 Claude 在此工作階段期間建立的提交上

255* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及應用銷毀資源的計畫255* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及應用銷毀資源的計畫

256 256

257Claude Code v2.1.195 及更新版本預設阻止更多類別。有些取決於[環境](/zh-TW/auto-mode-config#define-trusted-infrastructure)條目，例如敏感遠端目標和受保護的 IaC 範圍，您可以將其縮小到具體名稱。257Claude Code v2.1.195 及更新版本預設阻止更多類別。有些取決於[環境](/docs/zh-TW/auto-mode-config#define-trusted-infrastructure)條目，例如敏感遠端目標和受保護的 IaC 範圍，您可以將其縮小到具體名稱。

258 258

259* 寫入祕密管理器，或更改 DNS 記錄或 TLS 憑證259* 寫入祕密管理器，或更改 DNS 記錄或 TLS 憑證

260* 合併沒有人類批准的拉取請求、批准 Claude 自己的拉取請求或禁用 CI 檢查260* 合併沒有人類批准的拉取請求、批准 Claude 自己的拉取請求或禁用 CI 檢查

266* 互動式 shell 或埠轉發到敏感遠端目標266* 互動式 shell 或埠轉發到敏感遠端目標

267* 開啟隧道或反向 shell，使本地服務可從公共網際網路存取267* 開啟隧道或反向 shell，使本地服務可從公共網際網路存取

268* 將即時認證或令牌列印到文字記錄或檔案268* 將即時認證或令牌列印到文字記錄或檔案

269* 存取在您的[環境](/zh-TW/auto-mode-config#define-trusted-infrastructure)中列為敏感資料位置的位置，或從中複製資料。{/* min-version: 2.1.198 */}從 v2.1.198 開始，這也會阻止從一個位置向該條目排除的受眾傳送資料269* 存取在您的[環境](/docs/zh-TW/auto-mode-config#define-trusted-infrastructure)中列為敏感資料位置的位置，或從中複製資料。從 v2.1.198 開始，這也會阻止從一個位置向該條目排除的受眾傳送資料

270* 繞過您的內部套件登錄將套件安裝路由到公共登錄。{/* min-version: 2.1.198 */}從 v2.1.198 開始，這也適用於您在對話中告訴 Claude 內部登錄或鏡像存在的情況，而不僅僅是在您的環境中列出的情況270* 繞過您的內部套件登錄將套件安裝路由到公共登錄。從 v2.1.198 開始，這也適用於您在對話中告訴 Claude 內部登錄或鏡像存在的情況，而不僅僅是在您的環境中列出的情況

271* 使用禁用安全防護的標誌執行命令，例如 `--insecure`271* 使用禁用安全防護的標誌執行命令，例如 `--insecure`

272* 啟動在沒有人類批准或沙箱的情況下執行的自主代理迴圈，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 啟動的迴圈。{/* min-version: 2.1.198 */}從 v2.1.198 開始，這也涵蓋執行禁用隔離和每操作批准的第三方代理或評估工具，例如使用 `--yes-always` 啟動的執行器272* 啟動在沒有人類批准或沙箱的情況下執行的自主代理迴圈，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 啟動的迴圈。從 v2.1.198 開始，這也涵蓋執行禁用隔離和每操作批准的第三方代理或評估工具，例如使用 `--yes-always` 啟動的執行器

273* [Chrome 中的 Claude](/zh-TW/chrome)瀏覽器操作，可能會將頁面內容、Cookie 或認證傳送到跨源273* [Chrome 中的 Claude](/docs/zh-TW/chrome)瀏覽器操作，可能會將頁面內容、Cookie 或認證傳送到跨源

274 274

275Claude Code v2.1.198 及更新版本也預設阻止這些：275Claude Code v2.1.198 及更新版本也預設阻止這些：

276 276

277* 通過萬用字元、glob 或年齡篩選器而不是特定命名路徑刪除 `/tmp`、`$TMPDIR` 或其他共享暫存或快取目錄中的檔案277* 通過萬用字元、glob 或年齡篩選器而不是特定命名路徑刪除 `/tmp`、`$TMPDIR` 或其他共享暫存或快取目錄中的檔案

278* 當您自己的訊息未授權這些詳細資訊給該收件人時，在傳送、上傳、發佈或寫入其他人或共享系統的內容中包含敏感詳細資訊。{/* min-version: 2.1.200 */}當儲存庫在信任邊界外或公開時，PR 和問題正文、提交訊息和評論算作這種類型的出站內容，包括您組織自己的公開儲存庫；內部檔案路徑、代碼名稱、即時 API 回應資料（如電子郵件或帳戶識別碼）和基礎設施識別碼算作敏感詳細資訊。PR、問題和提交訊息範圍需要 Claude Code v2.1.200 或更新版本。{/* min-version: 2.1.203 */}PR 或問題正文中的即時個人資料（如電子郵件地址、帳戶或組織識別碼或使用指標）需要您命名這些詳細資訊和收件人，無論儲存庫的可見性或信任邊界如何。該檢查需要 Claude Code v2.1.203 或更新版本278* 當您自己的訊息未授權這些詳細資訊給該收件人時，在傳送、上傳、發佈或寫入其他人或共享系統的內容中包含敏感詳細資訊。當儲存庫在信任邊界外或公開時，PR 和問題正文、提交訊息和評論算作這種類型的出站內容，包括您組織自己的公開儲存庫；內部檔案路徑、代碼名稱、即時 API 回應資料（如電子郵件或帳戶識別碼）和基礎設施識別碼算作敏感詳細資訊。PR、問題和提交訊息範圍需要 Claude Code v2.1.200 或更新版本。PR 或問題正文中的即時個人資料（如電子郵件地址、帳戶或組織識別碼或使用指標）需要您命名這些詳細資訊和收件人，無論儲存庫的可見性或信任邊界如何。該檢查需要 Claude Code v2.1.203 或更新版本

279* 向 Claude Code 自己的 tmux 窗格傳送按鍵以驅動其自己的介面，分類器將其視為 Claude 更改自己的權限或監督279* 向 Claude Code 自己的 tmux 窗格傳送按鍵以驅動其自己的介面，分類器將其視為 Claude 更改自己的權限或監督

280 280

281Claude Code v2.1.200 及更新版本也預設阻止這些：281Claude Code v2.1.200 及更新版本也預設阻止這些：

284* 刪除或拆除 Claude 在工作階段中未建立的有狀態資源，當沒有更具體的刪除規則適用且您未命名該資源時284* 刪除或拆除 Claude 在工作階段中未建立的有狀態資源，當沒有更具體的刪除規則適用且您未命名該資源時

285* 將 API 基礎 URL、代理端點、webhook 接收器或登錄鏡像重新指向不適合任務的第三方主機，包括在 `.env.example` 等範例檔案中285* 將 API 基礎 URL、代理端點、webhook 接收器或登錄鏡像重新指向不適合任務的第三方主機，包括在 `.env.example` 等範例檔案中

286* 使用 `git remote set-url` 或 `git remote add` 更改推送的去向，除非您命名了新遠端286* 使用 `git remote set-url` 或 `git remote add` 更改推送的去向，除非您命名了新遠端

287* 推送祕密或個人或受託資料到已知為公開的儲存庫，或推送不是該儲存庫自己工作一部分的機密材料。{/* min-version: 2.1.203 */}dotfiles 儲存庫自己的主題是個人或受託資料的唯一例外，來自私有儲存庫到任何公開表面的內容以相同方式被阻止；兩項改進都需要 Claude Code v2.1.203 或更新版本。在 v2.1.203 之前，個人資料與機密材料分組，僅當它不是該儲存庫自己工作的一部分時才被阻止。當儲存庫的可見性未確定時，分類器不會單獨阻止；它改為根據其他規則判斷內容287* 推送祕密或個人或受託資料到已知為公開的儲存庫，或推送不是該儲存庫自己工作一部分的機密材料。dotfiles 儲存庫自己的主題是個人或受託資料的唯一例外，來自私有儲存庫到任何公開表面的內容以相同方式被阻止；兩項改進都需要 Claude Code v2.1.203 或更新版本。在 v2.1.203 之前，個人資料與機密材料分組，僅當它不是該儲存庫自己工作的一部分時才被阻止。當儲存庫的可見性未確定時，分類器不會單獨阻止；它改為根據其他規則判斷內容

288* 針對不同儲存庫或組織開啟拉取請求、使用 `gh repo fork` 進行分叉或推送到第三方儲存庫，除非您命名了該外部目標288* 針對不同儲存庫或組織開啟拉取請求、使用 `gh repo fork` 進行分叉或推送到第三方儲存庫，除非您命名了該外部目標

289 289

290Claude Code v2.1.203 及更新版本也預設阻止這些：290Claude Code v2.1.203 及更新版本也預設阻止這些：

303* 讀取 `.env` 並將認證傳送到其匹配的 API303* 讀取 `.env` 並將認證傳送到其匹配的 API

304* 唯讀 HTTP 請求304* 唯讀 HTTP 請求

305* 推送到您啟動的分支或 Claude 建立的分支305* 推送到您啟動的分支或 Claude 建立的分支

306* {/* min-version: 2.1.203 */}例行推送到儲存庫預設分支。在 v2.1.203 之前，任何直接推送到預設分支都被阻止306* 例行推送到儲存庫預設分支。在 v2.1.203 之前，任何直接推送到預設分支都被阻止

307 307

308Claude Code v2.1.195 及更新版本也預設允許這些：308Claude Code v2.1.195 及更新版本也預設允許這些：

309 309

310* 刪除 Claude 在同一工作階段中較早建立的確切工作310* 刪除 Claude 在同一工作階段中較早建立的確切工作

311* 作為您的任務的一部分讀取、審查或編寫安全相關程式碼、配置和威脅模型311* 作為您的任務的一部分讀取、審查或編寫安全相關程式碼、配置和威脅模型

312* 在同一多代理工作階段中一起工作的代理之間的訊息312* 在同一多代理工作階段中一起工作的代理之間的訊息

313* 將資料傳送到您在 [`environment`](/zh-TW/auto-mode-config#define-trusted-infrastructure)中列出的受信任網域、儲存桶和服務。這僅涵蓋資料流，而不是相同基礎設施上的破壞性或認證操作313* 將資料傳送到您在 [`environment`](/docs/zh-TW/auto-mode-config#define-trusted-infrastructure)中列出的受信任網域、儲存桶和服務。這僅涵蓋資料流，而不是相同基礎設施上的破壞性或認證操作

314* [Chrome 中的 Claude](/zh-TW/chrome)導航到受信任的內部網域、localhost 或您命名的 URL314* [Chrome 中的 Claude](/docs/zh-TW/chrome)導航到受信任的內部網域、localhost 或您命名的 URL

315 315

316沙箱網路存取請求通過分類器路由，而不是預設允許。{/* min-version: 2.1.198 */}從 v2.1.198 開始，分類器重複使用其對網路主機和埠的判決，而不是在每次連線時重新執行：316沙箱網路存取請求通過分類器路由，而不是預設允許。從 v2.1.198 開始，分類器重複使用其對網路主機和埠的判決，而不是在每次連線時重新執行：

317 317

318* 允許被重複使用，直到新內容進入對話，此時該主機被再次檢查318* 允許被重複使用，直到新內容進入對話，此時該主機被再次檢查

319* 在互動式 CLI 中，拒絕在輪次結束時被丟棄319* 在互動式 CLI 中，拒絕在輪次結束時被丟棄

320* 在[非互動式模式](/zh-TW/headless)和 Agent SDK 工作階段中沒有輪次邊界，因此拒絕在執行的其餘部分被重複使用320* 在[非互動式模式](/docs/zh-TW/headless)和 Agent SDK 工作階段中沒有輪次邊界，因此拒絕在執行的其餘部分被重複使用

321* 更改您的權限模式或規則會丟棄所有快取判決321* 更改您的權限模式或規則會丟棄所有快取判決

322 322

323執行 `claude auto-mode defaults` 以查看完整規則清單。如果例行操作被阻止，管理員可以通過 `autoMode.environment` 設定新增受信任的儲存庫、儲存桶和服務：請參閱[配置自動模式](/zh-TW/auto-mode-config)。323執行 `claude auto-mode defaults` 以查看完整規則清單。如果例行操作被阻止，管理員可以通過 `autoMode.environment` 設定新增受信任的儲存庫、儲存桶和服務：請參閱[配置自動模式](/docs/zh-TW/auto-mode-config)。

324 324

325推送到您的工作分支、進行例行推送到儲存庫預設分支，以及建立與您的請求相符的拉取請求都無需提示即可執行。分類器僅在推送帶有風險時才阻止推送，例如強制推送或繞過您設定的審查的內容。要在保持自動模式的同時要求在這些操作前進行人工檢查點，請新增 `permissions.ask` 規則：請參閱[常見邊界](/zh-TW/auto-mode-config#common-boundaries)。325推送到您的工作分支、進行例行推送到儲存庫預設分支，以及建立與您的請求相符的拉取請求都無需提示即可執行。分類器僅在推送帶有風險時才阻止推送，例如強制推送或繞過您設定的審查的內容。要在保持自動模式的同時要求在這些操作前進行人工檢查點，請新增 `permissions.ask` 規則：請參閱[常見邊界](/docs/zh-TW/auto-mode-config#common-boundaries)。

326 326

327<h3 id="boundaries-you-state-in-conversation">327<h3 id="boundaries-you-state-in-conversation">

328 您在對話中陳述的邊界328 您在對話中陳述的邊界

330 330

331分類器將您在對話中陳述的邊界視為阻止信號。如果您告訴 Claude「不要推送」或「在我審查後再部署」，分類器會阻止匹配的操作，即使預設規則會允許它們。邊界保持有效，直到您在後續訊息中解除它。Claude 自己的判斷條件已滿足不會解除它。331分類器將您在對話中陳述的邊界視為阻止信號。如果您告訴 Claude「不要推送」或「在我審查後再部署」，分類器會阻止匹配的操作，即使預設規則會允許它們。邊界保持有效，直到您在後續訊息中解除它。Claude 自己的判斷條件已滿足不會解除它。

332 332

333邊界不作為規則儲存。分類器在每次檢查時從文字記錄重新讀取它們，因此如果[上下文壓縮](/zh-TW/costs#reduce-token-usage)移除陳述邊界的訊息，邊界可能會丟失。為了獲得硬保證，請改為新增[拒絕規則](/zh-TW/permissions#permission-rule-syntax)。333邊界不作為規則儲存。分類器在每次檢查時從文字記錄重新讀取它們，因此如果[上下文壓縮](/docs/zh-TW/costs#reduce-token-usage)移除陳述邊界的訊息，邊界可能會丟失。為了獲得硬保證，請改為新增[拒絕規則](/docs/zh-TW/permissions#permission-rule-syntax)。

334 334

335<h3 id="when-auto-mode-falls-back">335<h3 id="when-auto-mode-falls-back">

336 自動模式何時回退336 自動模式何時回退

340 340

341如果分類器連續阻止操作 3 次或總共 20 次，自動模式暫停，Claude Code 恢復提示。批准提示的操作會恢復自動模式。這些閾值不可配置。任何允許的操作都會重置連續計數器，而總計數器在工作階段中持續，僅在其自己的限制觸發回退時重置。341如果分類器連續阻止操作 3 次或總共 20 次，自動模式暫停，Claude Code 恢復提示。批准提示的操作會恢復自動模式。這些閾值不可配置。任何允許的操作都會重置連續計數器，而總計數器在工作階段中持續，僅在其自己的限制觸發回退時重置。

342 342

343在[非互動式模式](/zh-TW/headless)中使用 `-p` 標誌，重複阻止會中止工作階段，因為沒有使用者可提示。343在[非互動式模式](/docs/zh-TW/headless)中使用 `-p` 標誌，重複阻止會中止工作階段，因為沒有使用者可提示。

344 344

345重複阻止通常意味著分類器缺少有關您的基礎設施的上下文。使用 `/feedback` 報告誤報，或讓管理員[配置受信任的基礎設施](/zh-TW/auto-mode-config)。345重複阻止通常意味著分類器缺少有關您的基礎設施的上下文。使用 `/feedback` 報告誤報，或讓管理員[配置受信任的基礎設施](/docs/zh-TW/auto-mode-config)。

346 346

347<AccordionGroup>347<AccordionGroup>

348 <Accordion title="分類器如何評估操作">348 <Accordion title="分類器如何評估操作">

349 每個操作都經過固定的決策順序。第一個匹配的步驟獲勝：349 每個操作都經過固定的決策順序。第一個匹配的步驟獲勝：

350 350

351 1. 與您的[允許、詢問或拒絕規則](/zh-TW/permissions#manage-permissions)匹配的操作立即解決。寫入[受保護路徑](#protected-paths)即使允許規則匹配也會路由到分類器。您的組織設定為 `ask` 的[連接器工具](/zh-TW/mcp#organization-controls-on-connector-tools)和標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使允許規則匹配也會直接提示您。內容範圍的詢問規則回退到權限提示351 1. 與您的[允許、詢問或拒絕規則](/docs/zh-TW/permissions#manage-permissions)匹配的操作立即解決。寫入[受保護路徑](#protected-paths)即使允許規則匹配也會路由到分類器。您的組織設定為 `ask` 的[連接器工具](/docs/zh-TW/mcp#organization-controls-on-connector-tools)和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使允許規則匹配也會直接提示您。內容範圍的詢問規則回退到權限提示

352 2. 唯讀操作和工作目錄中的檔案編輯會自動批准，除了[受保護路徑](#protected-paths)的寫入352 2. 唯讀操作和工作目錄中的檔案編輯會自動批准，除了[受保護路徑](#protected-paths)的寫入

353 3. 其他所有內容都進入分類器。您的組織設定為 `ask` 的[連接器工具](/zh-TW/mcp#organization-controls-on-connector-tools)跳過分類器並直接提示您，因此組織要求的批准永遠不會自動批准。{/* min-version: 2.1.199 */}從 v2.1.199 開始，標記有 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具也跳過分類器並直接提示您，因此同意步驟永遠不會代表工具作者自動批准353 3. 其他所有內容都進入分類器。您的組織設定為 `ask` 的[連接器工具](/docs/zh-TW/mcp#organization-controls-on-connector-tools)跳過分類器並直接提示您，因此組織要求的批准永遠不會自動批准。從 v2.1.199 開始，標記有 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具也跳過分類器並直接提示您，因此同意步驟永遠不會代表工具作者自動批准

354 4. 如果分類器阻止，Claude 會收到原因並嘗試替代方案354 4. 如果分類器阻止，Claude 會收到原因並嘗試替代方案

355 355

356 進入自動模式時，授予任意程式碼執行的廣泛允許規則被丟棄：356 進入自動模式時，授予任意程式碼執行的廣泛允許規則被丟棄：

366 </Accordion>366 </Accordion>

367 367

368 <Accordion title="自動模式如何處理子代理">368 <Accordion title="自動模式如何處理子代理">

369 分類器在三個點檢查[子代理](/zh-TW/sub-agents)工作：369 分類器在三個點檢查[子代理](/docs/zh-TW/sub-agents)工作：

370 370

371 1. 在子代理啟動之前，委派的任務描述被評估，因此危險看起來的任務在生成時被阻止。371 1. 在子代理啟動之前，委派的任務描述被評估，因此危險看起來的任務在生成時被阻止。

372 2. 當子代理執行時，其每個操作都通過分類器，使用與父工作階段相同的規則，子代理前言中的任何 `permissionMode` 都被忽略。372 2. 當子代理執行時，其每個操作都通過分類器，使用與父工作階段相同的規則，子代理前言中的任何 `permissionMode` 都被忽略。

376 </Accordion>376 </Accordion>

377 377

378 <Accordion title="成本和延遲">378 <Accordion title="成本和延遲">

379 分類器在獨立於您的 `/model` 選擇的伺服器配置模型上執行，因此切換模型不會改變分類器可用性。分類器呼叫計入您的令牌使用。每次檢查發送文字記錄的一部分加上待執行操作，在執行前新增往返。受保護路徑外的讀取和工作目錄編輯跳過分類器，因此開銷主要來自 shell 命令和網路操作。{/* min-version: 2.1.198 */}從 v2.1.198 開始，沙箱網路判決對於主機和埠被重複使用，而不是在每次連線時重新分類，因此重複連線到同一主機不會各自新增檢查。[分類器預設阻止的內容](#what-the-classifier-blocks-by-default)描述允許和拒絕持續多長時間。379 分類器在獨立於您的 `/model` 選擇的伺服器配置模型上執行，因此切換模型不會改變分類器可用性。分類器呼叫計入您的令牌使用。每次檢查發送文字記錄的一部分加上待執行操作，在執行前新增往返。受保護路徑外的讀取和工作目錄編輯跳過分類器，因此開銷主要來自 shell 命令和網路操作。從 v2.1.198 開始，沙箱網路判決對於主機和埠被重複使用，而不是在每次連線時重新分類，因此重複連線到同一主機不會各自新增檢查。[分類器預設阻止的內容](#what-the-classifier-blocks-by-default)描述允許和拒絕持續多長時間。

380 </Accordion>380 </Accordion>

381</AccordionGroup>381</AccordionGroup>

382 382

384 使用 dontAsk 模式僅允許預先核准的工具384 使用 dontAsk 模式僅允許預先核准的工具

385</h2>385</h2>

386 386

387如果您設定 `dontAsk` 模式，Claude Code 會自動拒絕所有原本會提示的工具呼叫。Claude 只執行符合您的 `permissions.allow` 規則、[唯讀 Bash 命令](/zh-TW/permissions#read-only-commands)的動作，以及由 [PreToolUse hook](/zh-TW/permissions#extend-permissions-with-hooks) 核准的呼叫。在您預先定義 Claude 可以執行的確切操作的 CI 管道或受限環境中使用此模式；工作階段永遠不會等待輸入。此模式啟用時，狀態列會顯示 `⏵⏵ don't ask on`。387如果您設定 `dontAsk` 模式，Claude Code 會自動拒絕所有原本會提示的工具呼叫。Claude 只執行符合您的 `permissions.allow` 規則、[唯讀 Bash 命令](/docs/zh-TW/permissions#read-only-commands)的動作，以及由 [PreToolUse hook](/docs/zh-TW/permissions#extend-permissions-with-hooks) 核准的呼叫。在您預先定義 Claude 可以執行的確切操作的 CI 管道或受限環境中使用此模式；工作階段永遠不會等待輸入。此模式啟用時，狀態列會顯示 `⏵⏵ don't ask on`。

388 388

389Claude Code 會拒絕符合您明確 [`ask` 規則](/zh-TW/permissions#manage-permissions) 的呼叫，而不是提示。它也會拒絕內建的 `AskUserQuestion` 工具和連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)，即使您的允許規則符合它們。{/* min-version: 2.1.199 */}它以相同方式拒絕標記為 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，因為它們的核准卡需要此模式永遠不會收集的答案；這需要 Claude Code v2.1.199 或更新版本。389Claude Code 會拒絕符合您明確 [`ask` 規則](/docs/zh-TW/permissions#manage-permissions) 的呼叫，而不是提示。它也會拒絕內建的 `AskUserQuestion` 工具和連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)，即使您的允許規則符合它們。它以相同方式拒絕標記為 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，因為它們的核准卡需要此模式永遠不會收集的答案；這需要 Claude Code v2.1.199 或更新版本。

390 390

391[Claude Code on the web](/zh-TW/claude-code-on-the-web) 上的雲端工作階段會忽略 `defaultMode: "dontAsk"`；詳見 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) 以了解詳情。391[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 上的雲端工作階段會忽略 `defaultMode: "dontAsk"`；詳見 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) 以了解詳情。

392 392

393在啟動時使用旗標設定：393在啟動時使用旗標設定：

394 394

402 402

403`bypassPermissions` 模式會停用權限提示和安全檢查，以便工具呼叫立即執行，包括寫入[受保護的路徑](#protected-paths)。在 v2.1.126 之前，受保護路徑的寫入在此模式中仍會提示。403`bypassPermissions` 模式會停用權限提示和安全檢查，以便工具呼叫立即執行，包括寫入[受保護的路徑](#protected-paths)。在 v2.1.126 之前，受保護路徑的寫入在此模式中仍會提示。

404 404

405明確的[詢問規則](/zh-TW/permissions#manage-permissions)和連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)仍會在此模式中強制提示。{/* min-version: 2.1.199 */}標記有 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具也仍會提示；這需要 Claude Code v2.1.199 或更新版本。405明確的[詢問規則](/docs/zh-TW/permissions#manage-permissions)和連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)仍會在此模式中強制提示。標記有 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具也仍會提示；這需要 Claude Code v2.1.199 或更新版本。

406 406

407針對檔案系統根目錄或主目錄的移除操作，例如 `rm -rf /` 和 `rm -rf ~`，仍會作為針對模型錯誤的斷路器而提示。{/* min-version: 2.1.208 */}當命令包含使用 `$(...)` 或反引號的命令替換，或使用 `<(...)` 的程序替換時，斷路器也會觸發，無論移除操作位於替換內部（如 `echo "$(rm -rf ~)"`），還是位於同一命令中的其他位置。純形式（作為其自身命令輸入）自引入斷路器以來在此模式中已提示；在 v2.1.208 之前，包含這些形式的命令不會提示。407針對檔案系統根目錄或主目錄的移除操作，例如 `rm -rf /` 和 `rm -rf ~`，仍會作為針對模型錯誤的斷路器而提示。當命令包含使用 `$(...)` 或反引號的命令替換，或使用 `<(...)` 的程序替換時，斷路器也會觸發，無論移除操作位於替換內部（如 `echo "$(rm -rf ~)"`），還是位於同一命令中的其他位置。純形式（作為其自身命令輸入）自引入斷路器以來在此模式中已提示；在 v2.1.208 之前，包含這些形式的命令不會提示。

408 408

409<Warning>409<Warning>

410 僅在隔離環境（例如容器、虛擬機或無網際網路存取的開發容器）中使用此模式，其中 Claude Code 無法損害您的主機系統。410 僅在隔離環境（例如容器、虛擬機或無網際網路存取的開發容器）中使用此模式，其中 Claude Code 無法損害您的主機系統。

424--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons424--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons

425```425```

426 426

427檢查會在識別的沙箱內自動跳過。若要在容器中自主執行，請使用[開發容器](/zh-TW/devcontainer)配置，該配置以非 root 使用者身份執行 Claude Code。427檢查會在識別的沙箱內自動跳過。若要在容器中自主執行，請使用[開發容器](/docs/zh-TW/devcontainer)配置，該配置以非 root 使用者身份執行 Claude Code。

428 428

429[網路上的 Claude Code](/zh-TW/claude-code-on-the-web) 不會遵守您設定檔案中的 `defaultMode: "bypassPermissions"` 或 `"dontAsk"`，因此儲存庫的簽入設定無法在略過權限模式下啟動雲端工作階段。該設定會被無聲地忽略，工作階段會改為以模式下拉式選單中顯示的模式啟動。請參閱[切換權限模式](#switch-permission-modes)以了解雲端工作階段提供的模式。429[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 不會遵守您設定檔案中的 `defaultMode: "bypassPermissions"` 或 `"dontAsk"`，因此儲存庫的簽入設定無法在略過權限模式下啟動雲端工作階段。該設定會被無聲地忽略，工作階段會改為以模式下拉式選單中顯示的模式啟動。請參閱[切換權限模式](#switch-permission-modes)以了解雲端工作階段提供的模式。

430 430

431<Warning>431<Warning>

432 `bypassPermissions` 不提供針對提示注入或意外操作的保護。若要使用背景安全檢查且權限提示大幅減少，請改用[自動模式](#eliminate-prompts-with-auto-mode)。管理員可以透過在[受管設定](/zh-TW/permissions#managed-settings)中將 `permissions.disableBypassPermissionsMode` 設定為 `"disable"` 來封鎖此模式。432 `bypassPermissions` 不提供針對提示注入或意外操作的保護。若要使用背景安全檢查且權限提示大幅減少，請改用[自動模式](#eliminate-prompts-with-auto-mode)。管理員可以透過在[受管設定](/docs/zh-TW/permissions#managed-settings)中將 `permissions.disableBypassPermissionsMode` 設定為 `"disable"` 來封鎖此模式。

433</Warning>433</Warning>

434 434

435<h2 id="protected-paths">435<h2 id="protected-paths">

445| `dontAsk` | 拒絕 |445| `dontAsk` | 拒絕 |

446| `bypassPermissions` | 允許 |446| `bypassPermissions` | 允許 |

447 447

448設定檔案中的 [`permissions.allow`](/zh-TW/permissions#manage-permissions) 規則不會預先批准受保護路徑的寫入。安全檢查在 Claude Code 評估設定中的允許規則之前執行，因此在 `~/.claude/settings.json` 或 `.claude/settings.json` 中的 `Edit(.claude/**)` 之類的項目不會改變上表中的每個模式結果。在提示的模式中，`.claude/` 寫入的提示會提供**是的，並允許 Claude 在此工作階段編輯其自身設定**，這會在該工作階段中批准後續的 `.claude/` 寫入而無需再次提示。448設定檔案中的 [`permissions.allow`](/docs/zh-TW/permissions#manage-permissions) 規則不會預先批准受保護路徑的寫入。安全檢查在 Claude Code 評估設定中的允許規則之前執行，因此在 `~/.claude/settings.json` 或 `.claude/settings.json` 中的 `Edit(.claude/**)` 之類的項目不會改變上表中的每個模式結果。在提示的模式中，`.claude/` 寫入的提示會提供**是的，並允許 Claude 在此工作階段編輯其自身設定**，這會在該工作階段中批准後續的 `.claude/` 寫入而無需再次提示。

449 449

450受保護的目錄：450受保護的目錄：

451 451

476 另請參閱476 另請參閱

477</h2>477</h2>

478 478

479* [Permissions](/zh-TW/permissions)：allow、ask 和 deny 規則；受管理的原則479* [Permissions](/docs/zh-TW/permissions)：allow、ask 和 deny 規則；受管理的原則

480* [Configure auto mode](/zh-TW/auto-mode-config)：告訴分類器您的組織信任哪些基礎設施480* [Configure auto mode](/docs/zh-TW/auto-mode-config)：告訴分類器您的組織信任哪些基礎設施

481* [Hooks](/zh-TW/hooks)：透過 `PreToolUse` 和 `PermissionRequest` hooks 的自訂權限邏輯481* [Hooks](/docs/zh-TW/hooks)：透過 `PreToolUse` 和 `PermissionRequest` hooks 的自訂權限邏輯

482* [Ultraplan](/zh-TW/ultraplan)：在 Claude Code 網頁工作階段中執行計畫模式，並進行瀏覽器型審查482* [Ultraplan](/docs/zh-TW/ultraplan)：在 Claude Code 網頁工作階段中執行計畫模式，並進行瀏覽器型審查

483* [Security](/zh-TW/security)：保護措施和最佳實踐483* [Security](/docs/zh-TW/security)：保護措施和最佳實踐

484* [Sandboxing](/zh-TW/sandboxing)：Bash 命令的檔案系統和網路隔離484* [Sandboxing](/docs/zh-TW/sandboxing)：Bash 命令的檔案系統和網路隔離

485* [Non-interactive mode](/zh-TW/headless)：使用 `-p` 旗標執行 Claude Code485* [Non-interactive mode](/docs/zh-TW/headless)：使用 `-p` 旗標執行 Claude Code

permissions.md +58 −58

Details

22 22

23在 Bash 或 PowerShell 權限提示上，按 `Ctrl+E` 以顯示命令的說明：它的功能、Claude 為什麼執行它，以及可能出現的問題，標記為**低風險**、**中風險**或**高風險**。Claude Code 只在您按 `Ctrl+E` 時才會將命令和 Claude 自己對該呼叫的描述傳送給模型以產生說明，而不是在每次提示時都這樣做。顯示說明不會執行命令；再次按 `Ctrl+E` 以隱藏它。23在 Bash 或 PowerShell 權限提示上，按 `Ctrl+E` 以顯示命令的說明：它的功能、Claude 為什麼執行它，以及可能出現的問題，標記為**低風險**、**中風險**或**高風險**。Claude Code 只在您按 `Ctrl+E` 時才會將命令和 Claude 自己對該呼叫的描述傳送給模型以產生說明，而不是在每次提示時都這樣做。顯示說明不會執行命令；再次按 `Ctrl+E` 以隱藏它。

24 24

~~25若要關閉快捷鍵，請在 `~/.claude.json` 中將 [`permissionExplainerEnabled`](/zh-TW/settings#global-config-settings) 設定為 `false`。~~25若要關閉快捷鍵，請在 `~/.claude.json` 中將 [`permissionExplainerEnabled`](/docs/zh-TW/settings#global-config-settings) 設定為 `false`。

26 26

27<h2 id="manage-permissions">27<h2 id="manage-permissions">

28 管理權限28 管理權限

41Deny 規則的行為取決於它們是否命名工具或在工具內限定模式。像 `Bash` 這樣的裸工具名稱會將工具從 Claude 的上下文中完全移除，因此 Claude 永遠看不到它。像 `Bash(rm *)` 這樣的限定規則會保留工具可用性，並在 Claude 嘗試時阻止符合的呼叫。41Deny 規則的行為取決於它們是否命名工具或在工具內限定模式。像 `Bash` 這樣的裸工具名稱會將工具從 Claude 的上下文中完全移除，因此 Claude 永遠看不到它。像 `Bash(rm *)` 這樣的限定規則會保留工具可用性，並在 Claude 嘗試時阻止符合的呼叫。

42 42

43<Note>43<Note>

44 權限規則由 Claude Code 強制執行，而不是由模型強制執行。您的提示或 `CLAUDE.md` 中的指令會影響 Claude 嘗試執行的操作，但不會改變 Claude Code 允許的操作。若要授予或撤銷存取權限，請使用 `/permissions`、此處描述的規則、[permission mode](/zh-TW/permission-modes) 或 [PreToolUse hook](#extend-permissions-with-hooks)。44 權限規則由 Claude Code 強制執行，而不是由模型強制執行。您的提示或 `CLAUDE.md` 中的指令會影響 Claude 嘗試執行的操作，但不會改變 Claude Code 允許的操作。若要授予或撤銷存取權限，請使用 `/permissions`、此處描述的規則、[permission mode](/docs/zh-TW/permission-modes) 或 [PreToolUse hook](#extend-permissions-with-hooks)。

45</Note>45</Note>

46 46

47<h2 id="permission-modes">47<h2 id="permission-modes">

48 權限模式48 權限模式

49</h2>49</h2>

50 50

51Claude Code 支援多種權限模式來控制工具的批准方式。請參閱 [Permission modes](/zh-TW/permission-modes) 以了解何時使用每一種。在您的 [settings files](/zh-TW/settings#settings-files) 中設定 `defaultMode`：51Claude Code 支援多種權限模式來控制工具的批准方式。請參閱 [Permission modes](/docs/zh-TW/permission-modes) 以了解何時使用每一種。在您的 [settings files](/docs/zh-TW/settings#settings-files) 中設定 `defaultMode`：

52 52

53| 模式 | 描述 |53| 模式 | 描述 |

54| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |54| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

55| `default` | 標準行為：在首次使用每個工具時提示權限。{/* min-version: 2.1.200 */}在 CLI、VS Code 和 JetBrains 擴充功能以及桌面應用程式中標示為 Manual，Claude Code 接受 `manual` 作為別名。標籤和別名需要 Claude Code v2.1.200 或更新版本。桌面應用程式的標籤不取決於您的 CLI 版本 |55| `default` | 標準行為：在首次使用每個工具時提示權限。在 CLI、VS Code 和 JetBrains 擴充功能以及桌面應用程式中標示為 Manual，Claude Code 接受 `manual` 作為別名。標籤和別名需要 Claude Code v2.1.200 或更新版本。桌面應用程式的標籤不取決於您的 CLI 版本 |

59| `dontAsk` | 自動拒絕工具，除非透過 `/permissions` 或 `permissions.allow` 規則預先批准。`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和標示為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使您已允許它們也會被拒絕 |59| `dontAsk` | 自動拒絕工具，除非透過 `/permissions` 或 `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 工具即使您已允許它們也會被拒絕 |

60| `bypassPermissions` | 跳過權限提示，但明確的 `ask` 規則、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和標示為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具強制的提示除外。根目錄和主目錄移除（例如 `rm -rf /`）仍會作為斷路器提示 |60| `bypassPermissions` | 跳過權限提示，但明確的 `ask` 規則、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標示為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具強制的提示除外。根目錄和主目錄移除（例如 `rm -rf /`）仍會作為斷路器提示 |

61 61

62<Warning>62<Warning>

63 `bypassPermissions` 模式會跳過權限提示，包括對 `.git`、`.config/git`、`.claude`、`.vscode`、`.idea`、`.husky`、`.cargo`、`.devcontainer`、`.yarn` 和 `.mvn` 的寫入。僅在隔離環境（如容器或虛擬機）中使用此模式，其中 Claude Code 無法造成損害。63 `bypassPermissions` 模式會跳過權限提示，包括對 `.git`、`.config/git`、`.claude`、`.vscode`、`.idea`、`.husky`、`.cargo`、`.devcontainer`、`.yarn` 和 `.mvn` 的寫入。僅在隔離環境（如容器或虛擬機）中使用此模式，其中 Claude Code 無法造成損害。

64 64

65 此模式中仍會觸發一些提示。明確的 `ask` 規則、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和標示為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具仍會提示。針對檔案系統根目錄或主目錄的移除（例如 `rm -rf /` 和 `rm -rf ~`）也會作為斷路器提示以防止模型錯誤，{/* min-version: 2.1.208 */}包括當命令包含使用 `$(...)` 或反引號的命令替換或使用 `<(...)` 的程序替換時。在 v2.1.208 之前，只有純形式（例如 `rm -rf ~` 作為其自身命令輸入）會提示；透過替換到達移除的命令不會提示。65 此模式中仍會觸發一些提示。明確的 `ask` 規則、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標示為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具仍會提示。針對檔案系統根目錄或主目錄的移除（例如 `rm -rf /` 和 `rm -rf ~`）也會作為斷路器提示以防止模型錯誤，包括當命令包含使用 `$(...)` 或反引號的命令替換或使用 `<(...)` 的程序替換時。在 v2.1.208 之前，只有純形式（例如 `rm -rf ~` 作為其自身命令輸入）會提示；透過替換到達移除的命令不會提示。

66</Warning>66</Warning>

67 67

68若要防止 `bypassPermissions` 或 `auto` 模式被使用，請在任何 [settings file](/zh-TW/settings#settings-files) 中將 `permissions.disableBypassPermissionsMode` 或 `permissions.disableAutoMode` 設定為 `"disable"`。這些在 [managed settings](#managed-settings) 中最有用，因為它們無法被覆蓋。68若要防止 `bypassPermissions` 或 `auto` 模式被使用，請在任何 [settings file](/docs/zh-TW/settings#settings-files) 中將 `permissions.disableBypassPermissionsMode` 或 `permissions.disableAutoMode` 設定為 `"disable"`。這些在 [managed settings](#managed-settings) 中最有用，因為它們無法被覆蓋。

69 69

70<h2 id="permission-rule-syntax">70<h2 id="permission-rule-syntax">

71 權限規則語法71 權限規則語法

117* 每個規則命名一個參數。若要在 `model` 和 `isolation` 上設定閘道，請寫入兩個規則 `Agent(model:opus)` 和 `Agent(isolation:worktree)`，而不是在一個規則中組合它們117* 每個規則命名一個參數。若要在 `model` 和 `isolation` 上設定閘道，請寫入兩個規則 `Agent(model:opus)` 和 `Agent(isolation:worktree)`，而不是在一個規則中組合它們

118* 值支援 `*` 作為符合任何字元序列的萬用字元，因此 `Agent(isolation:*)` 符合任何明確的隔離值。沒有 `*` 時，符合是確切的118* 值支援 `*` 作為符合任何字元序列的萬用字元，因此 `Agent(isolation:*)` 符合任何明確的隔離值。沒有 `*` 時，符合是確切的

119* 模型省略的參數永遠不會被符合，因此 `Agent(model:*)` 不符合留下 `model` 未設定的呼叫119* 模型省略的參數永遠不會被符合，因此 `Agent(model:*)` 不符合留下 `model` 未設定的呼叫

120* 值與 Claude 傳送的字面輸入進行比較，在任何正規化之前。`Agent(model:opus)` 符合別名 `opus` 但不符合完整模型 ID。使用 [`--verbose`](/zh-TW/cli-reference) 執行以查看每個工具呼叫中的確切參數名稱和值120* 值與 Claude 傳送的字面輸入進行比較，在任何正規化之前。`Agent(model:opus)` 符合別名 `opus` 但不符合完整模型 ID。使用 [`--verbose`](/docs/zh-TW/cli-reference) 執行以查看每個工具呼叫中的確切參數名稱和值

121* 冒號周圍的空格被忽略121* 冒號周圍的空格被忽略

122 122

123工具已使用自己的規範化規則符合的欄位不可以這種方式符合：Bash 和 PowerShell 的 `command`、Read、Edit 和 Write 的 `file_path`、Grep 和 Glob 的 `path`、NotebookEdit 的 `notebook_path`，以及 WebFetch 的 `url`。像 `Bash(command:rm *)` 這樣的規則可能會被複合命令繞過，因此 Claude Code 會忽略它並在啟動時發出警告。改用 `Bash(rm *)`、`Read(./path)` 或 `WebFetch(domain:host)`。123工具已使用自己的規範化規則符合的欄位不可以這種方式符合：Bash 和 PowerShell 的 `command`、Read、Edit 和 Write 的 `file_path`、Grep 和 Glob 的 `path`、NotebookEdit 的 `notebook_path`，以及 WebFetch 的 `url`。像 `Bash(command:rm *)` 這樣的規則可能會被複合命令繞過，因此 Claude Code 會忽略它並在啟動時發出警告。改用 `Bash(rm *)`、`Read(./path)` 或 `WebFetch(domain:host)`。

169 169

170拒絕或詢問規則，其工具名稱不符合任何已知工具，會在啟動時產生警告以捕捉拼寫錯誤。包含 `_` 或 `*` 的工具名稱不受檢查限制。170拒絕或詢問規則，其工具名稱不符合任何已知工具，會在啟動時產生警告以捕捉拼寫錯誤。包含 `_` 或 `*` 的工具名稱不受檢查限制。

171 171

172工具在文字記錄和權限對話框中顯示的標籤可能與其規範名稱不同。例如，文字記錄中標記為 `Stop Task` 的工具具有規範名稱 `TaskStop`。權限規則和 [hook 匹配器](/zh-TW/hooks)僅符合規範名稱，因此寫成 `Stop Task` 的規則不符合。對於拒絕和詢問規則，上述啟動警告會捕捉不匹配。使用 [工具參考](/zh-TW/tools-reference)中列出的規範名稱。172工具在文字記錄和權限對話框中顯示的標籤可能與其規範名稱不同。例如，文字記錄中標記為 `Stop Task` 的工具具有規範名稱 `TaskStop`。權限規則和 [hook 匹配器](/docs/zh-TW/hooks)僅符合規範名稱，因此寫成 `Stop Task` 的規則不符合。對於拒絕和詢問規則，上述啟動警告會捕捉不匹配。使用 [工具參考](/docs/zh-TW/tools-reference)中列出的規範名稱。

173 173

174<h2 id="tool-specific-permission-rules">174<h2 id="tool-specific-permission-rules">

175 工具特定的權限規則175 工具特定的權限規則

223 223

224`cd` 進入工作目錄或[額外目錄](#working-directories)內的路徑也是唯讀的。像 `cd packages/api && ls` 這樣的複合命令在每個部分都符合時無需提示即可執行。在一個複合命令中結合 `cd` 和 `git` 會在 `cd` 變更進入不同目錄時提示，因為在新目錄中執行 `git` 可能會執行該目錄的 hooks。`cd` 其目標解析為目前工作目錄的是無操作的，不會觸發此提示。224`cd` 進入工作目錄或[額外目錄](#working-directories)內的路徑也是唯讀的。像 `cd packages/api && ls` 這樣的複合命令在每個部分都符合時無需提示即可執行。在一個複合命令中結合 `cd` 和 `git` 會在 `cd` 變更進入不同目錄時提示，因為在新目錄中執行 `git` 可能會執行該目錄的 hooks。`cd` 其目標解析為目前工作目錄的是無操作的，不會觸發此提示。

225 225

226在一個複合命令中結合 `cd` 與輸出重新導向也會在 Claude Code 無法判斷重新導向目標在 `cd` 執行後針對哪個目錄解析時提示。其唯一重新導向目標是 `/dev/null` 的命令，如 `cd app; grep -r pattern . 2>/dev/null`，不會觸發此提示，因為 `/dev/null` 不依賴於工作目錄。{/* min-version: 2.1.207 */}在 v2.1.207 之前，包含 `cd` 的複合命令會針對任何輸出重新導向提示，包括其唯一目標是 `/dev/null` 的重新導向。226在一個複合命令中結合 `cd` 與輸出重新導向也會在 Claude Code 無法判斷重新導向目標在 `cd` 執行後針對哪個目錄解析時提示。其唯一重新導向目標是 `/dev/null` 的命令，如 `cd app; grep -r pattern . 2>/dev/null`，不會觸發此提示，因為 `/dev/null` 不依賴於工作目錄。在 v2.1.207 之前，包含 `cd` 的複合命令會針對任何輸出重新導向提示，包括其唯一目標是 `/dev/null` 的重新導向。

227 227

228<Warning>228<Warning>

229 嘗試限制命令引數的 Bash 權限模式很脆弱。例如，`Bash(curl http://github.com/ *)` 旨在將 curl 限制為 GitHub URL，但不會符合以下變化：229 嘗試限制命令引數的 Bash 權限模式很脆弱。例如，`Bash(curl http://github.com/ *)` 旨在將 curl 限制為 GitHub URL，但不會符合以下變化：

271 Read 和 Edit271 Read 和 Edit

272</h3>272</h3>

273 273

274`Edit` 規則適用於所有編輯檔案的內建工具。Claude 會盡力嘗試將 `Read` 規則應用於所有讀取檔案的內建工具，如 Grep 和 Glob，以及您提示中的 `@file` 提及，以及連接的 [IDE](/zh-TW/vs-code#the-built-in-ide-mcp-server) 與 Claude 共享的選擇和開啟檔案內容。274`Edit` 規則適用於所有編輯檔案的內建工具。Claude 會盡力嘗試將 `Read` 規則應用於所有讀取檔案的內建工具，如 Grep 和 Glob，以及您提示中的 `@file` 提及，以及連接的 [IDE](/docs/zh-TW/vs-code#the-built-in-ide-mcp-server) 與 Claude 共享的選擇和開啟檔案內容。

275 275

276{/* min-version: 2.1.208 */}`Read` deny 規則也會阻止同一路徑上的 [Edit 工具](/zh-TW/errors#file-is-covered-by-a-read-deny-rule)，包括在該處建立新檔案。Write 和 NotebookEdit 不涵蓋，所以為任何工具都不可變更的路徑新增 `Edit` deny 規則。需要 Claude Code v2.1.208 或更新版本。276`Read` deny 規則也會阻止同一路徑上的 [Edit 工具](/docs/zh-TW/errors#file-is-covered-by-a-read-deny-rule)，包括在該處建立新檔案。Write 和 NotebookEdit 不涵蓋，所以為任何工具都不可變更的路徑新增 `Edit` deny 規則。需要 Claude Code v2.1.208 或更新版本。

277 277

278<Warning>278<Warning>

279 Read 和 Edit deny 規則適用於 Claude 的內建檔案工具和 Claude Code 在 Bash 中識別的檔案命令，如 `cat`、`head`、`tail` 和 `sed`。它們不適用於間接讀取或寫入檔案的任意子程序，如自行開啟檔案的 Python 或 Node 指令碼。為了進行作業系統級別的強制執行，以阻止所有程序存取路徑，請[啟用沙箱](/zh-TW/sandboxing)。279 Read 和 Edit deny 規則適用於 Claude 的內建檔案工具和 Claude Code 在 Bash 中識別的檔案命令，如 `cat`、`head`、`tail` 和 `sed`。它們不適用於間接讀取或寫入檔案的任意子程序，如自行開啟檔案的 Python 或 Node 指令碼。為了進行作業系統級別的強制執行，以阻止所有程序存取路徑，請[啟用沙箱](/docs/zh-TW/sandboxing)。

280</Warning>280</Warning>

281 281

282Read 和 Edit 規則都遵循 [gitignore](https://git-scm.com/docs/gitignore) 規格，具有四種不同的模式類型：282Read 和 Edit 規則都遵循 [gitignore](https://git-scm.com/docs/gitignore) 規格，具有四種不同的模式類型：

323 在 gitignore 模式中，`*` 符合單一目錄中的檔案，而 `**` 遞迴符合目錄。若要允許所有檔案存取，請使用不帶括號的工具名稱：`Read`、`Edit` 或 `Write`。323 在 gitignore 模式中，`*` 符合單一目錄中的檔案，而 `**` 遞迴符合目錄。若要允許所有檔案存取，請使用不帶括號的工具名稱：`Read`、`Edit` 或 `Write`。

324</Note>324</Note>

325 325

326{/* min-version: 2.1.202 */}當您使用「是，不要再問」批准檔案路徑時，Claude Code 會逸出該路徑中的 gitignore 模式字元，如 `[`、`]` 和 `*`，所以產生的規則只符合您批准的字面路徑。您自己編寫的規則不會被逸出。在 v2.1.202 之前，Claude Code 會儲存未逸出的路徑，所以名為 `[2024-06] Reports` 的目錄產生的規則可能無法符合其自己的路徑或符合無意的同級目錄。326當您使用「是，不要再問」批准檔案路徑時，Claude Code 會逸出該路徑中的 gitignore 模式字元，如 `[`、`]` 和 `*`，所以產生的規則只符合您批准的字面路徑。您自己編寫的規則不會被逸出。在 v2.1.202 之前，Claude Code 會儲存未逸出的路徑，所以名為 `[2024-06] Reports` 的目錄產生的規則可能無法符合其自己的路徑或符合無意的同級目錄。

327 327

328當 Claude 存取符號連結時，權限規則檢查兩個路徑：符號連結本身和它解析到的檔案。Allow 和 deny 規則對該對的處理方式不同：allow 規則回退到提示您，而 deny 規則直接阻止。328當 Claude 存取符號連結時，權限規則檢查兩個路徑：符號連結本身和它解析到的檔案。Allow 和 deny 規則對該對的處理方式不同：allow 規則回退到提示您，而 deny 規則直接阻止。

329 329

354* `mcp__puppeteer__*` 使用萬用字元語法，也符合來自 `puppeteer` 伺服器的所有工具354* `mcp__puppeteer__*` 使用萬用字元語法，也符合來自 `puppeteer` 伺服器的所有工具

355* `mcp__puppeteer__puppeteer_navigate` 符合由 `puppeteer` 伺服器提供的 `puppeteer_navigate` 工具355* `mcp__puppeteer__puppeteer_navigate` 符合由 `puppeteer` 伺服器提供的 `puppeteer_navigate` 工具

356 356

357如果您的組織已將 [claude.ai 連接器](/zh-TW/mcp#organization-controls-on-connector-tools)工具設定為 `ask`，該工具的 allow 規則不會生效：Claude Code 會在每次呼叫時提示，即使在 `auto` 和 `bypassPermissions` 模式中也是如此。在 `dontAsk` 模式中（永不提示），Claude Code 會改為拒絕呼叫。連接器工具顯示為 `mcp__claude_ai_<server>__<tool>`。357如果您的組織已將 [claude.ai 連接器](/docs/zh-TW/mcp#organization-controls-on-connector-tools)工具設定為 `ask`，該工具的 allow 規則不會生效：Claude Code 會在每次呼叫時提示，即使在 `auto` 和 `bypassPermissions` 模式中也是如此。在 `dontAsk` 模式中（永不提示），Claude Code 會改為拒絕呼叫。連接器工具顯示為 `mcp__claude_ai_<server>__<tool>`。

358 358

359<h3 id="agent-subagents">359<h3 id="agent-subagents">

360 Agent（subagents）360 Agent（subagents）

361</h3>361</h3>

362 362

363使用 `Agent(AgentName)` 規則來控制 Claude 可以使用哪些 [subagents](/zh-TW/sub-agents)：363使用 `Agent(AgentName)` 規則來控制 Claude 可以使用哪些 [subagents](/docs/zh-TW/sub-agents)：

364 364

365* `Agent(Explore)` 符合 Explore subagent365* `Agent(Explore)` 符合 Explore subagent

366* `Agent(Plan)` 符合 Plan subagent366* `Agent(Plan)` 符合 Plan subagent

380 Cd380 Cd

381</h3>381</h3>

382 382

383`Cd` 規則控制 [`/cd` 命令](/zh-TW/commands) 可以將工作階段移動到哪些目錄。`Cd` 不是模型可呼叫的工具：Claude 無法呼叫它，規則僅在您自己執行 `/cd` 時適用。383`Cd` 規則控制 [`/cd` 命令](/docs/zh-TW/commands) 可以將工作階段移動到哪些目錄。`Cd` 不是模型可呼叫的工具：Claude 無法呼叫它，規則僅在您自己執行 `/cd` 時適用。

384 384

385裸 `Cd` deny 規則會完全停用 `/cd`。`Cd(<path-pattern>)` deny 規則會阻止符合的目標。Deny 規則檢查目標的每個拼寫，包括它解析通過的每個符號連結跳躍，所以為一個路徑編寫的規則也會阻止解析到它的目標。385裸 `Cd` deny 規則會完全停用 `/cd`。`Cd(<path-pattern>)` deny 規則會阻止符合的目標。Deny 規則檢查目標的每個拼寫，包括它解析通過的每個符號連結跳躍，所以為一個路徑編寫的規則也會阻止解析到它的目標。

386 386

398 使用 hooks 擴展權限398 使用 hooks 擴展權限

399</h2>399</h2>

400 400

401[Claude Code hooks](/zh-TW/hooks-guide) 提供了一種方式來註冊自訂 shell 命令，以在執行時執行權限評估。當 Claude Code 進行工具呼叫時，PreToolUse hooks 在權限提示之前執行。hook 輸出可以拒絕工具呼叫、強制提示或跳過提示以讓呼叫繼續進行。401[Claude Code hooks](/docs/zh-TW/hooks-guide) 提供了一種方式來註冊自訂 shell 命令，以在執行時執行權限評估。當 Claude Code 進行工具呼叫時，PreToolUse hooks 在權限提示之前執行。hook 輸出可以拒絕工具呼叫、強制提示或跳過提示以讓呼叫繼續進行。

402 402

403Hook 決定不會繞過權限規則。Claude Code 會評估 deny 和 ask 規則，無論 PreToolUse hook 返回什麼：符合的 deny 規則會阻止呼叫，符合的 ask 規則即使在 hook 返回 `"allow"` 或 `"ask"` 時仍會提示。這保留了 [Manage permissions](#manage-permissions) 中描述的 deny 優先順序，包括在受管理設定中設定的 deny 規則。403Hook 決定不會繞過權限規則。Claude Code 會評估 deny 和 ask 規則，無論 PreToolUse hook 返回什麼：符合的 deny 規則會阻止呼叫，符合的 ask 規則即使在 hook 返回 `"allow"` 或 `"ask"` 時仍會提示。這保留了 [Manage permissions](#manage-permissions) 中描述的 deny 優先順序，包括在受管理設定中設定的 deny 規則。

404 404

405連接器工具[您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具在 hook 返回 `"allow"` 時仍會提示。405連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具在 hook 返回 `"allow"` 時仍會提示。

406 406

407阻止 hook 也優先於 allow 規則。以代碼 2 退出的 hook 會在評估權限規則之前停止工具呼叫，因此即使 allow 規則會允許呼叫，該阻止也會適用。若要執行所有 Bash 命令而無需提示，除了您想要阻止的少數幾個，請將 `"Bash"` 新增到您的 allow 清單，並註冊一個 PreToolUse hook 來拒絕那些特定命令。請參閱 [Block edits to protected files](/zh-TW/hooks-guide#block-edits-to-protected-files) 以取得您可以調整的 hook 指令碼。407阻止 hook 也優先於 allow 規則。以代碼 2 退出的 hook 會在評估權限規則之前停止工具呼叫，因此即使 allow 規則會允許呼叫，該阻止也會適用。若要執行所有 Bash 命令而無需提示，除了您想要阻止的少數幾個，請將 `"Bash"` 新增到您的 allow 清單，並註冊一個 PreToolUse hook 來拒絕那些特定命令。請參閱 [Block edits to protected files](/docs/zh-TW/hooks-guide#block-edits-to-protected-files) 以取得您可以調整的 hook 指令碼。

408 408

409<h2 id="working-directories">409<h2 id="working-directories">

410 工作目錄410 工作目錄

414 414

415* **在啟動期間**：使用 `--add-dir <path>` CLI 引數415* **在啟動期間**：使用 `--add-dir <path>` CLI 引數

416* **在工作階段期間**：使用 `/add-dir` 命令416* **在工作階段期間**：使用 `/add-dir` 命令

417* **持久設定**：新增到 [settings files](/zh-TW/settings#settings-files) 中的 `additionalDirectories`417* **持久設定**：新增到 [settings files](/docs/zh-TW/settings#settings-files) 中的 `additionalDirectories`

418 418

419其他目錄中的檔案遵循與原始工作目錄相同的權限規則：它們變成可讀的而無需提示，檔案編輯權限遵循目前的權限模式。419其他目錄中的檔案遵循與原始工作目錄相同的權限規則：它們變成可讀的而無需提示，檔案編輯權限遵循目前的權限模式。

420 420

421在 macOS 的背景工作階段中，當 Claude 需要讀取或寫入檔案時，工作階段主機會分別從您的終端機要求存取受保護的資料夾，例如 `~/Desktop`、`~/Documents` 和 `~/Downloads`；如果讀取失敗並出現 `Operation not permitted`，請參閱[如何授予背景工作階段對資料夾的存取權](/zh-TW/agent-view#background-sessions-can't-read-desktop-documents-or-downloads-on-macos)。421在 macOS 的背景工作階段中，當 Claude 需要讀取或寫入檔案時，工作階段主機會分別從您的終端機要求存取受保護的資料夾，例如 `~/Desktop`、`~/Documents` 和 `~/Downloads`；如果讀取失敗並出現 `Operation not permitted`，請參閱[如何授予背景工作階段對資料夾的存取權](/docs/zh-TW/agent-view#background-sessions-can't-read-desktop-documents-or-downloads-on-macos)。

422 422

423若要改變工作階段的主要工作目錄而不是新增另一個，請使用 [`/cd`](/zh-TW/commands)。`/cd` 命令需要 Claude Code v2.1.169 或更新版本。與 `/add-dir` 不同，它會重新定位工作階段：新目錄的 `CLAUDE.md` 會被載入，而 `--resume` 會從該處找到工作階段。423若要改變工作階段的主要工作目錄而不是新增另一個，請使用 [`/cd`](/docs/zh-TW/commands)。`/cd` 命令需要 Claude Code v2.1.169 或更新版本。與 `/add-dir` 不同，它會重新定位工作階段：新目錄的 `CLAUDE.md` 會被載入，而 `--resume` 會從該處找到工作階段。

424 424

425<h3 id="additional-directories-grant-file-access-not-configuration">425<h3 id="additional-directories-grant-file-access-not-configuration">

426 其他目錄授予檔案存取權，而非設定426 其他目錄授予檔案存取權，而非設定

434 434

435| 設定 | 從 `--add-dir` 載入 |435| 設定 | 從 `--add-dir` 載入 |

436| :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |436| :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |

438| `.claude/agents/` 中的 [Subagents](/zh-TW/sub-agents) | 是 |438| `.claude/agents/` 中的 [Subagents](/docs/zh-TW/sub-agents) | 是 |

439| `.claude/settings.json` 和 `.claude/settings.local.json` 中的 [Settings](/zh-TW/settings) | 僅 `enabledPlugins` 和 `extraKnownMarketplaces` 金鑰 |439| `.claude/settings.json` 和 `.claude/settings.local.json` 中的 [Settings](/docs/zh-TW/settings) | 僅 `enabledPlugins` 和 `extraKnownMarketplaces` 金鑰 |

440| [CLAUDE.md](/zh-TW/memory) 檔案、`.claude/rules/` 和 `CLAUDE.local.md` | 僅當設定 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` 時。`CLAUDE.local.md` 另外需要 `local` 設定來源，預設啟用 |440| [CLAUDE.md](/docs/zh-TW/memory) 檔案、`.claude/rules/` 和 `CLAUDE.local.md` | 僅當設定 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` 時。`CLAUDE.local.md` 另外需要 `local` 設定來源，預設啟用 |

441 441

442命令和輸出樣式是從目前工作目錄及其父目錄、您在 `~/.claude/` 的使用者目錄和受管理設定發現的。Hooks 和其他 `settings.json` 金鑰從目前工作目錄的 `.claude/` 資料夾載入，沒有父目錄回退，同時也從您的使用者 `~/.claude/settings.json` 和受管理設定載入。若要在專案間共享該設定，請使用以下方法之一：442命令和輸出樣式是從目前工作目錄及其父目錄、您在 `~/.claude/` 的使用者目錄和受管理設定發現的。Hooks 和其他 `settings.json` 金鑰從目前工作目錄的 `.claude/` 資料夾載入，沒有父目錄回退，同時也從您的使用者 `~/.claude/settings.json` 和受管理設定載入。若要在專案間共享該設定，請使用以下方法之一：

443 443

444* **使用者級別設定**：將檔案放在 `~/.claude/agents/`、`~/.claude/output-styles/` 或 `~/.claude/settings.json` 中，使其在每個專案中可用444* **使用者級別設定**：將檔案放在 `~/.claude/agents/`、`~/.claude/output-styles/` 或 `~/.claude/settings.json` 中，使其在每個專案中可用

445* **外掛**：將設定打包並分發為 [plugin](/zh-TW/plugins)，供團隊安裝445* **外掛**：將設定打包並分發為 [plugin](/docs/zh-TW/plugins)，供團隊安裝

446* **從設定目錄啟動**：從包含您想要的 `.claude/` 設定的目錄執行 Claude Code446* **從設定目錄啟動**：從包含您想要的 `.claude/` 設定的目錄執行 Claude Code

447 447

448<h2 id="how-permissions-interact-with-sandboxing">448<h2 id="how-permissions-interact-with-sandboxing">

449 權限如何與沙箱互動449 權限如何與沙箱互動

450</h2>450</h2>

451 451

452權限和 [sandboxing](/zh-TW/sandboxing) 是互補的安全層：452權限和 [sandboxing](/docs/zh-TW/sandboxing) 是互補的安全層：

453 453

454* **權限**控制 Claude Code 可以使用哪些工具以及它可以存取哪些檔案或網域。它們適用於所有工具，包括 Bash、Read、Edit、WebFetch 和 MCP。454* **權限**控制 Claude Code 可以使用哪些工具以及它可以存取哪些檔案或網域。它們適用於所有工具，包括 Bash、Read、Edit、WebFetch 和 MCP。

455* **沙箱**提供作業系統級別的強制執行，限制 Bash 工具的檔案系統和網路存取。它僅適用於 Bash 命令及其子程序。455* **沙箱**提供作業系統級別的強制執行，限制 Bash 工具的檔案系統和網路存取。它僅適用於 Bash 命令及其子程序。

458 458

459* 權限 deny 規則阻止 Claude 甚至嘗試存取受限資源459* 權限 deny 規則阻止 Claude 甚至嘗試存取受限資源

460* 沙箱限制防止 Bash 命令到達定義邊界外的資源，即使提示注入繞過 Claude 的決策制定460* 沙箱限制防止 Bash 命令到達定義邊界外的資源，即使提示注入繞過 Claude 的決策制定

461* 沙箱中的檔案系統限制結合 [`sandbox.filesystem`](/zh-TW/sandboxing) 設定與 Read 和 Edit deny 規則；兩者都合併到最終沙箱邊界中461* 沙箱中的檔案系統限制結合 [`sandbox.filesystem`](/docs/zh-TW/sandboxing) 設定與 Read 和 Edit deny 規則；兩者都合併到最終沙箱邊界中

462* 網路限制結合 WebFetch 權限規則與沙箱的 `allowedDomains` 和 `deniedDomains` 清單462* 網路限制結合 WebFetch 權限規則與沙箱的 `allowedDomains` 和 `deniedDomains` 清單

463 463

464當沙箱啟用 `autoAllowBashIfSandboxed: true`（預設值）時，沙箱化 Bash 命令無需提示即可執行，即使您的權限包括 bare `Bash` ask 規則，或 [等效的 `Bash(*)` 形式](#match-all-uses-of-a-tool)：沙箱邊界替代整個工具提示。這些檢查仍然適用：464當沙箱啟用 `autoAllowBashIfSandboxed: true`（預設值）時，沙箱化 Bash 命令無需提示即可執行，即使您的權限包括 bare `Bash` ask 規則，或 [等效的 `Bash(*)` 形式](#match-all-uses-of-a-tool)：沙箱邊界替代整個工具提示。這些檢查仍然適用：

467* 明確的 deny 規則仍然適用467* 明確的 deny 規則仍然適用

468* 針對 `/`、您的主目錄或其他關鍵系統路徑的 `rm` 或 `rmdir` 命令仍然會觸發提示468* 針對 `/`、您的主目錄或其他關鍵系統路徑的 `rm` 或 `rmdir` 命令仍然會觸發提示

469 469

470不會在沙箱中執行的命令（例如排除的命令）會遵守 bare `Bash` ask 規則。請參閱 [sandbox modes](/zh-TW/sandboxing#sandbox-modes) 以變更此行為。470不會在沙箱中執行的命令（例如排除的命令）會遵守 bare `Bash` ask 規則。請參閱 [sandbox modes](/docs/zh-TW/sandboxing#sandbox-modes) 以變更此行為。

471 471

472<h2 id="managed-settings">472<h2 id="managed-settings">

473 受管理設定473 受管理設定

474</h2>474</h2>

475 475

476對於需要集中控制 Claude Code 設定的組織，管理員可以部署無法被使用者或專案設定覆蓋的受管理設定。這些原則設定遵循與一般設定檔案相同的格式，可以透過 MDM/OS 級別原則、受管理設定檔案、[server-managed settings](/zh-TW/server-managed-settings) 或自我託管的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 傳遞。請參閱 [settings files](/zh-TW/settings#settings-files) 以了解傳遞機制和檔案位置。476對於需要集中控制 Claude Code 設定的組織，管理員可以部署無法被使用者或專案設定覆蓋的受管理設定。這些原則設定遵循與一般設定檔案相同的格式，可以透過 MDM/OS 級別原則、受管理設定檔案、[server-managed settings](/docs/zh-TW/server-managed-settings) 或自我託管的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 傳遞。請參閱 [settings files](/docs/zh-TW/settings#settings-files) 以了解傳遞機制和檔案位置。

477 477

478<h3 id="managed-only-settings">478<h3 id="managed-only-settings">

479 僅受管理的設定479 僅受管理的設定

482以下設定僅在受管理設定中有效。將它們放在使用者或專案設定檔案中沒有效果。482以下設定僅在受管理設定中有效。將它們放在使用者或專案設定檔案中沒有效果。

483 483

484| 設定 | 描述 |484| 設定 | 描述 |

485| :--------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |485| :--------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

486| `allowAllClaudeAiMcps` | 當為 `true` 時，claude.ai 連接器會與已部署的 `managed-mcp.json` 一起載入，而不是被其獨佔控制所抑制。請參閱 [Managed MCP configuration](/zh-TW/managed-mcp) |486| `allowAllClaudeAiMcps` | 當為 `true` 時，claude.ai 連接器會與已部署的 `managed-mcp.json` 一起載入，而不是被其獨佔控制所抑制。請參閱 [Managed MCP configuration](/docs/zh-TW/managed-mcp) |

487| `allowedChannelPlugins` | 可能推送訊息的頻道外掛的允許清單。設定時替換預設 Anthropic 允許清單。需要 `channelsEnabled: true`。請參閱 [Restrict which channel plugins can run](/zh-TW/channels#restrict-which-channel-plugins-can-run) |487| `allowedChannelPlugins` | 可能推送訊息的頻道外掛的允許清單。設定時替換預設 Anthropic 允許清單。需要 `channelsEnabled: true`。請參閱 [Restrict which channel plugins can run](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) |

488| `allowManagedHooksOnly` | 當為 `true` 時，僅載入受管理 hooks、SDK hooks 和在受管理設定 `enabledPlugins` 中強制啟用的外掛中的 hooks。使用者、專案和所有其他外掛 hooks 被阻止 |488| `allowManagedHooksOnly` | 當為 `true` 時，僅載入受管理 hooks、SDK hooks 和在受管理設定 `enabledPlugins` 中強制啟用的外掛中的 hooks。使用者、專案和所有其他外掛 hooks 被阻止 |

489| `allowManagedMcpServersOnly` | 當為 `true` 時，僅尊重受管理設定中的 `allowedMcpServers`。`deniedMcpServers` 仍然從所有來源合併。請參閱 [Managed MCP configuration](/zh-TW/managed-mcp) |489| `allowManagedMcpServersOnly` | 當為 `true` 時，僅尊重受管理設定中的 `allowedMcpServers`。`deniedMcpServers` 仍然從所有來源合併。請參閱 [Managed MCP configuration](/docs/zh-TW/managed-mcp) |

490| `allowManagedPermissionRulesOnly` | 當為 `true` 時，防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅套用受管理設定中的規則。不影響 MCP 伺服器允許清單；如需設定，請設定 `allowManagedMcpServersOnly` |490| `allowManagedPermissionRulesOnly` | 當為 `true` 時，防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅套用受管理設定中的規則。不影響 MCP 伺服器允許清單；如需設定，請設定 `allowManagedMcpServersOnly` |

491| `blockedMarketplaces` | 市場來源的封鎖清單。在下載前檢查被封鎖的來源，因此它們永遠不會接觸檔案系統。請參閱 [managed marketplace restrictions](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) |491| `blockedMarketplaces` | 市場來源的封鎖清單。在下載前檢查被封鎖的來源，因此它們永遠不會接觸檔案系統。請參閱 [managed marketplace restrictions](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) |

492| `channelsEnabled` | 允許組織使用 [channels](/zh-TW/channels)。請參閱 [enterprise controls](/zh-TW/channels#enterprise-controls) 以了解每個方案的預設值 |492| `channelsEnabled` | 允許組織使用 [channels](/docs/zh-TW/channels)。請參閱 [enterprise controls](/docs/zh-TW/channels#enterprise-controls) 以了解每個方案的預設值 |

493| `disableSideloadFlags` | {/* min-version: 2.1.193 */}在啟動時拒絕 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 旗標。沒有這個設定，使用者可以透過傳遞這些旗標來為單次執行繞過 `strictKnownMarketplaces`。請參閱 [`disableSideloadFlags`](/zh-TW/settings#available-settings)。需要 Claude Code v2.1.193 或更新版本 |493| `disableSideloadFlags` | 在啟動時拒絕 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 旗標。沒有這個設定，使用者可以透過傳遞這些旗標來為單次執行繞過 `strictKnownMarketplaces`。請參閱 [`disableSideloadFlags`](/docs/zh-TW/settings#available-settings)。需要 Claude Code v2.1.193 或更新版本 |

494| `forceRemoteSettingsRefresh` | 當為 `true` 時，阻止 CLI 啟動直到遠端受管理設定被新鮮擷取，如果擷取失敗則退出。請參閱 [fail-closed enforcement](/zh-TW/server-managed-settings#enforce-fail-closed-startup) |494| `forceRemoteSettingsRefresh` | 當為 `true` 時，阻止 CLI 啟動直到遠端受管理設定被新鮮擷取，如果擷取失敗則退出。請參閱 [fail-closed enforcement](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup) |

497| `sandbox.network.allowManagedDomainsOnly` | 當為 `true` 時，僅尊重來自受管理設定的 `allowedDomains` 和 `WebFetch(domain:...)` allow 規則。非允許的網域會自動被阻止，無需提示使用者。被拒絕的網域仍然從所有來源合併 |497| `sandbox.network.allowManagedDomainsOnly` | 當為 `true` 時，僅尊重來自受管理設定的 `allowedDomains` 和 `WebFetch(domain:...)` allow 規則。非允許的網域會自動被阻止，無需提示使用者。被拒絕的網域仍然從所有來源合併 |

498| `strictKnownMarketplaces` | 控制使用者可以新增和安裝外掛的外掛市場來源。請參閱 [managed marketplace restrictions](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) |498| `strictKnownMarketplaces` | 控制使用者可以新增和安裝外掛的外掛市場來源。請參閱 [managed marketplace restrictions](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) |

499| `strictPluginOnlyCustomization` | 阻止 skills、agents、hooks 和 MCP servers 來自使用者和專案來源，因此它們只能來自外掛或受管理設定。`true` 鎖定所有四個表面；像 `["skills", "hooks"]` 這樣的陣列僅鎖定命名的表面。請參閱 [`strictPluginOnlyCustomization`](/zh-TW/settings#strictpluginonlycustomization) |499| `strictPluginOnlyCustomization` | 阻止 skills、agents、hooks 和 MCP servers 來自使用者和專案來源，因此它們只能來自外掛或受管理設定。`true` 鎖定所有四個表面；像 `["skills", "hooks"]` 這樣的陣列僅鎖定命名的表面。請參閱 [`strictPluginOnlyCustomization`](/docs/zh-TW/settings#strictpluginonlycustomization) |

500| `wslInheritsWindowsSettings` | 當在 Windows HKLM 登錄機碼或 `C:\Program Files\ClaudeCode\managed-settings.json` 中為 `true` 時，WSL 從 Windows 原則鏈以及 `/etc/claude-code` 讀取受管理設定。請參閱 [Settings files](/zh-TW/settings#settings-files) |500| `wslInheritsWindowsSettings` | 當在 Windows HKLM 登錄機碼或 `C:\Program Files\ClaudeCode\managed-settings.json` 中為 `true` 時，WSL 從 Windows 原則鏈以及 `/etc/claude-code` 讀取受管理設定。請參閱 [Settings files](/docs/zh-TW/settings#settings-files) |

501 501

502`disableBypassPermissionsMode` 通常放在受管理設定中以強制執行組織原則，但它可以從任何範圍工作。使用者可以在自己的設定中設定它以鎖定自己的繞過模式。502`disableBypassPermissionsMode` 通常放在受管理設定中以強制執行組織原則，但它可以從任何範圍工作。使用者可以在自己的設定中設定它以鎖定自己的繞過模式。

503 503

504<Note>504<Note>

505 在 Team 和 Enterprise 方案上，管理員在 [Claude Code admin settings](https://claude.ai/admin-settings/claude-code) 中啟用或停用 [Remote Control](/zh-TW/remote-control) 和 [web sessions](/zh-TW/claude-code-on-the-web) 組織範圍內。Remote Control 可以另外透過 [`disableRemoteControl`](/zh-TW/settings#available-settings) 受管理設定按裝置停用。Web sessions 沒有按裝置受管理設定金鑰。505 在 Team 和 Enterprise 方案上，管理員在 [Claude Code admin settings](https://claude.ai/admin-settings/claude-code) 中啟用或停用 [Remote Control](/docs/zh-TW/remote-control) 和 [web sessions](/docs/zh-TW/claude-code-on-the-web) 組織範圍內。Remote Control 可以另外透過 [`disableRemoteControl`](/docs/zh-TW/settings#available-settings) 受管理設定按裝置停用。Web sessions 沒有按裝置受管理設定金鑰。

506</Note>506</Note>

507 507

508<h2 id="settings-precedence">508<h2 id="settings-precedence">

509 設定優先順序509 設定優先順序

510</h2>510</h2>

511 511

512權限規則遵循與所有其他 Claude Code 設定相同的 [settings precedence](/zh-TW/settings#settings-precedence)：512權限規則遵循與所有其他 Claude Code 設定相同的 [settings precedence](/docs/zh-TW/settings#settings-precedence)：

513 513

5141. **受管理設定**：無法被任何其他級別覆蓋，包括命令列引數5141. **受管理設定**：無法被任何其他級別覆蓋，包括命令列引數

5152. **命令列引數**：臨時工作階段覆蓋5152. **命令列引數**：臨時工作階段覆蓋

521 521

522相同的規則也適用於設定範圍：如果使用者設定允許某項權限而專案設定拒絕它，deny 規則會阻止它。反之亦然：使用者級別的 deny 會阻止專案級別的 allow，因為來自任何範圍的 deny 規則會在 allow 規則之前進行評估。522相同的規則也適用於設定範圍：如果使用者設定允許某項權限而專案設定拒絕它，deny 規則會阻止它。反之亦然：使用者級別的 deny 會阻止專案級別的 allow，因為來自任何範圍的 deny 規則會在 allow 規則之前進行評估。

523 523

524嵌入主機可以在 [`parentSettingsBehavior`](/zh-TW/settings#settings-precedence) 設定為 `"merge"` 時，透過 SDK `managedSettings` 選項提供額外的受管理原則；嵌入器值可以收緊原則但不能放寬它。524嵌入主機可以在 [`parentSettingsBehavior`](/docs/zh-TW/settings#settings-precedence) 設定為 `"merge"` 時，透過 SDK `managedSettings` 選項提供額外的受管理原則；嵌入器值可以收緊原則但不能放寬它。

525 525

526<h2 id="project-allow-rules-and-workspace-trust">526<h2 id="project-allow-rules-and-workspace-trust">

527 專案允許規則和工作區信任527 專案允許規則和工作區信任

528</h2>528</h2>

529 529

530`permissions.allow` 規則和專案 `.claude/settings.json` 中的 `permissions.additionalDirectories` 項目會授予功能，因此 Claude Code 只有在您接受該工作區的[工作區信任對話框](/zh-TW/security#additional-safeguards)後才會套用這些規則。在此之前，Claude Code 會讀取規則但不會套用它們。信任對話框會列出資料夾將授予的允許規則和其他目錄，以便您在接受前進行檢查。`deny` 和 `ask` 規則不受影響，因為它們只會限制。530`permissions.allow` 規則和專案 `.claude/settings.json` 中的 `permissions.additionalDirectories` 項目會授予功能，因此 Claude Code 只有在您接受該工作區的[工作區信任對話框](/docs/zh-TW/security#additional-safeguards)後才會套用這些規則。在此之前，Claude Code 會讀取規則但不會套用它們。信任對話框會列出資料夾將授予的允許規則和其他目錄，以便您在接受前進行檢查。`deny` 和 `ask` 規則不受影響，因為它們只會限制。

531 531

532Claude Code 按工作區儲存信任，以 git 儲存庫根目錄為鍵，或在儲存庫外，以您啟動 Claude Code 的目錄為鍵。當您在主目錄中啟動時，信任僅在目前工作階段內保持，不會寫入磁碟；請參閱[額外保護措施](/zh-TW/security#additional-safeguards)說明。信任父目錄不會套用巢狀專案的允許規則。532Claude Code 按工作區儲存信任，以 git 儲存庫根目錄為鍵，或在儲存庫外，以您啟動 Claude Code 的目錄為鍵。當您在主目錄中啟動時，信任僅在目前工作階段內保持，不會寫入磁碟；請參閱[額外保護措施](/docs/zh-TW/security#additional-safeguards)說明。信任父目錄不會套用巢狀專案的允許規則。

533 533

534`.claude/settings.local.json` 是您自己的檔案，因此工作區信任檢查通常不適用於它。當儲存庫可能已提供該檔案時，例如當它被提交到 git 或 `.claude` 是符號連結時，其允許規則和其他目錄會經過信任檢查，就像專案設定一樣。534`.claude/settings.local.json` 是您自己的檔案，因此工作區信任檢查通常不適用於它。當儲存庫可能已提供該檔案時，例如當它被提交到 git 或 `.claude` 是符號連結時，其允許規則和其他目錄會經過信任檢查，就像專案設定一樣。

535 535

538`.claude/settings.local.json` 中的允許規則和其他目錄在兩種情況下也可以在沒有工作區信任的情況下套用：538`.claude/settings.local.json` 中的允許規則和其他目錄在兩種情況下也可以在沒有工作區信任的情況下套用：

539 539

540* 您啟動 Claude Code 的目錄不在 git 儲存庫內。540* 您啟動 Claude Code 的目錄不在 git 儲存庫內。

541* 工作階段在您自己的設定主目錄中執行：您的主目錄或任何您已設定為 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars) 的 `.claude` 子目錄。541* 工作階段在您自己的設定主目錄中執行：您的主目錄或任何您已設定為 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 的 `.claude` 子目錄。

542 542

543在這兩種情況下，該檔案都是您建立的，而不是儲存庫可能提供的檔案，而儲存庫提交的 `.claude/settings.local.json` 仍然需要工作區信任。版本 2.1.196 至 2.1.199 在這些工作區中將該檔案視為儲存庫提供的檔案，忽略其允許規則，並向 stderr 列印[`this workspace has not been trusted`](/zh-TW/errors#workspace-has-not-been-trusted)警告。上述兩個例外與 v2.1.195 及更早版本相符，並在 v2.1.200 中恢復。543在這兩種情況下，該檔案都是您建立的，而不是儲存庫可能提供的檔案，而儲存庫提交的 `.claude/settings.local.json` 仍然需要工作區信任。版本 2.1.196 至 2.1.199 在這些工作區中將該檔案視為儲存庫提供的檔案，忽略其允許規則，並向 stderr 列印[`this workspace has not been trusted`](/docs/zh-TW/errors#workspace-has-not-been-trusted)警告。上述兩個例外與 v2.1.195 及更早版本相符，並在 v2.1.200 中恢復。

544 544

545同樣從 v2.1.200 開始，工作區的允許規則或其他目錄仍未被套用，但由於父目錄已被信任而從未顯示信任對話框，在您下次以互動方式在該處啟動 Claude Code 時會顯示對話框。對話框提供兩個選擇：545同樣從 v2.1.200 開始，工作區的允許規則或其他目錄仍未被套用，但由於父目錄已被信任而從未顯示信任對話框，在您下次以互動方式在該處啟動 Claude Code 時會顯示對話框。對話框提供兩個選擇：

546 546

547* **Yes, I trust this folder**：儲存該工作區的信任並在同一工作階段中套用規則。547* **Yes, I trust this folder**：儲存該工作區的信任並在同一工作階段中套用規則。

548* **No, continue without these permissions**：繼續工作，忽略這些規則。對話框將在下一個工作階段中再次出現。548* **No, continue without these permissions**：繼續工作，忽略這些規則。對話框將在下一個工作階段中再次出現。

549 549

550在[非互動模式](/zh-TW/headless)中使用 `-p`，不會出現對話框，規則保持被忽略。550在[非互動模式](/docs/zh-TW/headless)中使用 `-p`，不會出現對話框，規則保持被忽略。

551 551

552<h2 id="example-configurations">552<h2 id="example-configurations">

553 範例設定553 範例設定

559 另請參閱559 另請參閱

560</h2>560</h2>

561 561

562* [Settings](/zh-TW/settings)：完整設定參考，包括權限設定表562* [Settings](/docs/zh-TW/settings)：完整設定參考，包括權限設定表

563* [Configure auto mode](/zh-TW/auto-mode-config)：告訴 auto mode 分類器您的組織信任哪些基礎設施563* [Configure auto mode](/docs/zh-TW/auto-mode-config)：告訴 auto mode 分類器您的組織信任哪些基礎設施

564* [Sandboxing](/zh-TW/sandboxing)：Bash 命令的作業系統級別檔案系統和網路隔離564* [Sandboxing](/docs/zh-TW/sandboxing)：Bash 命令的作業系統級別檔案系統和網路隔離

565* [Authentication](/zh-TW/authentication)：設定使用者對 Claude Code 的存取565* [Authentication](/docs/zh-TW/authentication)：設定使用者對 Claude Code 的存取

566* [Security](/zh-TW/security)：安全防護措施和最佳實踐566* [Security](/docs/zh-TW/security)：安全防護措施和最佳實踐

567* [Hooks](/zh-TW/hooks-guide)：自動化工作流程並擴展權限評估567* [Hooks](/docs/zh-TW/hooks-guide)：自動化工作流程並擴展權限評估

plugin-hints.md +7 −7

Details

10 10

11Claude Code 在將命令輸出發送給模型之前會從中移除提示行，因此標記永遠不會出現在對話中，也不會計入代幣使用量。該協議不需要額外命令，也不會改變您的 CLI 為 Claude Code 外部使用者列印的內容。11Claude Code 在將命令輸出發送給模型之前會從中移除提示行，因此標記永遠不會出現在對話中，也不會計入代幣使用量。該協議不需要額外命令，也不會改變您的 CLI 為 Claude Code 外部使用者列印的內容。

12 12

~~13本頁面適用於 CLI 和 SDK 維護者。如果您正在尋找安裝外掛程式，請參閱[探索和安裝外掛程式](/zh-TW/discover-plugins)。~~13本頁面適用於 CLI 和 SDK 維護者。如果您正在尋找安裝外掛程式，請參閱[探索和安裝外掛程式](/docs/zh-TW/discover-plugins)。

14 14

15<h2 id="how-it-works">15<h2 id="how-it-works">

16 運作方式16 運作方式

17</h2>17</h2>

18 18

19Claude Code 為透過 Bash 和 PowerShell 工具執行的每個命令，以及 [hook](/zh-TW/hooks) 命令設定 [`CLAUDECODE`](/zh-TW/env-vars) 環境變數為 `1`。{/* min-version: 2.1.172 */}從 v2.1.172 開始，它也會在這些相同的子程序中將 [`CLAUDE_CODE_CHILD_SESSION`](/zh-TW/env-vars) 設定為 `1`。當您的 CLI 看到其中一個變數時，它會向 stderr 寫入自閉合的 `<claude-code-hint />` 標籤。在 hook 命令中，提示標籤會被移除並忽略。只有 Bash 和 PowerShell 工具輸出會觸發安裝提示。19Claude Code 為透過 Bash 和 PowerShell 工具執行的每個命令，以及 [hook](/docs/zh-TW/hooks) 命令設定 [`CLAUDECODE`](/docs/zh-TW/env-vars) 環境變數為 `1`。從 v2.1.172 開始，它也會在這些相同的子程序中將 [`CLAUDE_CODE_CHILD_SESSION`](/docs/zh-TW/env-vars) 設定為 `1`。當您的 CLI 看到其中一個變數時，它會向 stderr 寫入自閉合的 `<claude-code-hint />` 標籤。在 hook 命令中，提示標籤會被移除並忽略。只有 Bash 和 PowerShell 工具輸出會觸發安裝提示。

20 20

21當 Claude Code 接收到命令輸出時，它會：21當 Claude Code 接收到命令輸出時，它會：

22 22

36在環境變數上設定發出條件，以便標記不太可能在人類直接執行您的 CLI 時出現，然後將標籤寫入 stderr 的單獨一行。選擇要檢查的變數：36在環境變數上設定發出條件，以便標記不太可能在人類直接執行您的 CLI 時出現，然後將標籤寫入 stderr 的單獨一行。選擇要檢查的變數：

37 37

38* `CLAUDECODE`：在每個 Claude Code 版本上設定，因此可以到達最多的工作階段。它也在 Claude Code 啟動的 tmux 工作階段和 stdio MCP 伺服器子程序中設定，IDE 擴充功能在其整合終端中設定它，人類可能在那裡直接執行您的 CLI。38* `CLAUDECODE`：在每個 Claude Code 版本上設定，因此可以到達最多的工作階段。它也在 Claude Code 啟動的 tmux 工作階段和 stdio MCP 伺服器子程序中設定，IDE 擴充功能在其整合終端中設定它，人類可能在那裡直接執行您的 CLI。

39* {/* min-version: 2.1.172 */}`CLAUDE_CODE_CHILD_SESSION`：僅在 Claude Code 本身產生的子程序中設定，例如工具呼叫、hook 命令和[狀態列](/zh-TW/statusline)命令，因此標籤通常不會到達人類終端。在工作階段內啟動的長期程序（例如 tmux 伺服器）會捕獲該變數，因此稍後從該程序啟動的 shell 仍會顯示原始標籤。需要 Claude Code v2.1.172 或更新版本，因此舊版本上的工作階段會遺漏提示。39* `CLAUDE_CODE_CHILD_SESSION`：僅在 Claude Code 本身產生的子程序中設定，例如工具呼叫、hook 命令和[狀態列](/docs/zh-TW/statusline)命令，因此標籤通常不會到達人類終端。在工作階段內啟動的長期程序（例如 tmux 伺服器）會捕獲該變數，因此稍後從該程序啟動的 shell 仍會顯示原始標籤。需要 Claude Code v2.1.172 或更新版本，因此舊版本上的工作階段會遺漏提示。

40 40

41以下範例在 `CLAUDECODE` 上設定條件以達到最大覆蓋範圍，並為官方市場中名為 `example-cli` 的外掛程式發出提示：41以下範例在 `CLAUDECODE` 上設定條件以達到最大覆蓋範圍，並為官方市場中名為 `example-cli` 的外掛程式發出提示：

42 42

158 將您的外掛程式納入官方市場158 將您的外掛程式納入官方市場

159</h2>159</h2>

160 160

161提示協議僅對列在官方 Anthropic 市場 `claude-plugins-official` 中的外掛程式生效。Anthropic 自行決定策劃該市場，應用程式內提交表單會將外掛程式新增到[社群市場](/zh-TW/plugins#submit-your-plugin-to-the-community-marketplace)，提示協議不會檢查該市場。如果您正在與 Anthropic 合作夥伴聯絡人合作，請與他們聯繫以協調官方市場列表。161提示協議僅對列在官方 Anthropic 市場 `claude-plugins-official` 中的外掛程式生效。Anthropic 自行決定策劃該市場，應用程式內提交表單會將外掛程式新增到[社群市場](/docs/zh-TW/plugins#submit-your-plugin-to-the-community-marketplace)，提示協議不會檢查該市場。如果您正在與 Anthropic 合作夥伴聯絡人合作，請與他們聯繫以協調官方市場列表。

162 162

163<h2 id="see-also">163<h2 id="see-also">

164 另請參閱164 另請參閱

165</h2>165</h2>

166 166

167* [建立外掛程式](/zh-TW/plugins)：建立您的 CLI 推薦的外掛程式167* [建立外掛程式](/docs/zh-TW/plugins)：建立您的 CLI 推薦的外掛程式

168* [建立和發佈外掛程式市場](/zh-TW/plugin-marketplaces)：在官方市場外託管外掛程式168* [建立和發佈外掛程式市場](/docs/zh-TW/plugin-marketplaces)：在官方市場外託管外掛程式

169* [環境變數](/zh-TW/env-vars)：`CLAUDECODE` 和相關變數的完整參考169* [環境變數](/docs/zh-TW/env-vars)：`CLAUDECODE` 和相關變數的完整參考

plugin-marketplaces.md +36 −36

Details

8 8

9**plugin marketplace** 是一個目錄，可讓您將 plugin 分發給他人。Marketplace 提供集中式發現、版本追蹤、自動更新，以及對多種來源類型（包括 git 儲存庫和本機路徑）的支援。本指南將向您展示如何建立自己的 marketplace，以與您的團隊或社群分享 plugin。9**plugin marketplace** 是一個目錄，可讓您將 plugin 分發給他人。Marketplace 提供集中式發現、版本追蹤、自動更新，以及對多種來源類型（包括 git 儲存庫和本機路徑）的支援。本指南將向您展示如何建立自己的 marketplace，以與您的團隊或社群分享 plugin。

10 10

~~11想要從現有 marketplace 安裝 plugin？請參閱[探索並安裝預先建立的 plugin](/zh-TW/discover-plugins)。~~11想要從現有 marketplace 安裝 plugin？請參閱[探索並安裝預先建立的 plugin](/docs/zh-TW/discover-plugins)。

12 12

13<h2 id="overview">13<h2 id="overview">

14 概述14 概述

16 16

17建立並分發 marketplace 涉及：17建立並分發 marketplace 涉及：

18 18

191. **建立 plugin**：使用 skills、agents、hooks、MCP servers 或 LSP servers 建立一個或多個 plugin。本指南假設您已經有要分發的 plugin；有關如何建立 plugin 的詳細資訊，請參閱[建立 plugin](/zh-TW/plugins)。191. **建立 plugin**：使用 skills、agents、hooks、MCP servers 或 LSP servers 建立一個或多個 plugin。本指南假設您已經有要分發的 plugin；有關如何建立 plugin 的詳細資訊，請參閱[建立 plugin](/docs/zh-TW/plugins)。

202. **建立 marketplace 檔案**：定義 `marketplace.json`，列出您的 plugin 及其位置。請參閱[建立 marketplace 檔案](#create-the-marketplace-file)。202. **建立 marketplace 檔案**：定義 `marketplace.json`，列出您的 plugin 及其位置。請參閱[建立 marketplace 檔案](#create-the-marketplace-file)。

213. **託管 marketplace**：推送到 GitHub、GitLab 或其他 git 主機。請參閱[託管並分發 marketplace](#host-and-distribute-marketplaces)。213. **託管 marketplace**：推送到 GitHub、GitLab 或其他 git 主機。請參閱[託管並分發 marketplace](#host-and-distribute-marketplaces)。

~~224. **與使用者分享**：使用者使用 `/plugin marketplace add` 新增您的 marketplace 並安裝個別 plugin。請參閱[探索並安裝 plugin](/zh-TW/discover-plugins)。~~224. **與使用者分享**：使用者使用 `/plugin marketplace add` 新增您的 marketplace 並安裝個別 plugin。請參閱[探索並安裝 plugin](/docs/zh-TW/discover-plugins)。

23 23

24一旦您的 marketplace 上線，您可以透過推送變更到您的儲存庫來更新它。使用者使用 `/plugin marketplace update` 重新整理其本機副本。24一旦您的 marketplace 上線，您可以透過推送變更到您的儲存庫來更新它。使用者使用 `/plugin marketplace update` 重新整理其本機副本。

25 25

110 </Step>110 </Step>

111</Steps>111</Steps>

112 112

113若要深入瞭解 plugin 可以執行的操作，包括 hooks、agents、MCP servers 和 LSP servers，請參閱 [Plugins](/zh-TW/plugins)。113若要深入瞭解 plugin 可以執行的操作，包括 hooks、agents、MCP servers 和 LSP servers，請參閱 [Plugins](/docs/zh-TW/plugins)。

114 114

115<Note>115<Note>

116 **plugin 如何安裝**：當使用者安裝 plugin 時，Claude Code 會將 plugin 目錄複製到快取位置。這表示 plugin 無法使用 `../shared-utils` 之類的路徑參考其目錄外的檔案，因為這些檔案不會被複製。116 **plugin 如何安裝**：當使用者安裝 plugin 時，Claude Code 會將 plugin 目錄複製到快取位置。這表示 plugin 無法使用 `../shared-utils` 之類的路徑參考其目錄外的檔案，因為這些檔案不會被複製。

117 117

118 如果您需要在 plugin 之間共享檔案，請使用符號連結。有關詳細資訊，請參閱 [Plugin caching and file resolution](/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。118 如果您需要在 plugin 之間共享檔案，請使用符號連結。有關詳細資訊，請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。

119</Note>119</Note>

120 120

121<h2 id="create-the-marketplace-file">121<h2 id="create-the-marketplace-file">

172<Note>172<Note>

173 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`healthcare`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留這些名稱可防止第三方 marketplace 將自己冒充為 Anthropic 發佈的來源。173 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`healthcare`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留這些名稱可防止第三方 marketplace 將自己冒充為 Anthropic 發佈的來源。

174 174

175 Claude Code 每次載入 marketplace 時都會重新檢查保留名稱，而不僅在您新增 marketplace 時檢查。在名稱成為保留名稱之前以其中一個名稱註冊的 marketplace 會停止載入，並報告它是[從不受信任的來源註冊](/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。移除該 marketplace，並從官方 Anthropic 來源重新新增它。受新保留名稱影響的第三方 marketplace 在您以不同名稱重新新增它後立即再次載入。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 未被保留，已在保留名稱下註冊的 marketplace 繼續載入。175 Claude Code 每次載入 marketplace 時都會重新檢查保留名稱，而不僅在您新增 marketplace 時檢查。在名稱成為保留名稱之前以其中一個名稱註冊的 marketplace 會停止載入，並報告它是[從不受信任的來源註冊](/docs/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。移除該 marketplace，並從官方 Anthropic 來源重新新增它。受新保留名稱影響的第三方 marketplace 在您以不同名稱重新新增它後立即再次載入。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 未被保留，已在保留名稱下註冊的 marketplace 繼續載入。

176</Note>176</Note>

177 177

178<h3 id="owner-fields">178<h3 id="owner-fields">

189</h3>189</h3>

190 190

191| 欄位 | 類型 | 描述 |191| 欄位 | 類型 | 描述 |

192| :------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |192| :------------------------------------ | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

197| `allowCrossMarketplaceDependenciesOn` | array | 此 marketplace 中的 plugin 可能依賴的其他 marketplace。來自此處未列出的 marketplace 的相依性在安裝時被阻止。請參閱[依賴來自另一個 marketplace 的 plugin](/zh-TW/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |197| `allowCrossMarketplaceDependenciesOn` | array | 此 marketplace 中的 plugin 可能依賴的其他 marketplace。來自此處未列出的 marketplace 的相依性在安裝時被阻止。請參閱[依賴來自另一個 marketplace 的 plugin](/docs/zh-TW/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |

198| `renames` | object | {/* min-version: 2.1.193 */}從前一個 plugin `name` 對應到其目前名稱，或對應到 `null`（如果 plugin 已移除）的對應。當您重新命名或移除 `plugins` 中的項目時，可讓現有使用者自動遷移。請參閱[重新命名或移除 plugin](#rename-or-remove-a-plugin)。需要 Claude Code v2.1.193 或更新版本。 |198| `renames` | object | 從前一個 plugin `name` 對應到其目前名稱，或對應到 `null`（如果 plugin 已移除）的對應。當您重新命名或移除 `plugins` 中的項目時，可讓現有使用者自動遷移。請參閱[重新命名或移除 plugin](#rename-or-remove-a-plugin)。需要 Claude Code v2.1.193 或更新版本。 |

199 199

200`description` 和 `version` 也可在 `metadata` 下接受，以保持向後相容性。200`description` 和 `version` 也可在 `metadata` 下接受，以保持向後相容性。

201 201

203 Plugin 項目203 Plugin 項目

204</h2>204</h2>

205 205

206`plugins` 陣列中的每個 plugin 項目描述一個 plugin 及其位置。您可以包含 [plugin manifest 架構](/zh-TW/plugins-reference#plugin-manifest-schema)中的任何欄位（如 `description`、`version`、`author`、`commands`、`hooks` 等），加上這些 marketplace 特定欄位：`source`、`category`、`tags`、`strict` 和 `relevance`。206`plugins` 陣列中的每個 plugin 項目描述一個 plugin 及其位置。您可以包含 [plugin manifest 架構](/docs/zh-TW/plugins-reference#plugin-manifest-schema)中的任何欄位（如 `description`、`version`、`author`、`commands`、`hooks` 等），加上這些 marketplace 特定欄位：`source`、`category`、`tags`、`strict` 和 `relevance`。

207 207

208<h3 id="required-fields-2">208<h3 id="required-fields-2">

209 必需欄位209 必需欄位

221**標準中繼資料欄位：**221**標準中繼資料欄位：**

222 222

223| 欄位 | 類型 | 描述 |223| 欄位 | 類型 | 描述 |

224| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |224| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

225| `displayName` | string | {/* min-version: 2.1.143 */}在 UI 介面中顯示的人類可讀名稱。當省略時回退到 `name`。可以包含空格和任何大小寫。不用於命名空間或查詢。需要 Claude Code v2.1.143 或更新版本。 |225| `displayName` | string | 在 UI 介面中顯示的人類可讀名稱。當省略時回退到 `name`。可以包含空格和任何大小寫。不用於命名空間或查詢。需要 Claude Code v2.1.143 或更新版本。 |

227| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。省略以回退到 git commit SHA。請參閱 [版本解析](#version-resolution-and-release-channels)。 |227| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。省略以回退到 git commit SHA。請參閱 [版本解析](#version-resolution-and-release-channels)。 |

236| `relevance` | object | {/* min-version: 2.1.152 */}告知 Claude Code 何時向使用者建議此 plugin 的訊號。僅對管理員在受管設定中允許清單的 marketplace 生效。請參閱 [為您的組織推薦 plugin](/zh-TW/plugin-relevance)。需要 Claude Code v2.1.152 或更新版本。 |236| `relevance` | object | 告知 Claude Code 何時向使用者建議此 plugin 的訊號。僅對管理員在受管設定中允許清單的 marketplace 生效。請參閱 [為您的組織推薦 plugin](/docs/zh-TW/plugin-relevance)。需要 Claude Code v2.1.152 或更新版本。 |

237| `defaultEnabled` | boolean | {/* min-version: 2.1.154 */}安裝後 plugin 是否啟用（預設值：true）。設定為 `false` 以安裝已停用的 plugin，直到使用者選擇加入。優先於 plugin 的 `plugin.json` 中的相同欄位。請參閱 [預設啟用](/zh-TW/plugins-reference#default-enablement)。需要 Claude Code v2.1.154 或更新版本。 |237| `defaultEnabled` | boolean | 安裝後 plugin 是否啟用（預設值：true）。設定為 `false` 以安裝已停用的 plugin，直到使用者選擇加入。優先於 plugin 的 `plugin.json` 中的相同欄位。請參閱 [預設啟用](/docs/zh-TW/plugins-reference#default-enablement)。需要 Claude Code v2.1.154 或更新版本。 |

238 238

239**元件配置欄位：**239**元件配置欄位：**

240 240

508 508

509* **`commands` 和 `agents`**：您可以指定多個目錄或個別檔案。路徑相對於 plugin 根目錄。509* **`commands` 和 `agents`**：您可以指定多個目錄或個別檔案。路徑相對於 plugin 根目錄。

510* **`${CLAUDE_PLUGIN_ROOT}`**：在 hooks 和 MCP server 配置中使用此變數來參考 plugin 安裝目錄內的檔案。這是必要的，因為 plugin 在安裝時被複製到快取位置。510* **`${CLAUDE_PLUGIN_ROOT}`**：在 hooks 和 MCP server 配置中使用此變數來參考 plugin 安裝目錄內的檔案。這是必要的，因為 plugin 在安裝時被複製到快取位置。

511 * 請參閱[替換表](/zh-TW/plugins-reference#environment-variables)以了解每個伺服器類型的哪些配置欄位會替換它511 * 請參閱[替換表](/docs/zh-TW/plugins-reference#environment-variables)以了解每個伺服器類型的哪些配置欄位會替換它

512 * 對於應在 plugin 更新後保留的相依性或狀態，請改用 [`${CLAUDE_PLUGIN_DATA}`](/zh-TW/plugins-reference#persistent-data-directory)512 * 對於應在 plugin 更新後保留的相依性或狀態，請改用 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-TW/plugins-reference#persistent-data-directory)

513* **`strict: false`**：由於此設定為 false，plugin 不需要自己的 `plugin.json`。marketplace 項目定義所有內容。請參閱下面的 [Strict mode](#strict-mode)。513* **`strict: false`**：由於此設定為 false，plugin 不需要自己的 `plugin.json`。marketplace 項目定義所有內容。請參閱下面的 [Strict mode](#strict-mode)。

514 514

515根據預設，plugin 的 skills 從其 `source` 下的 `skills/` 目錄載入。`skills` 欄位中列出的路徑會新增到該掃描中：515根據預設，plugin 的 skills 從其 `source` 下的 `skills/` 目錄載入。`skills` 欄位中列出的路徑會新增到該掃描中：

573 私人儲存庫573 私人儲存庫

574</h3>574</h3>

575 575

576Claude Code 支援從私人儲存庫安裝 plugin。對於手動安裝和更新，Claude Code 使用您現有的 git 認證助手，因此 HTTPS 存取透過 `gh auth login`、macOS Keychain 或 `git-credential-store` 的方式與在您的終端中相同。只要主機已在您的 `known_hosts` 檔案中且金鑰已載入 `ssh-agent`，SSH 存取就可以運作，因為 Claude Code 會抑制主機指紋和金鑰密碼的互動式 SSH 提示。GitHub `owner/repo` 簡寫來源預設透過 SSH 複製；設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/zh-TW/env-vars#variables) 以改為透過 HTTPS 複製它們。576Claude Code 支援從私人儲存庫安裝 plugin。對於手動安裝和更新，Claude Code 使用您現有的 git 認證助手，因此 HTTPS 存取透過 `gh auth login`、macOS Keychain 或 `git-credential-store` 的方式與在您的終端中相同。只要主機已在您的 `known_hosts` 檔案中且金鑰已載入 `ssh-agent`，SSH 存取就可以運作，因為 Claude Code 會抑制主機指紋和金鑰密碼的互動式 SSH 提示。GitHub `owner/repo` 簡寫來源預設透過 SSH 複製；設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars#variables) 以改為透過 HTTPS 複製它們。

577 577

578背景自動更新的運作方式不同。根據預設，背景重新整理會為其 `git pull` 停用 git 認證助手，因此即使已配置助手，pull 也無法對私人儲存庫進行 HTTPS 驗證。SSH 遠端不受影響：載入在 `ssh-agent` 中的金鑰會以與手動操作相同的方式驗證背景 pull。當背景 pull 失敗時，Claude Code 會回退到從頭重新複製 marketplace。重新複製確實會使用您儲存的 git 認證，但它可能會在大型儲存庫上[逾時](#git-operations-time-out)，因此私人 marketplace 自動更新可能會間歇性失敗。578背景自動更新的運作方式不同。根據預設，背景重新整理會為其 `git pull` 停用 git 認證助手，因此即使已配置助手，pull 也無法對私人儲存庫進行 HTTPS 驗證。SSH 遠端不受影響：載入在 `ssh-agent` 中的金鑰會以與手動操作相同的方式驗證背景 pull。當背景 pull 失敗時，Claude Code 會回退到從頭重新複製 marketplace。重新複製確實會使用您儲存的 git 認證，但它可能會在大型儲存庫上[逾時](#git-operations-time-out)，因此私人 marketplace 自動更新可能會間歇性失敗。

579 579

617/plugin install quality-review-plugin@my-plugins617/plugin install quality-review-plugin@my-plugins

618```618```

619 619

620有關完整的新增命令範圍（GitHub、Git URL、本機路徑、遠端 URL），請參閱[新增 marketplace](/zh-TW/discover-plugins#add-marketplaces)。620有關完整的新增命令範圍（GitHub、Git URL、本機路徑、遠端 URL），請參閱[新增 marketplace](/docs/zh-TW/discover-plugins#add-marketplaces)。

621 621

622<h3 id="require-marketplaces-for-your-team">622<h3 id="require-marketplaces-for-your-team">

623 為您的團隊要求 marketplace623 為您的團隊要求 marketplace

649}649}

650```650```

651 651

652有關完整的配置選項，請參閱 [Plugin settings](/zh-TW/settings#plugin-settings)。652有關完整的配置選項，請參閱 [Plugin settings](/docs/zh-TW/settings#plugin-settings)。

653 653

654<Note>654<Note>

655 如果您使用具有相對路徑的本機 `directory` 或 `file` 來源，路徑會針對您的儲存庫的主要簽出進行解析。當您從 git worktree 執行 Claude Code 時，路徑仍然指向主要簽出，因此所有 worktrees 共享相同的 marketplace 位置。Marketplace 狀態每個使用者儲存一次在 `~/.claude/plugins/known_marketplaces.json` 中，而不是每個專案。655 如果您使用具有相對路徑的本機 `directory` 或 `file` 來源，路徑會針對您的儲存庫的主要簽出進行解析。當您從 git worktree 執行 Claude Code 時，路徑仍然指向主要簽出，因此所有 worktrees 共享相同的 marketplace 位置。Marketplace 狀態每個使用者儲存一次在 `~/.claude/plugins/known_marketplaces.json` 中，而不是每個專案。

697 受管 marketplace 限制697 受管 marketplace 限制

698</h3>698</h3>

699 699

700對於需要對 plugin 來源進行嚴格控制的組織，管理員可以使用受管設定中的 [`strictKnownMarketplaces`](/zh-TW/settings#strictknownmarketplaces) 設定限制使用者允許新增的 plugin marketplace。若要也拒絕為單次執行側載 plugin、agent 和 MCP 伺服器的 CLI 旗標，請將其與 [`disableSideloadFlags`](/zh-TW/settings#available-settings) 配對。若要允許清單化哪些 marketplace 的 plugin 可以顯示為內容相關安裝建議，請設定 [`pluginSuggestionMarketplaces`](/zh-TW/settings#available-settings)。700對於需要對 plugin 來源進行嚴格控制的組織，管理員可以使用受管設定中的 [`strictKnownMarketplaces`](/docs/zh-TW/settings#strictknownmarketplaces) 設定限制使用者允許新增的 plugin marketplace。若要也拒絕為單次執行側載 plugin、agent 和 MCP 伺服器的 CLI 旗標，請將其與 [`disableSideloadFlags`](/docs/zh-TW/settings#available-settings) 配對。若要允許清單化哪些 marketplace 的 plugin 可以顯示為內容相關安裝建議，請設定 [`pluginSuggestionMarketplaces`](/docs/zh-TW/settings#available-settings)。

701 701

702當在受管設定中配置 `strictKnownMarketplaces` 時，限制行為取決於值：702當在受管設定中配置 `strictKnownMarketplaces` 時，限制行為取決於值：

703 703

741}741}

742```742```

743 743

744使用主機上的正規表達式模式匹配允許來自內部 git 伺服器的所有 marketplace。這是 [GitHub Enterprise Server](/zh-TW/github-enterprise-server#plugin-marketplaces-on-ghes) 或自託管 GitLab 執行個體的推薦方法：744使用主機上的正規表達式模式匹配允許來自內部 git 伺服器的所有 marketplace。這是 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server#plugin-marketplaces-on-ghes) 或自託管 GitLab 執行個體的推薦方法：

745 745

746```json theme={null}746```json theme={null}

747{747{

770使用 `".*"` 作為 `pathPattern` 以允許任何檔案系統路徑，同時仍使用 `hostPattern` 控制網路來源。770使用 `".*"` 作為 `pathPattern` 以允許任何檔案系統路徑，同時仍使用 `hostPattern` 控制網路來源。

771 771

772<Note>772<Note>

773 `strictKnownMarketplaces` 限制使用者可以新增的內容，但不會自行註冊 marketplace。若要在不需要使用者執行 `/plugin marketplace add` 的情況下自動提供允許的 marketplace，請將其與同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/zh-TW/settings#extraknownmarketplaces) 配對。請參閱[同時使用兩者](/zh-TW/settings#strictknownmarketplaces)。773 `strictKnownMarketplaces` 限制使用者可以新增的內容，但不會自行註冊 marketplace。若要在不需要使用者執行 `/plugin marketplace add` 的情況下自動提供允許的 marketplace，請將其與同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/docs/zh-TW/settings#extraknownmarketplaces) 配對。請參閱[同時使用兩者](/docs/zh-TW/settings#strictknownmarketplaces)。

774</Note>774</Note>

775 775

776<h4 id="how-restrictions-work">776<h4 id="how-restrictions-work">

788 788

789精確匹配不會正規化 URL：尾部斜線、`.git` 後綴或 `ssh://` 與 `https://` 形式被視為不同的值。如果您的組織 marketplace 可以透過多個 URL 形式複製，請優先使用 `hostPattern` 項目而不是字面 URL，以便所有形式都相符。789精確匹配不會正規化 URL：尾部斜線、`.git` 後綴或 `ssh://` 與 `https://` 形式被視為不同的值。如果您的組織 marketplace 可以透過多個 URL 形式複製，請優先使用 `hostPattern` 項目而不是字面 URL，以便所有形式都相符。

790 790

791因為 `strictKnownMarketplaces` 在[受管設定](/zh-TW/settings#settings-files)中設定，個別使用者和專案配置無法覆蓋這些限制。791因為 `strictKnownMarketplaces` 在[受管設定](/docs/zh-TW/settings#settings-files)中設定，個別使用者和專案配置無法覆蓋這些限制。

792 792

793有關完整的配置詳細資訊，包括所有支援的來源類型和與 `extraKnownMarketplaces` 的比較，請參閱 [strictKnownMarketplaces 參考](/zh-TW/settings#strictknownmarketplaces)。793有關完整的配置詳細資訊，包括所有支援的來源類型和與 `extraKnownMarketplaces` 的比較，請參閱 [strictKnownMarketplaces 參考](/docs/zh-TW/settings#strictknownmarketplaces)。

794 794

795<h3 id="version-resolution-and-release-channels">795<h3 id="version-resolution-and-release-channels">

796 版本解析和發行通道796 版本解析和發行通道

816 設定發行通道816 設定發行通道

817</h4>817</h4>

818 818

819若要為您的 plugin 支援「穩定」和「最新」發行通道，您可以設定兩個指向同一儲存庫的不同 ref 或 SHA 的 marketplace。然後，您可以透過[受管設定](/zh-TW/settings#settings-files)將兩個 marketplace 指派給不同的使用者群組。819若要為您的 plugin 支援「穩定」和「最新」發行通道，您可以設定兩個指向同一儲存庫的不同 ref 或 SHA 的 marketplace。然後，您可以透過[受管設定](/docs/zh-TW/settings#settings-files)將兩個 marketplace 指派給不同的使用者群組。

820 820

821<Warning>821<Warning>

822 每個通道必須解析為不同的版本。如果您使用明確版本，`plugin.json` 必須在每個固定的 ref 處宣告不同的 `version`。如果您省略 `version`，不同的提交 SHA 已經區分通道。如果兩個 ref 解析為相同的版本字串，Claude Code 會將它們視為相同並跳過更新。822 每個通道必須解析為不同的版本。如果您使用明確版本，`plugin.json` 必須在每個固定的 ref 處宣告不同的 `version`。如果您省略 `version`，不同的提交 SHA 已經區分通道。如果兩個 ref 解析為相同的版本字串，Claude Code 會將它們視為相同並跳過更新。

896 固定依賴版本896 固定依賴版本

897</h4>897</h4>

898 898

899Plugin 可以將其依賴限制在 semver 範圍內，以便依賴的更新不會破壞依賴 plugin。請參閱[限制 plugin 依賴版本](/zh-TW/plugin-dependencies)以了解 `{plugin-name}--v{version}` git 標籤慣例、範圍語法，以及如何組合對同一依賴的多個限制。899Plugin 可以將其依賴限制在 semver 範圍內，以便依賴的更新不會破壞依賴 plugin。請參閱[限制 plugin 依賴版本](/docs/zh-TW/plugin-dependencies)以了解 `{plugin-name}--v{version}` git 標籤慣例、範圍語法，以及如何組合對同一依賴的多個限制。

900 900

901<h3 id="rename-or-remove-a-plugin">901<h3 id="rename-or-remove-a-plugin">

902 重新命名或移除 plugin902 重新命名或移除 plugin

966/plugin install test-plugin@marketplace-name966/plugin install test-plugin@marketplace-name

967```967```

968 968

969有關完整的 plugin 測試工作流程，請參閱[在本機測試您的 plugin](/zh-TW/plugins#test-your-plugins-locally)。有關技術疑難排解，請參閱 [Plugins reference](/zh-TW/plugins-reference)。969有關完整的 plugin 測試工作流程，請參閱[在本機測試您的 plugin](/docs/zh-TW/plugins#test-your-plugins-locally)。有關技術疑難排解，請參閱 [Plugins reference](/docs/zh-TW/plugins-reference)。

970 970

971<h2 id="manage-marketplaces-from-the-cli">971<h2 id="manage-marketplaces-from-the-cli">

972 從 CLI 管理 marketplace972 從 CLI 管理 marketplace

994 994

995| 選項 | 描述 | 預設 |995| 選項 | 描述 | 預設 |

996| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :----- |996| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :----- |

999 999

1000從 GitHub 使用 `owner/repo` 簡寫新增 marketplace：1000從 GitHub 使用 `owner/repo` 簡寫新增 marketplace：

1075 1075

1076| 選項 | 描述 | 預設 |1076| 選項 | 描述 | 預設 |

1077| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |1077| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1078| `--scope <scope>` | 限制移除到單一設定範圍：`user`、`project` 或 `local`。請參閱 [Plugin installation scopes](/zh-TW/plugins-reference#plugin-installation-scopes)。省略時，宣告會從每個可編輯的範圍中移除。指定時，只會移除該範圍的宣告；當 marketplace 仍在另一個範圍中宣告時，共享狀態、快取和已安裝的 plugin 資料會被保留 | (所有範圍) |1078| `--scope <scope>` | 限制移除到單一設定範圍：`user`、`project` 或 `local`。請參閱 [Plugin installation scopes](/docs/zh-TW/plugins-reference#plugin-installation-scopes)。省略時，宣告會從每個可編輯的範圍中移除。指定時，只會移除該範圍的宣告；當 marketplace 仍在另一個範圍中宣告時，共享狀態、快取和已安裝的 plugin 資料會被保留 | (所有範圍) |

1079 1079

1080<Warning>1080<Warning>

1081 從其最後剩餘的範圍移除 marketplace 也會卸載您從中安裝的任何 plugin。若要重新整理 marketplace 而不失去已安裝的 plugin，請改用 `claude plugin marketplace update`。1081 從其最後剩餘的範圍移除 marketplace 也會卸載您從中安裝的任何 plugin。若要重新整理 marketplace 而不失去已安裝的 plugin，請改用 `claude plugin marketplace update`。

1236 1236

1237**原因**：Plugin 被複製到快取目錄而不是就地使用。參考 plugin 目錄外檔案的路徑（例如 `../shared-utils`）無法運作，因為這些檔案不會被複製。1237**原因**：Plugin 被複製到快取目錄而不是就地使用。參考 plugin 目錄外檔案的路徑（例如 `../shared-utils`）無法運作，因為這些檔案不會被複製。

1238 1238

1239**解決方案**：有關解決方案（包括符號連結和目錄重組），請參閱 [Plugin caching and file resolution](/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。1239**解決方案**：有關解決方案（包括符號連結和目錄重組），請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。

1240 1240

1241有關其他偵錯工具和常見問題，請參閱 [Debugging and development tools](/zh-TW/plugins-reference#debugging-and-development-tools)。1241有關其他偵錯工具和常見問題，請參閱 [Debugging and development tools](/docs/zh-TW/plugins-reference#debugging-and-development-tools)。

1242 1242

1243<h2 id="see-also">1243<h2 id="see-also">

1244 另請參閱1244 另請參閱

1245</h2>1245</h2>

1246 1246

1247* [探索並安裝預先建立的 plugins](/zh-TW/discover-plugins) - 從現有 marketplace 安裝 plugins1247* [探索並安裝預先建立的 plugins](/docs/zh-TW/discover-plugins) - 從現有 marketplace 安裝 plugins

1248* [Plugins](/zh-TW/plugins) - 建立您自己的 plugins1248* [Plugins](/docs/zh-TW/plugins) - 建立您自己的 plugins

1249* [Plugins reference](/zh-TW/plugins-reference) - 完整的技術規格和架構1249* [Plugins reference](/docs/zh-TW/plugins-reference) - 完整的技術規格和架構

1250* [Plugin settings](/zh-TW/settings#plugin-settings) - Plugin 配置選項1250* [Plugin settings](/docs/zh-TW/settings#plugin-settings) - Plugin 配置選項

1251* [strictKnownMarketplaces reference](/zh-TW/settings#strictknownmarketplaces) - 受管 marketplace 限制1251* [strictKnownMarketplaces reference](/docs/zh-TW/settings#strictknownmarketplaces) - 受管 marketplace 限制

plugin-relevance.md +13 −13

Details

8 8

9如果您為組織運營外掛程式 marketplace，您可以根據使用者正在進行的工作，讓 Claude Code 向使用者建議特定的外掛程式。在 `marketplace.json` 中的外掛程式項目中新增 `relevance` 區塊，然後在受管設定中將 marketplace 加入允許清單。當使用者的工作階段符合其中一個已宣告的信號時，Claude Code 會顯示該外掛程式的安裝建議。9如果您為組織運營外掛程式 marketplace，您可以根據使用者正在進行的工作，讓 Claude Code 向使用者建議特定的外掛程式。在 `marketplace.json` 中的外掛程式項目中新增 `relevance` 區塊，然後在受管設定中將 marketplace 加入允許清單。當使用者的工作階段符合其中一個已宣告的信號時，Claude Code 會顯示該外掛程式的安裝建議。

10 10

11Marketplace 宣告的建議是透過[受管設定](/zh-TW/settings#settings-files)按 marketplace 選擇加入的。在管理員將任何 marketplace 新增至允許清單之前，該 marketplace 的 `relevance` 宣告都不會產生建議，包括官方 Anthropic marketplace。Claude Code 還包括一個獨立於此允許清單的內建建議；當 [`spinnerTipsEnabled`](/zh-TW/settings#available-settings) 設定為 `false` 時，該提示和所有 marketplace 宣告的提示都會被停用。11Marketplace 宣告的建議是透過[受管設定](/docs/zh-TW/settings#settings-files)按 marketplace 選擇加入的。在管理員將任何 marketplace 新增至允許清單之前，該 marketplace 的 `relevance` 宣告都不會產生建議，包括官方 Anthropic marketplace。Claude Code 還包括一個獨立於此允許清單的內建建議；當 [`spinnerTipsEnabled`](/docs/zh-TW/settings#available-settings) 設定為 `false` 時，該提示和所有 marketplace 宣告的提示都會被停用。

12 12

~~13{/* min-version: 2.1.152 */}此功能需要 Claude Code v2.1.152 或更新版本。較舊的用戶端會忽略 `relevance` 欄位。~~13此功能需要 Claude Code v2.1.152 或更新版本。較舊的用戶端會忽略 `relevance` 欄位。

14 14

~~15此頁面適用於 marketplace 運營商和企業管理員。如果您想要安裝外掛程式，請參閱[探索和安裝外掛程式](/zh-TW/discover-plugins)。~~15此頁面適用於 marketplace 運營商和企業管理員。如果您想要安裝外掛程式，請參閱[探索和安裝外掛程式](/docs/zh-TW/discover-plugins)。

16 16

17<h2 id="how-it-works">17<h2 id="how-it-works">

18 運作方式18 運作方式

25當信號相符且外掛程式尚未安裝時，Claude Code 會在三個位置顯示該外掛程式：25當信號相符且外掛程式尚未安裝時，Claude Code 會在三個位置顯示該外掛程式：

26 26

27* **Spinner 提示**：當 Claude 正在回應時，spinner 下方會出現「使用 *主題*？安裝 *外掛程式* 外掛程式」訊息，並附帶 `/plugin install` 命令。27* **Spinner 提示**：當 Claude 正在回應時，spinner 下方會出現「使用 *主題*？安裝 *外掛程式* 外掛程式」訊息，並附帶 `/plugin install` 命令。

28* **工作階段開始建議**：{/* min-version: 2.1.153 */}如果 `cwd` 信號符合工作目錄，在第一個回合之前會出現一行 `plugin suggestion: <name>@<marketplace> · /plugin` 通知。此介面需要 Claude Code v2.1.153 或更新版本。28* **工作階段開始建議**：如果 `cwd` 信號符合工作目錄，在第一個回合之前會出現一行 `plugin suggestion: <name>@<marketplace> · /plugin` 通知。此介面需要 Claude Code v2.1.153 或更新版本。

29* **`/plugin` Discover 標籤**：{/* min-version: 2.1.154 */}外掛程式會被釘選到 Discover 清單的頂部，並附帶註解，例如「建議用於此目錄」或「建議用於 stripe 命令」。此介面需要 Claude Code v2.1.154 或更新版本。29* **`/plugin` Discover 標籤**：外掛程式會被釘選到 Discover 清單的頂部，並附帶註解，例如「建議用於此目錄」或「建議用於 stripe 命令」。此介面需要 Claude Code v2.1.154 或更新版本。

30 30

31Spinner 提示和工作階段開始通知是 spinner 提示系統的一部分。當使用者或專案將 `spinnerTipsEnabled` 設定為 `false`，或當使用 `excludeDefault` 配置自訂 `spinnerTipsOverride` 時，兩者都會被停用。Discover 標籤釘選獨立於提示設定。31Spinner 提示和工作階段開始通知是 spinner 提示系統的一部分。當使用者或專案將 `spinnerTipsEnabled` 設定為 `false`，或當使用 `excludeDefault` 配置自訂 `spinnerTipsOverride` 時，兩者都會被停用。Discover 標籤釘選獨立於提示設定。

32 32

80 80

81| 欄位 | 類型 | 說明 |81| 欄位 | 類型 | 說明 |

82| :------------- | :--- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |82| :------------- | :--- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

83| `cwd` | 字串陣列 | {/* min-version: 2.1.153 */}與工作階段工作目錄相符的 Glob 模式。作為絕對路徑相符，當在 git 儲存庫內時，作為相對於儲存庫根目錄的路徑相符。正斜線正規化且不區分大小寫。每個模式都符合目錄本身及其下的所有內容，因此 `infra`、`infra/` 和 `infra/**` 的行為相同。這是唯一可以在工作階段開始時（在第一個回合之前）相符的信號。最多 10 個模式，每個 256 個字元。 |83| `cwd` | 字串陣列 | 與工作階段工作目錄相符的 Glob 模式。作為絕對路徑相符，當在 git 儲存庫內時，作為相對於儲存庫根目錄的路徑相符。正斜線正規化且不區分大小寫。每個模式都符合目錄本身及其下的所有內容，因此 `infra`、`infra/` 和 `infra/**` 的行為相同。這是唯一可以在工作階段開始時（在第一個回合之前）相符的信號。最多 10 個模式，每個 256 個字元。 |

84| `cli` | 字串陣列 | Claude 在此工作階段執行的 shell 命令中的命令名稱，例如 `["stripe"]`。適用於每個平台：在 Windows 上透過 PowerShell 或 Git Bash 執行的命令以相同方式記錄。Claude Code 為每個 shell 工具呼叫記錄一個命令名稱：任何前導環境變數指派和 `sudo` 之後的第一個權杖。複合命令只貢獻其前導命令，因此 `cd infra && terraform plan` 記錄 `cd`，而不是 `terraform`。完全相符。最多 10 個項目，每個 64 個字元。 |84| `cli` | 字串陣列 | Claude 在此工作階段執行的 shell 命令中的命令名稱，例如 `["stripe"]`。適用於每個平台：在 Windows 上透過 PowerShell 或 Git Bash 執行的命令以相同方式記錄。Claude Code 為每個 shell 工具呼叫記錄一個命令名稱：任何前導環境變數指派和 `sudo` 之後的第一個權杖。複合命令只貢獻其前導命令，因此 `cd infra && terraform plan` 記錄 `cd`，而不是 `terraform`。完全相符。最多 10 個項目，每個 64 個字元。 |

86| `filesRead` | 字串陣列 | {/* min-version: 2.1.153 */}與 Claude 在此工作階段讀取的檔案路徑相符的 Glob 模式，例如 `["**/*.tf"]`。正斜線正規化且不區分大小寫。最多 10 個模式，每個 256 個字元。 |86| `filesRead` | 字串陣列 | 與 Claude 在此工作階段讀取的檔案路徑相符的 Glob 模式，例如 `["**/*.tf"]`。正斜線正規化且不區分大小寫。最多 10 個模式，每個 256 個字元。 |

87| `manifestDeps` | 物件陣列 | Claude 在此工作階段讀取的套件資訊清單中宣告的相依性。每個項目都是 `{ "file": "...", "pattern": "..." }`，其中 `file` 是與資訊清單檔案路徑相符的正規表達式（如工作階段狀態中所記錄，通常是絕對路徑），`pattern` 是與該檔案內容相符的正規表達式。在 `file` 的末尾錨定，例如 JSON 逸出形式中的 `[/\\\\]package\\.json$`，因為開始錨定的模式永遠不會符合絕對路徑。路徑不會針對此信號進行分隔符號正規化，因此 Windows 路徑使用反斜線。大於 512 KB 的資訊清單檔案會被跳過。兩個值都是最多 256 個字元的 JavaScript `RegExp` 來源字串。`file` 不區分大小寫相符。`pattern` 區分大小寫。最多 10 個項目。 |87| `manifestDeps` | 物件陣列 | Claude 在此工作階段讀取的套件資訊清單中宣告的相依性。每個項目都是 `{ "file": "...", "pattern": "..." }`，其中 `file` 是與資訊清單檔案路徑相符的正規表達式（如工作階段狀態中所記錄，通常是絕對路徑），`pattern` 是與該檔案內容相符的正規表達式。在 `file` 的末尾錨定，例如 JSON 逸出形式中的 `[/\\\\]package\\.json$`，因為開始錨定的模式永遠不會符合絕對路徑。路徑不會針對此信號進行分隔符號正規化，因此 Windows 路徑使用反斜線。大於 512 KB 的資訊清單檔案會被跳過。兩個值都是最多 256 個字元的 JavaScript `RegExp` 來源字串。`file` 不區分大小寫相符。`pattern` 區分大小寫。最多 10 個項目。 |

88 88

89`cli`、`hosts`、`filesRead` 和 `manifestDeps` 信號需要工作階段歷史記錄，因此它們只能在 spinner 提示和 Discover 標籤上相符。只有 `cwd` 可以在工作階段開始時相符。`filesRead` 和 `manifestDeps` 信號測試工作階段的記錄檔案狀態，其中也包括 Claude 已寫入或編輯的檔案以及自動載入的 `CLAUDE.md` 記憶體檔案。89`cli`、`hosts`、`filesRead` 和 `manifestDeps` 信號需要工作階段歷史記錄，因此它們只能在 spinner 提示和 Discover 標籤上相符。只有 `cwd` 可以在工作階段開始時相符。`filesRead` 和 `manifestDeps` 信號測試工作階段的記錄檔案狀態，其中也包括 Claude 已寫入或編輯的檔案以及自動載入的 `CLAUDE.md` 記憶體檔案。

116 在受管設定中啟用建議116 在受管設定中啟用建議

117</h2>117</h2>

118 118

119在 `marketplace.json` 中宣告 `relevance` 本身是不夠的。管理員必須在[受管設定](/zh-TW/settings#settings-files)中將 marketplace 加入允許清單，才能向使用者顯示其建議。119在 `marketplace.json` 中宣告 `relevance` 本身是不夠的。管理員必須在[受管設定](/docs/zh-TW/settings#settings-files)中將 marketplace 加入允許清單，才能向使用者顯示其建議。

120 120

121將 marketplace 名稱新增至 `pluginSuggestionMarketplaces`。對於官方 Anthropic marketplace 以外的任何 marketplace，也在相同的受管設定中宣告 marketplace 來源，可以是該名稱在 `extraKnownMarketplaces` 中的項目，或在 `strictKnownMarketplaces` 中的項目。如果在機器上註冊的 marketplace 來自不同的來源，允許清單中的名稱會被忽略。這可防止無關的來源以允許清單中的名稱進行註冊，以便在整個組織中建議其外掛程式。121將 marketplace 名稱新增至 `pluginSuggestionMarketplaces`。對於官方 Anthropic marketplace 以外的任何 marketplace，也在相同的受管設定中宣告 marketplace 來源，可以是該名稱在 `extraKnownMarketplaces` 中的項目，或在 `strictKnownMarketplaces` 中的項目。如果在機器上註冊的 marketplace 來自不同的來源，允許清單中的名稱會被忽略。這可防止無關的來源以允許清單中的名稱進行註冊，以便在整個組織中建議其外掛程式。

122 122

144}144}

145```145```

146 146

147請參閱[設定參考](/zh-TW/settings)以取得 `pluginSuggestionMarketplaces` 和 [`extraKnownMarketplaces`](/zh-TW/settings#extraknownmarketplaces) 的完整配置詳細資訊。147請參閱[設定參考](/docs/zh-TW/settings)以取得 `pluginSuggestionMarketplaces` 和 [`extraKnownMarketplaces`](/docs/zh-TW/settings#extraknownmarketplaces) 的完整配置詳細資訊。

148 148

149<h2 id="what-the-user-sees">149<h2 id="what-the-user-sees">

150 使用者看到的內容150 使用者看到的內容

165 165

166給定外掛程式的建議在 spinner 提示和工作階段開始通知的組合中最多每三個工作階段出現一次，安裝外掛程式後兩者都不會重複。工作階段開始通知在建議顯示兩次後還會停止出現。166給定外掛程式的建議在 spinner 提示和工作階段開始通知的組合中最多每三個工作階段出現一次，安裝外掛程式後兩者都不會重複。工作階段開始通知在建議顯示兩次後還會停止出現。

167 167

168{/* min-version: 2.1.154 */}在 `/plugin` Discover 標籤中，外掛程式會被釘選在其他結果上方，並附帶命名相符信號的註解，例如 `suggested for this directory` 或 `suggested for terraform commands`。Discover 標籤釘選給定的外掛程式一次；稍後的訪問會以正常順序列出它。Discover 標籤釘選需要 Claude Code v2.1.154 或更新版本。在 v2.1.152 上，只有 spinner 提示出現；工作階段開始通知在 v2.1.153 中新增。168在 `/plugin` Discover 標籤中，外掛程式會被釘選在其他結果上方，並附帶命名相符信號的註解，例如 `suggested for this directory` 或 `suggested for terraform commands`。Discover 標籤釘選給定的外掛程式一次；稍後的訪問會以正常順序列出它。Discover 標籤釘選需要 Claude Code v2.1.154 或更新版本。在 v2.1.152 上，只有 spinner 提示出現；工作階段開始通知在 v2.1.153 中新增。

169 169

170<h2 id="validate-your-marketplace">170<h2 id="validate-your-marketplace">

171 驗證您的 marketplace171 驗證您的 marketplace

183 另請參閱183 另請參閱

184</h2>184</h2>

185 185

186* [建立和發佈外掛程式 marketplace](/zh-TW/plugin-marketplaces)：建立託管您的外掛程式的 marketplace186* [建立和發佈外掛程式 marketplace](/docs/zh-TW/plugin-marketplaces)：建立託管您的外掛程式的 marketplace

187* [從您的 CLI 推薦您的外掛程式](/zh-TW/plugin-hints)：從您自己的 CLI 而不是從 Claude Code 的工作階段信號提示使用者187* [從您的 CLI 推薦您的外掛程式](/docs/zh-TW/plugin-hints)：從您自己的 CLI 而不是從 Claude Code 的工作階段信號提示使用者

188* [設定](/zh-TW/settings)：`pluginSuggestionMarketplaces` 和 `extraKnownMarketplaces` 的完整參考188* [設定](/docs/zh-TW/settings)：`pluginSuggestionMarketplaces` 和 `extraKnownMarketplaces` 的完整參考

plugins-reference.md +3 −3

Details

515| 欄位 | 類型 | 描述 | 範例 |515| 欄位 | 類型 | 描述 | 範例 |

516| :--------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |516| :--------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |

518| `displayName` | string | {/* min-version: 2.1.143 */}在 `/plugin` 選擇器和其他 UI 介面中顯示的人類可讀名稱。當省略時回退到 `name`。與 `name` 不同，可能包含空格和任何大小寫。不用於命名空間或查詢。需要 Claude Code v2.1.143 或更新版本。 | `"Deployment Tools"` |518| `displayName` | string | 在 `/plugin` 選擇器和其他 UI 介面中顯示的人類可讀名稱。當省略時回退到 `name`。與 `name` 不同，可能包含空格和任何大小寫。不用於命名空間或查詢。需要 Claude Code v2.1.143 或更新版本。 | `"Deployment Tools"` |

519| `version` | string | 選用。語義版本。設定此項會將 plugin 固定到該版本字串，因此使用者只會在您提升版本時收到更新。如果省略，Claude Code 會回退到 git commit SHA，因此每個 commit 都被視為新版本。如果也在 marketplace 項目中設定，`plugin.json` 優先。請參閱[版本管理](#version-management)。 | `"2.1.0"` |519| `version` | string | 選用。語義版本。設定此項會將 plugin 固定到該版本字串，因此使用者只會在您提升版本時收到更新。如果省略，Claude Code 會回退到 git commit SHA，因此每個 commit 都被視為新版本。如果也在 marketplace 項目中設定，`plugin.json` 優先。請參閱[版本管理](#version-management)。 | `"2.1.0"` |

521| `author` | object | 作者資訊 | `{"name": "Dev Team", "email": "dev@company.com"}` |521| `author` | object | 作者資訊 | `{"name": "Dev Team", "email": "dev@company.com"}` |

526| `defaultEnabled` | boolean | {/* min-version: 2.1.154 */}當使用者未設定時，plugin 是否以啟用狀態啟動。預設為 `true`。請參閱[預設啟用](#default-enablement)。需要 Claude Code v2.1.154 或更新版本。 | `false` |526| `defaultEnabled` | boolean | 當使用者未設定時，plugin 是否以啟用狀態啟動。預設為 `true`。請參閱[預設啟用](#default-enablement)。需要 Claude Code v2.1.154 或更新版本。 | `false` |

527 527

528<h3 id="default-enablement">528<h3 id="default-enablement">

529 預設啟用529 預設啟用

612 612

613在 v2.1.207 之前，這些欄位替換 `${user_config.KEY}` 值；更新依賴此功能的 plugins。613在 v2.1.207 之前，這些欄位替換 `${user_config.KEY}` 值；更新依賴此功能的 plugins。

614 614

615非敏感值儲存在 `settings.json` 中的 [`pluginConfigs`](/docs/zh-TW/settings#pluginconfigs) 金鑰下，作為 `pluginConfigs[<plugin-id>].options`。{/* min-version: 2.1.207 */}Claude Code 將金鑰寫入使用者設定並從使用者設定、`--settings` 旗標和受管設定讀取；專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目會被忽略。在 v2.1.207 之前，Claude Code 也讀取專案和本地設定。615非敏感值儲存在 `settings.json` 中的 [`pluginConfigs`](/docs/zh-TW/settings#pluginconfigs) 金鑰下，作為 `pluginConfigs[<plugin-id>].options`。Claude Code 將金鑰寫入使用者設定並從使用者設定、`--settings` 旗標和受管設定讀取；專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的項目會被忽略。在 v2.1.207 之前，Claude Code 也讀取專案和本地設定。

616 616

617敏感值進入 macOS Keychain，或在沒有支援的 keychain 可用的平台上進入 `~/.claude/.credentials.json`。Keychain 儲存與 OAuth 令牌共享，總限制約為 2 KB，因此請保持敏感值較小。617敏感值進入 macOS Keychain，或在沒有支援的 keychain 可用的平台上進入 `~/.claude/.credentials.json`。Keychain 儲存與 OAuth 令牌共享，總限制約為 2 KB，因此請保持敏感值較小。

618 618

prompt-caching.md +1 −1

Details

116 116

117例外是提供 [MCP 伺服器](/docs/zh-TW/plugins-reference#mcp-servers)的外掛程式。啟用或停用一個遵循與[連接或斷開 MCP 伺服器](#connecting-or-disconnecting-an-mcp-server)相同的規則：當伺服器的工具被延遲時快取會保留，當它們載入到前綴中時下一個請求會重新讀取整個對話。117例外是提供 [MCP 伺服器](/docs/zh-TW/plugins-reference#mcp-servers)的外掛程式。啟用或停用一個遵循與[連接或斷開 MCP 伺服器](#connecting-or-disconnecting-an-mcp-server)相同的規則：當伺服器的工具被延遲時快取會保留，當它們載入到前綴中時下一個請求會重新讀取整個對話。

118 118

119外掛程式變更在您運行 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 或啟動新會話時應用。成本（無論是附加公告還是完整重新讀取）會在重新載入後的第一個轉換時顯示，而不是在您運行 `/plugin install`、`/plugin enable` 或 `/plugin disable` 時。{/* min-version: 2.1.163 */}自 v2.1.163 起，當重新載入會觸發完整重新讀取時，`/reload-plugins` 會顯示警告並不應用重新載入。傳遞 `--force` 以強制應用。119外掛程式變更在您運行 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 或啟動新會話時應用。成本（無論是附加公告還是完整重新讀取）會在重新載入後的第一個轉換時顯示，而不是在您運行 `/plugin install`、`/plugin enable` 或 `/plugin disable` 時。自 v2.1.163 起，當重新載入會觸發完整重新讀取時，`/reload-plugins` 會顯示警告並不應用重新載入。傳遞 `--force` 以強制應用。

120 120

121停用您在會話中較早啟用的外掛程式會恢復先前的請求形狀。如果該前綴仍在其[快取生命週期](#cache-lifetime)內，下一個請求會讀取較舊的快取項目，而不是重新建立。121停用您在會話中較早啟用的外掛程式會恢復先前的請求形狀。如果該前綴仍在其[快取生命週期](#cache-lifetime)內，下一個請求會讀取較舊的快取項目，而不是重新建立。

122 122

remote-control.md +38 −38

Details

14 14

15當您在機器上啟動 Remote Control 會話時，Claude 會在整個過程中在本地執行，因此您的程式碼執行和檔案系統存取保持在您的機器上。使用 Remote Control，您可以：15當您在機器上啟動 Remote Control 會話時，Claude 會在整個過程中在本地執行，因此您的程式碼執行和檔案系統存取保持在您的機器上。使用 Remote Control，您可以：

16 16

~~17* **遠端使用您的完整本地環境**：您的檔案系統、[MCP servers](/zh-TW/mcp)、工具和專案配置都保持可用，輸入 `@` 會自動完成來自您本地專案的檔案路徑~~17* **遠端使用您的完整本地環境**：您的檔案系統、[MCP servers](/docs/zh-TW/mcp)、工具和專案配置都保持可用，輸入 `@` 會自動完成來自您本地專案的檔案路徑

18* **同時在兩個介面上工作**：對話和 [subagents](/zh-TW/sub-agents) 和 [dynamic workflows](/zh-TW/workflows) 的進度在所有連接的裝置上保持同步，因此您可以從終端機、瀏覽器和手機交替發送訊息。{/* min-version: 2.1.207 */}在 v2.1.207 之前，由 [Desktop app](/zh-TW/desktop) 託管的會話不會將 subagent 或工作流程進度發送到連接的裝置。18* **同時在兩個介面上工作**：對話和 [subagents](/docs/zh-TW/sub-agents) 和 [dynamic workflows](/docs/zh-TW/workflows) 的進度在所有連接的裝置上保持同步，因此您可以從終端機、瀏覽器和手機交替發送訊息。在 v2.1.207 之前，由 [Desktop app](/docs/zh-TW/desktop) 託管的會話不會將 subagent 或工作流程進度發送到連接的裝置。

19* **從您的手機或瀏覽器傳送影像和檔案**：當您在 Claude 應用程式或 claude.ai/code 中新增附件時，Claude Code 會將其下載到您的機器，並將其作為 `@` 檔案參考傳遞給 Claude，可以有或沒有標題。{/* min-version: 2.1.202 */}在 v2.1.202 之前，Claude Code 可能會在沒有標題的附件到達會話之前將其丟棄。19* **從您的手機或瀏覽器傳送影像和檔案**：當您在 Claude 應用程式或 claude.ai/code 中新增附件時，Claude Code 會將其下載到您的機器，並將其作為 `@` 檔案參考傳遞給 Claude，可以有或沒有標題。在 v2.1.202 之前，Claude Code 可能會在沒有標題的附件到達會話之前將其丟棄。

20* **克服中斷**：如果您的筆記型電腦進入睡眠狀態或網路中斷，當您的機器重新上線時，會話會自動重新連接。Claude Code 會在連接重建時將來自 subagents 和工作流程的狀態更新排隊，並在恢復後傳遞它們。{/* min-version: 2.1.207 */}在 v2.1.207 之前，在重新連接或認證重新整理期間發送的更新可能會遺失，因此連接的裝置會繼續將已完成的任務顯示為執行中。20* **克服中斷**：如果您的筆記型電腦進入睡眠狀態或網路中斷，當您的機器重新上線時，會話會自動重新連接。Claude Code 會在連接重建時將來自 subagents 和工作流程的狀態更新排隊，並在恢復後傳遞它們。在 v2.1.207 之前，在重新連接或認證重新整理期間發送的更新可能會遺失，因此連接的裝置會繼續將已完成的任務顯示為執行中。

21 21

22與[網頁版 Claude Code](/zh-TW/claude-code-on-the-web)（在雲端基礎設施上執行）不同，Remote Control 會話直接在您的機器上執行並與您的本地檔案系統互動。網頁和行動介面只是該本地會話的一個窗口。22與[網頁版 Claude Code](/docs/zh-TW/claude-code-on-the-web)（在雲端基礎設施上執行）不同，Remote Control 會話直接在您的機器上執行並與您的本地檔案系統互動。網頁和行動介面只是該本地會話的一個窗口。

23 23

24本頁涵蓋設定、如何啟動和連接到會話，以及 Remote Control 與網頁版 Claude Code 的比較。24本頁涵蓋設定、如何啟動和連接到會話，以及 Remote Control 與網頁版 Claude Code 的比較。

25 25

31 31

32* **訂閱**：在 Pro、Max、Team 和 Enterprise 方案上可用。不支援 API 金鑰。在 Team 和 Enterprise 上，管理員必須先在 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)中啟用 Remote Control 切換。32* **訂閱**：在 Pro、Max、Team 和 Enterprise 方案上可用。不支援 API 金鑰。在 Team 和 Enterprise 上，管理員必須先在 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)中啟用 Remote Control 切換。

33* **驗證**：執行 `claude` 並使用 `/login` 透過 claude.ai 登入（如果您還沒有登入）。33* **驗證**：執行 `claude` 並使用 `/login` 透過 claude.ai 登入（如果您還沒有登入）。

34* **API 端點**：在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機（例如 [LLM 閘道](/zh-TW/llm-gateway)或代理）時，Remote Control 也會被停用。取消設定該變數以使用 Remote Control。34* **API 端點**：在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。自 v2.1.196 起，當 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)或代理）時，Remote Control 也會被停用。取消設定該變數以使用 Remote Control。

35* **工作區信任**：在您的專案目錄中至少執行一次 `claude` 以接受工作區信任對話框。35* **工作區信任**：在您的專案目錄中至少執行一次 `claude` 以接受工作區信任對話框。

36 36

37<h2 id="start-a-remote-control-session">37<h2 id="start-a-remote-control-session">

56 | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |56 | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

58 | `--remote-control-session-name-prefix <prefix>` | 未設定明確名稱時自動生成會話名稱的前綴。預設為您機器的主機名稱，產生類似 `myhost-graceful-unicorn` 的名稱。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以獲得相同效果。 |58 | `--remote-control-session-name-prefix <prefix>` | 未設定明確名稱時自動生成會話名稱的前綴。預設為您機器的主機名稱，產生類似 `myhost-graceful-unicorn` 的名稱。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以獲得相同效果。 |

59 | `-c`, `--continue` | {/* min-version: 2.1.200 */}恢復從此目錄啟動的最近 Remote Control 會話，而不是建立新會話。無法與 `--session-id`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 結合。需要 Claude Code v2.1.200 或更新版本；較早版本會將該旗標拒絕為未知引數。 |59 | `-c`, `--continue` | 恢復從此目錄啟動的最近 Remote Control 會話，而不是建立新會話。無法與 `--session-id`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 結合。需要 Claude Code v2.1.200 或更新版本；較早版本會將該旗標拒絕為未知引數。 |

60 | `--session-id <id>` | {/* min-version: 2.1.200 */}按其 ID 恢復特定的 Remote Control 會話。無法與 `--continue`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 結合。需要 Claude Code v2.1.200 或更新版本；較早版本會將該旗標拒絕為未知引數。 |60 | `--session-id <id>` | 按其 ID 恢復特定的 Remote Control 會話。無法與 `--continue`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 結合。需要 Claude Code v2.1.200 或更新版本；較早版本會將該旗標拒絕為未知引數。 |

61 | `--spawn <mode>` | 伺服器如何建立會話。<br />• `same-dir`（預設）：所有會話共享目前的工作目錄，因此如果編輯相同的檔案可能會衝突。<br />• `worktree`：每個按需會話都會獲得自己的 [git worktree](/zh-TW/worktrees)。需要 git 儲存庫。<br />• `session`：單一會話模式。恰好提供一個會話並拒絕其他連接。僅在啟動時設定。<br />在執行時按 `w` 在 `same-dir` 和 `worktree` 之間切換。 |61 | `--spawn <mode>` | 伺服器如何建立會話。<br />• `same-dir`（預設）：所有會話共享目前的工作目錄，因此如果編輯相同的檔案可能會衝突。<br />• `worktree`：每個按需會話都會獲得自己的 [git worktree](/docs/zh-TW/worktrees)。需要 git 儲存庫。<br />• `session`：單一會話模式。恰好提供一個會話並拒絕其他連接。僅在啟動時設定。<br />在執行時按 `w` 在 `same-dir` 和 `worktree` 之間切換。 |

63 | `--[no-]create-session-in-dir` | 伺服器啟動時在目前目錄中預先建立一個會話，以便您有地方立即輸入。在 `worktree` 模式中，此會話保留在目前目錄中，而按需會話會獲得隔離的 worktrees。預設為開啟；傳遞 `--no-create-session-in-dir` 以不建立任何會話啟動。 |63 | `--[no-]create-session-in-dir` | 伺服器啟動時在目前目錄中預先建立一個會話，以便您有地方立即輸入。在 `worktree` 模式中，此會話保留在目前目錄中，而按需會話會獲得隔離的 worktrees。預設為開啟；傳遞 `--no-create-session-in-dir` 以不建立任何會話啟動。 |

66 </Tab>66 </Tab>

67 67

68 <Tab title="互動式會話">68 <Tab title="互動式會話">

100 </Tab>100 </Tab>

101 101

102 <Tab title="VS Code">102 <Tab title="VS Code">

103 在 [Claude Code VS Code 擴充功能](/zh-TW/vs-code)中，在提示框中輸入 `/remote-control` 或 `/rc`，或使用 `/` 開啟命令選單並選擇它。103 在 [Claude Code VS Code 擴充功能](/docs/zh-TW/vs-code)中，在提示框中輸入 `/remote-control` 或 `/rc`，或使用 `/` 開啟命令選單並選擇它。

104 104

105 ```text theme={null}105 ```text theme={null}

106 /remote-control106 /remote-control

132* **掃描 QR 碼** 顯示在會話 URL 旁邊，直接在 Claude 應用程式中開啟它。使用 `claude remote-control` 時，按空格鍵切換 QR 碼顯示。132* **掃描 QR 碼** 顯示在會話 URL 旁邊，直接在 Claude 應用程式中開啟它。使用 `claude remote-control` 時，按空格鍵切換 QR 碼顯示。

133* **開啟 [claude.ai/code](https://claude.ai/code) 或 Claude 應用程式**，並在會話清單中按名稱找到會話。在 Claude 行動應用程式中，點擊導航中的**程式碼**以到達會話清單。Remote Control 會話在線上時顯示帶有綠色狀態點的電腦圖示。133* **開啟 [claude.ai/code](https://claude.ai/code) 或 Claude 應用程式**，並在會話清單中按名稱找到會話。在 Claude 行動應用程式中，點擊導航中的**程式碼**以到達會話清單。Remote Control 會話在線上時顯示帶有綠色狀態點的電腦圖示。

134 134

135當您連接時，該裝置會顯示會話已在背景執行的任何子代理和工作流程。{/* min-version: 2.1.208 */}在 v2.1.208 之前，連接到在互動式終端機中託管的會話的裝置在其中一個子代理或工作流程啟動或停止之前，不會顯示已在執行的子代理和工作流程。135當您連接時，該裝置會顯示會話已在背景執行的任何子代理和工作流程。在 v2.1.208 之前，連接到在互動式終端機中託管的會話的裝置在其中一個子代理或工作流程啟動或停止之前，不會顯示已在執行的子代理和工作流程。

136 136

137遠端會話標題按以下順序選擇：137遠端會話標題按以下順序選擇：

138 138

1413. 現有對話歷史記錄中最後一條有意義的訊息1413. 現有對話歷史記錄中最後一條有意義的訊息

1424. 類似 `myhost-graceful-unicorn` 的自動生成名稱，其中 `myhost` 是您機器的主機名稱或您使用 `--remote-control-session-name-prefix` 設定的前綴1424. 類似 `myhost-graceful-unicorn` 的自動生成名稱，其中 `myhost` 是您機器的主機名稱或您使用 `--remote-control-session-name-prefix` 設定的前綴

143 143

144如果您沒有設定明確名稱，標題會在您發送提示後更新以反映您的提示。{/* min-version: 2.1.176 */}自 Claude Code v2.1.176 起，自動生成的標題會符合您對話的語言，或設定的 [`language`](/zh-TW/settings#available-settings) 設定（如果已配置）。從 claude.ai 或 Claude 應用程式重新命名會話也會更新在 `claude --resume` 中顯示的本地標題。144如果您沒有設定明確名稱，標題會在您發送提示後更新以反映您的提示。自 Claude Code v2.1.176 起，自動生成的標題會符合您對話的語言，或設定的 [`language`](/docs/zh-TW/settings#available-settings) 設定（如果已配置）。從 claude.ai 或 Claude 應用程式重新命名會話也會更新在 `claude --resume` 中顯示的本地標題。

145 145

146如果環境已經有一個活動會話，您將被詢問是否繼續它或啟動一個新會話。146如果環境已經有一個活動會話，您將被詢問是否繼續它或啟動一個新會話。

147 147

151 為所有會話啟用 Remote Control151 為所有會話啟用 Remote Control

152</h3>152</h3>

153 153

154預設情況下，Remote Control 只在您明確執行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 時啟動，除非自動連接已開啟。要為每個互動式會話自動啟用它，請在 Claude Code 內執行 `/config` 並將**為所有會話啟用 Remote Control** 設定為 `true`。將其設定為 `false` 以永不自動連接，或保留未設定以遵循您組織的預設值。在桌面應用程式中，您也可以從**設定 → Claude Code → 預設啟用遠端控制**切換此選項。{/* min-version: 2.1.203 */}在 [VS Code 擴充功能](/zh-TW/vs-code#use-the-prompt-box)中，相同的切換會在命令選單的設定部分中顯示為**為所有會話啟用 Remote Control**；需要 Claude Code v2.1.203 或更新版本。154預設情況下，Remote Control 只在您明確執行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 時啟動，除非自動連接已開啟。要為每個互動式會話自動啟用它，請在 Claude Code 內執行 `/config` 並將**為所有會話啟用 Remote Control** 設定為 `true`。將其設定為 `false` 以永不自動連接，或保留未設定以遵循您組織的預設值。在桌面應用程式中，您也可以從**設定 → Claude Code → 預設啟用遠端控制**切換此選項。在 [VS Code 擴充功能](/docs/zh-TW/vs-code#use-the-prompt-box)中，相同的切換會在命令選單的設定部分中顯示為**為所有會話啟用 Remote Control**；需要 Claude Code v2.1.203 或更新版本。

155 155

156啟用此設定後，每個互動式 Claude Code 程序會註冊一個遠端會話。如果您執行多個實例，每個實例都會獲得自己的環境和會話。要從單個程序執行多個並行會話，請改用[伺服器模式](#start-a-remote-control-session)。156啟用此設定後，每個互動式 Claude Code 程序會註冊一個遠端會話。如果您執行多個實例，每個實例都會獲得自己的環境和會話。要從單個程序執行多個並行會話，請改用[伺服器模式](#start-a-remote-control-session)。

157 157

163 163

164所有流量都透過 TLS 上的 Anthropic API 傳輸，與任何 Claude Code 會話相同的傳輸安全性。連接使用多個短期認證，每個認證的範圍限定為單一目的並獨立過期。164所有流量都透過 TLS 上的 Anthropic API 傳輸，與任何 Claude Code 會話相同的傳輸安全性。連接使用多個短期認證，每個認證的範圍限定為單一目的並獨立過期。

165 165

166Remote Control 連接時，會話記錄（包括您的訊息、Claude 的回應和工具活動）會儲存在 Anthropic 伺服器上。儲存的記錄可讓對話在您的裝置間保持同步，並讓會話在網路中斷後重新連接。執行和檔案系統存取保留在您的機器上，儲存的記錄會根據[資料使用](/zh-TW/data-usage)政策保留。166Remote Control 連接時，會話記錄（包括您的訊息、Claude 的回應和工具活動）會儲存在 Anthropic 伺服器上。儲存的記錄可讓對話在您的裝置間保持同步，並讓會話在網路中斷後重新連接。執行和檔案系統存取保留在您的機器上，儲存的記錄會根據[資料使用](/docs/zh-TW/data-usage)政策保留。

167 167

168若要完全關閉 Remote Control，請使用 [`disableRemoteControl`](/zh-TW/settings#available-settings) 設定。具有零資料保留等合規要求的組織無法啟用 Remote Control。168若要完全關閉 Remote Control，請使用 [`disableRemoteControl`](/docs/zh-TW/settings#available-settings) 設定。具有零資料保留等合規要求的組織無法啟用 Remote Control。

169 169

170<h2 id="trusted-devices">170<h2 id="trusted-devices">

171 受信任的裝置171 受信任的裝置

234 Remote Control 與網頁版 Claude Code 的比較234 Remote Control 與網頁版 Claude Code 的比較

235</h2>235</h2>

236 236

237Remote Control 和[網頁版 Claude Code](/zh-TW/claude-code-on-the-web)都使用 claude.ai/code 介面。關鍵區別在於會話執行的位置：Remote Control 在您的機器上執行，因此您的本地 MCP servers、工具和專案配置保持可用。網頁版 Claude Code 在 Anthropic 管理的雲端基礎設施中執行。237Remote Control 和[網頁版 Claude Code](/docs/zh-TW/claude-code-on-the-web)都使用 claude.ai/code 介面。關鍵區別在於會話執行的位置：Remote Control 在您的機器上執行，因此您的本地 MCP servers、工具和專案配置保持可用。網頁版 Claude Code 在 Anthropic 管理的雲端基礎設施中執行。

238 238

239當您在本地工作中途並想從另一個裝置繼續時，請使用 Remote Control。當您想在沒有任何本地設定的情況下啟動任務、處理您沒有複製的儲存庫或並行執行多個任務時，請使用網頁版 Claude Code。239當您在本地工作中途並想從另一個裝置繼續時，請使用 Remote Control。當您想在沒有任何本地設定的情況下啟動任務、處理您沒有複製的儲存庫或並行執行多個任務時，請使用網頁版 Claude Code。

240 240

272* 在 iOS 上，焦點模式和通知摘要可能會抑制或延遲推播。檢查設定 → 通知 → Claude。272* 在 iOS 上，焦點模式和通知摘要可能會抑制或延遲推播。檢查設定 → 通知 → Claude。

273* 在 Android 上，激進的電池優化可能會延遲傳遞。在系統設定中將 Claude 應用程式豁免於電池優化。273* 在 Android 上，激進的電池優化可能會延遲傳遞。在系統設定中將 Claude 應用程式豁免於電池優化。

274 274

275Claude Code 在您在連接的終端機中輸入或專注時會跳過行動推播通知。{/* min-version: 2.1.181 */}自 v2.1.181 起，您可以將 [`CLAUDE_CLIENT_PRESENCE_FILE`](/zh-TW/env-vars) 設定為標記檔案路徑，以將其擴展到您在機器上的任何時間，即使在另一個視窗中：當檔案存在時，通知會被跳過。配置螢幕鎖定監聽器或類似工具，以在螢幕解鎖時建立檔案，並在螢幕鎖定時刪除檔案。275Claude Code 在您在連接的終端機中輸入或專注時會跳過行動推播通知。自 v2.1.181 起，您可以將 [`CLAUDE_CLIENT_PRESENCE_FILE`](/docs/zh-TW/env-vars) 設定為標記檔案路徑，以將其擴展到您在機器上的任何時間，即使在另一個視窗中：當檔案存在時，通知會被跳過。配置螢幕鎖定監聽器或類似工具，以在螢幕解鎖時建立檔案，並在螢幕鎖定時刪除檔案。

276 276

277<h2 id="limitations">277<h2 id="limitations">

278 限制278 限制

281* **每個互動式程序一個遠端會話**：在伺服器模式之外，每個 Claude Code 實例一次支援一個遠端會話。使用[伺服器模式](#start-a-remote-control-session)從單個程序執行多個並行會話。281* **每個互動式程序一個遠端會話**：在伺服器模式之外，每個 Claude Code 實例一次支援一個遠端會話。使用[伺服器模式](#start-a-remote-control-session)從單個程序執行多個並行會話。

282* **本地程序必須保持執行**：Remote Control 作為本地程序執行。如果您關閉終端機、退出 VS Code 或以其他方式停止 `claude` 程序，會話結束。282* **本地程序必須保持執行**：Remote Control 作為本地程序執行。如果您關閉終端機、退出 VS Code 或以其他方式停止 `claude` 程序，會話結束。

283* **延長的網路中斷**：如果您的機器處於喚醒狀態但無法在大約 10 分鐘以上的時間內到達網路，會話會逾時並且程序退出。再次執行 `claude remote-control` 以啟動新會話。283* **延長的網路中斷**：如果您的機器處於喚醒狀態但無法在大約 10 分鐘以上的時間內到達網路，會話會逾時並且程序退出。再次執行 `claude remote-control` 以啟動新會話。

284* **Ultraplan 斷開 Remote Control**：啟動 [ultraplan](/zh-TW/ultraplan) 會話會斷開任何活動的 Remote Control 會話，因為兩個功能都佔據 claude.ai/code 介面，一次只能連接一個。284* **Ultraplan 斷開 Remote Control**：啟動 [ultraplan](/docs/zh-TW/ultraplan) 會話會斷開任何活動的 Remote Control 會話，因為兩個功能都佔據 claude.ai/code 介面，一次只能連接一個。

285* **某些命令僅限本地**：只在終端機介面中執行的命令，例如 `/plugin` 或 `/resume`，無論您是否傳遞引數，都只能從本地 CLI 使用。以下命令可從行動和網頁使用：285* **某些命令僅限本地**：只在終端機介面中執行的命令，例如 `/plugin` 或 `/resume`，無論您是否傳遞引數，都只能從本地 CLI 使用。以下命令可從行動和網頁使用：

286 * 文字輸出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`（執行文字形式而不是開啟 CLI 內對話框）、`/recap`、`/reload-plugins`286 * 文字輸出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`（執行文字形式而不是開啟 CLI 內對話框）、`/recap`、`/reload-plugins`

287 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：將值作為引數傳遞，例如 `/model sonnet` 或 `/effort high`。從行動和網頁，`/model` 和 `/effort` 在終端機選擇器或滑桿的位置接受引數。287 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：將值作為引數傳遞，例如 `/model sonnet` 或 `/effort high`。從行動和網頁，`/model` 和 `/effort` 在終端機選擇器或滑桿的位置接受引數。

288 * {/* min-version: 2.1.166 */}`/mcp`，自 v2.1.166 起：從行動應用程式，傳回伺服器狀態的文字摘要而不是開啟選擇器。在網頁上，`/mcp` 單獨開啟 [claude.ai 連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)的目錄而不是傳回摘要。`reconnect`、`enable` 和 `disable` [子命令](/zh-TW/commands#all-commands)可從兩者使用。與本地 CLI 不同，`/mcp reconnect` 不帶伺服器名稱會重新連接每個已失敗或需要驗證的伺服器。288 * `/mcp`，自 v2.1.166 起：從行動應用程式，傳回伺服器狀態的文字摘要而不是開啟選擇器。在網頁上，`/mcp` 單獨開啟 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)的目錄而不是傳回摘要。`reconnect`、`enable` 和 `disable` [子命令](/docs/zh-TW/commands#all-commands)可從兩者使用。與本地 CLI 不同，`/mcp reconnect` 不帶伺服器名稱會重新連接每個已失敗或需要驗證的伺服器。

289 * {/* min-version: 2.1.181 */}`/config`，自 v2.1.181 起：從行動應用程式，傳遞 `key=value` 以設定設定，或不帶引數執行以列出您可以設定的金鑰。在網頁上，`/config` 改為開啟您設定的 Claude Code 部分，並忽略命令後的文字。289 * `/config`，自 v2.1.181 起：從行動應用程式，傳遞 `key=value` 以設定設定，或不帶引數執行以列出您可以設定的金鑰。在網頁上，`/config` 改為開啟您設定的 Claude Code 部分，並忽略命令後的文字。

290 290

291<h2 id="troubleshooting">291<h2 id="troubleshooting">

292 疑難排解292 疑難排解

298 298

299您未使用 claude.ai 帳戶進行驗證。執行 `claude auth login` 並選擇 claude.ai 選項。如果在您的環境中設定了 `ANTHROPIC_API_KEY`，請先取消設定它。299您未使用 claude.ai 帳戶進行驗證。執行 `claude auth login` 並選擇 claude.ai 選項。如果在您的環境中設定了 `ANTHROPIC_API_KEY`，請先取消設定它。

300 300

301{/* min-version: 2.1.206 */}在 v2.1.206 之前，在登出時執行 `/remote-control` 會報告 `Unknown command: /remote-control` 而不是此訊息。301在 v2.1.206 之前，在登出時執行 `/remote-control` 會報告 `Unknown command: /remote-control` 而不是此訊息。

302 302

303<h3 id="remote-control-requires-a-full-scope-login-token">303<h3 id="remote-control-requires-a-full-scope-login-token">

304 「Remote Control 需要完整範圍登入令牌」304 「Remote Control 需要完整範圍登入令牌」

328 「Remote Control 僅在透過 api.anthropic.com 使用 Claude 時可用」328 「Remote Control 僅在透過 api.anthropic.com 使用 Claude 時可用」

329</h3>329</h3>

330 330

331會話未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端可配對。這發生在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機時，例如 [LLM 閘道](/zh-TW/llm-gateway)或代理，即使您使用 claude.ai 登入，也會發生這種情況。取消設定 `ANTHROPIC_BASE_URL` 並重新啟動會話以使用 Remote Control。331會話未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端可配對。這發生在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。自 v2.1.196 起，當 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機時，例如 [LLM 閘道](/docs/zh-TW/llm-gateway)或代理，即使您使用 claude.ai 登入，也會發生這種情況。取消設定 `ANTHROPIC_BASE_URL` 並重新啟動會話以使用 Remote Control。

332 332

333<h3 id="remote-control-is-disabled-by-your-organization’s-policy">333<h3 id="remote-control-is-disabled-by-your-organization’s-policy">

334 「Remote Control 已被您的組織政策停用」334 「Remote Control 已被您的組織政策停用」

339* **您使用 API 金鑰或 Console 帳戶進行驗證**：Remote Control 需要 claude.ai OAuth。執行 `/login` 並選擇 claude.ai 選項。如果在您的環境中設定了 `ANTHROPIC_API_KEY`，請取消設定它。339* **您使用 API 金鑰或 Console 帳戶進行驗證**：Remote Control 需要 claude.ai OAuth。執行 `/login` 並選擇 claude.ai 選項。如果在您的環境中設定了 `ANTHROPIC_API_KEY`，請取消設定它。

340* **您的組織管理員尚未啟用它**：Remote Control 在 Team 和 Enterprise 方案上預設為關閉。管理員可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 透過開啟 **Remote Control** 切換來啟用它。此切換是伺服器端組織設定。340* **您的組織管理員尚未啟用它**：Remote Control 在 Team 和 Enterprise 方案上預設為關閉。管理員可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 透過開啟 **Remote Control** 切換來啟用它。此切換是伺服器端組織設定。

341* **管理員切換呈灰色**：您的組織具有與 Remote Control 不相容的資料保留或合規配置。這無法從管理面板更改。請聯絡 Anthropic 支援以討論選項。341* **管理員切換呈灰色**：您的組織具有與 Remote Control 不相容的資料保留或合規配置。這無法從管理面板更改。請聯絡 Anthropic 支援以討論選項。

342* **錯誤提及 `disableRemoteControl`**：您的 IT 管理員已透過[受管設定](/zh-TW/settings#settings-files)在此裝置上停用 Remote Control，獨立於組織範圍的切換。342* **錯誤提及 `disableRemoteControl`**：您的 IT 管理員已透過[受管設定](/docs/zh-TW/settings#settings-files)在此裝置上停用 Remote Control，獨立於組織範圍的切換。

343 343

344<h3 id="remote-credentials-fetch-failed">344<h3 id="remote-credentials-fetch-failed">

345 「Remote credentials fetch failed」345 「Remote credentials fetch failed」

365 365

366您的本機會話在沒有 Remote Control 的情況下繼續執行。執行 `/remote-control` 以重試連接，或在不使用 `--resume` 的情況下啟動 Claude Code 以建立新的 Remote Control 會話。366您的本機會話在沒有 Remote Control 的情況下繼續執行。執行 `/remote-control` 以重試連接，或在不使用 `--resume` 的情況下啟動 Claude Code 以建立新的 Remote Control 會話。

367 367

368{/* min-version: 2.1.200 */}在 v2.1.200 之前，重新連接失敗會建立新的 Remote Control 會話，而不是顯示此訊息，這在 claude.ai/code 的會話清單中留下了額外的會話。368在 v2.1.200 之前，重新連接失敗會建立新的 Remote Control 會話，而不是顯示此訊息，這在 claude.ai/code 的會話清單中留下了額外的會話。

369 369

370<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">370<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">

371 「您的組織需要受信任的裝置進行 Remote Control，但此裝置未註冊」371 「您的組織需要受信任的裝置進行 Remote Control，但此裝置未註冊」

387 387

389| :--------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |389| :--------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |

392| [Channels](/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/en/channels#quickstart) or [build your own](/en/channels-reference) | Reacting to external events like CI failures or chat messages |392| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |

395 395

396<h2 id="related-resources">396<h2 id="related-resources">

397 相關資源397 相關資源

398</h2>398</h2>

399 399

400* [網頁版 Claude Code](/zh-TW/claude-code-on-the-web)：在 Anthropic 管理的雲端環境中執行會話，而不是在您的機器上400* [網頁版 Claude Code](/docs/zh-TW/claude-code-on-the-web)：在 Anthropic 管理的雲端環境中執行會話，而不是在您的機器上

401* [Ultraplan](/zh-TW/ultraplan)：從您的終端機啟動雲端規劃會話，並在瀏覽器中檢查計畫401* [Ultraplan](/docs/zh-TW/ultraplan)：從您的終端機啟動雲端規劃會話，並在瀏覽器中檢查計畫

402* [Channels](/zh-TW/channels)：將 Telegram、Discord 或 iMessage 轉發到會話中，以便 Claude 在您離開時對訊息做出反應402* [Channels](/docs/zh-TW/channels)：將 Telegram、Discord 或 iMessage 轉發到會話中，以便 Claude 在您離開時對訊息做出反應

403* [Dispatch](/zh-TW/desktop#sessions-from-dispatch)：從您的手機傳送任務訊息，它可以生成 Desktop 會話來處理它403* [Dispatch](/docs/zh-TW/desktop#sessions-from-dispatch)：從您的手機傳送任務訊息，它可以生成 Desktop 會話來處理它

404* [驗證](/zh-TW/authentication)：設定 `/login` 並管理 claude.ai 的認證404* [驗證](/docs/zh-TW/authentication)：設定 `/login` 並管理 claude.ai 的認證

405* [CLI 參考](/zh-TW/cli-reference)：包括 `claude remote-control` 的旗標和命令的完整清單405* [CLI 參考](/docs/zh-TW/cli-reference)：包括 `claude remote-control` 的旗標和命令的完整清單

406* [安全性](/zh-TW/security)：Remote Control 會話如何適應 Claude Code 安全模型406* [安全性](/docs/zh-TW/security)：Remote Control 會話如何適應 Claude Code 安全模型

407* [資料使用](/zh-TW/data-usage)：在本地和遠端會話期間透過 Anthropic API 流動的資料407* [資料使用](/docs/zh-TW/data-usage)：在本地和遠端會話期間透過 Anthropic API 流動的資料

sandboxing.md +44 −44

Details

9Bash 沙箱讓 Claude 執行大多數 shell 命令，而無需停下來請求權限。與其批准每個命令，您可以定義命令可以接觸哪些檔案和網路域，作業系統會為每個 Bash 命令及其子流程強制執行該邊界。9Bash 沙箱讓 Claude 執行大多數 shell 命令，而無需停下來請求權限。與其批准每個命令，您可以定義命令可以接觸哪些檔案和網路域，作業系統會為每個 Bash 命令及其子流程強制執行該邊界。

10 10

11<Note>11<Note>

12 若要比較其他隔離方法，例如開發容器、自訂容器和虛擬機，請參閱 [Sandbox environments](/zh-TW/sandbox-environments)。若要減少 Bash 以外工具的權限提示，請參閱 [permission modes](/zh-TW/permission-modes)。12 若要比較其他隔離方法，例如開發容器、自訂容器和虛擬機，請參閱 [Sandbox environments](/docs/zh-TW/sandbox-environments)。若要減少 Bash 以外工具的權限提示，請參閱 [permission modes](/docs/zh-TW/permission-modes)。

13</Note>13</Note>

14 14

15<h2 id="get-started">15<h2 id="get-started">

31 這會開啟沙箱面板，有三個標籤：31 這會開啟沙箱面板，有三個標籤：

32 32

33 * **Mode**：選擇沙箱化命令的批准方式，詳見下一步33 * **Mode**：選擇沙箱化命令的批准方式，詳見下一步

~~34 * **Overrides**：選擇在沙箱下失敗的命令是否可以回退到執行未沙箱化。這是 [`allowUnsandboxedCommands`](/zh-TW/settings#sandbox-settings) 設定~~34 * **Overrides**：選擇在沙箱下失敗的命令是否可以回退到執行未沙箱化。這是 [`allowUnsandboxedCommands`](/docs/zh-TW/settings#sandbox-settings) 設定

35 * **Config**：檢視已解析的沙箱設定35 * **Config**：檢視已解析的沙箱設定

36 36

37 如果面板只顯示 Dependencies 標籤，則缺少必需的套件。按照 [Set up Linux and WSL2](#set-up-linux-and-wsl2) 中的說明安裝它，重新啟動 Claude Code，然後再次執行 `/sandbox`。37 如果面板只顯示 Dependencies 標籤，則缺少必需的套件。按照 [Set up Linux and WSL2](#set-up-linux-and-wsl2) 中的說明安裝它，重新啟動 Claude Code，然後再次執行 `/sandbox`。

48 </Step>48 </Step>

49</Steps>49</Steps>

50 50

51在面板中選擇模式會寫入您專案的本地設定，位於 `.claude/settings.local.json`，這適用於目前專案，不會簽入 git。若要在所有專案中啟用沙箱，請在 `~/.claude/settings.json` 的使用者設定中將 [`sandbox.enabled`](/zh-TW/settings#sandbox-settings) 設定為 `true`。若要為組織中的每個開發人員強制執行沙箱化，請使用 [managed settings](#enforce-sandboxing-with-managed-settings)。51在面板中選擇模式會寫入您專案的本地設定，位於 `.claude/settings.local.json`，這適用於目前專案，不會簽入 git。若要在所有專案中啟用沙箱，請在 `~/.claude/settings.json` 的使用者設定中將 [`sandbox.enabled`](/docs/zh-TW/settings#sandbox-settings) 設定為 `true`。若要為組織中的每個開發人員強制執行沙箱化，請使用 [managed settings](#enforce-sandboxing-with-managed-settings)。

52 52

53<Warning>53<Warning>

54 預設情況下，如果沙箱因缺少依賴項或不支援的平台而無法啟動，Claude Code 會顯示警告並在沒有沙箱化的情況下執行命令。若要改為將其設為硬失敗，請將 [`sandbox.failIfUnavailable`](/zh-TW/settings#sandbox-settings) 設定為 `true`。這適用於需要沙箱化作為安全閘道的受管部署。54 預設情況下，如果沙箱因缺少依賴項或不支援的平台而無法啟動，Claude Code 會顯示警告並在沒有沙箱化的情況下執行命令。若要改為將其設為硬失敗，請將 [`sandbox.failIfUnavailable`](/docs/zh-TW/settings#sandbox-settings) 設定為 `true`。這適用於需要沙箱化作為安全閘道的受管部署。

55</Warning>55</Warning>

56 56

57<h3 id="set-up-linux-and-wsl2">57<h3 id="set-up-linux-and-wsl2">

111 <Accordion title="WSL2 注意事項">111 <Accordion title="WSL2 注意事項">

112 使用 PowerShell 中的 `wsl -l -v` 檢查您的 WSL 版本。如果您看到 `Sandboxing requires WSL2`，您的發行版執行的是 WSL1。將其升級到 WSL2 或在沒有沙箱化的情況下執行 Claude Code。112 使用 PowerShell 中的 `wsl -l -v` 檢查您的 WSL 版本。如果您看到 `Sandboxing requires WSL2`，您的發行版執行的是 WSL1。將其升級到 WSL2 或在沒有沙箱化的情況下執行 Claude Code。

113 113

114 在 WSL2 上，沙箱化命令無法啟動 Windows 二進位檔案，例如 `cmd.exe`、`powershell.exe` 或 `/mnt/c/` 下的任何內容。WSL 通過 Unix 套接字將這些交給 Windows 主機，沙箱會阻止此操作。如果命令需要呼叫 Windows 二進位檔案，請將其新增到 [`excludedCommands`](/zh-TW/settings#sandbox-settings)，以便它在沙箱外執行。114 在 WSL2 上，沙箱化命令無法啟動 Windows 二進位檔案，例如 `cmd.exe`、`powershell.exe` 或 `/mnt/c/` 下的任何內容。WSL 通過 Unix 套接字將這些交給 Windows 主機，沙箱會阻止此操作。如果命令需要呼叫 Windows 二進位檔案，請將其新增到 [`excludedCommands`](/docs/zh-TW/settings#sandbox-settings)，以便它在沙箱外執行。

115 </Accordion>115 </Accordion>

116</AccordionGroup>116</AccordionGroup>

117 117

121 121

122Claude Code 提供兩種沙箱模式：122Claude Code 提供兩種沙箱模式：

123 123

124**自動允許模式**：Bash 命令將嘗試在沙箱內執行，並自動允許而無需權限。無法沙箱化的命令（例如需要存取非允許主機的網路存取的命令）會回退到常規權限流程，其中 Claude Code 檢查您的 [permission rules](/zh-TW/permissions) 並提示您進行這些規則不允許的任何命令，在預設模式中提示或在 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中使用分類器。124**自動允許模式**：Bash 命令將嘗試在沙箱內執行，並自動允許而無需權限。無法沙箱化的命令（例如需要存取非允許主機的網路存取的命令）會回退到常規權限流程，其中 Claude Code 檢查您的 [permission rules](/docs/zh-TW/permissions) 並提示您進行這些規則不允許的任何命令，在預設模式中提示或在 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中使用分類器。

125 125

126即使在自動允許模式中，以下仍然適用：126即使在自動允許模式中，以下仍然適用：

127 127

128* 明確的 [deny rules](/zh-TW/permissions) 始終被尊重128* 明確的 [deny rules](/docs/zh-TW/permissions) 始終被尊重

129* 針對 `/`、您的主目錄或其他關鍵系統路徑的 `rm` 或 `rmdir` 命令仍然會觸發權限提示129* 針對 `/`、您的主目錄或其他關鍵系統路徑的 `rm` 或 `rmdir` 命令仍然會觸發權限提示

130* 內容範圍的 [ask rules](/zh-TW/permissions)（例如 `Bash(git push *)`）仍然會強制提示，即使是沙箱化命令130* 內容範圍的 [ask rules](/docs/zh-TW/permissions)（例如 `Bash(git push *)`）仍然會強制提示，即使是沙箱化命令

131* 裸 `Bash` ask 規則，或等效的 `Bash(*)` 形式，對於執行沙箱化的命令會被跳過；它仍然適用於回退到常規權限流程的命令131* 裸 `Bash` ask 規則，或等效的 `Bash(*)` 形式，對於執行沙箱化的命令會被跳過；它仍然適用於回退到常規權限流程的命令

132 132

133**常規權限模式**：所有 Bash 命令都通過常規權限流程進行，即使沙箱化也是如此。這提供了更多控制，但需要更多批准。133**常規權限模式**：所有 Bash 命令都通過常規權限流程進行，即使沙箱化也是如此。這提供了更多控制，但需要更多批准。

136 136

137工作階段暫存目錄在沙箱內預設可寫，與工作目錄一起。Claude Code 為沙箱化命令設定 `$TMPDIR` 為此目錄，因此寫入暫存檔案的工具無需額外配置即可工作。未沙箱化命令繼承您的 shell 的 `$TMPDIR` 不變，這意味著沙箱化和未沙箱化命令將 `$TMPDIR` 解析為不同的目錄。若要在兩者之間傳遞暫存檔案，請改為在工作目錄下寫入它們。137工作階段暫存目錄在沙箱內預設可寫，與工作目錄一起。Claude Code 為沙箱化命令設定 `$TMPDIR` 為此目錄，因此寫入暫存檔案的工具無需額外配置即可工作。未沙箱化命令繼承您的 shell 的 `$TMPDIR` 不變，這意味著沙箱化和未沙箱化命令將 `$TMPDIR` 解析為不同的目錄。若要在兩者之間傳遞暫存檔案，請改為在工作目錄下寫入它們。

138 138

139某些命令根本無法在沙箱內執行，例如與其不相容的工具或需要您未允許的主機的工具。與其讓任務失敗或要求您關閉沙箱化，Claude Code 包含一個逃生艙：當命令因沙箱限制而失敗時，Claude 分析失敗，可能使用 `dangerouslyDisableSandbox` 參數重試命令。重試的命令在沙箱外執行，因此通過常規權限流程進行：在預設模式中您會獲得確認提示；在 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中分類器評估基礎命令而不是提示您。若要在 auto mode 中即使在每次未沙箱化重試時也被提示，請新增 [ask rule](/zh-TW/permissions#match-by-input-parameter) 用於 `Bash(dangerouslyDisableSandbox:true)`。139某些命令根本無法在沙箱內執行，例如與其不相容的工具或需要您未允許的主機的工具。與其讓任務失敗或要求您關閉沙箱化，Claude Code 包含一個逃生艙：當命令因沙箱限制而失敗時，Claude 分析失敗，可能使用 `dangerouslyDisableSandbox` 參數重試命令。重試的命令在沙箱外執行，因此通過常規權限流程進行：在預設模式中您會獲得確認提示；在 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中分類器評估基礎命令而不是提示您。若要在 auto mode 中即使在每次未沙箱化重試時也被提示，請新增 [ask rule](/docs/zh-TW/permissions#match-by-input-parameter) 用於 `Bash(dangerouslyDisableSandbox:true)`。

140 140

141您可以通過在 [sandbox settings](/zh-TW/settings#sandbox-settings) 中設定 `"allowUnsandboxedCommands": false` 來禁用此逃生艙。禁用時，`/sandbox` Overrides 標籤顯示為 **Strict sandbox mode**，`dangerouslyDisableSandbox` 參數被完全忽略，所有命令必須沙箱化執行或在 `excludedCommands` 中明確列出。141您可以通過在 [sandbox settings](/docs/zh-TW/settings#sandbox-settings) 中設定 `"allowUnsandboxedCommands": false` 來禁用此逃生艙。禁用時，`/sandbox` Overrides 標籤顯示為 **Strict sandbox mode**，`dangerouslyDisableSandbox` 參數被完全忽略，所有命令必須沙箱化執行或在 `excludedCommands` 中明確列出。

142 142

143<Info>143<Info>

144 自動允許模式獨立於您的權限模式設定工作。即使您不在「接受編輯」模式中，當啟用自動允許時，沙箱化 Bash 命令也會自動執行。這意味著在沙箱邊界內修改檔案的 Bash 命令將執行而不提示，即使檔案編輯工具通常需要批准。144 自動允許模式獨立於您的權限模式設定工作。即使您不在「接受編輯」模式中，當啟用自動允許時，沙箱化 Bash 命令也會自動執行。這意味著在沙箱邊界內修改檔案的 Bash 命令將執行而不提示，即使檔案編輯工具通常需要批准。

148 設定沙箱化148 設定沙箱化

149</h2>149</h2>

150 150

151通過您的 `settings.json` 檔案自訂沙箱行為。請參閱 [Settings](/zh-TW/settings#sandbox-settings) 以了解完整的配置參考。151通過您的 `settings.json` 檔案自訂沙箱行為。請參閱 [Settings](/docs/zh-TW/settings#sandbox-settings) 以了解完整的配置參考。

152 152

153預設情況下，沙箱化命令只能寫入目前工作目錄和工作階段暫存目錄。如果子流程命令（如 `kubectl`、`terraform` 或 `npm`）需要寫入這些目錄外，請使用 `sandbox.filesystem.allowWrite` 授予對特定路徑的存取：153預設情況下，沙箱化命令只能寫入目前工作目錄和工作階段暫存目錄。如果子流程命令（如 `kubectl`、`terraform` 或 `npm`）需要寫入這些目錄外，請使用 `sandbox.filesystem.allowWrite` 授予對特定路徑的存取：

154 154

165 165

166這些路徑在作業系統級別強制執行，因此在沙箱內執行的所有命令（包括其子流程）都尊重它們。當工具需要對特定位置的寫入存取時，這是推薦的方法，而不是使用 `excludedCommands` 將工具排除在沙箱外。166這些路徑在作業系統級別強制執行，因此在沙箱內執行的所有命令（包括其子流程）都尊重它們。當工具需要對特定位置的寫入存取時，這是推薦的方法，而不是使用 `excludedCommands` 將工具排除在沙箱外。

167 167

168當在多個 [settings scopes](/zh-TW/settings#settings-precedence) 中定義相同的檔案系統陣列時，陣列被合併：來自每個範圍的路徑被組合，而不是被替換。168當在多個 [settings scopes](/docs/zh-TW/settings#settings-precedence) 中定義相同的檔案系統陣列時，陣列被合併：來自每個範圍的路徑被組合，而不是被替換。

169 169

170路徑前綴控制路徑的解析方式：170路徑前綴控制路徑的解析方式：

171 171

175| `~/` | 相對於主目錄 | `~/.kube` 變成 `$HOME/.kube` |175| `~/` | 相對於主目錄 | `~/.kube` 變成 `$HOME/.kube` |

177 177

178此語法與 [Read and Edit permission rules](/zh-TW/permissions#read-and-edit) 不同，後者使用 `//path` 表示絕對路徑，`/path` 表示專案相對路徑。沙箱檔案系統路徑使用標準慣例：`/tmp/build` 是絕對路徑。178此語法與 [Read and Edit permission rules](/docs/zh-TW/permissions#read-and-edit) 不同，後者使用 `//path` 表示絕對路徑，`/path` 表示專案相對路徑。沙箱檔案系統路徑使用標準慣例：`/tmp/build` 是絕對路徑。

179 179

180您也可以使用 `sandbox.filesystem.denyWrite` 和 `sandbox.filesystem.denyRead` 拒絕寫入或讀取存取，並使用 `sandbox.filesystem.allowRead` 重新允許讀取被拒絕區域內的特定路徑。當讀取規則重疊時，更具體的路徑優先：180您也可以使用 `sandbox.filesystem.denyWrite` 和 `sandbox.filesystem.denyRead` 拒絕寫入或讀取存取，並使用 `sandbox.filesystem.allowRead` 重新允許讀取被拒絕區域內的特定路徑。當讀取規則重疊時，更具體的路徑優先：

181 181

230 230

231檔案項目僅支援 `"mode": "deny"`。環境變數項目也接受 `"mode": "mask"`，如下所述。231檔案項目僅支援 `"mode": "deny"`。環境變數項目也接受 `"mode": "mask"`，如下所述。

232 232

233檔案路徑遵循與 `sandbox.filesystem.*` 設定相同的 [prefix rules](/zh-TW/settings#sandbox-path-prefixes)，來自每個 [settings scope](/zh-TW/settings#settings-precedence) 的 `deny` 項目被合併。`deny` 項目只會縮小存取，因此任何範圍都可以新增一個，但沒有任何範圍可以移除另一個範圍新增的項目。233檔案路徑遵循與 `sandbox.filesystem.*` 設定相同的 [prefix rules](/docs/zh-TW/settings#sandbox-path-prefixes)，來自每個 [settings scope](/docs/zh-TW/settings#settings-precedence) 的 `deny` 項目被合併。`deny` 項目只會縮小存取，因此任何範圍都可以新增一個，但沒有任何範圍可以移除另一個範圍新增的項目。

234 234

235沒有內建的認證拒絕清單，因此只有您列出的檔案和變數被限制。此設定僅影響沙箱化 Bash 命令。若要從所有子流程中移除 Anthropic 和雲端提供者認證，無論沙箱化如何，請設定 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-TW/env-vars)。235沒有內建的認證拒絕清單，因此只有您列出的檔案和變數被限制。此設定僅影響沙箱化 Bash 命令。若要從所有子流程中移除 Anthropic 和雲端提供者認證，無論沙箱化如何，請設定 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/zh-TW/env-vars)。

236 236

237<h4 id="mask-environment-variables">237<h4 id="mask-environment-variables">

238 遮罩環境變數238 遮罩環境變數

242 242

243使用 `mask`，沙箱化命令看到的是每個工作階段的哨兵值而不是真實值。當請求離開沙箱前往認證的 `injectHosts` 之一時，[sandbox proxy](#network-isolation) 將哨兵值替換為真實值。命令和它記錄的任何內容都不會持有真實認證，但其請求仍然進行身份驗證。243使用 `mask`，沙箱化命令看到的是每個工作階段的哨兵值而不是真實值。當請求離開沙箱前往認證的 `injectHosts` 之一時，[sandbox proxy](#network-isolation) 將哨兵值替換為真實值。命令和它記錄的任何內容都不會持有真實認證，但其請求仍然進行身份驗證。

244 244

245代理在請求內容中替換認證，因此它必須看到它們。設定 [`network.tlsTerminate`](/zh-TW/settings#sandbox-settings) 以便代理自己終止 TLS。沒有它，遮罩會失敗關閉：命令仍然只看到哨兵值，但哨兵值不變地到達伺服器，身份驗證失敗。Claude Code 在啟動時報告此配置錯誤。245代理在請求內容中替換認證，因此它必須看到它們。設定 [`network.tlsTerminate`](/docs/zh-TW/settings#sandbox-settings) 以便代理自己終止 TLS。沒有它，遮罩會失敗關閉：命令仍然只看到哨兵值，但哨兵值不變地到達伺服器，身份驗證失敗。Claude Code 在啟動時報告此配置錯誤。

246 246

247下面的範例遮罩兩個令牌。`GH_TOKEN` 僅在對 `api.github.com` 的請求上被替換，而 `NPM_TOKEN` 沒有 `injectHosts` 並在對 `network.allowedDomains` 中每個主機的請求上被替換。每個 `injectHosts` 項目本身必須被 `network.allowedDomains` 覆蓋。247下面的範例遮罩兩個令牌。`GH_TOKEN` 僅在對 `api.github.com` 的請求上被替換，而 `NPM_TOKEN` 沒有 `injectHosts` 並在對 `network.allowedDomains` 中每個主機的請求上被替換。每個 `injectHosts` 項目本身必須被 `network.allowedDomains` 覆蓋。

248 248

264}264}

265```265```

266 266

267與 `deny` 不同，遮罩授權代理將您的真實認證發送到列出的主機，因此它僅從您或您的管理員控制的設定中被尊重：使用者設定、受管設定和 `--settings` CLI 旗標。`mask` 項目、`network.tlsTerminate` 和 [`credentials.allowPlaintextInject`](/zh-TW/settings#sandbox-settings) 在儲存庫的 `.claude/settings.json` 或 `.claude/settings.local.json` 中被忽略。267與 `deny` 不同，遮罩授權代理將您的真實認證發送到列出的主機，因此它僅從您或您的管理員控制的設定中被尊重：使用者設定、受管設定和 `--settings` CLI 旗標。`mask` 項目、`network.tlsTerminate` 和 [`credentials.allowPlaintextInject`](/docs/zh-TW/settings#sandbox-settings) 在儲存庫的 `.claude/settings.json` 或 `.claude/settings.local.json` 中被忽略。

268 268

269當相同的變數在任何範圍中以 `deny` 列出時，`deny` 優先。269當相同的變數在任何範圍中以 `deny` 列出時，`deny` 優先。

270 270

281* **預設寫入行為**：對目前工作目錄及其子目錄的讀取和寫入存取，加上 `$TMPDIR` 指向的工作階段暫存目錄281* **預設寫入行為**：對目前工作目錄及其子目錄的讀取和寫入存取，加上 `$TMPDIR` 指向的工作階段暫存目錄

282* **預設讀取行為**：對整個電腦的讀取存取，除了某些被拒絕的目錄。請注意，此預設仍允許讀取認證檔案，例如 `~/.aws/credentials` 和 `~/.ssh/`。使用 [`sandbox.credentials`](#protect-credentials) 來阻止讀取這些檔案並取消設定祕密環境變數，或將路徑新增到 `denyRead`。282* **預設讀取行為**：對整個電腦的讀取存取，除了某些被拒絕的目錄。請注意，此預設仍允許讀取認證檔案，例如 `~/.aws/credentials` 和 `~/.ssh/`。使用 [`sandbox.credentials`](#protect-credentials) 來阻止讀取這些檔案並取消設定祕密環境變數，或將路徑新增到 `denyRead`。

283* **被阻止的存取**：無法在沒有明確權限的情況下修改目前工作目錄和工作階段暫存目錄外的檔案，包括 shell 配置檔案（例如 `~/.bashrc`）和 `/bin/` 中的系統二進位檔案283* **被阻止的存取**：無法在沒有明確權限的情況下修改目前工作目錄和工作階段暫存目錄外的檔案，包括 shell 配置檔案（例如 `~/.bashrc`）和 `/bin/` 中的系統二進位檔案

284* **Git worktrees**：當工作目錄是[連結的 git worktree](/zh-TW/worktrees)時，沙箱也允許寫入主儲存庫的共享 `.git` 目錄，以便 `git commit` 等命令可以更新 refs 和索引。對該目錄內的 `hooks/` 和 `config` 的寫入仍然被拒絕。284* **Git worktrees**：當工作目錄是[連結的 git worktree](/docs/zh-TW/worktrees)時，沙箱也允許寫入主儲存庫的共享 `.git` 目錄，以便 `git commit` 等命令可以更新 refs 和索引。對該目錄內的 `hooks/` 和 `config` 的寫入仍然被拒絕。

285* **可配置**：通過設定定義自訂允許和拒絕的路徑285* **可配置**：通過設定定義自訂允許和拒絕的路徑

286 286

287您可以使用設定中的 `sandbox.filesystem.allowWrite` 授予對其他路徑的寫入存取。這些限制在作業系統級別強制執行，因此它們適用於所有子流程命令，包括 `kubectl`、`terraform` 和 `npm` 等工具，而不僅僅是 Claude 的檔案工具。287您可以使用設定中的 `sandbox.filesystem.allowWrite` 授予對其他路徑的寫入存取。這些限制在作業系統級別強制執行，因此它們適用於所有子流程命令，包括 `kubectl`、`terraform` 和 `npm` 等工具，而不僅僅是 Claude 的檔案工具。

292 292

293網路存取通過在沙箱外執行的代理伺服器進行控制：293網路存取通過在沙箱外執行的代理伺服器進行控制：

294 294

295* **域名限制**：沒有預先允許的域名。命令首次需要新的域名時，Claude Code 會提示批准。{/* min-version: 2.1.191 */}自 v2.1.191 起，選擇「是」允許該主機在目前工作階段的其餘時間內使用，因此稍後連線到同一主機時不會再次提示。使用 [`allowedDomains`](/zh-TW/settings#sandbox-settings) 預先允許域名以避免提示。295* **域名限制**：沒有預先允許的域名。命令首次需要新的域名時，Claude Code 會提示批准。自 v2.1.191 起，選擇「是」允許該主機在目前工作階段的其餘時間內使用，因此稍後連線到同一主機時不會再次提示。使用 [`allowedDomains`](/docs/zh-TW/settings#sandbox-settings) 預先允許域名以避免提示。

296* **受管鎖定**：如果在受管設定中設定了 [`allowManagedDomainsOnly`](/zh-TW/settings#sandbox-settings)，非允許的域名會自動被阻止而不是提示，只有來自受管設定的 `allowedDomains` 被尊重。296* **受管鎖定**：如果在受管設定中設定了 [`allowManagedDomainsOnly`](/docs/zh-TW/settings#sandbox-settings)，非允許的域名會自動被阻止而不是提示，只有來自受管設定的 `allowedDomains` 被尊重。

297* **自訂代理支援**：進階使用者可以在出站流量上實施自訂規則297* **自訂代理支援**：進階使用者可以在出站流量上實施自訂規則

298* **全面覆蓋**：限制適用於所有指令碼、程式和由命令產生的子流程298* **全面覆蓋**：限制適用於所有指令碼、程式和由命令產生的子流程

299 299

300<Note>300<Note>

301 內建代理根據請求的主機名強制執行允許清單，預設不終止或檢查 TLS 流量。{/* min-version: 2.1.199 */}實驗性的 [`network.tlsTerminate`](/zh-TW/settings#sandbox-settings) 設定在 Claude Code v2.1.199 及更新版本中可用，使內建代理自行終止 TLS，這是 [`mask` 認證項目](#protect-credentials)所需的。請參閱 [Security limitations](#security-limitations) 了解預設設計的含義，以及 [Custom proxy configuration](#custom-proxy-configuration) 如果您的威脅模型需要 TLS 檢查。301 內建代理根據請求的主機名強制執行允許清單，預設不終止或檢查 TLS 流量。實驗性的 [`network.tlsTerminate`](/docs/zh-TW/settings#sandbox-settings) 設定在 Claude Code v2.1.199 及更新版本中可用，使內建代理自行終止 TLS，這是 [`mask` 認證項目](#protect-credentials)所需的。請參閱 [Security limitations](#security-limitations) 了解預設設計的含義，以及 [Custom proxy configuration](#custom-proxy-configuration) 如果您的威脅模型需要 TLS 檢查。

302</Note>302</Note>

303 303

304<h3 id="os-level-enforcement">304<h3 id="os-level-enforcement">

313 313

314不支援 WSL1，因為 bubblewrap 需要僅在 WSL2 中可用的核心功能。這些作業系統級別的限制確保由 Claude Code 命令產生的所有子流程都繼承相同的安全邊界。314不支援 WSL1，因為 bubblewrap 需要僅在 WSL2 中可用的核心功能。這些作業系統級別的限制確保由 Claude Code 命令產生的所有子流程都繼承相同的安全邊界。

315 315

316這些相同的原語可作為獨立的 [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) 套件使用，[Sandbox environments](/zh-TW/sandbox-environments#sandbox-runtime) 頁面涵蓋作為包裝整個 Claude Code 流程的單獨方法。316這些相同的原語可作為獨立的 [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) 套件使用，[Sandbox environments](/docs/zh-TW/sandbox-environments#sandbox-runtime) 頁面涵蓋作為包裝整個 Claude Code 流程的單獨方法。

317 317

318<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">318<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">

319 沙箱化與權限和權限模式的關係319 沙箱化與權限和權限模式的關係

320</h2>320</h2>

321 321

322沙箱化、[permission rules](/zh-TW/permissions) 和 [permission modes](/zh-TW/permission-modes) 是互補的層。下面的部分涵蓋沙箱如何與每個互動。322沙箱化、[permission rules](/docs/zh-TW/permissions) 和 [permission modes](/docs/zh-TW/permission-modes) 是互補的層。下面的部分涵蓋沙箱如何與每個互動。

323 323

324<h3 id="permission-rules">324<h3 id="permission-rules">

325 權限規則325 權限規則

353 權限模式353 權限模式

354</h3>354</h3>

355 355

356`/sandbox` 不是 [permission mode](/zh-TW/permission-modes)。權限模式決定工具呼叫是否執行以及您是否首先被提示，而沙箱限制 Bash 命令執行後可以存取的內容。它們在控制的內容和替換每個操作提示的內容上有所不同：356`/sandbox` 不是 [permission mode](/docs/zh-TW/permission-modes)。權限模式決定工具呼叫是否執行以及您是否首先被提示，而沙箱限制 Bash 命令執行後可以存取的內容。它們在控制的內容和替換每個操作提示的內容上有所不同：

357 357

358| | 它控制什麼 | 替換提示的內容 |358| | 它控制什麼 | 替換提示的內容 |

359| :-------------------------------------------------------------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |359| :-------------------------------------------------------------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

362| `--dangerously-skip-permissions` | 每個工具呼叫是否執行 | 無。[Protected path](/zh-TW/permission-modes#protected-paths) 檢查也被跳過；只有明確的 [ask rules](/zh-TW/permissions#manage-permissions)、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)、標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及移除 `/` 或您的主目錄仍然提示 |362| `--dangerously-skip-permissions` | 每個工具呼叫是否執行 | 無。[Protected path](/docs/zh-TW/permission-modes#protected-paths) 檢查也被跳過；只有明確的 [ask rules](/docs/zh-TW/permissions#manage-permissions)、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及移除 `/` 或您的主目錄仍然提示 |

363 363

364沙箱的 [auto-allow mode](#sandbox-modes) 與 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分開：自動允許批准 Bash 命令，因為沙箱邊界包含它們，而自動模式使用分類器檢查操作。這兩個獨立工作，可以結合。若要為無人值守執行選擇隔離邊界，請參閱 [Sandbox environments](/zh-TW/sandbox-environments#how-isolation-relates-to-permission-modes)。364沙箱的 [auto-allow mode](#sandbox-modes) 與 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分開：自動允許批准 Bash 命令，因為沙箱邊界包含它們，而自動模式使用分類器檢查操作。這兩個獨立工作，可以結合。若要為無人值守執行選擇隔離邊界，請參閱 [Sandbox environments](/docs/zh-TW/sandbox-environments#how-isolation-relates-to-permission-modes)。

365 365

366<h2 id="configure-the-sandbox-for-your-organization">366<h2 id="configure-the-sandbox-for-your-organization">

367 為您的組織設定沙箱367 為您的組織設定沙箱

373 使用受管設定強制執行沙箱化373 使用受管設定強制執行沙箱化

374</h3>374</h3>

375 375

376若要為每個開發人員要求沙箱，通過 [managed settings](/zh-TW/settings#settings-files) 傳遞 `sandbox` 金鑰，可以是由您的 MDM 管理的檔案，也可以是通過 Claude.ai 上的 [server-managed settings](/zh-TW/server-managed-settings)。376若要為每個開發人員要求沙箱，通過 [managed settings](/docs/zh-TW/settings#settings-files) 傳遞 `sandbox` 金鑰，可以是由您的 MDM 管理的檔案，也可以是通過 Claude.ai 上的 [server-managed settings](/docs/zh-TW/server-managed-settings)。

377 377

378以下受管設定配置啟用沙箱，如果沙箱無法初始化則拒絕啟動 Claude Code，並防止模型在沙箱外重試命令：378以下受管設定配置啟用沙箱，如果沙箱無法初始化則拒絕啟動 Claude Code，並防止模型在沙箱外重試命令：

379 379

402 402

403對於布林金鑰（例如 `enabled` 和 `failIfUnavailable`），Claude Code 使用受管值並忽略開發人員在本地設定的任何內容。對於陣列金鑰（例如 `excludedCommands` 和 `allowRead`），Claude Code 合併來自每個範圍的項目，因此開發人員可以附加擴大策略的項目。403對於布林金鑰（例如 `enabled` 和 `failIfUnavailable`），Claude Code 使用受管值並忽略開發人員在本地設定的任何內容。對於陣列金鑰（例如 `excludedCommands` 和 `allowRead`），Claude Code 合併來自每個範圍的項目，因此開發人員可以附加擴大策略的項目。

404 404

405在受管設定中將 `allowManagedReadPathsOnly` 設定為 `true`，以便只有來自受管設定的 `allowRead` 項目被尊重。使用者、專案和本地 `allowRead` 項目被忽略。這防止開發人員擴大讀取存取超過組織批准的路徑。若要以相同方式將網路域鎖定到受管值，請設定 [`allowManagedDomainsOnly`](/zh-TW/settings#sandbox-settings)。405在受管設定中將 `allowManagedReadPathsOnly` 設定為 `true`，以便只有來自受管設定的 `allowRead` 項目被尊重。使用者、專案和本地 `allowRead` 項目被忽略。這防止開發人員擴大讀取存取超過組織批准的路徑。若要以相同方式將網路域鎖定到受管值，請設定 [`allowManagedDomainsOnly`](/docs/zh-TW/settings#sandbox-settings)。

406 406

407`excludedCommands` 沒有等效的受管專用鎖定，因此開發人員總是可以附加在沙箱外執行其他命令的項目。保持受管清單狹窄。407`excludedCommands` 沒有等效的受管專用鎖定，因此開發人員總是可以附加在沙箱外執行其他命令的項目。保持受管清單狹窄。

408 408

417* 記錄所有網路請求417* 記錄所有網路請求

418* 與現有安全基礎設施整合418* 與現有安全基礎設施整合

419 419

420若要將 Claude Code 指向您的代理，請在 [sandbox settings](/zh-TW/settings#sandbox-settings) 中設定代理連接埠：420若要將 Claude Code 指向您的代理，請在 [sandbox settings](/docs/zh-TW/settings#sandbox-settings) 中設定代理連接埠：

421 421

422```json theme={null}422```json theme={null}

423{423{

438 438

439* **命令因主機不允許錯誤而失敗**：許多 CLI 工具需要到達特定主機。在提示時授予權限會將主機新增到您的允許清單，以便工具在將來在沙箱內執行。439* **命令因主機不允許錯誤而失敗**：許多 CLI 工具需要到達特定主機。在提示時授予權限會將主機新增到您的允許清單，以便工具在將來在沙箱內執行。

440* **`jest` 掛起或失敗**：`watchman` 與沙箱不相容。改為執行 `jest --no-watchman`。440* **`jest` 掛起或失敗**：`watchman` 與沙箱不相容。改為執行 `jest --no-watchman`。

441* **Go 型 CLI 在 macOS 上 TLS 驗證失敗**：`gh`、`gcloud` 和 `terraform` 等工具在 Seatbelt 下可能無法進行 TLS 驗證。在 `excludedCommands` 中列出這些工具以在沙箱外執行它們。如果您使用 `httpProxyPort` 與 MITM 代理和自訂 CA，請改為將 [`enableWeakerNetworkIsolation`](/zh-TW/settings#sandbox-settings) 設定為 `true`。441* **Go 型 CLI 在 macOS 上 TLS 驗證失敗**：`gh`、`gcloud` 和 `terraform` 等工具在 Seatbelt 下可能無法進行 TLS 驗證。在 `excludedCommands` 中列出這些工具以在沙箱外執行它們。如果您使用 `httpProxyPort` 與 MITM 代理和自訂 CA，請改為將 [`enableWeakerNetworkIsolation`](/docs/zh-TW/settings#sandbox-settings) 設定為 `true`。

442* **`open`、`osascript` 或瀏覽器型驗證流程在 macOS 上因錯誤 `-600` 而失敗**：沙箱預設會阻止 Apple Events。在您的使用者、受管理或 CLI 設定中將 [`allowAppleEvents`](/zh-TW/settings#sandbox-settings) 設定為 `true` 以允許它們。專案設定會被忽略此金鑰。啟用它會移除程式碼執行隔離，因為沙箱化命令之後可以啟動其他應用程式而不進行沙箱化，無需使用者提示，並向執行中的應用程式傳送 AppleScript 命令，受限於 macOS 自動化同意提示 (TCC)。或者，將命令新增到 `excludedCommands` 以在沙箱外執行它。442* **`open`、`osascript` 或瀏覽器型驗證流程在 macOS 上因錯誤 `-600` 而失敗**：沙箱預設會阻止 Apple Events。在您的使用者、受管理或 CLI 設定中將 [`allowAppleEvents`](/docs/zh-TW/settings#sandbox-settings) 設定為 `true` 以允許它們。專案設定會被忽略此金鑰。啟用它會移除程式碼執行隔離，因為沙箱化命令之後可以啟動其他應用程式而不進行沙箱化，無需使用者提示，並向執行中的應用程式傳送 AppleScript 命令，受限於 macOS 自動化同意提示 (TCC)。或者，將命令新增到 `excludedCommands` 以在沙箱外執行它。

443* **`docker` 命令失敗**：`docker` 與沙箱不相容。將 `docker *` 新增到 `excludedCommands` 以在沙箱外執行它。443* **`docker` 命令失敗**：`docker` 與沙箱不相容。將 `docker *` 新增到 `excludedCommands` 以在沙箱外執行它。

444* **Bubblewrap 在容器內啟動失敗**：在無特權容器中，bubblewrap 無法掛載新的 `/proc` 檔案系統。將 [`enableWeakerNestedSandbox`](/zh-TW/settings#sandbox-settings) 設定為 `true`，以便內部沙箱綁定掛載容器的現有 `/proc`。僅在外部容器已提供您需要的隔離邊界時使用此設定，因為它向沙箱化命令公開流程資訊，新的 `/proc` 掛載會隱藏。444* **Bubblewrap 在容器內啟動失敗**：在無特權容器中，bubblewrap 無法掛載新的 `/proc` 檔案系統。將 [`enableWeakerNestedSandbox`](/docs/zh-TW/settings#sandbox-settings) 設定為 `true`，以便內部沙箱綁定掛載容器的現有 `/proc`。僅在外部容器已提供您需要的隔離邊界時使用此設定，因為它向沙箱化命令公開流程資訊，新的 `/proc` 掛載會隱藏。

445* **Linux 上的 Seccomp 過濾器**：seccomp 過濾器是阻止 Unix 域套接字所必需的。`/sandbox` 中的 Dependencies 標籤顯示它是否可用。如果缺少，請執行 `npm install -g @anthropic-ai/sandbox-runtime` 安裝幫助程式。445* **Linux 上的 Seccomp 過濾器**：seccomp 過濾器是阻止 Unix 域套接字所必需的。`/sandbox` 中的 Dependencies 標籤顯示它是否可用。如果缺少，請執行 `npm install -g @anthropic-ai/sandbox-runtime` 安裝幫助程式。

446* **`--dangerously-skip-permissions` 以 root 身份失敗**：在 Linux 和 macOS 上以 root 身份或通過 sudo 執行時，此旗標被阻止，因為 root 存取加上沒有權限提示可以修改系統上的任何檔案或服務。檢查在識別的沙箱內自動跳過。若要在容器中自主執行，請使用 [dev container](/zh-TW/devcontainer) 配置，它以非 root 使用者身份執行 Claude Code。446* **`--dangerously-skip-permissions` 以 root 身份失敗**：在 Linux 和 macOS 上以 root 身份或通過 sudo 執行時，此旗標被阻止，因為 root 存取加上沒有權限提示可以修改系統上的任何檔案或服務。檢查在識別的沙箱內自動跳過。若要在容器中自主執行，請使用 [dev container](/docs/zh-TW/devcontainer) 配置，它以非 root 使用者身份執行 Claude Code。

447 447

448<h2 id="limitations">448<h2 id="limitations">

449 限制449 限制

455 安全限制455 安全限制

456</h3>456</h3>

457 457

458* **網路過濾**：沙箱限制流程可以連接的域名。預設情況下，內建代理不終止或檢查出站流量上的 TLS，因此加密連接的內容不被檢查。實驗性的 [`network.tlsTerminate`](/zh-TW/settings#sandbox-settings) 設定在代理處終止 TLS 以進行 [`mask` 認證替換](#protect-credentials)，但不添加內容過濾。您負責確保只有受信任的域名在您的策略中被允許。458* **網路過濾**：沙箱限制流程可以連接的域名。預設情況下，內建代理不終止或檢查出站流量上的 TLS，因此加密連接的內容不被檢查。實驗性的 [`network.tlsTerminate`](/docs/zh-TW/settings#sandbox-settings) 設定在代理處終止 TLS 以進行 [`mask` 認證替換](#protect-credentials)，但不添加內容過濾。您負責確保只有受信任的域名在您的策略中被允許。

459 459

460<Warning>460<Warning>

461 允許廣泛域名（例如 `github.com`）可能會為資料洩露建立路徑。因為代理根據用戶端提供的主機名進行允許決定而不檢查 TLS，在沙箱內執行的程式碼可能可以使用 [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) 或類似技術到達允許清單外的主機。如果您的威脅模型需要更強的保證，請配置 [custom proxy](#custom-proxy-configuration)，它終止 TLS 並檢查流量，並在沙箱內安裝其 CA 憑證。更強的 TLS 感知網路隔離是一個活躍的開發領域。461 允許廣泛域名（例如 `github.com`）可能會為資料洩露建立路徑。因為代理根據用戶端提供的主機名進行允許決定而不檢查 TLS，在沙箱內執行的程式碼可能可以使用 [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) 或類似技術到達允許清單外的主機。如果您的威脅模型需要更強的保證，請配置 [custom proxy](#custom-proxy-configuration)，它終止 TLS 並檢查流量，並在沙箱內安裝其 CA 憑證。更強的 TLS 感知網路隔離是一個活躍的開發領域。

481 481

482沙箱隔離 Bash 子流程。其他工具在不同的邊界下運作：482沙箱隔離 Bash 子流程。其他工具在不同的邊界下運作：

483 483

484* **內建檔案工具**：Read、Edit 和 Write 直接使用權限系統，而不是通過沙箱執行。請參閱 [permissions](/zh-TW/permissions)。484* **內建檔案工具**：Read、Edit 和 Write 直接使用權限系統，而不是通過沙箱執行。請參閱 [permissions](/docs/zh-TW/permissions)。

485* **電腦使用**：當 Claude 打開應用程式並控制您的螢幕時，它在您的實際桌面上執行，而不是在隔離環境中。每個應用程式的權限提示控制每個應用程式。請參閱 [CLI 中的電腦使用](/zh-TW/computer-use) 或 [Desktop 中的電腦使用](/zh-TW/desktop#let-claude-use-your-computer)。485* **電腦使用**：當 Claude 打開應用程式並控制您的螢幕時，它在您的實際桌面上執行，而不是在隔離環境中。每個應用程式的權限提示控制每個應用程式。請參閱 [CLI 中的電腦使用](/docs/zh-TW/computer-use) 或 [Desktop 中的電腦使用](/docs/zh-TW/desktop#let-claude-use-your-computer)。

486* **環境變數**：沙箱化 Bash 命令預設繼承父流程環境，包括在那裡設定的任何認證。使用 [`sandbox.credentials`](#protect-credentials) 為沙箱化命令取消設定或遮罩特定變數，或設定 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-TW/env-vars) 以從所有子流程中去除 Anthropic 和雲端提供商認證。486* **環境變數**：沙箱化 Bash 命令預設繼承父流程環境，包括在那裡設定的任何認證。使用 [`sandbox.credentials`](#protect-credentials) 為沙箱化命令取消設定或遮罩特定變數，或設定 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/zh-TW/env-vars) 以從所有子流程中去除 Anthropic 和雲端提供商認證。

487* **子代理**：[subagents](/zh-TW/sub-agents) 在與父工作階段相同的流程中執行，並使用相同的沙箱配置。當在父工作階段中啟用沙箱化時，子代理內的 Bash 命令被沙箱化。487* **子代理**：[subagents](/docs/zh-TW/sub-agents) 在與父工作階段相同的流程中執行，並使用相同的沙箱配置。當在父工作階段中啟用沙箱化時，子代理內的 Bash 命令被沙箱化。

488 488

489<Warning>489<Warning>

490 有效的沙箱化需要同時進行檔案系統和網路隔離。沒有網路隔離，受損的代理可能會洩露敏感檔案，如 SSH 金鑰。沒有檔案系統隔離，受損的代理可能會後門系統資源以獲得網路存取。當您擴大預設值時，檢查 `allowWrite` 路徑、廣泛的 `allowedDomains` 項目或 `excludedCommands` 例外是否不會撤銷另一側的限制。490 有效的沙箱化需要同時進行檔案系統和網路隔離。沒有網路隔離，受損的代理可能會洩露敏感檔案，如 SSH 金鑰。沒有檔案系統隔離，受損的代理可能會後門系統資源以獲得網路存取。當您擴大預設值時，檢查 `allowWrite` 路徑、廣泛的 `allowedDomains` 項目或 `excludedCommands` 例外是否不會撤銷另一側的限制。

494 另請參閱494 另請參閱

495</h2>495</h2>

496 496

497* [Sandbox environments](/zh-TW/sandbox-environments)：比較內建沙箱與開發容器、容器和虛擬機497* [Sandbox environments](/docs/zh-TW/sandbox-environments)：比較內建沙箱與開發容器、容器和虛擬機

498* [Security](/zh-TW/security)：全面的安全功能和最佳實踐498* [Security](/docs/zh-TW/security)：全面的安全功能和最佳實踐

499* [Permissions](/zh-TW/permissions)：權限配置和存取控制499* [Permissions](/docs/zh-TW/permissions)：權限配置和存取控制

500* [Settings](/zh-TW/settings)：完整配置參考500* [Settings](/docs/zh-TW/settings)：完整配置參考

501* [CLI reference](/zh-TW/cli-reference)：命令列選項501* [CLI reference](/docs/zh-TW/cli-reference)：命令列選項

scheduled-tasks.md +17 −17

Details

6 6

7> 使用 /loop 和 cron 排程工具在 Claude Code 工作階段內重複執行提示、輪詢狀態或設定一次性提醒。7> 使用 /loop 和 cron 排程工具在 Claude Code 工作階段內重複執行提示、輪詢狀態或設定一次性提醒。

8 8

9排程任務讓 Claude 按間隔自動重新執行提示。使用它們來輪詢部署、監督 PR、檢查長時間執行的建置，或在工作階段稍後提醒自己執行某些操作。若要改為對事件發生時做出反應而不是輪詢，請參閱 [Channels](/zh-TW/channels)：您的 CI 可以直接將失敗推送到工作階段中。若要保持工作階段逐輪執行直到符合條件而不是按間隔執行，請參閱 [`/goal`](/zh-TW/goal)。9排程任務讓 Claude 按間隔自動重新執行提示。使用它們來輪詢部署、監督 PR、檢查長時間執行的建置，或在工作階段稍後提醒自己執行某些操作。若要改為對事件發生時做出反應而不是輪詢，請參閱 [Channels](/docs/zh-TW/channels)：您的 CI 可以直接將失敗推送到工作階段中。若要保持工作階段逐輪執行直到符合條件而不是按間隔執行，請參閱 [`/goal`](/docs/zh-TW/goal)。

10 10

11任務的範圍限於工作階段：它們存在於目前的對話中，當您啟動新的對話時就會停止。使用 `--resume` 或 `--continue` 繼續會恢復任何尚未[過期](#seven-day-expiry)的任務：在過去 7 天內建立的重複執行任務，或排程時間尚未到達的一次性任務。對於獨立於任何工作階段而存在的排程，請使用 [Routines](/zh-TW/routines) 在 Anthropic 管理的基礎設施上建立例行程序、設定 [Desktop 排程任務](/zh-TW/desktop-scheduled-tasks)，或使用 [GitHub Actions](/zh-TW/github-actions)。11任務的範圍限於工作階段：它們存在於目前的對話中，當您啟動新的對話時就會停止。使用 `--resume` 或 `--continue` 繼續會恢復任何尚未[過期](#seven-day-expiry)的任務：在過去 7 天內建立的重複執行任務，或排程時間尚未到達的一次性任務。對於獨立於任何工作階段而存在的排程，請使用 [Routines](/docs/zh-TW/routines) 在 Anthropic 管理的基礎設施上建立例行程序、設定 [Desktop 排程任務](/docs/zh-TW/desktop-scheduled-tasks)，或使用 [GitHub Actions](/docs/zh-TW/github-actions)。

12 12

13<h2 id="compare-scheduling-options">13<h2 id="compare-scheduling-options">

14 比較排程選項14 比較排程選項

16 16

17Claude Code offers three ways to schedule recurring or one-off work:17Claude Code offers three ways to schedule recurring or one-off work:

18 18

20| :------------------------- | :----------------------------- | :------------------------------------- | :---------------------------------- |20| :------------------------- | :----------------------------- | :------------------------------------- | :---------------------------------- |

22| Requires machine on | No | Yes | Yes |22| Requires machine on | No | Yes | Yes |

23| Requires open session | No | No | Yes |23| Requires open session | No | No | Yes |

24| Persistent across restarts | Yes | Yes | Restored on `--resume` if unexpired |24| Persistent across restarts | Yes | Yes | Restored on `--resume` if unexpired |

25| Access to local files | No (fresh clone) | Yes | Yes |25| Access to local files | No (fresh clone) | Yes | Yes |

28| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |28| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |

36 使用 /loop 重複執行提示36 使用 /loop 重複執行提示

37</h2>37</h2>

38 38

39`/loop` [bundled skill](/zh-TW/commands) 是在工作階段保持開啟的情況下重複執行提示的最快方式。間隔和提示都是選用的，您提供的內容決定了迴圈的行為方式。39`/loop` [bundled skill](/docs/zh-TW/commands) 是在工作階段保持開啟的情況下重複執行提示的最快方式。間隔和提示都是選用的，您提供的內容決定了迴圈的行為方式。

40 40

41| 您提供的內容 | 範例 | 發生的情況 |41| 您提供的內容 | 範例 | 發生的情況 |

42| :----- | :-------------------------- | :------------------------------------------------------------------- |42| :----- | :-------------------------- | :------------------------------------------------------------------- |

44| 僅提示 | `/loop check the deploy` | 您的提示在 [Claude 選擇的間隔](#let-claude-choose-the-interval)上執行，每次迭代 |44| 僅提示 | `/loop check the deploy` | 您的提示在 [Claude 選擇的間隔](#let-claude-choose-the-interval)上執行，每次迭代 |

46 46

47您也可以傳遞一個 skill 作為提示，例如 `/loop 20m /review-pr 1234`，以在每次迭代時重新執行該 skill。{/* min-version: 2.1.196 */}自 v2.1.196 起，排程的執行只會執行 Claude [允許自行叫用](/zh-TW/skills#control-who-invokes-a-skill)的 skill。以下內容會以純文字形式傳達給 Claude，而不是執行：47您也可以傳遞一個 skill 作為提示，例如 `/loop 20m /review-pr 1234`，以在每次迭代時重新執行該 skill。自 v2.1.196 起，排程的執行只會執行 Claude [允許自行叫用](/docs/zh-TW/skills#control-who-invokes-a-skill)的 skill。以下內容會以純文字形式傳達給 Claude，而不是執行：

48 48

49* 內建命令，例如 `/permissions`、`/model` 或 `/clear`49* 內建命令，例如 `/permissions`、`/model` 或 `/clear`

~~50* 標記為 [`disable-model-invocation: true`](/zh-TW/skills#frontmatter-reference) 的 skill~~50* 標記為 [`disable-model-invocation: true`](/docs/zh-TW/skills#frontmatter-reference) 的 skill

~~51* 由 [`skillOverrides`](/zh-TW/skills#override-skill-visibility-from-settings) 設定或 `Skill` [deny rule](/zh-TW/skills#restrict-claude’s-skill-access) 從 Claude 隱藏的 skill~~51* 由 [`skillOverrides`](/docs/zh-TW/skills#override-skill-visibility-from-settings) 設定或 `Skill` [deny rule](/docs/zh-TW/skills#restrict-claude’s-skill-access) 從 Claude 隱藏的 skill

~~52* [MCP prompts](/zh-TW/mcp#use-mcp-prompts-as-commands)，例如 `/mcp__github__list_prs`；MCP 伺服器公開的 skill 仍會執行~~52* [MCP prompts](/docs/zh-TW/mcp#use-mcp-prompts-as-commands)，例如 `/mcp__github__list_prs`；MCP 伺服器公開的 skill 仍會執行

53 53

54<h3 id="run-on-a-fixed-interval">54<h3 id="run-on-a-fixed-interval">

55 在固定間隔上執行55 在固定間隔上執行

77/loop check whether CI passed and address any review comments77/loop check whether CI passed and address any review comments

78```78```

79 79

80當您要求動態 `/loop` 排程時，Claude 可能會直接使用 [Monitor tool](/zh-TW/tools-reference#monitor-tool)。Monitor 執行背景指令碼並串流回每個輸出行，這完全避免了輪詢，通常比在間隔上重新執行提示更具令牌效率和回應性。80當您要求動態 `/loop` 排程時，Claude 可能會直接使用 [Monitor tool](/docs/zh-TW/tools-reference#monitor-tool)。Monitor 執行背景指令碼並串流回每個輸出行，這完全避免了輪詢，通常比在間隔上重新執行提示更具令牌效率和回應性。

81 81

82動態排程的迴圈會像任何其他任務一樣出現在您的[排程任務清單](#manage-scheduled-tasks)中，因此您可以以相同的方式列出或取消它。[抖動規則](#jitter)不適用於它，但[七天過期](#seven-day-expiry)適用：迴圈在您啟動它七天後自動結束。82動態排程的迴圈會像任何其他任務一樣出現在您的[排程任務清單](#manage-scheduled-tasks)中，因此您可以以相同的方式列出或取消它。[抖動規則](#jitter)不適用於它，但[七天過期](#seven-day-expiry)適用：迴圈在您啟動它七天後自動結束。

83 83

141 141

142若要在 `/loop` 等待下一次迭代時停止它，請按 `Esc`。這會清除待處理的喚醒，使迴圈不會再次執行。您透過[直接要求 Claude](#manage-scheduled-tasks) 排程的任務不受 `Esc` 影響，會保留在原位，直到您刪除它們。142若要在 `/loop` 等待下一次迭代時停止它，請按 `Esc`。這會清除待處理的喚醒，使迴圈不會再次執行。您透過[直接要求 Claude](#manage-scheduled-tasks) 排程的任務不受 `Esc` 影響，會保留在原位，直到您刪除它們。

143 143

144在[自我調整模式](#let-claude-choose-the-interval)中，Claude 也可以在任務完成後自行結束迴圈。Claude 呼叫 [`ScheduleWakeup` tool](/zh-TW/tools-reference)，其中 `stop: true`，這會立即取消待處理的喚醒。如果迭代結束時既未重新排程也未停止，Claude Code 會排程一個大約 20 分鐘後的備用喚醒，並在該迭代也不重新排程時結束迴圈。在 v2.1.202 之前，不重新排程是 Claude 自行結束迴圈的唯一方式。144在[自我調整模式](#let-claude-choose-the-interval)中，Claude 也可以在任務完成後自行結束迴圈。Claude 呼叫 [`ScheduleWakeup` tool](/docs/zh-TW/tools-reference)，其中 `stop: true`，這會立即取消待處理的喚醒。如果迭代結束時既未重新排程也未停止，Claude Code 會排程一個大約 20 分鐘後的備用喚醒，並在該迭代也不重新排程時結束迴圈。在 v2.1.202 之前，不重新排程是 Claude 自行結束迴圈的唯一方式。

145 145

146固定間隔上的迴圈會持續執行，直到您停止它們或[七天過去](#seven-day-expiry)。146固定間隔上的迴圈會持續執行，直到您停止它們或[七天過去](#seven-day-expiry)。

147 147

208 七天過期208 七天過期

209</h3>209</h3>

210 210

211重複執行的任務在建立後 7 天自動過期。任務最後執行一次，然後刪除自己。這限制了被遺忘的迴圈可以執行多長時間。如果您需要重複執行的任務持續更長時間，請在過期前取消並重新建立它，或使用 [Routines](/zh-TW/routines) 或 [Desktop 排程任務](/zh-TW/desktop-scheduled-tasks) 進行持久排程。211重複執行的任務在建立後 7 天自動過期。任務最後執行一次，然後刪除自己。這限制了被遺忘的迴圈可以執行多長時間。如果您需要重複執行的任務持續更長時間，請在過期前取消並重新建立它，或使用 [Routines](/docs/zh-TW/routines) 或 [Desktop 排程任務](/docs/zh-TW/desktop-scheduled-tasks) 進行持久排程。

212 212

213<h2 id="cron-expression-reference">213<h2 id="cron-expression-reference">

214 Cron 表達式參考214 Cron 表達式參考

233 停用排程任務233 停用排程任務

234</h2>234</h2>

235 235

236在您的環境中設定 `CLAUDE_CODE_DISABLE_CRON=1` 以完全停用排程器。cron 工具和 `/loop` 變得不可用，任何已排程的任務都停止執行。請參閱 [環境變數](/zh-TW/env-vars) 以取得完整的停用標誌清單。236在您的環境中設定 `CLAUDE_CODE_DISABLE_CRON=1` 以完全停用排程器。cron 工具和 `/loop` 變得不可用，任何已排程的任務都停止執行。請參閱 [環境變數](/docs/zh-TW/env-vars) 以取得完整的停用標誌清單。

237 237

238<h2 id="limitations">238<h2 id="limitations">

239 限制239 限制

241 241

242工作階段範圍的排程有固有的限制：242工作階段範圍的排程有固有的限制：

243 243

244* 任務只在 Claude Code 執行且閒置時執行。關閉終端或讓工作階段退出會停止它們執行。[將工作階段放在背景執行](/zh-TW/agent-view#from-inside-a-session)會將 `/loop` 任務帶到背景工作階段，該工作階段會持續執行而無需終端。244* 任務只在 Claude Code 執行且閒置時執行。關閉終端或讓工作階段退出會停止它們執行。[將工作階段放在背景執行](/docs/zh-TW/agent-view#from-inside-a-session)會將 `/loop` 任務帶到背景工作階段，該工作階段會持續執行而無需終端。

245* 沒有錯過執行的追趕。如果任務的排程時間在 Claude 忙於長時間執行的請求時經過，它會在 Claude 變為閒置時執行一次，而不是每個錯過的間隔執行一次。245* 沒有錯過執行的追趕。如果任務的排程時間在 Claude 忙於長時間執行的請求時經過，它會在 Claude 變為閒置時執行一次，而不是每個錯過的間隔執行一次。

246* 啟動新的對話會清除所有工作階段範圍的任務。使用 `claude --resume` 或 `claude --continue` 繼續會恢復尚未過期的任務：建立後七天內的重複執行任務，以及排程時間尚未到達的一次性任務。背景 Bash 和監視任務在繼續時永遠不會被恢復。246* 啟動新的對話會清除所有工作階段範圍的任務。使用 `claude --resume` 或 `claude --continue` 繼續會恢復尚未過期的任務：建立後七天內的重複執行任務，以及排程時間尚未到達的一次性任務。背景 Bash 和監視任務在繼續時永遠不會被恢復。

247 247

248對於需要無人值守執行的 cron 驅動自動化：248對於需要無人值守執行的 cron 驅動自動化：

249 249

250* [Routines](/zh-TW/routines)：在 Anthropic 管理的基礎設施上按排程執行、透過 API 呼叫或在 GitHub 事件上執行250* [Routines](/docs/zh-TW/routines)：在 Anthropic 管理的基礎設施上按排程執行、透過 API 呼叫或在 GitHub 事件上執行

251* [GitHub Actions](/zh-TW/github-actions)：在 CI 中使用 `schedule` 觸發器251* [GitHub Actions](/docs/zh-TW/github-actions)：在 CI 中使用 `schedule` 觸發器

252* [Desktop 排程任務](/zh-TW/desktop-scheduled-tasks)：在您的機器上本地執行252* [Desktop 排程任務](/docs/zh-TW/desktop-scheduled-tasks)：在您的機器上本地執行

security-guidance.md +13 −13

Details

10 10

11安裝後，外掛程式會自動執行。無需調用任何內容，也無需記住任何單獨的命令。11安裝後，外掛程式會自動執行。無需調用任何內容，也無需記住任何單獨的命令。

12 12

13該外掛程式是 [Code Review](/zh-TW/code-review) 的工作階段內伴侶，Code Review 在拉取請求上執行。此外掛程式減少了進入 PR 的內容。Code Review 捕捉遺漏的內容。有關外掛程式如何與按需審查和 CI 掃描分層的信息，請參閱 [此功能如何與其他安全工具配合](#how-this-fits-with-other-security-tools)。13該外掛程式是 [Code Review](/docs/zh-TW/code-review) 的工作階段內伴侶，Code Review 在拉取請求上執行。此外掛程式減少了進入 PR 的內容。Code Review 捕捉遺漏的內容。有關外掛程式如何與按需審查和 CI 掃描分層的信息，請參閱 [此功能如何與其他安全工具配合](#how-this-fits-with-other-security-tools)。

14 14

15<h2 id="prerequisites">15<h2 id="prerequisites">

16 先決條件16 先決條件

26 安裝外掛程式26 安裝外掛程式

27</h2>27</h2>

28 28

~~29在 Claude Code 工作階段中，從 [官方 Anthropic 市場](/zh-TW/discover-plugins#official-anthropic-marketplace) 安裝：~~29在 Claude Code 工作階段中，從 [官方 Anthropic 市場](/docs/zh-TW/discover-plugins#official-anthropic-marketplace) 安裝：

30 30

31```text theme={null}31```text theme={null}

32/plugin install security-guidance@claude-plugins-official32/plugin install security-guidance@claude-plugins-official

44 在雲端工作階段和共享儲存庫中啟用44 在雲端工作階段和共享儲存庫中啟用

45</h3>45</h3>

46 46

47使用者範圍的外掛程式不會進入 [網路上的 Claude Code](/zh-TW/claude-code-on-the-web)，因為這些工作階段在 Anthropic 基礎設施上執行，而不是在您的機器上。要在那裡啟用外掛程式，或為克隆儲存庫的所有人開啟它，請在專案的簽入設定中聲明它：47使用者範圍的外掛程式不會進入 [網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web)，因為這些工作階段在 Anthropic 基礎設施上執行，而不是在您的機器上。要在那裡啟用外掛程式，或為克隆儲存庫的所有人開啟它，請在專案的簽入設定中聲明它：

48 48

49```json .claude/settings.json theme={null}49```json .claude/settings.json theme={null}

50{50{

54}54}

55```55```

56 56

~~57管理員可以通過在 [受管設定](/zh-TW/admin-setup) 中設定 [`enabledPlugins`](/zh-TW/settings#plugin-settings) 來組織範圍內啟用外掛程式。~~57管理員可以通過在 [受管設定](/docs/zh-TW/admin-setup) 中設定 [`enabledPlugins`](/docs/zh-TW/settings#plugin-settings) 來組織範圍內啟用外掛程式。

58 58

59<h2 id="what-the-plugin-checks">59<h2 id="what-the-plugin-checks">

60 外掛程式檢查的內容60 外掛程式檢查的內容

139- 使用 `crypto.timingSafeEqual` 進行令牌比較，而不是 `===`。139- 使用 `crypto.timingSafeEqual` 進行令牌比較，而不是 `===`。

140```140```

141 141

142這些規則是審查者的指導，而不是確定性的護欄。外掛程式將違規作為發現呈現給 Claude 修復，但它不會阻止寫入或保證捕捉每個違規。指導是附加的：說要忽略漏洞類別的規則不會抑制這些發現。對於硬執行，將外掛程式與 [阻止編輯受保護檔案的鉤子](/zh-TW/hooks-guide#block-edits-to-protected-files) 或 CI 檢查配對。142這些規則是審查者的指導，而不是確定性的護欄。外掛程式將違規作為發現呈現給 Claude 修復，但它不會阻止寫入或保證捕捉每個違規。指導是附加的：說要忽略漏洞類別的規則不會抑制這些發現。對於硬執行，將外掛程式與 [阻止編輯受保護檔案的鉤子](/docs/zh-TW/hooks-guide#block-edits-to-protected-files) 或 CI 檢查配對。

143 143

144<h3 id="add-custom-per-edit-patterns">144<h3 id="add-custom-per-edit-patterns">

145 添加自訂的每個編輯模式145 添加自訂的每個編輯模式

187 使用成本187 使用成本

188</h2>188</h2>

189 189

190[每個檔案編輯時的模式檢查](#on-each-file-edit) 不進行模型呼叫，不增加成本。[每個回合結束時](#at-the-end-of-each-turn) 和 [每次提交或推送時](#on-each-commit-or-push-claude-makes) 的審查各自花費額外的模型使用，計入您的 [使用](/zh-TW/costs)，就像任何其他 Claude 請求一樣。提交審查是代理性的，每次提交可能需要多個模型回合，限制為每滾動小時 20 次審查。預期大約每個更改檔案的回合進行一次審查呼叫，每次提交進行一次更深層的審查，兩者都受上述上限的限制。190[每個檔案編輯時的模式檢查](#on-each-file-edit) 不進行模型呼叫，不增加成本。[每個回合結束時](#at-the-end-of-each-turn) 和 [每次提交或推送時](#on-each-commit-or-push-claude-makes) 的審查各自花費額外的模型使用，計入您的 [使用](/docs/zh-TW/costs)，就像任何其他 Claude 請求一樣。提交審查是代理性的，每次提交可能需要多個模型回合，限制為每滾動小時 20 次審查。預期大約每個更改檔案的回合進行一次審查呼叫，每次提交進行一次更深層的審查，兩者都受上述上限的限制。

191 191

192兩個模型支持的審查預設使用 Claude Opus 4.7。設定 `SECURITY_REVIEW_MODEL` 為端回合審查選擇不同的模型，設定 `SG_AGENTIC_MODEL` 為提交審查選擇不同的模型。192兩個模型支持的審查預設使用 Claude Opus 4.7。設定 `SECURITY_REVIEW_MODEL` 為端回合審查選擇不同的模型，設定 `SG_AGENTIC_MODEL` 為提交審查選擇不同的模型。

193 193

219/plugin uninstall security-guidance@claude-plugins-official219/plugin uninstall security-guidance@claude-plugins-official

220```220```

221 221

222如果外掛程式通過專案的 `.claude/settings.json` 啟用，從 `/plugin` 禁用它會將覆蓋寫入您的 `.claude/settings.local.json`，而不是編輯簽入的檔案，因此外掛程式對您保持關閉，而不影響隊友。{/* min-version: 2.1.203 */}同一對話框也提供選項以移除外掛程式供所有人使用，方法是從共享的 `.claude/settings.json` 中移除它；該選項需要 Claude Code v2.1.203 或更新版本。如果它通過 [受管設定](/zh-TW/admin-setup) 啟用，只有管理員可以禁用它。222如果外掛程式通過專案的 `.claude/settings.json` 啟用，從 `/plugin` 禁用它會將覆蓋寫入您的 `.claude/settings.local.json`，而不是編輯簽入的檔案，因此外掛程式對您保持關閉，而不影響隊友。同一對話框也提供選項以移除外掛程式供所有人使用，方法是從共享的 `.claude/settings.json` 中移除它；該選項需要 Claude Code v2.1.203 或更新版本。如果它通過 [受管設定](/docs/zh-TW/admin-setup) 啟用，只有管理員可以禁用它。

223 223

224<h2 id="how-the-plugin-integrates-with-claude-code">224<h2 id="how-the-plugin-integrates-with-claude-code">

225 外掛程式如何與 Claude Code 整合225 外掛程式如何與 Claude Code 整合

226</h2>226</h2>

227 227

228外掛程式完全建立在 [hooks](/zh-TW/hooks) 上，這是在 Claude 迴圈中的特定點執行您自己的程式碼的機制。它註冊：228外掛程式完全建立在 [hooks](/docs/zh-TW/hooks) 上，這是在 Claude 迴圈中的特定點執行您自己的程式碼的機制。它註冊：

229 229

230| Hook 事件 | 目的 |230| Hook 事件 | 目的 |

231| :----------------------------------------------------- | :------------------ |231| :----------------------------------------------------- | :------------------ |

246| 階段 | 工具 | 涵蓋的內容 |246| 階段 | 工具 | 涵蓋的內容 |

247| :----- | :----------------------------------------------------- | :----------------------------- |247| :----- | :----------------------------------------------------- | :----------------------------- |

249| 按需 | [`/security-review`](/zh-TW/commands#all-commands) | 對當前分支的一次性安全檢查，在您要求時執行 |249| 按需 | [`/security-review`](/docs/zh-TW/commands#all-commands) | 對當前分支的一次性安全檢查，在您要求時執行 |

252 252

253每個後期階段捕捉早期階段遺漏的內容。外掛程式的價值是減少到達它們的數量，而不是消除對它們的需求。253每個後期階段捕捉早期階段遺漏的內容。外掛程式的價值是減少到達它們的數量，而不是消除對它們的需求。

270 270

271要深入了解此頁面涉及的部分：271要深入了解此頁面涉及的部分：

272 272

273* [Code Review](/zh-TW/code-review)：設定 PR 時間多代理審查273* [Code Review](/docs/zh-TW/code-review)：設定 PR 時間多代理審查

274* [使用 hooks 自動化工作流](/zh-TW/hooks-guide)：在相同的生命週期點構建您自己的檢查274* [使用 hooks 自動化工作流](/docs/zh-TW/hooks-guide)：在相同的生命週期點構建您自己的檢查

275* [發現和安裝外掛程式](/zh-TW/discover-plugins#official-anthropic-marketplace)：瀏覽其他官方外掛程式275* [發現和安裝外掛程式](/docs/zh-TW/discover-plugins#official-anthropic-marketplace)：瀏覽其他官方外掛程式

server-managed-settings.md +29 −29

Details

28 在伺服器管理和端點管理的設定之間選擇28 在伺服器管理和端點管理的設定之間選擇

29</h2>29</h2>

30 30

31Claude Code 支援兩種集中設定方法。伺服器管理的設定從 Anthropic 的伺服器傳遞設定。[端點管理的設定](/zh-TW/settings#settings-files) 透過原生作業系統原則 (macOS 受管偏好設定、Windows 登錄) 或受管設定檔直接部署到裝置。31Claude Code 支援兩種集中設定方法。伺服器管理的設定從 Anthropic 的伺服器傳遞設定。[端點管理的設定](/docs/zh-TW/settings#settings-files) 透過原生作業系統原則 (macOS 受管偏好設定、Windows 登錄) 或受管設定檔直接部署到裝置。

32 32

33| 方法 | 最適合 | 安全模型 |33| 方法 | 最適合 | 安全模型 |

34| :-------------------------------------------- | :--------------------- | :---------------------------- |34| :-------------------------------------------- | :--------------------- | :---------------------------- |

37 37

38如果您的裝置已在 MDM 或端點管理解決方案中註冊，端點管理的設定提供更強的安全保證，因為設定檔可以在作業系統層級受到保護，防止使用者修改。端點管理的設定不會到達 [雲端工作階段](/zh-TW/model-config#surface-coverage)，因此在網路上使用 Claude Code 的組織也應該設定伺服器管理的設定。38如果您的裝置已在 MDM 或端點管理解決方案中註冊，端點管理的設定提供更強的安全保證，因為設定檔可以在作業系統層級受到保護，防止使用者修改。端點管理的設定不會到達 [雲端工作階段](/docs/zh-TW/model-config#surface-coverage)，因此在網路上使用 Claude Code 的組織也應該設定伺服器管理的設定。

39 39

40<h2 id="configure-server-managed-settings">40<h2 id="configure-server-managed-settings">

41 設定伺服器管理的設定41 設定伺服器管理的設定

49 </Step>49 </Step>

50 50

51 <Step title="定義您的設定">51 <Step title="定義您的設定">

52 將您的設定新增為 JSON。支援 [`settings.json` 中提供的所有設定](/zh-TW/settings#available-settings)，除了限制於作業系統層級原則傳遞的設定外；請參閱[目前的限制](#current-limitations)以取得該簡短清單。這包括 [hooks](/zh-TW/hooks)、[環境變數](/zh-TW/env-vars) 和[僅限受管的設定](/zh-TW/permissions#managed-only-settings)，例如 `allowManagedPermissionRulesOnly`。52 將您的設定新增為 JSON。支援 [`settings.json` 中提供的所有設定](/docs/zh-TW/settings#available-settings)，除了限制於作業系統層級原則傳遞的設定外；請參閱[目前的限制](#current-limitations)以取得該簡短清單。這包括 [hooks](/docs/zh-TW/hooks)、[環境變數](/docs/zh-TW/env-vars) 和[僅限受管的設定](/docs/zh-TW/permissions#managed-only-settings)，例如 `allowManagedPermissionRulesOnly`。

53 53

54 此範例強制執行權限拒絕清單，防止使用者繞過權限，並將權限規則限制為在受管設定中定義的規則：54 此範例強制執行權限拒絕清單，防止使用者繞過權限，並將權限規則限制為在受管設定中定義的規則：

55 55

87 }87 }

88 ```88 ```

89 89

~~90 若要設定 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器，使其知道您的組織信任哪些儲存庫、儲存桶和網域：~~90 若要設定 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器，使其知道您的組織信任哪些儲存庫、儲存桶和網域：

91 91

92 ```json theme={null}92 ```json theme={null}

93 {93 {

101 }101 }

102 ```102 ```

103 103

104 因為 hooks 執行 shell 命令，使用者在套用前會看到[安全核准對話方塊](#security-approval-dialogs)。請參閱[設定 auto mode](/zh-TW/auto-mode-config)，了解 `autoMode` 項目如何影響分類器阻止的內容，以及關於 `environment`、`allow`、`soft_deny` 和 `hard_deny` 欄位的重要警告。104 因為 hooks 執行 shell 命令，使用者在套用前會看到[安全核准對話方塊](#security-approval-dialogs)。請參閱[設定 auto mode](/docs/zh-TW/auto-mode-config)，了解 `autoMode` 項目如何影響分類器阻止的內容，以及關於 `environment`、`allow`、`soft_deny` 和 `hard_deny` 欄位的重要警告。

105 </Step>105 </Step>

106 106

107 <Step title="儲存並部署">107 <Step title="儲存並部署">

130 僅限受管的設定130 僅限受管的設定

131</h3>131</h3>

132 132

133大多數[設定金鑰](/zh-TW/settings#available-settings)可在任何範圍中運作。少數金鑰只能從受管設定中讀取，在放置於使用者或專案設定檔中時無效。請參閱[僅限受管的設定](/zh-TW/permissions#managed-only-settings)以取得完整清單。任何不在該清單上的設定仍然可以放置在受管設定中，並具有最高優先順序。133大多數[設定金鑰](/docs/zh-TW/settings#available-settings)可在任何範圍中運作。少數金鑰只能從受管設定中讀取，在放置於使用者或專案設定檔中時無效。請參閱[僅限受管的設定](/docs/zh-TW/permissions#managed-only-settings)以取得完整清單。任何不在該清單上的設定仍然可以放置在受管設定中，並具有最高優先順序。

134 134

135<h3 id="current-limitations">135<h3 id="current-limitations">

136 目前的限制136 目前的限制

139伺服器管理的設定有以下限制：139伺服器管理的設定有以下限制：

140 140

141* 設定統一套用到組織中的所有使用者。尚不支援每個群組的設定。141* 設定統一套用到組織中的所有使用者。尚不支援每個群組的設定。

142* [`managed-mcp.json`](/zh-TW/managed-mcp) 檔案無法透過伺服器管理的設定分發。改為在該處傳遞 `allowedMcpServers` 和 `deniedMcpServers` 原則金鑰。142* [`managed-mcp.json`](/docs/zh-TW/managed-mcp) 檔案無法透過伺服器管理的設定分發。改為在該處傳遞 `allowedMcpServers` 和 `deniedMcpServers` 原則金鑰。

143* 限制於作業系統層級原則來源的設定，例如 `policyHelper` 和 `wslInheritsWindowsSettings`，不會被接受。改為透過 MDM 或系統 `managed-settings.json` 檔案部署它們。143* 限制於作業系統層級原則來源的設定，例如 `policyHelper` 和 `wslInheritsWindowsSettings`，不會被接受。改為透過 MDM 或系統 `managed-settings.json` 檔案部署它們。

144 144

145<h2 id="settings-delivery">145<h2 id="settings-delivery">

150 設定優先順序150 設定優先順序

151</h3>151</h3>

152 152

153伺服器管理的設定和[端點管理的設定](/zh-TW/settings#settings-files)都佔據 Claude Code [設定階層](/zh-TW/settings#settings-precedence)中的最高層級。沒有其他設定層級可以覆蓋它們，包括命令列引數。153伺服器管理的設定和[端點管理的設定](/docs/zh-TW/settings#settings-files)都佔據 Claude Code [設定階層](/docs/zh-TW/settings#settings-precedence)中的最高層級。沒有其他設定層級可以覆蓋它們，包括命令列引數。

154 154

155在受管層級內，已設定的 [`policyHelper`](/zh-TW/settings#compute-managed-settings-with-a-policy-helper) 會優先於其他所有受管來源，包括伺服器管理的設定：其輸出成為該執行的唯一受管設定。155在受管層級內，已設定的 [`policyHelper`](/docs/zh-TW/settings#compute-managed-settings-with-a-policy-helper) 會優先於其他所有受管來源，包括伺服器管理的設定：其輸出成為該執行的唯一受管設定。

156 156

157否則，Claude Code 會使用第一個傳遞非空設定的來源。伺服器管理的設定會先檢查，然後是端點管理的設定。來源不會合併：如果伺服器管理的設定傳遞任何金鑰，其他端點管理的設定會被完全忽略。如果伺服器管理的設定不傳遞任何內容，端點管理的設定會套用。157否則，Claude Code 會使用第一個傳遞非空設定的來源。伺服器管理的設定會先檢查，然後是端點管理的設定。來源不會合併：如果伺服器管理的設定傳遞任何金鑰，其他端點管理的設定會被完全忽略。如果伺服器管理的設定不傳遞任何內容，端點管理的設定會套用。

158 158

159有一個例外適用：當任何管理員控制的受管來源設定時，會遵守一小組[跨來源鎖定金鑰](/zh-TW/settings#settings-precedence)（例如沙箱允許清單鎖定）；使用者可寫入的 HKCU 登錄層級被排除。159有一個例外適用：當任何管理員控制的受管來源設定時，會遵守一小組[跨來源鎖定金鑰](/docs/zh-TW/settings#settings-precedence)（例如沙箱允許清單鎖定）；使用者可寫入的 HKCU 登錄層級被排除。

160 160

161如果您在管理員主控台中清除伺服器管理的設定，意圖回退到端點管理的 plist 或登錄原則，請注意[快取的設定](#fetch-and-caching-behavior)會在用戶端機器上持續存在，直到下次成功擷取。執行 `/status` 以查看哪個受管來源處於作用中。161如果您在管理員主控台中清除伺服器管理的設定，意圖回退到端點管理的 plist 或登錄原則，請注意[快取的設定](#fetch-and-caching-behavior)會在用戶端機器上持續存在，直到下次成功擷取。執行 `/status` 以查看哪個受管來源處於作用中。

162 162

178* Claude Code 在背景擷取新鮮設定178* Claude Code 在背景擷取新鮮設定

179* 快取設定透過網路故障持續存在。被保留的環境變數會保持被保留，直到擷取成功179* 快取設定透過網路故障持續存在。被保留的環境變數會保持被保留，直到擷取成功

180 180

181自 v2.1.198 起，Claude Code 會在快取的 `env` 區塊中保留三個環境變數類別，直到伺服器確認該工作階段的承載。這可防止快取的 Proxy、憑證授權單位、端點或認證值重新導向、攔截或重新驗證確認承載的設定擷取。強化只適用於伺服器擷取的設定快取：透過 MDM 或 `managed-settings.json` 部署的[端點管理的設定](/zh-TW/settings#settings-files)不受影響。被保留的類別為：181自 v2.1.198 起，Claude Code 會在快取的 `env` 區塊中保留三個環境變數類別，直到伺服器確認該工作階段的承載。這可防止快取的 Proxy、憑證授權單位、端點或認證值重新導向、攔截或重新驗證確認承載的設定擷取。強化只適用於伺服器擷取的設定快取：透過 MDM 或 `managed-settings.json` 部署的[端點管理的設定](/docs/zh-TW/settings#settings-files)不受影響。被保留的類別為：

182 182

183* Proxy 和 TLS 設定，例如 `HTTPS_PROXY`、`NODE_EXTRA_CA_CERTS` 和 mTLS 用戶端憑證變數 `CLAUDE_CODE_CLIENT_CERT` 和 `CLAUDE_CODE_CLIENT_KEY`183* Proxy 和 TLS 設定，例如 `HTTPS_PROXY`、`NODE_EXTRA_CA_CERTS` 和 mTLS 用戶端憑證變數 `CLAUDE_CODE_CLIENT_CERT` 和 `CLAUDE_CODE_CLIENT_KEY`

184* API 路由和提供者選擇，包括 `ANTHROPIC_BASE_URL`、提供者選擇變數（例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`）以及提供者端點 URL（例如 `ANTHROPIC_BEDROCK_BASE_URL`）184* API 路由和提供者選擇，包括 `ANTHROPIC_BASE_URL`、提供者選擇變數（例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`）以及提供者端點 URL（例如 `ANTHROPIC_BEDROCK_BASE_URL`）

186 186

187快取 `env` 區塊中的所有其他金鑰（例如遙測和 OpenTelemetry 設定）會如之前一樣在啟動時套用。擷取成功後，被保留的變數會在工作階段的其餘時間套用。187快取 `env` 區塊中的所有其他金鑰（例如遙測和 OpenTelemetry 設定）會如之前一樣在啟動時套用。擷取成功後，被保留的變數會在工作階段的其餘時間套用。

188 188

189如果您的組織需要 Proxy 才能到達 `api.anthropic.com`，請在殼層環境或[使用者設定](/zh-TW/settings#settings-files)中設定它，而不是只在受管 `env` 區塊中設定。首次啟動沒有快取，因此這些來源已經是初始擷取的必要條件。189如果您的組織需要 Proxy 才能到達 `api.anthropic.com`，請在殼層環境或[使用者設定](/docs/zh-TW/settings#settings-files)中設定它，而不是只在受管 `env` 區塊中設定。首次啟動沒有快取，因此這些來源已經是初始擷取的必要條件。

190 190

191Claude Code 自動套用設定更新而無需重新啟動，除了進階設定（例如 OpenTelemetry 設定）需要完整重新啟動才能生效。191Claude Code 自動套用設定更新而無需重新啟動，除了進階設定（例如 OpenTelemetry 設定）需要完整重新啟動才能生效。

192 192

194 傳遞設定中的無效項目194 傳遞設定中的無效項目

195</h3>195</h3>

196 196

197傳遞的承載會以與其他受管來源相同的規則寬容地解析。當承載包含無法通過結構描述驗證的項目時，Claude Code 會移除該項目、顯示驗證錯誤，並套用每個剩餘的有效設定。請參閱[受管設定中的無效項目](/zh-TW/settings#invalid-entries-in-managed-settings)以了解欄位層級的行為，包括如何處理安全強制欄位。需要 Claude Code v2.1.169 或更新版本。197傳遞的承載會以與其他受管來源相同的規則寬容地解析。當承載包含無法通過結構描述驗證的項目時，Claude Code 會移除該項目、顯示驗證錯誤，並套用每個剩餘的有效設定。請參閱[受管設定中的無效項目](/docs/zh-TW/settings#invalid-entries-in-managed-settings)以了解欄位層級的行為，包括如何處理安全強制欄位。需要 Claude Code v2.1.169 或更新版本。

198 198

199伺服器管理的傳遞新增這些行為：199伺服器管理的傳遞新增這些行為：

200 200

220}220}

221```221```

222 222

223您也可以在[端點管理的](/zh-TW/settings#settings-files) MDM 設定檔或系統 `managed-settings.json` 檔案中設定此金鑰，以在首次啟動時強制執行失敗關閉行為，在任何伺服器承載被傳遞之前。自 v2.1.191 起，此旗標是上述[優先順序規則](#settings-precedence)的例外：當在任何受管來源中設定時，即使快取的伺服器管理承載也存在，它也會被接受，因此當伺服器管理的設定存在時，MDM 傳遞的值不會被忽略。223您也可以在[端點管理的](/docs/zh-TW/settings#settings-files) MDM 設定檔或系統 `managed-settings.json` 檔案中設定此金鑰，以在首次啟動時強制執行失敗關閉行為，在任何伺服器承載被傳遞之前。自 v2.1.191 起，此旗標是上述[優先順序規則](#settings-precedence)的例外：當在任何受管來源中設定時，即使快取的伺服器管理承載也存在，它也會被接受，因此當伺服器管理的設定存在時，MDM 傳遞的值不會被忽略。

224 224

225設定擷取也會傳送 `Cache-Control: no-cache` 標頭，以便中間 HTTP Proxy 不會提供過時的回應。225設定擷取也會傳送 `Cache-Control: no-cache` 標頭，以便中間 HTTP Proxy 不會提供過時的回應。

226 226

249 平台可用性249 平台可用性

250</h2>250</h2>

251 251

252伺服器管理的設定需要直接連線到 `api.anthropic.com`，並且傳遞需要工作階段使用組織 OAuth 登入或直接配置的 API 金鑰進行驗證。由 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼傳回的金鑰不會觸發設定擷取。252伺服器管理的設定需要直接連線到 `api.anthropic.com`，並且傳遞需要工作階段使用組織 OAuth 登入或直接配置的 API 金鑰進行驗證。由 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 指令碼傳回的金鑰不會觸發設定擷取。

253 253

254在使用第三方模型提供者時，伺服器管理的設定無法使用：254在使用第三方模型提供者時，伺服器管理的設定無法使用：

255 255

256* Amazon Bedrock256* Amazon Bedrock

257* Google Cloud 的 Agent Platform257* Google Cloud 的 Agent Platform

258* Microsoft Foundry258* Microsoft Foundry

259* [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)259* [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)

260* 透過 `ANTHROPIC_BASE_URL` 或第三方 [LLM 閘道](/zh-TW/llm-gateway) 的自訂 API 端點260* 透過 `ANTHROPIC_BASE_URL` 或第三方 [LLM 閘道](/docs/zh-TW/llm-gateway) 的自訂 API 端點

261 261

262如果您在殼層中匯出 `CLAUDE_CODE_USE_*` 提供者變數或非預設的 `ANTHROPIC_BASE_URL`，Claude Code 會略過您工作階段的設定擷取。您無法使用伺服器管理的 `env` 區塊清除匯出，因為該區塊是透過匯出所防止的擷取來傳遞的。[端點管理的設定](/zh-TW/settings#settings-files) `env` 區塊也不會還原擷取：Claude Code 在套用管理的 `env` 區塊之前會檢查合格性，因此覆寫會變更工作階段的提供者選擇，但擷取仍會被略過。262如果您在殼層中匯出 `CLAUDE_CODE_USE_*` 提供者變數或非預設的 `ANTHROPIC_BASE_URL`，Claude Code 會略過您工作階段的設定擷取。您無法使用伺服器管理的 `env` 區塊清除匯出，因為該區塊是透過匯出所防止的擷取來傳遞的。[端點管理的設定](/docs/zh-TW/settings#settings-files) `env` 區塊也不會還原擷取：Claude Code 在套用管理的 `env` 區塊之前會檢查合格性，因此覆寫會變更工作階段的提供者選擇，但擷取仍會被略過。

263 263

264若要還原伺服器管理的傳遞，請從殼層移除匯出，或在您的使用者設定 `env` 區塊中將變數設定為 `""`，這會在合格性檢查之前套用。若要在不依賴使用者變更其殼層的情況下強制執行原則，請改為透過端點管理的通道傳遞設定。264若要還原伺服器管理的傳遞，請從殼層移除匯出，或在您的使用者設定 `env` 區塊中將變數設定為 `""`，這會在合格性檢查之前套用。若要在不依賴使用者變更其殼層的情況下強制執行原則，請改為透過端點管理的通道傳遞設定。

265 265

266對於 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 部署，自託管的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway) 提供等效的遠端管理設定傳遞：閘道登入的用戶端從閘道而不是 `api.anthropic.com` 擷取管理設定。啟動時的失敗語義不同：無法到達閘道的閘道用戶端會以錯誤結束，而不是回退到快取的設定，而每小時的背景重新整理在兩個通道上都是開放失敗的。266對於 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 部署，自託管的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 提供等效的遠端管理設定傳遞：閘道登入的用戶端從閘道而不是 `api.anthropic.com` 擷取管理設定。啟動時的失敗語義不同：無法到達閘道的閘道用戶端會以錯誤結束，而不是回退到快取的設定，而每小時的背景重新整理在兩個通道上都是開放失敗的。

267 267

268<h2 id="audit-logging">268<h2 id="audit-logging">

269 稽核記錄269 稽核記錄

280伺服器管理的設定提供集中式原則強制執行，但它們作為用戶端控制運作，而非安全邊界。在非受管裝置上，使用者不需要管理員或 sudo 存取權就能略過它們。280伺服器管理的設定提供集中式原則強制執行，但它們作為用戶端控制運作，而非安全邊界。在非受管裝置上，使用者不需要管理員或 sudo 存取權就能略過它們。

281 281

282| 情況 | 行為 |282| 情況 | 行為 |

283| :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |283| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

284| 使用者編輯快取的設定檔 | 篡改的檔案在啟動時套用，但正確的設定會在下次伺服器擷取時還原。{/* min-version: 2.1.198 */}自 v2.1.198 起，`env` 區塊中的傳輸、API 路由和驗證環境變數會[在伺服器確認承載後才提供](#fetch-and-caching-behavior) |284| 使用者編輯快取的設定檔 | 篡改的檔案在啟動時套用，但正確的設定會在下次伺服器擷取時還原。自 v2.1.198 起，`env` 區塊中的傳輸、API 路由和驗證環境變數會[在伺服器確認承載後才提供](#fetch-and-caching-behavior) |

285| 使用者刪除快取的設定檔 | 首次啟動行為發生：設定非同步擷取，有一個簡短的未強制執行視窗 |285| 使用者刪除快取的設定檔 | 首次啟動行為發生：設定非同步擷取，有一個簡短的未強制執行視窗 |

286| 使用者執行修改過的 Claude Code 二進位檔 | 能夠執行修改過用戶端的使用者可以略過任何用戶端控制 |286| 使用者執行修改過的 Claude Code 二進位檔 | 能夠執行修改過用戶端的使用者可以略過任何用戶端控制 |

287| 使用者執行較舊的 Claude Code 版本 | 早於伺服器管理設定的版本不會擷取或套用它們 |287| 使用者執行較舊的 Claude Code 版本 | 早於伺服器管理設定的版本不會擷取或套用它們 |

288| API 無法使用 | 如果可用，快取設定會套用，否則受管設定在下次成功擷取之前不會強制執行。{/* min-version: 2.1.198 */}自 v2.1.198 起，快取 `env` 區塊中的傳輸、API 路由和驗證環境變數會[在擷取失敗時被保留](#fetch-and-caching-behavior)；快取的其餘部分仍然適用。使用 `forceRemoteSettingsRefresh: true` 時，CLI 會結束而不是繼續，除了 [`claude auth` 子命令](#enforce-fail-closed-startup) |288| API 無法使用 | 如果可用，快取設定會套用，否則受管設定在下次成功擷取之前不會強制執行。自 v2.1.198 起，快取 `env` 區塊中的傳輸、API 路由和驗證環境變數會[在擷取失敗時被保留](#fetch-and-caching-behavior)；快取的其餘部分仍然適用。使用 `forceRemoteSettingsRefresh: true` 時，CLI 會結束而不是繼續，除了 [`claude auth` 子命令](#enforce-fail-closed-startup) |

289| 使用者使用不同的組織進行身份驗證 | 不會為受管組織外的帳戶傳遞設定 |289| 使用者使用不同的組織進行身份驗證 | 不會為受管組織外的帳戶傳遞設定 |

290| 使用者設定[第三方模型提供者](#platform-availability) | 伺服器管理的設定會被略過。這包括設定 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非預設的 `ANTHROPIC_BASE_URL` |290| 使用者設定[第三方模型提供者](#platform-availability) | 伺服器管理的設定會被略過。這包括設定 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非預設的 `ANTHROPIC_BASE_URL` |

291| 網路流量被攔截或重新導向 | 停用的 TLS 驗證或攔截的流量可以改變用戶端接收的設定 |291| 網路流量被攔截或重新導向 | 停用的 TLS 驗證或攔截的流量可以改變用戶端接收的設定 |

292 292

293若要偵測執行時期設定變更，請使用 [`ConfigChange` hooks](/zh-TW/hooks#configchange) 來記錄修改或在未授權的變更生效前阻止它們。293若要偵測執行時期設定變更，請使用 [`ConfigChange` hooks](/docs/zh-TW/hooks#configchange) 來記錄修改或在未授權的變更生效前阻止它們。

294 294

295若要限制使用者可以使用用戶端提供的認證存取的組織，請參閱 Claude 說明中心中的[使用租戶限制強制執行網路層級存取控制](https://support.claude.com/en/articles/13198485-enforce-network-level-access-control-with-tenant-restrictions)。如需更強的強制執行保證，請在已在 MDM 解決方案中註冊的裝置上使用[端點管理的設定](/zh-TW/settings#settings-files)。295若要限制使用者可以使用用戶端提供的認證存取的組織，請參閱 Claude 說明中心中的[使用租戶限制強制執行網路層級存取控制](https://support.claude.com/en/articles/13198485-enforce-network-level-access-control-with-tenant-restrictions)。如需更強的強制執行保證，請在已在 MDM 解決方案中註冊的裝置上使用[端點管理的設定](/docs/zh-TW/settings#settings-files)。

296 296

297<h2 id="see-also">297<h2 id="see-also">

298 另請參閱298 另請參閱

300 300

301用於管理 Claude Code 設定的相關頁面：301用於管理 Claude Code 設定的相關頁面：

302 302

303* [Settings](/zh-TW/settings)：完整的設定參考，包括所有可用的設定303* [Settings](/docs/zh-TW/settings)：完整的設定參考，包括所有可用的設定

304* [Endpoint-managed settings](/zh-TW/settings#settings-files)：由 IT 部門部署到裝置的受管設定304* [Endpoint-managed settings](/docs/zh-TW/settings#settings-files)：由 IT 部門部署到裝置的受管設定

305* [Authentication](/zh-TW/authentication)：設定使用者對 Claude Code 的存取305* [Authentication](/docs/zh-TW/authentication)：設定使用者對 Claude Code 的存取

306* [Security](/zh-TW/security)：安全保護措施和最佳實踐306* [Security](/docs/zh-TW/security)：安全保護措施和最佳實踐

sessions.md +21 −21

Details

8 8

9session 是與專案目錄相關聯的已儲存對話。Claude Code 在您工作時將其儲存在本地，因此您可以從中斷的地方繼續、分支以嘗試不同的方法，或在任務之間切換。9session 是與專案目錄相關聯的已儲存對話。Claude Code 在您工作時將其儲存在本地，因此您可以從中斷的地方繼續、分支以嘗試不同的方法，或在任務之間切換。

10 10

11[桌面應用程式](/zh-TW/desktop#work-in-parallel-with-sessions)、[Claude Code 網頁版](/zh-TW/claude-code-on-the-web)和 [VS Code 擴充功能](/zh-TW/vs-code#resume-past-conversations)各自維護自己的 session 歷史記錄。本頁涵蓋 CLI。11[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)、[Claude Code 網頁版](/docs/zh-TW/claude-code-on-the-web)和 [VS Code 擴充功能](/docs/zh-TW/vs-code#resume-past-conversations)各自維護自己的 session 歷史記錄。本頁涵蓋 CLI。

12 12

13<h2 id="resume-a-session">13<h2 id="resume-a-session">

14 恢復 session14 恢復 session

24| `claude --from-pr <number>` | 恢復連結到該 pull request 的 session |24| `claude --from-pr <number>` | 恢復連結到該 pull request 的 session |

25| `/resume` | 從活躍 session 內切換到不同的對話 |25| `/resume` | 從活躍 session 內切換到不同的對話 |

26 26

27使用 [`claude -p`](/zh-TW/headless) 或 [Agent SDK](/zh-TW/agent-sdk/overview) 建立的 sessions 不會出現在 session 選擇器中，但您仍然可以透過將其 session ID 傳遞給 `claude --resume <session-id>` 來恢復它。從啟動 session 的目錄執行此命令：session ID 查詢的範圍限於目前專案目錄及其 git worktrees，因此在其他地方建立的 session 會報告 `No conversation found with session ID: <session-id>`。27使用 [`claude -p`](/docs/zh-TW/headless) 或 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 建立的 sessions 不會出現在 session 選擇器中，但您仍然可以透過將其 session ID 傳遞給 `claude --resume <session-id>` 來恢復它。從啟動 session 的目錄執行此命令：session ID 查詢的範圍限於目前專案目錄及其 git worktrees，因此在其他地方建立的 session 會報告 `No conversation found with session ID: <session-id>`。

28 28

29<h3 id="where-the-session-picker-looks">29<h3 id="where-the-session-picker-looks">

30 session 選擇器查看的位置30 session 選擇器查看的位置

32 32

33Sessions 按專案目錄儲存。預設情況下，session 選擇器顯示來自目前 worktree 的互動式 sessions，以及在其他地方啟動並使用 `/add-dir` 新增目前目錄的 sessions。使用 `Ctrl+W` 擴展到儲存庫的所有 worktrees，或使用 `Ctrl+A` 擴展到此機器上的每個專案。33Sessions 按專案目錄儲存。預設情況下，session 選擇器顯示來自目前 worktree 的互動式 sessions，以及在其他地方啟動並使用 `/add-dir` 新增目前目錄的 sessions。使用 `Ctrl+W` 擴展到儲存庫的所有 worktrees，或使用 `Ctrl+A` 擴展到此機器上的每個專案。

34 34

35從 v2.1.169 開始，使用 [`/cd`](/zh-TW/commands) 移動 session 會將其重新定位到新目錄的專案儲存空間，因此之後會出現在該目錄的選擇器中。從 v2.1.196 開始，移動的 session 即使在當機或強制退出後，也會保持不在舊目錄的選擇器中。在較早的版本上，當舊路徑包含特殊字元（例如底線）時，在不乾淨的退出後，它也可能在舊目錄的清單中重新出現。35從 v2.1.169 開始，使用 [`/cd`](/docs/zh-TW/commands) 移動 session 會將其重新定位到新目錄的專案儲存空間，因此之後會出現在該目錄的選擇器中。從 v2.1.196 開始，移動的 session 即使在當機或強制退出後，也會保持不在舊目錄的選擇器中。在較早的版本上，當舊路徑包含特殊字元（例如底線）時，在不乾淨的退出後，它也可能在舊目錄的清單中重新出現。

36 36

37從同一儲存庫的另一個 worktree 選擇 session 會在原地恢復它。從不相關的專案選擇 session 會將 `cd` 和恢復命令複製到您的剪貼簿。37從同一儲存庫的另一個 worktree 選擇 session 會在原地恢復它。從不相關的專案選擇 session 會將 `cd` 和恢復命令複製到您的剪貼簿。

38 38

54| 啟動時 | `claude -n auth-refactor` |54| 啟動時 | `claude -n auth-refactor` |

55| 在 session 期間 | `/rename auth-refactor`。名稱也會出現在提示列上 |55| 在 session 期間 | `/rename auth-refactor`。名稱也會出現在提示列上 |

56| 從 session 選擇器 | 反白 session 並按 `Ctrl+R` |56| 從 session 選擇器 | 反白 session 並按 `Ctrl+R` |

~~57| 在計畫接受時 | 在 [plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 中接受計畫會根據計畫內容命名 session，除非您已經設定了一個 |~~57| 在計畫接受時 | 在 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 中接受計畫會根據計畫內容命名 session，除非您已經設定了一個 |

58 58

59session 命名後，使用 `claude --resume <name>` 或 `/resume <name>` 返回到它。請參閱[恢復 session](#resume-a-session) 以了解名稱解析在 worktrees 中的行為方式。59session 命名後，使用 `claude --resume <name>` 或 `/resume <name>` 返回到它。請參閱[恢復 session](#resume-a-session) 以了解名稱解析在 worktrees 中的行為方式。

60 60

61{/* min-version: 2.1.196 */}您從未命名的互動式 sessions 在啟動時仍會獲得預設顯示名稱。需要 Claude Code v2.1.196 或更新版本。預設名稱結合了工作目錄的名稱和一個兩字元的後綴，例如 `my-app-3f`，並在執行中 sessions 的列表中識別該 session，例如 [agent view](/zh-TW/agent-view) 和 `claude agents --json` 輸出。61您從未命名的互動式 sessions 在啟動時仍會獲得預設顯示名稱。需要 Claude Code v2.1.196 或更新版本。預設名稱結合了工作目錄的名稱和一個兩字元的後綴，例如 `my-app-3f`，並在執行中 sessions 的列表中識別該 session，例如 [agent view](/docs/zh-TW/agent-view) 和 `claude agents --json` 輸出。

62 62

63預設名稱不是恢復控制代碼：`claude --resume <name>`、`/resume <name>` 和 session 選擇器只符合您設定的名稱。命名 session 會取代預設名稱。63預設名稱不是恢復控制代碼：`claude --resume <name>`、`/resume <name>` 和 session 選擇器只符合您設定的名稱。命名 session 會取代預設名稱。

64 64

97/branch try-streaming-approach97/branch try-streaming-approach

98```98```

99 99

100如果您省略名稱，Claude Code 會根據對話中的第一個提示為新分支命名。從 v2.1.198 開始，這也適用於 [壓縮](/zh-TW/how-claude-code-works#when-context-fills-up) 之後；較早的版本會回退到字面名稱 `Branched conversation`，而不是查看壓縮摘要之外的原始第一個提示。100如果您省略名稱，Claude Code 會根據對話中的第一個提示為新分支命名。從 v2.1.198 開始，這也適用於 [壓縮](/docs/zh-TW/how-claude-code-works#when-context-fills-up) 之後；較早的版本會回退到字面名稱 `Branched conversation`，而不是查看壓縮摘要之外的原始第一個提示。

101 101

102從命令列，將 `--continue` 或 `--resume` 與 `--fork-session` 結合：102從命令列，將 `--continue` 或 `--resume` 與 `--fork-session` 結合：

103 103

107 107

108原始 session 保持不變，並在 session 選擇器中保持可用。`/branch` 確認會列印兩個 session ID：您現在所在的新分支和原始分支。要返回原始分支，將其 ID 傳遞給 `/resume`、使用 session 選擇器或執行 `/resume <original-name>`。您使用「允許此 session」核准的權限不會轉移到新分支。如果您在兩個終端中恢復同一 session 而不進行分支，來自兩者的訊息會交錯到一個文字記錄中。108原始 session 保持不變，並在 session 選擇器中保持可用。`/branch` 確認會列印兩個 session ID：您現在所在的新分支和原始分支。要返回原始分支，將其 ID 傳遞給 `/resume`、使用 session 選擇器或執行 `/resume <original-name>`。您使用「允許此 session」核准的權限不會轉移到新分支。如果您在兩個終端中恢復同一 session 而不進行分支，來自兩者的訊息會交錯到一個文字記錄中。

109 109

110有關單個 session 內基於 checkpoint 的 rewind，請參閱 [Checkpointing](/zh-TW/checkpointing)。110有關單個 session 內基於 checkpoint 的 rewind，請參閱 [Checkpointing](/docs/zh-TW/checkpointing)。

111 111

112<h2 id="manage-context-within-a-session">112<h2 id="manage-context-within-a-session">

113 在 session 內管理上下文113 在 session 內管理上下文

115 115

116這些命令控制上下文視窗中的內容，而無需離開 session：116這些命令控制上下文視窗中的內容，而無需離開 session：

117 117

118* **`/clear`**：以空上下文重新開始。先前的對話已儲存並可恢復，使用 `/resume` 恢復，或在同一個 Claude Code 程序中，{/* min-version: 2.1.191 */}從[倒帶選單的前一個 session 項目](/zh-TW/checkpointing#rewind-past-a-cleared-conversation)118* **`/clear`**：以空上下文重新開始。先前的對話已儲存並可恢復，使用 `/resume` 恢復，或在同一個 Claude Code 程序中，從[倒帶選單的前一個 session 項目](/docs/zh-TW/checkpointing#rewind-past-a-cleared-conversation)

119* **`/compact [instructions]`**：用摘要替換歷史記錄，可選擇性地專注於您指定的內容119* **`/compact [instructions]`**：用摘要替換歷史記錄，可選擇性地專注於您指定的內容

120* **`/context`**：顯示目前消耗上下文的內容120* **`/context`**：顯示目前消耗上下文的內容

121 121

122有關壓縮如何與 CLAUDE.md、skills 和規則互動，請參閱[上下文視窗指南](/zh-TW/context-window)。有關何時清除與壓縮的策略，請參閱[最佳實踐](/zh-TW/best-practices#manage-your-session)。122有關壓縮如何與 CLAUDE.md、skills 和規則互動，請參閱[上下文視窗指南](/docs/zh-TW/context-window)。有關何時清除與壓縮的策略，請參閱[最佳實踐](/docs/zh-TW/best-practices#manage-your-session)。

123 123

124<h2 id="export-and-locate-session-data">124<h2 id="export-and-locate-session-data">

125 匯出和定位 session 資料125 匯出和定位 session 資料

133 133

134`/export` 產生供人閱讀的呈現文字記錄。下列介面產生供指令碼解析的結構化資料：執行的 JSON 結果、session 文字記錄檔案的路徑，或事件的即時串流。根據觸發指令碼的內容選擇：134`/export` 產生供人閱讀的呈現文字記錄。下列介面產生供指令碼解析的結構化資料：執行的 JSON 結果、session 文字記錄檔案的路徑，或事件的即時串流。根據觸發指令碼的內容選擇：

135 135

136* **執行 Claude 一次並擷取結果**：使用 [`--output-format json` 或 `stream-json`](/zh-TW/headless#get-structured-output) 叫用 `claude -p`，以將非互動執行的結果、session ID、使用情況和成本擷取為結構化 JSON。136* **執行 Claude 一次並擷取結果**：使用 [`--output-format json` 或 `stream-json`](/docs/zh-TW/headless#get-structured-output) 叫用 `claude -p`，以將非互動執行的結果、session ID、使用情況和成本擷取為結構化 JSON。

137* **詢問現有 session 一個問題**：將 session ID 傳遞給 [`claude -p --resume`](/zh-TW/headless#continue-conversations)，以傳送後續提示（例如摘要要求），並擷取結構化回應。137* **詢問現有 session 一個問題**：將 session ID 傳遞給 [`claude -p --resume`](/docs/zh-TW/headless#continue-conversations)，以傳送後續提示（例如摘要要求），並擷取結構化回應。

138* **對 session 事件做出反應**：讀取 [hooks](/zh-TW/hooks#common-input-fields) 和 [status line commands](/zh-TW/statusline#available-data) 作為輸入接收的 `transcript_path` 欄位。`SessionEnd` hook 可在 session 結束時封存文字記錄。138* **對 session 事件做出反應**：讀取 [hooks](/docs/zh-TW/hooks#common-input-fields) 和 [status line commands](/docs/zh-TW/statusline#available-data) 作為輸入接收的 `transcript_path` 欄位。`SessionEnd` hook 可在 session 結束時封存文字記錄。

139* **在 TypeScript 或 Python 應用程式中嵌入 Claude**：使用 [Agent SDK](/zh-TW/agent-sdk/overview) 以程式設計方式接收每條訊息。139* **在 TypeScript 或 Python 應用程式中嵌入 Claude**：使用 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 以程式設計方式接收每條訊息。

140 140

141下列範例使用第二個介面。它傳送後續提示給現有 session，並使用 `jq` 讀取答案：141下列範例使用第二個介面。它傳送後續提示給現有 session，並使用 `jq` 讀取答案：

142 142

154 154

155| 目的 | 設定 | 位置 |155| 目的 | 設定 | 位置 |

156| ------------------- | --------------------------------------------------------- | ----------------------- |156| ------------------- | --------------------------------------------------------- | ----------------------- |

161 161

162<h2 id="see-also">162<h2 id="see-also">

163 另請參閱163 另請參閱

165 165

166這些頁面涵蓋相關的 session 和平行處理機制：166這些頁面涵蓋相關的 session 和平行處理機制：

167 167

168* [Worktrees](/zh-TW/worktrees)：在單獨的分支上執行隔離的平行 sessions168* [Worktrees](/docs/zh-TW/worktrees)：在單獨的分支上執行隔離的平行 sessions

169* [Checkpointing](/zh-TW/checkpointing)：將程式碼和對話 rewind 到較早的點169* [Checkpointing](/docs/zh-TW/checkpointing)：將程式碼和對話 rewind 到較早的點

170* [Context window](/zh-TW/context-window)：什麼填充上下文以及什麼在壓縮中存活170* [Context window](/docs/zh-TW/context-window)：什麼填充上下文以及什麼在壓縮中存活

171* [Non-interactive mode](/zh-TW/headless)：`claude -p` 下的 session 行為171* [Non-interactive mode](/docs/zh-TW/headless)：`claude -p` 下的 session 行為

settings.md +160 −160

Details

6 6

7> 使用全域和專案層級設定以及環境變數來設定 Claude Code。7> 使用全域和專案層級設定以及環境變數來設定 Claude Code。

8 8

9Claude Code 提供多種設定選項，可根據您的需求配置其行為。您可以執行 `/config` 命令來設定 Claude Code，這會開啟一個標籤式設定介面，您可以在其中查看狀態資訊並修改設定選項。{/* min-version: 2.1.181 */}從 v2.1.181 版本開始，您可以透過將 `key=value` 傳遞給 `/config` 來變更單一選項，而無需開啟介面，例如 `/config verbose=true`。9Claude Code 提供多種設定選項，可根據您的需求配置其行為。您可以執行 `/config` 命令來設定 Claude Code，這會開啟一個標籤式設定介面，您可以在其中查看狀態資訊並修改設定選項。從 v2.1.181 版本開始，您可以透過將 `key=value` 傳遞給 `/config` 來變更單一選項，而無需開啟介面，例如 `/config verbose=true`。

10 10

11<h2 id="configuration-scopes">11<h2 id="configuration-scopes">

12 設定範圍12 設定範圍

96 * `.claude/settings.json` 用於簽入原始碼控制並與您的團隊共享的設定96 * `.claude/settings.json` 用於簽入原始碼控制並與您的團隊共享的設定

97 * `.claude/settings.local.json` 用於未簽入的設定，適用於個人偏好和實驗。Claude Code 建立 `.claude/settings.local.json` 時，會設定 git 以忽略該檔案。如果您自己建立該檔案，請手動將其新增到 gitignore。97 * `.claude/settings.local.json` 用於未簽入的設定，適用於個人偏好和實驗。Claude Code 建立 `.claude/settings.local.json` 時，會設定 git 以忽略該檔案。如果您自己建立該檔案，請手動將其新增到 gitignore。

98 98

99 因為此檔案是您的而不是儲存庫的，其權限 `allow` 規則會生效，無需 `.claude/settings.json` allow 規則所需的[工作區信任](/zh-TW/permissions#project-allow-rules-and-workspace-trust)步驟。如果儲存庫提供該檔案，例如透過提交它，工作區信任仍然適用。99 因為此檔案是您的而不是儲存庫的，其權限 `allow` 規則會生效，無需 `.claude/settings.json` allow 規則所需的[工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)步驟。如果儲存庫提供該檔案，例如透過提交它，工作區信任仍然適用。

100* **Managed 設定**：對於需要集中控制的組織，Claude Code 支援多種 managed 設定的傳遞機制。所有機制都使用相同的 JSON 格式，無法被使用者或專案設定覆蓋：100* **Managed 設定**：對於需要集中控制的組織，Claude Code 支援多種 managed 設定的傳遞機制。所有機制都使用相同的 JSON 格式，無法被使用者或專案設定覆蓋：

101 101

102 * **伺服器管理的設定**：透過 Anthropic 的伺服器或自託管的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 在登入時遠端傳遞，可從 claude.ai 管理員主控台或自託管 Claude apps gateway 傳遞。請參閱[伺服器管理的設定](/zh-TW/server-managed-settings)。102 * **伺服器管理的設定**：透過 Anthropic 的伺服器或自託管的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 在登入時遠端傳遞，可從 claude.ai 管理員主控台或自託管 Claude apps gateway 傳遞。請參閱[伺服器管理的設定](/docs/zh-TW/server-managed-settings)。

103 * **MDM/OS 層級政策**：透過 macOS 和 Windows 上的原生裝置管理傳遞：103 * **MDM/OS 層級政策**：透過 macOS 和 Windows 上的原生裝置管理傳遞：

104 * macOS：`com.anthropic.claudecode` managed preferences 網域。plist 的頂層金鑰鏡像 `managed-settings.json`，巢狀設定為字典，陣列為 plist 陣列。透過 Jamf、Iru (Kandji) 或類似 MDM 工具中的設定檔案部署。104 * macOS：`com.anthropic.claudecode` managed preferences 網域。plist 的頂層金鑰鏡像 `managed-settings.json`，巢狀設定為字典，陣列為 plist 陣列。透過 Jamf、Iru (Kandji) 或類似 MDM 工具中的設定檔案部署。

105 * Windows：`HKLM\SOFTWARE\Policies\ClaudeCode` 登錄機碼，其中包含 `Settings` 值（REG\_SZ 或 REG\_EXPAND\_SZ）包含 JSON（透過群組原則或 Intune 部署）105 * Windows：`HKLM\SOFTWARE\Policies\ClaudeCode` 登錄機碼，其中包含 `Settings` 值（REG\_SZ 或 REG\_EXPAND\_SZ）包含 JSON（透過群組原則或 Intune 部署）

120 120

121 使用數字前綴來控制合併順序，例如 `10-telemetry.json` 和 `20-security.json`。121 使用數字前綴來控制合併順序，例如 `10-telemetry.json` 和 `20-security.json`。

122 122

123 請參閱 [managed 設定](/zh-TW/permissions#managed-only-settings) 和 [Managed MCP 設定](/zh-TW/managed-mcp) 以取得詳細資訊。123 請參閱 [managed 設定](/docs/zh-TW/permissions#managed-only-settings) 和 [Managed MCP 設定](/docs/zh-TW/managed-mcp) 以取得詳細資訊。

124 124

125 此[儲存庫](https://github.com/anthropics/claude-code/tree/main/examples/mdm)包含 Jamf、Iru (Kandji)、Intune 和群組原則的入門部署範本。使用這些作為起點，並根據您的需求進行調整。125 此[儲存庫](https://github.com/anthropics/claude-code/tree/main/examples/mdm)包含 Jamf、Iru (Kandji)、Intune 和群組原則的入門部署範本。使用這些作為起點，並根據您的需求進行調整。

126 126

127 <Note>127 <Note>

128 Managed 部署也可以使用 `strictKnownMarketplaces` 限制 **plugin marketplace 新增**。如需詳細資訊，請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)。128 Managed 部署也可以使用 `strictKnownMarketplaces` 限制 **plugin marketplace 新增**。如需詳細資訊，請參閱 [Managed marketplace 限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)。

129 </Note>129 </Note>

130* **其他設定**儲存在 `~/.claude.json` 中。此檔案包含您的 OAuth 工作階段、[MCP server](/zh-TW/mcp) 設定（用於使用者和本機範圍）、每個專案的狀態（允許的工具、信任設定）和各種快取。專案範圍的 MCP servers 分別儲存在 `.mcp.json` 中。130* **其他設定**儲存在 `~/.claude.json` 中。此檔案包含您的 OAuth 工作階段、[MCP server](/docs/zh-TW/mcp) 設定（用於使用者和本機範圍）、每個專案的狀態（允許的工具、信任設定）和各種快取。專案範圍的 MCP servers 分別儲存在 `.mcp.json` 中。

131 131

132<Note>132<Note>

133 Claude Code 會自動建立設定檔案的時間戳記備份，並保留最近五個備份以防止資料遺失。133 Claude Code 會自動建立設定檔案的時間戳記備份，並保留最近五個備份以防止資料遺失。

169 編輯何時生效169 編輯何時生效

170</h3>170</h3>

171 171

172Claude Code 會監視您的設定檔案，並在它們變更時重新載入它們，因此對大多數金鑰的編輯會在執行中的工作階段中應用，無需重新啟動。這包括 `permissions`、`hooks` 和認證協助程式（如 `apiKeyHelper`）。重新載入涵蓋使用者、專案、本機和 managed 設定，並且 [`ConfigChange` hook](/zh-TW/hooks#configchange) 會針對每個偵測到的變更觸發。172Claude Code 會監視您的設定檔案，並在它們變更時重新載入它們，因此對大多數金鑰的編輯會在執行中的工作階段中應用，無需重新啟動。這包括 `permissions`、`hooks` 和認證協助程式（如 `apiKeyHelper`）。重新載入涵蓋使用者、專案、本機和 managed 設定，並且 [`ConfigChange` hook](/docs/zh-TW/hooks#configchange) 會針對每個偵測到的變更觸發。

173 173

174少數金鑰在工作階段啟動時讀取一次，並在下次重新啟動時應用：174少數金鑰在工作階段啟動時讀取一次，並在下次重新啟動時應用：

175 175

176* `model`：使用 [`/model`](/zh-TW/model-config#setting-your-model) 在工作階段中切換176* `model`：使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 在工作階段中切換

177* [`outputStyle`](/zh-TW/output-styles)：系統提示的一部分，在 `/clear` 或重新啟動時重建177* [`outputStyle`](/docs/zh-TW/output-styles)：系統提示的一部分，在 `/clear` 或重新啟動時重建

178 178

179<h3 id="invalid-entries-in-managed-settings">179<h3 id="invalid-entries-in-managed-settings">

180 Managed 設定中的無效項目180 Managed 設定中的無效項目

181</h3>181</h3>

182 182

183Managed 設定會寬容地解析。當 managed 設定包含驗證架構失敗的項目時，Claude Code 會移除該項目、記錄警告，並強制執行每個剩餘的有效政策。單一拼寫錯誤無法停用組織政策的其餘部分。執行 [`/doctor`](/zh-TW/debug-your-config#check-resolved-settings) 以列出被移除的項目及其來源檔案和欄位。183Managed 設定會寬容地解析。當 managed 設定包含驗證架構失敗的項目時，Claude Code 會移除該項目、記錄警告，並強制執行每個剩餘的有效政策。單一拼寫錯誤無法停用組織政策的其餘部分。執行 [`/doctor`](/docs/zh-TW/debug-your-config#check-resolved-settings) 以列出被移除的項目及其來源檔案和欄位。

184 184

185此行為在所有三種傳遞機制中一致：[伺服器管理的設定](/zh-TW/server-managed-settings)、透過 MDM 部署的 plist 和登錄政策，以及 `managed-settings.json` 檔案。需要 Claude Code v2.1.169 或更新版本。185此行為在所有三種傳遞機制中一致：[伺服器管理的設定](/docs/zh-TW/server-managed-settings)、透過 MDM 部署的 plist 和登錄政策，以及 `managed-settings.json` 檔案。需要 Claude Code v2.1.169 或更新版本。

186 186

187安全強制欄位按欄位處理，而不是在存在但無效時被整體移除：187安全強制欄位按欄位處理，而不是在存在但無效時被整體移除：

188 188

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

190| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |190| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |

193| `availableModels` | {/* min-version: 2.1.175 */}作為空白名單強制執行，因此在修復值之前僅預設模型可用。個別非字串項目會被移除，有效子集會被強制執行。適用於 v2.1.175 及更新版本。 |193| `availableModels` | 作為空白名單強制執行，因此在修復值之前僅預設模型可用。個別非字串項目會被移除，有效子集會被強制執行。適用於 v2.1.175 及更新版本。 |

194| `enforceAvailableModels` | {/* min-version: 2.1.175 */}視為 `true`。適用於 v2.1.175 及更新版本。 |194| `enforceAvailableModels` | 視為 `true`。適用於 v2.1.175 及更新版本。 |

197| `sandbox.credentials` | {/* min-version: 2.1.191 */}在 `files` 或 `envVars` 中的個別無效項目會被移除並出現警告，有效子集會被強制執行。完全無效的 `credentials` 值會被丟棄並出現警告，而 `sandbox` 的其餘部分仍然適用。適用於 v2.1.191 及更新版本。 |197| `sandbox.credentials` | 在 `files` 或 `envVars` 中的個別無效項目會被移除並出現警告，有效子集會被強制執行。完全無效的 `credentials` 值會被丟棄並出現警告，而 `sandbox` 的其餘部分仍然適用。適用於 v2.1.191 及更新版本。 |

198 198

199`requiredMinimumVersion` 和 `requiredMaximumVersion` 設計上會失敗開放：無效的值會被移除而不是強制執行，因此不良的政策推送無法防止 Claude Code 啟動。199`requiredMinimumVersion` 和 `requiredMaximumVersion` 設計上會失敗開放：無效的值會被移除而不是強制執行，因此不良的政策推送無法防止 Claude Code 啟動。

200 200

202 202

203* 互動式工作階段在啟動時顯示列出無效項目的對話框。203* 互動式工作階段在啟動時顯示列出無效項目的對話框。

204* 使用 `-p` 的無頭執行會將摘要列印到 stderr。204* 使用 `-p` 的無頭執行會將摘要列印到 stderr。

205* [`claude doctor`](/zh-TW/debug-your-config) 列出每個無效項目及其來源和欄位。205* [`claude doctor`](/docs/zh-TW/debug-your-config) 列出每個無效項目及其來源和欄位。

206 206

207在整個機隊部署政策變更之前，在測試機器上執行 `claude doctor` 以驗證政策變更。207在整個機隊部署政策變更之前，在測試機器上執行 `claude doctor` 以驗證政策變更。

208 208

215`settings.json` 支援多個選項：215`settings.json` 支援多個選項：

216 216

217| 金鑰 | 說明 | 範例 |217| 金鑰 | 說明 | 範例 |

218| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |218| :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |

219| `advisorModel` | 伺服器端 [advisor tool](/zh-TW/advisor) 的模型。接受模型別名，例如 `"opus"`、`"sonnet"` 或 `"fable"`（{/* min-version: 2.1.170 */}v2.1.170+），或完整模型 ID。當您執行 `/advisor` 時自動寫入。取消設定以停用 advisor | `"opus"` |219| `advisorModel` | 伺服器端 [advisor tool](/docs/zh-TW/advisor) 的模型。接受模型別名，例如 `"opus"`、`"sonnet"` 或 `"fable"`（v2.1.170+），或完整模型 ID。當您執行 `/advisor` 時自動寫入。取消設定以停用 advisor | `"opus"` |

220| `agent` | 將主執行緒作為命名 subagent 執行，並為從 `claude agents` 分派的工作階段設定預設 agent。應用該 subagent 的系統提示、工具限制和模型。請參閱[明確叫用 subagents](/zh-TW/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |220| `agent` | 將主執行緒作為命名 subagent 執行，並為從 `claude agents` 分派的工作階段設定預設 agent。應用該 subagent 的系統提示、工具限制和模型。請參閱[明確叫用 subagents](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |

221| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**預設**：`false`。當[遠端控制](/zh-TW/remote-control)已連線時，允許 Claude 主動傳送推播通知到您的手機，例如當長時間工作完成時。在 `/config` 中顯示為**Claude 決定時推播**。請參閱[行動推播通知](/zh-TW/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更新版本 | `true` |221| `agentPushNotifEnabled` | **預設**：`false`。當[遠端控制](/docs/zh-TW/remote-control)已連線時，允許 Claude 主動傳送推播通知到您的手機，例如當長時間工作完成時。在 `/config` 中顯示為**Claude 決定時推播**。請參閱[行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更新版本 | `true` |

223| `allowedChannelPlugins` | （Managed 設定僅限）可能推送訊息的頻道 plugins 白名單。在設定時替換預設 Anthropic 白名單。未定義 = 回退到預設值，空陣列 = 阻止所有頻道 plugins。需要 `channelsEnabled: true`。請參閱[限制哪些頻道 plugins 可以執行](/zh-TW/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |223| `allowedChannelPlugins` | （Managed 設定僅限）可能推送訊息的頻道 plugins 白名單。在設定時替換預設 Anthropic 白名單。未定義 = 回退到預設值，空陣列 = 阻止所有頻道 plugins。需要 `channelsEnabled: true`。請參閱[限制哪些頻道 plugins 可以執行](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |

224| `allowedHttpHookUrls` | HTTP hooks 可能針對的 URL 模式白名單。支援 `*` 作為萬用字元。設定時，具有不匹配 URL 的 hooks 會被阻止。未定義 = 無限制，空陣列 = 阻止所有 HTTP hooks。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["https://hooks.example.com/*"]` |224| `allowedHttpHookUrls` | HTTP hooks 可能針對的 URL 模式白名單。支援 `*` 作為萬用字元。設定時，具有不匹配 URL 的 hooks 會被阻止。未定義 = 無限制，空陣列 = 阻止所有 HTTP hooks。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["https://hooks.example.com/*"]` |

225| `allowedMcpServers` | 在 managed-settings.json 中設定時，使用者可以設定的 MCP servers 白名單。未定義 = 無限制，空陣列 = 鎖定。適用於所有範圍。拒絕清單優先。請參閱 [Managed MCP 設定](/zh-TW/managed-mcp) | `[{ "serverName": "github" }]` |225| `allowedMcpServers` | 在 managed-settings.json 中設定時，使用者可以設定的 MCP servers 白名單。未定義 = 無限制，空陣列 = 鎖定。適用於所有範圍。拒絕清單優先。請參閱 [Managed MCP 設定](/docs/zh-TW/managed-mcp) | `[{ "serverName": "github" }]` |

226| `allowManagedHooksOnly` | （Managed 設定僅限）僅載入 managed hooks、SDK hooks 和在 managed 設定 `enabledPlugins` 中強制啟用的 plugins 中的 hooks。使用者、專案和所有其他 plugin hooks 被阻止。請參閱 [Hook 設定](#hook-configuration) | `true` |226| `allowManagedHooksOnly` | （Managed 設定僅限）僅載入 managed hooks、SDK hooks 和在 managed 設定 `enabledPlugins` 中強制啟用的 plugins 中的 hooks。使用者、專案和所有其他 plugin hooks 被阻止。請參閱 [Hook 設定](#hook-configuration) | `true` |

227| `allowManagedMcpServersOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedMcpServers`。`deniedMcpServers` 仍從所有來源合併。使用者仍可新增 MCP servers，但僅適用管理員定義的白名單。請參閱 [Managed MCP 設定](/zh-TW/managed-mcp) | `true` |227| `allowManagedMcpServersOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedMcpServers`。`deniedMcpServers` 仍從所有來源合併。使用者仍可新增 MCP servers，但僅適用管理員定義的白名單。請參閱 [Managed MCP 設定](/docs/zh-TW/managed-mcp) | `true` |

228| `allowManagedPermissionRulesOnly` | （Managed 設定僅限）防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅適用 managed 設定中的規則。請參閱 [Managed 專用設定](/zh-TW/permissions#managed-only-settings) | `true` |228| `allowManagedPermissionRulesOnly` | （Managed 設定僅限）防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅適用 managed 設定中的規則。請參閱 [Managed 專用設定](/docs/zh-TW/permissions#managed-only-settings) | `true` |

229| `alwaysThinkingEnabled` | 為所有工作階段預設啟用[擴展思考](/zh-TW/model-config#extended-thinking)。通常透過 `/config` 命令而不是直接編輯來設定。若要強制思考關閉，無論此設定如何，請在 `env` 中設定 [`MAX_THINKING_TOKENS=0`](/zh-TW/env-vars)，這會停用 Anthropic API 上的思考，除了 Fable 5，無法關閉思考。在[第三方提供者](/zh-TW/third-party-integrations)上，這會改為省略 `thinking` 參數，自適應推理模型仍可能思考 | `true` |229| `alwaysThinkingEnabled` | 為所有工作階段預設啟用[擴展思考](/docs/zh-TW/model-config#extended-thinking)。通常透過 `/config` 命令而不是直接編輯來設定。若要強制思考關閉，無論此設定如何，請在 `env` 中設定 [`MAX_THINKING_TOKENS=0`](/docs/zh-TW/env-vars)，這會停用 Anthropic API 上的思考，除了 Fable 5，無法關閉思考。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，這會改為省略 `thinking` 參數，自適應推理模型仍可能思考 | `true` |

230| `apiKeyHelper` | 自訂指令碼，在系統 shell（macOS 和 Linux 上為 `/bin/sh`，Windows 上為 `cmd`）中執行，以產生驗證值。此值將作為 `X-Api-Key` 和 `Authorization: Bearer` 標頭傳送以進行模型請求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/zh-TW/env-vars) 設定重新整理間隔 | `/bin/generate_temp_api_key.sh` |230| `apiKeyHelper` | 自訂指令碼，在系統 shell（macOS 和 Linux 上為 `/bin/sh`，Windows 上為 `cmd`）中執行，以產生驗證值。此值將作為 `X-Api-Key` 和 `Authorization: Bearer` 標頭傳送以進行模型請求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/docs/zh-TW/env-vars) 設定重新整理間隔 | `/bin/generate_temp_api_key.sh` |

231| `askUserQuestionTimeout` | {/* min-version: 2.1.200 */}**預設**：`"never"`。未回答的 [`AskUserQuestion`](/zh-TW/tools-reference) 對話框在自動繼續前的閒置時間，使用您已選擇的任何選項。接受 `"60s"`、`"5m"`、`"10m"` 或 `"never"`。使用預設值，問題會等待您回答。在 `/config` 中顯示為**問題自動繼續逾時**，會將此金鑰寫入使用者設定。不從專案或本機設定讀取。需要 Claude Code v2.1.200 或更新版本 | `"5m"` |231| `askUserQuestionTimeout` | **預設**：`"never"`。未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在自動繼續前的閒置時間，使用您已選擇的任何選項。接受 `"60s"`、`"5m"`、`"10m"` 或 `"never"`。使用預設值，問題會等待您回答。在 `/config` 中顯示為**問題自動繼續逾時**，會將此金鑰寫入使用者設定。不從專案或本機設定讀取。需要 Claude Code v2.1.200 或更新版本 | `"5m"` |

232| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |232| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

233| `autoCompactEnabled` | {/* min-version: 2.1.119 */}**預設**：`true`。當內容接近限制時自動壓縮對話。在 `/config` 中顯示為**自動壓縮**。若要透過環境變數停用，請在 `env` 中設定 [`DISABLE_AUTO_COMPACT`](/zh-TW/env-vars) | `false` |233| `autoCompactEnabled` | **預設**：`true`。當內容接近限制時自動壓縮對話。在 `/config` 中顯示為**自動壓縮**。若要透過環境變數停用，請在 `env` 中設定 [`DISABLE_AUTO_COMPACT`](/docs/zh-TW/env-vars) | `false` |

235| `autoMemoryEnabled` | **預設**：`true`。啟用[自動記憶](/zh-TW/memory#enable-or-disable-auto-memory)。當為 `false` 時，Claude 不會從自動記憶目錄讀取或寫入。您也可以在工作階段期間使用 `/memory` 切換此設定。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/zh-TW/env-vars) | `false` |235| `autoMemoryEnabled` | **預設**：`true`。啟用[自動記憶](/docs/zh-TW/memory#enable-or-disable-auto-memory)。當為 `false` 時，Claude 不會從自動記憶目錄讀取或寫入。您也可以在工作階段期間使用 `/memory` 切換此設定。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/docs/zh-TW/env-vars) | `false` |

236| `autoMode` | 自訂[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器阻止和允許的內容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 陣列的散文規則。在陣列中包含字面字串 `"$defaults"` 以在該位置繼承內建規則。請參閱[設定自動模式](/zh-TW/auto-mode-config)。僅從使用者設定、`--settings` 旗標和 managed 設定讀取。在專案 `.claude/settings.json` 和本機 `.claude/settings.local.json` 中被忽略。{/* min-version: 2.1.207 */}在 v2.1.207 之前，`.claude/settings.local.json` 也被讀取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |236| `autoMode` | 自訂[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器阻止和允許的內容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 陣列的散文規則。在陣列中包含字面字串 `"$defaults"` 以在該位置繼承內建規則。請參閱[設定自動模式](/docs/zh-TW/auto-mode-config)。僅從使用者設定、`--settings` 旗標和 managed 設定讀取。在專案 `.claude/settings.json` 和本機 `.claude/settings.local.json` 中被忽略。在 v2.1.207 之前，`.claude/settings.local.json` 也被讀取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

237| `autoMode.classifyAllShell` | {/* min-version: 2.1.193 */}**預設**：`false`。當為 `true` 時，在自動模式使用中時暫停每個 Bash 和 PowerShell 允許規則，以便所有 shell 命令透過分類器路由，而不僅僅是符合任意程式碼執行模式的規則。請參閱[透過分類器路由所有 shell 命令](/zh-TW/auto-mode-config#route-all-shell-commands-through-the-classifier)。需要 Claude Code v2.1.193 或更新版本 | `true` |237| `autoMode.classifyAllShell` | **預設**：`false`。當為 `true` 時，在自動模式使用中時暫停每個 Bash 和 PowerShell 允許規則，以便所有 shell 命令透過分類器路由，而不僅僅是符合任意程式碼執行模式的規則。請參閱[透過分類器路由所有 shell 命令](/docs/zh-TW/auto-mode-config#route-all-shell-commands-through-the-classifier)。需要 Claude Code v2.1.193 或更新版本 | `true` |

239| `autoUpdatesChannel` | **預設**：`"latest"`。遵循更新的發行頻道。使用 `"stable"` 以取得通常約一週舊的版本並跳過有重大迴歸的版本，或 `"latest"` 以取得最新版本。若要完全停用自動更新，請在 `env` 中設定 [`DISABLE_AUTOUPDATER`](/zh-TW/setup#disable-auto-updates) | `"stable"` |239| `autoUpdatesChannel` | **預設**：`"latest"`。遵循更新的發行頻道。使用 `"stable"` 以取得通常約一週舊的版本並跳過有重大迴歸的版本，或 `"latest"` 以取得最新版本。若要完全停用自動更新，請在 `env` 中設定 [`DISABLE_AUTOUPDATER`](/docs/zh-TW/setup#disable-auto-updates) | `"stable"` |

240| `availableModels` | 限制使用者可以為主工作階段、[subagents](/zh-TW/sub-agents)、[skills](/zh-TW/skills) 和 [advisor](/zh-TW/advisor) 選擇的模型。不影響預設選項，除非 `enforceAvailableModels` 也設定。請參閱[限制模型選擇](/zh-TW/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |240| `availableModels` | 限制使用者可以為主工作階段、[subagents](/docs/zh-TW/sub-agents)、[skills](/docs/zh-TW/skills) 和 [advisor](/docs/zh-TW/advisor) 選擇的模型。不影響預設選項，除非 `enforceAvailableModels` 也設定。請參閱[限制模型選擇](/docs/zh-TW/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |

244| `axScreenReader` | {/* min-version: 2.1.181 */}渲染螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。螢幕閱讀器模式使用經典渲染器，因此在其使用中時 `tui` 設定無效；附加的[背景工作階段](/zh-TW/agent-view)仍會全螢幕渲染。[`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 環境變數和 [`--ax-screen-reader`](/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 | `true` |244| `axScreenReader` | 渲染螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。螢幕閱讀器模式使用經典渲染器，因此在其使用中時 `tui` 設定無效；附加的[背景工作階段](/docs/zh-TW/agent-view)仍會全螢幕渲染。[`CLAUDE_AX_SCREEN_READER`](/docs/zh-TW/env-vars) 環境變數和 [`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 | `true` |

245| `blockedMarketplaces` | （Managed 設定僅限）marketplace 來源的黑名單。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |245| `blockedMarketplaces` | （Managed 設定僅限）marketplace 來源的黑名單。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。請參閱 [Managed marketplace 限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

246| `browserExternalPageTools` | （Managed 設定僅限）設定為 `"disabled"` 以防止 Claude 使用工具讀取或作用於桌面應用程式[瀏覽器窗格](/zh-TW/desktop#browse-external-sites)中的外部頁面。使用者仍可自行導覽到外部網站，本機開發伺服器預覽不受影響 | `"disabled"` |246| `browserExternalPageTools` | （Managed 設定僅限）設定為 `"disabled"` 以防止 Claude 使用工具讀取或作用於桌面應用程式[瀏覽器窗格](/docs/zh-TW/desktop#browse-external-sites)中的外部頁面。使用者仍可自行導覽到外部網站，本機開發伺服器預覽不受影響 | `"disabled"` |

247| `channelsEnabled` | （Managed 設定僅限）允許組織使用[頻道](/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上，當此設定未設定或為 `false` 時，頻道會被阻止。對於使用 API 金鑰驗證的 [Anthropic Console](/zh-TW/authentication#claude-console-authentication) 帳戶，除非您的組織部署 managed 設定（在這種情況下此金鑰必須設定為 `true`），否則預設允許頻道 | `true` |247| `channelsEnabled` | （Managed 設定僅限）允許組織使用[頻道](/docs/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上，當此設定未設定或為 `false` 時，頻道會被阻止。對於使用 API 金鑰驗證的 [Anthropic Console](/docs/zh-TW/authentication#claude-console-authentication) 帳戶，除非您的組織部署 managed 設定（在這種情況下此金鑰必須設定為 `true`），否則預設允許頻道 | `true` |

248| `claudeMd` | （Managed 設定僅限）CLAUDE.md 樣式的指示，作為組織管理的記憶注入。僅在 managed 或政策設定中設定時受尊重，在使用者、專案和本機設定中被忽略。請參閱[組織範圍的 CLAUDE.md](/zh-TW/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |248| `claudeMd` | （Managed 設定僅限）CLAUDE.md 樣式的指示，作為組織管理的記憶注入。僅在 managed 或政策設定中設定時受尊重，在使用者、專案和本機設定中被忽略。請參閱[組織範圍的 CLAUDE.md](/docs/zh-TW/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |

249| `claudeMdExcludes` | 載入[記憶](/zh-TW/memory)時要跳過的 `CLAUDE.md` 檔案的 Glob 模式或絕對路徑。模式與絕對檔案路徑相符。僅適用於使用者、專案和本機記憶；managed 政策檔案無法排除 | `["**/vendor/**/CLAUDE.md"]` |249| `claudeMdExcludes` | 載入[記憶](/docs/zh-TW/memory)時要跳過的 `CLAUDE.md` 檔案的 Glob 模式或絕對路徑。模式與絕對檔案路徑相符。僅適用於使用者、專案和本機記憶；managed 政策檔案無法排除 | `["**/vendor/**/CLAUDE.md"]` |

250| `cleanupPeriodDays` | **預設**：`30` 天，最少 `1`。Claude Code 刪除[工作階段檔案和其他應用程式資料](/zh-TW/claude-directory#cleaned-up-automatically)超過此期間的檔案在啟動時。設定 `0` 會失敗並出現驗證錯誤。相同的年齡截止也適用於[孤立 worktrees](/zh-TW/worktrees#clean-up-worktrees) 在啟動時的自動移除。{/* min-version: 2.1.203 */}如果 Claude Code 無法讀取或解析設定檔案，它會暫停保留清理掃描並在 `/status` 中顯示警告，直到您修復檔案，除非 [managed 設定](/zh-TW/server-managed-settings)提供 `cleanupPeriodDays`，在這種情況下掃描以 managed 值執行。在 v2.1.203 之前，清理以 30 天預設執行，並可能刪除較長 `cleanupPeriodDays` 打算保留的文字記錄；新於 30 天的檔案永遠不會被移除。若要完全停用文字記錄寫入，請設定 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數。在非互動模式中，使用 `--no-session-persistence` 與 `-p` 一起傳遞或在 Agent SDK 中設定 `persistSession: false`。 | `20` |250| `cleanupPeriodDays` | **預設**：`30` 天，最少 `1`。Claude Code 刪除[工作階段檔案和其他應用程式資料](/docs/zh-TW/claude-directory#cleaned-up-automatically)超過此期間的檔案在啟動時。設定 `0` 會失敗並出現驗證錯誤。相同的年齡截止也適用於[孤立 worktrees](/docs/zh-TW/worktrees#clean-up-worktrees) 在啟動時的自動移除。如果 Claude Code 無法讀取或解析設定檔案，它會暫停保留清理掃描並在 `/status` 中顯示警告，直到您修復檔案，除非 [managed 設定](/docs/zh-TW/server-managed-settings)提供 `cleanupPeriodDays`，在這種情況下掃描以 managed 值執行。在 v2.1.203 之前，清理以 30 天預設執行，並可能刪除較長 `cleanupPeriodDays` 打算保留的文字記錄；新於 30 天的檔案永遠不會被移除。若要完全停用文字記錄寫入，請設定 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/zh-TW/env-vars) 環境變數。在非互動模式中，使用 `--no-session-persistence` 與 `-p` 一起傳遞或在 Agent SDK 中設定 `persistSession: false`。 | `20` |

252| `defaultShell` | **預設**：`"bash"`，或在 Bash 不可用時 Windows 上為 `"powershell"`。輸入框 `!` 命令的預設 shell。接受 `"bash"` 或 `"powershell"`。設定 `"powershell"` 會在 Windows 上透過 PowerShell 路由互動式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) | `"powershell"` |252| `defaultShell` | **預設**：`"bash"`，或在 Bash 不可用時 Windows 上為 `"powershell"`。輸入框 `!` 命令的預設 shell。接受 `"bash"` 或 `"powershell"`。設定 `"powershell"` 會在 Windows 上透過 PowerShell 路由互動式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。請參閱 [PowerShell tool](/docs/zh-TW/tools-reference#powershell-tool) | `"powershell"` |

253| `deniedMcpServers` | 在 managed-settings.json 中設定時，明確阻止的 MCP servers 拒絕清單。適用於所有範圍，包括 managed servers。拒絕清單優先於白名單。請參閱 [Managed MCP 設定](/zh-TW/managed-mcp) | `[{ "serverName": "filesystem" }]` |253| `deniedMcpServers` | 在 managed-settings.json 中設定時，明確阻止的 MCP servers 拒絕清單。適用於所有範圍，包括 managed servers。拒絕清單優先於白名單。請參閱 [Managed MCP 設定](/docs/zh-TW/managed-mcp) | `[{ "serverName": "filesystem" }]` |

254| `disableAgentView` | 設定為 `true` 以關閉[背景代理和代理檢視](/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和隨選主管。通常在 [managed 設定](/zh-TW/permissions#managed-settings) 中設定。等同於將 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 設定為 `1` | `true` |254| `disableAgentView` | 設定為 `true` 以關閉[背景代理和代理檢視](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和隨選主管。通常在 [managed 設定](/docs/zh-TW/permissions#managed-settings) 中設定。等同於將 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 設定為 `1` | `true` |

257| `disableAutoMode` | 設定為 `"disable"` 以防止[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)被啟用。從 `Shift+Tab` 循環中移除 `auto` 並在啟動時拒絕 `--permission-mode auto`。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `"disable"` |257| `disableAutoMode` | 設定為 `"disable"` 以防止[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)被啟用。從 `Shift+Tab` 循環中移除 `auto` 並在啟動時拒絕 `--permission-mode auto`。在[managed 設定](/docs/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `"disable"` |

258| `disableBrowserExternalNavigation` | （Managed 設定僅限）設定為 `true` 以關閉桌面應用程式[瀏覽器窗格](/zh-TW/desktop#browse-external-sites)中的外部瀏覽。使用者和 Claude 都無法導覽到外部網站，localhost 開發伺服器預覽不受影響。值必須是 JSON 布林值 `true`；字串 `"true"` 會被忽略 | `true` |258| `disableBrowserExternalNavigation` | （Managed 設定僅限）設定為 `true` 以關閉桌面應用程式[瀏覽器窗格](/docs/zh-TW/desktop#browse-external-sites)中的外部瀏覽。使用者和 Claude 都無法導覽到外部網站，localhost 開發伺服器預覽不受影響。值必須是 JSON 布林值 `true`；字串 `"true"` 會被忽略 | `true` |

259| `disableBundledSkills` | 設定為 `true` 以停用隨 Claude Code 一起提供的 [skills](/zh-TW/skills) 和工作流程：bundled skills 和工作流程會被完全移除，而內建斜線命令（如 `/init`）保持可輸入但對模型隱藏。`/doctor` 保持可輸入，如內建命令；改用 [`DISABLE_DOCTOR_COMMAND`](/zh-TW/env-vars) 隱藏它。來自 plugins、`.claude/skills/` 和 `.claude/commands/` 的 Skills 不受影響。等同於將 `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` 設定為 `1` | `true` |259| `disableBundledSkills` | 設定為 `true` 以停用隨 Claude Code 一起提供的 [skills](/docs/zh-TW/skills) 和工作流程：bundled skills 和工作流程會被完全移除，而內建斜線命令（如 `/init`）保持可輸入但對模型隱藏。`/doctor` 保持可輸入，如內建命令；改用 [`DISABLE_DOCTOR_COMMAND`](/docs/zh-TW/env-vars) 隱藏它。來自 plugins、`.claude/skills/` 和 `.claude/commands/` 的 Skills 不受影響。等同於將 `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` 設定為 `1` | `true` |

260| `disableClaudeAiConnectors` | {/* min-version: 2.1.182 */}停用 [claude.ai MCP connectors](/zh-TW/mcp#use-mcp-servers-from-claude-ai)，使其不會自動擷取或連線。在任何設定範圍中設定。任何來源中的 `true` 優先，因此簽入的專案 `.claude/settings.json` 可以選擇退出雲端 connectors，但專案層級的 `false` 無法覆蓋使用者或政策層級的 `true`。透過 `--mcp-config` 明確傳遞的 Servers 不受影響。若要拒絕個別 connectors 而不是所有 connectors，請改用 [`deniedMcpServers`](/zh-TW/managed-mcp)。需要 Claude Code v2.1.182 或更新版本 | `true` |260| `disableClaudeAiConnectors` | 停用 [claude.ai MCP connectors](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)，使其不會自動擷取或連線。在任何設定範圍中設定。任何來源中的 `true` 優先，因此簽入的專案 `.claude/settings.json` 可以選擇退出雲端 connectors，但專案層級的 `false` 無法覆蓋使用者或政策層級的 `true`。透過 `--mcp-config` 明確傳遞的 Servers 不受影響。若要拒絕個別 connectors 而不是所有 connectors，請改用 [`deniedMcpServers`](/docs/zh-TW/managed-mcp)。需要 Claude Code v2.1.182 或更新版本 | `true` |

261| `disableDeepLinkRegistration` | 設定為 `"disable"` 以防止 Claude Code 在啟動時向作業系統註冊 `claude-cli://` 協議處理程式。[深層連結](/zh-TW/deep-links)讓外部工具透過預先填入的提示開啟 Claude Code 工作階段。在協議處理程式註冊受限或單獨管理的環境中很有用 | `"disable"` |261| `disableDeepLinkRegistration` | 設定為 `"disable"` 以防止 Claude Code 在啟動時向作業系統註冊 `claude-cli://` 協議處理程式。[深層連結](/docs/zh-TW/deep-links)讓外部工具透過預先填入的提示開啟 Claude Code 工作階段。在協議處理程式註冊受限或單獨管理的環境中很有用 | `"disable"` |

263| `disableRemoteControl` | {/* min-version: 2.1.128 */}停用[遠端控制](/zh-TW/remote-control)：阻止 `claude remote-control`、`--remote-control` 旗標、自動啟動和工作階段內切換。通常放在[managed 設定](/zh-TW/permissions#managed-settings)中以進行每個裝置的 MDM 強制執行，但適用於任何範圍。需要 Claude Code v2.1.128 或更新版本 | `true` |263| `disableRemoteControl` | 停用[遠端控制](/docs/zh-TW/remote-control)：阻止 `claude remote-control`、`--remote-control` 旗標、自動啟動和工作階段內切換。通常放在[managed 設定](/docs/zh-TW/permissions#managed-settings)中以進行每個裝置的 MDM 強制執行，但適用於任何範圍。需要 Claude Code v2.1.128 或更新版本 | `true` |

264| `disableSideloadFlags` | {/* min-version: 2.1.193 */}（Managed 設定僅限）在啟動時拒絕 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 旗標，使用者可能會傳遞這些旗標以繞過 [`strictKnownMarketplaces`](#strictknownmarketplaces) 進行單一執行。也拒絕從任何內部產生 CLI 的表面傳遞這些旗標，目前[Cowork](/zh-TW/desktop) 桌面應用程式中的本機工作階段。其 servers 全部為進程內 `type: "sdk"` 項目的 `--mcp-config` 仍被接受，因此 Agent SDK 和 VS Code 擴充功能保持工作。不阻止 `claude mcp add`、`.mcp.json` 或 SDK `setMcpServers()`；與 [`allowedMcpServers`](/zh-TW/managed-mcp) 配對以進行每個 server 的 MCP 控制。需要 Claude Code v2.1.193 或更新版本 | `true` |264| `disableSideloadFlags` | （Managed 設定僅限）在啟動時拒絕 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 旗標，使用者可能會傳遞這些旗標以繞過 [`strictKnownMarketplaces`](#strictknownmarketplaces) 進行單一執行。也拒絕從任何內部產生 CLI 的表面傳遞這些旗標，目前[Cowork](/docs/zh-TW/desktop) 桌面應用程式中的本機工作階段。其 servers 全部為進程內 `type: "sdk"` 項目的 `--mcp-config` 仍被接受，因此 Agent SDK 和 VS Code 擴充功能保持工作。不阻止 `claude mcp add`、`.mcp.json` 或 SDK `setMcpServers()`；與 [`allowedMcpServers`](/docs/zh-TW/managed-mcp) 配對以進行每個 server 的 MCP 控制。需要 Claude Code v2.1.193 或更新版本 | `true` |

265| `disableSkillShellExecution` | 停用 [skills](/zh-TW/skills) 和來自使用者、專案、plugin 或其他目錄來源的自訂命令中的內嵌 shell 執行（`` !`...` `` 和 ` ```! ` 區塊）。命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。Bundled 和 managed skills 不受影響。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `true` |265| `disableSkillShellExecution` | 停用 [skills](/docs/zh-TW/skills) 和來自使用者、專案、plugin 或其他目錄來源的自訂命令中的內嵌 shell 執行（`` !`...` `` 和 ` ```! ` 區塊）。命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。Bundled 和 managed skills 不受影響。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `true` |

267| `editorMode` | **預設**：`"normal"`。輸入提示的快捷鍵模式：`"normal"` 或 `"vim"`。在 `/config` 中顯示為**編輯器模式** | `"vim"` |267| `editorMode` | **預設**：`"normal"`。輸入提示的快捷鍵模式：`"normal"` 或 `"vim"`。在 `/config` 中顯示為**編輯器模式** | `"vim"` |

268| `effortLevel` | 跨工作階段持久化[努力等級](/zh-TW/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。當您執行 `/effort` 時自動寫入，其中包含其中一個值。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/zh-TW/env-vars) 會覆蓋此設定以進行一個工作階段。請參閱[調整努力等級](/zh-TW/model-config#adjust-effort-level)以了解支援的模型 | `"xhigh"` |268| `effortLevel` | 跨工作階段持久化[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。當您執行 `/effort` 時自動寫入，其中包含其中一個值。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-TW/env-vars) 會覆蓋此設定以進行一個工作階段。請參閱[調整努力等級](/docs/zh-TW/model-config#adjust-effort-level)以了解支援的模型 | `"xhigh"` |

269| `enableAllProjectMcpServers` | 自動批准專案 `.mcp.json` 檔案中定義的所有 MCP servers。{/* min-version: 2.1.196 */}自 v2.1.196 起，`claude mcp list` 和 `claude mcp get` 在不受信任的資料夾中僅從[未簽入儲存庫的設定檔案](/zh-TW/mcp#managing-your-servers)中尊重此金鑰 | `true` |269| `enableAllProjectMcpServers` | 自動批准專案 `.mcp.json` 檔案中定義的所有 MCP servers。自 v2.1.196 起，`claude mcp list` 和 `claude mcp get` 在不受信任的資料夾中僅從[未簽入儲存庫的設定檔案](/docs/zh-TW/mcp#managing-your-servers)中尊重此金鑰 | `true` |

270| `enableArtifact` | {/* min-version: 2.1.196 */}為此使用者啟用或停用 [Artifact](/zh-TW/artifacts) 工具。未設定時，預設遵循功能的[可用性](/zh-TW/artifacts#availability)以取得您的帳戶。`/config` 中的 **Artifacts** 列寫入此金鑰。Managed `disableArtifact` 和您組織的[管理員設定](/zh-TW/artifacts#manage-artifacts-for-your-organization)優先，該金鑰在專案和本機設定（`.claude/settings.json`、`.claude/settings.local.json`）中被忽略，儲存庫可能會簽入。需要 Claude Code v2.1.196 或更新版本 | `true` |270| `enableArtifact` | 為此使用者啟用或停用 [Artifact](/docs/zh-TW/artifacts) 工具。未設定時，預設遵循功能的[可用性](/docs/zh-TW/artifacts#availability)以取得您的帳戶。`/config` 中的 **Artifacts** 列寫入此金鑰。Managed `disableArtifact` 和您組織的[管理員設定](/docs/zh-TW/artifacts#manage-artifacts-for-your-organization)優先，該金鑰在專案和本機設定（`.claude/settings.json`、`.claude/settings.local.json`）中被忽略，儲存庫可能會簽入。需要 Claude Code v2.1.196 或更新版本 | `true` |

271| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 檔案中特定 MCP servers 的清單。{/* min-version: 2.1.196 */}自 v2.1.196 起，`claude mcp list` 和 `claude mcp get` 在不受信任的資料夾中僅從[未簽入儲存庫的設定檔案](/zh-TW/mcp#managing-your-servers)中尊重此金鑰 | `["memory", "github"]` |271| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 檔案中特定 MCP servers 的清單。自 v2.1.196 起，`claude mcp list` 和 `claude mcp get` 在不受信任的資料夾中僅從[未簽入儲存庫的設定檔案](/docs/zh-TW/mcp#managing-your-servers)中尊重此金鑰 | `["memory", "github"]` |

272| `enforceAvailableModels` | {/* min-version: 2.1.175 */}將 `availableModels` 白名單擴展到預設模型。當在 managed 設定中為 `true` 且 `availableModels` 是非空陣列時，預設選項會回退到第一個可用的白名單項目，但僅當使用者帳戶類型的預設模型不在白名單中時；白名單預設會保持原樣。當 `availableModels` 未設定或為空時無效。請參閱[為預設模型強制執行白名單](/zh-TW/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更新版本 | `true` |272| `enforceAvailableModels` | 將 `availableModels` 白名單擴展到預設模型。當在 managed 設定中為 `true` 且 `availableModels` 是非空陣列時，預設選項會回退到第一個可用的白名單項目，但僅當使用者帳戶類型的預設模型不在白名單中時；白名單預設會保持原樣。當 `availableModels` 未設定或為空時無效。請參閱[為預設模型強制執行白名單](/docs/zh-TW/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更新版本 | `true` |

273| `env` | 應用於每個工作階段和 Claude Code 從中產生的子流程的環境變數。將變數設定為 `""` 以使用空字串覆蓋 shell 匯出，Claude Code 將其視為未設定以進行提供者選擇。子流程仍會繼承空值。`NO_COLOR` 和 `FORCE_COLOR` 在此處設定時僅到達子流程；若要變更 Claude Code 自己的介面顏色，請在啟動 `claude` 前在您的 shell 中設定它們。{/* min-version: 2.1.195 */}自 v2.1.195 起，Claude Code 的託管環境設定的身份變數（例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`）在此處設定時會被忽略 | `{"FOO": "bar"}` |273| `env` | 應用於每個工作階段和 Claude Code 從中產生的子流程的環境變數。將變數設定為 `""` 以使用空字串覆蓋 shell 匯出，Claude Code 將其視為未設定以進行提供者選擇。子流程仍會繼承空值。`NO_COLOR` 和 `FORCE_COLOR` 在此處設定時僅到達子流程；若要變更 Claude Code 自己的介面顏色，請在啟動 `claude` 前在您的 shell 中設定它們。自 v2.1.195 起，Claude Code 的託管環境設定的身份變數（例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`）在此處設定時會被忽略 | `{"FOO": "bar"}` |

274| `fallbackModel` | 當主模型過載或不可用時按順序嘗試的備用模型。Claude Code 會為該輪的其餘部分切換到鏈中的下一個可用模型並顯示通知。`"default"` 擴展為預設模型。鏈限制為三個模型；額外項目會被忽略。與大多數陣列設定不同，此金鑰不跨設定檔案合併：定義它的最高優先順序檔案提供整個鏈。[`--fallback-model`](/zh-TW/cli-reference#cli-flags) 旗標會覆蓋此設定以進行一個工作階段。請參閱[備用模型鏈](/zh-TW/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |274| `fallbackModel` | 當主模型過載或不可用時按順序嘗試的備用模型。Claude Code 會為該輪的其餘部分切換到鏈中的下一個可用模型並顯示通知。`"default"` 擴展為預設模型。鏈限制為三個模型；額外項目會被忽略。與大多數陣列設定不同，此金鑰不跨設定檔案合併：定義它的最高優先順序檔案提供整個鏈。[`--fallback-model`](/docs/zh-TW/cli-reference#cli-flags) 旗標會覆蓋此設定以進行一個工作階段。請參閱[備用模型鏈](/docs/zh-TW/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |

276| `fastModePerSessionOptIn` | 當為 `true` 時，快速模式不會跨工作階段持久化。每個工作階段都以快速模式關閉開始，需要使用者使用 `/fast` 啟用它。使用者的快速模式偏好仍會儲存。請參閱[需要每個工作階段的選擇加入](/zh-TW/fast-mode#require-per-session-opt-in) | `true` |276| `fastModePerSessionOptIn` | 當為 `true` 時，快速模式不會跨工作階段持久化。每個工作階段都以快速模式關閉開始，需要使用者使用 `/fast` 啟用它。使用者的快速模式偏好仍會儲存。請參閱[需要每個工作階段的選擇加入](/docs/zh-TW/fast-mode#require-per-session-opt-in) | `true` |

277| `feedbackSurveyRate` | [工作階段品質調查](/zh-TW/data-usage#session-quality-surveys)出現時符合條件的機率（0–1）。設定為 `0` 以完全抑制，或設定 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-TW/env-vars) 在 `env` 中。在使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時很有用，其中預設樣本率不適用 | `0.05` |277| `feedbackSurveyRate` | [工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys)出現時符合條件的機率（0–1）。設定為 `0` 以完全抑制，或設定 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/docs/zh-TW/env-vars) 在 `env` 中。在使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時很有用，其中預設樣本率不適用 | `0.05` |

278| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**預設**：`true`。在每次編輯前快照檔案，以便 [`/rewind`](/zh-TW/checkpointing) 可以還原它們。在 `/config` 中顯示為**倒帶程式碼（檢查點）**。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/zh-TW/env-vars) | `false` |278| `fileCheckpointingEnabled` | **預設**：`true`。在每次編輯前快照檔案，以便 [`/rewind`](/docs/zh-TW/checkpointing) 可以還原它們。在 `/config` 中顯示為**倒帶程式碼（檢查點）**。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/docs/zh-TW/env-vars) | `false` |

279| `fileSuggestion` | 為 `@` 檔案自動完成設定自訂指令碼。請參閱[檔案建議設定](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |279| `fileSuggestion` | 為 `@` 檔案自動完成設定自訂指令碼。請參閱[檔案建議設定](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

280| `footerLinksRegexes` | {/* min-version: 2.1.176 */}當 regex 符合輪次輸出時在頁尾中渲染額外的可點擊徽章。每個項目都有一個 `pattern`、一個包含 `{name}` 佔位符的 URL 範本（從命名擷取群組填入），以及一個選用的 `label`。僅從使用者設定、`--settings` 旗標和 managed 設定讀取。請參閱[頁尾連結徽章](#footer-link-badges)以了解 URL 限制、方案白名單和限制。需要 Claude Code v2.1.176 或更新版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |280| `footerLinksRegexes` | 當 regex 符合輪次輸出時在頁尾中渲染額外的可點擊徽章。每個項目都有一個 `pattern`、一個包含 `{name}` 佔位符的 URL 範本（從命名擷取群組填入），以及一個選用的 `label`。僅從使用者設定、`--settings` 旗標和 managed 設定讀取。請參閱[頁尾連結徽章](#footer-link-badges)以了解 URL 限制、方案白名單和限制。需要 Claude Code v2.1.176 或更新版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |

281| `forceLoginMethod` | 使用 `claudeai` 限制登入到 Claude.ai 帳戶，`console` 限制登入到 Claude Console 帳戶，或 `gateway` 限制登入到雲端閘道；請參閱 [Claude apps gateway](/zh-TW/claude-apps-gateway)。在 managed 設定中設定為任何值時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止，因為環境認證無法滿足所需的登入方法。第三方提供者工作階段（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：它們針對您的雲端提供者而不是 Anthropic 進行驗證 | `claudeai` |281| `forceLoginMethod` | 使用 `claudeai` 限制登入到 Claude.ai 帳戶，`console` 限制登入到 Claude Console 帳戶，或 `gateway` 限制登入到雲端閘道；請參閱 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway)。在 managed 設定中設定為任何值時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止，因為環境認證無法滿足所需的登入方法。第三方提供者工作階段（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：它們針對您的雲端提供者而不是 Anthropic 進行驗證 | `claudeai` |

282| `forceLoginGatewayUrl` | 在 `/login` 雲端閘道畫面上預先填入並鎖定閘道 URL。此金鑰或 `forceLoginMethod: "gateway"` 會顯示該畫面；同時設定兩者以便 URL 被填入。僅在 managed 政策層級受尊重；在使用者和專案設定中被忽略。請參閱 [Claude apps gateway](/zh-TW/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |282| `forceLoginGatewayUrl` | 在 `/login` 雲端閘道畫面上預先填入並鎖定閘道 URL。此金鑰或 `forceLoginMethod: "gateway"` 會顯示該畫面；同時設定兩者以便 URL 被填入。僅在 managed 政策層級受尊重；在使用者和專案設定中被忽略。請參閱 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |

283| `forceLoginOrgUUID` | 要求登入屬於特定 Anthropic 組織。接受單一 UUID 字串（也會在登入期間預先選擇該組織），或 UUID 陣列，其中接受任何列出的組織而不預先選擇。在 managed 設定中設定時，如果驗證帳戶不屬於列出的組織，登入會失敗；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止，因為無法驗證它們的組織成員資格。第三方提供者工作階段（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：使用您的雲端 IAM 限制可以使用哪些雲端帳戶。空陣列會失敗關閉並使用誤設定訊息阻止登入 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |283| `forceLoginOrgUUID` | 要求登入屬於特定 Anthropic 組織。接受單一 UUID 字串（也會在登入期間預先選擇該組織），或 UUID 陣列，其中接受任何列出的組織而不預先選擇。在 managed 設定中設定時，如果驗證帳戶不屬於列出的組織，登入會失敗；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止，因為無法驗證它們的組織成員資格。第三方提供者工作階段（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：使用您的雲端 IAM 限制可以使用哪些雲端帳戶。空陣列會失敗關閉並使用誤設定訊息阻止登入 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

284| `forceRemoteSettingsRefresh` | （Managed 設定僅限）阻止 CLI 啟動，直到從伺服器新鮮擷取遠端 managed 設定。如果擷取失敗，CLI 會結束而不是繼續使用快取或無設定。未設定時，啟動會繼續而不等待遠端設定。請參閱[失敗關閉強制執行](/zh-TW/server-managed-settings#enforce-fail-closed-startup) | `true` |284| `forceRemoteSettingsRefresh` | （Managed 設定僅限）阻止 CLI 啟動，直到從伺服器新鮮擷取遠端 managed 設定。如果擷取失敗，CLI 會結束而不是繼續使用快取或無設定。未設定時，啟動會繼續而不等待遠端設定。請參閱[失敗關閉強制執行](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup) | `true` |

285| `gcpAuthRefresh` | 當 GCP Application Default Credentials 過期或無法載入時重新整理它們的自訂指令碼。請參閱[進階認證設定](/zh-TW/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |285| `gcpAuthRefresh` | 當 GCP Application Default Credentials 過期或無法載入時重新整理它們的自訂指令碼。請參閱[進階認證設定](/docs/zh-TW/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |

287| `httpHookAllowedEnvVars` | HTTP hooks 可能插入到標頭中的環境變數名稱白名單。設定時，每個 hook 的有效 `allowedEnvVars` 是與此清單的交集。未定義 = 無限制。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |287| `httpHookAllowedEnvVars` | HTTP hooks 可能插入到標頭中的環境變數名稱白名單。設定時，每個 hook 的有效 `allowedEnvVars` 是與此清單的交集。未定義 = 無限制。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |

288| `includeGitInstructions` | **預設**：`true`。在 Claude 的系統提示中包含內建提交和 PR 工作流程指示和 git 狀態快照。設定為 `false` 以移除兩者，例如在使用您自己的 git 工作流程 skills 時。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 環境變數在設定時優先於此設定 | `false` |288| `includeGitInstructions` | **預設**：`true`。在 Claude 的系統提示中包含內建提交和 PR 工作流程指示和 git 狀態快照。設定為 `false` 以移除兩者，例如在使用您自己的 git 工作流程 skills 時。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 環境變數在設定時優先於此設定 | `false` |

289| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}**預設**：`false`。當[遠端控制](/zh-TW/remote-control)已連線時，當權限提示或問題等待您的輸入時傳送推播通知到您的手機。在 `/config` 中顯示為**需要操作時推播**。請參閱[行動推播通知](/zh-TW/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更新版本 | `true` |289| `inputNeededNotifEnabled` | **預設**：`false`。當[遠端控制](/docs/zh-TW/remote-control)已連線時，當權限提示或問題等待您的輸入時傳送推播通知到您的手機。在 `/config` 中顯示為**需要操作時推播**。請參閱[行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更新版本 | `true` |

290| `language` | 設定 Claude 的首選回應語言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 預設會以此語言回應。也設定[語音聽寫](/zh-TW/voice-dictation#change-the-dictation-language)語言和自動產生的工作階段標題。{/* min-version: 2.1.176 */}自 v2.1.176 起，未設定時，工作階段標題符合您對話的語言 | `"japanese"` |290| `language` | 設定 Claude 的首選回應語言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 預設會以此語言回應。也設定[語音聽寫](/docs/zh-TW/voice-dictation#change-the-dictation-language)語言和自動產生的工作階段標題。自 v2.1.176 起，未設定時，工作階段標題符合您對話的語言 | `"japanese"` |

291| `minimumVersion` | 防止背景自動更新和 `claude update` 安裝低於此版本的版本。當從 `"latest"` 頻道切換到 `"stable"` 時透過 `/config` 提示您保持在目前版本或允許降級。選擇保持設定此值。也適用於[managed 設定](/zh-TW/permissions#managed-settings)以釘選組織範圍的最小值。如需完全阻止啟動的硬底線，請參閱 `requiredMinimumVersion` | `"2.1.100"` |291| `minimumVersion` | 防止背景自動更新和 `claude update` 安裝低於此版本的版本。當從 `"latest"` 頻道切換到 `"stable"` 時透過 `/config` 提示您保持在目前版本或允許降級。選擇保持設定此值。也適用於[managed 設定](/docs/zh-TW/permissions#managed-settings)以釘選組織範圍的最小值。如需完全阻止啟動的硬底線，請參閱 `requiredMinimumVersion` | `"2.1.100"` |

293| `modelOverrides` | 將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Amazon Bedrock 推論設定檔 ARN。每個模型選擇器項目在呼叫提供者 API 時使用其對應的值。請參閱[按版本覆蓋模型 ID](/zh-TW/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |293| `modelOverrides` | 將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Amazon Bedrock 推論設定檔 ARN。每個模型選擇器項目在呼叫提供者 API 時使用其對應的值。請參閱[按版本覆蓋模型 ID](/docs/zh-TW/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

294| `otelHeadersHelper` | 產生動態 OpenTelemetry 標頭的指令碼。在啟動時和定期執行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-TW/env-vars) 設定重新整理間隔。請參閱[動態標頭](/zh-TW/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |294| `otelHeadersHelper` | 產生動態 OpenTelemetry 標頭的指令碼。在啟動時和定期執行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/docs/zh-TW/env-vars) 設定重新整理間隔。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |

296| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}（Managed 設定僅限）**預設**：`"first-wins"`。控制由嵌入主機流程（例如 Agent SDK 或 IDE 擴充功能）以程式設計方式提供的 managed 設定在同時存在管理員部署的 managed 層級時是否適用。`"first-wins"`：父級提供的設定被丟棄，僅適用管理員層級。`"merge"`：父級提供的設定適用於管理員層級下方，經過篩選以便它們可以收緊 managed 政策但不能放鬆政策。當未部署管理員層級時無效。需要 Claude Code v2.1.133 或更新版本 | `"merge"` |296| `parentSettingsBehavior` | （Managed 設定僅限）**預設**：`"first-wins"`。控制由嵌入主機流程（例如 Agent SDK 或 IDE 擴充功能）以程式設計方式提供的 managed 設定在同時存在管理員部署的 managed 層級時是否適用。`"first-wins"`：父級提供的設定被丟棄，僅適用管理員層級。`"merge"`：父級提供的設定適用於管理員層級下方，經過篩選以便它們可以收緊 managed 政策但不能放鬆政策。當未部署管理員層級時無效。需要 Claude Code v2.1.133 或更新版本 | `"merge"` |

299| `pluginSuggestionMarketplaces` | （Managed 設定僅限）其 plugins 可以作為內容相關安裝建議出現的 marketplace 名稱。沒有 marketplace 宣告的建議會出現而不需要此白名單；內建第一方前端設計提示不受影響。建議來自每個 plugin 在其 marketplace 項目中的 `relevance` 宣告。名稱僅在 marketplace 在機器上註冊且其註冊來源也在 managed 設定中宣告時才生效，作為該名稱的 `extraKnownMarketplaces` 項目或 `strictKnownMarketplaces` 的項目。從不同來源在白名單名稱下註冊的 marketplace 會被忽略。官方 marketplace 豁免於來源要求：白名單其名稱就足夠了，因為該名稱只能從官方 Anthropic 來源註冊。 | `["acme-corp-plugins"]` |299| `pluginSuggestionMarketplaces` | （Managed 設定僅限）其 plugins 可以作為內容相關安裝建議出現的 marketplace 名稱。沒有 marketplace 宣告的建議會出現而不需要此白名單；內建第一方前端設計提示不受影響。建議來自每個 plugin 在其 marketplace 項目中的 `relevance` 宣告。名稱僅在 marketplace 在機器上註冊且其註冊來源也在 managed 設定中宣告時才生效，作為該名稱的 `extraKnownMarketplaces` 項目或 `strictKnownMarketplaces` 的項目。從不同來源在白名單名稱下註冊的 marketplace 會被忽略。官方 marketplace 豁免於來源要求：白名單其名稱就足夠了，因為該名稱只能從官方 Anthropic 來源註冊。 | `["acme-corp-plugins"]` |

300| `pluginTrustMessage` | （Managed 設定僅限）在安裝前顯示的 plugin 信任警告中附加的自訂訊息。使用此選項新增組織特定的內容，例如確認來自您內部 marketplace 的 plugins 已經過審查。 | `"All plugins from our marketplace are approved by IT"` |300| `pluginTrustMessage` | （Managed 設定僅限）在安裝前顯示的 plugin 信任警告中附加的自訂訊息。使用此選項新增組織特定的內容，例如確認來自您內部 marketplace 的 plugins 已經過審查。 | `"All plugins from our marketplace are approved by IT"` |

301| `policyHelper` | {/* min-version: 2.1.136 */}管理員部署的可執行檔，在啟動時動態計算 managed 設定。僅從 MDM 或系統 `managed-settings.json` 檔案受尊重。請參閱[使用政策協助程式計算 managed 設定](#compute-managed-settings-with-a-policy-helper)。需要 Claude Code v2.1.136 或更新版本 | `{"path": "/usr/local/bin/claude-policy"}` |301| `policyHelper` | 管理員部署的可執行檔，在啟動時動態計算 managed 設定。僅從 MDM 或系統 `managed-settings.json` 檔案受尊重。請參閱[使用政策協助程式計算 managed 設定](#compute-managed-settings-with-a-policy-helper)。需要 Claude Code v2.1.136 或更新版本 | `{"path": "/usr/local/bin/claude-policy"}` |

302| `preferredNotifChannel` | **預設**：`"auto"`。工作完成和權限提示通知的方法：`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。`"auto"` 在 iTerm2、Ghostty 和 Kitty 中傳送桌面通知，在其他終端機中不執行任何操作。設定 `"terminal_bell"` 以在任何終端機中響鈴字元。在 `/config` 中顯示為**通知**。請參閱[取得終端機鈴聲或通知](/zh-TW/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |302| `preferredNotifChannel` | **預設**：`"auto"`。工作完成和權限提示通知的方法：`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。`"auto"` 在 iTerm2、Ghostty 和 Kitty 中傳送桌面通知，在其他終端機中不執行任何操作。設定 `"terminal_bell"` 以在任何終端機中響鈴字元。在 `/config` 中顯示為**通知**。請參閱[取得終端機鈴聲或通知](/docs/zh-TW/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |

304| `prUrlTemplate` | PR 徽章的 URL 範本，顯示在頁尾和工具結果摘要中。替換 `gh` 報告的 PR URL 中的 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。使用以指向內部程式碼審查工具而不是 `github.com`。不影響 Claude 散文中的 `#123` 自動連結 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |304| `prUrlTemplate` | PR 徽章的 URL 範本，顯示在頁尾和工具結果摘要中。替換 `gh` 報告的 PR URL 中的 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。使用以指向內部程式碼審查工具而不是 `github.com`。不影響 Claude 散文中的 `#123` 自動連結 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |

305| `remoteControlAtStartup` | {/* min-version: 2.1.119 */}當每個互動式工作階段啟動時自動連線[遠端控制](/zh-TW/remote-control)，而不是等待 `/remote-control`。設定為 `true` 以始終自動連線，`false` 以永不自動連線，或保留未設定以遵循您組織的預設。在 `/config` 中顯示為**為所有工作階段啟用遠端控制**。請參閱[為所有工作階段啟用遠端控制](/zh-TW/remote-control#enable-remote-control-for-all-sessions) | `false` |305| `remoteControlAtStartup` | 當每個互動式工作階段啟動時自動連線[遠端控制](/docs/zh-TW/remote-control)，而不是等待 `/remote-control`。設定為 `true` 以始終自動連線，`false` 以永不自動連線，或保留未設定以遵循您組織的預設。在 `/config` 中顯示為**為所有工作階段啟用遠端控制**。請參閱[為所有工作階段啟用遠端控制](/docs/zh-TW/remote-control#enable-remote-control-for-all-sessions) | `false` |

306| `requiredMaximumVersion` | Managed 設定僅限。允許啟動的最大 Claude Code 版本。如果執行中的版本較新，Claude Code 會在啟動時結束並指示使用者透過組織的核准方法安裝核准的版本；`claude install <version>` 也可能有效。背景自動更新和 `claude update` 會跳過高於上限的版本，因此在範圍內的安裝保持在範圍內。`claude update`、`claude install` 和 `claude doctor` 在上限以上保持工作，以便使用者可以恢復。早於此設定的版本會忽略它 | `"2.1.150"` |306| `requiredMaximumVersion` | Managed 設定僅限。允許啟動的最大 Claude Code 版本。如果執行中的版本較新，Claude Code 會在啟動時結束並指示使用者透過組織的核准方法安裝核准的版本；`claude install <version>` 也可能有效。背景自動更新和 `claude update` 會跳過高於上限的版本，因此在範圍內的安裝保持在範圍內。`claude update`、`claude install` 和 `claude doctor` 在上限以上保持工作，以便使用者可以恢復。早於此設定的版本會忽略它 | `"2.1.150"` |

307| `requiredMinimumVersion` | Managed 設定僅限。啟動所需的最小 Claude Code 版本。如果執行中的版本較舊，Claude Code 會在啟動時結束並指示使用者透過組織的核准方法更新。`claude update`、`claude install` 和 `claude doctor` 在底線以下保持工作，以便使用者可以恢復。與 `minimumVersion` 不同，後者防止降級但永遠不會阻止啟動。早於此設定的版本會忽略它 | `"2.1.150"` |307| `requiredMinimumVersion` | Managed 設定僅限。啟動所需的最小 Claude Code 版本。如果執行中的版本較舊，Claude Code 會在啟動時結束並指示使用者透過組織的核准方法更新。`claude update`、`claude install` 和 `claude doctor` 在底線以下保持工作，以便使用者可以恢復。與 `minimumVersion` 不同，後者防止降級但永遠不會阻止啟動。早於此設定的版本會忽略它 | `"2.1.150"` |

309| `respondToBashCommands` | {/* min-version: 2.1.186 */}**預設**：`true`。輸入框 `!` shell 命令執行後 Claude 是否回應。設定為 `false` 以將命令輸出新增到內容而不回應。請參閱[使用 `!` 前綴的 Shell 模式](/zh-TW/interactive-mode#shell-mode-with-prefix)。需要 Claude Code v2.1.186 或更新版本 | `false` |309| `respondToBashCommands` | **預設**：`true`。輸入框 `!` shell 命令執行後 Claude 是否回應。設定為 `false` 以將命令輸出新增到內容而不回應。請參閱[使用 `!` 前綴的 Shell 模式](/docs/zh-TW/interactive-mode#shell-mode-with-prefix)。需要 Claude Code v2.1.186 或更新版本 | `false` |

311| `showThinkingSummaries` | **預設**：`false`。在互動式工作階段中顯示[擴展思考](/zh-TW/model-config#extended-thinking)摘要。未設定或 `false` 時，思考區塊由 API 編輯並顯示為摺疊的存根。編輯只會改變您看到的內容，而不是模型生成的內容：若要減少思考支出，請[降低預算或停用思考](/zh-TW/model-config#extended-thinking)。此設定在非互動模式（`-p`）、Agent SDK 或 IDE 擴充功能（例如 VS Code）中無效 | `true` |311| `showThinkingSummaries` | **預設**：`false`。在互動式工作階段中顯示[擴展思考](/docs/zh-TW/model-config#extended-thinking)摘要。未設定或 `false` 時，思考區塊由 API 編輯並顯示為摺疊的存根。編輯只會改變您看到的內容，而不是模型生成的內容：若要減少思考支出，請[降低預算或停用思考](/docs/zh-TW/model-config#extended-thinking)。此設定在非互動模式（`-p`）、Agent SDK 或 IDE 擴充功能（例如 VS Code）中無效 | `true` |

313| `skillListingBudgetFraction` | **預設**：`0.01`。為 Claude 每輪看到的[skill 清單](/zh-TW/skills#skill-descriptions-are-cut-short)保留的模型內容視窗分數。當清單超過預算時，最少使用的 skills 的描述會摺疊為裸名稱，以便 Claude 仍可叫用它們，但不會看到原因。提高以保持更多描述可見，代價是每輪更多內容。`/doctor` 估計清單成本對預算 | `0.02` |313| `skillListingBudgetFraction` | **預設**：`0.01`。為 Claude 每輪看到的[skill 清單](/docs/zh-TW/skills#skill-descriptions-are-cut-short)保留的模型內容視窗分數。當清單超過預算時，最少使用的 skills 的描述會摺疊為裸名稱，以便 Claude 仍可叫用它們，但不會看到原因。提高以保持更多描述可見，代價是每輪更多內容。`/doctor` 估計清單成本對預算 | `0.02` |

314| `skillListingMaxDescChars` | **預設**：`1536`。[skill 清單](/zh-TW/skills#skill-descriptions-are-cut-short)中每個 skill 的字元上限，Claude 每輪看到的 `description` 和 `when_to_use` 文字的組合。超過此長度的文字會被截斷。提高以保持長描述完整，代價是每輪更多內容；降低以在 [`skillListingBudgetFraction`](#available-settings) 下適應更多 skills | `2048` |314| `skillListingMaxDescChars` | **預設**：`1536`。[skill 清單](/docs/zh-TW/skills#skill-descriptions-are-cut-short)中每個 skill 的字元上限，Claude 每輪看到的 `description` 和 `when_to_use` 文字的組合。超過此長度的文字會被截斷。提高以保持長描述完整，代價是每輪更多內容；降低以在 [`skillListingBudgetFraction`](#available-settings) 下適應更多 skills | `2048` |

315| `skillOverrides` | {/* min-version: 2.1.129 */}按 skill 名稱鍵入的每個 skill 可見性覆蓋。值為 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。讓您隱藏或摺疊 skill 而無需編輯其 SKILL.md。不適用於 plugin skills，這些由 `/plugin` 管理。`/skills` 功能表將這些寫入 `.claude/settings.local.json`。請參閱[從設定覆蓋 skill 可見性](/zh-TW/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更新版本 | `{"legacy-context": "name-only", "deploy": "off"}` |315| `skillOverrides` | 按 skill 名稱鍵入的每個 skill 可見性覆蓋。值為 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。讓您隱藏或摺疊 skill 而無需編輯其 SKILL.md。不適用於 plugin skills，這些由 `/plugin` 管理。`/skills` 功能表將這些寫入 `.claude/settings.local.json`。請參閱[從設定覆蓋 skill 可見性](/docs/zh-TW/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更新版本 | `{"legacy-context": "name-only", "deploy": "off"}` |

316| `skipWebFetchPreflight` | 跳過[WebFetch 網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，該檢查在擷取前將每個請求的主機名稱傳送到 `api.anthropic.com`。在阻止流量到 Anthropic 的環境中設定為 `true`，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 部署，具有限制性的出站。跳過時，WebFetch 嘗試任何 URL 而不諮詢黑名單 | `true` |316| `skipWebFetchPreflight` | 跳過[WebFetch 網域安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check)，該檢查在擷取前將每個請求的主機名稱傳送到 `api.anthropic.com`。在阻止流量到 Anthropic 的環境中設定為 `true`，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 部署，具有限制性的出站。跳過時，WebFetch 嘗試任何 URL 而不諮詢黑名單 | `true` |

318| `spinnerTipsOverride` | 使用自訂字串覆蓋微調器提示。`tips`：提示字串陣列。`excludeDefault`：如果為 `true`，僅顯示自訂提示；如果為 `false` 或不存在，自訂提示會與內建提示合併 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |318| `spinnerTipsOverride` | 使用自訂字串覆蓋微調器提示。`tips`：提示字串陣列。`excludeDefault`：如果為 `true`，僅顯示自訂提示；如果為 `false` 或不存在，自訂提示會與內建提示合併 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

319| `spinnerVerbs` | 自訂在微調器中顯示的動作動詞。將 `mode` 設定為 `"replace"` 以僅使用您的動詞，或 `"append"` 以將它們新增到預設值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |319| `spinnerVerbs` | 自訂在微調器中顯示的動作動詞。將 `mode` 設定為 `"replace"` 以僅使用您的動詞，或 `"append"` 以將它們新增到預設值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

320| `sshConfigs` | 要在[桌面](/zh-TW/desktop#pre-configure-ssh-connections-for-your-team)環境下拉式清單中顯示的 SSH 連線。每個項目需要 `id`、`name` 和 `sshHost`；`sshPort`、`sshIdentityFile` 和 `startDirectory` 是選用的。在 managed 設定中設定時，連線對使用者是唯讀的。僅從 managed 和使用者設定讀取 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |320| `sshConfigs` | 要在[桌面](/docs/zh-TW/desktop#pre-configure-ssh-connections-for-your-team)環境下拉式清單中顯示的 SSH 連線。每個項目需要 `id`、`name` 和 `sshHost`；`sshPort`、`sshIdentityFile` 和 `startDirectory` 是選用的。在 managed 設定中設定時，連線對使用者是唯讀的。僅從 managed 和使用者設定讀取 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |

321| `statusLine` | 設定自訂狀態行以顯示內容。物件的選用 `padding`、`refreshInterval` 和 `hideVimModeIndicator` 欄位控制間距、定期重新執行和是否隱藏提示下方的內建 vim 模式指示器。請參閱 [`statusLine` 文件](/zh-TW/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |321| `statusLine` | 設定自訂狀態行以顯示內容。物件的選用 `padding`、`refreshInterval` 和 `hideVimModeIndicator` 欄位控制間距、定期重新執行和是否隱藏提示下方的內建 vim 模式指示器。請參閱 [`statusLine` 文件](/docs/zh-TW/statusline#manually-configure-a-status-line) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

322| `strictKnownMarketplaces` | （Managed 設定僅限）plugin marketplaces 白名單。未定義 = 無限制，空陣列 = 鎖定。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |322| `strictKnownMarketplaces` | （Managed 設定僅限）plugin marketplaces 白名單。未定義 = 無限制，空陣列 = 鎖定。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。請參閱 [Managed marketplace 限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

323| `strictPluginOnlyCustomization` | （Managed 設定僅限）阻止 skills、agents、hooks 和 MCP servers 來自使用者和專案來源，因此它們只能來自 plugins 或 managed 設定。`true` 鎖定所有四個表面；陣列僅鎖定命名的表面。請參閱 [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |323| `strictPluginOnlyCustomization` | （Managed 設定僅限）阻止 skills、agents、hooks 和 MCP servers 來自使用者和專案來源，因此它們只能來自 plugins 或 managed 設定。`true` 鎖定所有四個表面；陣列僅鎖定命名的表面。請參閱 [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |

325| `teammateMode` | **預設**：`in-process`。[agent team](/zh-TW/agent-teams) 隊友的顯示方式：`in-process`、`auto`（在 tmux 或 iTerm2 中選擇分割窗格，否則為進程內）、`tmux`（使用 tmux 或 iTerm2 選擇分割窗格，從您的終端機偵測）或 {/* min-version: 2.1.186 */}}`iterm2`（iTerm2 原生分割窗格透過 `it2` CLI，在 v2.1.186 中新增）。預設在 v2.1.179 中從 `auto` 變更。`--teammate-mode` 會覆蓋此設定以進行一個工作階段。請參閱[選擇顯示模式](/zh-TW/agent-teams#choose-a-display-mode) | `"auto"` |325| `teammateMode` | **預設**：`in-process`。[agent team](/docs/zh-TW/agent-teams) 隊友的顯示方式：`in-process`、`auto`（在 tmux 或 iTerm2 中選擇分割窗格，否則為進程內）、`tmux`（使用 tmux 或 iTerm2 選擇分割窗格，從您的終端機偵測）或 }`iterm2`（iTerm2 原生分割窗格透過 `it2` CLI，在 v2.1.186 中新增）。預設在 v2.1.179 中從 `auto` 變更。`--teammate-mode` 會覆蓋此設定以進行一個工作階段。請參閱[選擇顯示模式](/docs/zh-TW/agent-teams#choose-a-display-mode) | `"auto"` |

327| `theme` | {/* min-version: 2.1.119 */}**預設**：`"dark"`。介面的色彩主題：`"auto"`、`"dark"`、`"light"`、`"dark-daltonized"`、`"light-daltonized"`、`"dark-ansi"`、`"light-ansi"` 或自訂主題參考，例如 `"custom:<slug>"` 或 `"custom:<plugin-name>:<slug>"`。請參閱[建立自訂主題](/zh-TW/terminal-config#create-a-custom-theme)。在 `/config` 中顯示為**主題** | `"dark"` |327| `theme` | **預設**：`"dark"`。介面的色彩主題：`"auto"`、`"dark"`、`"light"`、`"dark-daltonized"`、`"light-daltonized"`、`"dark-ansi"`、`"light-ansi"` 或自訂主題參考，例如 `"custom:<slug>"` 或 `"custom:<plugin-name>:<slug>"`。請參閱[建立自訂主題](/docs/zh-TW/terminal-config#create-a-custom-theme)。在 `/config` 中顯示為**主題** | `"dark"` |

328| `tui` | 終端機 UI 渲染器。使用 `"fullscreen"` 以取得無閃爍[替代螢幕渲染器](/zh-TW/fullscreen)，具有虛擬化捲軸。使用 `"default"` 以取得經典主螢幕渲染器。透過 `/tui` 設定。您也可以設定 [`CLAUDE_CODE_NO_FLICKER`](/zh-TW/env-vars) 環境變數。背景工作階段從[代理檢視](/zh-TW/agent-view)開啟時，無論此設定如何，始終使用全螢幕渲染器 | `"fullscreen"` |328| `tui` | 終端機 UI 渲染器。使用 `"fullscreen"` 以取得無閃爍[替代螢幕渲染器](/docs/zh-TW/fullscreen)，具有虛擬化捲軸。使用 `"default"` 以取得經典主螢幕渲染器。透過 `/tui` 設定。您也可以設定 [`CLAUDE_CODE_NO_FLICKER`](/docs/zh-TW/env-vars) 環境變數。背景工作階段從[代理檢視](/docs/zh-TW/agent-view)開啟時，無論此設定如何，始終使用全螢幕渲染器 | `"fullscreen"` |

329| `ultracode` | 為工作階段開啟 [ultracode](/zh-TW/workflows#let-claude-decide-with-ultracode)。此金鑰不從 `settings.json` 讀取。透過 `/effort ultracode`、`--settings` 或 Agent SDK 控制請求設定。{/* min-version: 2.1.203 */}若要以 ultracode 已開啟的狀態啟動工作階段，請使用 `claude --effort ultracode` 啟動，需要 Claude Code v2.1.203 或更新版本 | `true` |329| `ultracode` | 為工作階段開啟 [ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)。此金鑰不從 `settings.json` 讀取。透過 `/effort ultracode`、`--settings` 或 Agent SDK 控制請求設定。若要以 ultracode 已開啟的狀態啟動工作階段，請使用 `claude --effort ultracode` 啟動，需要 Claude Code v2.1.203 或更新版本 | `true` |

331| `verbose` | {/* min-version: 2.1.119 */}**預設**：`false`。顯示完整工具輸出而不是截斷摘要。在 `/config` 中顯示為**詳細輸出**。`--verbose` 旗標會覆蓋此設定以進行一個工作階段 | `true` |331| `verbose` | **預設**：`false`。顯示完整工具輸出而不是截斷摘要。在 `/config` 中顯示為**詳細輸出**。`--verbose` 旗標會覆蓋此設定以進行一個工作階段 | `true` |

333| `vimInsertModeRemaps` | {/* min-version: 2.1.208 */}將兩個按鍵 INSERT 模式序列對應到 Escape 在[vim 編輯器模式](/zh-TW/interactive-mode#vim-editor-mode)中。每個金鑰恰好是兩個按順序輸入的可列印字元，`"<Esc>"` 是唯一支援的目標；其他項目被忽略。僅從使用者、`--settings` 旗標和 managed 設定讀取，因此儲存庫的簽入設定無法重新對應您的按鍵。除非 `editorMode` 為 `"vim"`，否則無效。請參閱[重新對應 INSERT 模式按鍵序列](/zh-TW/interactive-mode#remap-insert-mode-key-sequences)。需要 Claude Code v2.1.208 或更新版本 | `{"jj": "<Esc>"}` |333| `vimInsertModeRemaps` | 將兩個按鍵 INSERT 模式序列對應到 Escape 在[vim 編輯器模式](/docs/zh-TW/interactive-mode#vim-editor-mode)中。每個金鑰恰好是兩個按順序輸入的可列印字元，`"<Esc>"` 是唯一支援的目標；其他項目被忽略。僅從使用者、`--settings` 旗標和 managed 設定讀取，因此儲存庫的簽入設定無法重新對應您的按鍵。除非 `editorMode` 為 `"vim"`，否則無效。請參閱[重新對應 INSERT 模式按鍵序列](/docs/zh-TW/interactive-mode#remap-insert-mode-key-sequences)。需要 Claude Code v2.1.208 或更新版本 | `{"jj": "<Esc>"}` |

334| `voice` | [語音聽寫](/zh-TW/voice-dictation)設定：`enabled` 開啟聽寫，`mode` 選擇 `"hold"` 或 `"tap"`，`autoSubmit` 在保持模式中按鍵釋放時傳送提示。當您執行 `/voice` 時自動寫入。需要 Claude.ai 帳戶 | `{ "enabled": true, "mode": "tap" }` |334| `voice` | [語音聽寫](/docs/zh-TW/voice-dictation)設定：`enabled` 開啟聽寫，`mode` 選擇 `"hold"` 或 `"tap"`，`autoSubmit` 在保持模式中按鍵釋放時傳送提示。當您執行 `/voice` 時自動寫入。需要 Claude.ai 帳戶 | `{ "enabled": true, "mode": "tap" }` |

336| `wheelScrollAccelerationEnabled` | {/* min-version: 2.1.174 */}**預設**：`true`。在[全螢幕渲染](/zh-TW/fullscreen#mouse-wheel-scrolling)中，加速滑鼠滾輪捲軸速度在快速捲軸期間。設定為 `false` 以取得每個滾輪缺口的恆定捲軸速率。需要 Claude Code v2.1.174 或更新版本 | `false` |336| `wheelScrollAccelerationEnabled` | **預設**：`true`。在[全螢幕渲染](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中，加速滑鼠滾輪捲軸速度在快速捲軸期間。設定為 `false` 以取得每個滾輪缺口的恆定捲軸速率。需要 Claude Code v2.1.174 或更新版本 | `false` |

337| `workflowKeywordTriggerEnabled` | {/* min-version: 2.1.157 */}**預設**：`true`。提示中的單詞 `ultracode` 是否觸發[動態工作流程](/zh-TW/workflows#ask-for-a-workflow-in-your-prompt)。設定為 `false` 以輸入單詞而不觸發一個。Ultracode 努力設定、`/workflows` 和儲存的工作流程命令不受影響。在 `/config` 中顯示為**Ultracode 關鍵字觸發**。在 v2.1.160 之前，觸發關鍵字是 `workflow` | `false` |337| `workflowKeywordTriggerEnabled` | **預設**：`true`。提示中的單詞 `ultracode` 是否觸發[動態工作流程](/docs/zh-TW/workflows#ask-for-a-workflow-in-your-prompt)。設定為 `false` 以輸入單詞而不觸發一個。Ultracode 努力設定、`/workflows` 和儲存的工作流程命令不受影響。在 `/config` 中顯示為**Ultracode 關鍵字觸發**。在 v2.1.160 之前，觸發關鍵字是 `workflow` | `false` |

338| `wslInheritsWindowsSettings` | （Windows managed 設定僅限）當為 `true` 時，WSL 上的 Claude Code 除了 `/etc/claude-code` 外還會從 Windows 政策鏈讀取 managed 設定，Windows 來源優先。僅在 HKLM 登錄機碼或 `C:\Program Files\ClaudeCode\managed-settings.json` 中設定時受尊重，兩者都需要 Windows 管理員才能寫入。為了讓 HKCU 政策也在 WSL 上適用，旗標必須另外在 HKCU 本身中設定。對原生 Windows 無效 | `true` |338| `wslInheritsWindowsSettings` | （Windows managed 設定僅限）當為 `true` 時，WSL 上的 Claude Code 除了 `/etc/claude-code` 外還會從 Windows 政策鏈讀取 managed 設定，Windows 來源優先。僅在 HKLM 登錄機碼或 `C:\Program Files\ClaudeCode\managed-settings.json` 中設定時受尊重，兩者都需要 Windows 管理員才能寫入。為了讓 HKCU 政策也在 WSL 上適用，旗標必須另外在 HKCU 本身中設定。對原生 Windows 無效 | `true` |

339 339

340<h3 id="global-config-settings">340<h3 id="global-config-settings">

348</Note>348</Note>

349 349

350| 金鑰 | 說明 | 範例 |350| 金鑰 | 說明 | 範例 |

351| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |351| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |

352| `autoConnectIde` | **預設**：`false`。當 Claude Code 從外部終端機啟動時自動連線到執行中的 IDE。在 VS Code 或 JetBrains 終端機外執行時在 `/config` 中顯示為**自動連線到 IDE（外部終端機）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/zh-TW/env-vars) 環境變數在設定時會覆蓋此設定 | `true` |352| `autoConnectIde` | **預設**：`false`。當 Claude Code 從外部終端機啟動時自動連線到執行中的 IDE。在 VS Code 或 JetBrains 終端機外執行時在 `/config` 中顯示為**自動連線到 IDE（外部終端機）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/docs/zh-TW/env-vars) 環境變數在設定時會覆蓋此設定 | `true` |

353| `autoInstallIdeExtension` | **預設**：`true`。從 VS Code 終端機執行時自動安裝 Claude Code IDE 擴充功能。在 VS Code 或 JetBrains 終端機內執行時在 `/config` 中顯示為**自動安裝 IDE 擴充功能**。您也可以設定 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-TW/env-vars) 環境變數 | `false` |353| `autoInstallIdeExtension` | **預設**：`true`。從 VS Code 終端機執行時自動安裝 Claude Code IDE 擴充功能。在 VS Code 或 JetBrains 終端機內執行時在 `/config` 中顯示為**自動安裝 IDE 擴充功能**。您也可以設定 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/docs/zh-TW/env-vars) 環境變數 | `false` |

355| `permissionExplainerEnabled` | **預設**：`true`。當您在 Bash 或 PowerShell 權限提示上按 `Ctrl+E` 時顯示模型產生的[命令說明](/zh-TW/permissions#permission-system)。設定為 `false` 以關閉快捷鍵 | `false` |355| `permissionExplainerEnabled` | **預設**：`true`。當您在 Bash 或 PowerShell 權限提示上按 `Ctrl+E` 時顯示模型產生的[命令說明](/docs/zh-TW/permissions#permission-system)。設定為 `false` 以關閉快捷鍵 | `false` |

356| `teammateDefaultModel` | [agent team](/zh-TW/agent-teams) 隊友在生成提示未指定時的預設模型。設定為模型別名（例如 `"sonnet"`），或 `null` 以繼承主管的目前 `/model` 選擇。在 `/config` 中顯示為**預設隊友模型** | `"sonnet"` |356| `teammateDefaultModel` | [agent team](/docs/zh-TW/agent-teams) 隊友在生成提示未指定時的預設模型。設定為模型別名（例如 `"sonnet"`），或 `null` 以繼承主管的目前 `/model` 選擇。在 `/config` 中顯示為**預設隊友模型** | `"sonnet"` |

357| `workflowSizeGuideline` | {/* min-version: 2.1.202 */}**預設**：`unrestricted`，不傳送任何指南。設定 Claude 在其撰寫的動態工作流程中目標的[代理計數](/zh-TW/workflows#set-a-size-guideline)。Claude Code 將值作為建議而不是強制上限傳送給 Claude。接受 `unrestricted`、`small`、`medium` 或 `large`。在 `/config` 中顯示為**動態工作流程大小**。您也可以使用 `/config workflowSizeGuideline=small` 直接設定它。需要 Claude Code v2.1.202 或更新版本。{/* min-version: 2.1.203 */}指南的代理計數也替換[`Large workflow` 警告](/zh-TW/workflows#cost)的預設閾值；該行為需要 Claude Code v2.1.203 或更新版本 | `"small"` |357| `workflowSizeGuideline` | **預設**：`unrestricted`，不傳送任何指南。設定 Claude 在其撰寫的動態工作流程中目標的[代理計數](/docs/zh-TW/workflows#set-a-size-guideline)。Claude Code 將值作為建議而不是強制上限傳送給 Claude。接受 `unrestricted`、`small`、`medium` 或 `large`。在 `/config` 中顯示為**動態工作流程大小**。您也可以使用 `/config workflowSizeGuideline=small` 直接設定它。需要 Claude Code v2.1.202 或更新版本。指南的代理計數也替換[`Large workflow` 警告](/docs/zh-TW/workflows#cost)的預設閾值；該行為需要 Claude Code v2.1.203 或更新版本 | `"small"` |

358 358

359<h3 id="worktree-settings">359<h3 id="worktree-settings">

360 Worktree 設定360 Worktree 設定

363設定 `--worktree` 如何建立和管理 git worktrees。363設定 `--worktree` 如何建立和管理 git worktrees。

364 364

365| 金鑰 | 說明 | 範例 |365| 金鑰 | 說明 | 範例 |

366| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |366| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

367| `worktree.baseRef` | 新 worktrees 分支的來源 ref。`"fresh"`（預設）從 `origin/<default-branch>` 分支以取得與遠端相符的乾淨樹。`"head"` 從您目前的本機 `HEAD` 分支，所以未推送的提交和功能分支狀態存在於 worktree 中。在連結的 worktree 內，`"head"` 解析為該 worktree 的 `HEAD`，而不是主簽出的。適用於 `--worktree`、`EnterWorktree` 工具和 subagent 隔離 | `"head"` |367| `worktree.baseRef` | 新 worktrees 分支的來源 ref。`"fresh"`（預設）從 `origin/<default-branch>` 分支以取得與遠端相符的乾淨樹。`"head"` 從您目前的本機 `HEAD` 分支，所以未推送的提交和功能分支狀態存在於 worktree 中。在連結的 worktree 內，`"head"` 解析為該 worktree 的 `HEAD`，而不是主簽出的。適用於 `--worktree`、`EnterWorktree` 工具和 subagent 隔離 | `"head"` |

369| `worktree.sparsePaths` | 要在每個 worktree 中透過 git sparse-checkout 簽出的目錄。僅將列出的目錄加上根層級檔案寫入磁碟，在大型 monorepos 中速度更快。當稀疏 worktree 存在時，git 在儲存庫的共享 `.git/config` 中啟用 `extensions.worktreeConfig`；請參閱[僅簽出您需要的目錄](/zh-TW/large-codebases#check-out-only-the-directories-you-need) | `["packages/my-app", "shared/utils"]` |369| `worktree.sparsePaths` | 要在每個 worktree 中透過 git sparse-checkout 簽出的目錄。僅將列出的目錄加上根層級檔案寫入磁碟，在大型 monorepos 中速度更快。當稀疏 worktree 存在時，git 在儲存庫的共享 `.git/config` 中啟用 `extensions.worktreeConfig`；請參閱[僅簽出您需要的目錄](/docs/zh-TW/large-codebases#check-out-only-the-directories-you-need) | `["packages/my-app", "shared/utils"]` |

370| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}[背景工作階段](/zh-TW/agent-view#how-file-edits-are-isolated)的隔離模式。`"worktree"`（預設）在呼叫 `EnterWorktree` 之前阻止主簽出中的 `Edit`/`Write`。{/* min-version: 2.1.203 */}在 git 儲存庫外，失敗的 [`WorktreeCreate` hook](/zh-TW/worktrees#non-git-version-control) 會釋放區塊，以便工作階段可以就地編輯工作目錄；需要 Claude Code v2.1.203 或更新版本。`"none"` 讓背景工作直接編輯工作副本。需要 Claude Code v2.1.143 或更新版本 | `"none"` |370| `worktree.bgIsolation` | [背景工作階段](/docs/zh-TW/agent-view#how-file-edits-are-isolated)的隔離模式。`"worktree"`（預設）在呼叫 `EnterWorktree` 之前阻止主簽出中的 `Edit`/`Write`。在 git 儲存庫外，失敗的 [`WorktreeCreate` hook](/docs/zh-TW/worktrees#non-git-version-control) 會釋放區塊，以便工作階段可以就地編輯工作目錄；需要 Claude Code v2.1.203 或更新版本。`"none"` 讓背景工作直接編輯工作副本。需要 Claude Code v2.1.143 或更新版本 | `"none"` |

371 371

372若要將 gitignored 檔案（如 `.env`）複製到新的 worktrees，請改用專案根目錄中的 [`.worktreeinclude` 檔案](/zh-TW/worktrees#copy-gitignored-files-into-worktrees)，而不是設定。372若要將 gitignored 檔案（如 `.env`）複製到新的 worktrees，請改用專案根目錄中的 [`.worktreeinclude` 檔案](/docs/zh-TW/worktrees#copy-gitignored-files-into-worktrees)，而不是設定。

373 373

374<h3 id="permission-settings">374<h3 id="permission-settings">

375 權限設定375 權限設定

376</h3>376</h3>

377 377

378| 金鑰 | 說明 | 範例 |378| 金鑰 | 說明 | 範例 |

379| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |379| :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

380| `allow` | 允許工具使用的權限規則陣列。工具名稱 globs 僅在字面 `mcp__<server>__` 前綴之後的工具位置支援，例如 `mcp__github__get_*`；server 段必須無 glob。請參閱下面的[權限規則語法](#permission-rule-syntax)以了解模式匹配詳細資訊 | `[ "Bash(git diff *)" ]` |380| `allow` | 允許工具使用的權限規則陣列。工具名稱 globs 僅在字面 `mcp__<server>__` 前綴之後的工具位置支援，例如 `mcp__github__get_*`；server 段必須無 glob。請參閱下面的[權限規則語法](#permission-rule-syntax)以了解模式匹配詳細資訊 | `[ "Bash(git diff *)" ]` |

381| `ask` | 要求在工具使用時確認的權限規則陣列。請參閱下面的[權限規則語法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |381| `ask` | 要求在工具使用時確認的權限規則陣列。請參閱下面的[權限規則語法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |

382| `deny` | 拒絕工具使用的權限規則陣列。使用此選項從 Claude Code 存取中排除敏感檔案。工具名稱接受 glob 模式：`"*"` 拒絕每個工具，`"mcp__*"` 拒絕所有 MCP 工具。請參閱[權限規則語法](#permission-rule-syntax)和 [Bash 權限限制](/zh-TW/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |382| `deny` | 拒絕工具使用的權限規則陣列。使用此選項從 Claude Code 存取中排除敏感檔案。工具名稱接受 glob 模式：`"*"` 拒絕每個工具，`"mcp__*"` 拒絕所有 MCP 工具。請參閱[權限規則語法](#permission-rule-syntax)和 [Bash 權限限制](/docs/zh-TW/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

383| `additionalDirectories` | Claude 有權存取的其他[工作目錄](/zh-TW/permissions#working-directories)。大多數 `.claude/` 設定[未從這些目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |383| `additionalDirectories` | Claude 有權存取的其他[工作目錄](/docs/zh-TW/permissions#working-directories)。大多數 `.claude/` 設定[未從這些目錄發現](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |

384| `defaultMode` | 開啟 Claude Code 時的預設[權限模式](/zh-TW/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 和 {/* min-version: 2.1.200 */}}`manual` 作為 `default` 的別名，CLI 和 VS Code 和 JetBrains 擴充功能中標記為 Manual 的模式。`manual` 別名需要 Claude Code v2.1.200 或更新版本。{/* min-version: 2.1.142 */}自 Claude Code v2.1.142 起，當在專案或本機設定（`.claude/settings.json`、`.claude/settings.local.json`）中設定時，`auto` 會被忽略，因此儲存庫無法授予自己自動模式。改為在 `~/.claude/settings.json` 中設定它。在 v2.1.142 之前，專案設定可以設定 `auto`。`--permission-mode` CLI 旗標會覆蓋此設定以進行單一工作階段 | `"acceptEdits"` |384| `defaultMode` | 開啟 Claude Code 時的預設[權限模式](/docs/zh-TW/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 和 }`manual` 作為 `default` 的別名，CLI 和 VS Code 和 JetBrains 擴充功能中標記為 Manual 的模式。`manual` 別名需要 Claude Code v2.1.200 或更新版本。自 Claude Code v2.1.142 起，當在專案或本機設定（`.claude/settings.json`、`.claude/settings.local.json`）中設定時，`auto` 會被忽略，因此儲存庫無法授予自己自動模式。改為在 `~/.claude/settings.json` 中設定它。在 v2.1.142 之前，專案設定可以設定 `auto`。`--permission-mode` CLI 旗標會覆蓋此設定以進行單一工作階段 | `"acceptEdits"` |

385| `disableBypassPermissionsMode` | 設定為 `"disable"` 以防止啟用 `bypassPermissions` 模式。這會停用 `--dangerously-skip-permissions` 旗標。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `"disable"` |385| `disableBypassPermissionsMode` | 設定為 `"disable"` 以防止啟用 `bypassPermissions` 模式。這會停用 `--dangerously-skip-permissions` 旗標。在[managed 設定](/docs/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `"disable"` |

386| `skipDangerousModePermissionPrompt` | 跳過透過 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 進入 bypass permissions 模式之前顯示的確認提示。在專案設定（`.claude/settings.json`）中設定時被忽略，以防止不受信任的儲存庫自動繞過提示 | `true` |386| `skipDangerousModePermissionPrompt` | 跳過透過 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 進入 bypass permissions 模式之前顯示的確認提示。在專案設定（`.claude/settings.json`）中設定時被忽略，以防止不受信任的儲存庫自動繞過提示 | `true` |

387 387

388<h3 id="permission-rule-syntax">388<h3 id="permission-rule-syntax">

389 權限規則語法389 權限規則語法

390</h3>390</h3>

391 391

392權限規則遵循 `Tool` 或 `Tool(specifier)` 的格式。規則按順序評估：首先是拒絕規則，然後是詢問，最後是允許。第一個匹配的規則決定結果，無論規則特異性如何。請參閱[權限規則評估順序](/zh-TW/permissions#manage-permissions)以了解詳細資訊。392權限規則遵循 `Tool` 或 `Tool(specifier)` 的格式。規則按順序評估：首先是拒絕規則，然後是詢問，最後是允許。第一個匹配的規則決定結果，無論規則特異性如何。請參閱[權限規則評估順序](/docs/zh-TW/permissions#manage-permissions)以了解詳細資訊。

393 393

394快速範例：394快速範例：

395 395

402 402

403如需完整的規則語法參考，包括萬用字元行為、Read、Edit、WebFetch、MCP 和 Agent 規則的工具特定模式，以及 Bash 模式的安全限制，請參閱[權限規則語法](/zh-TW/permissions#permission-rule-syntax)。403如需完整的規則語法參考，包括萬用字元行為、Read、Edit、WebFetch、MCP 和 Agent 規則的工具特定模式，以及 Bash 模式的安全限制，請參閱[權限規則語法](/docs/zh-TW/permissions#permission-rule-syntax)。

404 404

405<h3 id="sandbox-settings">405<h3 id="sandbox-settings">

406 Sandbox 設定406 Sandbox 設定

407</h3>407</h3>

408 408

409設定進階 sandboxing 行為。Sandboxing 將 bash 命令與您的檔案系統和網路隔離。請參閱 [Sandboxing](/zh-TW/sandboxing) 以了解詳細資訊。409設定進階 sandboxing 行為。Sandboxing 將 bash 命令與您的檔案系統和網路隔離。請參閱 [Sandboxing](/docs/zh-TW/sandboxing) 以了解詳細資訊。

410 410

411| 金鑰 | 說明 | 範例 |411| 金鑰 | 說明 | 範例 |

412| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |412| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |

414| `failIfUnavailable` | 如果 `sandbox.enabled` 為 true 但 sandbox 無法啟動（遺失相依性、不支援的平台），則在啟動時以錯誤結束。當為 false（預設）時，會顯示警告，命令會以 unsandboxed 方式執行。適用於需要 sandboxing 作為硬閘門的 managed 設定部署 | `true` |414| `failIfUnavailable` | 如果 `sandbox.enabled` 為 true 但 sandbox 無法啟動（遺失相依性、不支援的平台），則在啟動時以錯誤結束。當為 false（預設）時，會顯示警告，命令會以 unsandboxed 方式執行。適用於需要 sandboxing 作為硬閘門的 managed 設定部署 | `true` |

418| `filesystem.allowWrite` | sandboxed 命令可以寫入的其他路徑。陣列跨所有設定範圍合併：使用者、專案和 managed 路徑合併，不替換。也與 `Edit(...)` 允許權限規則中的路徑合併。請參閱下面的[路徑前綴](#sandbox-path-prefixes)。 | `["/tmp/build", "~/.kube"]` |418| `filesystem.allowWrite` | sandboxed 命令可以寫入的其他路徑。陣列跨所有設定範圍合併：使用者、專案和 managed 路徑合併，不替換。也與 `Edit(...)` 允許權限規則中的路徑合併。請參閱下面的[路徑前綴](#sandbox-path-prefixes)。 | `["/tmp/build", "~/.kube"]` |

421| `filesystem.allowRead` | 在 `denyRead` 區域內重新允許讀取的路徑。`allowRead` 路徑在更廣泛的 `denyRead` 區域內重新開啟讀取，`denyRead` 中的精確路徑在更廣泛的 `allowRead` 內保持被阻止；請參閱[重疊表](/zh-TW/sandboxing#configure-sandboxing)以了解範例。陣列跨所有設定範圍合併。使用此選項建立僅工作區讀取存取模式。 | `["."]` |421| `filesystem.allowRead` | 在 `denyRead` 區域內重新允許讀取的路徑。`allowRead` 路徑在更廣泛的 `denyRead` 區域內重新開啟讀取，`denyRead` 中的精確路徑在更廣泛的 `allowRead` 內保持被阻止；請參閱[重疊表](/docs/zh-TW/sandboxing#configure-sandboxing)以了解範例。陣列跨所有設定範圍合併。使用此選項建立僅工作區讀取存取模式。 | `["."]` |

423| `credentials.files` | {/* min-version: 2.1.187 */}Sandboxed 命令無法讀取的認證檔案或目錄。應用與 `filesystem.denyRead` 相同的讀取區塊；單獨的金鑰將認證路徑與 `credentials.envVars` 分組，並與一般檔案系統規則分開。每個項目為 `{ "path": "...", "mode": "deny" }`，僅支援 `deny`。路徑使用與 `filesystem.*` 設定相同的[前綴](#sandbox-path-prefixes)。陣列跨所有設定範圍合併。需要 Claude Code v2.1.187 或更新版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |423| `credentials.files` | Sandboxed 命令無法讀取的認證檔案或目錄。應用與 `filesystem.denyRead` 相同的讀取區塊；單獨的金鑰將認證路徑與 `credentials.envVars` 分組，並與一般檔案系統規則分開。每個項目為 `{ "path": "...", "mode": "deny" }`，僅支援 `deny`。路徑使用與 `filesystem.*` 設定相同的[前綴](#sandbox-path-prefixes)。陣列跨所有設定範圍合併。需要 Claude Code v2.1.187 或更新版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |

424| `credentials.envVars` | {/* min-version: 2.1.187 */}環境變數以[保護免受 sandboxed 命令](/zh-TW/sandboxing#protect-credentials)。每個項目有一個 `name` 和一個 `mode`；名稱必須以字母或底線開頭，並僅包含字母、數字和底線。`deny` 從 sandboxed 命令的環境中移除變數。需要 Claude Code v2.1.187 或更新版本。{/* min-version: 2.1.199 */}}`mask` 在 sandbox 內用每個工作階段的 sentinel 值替換變數，而 sandbox 代理在該項目的 `injectHosts` 的出站請求上替換真實值；它需要 `network.tlsTerminate` 和 Claude Code v2.1.199 或更新版本。`mask` 項目僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。陣列跨所有設定範圍合併，當相同變數同時出現兩種模式時 `deny` 優先。 | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |424| `credentials.envVars` | 環境變數以[保護免受 sandboxed 命令](/docs/zh-TW/sandboxing#protect-credentials)。每個項目有一個 `name` 和一個 `mode`；名稱必須以字母或底線開頭，並僅包含字母、數字和底線。`deny` 從 sandboxed 命令的環境中移除變數。需要 Claude Code v2.1.187 或更新版本。}`mask` 在 sandbox 內用每個工作階段的 sentinel 值替換變數，而 sandbox 代理在該項目的 `injectHosts` 的出站請求上替換真實值；它需要 `network.tlsTerminate` 和 Claude Code v2.1.199 或更新版本。`mask` 項目僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。陣列跨所有設定範圍合併，當相同變數同時出現兩種模式時 `deny` 優先。 | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |

425| `credentials.envVars[].injectHosts` | Sandbox 代理替換 `mask` 項目真實值的主機。每個主機也必須由 `network.allowedDomains` 涵蓋，無論是精確還是通過萬用字元。未設定時，代理在 `network.allowedDomains` 中的每個主機上替換值。當 `mode` 為 `deny` 時被接受但忽略。需要 Claude Code v2.1.199 或更新版本。{/* min-version: 2.1.199 */}} | `["api.github.com"]` |425| `credentials.envVars[].injectHosts` | Sandbox 代理替換 `mask` 項目真實值的主機。每個主機也必須由 `network.allowedDomains` 涵蓋，無論是精確還是通過萬用字元。未設定時，代理在 `network.allowedDomains` 中的每個主機上替換值。當 `mode` 為 `deny` 時被接受但忽略。需要 Claude Code v2.1.199 或更新版本。} | `["api.github.com"]` |

426| `credentials.allowPlaintextInject` | 允許 `mask` 替換在純 HTTP 請求以及 TLS 終止的 HTTPS 上。在純 HTTP 上，上游身份未驗證，認證以明文形式傳輸，因此在受信任的測試網路外保持此設定關閉。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。預設：false。需要 Claude Code v2.1.199 或更新版本。{/* min-version: 2.1.199 */}} | `true` |426| `credentials.allowPlaintextInject` | 允許 `mask` 替換在純 HTTP 請求以及 TLS 終止的 HTTPS 上。在純 HTTP 上，上游身份未驗證，認證以明文形式傳輸，因此在受信任的測試網路外保持此設定關閉。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。預設：false。需要 Claude Code v2.1.199 或更新版本。} | `true` |

427| `network.allowUnixSockets` | （macOS 僅限）sandbox 中可存取的 Unix socket 路徑。在 Linux 和 WSL2 上被忽略，其中 seccomp 篩選器無法檢查 socket 路徑；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |427| `network.allowUnixSockets` | （macOS 僅限）sandbox 中可存取的 Unix socket 路徑。在 Linux 和 WSL2 上被忽略，其中 seccomp 篩選器無法檢查 socket 路徑；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |

428| `network.allowAllUnixSockets` | 允許 sandbox 中的所有 Unix socket 連線。在 Linux 和 WSL2 上，這是允許 Unix sockets 的唯一方式，因為它跳過了 seccomp 篩選器，否則會阻止 `socket(AF_UNIX, ...)` 呼叫。預設：false | `true` |428| `network.allowAllUnixSockets` | 允許 sandbox 中的所有 Unix socket 連線。在 Linux 和 WSL2 上，這是允許 Unix sockets 的唯一方式，因為它跳過了 seccomp 篩選器，否則會阻止 `socket(AF_UNIX, ...)` 呼叫。預設：false | `true` |

433| `network.allowManagedDomainsOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則。來自使用者、專案和本機設定的網域會被忽略。非允許的網域會自動阻止，不會提示使用者。拒絕的網域仍從所有來源受尊重。預設：false | `true` |433| `network.allowManagedDomainsOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則。來自使用者、專案和本機設定的網域會被忽略。非允許的網域會自動阻止，不會提示使用者。拒絕的網域仍從所有來源受尊重。預設：false | `true` |

434| `network.httpProxyPort` | 如果您想帶上自己的代理，使用的 HTTP 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8080` |434| `network.httpProxyPort` | 如果您想帶上自己的代理，使用的 HTTP 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8080` |

435| `network.socksProxyPort` | 如果您想帶上自己的代理，使用的 SOCKS5 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8081` |435| `network.socksProxyPort` | 如果您想帶上自己的代理，使用的 SOCKS5 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8081` |

436| `network.tlsTerminate` | 實驗性。在 sandbox 代理內終止 TLS，以便它可以讀取 HTTPS 請求的內容。[credential substitution](/zh-TW/sandboxing#protect-credentials) 的 `mask` 需要。設定 `{}` 以為工作階段產生臨時憑證授權單位，或設定 `caCertPath` 和 `caKeyPath` 以使用您自己的。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。需要 Claude Code v2.1.199 或更新版本。{/* min-version: 2.1.199 */}} | `{}` |436| `network.tlsTerminate` | 實驗性。在 sandbox 代理內終止 TLS，以便它可以讀取 HTTPS 請求的內容。[credential substitution](/docs/zh-TW/sandboxing#protect-credentials) 的 `mask` 需要。設定 `{}` 以為工作階段產生臨時憑證授權單位，或設定 `caCertPath` 和 `caKeyPath` 以使用您自己的。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。需要 Claude Code v2.1.199 或更新版本。} | `{}` |

438| `enableWeakerNetworkIsolation` | （macOS 僅限）允許在 sandbox 中存取系統 TLS 信任服務（`com.apple.trustd.agent`）。使用 `httpProxyPort` 和自訂 CA 的 MITM 代理時，Go 型工具（如 `gh`、`gcloud` 和 `terraform`）需要驗證 TLS 憑證。**透過開啟潛在的資料外洩路徑降低安全性**。預設：false | `true` |438| `enableWeakerNetworkIsolation` | （macOS 僅限）允許在 sandbox 中存取系統 TLS 信任服務（`com.apple.trustd.agent`）。使用 `httpProxyPort` 和自訂 CA 的 MITM 代理時，Go 型工具（如 `gh`、`gcloud` 和 `terraform`）需要驗證 TLS 憑證。**透過開啟潛在的資料外洩路徑降低安全性**。預設：false | `true` |

439| `allowAppleEvents` | （macOS 僅限）允許 sandboxed 命令傳送 Apple Events。`open`、`osascript` 和在瀏覽器中開啟 URL 的工具需要，否則會失敗並出現錯誤 `-600`。**移除程式碼執行隔離。** Sandboxed 命令可以啟動其他應用程式 unsandboxed，無需使用者提示；它們也可以傳送 AppleScript 命令到執行中的應用程式（例如終端機），受限於每個應用程式的 macOS 自動化同意提示 (TCC)。僅從使用者、managed 或 CLI 設定受尊重，不從專案設定。預設：false | `true` |439| `allowAppleEvents` | （macOS 僅限）允許 sandboxed 命令傳送 Apple Events。`open`、`osascript` 和在瀏覽器中開啟 URL 的工具需要，否則會失敗並出現錯誤 `-600`。**移除程式碼執行隔離。** Sandboxed 命令可以啟動其他應用程式 unsandboxed，無需使用者提示；它們也可以傳送 AppleScript 命令到執行中的應用程式（例如終端機），受限於每個應用程式的 macOS 自動化同意提示 (TCC)。僅從使用者、managed 或 CLI 設定受尊重，不從專案設定。預設：false | `true` |

440| `bwrapPath` | （Managed 設定僅限，Linux/WSL2）bubblewrap (`bwrap`) 二進位檔的絕對路徑。覆蓋透過 `PATH` 的自動偵測。僅從 [managed 設定](/zh-TW/settings#settings-files)受尊重，不從使用者或專案設定。在 managed 環境中 `bwrap` 安裝在非標準位置時很有用。 | `/opt/admin/bwrap` |440| `bwrapPath` | （Managed 設定僅限，Linux/WSL2）bubblewrap (`bwrap`) 二進位檔的絕對路徑。覆蓋透過 `PATH` 的自動偵測。僅從 [managed 設定](/docs/zh-TW/settings#settings-files)受尊重，不從使用者或專案設定。在 managed 環境中 `bwrap` 安裝在非標準位置時很有用。 | `/opt/admin/bwrap` |

442 442

443<h4 id="sandbox-path-prefixes">443<h4 id="sandbox-path-prefixes">

452| `~/` | 相對於主目錄 | `~/.kube` 變成 `$HOME/.kube` |452| `~/` | 相對於主目錄 | `~/.kube` 變成 `$HOME/.kube` |

454 454

455較舊的 `//path` 前綴用於絕對路徑仍然有效。如果您之前使用單斜線 `/path` 期望專案相對解析，請切換到 `./path`。此語法與[讀取和編輯權限規則](/zh-TW/permissions#read-and-edit)不同，後者使用 `//path` 用於絕對和 `/path` 用於專案相對。Sandbox 檔案系統路徑使用標準慣例：`/tmp/build` 是絕對路徑。455較舊的 `//path` 前綴用於絕對路徑仍然有效。如果您之前使用單斜線 `/path` 期望專案相對解析，請切換到 `./path`。此語法與[讀取和編輯權限規則](/docs/zh-TW/permissions#read-and-edit)不同，後者使用 `//path` 用於絕對和 `/path` 用於專案相對。Sandbox 檔案系統路徑使用標準慣例：`/tmp/build` 是絕對路徑。

456 456

457**設定範例：**457**設定範例：**

458 458

542}542}

543```543```

544 544

545該命令使用與 [hooks](/zh-TW/hooks) 相同的環境變數執行，包括 `CLAUDE_PROJECT_DIR`。它透過 stdin 接收包含 `query` 欄位的 JSON：545該命令使用與 [hooks](/docs/zh-TW/hooks) 相同的環境變數執行，包括 `CLAUDE_PROJECT_DIR`。它透過 stdin 接收包含 `query` 欄位的 JSON：

546 546

547```json theme={null}547```json theme={null}

548{"query": "src/comp"}548{"query": "src/comp"}

603 603

604輪次完成時，Claude Code 在主執行緒上將每個項目的 `pattern` regex 與輪次輸出相符，因此緩慢的 regex 會阻止 UI，直到完成。嵌套量詞（例如 `(a+)+$`）可能針對某些輸入花費指數級長時間並凍結工作階段，因此保持每個 `pattern` 線性並避免嵌套 `+` 或 `*`。604輪次完成時，Claude Code 在主執行緒上將每個項目的 `pattern` regex 與輪次輸出相符，因此緩慢的 regex 會阻止 UI，直到完成。嵌套量詞（例如 `(a+)+$`）可能針對某些輸入花費指數級長時間並凍結工作階段，因此保持每個 `pattern` 線性並避免嵌套 `+` 或 `*`。

605 605

606頁尾徽章與[自訂狀態行](/zh-TW/statusline)並排渲染（當設定一個時）；兩者都不替換另一個。使用狀態行用於從工作階段資料計算自己內容的指令碼驅動列，使用頁尾徽章將對話中的 ID 轉換為連結，而無需指令碼。606頁尾徽章與[自訂狀態行](/docs/zh-TW/statusline)並排渲染（當設定一個時）；兩者都不替換另一個。使用狀態行用於從工作階段資料計算自己內容的指令碼驅動列，使用頁尾徽章將對話中的 ID 轉換為連結，而無需指令碼。

607 607

608<h3 id="hook-configuration">608<h3 id="hook-configuration">

609 Hook 設定609 Hook 設定

641 使用政策協助程式計算 managed 設定641 使用政策協助程式計算 managed 設定

642</h3>642</h3>

643 643

644`policyHelper` 設定指向在啟動時計算 managed 設定的可執行檔，因此管理員可以從裝置狀態、身份或遠端服務衍生政策，而不是靜態檔案。從 MDM 或系統 `managed-settings.json` 檔案設定它。Claude Code 在任何其他範圍中出現 `policyHelper` 時會忽略它，包括使用者設定、專案設定、HKCU 登錄 hive 和[伺服器管理的設定](/zh-TW/server-managed-settings)。644`policyHelper` 設定指向在啟動時計算 managed 設定的可執行檔，因此管理員可以從裝置狀態、身份或遠端服務衍生政策，而不是靜態檔案。從 MDM 或系統 `managed-settings.json` 檔案設定它。Claude Code 在任何其他範圍中出現 `policyHelper` 時會忽略它，包括使用者設定、專案設定、HKCU 登錄 hive 和[伺服器管理的設定](/docs/zh-TW/server-managed-settings)。

645 645

646該設定接受這些金鑰：646該設定接受這些金鑰：

647 647

671 671

672設定按優先順序順序應用。從最高到最低：672設定按優先順序順序應用。從最高到最低：

673 673

6741. **Managed 設定**（[伺服器管理](/zh-TW/server-managed-settings)、[MDM/OS 層級政策](#configuration-scopes)或 [managed 設定](#settings-files)）6741. **Managed 設定**（[伺服器管理](/docs/zh-TW/server-managed-settings)、[MDM/OS 層級政策](#configuration-scopes)或 [managed 設定](#settings-files)）

675 * 由 IT 透過伺服器傳遞、MDM 設定檔案、登錄政策或 managed 設定檔案部署的政策675 * 由 IT 透過伺服器傳遞、MDM 設定檔案、登錄政策或 managed 設定檔案部署的政策

676 * 無法被任何其他層級覆蓋，包括命令列引數676 * 無法被任何其他層級覆蓋，包括命令列引數

677 * 在 managed 層級內，僅使用一個 managed 來源，其他來源被忽略而不是合併。優先順序，最高優先：677 * 在 managed 層級內，僅使用一個 managed 來源，其他來源被忽略而不是合併。優先順序，最高優先：

678 * [`policyHelper`](#compute-managed-settings-with-a-policy-helper) 輸出：當設定時，這是唯一使用的 managed 來源678 * [`policyHelper`](#compute-managed-settings-with-a-policy-helper) 輸出：當設定時，這是唯一使用的 managed 來源

679 * 遠端（claude.ai [伺服器管理](/zh-TW/server-managed-settings)或 [Claude apps gateway](/zh-TW/claude-apps-gateway)傳遞）679 * 遠端（claude.ai [伺服器管理](/docs/zh-TW/server-managed-settings)或 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway)傳遞）

680 * MDM/OS 層級政策680 * MDM/OS 層級政策

681 * 檔案型（`managed-settings.d/*.json` 和 `managed-settings.json`，合併在一起）681 * 檔案型（`managed-settings.d/*.json` 和 `managed-settings.json`，合併在一起）

682 * HKCU 登錄（僅限 Windows）682 * HKCU 登錄（僅限 Windows）

684 * sandbox 鎖定金鑰 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`，以及其相關聯的白名單684 * sandbox 鎖定金鑰 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`，以及其相關聯的白名單

685 * `allowAllClaudeAiMcps`685 * `allowAllClaudeAiMcps`

686 * sandbox 二進位路徑 `sandbox.bwrapPath` 和 `sandbox.socatPath`686 * sandbox 二進位路徑 `sandbox.bwrapPath` 和 `sandbox.socatPath`

687 * [`forceRemoteSettingsRefresh`](/zh-TW/server-managed-settings)687 * [`forceRemoteSettingsRefresh`](/docs/zh-TW/server-managed-settings)

688 * 嵌入主機（例如 Claude Desktop）可以透過 SDK `managedSettings` 選項提供政策。預設情況下，當任何 admin 部署的 managed 來源存在時，此會被忽略：伺服器管理的設定、MDM 或 OS 層級政策，或 managed 設定檔案。使用者可寫的 HKCU 登錄回退不計為 admin 部署的來源。管理員可以透過設定 [`parentSettingsBehavior`](#available-settings) 為 `"merge"` 來選擇加入。嵌入器的值會被篩選，以便它們可以收緊 managed 政策但不能放鬆政策。688 * 嵌入主機（例如 Claude Desktop）可以透過 SDK `managedSettings` 選項提供政策。預設情況下，當任何 admin 部署的 managed 來源存在時，此會被忽略：伺服器管理的設定、MDM 或 OS 層級政策，或 managed 設定檔案。使用者可寫的 HKCU 登錄回退不計為 admin 部署的來源。管理員可以透過設定 [`parentSettingsBehavior`](#available-settings) 為 `"merge"` 來選擇加入。嵌入器的值會被篩選，以便它們可以收緊 managed 政策但不能放鬆政策。

689 689

6902. **命令列引數**6902. **命令列引數**

6995. **使用者設定**（`~/.claude/settings.json`）6995. **使用者設定**（`~/.claude/settings.json`）

700 * 個人全域設定700 * 個人全域設定

701 701

702此階層確保組織政策始終被強制執行，同時仍允許團隊和個人自訂其體驗。無論您從 CLI、[VS Code 擴充功能](/zh-TW/vs-code)或 [JetBrains IDE](/zh-TW/jetbrains) 執行 Claude Code，相同的優先順序都適用。702此階層確保組織政策始終被強制執行，同時仍允許團隊和個人自訂其體驗。無論您從 CLI、[VS Code 擴充功能](/docs/zh-TW/vs-code)或 [JetBrains IDE](/docs/zh-TW/jetbrains) 執行 Claude Code，相同的優先順序都適用。

703 703

704例如，如果您的使用者設定將 `permissions.defaultMode` 設定為 `acceptEdits`，而專案的共享設定將其設定為 `default`，則專案值適用。下面的範例涵蓋陣列值設定（如權限規則）如何組合的方式。704例如，如果您的使用者設定將 `permissions.defaultMode` 設定為 `acceptEdits`，而專案的共享設定將其設定為 `default`，則專案值適用。下面的範例涵蓋陣列值設定（如權限規則）如何組合的方式。

705 705

709 兩個陣列設定不以此方式合併：709 兩個陣列設定不以此方式合併：

710 710

711 * [`fallbackModel`](#available-settings) 是一個有序鏈，其中位置具有意義：定義它的最高優先順序檔案提供整個值。711 * [`fallbackModel`](#available-settings) 是一個有序鏈，其中位置具有意義：定義它的最高優先順序檔案提供整個值。

712 * [`availableModels`](#available-settings)：{/* min-version: 2.1.175 */}當[最高優先順序 managed 來源](/zh-TW/server-managed-settings#settings-precedence)定義它時，該清單按原樣應用，使用者、專案和本機項目無法擴展它。跨非 managed 範圍，陣列會照常合併。請參閱[合併行為](/zh-TW/model-config#merge-behavior)。712 * [`availableModels`](#available-settings)：當[最高優先順序 managed 來源](/docs/zh-TW/server-managed-settings#settings-precedence)定義它時，該清單按原樣應用，使用者、專案和本機項目無法擴展它。跨非 managed 範圍，陣列會照常合併。請參閱[合併行為](/docs/zh-TW/model-config#merge-behavior)。

713</Note>713</Note>

714 714

715<h3 id="verify-active-settings">715<h3 id="verify-active-settings">

716 驗證使用中的設定716 驗證使用中的設定

717</h3>717</h3>

718 718

719在 Claude Code 內執行 `/status` 以查看哪些設定來源是使用中的。在功能表內，**Status** 標籤包含 `Setting sources` 行，列出 Claude Code 為目前工作階段載入的每一層，例如 `User settings` 或 `Project local settings`。當[managed 設定](/zh-TW/admin-setup#decide-how-settings-reach-devices)生效時，項目會在括號中顯示傳遞頻道，例如 `Enterprise managed settings (remote)`、`(plist)`、`(HKLM)`、`(HKCU)` 或 `(file)`。`remote` 頻道涵蓋 claude.ai 伺服器管理的設定和 [Claude apps gateway](/zh-TW/claude-apps-gateway)傳遞的政策。層級僅在該來源以至少一個金鑰載入時才出現在清單中，因此空清單表示未找到任何設定來源。719在 Claude Code 內執行 `/status` 以查看哪些設定來源是使用中的。在功能表內，**Status** 標籤包含 `Setting sources` 行，列出 Claude Code 為目前工作階段載入的每一層，例如 `User settings` 或 `Project local settings`。當[managed 設定](/docs/zh-TW/admin-setup#decide-how-settings-reach-devices)生效時，項目會在括號中顯示傳遞頻道，例如 `Enterprise managed settings (remote)`、`(plist)`、`(HKLM)`、`(HKCU)` 或 `(file)`。`remote` 頻道涵蓋 claude.ai 伺服器管理的設定和 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway)傳遞的政策。層級僅在該來源以至少一個金鑰載入時才出現在清單中，因此空清單表示未找到任何設定來源。

720 720

721`Setting sources` 行確認正在讀取哪些來源。它不顯示哪一層提供了每個個別金鑰。同一對話框中的 **Config** 標籤是固定切換集（例如主題和詳細輸出）的編輯器，而不是您 `settings.json` 內容的檢視。721`Setting sources` 行確認正在讀取哪些來源。它不顯示哪一層提供了每個個別金鑰。同一對話框中的 **Config** 標籤是固定切換集（例如主題和詳細輸出）的編輯器，而不是您 `settings.json` 內容的檢視。

722 722

770* **使用者 subagents**：`~/.claude/agents/`，在所有專案中可用770* **使用者 subagents**：`~/.claude/agents/`，在所有專案中可用

771* **專案 subagents**：`.claude/agents/`，特定於您的專案，可與您的團隊共享771* **專案 subagents**：`.claude/agents/`，特定於您的專案，可與您的團隊共享

772 772

773Subagent 檔案定義具有自訂提示和工具權限的專門 AI 助手。在 [subagents 文件](/zh-TW/sub-agents)中深入了解建立和使用 subagents。773Subagent 檔案定義具有自訂提示和工具權限的專門 AI 助手。在 [subagents 文件](/docs/zh-TW/sub-agents)中深入了解建立和使用 subagents。

774 774

775<h2 id="plugin-configuration">775<h2 id="plugin-configuration">

776 Plugin 配置776 Plugin 配置

806 `enabledPlugins`806 `enabledPlugins`

807</h4>807</h4>

808 808

809控制啟用哪些 plugins。格式：`"plugin-name@marketplace-name": true/false`。沒有在任何範圍中有項目的 plugin 會回退到其 [`defaultEnabled`](/zh-TW/plugins-reference#default-enablement) 值。809控制啟用哪些 plugins。格式：`"plugin-name@marketplace-name": true/false`。沒有在任何範圍中有項目的 plugin 會回退到其 [`defaultEnabled`](/docs/zh-TW/plugins-reference#default-enablement) 值。

810 810

811**範圍**：811**範圍**：

812 812

820 820

821 由 managed 設定強制啟用的 plugins 無法以此方式停用，因為 managed 設定會覆蓋本機設定。821 由 managed 設定強制啟用的 plugins 無法以此方式停用，因為 managed 設定會覆蓋本機設定。

822 822

823 自 Claude Code v2.1.195 起，在專案的 `.claude/settings.json` 中啟用來自外部來源（例如 GitHub 儲存庫或 npm 套件）的 plugin 不會為其他人安裝它。每個載入 plugins 的路徑都會要求每個使用者在執行前[安裝並信任 plugin](/zh-TW/discover-plugins#configure-team-marketplaces)。823 自 Claude Code v2.1.195 起，在專案的 `.claude/settings.json` 中啟用來自外部來源（例如 GitHub 儲存庫或 npm 套件）的 plugin 不會為其他人安裝它。每個載入 plugins 的路徑都會要求每個使用者在執行前[安裝並信任 plugin](/docs/zh-TW/discover-plugins#configure-team-marketplaces)。

824</Note>824</Note>

825 825

826**範例**：826**範例**：

839 `pluginConfigs`839 `pluginConfigs`

840</h4>840</h4>

841 841

842儲存 plugin 的 [`userConfig`](/zh-TW/plugins-reference#user-configuration) 提示收集的非敏感選項值，按 plugin ID 鍵入。Claude Code 在您填入 plugin 的設定對話框時會將此鍵寫入使用者設定，因此您無需手動編輯它。敏感選項改為儲存在 macOS Keychain 中，或在沒有支援 keychain 的平台上儲存在 `~/.claude/.credentials.json` 中。842儲存 plugin 的 [`userConfig`](/docs/zh-TW/plugins-reference#user-configuration) 提示收集的非敏感選項值，按 plugin ID 鍵入。Claude Code 在您填入 plugin 的設定對話框時會將此鍵寫入使用者設定，因此您無需手動編輯它。敏感選項改為儲存在 macOS Keychain 中，或在沒有支援 keychain 的平台上儲存在 `~/.claude/.credentials.json` 中。

843 843

844此範例儲存從 `acme-tools` marketplace 安裝的 plugin 的一個選項：844此範例儲存從 `acme-tools` marketplace 安裝的 plugin 的一個選項：

845 845

899* `hostPattern`：正規表達式模式以符合 marketplace 主機（使用 `hostPattern`）899* `hostPattern`：正規表達式模式以符合 marketplace 主機（使用 `hostPattern`）

900* `settings`：直接在 settings.json 中宣告的內嵌 marketplace，無需單獨的託管儲存庫（使用 `name` 和 `plugins`）900* `settings`：直接在 settings.json 中宣告的內嵌 marketplace，無需單獨的託管儲存庫（使用 `name` 和 `plugins`）

901 901

902`git` 來源類型適用於任何 git 託管服務，包括自託管 GitLab 和 Bitbucket。Claude Code 使用與該機器上 `git clone` 相同的驗證來複製儲存庫：已設定的認證助手或 SSH 金鑰。提供者 token（例如 `GITHUB_TOKEN`）只有透過讀取它的認證助手才會生效。請參閱[私有儲存庫](/zh-TW/plugin-marketplaces#private-repositories)以了解設定詳細資訊。902`git` 來源類型適用於任何 git 託管服務，包括自託管 GitLab 和 Bitbucket。Claude Code 使用與該機器上 `git clone` 相同的驗證來複製儲存庫：已設定的認證助手或 SSH 金鑰。提供者 token（例如 `GITHUB_TOKEN`）只有透過讀取它的認證助手才會生效。請參閱[私有儲存庫](/docs/zh-TW/plugin-marketplaces#private-repositories)以了解設定詳細資訊。

903 903

904對於 `github` 和 `git` 來源，在 `source` 物件內設定 `"skipLfs": true`（與 `repo` 或 `url` 並列）以在 Claude Code 複製或更新 marketplace 儲存庫時跳過 Git LFS 下載。LFS 指標檔案保持為指標而不是下載其內容。當儲存庫包含與 plugin 內容無關的大型 LFS 物件時，請使用此選項。{/* min-version: 2.1.153 */}需要 Claude Code v2.1.153 或更新版本。904對於 `github` 和 `git` 來源，在 `source` 物件內設定 `"skipLfs": true`（與 `repo` 或 `url` 並列）以在 Claude Code 複製或更新 marketplace 儲存庫時跳過 Git LFS 下載。LFS 指標檔案保持為指標而不是下載其內容。當儲存庫包含與 plugin 內容無關的大型 LFS 物件時，請使用此選項。需要 Claude Code v2.1.153 或更新版本。

905 905

906每個 marketplace 項目也接受選用的 `autoUpdate` 布林值。在 `source` 旁邊設定 `"autoUpdate": true`，使 Claude Code 在啟動時重新整理該 marketplace 並更新其已安裝的 plugins。省略時，官方 Anthropic marketplaces 預設為 `true`，所有其他 marketplaces 預設為 `false`。請參閱[設定自動更新](/zh-TW/discover-plugins#configure-auto-updates)。906每個 marketplace 項目也接受選用的 `autoUpdate` 布林值。在 `source` 旁邊設定 `"autoUpdate": true`，使 Claude Code 在啟動時重新整理該 marketplace 並更新其已安裝的 plugins。省略時，官方 Anthropic marketplaces 預設為 `true`，所有其他 marketplaces 預設為 `false`。請參閱[設定自動更新](/docs/zh-TW/discover-plugins#configure-auto-updates)。

907 907

908使用 `source: 'settings'` 宣告一小組 plugins，無需設定託管 marketplace 儲存庫。此處列出的 Plugins 必須參考外部來源，例如 GitHub 或 npm。您仍需要在 `enabledPlugins` 中分別啟用每個 plugin。908使用 `source: 'settings'` 宣告一小組 plugins，無需設定託管 marketplace 儲存庫。此處列出的 Plugins 必須參考外部來源，例如 GitHub 或 npm。您仍需要在 `enabledPlugins` 中分別啟用每個 plugin。

909 909

933 `strictKnownMarketplaces`933 `strictKnownMarketplaces`

934</h4>934</h4>

935 935

936**Managed 設定僅限**：控制使用者可以新增和安裝 plugins 的 plugin marketplaces。此設定只能在 [managed 設定](/zh-TW/settings#settings-files)中設定，並為管理員提供對 marketplace 來源的嚴格控制。936**Managed 設定僅限**：控制使用者可以新增和安裝 plugins 的 plugin marketplaces。此設定只能在 [managed 設定](/docs/zh-TW/settings#settings-files)中設定，並為管理員提供對 marketplace 來源的嚴格控制。

937 937

938**Managed 設定檔案位置**：938**Managed 設定檔案位置**：

939 939

988欄位：`url`（必需）、`headers`（選用：用於驗證存取的 HTTP 標頭）988欄位：`url`（必需）、`headers`（選用：用於驗證存取的 HTTP 標頭）

989 989

990<Note>990<Note>

991 基於 URL 的 marketplaces 僅下載 `marketplace.json` 檔案。它們不從伺服器下載 plugin 檔案。基於 URL 的 marketplaces 中的 Plugins 必須使用外部來源（GitHub、npm 或 git URL），而不是相對路徑。對於具有相對路徑的 plugins，請改用基於 Git 的 marketplace。請參閱[疑難排解](/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)以了解詳細資訊。991 基於 URL 的 marketplaces 僅下載 `marketplace.json` 檔案。它們不從伺服器下載 plugin 檔案。基於 URL 的 marketplaces 中的 Plugins 必須使用外部來源（GitHub、npm 或 git URL），而不是相對路徑。對於具有相對路徑的 plugins，請改用基於 Git 的 marketplace。請參閱[疑難排解](/docs/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)以了解詳細資訊。

992</Note>992</Note>

993 993

9944. **NPM 套件**：9944. **NPM 套件**：

1178* 限制在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行。在設定政策之前新增的 marketplace 一旦其來源不再符合白名單，就無法用於安裝或更新 plugins1178* 限制在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行。在設定政策之前新增的 marketplace 一旦其來源不再符合白名單，就無法用於安裝或更新 plugins

1179* Managed 設定具有最高優先順序，無法被覆蓋1179* Managed 設定具有最高優先順序，無法被覆蓋

1180 1180

1181請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)以了解面向使用者的文件。1181請參閱 [Managed marketplace 限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)以了解面向使用者的文件。

1182 1182

1183<h4 id="strictpluginonlycustomization">1183<h4 id="strictpluginonlycustomization">

1184 `strictPluginOnlyCustomization`1184 `strictPluginOnlyCustomization`

1204| `mcp` | `~/.claude.json` 和 `.mcp.json` 中的 Servers | Plugin MCP servers、[`managed-mcp.json`](/zh-TW/managed-mcp) servers |1204| `mcp` | `~/.claude.json` 和 `.mcp.json` 中的 Servers | Plugin MCP servers、[`managed-mcp.json`](/docs/zh-TW/managed-mcp) servers |

1205 1205

1206Claude Code 版本不識別的表面名稱會被忽略而不是導致設定檔案失敗，因此您可以在所有用戶端更新之前新增新的表面名稱。1206Claude Code 版本不識別的表面名稱會被忽略而不是導致設定檔案失敗，因此您可以在所有用戶端更新之前新增新的表面名稱。

1207 1207

1217* 檢視 plugin 詳細資訊（提供的 skills、agents、hooks）1217* 檢視 plugin 詳細資訊（提供的 skills、agents、hooks）

1218* 新增/移除 marketplaces1218* 新增/移除 marketplaces

1219 1219

1220在 [plugins 文件](/zh-TW/plugins)中深入了解 plugin 系統。1220在 [plugins 文件](/docs/zh-TW/plugins)中深入了解 plugin 系統。

1221 1221

1222<h2 id="environment-variables">1222<h2 id="environment-variables">

1223 環境變數1223 環境變數

1225 1225

1226環境變數可讓您控制 Claude Code 行為，而無需編輯設定檔案。任何變數也可以在 [`settings.json`](#available-settings) 中的 `env` 金鑰下設定，以將其應用於每個工作階段或推出到您的團隊。1226環境變數可讓您控制 Claude Code 行為，而無需編輯設定檔案。任何變數也可以在 [`settings.json`](#available-settings) 中的 `env` 金鑰下設定，以將其應用於每個工作階段或推出到您的團隊。

1227 1227

1228請參閱[環境變數參考](/zh-TW/env-vars)以了解完整清單。1228請參閱[環境變數參考](/docs/zh-TW/env-vars)以了解完整清單。

1229 1229

1230<h2 id="tools-available-to-claude">1230<h2 id="tools-available-to-claude">

1231 Claude 可用的工具1231 Claude 可用的工具

1233 1233

1234Claude Code 可以存取一組工具，用於讀取、編輯、搜尋、執行命令和協調 subagents。工具名稱是您在權限規則和 hook 匹配器中使用的確切字串。1234Claude Code 可以存取一組工具，用於讀取、編輯、搜尋、執行命令和協調 subagents。工具名稱是您在權限規則和 hook 匹配器中使用的確切字串。

1235 1235

1236請參閱[工具參考](/zh-TW/tools-reference)以了解完整清單和 Bash 工具行為詳細資訊。1236請參閱[工具參考](/docs/zh-TW/tools-reference)以了解完整清單和 Bash 工具行為詳細資訊。

1237 1237

1238<h2 id="see-also">1238<h2 id="see-also">

1239 另請參閱1239 另請參閱

1240</h2>1240</h2>

1241 1241

1242* [Permissions](/zh-TW/permissions)：權限系統、規則語法、工具特定模式和 managed 政策1242* [Permissions](/docs/zh-TW/permissions)：權限系統、規則語法、工具特定模式和 managed 政策

1243* [Authentication](/zh-TW/authentication)：設定使用者對 Claude Code 的存取1243* [Authentication](/docs/zh-TW/authentication)：設定使用者對 Claude Code 的存取

1244* [Debug your configuration](/zh-TW/debug-your-config)：診斷為什麼設定、hook 或 MCP server 未生效1244* [Debug your configuration](/docs/zh-TW/debug-your-config)：診斷為什麼設定、hook 或 MCP server 未生效

1245* [Troubleshoot installation and login](/zh-TW/troubleshoot-install)：安裝、authentication 和平台問題1245* [Troubleshoot installation and login](/docs/zh-TW/troubleshoot-install)：安裝、authentication 和平台問題

skills.md +45 −45

Details

11當您不斷將相同的劇本、檢查清單或多步驟程序貼到聊天中時，或當 CLAUDE.md 的某個部分已成長為程序而不是事實時，請建立一個 skill。與 CLAUDE.md 內容不同，skill 的主體僅在使用時載入，因此長參考資料在您需要之前幾乎不花費任何成本。11當您不斷將相同的劇本、檢查清單或多步驟程序貼到聊天中時，或當 CLAUDE.md 的某個部分已成長為程序而不是事實時，請建立一個 skill。與 CLAUDE.md 內容不同，skill 的主體僅在使用時載入，因此長參考資料在您需要之前幾乎不花費任何成本。

12 12

13<Note>13<Note>

~~14 對於內建命令（如 `/help` 和 `/compact`）以及捆綁的 skills（如 `/debug` 和 `/code-review`），請參閱[命令參考](/zh-TW/commands)。~~14 對於內建命令（如 `/help` 和 `/compact`）以及捆綁的 skills（如 `/debug` 和 `/code-review`），請參閱[命令參考](/docs/zh-TW/commands)。

15 15

16 **自訂命令已合併到 skills 中。** `.claude/commands/deploy.md` 中的檔案和 `.claude/skills/deploy/SKILL.md` 中的 skill 都會建立 `/deploy` 並以相同方式運作。您現有的 `.claude/commands/` 檔案會繼續運作。Skills 新增了可選功能：支援檔案的目錄、[控制您或 Claude 是否叫用它們](#control-who-invokes-a-skill)的 frontmatter，以及 Claude 在相關時自動載入它們的能力。16 **自訂命令已合併到 skills 中。** `.claude/commands/deploy.md` 中的檔案和 `.claude/skills/deploy/SKILL.md` 中的 skill 都會建立 `/deploy` 並以相同方式運作。您現有的 `.claude/commands/` 檔案會繼續運作。Skills 新增了可選功能：支援檔案的目錄、[控制您或 Claude 是否叫用它們](#control-who-invokes-a-skill)的 frontmatter，以及 Claude 在相關時自動載入它們的能力。

17</Note>17</Note>

22 捆綁的 skills22 捆綁的 skills

23</h2>23</h2>

24 24

25Claude Code 包含一組捆綁的 skills，在每個工作階段中都可用，除非使用 [`disableBundledSkills`](/zh-TW/settings#available-settings) 設定停用，包括 `/doctor`、`/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。與大多數內建命令不同，內建命令直接執行固定邏輯，捆綁的 skills 是基於提示的：它們為 Claude 提供詳細的劇本，並讓它使用其工具來協調工作。您叫用它們的方式與任何其他 skill 相同，輸入 `/` 後跟 skill 名稱。25Claude Code 包含一組捆綁的 skills，在每個工作階段中都可用，除非使用 [`disableBundledSkills`](/docs/zh-TW/settings#available-settings) 設定停用，包括 `/doctor`、`/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。與大多數內建命令不同，內建命令直接執行固定邏輯，捆綁的 skills 是基於提示的：它們為 Claude 提供詳細的劇本，並讓它使用其工具來協調工作。您叫用它們的方式與任何其他 skill 相同，輸入 `/` 後跟 skill 名稱。

26 26

27[`/doctor`](/zh-TW/commands#all-commands) 設定檢查是 Claude Code v2.1.205 及更新版本中 `disableBundledSkills` 的一個例外：當設定開啟時，它仍然可以輸入。若要隱藏它，請設定 `DISABLE_DOCTOR_COMMAND` 環境變數或 [`skillOverrides`](#override-skill-visibility-from-settings) 項目 `"doctor": "off"`。在 v2.1.205 之前，`/doctor` 是內建命令而不是捆綁的 skill。27[`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查是 Claude Code v2.1.205 及更新版本中 `disableBundledSkills` 的一個例外：當設定開啟時，它仍然可以輸入。若要隱藏它，請設定 `DISABLE_DOCTOR_COMMAND` 環境變數或 [`skillOverrides`](#override-skill-visibility-from-settings) 項目 `"doctor": "off"`。在 v2.1.205 之前，`/doctor` 是內建命令而不是捆綁的 skill。

28 28

~~29捆綁的 skills 在[命令參考](/zh-TW/commands)中與內建命令一起列出，在「目的」欄中標記為 **Skill**。~~29捆綁的 skills 在[命令參考](/docs/zh-TW/commands)中與內建命令一起列出，在「目的」欄中標記為 **Skill**。

30 30

31<h3 id="run-and-verify-your-app">31<h3 id="run-and-verify-your-app">

32 執行並驗證您的應用程式32 執行並驗證您的應用程式

40| `/verify` | 建置並執行您的應用程式以確認程式碼變更是否執行預期的操作，無需回退到測試或型別檢查 |40| `/verify` | 建置並執行您的應用程式以確認程式碼變更是否執行預期的操作，無需回退到測試或型別檢查 |

41| `/run-skill-generator` | 教導 `/run` 和 `/verify` 如何建置和啟動您的專案 |41| `/run-skill-generator` | 教導 `/run` 和 `/verify` 如何建置和啟動您的專案 |

42 42

~~43{/* min-version: 2.1.145 */}所有三個 skills 都需要 Claude Code v2.1.145 或更新版本。~~43所有三個 skills 都需要 Claude Code v2.1.145 或更新版本。

44 44

45`/run` 和 `/verify` 無需設定即可運作。它們根據您的專案類型（CLI、伺服器、TUI、瀏覽器驅動）以及您的 README、`package.json` 或 `Makefile` 中的內容推斷啟動。該推斷對於需要超出標準啟動的任何內容的專案變得不可靠：資料庫、env 檔案、圖形工作階段、多步驟建置。45`/run` 和 `/verify` 無需設定即可運作。它們根據您的專案類型（CLI、伺服器、TUI、瀏覽器驅動）以及您的 README、`package.json` 或 `Makefile` 中的內容推斷啟動。該推斷對於需要超出標準啟動的任何內容的專案變得不可靠：資料庫、env 檔案、圖形工作階段、多步驟建置。

46 46

114 114

115| 位置 | 路徑 | 適用於 |115| 位置 | 路徑 | 適用於 |

116| :- | :---------------------------------------- | :--------- |116| :- | :---------------------------------------- | :--------- |

117| 企業 | 請參閱[受管設定](/zh-TW/settings#settings-files) | 您組織中的所有使用者 |117| 企業 | 請參閱[受管設定](/docs/zh-TW/settings#settings-files) | 您組織中的所有使用者 |

118| 個人 | `~/.claude/skills/<skill-name>/SKILL.md` | 您的所有專案 |118| 個人 | `~/.claude/skills/<skill-name>/SKILL.md` | 您的所有專案 |

119| 專案 | `.claude/skills/<skill-name>/SKILL.md` | 僅此專案 |119| 專案 | `.claude/skills/<skill-name>/SKILL.md` | 僅此專案 |

120| 外掛 | `<plugin>/skills/<skill-name>/SKILL.md` | 啟用外掛的位置 |120| 外掛 | `<plugin>/skills/<skill-name>/SKILL.md` | 啟用外掛的位置 |

133 133

134當您或 Claude 叫用未限定的名稱時，專案根目錄 skill 會載入，Claude Code 會將目錄限定變體的清單附加到其內容中，並附帶指示以也叫用任何目錄包含 Claude 正在處理的檔案的變體。因此，巢狀 skill 在其目錄中的工作時仍然適用，即使只叫用未限定的名稱。需要 Claude Code v2.1.203 或更新版本。134當您或 Claude 叫用未限定的名稱時，專案根目錄 skill 會載入，Claude Code 會將目錄限定變體的清單附加到其內容中，並附帶指示以也叫用任何目錄包含 Claude 正在處理的檔案的變體。因此，巢狀 skill 在其目錄中的工作時仍然適用，即使只叫用未限定的名稱。需要 Claude Code v2.1.203 或更新版本。

135 135

136一個 `<skill-name>` 項目在企業、個人或專案位置可以是磁碟上其他位置的目錄的符號連結。Claude Code 遵循符號連結並從目標目錄讀取 `SKILL.md`，如果相同的目標可從多個位置到達，Claude Code 會載入該 skill 一次。外掛 skills 以不同方式處理符號連結；請參閱[使用符號連結在市集中共享檔案](/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)。136一個 `<skill-name>` 項目在企業、個人或專案位置可以是磁碟上其他位置的目錄的符號連結。Claude Code 遵循符號連結並從目標目錄讀取 `SKILL.md`，如果相同的目標可從多個位置到達，Claude Code 會載入該 skill 一次。外掛 skills 以不同方式處理符號連結；請參閱[使用符號連結在市集中共享檔案](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)。

137 137

138<Note>138<Note>

139 將 `.claude-plugin/plugin.json` 新增到 skill 資料夾，它會載入為名為 `<name>@skills-dir` 的[外掛](/zh-TW/plugins-reference#skills-directory-plugins)，因此它可以捆綁代理、hooks 和 MCP 伺服器。在專案的 `.claude/skills/` 中，這需要先接受工作區信任對話。139 將 `.claude-plugin/plugin.json` 新增到 skill 資料夾，它會載入為名為 `<name>@skills-dir` 的[外掛](/docs/zh-TW/plugins-reference#skills-directory-plugins)，因此它可以捆綁代理、hooks 和 MCP 伺服器。在專案的 `.claude/skills/` 中，這需要先接受工作區信任對話。

140</Note>140</Note>

141 141

142<h4 id="live-change-detection">142<h4 id="live-change-detection">

146Claude Code 監視 skill 目錄以尋找檔案變更。在 `~/.claude/skills/`、專案 `.claude/skills/` 或 `--add-dir` 目錄內的 `.claude/skills/` 中新增、編輯或移除 skill 會在目前工作階段內生效，無需重新啟動。建立在工作階段開始時不存在的頂級 skills 目錄需要重新啟動 Claude Code，以便可以監視新目錄。146Claude Code 監視 skill 目錄以尋找檔案變更。在 `~/.claude/skills/`、專案 `.claude/skills/` 或 `--add-dir` 目錄內的 `.claude/skills/` 中新增、編輯或移除 skill 會在目前工作階段內生效，無需重新啟動。建立在工作階段開始時不存在的頂級 skills 目錄需要重新啟動 Claude Code，以便可以監視新目錄。

147 147

148<Note>148<Note>

149 即時變更偵測僅涵蓋 `SKILL.md` 文字。對於也是[外掛](/zh-TW/plugins-reference#skills-directory-plugins)的 skill 資料夾，`hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的變更需要 `/reload-plugins` 才能生效。149 即時變更偵測僅涵蓋 `SKILL.md` 文字。對於也是[外掛](/docs/zh-TW/plugins-reference#skills-directory-plugins)的 skill 資料夾，`hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的變更需要 `/reload-plugins` 才能生效。

150</Note>150</Note>

151 151

152<h4 id="automatic-discovery-from-parent-and-nested-directories">152<h4 id="automatic-discovery-from-parent-and-nested-directories">

177 來自其他目錄的 skills177 來自其他目錄的 skills

178</h4>178</h4>

179 179

180`--add-dir` 旗標和 `/add-dir` 命令[授予檔案存取權](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)而不是設定發現，但 skills 是例外：已新增目錄中的 `.claude/skills/` 會自動載入。此例外僅適用於 `--add-dir` 和 `/add-dir`。`settings.json` 中的 `permissions.additionalDirectories` 設定僅授予檔案存取權，不會載入 skills。請參閱[即時變更偵測](#live-change-detection)以了解編輯在工作階段期間如何被拾取。180`--add-dir` 旗標和 `/add-dir` 命令[授予檔案存取權](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)而不是設定發現，但 skills 是例外：已新增目錄中的 `.claude/skills/` 會自動載入。此例外僅適用於 `--add-dir` 和 `/add-dir`。`settings.json` 中的 `permissions.additionalDirectories` 設定僅授予檔案存取權，不會載入 skills。請參閱[即時變更偵測](#live-change-detection)以了解編輯在工作階段期間如何被拾取。

181 181

182其他 `.claude/` 設定（例如命令和輸出樣式）不會從其他目錄載入。請參閱[例外表](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)以取得完整的載入和未載入內容清單，以及跨專案共享設定的建議方式。182其他 `.claude/` 設定（例如命令和輸出樣式）不會從其他目錄載入。請參閱[例外表](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)以取得完整的載入和未載入內容清單，以及跨專案共享設定的建議方式。

183 183

184<Note>184<Note>

185 來自 `--add-dir` 目錄的 CLAUDE.md 檔案預設不會載入。若要載入它們，請設定 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`。請參閱[從其他目錄載入](/zh-TW/memory#load-from-additional-directories)。185 來自 `--add-dir` 目錄的 CLAUDE.md 檔案預設不會載入。若要載入它們，請設定 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`。請參閱[從其他目錄載入](/docs/zh-TW/memory#load-from-additional-directories)。

186</Note>186</Note>

187 187

188<h2 id="configure-skills">188<h2 id="configure-skills">

229 229

230您的 `SKILL.md` 可以包含任何內容，但思考您想如何叫用該 skill（由您、由 Claude 或兩者）以及您想在哪裡執行它（內聯或在 subagent 中）有助於指導要包含的內容。對於複雜的 skills，您也可以[新增支援檔案](#add-supporting-files)以保持主要 skill 的焦點。230您的 `SKILL.md` 可以包含任何內容，但思考您想如何叫用該 skill（由您、由 Claude 或兩者）以及您想在哪裡執行它（內聯或在 subagent 中）有助於指導要包含的內容。對於複雜的 skills，您也可以[新增支援檔案](#add-supporting-files)以保持主要 skill 的焦點。

231 231

232保持內容本身簡潔。一旦 skill 載入，其內容[在整個回合中保持在上下文中](#skill-content-lifecycle)，因此每一行都是一個重複的令牌成本。陳述要做什麼，而不是敘述如何或為什麼，並應用與您對 [CLAUDE.md 內容](/zh-TW/best-practices#write-an-effective-claude-md)所做的相同簡潔性測試。232保持內容本身簡潔。一旦 skill 載入，其內容[在整個回合中保持在上下文中](#skill-content-lifecycle)，因此每一行都是一個重複的令牌成本。陳述要做什麼，而不是敘述如何或為什麼，並應用與您對 [CLAUDE.md 內容](/docs/zh-TW/best-practices#write-an-effective-claude-md)所做的相同簡潔性測試。

233 233

234<h3 id="frontmatter-reference">234<h3 id="frontmatter-reference">

235 Frontmatter 參考235 Frontmatter 參考

257| `when_to_use` | 否 | Claude 應何時叫用該 skill 的額外上下文，例如觸發短語或範例請求。附加到 skill 清單中的 `description`，並計入 1,536 個字元的上限。 |257| `when_to_use` | 否 | Claude 應何時叫用該 skill 的額外上下文，例如觸發短語或範例請求。附加到 skill 清單中的 `description`，並計入 1,536 個字元的上限。 |

258| `argument-hint` | 否 | 自動完成期間顯示的提示，指示預期的引數。範例：`[issue-number]` 或 `[filename] [format]`。 |258| `argument-hint` | 否 | 自動完成期間顯示的提示，指示預期的引數。範例：`[issue-number]` 或 `[filename] [format]`。 |

259| `arguments` | 否 | 用於 skill 內容中[`$name` 替換](#available-string-substitutions)的具名位置引數。接受空格分隔的字串或 YAML 清單。名稱按順序對應到引數位置。 |259| `arguments` | 否 | 用於 skill 內容中[`$name` 替換](#available-string-substitutions)的具名位置引數。接受空格分隔的字串或 YAML 清單。名稱按順序對應到引數位置。 |

260| `disable-model-invocation` | 否 | 設定為 `true` 以防止 Claude 自動載入此 skill。用於您想使用 `/name` 手動觸發的工作流程。也防止該 skill 被[預載入到 subagents](/zh-TW/sub-agents#preload-skills-into-subagents)。自 v2.1.196 起，也防止該 skill 在[排程任務](/zh-TW/scheduled-tasks)以該 skill 作為其提示觸發時執行。預設值：`false`。 |260| `disable-model-invocation` | 否 | 設定為 `true` 以防止 Claude 自動載入此 skill。用於您想使用 `/name` 手動觸發的工作流程。也防止該 skill 被[預載入到 subagents](/docs/zh-TW/sub-agents#preload-skills-into-subagents)。自 v2.1.196 起，也防止該 skill 在[排程任務](/docs/zh-TW/scheduled-tasks)以該 skill 作為其提示觸發時執行。預設值：`false`。 |

261| `user-invocable` | 否 | 設定為 `false` 以從 `/` 功能表中隱藏。用於使用者不應直接叫用的背景知識。預設值：`true`。 |261| `user-invocable` | 否 | 設定為 `false` 以從 `/` 功能表中隱藏。用於使用者不應直接叫用的背景知識。預設值：`true`。 |

262| `allowed-tools` | 否 | 當此 skill 處於作用中時，Claude 可以使用而無需詢問許可的工具。接受空格分隔的字串或逗號分隔的字串，或 YAML 清單。 |262| `allowed-tools` | 否 | 當此 skill 處於作用中時，Claude 可以使用而無需詢問許可的工具。接受空格分隔的字串或逗號分隔的字串，或 YAML 清單。 |

263| `disallowed-tools` | 否 | 當此 skill 處於作用中時從 Claude 的可用工具池中移除的工具。用於不應呼叫某些工具的自主 skills，例如用於背景迴圈的 `AskUserQuestion`。接受空格分隔的字串或逗號分隔的字串，或 YAML 清單。限制在您傳送下一則訊息時清除。 |263| `disallowed-tools` | 否 | 當此 skill 處於作用中時從 Claude 的可用工具池中移除的工具。用於不應呼叫某些工具的自主 skills，例如用於背景迴圈的 `AskUserQuestion`。接受空格分隔的字串或逗號分隔的字串，或 YAML 清單。限制在您傳送下一則訊息時清除。 |

264| `model` | 否 | 當此 skill 處於作用中時要使用的模型。覆蓋適用於目前回合的其餘部分，不會儲存到設定；工作階段模型在您的下一個提示時恢復。接受與 [`/model`](/zh-TW/model-config) 相同的值，或 `inherit` 以保持作用中的模型。由您組織的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單排除的值不會被使用，工作階段會保持其目前的模型。 |264| `model` | 否 | 當此 skill 處於作用中時要使用的模型。覆蓋適用於目前回合的其餘部分，不會儲存到設定；工作階段模型在您的下一個提示時恢復。接受與 [`/model`](/docs/zh-TW/model-config) 相同的值，或 `inherit` 以保持作用中的模型。由您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除的值不會被使用，工作階段會保持其目前的模型。 |

265| `effort` | 否 | 當此 skill 處於作用中時的[努力級別](/zh-TW/model-config#adjust-effort-level)。覆蓋工作階段努力級別。預設值：繼承自工作階段。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用級別取決於模型。 |265| `effort` | 否 | 當此 skill 處於作用中時的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。覆蓋工作階段努力級別。預設值：繼承自工作階段。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用級別取決於模型。 |

266| `context` | 否 | 設定為 `fork` 以在分叉的 subagent 上下文中執行。 |266| `context` | 否 | 設定為 `fork` 以在分叉的 subagent 上下文中執行。 |

267| `agent` | 否 | 當設定 `context: fork` 時要使用的 subagent 類型。 |267| `agent` | 否 | 當設定 `context: fork` 時要使用的 subagent 類型。 |

268| `hooks` | 否 | 限定於此 skill 生命週期的 hooks。請參閱 [Skills 和代理中的 Hooks](/zh-TW/hooks#hooks-in-skills-and-agents) 以取得設定格式。 |268| `hooks` | 否 | 限定於此 skill 生命週期的 hooks。請參閱 [Skills 和代理中的 Hooks](/docs/zh-TW/hooks#hooks-in-skills-and-agents) 以取得設定格式。 |

269| `paths` | 否 | Glob 模式，限制何時啟動此 skill。接受逗號分隔的字串或 YAML 清單。設定時，Claude 僅在使用與模式相符的檔案時自動載入該 skill。使用與[路徑特定規則](/zh-TW/memory#path-specific-rules)相同的格式。 |269| `paths` | 否 | Glob 模式，限制何時啟動此 skill。接受逗號分隔的字串或 YAML 清單。設定時，Claude 僅在使用與模式相符的檔案時自動載入該 skill。使用與[路徑特定規則](/docs/zh-TW/memory#path-specific-rules)相同的格式。 |

270| `shell` | 否 | 用於此 skill 中 `` !`command` `` 和 ` ```! ` 區塊的 shell。接受 `bash`（預設）或 `powershell`。設定 `powershell` 會在 Windows 上透過 PowerShell 執行內聯 shell 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。 |270| `shell` | 否 | 用於此 skill 中 `` !`command` `` 和 ` ```! ` 區塊的 shell。接受 `bash`（預設）或 `powershell`。設定 `powershell` 會在 Windows 上透過 PowerShell 執行內聯 shell 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。 |

271 271

272<h4 id="how-a-skill-gets-its-command-name">272<h4 id="how-a-skill-gets-its-command-name">

286| 外掛根目錄 `SKILL.md` | Frontmatter `name`，以外掛目錄名稱作為後備 | `my-plugin/SKILL.md` 搭配 `name: review` → `/my-plugin:review`。請參閱[路徑行為規則](/zh-TW/plugins-reference#path-behavior-rules) |286| 外掛根目錄 `SKILL.md` | Frontmatter `name`，以外掛目錄名稱作為後備 | `my-plugin/SKILL.md` 搭配 `name: review` → `/my-plugin:review`。請參閱[路徑行為規則](/docs/zh-TW/plugins-reference#path-behavior-rules) |

287 287

288外掛根目錄情況是 `name` 設定命令名稱的唯一地方，因為沒有 skill 目錄可從中取得。如果 frontmatter 中未設定 `name`，則改用外掛的目錄名稱。288外掛根目錄情況是 `name` 設定命令名稱的唯一地方，因為沒有 skill 目錄可從中取得。如果 frontmatter 中未設定 `name`，則改用外掛的目錄名稱。

289 289

302| `${CLAUDE_SESSION_ID}` | 目前的工作階段 ID。適用於記錄、建立工作階段特定檔案或將 skill 輸出與工作階段相關聯。 |302| `${CLAUDE_SESSION_ID}` | 目前的工作階段 ID。適用於記錄、建立工作階段特定檔案或將 skill 輸出與工作階段相關聯。 |

303| `${CLAUDE_EFFORT}` | 目前的努力級別：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。使用此來根據作用中的努力設定調整 skill 說明。 |303| `${CLAUDE_EFFORT}` | 目前的努力級別：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。使用此來根據作用中的努力設定調整 skill 說明。 |

304| `${CLAUDE_SKILL_DIR}` | 包含 skill 的 `SKILL.md` 檔案的目錄。對於外掛 skills，這是外掛中 skill 的子目錄，而不是外掛根目錄。在 bash 注入命令中使用此來參考與 skill 捆綁的指令碼或檔案，無論目前的工作目錄如何。 |304| `${CLAUDE_SKILL_DIR}` | 包含 skill 的 `SKILL.md` 檔案的目錄。對於外掛 skills，這是外掛中 skill 的子目錄，而不是外掛根目錄。在 bash 注入命令中使用此來參考與 skill 捆綁的指令碼或檔案，無論目前的工作目錄如何。 |

305| `${CLAUDE_PROJECT_DIR}` | 專案根目錄。這是 [hooks](/zh-TW/hooks#reference-scripts-by-path) 和 MCP 伺服器接收的相同路徑作為 `CLAUDE_PROJECT_DIR`。使用此來參考專案本地指令碼或檔案，例如 `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`，獨立於 skill 的安裝位置。 |305| `${CLAUDE_PROJECT_DIR}` | 專案根目錄。這是 [hooks](/docs/zh-TW/hooks#reference-scripts-by-path) 和 MCP 伺服器接收的相同路徑作為 `CLAUDE_PROJECT_DIR`。使用此來參考專案本地指令碼或檔案，例如 `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`，獨立於 skill 的安裝位置。 |

306 306

307`${CLAUDE_PROJECT_DIR}` 替換需要 Claude Code v2.1.196 或更新版本。它適用於 skill 主體和 [`allowed-tools`](#frontmatter-reference) frontmatter，因此許可規則（例如 `Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)` 解析為 skill 主體使用的相同路徑。307`${CLAUDE_PROJECT_DIR}` 替換需要 Claude Code v2.1.196 或更新版本。它適用於 skill 主體和 [`allowed-tools`](#frontmatter-reference) frontmatter，因此許可規則（例如 `Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)` 解析為 skill 主體使用的相同路徑。

308 308

385| `user-invocable: false` | 否 | 是 | 描述始終在上下文中，叫用時載入完整 skill |385| `user-invocable: false` | 否 | 是 | 描述始終在上下文中，叫用時載入完整 skill |

386 386

387<Note>387<Note>

388 在常規工作階段中，skill 描述會載入上下文，以便 Claude 知道可用的內容，但完整 skill 內容僅在叫用時載入。[預載入 skills 的 Subagents](/zh-TW/sub-agents#preload-skills-into-subagents) 的運作方式不同：完整 skill 內容在啟動時注入。388 在常規工作階段中，skill 描述會載入上下文，以便 Claude 知道可用的內容，但完整 skill 內容僅在叫用時載入。[預載入 skills 的 Subagents](/docs/zh-TW/sub-agents#preload-skills-into-subagents) 的運作方式不同：完整 skill 內容在啟動時注入。

389</Note>389</Note>

390 390

391<h3 id="skill-content-lifecycle">391<h3 id="skill-content-lifecycle">

396 396

397當 Claude 重新叫用其呈現內容與已在上下文中的副本相同的 skill 時，Claude Code 會新增一個簡短的註記，表示該 skill 已載入，而不是內容的第二份副本。當呈現內容不同時（因為引數改變或[動態上下文](#inject-dynamic-context)命令產生了新輸出），Claude Code 會附加完整內容。在 v2.1.202 之前，每次重新叫用都會附加 skill 說明的另一份完整副本。397當 Claude 重新叫用其呈現內容與已在上下文中的副本相同的 skill 時，Claude Code 會新增一個簡短的註記，表示該 skill 已載入，而不是內容的第二份副本。當呈現內容不同時（因為引數改變或[動態上下文](#inject-dynamic-context)命令產生了新輸出），Claude Code 會附加完整內容。在 v2.1.202 之前，每次重新叫用都會附加 skill 說明的另一份完整副本。

398 398

399[Auto-compact](/zh-TW/how-claude-code-works#when-context-fills-up) 在令牌預算內轉發叫用的 skills。當對話被摘要以釋放上下文時，Claude Code 在摘要後重新附加每個 skill 的最新叫用，保留每個的前 5,000 個令牌。重新附加的 skills 共享 25,000 個令牌的組合預算。Claude Code 從最近叫用的 skill 開始填充此預算，因此如果您在一個工作階段中叫用了許多 skills，較舊的 skills 可能在 compaction 後完全被丟棄。399[Auto-compact](/docs/zh-TW/how-claude-code-works#when-context-fills-up) 在令牌預算內轉發叫用的 skills。當對話被摘要以釋放上下文時，Claude Code 在摘要後重新附加每個 skill 的最新叫用，保留每個的前 5,000 個令牌。重新附加的 skills 共享 25,000 個令牌的組合預算。Claude Code 從最近叫用的 skill 開始填充此預算，因此如果您在一個工作階段中叫用了許多 skills，較舊的 skills 可能在 compaction 後完全被丟棄。

400 400

401如果 skill 在第一個回應後似乎停止影響行為，內容通常仍然存在，模型正在選擇其他工具或方法。加強 skill 的 `description` 和說明，以便模型繼續偏好它，或使用 [hooks](/zh-TW/hooks) 來確定性地強制行為。如果 skill 很大或您在它之後叫用了其他幾個，請在 compaction 後重新叫用它以恢復完整內容。401如果 skill 在第一個回應後似乎停止影響行為，內容通常仍然存在，模型正在選擇其他工具或方法。加強 skill 的 `description` 和說明，以便模型繼續偏好它，或使用 [hooks](/docs/zh-TW/hooks) 來確定性地強制行為。如果 skill 很大或您在它之後叫用了其他幾個，請在 compaction 後重新叫用它以恢復完整內容。

402 402

403<h3 id="pre-approve-tools-for-a-skill">403<h3 id="pre-approve-tools-for-a-skill">

404 為 skill 預先批准工具404 為 skill 預先批准工具

405</h3>405</h3>

406 406

407`allowed-tools` 欄位在 skill 處於作用中時授予列出的工具的許可，因此 Claude 可以使用它們而無需提示您批准。它不會限制哪些工具可用：每個工具仍然可呼叫，您的[許可設定](/zh-TW/permissions)仍然管理未列出的工具。407`allowed-tools` 欄位在 skill 處於作用中時授予列出的工具的許可，因此 Claude 可以使用它們而無需提示您批准。它不會限制哪些工具可用：每個工具仍然可呼叫，您的[許可設定](/docs/zh-TW/permissions)仍然管理未列出的工具。

408 408

409對於簽入到專案的 `.claude/skills/` 目錄的 skills，`allowed-tools` 在您接受該資料夾的工作區信任對話後生效，與 `.claude/settings.json` 中的許可規則相同。在信任存放庫之前檢查專案 skills，因為 skill 可以授予自己廣泛的工具存取權限。409對於簽入到專案的 `.claude/skills/` 目錄的 skills，`allowed-tools` 在您接受該資料夾的工作區信任對話後生效，與 `.claude/settings.json` 中的許可規則相同。在信任存放庫之前檢查專案 skills，因為 skill 可以授予自己廣泛的工具存取權限。

410 410

419---419---

420```420```

421 421

422若要在 skill 處於作用中時從 Claude 的可用工具池中移除工具，請在 skill 的 frontmatter 中的 `disallowed-tools` 中列出它們。限制在您傳送下一則訊息時清除。若要在所有 skills 和提示中阻止工具，請在您的[許可設定](/zh-TW/permissions)中新增拒絕規則。422若要在 skill 處於作用中時從 Claude 的可用工具池中移除工具，請在 skill 的 frontmatter 中的 `disallowed-tools` 中列出它們。限制在您傳送下一則訊息時清除。若要在所有 skills 和提示中阻止工具，請在您的[許可設定](/docs/zh-TW/permissions)中新增拒絕規則。

423 423

424<h3 id="pass-arguments-to-skills">424<h3 id="pass-arguments-to-skills">

425 將引數傳遞給 skills425 將引數傳遞給 skills

530```530```

531````531````

532 532

533若要停用來自使用者、專案、外掛或[其他目錄](#skills-from-additional-directories)來源的 skills 和自訂命令的此行為，請在[設定](/zh-TW/settings)中設定 `"disableSkillShellExecution": true`。每個命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。捆綁和受管 skills 不受影響。此設定在[受管設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它。533若要停用來自使用者、專案、外掛或[其他目錄](#skills-from-additional-directories)來源的 skills 和自訂命令的此行為，請在[設定](/docs/zh-TW/settings)中設定 `"disableSkillShellExecution": true`。每個命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。捆綁和受管 skills 不受影響。此設定在[受管設定](/docs/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它。

534 534

535<Tip>535<Tip>

536 若要在 skill 執行時要求更深入的推理，請在 skill 內容中的任何位置包含 `ultrathink`。請參閱[使用 ultrathink 進行一次性深入推理](/zh-TW/model-config#use-ultrathink-for-one-off-deep-reasoning)。536 若要在 skill 執行時要求更深入的推理，請在 skill 內容中的任何位置包含 `ultrathink`。請參閱[使用 ultrathink 進行一次性深入推理](/docs/zh-TW/model-config#use-ultrathink-for-one-off-deep-reasoning)。

537</Tip>537</Tip>

538 538

539<h3 id="run-skills-in-a-subagent">539<h3 id="run-skills-in-a-subagent">

546 `context: fork` 僅對具有明確說明的 skills 有意義。如果您的 skill 包含「使用這些 API 慣例」之類的指南而沒有任務，subagent 會收到指南但沒有可操作的提示，並返回而沒有有意義的輸出。546 `context: fork` 僅對具有明確說明的 skills 有意義。如果您的 skill 包含「使用這些 API 慣例」之類的指南而沒有任務，subagent 會收到指南但沒有可操作的提示，並返回而沒有有意義的輸出。

547</Warning>547</Warning>

548 548

549Skills 和 [subagents](/zh-TW/sub-agents) 以兩個方向協同運作：549Skills 和 [subagents](/docs/zh-TW/sub-agents) 以兩個方向協同運作：

550 550

551| 方法 | 系統提示 | 任務 | 也載入 |551| 方法 | 系統提示 | 任務 | 也載入 |

552| :------------------------- | :--------------------- | :----------- | :----------------------------- |552| :------------------------- | :--------------------- | :----------- | :----------------------------- |

555 555

556使用 `context: fork`，您在 skill 中編寫任務並選擇代理類型來執行它。內建的 Explore 和 Plan 代理[跳過 CLAUDE.md 和 git status](/zh-TW/sub-agents#what-loads-at-startup)以保持其上下文較小，因此使用 `agent: Explore` 的分叉 skill 只看到 SKILL.md 內容和代理自己的系統提示。對於反向情況，其中您定義使用 skills 作為參考資料的自訂 subagent，請參閱 [Subagents](/zh-TW/sub-agents#preload-skills-into-subagents)。556使用 `context: fork`，您在 skill 中編寫任務並選擇代理類型來執行它。內建的 Explore 和 Plan 代理[跳過 CLAUDE.md 和 git status](/docs/zh-TW/sub-agents#what-loads-at-startup)以保持其上下文較小，因此使用 `agent: Explore` 的分叉 skill 只看到 SKILL.md 內容和代理自己的系統提示。對於反向情況，其中您定義使用 skills 作為參考資料的自訂 subagent，請參閱 [Subagents](/docs/zh-TW/sub-agents#preload-skills-into-subagents)。

557 557

558<h4 id="example-research-skill-using-explore-agent">558<h4 id="example-research-skill-using-explore-agent">

559 範例：使用 Explore 代理的研究 skill559 範例：使用 Explore 代理的研究 skill

589 限制 Claude 的 skill 存取589 限制 Claude 的 skill 存取

590</h3>590</h3>

591 591

592預設情況下，Claude 可以叫用任何沒有設定 `disable-model-invocation: true` 的 skill。定義 `allowed-tools` 的 Skills 在 skill 處於作用中時授予 Claude 對這些工具的存取權，無需每次使用批准。您的[許可設定](/zh-TW/permissions)仍然管理所有其他工具的基準批准行為。一些內建命令也可透過 Skill 工具取得，包括 `/init`、`/review` 和 `/security-review`。其他內建命令（例如 `/compact`）則不行。592預設情況下，Claude 可以叫用任何沒有設定 `disable-model-invocation: true` 的 skill。定義 `allowed-tools` 的 Skills 在 skill 處於作用中時授予 Claude 對這些工具的存取權，無需每次使用批准。您的[許可設定](/docs/zh-TW/permissions)仍然管理所有其他工具的基準批准行為。一些內建命令也可透過 Skill 工具取得，包括 `/init`、`/review` 和 `/security-review`。其他內建命令（例如 `/compact`）則不行。

593 593

594控制 Claude 可以叫用哪些 skills 的三種方式：594控制 Claude 可以叫用哪些 skills 的三種方式：

595 595

600Skill600Skill

601```601```

602 602

603**使用[許可規則](/zh-TW/permissions)允許或拒絕特定 skills**：603**使用[許可規則](/docs/zh-TW/permissions)允許或拒絕特定 skills**：

604 604

605```text theme={null}605```text theme={null}

606# Allow only specific skills606# Allow only specific skills

623 從設定覆蓋 skill 可見性623 從設定覆蓋 skill 可見性

624</h3>624</h3>

625 625

626`skillOverrides` 設定從您的[設定](/zh-TW/settings)控制 skill 可見性，而不是 skill 自己的 frontmatter。將其用於您不想編輯 SKILL.md 的 skills，例如簽入共享專案儲存庫或由 MCP 伺服器提供的 skills。`/skills` 功能表為您編寫：突出顯示 skill 並按 `Space` 循環狀態，然後按 `Enter` 儲存到 `.claude/settings.local.json`。626`skillOverrides` 設定從您的[設定](/docs/zh-TW/settings)控制 skill 可見性，而不是 skill 自己的 frontmatter。將其用於您不想編輯 SKILL.md 的 skills，例如簽入共享專案儲存庫或由 MCP 伺服器提供的 skills。`/skills` 功能表為您編寫：突出顯示 skill 並按 `Space` 循環狀態，然後按 `Enter` 儲存到 `.claude/settings.local.json`。

627 627

628每個鍵是 skill 名稱，每個值是四種狀態之一：628每個鍵是 skill 名稱，每個值是四種狀態之一：

629 629

634| `"user-invocable-only"` | 隱藏 | 是 |634| `"user-invocable-only"` | 隱藏 | 是 |

635| `"off"` | 隱藏 | 隱藏 |635| `"off"` | 隱藏 | 隱藏 |

636 636

637自 v2.1.199 起，`"off"` 也會從廣告給 [Remote Control](/zh-TW/remote-control) 用戶端和 [Agent SDK](/zh-TW/agent-sdk/slash-commands) 呼叫者的命令列表中隱藏 skill，而不僅僅是終端 `/` 功能表。透過其完整名稱叫用隱藏的 skill 仍會返回 `skillOverrides` 錯誤，而不是執行它。637自 v2.1.199 起，`"off"` 也會從廣告給 [Remote Control](/docs/zh-TW/remote-control) 用戶端和 [Agent SDK](/docs/zh-TW/agent-sdk/slash-commands) 呼叫者的命令列表中隱藏 skill，而不僅僅是終端 `/` 功能表。透過其完整名稱叫用隱藏的 skill 仍會返回 `skillOverrides` 錯誤，而不是執行它。

638 638

639`skillOverrides` 中不存在的 skill 被視為 `"on"`。下面的範例將一個 skill 摺疊為其名稱，並完全關閉另一個：639`skillOverrides` 中不存在的 skill 被視為 `"on"`。下面的範例將一個 skill 摺疊為其名稱，並完全關閉另一個：

640 640

672安裝後，執行 `/reload-plugins` 以在目前工作階段中提供外掛的 skills。然後要求 Claude 評估現有 skill，例如 `evaluate my summarize-changes skill with skill-creator`。外掛會引導您完成編寫測試案例並執行迴圈：672安裝後，執行 `/reload-plugins` 以在目前工作階段中提供外掛的 skills。然後要求 Claude 評估現有 skill，例如 `evaluate my summarize-changes skill with skill-creator`。外掛會引導您完成編寫測試案例並執行迴圈：

673 673

674* **測試案例**：在 skill 目錄內的 `evals/evals.json` 中儲存提示、輸入檔案和預期行為674* **測試案例**：在 skill 目錄內的 `evals/evals.json` 中儲存提示、輸入檔案和預期行為

675* **隔離執行**：為每個測試案例生成一個 [subagent](/zh-TW/sub-agents)，以便每次執行都從乾淨的上下文開始，並記錄令牌計數和持續時間675* **隔離執行**：為每個測試案例生成一個 [subagent](/docs/zh-TW/sub-agents)，以便每次執行都從乾淨的上下文開始，並記錄令牌計數和持續時間

676* **評分**：根據輸出檢查每個判斷，並將通過或失敗與證據寫入 `grading.json`676* **評分**：根據輸出檢查每個判斷，並將通過或失敗與證據寫入 `grading.json`

677* **基準**：將通過率、時間和令牌聚合為有 skill 與無 skill 的 `benchmark.json`，以便您可以比較通過率改進與令牌和時間開銷677* **基準**：將通過率、時間和令牌聚合為有 skill 與無 skill 的 `benchmark.json`，以便您可以比較通過率改進與令牌和時間開銷

678* **版本比較**：在兩個版本的 skill 之間執行盲 A/B，以便您可以在提交之前確認編輯是改進678* **版本比較**：在兩個版本的 skill 之間執行盲 A/B，以便您可以在提交之前確認編輯是改進

688Skills 可以根據您的受眾在不同範圍內分發：688Skills 可以根據您的受眾在不同範圍內分發：

689 689

690* **專案 skills**：將 `.claude/skills/` 提交到版本控制690* **專案 skills**：將 `.claude/skills/` 提交到版本控制

691* **外掛**：在您的[外掛](/zh-TW/plugins)中建立 `skills/` 目錄691* **外掛**：在您的[外掛](/docs/zh-TW/plugins)中建立 `skills/` 目錄

692* **受管**：透過[受管設定](/zh-TW/settings#settings-files)部署組織範圍692* **受管**：透過[受管設定](/docs/zh-TW/settings#settings-files)部署組織範圍

693 693

694<h3 id="generate-visual-output">694<h3 id="generate-visual-output">

695 生成視覺輸出695 生成視覺輸出

916 916

917Claude Code 會將 skill 名稱和描述的清單載入上下文，以便 Claude 知道可用的內容。清單始終包含每個 skill 名稱，但如果您有許多 skills，Claude Code 會縮短描述以適應清單的字元預算，這可能會去除 Claude 需要匹配您的請求的關鍵字。預算在模型上下文視窗的 1% 處動態縮放。當清單超出預算時，Claude Code 會從您最少叫用的 skills 開始捨棄描述，因此您使用最多的 skills 會保留其完整文字。917Claude Code 會將 skill 名稱和描述的清單載入上下文，以便 Claude 知道可用的內容。清單始終包含每個 skill 名稱，但如果您有許多 skills，Claude Code 會縮短描述以適應清單的字元預算，這可能會去除 Claude 需要匹配您的請求的關鍵字。預算在模型上下文視窗的 1% 處動態縮放。當清單超出預算時，Claude Code 會從您最少叫用的 skills 開始捨棄描述，因此您使用最多的 skills 會保留其完整文字。

918 918

919執行 `/doctor` 以估計清單的上下文成本及其最大貢獻者。當清單超出預算時，Claude Code 也會將警告寫入偵錯日誌，可透過 [`--debug`](/zh-TW/cli-reference#cli-flags) 查看。919執行 `/doctor` 以估計清單的上下文成本及其最大貢獻者。當清單超出預算時，Claude Code 也會將警告寫入偵錯日誌，可透過 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 查看。

920 920

921`/context` 中的 Skills 列會報告套用預算後的清單大小，因此它與模型接收的內容相符。在 v2.1.196 之前，該列會計算每個描述的完整文字，可能會顯示一個比設定的預算大幾倍的值。921`/context` 中的 Skills 列會報告套用預算後的清單大小，因此它與模型接收的內容相符。在 v2.1.196 之前，該列會計算每個描述的完整文字，可能會顯示一個比設定的預算大幾倍的值。

922 922

923若要提高預算，請設定 [`skillListingBudgetFraction`](/zh-TW/settings#available-settings) 設定（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 環境變數為固定字元計數。若要為其他 skills 釋放預算，請在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將低優先順序項目設定為 `"name-only"`，以便它們列出而不顯示描述。您也可以在來源處修剪 `description` 和 `when_to_use` 文字：前置關鍵使用案例，因為每個項目的結合文字無論預算如何都限制在 1,536 個字元。此上限可透過 [`skillListingMaxDescChars`](/zh-TW/settings#available-settings) 進行設定。923若要提高預算，請設定 [`skillListingBudgetFraction`](/docs/zh-TW/settings#available-settings) 設定（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 環境變數為固定字元計數。若要為其他 skills 釋放預算，請在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將低優先順序項目設定為 `"name-only"`，以便它們列出而不顯示描述。您也可以在來源處修剪 `description` 和 `when_to_use` 文字：前置關鍵使用案例，因為每個項目的結合文字無論預算如何都限制在 1,536 個字元。此上限可透過 [`skillListingMaxDescChars`](/docs/zh-TW/settings#available-settings) 進行設定。

924 924

925<h2 id="related-resources">925<h2 id="related-resources">

926 相關資源926 相關資源

927</h2>927</h2>

928 928

929* **[除錯您的設定](/zh-TW/debug-your-config)**：診斷為什麼 skill 沒有出現或觸發929* **[除錯您的設定](/docs/zh-TW/debug-your-config)**：診斷為什麼 skill 沒有出現或觸發

930* **[評估 skill 輸出品質](https://agentskills.io/skill-creation/evaluating-skills)**：agentskills.io 上的 eval 檔案格式和反覆運算工作流程930* **[評估 skill 輸出品質](https://agentskills.io/skill-creation/evaluating-skills)**：agentskills.io 上的 eval 檔案格式和反覆運算工作流程

931* **[Skill 編寫最佳實踐](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**：適用於 Claude 產品的編寫指導931* **[Skill 編寫最佳實踐](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**：適用於 Claude 產品的編寫指導

932* **[Subagents](/zh-TW/sub-agents)**：委派任務給專門的代理932* **[Subagents](/docs/zh-TW/sub-agents)**：委派任務給專門的代理

933* **[Plugins](/zh-TW/plugins)**：使用其他擴展功能打包和分發 skills933* **[Plugins](/docs/zh-TW/plugins)**：使用其他擴展功能打包和分發 skills

934* **[Hooks](/zh-TW/hooks)**：自動化工具事件周圍的工作流程934* **[Hooks](/docs/zh-TW/hooks)**：自動化工具事件周圍的工作流程

935* **[Memory](/zh-TW/memory)**：管理 CLAUDE.md 檔案以取得持久上下文935* **[Memory](/docs/zh-TW/memory)**：管理 CLAUDE.md 檔案以取得持久上下文

936* **[Commands](/zh-TW/commands)**：內建命令和捆綁 skills 的參考936* **[Commands](/docs/zh-TW/commands)**：內建命令和捆綁 skills 的參考

937* **[Permissions](/zh-TW/permissions)**：控制工具和 skill 存取937* **[Permissions](/docs/zh-TW/permissions)**：控制工具和 skill 存取

938* **[Claude Tag skills](https://claude.com/docs/claude-tag/admins/skills-repo)**：提交到儲存庫的專案 skills 在該儲存庫用於 Claude Tag 頻道時也會載入938* **[Claude Tag skills](https://claude.com/docs/claude-tag/admins/skills-repo)**：提交到儲存庫的專案 skills 在該儲存庫用於 Claude Tag 頻道時也會載入

statusline.md +11 −11

Details

15* 您跨多個工作階段工作，需要區分它們15* 您跨多個工作階段工作，需要區分它們

16* 您希望 git 分支和狀態始終可見16* 您希望 git 分支和狀態始終可見

17 17

18狀態列會在內建頁尾徽章上方的自己的列中呈現，不會取代它們。若要在對話中出現 ID 時在頁尾新增可點擊的連結徽章，而不需要撰寫指令碼，請改為設定 [`footerLinksRegexes`](/zh-TW/settings#footer-link-badges)。18狀態列會在內建頁尾徽章上方的自己的列中呈現，不會取代它們。若要在對話中出現 ID 時在頁尾新增可點擊的連結徽章，而不需要撰寫指令碼，請改為設定 [`footerLinksRegexes`](/docs/zh-TW/settings#footer-link-badges)。

19 19

20以下是一個[多行狀態列](#display-multiple-lines)的範例，在第一行顯示 git 資訊，在第二行顯示顏色編碼的 context 列。20以下是一個[多行狀態列](#display-multiple-lines)的範例，在第一行顯示 git 資訊，在第二行顯示顏色編碼的 context 列。

21 21

45 手動設定狀態列45 手動設定狀態列

46</h3>46</h3>

47 47

48將 `statusLine` 欄位新增到您的使用者設定（`~/.claude/settings.json`，其中 `~` 是您的主目錄）或[專案設定](/zh-TW/settings#settings-files)。將 `type` 設定為 `"command"`，並將 `command` 指向指令碼路徑或內聯 shell 命令。如需建立指令碼的完整逐步說明，請參閱[逐步建立狀態列](#build-a-status-line-step-by-step)。48將 `statusLine` 欄位新增到您的使用者設定（`~/.claude/settings.json`，其中 `~` 是您的主目錄）或[專案設定](/docs/zh-TW/settings#settings-files)。將 `type` 設定為 `"command"`，並將 `command` 指向指令碼路徑或內聯 shell 命令。如需建立指令碼的完整逐步說明，請參閱[逐步建立狀態列](#build-a-status-line-step-by-step)。

49 49

50```json theme={null}50```json theme={null}

51{51{

160 160

161**調整輸出大小以適應終端**161**調整輸出大小以適應終端**

162 162

163Claude Code 會擷取您指令碼的輸出，而不是直接將其連接到終端，因此 `tput cols` 和語言層級的寬度偵測無法從指令碼內部讀取終端大小。{/* min-version: 2.1.153 */}改為讀取 `COLUMNS` 和 `LINES` 環境變數。Claude Code 在執行您的指令碼之前會將這些設定為目前的終端尺寸。需要 Claude Code v2.1.153 或更新版本。163Claude Code 會擷取您指令碼的輸出，而不是直接將其連接到終端，因此 `tput cols` 和語言層級的寬度偵測無法從指令碼內部讀取終端大小。改為讀取 `COLUMNS` 和 `LINES` 環境變數。Claude Code 在執行您的指令碼之前會將這些設定為目前的終端尺寸。需要 Claude Code v2.1.153 或更新版本。

164 164

165<Note>狀態列在本地執行，不消耗 API 令牌。在某些 UI 互動期間，它會暫時隱藏，包括自動完成建議、說明功能表和權限提示。</Note>165<Note>狀態列在本地執行，不消耗 API 令牌。在某些 UI 互動期間，它會暫時隱藏，包括自動完成建議、說明功能表和權限提示。</Note>

166 166

171Claude Code 透過 stdin 將以下 JSON 欄位傳送到您的指令碼：171Claude Code 透過 stdin 將以下 JSON 欄位傳送到您的指令碼：

172 172

173| 欄位 | 描述 |173| 欄位 | 描述 |

174| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |174| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |

185| `context_window.total_input_tokens`, `context_window.total_output_tokens` | 目前在 context window 中的令牌計數，來自最近的 API 回應。輸入包括快取讀取和寫入。{/* min-version: 2.1.132 */}v2.1.132 之前這些是累積工作階段總計 |185| `context_window.total_input_tokens`, `context_window.total_output_tokens` | 目前在 context window 中的令牌計數，來自最近的 API 回應。輸入包括快取讀取和寫入。v2.1.132 之前這些是累積工作階段總計 |

197| `prompt_id` | 識別目前正在處理的使用者提示的 UUID。符合 [OpenTelemetry 事件上的 `prompt.id` 屬性](/zh-TW/monitoring-usage#event-correlation-attributes)。在第一次使用者輸入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本 |197| `prompt_id` | 識別目前正在處理的使用者提示的 UUID。符合 [OpenTelemetry 事件上的 `prompt.id` 屬性](/docs/zh-TW/monitoring-usage#event-correlation-attributes)。在第一次使用者輸入之前不存在。需要 Claude Code v2.1.196 或更新版本 |

201| `vim.mode` | 啟用 [vim 模式](/zh-TW/interactive-mode#vim-editor-mode)時的目前 vim 模式（`NORMAL`、`INSERT`、`VISUAL` 或 `VISUAL LINE`） |201| `vim.mode` | 啟用 [vim 模式](/docs/zh-TW/interactive-mode#vim-editor-mode)時的目前 vim 模式（`NORMAL`、`INSERT`、`VISUAL` 或 `VISUAL LINE`） |

332* `cache_creation_input_tokens`：寫入快取的令牌332* `cache_creation_input_tokens`：寫入快取的令牌

333* `cache_read_input_tokens`：從快取讀取的令牌333* `cache_read_input_tokens`：從快取讀取的令牌

334 334

335如需了解快取欄位的含義及其計費方式，請參閱[檢查快取效能](/zh-TW/prompt-caching#check-cache-performance)。335如需了解快取欄位的含義及其計費方式，請參閱[檢查快取效能](/docs/zh-TW/prompt-caching#check-cache-performance)。

336 336

337`used_percentage` 欄位僅從輸入令牌計算：`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`。它不包括 `output_tokens`。337`used_percentage` 欄位僅從輸入令牌計算：`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`。它不包括 `output_tokens`。

338 338

1029 子代理狀態列1029 子代理狀態列

1030</h2>1030</h2>

1031 1031

1032`subagentStatusLine` 設定為[子代理](/zh-TW/sub-agents)面板中顯示的每個子代理呈現自訂行主體。使用它來用您自己的格式化取代預設的 `name · description · token count` 行。1032`subagentStatusLine` 設定為[子代理](/docs/zh-TW/sub-agents)面板中顯示的每個子代理呈現自訂行主體。使用它來用您自己的格式化取代預設的 `name · description · token count` 行。

1033 1033

1034```json theme={null}1034```json theme={null}

1035{1035{

1040}1040}

1041```1041```

1042 1042

1043命令在每個重新整理刻度上執行一次，所有可見的子代理行作為單個 JSON 物件在 stdin 上傳遞。輸入包括[基本 hook 欄位](/zh-TW/hooks#common-input-fields)、`columns` 欄位（可用行寬度）和 `tasks` 陣列。每個任務具有 `id`、`name`、`type`、`status`、`description`、`label`、`startTime`、`model`、`contextWindowSize`、`tokenCount`、`tokenSamples` 和 `cwd`。1043命令在每個重新整理刻度上執行一次，所有可見的子代理行作為單個 JSON 物件在 stdin 上傳遞。輸入包括[基本 hook 欄位](/docs/zh-TW/hooks#common-input-fields)、`columns` 欄位（可用行寬度）和 `tasks` 陣列。每個任務具有 `id`、`name`、`type`、`status`、`description`、`label`、`startTime`、`model`、`contextWindowSize`、`tokenCount`、`tokenSamples` 和 `cwd`。

1044 1044

1045每個任務的 `model` 欄位是任務執行所在的已解析模型 ID。`contextWindowSize` 是該模型的內容視窗（以 token 計），計算方式與主狀態列的 `context_window.context_window_size` 相同，因此您可以從 `tokenCount` 呈現每行百分比。兩個欄位都需要 Claude Code v2.1.205 或更新版本，並且對於模型尚未解析的任務會被省略。1045每個任務的 `model` 欄位是任務執行所在的已解析模型 ID。`contextWindowSize` 是該模型的內容視窗（以 token 計），計算方式與主狀態列的 `context_window.context_window_size` 相同，因此您可以從 `tokenCount` 呈現每行百分比。兩個欄位都需要 Claude Code v2.1.205 或更新版本，並且對於模型尚未解析的任務會被省略。

1046 1046

1047將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。1047將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。

1048 1048

1049適用於 `statusLine` 的相同信任和 `disableAllHooks` 閘門也適用於此。外掛程式可以在其 [`settings.json`](/zh-TW/plugins-reference#standard-plugin-layout) 中提供預設 `subagentStatusLine`。1049適用於 `statusLine` 的相同信任和 `disableAllHooks` 閘門也適用於此。外掛程式可以在其 [`settings.json`](/docs/zh-TW/plugins-reference#standard-plugin-layout) 中提供預設 `subagentStatusLine`。

1050 1050

1051<h2 id="tips">1051<h2 id="tips">

1052 提示1052 提示

sub-agents.md +88 −88

Details

8 8

9Subagents 是專門的 AI 助手，用於處理特定類型的任務。當側面任務會用搜尋結果、日誌或檔案內容淹沒您的主要對話時，請使用一個 subagent，而您不會再次參考這些內容：subagent 在自己的上下文中執行該工作，並僅返回摘要。當您持續產生相同類型的工作者並使用相同指令時，定義自訂 subagent。9Subagents 是專門的 AI 助手，用於處理特定類型的任務。當側面任務會用搜尋結果、日誌或檔案內容淹沒您的主要對話時，請使用一個 subagent，而您不會再次參考這些內容：subagent 在自己的上下文中執行該工作，並僅返回摘要。當您持續產生相同類型的工作者並使用相同指令時，定義自訂 subagent。

10 10

11每個 subagent 在自己的 context window 中執行，具有自訂系統提示、特定工具存取和獨立權限。當 Claude 遇到與 subagent 描述相符的任務時，它會委派給該 subagent，該 subagent 獨立工作並返回結果。若要在實踐中查看上下文節省，[context window visualization](/zh-TW/context-window) 會逐步說明一個 subagent 在自己的獨立視窗中處理研究的工作階段。11每個 subagent 在自己的 context window 中執行，具有自訂系統提示、特定工具存取和獨立權限。當 Claude 遇到與 subagent 描述相符的任務時，它會委派給該 subagent，該 subagent 獨立工作並返回結果。若要在實踐中查看上下文節省，[context window visualization](/docs/zh-TW/context-window) 會逐步說明一個 subagent 在自己的獨立視窗中處理研究的工作階段。

12 12

13<Note>13<Note>

14 Subagents 在單一工作階段內工作。若要執行許多獨立工作階段並行並從一個地方監控它們，請參閱 [background agents](/zh-TW/agent-view)。對於相互通訊的工作階段，請參閱 [agent teams](/zh-TW/agent-teams)。14 Subagents 在單一工作階段內工作。若要執行許多獨立工作階段並行並從一個地方監控它們，請參閱 [background agents](/docs/zh-TW/agent-view)。對於相互通訊的工作階段，請參閱 [agent teams](/docs/zh-TW/agent-teams)。

15</Note>15</Note>

16 16

17Subagents 可以幫助您：17Subagents 可以幫助您：

42 * **Tools**：唯讀工具；Write 和 Edit 被拒絕42 * **Tools**：唯讀工具；Write 和 Edit 被拒絕

43 * **Purpose**：檔案發現、程式碼搜尋、程式碼庫探索43 * **Purpose**：檔案發現、程式碼搜尋、程式碼庫探索

44 44

45 {/* min-version: 2.1.198 */}自 v2.1.198 起，Explore 繼承主要對話的模型，而不是始終在 Haiku 上執行。在 Claude API 上，繼承的模型限制為 Opus：主要對話在更高層級上會在 Opus 上執行 Explore，而主要對話在 Sonnet 或 Haiku 上會在相同模型上執行 Explore。在任何其他提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform](/zh-TW/third-party-integrations)，Explore 直接繼承主要對話的模型。45 自 v2.1.198 起，Explore 繼承主要對話的模型，而不是始終在 Haiku 上執行。在 Claude API 上，繼承的模型限制為 Opus：主要對話在更高層級上會在 Opus 上執行 Explore，而主要對話在 Sonnet 或 Haiku 上會在相同模型上執行 Explore。在任何其他提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform](/docs/zh-TW/third-party-integrations)，Explore 直接繼承主要對話的模型。

46 46

47 一個名為 `Explore` 的[使用者或專案 subagent](#choose-the-subagent-scope) 會覆蓋內建的，並保留其自己的 `model` 欄位，因此定義一個具有 `model: haiku` 的以保持探索在較低成本的模型上。47 一個名為 `Explore` 的[使用者或專案 subagent](#choose-the-subagent-scope) 會覆蓋內建的，並保留其自己的 `model` 欄位，因此定義一個具有 `model: haiku` 的以保持探索在較低成本的模型上。

48 48

52 </Tab>52 </Tab>

53 53

54 <Tab title="Plan">54 <Tab title="Plan">

~~55 一個研究代理，在 [plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 期間使用，以在呈現計畫之前收集上下文。~~55 一個研究代理，在 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 期間使用，以在呈現計畫之前收集上下文。

56 56

57 * **Model**：從主要對話繼承57 * **Model**：從主要對話繼承

58 * **Tools**：唯讀工具（拒絕存取 Write 和 Edit 工具）58 * **Tools**：唯讀工具（拒絕存取 Write 和 Edit 工具）

84內建 subagents 在互動式工作階段中預設會被註冊。若要限制它們：84內建 subagents 在互動式工作階段中預設會被註冊。若要限制它們：

85 85

86* 若要封鎖特定的內建類型，請將其新增至 `permissions.deny`，如[停用特定 subagents](#disable-specific-subagents) 中所示。86* 若要封鎖特定的內建類型，請將其新增至 `permissions.deny`，如[停用特定 subagents](#disable-specific-subagents) 中所示。

~~87* 若要防止 Claude 委派給任何 subagent，請使用 [`permissions.deny`](/zh-TW/permissions#tool-specific-permission-rules) 拒絕 `Agent` 工具本身。~~87* 若要防止 Claude 委派給任何 subagent，請使用 [`permissions.deny`](/docs/zh-TW/permissions#tool-specific-permission-rules) 拒絕 `Agent` 工具本身。

88* {/* min-version: 2.1.198 */}若要僅移除內建的 `Explore` 和 `Plan` subagents，請設定 [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/zh-TW/env-vars)。Claude 會直接讀取和探索檔案，而不是委派給它們。需要 Claude Code v2.1.198 或更新版本。88* 若要僅移除內建的 `Explore` 和 `Plan` subagents，請設定 [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/docs/zh-TW/env-vars)。Claude 會直接讀取和探索檔案，而不是委派給它們。需要 Claude Code v2.1.198 或更新版本。

89* 在[非互動式模式](/zh-TW/headless)和 [Agent SDK](/zh-TW/agent-sdk/overview) 中，設定 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/zh-TW/env-vars) 以移除所有內建類型，並僅提供您自己的。89* 在[非互動式模式](/docs/zh-TW/headless)和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中，設定 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/docs/zh-TW/env-vars) 以移除所有內建類型，並僅提供您自己的。

90 90

91除了這些內建 subagents 之外，您可以建立自己的 subagents，具有自訂提示、工具限制、權限模式、hooks 和 skills。以下部分展示如何開始和自訂 subagents。91除了這些內建 subagents 之外，您可以建立自己的 subagents，具有自訂提示、工具限制、權限模式、hooks 和 skills。以下部分展示如何開始和自訂 subagents。

92 92

96 96

97Subagents 是具有 YAML frontmatter 的 Markdown 檔案。若要建立一個，請要求 Claude 為您撰寫，或 [自行撰寫檔案](#write-subagent-files)。97Subagents 是具有 YAML frontmatter 的 Markdown 檔案。若要建立一個，請要求 Claude 為您撰寫，或 [自行撰寫檔案](#write-subagent-files)。

98 98

99{/* min-version: 2.1.198 */}自 v2.1.198 起，`/agents` 命令不再開啟互動式建立精靈；執行它會列印提醒，要求您詢問 Claude 或直接編輯 `.claude/agents/`。Subagent 檔案、frontmatter 欄位以及 `.claude/agents/` 和 `~/.claude/agents/` 位置保持不變；只有終端精靈被移除。99自 v2.1.198 起，`/agents` 命令不再開啟互動式建立精靈；執行它會列印提醒，要求您詢問 Claude 或直接編輯 `.claude/agents/`。Subagent 檔案、frontmatter 欄位以及 `.claude/agents/` 和 `~/.claude/agents/` 位置保持不變；只有終端精靈被移除。

100 100

101本逐步指南建立一個使用者層級的 subagent，用於審查程式碼並提出改進建議。101本逐步指南建立一個使用者層級的 subagent，用於審查程式碼並提出改進建議。

102 102

150您也可以手動撰寫 subagent 檔案、透過 CLI 旗標定義它們，或透過外掛程式分發它們。以下部分涵蓋所有配置選項。150您也可以手動撰寫 subagent 檔案、透過 CLI 旗標定義它們，或透過外掛程式分發它們。以下部分涵蓋所有配置選項。

151 151

152<Note>152<Note>

153 在 Claude Code v2.1.197 及更早版本上，`/agents` 開啟一個互動式精靈，其中包含列出即時 subagents 的 **Running** 標籤和用於建立、編輯和刪除它們的 **Library** 標籤。{/* max-version: 2.1.197 */}153 在 Claude Code v2.1.197 及更早版本上，`/agents` 開啟一個互動式精靈，其中包含列出即時 subagents 的 **Running** 標籤和用於建立、編輯和刪除它們的 **Library** 標籤。

154</Note>154</Note>

155 155

156<h2 id="configure-subagents">156<h2 id="configure-subagents">

167 167

169| :-------------------- | :-------- | :------- | :---------------------------------------- |169| :-------------------- | :-------- | :------- | :---------------------------------------- |

170| 受管設定 | 組織範圍 | 1（最高） | 透過 [managed settings](/zh-TW/settings) 部署 |170| 受管設定 | 組織範圍 | 1（最高） | 透過 [managed settings](/docs/zh-TW/settings) 部署 |

175 175

176**專案 subagents**（`.claude/agents/`）非常適合特定於程式碼庫的 subagents。將它們簽入版本控制，以便您的團隊可以協作使用和改進它們。176**專案 subagents**（`.claude/agents/`）非常適合特定於程式碼庫的 subagents。將它們簽入版本控制，以便您的團隊可以協作使用和改進它們。

177 177

178專案 subagents 是透過從目前工作目錄向上走來發現的，因此會掃描那裡和儲存庫根目錄之間的每個 `.claude/agents/`。{/* min-version: 2.1.178 */}自 v2.1.178 起，當這些巢狀目錄中的多個定義相同的 `name` 時，Claude Code 使用最接近工作目錄的定義。178專案 subagents 是透過從目前工作目錄向上走來發現的，因此會掃描那裡和儲存庫根目錄之間的每個 `.claude/agents/`。自 v2.1.178 起，當這些巢狀目錄中的多個定義相同的 `name` 時，Claude Code 使用最接近工作目錄的定義。

179 179

180使用 `--add-dir` 新增的目錄也會被掃描：新增目錄內的 `.claude/agents/` 資料夾與專案 subagents 一起載入。請參閱 [Additional directories](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 以了解哪些其他配置類型從 `--add-dir` 載入。若要跨專案共享 subagents 而不使用 `--add-dir`，請使用 `~/.claude/agents/` 或 [plugin](/zh-TW/plugins)。180使用 `--add-dir` 新增的目錄也會被掃描：新增目錄內的 `.claude/agents/` 資料夾與專案 subagents 一起載入。請參閱 [Additional directories](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 以了解哪些其他配置類型從 `--add-dir` 載入。若要跨專案共享 subagents 而不使用 `--add-dir`，請使用 `~/.claude/agents/` 或 [plugin](/docs/zh-TW/plugins)。

181 181

182**使用者 subagents**（`~/.claude/agents/`）是在所有專案中可用的個人 subagents。182**使用者 subagents**（`~/.claude/agents/`）是在所有專案中可用的個人 subagents。

183 183

184Claude Code 會遞迴掃描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以將定義組織到子資料夾中，例如 `agents/review/` 或 `agents/research/`。子目錄路徑不會影響 subagent 的識別或呼叫方式，因為身份僅來自 `name` frontmatter 欄位。184Claude Code 會遞迴掃描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以將定義組織到子資料夾中，例如 `agents/review/` 或 `agents/research/`。子目錄路徑不會影響 subagent 的識別或呼叫方式，因為身份僅來自 `name` frontmatter 欄位。

185 185

186在整個樹中保持 `name` 值唯一：如果一個 `.claude/agents/` 目錄下的兩個檔案（包括其子資料夾）宣告相同的名稱，Claude Code 只會載入其中一個，由檔案系統讀取順序選擇，而不是有文件記載的優先級。在巢狀專案目錄中，最接近工作目錄的定義獲勝，如上所述。{/* min-version: 2.1.205 */}[`/doctor`](/zh-TW/commands#all-commands) 設定檢查會報告同一目錄中共享名稱的檔案，並建議重新命名或移除除一個以外的所有檔案。在 v2.1.205 之前，`/doctor` 開啟診斷畫面，列出重複項並顯示哪個定義處於活動狀態。186在整個樹中保持 `name` 值唯一：如果一個 `.claude/agents/` 目錄下的兩個檔案（包括其子資料夾）宣告相同的名稱，Claude Code 只會載入其中一個，由檔案系統讀取順序選擇，而不是有文件記載的優先級。在巢狀專案目錄中，最接近工作目錄的定義獲勝，如上所述。[`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查會報告同一目錄中共享名稱的檔案，並建議重新命名或移除除一個以外的所有檔案。在 v2.1.205 之前，`/doctor` 開啟診斷畫面，列出重複項並顯示哪個定義處於活動狀態。

187 187

188外掛程式 `agents/` 目錄也會遞迴掃描。與專案和使用者範圍不同，外掛程式 `agents/` 目錄內的子資料夾成為 [scoped identifier](#invoke-subagents-explicitly) 的一部分：外掛程式 `my-plugin` 中位於 `agents/review/security.md` 的檔案註冊為 `my-plugin:review:security`。188外掛程式 `agents/` 目錄也會遞迴掃描。與專案和使用者範圍不同，外掛程式 `agents/` 目錄內的子資料夾成為 [scoped identifier](#invoke-subagents-explicitly) 的一部分：外掛程式 `my-plugin` 中位於 `agents/review/security.md` 的檔案註冊為 `my-plugin:review:security`。

189 189

229 229

230`--agents` 標誌接受 JSON，具有與基於檔案的 subagents 相同的 [frontmatter](#supported-frontmatter-fields) 欄位：`description`、`prompt`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`isolation` 和 `color`。使用 `prompt` 作為系統提示，等同於基於檔案的 subagents 中的 markdown 主體。230`--agents` 標誌接受 JSON，具有與基於檔案的 subagents 相同的 [frontmatter](#supported-frontmatter-fields) 欄位：`description`、`prompt`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`isolation` 和 `color`。使用 `prompt` 作為系統提示，等同於基於檔案的 subagents 中的 markdown 主體。

231 231

232**受管 subagents** 由組織管理員部署。將 markdown 檔案放在 [managed settings directory](/zh-TW/settings#settings-files) 內的 `.claude/agents/` 中，使用與專案和使用者 subagents 相同的 frontmatter 格式。受管定義優先於具有相同名稱的專案和使用者 subagents。232**受管 subagents** 由組織管理員部署。將 markdown 檔案放在 [managed settings directory](/docs/zh-TW/settings#settings-files) 內的 `.claude/agents/` 中，使用與專案和使用者 subagents 相同的 frontmatter 格式。受管定義優先於具有相同名稱的專案和使用者 subagents。

233 233

234**外掛程式 subagents** 來自您已安裝的 [plugins](/zh-TW/plugins)。它們與您的自訂 subagents 一起載入，並在 @-mention 類型提前中以其範圍名稱出現。請參閱 [plugin components reference](/zh-TW/plugins-reference#agents) 以了解建立外掛程式 subagents 的詳細資訊。234**外掛程式 subagents** 來自您已安裝的 [plugins](/docs/zh-TW/plugins)。它們與您的自訂 subagents 一起載入，並在 @-mention 類型提前中以其範圍名稱出現。請參閱 [plugin components reference](/docs/zh-TW/plugins-reference#agents) 以了解建立外掛程式 subagents 的詳細資訊。

235 235

236<Note>236<Note>

237 基於安全考慮，外掛程式 subagents 不支援 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 欄位。從外掛程式載入代理時，這些欄位會被忽略。如果您需要它們，請將代理檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中的 [`permissions.allow`](/zh-TW/settings#permission-settings) 新增規則，但這些規則適用於整個工作階段，而不僅僅是外掛程式 subagent。237 基於安全考慮，外掛程式 subagents 不支援 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 欄位。從外掛程式載入代理時，這些欄位會被忽略。如果您需要它們，請將代理檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中的 [`permissions.allow`](/docs/zh-TW/settings#permission-settings) 新增規則，但這些規則適用於整個工作階段，而不僅僅是外掛程式 subagent。

238</Note>238</Note>

239 239

240來自任何這些範圍的 subagent 定義也可用於 [agent teams](/zh-TW/agent-teams#use-subagent-definitions-for-teammates)：當產生隊友時，您可以參考 subagent 類型，隊友會使用其 `tools` 和 `model`，定義的主體作為額外指令附加到隊友的系統提示。請參閱 [agent teams](/zh-TW/agent-teams#use-subagent-definitions-for-teammates) 以了解哪些 frontmatter 欄位適用於該路徑。240來自任何這些範圍的 subagent 定義也可用於 [agent teams](/docs/zh-TW/agent-teams#use-subagent-definitions-for-teammates)：當產生隊友時，您可以參考 subagent 類型，隊友會使用其 `tools` 和 `model`，定義的主體作為額外指令附加到隊友的系統提示。請參閱 [agent teams](/docs/zh-TW/agent-teams#use-subagent-definitions-for-teammates) 以了解哪些 frontmatter 欄位適用於該路徑。

241 241

242<h3 id="write-subagent-files">242<h3 id="write-subagent-files">

243 編寫 subagent 檔案243 編寫 subagent 檔案

268 268

269Frontmatter 定義 subagent 的中繼資料和配置。主體成為指導 subagent 行為的系統提示。Subagents 只接收此系統提示（加上基本環境詳細資訊，如工作目錄），而不是完整的 Claude Code 系統提示。269Frontmatter 定義 subagent 的中繼資料和配置。主體成為指導 subagent 行為的系統提示。Subagents 只接收此系統提示（加上基本環境詳細資訊，如工作目錄），而不是完整的 Claude Code 系統提示。

270 270

271在 [non-interactive mode](/zh-TW/headless) 中，[`--append-subagent-system-prompt`](/zh-TW/cli-reference#cli-flags) 標誌將您提供的文字附加到每個 subagent 的系統提示末尾，包括巢狀 subagents。需要 Claude Code v2.1.205 或更高版本。271在 [non-interactive mode](/docs/zh-TW/headless) 中，[`--append-subagent-system-prompt`](/docs/zh-TW/cli-reference#cli-flags) 標誌將您提供的文字附加到每個 subagent 的系統提示末尾，包括巢狀 subagents。需要 Claude Code v2.1.205 或更高版本。

272 272

273一個 subagent 在主要對話的目前工作目錄中啟動。在 subagent 內，`cd` 命令不會在 Bash 或 PowerShell 工具呼叫之間持續，也不會影響主要對話的工作目錄。若要改為給 subagent 儲存庫的隔離副本，請設定 [`isolation: worktree`](#supported-frontmatter-fields)。273一個 subagent 在主要對話的目前工作目錄中啟動。在 subagent 內，`cd` 命令不會在 Bash 或 PowerShell 工具呼叫之間持續，也不會影響主要對話的工作目錄。若要改為給 subagent 儲存庫的隔離副本，請設定 [`isolation: worktree`](#supported-frontmatter-fields)。

274 274

275{/* min-version: 2.1.203 */}具有 `isolation: worktree` 的 subagent 在其 worktree 內執行其 Bash 和 PowerShell 命令。一個工作目錄解析到您的主要簽出的命令（例如，因為 subagent 執行時 worktree 目錄被移除）會失敗並出現錯誤。在 v2.1.203 之前，此類命令可能在主要簽出中執行。275具有 `isolation: worktree` 的 subagent 在其 worktree 內執行其 Bash 和 PowerShell 命令。一個工作目錄解析到您的主要簽出的命令（例如，因為 subagent 執行時 worktree 目錄被移除）會失敗並出現錯誤。在 v2.1.203 之前，此類命令可能在主要簽出中執行。

276 276

277<h4 id="supported-frontmatter-fields">277<h4 id="supported-frontmatter-fields">

278 支援的 frontmatter 欄位278 支援的 frontmatter 欄位

281以下欄位可用於 YAML frontmatter。只有 `name` 和 `description` 是必需的。281以下欄位可用於 YAML frontmatter。只有 `name` 和 `description` 是必需的。

282 282

283| Field | 必需 | Description |283| Field | 必需 | Description |

284| :---------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |284| :---------------- | :- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

285| `name` | 是 | 使用小寫字母和連字號的唯一識別碼。[Hooks](/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符 |285| `name` | 是 | 使用小寫字母和連字號的唯一識別碼。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符 |

286| `description` | 是 | Claude 何時應委派給此 subagent |286| `description` | 是 | Claude 何時應委派給此 subagent |

287| `tools` | 否 | [Tools](#available-tools) subagent 可以使用。如果省略，繼承所有工具。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |287| `tools` | 否 | [Tools](#available-tools) subagent 可以使用。如果省略，繼承所有工具。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |

288| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除 |288| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除 |

289| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-4-8`）或 `inherit`。預設為 `inherit` |289| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-4-8`）或 `inherit`。預設為 `inherit` |

290| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 {/* min-version: 2.1.200 */}`manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |290| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 `manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

291| `maxTurns` | 否 | subagent 停止前的最大代理轉數 |291| `maxTurns` | 否 | subagent 停止前的最大代理轉數 |

292| `skills` | 否 | [Skills](/zh-TW/skills) 在啟動時預載入到 subagent 的上下文中。注入完整技能內容，而不僅僅是描述。Subagents 仍然可以透過 Skill 工具呼叫未列出的專案、使用者和外掛程式技能 |292| `skills` | 否 | [Skills](/docs/zh-TW/skills) 在啟動時預載入到 subagent 的上下文中。注入完整技能內容，而不僅僅是描述。Subagents 仍然可以透過 Skill 工具呼叫未列出的專案、使用者和外掛程式技能 |

293| `mcpServers` | 否 | [MCP servers](/zh-TW/mcp) 可用於此 subagent。每個條目要麼是參考已配置伺服器的伺服器名稱（例如，`"slack"`），要麼是內聯定義，其中伺服器名稱為鍵，完整 [MCP server config](/zh-TW/mcp#installing-mcp-servers) 為值。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |293| `mcpServers` | 否 | [MCP servers](/docs/zh-TW/mcp) 可用於此 subagent。每個條目要麼是參考已配置伺服器的伺服器名稱（例如，`"slack"`），要麼是內聯定義，其中伺服器名稱為鍵，完整 [MCP server config](/docs/zh-TW/mcp#installing-mcp-servers) 為值。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

294| `hooks` | 否 | [Lifecycle hooks](#define-hooks-for-subagents) 限定於此 subagent。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |294| `hooks` | 否 | [Lifecycle hooks](#define-hooks-for-subagents) 限定於此 subagent。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

295| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。啟用跨工作階段學習 |295| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。啟用跨工作階段學習 |

296| `background` | 否 | 設定為 `true` 以始終將此 subagent 作為 [background task](#run-subagents-in-foreground-or-background) 執行，即使 Claude 需要其結果。未設定時，Claude 選擇，{/* min-version: 2.1.198 */}自 v2.1.198 起，它預設在背景執行 subagents |296| `background` | 否 | 設定為 `true` 以始終將此 subagent 作為 [background task](#run-subagents-in-foreground-or-background) 執行，即使 Claude 需要其結果。未設定時，Claude 選擇，自 v2.1.198 起，它預設在背景執行 subagents |

297| `effort` | 否 | 此 subagent 活動時的努力程度。覆蓋工作階段努力程度。預設：從工作階段繼承。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型 |297| `effort` | 否 | 此 subagent 活動時的努力程度。覆蓋工作階段努力程度。預設：從工作階段繼承。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型 |

298| `isolation` | 否 | 設定為 `worktree` 以在臨時 [git worktree](/zh-TW/worktrees) 中執行 subagent，為其提供儲存庫的隔離副本，預設從您的 [default branch](/zh-TW/worktrees#choose-the-base-branch) 分支，而不是父工作階段的 `HEAD`。如果 subagent 不進行任何更改，worktree 會自動清理 |298| `isolation` | 否 | 設定為 `worktree` 以在臨時 [git worktree](/docs/zh-TW/worktrees) 中執行 subagent，為其提供儲存庫的隔離副本，預設從您的 [default branch](/docs/zh-TW/worktrees#choose-the-base-branch) 分支，而不是父工作階段的 `HEAD`。如果 subagent 不進行任何更改，worktree 會自動清理 |

299| `color` | 否 | Subagent 在任務清單和文字中的顯示顏色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |299| `color` | 否 | Subagent 在任務清單和文字中的顯示顏色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |

300| `initialPrompt` | 否 | 當此代理作為主工作階段代理執行時（透過 `--agent` 或 `agent` 設定），自動提交為第一個使用者轉數。[Commands](/zh-TW/commands) 和 [skills](/zh-TW/skills) 會被處理。前置於任何使用者提供的提示 |300| `initialPrompt` | 否 | 當此代理作為主工作階段代理執行時（透過 `--agent` 或 `agent` 設定），自動提交為第一個使用者轉數。[Commands](/docs/zh-TW/commands) 和 [skills](/docs/zh-TW/skills) 會被處理。前置於任何使用者提供的提示 |

301 301

302<h3 id="choose-a-model">302<h3 id="choose-a-model">

303 選擇模型303 選擇模型

304</h3>304</h3>

305 305

306`model` 欄位控制 subagent 使用的 [AI model](/zh-TW/model-config)：306`model` 欄位控制 subagent 使用的 [AI model](/docs/zh-TW/model-config)：

307 307

308* **Model alias**：使用可用的別名之一：`sonnet`、`opus`、`haiku` 或 `fable`308* **Model alias**：使用可用的別名之一：`sonnet`、`opus`、`haiku` 或 `fable`

309* **Full model ID**：使用完整模型 ID，例如 `claude-opus-4-8` 或 `claude-sonnet-5`。接受與 `--model` 標誌相同的值309* **Full model ID**：使用完整模型 ID，例如 `claude-opus-4-8` 或 `claude-sonnet-5`。接受與 `--model` 標誌相同的值

312 312

313當 Claude 呼叫 subagent 時，它也可以為該特定呼叫傳遞 `model` 參數。Claude Code 按此順序解析 subagent 的模型：313當 Claude 呼叫 subagent 時，它也可以為該特定呼叫傳遞 `model` 參數。Claude Code 按此順序解析 subagent 的模型：

314 314

3151. [`CLAUDE_CODE_SUBAGENT_MODEL`](/zh-TW/model-config#environment-variables) 環境變數（如果設定為模型別名或模型 ID）3151. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-TW/model-config#environment-variables) 環境變數（如果設定為模型別名或模型 ID）

3162. 每次呼叫的 `model` 參數3162. 每次呼叫的 `model` 參數

3173. Subagent 定義的 `model` frontmatter3173. Subagent 定義的 `model` frontmatter

3184. 主要對話的模型3184. 主要對話的模型

319 319

320{/* min-version: 2.1.196 */}自 v2.1.196 起，將 `CLAUDE_CODE_SUBAGENT_MODEL` 設定為 `inherit` 與不設定相同：解析繼續進行每次呼叫的 `model` 參數，然後是 frontmatter。在較早的版本中，`inherit` 強制 subagents 使用主要對話的模型，並忽略這兩個來源。320自 v2.1.196 起，將 `CLAUDE_CODE_SUBAGENT_MODEL` 設定為 `inherit` 與不設定相同：解析繼續進行每次呼叫的 `model` 參數，然後是 frontmatter。在較早的版本中，`inherit` 強制 subagents 使用主要對話的模型，並忽略這兩個來源。

321 321

322環境變數、每次呼叫的參數和 frontmatter 值會根據您組織的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單進行檢查。解析為排除模型的值不會被使用，subagent 會改為在繼承的模型上執行。322環境變數、每次呼叫的參數和 frontmatter 值會根據您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單進行檢查。解析為排除模型的值不會被使用，subagent 會改為在繼承的模型上執行。

323 323

324{/* min-version: 2.1.198 */}自 v2.1.198 起，subagents 也繼承主要對話的 [extended thinking](/zh-TW/model-config#extended-thinking) 配置：如果思考在您的工作階段中開啟，它對 subagent 也開啟，如果關閉，它保持關閉。沒有每個 subagent 的思考設定。在 v2.1.198 之前，subagents 執行時禁用擴展思考，無論主要對話的設定如何。324自 v2.1.198 起，subagents 也繼承主要對話的 [extended thinking](/docs/zh-TW/model-config#extended-thinking) 配置：如果思考在您的工作階段中開啟，它對 subagent 也開啟，如果關閉，它保持關閉。沒有每個 subagent 的思考設定。在 v2.1.198 之前，subagents 執行時禁用擴展思考，無論主要對話的設定如何。

325 325

326<h3 id="control-subagent-capabilities">326<h3 id="control-subagent-capabilities">

327 控制 subagent 功能327 控制 subagent 功能

333 可用工具333 可用工具

334</h4>334</h4>

335 335

336Subagents 預設從主要對話繼承 [internal tools](/zh-TW/tools-reference) 和 MCP 工具。以下工具取決於主要對話的 UI 或工作階段狀態，即使在 `tools` 欄位中列出也不可用於 subagents：336Subagents 預設從主要對話繼承 [internal tools](/docs/zh-TW/tools-reference) 和 MCP 工具。以下工具取決於主要對話的 UI 或工作階段狀態，即使在 `tools` 欄位中列出也不可用於 subagents：

337 337

338* `AskUserQuestion`338* `AskUserQuestion`

339* `EnterPlanMode`339* `EnterPlanMode`

363 363

364如果兩者都設定，`disallowedTools` 首先應用，然後 `tools` 針對剩餘的池進行解析。同時列在兩者中的工具會被移除。364如果兩者都設定，`disallowedTools` 首先應用，然後 `tools` 針對剩餘的池進行解析。同時列在兩者中的工具會被移除。

365 365

366當 `tools` 清單中沒有任何內容解析為工具時（例如，因為每個條目都拼寫錯誤或命名一個對 subagents 不可用的工具），Claude Code 拒絕啟動 subagent，Agent 工具會傳回一個錯誤，命名未解析的條目。{/* min-version: 2.1.208 */}在 v2.1.208 之前，該 subagent 啟動時沒有工具，可能會傳回空的或令人困惑的結果。366當 `tools` 清單中沒有任何內容解析為工具時（例如，因為每個條目都拼寫錯誤或命名一個對 subagents 不可用的工具），Claude Code 拒絕啟動 subagent，Agent 工具會傳回一個錯誤，命名未解析的條目。在 v2.1.208 之前，該 subagent 啟動時沒有工具，可能會傳回空的或令人困惑的結果。

367 367

368兩個欄位都接受 MCP 伺服器層級的模式，除了確切的工具名稱：`mcp__<server>` 或 `mcp__<server>__*` 授予或移除來自命名伺服器的每個工具。在 `disallowedTools` 中，`mcp__*` 也會移除來自任何伺服器的每個 MCP 工具。此範例移除來自 `github` MCP 伺服器的每個工具，同時保留來自其他伺服器的工具和每個內建工具：368兩個欄位都接受 MCP 伺服器層級的模式，除了確切的工具名稱：`mcp__<server>` 或 `mcp__<server>__*` 授予或移除來自命名伺服器的每個工具。在 `disallowedTools` 中，`mcp__*` 也會移除來自任何伺服器的每個 MCP 工具。此範例移除來自 `github` MCP 伺服器的每個工具，同時保留來自其他伺服器的工具和每個內建工具：

369 369

407 將 MCP 伺服器限定於 subagent407 將 MCP 伺服器限定於 subagent

408</h4>408</h4>

409 409

410使用 `mcpServers` 欄位為 subagent 提供對主要對話中不可用的 [MCP](/zh-TW/mcp) 伺服器的存取。此處定義的內聯伺服器在 subagent 啟動時連接，在完成時斷開連接。字串參考共享父工作階段的連接。410使用 `mcpServers` 欄位為 subagent 提供對主要對話中不可用的 [MCP](/docs/zh-TW/mcp) 伺服器的存取。此處定義的內聯伺服器在 subagent 啟動時連接，在完成時斷開連接。字串參考共享父工作階段的連接。

411 411

412<Note>412<Note>

413 `mcpServers` 欄位適用於代理檔案可以執行的兩個上下文：413 `mcpServers` 欄位適用於代理檔案可以執行的兩個上下文：

415 * 作為 subagent，透過 Agent 工具或 @-mention 產生415 * 作為 subagent，透過 Agent 工具或 @-mention 產生

416 * 作為主工作階段，使用 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 設定啟動416 * 作為主工作階段，使用 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 設定啟動

417 417

418 當代理是主工作階段時，內聯伺服器定義在啟動時與來自 [`.mcp.json`](/zh-TW/mcp) 和設定檔案的伺服器一起連接。418 當代理是主工作階段時，內聯伺服器定義在啟動時與來自 [`.mcp.json`](/docs/zh-TW/mcp) 和設定檔案的伺服器一起連接。

419</Note>419</Note>

420 420

421清單中的每個條目要麼是內聯伺服器定義，要麼是參考工作階段中已配置的 MCP 伺服器的字串：421清單中的每個條目要麼是內聯伺服器定義，要麼是參考工作階段中已配置的 MCP 伺服器的字串：

443 443

444自 v2.1.153 起，適用於主工作階段的 MCP 限制也涵蓋在 subagent frontmatter 中宣告的伺服器：444自 v2.1.153 起，適用於主工作階段的 MCP 限制也涵蓋在 subagent frontmatter 中宣告的伺服器：

445 445

446* [`--strict-mcp-config`](/zh-TW/cli-reference) 和 [`--bare`](/zh-TW/cli-reference)446* [`--strict-mcp-config`](/docs/zh-TW/cli-reference) 和 [`--bare`](/docs/zh-TW/cli-reference)

447* [Enterprise managed MCP configuration](/zh-TW/managed-mcp)447* [Enterprise managed MCP configuration](/docs/zh-TW/managed-mcp)

448* [`allowedMcpServers` 和 `deniedMcpServers` 政策](/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists)448* [`allowedMcpServers` 和 `deniedMcpServers` 政策](/docs/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists)

449 449

450當其中之一阻止伺服器時，Claude Code 會跳過它並顯示警告，命名被阻止的伺服器。450當其中之一阻止伺服器時，Claude Code 會跳過它並顯示警告，命名被阻止的伺服器。

451 451

461| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |461| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

465| `dontAsk` | 自動拒絕權限提示。明確允許的工具仍然工作；`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使您已允許它們也會被拒絕 |465| `dontAsk` | 自動拒絕權限提示。明確允許的工具仍然工作；`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使您已允許它們也會被拒絕 |

468 468

469<Warning>469<Warning>

470 謹慎使用 `bypassPermissions`。它跳過權限提示，允許 subagent 執行操作而無需批准，包括寫入 `.git`、`.config/git`、`.claude`、`.vscode`、`.idea`、`.husky`、`.cargo`、`.devcontainer`、`.yarn` 和 `.mvn`。470 謹慎使用 `bypassPermissions`。它跳過權限提示，允許 subagent 執行操作而無需批准，包括寫入 `.git`、`.config/git`、`.claude`、`.vscode`、`.idea`、`.husky`、`.cargo`、`.devcontainer`、`.yarn` 和 `.mvn`。

471 471

472 明確的 [`ask` 規則](/zh-TW/permissions#manage-permissions)、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools)、標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及根和主目錄移除（例如 `rm -rf /`）仍然會提示。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) 以了解詳細資訊。472 明確的 [`ask` 規則](/docs/zh-TW/permissions#manage-permissions)、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及根和主目錄移除（例如 `rm -rf /`）仍然會提示。請參閱 [permission modes](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) 以了解詳細資訊。

473</Warning>473</Warning>

474 474

475如果父級使用 `bypassPermissions` 或 `acceptEdits`，這優先並且無法被覆蓋。如果父級使用 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，subagent 繼承 auto mode，其 frontmatter 中的任何 `permissionMode` 都會被忽略：分類器使用與父工作階段相同的阻止和允許規則評估 subagent 的工具呼叫。475如果父級使用 `bypassPermissions` 或 `acceptEdits`，這優先並且無法被覆蓋。如果父級使用 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，subagent 繼承 auto mode，其 frontmatter 中的任何 `permissionMode` 都會被忽略：分類器使用與父工作階段相同的阻止和允許規則評估 subagent 的工具呼叫。

476 476

477<h4 id="preload-skills-into-subagents">477<h4 id="preload-skills-into-subagents">

478 將技能預載入 subagents478 將技能預載入 subagents

494 494

495每個列出的技能的完整內容被注入到 subagent 的上下文中。此欄位控制哪些技能被預載入，而不是 subagent 可以存取哪些技能：沒有它，subagent 仍然可以在執行期間透過 Skill 工具發現和呼叫專案、使用者和外掛程式技能。若要防止 subagent 完全呼叫技能，請從 [`tools`](#available-tools) 清單中省略 `Skill` 或將其新增到 `disallowedTools`。495每個列出的技能的完整內容被注入到 subagent 的上下文中。此欄位控制哪些技能被預載入，而不是 subagent 可以存取哪些技能：沒有它，subagent 仍然可以在執行期間透過 Skill 工具發現和呼叫專案、使用者和外掛程式技能。若要防止 subagent 完全呼叫技能，請從 [`tools`](#available-tools) 清單中省略 `Skill` 或將其新增到 `disallowedTools`。

496 496

497您無法預載入設定 [`disable-model-invocation: true`](/zh-TW/skills#control-who-invokes-a-skill) 的技能，因為預載入來自 Claude 可以呼叫的相同技能集。如果列出的技能遺失或已停用，Claude Code 會跳過它並將警告記錄到除錯日誌。497您無法預載入設定 [`disable-model-invocation: true`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的技能，因為預載入來自 Claude 可以呼叫的相同技能集。如果列出的技能遺失或已停用，Claude Code 會跳過它並將警告記錄到除錯日誌。

498 498

499<Note>499<Note>

500 這與 [在 subagent 中執行技能](/zh-TW/skills#run-skills-in-a-subagent) 相反。使用 subagent 中的 `skills`，subagent 控制系統提示並載入技能內容。使用技能中的 `context: fork`，技能內容被注入到您指定的代理中。兩者都使用相同的基礎系統。500 這與 [在 subagent 中執行技能](/docs/zh-TW/skills#run-skills-in-a-subagent) 相反。使用 subagent 中的 `skills`，subagent 控制系統提示並載入技能內容。使用技能中的 `context: fork`，技能內容被注入到您指定的代理中。兩者都使用相同的基礎系統。

501</Note>501</Note>

502 502

503<h4 id="enable-persistent-memory">503<h4 id="enable-persistent-memory">

569---569---

570```570```

571 571

572Claude Code [透過 stdin 將 hook 輸入作為 JSON 傳遞](/zh-TW/hooks#pretooluse-input) 給 hook 命令。驗證指令碼讀取此 JSON，提取 Bash 命令，並 [以代碼 2 退出](/zh-TW/hooks#exit-code-2-behavior-per-event) 以阻止寫入操作：572Claude Code [透過 stdin 將 hook 輸入作為 JSON 傳遞](/docs/zh-TW/hooks#pretooluse-input) 給 hook 命令。驗證指令碼讀取此 JSON，提取 Bash 命令，並 [以代碼 2 退出](/docs/zh-TW/hooks#exit-code-2-behavior-per-event) 以阻止寫入操作：

573 573

574```bash theme={null}574```bash theme={null}

575#!/bin/bash575#!/bin/bash

587exit 0587exit 0

588```588```

589 589

590請參閱 [Hook input](/zh-TW/hooks#pretooluse-input) 以了解完整的輸入架構，以及 [exit codes](/zh-TW/hooks#exit-code-output) 以了解退出代碼如何影響行為。在 Windows 上，在 PowerShell 中編寫 hook 指令碼，並在 hook 條目中新增 `shell: powershell`，如 [在 PowerShell 中執行 hooks](/zh-TW/hooks#windows-powershell-tool) 所示。590請參閱 [Hook input](/docs/zh-TW/hooks#pretooluse-input) 以了解完整的輸入架構，以及 [exit codes](/docs/zh-TW/hooks#exit-code-output) 以了解退出代碼如何影響行為。在 Windows 上，在 PowerShell 中編寫 hook 指令碼，並在 hook 條目中新增 `shell: powershell`，如 [在 PowerShell 中執行 hooks](/docs/zh-TW/hooks#windows-powershell-tool) 所示。

591 591

592<h4 id="disable-specific-subagents">592<h4 id="disable-specific-subagents">

593 禁用特定 subagents593 禁用特定 subagents

594</h4>594</h4>

595 595

596您可以透過將 subagents 新增到 [settings](/zh-TW/settings#permission-settings) 中的 `deny` 陣列來防止 Claude 使用特定 subagents。使用格式 `Agent(subagent-name)`，其中 `subagent-name` 與 subagent 的 name 欄位相符。596您可以透過將 subagents 新增到 [settings](/docs/zh-TW/settings#permission-settings) 中的 `deny` 陣列來防止 Claude 使用特定 subagents。使用格式 `Agent(subagent-name)`，其中 `subagent-name` 與 subagent 的 name 欄位相符。

597 597

598```json theme={null}598```json theme={null}

599{599{

609claude --disallowedTools "Agent(Explore)"609claude --disallowedTools "Agent(Explore)"

610```610```

611 611

612請參閱 [Permissions documentation](/zh-TW/permissions#tool-specific-permission-rules) 以了解有關權限規則的更多詳細資訊。612請參閱 [Permissions documentation](/docs/zh-TW/permissions#tool-specific-permission-rules) 以了解有關權限規則的更多詳細資訊。

613 613

614<h3 id="define-hooks-for-subagents">614<h3 id="define-hooks-for-subagents">

615 為 subagents 定義 hooks615 為 subagents 定義 hooks

616</h3>616</h3>

617 617

618Subagents 可以定義在 subagent 生命週期期間執行的 [hooks](/zh-TW/hooks)。有兩種方式來配置 hooks：618Subagents 可以定義在 subagent 生命週期期間執行的 [hooks](/docs/zh-TW/hooks)。有兩種方式來配置 hooks：

619 619

620* **在 subagent 的 frontmatter 中**：定義只在該 subagent 活動時執行的 hooks620* **在 subagent 的 frontmatter 中**：定義只在該 subagent 活動時執行的 hooks

621* **在 `settings.json` 中**：定義在 subagents 啟動或停止時在主工作階段中執行的 hooks621* **在 `settings.json` 中**：定義在 subagents 啟動或停止時在主工作階段中執行的 hooks

627直接在 subagent 的 markdown 檔案中定義 hooks。這些 hooks 只在該特定 subagent 活動時執行，並在完成時清理。627直接在 subagent 的 markdown 檔案中定義 hooks。這些 hooks 只在該特定 subagent 活動時執行，並在完成時清理。

628 628

629<Note>629<Note>

630 Frontmatter hooks 在代理透過 Agent 工具或 @-mention 作為 subagent 產生時觸發，以及當代理透過 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 設定作為主工作階段執行時觸發。在主工作階段情況下，它們與在 [`settings.json`](/zh-TW/hooks) 中定義的任何 hooks 一起執行。630 Frontmatter hooks 在代理透過 Agent 工具或 @-mention 作為 subagent 產生時觸發，以及當代理透過 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 設定作為主工作階段執行時觸發。在主工作階段情況下，它們與在 [`settings.json`](/docs/zh-TW/hooks) 中定義的任何 hooks 一起執行。

631</Note>631</Note>

632 632

633支援所有 [hook events](/zh-TW/hooks#hook-events)。subagents 最常見的事件是：633支援所有 [hook events](/docs/zh-TW/hooks#hook-events)。subagents 最常見的事件是：

634 634

636| :------------ | :------------ | :------------------------------------- |636| :------------ | :------------ | :------------------------------------- |

673 673

674兩個事件都支援匹配器以按名稱針對特定代理類型。匹配器值是專案層級和使用者層級 subagents 的代理 frontmatter `name`，或 [plugin subagents](/zh-TW/plugins) 的外掛程式範圍識別碼，例如 `my-plugin:db-agent`。範圍名稱包含冒號，因此它被評估為 [unanchored regular expression](/zh-TW/hooks#matcher-patterns)；使用 `^` 和 `$` 錨定它，如 `^my-plugin:db-agent$`，以僅匹配該代理。674兩個事件都支援匹配器以按名稱針對特定代理類型。匹配器值是專案層級和使用者層級 subagents 的代理 frontmatter `name`，或 [plugin subagents](/docs/zh-TW/plugins) 的外掛程式範圍識別碼，例如 `my-plugin:db-agent`。範圍名稱包含冒號，因此它被評估為 [unanchored regular expression](/docs/zh-TW/hooks#matcher-patterns)；使用 `^` 和 `$` 錨定它，如 `^my-plugin:db-agent$`，以僅匹配該代理。

675 675

676此範例僅在 `db-agent` subagent 啟動時執行設定指令碼，並在任何 subagent 停止時執行清理指令碼：676此範例僅在 `db-agent` subagent 啟動時執行設定指令碼，並在任何 subagent 停止時執行清理指令碼：

677 677

699 699

700連字號匹配器（如 `db-agent`）在 Claude Code v2.1.195 或更高版本上精確匹配。在較早的版本上，它被評估為 unanchored regular expression，也會針對任何包含它的代理類型觸發，例如 `prod-db-agent`；在這些版本上使用 `^db-agent$` 錨定它。700連字號匹配器（如 `db-agent`）在 Claude Code v2.1.195 或更高版本上精確匹配。在較早的版本上，它被評估為 unanchored regular expression，也會針對任何包含它的代理類型觸發，例如 `prod-db-agent`；在這些版本上使用 `^db-agent$` 錨定它。

701 701

702請參閱 [Hooks](/zh-TW/hooks) 以了解完整的 hook 配置格式。702請參閱 [Hooks](/docs/zh-TW/hooks) 以了解完整的 hook 配置格式。

703 703

704<h2 id="work-with-subagents">704<h2 id="work-with-subagents">

705 使用 subagents705 使用 subagents

736 736

737您的完整訊息仍然會傳送給 Claude，它根據您要求的內容為 subagent 編寫任務提示。@-mention 控制 Claude 呼叫哪個 subagent，而不是它接收什麼提示。737您的完整訊息仍然會傳送給 Claude，它根據您要求的內容為 subagent 編寫任務提示。@-mention 控制 Claude 呼叫哪個 subagent，而不是它接收什麼提示。

738 738

739由啟用的 [plugin](/zh-TW/plugins) 提供的 Subagents 在預輸入中顯示為其限定名稱，例如 `my-plugin:code-reviewer` 或 `my-plugin:review:security`（當 plugin [將 agents 組織到子資料夾](#choose-the-subagent-scope) 時）。名為背景 subagents 目前在工作階段中執行也出現在預輸入中，在名稱旁邊顯示其狀態。739由啟用的 [plugin](/docs/zh-TW/plugins) 提供的 Subagents 在預輸入中顯示為其限定名稱，例如 `my-plugin:code-reviewer` 或 `my-plugin:review:security`（當 plugin [將 agents 組織到子資料夾](#choose-the-subagent-scope) 時）。名為背景 subagents 目前在工作階段中執行也出現在預輸入中，在名稱旁邊顯示其狀態。

740 740

741您也可以手動輸入提及而不使用選擇器：`@agent-<name>` 用於本地 subagents，或 `@agent-` 後跟外掛程式 subagents 的限定名稱，例如 `@agent-my-plugin:code-reviewer`。741您也可以手動輸入提及而不使用選擇器：`@agent-<name>` 用於本地 subagents，或 `@agent-` 後跟外掛程式 subagents 的限定名稱，例如 `@agent-my-plugin:code-reviewer`。

742 742

743**將整個工作階段作為 subagent 執行。** 傳遞 [`--agent <name>`](/zh-TW/cli-reference) 以啟動一個工作階段，其中主執行緒本身採用該 subagent 的系統提示、工具限制和模型：743**將整個工作階段作為 subagent 執行。** 傳遞 [`--agent <name>`](/docs/zh-TW/cli-reference) 以啟動一個工作階段，其中主執行緒本身採用該 subagent 的系統提示、工具限制和模型：

744 744

745```bash theme={null}745```bash theme={null}

746claude --agent code-reviewer746claude --agent code-reviewer

747```747```

748 748

749Subagent 的系統提示完全替換預設 Claude Code 系統提示，就像 [`--system-prompt`](/zh-TW/cli-reference) 一樣。`CLAUDE.md` 檔案和專案記憶仍然透過正常訊息流載入。代理名稱在啟動標題中顯示為 `@<name>`，以便您可以確認它是活動的。749Subagent 的系統提示完全替換預設 Claude Code 系統提示，就像 [`--system-prompt`](/docs/zh-TW/cli-reference) 一樣。`CLAUDE.md` 檔案和專案記憶仍然透過正常訊息流載入。代理名稱在啟動標題中顯示為 `@<name>`，以便您可以確認它是活動的。

750 750

751這適用於內建和自訂 subagents，選擇在您恢復工作階段時持續。751這適用於內建和自訂 subagents，選擇在您恢復工作階段時持續。

752 752

781Subagents 可以在前景或背景中執行：781Subagents 可以在前景或背景中執行：

782 782

783* **前景 subagents** 阻止主要對話直到完成。權限提示會在出現時傳遞給您。783* **前景 subagents** 阻止主要對話直到完成。權限提示會在出現時傳遞給您。

784* **背景 subagents** 在您繼續工作時並行執行。{/* min-version: 2.1.186 */}自 v2.1.186 起，當背景 subagent 到達需要權限的工具呼叫時，提示會在您的主要工作階段中出現，並命名要求的 subagent。批准以讓 subagent 繼續，或按 Esc 拒絕該單一工具呼叫而不停止 subagent。在 v2.1.186 之前，背景 subagents 自動拒絕任何會提示的工具呼叫。784* **背景 subagents** 在您繼續工作時並行執行。自 v2.1.186 起，當背景 subagent 到達需要權限的工具呼叫時，提示會在您的主要工作階段中出現，並命名要求的 subagent。批准以讓 subagent 繼續，或按 Esc 拒絕該單一工具呼叫而不停止 subagent。在 v2.1.186 之前，背景 subagents 自動拒絕任何會提示的工具呼叫。

785 785

786{/* min-version: 2.1.198 */}自 v2.1.198 起，subagents 預設在背景中執行。Claude 在需要結果才能繼續時在前景中執行 subagent。預設值改變 subagent 執行的位置，而不是它被允許做什麼：背景 subagents 仍然在您的主要工作階段中出現每個權限提示。在 v2.1.198 之前，Claude 根據任務在前景和背景之間選擇。786自 v2.1.198 起，subagents 預設在背景中執行。Claude 在需要結果才能繼續時在前景中執行 subagent。預設值改變 subagent 執行的位置，而不是它被允許做什麼：背景 subagents 仍然在您的主要工作階段中出現每個權限提示。在 v2.1.198 之前，Claude 根據任務在前景和背景之間選擇。

787 787

788您也可以自己引導這個：788您也可以自己引導這個：

789 789

790* 要求 Claude 在背景或前景中執行任務790* 要求 Claude 在背景或前景中執行任務

791* 按 **Ctrl+B** 將執行中的任務放在背景中791* 按 **Ctrl+B** 將執行中的任務放在背景中

792 792

793{/* min-version: 2.1.208 */}完成的背景 subagent 保持列在 [`/tasks`](/zh-TW/commands) 中，標記為完成並排序在執行中的工作下方，直到工作階段清理其任務列表。當 subagent 完成時，其詳細檢視保持開啟。失敗或您停止的 Subagents 會離開列表。在 v2.1.208 之前，完成的 subagent 在完成時立即離開列表，其詳細檢視關閉。793完成的背景 subagent 保持列在 [`/tasks`](/docs/zh-TW/commands) 中，標記為完成並排序在執行中的工作下方，直到工作階段清理其任務列表。當 subagent 完成時，其詳細檢視保持開啟。失敗或您停止的 Subagents 會離開列表。在 v2.1.208 之前，完成的 subagent 在完成時立即離開列表，其詳細檢視關閉。

794 794

795若要禁用所有背景任務功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。請參閱 [Environment variables](/zh-TW/env-vars)。795若要禁用所有背景任務功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。請參閱 [Environment variables](/docs/zh-TW/env-vars)。

796 796

797當 [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) 設定為 `1` 時，每個 subagent 產生都在背景中執行，frontmatter `background` 欄位沒有效果，因為 fork 模式從 `Agent` 工具中移除 `run_in_background` 參數。`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 優先於 fork 模式，並將 subagent 產生保持在前景中。797當 [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) 設定為 `1` 時，每個 subagent 產生都在背景中執行，frontmatter `background` 欄位沒有效果，因為 fork 模式從 `Agent` 工具中移除 `run_in_background` 參數。`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 優先於 fork 模式，並將 subagent 產生保持在前景中。

798 798

800 Subagents 中的 API 錯誤800 Subagents 中的 API 錯誤

801</h3>801</h3>

802 802

803{/* min-version: 2.1.199 */}自 v2.1.199 起，subagent 的執行因 API 錯誤（例如使用限制或重複的伺服器錯誤）而結束時，會將該失敗報告回 Claude，而不是將錯誤文字作為 subagent 的發現返回。Claude 接收的內容取決於 subagent 執行的位置：803自 v2.1.199 起，subagent 的執行因 API 錯誤（例如使用限制或重複的伺服器錯誤）而結束時，會將該失敗報告回 Claude，而不是將錯誤文字作為 subagent 的發現返回。Claude 接收的內容取決於 subagent 執行的位置：

804 804

805* **前景**：如果速率限制、過載或伺服器錯誤切斷已經產生輸出的 subagent，Agent 工具會返回該部分輸出，並附註 subagent 被切斷且未完成其任務。{/* min-version: 2.1.200 */}未產生任何內容或其唯一輸出為工具呼叫的 subagent 會失敗，並顯示 [`Agent terminated early due to an API error`](/zh-TW/errors#agent-terminated-early-due-to-an-api-error)，後跟錯誤詳細資訊。在 v2.1.199 中，切斷工具呼叫專用形狀的速率限制、過載或伺服器錯誤返回了只包含切斷注記的空部分結果。805* **前景**：如果速率限制、過載或伺服器錯誤切斷已經產生輸出的 subagent，Agent 工具會返回該部分輸出，並附註 subagent 被切斷且未完成其任務。未產生任何內容或其唯一輸出為工具呼叫的 subagent 會失敗，並顯示 [`Agent terminated early due to an API error`](/docs/zh-TW/errors#agent-terminated-early-due-to-an-api-error)，後跟錯誤詳細資訊。在 v2.1.199 中，切斷工具呼叫專用形狀的速率限制、過載或伺服器錯誤返回了只包含切斷注記的空部分結果。

806* **背景**：subagent 被標記為失敗，Claude 在其結束時接收的訊息命名 API 錯誤並包括 subagent 的最後輸出，所以部分工作不會丟失。806* **背景**：subagent 被標記為失敗，Claude 在其結束時接收的訊息命名 API 錯誤並包括 subagent 的最後輸出，所以部分工作不會丟失。

807 807

808一旦基礎 API 錯誤清除，要求 Claude 重試任務或 [恢復 subagent](#resume-subagents)。808一旦基礎 API 錯誤清除，要求 Claude 重試任務或 [恢復 subagent](#resume-subagents)。

837 當 subagents 完成時，其結果返回到主要對話。執行許多 subagents，每個都返回詳細結果，可能會消耗大量上下文。837 當 subagents 完成時，其結果返回到主要對話。執行許多 subagents，每個都返回詳細結果，可能會消耗大量上下文。

838</Warning>838</Warning>

839 839

840對於需要持續並行性或超過上下文視窗的任務，[agent teams](/zh-TW/agent-teams) 為每個工作者提供自己的獨立上下文。840對於需要持續並行性或超過上下文視窗的任務，[agent teams](/docs/zh-TW/agent-teams) 為每個工作者提供自己的獨立上下文。

841 841

842<h4 id="chain-subagents">842<h4 id="chain-subagents">

843 鏈接 subagents843 鏈接 subagents

866* 您想強制執行特定的工具限制或權限866* 您想強制執行特定的工具限制或權限

867* 工作是自包含的，可以返回摘要867* 工作是自包含的，可以返回摘要

868 868

869當您想要可重複使用的提示或在主要對話上下文中執行的工作流程而不是隔離的 subagent 上下文時，請改為考慮 [Skills](/zh-TW/skills)。869當您想要可重複使用的提示或在主要對話上下文中執行的工作流程而不是隔離的 subagent 上下文時，請改為考慮 [Skills](/docs/zh-TW/skills)。

870 870

871對於關於對話中已有內容的快速問題，請使用 [`/btw`](/zh-TW/interactive-mode#side-questions-with-%2Fbtw) 而不是 subagent。它看到您的完整上下文，但沒有工具存取，答案被丟棄而不是新增到歷史記錄。871對於關於對話中已有內容的快速問題，請使用 [`/btw`](/docs/zh-TW/interactive-mode#side-questions-with-%2Fbtw) 而不是 subagent。它看到您的完整上下文，但沒有工具存取，答案被丟棄而不是新增到歷史記錄。

872 872

873<h3 id="spawn-nested-subagents">873<h3 id="spawn-nested-subagents">

874 產生嵌套 subagents874 產生嵌套 subagents

875</h3>875</h3>

876 876

877{/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，subagent 可以產生自己的 subagents。當委派的任務本身分裂成並行子任務時使用此功能，例如審查者 subagent 為每個發現分派驗證者，所以中間輸出永遠不會到達您的主要對話。只有頂級 subagent 的摘要返回給您。877自 Claude Code v2.1.172 起，subagent 可以產生自己的 subagents。當委派的任務本身分裂成並行子任務時使用此功能，例如審查者 subagent 為每個發現分派驗證者，所以中間輸出永遠不會到達您的主要對話。只有頂級 subagent 的摘要返回給您。

878 878

879嵌套 subagent 的配置方式與頂級 subagent 相同，並從相同的 [scopes](#choose-the-subagent-scope) 解析。879嵌套 subagent 的配置方式與頂級 subagent 相同，並從相同的 [scopes](#choose-the-subagent-scope) 解析。

880 880

881提示輸入下方的 subagent 面板顯示完整樹：每一行顯示後代的 `(+N)` 計數，{/* min-version: 2.1.193 */}自 v2.1.193 起，打開一行會顯示該 subagent 的同級和直接子代，以及返回到 `main` 的路徑。881提示輸入下方的 subagent 面板顯示完整樹：每一行顯示後代的 `(+N)` 計數，自 v2.1.193 起，打開一行會顯示該 subagent 的同級和直接子代，以及返回到 `main` 的路徑。

882 882

883深度計算為主要對話下方的 subagent 級別數，無論每個級別是否在 [前景或背景](#run-subagents-in-foreground-or-background) 中執行。深度為五的 subagent 不接收 Agent 工具，無法進一步產生。限制是固定的且不可配置。883深度計算為主要對話下方的 subagent 級別數，無論每個級別是否在 [前景或背景](#run-subagents-in-foreground-or-background) 中執行。深度為五的 subagent 不接收 Agent 工具，無法進一步產生。限制是固定的且不可配置。

884 884

902 902

903* **系統提示**：代理自己的提示加上 Claude Code 附加的環境詳細資訊，而不是完整的 Claude Code 系統提示。自訂 subagents 在 [markdown 正文](#write-subagent-files) 或 `prompt` 欄位中定義它們。內建代理有預定義的提示。903* **系統提示**：代理自己的提示加上 Claude Code 附加的環境詳細資訊，而不是完整的 Claude Code 系統提示。自訂 subagents 在 [markdown 正文](#write-subagent-files) 或 `prompt` 欄位中定義它們。內建代理有預定義的提示。

904* **任務訊息**：Claude 在交接工作時編寫的委派提示。904* **任務訊息**：Claude 在交接工作時編寫的委派提示。

905* **CLAUDE.md 和記憶**：主要對話載入的 [記憶層級](/zh-TW/memory#how-claude-md-files-load) 的每個級別，包括 `~/.claude/CLAUDE.md`、專案規則、`CLAUDE.local.md` 和受管理的政策檔案。內建的 Explore 和 Plan 代理跳過這個。905* **CLAUDE.md 和記憶**：主要對話載入的 [記憶層級](/docs/zh-TW/memory#how-claude-md-files-load) 的每個級別，包括 `~/.claude/CLAUDE.md`、專案規則、`CLAUDE.local.md` 和受管理的政策檔案。內建的 Explore 和 Plan 代理跳過這個。

906* **Git 狀態**：在父工作階段開始時拍攝的快照。當工作目錄不是 Git 儲存庫或當 [`includeGitInstructions`](/zh-TW/settings#available-settings) 為 `false` 時不存在。Explore 和 Plan 無論如何都跳過它。906* **Git 狀態**：在父工作階段開始時拍攝的快照。當工作目錄不是 Git 儲存庫或當 [`includeGitInstructions`](/docs/zh-TW/settings#available-settings) 為 `false` 時不存在。Explore 和 Plan 無論如何都跳過它。

907* **預載入的技能**：代理的 [`skills` 欄位](#preload-skills-into-subagents) 中命名的任何技能的完整內容。內建代理不預載入技能。907* **預載入的技能**：代理的 [`skills` 欄位](#preload-skills-into-subagents) 中命名的任何技能的完整內容。內建代理不預載入技能。

908* **同級名單**：系統提醒，列出 `main` 和工作階段中的每個其他命名代理，每個都是 [`SendMessage`](#resume-subagents) 的有效 `to` 值。{/* min-version: 2.1.206 */}需要 Claude Code v2.1.206 或更新版本。名單僅在 subagent 的工具包括 `SendMessage` 且至少有一個其他代理有名稱時出現，無論 Claude 在產生時命名它還是它作為 [agent teams](/zh-TW/agent-teams) 隊友執行。它是在 subagent 啟動時拍攝的快照，所以稍後命名的代理不會出現。908* **同級名單**：系統提醒，列出 `main` 和工作階段中的每個其他命名代理，每個都是 [`SendMessage`](#resume-subagents) 的有效 `to` 值。需要 Claude Code v2.1.206 或更新版本。名單僅在 subagent 的工具包括 `SendMessage` 且至少有一個其他代理有名稱時出現，無論 Claude 在產生時命名它還是它作為 [agent teams](/docs/zh-TW/agent-teams) 隊友執行。它是在 subagent 啟動時拍攝的快照，所以稍後命名的代理不會出現。

909 909

910Explore 和 Plan 是唯一省略 CLAUDE.md 和 git 狀態的 subagents。沒有 frontmatter 欄位或每個代理設定來改變哪些代理跳過它們。910Explore 和 Plan 是唯一省略 CLAUDE.md 和 git 狀態的 subagents。沒有 frontmatter 欄位或每個代理設定來改變哪些代理跳過它們。

911 911

921 921

922當 subagent 完成時，Claude 接收其代理 ID。內建的 Explore 和 Plan 代理是一次性的，不返回代理 ID，所以它們無法被恢復；當您需要繼續工作時，請使用 `general-purpose` 或自訂 subagent。922當 subagent 完成時，Claude 接收其代理 ID。內建的 Explore 和 Plan 代理是一次性的，不返回代理 ID，所以它們無法被恢復；當您需要繼續工作時，請使用 `general-purpose` 或自訂 subagent。

923 923

924Claude 使用 `SendMessage` 工具，將代理的 ID 或名稱作為 `to` 欄位來恢復它。`SendMessage` 不需要啟用 [agent teams](/zh-TW/agent-teams)；只有結構化的團隊協議訊息，例如 `shutdown_request` 和 `plan_approval_response`，才需要啟用。924Claude 使用 `SendMessage` 工具，將代理的 ID 或名稱作為 `to` 欄位來恢復它。`SendMessage` 不需要啟用 [agent teams](/docs/zh-TW/agent-teams)；只有結構化的團隊協議訊息，例如 `shutdown_request` 和 `plan_approval_response`，才需要啟用。

925 925

926若要恢復 subagent，請要求 Claude 繼續先前的工作：926若要恢復 subagent，請要求 Claude 繼續先前的工作：

927 927

935 935

936如果停止的 subagent 接收 `SendMessage`，它會自動在背景中恢復，無需新的 `Agent` 呼叫。同樣適用於 Claude 使用 `TaskStop` 工具停止的 subagent。936如果停止的 subagent 接收 `SendMessage`，它會自動在背景中恢復，無需新的 `Agent` 呼叫。同樣適用於 Claude 使用 `TaskStop` 工具停止的 subagent。

937 937

938{/* min-version: 2.1.191 */}自 v2.1.191 起，您自己停止的 subagent，使用 `/tasks` 中的 `x` 或 SDK `stop_task` 請求，不會自動恢復。`SendMessage` 呼叫返回拒絕，告訴 Claude 代理已被取消。在 subagent 面板中輸入該 subagent 的文字以自己恢復它，這會清除停止，以便稍後 `SendMessage` 呼叫可以再次自動恢復它。938自 v2.1.191 起，您自己停止的 subagent，使用 `/tasks` 中的 `x` 或 SDK `stop_task` 請求，不會自動恢復。`SendMessage` 呼叫返回拒絕，告訴 Claude 代理已被取消。在 subagent 面板中輸入該 subagent 的文字以自己恢復它，這會清除停止，以便稍後 `SendMessage` 呼叫可以再次自動恢復它。

939 939

940恢復會在相同 ID 下啟動代理的新執行，所以已經失敗或完成的 subagent 在任務列表和 Agent SDK 的任務事件中再次顯示為執行中。在 v2.1.205 之前，它在恢復的執行工作時保持顯示其較早的失敗或完成狀態。940恢復會在相同 ID 下啟動代理的新執行，所以已經失敗或完成的 subagent 在任務列表和 Agent SDK 的任務事件中再次顯示為執行中。在 v2.1.205 之前，它在恢復的執行工作時保持顯示其較早的失敗或完成狀態。

941 941

942{/* min-version: 2.1.199 */}自 v2.1.199 起，`SendMessage` 檢查名稱是否仍然指向它在對話中較早時到達的同一代理。如果較新的代理已取得該名稱，例如重新產生的背景代理重複使用了它，Claude Code 會拒絕發送，而不是將其傳遞給錯誤的代理，錯誤會報告該名稱現在到達的代理，以便 Claude 可以重新定位。若要在較早的代理仍在執行時到達它，Claude 會透過其產生結果中的代理 ID 來定址它。檢查的範圍是目前對話，並在 `/clear` 時重置。942自 v2.1.199 起，`SendMessage` 檢查名稱是否仍然指向它在對話中較早時到達的同一代理。如果較新的代理已取得該名稱，例如重新產生的背景代理重複使用了它，Claude Code 會拒絕發送，而不是將其傳遞給錯誤的代理，錯誤會報告該名稱現在到達的代理，以便 Claude 可以重新定位。若要在較早的代理仍在執行時到達它，Claude 會透過其產生結果中的代理 ID 來定址它。檢查的範圍是目前對話，並在 `/clear` 時重置。

943 943

944{/* min-version: 2.1.198 */}自 v2.1.198 起，subagent 將來自啟動它的代理的訊息視為正常任務方向，包括中途任務課程更正，並在其自己的權限設定內對其進行操作。無論誰發送訊息，兩個限制仍然成立：來自任何代理的任何訊息都不計為您對待處理權限提示的批准，任何代理訊息都無法改變 subagent 的權限設定、`CLAUDE.md` 或配置。只有權限系統或您自己的訊息可以授予批准。944自 v2.1.198 起，subagent 將來自啟動它的代理的訊息視為正常任務方向，包括中途任務課程更正，並在其自己的權限設定內對其進行操作。無論誰發送訊息，兩個限制仍然成立：來自任何代理的任何訊息都不計為您對待處理權限提示的批准，任何代理訊息都無法改變 subagent 的權限設定、`CLAUDE.md` 或配置。只有權限系統或您自己的訊息可以授予批准。

945 945

946您也可以要求 Claude 提供代理 ID，如果您想明確參考它，或在 `~/.claude/projects/{project}/{sessionId}/subagents/` 的文字檔案中找到 ID。每個文字都儲存為 `agent-{agentId}.jsonl`。946您也可以要求 Claude 提供代理 ID，如果您想明確參考它，或在 `~/.claude/projects/{project}/{sessionId}/subagents/` 的文字檔案中找到 ID。每個文字都儲存為 `agent-{agentId}.jsonl`。

947 947

955 自動壓縮955 自動壓縮

956</h4>956</h4>

957 957

958Subagents 支援使用與主要對話相同的邏輯進行自動壓縮。壓縮在相同條件下觸發，`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 也適用於 subagents。請參閱 [environment variables](/zh-TW/env-vars) 以了解何時覆蓋生效。958Subagents 支援使用與主要對話相同的邏輯進行自動壓縮。壓縮在相同條件下觸發，`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 也適用於 subagents。請參閱 [environment variables](/docs/zh-TW/env-vars) 以了解何時覆蓋生效。

959 959

960壓縮事件記錄在 subagent 文字檔案中：960壓縮事件記錄在 subagent 文字檔案中：

961 961

977</h2>977</h2>

978 978

979<Note>979<Note>

980 Forked subagents 需要 Claude Code v2.1.117 或更新版本。{/* min-version: 2.1.161 */}從 v2.1.161 開始，`/fork` 命令預設啟用；在較早版本中，它需要將 [`CLAUDE_CODE_FORK_SUBAGENT`](/zh-TW/env-vars) 環境變數設定為 `1`。讓 Claude 本身產生 forks 是實驗性的，可能在未來版本中變更。此功能也可能在互動式工作階段中啟用，作為分階段推出的一部分。980 Forked subagents 需要 Claude Code v2.1.117 或更新版本。從 v2.1.161 開始，`/fork` 命令預設啟用；在較早版本中，它需要將 [`CLAUDE_CODE_FORK_SUBAGENT`](/docs/zh-TW/env-vars) 環境變數設定為 `1`。讓 Claude 本身產生 forks 是實驗性的，可能在未來版本中變更。此功能也可能在互動式工作階段中啟用，作為分階段推出的一部分。

981</Note>981</Note>

982 982

983Fork 是一個 subagent，它繼承到目前為止的整個對話，而不是從頭開始。這會放棄 subagents 否則提供的輸入隔離：fork 看到與主工作階段相同的系統提示、工具、模型和訊息歷史記錄，因此您可以將側面任務交給它，而無需重新解釋情況。Fork 自己的工具呼叫仍然保持在您的對話之外，只有其最終結果返回，因此您的主要上下文視窗保持乾淨。當命名 subagent 需要太多背景才能有用時，或當您想從相同的起點並行嘗試多種方法時，使用 fork。983Fork 是一個 subagent，它繼承到目前為止的整個對話，而不是從頭開始。這會放棄 subagents 否則提供的輸入隔離：fork 看到與主工作階段相同的系統提示、工具、模型和訊息歷史記錄，因此您可以將側面任務交給它，而無需重新解釋情況。Fork 自己的工具呼叫仍然保持在您的對話之外，只有其最終結果返回，因此您的主要上下文視窗保持乾淨。當命名 subagent 需要太多背景才能有用時，或當您想從相同的起點並行嘗試多種方法時，使用 fork。

984 984

985若要控制 fork 模式，無論分階段推出如何，請將 [`CLAUDE_CODE_FORK_SUBAGENT`](/zh-TW/env-vars) 設定為 `1` 以明確啟用它，或設定為 `0` 以停用它。該變數在互動模式中以及透過 SDK 或 `claude -p` 被接受。985若要控制 fork 模式，無論分階段推出如何，請將 [`CLAUDE_CODE_FORK_SUBAGENT`](/docs/zh-TW/env-vars) 設定為 `1` 以明確啟用它，或設定為 `0` 以停用它。該變數在互動模式中以及透過 SDK 或 `claude -p` 被接受。

986 986

987啟用 fork 模式會以兩種方式改變 Claude Code：987啟用 fork 模式會以兩種方式改變 Claude Code：

988 988

1010| `x` | 關閉完成的 fork 或停止執行中的 fork |1010| `x` | 關閉完成的 fork 或停止執行中的 fork |

1011| `Esc` | 將焦點返回到提示輸入 |1011| `Esc` | 將焦點返回到提示輸入 |

1012 1012

1013使用 fork 或 subagent 的文字記錄開啟時，後續訊息和 [skills](/zh-TW/skills) 會傳送到該代理，但內建命令仍在您的主要對話中執行。{/* min-version: 2.1.199 */}從 v2.1.199 開始，在該檢視中輸入 `/model` 或 `/fast` 會顯示通知，表示它會變更主要對話的模型或快速模式，而不是檢視的代理，而不是以無聲方式執行。1013使用 fork 或 subagent 的文字記錄開啟時，後續訊息和 [skills](/docs/zh-TW/skills) 會傳送到該代理，但內建命令仍在您的主要對話中執行。從 v2.1.199 開始，在該檢視中輸入 `/model` 或 `/fast` 會顯示通知，表示它會變更主要對話的模型或快速模式，而不是檢視的代理，而不是以無聲方式執行。

1014 1014

1015<h3 id="how-forks-differ-from-named-subagents">1015<h3 id="how-forks-differ-from-named-subagents">

1016 Forks 與命名 subagents 的區別1016 Forks 與命名 subagents 的區別

1028 1028

1029因為 fork 的系統提示和工具定義與父級相同，其第一個請求重複使用父級的 [prompt cache](/zh-TW/prompt-caching#subagents-and-the-cache)。這使得 forking 比為需要相同上下文的任務產生新 subagent 更便宜。1029因為 fork 的系統提示和工具定義與父級相同，其第一個請求重複使用父級的 [prompt cache](/docs/zh-TW/prompt-caching#subagents-and-the-cache)。這使得 forking 比為需要相同上下文的任務產生新 subagent 更便宜。

1030 1030

1031當 Claude 透過 Agent 工具產生 fork 時，它可以傳遞 `isolation: "worktree"`，以便 fork 的檔案編輯被寫入單獨的 git worktree 而不是您的簽出。1031當 Claude 透過 Agent 工具產生 fork 時，它可以傳遞 `isolation: "worktree"`，以便 fork 的檔案編輯被寫入單獨的 git worktree 而不是您的簽出。

1032 1032

1034 限制1034 限制

1035</h3>1035</h3>

1036 1036

1037設定 `CLAUDE_CODE_FORK_SUBAGENT=1` 在互動式工作階段、[non-interactive mode](/zh-TW/headless) 和 Agent SDK 中啟用 fork 模式；將其設定為 `0` 會在所有地方停用 fork 模式，包括任何伺服器端推出。Fork 無法產生進一步的 forks。1037設定 `CLAUDE_CODE_FORK_SUBAGENT=1` 在互動式工作階段、[non-interactive mode](/docs/zh-TW/headless) 和 Agent SDK 中啟用 fork 模式；將其設定為 `0` 會在所有地方停用 fork 模式，包括任何伺服器端推出。Fork 無法產生進一步的 forks。

1038 1038

1039<h2 id="example-subagents">1039<h2 id="example-subagents">

1040 範例 subagents1040 範例 subagents

1197You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.1197You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

1198```1198```

1199 1199

1200Claude Code [透過 stdin 將 hook 輸入作為 JSON 傳遞](/zh-TW/hooks#pretooluse-input) 給 hook 命令。驗證指令碼讀取此 JSON，提取正在執行的命令，並根據 SQL 寫入操作清單檢查它。如果檢測到寫入操作，指令碼 [以代碼 2 退出](/zh-TW/hooks#exit-code-2-behavior-per-event) 以阻止執行並透過 stderr 向 Claude 返回錯誤訊息。1200Claude Code [透過 stdin 將 hook 輸入作為 JSON 傳遞](/docs/zh-TW/hooks#pretooluse-input) 給 hook 命令。驗證指令碼讀取此 JSON，提取正在執行的命令，並根據 SQL 寫入操作清單檢查它。如果檢測到寫入操作，指令碼 [以代碼 2 退出](/docs/zh-TW/hooks#exit-code-2-behavior-per-event) 以阻止執行並透過 stderr 向 Claude 返回錯誤訊息。

1201 1201

1202在專案中的任何位置建立驗證指令碼。路徑必須與 hook 配置中的 `command` 欄位相符：1202在專案中的任何位置建立驗證指令碼。路徑必須與 hook 配置中的 `command` 欄位相符：

1203 1203

1230chmod +x ./scripts/validate-readonly-query.sh1230chmod +x ./scripts/validate-readonly-query.sh

1231```1231```

1232 1232

1233在 Windows 上，使用 PowerShell 編寫驗證指令碼，並將 `shell: powershell` 新增至 hook 項目。請參閱 [在 PowerShell 中執行 hooks](/zh-TW/hooks#windows-powershell-tool)。1233在 Windows 上，使用 PowerShell 編寫驗證指令碼，並將 `shell: powershell` 新增至 hook 項目。請參閱 [在 PowerShell 中執行 hooks](/docs/zh-TW/hooks#windows-powershell-tool)。

1234 1234

1235Hook 透過 stdin 接收 JSON，Bash 命令在 `tool_input.command` 中。退出代碼 2 阻止操作並將錯誤訊息反饋給 Claude。請參閱 [Hooks](/zh-TW/hooks#exit-code-output) 以了解退出代碼和 [Hook input](/zh-TW/hooks#pretooluse-input) 以了解完整的輸入架構。1235Hook 透過 stdin 接收 JSON，Bash 命令在 `tool_input.command` 中。退出代碼 2 阻止操作並將錯誤訊息反饋給 Claude。請參閱 [Hooks](/docs/zh-TW/hooks#exit-code-output) 以了解退出代碼和 [Hook input](/docs/zh-TW/hooks#pretooluse-input) 以了解完整的輸入架構。

1236 1236

1237<h2 id="next-steps">1237<h2 id="next-steps">

1238 後續步驟1238 後續步驟

1240 1240

1241現在您理解了 subagents，請探索這些相關功能：1241現在您理解了 subagents，請探索這些相關功能：

1242 1242

1243* [使用外掛程式分發 subagents](/zh-TW/plugins) 以跨團隊或專案共享 subagents1243* [使用外掛程式分發 subagents](/docs/zh-TW/plugins) 以跨團隊或專案共享 subagents

1244* [以程式方式執行 Claude Code](/zh-TW/headless) 使用 Agent SDK 進行 CI/CD 和自動化1244* [以程式方式執行 Claude Code](/docs/zh-TW/headless) 使用 Agent SDK 進行 CI/CD 和自動化

1245* [使用 MCP 伺服器](/zh-TW/mcp) 為 subagents 提供對外部工具和資料的存取1245* [使用 MCP 伺服器](/docs/zh-TW/mcp) 為 subagents 提供對外部工具和資料的存取

tools-reference.md +78 −78

Details

6 6

7> Claude Code 可以使用的工具的完整參考，包括權限要求和各工具行為。7> Claude Code 可以使用的工具的完整參考，包括權限要求和各工具行為。

8 8

9Claude Code 可以存取一組內建工具，幫助它理解和修改您的程式碼庫。工具名稱是您在 [權限規則](/zh-TW/permissions#tool-specific-permission-rules)、[subagent 工具清單](/zh-TW/sub-agents) 和 [hook 匹配器](/zh-TW/hooks) 中使用的確切字串。若要完全停用工具，請將其名稱新增到您的 [權限設定](/zh-TW/permissions#tool-specific-permission-rules) 中的 `deny` 陣列。9Claude Code 可以存取一組內建工具，幫助它理解和修改您的程式碼庫。工具名稱是您在 [權限規則](/docs/zh-TW/permissions#tool-specific-permission-rules)、[subagent 工具清單](/docs/zh-TW/sub-agents) 和 [hook 匹配器](/docs/zh-TW/hooks) 中使用的確切字串。若要完全停用工具，請將其名稱新增到您的 [權限設定](/docs/zh-TW/permissions#tool-specific-permission-rules) 中的 `deny` 陣列。

10 10

11若要新增自訂工具，請連接 [MCP server](/zh-TW/mcp)。若要使用可重複使用的提示型工作流程擴展 Claude，請撰寫 [skill](/zh-TW/skills)，它透過現有的 `Skill` 工具執行，而不是新增工具項目。11若要新增自訂工具，請連接 [MCP server](/docs/zh-TW/mcp)。若要使用可重複使用的提示型工作流程擴展 Claude，請撰寫 [skill](/docs/zh-TW/skills)，它透過現有的 `Skill` 工具執行，而不是新增工具項目。

12 12

13Permission required 欄位顯示工具是否在預設權限模式下針對工作目錄內的路徑進行提示。標記為「否」的檔案存取工具（包括 `Read`、`Grep` 和 `Glob`）仍會針對 [工作目錄和其他目錄](/zh-TW/permissions#working-directories) 外的路徑進行提示。`Bash` 標記為「是」，但執行內建的 [唯讀命令](/zh-TW/permissions#read-only-commands) 集合，無需提示。13Permission required 欄位顯示工具是否在預設權限模式下針對工作目錄內的路徑進行提示。標記為「否」的檔案存取工具（包括 `Read`、`Grep` 和 `Glob`）仍會針對 [工作目錄和其他目錄](/docs/zh-TW/permissions#working-directories) 外的路徑進行提示。`Bash` 標記為「是」，但執行內建的 [唯讀命令](/docs/zh-TW/permissions#read-only-commands) 集合，無需提示。

14 14

15| 工具 | 描述 | 需要權限 |15| 工具 | 描述 | 需要權限 |

16| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- |16| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- |

17| `Agent` | 生成一個具有自己 context window 的 [subagent](/zh-TW/sub-agents)，以處理任務。請參閱 [Agent 工具行為](#agent-tool-behavior) | 否 |17| `Agent` | 生成一個具有自己 context window 的 [subagent](/docs/zh-TW/sub-agents)，以處理任務。請參閱 [Agent 工具行為](#agent-tool-behavior) | 否 |

18| `Artifact` | 將 HTML 或 Markdown 檔案發佈為 [artifact](/zh-TW/artifacts)：一個私人的互動式頁面，在 claude.ai 上。在 Team 和 Enterprise 計畫上，您可以在組織內部分享。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 計畫和 `/login` 驗證；請參閱 [可用性](/zh-TW/artifacts#availability) | 是 |18| `Artifact` | 將 HTML 或 Markdown 檔案發佈為 [artifact](/docs/zh-TW/artifacts)：一個私人的互動式頁面，在 claude.ai 上。在 Team 和 Enterprise 計畫上，您可以在組織內部分享。需要 Pro、Max、Team 或 Enterprise 計畫和 `/login` 驗證；請參閱 [可用性](/docs/zh-TW/artifacts#availability) | 是 |

19| `AskUserQuestion` | 提出多選題以收集需求或澄清歧義。{/* min-version: 2.1.200 */}問題會保持開啟直到您回答：預設情況下沒有閒置逾時。若要讓閒置對話框自動繼續，請將 [`askUserQuestionTimeout`](/zh-TW/settings#available-settings) 設定設為 `60s`、`5m` 或 `10m`，可在您的使用者 `settings.json` 中或從 `/config` 中的**問題自動繼續逾時**列進行設定。一旦經過所選的閒置時間且沒有輸入，對話框會自動關閉：它會提交您已選擇的任何選項，並告訴 Claude 您可能離開了鍵盤，因此 Claude 會根據自己的判斷進行，稍後可以重新提問。最後 20 秒會出現倒數計時。任何按鍵都會重新啟動計時器，報告焦點的終端機上的焦點視窗也會。逾時僅適用於 `AskUserQuestion` 的多選題；權限提示（包括計畫批准）在閒置時永遠不會自動解決。在 v2.1.198 和 v2.1.199 中，對話框預設在 60 秒閒置後自動繼續，[`CLAUDE_AFK_TIMEOUT_MS`](/zh-TW/env-vars#variables) 是唯一改變該行為的方式 | 否 |19| `AskUserQuestion` | 提出多選題以收集需求或澄清歧義。問題會保持開啟直到您回答：預設情況下沒有閒置逾時。若要讓閒置對話框自動繼續，請將 [`askUserQuestionTimeout`](/docs/zh-TW/settings#available-settings) 設定設為 `60s`、`5m` 或 `10m`，可在您的使用者 `settings.json` 中或從 `/config` 中的**問題自動繼續逾時**列進行設定。一旦經過所選的閒置時間且沒有輸入，對話框會自動關閉：它會提交您已選擇的任何選項，並告訴 Claude 您可能離開了鍵盤，因此 Claude 會根據自己的判斷進行，稍後可以重新提問。最後 20 秒會出現倒數計時。任何按鍵都會重新啟動計時器，報告焦點的終端機上的焦點視窗也會。逾時僅適用於 `AskUserQuestion` 的多選題；權限提示（包括計畫批准）在閒置時永遠不會自動解決。在 v2.1.198 和 v2.1.199 中，對話框預設在 60 秒閒置後自動繼續，[`CLAUDE_AFK_TIMEOUT_MS`](/docs/zh-TW/env-vars#variables) 是唯一改變該行為的方式 | 否 |

20| `Bash` | 在您的環境中執行 shell 命令。請參閱 [Bash 工具行為](#bash-tool-behavior) | 是 |20| `Bash` | 在您的環境中執行 shell 命令。請參閱 [Bash 工具行為](#bash-tool-behavior) | 是 |

21| `CronCreate` | 在目前工作階段內排程定期或一次性提示。任務的範圍限於工作階段，並在 `--resume` 或 `--continue` 時恢復（如果未過期）。請參閱 [排程任務](/zh-TW/scheduled-tasks) | 否 |21| `CronCreate` | 在目前工作階段內排程定期或一次性提示。任務的範圍限於工作階段，並在 `--resume` 或 `--continue` 時恢復（如果未過期）。請參閱 [排程任務](/docs/zh-TW/scheduled-tasks) | 否 |

22| `CronDelete` | 按 ID 取消排程任務 | 否 |22| `CronDelete` | 按 ID 取消排程任務 | 否 |

23| `CronList` | 列出工作階段中的所有排程任務 | 否 |23| `CronList` | 列出工作階段中的所有排程任務 | 否 |

24| `Edit` | 對特定檔案進行目標編輯。請參閱 [Edit 工具行為](#edit-tool-behavior) | 是 |24| `Edit` | 對特定檔案進行目標編輯。請參閱 [Edit 工具行為](#edit-tool-behavior) | 是 |

25| `EnterPlanMode` | 切換到 Plan Mode 以在編碼前設計方法 | 否 |25| `EnterPlanMode` | 切換到 Plan Mode 以在編碼前設計方法 | 否 |

26| `EnterWorktree` | 建立隔離的 [git worktree](/zh-TW/worktrees) 並切換到其中。傳遞 `path` 以切換到現有 worktree，而不是建立新的。{/* min-version: 2.1.203 */}首次進入時，目標可能是目前儲存庫的 worktree，或在多儲存庫工作區中，是其中嵌套的儲存庫的 worktree。在 v2.1.203 之前，嵌套儲存庫的 worktree 會被拒絕。{/* min-version: 2.1.206 */}`.claude/worktrees/` 外的 `path` 會在進入前提示您的批准，因為它會移動工作階段的工作目錄和寫入存取權限到該位置。新 worktree 建立和 `.claude/worktrees/` 下的路徑不會提示。在 v2.1.206 之前，Claude 進入 `.claude/worktrees/` 外的路徑時不會提示。從 worktree 工作階段內，或從具有固定工作目錄的 subagent（例如 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)）中，只有 `path` 形式可用，且目標必須在工作階段儲存庫的 `.claude/worktrees/` 下 | 是 |26| `EnterWorktree` | 建立隔離的 [git worktree](/docs/zh-TW/worktrees) 並切換到其中。傳遞 `path` 以切換到現有 worktree，而不是建立新的。首次進入時，目標可能是目前儲存庫的 worktree，或在多儲存庫工作區中，是其中嵌套的儲存庫的 worktree。在 v2.1.203 之前，嵌套儲存庫的 worktree 會被拒絕。`.claude/worktrees/` 外的 `path` 會在進入前提示您的批准，因為它會移動工作階段的工作目錄和寫入存取權限到該位置。新 worktree 建立和 `.claude/worktrees/` 下的路徑不會提示。在 v2.1.206 之前，Claude 進入 `.claude/worktrees/` 外的路徑時不會提示。從 worktree 工作階段內，或從具有固定工作目錄的 subagent（例如 [`isolation: worktree`](/docs/zh-TW/sub-agents#supported-frontmatter-fields)）中，只有 `path` 形式可用，且目標必須在工作階段儲存庫的 `.claude/worktrees/` 下 | 是 |

27| `ExitPlanMode` | 提出計畫以供批准並退出 Plan Mode | 是 |27| `ExitPlanMode` | 提出計畫以供批准並退出 Plan Mode | 是 |

28| `ExitWorktree` | 退出 worktree 工作階段並返回原始目錄。不適用於已在自己的工作目錄中執行的 subagents，例如使用 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields) | 否 |28| `ExitWorktree` | 退出 worktree 工作階段並返回原始目錄。不適用於已在自己的工作目錄中執行的 subagents，例如使用 [`isolation: worktree`](/docs/zh-TW/sub-agents#supported-frontmatter-fields) | 否 |

29| `Glob` | 根據模式匹配查找檔案。請參閱 [Glob 工具行為](#glob-tool-behavior) | 否 |29| `Glob` | 根據模式匹配查找檔案。請參閱 [Glob 工具行為](#glob-tool-behavior) | 否 |

30| `Grep` | 在檔案內容中搜尋模式。請參閱 [Grep 工具行為](#grep-tool-behavior) | 否 |30| `Grep` | 在檔案內容中搜尋模式。請參閱 [Grep 工具行為](#grep-tool-behavior) | 否 |

31| `ListMcpResourcesTool` | 列出連接的 [MCP servers](/zh-TW/mcp) 公開的資源 | 否 |31| `ListMcpResourcesTool` | 列出連接的 [MCP servers](/docs/zh-TW/mcp) 公開的資源 | 否 |

32| `LSP` | 透過語言伺服器進行程式碼智慧：跳轉到定義、尋找參考、報告型別錯誤和警告。請參閱 [LSP 工具行為](#lsp-tool-behavior) | 否 |32| `LSP` | 透過語言伺服器進行程式碼智慧：跳轉到定義、尋找參考、報告型別錯誤和警告。請參閱 [LSP 工具行為](#lsp-tool-behavior) | 否 |

33| `Monitor` | 在背景執行命令，並將每個輸出行回饋給 Claude，以便它可以對日誌項目、檔案變更或輪詢狀態做出反應。也可以開啟 WebSocket 並將每個傳入訊息視為事件。請參閱 [Monitor 工具](#monitor-tool) | 是 |33| `Monitor` | 在背景執行命令，並將每個輸出行回饋給 Claude，以便它可以對日誌項目、檔案變更或輪詢狀態做出反應。也可以開啟 WebSocket 並將每個傳入訊息視為事件。請參閱 [Monitor 工具](#monitor-tool) | 是 |

34| `NotebookEdit` | 修改 Jupyter notebook 儲存格。請參閱 [NotebookEdit 工具行為](#notebookedit-tool-behavior) | 是 |34| `NotebookEdit` | 修改 Jupyter notebook 儲存格。請參閱 [NotebookEdit 工具行為](#notebookedit-tool-behavior) | 是 |

35| `PowerShell` | 原生執行 PowerShell 命令。請參閱 [PowerShell 工具](#powershell-tool) 以了解可用性 | 是 |35| `PowerShell` | 原生執行 PowerShell 命令。請參閱 [PowerShell 工具](#powershell-tool) 以了解可用性 | 是 |

36| `PushNotification` | 傳送桌面通知，以及當 [Remote Control](/zh-TW/remote-control) 已連接時傳送手機推播，以便長時間執行的任務或 [排程任務](/zh-TW/scheduled-tasks) 可以在您離開時聯繫您。{/* plan-availability: feature=push-notifications providers=anthropic */}推播傳遞透過 Anthropic 託管的基礎設施執行，無法從 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取 | 否 |36| `PushNotification` | 傳送桌面通知，以及當 [Remote Control](/docs/zh-TW/remote-control) 已連接時傳送手機推播，以便長時間執行的任務或 [排程任務](/docs/zh-TW/scheduled-tasks) 可以在您離開時聯繫您。推播傳遞透過 Anthropic 託管的基礎設施執行，無法從 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取 | 否 |

37| `Read` | 讀取檔案的內容。請參閱 [Read 工具行為](#read-tool-behavior) | 否 |37| `Read` | 讀取檔案的內容。請參閱 [Read 工具行為](#read-tool-behavior) | 否 |

38| `ReadMcpResourceTool` | 按 URI 讀取特定 MCP 資源 | 否 |38| `ReadMcpResourceTool` | 按 URI 讀取特定 MCP 資源 | 否 |

39| `RemoteTrigger` | 在 claude.ai 上建立、更新、執行和列出 [Routines](/zh-TW/routines)。支援 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 位於 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 計畫，因此此工具無法從 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取 | 否 |39| `RemoteTrigger` | 在 claude.ai 上建立、更新、執行和列出 [Routines](/docs/zh-TW/routines)。支援 `/schedule` 命令。Routines 位於 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 計畫，因此此工具無法從 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取 | 否 |

40| `ReportFindings` | 將程式碼審查結果報告為結構化清單，每個結果包含檔案、摘要和失敗情景，以便 Claude Code 可以呈現它們而不是將其列印為文字。當有效的程式碼審查指示告訴它時，Claude 會呼叫它。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本。{/* min-version: 2.1.199 */}自 v2.1.199 起，結果也可以攜帶選擇性的 `category` slug，例如 `correctness` 或 `test-coverage`，顯示在呈現清單中的檔案位置旁邊 | 否 |40| `ReportFindings` | 將程式碼審查結果報告為結構化清單，每個結果包含檔案、摘要和失敗情景，以便 Claude Code 可以呈現它們而不是將其列印為文字。當有效的程式碼審查指示告訴它時，Claude 會呼叫它。需要 Claude Code v2.1.196 或更新版本。自 v2.1.199 起，結果也可以攜帶選擇性的 `category` slug，例如 `correctness` 或 `test-coverage`，顯示在呈現清單中的檔案位置旁邊 | 否 |

41| `ScheduleWakeup` | 重新排程 [自主進行的 `/loop`](/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代結束時呼叫此工具，以選擇下一次執行的時間，範圍在一分鐘到一小時之間；您不需要直接呼叫它。若要改為結束迴圈，Claude 會以 `stop: true` 呼叫它，這會取消待處理的喚醒。{/* min-version: 2.1.202 */}`stop` 欄位需要 Claude Code v2.1.202 或更新版本。待處理的喚醒會出現在 [Stop hook input](/zh-TW/hooks#stop-input) 的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用，其中沒有間隔的 `/loop` 提示會改為按固定時間表執行 | 否 |41| `ScheduleWakeup` | 重新排程 [自主進行的 `/loop`](/docs/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代結束時呼叫此工具，以選擇下一次執行的時間，範圍在一分鐘到一小時之間；您不需要直接呼叫它。若要改為結束迴圈，Claude 會以 `stop: true` 呼叫它，這會取消待處理的喚醒。`stop` 欄位需要 Claude Code v2.1.202 或更新版本。待處理的喚醒會出現在 [Stop hook input](/docs/zh-TW/hooks#stop-input) 的 `session_crons` 中。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用，其中沒有間隔的 `/loop` 提示會改為按固定時間表執行 | 否 |

42| `SendMessage` | 傳送訊息給 [agent team](/zh-TW/agent-teams) 隊友，或按 agent ID 或名稱 [恢復 subagent](/zh-TW/sub-agents#resume-subagents)。已完成的 subagent 會在背景中自動恢復；您從 `/tasks` 停止的 subagent 不會，且呼叫會傳回拒絕。結構化的團隊協議訊息需要 agent teams。接收者永遠不會將來自另一個 agent 的訊息視為您的同意或批准。{/* min-version: 2.1.198 */}自 v2.1.198 起，subagent 將來自啟動它的 agent 的訊息視為正常任務指示，而不是對等請求。{/* min-version: 2.1.199 */}自 v2.1.199 起，傳送到現在解析為與對話中較早時間不同的 agent 的名稱會被拒絕而不是傳遞；請參閱 [恢復 subagents](/zh-TW/sub-agents#resume-subagents) | 否 |42| `SendMessage` | 傳送訊息給 [agent team](/docs/zh-TW/agent-teams) 隊友，或按 agent ID 或名稱 [恢復 subagent](/docs/zh-TW/sub-agents#resume-subagents)。已完成的 subagent 會在背景中自動恢復；您從 `/tasks` 停止的 subagent 不會，且呼叫會傳回拒絕。結構化的團隊協議訊息需要 agent teams。接收者永遠不會將來自另一個 agent 的訊息視為您的同意或批准。自 v2.1.198 起，subagent 將來自啟動它的 agent 的訊息視為正常任務指示，而不是對等請求。自 v2.1.199 起，傳送到現在解析為與對話中較早時間不同的 agent 的名稱會被拒絕而不是傳遞；請參閱 [恢復 subagents](/docs/zh-TW/sub-agents#resume-subagents) | 否 |

43| `SendUserFile` | 將工作階段中的檔案傳送給您，並附上選擇性標題，以便生成的報告、圖表、螢幕擷取畫面或建置的成品可以到達您的裝置，而不是只在文字記錄中提及。{/* min-version: 2.1.196 */}自 v2.1.196 起，選擇性的 `display` 輸入控制呈現方式：`render` 在用戶端中內聯開啟檔案，`attach` 僅顯示下載卡片，未設定時用戶端會根據檔案類型決定。當連接了 [Remote Control](/zh-TW/remote-control) 用戶端或工作階段在受管雲端環境（例如 [Claude Code on the web](/zh-TW/claude-code-on-the-web)）中執行時可用。傳遞透過 Anthropic 託管的基礎設施執行，因此該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用 | 否 |43| `SendUserFile` | 將工作階段中的檔案傳送給您，並附上選擇性標題，以便生成的報告、圖表、螢幕擷取畫面或建置的成品可以到達您的裝置，而不是只在文字記錄中提及。自 v2.1.196 起，選擇性的 `display` 輸入控制呈現方式：`render` 在用戶端中內聯開啟檔案，`attach` 僅顯示下載卡片，未設定時用戶端會根據檔案類型決定。當連接了 [Remote Control](/docs/zh-TW/remote-control) 用戶端或工作階段在受管雲端環境（例如 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)）中執行時可用。傳遞透過 Anthropic 託管的基礎設施執行，因此該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用 | 否 |

44| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上傳 `ONBOARDING.md` 並傳回隊友可以在 Claude Code 中開啟的分享連結。在撰寫指南後從 `/team-onboarding` 呼叫。適用於 Pro、Max、Team 和 Enterprise 計畫上的 claude.ai 訂閱者 | 是 |44| `ShareOnboardingGuide` | 上傳 `ONBOARDING.md` 並傳回隊友可以在 Claude Code 中開啟的分享連結。在撰寫指南後從 `/team-onboarding` 呼叫。適用於 Pro、Max、Team 和 Enterprise 計畫上的 claude.ai 訂閱者 | 是 |

45| `Skill` | 在主對話中執行 [skill](/zh-TW/skills#control-who-invokes-a-skill) | 是 |45| `Skill` | 在主對話中執行 [skill](/docs/zh-TW/skills#control-who-invokes-a-skill) | 是 |

46| `TaskCreate` | 在任務清單中建立新任務 | 否 |46| `TaskCreate` | 在任務清單中建立新任務 | 否 |

47| `TaskGet` | 檢索特定任務的完整詳細資訊 | 否 |47| `TaskGet` | 檢索特定任務的完整詳細資訊 | 否 |

48| `TaskList` | 列出所有任務及其目前狀態 | 否 |48| `TaskList` | 列出所有任務及其目前狀態 | 否 |

49| `TaskOutput` | 檢索背景任務的輸出。已在任務的輸出檔案路徑上使用 `Read` 取代。{/* min-version: 2.1.203 */}當沒有任務符合 ID 時，錯誤會列出執行中的背景 agents（按 ID 和描述）。在 v2.1.203 之前，錯誤只命名遺失的 ID | 否 |49| `TaskOutput` | 檢索背景任務的輸出。已在任務的輸出檔案路徑上使用 `Read` 取代。當沒有任務符合 ID 時，錯誤會列出執行中的背景 agents（按 ID 和描述）。在 v2.1.203 之前，錯誤只命名遺失的 ID | 否 |

50| `TaskStop` | 按 ID 終止執行中的背景任務。{/* min-version: 2.1.198 */}它也接受 [agent-team 隊友](/zh-TW/agent-teams) 或按 agent ID 或名稱的具名背景 agent。在 v2.1.198 之前，它只接受背景任務 ID。{/* min-version: 2.1.203 */}當沒有任務符合 ID 時，錯誤會列出執行中的背景 agents（按 ID 和描述），包括另一個 agent 生成的 agents。在 v2.1.203 之前，錯誤列出執行中的隊友和具名 agents，但不包括另一個 agent 生成的背景 agents，因此無法從主對話中識別或停止這些 agents | 否 |50| `TaskStop` | 按 ID 終止執行中的背景任務。它也接受 [agent-team 隊友](/docs/zh-TW/agent-teams) 或按 agent ID 或名稱的具名背景 agent。在 v2.1.198 之前，它只接受背景任務 ID。當沒有任務符合 ID 時，錯誤會列出執行中的背景 agents（按 ID 和描述），包括另一個 agent 生成的 agents。在 v2.1.203 之前，錯誤列出執行中的隊友和具名 agents，但不包括另一個 agent 生成的背景 agents，因此無法從主對話中識別或停止這些 agents | 否 |

51| `TaskUpdate` | 更新任務狀態、依賴項、詳細資訊或刪除任務 | 否 |51| `TaskUpdate` | 更新任務狀態、依賴項、詳細資訊或刪除任務 | 否 |

52| `TodoWrite` | {/* min-version: 2.1.142 */}管理工作階段任務檢查清單。自 v2.1.142 起預設停用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新啟用 | 否 |52| `TodoWrite` | 管理工作階段任務檢查清單。自 v2.1.142 起預設停用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新啟用 | 否 |

53| `ToolSearch` | 當啟用 [tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 時，搜尋並載入延遲工具 | 否 |53| `ToolSearch` | 當啟用 [tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 時，搜尋並載入延遲工具 | 否 |

54| `WaitForMcpServers` | 等待一個或多個仍在背景連接的 [MCP servers](/zh-TW/mcp)，以便請求可以使用其工具而無需重新啟動工作階段。Claude 會在所需的伺服器尚未連接時呼叫它。僅在停用 [tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 時出現，因為啟用時 `ToolSearch` 會處理等待 | 否 |54| `WaitForMcpServers` | 等待一個或多個仍在背景連接的 [MCP servers](/docs/zh-TW/mcp)，以便請求可以使用其工具而無需重新啟動工作階段。Claude 會在所需的伺服器尚未連接時呼叫它。僅在停用 [tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 時出現，因為啟用時 `ToolSearch` 會處理等待 | 否 |

55| `WebFetch` | 從指定 URL 擷取內容。請參閱 [WebFetch 工具行為](#webfetch-tool-behavior) | 是 |55| `WebFetch` | 從指定 URL 擷取內容。請參閱 [WebFetch 工具行為](#webfetch-tool-behavior) | 是 |

56| `WebSearch` | 執行網路搜尋。請參閱 [WebSearch 工具行為](#websearch-tool-behavior) | 是 |56| `WebSearch` | 執行網路搜尋。請參閱 [WebSearch 工具行為](#websearch-tool-behavior) | 是 |

57| `Workflow` | 執行 [dynamic workflow](/zh-TW/workflows)：一個在背景協調許多 subagents 並傳回一個統一結果的指令碼 | 是 |57| `Workflow` | 執行 [dynamic workflow](/docs/zh-TW/workflows)：一個在背景協調許多 subagents 並傳回一個統一結果的指令碼 | 是 |

58| `Write` | 建立或覆寫檔案。請參閱 [Write 工具行為](#write-tool-behavior) | 是 |58| `Write` | 建立或覆寫檔案。請參閱 [Write 工具行為](#write-tool-behavior) | 是 |

59 59

60<h2 id="configure-tools-with-permission-rules-and-hooks">60<h2 id="configure-tools-with-permission-rules-and-hooks">

63 63

64在大多數情況下，Claude 會決定何時使用這些工具，您在與 Claude 互動時不需要自己命名它們。當定義權限和其他設定時，您直接參考工具名稱：64在大多數情況下，Claude 會決定何時使用這些工具，您在與 Claude 互動時不需要自己命名它們。當定義權限和其他設定時，您直接參考工具名稱：

65 65

~~66* 在設定中的 [`permissions.allow` 和 `permissions.deny`](/zh-TW/settings#available-settings)，以及 `/permissions` 介面~~66* 在設定中的 [`permissions.allow` 和 `permissions.deny`](/docs/zh-TW/settings#available-settings)，以及 `/permissions` 介面

~~67* 在 `--allowedTools` 和 `--disallowedTools` [CLI 旗標](/zh-TW/cli-reference) 中~~67* 在 `--allowedTools` 和 `--disallowedTools` [CLI 旗標](/docs/zh-TW/cli-reference) 中

~~68* 在 Agent SDK 的 [`allowedTools` 和 `disallowedTools`](/zh-TW/agent-sdk/permissions#allow-and-deny-rules) 選項中~~68* 在 Agent SDK 的 [`allowedTools` 和 `disallowedTools`](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) 選項中

~~69* 在 [subagent 的 `tools` 或 `disallowedTools`](/zh-TW/sub-agents#supported-frontmatter-fields) frontmatter 中~~69* 在 [subagent 的 `tools` 或 `disallowedTools`](/docs/zh-TW/sub-agents#supported-frontmatter-fields) frontmatter 中

~~70* 在 [skill 的 `allowed-tools`](/zh-TW/skills#frontmatter-reference) frontmatter 中~~70* 在 [skill 的 `allowed-tools`](/docs/zh-TW/skills#frontmatter-reference) frontmatter 中

~~71* 在 hook 的 [`if` 條件](/zh-TW/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field) 中~~71* 在 hook 的 [`if` 條件](/docs/zh-TW/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field) 中

72 72

73所有這些都接受相同的規則格式 `ToolName(specifier)`。specifier 取決於工具，多個工具共享一種格式：73所有這些都接受相同的規則格式 `ToolName(specifier)`。specifier 取決於工具，多個工具共享一種格式：

74 74

75| 規則格式 | 適用於 | 詳細資訊 |75| 規則格式 | 適用於 | 詳細資訊 |

76| :----------------------------- | :---------------------- | :----------------------------------------------------------------- |76| :----------------------------- | :---------------------- | :----------------------------------------------------------------- |

~~79| `Read(~/secrets/**)` | Read、Grep、Glob、LSP | [路徑模式匹配](/zh-TW/permissions#read-and-edit) |~~79| `Read(~/secrets/**)` | Read、Grep、Glob、LSP | [路徑模式匹配](/docs/zh-TW/permissions#read-and-edit) |

~~80| `Edit(/src/**)` | Edit、Write、NotebookEdit | [路徑模式匹配](/zh-TW/permissions#read-and-edit) |~~80| `Edit(/src/**)` | Edit、Write、NotebookEdit | [路徑模式匹配](/docs/zh-TW/permissions#read-and-edit) |

85 85

86此處未列出的工具，例如 `ExitPlanMode` 或 `ShareOnboardingGuide`，僅接受不帶 specifier 的裸工具名稱。86此處未列出的工具，例如 `ExitPlanMode` 或 `ShareOnboardingGuide`，僅接受不帶 specifier 的裸工具名稱。

87 87

88`Edit(...)` 允許規則也授予對相同路徑的讀取存取權，因此您不需要匹配的 `Read(...)` 規則。{/* min-version: 2.1.208 */}`Read(...)` 拒絕規則也會在相同路徑上阻止 Edit 工具，包括在該處建立新檔案，因為編輯需要讀取結果。Edit 上的 `Read` 拒絕檢查需要 Claude Code v2.1.208 或更新版本。88`Edit(...)` 允許規則也授予對相同路徑的讀取存取權，因此您不需要匹配的 `Read(...)` 規則。`Read(...)` 拒絕規則也會在相同路徑上阻止 Edit 工具，包括在該處建立新檔案，因為編輯需要讀取結果。Edit 上的 `Read` 拒絕檢查需要 Claude Code v2.1.208 或更新版本。

89 89

90Hook `matcher` 欄位使用裸工具名稱，而不是括號括起的規則格式。請參閱 [matcher 模式](/zh-TW/hooks#matcher-patterns) 以了解匹配規則。如需每個工具在 hooks 中傳遞給 `tool_input` 的欄位名稱，請參閱 [PreToolUse 輸入參考](/zh-TW/hooks#pretooluse-input)。90Hook `matcher` 欄位使用裸工具名稱，而不是括號括起的規則格式。請參閱 [matcher 模式](/docs/zh-TW/hooks#matcher-patterns) 以了解匹配規則。如需每個工具在 hooks 中傳遞給 `tool_input` 的欄位名稱，請參閱 [PreToolUse 輸入參考](/docs/zh-TW/hooks#pretooluse-input)。

91 91

92<h2 id="agent-tool-behavior">92<h2 id="agent-tool-behavior">

93 Agent 工具行為93 Agent 工具行為

95 95

96Agent 工具在單獨的 context window 中生成一個 subagent。subagent 自主地完成其任務，然後將單個文字結果傳回父對話。父對話看不到 subagent 的中間工具呼叫或輸出，只看到最終結果。96Agent 工具在單獨的 context window 中生成一個 subagent。subagent 自主地完成其任務，然後將單個文字結果傳回父對話。父對話看不到 subagent 的中間工具呼叫或輸出，只看到最終結果。

97 97

~~98若要限制 subagent 執行的轉數，請在 [subagent 定義](/zh-TW/sub-agents#supported-frontmatter-fields) 中設定 `maxTurns`。~~98若要限制 subagent 執行的轉數，請在 [subagent 定義](/docs/zh-TW/sub-agents#supported-frontmatter-fields) 中設定 `maxTurns`。

99 99

100相同的 Agent 工具也會在啟用 fork 模式時啟動 [forked subagents](/zh-TW/sub-agents#fork-the-current-conversation)。fork 繼承完整的父對話，而不是從頭開始，始終在背景執行，並仍在您的終端中顯示權限提示。本節的其餘部分描述命名的 subagents。100相同的 Agent 工具也會在啟用 fork 模式時啟動 [forked subagents](/docs/zh-TW/sub-agents#fork-the-current-conversation)。fork 繼承完整的父對話，而不是從頭開始，始終在背景執行，並仍在您的終端中顯示權限提示。本節的其餘部分描述命名的 subagents。

101 101

102命名的 subagent 可以使用哪些工具取決於 [subagent 定義](/zh-TW/sub-agents) 中的 `tools` 和 `disallowedTools` 欄位：102命名的 subagent 可以使用哪些工具取決於 [subagent 定義](/docs/zh-TW/sub-agents) 中的 `tools` 和 `disallowedTools` 欄位：

103 103

104* **兩個欄位都未設定**：subagent 繼承父對話可用的每個工具。104* **兩個欄位都未設定**：subagent 繼承父對話可用的每個工具。

105* **僅 `tools`**：subagent 僅獲得列出的工具。105* **僅 `tools`**：subagent 僅獲得列出的工具。

106* **僅 `disallowedTools`**：subagent 獲得除列出的工具外的每個父工具。106* **僅 `disallowedTools`**：subagent 獲得除列出的工具外的每個父工具。

107* **兩者都設定**：`disallowedTools` 優先。同時列在兩者中的工具會被移除。107* **兩者都設定**：`disallowedTools` 優先。同時列在兩者中的工具會被移除。

108 108

109當 subagent 的 `tools` 清單解析為完全沒有工具時，例如因為每個項目都拼寫錯誤或命名了一個對 subagents 不可用的工具，Agent 工具會傳回一個錯誤，列出這些項目，而不是啟動 subagent。{/* min-version: 2.1.208 */}在 v2.1.208 之前，subagent 會以無工具的方式啟動，並可能傳回空白或令人困惑的結果。109當 subagent 的 `tools` 清單解析為完全沒有工具時，例如因為每個項目都拼寫錯誤或命名了一個對 subagents 不可用的工具，Agent 工具會傳回一個錯誤，列出這些項目，而不是啟動 subagent。在 v2.1.208 之前，subagent 會以無工具的方式啟動，並可能傳回空白或令人困惑的結果。

110 110

111啟動 subagent 本身不會提示權限。Claude Code 在執行時會根據您的權限規則檢查 subagent 自己的工具呼叫。111啟動 subagent 本身不會提示權限。Claude Code 在執行時會根據您的權限規則檢查 subagent 自己的工具呼叫。

112 112

113{/* min-version: 2.1.198 */}自 v2.1.198 起，subagents 預設在背景執行；當 Claude 需要結果才能繼續時，會在前景執行一個。113自 v2.1.198 起，subagents 預設在背景執行；當 Claude 需要結果才能繼續時，會在前景執行一個。

114 114

115* **前景 subagents** 顯示您在主對話中會看到的相同權限提示，在每個工具呼叫發生時。115* **前景 subagents** 顯示您在主對話中會看到的相同權限提示，在每個工具呼叫發生時。

116* **背景 subagents** {/* min-version: 2.1.186 */}自 v2.1.186 起在您的主要工作階段中顯示權限提示。提示會指出哪個 subagent 在要求，按下 Esc 會拒絕該單一工具呼叫，而不會停止 subagent。在 v2.1.186 之前，背景 subagents 會自動拒絕任何否則會提示的工具呼叫，並在沒有該工具的情況下繼續。116* **背景 subagents** 自 v2.1.186 起在您的主要工作階段中顯示權限提示。提示會指出哪個 subagent 在要求，按下 Esc 會拒絕該單一工具呼叫，而不會停止 subagent。在 v2.1.186 之前，背景 subagents 會自動拒絕任何否則會提示的工具呼叫，並在沒有該工具的情況下繼續。

117 117

118若要首先限制 subagent 可以到達的內容，請縮小其 `tools` 欄位、將 Bash 排除在清單之外，或在您的設定中設定拒絕規則，如 [控制 subagent 功能](/zh-TW/sub-agents#control-subagent-capabilities) 中所述。如需有關選擇前景或背景的更多資訊，請參閱 [在前景或背景中執行 subagents](/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。118若要首先限制 subagent 可以到達的內容，請縮小其 `tools` 欄位、將 Bash 排除在清單之外，或在您的設定中設定拒絕規則，如 [控制 subagent 功能](/docs/zh-TW/sub-agents#control-subagent-capabilities) 中所述。如需有關選擇前景或背景的更多資訊，請參閱 [在前景或背景中執行 subagents](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。

119 119

120<h2 id="bash-tool-behavior">120<h2 id="bash-tool-behavior">

121 Bash 工具行為121 Bash 工具行為

123 123

124Bash 工具在單獨的程序中執行每個命令，具有以下持久性行為：124Bash 工具在單獨的程序中執行每個命令，具有以下持久性行為：

125 125

126* 當 Claude 在主工作階段中執行 `cd` 時，只要新的工作目錄保持在專案目錄內或您使用 `--add-dir`、`/add-dir` 或設定中的 `additionalDirectories` 新增的 [額外工作目錄](/zh-TW/permissions#working-directories) 內，新的工作目錄就會延續到後續的 Bash 命令。Subagent 工作階段永遠不會延續工作目錄變更。126* 當 Claude 在主工作階段中執行 `cd` 時，只要新的工作目錄保持在專案目錄內或您使用 `--add-dir`、`/add-dir` 或設定中的 `additionalDirectories` 新增的 [額外工作目錄](/docs/zh-TW/permissions#working-directories) 內，新的工作目錄就會延續到後續的 Bash 命令。Subagent 工作階段永遠不會延續工作目錄變更。

127 * 如果 `cd` 落在這些目錄之外，Claude Code 會重設為專案目錄，並將 `Shell cwd was reset to <dir>` 附加到工具結果。127 * 如果 `cd` 落在這些目錄之外，Claude Code 會重設為專案目錄，並將 `Shell cwd was reset to <dir>` 附加到工具結果。

128 * 若要停用此延續，使每個 Bash 命令都在專案目錄中啟動，請設定 `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`。128 * 若要停用此延續，使每個 Bash 命令都在專案目錄中啟動，請設定 `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`。

129* 環境變數不持久化。一個命令中的 `export` 在下一個命令中將不可用。129* 環境變數不持久化。一個命令中的 `export` 在下一個命令中將不可用。

130* 在您的 shell 啟動檔案中定義的別名和 shell 函式可用。在工作階段開始時，Claude Code 會來源 `~/.zshrc`、`~/.bashrc` 或 `~/.profile`（取決於您的 shell），擷取產生的別名、函式和 shell 選項，並將其應用於每個 Bash 命令。130* 在您的 shell 啟動檔案中定義的別名和 shell 函式可用。在工作階段開始時，Claude Code 會來源 `~/.zshrc`、`~/.bashrc` 或 `~/.profile`（取決於您的 shell），擷取產生的別名、函式和 shell 選項，並將其應用於每個 Bash 命令。

131 131

132在啟動 Claude Code 之前啟動您的 virtualenv 或 conda 環境。若要讓環境變數在 Bash 命令之間持久化，請在啟動 Claude Code 之前將 [`CLAUDE_ENV_FILE`](/zh-TW/env-vars) 設定為 shell 指令碼，或使用 [SessionStart hook](/zh-TW/hooks#persist-environment-variables) 動態填充它。132在啟動 Claude Code 之前啟動您的 virtualenv 或 conda 環境。若要讓環境變數在 Bash 命令之間持久化，請在啟動 Claude Code 之前將 [`CLAUDE_ENV_FILE`](/docs/zh-TW/env-vars) 設定為 shell 指令碼，或使用 [SessionStart hook](/docs/zh-TW/hooks#persist-environment-variables) 動態填充它。

133 133

134兩個限制限制每個命令：134兩個限制限制每個命令：

135 135

136* **逾時**：預設為兩分鐘。Claude 可以使用 `timeout` 參數要求每個命令最多 10 分鐘。使用 [`BASH_DEFAULT_TIMEOUT_MS` 和 `BASH_MAX_TIMEOUT_MS`](/zh-TW/env-vars) 覆寫預設值和上限。136* **逾時**：預設為兩分鐘。Claude 可以使用 `timeout` 參數要求每個命令最多 10 分鐘。使用 [`BASH_DEFAULT_TIMEOUT_MS` 和 `BASH_MAX_TIMEOUT_MS`](/docs/zh-TW/env-vars) 覆寫預設值和上限。

137* **輸出長度**：預設為 30,000 個字元。當命令產生超過該值的輸出時，Claude Code 會將完整輸出儲存到工作階段目錄中的檔案，並給予 Claude 檔案路徑加上開始處的簡短預覽。Claude 在需要其餘部分時讀取或搜尋該檔案。使用 [`BASH_MAX_OUTPUT_LENGTH`](/zh-TW/env-vars) 提高限制，最高可達 150,000 個字元的硬上限。137* **輸出長度**：預設為 30,000 個字元。當命令產生超過該值的輸出時，Claude Code 會將完整輸出儲存到工作階段目錄中的檔案，並給予 Claude 檔案路徑加上開始處的簡短預覽。Claude 在需要其餘部分時讀取或搜尋該檔案。使用 [`BASH_MAX_OUTPUT_LENGTH`](/docs/zh-TW/env-vars) 提高限制，最高可達 150,000 個字元的硬上限。

138 138

139對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 `run_in_background: true` 以將命令作為背景任務啟動，並在其執行時繼續工作。使用 `/tasks` 列出和停止背景任務。在使用 `-p` 旗標的非互動模式中，[背景任務在執行的最終結果後不久結束](/zh-TW/headless#background-tasks-at-exit)。139對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 `run_in_background: true` 以將命令作為背景任務啟動，並在其執行時繼續工作。使用 `/tasks` 列出和停止背景任務。在使用 `-p` 旗標的非互動模式中，[背景任務在執行的最終結果後不久結束](/docs/zh-TW/headless#background-tasks-at-exit)。

140 140

141<h2 id="edit-tool-behavior">141<h2 id="edit-tool-behavior">

142 Edit 工具行為142 Edit 工具行為

144 144

145Edit 工具執行確切的字串替換。它採用 `old_string` 和 `new_string` 並用第二個替換第一個。它不使用正規表達式或模糊匹配。145Edit 工具執行確切的字串替換。它採用 `old_string` 和 `new_string` 並用第二個替換第一個。它不使用正規表達式或模糊匹配。

146 146

147三個檢查必須通過才能應用編輯。{/* min-version: 2.1.208 */}在任何檢查之前，由 [`Read` 拒絕規則](/zh-TW/permissions#tool-specific-permission-rules) 匹配的路徑會被拒絕，包括在該處建立新檔案。此拒絕需要 Claude Code v2.1.208 或更新版本。147三個檢查必須通過才能應用編輯。在任何檢查之前，由 [`Read` 拒絕規則](/docs/zh-TW/permissions#tool-specific-permission-rules) 匹配的路徑會被拒絕，包括在該處建立新檔案。此拒絕需要 Claude Code v2.1.208 或更新版本。

148 148

149* **編輯前讀取**：Claude 在目前對話中讀取檔案後才編輯它，且以 [`PARTIAL view` 通知](#read-tool-behavior) 中斷的讀取不計算。Claude Opus 4.6、Claude Haiku 4.5 和更舊的模型始終需要讀取。較新的模型可以在讀取不需要權限提示且 Read 工具可用時編輯未讀檔案。149* **編輯前讀取**：Claude 在目前對話中讀取檔案後才編輯它，且以 [`PARTIAL view` 通知](#read-tool-behavior) 中斷的讀取不計算。Claude Opus 4.6、Claude Haiku 4.5 和更舊的模型始終需要讀取。較新的模型可以在讀取不需要權限提示且 Read 工具可用時編輯未讀檔案。

150* **匹配**：`old_string` 必須在檔案中完全按照撰寫方式出現。單個空白字元或縮排差異足以導致不匹配。150* **匹配**：`old_string` 必須在檔案中完全按照撰寫方式出現。單個空白字元或縮排差異足以導致不匹配。

151* **唯一性**：`old_string` 必須恰好出現一次。當它出現多次時，Claude 要麼提供更長的字串，其周圍有足夠的上下文來確定一個出現，要麼設定 `replace_all: true` 以替換所有出現。151* **唯一性**：`old_string` 必須恰好出現一次。當它出現多次時，Claude 要麼提供更長的字串，其周圍有足夠的上下文來確定一個出現，要麼設定 `replace_all: true` 以替換所有出現。

152 152

153在 Claude 最後讀取檔案後在磁碟上變更的檔案仍然可以編輯，當 `old_string` 與目前內容完全且明確匹配，且 Claude Code 可以讀取檔案而不提示時。針對檔案的目前內容進行匹配可保持安全，結果會注意到檔案包含其他變更，因此 Claude 在依賴周圍內容的編輯之前重新讀取它。在任何其他情況下，例如過時的 `old_string` 或不使用 `replace_all` 匹配多次的情況，Claude 在編輯前重新讀取檔案。{/* min-version: 2.1.208 */}未讀和已變更檔案的寬鬆處理需要 Claude Code v2.1.208 或更新版本；在此之前，Claude Code 拒絕對它在對話中未讀過或在讀取後在磁碟上變更的任何檔案進行編輯。153在 Claude 最後讀取檔案後在磁碟上變更的檔案仍然可以編輯，當 `old_string` 與目前內容完全且明確匹配，且 Claude Code 可以讀取檔案而不提示時。針對檔案的目前內容進行匹配可保持安全，結果會注意到檔案包含其他變更，因此 Claude 在依賴周圍內容的編輯之前重新讀取它。在任何其他情況下，例如過時的 `old_string` 或不使用 `replace_all` 匹配多次的情況，Claude 在編輯前重新讀取檔案。未讀和已變更檔案的寬鬆處理需要 Claude Code v2.1.208 或更新版本；在此之前，Claude Code 拒絕對它在對話中未讀過或在讀取後在磁碟上變更的任何檔案進行編輯。

154 154

155使用 Bash 檢視檔案也滿足編輯前讀取要求，當命令是 `cat`、`head`、`tail`、`sed -n 'X,Yp'`、`grep`、`egrep` 或 `fgrep` 在單個檔案上，沒有管道或重定向時。管道輸出和其他 Bash 命令不計算編輯前讀取檢查。155使用 Bash 檢視檔案也滿足編輯前讀取要求，當命令是 `cat`、`head`、`tail`、`sed -n 'X,Yp'`、`grep`、`egrep` 或 `fgrep` 在單個檔案上，沒有管道或重定向時。管道輸出和其他 Bash 命令不計算編輯前讀取檢查。

156 156

157這僅影響編輯資格，不影響權限。[Read 和 Edit 拒絕規則](/zh-TW/permissions#tool-specific-permission-rules) 也適用於 Claude Code 在 Bash 中識別的檔案命令，例如 `cat`、`head`、`tail`、`sed` 和 `grep`，但不適用於間接讀取或寫入檔案的任意子程序，例如自己開啟檔案的 Python 或 Node 指令碼。識別用於拒絕規則的命令集與上述編輯前讀取清單不同：例如，`egrep` 和 `fgrep` 計算編輯前讀取但不針對 Read 拒絕規則進行檢查。如需涵蓋每個程序的作業系統級別強制執行，請 [啟用沙箱](/zh-TW/sandboxing)。157這僅影響編輯資格，不影響權限。[Read 和 Edit 拒絕規則](/docs/zh-TW/permissions#tool-specific-permission-rules) 也適用於 Claude Code 在 Bash 中識別的檔案命令，例如 `cat`、`head`、`tail`、`sed` 和 `grep`，但不適用於間接讀取或寫入檔案的任意子程序，例如自己開啟檔案的 Python 或 Node 指令碼。識別用於拒絕規則的命令集與上述編輯前讀取清單不同：例如，`egrep` 和 `fgrep` 計算編輯前讀取但不針對 Read 拒絕規則進行檢查。如需涵蓋每個程序的作業系統級別強制執行，請 [啟用沙箱](/docs/zh-TW/sandboxing)。

158 158

159<h2 id="glob-tool-behavior">159<h2 id="glob-tool-behavior">

160 Glob 工具行為160 Glob 工具行為

170 170

171Glob 預設不尊重 `.gitignore`，因此它會找到 gitignored 檔案以及追蹤的檔案。這與 [Grep](#grep-tool-behavior) 不同，後者跳過 gitignored 檔案。若要讓 Glob 尊重 `.gitignore`，請在啟動 Claude Code 之前設定 `CLAUDE_CODE_GLOB_NO_IGNORE=false`。171Glob 預設不尊重 `.gitignore`，因此它會找到 gitignored 檔案以及追蹤的檔案。這與 [Grep](#grep-tool-behavior) 不同，後者跳過 gitignored 檔案。若要讓 Glob 尊重 `.gitignore`，請在啟動 Claude Code 之前設定 `CLAUDE_CODE_GLOB_NO_IGNORE=false`。

172 172

173包含空位元組的 `pattern` 或 `path` 值會傳回錯誤，要求 Claude 移除它。{/* min-version: 2.1.208 */}173包含空位元組的 `pattern` 或 `path` 值會傳回錯誤，要求 Claude 移除它。

174 174

175<h2 id="grep-tool-behavior">175<h2 id="grep-tool-behavior">

176 Grep 工具行為176 Grep 工具行為

180 180

181Grep 建立在 [ripgrep](https://github.com/BurntSushi/ripgrep) 上，使用 ripgrep 的正規表達式語法，而不是 POSIX grep。包含正規表達式元字元的模式需要轉義。例如，在 Go 程式碼中查找 `interface{}` 需要模式 `interface\{\}`。181Grep 建立在 [ripgrep](https://github.com/BurntSushi/ripgrep) 上，使用 ripgrep 的正規表達式語法，而不是 POSIX grep。包含正規表達式元字元的模式需要轉義。例如，在 Go 程式碼中查找 `interface{}` 需要模式 `interface\{\}`。

182 182

183一個模式、glob 或檔案類型若被 ripgrep 拒絕，會返回包含 ripgrep 診斷的錯誤，以便 Claude 可以更正輸入並再次搜尋。{/* min-version: 2.1.208 */}在 v2.1.208 之前，Claude Code 將被拒絕的輸入報告為 `No files found`，而不是錯誤，即使搜尋的文字存在於目標檔案中。183一個模式、glob 或檔案類型若被 ripgrep 拒絕，會返回包含 ripgrep 診斷的錯誤，以便 Claude 可以更正輸入並再次搜尋。在 v2.1.208 之前，Claude Code 將被拒絕的輸入報告為 `No files found`，而不是錯誤，即使搜尋的文字存在於目標檔案中。

184 184

185三個輸出模式控制返回的內容：185三個輸出模式控制返回的內容：

186 186

187* `files_with_matches`：僅檔案路徑，無行內容。這是預設值。187* `files_with_matches`：僅檔案路徑，無行內容。這是預設值。

188* `content`：匹配的行，帶有檔案和行號。188* `content`：匹配的行，帶有檔案和行號。

189* `count`：每個檔案的匹配計數，後面跟著所有匹配檔案的總計。{/* min-version: 2.1.208 */}總計涵蓋每個匹配，即使工具的 `head_limit` 或 `offset` 參數截斷了列出的每個檔案項目。在 v2.1.208 之前，總計只加總列出的項目。189* `count`：每個檔案的匹配計數，後面跟著所有匹配檔案的總計。總計涵蓋每個匹配，即使工具的 `head_limit` 或 `offset` 參數截斷了列出的每個檔案項目。在 v2.1.208 之前，總計只加總列出的項目。

190 190

191Claude 可以使用 `glob` 參數（例如 `**/*.tsx`）按檔案限制結果，或使用 `type` 參數（例如 `py` 或 `rust`）按語言限制結果。預設情況下，模式在單行內匹配。Claude 可以設定 `multiline: true` 以跨行邊界匹配。191Claude 可以使用 `glob` 參數（例如 `**/*.tsx`）按檔案限制結果，或使用 `type` 參數（例如 `py` 或 `rust`）按語言限制結果。預設情況下，模式在單行內匹配。Claude 可以設定 `multiline: true` 以跨行邊界匹配。

192 192

206* 尋找介面的實作206* 尋找介面的實作

207* 追蹤呼叫階層207* 追蹤呼叫階層

208 208

209該工具在您安裝您的語言的 [程式碼智慧外掛](/zh-TW/discover-plugins#code-intelligence) 之前處於非作用中狀態。該外掛包含語言伺服器設定，您需要單獨安裝伺服器二進位檔。209該工具在您安裝您的語言的 [程式碼智慧外掛](/docs/zh-TW/discover-plugins#code-intelligence) 之前處於非作用中狀態。該外掛包含語言伺服器設定，您需要單獨安裝伺服器二進位檔。

210 210

211<h2 id="monitor-tool">211<h2 id="monitor-tool">

212 Monitor 工具212 Monitor 工具

224 224

225您可以在同一工作階段中繼續工作，Claude 會在事件發生時插入。透過要求 Claude 取消監視或結束工作階段來停止監視。225您可以在同一工作階段中繼續工作，Claude 會在事件發生時插入。透過要求 Claude 取消監視或結束工作階段來停止監視。

226 226

227當 Monitor 執行命令時，它使用與 [Bash 相同的權限規則](/zh-TW/permissions#tool-specific-permission-rules)，因此您為 Bash 設定的 `allow` 和 `deny` 模式也適用於此處。[WebSocket 來源](#websocket-source)有其自己的核准提示。227當 Monitor 執行命令時，它使用與 [Bash 相同的權限規則](/docs/zh-TW/permissions#tool-specific-permission-rules)，因此您為 Bash 設定的 `allow` 和 `deny` 模式也適用於此處。[WebSocket 來源](#websocket-source)有其自己的核准提示。

228 228

229該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。當設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，它也不可用。229該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。當設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，它也不可用。

230 230

231外掛可以宣告在外掛啟用時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 [外掛監視](/zh-TW/plugins-reference#monitors)。231外掛可以宣告在外掛啟用時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 [外掛監視](/docs/zh-TW/plugins-reference#monitors)。

232 232

233<h3 id="websocket-source">233<h3 id="websocket-source">

234 WebSocket 來源234 WebSocket 來源

256 256

257開啟 WebSocket 會提示核准，提示不提供跳過相同主機的未來提示的選項。257開啟 WebSocket 會提示核准，提示不提供跳過相同主機的未來提示的選項。

258 258

259Claude Code 拒絕指向私有、連結本地或雲端中繼資料位址的 URL，包括解析為該位址的主機名稱。它也拒絕 `sandbox.network.deniedDomains` 中的主機，以及當在受管設定中設定 [`allowManagedDomainsOnly`](/zh-TW/settings#sandbox-settings) 時，受管允許清單外的任何主機。259Claude Code 拒絕指向私有、連結本地或雲端中繼資料位址的 URL，包括解析為該位址的主機名稱。它也拒絕 `sandbox.network.deniedDomains` 中的主機，以及當在受管設定中設定 [`allowManagedDomainsOnly`](/docs/zh-TW/settings#sandbox-settings) 時，受管允許清單外的任何主機。

260 260

261<h2 id="notebookedit-tool-behavior">261<h2 id="notebookedit-tool-behavior">

262 NotebookEdit 工具行為262 NotebookEdit 工具行為

308 308

309三個額外的設定控制 PowerShell 的使用位置：309三個額外的設定控制 PowerShell 的使用位置：

310 310

311* [`settings.json`](/zh-TW/settings#available-settings) 中的 `"defaultShell": "powershell"`：透過 PowerShell 路由互動式 `!` 命令。需要啟用 PowerShell 工具。311* [`settings.json`](/docs/zh-TW/settings#available-settings) 中的 `"defaultShell": "powershell"`：透過 PowerShell 路由互動式 `!` 命令。需要啟用 PowerShell 工具。

312* 個別 [command hooks](/zh-TW/hooks#command-hook-fields) 上的 `"shell": "powershell"`：在 PowerShell 中執行該 hook。Hooks 直接生成 PowerShell，因此無論 `CLAUDE_CODE_USE_POWERSHELL_TOOL` 如何，這都有效。312* 個別 [command hooks](/docs/zh-TW/hooks#command-hook-fields) 上的 `"shell": "powershell"`：在 PowerShell 中執行該 hook。Hooks 直接生成 PowerShell，因此無論 `CLAUDE_CODE_USE_POWERSHELL_TOOL` 如何，這都有效。

313* [skill frontmatter](/zh-TW/skills#frontmatter-reference) 中的 `shell: powershell`：在 PowerShell 中執行 `` !`command` `` 區塊。需要啟用 PowerShell 工具。313* [skill frontmatter](/docs/zh-TW/skills#frontmatter-reference) 中的 `shell: powershell`：在 PowerShell 中執行 `` !`command` `` 區塊。需要啟用 PowerShell 工具。

314 314

315Bash 工具部分中描述的相同主工作階段工作目錄重設行為適用於 PowerShell 命令，包括 `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` 環境變數。315Bash 工具部分中描述的相同主工作階段工作目錄重設行為適用於 PowerShell 命令，包括 `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` 環境變數。

316 316

317{/* min-version: 2.1.196 */}自 v2.1.196 起，PowerShell 工具符合 Bash 工具對搜尋和 diff 結束代碼的處理方式。來自 `grep`、`egrep`、`fgrep` 和 `git grep` 的結束代碼 1 表示沒有符合項目，來自 `git diff` 的結束代碼 1 表示存在差異，因此這些結果不會作為命令失敗報告給 Claude。317自 v2.1.196 起，PowerShell 工具符合 Bash 工具對搜尋和 diff 結束代碼的處理方式。來自 `grep`、`egrep`、`fgrep` 和 `git grep` 的結束代碼 1 表示沒有符合項目，來自 `git diff` 的結束代碼 1 表示存在差異，因此這些結果不會作為命令失敗報告給 Claude。

318 318

319<h3 id="preview-limitations">319<h3 id="preview-limitations">

320 預覽限制320 預覽限制

333 333

334預設情況下，Read 從開始傳回檔案。當整個檔案讀取超過令牌限制時，Read 傳回第一頁並附帶 `PARTIAL view` 通知，告訴 Claude 它收到了多少檔案內容以及如何使用 `offset` 和 `limit` 讀取更多內容。傳遞明確的 `offset` 或 `limit` 且仍然超過令牌限制的讀取會傳回錯誤。334預設情況下，Read 從開始傳回檔案。當整個檔案讀取超過令牌限制時，Read 傳回第一頁並附帶 `PARTIAL view` 通知，告訴 Claude 它收到了多少檔案內容以及如何使用 `offset` 和 `limit` 讀取更多內容。傳遞明確的 `offset` 或 `limit` 且仍然超過令牌限制的讀取會傳回錯誤。

335 335

336具有明確 `limit` 的讀取會在選定的行超過令牌限制可能容納的內容時立即停止，並傳回錯誤而不載入其餘範圍。該錯誤告訴 Claude 使用較小的 `limit`，或在單一行非常大時改用 [Grep](#grep-tool-behavior) 搜尋特定內容。{/* min-version: 2.1.208 */}在 v2.1.208 之前，Claude Code 在拒絕前會將整個範圍載入記憶體，因此具有極長單一行的檔案可能會耗盡記憶體。336具有明確 `limit` 的讀取會在選定的行超過令牌限制可能容納的內容時立即停止，並傳回錯誤而不載入其餘範圍。該錯誤告訴 Claude 使用較小的 `limit`，或在單一行非常大時改用 [Grep](#grep-tool-behavior) 搜尋特定內容。在 v2.1.208 之前，Claude Code 在拒絕前會將整個範圍載入記憶體，因此具有極長單一行的檔案可能會耗盡記憶體。

337 337

338讀取空檔案會傳回通知，表示檔案存在但其內容為空，而超過最後一行的 `offset` 會傳回通知，提供檔案的行數。{/* min-version: 2.1.208 */}在 v2.1.208 之前，讀取空檔案會傳回超過末尾的通知。338讀取空檔案會傳回通知，表示檔案存在但其內容為空，而超過最後一行的 `offset` 會傳回通知，提供檔案的行數。在 v2.1.208 之前，讀取空檔案會傳回超過末尾的通知。

339 339

340Read 處理純文字以外的多種檔案類型：340Read 處理純文字以外的多種檔案類型：

341 341

342* **影像**：PNG、JPG 和其他影像格式作為 Claude 可以看到的視覺內容傳回，而不是原始位元組。Claude Code 在傳送前調整大小並重新壓縮大型影像以適應模型的影像大小限制，因此 Claude 可能會看到大型螢幕截圖的縮小版本。{/* min-version: 2.1.196 */}自 v2.1.196 起，在調整大小後仍然大於 500KB 的影像會以降低品質的 JPEG 重新編碼，其像素尺寸保持不變。如果 Claude 在大型影像中遺漏細微的像素級詳細資訊，請要求它先裁剪感興趣的區域，例如使用 ImageMagick 透過 Bash。342* **影像**：PNG、JPG 和其他影像格式作為 Claude 可以看到的視覺內容傳回，而不是原始位元組。Claude Code 在傳送前調整大小並重新壓縮大型影像以適應模型的影像大小限制，因此 Claude 可能會看到大型螢幕截圖的縮小版本。自 v2.1.196 起，在調整大小後仍然大於 500KB 的影像會以降低品質的 JPEG 重新編碼，其像素尺寸保持不變。如果 Claude 在大型影像中遺漏細微的像素級詳細資訊，請要求它先裁剪感興趣的區域，例如使用 ImageMagick 透過 Bash。

343* **PDF**：Claude 完整讀取短 `.pdf` 檔案。對於超過 10 頁的 PDF，它使用 `pages` 參數（例如 `"1-5"`）按範圍讀取，一次最多 20 頁。343* **PDF**：Claude 完整讀取短 `.pdf` 檔案。對於超過 10 頁的 PDF，它使用 `pages` 參數（例如 `"1-5"`）按範圍讀取，一次最多 20 頁。

344* **Jupyter notebooks**：`.ipynb` 檔案傳回所有儲存格及其輸出，包括程式碼、markdown 和視覺化。344* **Jupyter notebooks**：`.ipynb` 檔案傳回所有儲存格及其輸出，包括程式碼、markdown 和視覺化。

345 345

360* 回應會快取 15 分鐘，因此相同 URL 的重複擷取會快速傳回。360* 回應會快取 15 分鐘，因此相同 URL 的重複擷取會快速傳回。

361* 當 URL 重定向到不同的主機時，WebFetch 傳回文字結果，命名原始 URL 和重定向目標，而不是跟隨它。Claude 然後使用第二個 WebFetch 呼叫擷取新 URL。361* 當 URL 重定向到不同的主機時，WebFetch 傳回文字結果，命名原始 URL 和重定向目標，而不是跟隨它。Claude 然後使用第二個 WebFetch 呼叫擷取新 URL。

362 362

363在預設和 `acceptEdits` 權限模式中，WebFetch 在首次到達新網域時提示，但有一組內建的預先核准文件網域除外，這些網域無需提示即可擷取。若要提前允許另一個網域而不提示，請新增像 `WebFetch(domain:example.com)` 這樣的權限規則。`auto` 和 `bypassPermissions` [權限模式](/zh-TW/permissions#permission-modes) 完全跳過提示。363在預設和 `acceptEdits` 權限模式中，WebFetch 在首次到達新網域時提示，但有一組內建的預先核准文件網域除外，這些網域無需提示即可擷取。若要提前允許另一個網域而不提示，請新增像 `WebFetch(domain:example.com)` 這樣的權限規則。`auto` 和 `bypassPermissions` [權限模式](/docs/zh-TW/permissions#permission-modes) 完全跳過提示。

364 364

365`deny`、`ask` 或 `allow` 中的明確 `WebFetch(domain:...)` 規則優先於預先核准的集合，因此您可以封鎖預先核准的網域或要求提示。365`deny`、`ask` 或 `allow` 中的明確 `WebFetch(domain:...)` 規則優先於預先核准的集合，因此您可以封鎖預先核准的網域或要求提示。

366 366

367WebFetch 設定以 `Claude-User` 開頭的 `User-Agent` 標頭，以及偏好 Markdown 而不是 HTML 的 `Accept` 標頭，以便支援內容協商的伺服器可以直接傳回 Markdown。您可以單獨設定 [sandbox](/zh-TW/sandboxing) 網路規則，因此您希望沙箱程序到達的網域仍需要明確的沙箱權限規則。367WebFetch 設定以 `Claude-User` 開頭的 `User-Agent` 標頭，以及偏好 Markdown 而不是 HTML 的 `Accept` 標頭，以便支援內容協商的伺服器可以直接傳回 Markdown。您可以單獨設定 [sandbox](/docs/zh-TW/sandboxing) 網路規則，因此您希望沙箱程序到達的網域仍需要明確的沙箱權限規則。

368 368

369<h2 id="websearch-tool-behavior">369<h2 id="websearch-tool-behavior">

370 WebSearch 工具行為370 WebSearch 工具行為

374 374

375該工具可能在傳回結果之前發出最多八個後端搜尋，在內部精煉搜尋。Claude 可以使用 `allowed_domains` 限制結果以僅包含某些主機，或使用 `blocked_domains` 排除它們。這兩個清單不能在單個呼叫中組合。375該工具可能在傳回結果之前發出最多八個後端搜尋，在內部精煉搜尋。Claude 可以使用 `allowed_domains` 限制結果以僅包含某些主機，或使用 `blocked_domains` 排除它們。這兩個清單不能在單個呼叫中組合。

376 376

377搜尋後端不可設定。若要使用不同的提供者進行搜尋，請新增公開搜尋工具的 [MCP server](/zh-TW/mcp)。377搜尋後端不可設定。若要使用不同的提供者進行搜尋，請新增公開搜尋工具的 [MCP server](/docs/zh-TW/mcp)。

378 378

379WebSearch 權限規則不採用 specifier。`allow` 或 `deny` 中的裸 `WebSearch` 項目是唯一的形式。379WebSearch 權限規則不採用 specifier。`allow` 或 `deny` 中的裸 `WebSearch` 項目是唯一的形式。

380 380

381<Note>381<Note>

382 WebSearch 在 Claude API、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud 的 Agent Platform 上，它適用於 Claude 4 及更新版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公開伺服器端 web search 工具。382 WebSearch 在 Claude API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud 的 Agent Platform 上，它適用於 Claude 4 及更新版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公開伺服器端 web search 工具。

383</Note>383</Note>

384 384

385<h2 id="write-tool-behavior">385<h2 id="write-tool-behavior">

407Claude 提供對話摘要。如需確切的 MCP 工具名稱，請執行 `/mcp`。407Claude 提供對話摘要。如需確切的 MCP 工具名稱，請執行 `/mcp`。

408 408

409<Note>409<Note>

410 [advisor tool](/zh-TW/advisor) 是一個 [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)，由 API 執行，而不是 Claude Code 實作的工具。它沒有您可以在權限規則或 hook 匹配器中參考的名稱。410 [advisor tool](/docs/zh-TW/advisor) 是一個 [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)，由 API 執行，而不是 Claude Code 實作的工具。它沒有您可以在權限規則或 hook 匹配器中參考的名稱。

411</Note>411</Note>

412 412

413<h2 id="see-also">413<h2 id="see-also">

414 另請參閱414 另請參閱

415</h2>415</h2>

416 416

417* [MCP servers](/zh-TW/mcp)：透過連接外部伺服器新增自訂工具417* [MCP servers](/docs/zh-TW/mcp)：透過連接外部伺服器新增自訂工具

418* [權限](/zh-TW/permissions)：權限系統、規則語法和工具特定模式418* [權限](/docs/zh-TW/permissions)：權限系統、規則語法和工具特定模式

419* [Subagents](/zh-TW/sub-agents)：為 subagents 設定工具存取419* [Subagents](/docs/zh-TW/sub-agents)：為 subagents 設定工具存取

420* [Hooks](/zh-TW/hooks-guide)：在工具執行前後執行自訂命令420* [Hooks](/docs/zh-TW/hooks-guide)：在工具執行前後執行自訂命令

troubleshoot-install.md +17 −17

Details

6 6

7> 修復安裝或登入 Claude Code 時的 command not found、PATH、權限、網路和身份驗證錯誤。7> 修復安裝或登入 Claude Code 時的 command not found、PATH、權限、網路和身份驗證錯誤。

8 8

9如果安裝失敗或無法登入，請在下方找到您的錯誤。如需 Claude Code 正常運作後的執行時問題，請參閱[排除故障](/zh-TW/troubleshooting)。如需設定問題（例如設定未套用或 hooks 未觸發），請參閱[偵錯您的設定](/zh-TW/debug-your-config)。9如果安裝失敗或無法登入，請在下方找到您的錯誤。如需 Claude Code 正常運作後的執行時問題，請參閱[排除故障](/docs/zh-TW/troubleshooting)。如需設定問題（例如設定未套用或 hooks 未觸發），請參閱[偵錯您的設定](/docs/zh-TW/debug-your-config)。

10 10

11<h2 id="find-your-error">11<h2 id="find-your-error">

12 找到您的錯誤12 找到您的錯誤

42| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |42| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

43| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |43| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

45 45

46如果您的問題未列出，請執行下面的診斷檢查以縮小原因範圍。46如果您的問題未列出，請執行下面的診斷檢查以縮小原因範圍。

47 47

48<Tip>48<Tip>

49 如果您寧願完全跳過終端，[Claude Code Desktop 應用程式](/zh-TW/desktop-quickstart)可讓您透過圖形介面安裝和使用 Claude Code。下載適用於 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) 或 [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 的版本，無需任何命令列設定即可開始編碼。在 Linux 上，請按照 [Linux 安裝說明](/zh-TW/desktop-linux)使用 apt 安裝應用程式。49 如果您寧願完全跳過終端，[Claude Code Desktop 應用程式](/docs/zh-TW/desktop-quickstart)可讓您透過圖形介面安裝和使用 Claude Code。下載適用於 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) 或 [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 的版本，無需任何命令列設定即可開始編碼。在 Linux 上，請按照 [Linux 安裝說明](/docs/zh-TW/desktop-linux)使用 apt 安裝應用程式。

50</Tip>50</Tip>

51 51

52<h2 id="run-diagnostic-checks">52<h2 id="run-diagnostic-checks">

100如果安裝成功但執行 `claude` 時收到 `command not found` 或 `not recognized` 錯誤，安裝目錄不在您的 PATH 中。您的 shell 在 PATH 中列出的目錄中搜尋程式，安裝程式在 macOS/Linux 上將 `claude` 放在 `~/.local/bin/claude`，或在 Windows 上放在 `%USERPROFILE%\.local\bin\claude.exe`。100如果安裝成功但執行 `claude` 時收到 `command not found` 或 `not recognized` 錯誤，安裝目錄不在您的 PATH 中。您的 shell 在 PATH 中列出的目錄中搜尋程式，安裝程式在 macOS/Linux 上將 `claude` 放在 `~/.local/bin/claude`，或在 Windows 上放在 `%USERPROFILE%\.local\bin\claude.exe`。

101 101

102<Note>102<Note>

103 [VS Code 擴充功能](/zh-TW/vs-code)不會將 `claude` 放在此位置。它在擴充功能目錄內為其自己的聊天面板捆綁了一份私有的 CLI 副本，並且不會將其新增到 PATH。如果您只安裝了擴充功能，`~/.local/bin/claude` 將不存在。執行[獨立安裝](/zh-TW/setup)以從終端使用 `claude`，然後繼續下面的步驟。103 [VS Code 擴充功能](/docs/zh-TW/vs-code)不會將 `claude` 放在此位置。它在擴充功能目錄內為其自己的聊天面板捆綁了一份私有的 CLI 副本，並且不會將其新增到 PATH。如果您只安裝了擴充功能，`~/.local/bin/claude` 將不存在。執行[獨立安裝](/docs/zh-TW/setup)以從終端使用 `claude`，然後繼續下面的步驟。

104</Note>104</Note>

105 105

106透過列出您的 PATH 項目並篩選 `local/bin` 來檢查安裝目錄是否在您的 PATH 中：106透過列出您的 PATH 項目並篩選 `local/bin` 來檢查安裝目錄是否在您的 PATH 中：

196 ls -la ~/.local/bin/claude196 ls -la ~/.local/bin/claude

197 ```197 ```

198 198

199 原生安裝會顯示一個指向 `~/.local/share/claude/versions/` 的符號連結。您在此路徑建立的指令碼或符號連結是自訂啟動程式，[自動更新會保留在原位](/zh-TW/setup#auto-updates)。199 原生安裝會顯示一個指向 `~/.local/share/claude/versions/` 的符號連結。您在此路徑建立的指令碼或符號連結是自訂啟動程式，[自動更新會保留在原位](/docs/zh-TW/setup#auto-updates)。

200 200

201 如果任一 `ls` 命令列印 `No such file or directory`，那不是錯誤。這表示該位置沒有安裝任何內容，所以繼續進行下一個檢查。201 如果任一 `ls` 命令列印 `No such file or directory`，那不是錯誤。這表示該位置沒有安裝任何內容，所以繼續進行下一個檢查。

202 202

294Get-Command claude | Select-Object Source294Get-Command claude | Select-Object Source

295```295```

296 296

297在 Linux 上，檢查遺失的共用程式庫。如果 `ldd` 顯示遺失的程式庫，您可能需要安裝系統套件。在 Alpine Linux 和其他基於 musl 的發行版上，請參閱 [Alpine Linux 設定](/zh-TW/setup#alpine-linux-and-musl-based-distributions)。297在 Linux 上，檢查遺失的共用程式庫。如果 `ldd` 顯示遺失的程式庫，您可能需要安裝系統套件。在 Alpine Linux 和其他基於 musl 的發行版上，請參閱 [Alpine Linux 設定](/docs/zh-TW/setup#alpine-linux-and-musl-based-distributions)。

298 298

299```bash theme={null}299```bash theme={null}

300ldd "$(command -v claude)" | grep "not found"300ldd "$(command -v claude)" | grep "not found"

413brew install --cask claude-code413brew install --cask claude-code

414```414```

415 415

416如果 Homebrew 安裝的 Claude Code 版本比您預期的舊，通常是相同的過時索引導致的。`claude-code` cask 追蹤穩定通道，通常比最新版本晚約一週；若要取得最新版本，請改為執行 `brew install --cask claude-code@latest`。請參閱[設定發行通道](/zh-TW/setup#configure-release-channel)以了解兩個 cask 之間的差異。416如果 Homebrew 安裝的 Claude Code 版本比您預期的舊，通常是相同的過時索引導致的。`claude-code` cask 追蹤穩定通道，通常比最新版本晚約一週；若要取得最新版本，請改為執行 `brew install --cask claude-code@latest`。請參閱[設定發行通道](/docs/zh-TW/setup#configure-release-channel)以了解兩個 cask 之間的差異。

417 417

418<h3 id="tls-or-ssl-connection-errors">418<h3 id="tls-or-ssl-connection-errors">

419 TLS 或 SSL 連線錯誤419 TLS 或 SSL 連線錯誤

468 curl -sI https://downloads.claude.ai/claude-code-releases/latest468 curl -sI https://downloads.claude.ai/claude-code-releases/latest

469 ```469 ```

470 470

4712. **如果在代理後面**，設定 `HTTPS_PROXY` 以便安裝程式可以透過它路由。請參閱[代理設定](/zh-TW/network-config#proxy-configuration)以取得詳細資訊。4712. **如果在代理後面**，設定 `HTTPS_PROXY` 以便安裝程式可以透過它路由。請參閱[代理設定](/docs/zh-TW/network-config#proxy-configuration)以取得詳細資訊。

472 ```bash theme={null}472 ```bash theme={null}

473 export HTTPS_PROXY=http://proxy.example.com:8080473 export HTTPS_PROXY=http://proxy.example.com:8080

474 curl -fsSL https://claude.ai/install.sh | bash474 curl -fsSL https://claude.ai/install.sh | bash

551 551

552在 v2.1.200 之前，指令碼僅以 shell 的裸 `Killed` 行結束，沒有說明。552在 v2.1.200 之前，指令碼僅以 shell 的裸 `Killed` 行結束，沒有說明。

553 553

554安裝需要大約 512 MB 的可用記憶體，執行 Claude Code 需要更多。請參閱[系統需求](/zh-TW/setup#system-requirements)。554安裝需要大約 512 MB 的可用記憶體，執行 Claude Code 需要更多。請參閱[系統需求](/docs/zh-TW/setup#system-requirements)。

555 555

556**解決方案：**556**解決方案：**

557 557

607 Windows 上的 Claude Code 需要 Git for Windows（用於 bash）或 PowerShell607 Windows 上的 Claude Code 需要 Git for Windows（用於 bash）或 PowerShell

608</h3>608</h3>

609 609

610Git for Windows 是選用的。Claude Code 在缺少 Git Bash 時使用 [PowerShell 工具](/zh-TW/tools-reference#powershell-tool)，因此此錯誤表示找不到任何一個 shell。610Git for Windows 是選用的。Claude Code 在缺少 Git Bash 時使用 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)，因此此錯誤表示找不到任何一個 shell。

611 611

612**如果 PowerShell 不在您的 PATH 中**，其預設位置是 `C:\Windows\System32\WindowsPowerShell\v1.0\`。將該目錄新增到您的 `PATH`，或安裝 [PowerShell 7](https://aka.ms/powershell)，它提供 `pwsh`。612**如果 PowerShell 不在您的 PATH 中**，其預設位置是 `C:\Windows\System32\WindowsPowerShell\v1.0\`。將該目錄新增到您的 `PATH`，或安裝 [PowerShell 7](https://aka.ms/powershell)，它提供 `pwsh`。

613 613

614**若要改為安裝 Git for Windows**，請從 [git-scm.com/downloads/win](https://git-scm.com/downloads/win) 下載。在設定期間，選擇「Add to PATH」。安裝後重新啟動您的終端。安裝它會啟用 Bash 工具，在使用基於 Bash 的指令碼和工具時很有用。614**若要改為安裝 Git for Windows**，請從 [git-scm.com/downloads/win](https://git-scm.com/downloads/win) 下載。在設定期間，選擇「Add to PATH」。安裝後重新啟動您的終端。安裝它會啟用 Bash 工具，在使用基於 Bash 的指令碼和工具時很有用。

615 615

616**如果 Git 已安裝**但 Claude Code 找不到它，請在您的 [settings.json 檔案](/zh-TW/settings)中設定路徑：616**如果 Git 已安裝**但 Claude Code 找不到它，請在您的 [settings.json 檔案](/docs/zh-TW/settings)中設定路徑：

617 617

618```json theme={null}618```json theme={null}

619{619{

641 641

642如果這列印 `True`，您的作業系統沒問題。關閉視窗，開啟不帶 x86 後綴的 `Windows PowerShell`，然後再次執行安裝命令。642如果這列印 `True`，您的作業系統沒問題。關閉視窗，開啟不帶 x86 後綴的 `Windows PowerShell`，然後再次執行安裝命令。

643 643

644如果這列印 `False`，您在 32 位元版本的 Windows 上。Claude Code 需要 64 位元作業系統。請參閱[系統需求](/zh-TW/setup#system-requirements)。644如果這列印 `False`，您在 32 位元版本的 Windows 上。Claude Code 需要 64 位元作業系統。請參閱[系統需求](/docs/zh-TW/setup#system-requirements)。

645 645

646<h3 id="linux-musl-or-glibc-binary-mismatch">646<h3 id="linux-musl-or-glibc-binary-mismatch">

647 Linux musl 或 glibc 二進位不相符647 Linux musl 或 glibc 二進位不相符

737 WSL 中的 npm 安裝錯誤737 WSL 中的 npm 安裝錯誤

738</h3>738</h3>

739 739

740如果您在 WSL 內使用 `npm install -g` 安裝了 Claude Code，這些問題適用。如果您使用了[原生安裝程式](/zh-TW/setup)，請跳過此部分。740如果您在 WSL 內使用 `npm install -g` 安裝了 Claude Code，這些問題適用。如果您使用了[原生安裝程式](/docs/zh-TW/setup)，請跳過此部分。

741 741

742**OS 或平台偵測問題。** 如果 npm 在安裝期間報告平台不相符，WSL 可能正在使用 Windows `npm`。首先執行 `npm config set os linux`，然後使用 `npm install -g @anthropic-ai/claude-code --force` 安裝。不要使用 `sudo`。742**OS 或平台偵測問題。** 如果 npm 在安裝期間報告平台不相符，WSL 可能正在使用 Windows `npm`。首先執行 `npm config set os linux`，然後使用 `npm install -g @anthropic-ai/claude-code --force` 安裝。不要使用 `sudo`。

743 743

786`@anthropic-ai/claude-code` npm 套件透過每個平台的可選相依性（如 `@anthropic-ai/claude-code-darwin-arm64`）拉入原生二進位檔。如果安裝後執行 `claude` 列印 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`，請檢查以下原因：786`@anthropic-ai/claude-code` npm 套件透過每個平台的可選相依性（如 `@anthropic-ai/claude-code-darwin-arm64`）拉入原生二進位檔。如果安裝後執行 `claude` 列印 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`，請檢查以下原因：

787 787

788* **可選相依性已停用。** 從您的 npm 安裝命令中移除 `--omit=optional`、從 pnpm 移除 `--no-optional` 或從 yarn 移除 `--ignore-optional`，並檢查 `.npmrc` 是否未設定 `optional=false`。然後重新安裝。原生二進位檔僅作為可選相依性提供，因此如果跳過它，沒有 JavaScript 後備。788* **可選相依性已停用。** 從您的 npm 安裝命令中移除 `--omit=optional`、從 pnpm 移除 `--no-optional` 或從 yarn 移除 `--ignore-optional`，並檢查 `.npmrc` 是否未設定 `optional=false`。然後重新安裝。原生二進位檔僅作為可選相依性提供，因此如果跳過它，沒有 JavaScript 後備。

789* **不支援的平台。** 預建二進位檔針對 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 發佈。Claude Code 不為其他平台提供二進位檔；請參閱[系統需求](/zh-TW/setup#system-requirements)。{/* min-version: 2.1.205 */}在 FreeBSD 上，安裝程式報告平台為不支援。在 v2.1.205 之前，它將 FreeBSD 視為 Linux 並下載了無法執行的二進位檔。789* **不支援的平台。** 預建二進位檔針對 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 發佈。Claude Code 不為其他平台提供二進位檔；請參閱[系統需求](/docs/zh-TW/setup#system-requirements)。在 FreeBSD 上，安裝程式報告平台為不支援。在 v2.1.205 之前，它將 FreeBSD 視為 Linux 並下載了無法執行的二進位檔。

790* **公司 npm 鏡像缺少平台套件。** 確保您的登錄鏡像除了元套件外，還鏡像所有八個 `@anthropic-ai/claude-code-*` 平台套件。790* **公司 npm 鏡像缺少平台套件。** 確保您的登錄鏡像除了元套件外，還鏡像所有八個 `@anthropic-ai/claude-code-*` 平台套件。

791 791

792使用 `--ignore-scripts` 安裝不會觸發此錯誤。跳過連結二進位檔到位置的 postinstall 步驟，因此 Claude Code 回退到在每次啟動時定位和生成平台二進位檔的包裝器。這有效但啟動速度較慢；使用啟用的指令碼重新安裝以進行直接執行。792使用 `--ignore-scripts` 安裝不會觸發此錯誤。跳過連結二進位檔到位置的 postinstall 步驟，因此 Claude Code 回退到在每次啟動時定位和生成平台二進位檔的包裝器。這有效但啟動速度較慢；使用啟用的指令碼重新安裝以進行直接執行。

829 829

830* **Claude Pro/Max 使用者**：在 [claude.ai/settings](https://claude.ai/settings) 驗證您的訂閱是否有效830* **Claude Pro/Max 使用者**：在 [claude.ai/settings](https://claude.ai/settings) 驗證您的訂閱是否有效

831* **Anthropic Console 使用者**：確認您的帳戶具有「Claude Code」或「Developer」角色。管理員在 Anthropic Console 的「設定」→「成員」中指派此角色。831* **Anthropic Console 使用者**：確認您的帳戶具有「Claude Code」或「Developer」角色。管理員在 Anthropic Console 的「設定」→「成員」中指派此角色。

832* **在代理後面**：公司代理可能干擾 API 請求。請參閱[網路設定](/zh-TW/network-config)以取得代理設定。832* **在代理後面**：公司代理可能干擾 API 請求。請參閱[網路設定](/docs/zh-TW/network-config)以取得代理設定。

833 833

834<h3 id="this-organization-has-been-disabled-with-an-active-subscription">834<h3 id="this-organization-has-been-disabled-with-an-active-subscription">

835 此組織已停用，但有有效的訂閱835 此組織已停用，但有有效的訂閱

837 837

838如果您看到 `API Error: 400 ... "This organization has been disabled"`，儘管有有效的 Claude 訂閱，`ANTHROPIC_API_KEY` 環境變數正在覆蓋您的訂閱。這通常發生在舊 API 金鑰（來自先前的雇主或專案）仍在您的 shell 設定檔中時。838如果您看到 `API Error: 400 ... "This organization has been disabled"`，儘管有有效的 Claude 訂閱，`ANTHROPIC_API_KEY` 環境變數正在覆蓋您的訂閱。這通常發生在舊 API 金鑰（來自先前的雇主或專案）仍在您的 shell 設定檔中時。

839 839

840當 `ANTHROPIC_API_KEY` 存在且您已核准它時，Claude Code 使用該金鑰而非您訂閱的 OAuth 認證。在使用 `-p` 旗標的非互動模式下，當存在時始終使用該金鑰。請參閱[身份驗證優先順序](/zh-TW/authentication#authentication-precedence)以取得完整的解決順序。840當 `ANTHROPIC_API_KEY` 存在且您已核准它時，Claude Code 使用該金鑰而非您訂閱的 OAuth 認證。在使用 `-p` 旗標的非互動模式下，當存在時始終使用該金鑰。請參閱[身份驗證優先順序](/docs/zh-TW/authentication#authentication-precedence)以取得完整的解決順序。

841 841

842要改用您的訂閱，請取消設定環境變數並從您的 shell 設定檔中移除它：842要改用您的訂閱，請取消設定環境變數並從您的 shell 設定檔中移除它：

843 843

907 907

908如果認證在您的終端中有效但在 VS Code 或 JetBrains 擴充功能中無效，IDE 程序可能未繼承您的 shell 環境。在 IDE 自己的設定中設定提供者環境變數，或從已匯出它們的終端啟動 IDE。908如果認證在您的終端中有效但在 VS Code 或 JetBrains 擴充功能中無效，IDE 程序可能未繼承您的 shell 環境。在 IDE 自己的設定中設定提供者環境變數，或從已匯出它們的終端啟動 IDE。

909 909

910請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 以取得完整的提供者設定。910請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 以取得完整的提供者設定。

911 911

912<h2 id="still-stuck">912<h2 id="still-stuck">

913 仍然卡住913 仍然卡住

ultraplan.md +0 −96 deleted

File Deleted View Diff

~~1> ## Documentation Index~~

~~2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt~~

~~3> Use this file to discover all available pages before exploring further.~~

~~5# 使用 ultraplan 在雲端進行規劃~~

~~7> 從您的 CLI 開始規劃，在網路上的 Claude Code 中草擬，然後遠端執行或回到您的終端機執行~~

~~9<Note>~~

~~10 Ultraplan 處於研究預覽階段。行為和功能可能會根據反饋而改變。~~

~~11</Note>~~

13Ultraplan 將規劃任務從您的本機 CLI 交給在 [plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 中執行的 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 工作階段。Claude 在雲端草擬計畫，同時您可以繼續在終端機中工作。當計畫準備好時，您可以在瀏覽器中開啟它來評論特定部分、要求修訂，並選擇在何處執行它。

~~15當您想要比終端機提供的更豐富的審查介面時，這很有用：~~

~~17* **有針對性的反饋**：對計畫的個別部分進行評論，而不是回覆整個計畫~~

~~18* **無需動手的草擬**：計畫在遠端生成，因此您的終端機可以自由進行其他工作~~

~~19* **靈活的執行**：批准計畫在網路上執行並開啟拉取請求，或將其發送回您的終端機~~

21Ultraplan 需要 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 帳戶和 GitHub 儲存庫。因為它在 Anthropic 的雲端基礎設施上執行，所以在使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時不可用。雲端工作階段在您帳戶的預設 [cloud environment](/zh-TW/claude-code-on-the-web#the-cloud-environment) 中執行。如果您還沒有雲端環境，ultraplan 會在首次啟動時自動建立一個。

~~23<h2 id="launch-ultraplan-from-the-cli">~~

~~24 從 CLI 啟動 ultraplan~~

~~25</h2>~~

~~27從您的本機 CLI 工作階段，您可以透過三種方式啟動 ultraplan：~~

~~29* **命令**：執行 `/ultraplan` 後跟您的提示~~

~~30* **關鍵字**：在正常提示中的任何地方包含 `ultraplan` 一詞~~

~~31* **從本機計畫**：當 Claude 完成本機計畫並顯示批准對話框時，選擇 **No, refine with Ultraplan on Claude Code on the web** 將草稿發送到雲端進行進一步迭代~~

~~33例如，要使用命令規劃服務遷移：~~

~~35```~~

~~36/ultraplan migrate the auth service from sessions to JWTs~~

~~37```~~

39命令和關鍵字路徑在啟動前開啟確認對話框。本機計畫路徑會跳過此對話框，因為該選擇已作為確認。如果 [Remote Control](/zh-TW/remote-control) 處於活動狀態，當 ultraplan 啟動時它會斷開連接，因為兩個功能都佔用 claude.ai/code 介面，一次只能連接一個。

~~41雲端工作階段啟動後，您的 CLI 的提示輸入會顯示狀態指示器，同時雲端工作階段工作：~~

~~43| 狀態 | 含義 |~~

~~44| :----------------------------- | :----------------------- |~~

~~45| `◇ ultraplan` | Claude 正在研究您的程式碼庫並草擬計畫 |~~

~~46| `◇ ultraplan needs your input` | Claude 有澄清問題；開啟工作階段連結以回應 |~~

~~47| `◆ ultraplan ready` | 計畫已準備好在您的瀏覽器中審查 |~~

49執行 `/tasks` 並選擇 ultraplan 項目以開啟詳細檢視，其中包含工作階段連結、代理活動和 **Stop ultraplan** 操作。停止會封存雲端工作階段並清除指示器；沒有任何內容保存到您的終端機。

~~51<h2 id="review-and-revise-the-plan-in-your-browser">~~

~~52 在瀏覽器中審查和修訂計畫~~

~~53</h2>~~

~~55當狀態變更為 `◆ ultraplan ready` 時，開啟工作階段連結以在 claude.ai 上檢視計畫。計畫出現在專用審查檢視中：~~

~~57* **內嵌評論**：反白任何段落並留下評論供 Claude 處理~~

~~58* **表情符號反應**：對某個部分做出反應以表示批准或關注，無需撰寫完整評論~~

~~59* **大綱側邊欄**：在計畫的各個部分之間跳轉~~

~~61當您要求 Claude 處理您的評論時，它會修訂計畫並呈現更新的草稿。您可以根據需要迭代多次，然後再選擇在何處執行。~~

~~63<h2 id="choose-where-to-execute">~~

~~64 選擇執行位置~~

~~65</h2>~~

~~67當計畫看起來正確時，您可以從瀏覽器選擇 Claude 是在同一雲端工作階段中實施它，還是將其發送回您等待的終端機。~~

~~69<h3 id="execute-on-the-web">~~

~~70 在網路上執行~~

~~71</h3>~~

73在瀏覽器中選擇 **Approve Claude's plan and start coding** 以讓 Claude 在同一 Claude Code on the web 工作階段中實施它。您的終端機會顯示確認，狀態指示器會清除，工作會在雲端繼續。實施完成後，[檢視差異](/zh-TW/claude-code-on-the-web#review-changes)並從網路介面建立拉取請求。

~~75<h3 id="send-the-plan-back-to-your-terminal">~~

~~76 將計畫發送回您的終端機~~

~~77</h3>~~

79在瀏覽器中選擇 **Approve plan and teleport back to terminal** 以使用對您環境的完全存取權限在本機實施計畫。當工作階段是從您的 CLI 啟動且終端機仍在輪詢時，此選項會出現。網路工作階段被封存，因此它不會並行繼續工作。

~~81您的終端機會在標題為 **Ultraplan approved** 的對話框中顯示計畫，有三個選項：~~

~~83* **Implement here**：將計畫注入您目前的對話並從您停止的地方繼續~~

~~84* **Start new session**：清除目前的對話並僅以計畫作為上下文開始新的對話~~

~~85* **Cancel**：將計畫保存到檔案而不執行它；Claude 會列印檔案路徑，以便您稍後可以返回它~~

~~87如果您開始新工作階段，Claude 會在頂部列印 `claude --resume` 命令，以便您稍後可以返回到您之前的對話。~~

~~89<h2 id="related-resources">~~

~~90 相關資源~~

~~91</h2>~~

~~93* [Claude Code on the web](/zh-TW/claude-code-on-the-web)：ultraplan 執行的雲端基礎設施~~

~~94* [Plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)：規劃在本機工作階段中的工作方式~~

~~95* [Find bugs with ultrareview](/zh-TW/ultrareview)：ultraplan 的程式碼審查對應項，用於在合併前捕捉問題~~

~~96* [Remote Control](/zh-TW/remote-control)：使用 claude.ai/code 介面與在您自己的機器上執行的工作階段~~

voice-dictation.md +16 −16

Details

12 點擊模式需要 Claude Code v2.1.116 或更高版本。使用 `claude --version` 檢查您的版本。12 點擊模式需要 Claude Code v2.1.116 或更高版本。使用 `claude --version` 檢查您的版本。

13</Note>13</Note>

14 14

~~15聽寫也適用於[代理檢視](/zh-TW/agent-view#peek-and-reply)。在調度輸入或窺視面板回覆聚焦時，按住或點擊您的推送通話鍵以聽寫到背景工作階段。~~15聽寫也適用於[代理檢視](/docs/zh-TW/agent-view#peek-and-reply)。在調度輸入或窺視面板回覆聚焦時，按住或點擊您的推送通話鍵以聽寫到背景工作階段。

16 16

17<h2 id="requirements">17<h2 id="requirements">

18 要求18 要求

22 22

23* **Claude.ai 帳戶**：語音轉文字服務僅在您使用 Claude.ai 帳戶進行身份驗證時可用，當 Claude Code 配置為直接使用 Anthropic API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時不可用。23* **Claude.ai 帳戶**：語音轉文字服務僅在您使用 Claude.ai 帳戶進行身份驗證時可用，當 Claude Code 配置為直接使用 Anthropic API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時不可用。

24* **未啟用 HIPAA 合規性的組織**：當此限制適用時，`/voice` 會顯示 `Voice mode is disabled by your organization's policy`。24* **未啟用 HIPAA 合規性的組織**：當此限制適用時，`/voice` 會顯示 `Voice mode is disabled by your organization's policy`。

~~25* **本地麥克風**：語音聽寫在遠端環境中不起作用，例如[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web)或 SSH 工作階段。~~25* **本地麥克風**：語音聽寫在遠端環境中不起作用，例如[網頁上的 Claude Code](/docs/zh-TW/claude-code-on-the-web)或 SSH 工作階段。

26* **如果您在 WSL 中執行 Claude Code，則需要 WSLg**：WSLg 在從 Microsoft Store 在 Windows 10 或 11 上安裝 WSL2 時包含。如果 WSLg 不可用，例如在 WSL1 上，改為在原生 Windows 中執行 Claude Code。26* **如果您在 WSL 中執行 Claude Code，則需要 WSLg**：WSLg 在從 Microsoft Store 在 Windows 10 或 11 上安裝 WSL2 時包含。如果 WSLg 不可用，例如在 WSL1 上，改為在原生 Windows 中執行 Claude Code。

27 27

~~28轉錄不會消耗 Claude 訊息或代幣，也不會計入 `/usage` 中顯示的限制。請參閱[資料使用](/zh-TW/data-usage)了解 Anthropic 如何處理您的資料。~~28轉錄不會消耗 Claude 訊息或代幣，也不會計入 `/usage` 中顯示的限制。請參閱[資料使用](/docs/zh-TW/data-usage)了解 Anthropic 如何處理您的資料。

29 29

30音頻錄製在 macOS、Linux 和 Windows 上使用內建的原生模組。在 Linux 上，如果原生模組無法載入，Claude Code 會回退到 ALSA utils 中的 `arecord` 或 SoX 中的 `rec`。如果兩者都不可用，`/voice` 會列印您的套件管理員的安裝命令。30音頻錄製在 macOS、Linux 和 Windows 上使用內建的原生模組。在 Linux 上，如果原生模組無法載入，Claude Code 會回退到 ALSA utils 中的 `arecord` 或 SoX 中的 `rec`。如果兩者都不可用，`/voice` 會列印您的套件管理員的安裝命令。

31 31

32Claude Code [VS Code 擴充功能](/zh-TW/vs-code)也支援語音聽寫，具有相同的 Claude.ai 帳戶要求。它在 VS Code Remote 工作階段中不可用，包括 SSH、Dev Containers 和 Codespaces，因為麥克風在您的本地機器上，而擴充功能在遠端主機上執行。32Claude Code [VS Code 擴充功能](/docs/zh-TW/vs-code)也支援語音聽寫，具有相同的 Claude.ai 帳戶要求。它在 VS Code Remote 工作階段中不可用，包括 SSH、Dev Containers 和 Codespaces，因為麥克風在您的本地機器上，而擴充功能在遠端主機上執行。

33 33

34<h2 id="enable-voice-dictation">34<h2 id="enable-voice-dictation">

35 啟用語音聽寫35 啟用語音聽寫

51| `/voice tap` | 在[點擊模式](#tap-to-record-and-send)中啟用 |51| `/voice tap` | 在[點擊模式](#tap-to-record-and-send)中啟用 |

52| `/voice off` | 停用 |52| `/voice off` | 停用 |

53 53

~~54語音聽寫在工作階段之間保持。直接在您的[使用者設定檔案](/zh-TW/settings)中設定它，而不是執行 `/voice`：~~54語音聽寫在工作階段之間保持。直接在您的[使用者設定檔案](/docs/zh-TW/settings)中設定它，而不是執行 `/voice`：

55 55

56```json theme={null}56```json theme={null}

57{57{

62}62}

63```63```

64 64

65啟用語音聽寫時，當提示為空時，輸入頁尾會顯示 `hold space to speak` 提示。提示文字反映您目前的 `voice:pushToTalk` 快捷鍵繫結，如果您[重新繫結聽寫鍵](#rebind-the-dictation-key)，則會更新。提示文字在兩種模式中都相同，如果您配置了[自訂狀態行](/zh-TW/statusline)，則不會出現。65啟用語音聽寫時，當提示為空時，輸入頁尾會顯示 `hold space to speak` 提示。提示文字反映您目前的 `voice:pushToTalk` 快捷鍵繫結，如果您[重新繫結聽寫鍵](#rebind-the-dictation-key)，則會更新。提示文字在兩種模式中都相同，如果您配置了[自訂狀態行](/docs/zh-TW/statusline)，則不會出現。

66 66

67轉錄在兩種模式中都針對編碼詞彙進行了調整。常見的開發術語如 `regex`、`OAuth`、`JSON` 和 `localhost` 都能正確識別，您目前的專案名稱和 git 分支名稱會自動新增為識別提示。67轉錄在兩種模式中都針對編碼詞彙進行了調整。常見的開發術語如 `regex`、`OAuth`、`JSON` 和 `localhost` 都能正確識別，您目前的專案名稱和 git 分支名稱會自動新增為識別提示。

68 68

108 變更聽寫語言108 變更聽寫語言

109</h2>109</h2>

110 110

111語音聽寫使用與控制 Claude 回應語言相同的[`language` 設定](/zh-TW/settings)。如果該設定為空，聽寫預設為英文。在 VS Code 擴充功能中，如果 `language` 為空，聽寫會在預設為英文之前使用 VS Code 的 `accessibility.voice.speechLanguage` 設定。111語音聽寫使用與控制 Claude 回應語言相同的[`language` 設定](/docs/zh-TW/settings)。如果該設定為空，聽寫預設為英文。在 VS Code 擴充功能中，如果 `language` 為空，聽寫會在預設為英文之前使用 VS Code 的 `accessibility.voice.speechLanguage` 設定。

112 112

113<Accordion title="支援的聽寫語言">113<Accordion title="支援的聽寫語言">

114 | 語言 | 代碼 |114 | 語言 | 代碼 |

149 重新繫結聽寫鍵149 重新繫結聽寫鍵

150</h2>150</h2>

151 151

152聽寫鍵在 `Chat` 上下文中繫結到 `voice:pushToTalk`，預設為 `Space`。相同的繫結控制按住和點擊模式。在 [`~/.claude/keybindings.json`](/zh-TW/keybindings) 中重新繫結它：152聽寫鍵在 `Chat` 上下文中繫結到 `voice:pushToTalk`，預設為 `Space`。相同的繫結控制按住和點擊模式。在 [`~/.claude/keybindings.json`](/docs/zh-TW/keybindings) 中重新繫結它：

153 153

154```json theme={null}154```json theme={null}

155{155{

169 169

170在按住模式中，避免繫結裸字母鍵，例如 `v`，因為按住偵測依賴於按鍵重複，字母在預熱期間輸入到提示中。使用 `Space`，或使用修飾符組合，例如 `meta+k` 以在第一次按鍵時開始錄製，無需預熱。點擊模式沒有預熱，因此大多數鍵都可以。170在按住模式中，避免繫結裸字母鍵，例如 `v`，因為按住偵測依賴於按鍵重複，字母在預熱期間輸入到提示中。使用 `Space`，或使用修飾符組合，例如 `meta+k` 以在第一次按鍵時開始錄製，無需預熱。點擊模式沒有預熱，因此大多數鍵都可以。

171 171

172某些鍵不會傳遞到終端應用程式，根本無法繫結。例如，如果您嘗試繫結 `Caps Lock`，它會顯示錯誤。請參閱[自訂鍵盤快捷鍵](/zh-TW/keybindings)了解完整的快捷鍵語法和保留快捷鍵的清單。172某些鍵不會傳遞到終端應用程式，根本無法繫結。例如，如果您嘗試繫結 `Caps Lock`，它會顯示錯誤。請參閱[自訂鍵盤快捷鍵](/docs/zh-TW/keybindings)了解完整的快捷鍵語法和保留快捷鍵的清單。

173 173

174<h2 id="troubleshooting">174<h2 id="troubleshooting">

175 疑難排解175 疑難排解

181* **`Voice mode is disabled by your organization's policy`**：您的組織的合規性配置停用了語音聽寫，如[需求](#requirements)中所述。請聯絡您的組織管理員以確認您的組織是否可使用語音聽寫。181* **`Voice mode is disabled by your organization's policy`**：您的組織的合規性配置停用了語音聽寫，如[需求](#requirements)中所述。請聯絡您的組織管理員以確認您的組織是否可使用語音聽寫。

182* **`Microphone access is denied`**：在系統設定中授予您的終端機麥克風權限。在 macOS 上，前往系統設定 → 隱私與安全 → 麥克風並啟用您的終端機應用程式，然後再次執行 `/voice`。在 Windows 上，前往設定 → 隱私與安全 → 麥克風並開啟桌面應用程式的麥克風存取，然後再次執行 `/voice`。如果您的終端機未列在 macOS 設定中，請參閱[終端機未列在 macOS 麥克風設定中](#terminal-not-listed-in-macos-microphone-settings)。182* **`Microphone access is denied`**：在系統設定中授予您的終端機麥克風權限。在 macOS 上，前往系統設定 → 隱私與安全 → 麥克風並啟用您的終端機應用程式，然後再次執行 `/voice`。在 Windows 上，前往設定 → 隱私與安全 → 麥克風並開啟桌面應用程式的麥克風存取，然後再次執行 `/voice`。如果您的終端機未列在 macOS 設定中，請參閱[終端機未列在 macOS 麥克風設定中](#terminal-not-listed-in-macos-microphone-settings)。

183* **Linux 上的 `No audio recording tool found`**：原生音頻模組無法載入，且未安裝回退。使用錯誤訊息中顯示的命令安裝 SoX，例如 `sudo apt-get install sox`。183* **Linux 上的 `No audio recording tool found`**：原生音頻模組無法載入，且未安裝回退。使用錯誤訊息中顯示的命令安裝 SoX，例如 `sudo apt-get install sox`。

184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安裝，但主機沒有音頻擷取裝置，例如無頭伺服器或容器。在具有麥克風的機器上執行 Claude Code。{/* min-version: 2.1.195 */}自 v2.1.195 起，Linux 上的 Claude Code 在該情況下報告此訊息；較早的版本即使已安裝 SoX 也會要求您安裝它。184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安裝，但主機沒有音頻擷取裝置，例如無頭伺服器或容器。在具有麥克風的機器上執行 Claude Code。自 v2.1.195 起，Linux 上的 Claude Code 在該情況下報告此訊息；較早的版本即使已安裝 SoX 也會要求您安裝它。

185* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 透過 PulseAudio 而非 ALSA 裝置路由音頻，因此 SoX 需要明確安裝其 PulseAudio 後端。執行 `sudo apt install sox libsox-fmt-pulse`。單獨安裝 `sox` 會拉入 ALSA 後端，這在 WSL 上無法錄製，因為沒有 `/dev/snd` 裝置。185* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 透過 PulseAudio 而非 ALSA 裝置路由音頻，因此 SoX 需要明確安裝其 PulseAudio 後端。執行 `sudo apt install sox libsox-fmt-pulse`。單獨安裝 `sox` 會拉入 ALSA 後端，這在 WSL 上無法錄製，因為沒有 `/dev/snd` 裝置。

186* **`Voice input is failing repeatedly and has been paused`**：語音聽寫連續遇到多個啟動失敗，並停止嘗試新的工作階段，直到一個成功。失敗計數無論麥克風無法啟動或錄音機啟動後停止而未產生任何音頻。這通常表示此主機上的麥克風或音頻堆疊無法捕獲音頻，例如無頭伺服器、沒有音頻傳遞的遠端 shell 或被拒絕的麥克風權限。確認工作輸入裝置，修復上述項目中的根本原因，然後再次觸發語音。{/* min-version: 2.1.202 */}在 v2.1.202 之前，只有啟動失敗計入暫停。186* **`Voice input is failing repeatedly and has been paused`**：語音聽寫連續遇到多個啟動失敗，並停止嘗試新的工作階段，直到一個成功。失敗計數無論麥克風無法啟動或錄音機啟動後停止而未產生任何音頻。這通常表示此主機上的麥克風或音頻堆疊無法捕獲音頻，例如無頭伺服器、沒有音頻傳遞的遠端 shell 或被拒絕的麥克風權限。確認工作輸入裝置，修復上述項目中的根本原因，然後再次觸發語音。在 v2.1.202 之前，只有啟動失敗計入暫停。

187* **在按住模式中按住 `Space` 時沒有任何反應**：在按住時監視提示輸入。如果空格不斷累積，語音聽寫可能已關閉；執行 `/voice hold` 啟用它。如果只出現一個或兩個空格然後沒有任何反應，語音聽寫已開啟但按住偵測未觸發。按住偵測需要您的終端機發送按鍵重複事件，因此如果在作業系統層級停用了按鍵重複，它無法偵測按住的鍵。使用 `/voice tap` 切換到點擊模式以避免按鍵重複要求。187* **在按住模式中按住 `Space` 時沒有任何反應**：在按住時監視提示輸入。如果空格不斷累積，語音聽寫可能已關閉；執行 `/voice hold` 啟用它。如果只出現一個或兩個空格然後沒有任何反應，語音聽寫已開啟但按住偵測未觸發。按住偵測需要您的終端機發送按鍵重複事件，因此如果在作業系統層級停用了按鍵重複，它無法偵測按住的鍵。使用 `/voice tap` 切換到點擊模式以避免按鍵重複要求。

188* **在點擊模式中點擊 `Space` 輸入空格而不是錄製**：第一次點擊只在提示輸入為空時開始錄製。先清除輸入，或通過執行 `/voice tap` 檢查您是否處於點擊模式。188* **在點擊模式中點擊 `Space` 輸入空格而不是錄製**：第一次點擊只在提示輸入為空時開始錄製。先清除輸入，或通過執行 `/voice tap` 檢查您是否處於點擊模式。

189* **`No audio detected from microphone`**：錄製已開始但捕獲了無聲。確認正確的輸入裝置設定為系統預設值，其輸入級別未靜音或接近零。在 Windows 上，開啟設定 → 系統 → 聲音 → 輸入並選擇您的麥克風。在 macOS 上，開啟系統設定 → 聲音 → 輸入。189* **`No audio detected from microphone`**：錄製已開始但捕獲了無聲。確認正確的輸入裝置設定為系統預設值，其輸入級別未靜音或接近零。在 Windows 上，開啟設定 → 系統 → 聲音 → 輸入並選擇您的麥克風。在 macOS 上，開啟系統設定 → 聲音 → 輸入。

190* **`Voice connection failed`**：您的錄製因為連線失敗而從未到達轉錄服務。檢查您的網路並重試。{/* min-version: 2.1.200 */}捕獲無音頻的錄製會報告 `No audio detected from microphone` 而不是此訊息。在 v2.1.200 之前，無聲麥克風可能會報告連線失敗，這暗示網路問題，而實際問題是輸入裝置。190* **`Voice connection failed`**：您的錄製因為連線失敗而從未到達轉錄服務。檢查您的網路並重試。捕獲無音頻的錄製會報告 `No audio detected from microphone` 而不是此訊息。在 v2.1.200 之前，無聲麥克風可能會報告連線失敗，這暗示網路問題，而實際問題是輸入裝置。

191* **`No speech detected`**：音頻到達轉錄服務但未識別任何單詞。靠近麥克風說話，減少背景噪音，並確認您的[聽寫語言](#change-the-dictation-language)與您說話的語言相符。191* **`No speech detected`**：音頻到達轉錄服務但未識別任何單詞。靠近麥克風說話，減少背景噪音，並確認您的[聽寫語言](#change-the-dictation-language)與您說話的語言相符。

192* **轉錄是亂碼或使用了錯誤的語言**：聽寫預設為英文。如果您用另一種語言聽寫，請先在 `/config` 中設定它。請參閱[變更聽寫語言](#change-the-dictation-language)。192* **轉錄是亂碼或使用了錯誤的語言**：聽寫預設為英文。如果您用另一種語言聽寫，請先在 `/config` 中設定它。請參閱[變更聽寫語言](#change-the-dictation-language)。

193 193

219 另請參閱219 另請參閱

220</h2>220</h2>

221 221

222* [自訂鍵盤快捷鍵](/zh-TW/keybindings)：重新繫結 `voice:pushToTalk` 和其他 CLI 鍵盤動作222* [自訂鍵盤快捷鍵](/docs/zh-TW/keybindings)：重新繫結 `voice:pushToTalk` 和其他 CLI 鍵盤動作

223* [設定設定](/zh-TW/settings)：`voice`、`language` 和其他設定鍵的完整參考223* [設定設定](/docs/zh-TW/settings)：`voice`、`language` 和其他設定鍵的完整參考

224* [互動模式](/zh-TW/interactive-mode)：鍵盤快捷鍵、輸入模式和工作階段控制224* [互動模式](/docs/zh-TW/interactive-mode)：鍵盤快捷鍵、輸入模式和工作階段控制

225* [命令](/zh-TW/commands)：`/voice`、`/config` 和所有其他命令的參考225* [命令](/docs/zh-TW/commands)：`/voice`、`/config` 和所有其他命令的參考

vs-code.md +35 −35

Details

19安裝前，請確保您擁有：19安裝前，請確保您擁有：

20 20

21* VS Code 1.98.0 或更高版本21* VS Code 1.98.0 或更高版本

22* Anthropic 帳戶：任何付費 Claude 訂閱（Pro、Max、Team 或 Enterprise）或 Claude Console 帳戶都可以使用，不需要 API 金鑰。首次開啟擴充功能時，您將[使用此帳戶登入](/zh-TW/authentication#log-in-to-claude-code)。如果您透過第三方提供者（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）存取 Claude，請參閱[使用第三方提供者](#use-third-party-providers)以取得設定說明。22* Anthropic 帳戶：任何付費 Claude 訂閱（Pro、Max、Team 或 Enterprise）或 Claude Console 帳戶都可以使用，不需要 API 金鑰。首次開啟擴充功能時，您將[使用此帳戶登入](/docs/zh-TW/authentication#log-in-to-claude-code)。如果您透過第三方提供者（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）存取 Claude，請參閱[使用第三方提供者](#use-third-party-providers)以取得設定說明。

23 23

24<Tip>24<Tip>

25 此擴充功能包含其自有的 CLI（命令列介面）副本供聊天面板使用。若要在 VS Code 的整合終端機中執行 `claude`，您還需要[獨立 CLI 安裝](/zh-TW/setup)。詳細資訊請參閱 [VS Code 擴充功能與 Claude Code CLI](#vs-code-extension-vs-claude-code-cli)。25 此擴充功能包含其自有的 CLI（命令列介面）副本供聊天面板使用。若要在 VS Code 的整合終端機中執行 `claude`，您還需要[獨立 CLI 安裝](/docs/zh-TW/setup)。詳細資訊請參閱 [VS Code 擴充功能與 Claude Code CLI](#vs-code-extension-vs-claude-code-cli)。

26</Tip>26</Tip>

27 27

28<h2 id="install-the-extension">28<h2 id="install-the-extension">

36 36

37或在 VS Code 中，按 `Cmd+Shift+X`（Mac）或 `Ctrl+Shift+X`（Windows/Linux）開啟擴充功能檢視，搜尋「Claude Code」，然後點擊**安裝**。37或在 VS Code 中，按 `Cmd+Shift+X`（Mac）或 `Ctrl+Shift+X`（Windows/Linux）開啟擴充功能檢視，搜尋「Claude Code」，然後點擊**安裝**。

38 38

39擴充功能也會安裝在其他 VS Code 分支中，例如 Devin Desktop 或 Kiro。在編輯器的擴充功能檢視中搜尋「Claude Code」，或從 [Open VSX registry](https://open-vsx.org/extension/Anthropic/claude-code) 安裝。如果您的編輯器無法安裝擴充功能，請[安裝 CLI](/zh-TW/quickstart) 並在其整合終端中執行 `claude`。CLI 可在任何終端中運作。39擴充功能也會安裝在其他 VS Code 分支中，例如 Devin Desktop 或 Kiro。在編輯器的擴充功能檢視中搜尋「Claude Code」，或從 [Open VSX registry](https://open-vsx.org/extension/Anthropic/claude-code) 安裝。如果您的編輯器無法安裝擴充功能，請[安裝 CLI](/docs/zh-TW/quickstart) 並在其整合終端中執行 `claude`。CLI 可在任何終端中運作。

40 40

41<Note>如果安裝後擴充功能未出現，請重新啟動 VS Code 或從命令面板執行「Developer: Reload Window」。</Note>41<Note>如果安裝後擴充功能未出現，請重新啟動 VS Code 或從命令面板執行「Developer: Reload Window」。</Note>

42 42

90 </Step>90 </Step>

91</Steps>91</Steps>

92 92

~~93有關您可以使用 Claude Code 做什麼的更多想法，請參閱[常見工作流程](/zh-TW/common-workflows)。~~93有關您可以使用 Claude Code 做什麼的更多想法，請參閱[常見工作流程](/docs/zh-TW/common-workflows)。

94 94

95<Tip>95<Tip>

96 從命令面板執行'Claude Code: Open Walkthrough'以獲得基礎知識的引導式導覽。96 從命令面板執行'Claude Code: Open Walkthrough'以獲得基礎知識的引導式導覽。

102 102

103提示框支援多項功能：103提示框支援多項功能：

104 104

105* **許可模式**：點擊提示框底部的模式指示器以切換模式，或在 VS Code 設定中的 `claudeCode.initialPermissionMode` 下設定預設值。請參閱[許可模式](/zh-TW/permission-modes#switch-permission-modes)以了解指示器提供的每種模式。105* **許可模式**：點擊提示框底部的模式指示器以切換模式，或在 VS Code 設定中的 `claudeCode.initialPermissionMode` 下設定預設值。請參閱[許可模式](/docs/zh-TW/permission-modes#switch-permission-modes)以了解指示器提供的每種模式。

106 * **Manual**：Claude 在檔案編輯和大多數 shell 命令前要求許可。106 * **Manual**：Claude 在檔案編輯和大多數 shell 命令前要求許可。

107 * **Plan**：Claude 描述它將做什麼，並在進行變更前等待批准。VS Code 會自動將計畫作為完整 Markdown 文件開啟，您可以在其中添加內聯評論以在 Claude 開始前提供反饋。107 * **Plan**：Claude 描述它將做什麼，並在進行變更前等待批准。VS Code 會自動將計畫作為完整 Markdown 文件開啟，您可以在其中添加內聯評論以在 Claude 開始前提供反饋。

108 * **Edit automatically**：Claude 進行編輯而不詢問。108 * **Edit automatically**：Claude 進行編輯而不詢問。

109* **命令菜單**：點擊 `/` 或輸入 `/` 以開啟命令菜單。選項包括附加檔案、切換模型、切換擴展思考、查看計畫使用情況（`/usage`）以及啟動 [Remote Control](/zh-TW/remote-control) 工作階段（`/remote-control`）。自訂部分提供對 MCP servers、hooks、memory、permissions 和 plugins 的存取。帶有終端機圖示的項目在整合終端機中開啟。109* **命令菜單**：點擊 `/` 或輸入 `/` 以開啟命令菜單。選項包括附加檔案、切換模型、切換擴展思考、查看計畫使用情況（`/usage`）以及啟動 [Remote Control](/docs/zh-TW/remote-control) 工作階段（`/remote-control`）。自訂部分提供對 MCP servers、hooks、memory、permissions 和 plugins 的存取。帶有終端機圖示的項目在整合終端機中開啟。

110 * {/* min-version: 2.1.203 */}設定部分包括**為所有工作階段啟用 Remote Control**，它設定 [`remoteControlAtStartup`](/zh-TW/settings#available-settings)，以便[每個新的互動工作階段都自動連接到 Remote Control](/zh-TW/remote-control#enable-remote-control-for-all-sessions)。需要 Claude Code v2.1.203 或更新版本。110 * 設定部分包括**為所有工作階段啟用 Remote Control**，它設定 [`remoteControlAtStartup`](/docs/zh-TW/settings#available-settings)，以便[每個新的互動工作階段都自動連接到 Remote Control](/docs/zh-TW/remote-control#enable-remote-control-for-all-sessions)。需要 Claude Code v2.1.203 或更新版本。

111* **上下文指示器**：提示框顯示您使用了多少 Claude 的 context window。Claude 在需要時會自動壓縮，或您可以手動執行 `/compact`。111* **上下文指示器**：提示框顯示您使用了多少 Claude 的 context window。Claude 在需要時會自動壓縮，或您可以手動執行 `/compact`。

112* **擴展思考**：讓 Claude 花更多時間推理複雜問題。透過命令菜單（`/`）切換它。Claude 的推理在對話中顯示為摺疊的區塊：點擊一個區塊以讀取它，或按 `Ctrl+O` 以展開或摺疊工作階段中的每個思考區塊。有關詳細資訊，請參閱 [Extended thinking](/zh-TW/model-config#extended-thinking)。112* **擴展思考**：讓 Claude 花更多時間推理複雜問題。透過命令菜單（`/`）切換它。Claude 的推理在對話中顯示為摺疊的區塊：點擊一個區塊以讀取它，或按 `Ctrl+O` 以展開或摺疊工作階段中的每個思考區塊。有關詳細資訊，請參閱 [Extended thinking](/docs/zh-TW/model-config#extended-thinking)。

113* **多行輸入**：按 `Shift+Enter` 以添加新行而不傳送。這也適用於問題對話框的「其他」自由文字輸入。113* **多行輸入**：按 `Shift+Enter` 以添加新行而不傳送。這也適用於問題對話框的「其他」自由文字輸入。

114 114

115<h3 id="reference-files-and-folders">115<h3 id="reference-files-and-folders">

133 恢復過去的對話133 恢復過去的對話

134</h3>134</h3>

135 135

136點擊 Claude Code 面板頂部的**工作階段歷史記錄**按鈕以存取您的對話歷史記錄。您可以按關鍵字搜尋或按時間瀏覽（今天、昨天、過去 7 天等）。點擊任何對話以使用完整訊息歷史記錄恢復它。新工作階段會根據您的第一條訊息接收 AI 生成的標題。將滑鼠懸停在工作階段上以顯示重新命名和移除操作：重新命名以給它一個描述性標題，或移除以將其從清單中刪除。有關恢復工作階段的更多資訊，請參閱 [Manage sessions](/zh-TW/sessions)。136點擊 Claude Code 面板頂部的**工作階段歷史記錄**按鈕以存取您的對話歷史記錄。您可以按關鍵字搜尋或按時間瀏覽（今天、昨天、過去 7 天等）。點擊任何對話以使用完整訊息歷史記錄恢復它。新工作階段會根據您的第一條訊息接收 AI 生成的標題。將滑鼠懸停在工作階段上以顯示重新命名和移除操作：重新命名以給它一個描述性標題，或移除以將其從清單中刪除。有關恢復工作階段的更多資訊，請參閱 [Manage sessions](/docs/zh-TW/sessions)。

137 137

138<h3 id="resume-cloud-sessions-from-claude-ai">138<h3 id="resume-cloud-sessions-from-claude-ai">

139 從 Claude.ai 恢復遠端工作階段139 從 Claude.ai 恢復遠端工作階段

140</h3>140</h3>

141 141

142如果您使用[網路上的 Claude Code](/zh-TW/claude-code-on-the-web)，您可以直接在 VS Code 中恢復這些遠端工作階段。這需要使用 **Claude.ai Subscription** 登入，而不是 Anthropic Console。142如果您使用[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web)，您可以直接在 VS Code 中恢復這些遠端工作階段。這需要使用 **Claude.ai Subscription** 登入，而不是 Anthropic Console。

143 143

144<Steps>144<Steps>

145 <Step title="開啟工作階段歷史記錄">145 <Step title="開啟工作階段歷史記錄">

167 167

168該對話框也會分解對您的方案限制有貢獻的內容。它會標記佔最近使用情況 10% 或以上的行為，例如快取未命中、長上下文和子代理程式密集或高度平行的工作階段，每個都有減少它的提示。歸因表顯示每個技能、子代理程式、外掛程式和 MCP server 貢獻了多少使用情況。需要 Claude Code v2.1.174 或更新版本。168該對話框也會分解對您的方案限制有貢獻的內容。它會標記佔最近使用情況 10% 或以上的行為，例如快取未命中、長上下文和子代理程式密集或高度平行的工作階段，每個都有減少它的提示。歸因表顯示每個技能、子代理程式、外掛程式和 MCP server 貢獻了多少使用情況。需要 Claude Code v2.1.174 或更新版本。

169 169

170使用「日」和「週」切換以在過去 24 小時和過去 7 天之間切換。這些數字是近似值，並從此機器上的本機工作階段計算，因此不包括來自其他裝置或 claude.ai 的使用情況。有關追蹤和減少使用情況的更多資訊，請參閱 [Track your costs](/zh-TW/costs#track-your-costs)。170使用「日」和「週」切換以在過去 24 小時和過去 7 天之間切換。這些數字是近似值，並從此機器上的本機工作階段計算，因此不包括來自其他裝置或 claude.ai 的使用情況。有關追蹤和減少使用情況的更多資訊，請參閱 [Track your costs](/docs/zh-TW/costs#track-your-costs)。

171 171

172<h2 id="customize-your-workflow">172<h2 id="customize-your-workflow">

173 自訂您的工作流程173 自訂您的工作流程

209 管理 plugins209 管理 plugins

210</h2>210</h2>

211 211

212VS Code 擴充功能包含用於安裝和管理 [plugins](/zh-TW/plugins) 的圖形介面。在提示框中輸入 `/plugins` 以開啟**管理 plugins** 介面。212VS Code 擴充功能包含用於安裝和管理 [plugins](/docs/zh-TW/plugins) 的圖形介面。在提示框中輸入 `/plugins` 以開啟**管理 plugins** 介面。

213 213

214<h3 id="install-plugins">214<h3 id="install-plugins">

215 安裝 plugins215 安裝 plugins

246 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中配置的 plugins 和市場也可在 CLI 中使用，反之亦然。246 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中配置的 plugins 和市場也可在 CLI 中使用，反之亦然。

247</Note>247</Note>

248 248

249有關 plugin 系統的更多資訊，請參閱 [Plugins](/zh-TW/plugins) 和 [Plugin marketplaces](/zh-TW/plugin-marketplaces)。249有關 plugin 系統的更多資訊，請參閱 [Plugins](/docs/zh-TW/plugins) 和 [Plugin marketplaces](/docs/zh-TW/plugin-marketplaces)。

250 250

251<h2 id="automate-browser-tasks-with-chrome">251<h2 id="automate-browser-tasks-with-chrome">

252 使用 Chrome 自動化瀏覽器任務252 使用 Chrome 自動化瀏覽器任務

264 264

265Claude 為瀏覽器任務開啟新標籤並共享您的瀏覽器登入狀態，因此它可以存取您已登入的任何網站。265Claude 為瀏覽器任務開啟新標籤並共享您的瀏覽器登入狀態，因此它可以存取您已登入的任何網站。

266 266

267有關設定說明、完整功能清單和故障排除，請參閱[使用 Claude Code 與 Chrome](/zh-TW/chrome)。267有關設定說明、完整功能清單和故障排除，請參閱[使用 Claude Code 與 Chrome](/docs/zh-TW/chrome)。

268 268

269<h2 id="vs-code-commands-and-shortcuts">269<h2 id="vs-code-commands-and-shortcuts">

270 VS Code 命令和快捷鍵270 VS Code 命令和快捷鍵

332| 參數 | 描述 |332| 參數 | 描述 |

333| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |333| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

335| `session` | 要恢復的工作階段 ID，而不是開始新對話。工作階段必須屬於目前在 VS Code 中開啟的工作區。如果找不到工作階段，會改為開始新的對話。如果工作階段已在標籤中開啟，該標籤會獲得焦點。若要以程式設計方式擷取工作階段 ID，請參閱[繼續對話](/zh-TW/headless#continue-conversations)。 |335| `session` | 要恢復的工作階段 ID，而不是開始新對話。工作階段必須屬於目前在 VS Code 中開啟的工作區。如果找不到工作階段，會改為開始新的對話。如果工作階段已在標籤中開啟，該標籤會獲得焦點。若要以程式設計方式擷取工作階段 ID，請參閱[繼續對話](/docs/zh-TW/headless#continue-conversations)。 |

336 336

337例如，若要開啟預先填入「review my changes」的標籤：337例如，若要開啟預先填入「review my changes」的標籤：

338 338

340vscode://anthropic.claude-code/open?prompt=review%20my%20changes340vscode://anthropic.claude-code/open?prompt=review%20my%20changes

341```341```

342 342

343若要啟動終端機工作階段而不是 VS Code 標籤，請使用 CLI 的 `claude-cli://` 處理程式。請參閱[從連結啟動工作階段](/zh-TW/deep-links)。343若要啟動終端機工作階段而不是 VS Code 標籤，請使用 CLI 的 `claude-cli://` 處理程式。請參閱[從連結啟動工作階段](/docs/zh-TW/deep-links)。

344 344

345<h2 id="configure-settings">345<h2 id="configure-settings">

346 配置設定346 配置設定

349擴充功能有兩種類型的設定：349擴充功能有兩種類型的設定：

350 350

351* **VS Code 中的擴充功能設定**：控制擴充功能在 VS Code 中的行為。使用 `Cmd+,`（Mac）或 `Ctrl+,`（Windows/Linux）開啟，然後前往「擴充功能」→「Claude Code」。您也可以輸入 `/` 並選擇**一般配置**以開啟設定。351* **VS Code 中的擴充功能設定**：控制擴充功能在 VS Code 中的行為。使用 `Cmd+,`（Mac）或 `Ctrl+,`（Windows/Linux）開啟，然後前往「擴充功能」→「Claude Code」。您也可以輸入 `/` 並選擇**一般配置**以開啟設定。

352* **`~/.claude/settings.json` 中的 Claude Code 設定**：在擴充功能和 CLI 之間共享。用於允許的命令、環境變數、hooks 和 MCP servers。有關詳細資訊，請參閱[設定](/zh-TW/settings)。352* **`~/.claude/settings.json` 中的 Claude Code 設定**：在擴充功能和 CLI 之間共享。用於允許的命令、環境變數、hooks 和 MCP servers。有關詳細資訊，請參閱[設定](/docs/zh-TW/settings)。

353 353

354<Tip>354<Tip>

355 將 `"$schema": "https://json.schemastore.org/claude-code-settings.json"` 添加到您的 `settings.json` 以在 VS Code 中直接獲得所有可用設定的自動完成和內聯驗證。355 將 `"$schema": "https://json.schemastore.org/claude-code-settings.json"` 添加到您的 `settings.json` 以在 VS Code 中直接獲得所有可用設定的自動完成和內聯驗證。

362| 設定 | 預設值 | 描述 |362| 設定 | 預設值 | 描述 |

363| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |363| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

365| `initialPermissionMode` | `default` | 控制新對話的批准提示：`default`、`plan`、`acceptEdits` 或 `bypassPermissions`。{/* min-version: 2.1.200 */}`manual` 是 `default` 的別名，並選擇模式指示器中標記為**手動**的模式。需要 Claude Code v2.1.200 或更新版本。請參閱[許可模式](/zh-TW/permission-modes)。 |365| `initialPermissionMode` | `default` | 控制新對話的批准提示：`default`、`plan`、`acceptEdits` 或 `bypassPermissions`。`manual` 是 `default` 的別名，並選擇模式指示器中標記為**手動**的模式。需要 Claude Code v2.1.200 或更新版本。請參閱[許可模式](/docs/zh-TW/permission-modes)。 |

374| `environmentVariables` | `[]` | 為 Claude 程序設定環境變數。改為使用 Claude Code 設定以進行共享配置。 |374| `environmentVariables` | `[]` | 為 Claude 程序設定環境變數。改為使用 Claude Code 設定以進行共享配置。 |

377| `claudeProcessWrapper` | - | 用於啟動 Claude 程序的可執行檔。當存在時，捆綁的二進制檔案路徑會作為引數傳遞。如果擴充功能組建不包含您平台的二進制檔案，請將此設定為單獨安裝的 `claude` 二進制檔案。如果擴充功能組建不包含您平台的二進制檔案，請參閱[哪些平台有預先建置的二進制檔案](/zh-TW/troubleshoot-install#native-binary-not-found-after-npm-install)。 |377| `claudeProcessWrapper` | - | 用於啟動 Claude 程序的可執行檔。當存在時，捆綁的二進制檔案路徑會作為引數傳遞。如果擴充功能組建不包含您平台的二進制檔案，請將此設定為單獨安裝的 `claude` 二進制檔案。如果擴充功能組建不包含您平台的二進制檔案，請參閱[哪些平台有預先建置的二進制檔案](/docs/zh-TW/troubleshoot-install#native-binary-not-found-after-npm-install)。 |

378 378

379<h2 id="vs-code-extension-vs-claude-code-cli">379<h2 id="vs-code-extension-vs-claude-code-cli">

380 VS Code 擴充功能與 Claude Code CLI380 VS Code 擴充功能與 Claude Code CLI

381</h2>381</h2>

382 382

383Claude Code 既可作為 VS Code 擴充功能（圖形面板）也可作為 CLI（終端機中的命令列介面）使用。某些功能僅在 CLI 中可用。如果您需要 CLI 專用功能，請在 VS Code 的整合終端機中執行 `claude`。這需要[獨立 CLI 安裝](/zh-TW/setup)：擴充功能不會將 `claude` 新增到您的 PATH。請參閱[在 VS Code 中執行 CLI](#run-cli-in-vs-code)。383Claude Code 既可作為 VS Code 擴充功能（圖形面板）也可作為 CLI（終端機中的命令列介面）使用。某些功能僅在 CLI 中可用。如果您需要 CLI 專用功能，請在 VS Code 的整合終端機中執行 `claude`。這需要[獨立 CLI 安裝](/docs/zh-TW/setup)：擴充功能不會將 `claude` 新增到您的 PATH。請參閱[在 VS Code 中執行 CLI](#run-cli-in-vs-code)。

384 384

385| 功能 | CLI | VS Code 擴充功能 |385| 功能 | CLI | VS Code 擴充功能 |

386| ------------- | --------------------- | ---------------------------------------- |386| ------------- | --------------------- | ---------------------------------------- |

388| MCP server 配置 | 是 | 部分（透過 CLI 添加伺服器；使用聊天面板中的 `/mcp` 管理現有伺服器） |388| MCP server 配置 | 是 | 部分（透過 CLI 添加伺服器；使用聊天面板中的 `/mcp` 管理現有伺服器） |

389| Checkpoints | 是 | 是 |389| Checkpoints | 是 | 是 |

390| `!` bash 快捷方式 | 是 | 否 |390| `!` bash 快捷方式 | 是 | 否 |

400* **將程式碼倒帶到此處**：將檔案變更還原回對話中的此點，同時保持完整的對話歷史記錄400* **將程式碼倒帶到此處**：將檔案變更還原回對話中的此點，同時保持完整的對話歷史記錄

401* **分支對話並倒帶程式碼**：開始新的對話分支並將檔案變更還原到此點401* **分支對話並倒帶程式碼**：開始新的對話分支並將檔案變更還原到此點

402 402

403有關 checkpoints 如何工作及其限制的完整詳細資訊，請參閱 [Checkpointing](/zh-TW/checkpointing)。403有關 checkpoints 如何工作及其限制的完整詳細資訊，請參閱 [Checkpointing](/docs/zh-TW/checkpointing)。

404 404

405<h3 id="run-cli-in-vs-code">405<h3 id="run-cli-in-vs-code">

406 在 VS Code 中執行 CLI406 在 VS Code 中執行 CLI

408 408

409若要在 VS Code 中使用 CLI，請開啟整合終端機（Windows/Linux 上的 `` Ctrl+` `` 或 Mac 上的 `` Cmd+` ``）並執行 `claude`。CLI 會自動與您的 IDE 整合，以獲得差異檢視和診斷共享等功能。409若要在 VS Code 中使用 CLI，請開啟整合終端機（Windows/Linux 上的 `` Ctrl+` `` 或 Mac 上的 `` Cmd+` ``）並執行 `claude`。CLI 會自動與您的 IDE 整合，以獲得差異檢視和診斷共享等功能。

410 410

411安裝擴充功能不會將 `claude` 放在您的 shell PATH 上。擴充功能為其聊天面板捆綁了 CLI 的私有副本，但在終端機中輸入 `claude` 需要[獨立 CLI 安裝](/zh-TW/setup)。執行一次安裝，此頁面上的命令（包括 `claude mcp add` 和 `claude --resume`）在任何終端機中都可以運作。如果安裝後仍未找到 `claude`，請[驗證您的 PATH](/zh-TW/troubleshoot-install#verify-your-path)。411安裝擴充功能不會將 `claude` 放在您的 shell PATH 上。擴充功能為其聊天面板捆綁了 CLI 的私有副本，但在終端機中輸入 `claude` 需要[獨立 CLI 安裝](/docs/zh-TW/setup)。執行一次安裝，此頁面上的命令（包括 `claude mcp add` 和 `claude --resume`）在任何終端機中都可以運作。如果安裝後仍未找到 `claude`，請[驗證您的 PATH](/docs/zh-TW/troubleshoot-install#verify-your-path)。

412 412

413如果使用外部終端機，請在 Claude Code 中執行 `/ide` 以將其連接到 VS Code。413如果使用外部終端機，請在 Claude Code 中執行 `/ide` 以將其連接到 VS Code。

414 414

445 445

446配置後，要求 Claude 使用工具（例如「Review PR #456」）。446配置後，要求 Claude 使用工具（例如「Review PR #456」）。

447 447

448若要在不離開 VS Code 的情況下管理 MCP servers，請在聊天面板中輸入 `/mcp`。MCP 管理對話框讓您啟用或停用伺服器、重新連接到伺服器以及管理 OAuth 身份驗證。有關可用伺服器，請參閱 [MCP 文件](/zh-TW/mcp)。448若要在不離開 VS Code 的情況下管理 MCP servers，請在聊天面板中輸入 `/mcp`。MCP 管理對話框讓您啟用或停用伺服器、重新連接到伺服器以及管理 OAuth 身份驗證。有關可用伺服器，請參閱 [MCP 文件](/docs/zh-TW/mcp)。

449 449

450<h2 id="work-with-git">450<h2 id="work-with-git">

451 使用 git451 使用 git

477claude --worktree feature-auth477claude --worktree feature-auth

478```478```

479 479

480每個 worktree 維護獨立的檔案狀態，同時共享 git 歷史記錄。這可防止 Claude 實例在處理不同任務時相互干擾。有關更多詳細資訊，請參閱[使用 Git worktrees 執行並行工作階段](/zh-TW/worktrees)。480每個 worktree 維護獨立的檔案狀態，同時共享 git 歷史記錄。這可防止 Claude 實例在處理不同任務時相互干擾。有關更多詳細資訊，請參閱[使用 Git worktrees 執行並行工作階段](/docs/zh-TW/worktrees)。

481 481

482<h2 id="use-third-party-providers">482<h2 id="use-third-party-providers">

483 使用第三方提供者483 使用第三方提供者

495 <Step title="配置您的提供者">495 <Step title="配置您的提供者">

496 遵循您的提供者的設定指南：496 遵循您的提供者的設定指南：

497 497

498 * [Amazon Bedrock 上的 Claude Code](/zh-TW/amazon-bedrock)498 * [Amazon Bedrock 上的 Claude Code](/docs/zh-TW/amazon-bedrock)

499 * [Google Cloud 的 Agent Platform 上的 Claude Code](/zh-TW/google-vertex-ai)499 * [Google Cloud 的 Agent Platform 上的 Claude Code](/docs/zh-TW/google-vertex-ai)

500 * [Microsoft Foundry 上的 Claude Code](/zh-TW/microsoft-foundry)500 * [Microsoft Foundry 上的 Claude Code](/docs/zh-TW/microsoft-foundry)

501 501

502 這些指南涵蓋在 `~/.claude/settings.json` 中配置您的提供者，這確保您的設定在 VS Code 擴充功能和 CLI 之間共享。502 這些指南涵蓋在 `~/.claude/settings.json` 中配置您的提供者，這確保您的設定在 VS Code 擴充功能和 CLI 之間共享。

503 </Step>503 </Step>

507 安全和隱私507 安全和隱私

508</h2>508</h2>

509 509

510您的程式碼保持私密。Claude Code 處理您的程式碼以提供協助，但不使用它來訓練模型。有關資料處理和如何選擇退出日誌記錄的詳細資訊，請參閱[資料和隱私](/zh-TW/data-usage)。510您的程式碼保持私密。Claude Code 處理您的程式碼以提供協助，但不使用它來訓練模型。有關資料處理和如何選擇退出日誌記錄的詳細資訊，請參閱[資料和隱私](/docs/zh-TW/data-usage)。

511 511

512啟用自動編輯許可後，Claude Code 可以修改 VS Code 配置檔案（如 `settings.json` 或 `tasks.json`），VS Code 可能會自動執行。為了在處理不受信任的程式碼時降低風險：512啟用自動編輯許可後，Claude Code 可以修改 VS Code 配置檔案（如 `settings.json` 或 `tasks.json`），VS Code 可能會自動執行。為了在處理不受信任的程式碼時降低風險：

513 513

523 523

524伺服器名為 `ide`，從 `/mcp` 隱藏，因為沒有什麼可配置的。但是，如果您的組織使用 `PreToolUse` hook 來允許列出 MCP 工具，您需要知道它存在。524伺服器名為 `ide`，從 `/mcp` 隱藏，因為沒有什麼可配置的。但是，如果您的組織使用 `PreToolUse` hook 來允許列出 MCP 工具，您需要知道它存在。

525 525

526**選擇和開啟檔案的內容。** 連接時，CLI 會在您傳送的每個提示上包含您目前的編輯器選擇和活動檔案的路徑作為內容。當發生這種情況時，文字記錄會顯示 `⧉ Selected N lines from <file>` 行。若要排除敏感檔案（如 `.env`），請為其路徑新增 [`Read` 拒絕規則](/zh-TW/permissions#read-and-edit)。匹配的拒絕規則會防止該檔案的選定文字和開啟檔案通知到達 Claude。526**選擇和開啟檔案的內容。** 連接時，CLI 會在您傳送的每個提示上包含您目前的編輯器選擇和活動檔案的路徑作為內容。當發生這種情況時，文字記錄會顯示 `⧉ Selected N lines from <file>` 行。若要排除敏感檔案（如 `.env`），請為其路徑新增 [`Read` 拒絕規則](/docs/zh-TW/permissions#read-and-edit)。匹配的拒絕規則會防止該檔案的選定文字和開啟檔案通知到達 Claude。

527 527

528**傳輸和身份驗證。** 伺服器綁定到 `127.0.0.1` 上的隨機高埠，埠號範圍為 10000–65535，且埠號不可配置。傳輸是未加密的 `ws://`；因為通訊端是環回專用的，任何可以捕獲流量的程序也可以從鎖定檔案讀取令牌，所以 TLS 不會增加保護。每次擴充功能啟動都會生成一個新的隨機身份驗證令牌，將其寫入 `~/.claude/ide/<port>.lock` 的鎖定檔案，CLI 必須將其作為 `X-Claude-Code-Ide-Authorization` 標頭提供才能連接。鎖定檔案在 `0700` 目錄中具有 `0600` 權限，因此只有執行 VS Code 的使用者可以讀取它。如果設定了 `CLAUDE_CONFIG_DIR`，鎖定檔案會改為寫入 `$CLAUDE_CONFIG_DIR/ide/`。528**傳輸和身份驗證。** 伺服器綁定到 `127.0.0.1` 上的隨機高埠，埠號範圍為 10000–65535，且埠號不可配置。傳輸是未加密的 `ws://`；因為通訊端是環回專用的，任何可以捕獲流量的程序也可以從鎖定檔案讀取令牌，所以 TLS 不會增加保護。每次擴充功能啟動都會生成一個新的隨機身份驗證令牌，將其寫入 `~/.claude/ide/<port>.lock` 的鎖定檔案，CLI 必須將其作為 `X-Claude-Code-Ide-Authorization` 標頭提供才能連接。鎖定檔案在 `0700` 目錄中具有 `0600` 權限，因此只有執行 VS Code 的使用者可以讀取它。如果設定了 `CLAUDE_CONFIG_DIR`，鎖定檔案會改為寫入 `$CLAUDE_CONFIG_DIR/ide/`。

529 529

6022. 搜尋「Claude Code」6022. 搜尋「Claude Code」

6033. 點擊**卸載**6033. 點擊**卸載**

604 604

605在 VS Code 整合終端中執行 `claude` 會自動重新安裝擴充功能。若要保持卸載狀態，請在 `/config` 中關閉**自動安裝 IDE 擴充功能**，或將 [`autoInstallIdeExtension`](/zh-TW/settings#global-config-settings) 設定為 `false`。您也可以將 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-TW/env-vars) 環境變數設定為 `1`。605在 VS Code 整合終端中執行 `claude` 會自動重新安裝擴充功能。若要保持卸載狀態，請在 `/config` 中關閉**自動安裝 IDE 擴充功能**，或將 [`autoInstallIdeExtension`](/docs/zh-TW/settings#global-config-settings) 設定為 `false`。您也可以將 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/docs/zh-TW/env-vars) 環境變數設定為 `1`。

606 606

607若要也移除擴充功能資料並重設所有設定，請刪除您平台的擴充功能儲存目錄。607若要也移除擴充功能資料並重設所有設定，請刪除您平台的擴充功能儲存目錄。

608 608

624Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"624Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"

625```625```

626 626

627如需其他幫助，請參閱[故障排除指南](/zh-TW/troubleshooting)。627如需其他幫助，請參閱[故障排除指南](/docs/zh-TW/troubleshooting)。

628 628

629<h2 id="next-steps">629<h2 id="next-steps">

630 後續步驟630 後續步驟

632 632

633現在您已在 VS Code 中設定了 Claude Code：633現在您已在 VS Code 中設定了 Claude Code：

634 634

635* [探索常見工作流程](/zh-TW/common-workflows)以充分利用 Claude Code635* [探索常見工作流程](/docs/zh-TW/common-workflows)以充分利用 Claude Code

636* [設定 MCP servers](/zh-TW/mcp) 以使用外部工具擴展 Claude 的功能。使用 CLI 添加伺服器，然後使用聊天面板中的 `/mcp` 管理它們。636* [設定 MCP servers](/docs/zh-TW/mcp) 以使用外部工具擴展 Claude 的功能。使用 CLI 添加伺服器，然後使用聊天面板中的 `/mcp` 管理它們。

637* [配置 Claude Code 設定](/zh-TW/settings)以自訂允許的命令、hooks 等。這些設定在擴充功能和 CLI 之間共享。637* [配置 Claude Code 設定](/docs/zh-TW/settings)以自訂允許的命令、hooks 等。這些設定在擴充功能和 CLI 之間共享。

web-quickstart.md +25 −25

Details

21* **不需要頻繁引導的任務**：提交一個定義明確的任務，做其他事情，並在 Claude 完成時檢查結果21* **不需要頻繁引導的任務**：提交一個定義明確的任務，做其他事情，並在 Claude 完成時檢查結果

22* **代碼問題和探索**：理解代碼庫或追蹤功能如何實現，無需本地簽出22* **代碼問題和探索**：理解代碼庫或追蹤功能如何實現，無需本地簽出

23 23

~~24對於需要您本地配置、工具或環境的工作，在本地執行 Claude Code 或使用 [Remote Control](/zh-TW/remote-control) 更合適。~~24對於需要您本地配置、工具或環境的工作，在本地執行 Claude Code 或使用 [Remote Control](/docs/zh-TW/remote-control) 更合適。

25 25

26<h2 id="how-sessions-run">26<h2 id="how-sessions-run">

27 會話如何執行27 會話如何執行

29 29

30當您提交任務時：30當您提交任務時：

31 31

~~321. **複製和準備**：您的儲存庫被複製到 Anthropic 管理的 VM，並且您的[設定指令碼](/zh-TW/claude-code-on-the-web#setup-scripts)會在配置時執行。~~321. **複製和準備**：您的儲存庫被複製到 Anthropic 管理的 VM，並且您的[設定指令碼](/docs/zh-TW/claude-code-on-the-web#setup-scripts)會在配置時執行。

~~332. **配置網路**：根據您環境的[存取級別](/zh-TW/claude-code-on-the-web#access-levels)設定網際網路存取。~~332. **配置網路**：根據您環境的[存取級別](/docs/zh-TW/claude-code-on-the-web#access-levels)設定網際網路存取。

343. **工作**：Claude 分析代碼、進行更改、執行測試並檢查其工作。您可以全程觀看和引導，或者離開並在完成時返回。343. **工作**：Claude 分析代碼、進行更改、執行測試並檢查其工作。您可以全程觀看和引導，或者離開並在完成時返回。

354. **推送分支**：當 Claude 達到停止點時，它會將其分支推送到 GitHub。您檢查差異、留下內聯評論、建立 PR 或發送另一條訊息以繼續。354. **推送分支**：當 Claude 達到停止點時，它會將其分支推送到 GitHub。您檢查差異、留下內聯評論、建立 PR 或發送另一條訊息以繼續。

36 36

49| **使用您的本地配置** | 否，僅儲存庫 | 是 | 是 | 本地為是，雲端為否 |49| **使用您的本地配置** | 否，僅儲存庫 | 是 | 是 | 本地為是，雲端為否 |

50| **需要 GitHub** | 是，或透過 `--cloud` [捆綁本地儲存庫](/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 | 僅限雲端會話 |50| **需要 GitHub** | 是，或透過 `--cloud` [捆綁本地儲存庫](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 | 僅限雲端會話 |

51| **如果您斷開連接，保持執行** | 是 | 終端保持開啟時 | 否 | 取決於會話類型 |51| **如果您斷開連接，保持執行** | 是 | 終端保持開啟時 | 否 | 取決於會話類型 |

54 54

~~55請參閱 [terminal quickstart](/zh-TW/quickstart)、[Desktop 應用程式](/zh-TW/desktop) 或 [Remote Control](/zh-TW/remote-control) 文件以設定這些。~~55請參閱 [terminal quickstart](/docs/zh-TW/quickstart)、[Desktop 應用程式](/docs/zh-TW/desktop) 或 [Remote Control](/docs/zh-TW/remote-control) 文件以設定這些。

56 56

57<h2 id="connect-github-and-create-an-environment">57<h2 id="connect-github-and-create-an-environment">

58 連接 GitHub 並建立環境58 連接 GitHub 並建立環境

70 </Step>70 </Step>

71 71

72 <Step title="建立您的環境">72 <Step title="建立您的環境">

73 連接 GitHub 後，系統會提示您建立雲端環境。環境控制 Claude 在會話期間可以存取的網路以及在建立新會話時執行的內容。請參閱[已安裝的工具](/zh-TW/claude-code-on-the-web#installed-tools)以了解無需任何配置即可使用的內容。73 連接 GitHub 後，系統會提示您建立雲端環境。環境控制 Claude 在會話期間可以存取的網路以及在建立新會話時執行的內容。請參閱[已安裝的工具](/docs/zh-TW/claude-code-on-the-web#installed-tools)以了解無需任何配置即可使用的內容。

74 74

75 表單具有以下欄位：75 表單具有以下欄位：

76 76

77 * **名稱**：顯示標籤。當您為不同的項目或存取級別有多個環境時很有用。77 * **名稱**：顯示標籤。當您為不同的項目或存取級別有多個環境時很有用。

78 * **網路存取**：控制會話可以在網際網路上到達的內容。預設值 `Trusted` 允許連接到[常見套件登錄](/zh-TW/claude-code-on-the-web#default-allowed-domains)（如 npm、PyPI 和 RubyGems），同時阻止一般網際網路存取。78 * **網路存取**：控制會話可以在網際網路上到達的內容。預設值 `Trusted` 允許連接到[常見套件登錄](/docs/zh-TW/claude-code-on-the-web#default-allowed-domains)（如 npm、PyPI 和 RubyGems），同時阻止一般網際網路存取。

79 * **環境變數**：可選變數，在每個會話中可用，採用 `.env` 格式。不要用引號包裝值，因為引號會儲存為值的一部分。這些對任何可以編輯此環境的人都可見。79 * **環境變數**：可選變數，在每個會話中可用，採用 `.env` 格式。不要用引號包裝值，因為引號會儲存為值的一部分。這些對任何可以編輯此環境的人都可見。

80 * **設定指令碼**：可選的 Bash 指令碼，在 Claude Code 啟動前執行。使用它來安裝雲端 VM 不包含的系統工具，如 `apt install -y gh`。結果會被[快取](/zh-TW/claude-code-on-the-web#environment-caching)，因此指令碼不會在每個會話上重新執行。請參閱[設定指令碼](/zh-TW/claude-code-on-the-web#setup-scripts)以了解範例和除錯提示。80 * **設定指令碼**：可選的 Bash 指令碼，在 Claude Code 啟動前執行。使用它來安裝雲端 VM 不包含的系統工具，如 `apt install -y gh`。結果會被[快取](/docs/zh-TW/claude-code-on-the-web#environment-caching)，因此指令碼不會在每個會話上重新執行。請參閱[設定指令碼](/docs/zh-TW/claude-code-on-the-web#setup-scripts)以了解範例和除錯提示。

81 81

82 對於第一個項目，保留預設值並點擊**建立環境**。您可以[稍後編輯它或為不同的項目建立其他環境](/zh-TW/claude-code-on-the-web#configure-your-environment)。82 對於第一個項目，保留預設值並點擊**建立環境**。您可以[稍後編輯它或為不同的項目建立其他環境](/docs/zh-TW/claude-code-on-the-web#configure-your-environment)。

83 </Step>83 </Step>

84</Steps>84</Steps>

85 85

87 從您的終端連接87 從您的終端連接

88</h3>88</h3>

89 89

90如果您已經使用 GitHub CLI (`gh`)，您可以在不打開瀏覽器的情況下設定 Claude Code on the web。這需要 [Claude Code CLI](/zh-TW/quickstart)。`/web-setup` 讀取您的本地 `gh` 令牌，將其連結到您的 Claude 帳戶，並在您沒有雲端環境時建立預設雲端環境。90如果您已經使用 GitHub CLI (`gh`)，您可以在不打開瀏覽器的情況下設定 Claude Code on the web。這需要 [Claude Code CLI](/docs/zh-TW/quickstart)。`/web-setup` 讀取您的本地 `gh` 令牌，將其連結到您的 Claude 帳戶，並在您沒有雲端環境時建立預設雲端環境。

91 91

92<Note>92<Note>

93 啟用了[零資料保留](/zh-TW/zero-data-retention)的組織無法使用 `/web-setup` 或其他雲端會話功能。如果未安裝或驗證 GitHub CLI，`/web-setup` 會改為開啟瀏覽器上線流程。93 啟用了[零資料保留](/docs/zh-TW/zero-data-retention)的組織無法使用 `/web-setup` 或其他雲端會話功能。如果未安裝或驗證 GitHub CLI，`/web-setup` 會改為開啟瀏覽器上線流程。

94</Note>94</Note>

95 95

96<Steps>96<Steps>

113 /web-setup113 /web-setup

114 ```114 ```

115 115

116 這會將您的 `gh` 令牌同步到您的 Claude 帳戶。如果您還沒有雲端環境，`/web-setup` 會建立一個具有 Trusted 網路存取且沒有設定指令碼的環境。您可以[稍後編輯環境或新增變數](/zh-TW/claude-code-on-the-web#configure-your-environment)。一旦 `/web-setup` 完成，您可以使用 [`--cloud`](/zh-TW/claude-code-on-the-web#from-terminal-to-web) 從您的終端啟動雲端會話，或使用 [`/schedule`](/zh-TW/routines) 設定定期任務。116 這會將您的 `gh` 令牌同步到您的 Claude 帳戶。如果您還沒有雲端環境，`/web-setup` 會建立一個具有 Trusted 網路存取且沒有設定指令碼的環境。您可以[稍後編輯環境或新增變數](/docs/zh-TW/claude-code-on-the-web#configure-your-environment)。一旦 `/web-setup` 完成，您可以使用 [`--cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web) 從您的終端啟動雲端會話，或使用 [`/schedule`](/docs/zh-TW/routines) 設定定期任務。

117 </Step>117 </Step>

118</Steps>118</Steps>

119 119

129 </Step>129 </Step>

130 130

131 <Step title="選擇權限模式">131 <Step title="選擇權限模式">

132 輸入框旁邊的模式下拉菜單預設為**接受編輯**，其中 Claude 進行更改並推送分支而無需停止以獲得批准。如果您希望 Claude 提出方法並在編輯文件前等待您的同意，請切換到 **Plan Mode**。雲端會話不提供 Manual 或 Bypass 權限。請參閱[權限模式完整列表](/zh-TW/permission-modes#available-modes)以了解每個模式允許的操作。132 輸入框旁邊的模式下拉菜單預設為**接受編輯**，其中 Claude 進行更改並推送分支而無需停止以獲得批准。如果您希望 Claude 提出方法並在編輯文件前等待您的同意，請切換到 **Plan Mode**。雲端會話不提供 Manual 或 Bypass 權限。請參閱[權限模式完整列表](/docs/zh-TW/permission-modes#available-modes)以了解每個模式允許的操作。

133 </Step>133 </Step>

134 134

135 <Step title="描述任務並提交">135 <Step title="描述任務並提交">

182 </Step>182 </Step>

183 183

184 <Step title="在 PR 後繼續迭代">184 <Step title="在 PR 後繼續迭代">

185 建立 PR 後會話保持活躍。將 CI 失敗輸出或審查者評論貼上到聊天中，並要求 Claude 解決它們。要讓 Claude 自動監控 PR，請參閱[自動修復拉取請求](/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)。185 建立 PR 後會話保持活躍。將 CI 失敗輸出或審查者評論貼上到聊天中，並要求 Claude 解決它們。要讓 Claude 自動監控 PR，請參閱[自動修復拉取請求](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)。

186 </Step>186 </Step>

187</Steps>187</Steps>

188 188

194 連接 GitHub 後沒有儲存庫出現194 連接 GitHub 後沒有儲存庫出現

195</h3>195</h3>

196 196

197雲端會話可以使用連接的 GitHub 帳戶可以看到的任何儲存庫，無論 Claude GitHub App 安裝在哪些儲存庫上。如果儲存庫遺失，請驗證連接的 GitHub 帳戶在 GitHub 上是否有權存取它。如果您還想要儲存庫的[自動修復](/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)，請在其上安裝應用程式：在 github.com 上，打開**設定 → 應用程式 → Claude → 配置**並驗證儲存庫是否列在**儲存庫存取**下。私有儲存庫需要與公開儲存庫相同的授權。197雲端會話可以使用連接的 GitHub 帳戶可以看到的任何儲存庫，無論 Claude GitHub App 安裝在哪些儲存庫上。如果儲存庫遺失，請驗證連接的 GitHub 帳戶在 GitHub 上是否有權存取它。如果您還想要儲存庫的[自動修復](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)，請在其上安裝應用程式：在 github.com 上，打開**設定 → 應用程式 → Claude → 配置**並驗證儲存庫是否列在**儲存庫存取**下。私有儲存庫需要與公開儲存庫相同的授權。

198 198

199<h3 id="the-page-only-shows-a-github-login-button">199<h3 id="the-page-only-shows-a-github-login-button">

200 頁面只顯示 GitHub 登入按鈕200 頁面只顯示 GitHub 登入按鈕

201</h3>201</h3>

202 202

203雲端會話需要連接的 GitHub 帳戶。透過上面的瀏覽器流程連接，或者如果您使用 GitHub CLI，從您的終端執行 `/web-setup`。如果您根本不想連接 GitHub，請參閱 [Remote Control](/zh-TW/remote-control) 以在您自己的機器上執行 Claude Code 並從網頁監控它。203雲端會話需要連接的 GitHub 帳戶。透過上面的瀏覽器流程連接，或者如果您使用 GitHub CLI，從您的終端執行 `/web-setup`。如果您根本不想連接 GitHub，請參閱 [Remote Control](/docs/zh-TW/remote-control) 以在您自己的機器上執行 Claude Code 並從網頁監控它。

204 204

205<h3 id="not-available-for-the-selected-organization">205<h3 id="not-available-for-the-selected-organization">

206 "不適用於選定的組織"206 "不適用於選定的組織"

220 使用 `--cloud` 或 ultraplan 時出現 "Could not create a cloud environment" 或 "No cloud environment available"220 使用 `--cloud` 或 ultraplan 時出現 "Could not create a cloud environment" 或 "No cloud environment available"

221</h3>221</h3>

222 222

223遠端會話功能會在您沒有雲端環境時自動建立預設雲端環境。如果您看到 "Could not create a cloud environment"，自動建立失敗。{/* max-version: 2.1.100 */}如果您看到 "No cloud environment available"，您的 CLI 早於自動建立。在任何一種情況下，在 Claude Code CLI 中執行 `/web-setup` 以手動建立一個，或訪問 [claude.ai/code](https://claude.ai/code) 並按照上面的**建立您的環境**步驟進行。223遠端會話功能會在您沒有雲端環境時自動建立預設雲端環境。如果您看到 "Could not create a cloud environment"，自動建立失敗。如果您看到 "No cloud environment available"，您的 CLI 早於自動建立。在任何一種情況下，在 Claude Code CLI 中執行 `/web-setup` 以手動建立一個，或訪問 [claude.ai/code](https://claude.ai/code) 並按照上面的**建立您的環境**步驟進行。

224 224

225<h3 id="setup-script-failed">225<h3 id="setup-script-failed">

226 設定指令碼失敗226 設定指令碼失敗

228 228

229設定指令碼以非零狀態退出，這會阻止會話啟動。常見原因：229設定指令碼以非零狀態退出，這會阻止會話啟動。常見原因：

230 230

231* 套件安裝失敗，因為登錄不在您的[網路存取級別](/zh-TW/claude-code-on-the-web#access-levels)中。`Trusted` 涵蓋大多數套件管理器；`None` 阻止它們全部。231* 套件安裝失敗，因為登錄不在您的[網路存取級別](/docs/zh-TW/claude-code-on-the-web#access-levels)中。`Trusted` 涵蓋大多數套件管理器；`None` 阻止它們全部。

232* 指令碼引用在新鮮複製中不存在的文件或路徑。232* 指令碼引用在新鮮複製中不存在的文件或路徑。

233* 在本地工作的命令在 Ubuntu 上需要不同的調用。233* 在本地工作的命令在 Ubuntu 上需要不同的調用。

234 234

238 新會話在設定期間掛起或逾時238 新會話在設定期間掛起或逾時

239</h3>239</h3>

240 240

241如果新會話在設定指令碼步驟上停滯或在指令碼完成前因通用容器錯誤而失敗，指令碼可能超過了大約五分鐘的時間預算來建立[環境快取](/zh-TW/claude-code-on-the-web#environment-caching)。繁重的步驟，例如拉取大型 Docker 映像、同步完整依賴樹或下載模型權重，通常會將總數推過限制，特別是當它們一個接一個執行時。241如果新會話在設定指令碼步驟上停滯或在指令碼完成前因通用容器錯誤而失敗，指令碼可能超過了大約五分鐘的時間預算來建立[環境快取](/docs/zh-TW/claude-code-on-the-web#environment-caching)。繁重的步驟，例如拉取大型 Docker 映像、同步完整依賴樹或下載模型權重，通常會將總數推過限制，特別是當它們一個接一個執行時。

242 242

243要修復此問題，修剪指令碼以便它可靠地在五分鐘內完成：243要修復此問題，修剪指令碼以便它可靠地在五分鐘內完成：

244 244

245* 使用 `&` 和最終 `wait` 並行執行獨立安裝，而不是按順序執行。245* 使用 `&` 和最終 `wait` 並行執行獨立安裝，而不是按順序執行。

246* 將最大的下載移出設定指令碼，進入[SessionStart hook](/zh-TW/claude-code-on-the-web#setup-scripts-vs-sessionstart-hooks)，在背景中啟動它們，以便會話在它們完成時變得可用。246* 將最大的下載移出設定指令碼，進入[SessionStart hook](/docs/zh-TW/claude-code-on-the-web#setup-scripts-vs-sessionstart-hooks)，在背景中啟動它們，以便會話在它們完成時變得可用。

247* 從設定指令碼中移除長重試睡眠，因為停滯的重試迴圈會計入預算。247* 從設定指令碼中移除長重試睡眠，因為停滯的重試迴圈會計入預算。

248 248

249<h3 id="session-keeps-running-after-closing-the-tab">249<h3 id="session-keeps-running-after-closing-the-tab">

250 會話在關閉標籤後保持執行250 會話在關閉標籤後保持執行

251</h3>251</h3>

252 252

253這是設計使然。關閉標籤或導航離開不會停止會話。它在背景中繼續執行，直到 Claude 完成當前任務，然後閒置。從側邊欄，您可以[存檔會話](/zh-TW/claude-code-on-the-web#archive-sessions)以將其從列表中隱藏，或[刪除它](/zh-TW/claude-code-on-the-web#delete-sessions)以永久移除它。253這是設計使然。關閉標籤或導航離開不會停止會話。它在背景中繼續執行，直到 Claude 完成當前任務，然後閒置。從側邊欄，您可以[存檔會話](/docs/zh-TW/claude-code-on-the-web#archive-sessions)以將其從列表中隱藏，或[刪除它](/docs/zh-TW/claude-code-on-the-web#delete-sessions)以永久移除它。

254 254

255<h2 id="next-steps">255<h2 id="next-steps">

256 後續步驟256 後續步驟

258 258

259現在您可以提交和檢查任務，這些頁面涵蓋接下來的內容：從您的終端啟動雲端會話、安排定期工作以及為 Claude 提供常設指令。259現在您可以提交和檢查任務，這些頁面涵蓋接下來的內容：從您的終端啟動雲端會話、安排定期工作以及為 Claude 提供常設指令。

260 260

261* [使用 Claude Code on the web](/zh-TW/claude-code-on-the-web)：完整參考，包括將會話傳送到您的終端、設定指令碼、環境變數和網路配置261* [使用 Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)：完整參考，包括將會話傳送到您的終端、設定指令碼、環境變數和網路配置

262* [Routines](/zh-TW/routines)：按計劃、透過 API 呼叫或回應 GitHub 事件自動化工作262* [Routines](/docs/zh-TW/routines)：按計劃、透過 API 呼叫或回應 GitHub 事件自動化工作

263* [CLAUDE.md](/zh-TW/memory)：為 Claude 提供在每個會話開始時載入的持久指令和上下文263* [CLAUDE.md](/docs/zh-TW/memory)：為 Claude 提供在每個會話開始時載入的持久指令和上下文

264* 安裝 Claude 行動應用程式以用於 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 以從您的手機監控會話。從 Claude Code CLI，`/mobile` 顯示 QR 碼。264* 安裝 Claude 行動應用程式以用於 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 以從您的手機監控會話。從 Claude Code CLI，`/mobile` 顯示 QR 碼。

workflows.md +19 −21

Details

6 6

7> 動態工作流程從 Claude 編寫的指令碼協調許多子代理，您可以重新執行。用於程式碼庫審計、大規模遷移和交叉檢查研究。7> 動態工作流程從 Claude 編寫的指令碼協調許多子代理，您可以重新執行。用於程式碼庫審計、大規模遷移和交叉檢查研究。

8 8

~~9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}~~

11<Note>9<Note>

12 Dynamic workflows 需要 Claude Code v2.1.154 或更新版本，並在所有付費方案上可用，具有 Anthropic API 存取權限，以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上可用。在 Pro 上，從 `/config` 中的 Dynamic workflows 列啟用它們。10 Dynamic workflows 需要 Claude Code v2.1.154 或更新版本，並在所有付費方案上可用，具有 Anthropic API 存取權限，以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上可用。在 Pro 上，從 `/config` 中的 Dynamic workflows 列啟用它們。

13</Note>11</Note>

14 12

15動態工作流程是一個 JavaScript 指令碼，可大規模協調[子代理](/zh-TW/sub-agents)。Claude 為您描述的任務編寫指令碼，執行時期在背景執行它，同時您的工作階段保持回應。13動態工作流程是一個 JavaScript 指令碼，可大規模協調[子代理](/docs/zh-TW/sub-agents)。Claude 為您描述的任務編寫指令碼，執行時期在背景執行它，同時您的工作階段保持回應。

16 14

17當任務需要超過一個對話可以協調的代理數量時，或當您想將協調編成可以讀取和重新執行的指令碼時，請使用工作流程。範例包括程式碼庫範圍的錯誤掃描、500 個檔案遷移、需要相互交叉檢查來源的研究問題，以及值得從多個獨立角度起草的困難計畫，然後再提交給其中一個。15當任務需要超過一個對話可以協調的代理數量時，或當您想將協調編成可以讀取和重新執行的指令碼時，請使用工作流程。範例包括程式碼庫範圍的錯誤掃描、500 個檔案遷移、需要相互交叉檢查來源的研究問題，以及值得從多個獨立角度起草的困難計畫，然後再提交給其中一個。

18 16

20 何時使用工作流程18 何時使用工作流程

21</h2>19</h2>

22 20

~~23[子代理](/zh-TW/sub-agents)、[技能](/zh-TW/skills)、[代理團隊](/zh-TW/agent-teams)和工作流程都可以執行多步驟任務。區別在於誰掌握計畫：~~21[子代理](/docs/zh-TW/sub-agents)、[技能](/docs/zh-TW/skills)、[代理團隊](/docs/zh-TW/agent-teams)和工作流程都可以執行多步驟任務。區別在於誰掌握計畫：

24 22

25| | 子代理 | 技能 | 代理團隊 | 工作流程 |23| | 子代理 | 技能 | 代理團隊 | 工作流程 |

26| :--------- | :------------ | :------------ | :------------ | :----------- |24| :--------- | :------------ | :------------ | :------------ | :----------- |

69 <Step title="閱讀報告">67 <Step title="閱讀報告">

70 執行完成後，報告進入您的工作階段。它引用每項聲明來自的來源，未通過交叉檢查的聲明已被篩選出去。68 執行完成後，報告進入您的工作階段。它引用每項聲明來自的來源，未通過交叉檢查的聲明已被篩選出去。

71 69

72 {/* min-version: 2.1.196 */}自 v2.1.196 起，當驗證代理無法檢查聲明時（例如在速率限制或 API 錯誤之後），報告會將該聲明列為未驗證，而不是計為駁回。70 自 v2.1.196 起，當驗證代理無法檢查聲明時（例如在速率限制或 API 錯誤之後），報告會將該聲明列為未驗證，而不是計為駁回。

73 </Step>71 </Step>

74</Steps>72</Steps>

75 73

83 81

84| 命令 | 它做什麼 |82| 命令 | 它做什麼 |

85| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |83| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |

86| `/deep-research <question>` | 在多個角度上展開網路搜尋問題，獲取並交叉檢查它找到的來源，對每項聲明進行投票，並返回引用的報告，其中未通過交叉檢查的聲明已被篩選出去。需要[WebSearch 工具](/zh-TW/tools-reference#websearch-tool-behavior)可用 |84| `/deep-research <question>` | 在多個角度上展開網路搜尋問題，獲取並交叉檢查它找到的來源，對每項聲明進行投票，並返回引用的報告，其中未通過交叉檢查的聲明已被篩選出去。需要[WebSearch 工具](/docs/zh-TW/tools-reference#websearch-tool-behavior)可用 |

87 85

88[您自己儲存的工作流程](#save-the-workflow-for-reuse)以相同方式成為命令，並在 `/` 自動完成中與捆綁的命令一起出現。86[您自己儲存的工作流程](#save-the-workflow-for-reuse)以相同方式成為命令，並在 `/` 自動完成中與捆綁的命令一起出現。

89 87

107| `j` / `k` | 當代理詳細資訊溢出時在其中捲動 |105| `j` / `k` | 當代理詳細資訊溢出時在其中捲動 |

108| `f` | {/* min-version: 2.1.186 */}按狀態篩選選定階段中的代理清單。再次按以循環 |106| `f` | 按狀態篩選選定階段中的代理清單。再次按以循環 |

109| `p` | 暫停或恢復執行 |107| `p` | 暫停或恢復執行 |

110| `x` | 停止選定的代理，或當焦點在執行上時停止整個工作流程 |108| `x` | 停止選定的代理，或當焦點在執行上時停止整個工作流程 |

111| `r` | 重新啟動選定的執行中代理 |109| `r` | 重新啟動選定的執行中代理 |

142 讓 Claude 使用 ultracode 決定140 讓 Claude 使用 ultracode 決定

143</h3>141</h3>

144 142

145Ultracode 是一個 Claude Code 設定，結合 `xhigh` [推理努力](/zh-TW/model-config#adjust-effort-level)與自動工作流程協調。啟用它後，Claude 為每項實質性任務規劃工作流程，而不是等待您要求。143Ultracode 是一個 Claude Code 設定，結合 `xhigh` [推理努力](/docs/zh-TW/model-config#adjust-effort-level)與自動工作流程協調。啟用它後，Claude 為每項實質性任務規劃工作流程，而不是等待您要求。

146 144

147```text theme={null}145```text theme={null}

148/effort ultracode146/effort ultracode

152 150

153啟用 ultracode 後，Claude 決定任務何時值得工作流程。單個請求可以變成一系列工作流程：一個用於理解程式碼，一個用於進行更改，一個用於驗證它。這適用於工作階段中的每項任務，因此每個請求使用更多令牌並花費比較低努力級別更長的時間。151啟用 ultracode 後，Claude 決定任務何時值得工作流程。單個請求可以變成一系列工作流程：一個用於理解程式碼，一個用於進行更改，一個用於驗證它。這適用於工作階段中的每項任務，因此每個請求使用更多令牌並花費比較低努力級別更長的時間。

154 152

155Ultracode 持續當前工作階段，當您啟動新工作階段時重設。當您返回日常工作時，使用 `/effort high` 下降。它在支援 `xhigh` [努力](/zh-TW/model-config#adjust-effort-level)的模型上可用；在其他模型上，`/effort` 功能表不提供它。153Ultracode 持續當前工作階段，當您啟動新工作階段時重設。當您返回日常工作時，使用 `/effort high` 下降。它在支援 `xhigh` [努力](/docs/zh-TW/model-config#adjust-effort-level)的模型上可用；在其他模型上，`/effort` 功能表不提供它。

156 154

157<h3 id="approve-the-plan-before-it-runs">155<h3 id="approve-the-plan-before-it-runs">

158 在執行前批准計畫156 在執行前批准計畫

167 165

168`Ctrl+G` 在您的編輯器中開啟指令碼。`Tab` 讓您在執行啟動前調整提示。166`Ctrl+G` 在您的編輯器中開啟指令碼。`Tab` 讓您在執行啟動前調整提示。

169 167

170您是否看到此提示取決於您的[權限模式](/zh-TW/permission-modes)：168您是否看到此提示取決於您的[權限模式](/docs/zh-TW/permission-modes)：

171 169

172| 權限模式 | 何時提示您 |170| 權限模式 | 何時提示您 |

173| :------------------------- | :--------------------------------------------------------- |171| :------------------------- | :--------------------------------------------------------- |

177 175

178在桌面應用程式中，批准卡顯示工作流程名稱、階段列表和令牌使用警告，具有**一次**、**始終**和**拒絕**動作。進度檢視出現在背景任務側窗格中。176在桌面應用程式中，批准卡顯示工作流程名稱、階段列表和令牌使用警告，具有**一次**、**始終**和**拒絕**動作。進度檢視出現在背景任務側窗格中。

179 177

180您的權限模式僅控制上面的啟動提示。工作流程生成的子代理始終在 `acceptEdits` 模式下執行，並繼承您的[工具允許清單](/zh-TW/settings#permission-settings)，無論您的工作階段模式如何。檔案編輯自動批准。178您的權限模式僅控制上面的啟動提示。工作流程生成的子代理始終在 `acceptEdits` 模式下執行，並繼承您的[工具允許清單](/docs/zh-TW/settings#permission-settings)，無論您的工作階段模式如何。檔案編輯自動批准。

181 179

182Shell 命令、網路獲取和不在您允許清單中的 MCP 工具仍可在執行中提示您。要在長時間執行時避免這種情況，請在啟動前將代理需要的命令新增到您的允許清單。180Shell 命令、網路獲取和不在您允許清單中的 MCP 工具仍可在執行中提示您。要在長時間執行時避免這種情況，請在啟動前將代理需要的命令新增到您的允許清單。

183 181

192執行 `/workflows`，選擇您想保留的執行，然後按 `s`。在儲存對話中，Tab 在兩個儲存位置之間切換：190執行 `/workflows`，選擇您想保留的執行，然後按 `s`。在儲存對話中，Tab 在兩個儲存位置之間切換：

193 191

194* `.claude/workflows/` 在您的專案中：與克隆儲存庫的每個人共享192* `.claude/workflows/` 在您的專案中：與克隆儲存庫的每個人共享

195* `~/.claude/workflows/` 在您的主目錄中：在每個專案中可用，僅對您可見。如果您設定了 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars)，此位置是該路徑下的 `workflows/` 目錄。193* `~/.claude/workflows/` 在您的主目錄中：在每個專案中可用，僅對您可見。如果您設定了 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)，此位置是該路徑下的 `workflows/` 目錄。

196 194

197{/* min-version: 2.1.208 */}儲存對話顯示個人位置的已解析路徑。在 v2.1.208 之前，即使設定了 `CLAUDE_CONFIG_DIR`，它也顯示 `~/.claude/workflows/`；檔案仍然儲存在配置的目錄下。195儲存對話顯示個人位置的已解析路徑。在 v2.1.208 之前，即使設定了 `CLAUDE_CONFIG_DIR`，它也顯示 `~/.claude/workflows/`；檔案仍然儲存在配置的目錄下。

198 196

199按 Enter 儲存。工作流程在未來工作階段中從任一位置作為 `/<name>` 執行。197按 Enter 儲存。工作流程在未來工作階段中從任一位置作為 `/<name>` 執行。

200 198

201{/* min-version: 2.1.178 */}自 v2.1.178 起，儲存到專案位置會寫入您的工作目錄和儲存庫根目錄之間已存在的最接近的 `.claude/workflows/` 目錄，或如果尚不存在則寫入儲存庫根目錄。專案工作流程也從該路徑沿著的每個 `.claude/workflows/` 載入，當多個定義相同名稱時 Claude Code 執行最接近工作目錄的那個。199自 v2.1.178 起，儲存到專案位置會寫入您的工作目錄和儲存庫根目錄之間已存在的最接近的 `.claude/workflows/` 目錄，或如果尚不存在則寫入儲存庫根目錄。專案工作流程也從該路徑沿著的每個 `.claude/workflows/` 載入，當多個定義相同名稱時 Claude Code 執行最接近工作目錄的那個。

202 200

203如果專案工作流程和個人工作流程共享名稱，則執行專案工作流程。201如果專案工作流程和個人工作流程共享名稱，則執行專案工作流程。

204 202

305return audits.filter(Boolean)303return audits.filter(Boolean)

306```304```

307 305

308主體是具有頂級 `await` 的純 JavaScript。`agent()` 生成一個子代理，`pipeline()` 為清單中的每個項目執行一個。如果您想手動編輯指令碼，請要求 Claude 引導您完成更改，或查看 [Agent SDK 參考](/zh-TW/agent-sdk/typescript)中的 Workflow 工具條目以獲取完整的選項集。306主體是具有頂級 `await` 的純 JavaScript。`agent()` 生成一個子代理，`pipeline()` 為清單中的每個項目執行一個。如果您想手動編輯指令碼，請要求 Claude 引導您完成更改，或查看 [Agent SDK 參考](/docs/zh-TW/agent-sdk/typescript)中的 Workflow 工具條目以獲取完整的選項集。

309 307

310<h2 id="how-a-workflow-runs">308<h2 id="how-a-workflow-runs">

311 工作流程如何執行309 工作流程如何執行

359* 如果您[設定大小指南](#set-a-size-guideline)，指南的代理計數會取代 25 個代理的閾值。357* 如果您[設定大小指南](#set-a-size-guideline)，指南的代理計數會取代 25 個代理的閾值。

360* 啟用[ultracode](#let-claude-decide-with-ultracode) 的工作階段不會顯示警告，因為啟用 ultracode 已經讓您選擇加入大型執行。358* 啟用[ultracode](#let-claude-decide-with-ultracode) 的工作階段不會顯示警告，因為啟用 ultracode 已經讓您選擇加入大型執行。

361 359

362工作流程中的每個代理使用您的工作階段模型，除非指令碼將階段路由到不同的模型，或設定了 [`CLAUDE_CODE_SUBAGENT_MODEL`](/zh-TW/model-config#environment-variables) 環境變數，這會覆蓋兩者。要控制模型成本：360工作流程中的每個代理使用您的工作階段模型，除非指令碼將階段路由到不同的模型，或設定了 [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-TW/model-config#environment-variables) 環境變數，這會覆蓋兩者。要控制模型成本：

363 361

364* 在大型執行前檢查 `/model`，如果您通常為日常工作切換到較小的模型362* 在大型執行前檢查 `/model`，如果您通常為日常工作切換到較小的模型

365* 當您描述任務時，要求 Claude 為不需要最強模型的階段使用較小的模型363* 當您描述任務時，要求 Claude 為不需要最強模型的階段使用較小的模型

385 關閉工作流程383 關閉工作流程

386</h3>384</h3>

387 385

388工作流程在 CLI、桌面應用程式、IDE 擴充功能、[非互動模式](/zh-TW/headless)與 `claude -p` 和 [Agent SDK](/zh-TW/agent-sdk/overview) 中可用。相同的禁用設定適用於每個表面。386工作流程在 CLI、桌面應用程式、IDE 擴充功能、[非互動模式](/docs/zh-TW/headless)與 `claude -p` 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中可用。相同的禁用設定適用於每個表面。

389 387

390要為自己關閉工作流程：388要為自己關閉工作流程：

391 389

393* 在 `~/.claude/settings.json` 中設定 `"disableWorkflows": true`。在工作階段中持續。391* 在 `~/.claude/settings.json` 中設定 `"disableWorkflows": true`。在工作階段中持續。

394* 設定 `CLAUDE_CODE_DISABLE_WORKFLOWS=1`。在啟動時讀取，因此它適用於您設定它的任何位置。392* 設定 `CLAUDE_CODE_DISABLE_WORKFLOWS=1`。在啟動時讀取，因此它適用於您設定它的任何位置。

395 393

396要為整個組織關閉工作流程，在[受管設定](/zh-TW/server-managed-settings)中設定 `"disableWorkflows": true`，或使用 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)頁面上的切換。394要為整個組織關閉工作流程，在[受管設定](/docs/zh-TW/server-managed-settings)中設定 `"disableWorkflows": true`，或使用 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)頁面上的切換。

397 395

398禁用工作流程時，捆綁的工作流程命令不可用，`ultracode` 關鍵字不再觸發執行，`ultracode` 從 `/effort` 功能表中移除。396禁用工作流程時，捆綁的工作流程命令不可用，`ultracode` 關鍵字不再觸發執行，`ultracode` 從 `/effort` 功能表中移除。

399 397

401 相關資源399 相關資源

402</h2>400</h2>

403 401

404* [並行執行代理](/zh-TW/agents)：比較子代理、代理檢視、代理團隊和工作流程402* [並行執行代理](/docs/zh-TW/agents)：比較子代理、代理檢視、代理團隊和工作流程

405* [建立自訂子代理](/zh-TW/sub-agents)：工作流程協調的工作者原始類型403* [建立自訂子代理](/docs/zh-TW/sub-agents)：工作流程協調的工作者原始類型

406* [管理成本](/zh-TW/costs)：多代理執行如何計入使用限制404* [管理成本](/docs/zh-TW/costs)：多代理執行如何計入使用限制

worktrees.md +21 −21

Details

8 8

9[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在自己的 worktree 中執行每個 Claude Code 會話意味著一個會話中的編輯永遠不會觸及另一個會話中的檔案，因此您可以讓 Claude 在一個終端中建置功能，同時在第二個終端中修復錯誤。9[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在自己的 worktree 中執行每個 Claude Code 會話意味著一個會話中的編輯永遠不會觸及另一個會話中的檔案，因此您可以讓 Claude 在一個終端中建置功能，同時在第二個終端中修復錯誤。

10 10

11本頁涵蓋 CLI 中的 worktree 隔離。下面的所有內容都假設使用 git 儲存庫。對於其他版本控制系統，請參閱[非 git 版本控制](#non-git-version-control)。[桌面應用程式](/zh-TW/desktop#work-in-parallel-with-sessions)會自動為每個新會話建立一個 worktree。11本頁涵蓋 CLI 中的 worktree 隔離。下面的所有內容都假設使用 git 儲存庫。對於其他版本控制系統，請參閱[非 git 版本控制](#non-git-version-control)。[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)會自動為每個新會話建立一個 worktree。

12 12

13Worktrees 是執行 Claude 平行處理的幾種方式之一。它們隔離檔案編輯，而[子代理](/zh-TW/sub-agents)和[代理團隊](/zh-TW/agent-teams)協調工作本身。請參閱[平行執行代理](/zh-TW/agents)以比較這些方法，或跳到[使用 worktrees 隔離子代理](#isolate-subagents-with-worktrees)以同時使用 worktrees 和子代理。13Worktrees 是執行 Claude 平行處理的幾種方式之一。它們隔離檔案編輯，而[子代理](/docs/zh-TW/sub-agents)和[代理團隊](/docs/zh-TW/agent-teams)協調工作本身。請參閱[平行執行代理](/docs/zh-TW/agents)以比較這些方法，或跳到[使用 worktrees 隔離子代理](#isolate-subagents-with-worktrees)以同時使用 worktrees 和子代理。

14 14

15<h2 id="start-claude-in-a-worktree">15<h2 id="start-claude-in-a-worktree">

16 在 worktree 中啟動 Claude16 在 worktree 中啟動 Claude

34claude --worktree34claude --worktree

35```35```

36 36

37您也可以在會話期間要求 Claude「在 worktree 中工作」，它將使用 [`EnterWorktree`](/zh-TW/tools-reference) 工具建立一個。進入 worktree 後，Claude 可以透過呼叫 `EnterWorktree` 並指定目標路徑，直接切換到 `.claude/worktrees/` 下的另一個 worktree。前一個 worktree 保持在磁碟上未被觸及。37您也可以在會話期間要求 Claude「在 worktree 中工作」，它將使用 [`EnterWorktree`](/docs/zh-TW/tools-reference) 工具建立一個。進入 worktree 後，Claude 可以透過呼叫 `EnterWorktree` 並指定目標路徑，直接切換到 `.claude/worktrees/` 下的另一個 worktree。前一個 worktree 保持在磁碟上未被觸及。

38 38

39進入儲存庫的 `.claude/worktrees/` 目錄外的路徑會先要求您的批准，因為它會移動會話的工作目錄、寫入存取權限和專案配置（例如 `CLAUDE.md` 和設定）到該位置。`EnterWorktree` [權限規則](/zh-TW/permissions)或選擇「不再詢問」不會抑制此提示；只有 `bypassPermissions` 模式會跳過它。在 v2.1.206 之前，Claude 可以進入任何現有的 worktree 路徑而無需詢問。39進入儲存庫的 `.claude/worktrees/` 目錄外的路徑會先要求您的批准，因為它會移動會話的工作目錄、寫入存取權限和專案配置（例如 `CLAUDE.md` 和設定）到該位置。`EnterWorktree` [權限規則](/docs/zh-TW/permissions)或選擇「不再詢問」不會抑制此提示；只有 `bypassPermissions` 模式會跳過它。在 v2.1.206 之前，Claude 可以進入任何現有的 worktree 路徑而無需詢問。

40 40

41{/* min-version: 2.1.198 */}自 v2.1.198 起，進入或退出 worktree 也會將會話記錄重新定位到該目錄的專案儲存空間，與 [`/cd`](/zh-TW/commands) 的方式相同，因此 `/desktop` 和 `--resume` 之後會在該處找到會話。由 [`WorktreeCreate` hook](#non-git-version-control) 建立的 Worktrees 被排除在外，並將記錄保留在啟動目錄中。41自 v2.1.198 起，進入或退出 worktree 也會將會話記錄重新定位到該目錄的專案儲存空間，與 [`/cd`](/docs/zh-TW/commands) 的方式相同，因此 `/desktop` 和 `--resume` 之後會在該處找到會話。由 [`WorktreeCreate` hook](#non-git-version-control) 建立的 Worktrees 被排除在外，並將記錄保留在啟動目錄中。

42 42

43Worktrees 在啟用[沙箱化](/zh-TW/sandboxing#filesystem-isolation)的情況下工作：沙箱允許寫入主儲存庫的共享 `.git` 目錄，以便 `git commit` 等命令可以從連結的 worktree 內部更新參考和索引。43Worktrees 在啟用[沙箱化](/docs/zh-TW/sandboxing#filesystem-isolation)的情況下工作：沙箱允許寫入主儲存庫的共享 `.git` 目錄，以便 `git commit` 等命令可以從連結的 worktree 內部更新參考和索引。

44 44

45在第一次在目錄中使用 `--worktree` 之前，請透過在該目錄中執行一次 `claude` 來接受工作區信任對話。如果尚未接受信任，`--worktree` 將以錯誤退出並提示您先在目錄中執行 `claude`。非互動式執行搭配 `-p` 會跳過[信任檢查](/zh-TW/security)，因此 `claude -p --worktree` 會在沒有信任檢查的情況下進行。45在第一次在目錄中使用 `--worktree` 之前，請透過在該目錄中執行一次 `claude` 來接受工作區信任對話。如果尚未接受信任，`--worktree` 將以錯誤退出並提示您先在目錄中執行 `claude`。非互動式執行搭配 `-p` 會跳過[信任檢查](/docs/zh-TW/security)，因此 `claude -p --worktree` 會在沒有信任檢查的情況下進行。

46 46

47如果 Claude Code 在啟動時無法進入 worktree 目錄，例如因為 [`WorktreeCreate` hook](/zh-TW/hooks#worktreecreate) 列印了建立的目錄以外的內容，或因為目錄在設定後被刪除，Claude Code 會列印一個錯誤，命名該路徑並以代碼 1 退出。在 v2.1.205 之前，這會導致會話崩潰，使用 `-p` 時會停滯約 30 秒，然後以代碼 0 退出。47如果 Claude Code 在啟動時無法進入 worktree 目錄，例如因為 [`WorktreeCreate` hook](/docs/zh-TW/hooks#worktreecreate) 列印了建立的目錄以外的內容，或因為目錄在設定後被刪除，Claude Code 會列印一個錯誤，命名該路徑並以代碼 1 退出。在 v2.1.205 之前，這會導致會話崩潰，使用 `-p` 時會停滯約 30 秒，然後以代碼 0 退出。

48 48

49{/* min-version: 2.1.200 */}在[專案範圍](/zh-TW/plugins-reference#plugin-installation-scopes)從主要檢出安裝的外掛程式也會在同一儲存庫的 worktrees 中載入，因此您不需要為每個 worktree 重新安裝它們。無論您使用 `--worktree` 還是使用 `git worktree add` 建立 worktree，這都適用。需要 Claude Code v2.1.200 或更新版本。49在[專案範圍](/docs/zh-TW/plugins-reference#plugin-installation-scopes)從主要檢出安裝的外掛程式也會在同一儲存庫的 worktrees 中載入，因此您不需要為每個 worktree 重新安裝它們。無論您使用 `--worktree` 還是使用 `git worktree add` 建立 worktree，這都適用。需要 Claude Code v2.1.200 或更新版本。

50 50

51<Tip>51<Tip>

52 將 `.claude/worktrees/` 新增到您的 `.gitignore`，以便 worktree 內容不會在您的主要檢出中顯示為未追蹤的檔案。52 將 `.claude/worktrees/` 新增到您的 `.gitignore`，以便 worktree 內容不會在您的主要檢出中顯示為未追蹤的檔案。

60 60

61重新整理需要 Claude Code v2.1.208 或更新版本；在此之前，新的 worktree 使用已在本地快取的任何 `origin/HEAD`。61重新整理需要 Claude Code v2.1.208 或更新版本；在此之前，新的 worktree 使用已在本地快取的任何 `origin/HEAD`。

62 62

63要始終從本地 `HEAD` 分支，請在[設定](/zh-TW/settings#worktree-settings)中將 `worktree.baseRef` 設定為 `"head"`。將 `baseRef` 設定為 `"head"` 會使新 worktrees 帶有您未推送的提交和功能分支狀態，這在隔離需要在進行中的工作上操作的子代理時很有用。當會話在連結的 worktree 內執行時，`"head"` 解析為該 worktree 的 `HEAD`，而不是主要檢出的。該設定僅接受 `"fresh"` 或 `"head"`，不接受任意 git refs：63要始終從本地 `HEAD` 分支，請在[設定](/docs/zh-TW/settings#worktree-settings)中將 `worktree.baseRef` 設定為 `"head"`。將 `baseRef` 設定為 `"head"` 會使新 worktrees 帶有您未推送的提交和功能分支狀態，這在隔離需要在進行中的工作上操作的子代理時很有用。當會話在連結的 worktree 內執行時，`"head"` 解析為該 worktree 的 `HEAD`，而不是主要檢出的。該設定僅接受 `"fresh"` 或 `"head"`，不接受任意 git refs：

64 64

65```json theme={null}65```json theme={null}

66{66{

76claude --worktree "#1234"76claude --worktree "#1234"

77```77```

78 78

~~79為了完全控制 worktrees 的建立方式，請配置 [`WorktreeCreate` hook](/zh-TW/hooks#worktreecreate)，它完全取代預設的 `git worktree` 邏輯。~~79為了完全控制 worktrees 的建立方式，請配置 [`WorktreeCreate` hook](/docs/zh-TW/hooks#worktreecreate)，它完全取代預設的 `git worktree` 邏輯。

80 80

81<h3 id="reuse-a-worktree-name">81<h3 id="reuse-a-worktree-name">

82 重複使用 worktree 名稱82 重複使用 worktree 名稱

108config/secrets.json108config/secrets.json

109```109```

110 110

111這適用於使用 `--worktree` 建立的 worktrees、[子代理 worktrees](#isolate-subagents-with-worktrees) 和[桌面應用程式](/zh-TW/desktop#work-in-parallel-with-sessions)中的平行會話。111這適用於使用 `--worktree` 建立的 worktrees、[子代理 worktrees](#isolate-subagents-with-worktrees) 和[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)中的平行會話。

112 112

113<h2 id="isolate-subagents-with-worktrees">113<h2 id="isolate-subagents-with-worktrees">

114 使用 worktrees 隔離子代理114 使用 worktrees 隔離子代理

115</h2>115</h2>

116 116

117子代理可以在自己的 worktrees 中執行，以便平行編輯不會衝突。要求 Claude「為您的代理使用 worktrees」，或通過將 `isolation: worktree` 新增到 frontmatter 在[自訂子代理](/zh-TW/sub-agents#supported-frontmatter-fields)上永久設定它。每個子代理都會獲得一個臨時 worktree，當子代理完成而沒有變更時會自動移除。117子代理可以在自己的 worktrees 中執行，以便平行編輯不會衝突。要求 Claude「為您的代理使用 worktrees」，或通過將 `isolation: worktree` 新增到 frontmatter 在[自訂子代理](/docs/zh-TW/sub-agents#supported-frontmatter-fields)上永久設定它。每個子代理都會獲得一個臨時 worktree，當子代理完成而沒有變更時會自動移除。

118 118

119子代理 worktrees 使用與 `--worktree` 相同的[基礎分支](#choose-the-base-branch)，因此它們從您的儲存庫的預設分支分支，除非 `worktree.baseRef` 設定為 `"head"`。119子代理 worktrees 使用與 `--worktree` 相同的[基礎分支](#choose-the-base-branch)，因此它們從您的儲存庫的預設分支分支，除非 `worktree.baseRef` 設定為 `"head"`。

120 120

124 124

125當您退出 worktree 會話時，清理取決於您是否進行了變更：125當您退出 worktree 會話時，清理取決於您是否進行了變更：

126 126

127* **無未提交的變更、無未追蹤的檔案且無新提交**：worktree 及其分支會自動移除。如果會話有[名稱](/zh-TW/sessions#name-your-sessions)，Claude 會改為提示您，以便您可以稍後保留 worktree127* **無未提交的變更、無未追蹤的檔案且無新提交**：worktree 及其分支會自動移除。如果會話有[名稱](/docs/zh-TW/sessions#name-your-sessions)，Claude 會改為提示您，以便您可以稍後保留 worktree

128* **存在未提交的變更、未追蹤的檔案或新提交**：Claude 會提示您保留或移除 worktree。保留會保留目錄和分支，以便您稍後可以返回。移除會刪除 worktree 目錄及其分支，丟棄所有未提交的變更、未追蹤的檔案和提交128* **存在未提交的變更、未追蹤的檔案或新提交**：Claude 會提示您保留或移除 worktree。保留會保留目錄和分支，以便您稍後可以返回。移除會刪除 worktree 目錄及其分支，丟棄所有未提交的變更、未追蹤的檔案和提交

129* **非互動式執行**：使用 `--worktree` 與 `-p` 一起建立的 worktrees 不會自動清理，因為沒有退出提示。使用 `git worktree remove` 移除它們129* **非互動式執行**：使用 `--worktree` 與 `-p` 一起建立的 worktrees 不會自動清理，因為沒有退出提示。使用 `git worktree remove` 移除它們

130 130

131Claude 為子代理和[背景會話](/zh-TW/agent-view#how-file-edits-are-isolated)建立的 Worktrees 一旦超過您的 [`cleanupPeriodDays`](/zh-TW/settings#available-settings) 設定，就會自動移除，前提是它們沒有未提交的變更、沒有未追蹤的檔案和沒有未推送的提交。您使用 `--worktree` 建立的 Worktrees 永遠不會被此掃描移除。131Claude 為子代理和[背景會話](/docs/zh-TW/agent-view#how-file-edits-are-isolated)建立的 Worktrees 一旦超過您的 [`cleanupPeriodDays`](/docs/zh-TW/settings#available-settings) 設定，就會自動移除，前提是它們沒有未提交的變更、沒有未追蹤的檔案和沒有未推送的提交。您使用 `--worktree` 建立的 Worktrees 永遠不會被此掃描移除。

132 132

133當代理正在執行時，Claude 會在其 worktree 上執行 `git worktree lock`，以便並行清理無法將其移除。當代理完成時，鎖定會被釋放。若要清理掃描保留的 worktree，請執行 `git worktree remove`，如果 worktree 有未提交的變更或未追蹤的檔案，請新增 `--force`。133當代理正在執行時，Claude 會在其 worktree 上執行 `git worktree lock`，以便並行清理無法將其移除。當代理完成時，鎖定會被釋放。若要清理掃描保留的 worktree，請執行 `git worktree remove`，如果 worktree 有未提交的變更或未追蹤的檔案，請新增 `--force`。

134 134

176 非 git 版本控制176 非 git 版本控制

177</h2>177</h2>

178 178

179Worktree 隔離預設使用 git。對於 SVN、Perforce、Mercurial 或其他系統，請配置 [`WorktreeCreate` 和 `WorktreeRemove` hooks](/zh-TW/hooks#worktreecreate) 以提供自訂建立和清理邏輯。因為 hook 取代了預設的 git 行為，當您使用 `--worktree` 時，[`.worktreeinclude`](#copy-gitignored-files-into-worktrees) 不會被處理。改為在您的 hook 指令碼內複製任何本地配置檔案。179Worktree 隔離預設使用 git。對於 SVN、Perforce、Mercurial 或其他系統，請配置 [`WorktreeCreate` 和 `WorktreeRemove` hooks](/docs/zh-TW/hooks#worktreecreate) 以提供自訂建立和清理邏輯。因為 hook 取代了預設的 git 行為，當您使用 `--worktree` 時，[`.worktreeinclude`](#copy-gitignored-files-into-worktrees) 不會被處理。改為在您的 hook 指令碼內複製任何本地配置檔案。

180 180

181此 `WorktreeCreate` hook 從 stdin 讀取 worktree 名稱，檢出新的 SVN 工作副本，並列印目錄路徑，以便 Claude Code 可以將其用作會話的工作目錄：181此 `WorktreeCreate` hook 從 stdin 讀取 worktree 名稱，檢出新的 SVN 工作副本，並列印目錄路徑，以便 Claude Code 可以將其用作會話的工作目錄：

182 182

197}197}

198```198```

199 199

200將其與 `WorktreeRemove` hook 配對以在會話結束時進行清理。有關輸入架構和移除範例，請參閱 [hooks 參考](/zh-TW/hooks#worktreecreate)。200將其與 `WorktreeRemove` hook 配對以在會話結束時進行清理。有關輸入架構和移除範例，請參閱 [hooks 參考](/docs/zh-TW/hooks#worktreecreate)。

201 201

202<h2 id="see-also">202<h2 id="see-also">

203 另請參閱203 另請參閱

205 205

206Worktrees 處理檔案隔離。下面的相關頁面涵蓋將工作委派到這些隔離的檢出中以及在您建立的會話之間切換：206Worktrees 處理檔案隔離。下面的相關頁面涵蓋將工作委派到這些隔離的檢出中以及在您建立的會話之間切換：

207 207

208* [子代理](/zh-TW/sub-agents)：在會話內將工作委派給隔離的代理208* [子代理](/docs/zh-TW/sub-agents)：在會話內將工作委派給隔離的代理

209* [代理團隊](/zh-TW/agent-teams)：自動協調多個 Claude 會話209* [代理團隊](/docs/zh-TW/agent-teams)：自動協調多個 Claude 會話

210* [管理會話](/zh-TW/sessions)：命名、恢復和在對話之間切換210* [管理會話](/docs/zh-TW/sessions)：命名、恢復和在對話之間切換

211* [桌面平行會話](/zh-TW/desktop#work-in-parallel-with-sessions)：桌面應用程式中由 worktree 支援的會話211* [桌面平行會話](/docs/zh-TW/desktop#work-in-parallel-with-sessions)：桌面應用程式中由 worktree 支援的會話

Documentation 2026-08-03 20:02 UTC to 2026-08-04 22:59 UTC