Documentation — Spybara

agent-sdk/secure-deployment.md +2 −2

Details

117 --network none \117 --network none \

118 --memory 2g \118 --memory 2g \

119 --cpus 2 \119 --cpus 2 \

120 --pids-limit 100 \120 --pids-limit 600 \

121 --user 1000:1000 \121 --user 1000:1000 \

122 -v /path/to/code:/workspace:ro \122 -v /path/to/code:/workspace:ro \

123 -v /var/run/proxy.sock:/var/run/proxy.sock:ro \123 -v /var/run/proxy.sock:/var/run/proxy.sock:ro \

agent-sdk/typescript.md +36 −3

Details

106 106

107只有在未設定 `initializeTimeoutMs` 時，執行緩慢的 [SessionStart](https://code.claude.com/docs/zh-TW/hooks.md#sessionstart) 和 [Setup](https://code.claude.com/docs/zh-TW/hooks.md#setup) [命令 hook](https://code.claude.com/docs/zh-TW/hooks.md#command-hook-fields) 才會獲得額外時間：

108

109* **若您未設定：** 這些 hook 執行所花費的時間不會計入 60 秒的預設值，總計最多 10 分鐘，因此初始化最多可能需要 11 分鐘。

110* **若您設定了值（包括 `60000`）：** 該值即為上限，即使 hook 正在執行中也一樣。

111

112額外時間需要 TypeScript Agent SDK v0.3.304 或更新版本。

113

107#### 傳回值114#### 傳回值

108 115

109傳回一個 `Promise<`[`WarmQuery`](#warmquery)`>`，在子程序啟動並完成初始化交握後解析。116傳回一個 `Promise<`[`WarmQuery`](#warmquery)`>`，在子程序啟動並完成初始化交握後解析。

128 135

129### `prewarm()`136### `prewarm()`

130 137

131*Alpha。* 在您知道要服務哪個工作階段之前，先啟動一個 Claude Code 程序作為備用，以便稍後透過 [`claim()`](#spareprocess) 將其繫結到某個工作階段。適用於在使用者選擇資料夾之前就已啟動的應用程式。需要 TypeScript Agent SDK v0.3.282 或更新版本。138*Alpha。* 在您知道要服務哪個工作階段之前，先啟動一個 Claude Code 程序作為備用，以便稍後透過 [`claim()`](#spareprocess) 將其繫結到某個工作階段。需要 TypeScript Agent SDK v0.3.282 或更新版本。

132 139

133`prewarm()` 會完成與 [`startup()`](#startup) 相同的初始化交握；若您設定了 `options.cwd`，程序會在該目錄中等待，否則會在您 Claude Code 設定目錄下的私有暫存目錄中等待。工作階段的工作目錄、其 `SessionStart` hook、其 stdio MCP 伺服器，以及其 CLAUDE.md 和 git 上下文，都會等到認領時才處理。備用程序在等待期間約佔用 230 到 260 MB 的記憶體。如果您的 [`spawnClaudeCodeProcess`](#options) 在另一台機器或容器中執行 Claude Code，請將 `options.cwd` 設定為該處存在的目錄，讓備用程序在其中等待。140當您的應用程式在使用者選擇資料夾之前就已啟動時，請使用 `prewarm()`。

134 141

135```typescript theme={null}142```typescript theme={null}

136function prewarm(params?: {143function prewarm(params?: {

139}): Promise<SpareProcess>;146}): Promise<SpareProcess>;

140```147```

141 148

142`options` 和 `initializeTimeoutMs` 的意義與 `startup()` 相同，但 `options.cwd` 僅設定備用程序等待的目錄。程序完成初始化交握後，promise 會以 [`SpareProcess`](#spareprocess) 解析。如果 `options` 設定了 `resume`、`continue` 或 `forkSession`，`prewarm()` 會擲出例外，因為備用程序尚無工作階段。凡是認領時無法設定的項目，例如 `mcpServers`、`hooks`、`canUseTool`、`settingSources`、`systemPrompt` 和 `plugins`，在備用程序的整個生命週期中都是固定的，因此請為每組不同的這類選項各保留一個備用程序，並在它們變更時重新預熱。149#### 參數

150

151| 參數 | 型別 | 說明 |

152| :- | :- | :- |

153| `options` | [`Options`](#options) | 選用的設定物件，與 `startup()` 所接受的型別相同 |

154| `initializeTimeoutMs` | `number` | 等待備用程序初始化的最長時間（毫秒）。預設為 `60000`。如果初始化未在時限內完成，promise 會以逾時錯誤拒絕 |

155

156`prewarm()` 會將 [Setup](https://code.claude.com/docs/zh-TW/hooks.md#setup) hook 所花費的時間計入 `initializeTimeoutMs`，即使您未設定它也一樣。若要給予執行緩慢的 Setup hook 更多時間，請設定較長的值。

157

158#### 傳回值

159

160傳回一個 `Promise<`[`SpareProcess`](#spareprocess)`>`，在備用程序可供認領時解析。

161

162如果您在 `options` 中要求 `resume`、`continue` 或 `forkSession`，promise 會被拒絕，因為備用程序尚無工作階段。

163

164#### 備用程序的運作方式

165

166* **備用程序在何處等待：** 在您 Claude Code 設定目錄下的私有暫存目錄中；若您在 `prewarm()` 中設定了 `options.cwd`，則在該目錄中。

167* **如果您的 [`spawnClaudeCodeProcess`](#options) 在另一台機器或容器中執行 Claude Code：** 請傳給 `prewarm()` 一個在該處存在的 `options.cwd`，因為預設的暫存目錄是在您的機器上建立的。

168* **記憶體：** 每個備用程序在等待期間約使用 230 到 260 MB。

169* **在您呼叫 `claim()` 之前不會發生的事：**

170 * 切換至您傳給 `claim()` 的工作目錄

171 * 執行 SessionStart hook

172 * 啟動 stdio MCP 伺服器

173 * 載入 CLAUDE.md 和 git 上下文

174* **認領無法變更的項目：** `mcpServers`、`hooks`、`canUseTool`、`settingSources` 和 `plugins` 等選項會保留其在 `prewarm()` 中的值。[`SpareProcess`](#spareprocess) 列出了認領時可設定的項目。

175* **如果各工作階段需要這些選項的不同值：** 請為每組值各保留一個備用程序。

143 176

144#### 範例177#### 範例

145 178

agent-view.md +5 −3

Details

8 8

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

10 10

11![終端中的 Agent view。頂部的一行計算等待輸入、執行中和已完成的工作階段。四個工作階段分組在「需要輸入」、「執行中」和「已完成」下。每一行顯示工作階段的名稱、其最新狀態或問題，以及一個時間。底部是用於描述新任務的輸入和一行快捷鍵提示。](https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-light.png?fit=max\&auto=format\&n=HDAmBwgbrZVk0pOt\&q=85\&s=d6905012bee31f3e6b3920b09c05dd02)11![終端中的 Agent view。頂部的一行計算等待輸入、執行中和已完成的工作階段。四個工作階段分組在「需要輸入」、「執行中」和「已完成」下。每一行顯示工作階段的名稱、其最新狀態或問題，以及一個時間。底部是用於描述新任務的輸入和一行快捷鍵提示。](https://mintcdn.com/claude-code/v_J840yKc6uuKDX_/images/agent-view-light.png?fit=max\&auto=format\&n=v_J840yKc6uuKDX_\&q=85\&s=bd95fda83ea66ca8b2e0e7b68f8cb29e)

12 12

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

14 14

628 628

629* Agent view 會移除它，包括未提交的變更，因此請先提交您想保留的內容。629* Agent view 會移除它，包括未提交的變更，因此請先提交您想保留的內容。

630* `claude rm` 在它有未提交的變更時會保留它，連同工作階段列一起保留。630* `claude rm` 在它有未提交的變更時會保留它，連同工作階段列一起保留。

631* 當另一個執行中的工作階段正在使用或已鎖定某個 worktree 時，agent view 和 `claude rm` 都不會移除它，再次刪除也不會改變這一點。Claude Code 會保留 worktree 和工作階段，並指出保留的目錄及原因；在 agent view 中，工作階段的列會顯示 `not deleted`。請關閉另一個工作階段，然後再次刪除。631* 當另一個執行中的工作階段正在使用或已鎖定某個 worktree 時，agent view 和 `claude rm` 都不會移除它，再次刪除也不會改變這一點。Claude Code 會保留 worktree 和工作階段，並指出保留的目錄及原因；在 agent view 中，工作階段的列會顯示 `not removed`。請關閉另一個工作階段，然後再次刪除。

632* 當您刪除的工作階段，其 worktree 有 Claude Code 無法確認已保存在其他地方的提交時，Claude Code 會保留 worktree 和工作階段，且訊息會指出 worktree 的分支以及有多少提交尚未推送。訊息也會提供兩種後續做法：推送提交，或再次刪除以捨棄它們。632* 當您刪除的工作階段，其 worktree 有 Claude Code 無法確認已保存在其他地方的提交時，Claude Code 會保留 worktree 和工作階段，且訊息會指出 worktree 的分支以及有多少提交尚未推送。訊息也會提供兩種後續做法：推送提交，或再次刪除以捨棄它們。

633 633

634 遠端上的提交不會阻擋刪除。位於您 `origin` 遠端預設分支之本機副本上的提交也不會，前提是該分支已在您的主簽出中簽出，也就是儲存庫目錄本身，而不是 worktree。634 遠端上的提交不會阻擋刪除。位於您 `origin` 遠端預設分支之本機副本上的提交也不會，前提是該分支已在您的主簽出中簽出，也就是儲存庫目錄本身，而不是 worktree。

935關閉或重新啟動您的機器會停止執行中的背景工作階段。等待您輸入的工作階段在您回來時會保留在 `Needs input` 下。對於任何其他執行中的工作階段，agent view 顯示的內容取決於它上次取得進度的時間有多久：935關閉或重新啟動您的機器會停止執行中的背景工作階段。等待您輸入的工作階段在您回來時會保留在 `Needs input` 下。對於任何其他執行中的工作階段，agent view 顯示的內容取決於它上次取得進度的時間有多久：

936 936

937* 在 48 小時內，工作階段顯示為失敗。附加或回覆它，它會從其已儲存的對話重新啟動。若要繼續被中斷的工作，請傳送回覆要求它繼續。937* 在 48 小時內，工作階段顯示為失敗。附加或回覆它，它會從其已儲存的對話重新啟動。若要繼續被中斷的工作，請傳送回覆要求它繼續。

938* 超過 48 小時，例如機器關閉數天後，工作階段顯示為停止，並顯示 `ended while the background service was off`。在該列上按 `Enter`，頁尾會顯示 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to delete it.` 在同一列上再次按 `Enter` 以恢復其已儲存的對話。回覆或 `claude attach <id>` 會在沒有該頁尾提示的情況下恢復它。938* 超過 48 小時，例如機器關閉數天後，工作階段顯示為停止，並顯示 `ended while the background service was off`。

939

940 在該列上按 `Enter`，頁尾會顯示 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` 在同一列上再次按 `Enter` 以恢復其已儲存的對話。回覆或 `claude attach <id>` 會在沒有該頁尾提示的情況下恢復它。

939 941

940當[逐字稿清理](https://code.claude.com/docs/zh-TW/settings-reference.md#cleanupperioddays)已移除停止工作階段的已儲存對話時，Claude Code 會拒絕開啟該列：訊息會說明沒有可恢復的內容。`claude rm <id>` 會刪除該列（上述[保留的情況](#what-deleting-a-session-removes)除外），而 `claude respawn <id>` 會再次執行其原始提示詞。請參閱[此工作階段的已儲存對話已不在磁碟上](https://code.claude.com/docs/zh-TW/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk)。942當[逐字稿清理](https://code.claude.com/docs/zh-TW/settings-reference.md#cleanupperioddays)已移除停止工作階段的已儲存對話時，Claude Code 會拒絕開啟該列：訊息會說明沒有可恢復的內容。`claude rm <id>` 會刪除該列（上述[保留的情況](#what-deleting-a-session-removes)除外），而 `claude respawn <id>` 會再次執行其原始提示詞。請參閱[此工作階段的已儲存對話已不在磁碟上](https://code.claude.com/docs/zh-TW/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk)。

941 943

amazon-bedrock.md +8 −3

Details

349 349

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

351 351

352如果您的帳戶失去對工作階段執行所在模型的存取權，例如因為管理員在您的 Amazon Bedrock 帳戶中停用了它，Claude Code 會將工作階段切換到另一個模型，而不是讓每個請求都失敗，並顯示 `Switched to <fallback> because <model> is not available`。它會嘗試與啟動備援相同的模型：先嘗試同一層級的較早版本，對於沒有可用 Opus 版本的 Opus 工作階段，則嘗試預設的 Sonnet 模型。352當 Amazon Bedrock 以您的帳戶無法使用為由拒絕您工作階段的模型時，Claude Code 會將您的工作階段切換到另一個模型，讓您可以繼續工作。您會看到一則以 `Switched to <fallback> because <model> is not available` 開頭的訊息。例如，當管理員停用該模型，或最新的模型尚未對您的帳戶開放時，就會發生這種情況。

353 353

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

355 355

356您設定的[備援模型鏈](https://code.claude.com/docs/zh-TW/model-config.md#fallback-model-chains)會取代層級切換：在這些拒絕上，Claude Code 會切換到您設定的備援模型。若要讓被拒絕的請求失敗而不是切換，請設定 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/zh-TW/env-vars)。您設定的備援鏈仍會在這些拒絕上切換；如果您希望每個被拒絕的請求都失敗，也請移除該鏈。356* 您的工作階段使用的是釘選的模型、您選擇的特定版本，或[應用程式推論設定檔 ARN](#map-each-model-version-to-an-inference-profile)

357* [Claude Code 嘗試的模型](#startup-model-checks)都無法使用。在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry)中，Claude Code 只會切換到自動模式在 Amazon Bedrock 上支援的模型。

358

359若要繼續工作，請在工作階段中執行 `/model`，並在您的帳戶可使用的模型上按 `s`，這樣不會變更您的預設。`403` 會顯示為 [AWS authentication failed](https://code.claude.com/docs/zh-TW/errors.md#aws-authentication-failed)。

360

361若要讓被拒絕的請求失敗而不是切換，請設定 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/zh-TW/env-vars)。如果您設定了備援模型鏈，也請將其移除，因為 Claude Code 仍會改用該備援模型。

357 362

358## 跨區域推論設定檔前綴363## 跨區域推論設定檔前綴

359 364

auto-mode-config.md +5 −1

Details

222 222

223每個都是散文描述的陣列，讀取為自然語言規則。對於在分類器之前執行的工具模式型硬阻止，請使用 [`permissions.deny`](https://code.claude.com/docs/zh-TW/permissions)。223每個都是散文描述的陣列，讀取為自然語言規則。對於在分類器之前執行的工具模式型硬阻止，請使用 [`permissions.deny`](https://code.claude.com/docs/zh-TW/permissions)。

224 224

225> [!NOTE]

226>

227> 在 [Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md#permission-checks) 工作階段中，分類器會在審查 Claude 的程式碼時套用 `hard_deny` 和 `soft_deny`，而不會套用至該程式碼發出的每個工具呼叫。`permissions.deny` 規則則會套用至每個呼叫。

228

225在分類器內，優先順序分為四個層級：229在分類器內，優先順序分為四個層級：

226 230

227* `hard_deny` 規則無條件阻止。使用者意圖和 `allow` 例外不適用。231* `hard_deny` 規則無條件阻止。使用者意圖和 `allow` 例外不適用。

283 287

284根據預設，narrow Bash 和 PowerShell 允許規則（例如 `Bash(npm test)`）在自動模式中保持有效。Claude Code 會在分類器執行前解析它們，除非命令帶有[每個命令允許的網域](https://code.claude.com/docs/zh-TW/sandboxing.md#per-command-allowed-domains-in-auto-mode)。Claude Code 只會暫停授予任意程式碼執行權限的廣泛規則，例如 `Bash(*)` 或萬用字元解釋器，以及每個命名 [`Monitor`](https://code.claude.com/docs/zh-TW/tools-reference#monitor-tool) 的規則，因為 Monitor 命令會透過 shell 執行。這表示 narrow 規則仍然可能讓破壞性引數通過而不被分類器看到，例如規則前綴未預期的指令碼路徑或旗標。288根據預設，narrow Bash 和 PowerShell 允許規則（例如 `Bash(npm test)`）在自動模式中保持有效。Claude Code 會在分類器執行前解析它們，除非命令帶有[每個命令允許的網域](https://code.claude.com/docs/zh-TW/sandboxing.md#per-command-allowed-domains-in-auto-mode)。Claude Code 只會暫停授予任意程式碼執行權限的廣泛規則，例如 `Bash(*)` 或萬用字元解釋器，以及每個命名 [`Monitor`](https://code.claude.com/docs/zh-TW/tools-reference#monitor-tool) 的規則，因為 Monitor 命令會透過 shell 執行。這表示 narrow 規則仍然可能讓破壞性引數通過而不被分類器看到，例如規則前綴未預期的指令碼路徑或旗標。

285 289

286將 `autoMode.classifyAllShell` 設定為 `true`，以在自動模式啟用時暫停每個 Bash 和 PowerShell 允許規則，讓分類器評估每個 shell 命令，無論您的允許清單為何，除了[關鍵路徑移除](https://code.claude.com/docs/zh-TW/permission-modes.md#critical-paths)。290將 `autoMode.classifyAllShell` 設定為 `true`，以在自動模式啟用時暫停每個 Bash 和 PowerShell 允許規則，讓分類器評估每個 shell 命令，無論您的允許清單為何，除了[關鍵路徑移除](https://code.claude.com/docs/zh-TW/permission-modes.md#critical-paths)。在 [Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md#permission-checks) 工作階段中，即使啟用此設定，分類器仍會審查執行這些命令的程式碼。

287 291

288```json theme={null}292```json theme={null}

289{293{

best-practices.md +1 −1

Details

315 {315 {

316 "matcher": "Edit|Write",316 "matcher": "Edit|Write",

317 "hooks": [317 "hooks": [

318 { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }318 { "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\"" }

319 ]319 ]

320 }320 }

321 ]321 ]

claude-apps-gateway.md +3 −1

Details

74| PostgreSQL 11 或更新版本 | 支援裝置登入流程與速率限制計數器。受管理的 PostgreSQL 服務亦可使用，包括最小的方案；請參閱[支援哪些資料庫](https://code.claude.com/docs/zh-TW/claude-apps-gateway-deploy.md#postgres)。搭配[支出上限](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md)使用時，它也會保存應備份的持久性支出、稽核與身分資料表。建議透過 `?sslmode=require` 使用 TLS。PostgreSQL 11、12 與 13 需要閘道伺服器上的 Claude Code 為 v2.1.290 或更新版本。PostgreSQL 專案已不再維護這些版本，因此請盡可能使用較新的版本。 |74| PostgreSQL 11 或更新版本 | 支援裝置登入流程與速率限制計數器。受管理的 PostgreSQL 服務亦可使用，包括最小的方案；請參閱[支援哪些資料庫](https://code.claude.com/docs/zh-TW/claude-apps-gateway-deploy.md#postgres)。搭配[支出上限](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md)使用時，它也會保存應備份的持久性支出、稽核與身分資料表。建議透過 `?sslmode=require` 使用 TLS。PostgreSQL 11、12 與 13 需要閘道伺服器上的 Claude Code 為 v2.1.290 或更新版本。PostgreSQL 專案已不再維護這些版本，因此請盡可能使用較新的版本。 |

75| 模型上游 | Amazon Bedrock 憑證、Claude Platform on AWS 憑證、Google Cloud 憑證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援具備容錯移轉的多個上游。 |75| 模型上游 | Amazon Bedrock 憑證、Claude Platform on AWS 憑證、Google Cloud 憑證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援具備容錯移轉的多個上游。 |

76| HTTPS | 開發人員的筆記型電腦以及用於登入的任何瀏覽器都必須能透過 `https://` 連線到閘道；閘道會在同一個接聽程式上提供裝置驗證頁面。請透過 `listen.tls` 提供 TLS 憑證，或在終止 TLS 的 ingress 之後執行，兩種情況下都請將 `listen.public_url` 設為外部來源。在 `/login` 時，只有當閘道主機為迴路位址（`localhost`、`127.0.0.1` 或 `::1`）時，Claude Code 才接受純 `http://` 來源。 |76| HTTPS | 開發人員的筆記型電腦以及用於登入的任何瀏覽器都必須能透過 `https://` 連線到閘道；閘道會在同一個接聽程式上提供裝置驗證頁面。請透過 `listen.tls` 提供 TLS 憑證，或在終止 TLS 的 ingress 之後執行，兩種情況下都請將 `listen.public_url` 設為外部來源。在 `/login` 時，只有當閘道主機為迴路位址（`localhost`、`127.0.0.1` 或 `::1`）時，Claude Code 才接受純 `http://` 來源。 |

77| 私人網路位址 | 在 `/login` 時，Claude Code 要求閘道的主機名稱或 IP 位址僅解析為私人位址：RFC 1918、鏈路本機、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或迴路位址。對於您自行託管的閘道，任何不在您所宣告區塊內的公用位址都會遭到拒絕；請參閱部署指南中的[威脅模型](https://code.claude.com/docs/zh-TW/claude-apps-gateway-deploy.md#threat-model-summary)。如果開發人員機器透過公司代理伺服器路由 HTTPS，登入時也要求代理伺服器主機解析為私人位址；若非如此，請將閘道主機加入 `NO_PROXY`，讓 CLI 直接連線。如果您的內部網路使用組織所擁有的公用 IPv4 位址空間進行編號，請[宣告這些區塊](#allow-a-gateway-on-public-address-space-you-own)，讓 `/login` 接受位於該處的閘道。 |77| 私人網路位址 | Claude Code 的 `/login` 要求閘道的主機名稱或 IP 位址僅解析為私人位址：RFC 1918 與鏈路本機範圍、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 以及迴路位址。請參閱[威脅模型](https://code.claude.com/docs/zh-TW/claude-apps-gateway-deploy.md#threat-model-summary)。如果您的內部網路使用組織所擁有的公用 IPv4 位址空間進行編號，請[宣告這些區塊](#allow-a-gateway-on-public-address-space-you-own)，讓 `/login` 接受位於該處的閘道。 |

78| Linux 執行環境 | 閘道伺服器只能在原生 Linux 二進位檔上執行。macOS 可用於本機開發。不支援以 Windows 作為伺服器平台。 |78| Linux 執行環境 | 閘道伺服器只能在原生 Linux 二進位檔上執行。macOS 可用於本機開發。不支援以 Windows 作為伺服器平台。 |

79 79

80當 `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於閘道主機時，登入還需要主機名稱解析為私人位址的代理伺服器，或在開發人員機器上將閘道主機加入 `NO_PROXY`，兩者擇一。如果這些機器也設定了 `no_proxy`，也請將閘道主機加入其中，否則模型請求仍會經過代理伺服器。

80### 步驟82### 步驟

81 83

82**1. 在您的 IdP 中註冊 OAuth 用戶端**84**1. 在您的 IdP 中註冊 OAuth 用戶端**

claude-apps-gateway-config.md +32 −9

Details

14 14

15## 檔案結構15## 檔案結構

16 16

17五個部分是[必需的](#required-sections)。其他所有部分都是[選擇性的](#optional-sections)，省略的部分會採用其預設值。未知的鍵會導致啟動失敗，因此打字錯誤會顯示為具名錯誤，而不是被無聲地忽略的設定。17五個部分是[必需的](#required-sections)。其他所有部分都是[選擇性的](#optional-sections)，省略的部分會採用其預設值。

18 18

19**必需部分：**19**必需部分：**

20 20

517 517

518需要執行 Claude Code v2.1.281 或更新版本的閘道。[AWS 上的成本歸因](https://code.claude.com/docs/zh-TW/claude-apps-gateway-on-aws.md#cost-attribution)涵蓋 IAM 角色以及 AWS 計費顯示工作階段的位置。518需要執行 Claude Code v2.1.281 或更新版本的閘道。[AWS 上的成本歸因](https://code.claude.com/docs/zh-TW/claude-apps-gateway-on-aws.md#cost-attribution)涵蓋 IAM 角色以及 AWS 計費顯示工作階段的位置。

519 519

520> [!NOTE]

521>

522> 若要依開發人員歸屬，請在每個 `bedrock` 與 [`mantle`](#amazon-bedrock-mantle-endpoint) 上游上設定含 `session_name` 的 `assume_role`，使用 `aws_bearer_token` 的上游除外。這些上游[無法使用 `assume_role`](#bedrock-in-another-aws-account)，因此其請求仍歸於單一主體。

523

520```yaml theme={null}524```yaml theme={null}

521upstreams:525upstreams:

522 - provider: bedrock526 - provider: bedrock

533 537

534閘道也在此角色上進行一個自己的呼叫：用戶端放棄的請求的 token 計數，以使[支出限制](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md)保持準確。該計數及其[一個 token 的備援請求](#amazon-bedrock)由共享的 `claude-apps-gateway` 工作階段簽署，因此 AWS 將該備援請求歸因於 `claude-apps-gateway` 而不是開發人員。538閘道也在此角色上進行一個自己的呼叫：用戶端放棄的請求的 token 計數，以使[支出限制](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md)保持準確。該計數及其[一個 token 的備援請求](#amazon-bedrock)由共享的 `claude-apps-gateway` 工作階段簽署，因此 AWS 將該備援請求歸因於 `claude-apps-gateway` 而不是開發人員。

535 539

536對於嚴格的每個開發人員歸因，在您列出的每個 Bedrock 上游上設定 `assume_role` 與 `session_name`。沒有它的上游使用其自己的憑證簽署它服務的請求。

~~537~~

538#### Amazon Bedrock Mantle 端點540#### Amazon Bedrock Mantle 端點

539 541

540`mantle` 提供者將推論傳送到 Amazon Bedrock 的 [Mantle 端點](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#use-the-mantle-endpoint)。它需要閘道伺服器上的 Claude Code v2.1.283 或更新版本。較早的閘道版本會在啟動時拒絕它，因此請在新增之前升級每個副本。542`mantle` 提供者將推論傳送到 Amazon Bedrock 的 [Mantle 端點](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#use-the-mantle-endpoint)。它需要閘道伺服器上的 Claude Code v2.1.283 或更新版本。較早的閘道版本會在啟動時拒絕它，因此請在新增之前升級每個副本。

654 656

655| 設定 | 方式 |657| 設定 | 方式 |

656| - | - |658| - | - |

658| 部署 | Microsoft Foundry 使用管理員選擇的部署名稱，而不是規範模型 ID。新增 [`models:`](#models) 區塊，將每個規範 ID 對應到您的部署名稱。 |660| 部署 | Microsoft Foundry 使用管理員選擇的部署名稱，而不是規範模型 ID。新增 [`models:`](#models) 區塊，將每個規範 ID 對應到您的部署名稱。 |

999 1001

1000`upstream_model` 下的每個金鑰必須符合已設定上游的 `name`，預設為提供者名稱。不符合任何上游的金鑰會導致啟動失敗，因此省略您不使用的提供者的列。1002`upstream_model` 下的每個金鑰必須符合已設定上游的 `name`，預設為提供者名稱。不符合任何上游的金鑰會導致啟動失敗，因此省略您不使用的提供者的列。

1001 1003

1004若要讓開發人員在 `auto_include_builtin_models: false` 時使用 `fable` 別名，請在 `models` 中加入 `claude-fable-5` 項目。對於登入閘道的開發人員，這就是 [`fable` 別名](https://code.claude.com/docs/zh-TW/model-config#fable-alias-resolution)解析成的 ID。若沒有此項目，他們的訊息會失敗，並出現以 `API Error: 400 model claude-fable-5 is not in the operator's model allowlist` 開頭的錯誤。

1005

1002### `managed`1006### `managed`

1003 1007

1004`managed` 區塊定義以 IdP 群組或電子郵件網域為鍵的角色型存取政策。政策會依序評估；預設會選取第一個符合的政策，然後合併到 `match: {}` 全包式基礎上。符合兩項角色政策的使用者只會取得第一項，因此除非您 [套用每一項符合的政策](#apply-every-matching-policy)，否則第二項政策的拒絕規則不會生效。政策會依使用者在 `GET /managed/settings` 提供，並使用 ETag/304 快取。1008`managed` 區塊定義以 IdP 群組或電子郵件網域為鍵的角色型存取政策。政策會依序評估；預設會選取第一個符合的政策，然後合併到 `match: {}` 全包式基礎上。符合兩項角色政策的使用者只會取得第一項，因此除非您 [套用每一項符合的政策](#apply-every-matching-policy)，否則第二項政策的拒絕規則不會生效。政策會依使用者在 `GET /managed/settings` 提供，並使用 ETag/304 快取。

1023`match: {}` 全部捕捉（按慣例列在最後）被視為基礎層。每個其他原則從全部捕捉繼承它未設定的任何金鑰，因此每個角色項目只需列出與組織預設不同的內容。合併規則取決於金鑰類型：1027`match: {}` 全部捕捉（按慣例列在最後）被視為基礎層。每個其他原則從全部捕捉繼承它未設定的任何金鑰，因此每個角色項目只需列出與組織預設不同的內容。合併規則取決於金鑰類型：

1024 1028

1025* **允許清單**：`availableModels` 和 `permissions.allow`。特定原則的清單完全替換基礎的。1029* **允許清單**：`availableModels` 和 `permissions.allow`。特定原則的清單完全替換基礎的。

1026* **拒絕清單與 hook 陣列**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces`、`deniedModels`，以及每個 `hooks` 事件類型陣列。這些會取基礎與政策的聯集，因此全組織的拒絕規則或稽核 hook 不會因各角色的覆寫而被意外移除。1030* **拒絕清單與 hook 陣列**：這些會取基礎層與政策的聯集：

1031 * `permissions.deny` 與 `permissions.ask`

1032 * `disabledMcpjsonServers` 與 `deniedMcpServers`

1033 * `blockedMarketplaces` 與 `deniedModels`

1034 * `hooks` 事件類型陣列

1027* **記錄類型金鑰**：`env`、`modelOverrides` 和 `skillOverrides`。這些淺合併，因此每個角色 `env` 區塊覆寫它設定的金鑰並從基礎繼承其餘的。1035* **記錄類型金鑰**：`env`、`modelOverrides` 和 `skillOverrides`。這些淺合併，因此每個角色 `env` 區塊覆寫它設定的金鑰並從基礎繼承其餘的。

1028 1036

1029`availableModels` 也在 `/v1/messages` 伺服器端強制執行，因此被拒絕的模型返回 `400`，無論用戶端傳送什麼。空清單會拒絕每個模型。此檢查也涵蓋開發者選擇模型之前工作階段啟動時所使用的模型，因此請[讓工作階段從原則允許的模型啟動](#start-sessions-on-a-model-the-policy-allows)。1037`availableModels` 也在 `/v1/messages` 伺服器端強制執行，因此被拒絕的模型返回 `400`，無論用戶端傳送什麼。空清單會拒絕每個模型。此檢查也涵蓋開發者選擇模型之前工作階段啟動時所使用的模型，因此請[讓工作階段從原則允許的模型啟動](#start-sessions-on-a-model-the-policy-allows)。

1275 1283

1276若要改為關閉 1M 上下文，請在相同的 `env` 區塊中設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"`](https://code.claude.com/docs/zh-TW/model-config#extended-context)。Claude Code 隨後會將每個模型視為具有 200K 視窗。在互動式工作階段中，每位開發者會在[核准對話框](#what-goes-in-cli)中核准此變數，之後才會生效。1284若要改為關閉 1M 上下文，請在相同的 `env` 區塊中設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"`](https://code.claude.com/docs/zh-TW/model-config#extended-context)。Claude Code 隨後會將每個模型視為具有 200K 視窗。在互動式工作階段中，每位開發者會在[核准對話框](#what-goes-in-cli)中核准此變數，之後才會生效。

1277 1285

1286> [!NOTE]

1287>

1288> Claude Code 不會讀取別名的 `upstream_model` 來決定其上下文視窗大小。若要讓 `models` 中 Claude Code 無法識別的別名使用其模型的視窗，請參閱[修正閘道或自訂模型 ID 的視窗](https://code.claude.com/docs/zh-TW/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id)。

1289

1278#### 一小時提示快取1290#### 一小時提示快取

1279 1291

1280若要請求一小時的[提示快取 TTL](https://code.claude.com/docs/zh-TW/prompt-caching.md#cache-lifetime)，而非預設的五分鐘，請將下列鍵新增到原則現有的 [`code`、`cli` 或 `settings` 區塊](#choose-cli-or-code)，然後重新啟動閘道。這些鍵需要閘道伺服器與用戶端上皆為 Claude Code v2.1.242 或更新版本。1292若要請求一小時的[提示快取 TTL](https://code.claude.com/docs/zh-TW/prompt-caching.md#cache-lifetime)，而非預設的五分鐘，請將下列鍵新增到原則現有的 [`code`、`cli` 或 `settings` 區塊](#choose-cli-or-code)，然後重新啟動閘道。這些鍵需要閘道伺服器與用戶端上皆為 Claude Code v2.1.242 或更新版本。

1377 1389

1378##### gateway 在啟動時拒絕的內容1390##### gateway 在啟動時拒絕的內容

1379 1391

1380gateway 在啟動時根據 Claude Desktop 本身使用的設定 schema 驗證每個 `desktop` 區塊，因此錯誤會在 gateway 啟動時顯示為命名金鑰的錯誤，而不是到達每個連接的桌面。當區塊包含以下內容時，gateway 在啟動時失敗：1392當 `desktop` 區塊包含以下內容時，閘道會在啟動時失敗：

1381 1393

1382* 未知金鑰1394* 已辨識的鍵，但其值會被 Claude Desktop 拒絕或無聲捨棄，例如空白值。

1383* 已識別的金鑰，其值 Claude Desktop 會拒絕或無聲丟棄，例如空值或巢狀項目內的拼寫錯誤的子金鑰。在 v2.1.260 之前，gateway 無聲丟棄 `managedMcpServers` 或 `orgPluginSettings` 項目的巢狀物件內的拼寫錯誤欄位，而不是在啟動時失敗。

1384* gateway 自己計算的金鑰：推論連接、模型清單和 OTLP 轉發。透過 [`upstreams`](#upstreams)、[`models`](#models) 和 [`telemetry`](#telemetry) 區塊的 `forward_to` 設定這些。1395* gateway 自己計算的金鑰：推論連接、模型清單和 OTLP 轉發。透過 [`upstreams`](#upstreams)、[`models`](#models) 和 [`telemetry`](#telemetry) 區塊的 `forward_to` 設定這些。

1385* 目前金鑰的舊版別名。在啟動錯誤中，gateway 命名規範金鑰以寫入。1396* 目前金鑰的舊版別名。在啟動錯誤中，gateway 命名規範金鑰以寫入。

1397* 自 v2.1.300 起，名稱以 `selfHosted` 開頭的任何鍵，例如自我託管工作階段主機的鍵。請在將閘道升級到 v2.1.300 或更新版本之前移除這些鍵。

1386 1398

1387如果您使用已棄用的值或項目形狀，例如沒有 `transport` 的 `managedMcpServers` 項目，gateway 啟動並記錄命名替換的警告。1399如果您使用已棄用的值或項目形狀，例如沒有 `transport` 的 `managedMcpServers` 項目，gateway 啟動並記錄命名替換的警告。

1388 1400

1389在 v2.1.232 之前，gateway 接受固定的 11 個功能閘道金鑰清單，例如 `chatTabEnabled` 和 `disableAutoUpdates`，並在啟動時拒絕每個其他金鑰。在 v2.1.227 之前，gateway 也在啟動時拒絕 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。1401在 v2.1.232 之前，gateway 接受固定的 11 個功能閘道金鑰清單，例如 `chatTabEnabled` 和 `disableAutoUpdates`，並在啟動時拒絕每個其他金鑰。在 v2.1.227 之前，gateway 也在啟動時拒絕 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。

1390 1402

1403##### 閘道不認得的鍵

1404

1405在執行 Claude Code v2.1.295 或更新版本的閘道上，來自較新 Claude Desktop 版本的大多數鍵不需要升級閘道。在 v2.1.321 或更新版本上，已知鍵內的大多數新子鍵也不需要。

1406

1407某些鍵和值仍會在啟動時失敗，例如以下這些：

1408

1409* 已知鍵的固定值清單中的新選項。

1410* 您可以在 `desktop` 區塊中設定之鍵的疑似拼寫錯誤，例如將 `disableAutoUpdates` 寫成 `disable_auto_updates`。錯誤會建議一個名稱。

1411

1412在每種情況下，如果該名稱或值在較新的 Claude Desktop 版本中確實存在，請將閘道[升級](https://code.claude.com/docs/zh-TW/claude-apps-gateway-deploy.md#upgrades)到最新版本。否則請更正或移除它。若要在部署前發現問題，請[測試原則](#test-a-policy-before-deployment)。

1413

1391##### 需要較新 gateway 或 Claude Desktop 版本的金鑰1414##### 需要較新 gateway 或 Claude Desktop 版本的金鑰

1392 1415

1393gateway 根據與其安裝版本捆綁的 schema 驗證 `desktop` 區塊，如同 `cli` 區塊。要傳遞較新 Claude Desktop 版本引入的設定，請先升級 gateway。例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要 gateway 伺服器上的 Claude Code v2.1.260 或更新版本以及成員機器上的 Claude Desktop 1.37937.0 或更新版本。1416`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要閘道伺服器上執行 Claude Code v2.1.260 或更新版本，且成員電腦上執行 Claude Desktop 1.37937.0 或更新版本。

1394 1417

1395`blockReadsOutsideWorkingDirectories`、`disableBypassPermissionsMode`、`configRecheckIntervalMinutes` 和 `sshClientPath` 需要 gateway 伺服器上的 Claude Code v2.1.281 或更新版本。Microsoft 365 `managedMcpServers` 項目的 `microsoftAuthBroker` 的 `required` 值和 `continuousAccessEvaluation` 欄位也是如此。早於 `required` 值的 Claude Desktop 版本將其讀取為 `disabled`，因此只在每個成員的 Claude Desktop 支援它之後設定 `required`。Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)列出首次讀取每個金鑰的版本。1418`blockReadsOutsideWorkingDirectories`、`disableBypassPermissionsMode`、`configRecheckIntervalMinutes` 和 `sshClientPath` 需要 gateway 伺服器上的 Claude Code v2.1.281 或更新版本。Microsoft 365 `managedMcpServers` 項目的 `microsoftAuthBroker` 的 `required` 值和 `continuousAccessEvaluation` 欄位也是如此。早於 `required` 值的 Claude Desktop 版本將其讀取為 `disabled`，因此只在每個成員的 Claude Desktop 支援它之後設定 `required`。Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)列出首次讀取每個金鑰的版本。

1396 1419

claude-apps-gateway-deploy.md +1 −1

Details

92 92

93除了二進位檔案，映像還需要：93除了二進位檔案，映像還需要：

94 94

95* **基於 glibc 的映像**：glibc 建置的唯一動態依賴項是 glibc 庫。基於 Musl 的映像需要 `linux-x64-musl` 或 `linux-arm64-musl` 建置加上額外套件；請參閱 [Alpine Linux 設定](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)。95* **基於 glibc 的映像**：glibc 建置的唯一動態相依性是 glibc 函式庫。基於 Musl 的映像需要 `linux-x64-musl` 或 `linux-arm64-musl` 建置，其唯一的動態相依性是 musl。

96* **可寫入的狀態目錄**：閘道以任何使用者身份執行，但最小映像沒有可寫入的主目錄。將 `CLAUDE_CONFIG_DIR` 設定為可寫入的路徑，例如 `/tmp/.claude`。96* **可寫入的狀態目錄**：閘道以任何使用者身份執行，但最小映像沒有可寫入的主目錄。將 `CLAUDE_CONFIG_DIR` 設定為可寫入的路徑，例如 `/tmp/.claude`。

97* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，設定檔案以唯讀方式掛載，祕密作為環境變數提供；閘道在 `listen.port` 上監聽，預設為 `8080`。97* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，設定檔案以唯讀方式掛載，祕密作為環境變數提供；閘道在 `listen.port` 上監聽，預設為 `8080`。

98 98

claude-code-on-the-web.md +2 −2

Details

189 189

190```190```

191Sent to cloud session.191Sent to cloud session.

192Session ID: session_01DiUkqY2kzbUbDmW1w96rfi192Session ID: session_01HJKLMNOPQRSTUVWXYZ

193View: https://claude.ai/code/session_01DiUkqY2kzbUbDmW1w96rfi?from=cli&m=0193View: https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ?from=cli&m=0

194```194```

195 195

196傳遞 `--output-format json` 以取得機器可讀的結果：成功時為 `{ok, session_id, url}`，或當傳送失敗時為 `{ok: false, session_id, error}`，例如當工作階段遺失或已封存時。設定錯誤（例如不支援的提供者或已停用的組織原則）會列印到 stderr，不含 JSON。`--output-format stream-json` 不支援 `--cloud <session-id>`。196傳遞 `--output-format json` 以取得機器可讀的結果：成功時為 `{ok, session_id, url}`，或當傳送失敗時為 `{ok: false, session_id, error}`，例如當工作階段遺失或已封存時。設定錯誤（例如不支援的提供者或已停用的組織原則）會列印到 stderr，不含 JSON。`--output-format stream-json` 不支援 `--cloud <session-id>`。

claude-projects.md +2 −0

Details

274 274

275執行緒在 [auto mode](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 中執行，因此 Claude 在該資料夾中執行命令和編輯檔案而不每次都詢問您。如果 auto mode 在該電腦的 Claude Code 中不可用或關閉，執行緒執行而不使用它，並且它引發的任何權限提示等待您在執行緒中的回答，如 [解除等待批准的執行緒](#unblock-a-thread-waiting-on-approval) 所述。275執行緒在 [auto mode](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 中執行，因此 Claude 在該資料夾中執行命令和編輯檔案而不每次都詢問您。如果 auto mode 在該電腦的 Claude Code 中不可用或關閉，執行緒執行而不使用它，並且它引發的任何權限提示等待您在執行緒中的回答，如 [解除等待批准的執行緒](#unblock-a-thread-waiting-on-approval) 所述。

276 276

277若要以其他模式執行執行緒，請使用 [`--settings`](https://code.claude.com/docs/zh-TW/remote-control#start-a-remote-control-session) 啟動 `claude remote-control`。然後，該檔案中或該電腦設定中的 [`permissions.defaultMode`](https://code.claude.com/docs/zh-TW/permission-modes#start-in-a-different-mode) 可以選擇其他模式。

278

277當執行緒執行時，其標題中的筆記型電腦圖示顯示您的電腦是否已連接。點擊它以查看執行緒使用的資料夾或關閉連接。當該電腦睡眠時執行緒暫停，如果桌面應用程式或 `claude remote-control` 退出則停止。279當執行緒執行時，其標題中的筆記型電腦圖示顯示您的電腦是否已連接。點擊它以查看執行緒使用的資料夾或關閉連接。當該電腦睡眠時執行緒暫停，如果桌面應用程式或 `claude remote-control` 退出則停止。

278 280

279* **要讓執行緒再次執行**：請參閱 [失去與您資料夾的聯繫](#lost-contact-with-your-folder)281* **要讓執行緒再次執行**：請參閱 [失去與您資料夾的聯繫](#lost-contact-with-your-folder)

code-mode.md +224 −0 created

Details

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# 使用 Code Mode 從程式碼執行工具呼叫

7> 試用 Code Mode，這是一項實驗性功能，Claude 會在其中撰寫 JavaScript，在一個步驟中進行多個工具呼叫。

9Code Mode 會改變 Claude 使用其[工具](https://code.claude.com/docs/zh-TW/tools-reference.md)的方式。未啟用 Code Mode 時，Claude 會直接請求 Bash、Read 或 Edit 等工具呼叫，並在決定下一步之前讀取每個結果。啟用 Code Mode 後，Claude 會撰寫一段進行工具呼叫的 JavaScript，並由 Claude Code 在您的工作階段中執行該程式碼。

11> [!NOTE]

12>

13> Code Mode 為實驗性功能，預設為關閉。它可能會在任何版本中變更或移除。如需分享意見回饋，請執行 `/feedback`。

15## Code Mode 的運作方式

17在 Code Mode 工作階段中，您仍然在提示詞中描述您的任務，而 Claude 會撰寫 JavaScript 來執行它。一段程式碼可以平行執行命令、在下一次呼叫中使用某個結果，並傳回 Claude 需要讀取的那部分輸出。

19例如，如果您請 Claude 提高重試上限，Claude 可能會撰寫以下程式碼來尋找檔案、編輯檔案並執行測試。最後一行會將檔案路徑和測試輸出傳回給 Claude：

21```javascript theme={null}

22const files = await $`rg -l "function retryPolicy" src`.text();

23const target = files.trim().split("\n")[0];

24await edit(target, "maxAttempts: 3", "maxAttempts: 5");

25({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });

26```

28在對話中，您會看到工具呼叫（例如編輯的差異），而不是程式碼。若要讀取程式碼，請按 `Ctrl+O` 開啟[逐字稿檢視器](https://code.claude.com/docs/zh-TW/interactive-mode.md#transcript-viewer)。每段程式碼都會在其中顯示為收合的 **Code** 列，並附有如何展開的提示。

30### 何時使用 Code Mode

32請在需要許多相關工具呼叫的任務上試用 Code Mode，例如：

34* 在許多檔案中重複進行的變更

35* 在 Claude 讀取結果之前需要先篩選結果的搜尋

36* 可以同時執行的數個獨立命令

38### Code Mode 的限制

40在開啟 Code Mode 之前，請確認您可以接受以下限制：

42* **繼續工作階段**：您只能在終端機中、且在 Code Mode 開啟的情況下繼續 Code Mode 工作階段

43* **自動模式**：自動模式的分類器會[審查程式碼，而非每個工具呼叫](#permission-checks)

44* **長時間執行的程式碼**：除非[程式碼可以在背景執行](#long-running-code)，否則您需要等待它完成，且它會在十分鐘後停止

45* **Hook**：當 `PreToolUse` hook 無法執行或逾時時，您可能會看到[工具呼叫被拒絕](#tool-call-refused-by-a-hook)，也可能會看到[程式碼輸出被 `UserPromptSubmit` hook 阻擋](#code-output-withheld-by-a-hook)

46* **無法使用的功能**：您無法使用 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md)、[Claude in Chrome](https://code.claude.com/docs/zh-TW/chrome.md) 或[電腦操作](https://code.claude.com/docs/zh-TW/computer-use.md)

47* **移動工作階段**：您無法將工作階段移至 Desktop 應用程式或將其轉為[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)，且 `/fork` 無法啟動背景副本

49## 需求

51* **版本**：Claude Code v2.1.323 或更新版本，任一[發布通道](https://code.claude.com/docs/zh-TW/setup.md#configure-release-channel)皆可。較舊的版本啟動時不會啟用 Code Mode，可能會也可能不會顯示原因 `it isn't open to your account yet`

52* **帳戶**：Claude 訂閱或 Console 帳戶。您無法透過閘道、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 使用 Code Mode

53* **組織**：您的組織未使用 [HIPAA 設定](https://code.claude.com/docs/zh-TW/hipaa-setup.md)，也未使用[零資料保留](https://code.claude.com/docs/zh-TW/zero-data-retention.md)

54* **模型**：Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2

55* **使用介面**：在終端機中的互動式 `claude` 工作階段。Code Mode 無法搭配 `-p`、Agent SDK、VS Code 面板、Desktop 應用程式或雲端工作階段使用

56* **安裝**：Claude Code 的[原生建置](https://code.claude.com/docs/zh-TW/setup.md)

57* **Windows**：已安裝 [Git for Windows](https://git-scm.com/downloads/win)

59在開啟某些設定的情況下，您也無法啟動 Code Mode，例如 API 金鑰輔助程式、agent team、OpenTelemetry 匯出或 `DISABLE_TELEMETRY`。各項的修正方式請參閱 [Code Mode 無法啟動](#code-mode-doesnt-start)。

61## 試用 Code Mode

63開啟 Code Mode，交給 Claude 一項任務，然後查看 Claude 撰寫的程式碼。

65**1. 檢查您的版本**

67執行 `claude --version`。如果版本早於 v2.1.323，請執行 `claude update`。如果您使用的是 `stable` 通道，且更新後未達到 v2.1.323，請等待 `stable` 跟上，或[切換至 `latest`](https://code.claude.com/docs/zh-TW/setup#configure-release-channel)。

69**2. 在開啟 Code Mode 的情況下啟動 Claude Code**

71將 [`CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`](https://code.claude.com/docs/zh-TW/env-vars#variables) 環境變數設為 `1`。若要試用 Code Mode，請在您的 shell 中設定。若要為每個新的工作階段開啟 Code Mode，請在您的使用者設定中設定。

73> [tab] macOS, Linux, WSL

74>

75> ```bash theme={null}

76> CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

77> ```

79> [tab] Windows PowerShell

80>

81> ```powershell theme={null}

82> $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"

83> claude

84> ```

86> [tab] settings.json

87>

88> 將此 `env` 區塊儲存在 `~/.claude/settings.json` 中，然後啟動 `claude`：

89>

90> ```json theme={null}

91> {

92> "env": {

93> "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"

94> }

95> }

96> ```

97>

98> Claude Code [會忽略專案設定檔中的此變數](https://code.claude.com/docs/zh-TW/settings-reference.md#variables-claude-code-ignores-in-env)，因此您複製的儲存庫無法替您開啟 Code Mode。

100**3. 確認您要使用 Code Mode**

101

102在您的第一個 Code Mode 工作階段之前，Claude Code 會請您確認。請選取 **Yes, turn on Code Mode**。Claude Code 會重新啟動，並在工作階段頂端附近顯示這一行：

103

104```text theme={null}

105Code Mode (experimental) is on · this session can be resumed only with Code Mode on

106```

107

108如果您看到不同的一行或沒有看到任何一行，請參閱 [Code Mode 無法啟動](#code-mode-doesnt-start)。

109

110**4. 交給 Claude 一項需要許多工具呼叫的任務**

111

112在您熟悉的專案中，傳送如下的提示詞：

113

114```text theme={null}

115Read every Markdown file in this project and list the links that point to local files that don't exist.

116```

117

118**5. 閱讀 Claude 撰寫的程式碼**

119

120按 `Ctrl+O` 並展開 **Code** 列，即可查看工具呼叫背後的 JavaScript。再按一次 `Ctrl+O` 即可返回對話。

121

122> [!WARNING]

123>

124> 若要在之後繼續 Code Mode 工作階段，請在執行 `claude --continue` 或 `claude --resume` 時，讓 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE` 維持設為 `1`。在 Code Mode 關閉的情況下，Claude Code 會拒絕繼續該工作階段。您在未啟用 Code Mode 時啟動的工作階段，即使設定了該變數，也會在未啟用 Code Mode 的情況下繼續。

125

126### 關閉 Code Mode

127

128從您的 shell 和 `~/.claude/settings.json` 中移除 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`，然後啟動新的工作階段。您也可以保留該變數，並在任一處將其值改為 `0`。只要其中一處為 `0`，即使您在另一處設定了 `1`，Code Mode 仍會保持關閉。

129

130### 為您的組織封鎖 Code Mode

131

132將值為 `0` 的 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE` 加入您的[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)，讓您組織中的任何人都無法使用 Code Mode：

133

134```json theme={null}

135{

136 "env": {

137 "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"

138 }

139}

140```

141

142正處於 Code Mode 工作階段中的使用者會留在其中，直到他們結束或重新啟動 Claude Code。之後，您的使用者在啟動時不會啟用 Code Mode，且在 `0` 生效期間無法繼續他們的 Code Mode 工作階段。您無法從受管設定為您的使用者開啟 Code Mode。

143

144## 權限與長時間執行的程式碼

145

146您的權限模式決定了 Claude 的程式碼如何接受檢查，以及在程式碼執行期間您是否能與 Claude 交談。

147

148### 權限檢查

149

150Claude 的程式碼所進行的每個工具呼叫，都會經過您的 `deny` 和 `ask` [權限規則](https://code.claude.com/docs/zh-TW/permissions.md)以及您的 [`PreToolUse` hook](https://code.claude.com/docs/zh-TW/hooks#pretooluse)。您不需要為 `Bash` 等工具變更規則或 matcher。除了規則和 hook 之外，在自動模式下會由分類器審查程式碼，而在會詢問的模式下則由您回應權限提示：

151

152* **[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)**：分類器會在每段程式碼執行前審查該段程式碼，而不是審查每個工具呼叫。它看不到在執行時計算出的值，例如取自搜尋輸出的路徑，因此對於您必須控管的呼叫，請保留規則或 hook。[在先前的程式碼執行期間有新的程式碼啟動時](#permission-prompt-with-a-countdown)，您仍可能收到權限提示

153* **其他[權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)**：程式碼會在未經審查的情況下啟動，而對於在該模式下會提示您的每個工具呼叫，您都會收到權限提示

154

155若要檢查程式碼本身，請撰寫一個比對 `REPL`（執行 Claude 程式碼的工具）的 `PreToolUse` hook，並從 `tool_input.code` 讀取 JavaScript。

156

157> [!WARNING]

158>

159> Bash 規則比對的是命令文字，因此無論是否啟用 Code Mode，Claude 都可能以[規則無法比對到的形式](https://code.claude.com/docs/zh-TW/permissions.md#bash-rule-limits)執行被拒絕的命令。如需不依賴命令文字的限制，請參閱[沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md)。

160

161### 長時間執行的程式碼

162

163當程式碼執行長時間的建置或測試時，Claude 會等待它，或讓它在背景繼續執行：

164

165* **等待**：Claude 會在程式碼完成後回覆，且程式碼會在十分鐘後停止，其中包括您在權限提示上花費的時間

166* **背景**：您可以繼續與 Claude 交談，且程式碼最多可執行兩小時

167

168若要讓程式碼在背景執行，請以自動或 `bypassPermissions` 模式啟動您的工作階段。如果 Claude 仍然等待，請檢查您目前的模式以及您啟動工作階段的方式：

169

170* **您切換到了其他模式**：按 `Shift+Tab`，直到回到您啟動時的模式

171* **您以其他模式啟動，或從 `claude --resume` 清單中選取了工作階段**：如果您可以使用[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)，請結束，然後在 Code Mode 開啟的情況下執行 `claude --continue --permission-mode auto`

172* **您將工具名稱傳給了 `--tools`**：以自動模式重新啟動，且不使用該旗標

173

174## 疑難排解

175

176### Code Mode 無法啟動

177

178工作階段頂端附近出現 `Code Mode (experimental) isn't available`，表示 Claude Code 啟動時未啟用 Code Mode。原因會接在同一行後面，`/status` 也會顯示。請在此表中找到原因，進行變更，然後啟動新的工作階段。如果原因未列在表中，請檢查[需求](#requirements)。

179

180| 原因包含 | 處理方式 |

181| :- | :- |

182| `it isn't open to your account yet` | 如果您的版本早於 v2.1.323，請[更新](#try-code-mode)。否則，請檢查您的網路連線並重新啟動。如果原因仍然存在，請改天再試 |

183| `it only works with the Anthropic API` | 移除透過雲端供應商、閘道或自訂 `ANTHROPIC_BASE_URL` 轉送請求的設定 |

184| `it doesn't work with an API key helper` | 移除 `apiKeyHelper`、`ANTHROPIC_AUTH_TOKEN`，以及 `ANTHROPIC_CUSTOM_HEADERS` 中的任何 `Authorization` 或 `X-Api-Key` 標頭。然後登入或設定 `ANTHROPIC_API_KEY` |

185| `it only works with Opus 5.5, Sonnet 5.5 and later models` | 使用[支援的模型](#requirements)啟動，例如使用 `--model opus`。Haiku 5.5 和 Fable 5.2 也可使用 |

186| `it doesn't work in background jobs` | 在前景啟動，且不使用 `--remote-control` |

187| `it needs settings that Claude Code downloads from Anthropic` | 取消設定[會關閉功能旗標擷取](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的變數，例如 `DISABLE_TELEMETRY` |

188| `OpenTelemetry is on` | 如果您可以不使用 [OpenTelemetry 匯出](https://code.claude.com/docs/zh-TW/monitoring-usage.md)，請取消設定 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `ENABLE_BETA_TRACING_DETAILED` |

189| `it doesn't yet work with an installed mod` | 關閉會檢查工具呼叫的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) |

190| `it can't be used together with agent teams yet` | 取消設定 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` |

191| `this launch's tool options` | 不使用 `--restricted` 啟動，將 `REPL` 加入 `--tools`，並從 `--disallowedTools` 和您的 `deny` 規則中移除 `REPL` |

192| `couldn't save your answer` | 讓 `~/.claude.json` 可寫入 |

193| `your organization's settings don't allow it` | 向您的管理員詢問相關的[受管設定](#block-code-mode-for-your-organization) |

194

195如果您沒有看到任何關於 Code Mode 的行，請執行 `claude --version`。如果您的版本早於 v2.1.323，請更新。接著確認您的 shell 或使用者設定中的 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE` 為 `1`，並從這些位置以及任何 `--settings` 檔案中移除所有 `0`。

196

197### 附有倒數計時的權限提示

198

199在自動模式下，當先前的程式碼仍在執行時 Claude 又啟動了更多程式碼，先前的程式碼就會失去分類器審查。Claude Code 接著會針對先前程式碼中需要審查的剩餘呼叫詢問您。在未連接 IDE 的情況下，權限提示會顯示倒數計時：

200

201```text theme={null}

202Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session

203```

204

205請在倒數計時結束前回應。否則該呼叫會被拒絕，且之後會顯示倒數計時的呼叫會在不提示的情況下被拒絕。若要再次看到權限提示，請傳送訊息給 Claude。

206

207### 工具呼叫被 hook 拒絕

208

209如果 Claude 回報工具呼叫被拒絕，請向它詢問錯誤文字。以下錯誤表示 `PreToolUse` hook 未提供決定，即使未設定 [`onFailure`](https://code.claude.com/docs/zh-TW/hooks#block-the-action-when-a-hook-fails)，這也會拒絕該呼叫：

210

211* **`the hook failed`**：在來自 Claude 程式碼的呼叫上，您的 hook 無法啟動、被終止、以 126、127 或大於 128 的代碼結束，或傳回 HTTP 錯誤或無效輸出。請修正該 hook

212* **`the hook did not finish`**：您的 hook 在來自 Claude 程式碼的呼叫上逾時，或在 Claude 於工作階段中執行過程式碼後，於任何其他工具呼叫上逾時。請提高該 hook 的 [`timeout`](https://code.claude.com/docs/zh-TW/hooks#common-fields)

213

214若要在 `command` 或 `http` hook 失敗或逾時時讓呼叫繼續進行，請在該 hook 上設定 `"onFailure": "continue"`。如果 `command` hook 以 1 之類的一般代碼結束，除非您設定了 `"onFailure": "block"`，否則該呼叫會繼續進行。

215

216### 程式碼輸出被 hook 攔截

217

218如果 Claude 在您預期看到 Claude 程式碼輸出的地方回報了 hook 的阻擋原因，請檢查您的 [`UserPromptSubmit`](https://code.claude.com/docs/zh-TW/hooks#userpromptsubmit) hook。當[程式碼可以在背景執行](#long-running-code)時，該事件上的 `command`、`http` 和 `mcp_tool` hook 也會在程式碼輸出上執行。若要讓輸出通過，請變更該 hook，使其在輸入中的 `source` 為 `poll_event` 時不進行阻擋。

219

220## 相關資源

221

222* [權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)：比較自動模式與會提示您的模式

223* [Hook 參考](https://code.claude.com/docs/zh-TW/hooks.md)：撰寫 `PreToolUse` 和 `UserPromptSubmit` hook

224* [受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)：在整個組織中套用同一套設定

commands.md +3 −5

Details

35下表列出 Claude Code 中包含的所有命令。大多數是內建命令，其行為已編碼到 CLI 中。有兩種類型的項目被標記：35下表列出 Claude Code 中包含的所有命令。大多數是內建命令，其行為已編碼到 CLI 中。有兩種類型的項目被標記：

36 36

37* **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)**：一個隨附 skill。它的運作方式與您自己編寫的 skill 相同：一個交給 Claude 的提示詞。37* **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)**：一個隨附 skill。它的運作方式與您自己編寫的 skill 相同：一個交給 Claude 的提示詞。

~~38 * `/verify` 僅在您調用時運行。~~

39* **[Workflow](https://code.claude.com/docs/zh-TW/workflows.md#bundled-workflows)**：一個隨附的[動態工作流程](https://code.claude.com/docs/zh-TW/workflows.md)，可將工作分散到多個 subagent 並在背景運行。38* **[Workflow](https://code.claude.com/docs/zh-TW/workflows.md#bundled-workflows)**：一個隨附的[動態工作流程](https://code.claude.com/docs/zh-TW/workflows.md)，可將工作分散到多個 subagent 並在背景運行。

~~40 * `/deep-research` 僅在您調用時運行。~~

41 39

42要添加您自己的命令，請參閱 [skill](https://code.claude.com/docs/zh-TW/skills.md)。40要添加您自己的命令，請參閱 [skill](https://code.claude.com/docs/zh-TW/skills.md)。

43 41

150| `/status` | 在 Status 標籤上打開設定介面，顯示版本、模型、帳戶和連線。`Session kind` 行在[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)中顯示 `background job · attached` 或 `background job · unattended`（取決於是否附加終端機），在任何其他工作階段中顯示 `interactive`。在 v2.1.221 之前，`/status` 不顯示此行。在 Claude 回應時也可運作 |148| `/status` | 在 Status 標籤上打開設定介面，顯示版本、模型、帳戶和連線。`Session kind` 行在[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)中顯示 `background job · attached` 或 `background job · unattended`（取決於是否附加終端機），在任何其他工作階段中顯示 `interactive`。在 v2.1.221 之前，`/status` 不顯示此行。在 Claude 回應時也可運作 |

151| `/statusline` | 設定 Claude Code 的[狀態列](https://code.claude.com/docs/zh-TW/statusline.md)。描述您想要的內容，或運行時不帶引數以從您的 shell 提示字元自動設定 |149| `/statusline` | 設定 Claude Code 的[狀態列](https://code.claude.com/docs/zh-TW/statusline.md)。描述您想要的內容，或運行時不帶引數以從您的 shell 提示字元自動設定 |

153| `/stop` | 停止您所附加的[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)，或您以[預覽回覆](https://code.claude.com/docs/zh-TW/agent-view.md#peek-and-reply)方式傳送此命令的目標工作階段；逐字稿和任何 worktree 都會保留。要分離而不停止，請使用 `/exit` 或按 `←` |151| `/stop` | 停止您所附加的[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)，或您以[預覽回覆](https://code.claude.com/docs/zh-TW/agent-view.md#peek-and-reply)方式傳送此命令的目標工作階段；逐字稿和任何 worktree 都會保留。要分離而不停止，請使用 `/exit` 或按 `←` |

154| `/subtask <task>` | 生成[分叉 subagent](https://code.claude.com/docs/zh-TW/sub-agents.md#fork-the-current-conversation)：一個繼承完整對話並在您繼續工作時處理任務的背景 subagent。其結果在完成時返回到此對話。要將對話複製到單獨的背景工作階段，請改用 `/fork`。當 [agent view 關閉](https://code.claude.com/docs/zh-TW/agent-view.md#turn-off-agent-view)時，`/subtask` 不可用，`/fork` 改為生成分叉 subagent |152| `/subtask <task>` | 生成[分叉 subagent](https://code.claude.com/docs/zh-TW/sub-agents.md#fork-the-current-conversation)：一個繼承完整對話並在您繼續工作時處理任務的背景 subagent。其結果在完成時返回到此對話。要將對話複製到單獨的背景工作階段，請改用 `/fork`。當 [agent view 關閉](https://code.claude.com/docs/zh-TW/agent-view.md#turn-off-agent-view)時，`/subtask` 不可用，`/fork` 改為生成分叉 subagent |

161| `/ultraplan <prompt>` | 已移除。改用 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode)。以前將計畫任務發送到[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)以在您的瀏覽器中檢查 |159| `/ultraplan <prompt>` | 已移除。改用 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode)。以前將計畫任務發送到[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)以在您的瀏覽器中檢查 |

162| `/ultrareview [PR or branch]` | 在雲端沙箱中使用 [ultrareview](https://code.claude.com/docs/zh-TW/ultrareview.md) 運行深度、多 agent 程式碼審查。傳遞 PR 參考以檢查該 pull request，或傳遞基礎分支或提交以變更比較基礎。首選調用是 `/code-review ultra`，`/ultrareview` 是別名。在 Pro、Max 和 Ultra 上包括 3 次免費運行，然後需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |160| `/ultrareview [PR or branch]` | 在雲端沙箱中使用 [ultrareview](https://code.claude.com/docs/zh-TW/ultrareview.md) 運行深度、多 agent 程式碼審查。傳遞 PR 參考以檢查該 pull request，或傳遞基礎分支或提交以變更比較基礎。首選調用是 `/code-review ultra`，`/ultrareview` 是別名。在 Pro、Max 和 Ultra 上包括 3 次免費運行，然後需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

163| `/update-config [request]` | **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)。** 描述設定變更，例如允許命令、設定環境變數或添加 [hook](https://code.claude.com/docs/zh-TW/hooks.md)，Claude 編輯匹配的 [`settings.json`](https://code.claude.com/docs/zh-TW/settings) 檔案。對於主題和模型等選項，改用 `/config` |161| `/update-config [request]` | **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)。** 描述設定變更，例如允許命令、設定環境變數或添加 [hook](https://code.claude.com/docs/zh-TW/hooks.md)，Claude 編輯匹配的 [`settings.json`](https://code.claude.com/docs/zh-TW/settings) 檔案。對於主題和模型等選項，改用 `/config` |

165| `/usage` | 顯示工作階段成本、方案用量上限和活動統計。在 Pro、Max、Ultra、Team 或 Enterprise 方案上，包括[計入您的方案上限的內容細目](https://code.claude.com/docs/zh-TW/costs.md#plan-usage-breakdown)。在追蹤支出的 Claude 應用程式閘道後方時，顯示[您透過閘道的支出](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md#usage-warnings-in-claude-code)。`/cost` 和 `/stats` 是別名 |163| `/usage` | 顯示工作階段成本、方案用量上限和活動統計。在 Pro、Max、Ultra、Team 或 Enterprise 方案上，包括[計入您的方案上限的內容細目](https://code.claude.com/docs/zh-TW/costs.md#plan-usage-breakdown)。在追蹤支出的 Claude 應用程式閘道後方時，顯示[您透過閘道的支出](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md#usage-warnings-in-claude-code)。`/cost` 和 `/stats` 是別名 |

166| `/usage-credits` | 在達到上限時設定用量點數，或向您的管理員請求。在瀏覽器中打開您的[用量點數計費設定](https://code.claude.com/docs/zh-TW/costs.md#add-usage-credits-to-your-subscription)，但沒有計費存取權的 Team 和 Enterprise 成員則改為從 CLI 向其管理員發送用量點數請求，並先在對話框中確認該請求會通知其管理員。當沒有瀏覽器可以打開計費頁面時，例如通過 SSH，命令會改為列印要前往的 URL；這需要 Claude Code v2.1.205 或更新版本，較早版本在這種情況下不顯示任何內容。以前為 `/extra-usage` |164| `/usage-credits` | 在達到上限時設定用量點數，或向您的管理員請求。在瀏覽器中打開您的[用量點數計費設定](https://code.claude.com/docs/zh-TW/costs.md#add-usage-credits-to-your-subscription)。沒有計費存取權的 Team 和 Enterprise 成員則改為從 CLI 向其管理員發送用量點數請求。在沒有瀏覽器可以打開該頁面的終端機上，例如通過 SSH，命令會列印 URL。列印 URL 需要 Claude Code v2.1.205 或更新版本。以前為 `/extra-usage` |

167| `/verify` | **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)。** 通過建置您的專案應用程式、運行它並觀察結果來確認程式碼變更執行其應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行和驗證您的應用程式](https://code.claude.com/docs/zh-TW/skills.md#run-and-verify-your-app) |165| `/verify` | **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)。** 通過建置您的專案應用程式、運行它並觀察結果來確認程式碼變更執行其應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行和驗證您的應用程式](https://code.claude.com/docs/zh-TW/skills.md#run-and-verify-your-app) |

168| `/vim` | 在 v2.1.92 中移除。要在 Vim 和 Normal 編輯模式之間切換，請使用 `/config` → Editor mode |166| `/vim` | 在 v2.1.92 中移除。要在 Vim 和 Normal 編輯模式之間切換，請使用 `/config` → Editor mode |

169| `/voice [hold\|tap\|off]` | 切換[語音聽寫](https://code.claude.com/docs/zh-TW/voice-dictation.md)或在特定模式下啟用它。需要 Claude.ai 帳戶 |167| `/voice [hold\|tap\|off]` | 切換[語音聽寫](https://code.claude.com/docs/zh-TW/voice-dictation.md)或在特定模式下啟用它。需要 Claude.ai 帳戶 |

desktop.md +0 −4

Details

2261 2261

2262Desktop 應用程式從 `claude_desktop_config.json` 將 MCP 伺服器載入到本機 Code 標籤工作階段中，以及來自 `~/.claude.json` 和 `.mcp.json` 的伺服器。在 `claude_desktop_config.json` 中定義的伺服器在 Desktop 聊天使用介面和本機 Code 標籤工作階段中都可用。2262Desktop 應用程式從 `claude_desktop_config.json` 將 MCP 伺服器載入到本機 Code 標籤工作階段中，以及來自 `~/.claude.json` 和 `.mcp.json` 的伺服器。在 `claude_desktop_config.json` 中定義的伺服器在 Desktop 聊天使用介面和本機 Code 標籤工作階段中都可用。

2263 2263

2264如果您在 `claude_desktop_config.json` 和 `~/.claude.json` 或 `.mcp.json` 中定義相同的伺服器名稱，本機工作階段中的 Code 標籤連接一次並使用 `claude_desktop_config.json` 定義。

~~2265~~

2266應用程式也會將 `~/.claude.json` 中的 stdio 伺服器重新傳遞到本機工作階段中的嵌入式 CLI。當 `~/.claude.json`（使用者範圍）和 `.mcp.json` 的頂層定義相同的 stdio 伺服器名稱時，Code 標籤使用 `~/.claude.json` 定義，偏離 CLI [範圍階層](https://code.claude.com/docs/zh-TW/mcp.md#scope-hierarchy-and-precedence)。

~~2267~~

2268> [!NOTE]2264> [!NOTE]

2269>2265>

2270> 獨立 CLI 不讀取 `claude_desktop_config.json`。在 macOS 和 WSL 上，執行 `claude mcp add-from-claude-desktop` 將這些伺服器複製到 `~/.claude.json`。請參閱[從 Claude Desktop 匯入 MCP 伺服器](https://code.claude.com/docs/zh-TW/mcp.md#import-mcp-servers-from-claude-desktop)以了解匯入流程和範圍選項。2266> 獨立 CLI 不讀取 `claude_desktop_config.json`。在 macOS 和 WSL 上，執行 `claude mcp add-from-claude-desktop` 將這些伺服器複製到 `~/.claude.json`。請參閱[從 Claude Desktop 匯入 MCP 伺服器](https://code.claude.com/docs/zh-TW/mcp.md#import-mcp-servers-from-claude-desktop)以了解匯入流程和範圍選項。

desktop-linux.md +1 −1

Details

71 71

72從您的應用程式啟動器啟動 **Claude**，或從終端機執行 `claude-desktop`，然後使用您的 Anthropic 帳戶登入。72從您的應用程式啟動器啟動 **Claude**，或從終端機執行 `claude-desktop`，然後使用您的 Anthropic 帳戶登入。

73 73

74Linux 應用程式的登入方式與 macOS 和 Windows 上相同：使用 claude.ai 訂閱，或透過您組織的 SSO。若要使用 API 金鑰身分驗證，請使用 [CLI](https://code.claude.com/docs/zh-TW/quickstart.md)。若要改為搭配 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 閘道使用 Desktop，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。關於這些部署中的代理伺服器和自訂憑證授權單位，請參閱 [網路設定](https://code.claude.com/docs/zh-TW/network-config.md)。74Linux 應用程式的登入方式與 macOS 和 Windows 上相同：使用 claude.ai 訂閱，或透過您組織的 SSO。若要改為搭配 Claude API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 閘道使用 Desktop，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。關於這些部署中的代理伺服器和自訂憑證授權單位，請參閱 [網路設定](https://code.claude.com/docs/zh-TW/network-config.md)。

75 75

76### 從下載的檔案安裝76### 從下載的檔案安裝

77 77

desktop-scheduled-tasks.md +7 −2

Details

83 83

84**8. 選擇權限模式和模型**84**8. 選擇權限模式和模型**

85 85

~~86在指示方塊的工具列中，選擇[權限模式](#permissions-for-scheduled-tasks)和模型。如果保持不變，執行時會使用您的 Claude Code 設定和預設模型。~~86在指示方塊的工具列中，選擇[權限模式](#permissions-for-scheduled-tasks)和模型。

88* **權限模式**：如果保持不變，執行時會使用您的 Claude Code 設定。

89* **模型**：如果模型選單顯示 **Default · Set by admin**，且您未選擇其他模型，執行時會使用您的組織在[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中設定的模型。在應用程式開啟時啟動的[補執行](#missed-runs)則可能改用[您帳戶的執行階段預設模型](https://code.claude.com/docs/zh-TW/model-config.md#default-model-setting)。

87 90

88**9. 建立任務**91**9. 建立任務**

89 92

90按一下 **Create**。如果您尚未信任該資料夾，Desktop 會在此時要求您信任它。任務的詳細資料頁面隨即開啟。93按一下 **Create**。如果您尚未信任該資料夾，Desktop 會在此時要求您信任它。任務的詳細資料頁面隨即開啟。

91 94

95若要查看 **Default · Set by admin** 代表哪個模型，請在詳細資料頁面上按一下 **Run now** 以立即執行任務。接著[開啟該次執行的工作階段](#find-a-runs-session)，提示詞方塊下方的列會顯示模型名稱。

92在詳細資料頁面上，按一下鉛筆圖示以開啟 [**Edit** 表單](#manage-scheduled-tasks)。您可以在其中變更 Desktop 根據您的指示填入的 **Description**、選擇 **Worktree**，或將排程切換為 **Manual** 或 **Custom**。97在詳細資料頁面上，按一下鉛筆圖示以開啟 [**Edit** 表單](#manage-scheduled-tasks)。您可以在其中變更 Desktop 根據您的指示填入的 **Description**、選擇 **Worktree**，或將排程切換為 **Manual** 或 **Custom**。

93 98

94您也可以透過在任何工作階段中描述您想要的內容來建立任務。例如，「設定每天早上 9 點執行的每日程式碼審查」會建立定期任務。像「提醒我明天下午 3 點檢查部署」這樣的請求會建立一次性任務，在觸發後會自動停用。99您也可以透過在任何工作階段中描述您想要的內容來建立任務。例如，「設定每天早上 9 點執行的每日程式碼審查」會建立定期任務。像「提醒我明天下午 3 點檢查部署」這樣的請求會建立一次性任務，在觸發後會自動停用。

181 186

182若要讓任務使用 `update_scheduled_task` MCP 工具變更其自己的排程或提示詞，請按一下 **Run now** 並每次核准該呼叫。187若要讓任務使用 `update_scheduled_task` MCP 工具變更其自己的排程或提示詞，請按一下 **Run now** 並每次核准該呼叫。

183 188

184若要在磁碟上編輯任務的提示，請開啟 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`（如果設定了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars)，則在其下）。該檔案使用 YAML frontmatter 作為 `name` 和 `description`，提示作為主體。變更在下一次執行時生效。Schedule、資料夾、模型和啟用狀態不在此檔案中：透過 Edit 表單變更它們或詢問 Claude。189若要在磁碟上編輯任務的提示詞，請開啟 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`（如果設定了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars)，則在其下）。該檔案使用 YAML frontmatter 作為 `name` 和 `description`，提示詞作為主體。變更在下一次執行時生效。排程、資料夾和啟用狀態不在此檔案中：透過 Edit 表單變更它們或詢問 Claude。

185 190

186## 相關資源191## 相關資源

187 192

env-vars.md +7 −3

Details

211| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆寫自動 [IDE 連線](https://code.claude.com/docs/zh-TW/vs-code.md)。預設情況下，在支援的 IDE 整合式終端機中啟動時，Claude Code 會自動連線。設定為 `false` 可防止此行為。設定為 `true` 可在自動偵測失敗時（例如 tmux 遮蔽了父終端機）強制嘗試連線。優先於 [`autoConnectIde`](https://code.claude.com/docs/zh-TW/settings-reference#autoconnectide) 全域設定 |211| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆寫自動 [IDE 連線](https://code.claude.com/docs/zh-TW/vs-code.md)。預設情況下，在支援的 IDE 整合式終端機中啟動時，Claude Code 會自動連線。設定為 `false` 可防止此行為。設定為 `true` 可在自動偵測失敗時（例如 tmux 遮蔽了父終端機）強制嘗試連線。優先於 [`autoConnectIde`](https://code.claude.com/docs/zh-TW/settings-reference#autoconnectide) 全域設定 |

212| `CLAUDE_CODE_AUTO_MODE_MODEL` | 設定 Claude Code 在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中傳送的分類器請求所使用的模型。請使用完整模型 ID，例如 `claude-sonnet-4-6`。關於 Claude Code 會忽略此變數的情況，請參閱[選擇分類器模型](https://code.claude.com/docs/zh-TW/permission-modes.md#choose-the-classifier-model)。需要 Claude Code v2.1.302 或更新版本 |212| `CLAUDE_CODE_AUTO_MODE_MODEL` | 設定 Claude Code 在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中傳送的分類器請求所使用的模型。請使用完整模型 ID，例如 `claude-sonnet-4-6`。關於 Claude Code 會忽略此變數的情況，請參閱[選擇分類器模型](https://code.claude.com/docs/zh-TW/permission-modes.md#choose-the-classifier-model)。需要 Claude Code v2.1.302 或更新版本 |

213| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否要求伺服器[審查自動模式動作](https://code.claude.com/docs/zh-TW/permission-modes.md#server-side-classifier-review)。設定為 `0` 可改用 Claude Code 自己的分類器請求。直接連線至 Anthropic API 時，需要 v2.1.281 或更新版本。連結的章節列出了變數未設定時哪些工作階段會詢問伺服器，以及從哪個版本開始。需要 Claude Code v2.1.271 或更新版本 |213| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否要求伺服器[審查自動模式動作](https://code.claude.com/docs/zh-TW/permission-modes.md#server-side-classifier-review)。設定為 `0` 可改用 Claude Code 自己的分類器請求。直接連線至 Anthropic API 時，需要 v2.1.281 或更新版本。連結的章節列出了變數未設定時哪些工作階段會詢問伺服器，以及從哪個版本開始。需要 Claude Code v2.1.271 或更新版本 |

214| `CLAUDE_CODE_AUTOMOUNT_ROOTS` | Claude Code 在工作目錄上層資料夾中尋找 `CLAUDE.md`、skill 和 `.mcp.json` 等檔案時要略過的自動掛載根資料夾。當這些查找需要等待自動掛載程式時，請設定此變數。多個路徑在 Unix 上以 `:` 分隔、在 Windows 上以 `;` 分隔，且每個路徑都必須是不含符號連結的絕對路徑。需要 Claude Code v2.1.323 或更新版本 |

214| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設憑證提供者鏈產生憑證的時間，單位為毫秒，超過後請求會因 [`AWS default-chain credential resolve timed out`](https://code.claude.com/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out) 而失敗（預設：`60000`）。當您的鏈中某個步驟確實需要更長時間時（例如透過 `aws-vault` 等包裝工具進行含 MFA 的瀏覽器型 SSO 登入），請調高此值。適用於 Amazon Bedrock、[Claude Platform on AWS](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md) 與 [Mantle 端點](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#use-the-mantle-endpoint)。請參閱[憑證快取與解析逾時](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |215| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設憑證提供者鏈產生憑證的時間，單位為毫秒，超過後請求會因 [`AWS default-chain credential resolve timed out`](https://code.claude.com/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out) 而失敗（預設：`60000`）。當您的鏈中某個步驟確實需要更長時間時（例如透過 `aws-vault` 等包裝工具進行含 MFA 的瀏覽器型 SSO 登入），請調高此值。適用於 Amazon Bedrock、[Claude Platform on AWS](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md) 與 [Mantle 端點](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#use-the-mantle-endpoint)。請參閱[憑證快取與解析逾時](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

215| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設定為 `0` 可關閉 [Bash 命令執行期間所變更檔案的差異](https://code.claude.com/docs/zh-TW/hooks.md#bash)，或設定為 `1` 以在每種權限模式下記錄。優先於 [`bashEditDiffEnabled`](https://code.claude.com/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |216| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設定為 `0` 可關閉 [Bash 命令執行期間所變更檔案的差異](https://code.claude.com/docs/zh-TW/hooks.md#bash)，或設定為 `1` 以在每種權限模式下記錄。優先於 [`bashEditDiffEnabled`](https://code.claude.com/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |

216| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設定為 `0` 可讓非互動工作階段在每個回合結束時向其主機回報閒置狀態，即使背景工作仍在執行。預設情況下，當背景 agent 或[工作流程](https://code.claude.com/docs/zh-TW/workflows.md)執行等背景工作仍在進行時，工作階段在回合結束後會持續回報執行中狀態。這可避免監看狀態的主機（例如遠端工作階段清單）在工作進行中宣告 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不會維持執行中狀態。執行中狀態的預設行為與 `0` 退出選項需要 Claude Code v2.1.269 或更新版本；在較早版本中，請設定 `1` 以維持執行中狀態 |217| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設定為 `0` 可讓非互動工作階段在每個回合結束時向其主機回報閒置狀態，即使背景工作仍在執行。預設情況下，當背景 agent 或[工作流程](https://code.claude.com/docs/zh-TW/workflows.md)執行等背景工作仍在進行時，工作階段在回合結束後會持續回報執行中狀態。這可避免監看狀態的主機（例如遠端工作階段清單）在工作進行中宣告 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不會維持執行中狀態。執行中狀態的預設行為與 `0` 退出選項需要 Claude Code v2.1.269 或更新版本；在較早版本中，請設定 `1` 以維持執行中狀態 |

298| `CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS` | 設為 `1` 以在 `bypassPermissions` 模式下[不經提示即執行危險的 `rm` 命令](https://code.claude.com/docs/zh-TW/permission-modes#turn-off-the-critical-path-removal-prompt-in-bypasspermissions-mode)，這會移除針對破壞性刪除的安全提示。連結的章節列出此設定不會生效的情況。[請在啟動 Claude Code 的環境中設定它](#set-variables-in-your-shell)，因為 Claude Code [會忽略設定 `env` 區塊中的此變數](https://code.claude.com/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。需要 Claude Code v2.1.311 或更新版本 |299| `CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS` | 設為 `1` 以在 `bypassPermissions` 模式下[不經提示即執行危險的 `rm` 命令](https://code.claude.com/docs/zh-TW/permission-modes#turn-off-the-critical-path-removal-prompt-in-bypasspermissions-mode)，這會移除針對破壞性刪除的安全提示。連結的章節列出此設定不會生效的情況。[請在啟動 Claude Code 的環境中設定它](#set-variables-in-your-shell)，因為 Claude Code [會忽略設定 `env` 區塊中的此變數](https://code.claude.com/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。需要 Claude Code v2.1.311 或更新版本 |

300| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | 設為 `1` 以啟用 [agent team](https://code.claude.com/docs/zh-TW/agent-teams.md)。agent team 為實驗性功能，預設為停用 |301| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | 設為 `1` 以啟用 [agent team](https://code.claude.com/docs/zh-TW/agent-teams.md)。agent team 為實驗性功能，預設為停用 |

302| `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE` | 設定為 `1` 可在 [Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md)（一項實驗性功能）中啟動工作階段。設定為 `0` 可保持關閉，或在受管設定中設定以[為組織封鎖它](https://code.claude.com/docs/zh-TW/code-mode.md#block-code-mode-for-your-organization)。此變數[並非在每個設定檔中都有效](https://code.claude.com/docs/zh-TW/settings-reference.md#variables-claude-code-ignores-in-env)。請參閱[版本與帳戶需求](https://code.claude.com/docs/zh-TW/code-mode.md#requirements) |

301| `CLAUDE_CODE_EXTRA_BODY` | 要合併至模型請求主體頂層的 JSON 物件，但不包括對話以外的某些請求，例如 `/model` 檢查。適用於傳遞 Claude Code 未直接公開的提供者特定參數。在您的 shell 中匯出的值也會套用至您使用 `claude agents` 或 `--bg` 分派的[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)。在 v2.1.206 之前，背景工作階段會忽略 shell 匯出的值，並使用背景監督程序所繼承的任何副本 |303| `CLAUDE_CODE_EXTRA_BODY` | 要合併至模型請求主體頂層的 JSON 物件，但不包括對話以外的某些請求，例如 `/model` 檢查。適用於傳遞 Claude Code 未直接公開的提供者特定參數。在您的 shell 中匯出的值也會套用至您使用 `claude agents` 或 `--bg` 分派的[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)。在 v2.1.206 之前，背景工作階段會忽略 shell 匯出的值，並使用背景監督程序所繼承的任何副本 |

302| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 覆寫[檔案讀取](https://code.claude.com/docs/zh-TW/tools-reference.md#large-files)的預設 token 上限，即 25,000 個 token。適用於需要完整讀取較大檔案時。當上下文視窗仍有空間時，Claude 使用 `allow_large` 參數進行的讀取可以超過此上限 |304| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 覆寫[檔案讀取](https://code.claude.com/docs/zh-TW/tools-reference.md#large-files)的預設 token 上限，即 25,000 個 token。適用於需要完整讀取較大檔案時。當上下文視窗仍有空間時，Claude 使用 `allow_large` 參數進行的讀取可以超過此上限 |

303| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設為 `1` 可強制保存逐字稿、提示詞歷史與 `claude agents` 註冊，即使這個 `claude` 是從另一個 Claude Code 工作階段內部啟動的。當繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段，或最初由 Claude Code 的 Bash 工具啟動的背景啟動器）導致真正的最上層工作階段被誤判為巢狀工作階段時使用。自 v2.1.178 起，Claude Code 會自動偵測 tmux 的情況並忽略繼承的標記，因此 tmux 不再需要此變數。在 v2.1.169 及更早版本中也有效；在 v2.1.170 與 v2.1.171 中沒有作用，因為其所覆寫的巢狀工作階段偵測在這些版本中已被移除 |305| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設為 `1` 可強制保存逐字稿、提示詞歷史與 `claude agents` 註冊，即使這個 `claude` 是從另一個 Claude Code 工作階段內部啟動的。當繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段，或最初由 Claude Code 的 Bash 工具啟動的背景啟動器）導致真正的最上層工作階段被誤判為巢狀工作階段時使用。自 v2.1.178 起，Claude Code 會自動偵測 tmux 的情況並忽略繼承的標記，因此 tmux 不再需要此變數。在 v2.1.169 及更早版本中也有效；在 v2.1.170 與 v2.1.171 中沒有作用，因為其所覆寫的巢狀工作階段偵測在這些版本中已被移除 |

348| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 清空擱置中 OpenTelemetry span 的逾時時間（毫秒）（預設：5000）。請參閱[監控](https://code.claude.com/docs/zh-TW/monitoring-usage.md) |350| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 清空擱置中 OpenTelemetry span 的逾時時間（毫秒）（預設：5000）。請參閱[監控](https://code.claude.com/docs/zh-TW/monitoring-usage.md) |

349| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000／29 分鐘）。請參閱[動態標頭](https://code.claude.com/docs/zh-TW/monitoring-usage.md#dynamic-headers) |351| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000／29 分鐘）。請參閱[動態標頭](https://code.claude.com/docs/zh-TW/monitoring-usage.md#dynamic-headers) |

350| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成作業的逾時時間（毫秒）（預設：2000）。若指標在結束時遺失，請調高此值。請參閱[監控](https://code.claude.com/docs/zh-TW/monitoring-usage.md) |352| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成作業的逾時時間（毫秒）（預設：2000）。若指標在結束時遺失，請調高此值。請參閱[監控](https://code.claude.com/docs/zh-TW/monitoring-usage.md) |

351| `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` | 當 API 以 `529` overloaded 錯誤拒絕請求時，該請求[自動重試](https://code.claude.com/docs/zh-TW/errors.md#tune-retry-behavior)之間指數退避的起始延遲（毫秒），取代預設的 500。在 API 容量已滿時，調高此值可將重試分散在較長的時間範圍內。請以純數字提供 500 至 32000 之間的整數毫秒數；Claude Code 會將任何其他值視為未設定。當 `CLAUDE_CODE_RETRY_WATCHDOG` 設為 `1`，或被拒絕的請求是在[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#handle-rate-limits)中傳送時，沒有作用。需要 Claude Code v2.1.292 或更新版本 |353| `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` | 對於 API 以 `529` 過載錯誤拒絕的請求，重試之間退避的起始延遲（毫秒）（預設：500）。在 API 達到容量上限時調高此值，可將重試分散到較長的時間範圍。請以純數字提供 500 到 32000 之間的整數毫秒；Claude Code 會將其他任何值視為未設定。請參閱[它何時沒有作用](https://code.claude.com/docs/zh-TW/errors.md#tune-retry-behavior)。需要 Claude Code v2.1.292 或更新版本 |

352| `CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS` | 對於 API 以 `529` overloaded 錯誤拒絕的請求，其[自動重試](https://code.claude.com/docs/zh-TW/errors.md#tune-retry-behavior)之間指數退避的上限（毫秒），取代預設的 32000。提高此值，可讓後續重試在 API 滿載時持續拉開間隔。以純數字提供 32000 至 64000 的整數毫秒數；Claude Code 會將任何其他值視為未設定。當 `CLAUDE_CODE_RETRY_WATCHDOG` 設定為 `1`，或遭拒的請求是在[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#handle-rate-limits)中傳送時，沒有作用。需要 Claude Code v2.1.296 或更新版本 |354| `CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS` | 對於 API 以 `529` 過載錯誤拒絕的請求，重試之間退避的上限（毫秒）（預設：32000）。調高此值可讓後續重試持續拉開間隔。請以純數字提供 32000 到 300000 之間的整數毫秒；Claude Code 會將其他任何值視為未設定。高於 64000 的值需要 v2.1.323 或更新版本。請參閱[它何時沒有作用](https://code.claude.com/docs/zh-TW/errors.md#tune-retry-behavior)。需要 Claude Code v2.1.296 或更新版本 |

353| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設為 `1` 可讓 Claude Code 在有新版本可用時，於背景執行套件管理員的升級命令。適用於 Homebrew 與 WinGet 安裝。其他套件管理員仍會顯示升級命令而不執行。請參閱[自動更新](https://code.claude.com/docs/zh-TW/setup.md#auto-updates) |355| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設為 `1` 可讓 Claude Code 在有新版本可用時，於背景執行套件管理員的升級命令。適用於 Homebrew 與 WinGet 安裝。其他套件管理員仍會顯示升級命令而不執行。請參閱[自動更新](https://code.claude.com/docs/zh-TW/setup.md#auto-updates) |

354| `CLAUDE_CODE_PERFORCE_MODE` | 設為 `1` 以啟用可感知 Perforce 的寫入保護。設定後，若目標檔案缺少擁有者寫入位元，Edit、Write 與 NotebookEdit 會失敗並提示 `p4 edit <file>`；Perforce 會清除已同步檔案的此位元，直到 `p4 edit` 開啟它們為止。這可防止 Claude Code 繞過 Perforce 變更追蹤 |356| `CLAUDE_CODE_PERFORCE_MODE` | 設為 `1` 以啟用可感知 Perforce 的寫入保護。設定後，若目標檔案缺少擁有者寫入位元，Edit、Write 與 NotebookEdit 會失敗並提示 `p4 edit <file>`；Perforce 會清除已同步檔案的此位元，直到 `p4 edit` 開啟它們為止。這可防止 Claude Code 繞過 Perforce 變更追蹤 |

370| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)執行時自動設為 `true`。可從 hook 或設定指令碼讀取此值，以偵測是否處於雲端工作階段中 |372| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)執行時自動設為 `true`。可從 hook 或設定指令碼讀取此值，以偵測是否處於雲端工作階段中 |

371| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中自動設為目前工作階段的 ID。讀取此值可建構返回工作階段逐字稿的連結。請參閱[將輸出連結回工作階段](https://code.claude.com/docs/zh-TW/cloud-environments.md#link-output-back-to-the-session) |373| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中自動設為目前工作階段的 ID。讀取此值可建構返回工作階段逐字稿的連結。請參閱[將輸出連結回工作階段](https://code.claude.com/docs/zh-TW/cloud-environments.md#link-output-back-to-the-session) |

372| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可以受限模式啟動工作階段，等同於傳遞 [`--restricted`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags)。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |374| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可以受限模式啟動工作階段，等同於傳遞 [`--restricted`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags)。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |

375| `CLAUDE_CODE_RESUME_HINT_COMMAND` | 在啟動 Claude Code 的包裝指令碼中，將此變數設為您執行包裝程式時輸入的名稱，例如 `mytool`。本機工作階段在結束時就會印出 `mytool --resume <session-id>`，取代 `claude --resume <session-id>`。Claude Code 會忽略不符合 `^\w[\w-]*$` 的名稱。它也會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.323 或更新版本 |

373| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設為 `1` 可在上一個工作階段於回合中途結束時自動繼續。用於 SDK 模式，讓模型無需 SDK 重新傳送提示詞即可繼續。若要關閉，請取消設定此變數或將其設為 `0`。關於 VS Code 聊天面板，請參閱[重新載入後繼續對話](https://code.claude.com/docs/zh-TW/vs-code.md#continue-conversations-after-a-reload) |376| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設為 `1` 可在上一個工作階段於回合中途結束時自動繼續。用於 SDK 模式，讓模型無需 SDK 重新傳送提示詞即可繼續。若要關閉，請取消設定此變數或將其設為 `0`。關於 VS Code 聊天面板，請參閱[重新載入後繼續對話](https://code.claude.com/docs/zh-TW/vs-code.md#continue-conversations-after-a-reload) |

374| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 對於在回合中途結束的工作階段，若要在繼續時自動接續，其最後一則逐字稿訊息的最大存在時間（毫秒）。當最後一則訊息比此界限更舊時，Claude Code 會略過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自動繼續及其 `CLAUDE_CODE_RESUME_PROMPT` 接續訊息，且工作階段會以閒置狀態啟動，讓您明確地繼續。未設定或設為 `0` 表示不設界限，但某些回合只會在其最後一則訊息後六小時內繼續，例如以 API 錯誤結束的回合。正值會為每個回合設定界限，包括那些回合；負值或非數值會套用一小時的界限。長時間執行之 agent 的產生指令碼可以設定此變數，讓針對舊逐字稿的重新啟動不會重新執行過時的提示詞。當 Claude Code 重新啟動從互動式工作階段繼承對話的已當機 [agent view](https://code.claude.com/docs/zh-TW/agent-view.md) 工作階段時，會自行設定一小時的界限。需要 Claude Code v2.1.211 或更新版本 |377| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 對於在回合中途結束的工作階段，若要在繼續時自動接續，其最後一則逐字稿訊息的最大存在時間（毫秒）。當最後一則訊息比此界限更舊時，Claude Code 會略過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自動繼續及其 `CLAUDE_CODE_RESUME_PROMPT` 接續訊息，且工作階段會以閒置狀態啟動，讓您明確地繼續。未設定或設為 `0` 表示不設界限，但某些回合只會在其最後一則訊息後六小時內繼續，例如以 API 錯誤結束的回合。正值會為每個回合設定界限，包括那些回合；負值或非數值會套用一小時的界限。長時間執行之 agent 的產生指令碼可以設定此變數，讓針對舊逐字稿的重新啟動不會重新執行過時的提示詞。當 Claude Code 重新啟動從互動式工作階段繼承對話的已當機 [agent view](https://code.claude.com/docs/zh-TW/agent-view.md) 工作階段時，會自行設定一小時的界限。需要 Claude Code v2.1.211 或更新版本 |

375| `CLAUDE_CODE_RESUME_PROMPT` | 覆寫當 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 接續中斷的回合而非重新傳送其提示詞時，或當您以 `-p` 繼續[延後的工具呼叫](https://code.claude.com/docs/zh-TW/hooks.md#defer-a-tool-call-for-later)時，Claude Code 傳送給 Claude 的接續訊息。預設為 `Continue from where you left off.`。空字串會使用預設值 |378| `CLAUDE_CODE_RESUME_PROMPT` | 覆寫當 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 接續中斷的回合而非重新傳送其提示詞時，或當您以 `-p` 繼續[延後的工具呼叫](https://code.claude.com/docs/zh-TW/hooks.md#defer-a-tool-call-for-later)時，Claude Code 傳送給 Claude 的接續訊息。預設為 `Continue from where you left off.`。空字串會使用預設值 |

405| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設為 `1` 可從 Claude Code 啟動之子程序（例如 Bash 命令、hook 與 stdio MCP 伺服器）的環境中移除憑證。清除機制會依變數名稱或其值辨識憑證，並保留 GitHub token 與代理伺服器設定。請參閱[子程序環境清除會移除哪些內容](#what-the-subprocess-environment-scrub-removes)。設定 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此變數 |408| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設為 `1` 可從 Claude Code 啟動之子程序（例如 Bash 命令、hook 與 stdio MCP 伺服器）的環境中移除憑證。清除機制會依變數名稱或其值辨識憑證，並保留 GitHub token 與代理伺服器設定。請參閱[子程序環境清除會移除哪些內容](#what-the-subprocess-environment-scrub-removes)。設定 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此變數 |

406| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設為 `1`，以在第一個查詢之前等待外掛安裝完成。若未設定，外掛會在背景安裝，且可能在第一個回合無法使用。可搭配 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 來限制等待時間 |409| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設為 `1`，以在第一個查詢之前等待外掛安裝完成。若未設定，外掛會在背景安裝，且可能在第一個回合無法使用。可搭配 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 來限制等待時間 |

407| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛安裝的逾時時間（毫秒）。超過時，Claude Code 會在沒有外掛的情況下繼續並記錄錯誤。沒有預設值：若未設定此變數，同步安裝會等到完成為止 |410| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛安裝的逾時時間（毫秒）。超過時，Claude Code 會在沒有外掛的情況下繼續並記錄錯誤。沒有預設值：若未設定此變數，同步安裝會等到完成為止 |

408| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 旗標的非互動模式中設為 `1`，讓 Claude Code 在該次執行中下載您 claude.ai 帳戶已啟用的 skill，並在執行第一個查詢之前等待其清單，最長為 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。需要 claude.ai 身分驗證。以 claude.ai 帳戶登入的終端機工作階段無需此變數即可[同步這些 skill](https://code.claude.com/docs/zh-TW/skills.md#where-synced-skills-load)，因此僅在 `-p` 執行需要在第一個查詢中使用您目前的 skill 時才設定 |411| `CLAUDE_CODE_SYNC_SKILLS` | 設為 `1` 可讓 Claude Code 下載為您的 claude.ai 帳戶啟用的 skill。在使用 `-p` 旗標的非互動模式中，Claude Code 也會在執行第一次查詢前，最多等待 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` 以取得 skill 清單。需要 claude.ai 身分驗證。以 claude.ai 帳戶登入的終端機工作階段無需此變數即可[同步這些 skill](https://code.claude.com/docs/zh-TW/skills.md#where-synced-skills-load)。在互動式工作階段中，此變數需要 v2.1.323 或更新版本 |

409| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當以 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/typescript.md#query-object) 建置的應用程式重新載入 skill 時，在工作階段中途執行之 skill 重新同步的逾時時間（毫秒）（預設：30000）。超過時，重新載入會以已到達的 skill 繼續，其餘下載則在背景完成 |412| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當以 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/typescript.md#query-object) 建置的應用程式重新載入 skill 時，在工作階段中途執行之 skill 重新同步的逾時時間（毫秒）（預設：30000）。超過時，重新載入會以已到達的 skill 繼續，其餘下載則在背景完成 |

410| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時時間（毫秒）（預設：5000）。超過時，第一個查詢會以已到達的 skill 執行。無論如何，下載都會在背景完成，且 Claude 在叫用某個 skill 時會等待該 skill 下載完成 |413| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時時間（毫秒）（預設：5000）。超過時，第一個查詢會以已到達的 skill 執行。無論如何，下載都會在背景完成，且 Claude 在叫用某個 skill 時會等待該 skill 下載完成 |

411| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設為 `false` 可停用差異輸出中的語法醒目提示。在顏色干擾您的終端機設定時很有用。若也要停用程式碼區塊與檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](https://code.claude.com/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |414| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設為 `false` 可停用差異輸出中的語法醒目提示。在顏色干擾您的終端機設定時很有用。若也要停用程式碼區塊與檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](https://code.claude.com/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |

585* 啟用 [You should know mod](https://code.claude.com/docs/zh-TW/interactive-mode.md#you-should-know-suggestions)588* 啟用 [You should know mod](https://code.claude.com/docs/zh-TW/interactive-mode.md#you-should-know-suggestions)

586* 使用 [advisor 工具](https://code.claude.com/docs/zh-TW/advisor.md#requirements)，但在 Claude Platform on AWS 上使用 Claude Code v2.1.300 或更新版本時除外589* 使用 [advisor 工具](https://code.claude.com/docs/zh-TW/advisor.md#requirements)，但在 Claude Platform on AWS 上使用 Claude Code v2.1.300 或更新版本時除外

587* 使用 [MCP tasks](https://code.claude.com/docs/zh-TW/mcp.md#mcp-tasks-that-run-on-the-server)590* 使用 [MCP tasks](https://code.claude.com/docs/zh-TW/mcp.md#mcp-tasks-that-run-on-the-server)

591* 啟用 [Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md#requirements)

588* 閱讀或回覆 [artifact 上的留言](https://code.claude.com/docs/zh-TW/artifacts.md#collect-comments-on-an-artifact)592* 閱讀或回覆 [artifact 上的留言](https://code.claude.com/docs/zh-TW/artifacts.md#collect-comments-on-an-artifact)

589* 讓 Claude 讀取[其他組織的公開 artifact](https://code.claude.com/docs/zh-TW/artifacts.md#read-an-artifact-shared-with-you)593* 讓 Claude 讀取[其他組織的公開 artifact](https://code.claude.com/docs/zh-TW/artifacts.md#read-an-artifact-shared-with-you)

590* 在已安裝 Git Bash 的 Windows 上，為 claude.ai 和 Console 帳戶預設取得 [PowerShell 工具](https://code.claude.com/docs/zh-TW/tools-reference.md#powershell-tool)；除非您設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否則 Claude Code 會透過 Git Bash 執行 shell 命令。在未安裝 Git Bash 的 Windows 上，該工具會保持啟用594* 在已安裝 Git Bash 的 Windows 上，為 claude.ai 和 Console 帳戶預設取得 [PowerShell 工具](https://code.claude.com/docs/zh-TW/tools-reference.md#powershell-tool)；除非您設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否則 Claude Code 會透過 Git Bash 執行 shell 命令。在未安裝 Git Bash 的 Windows 上，該工具會保持啟用

errors.md +100 −15

Details

122| `A request to MCP server "<name>" was sent without your stored credentials` | [身分驗證](#couldnt-read-the-stored-credentials-for-mcp-server) |122| `A request to MCP server "<name>" was sent without your stored credentials` | [身分驗證](#couldnt-read-the-stored-credentials-for-mcp-server) |

123| `This server's URL is missing or not a valid URL, so sign-in can't start` | [身分驗證](#mcp-server-url-is-missing-or-not-a-valid-url) |123| `This server's URL is missing or not a valid URL, so sign-in can't start` | [身分驗證](#mcp-server-url-is-missing-or-not-a-valid-url) |

125| `Stopped an OAuth request` | [身分驗證](#stopped-an-oauth-request) |

125| `Refusing to send credentials to non-https token endpoint` / `<short-name> from the MCP SDK for <server-url>` | [身分驗證](#refusing-to-send-credentials-to-non-https-token-endpoint) |126| `Refusing to send credentials to non-https token endpoint` / `<short-name> from the MCP SDK for <server-url>` | [身分驗證](#refusing-to-send-credentials-to-non-https-token-endpoint) |

153| 在雲端工作階段中出現、帶有 `GitHub GraphQL is not available from Claude Code sessions` 的 `403` | [GitHub 代理伺服器](https://code.claude.com/docs/zh-TW/cloud-environments.md#github-proxy) |154| 在雲端工作階段中出現、帶有 `GitHub GraphQL is not available from Claude Code sessions` 的 `403` | [GitHub 代理伺服器](https://code.claude.com/docs/zh-TW/cloud-environments.md#github-proxy) |

154| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [網路](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |155| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [網路](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |

155| `Failed to fetch session from Sessions API: Failed to fetch session logs` | [網路](#failed-to-fetch-session-from-sessions-api) |156| `Failed to fetch session from Sessions API: Failed to fetch session logs` | [網路](#failed-to-fetch-session-from-sessions-api) |

157| `Couldn't load the history of cloud session` | [網路](#couldnt-load-the-history-of-cloud-session) |

157| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [網路](#sessions-ended-while-this-machine-was-offline) |159| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [網路](#sessions-ended-while-this-machine-was-offline) |

182| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [請求錯誤](#tool-input-schema-is-invalid) |184| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [請求錯誤](#tool-input-schema-is-invalid) |

185| `N tools left out`（顯示於 `/mcp` 中的伺服器旁）/ `Claude wasn't given N tools because the Anthropic API would reject their input schemas` | [具有無效輸入 schema 的工具](https://code.claude.com/docs/zh-TW/mcp.md#tools-with-invalid-input-schemas) |

183| `Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128` | [請求錯誤](#mcp-tool-name-over-128-characters) |186| `Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128` | [請求錯誤](#mcp-tool-name-over-128-characters) |

253| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [命令列錯誤](#not-carried-over-to-the-sessions-remote-control-starts) |256| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [命令列錯誤](#not-carried-over-to-the-sessions-remote-control-starts) |

257| `Remote Control did not start, because sessions would skip part or all of the --settings file` | [命令列錯誤](#remote-control-did-not-start-because-of-the-settings-file) |

258| `The settings file <file> has changed since Remote Control started, so this session did not start` | [命令列錯誤](#settings-file-changed-since-remote-control-started) |

254| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [命令列錯誤](#sandbox-is-not-supported-by-claude-remote-control) |259| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [命令列錯誤](#sandbox-is-not-supported-by-claude-remote-control) |

269| `Shell command failed for pattern "..."`，來自 `/security-review` 或任何注入動態上下文的 skill | [命令列錯誤](#security-review-fails-without-origin-head) |274| `Shell command failed for pattern "..."`，來自 `/security-review` 或任何注入動態上下文的 skill | [命令列錯誤](#security-review-fails-without-origin-head) |

270| 來自注入動態上下文之 skill 的 `Shell command permission check failed for pattern "..."` | [命令列錯誤](#security-review-fails-without-origin-head) |275| 來自注入動態上下文之 skill 的 `Shell command permission check failed for pattern "..."` | [命令列錯誤](#security-review-fails-without-origin-head) |

276| ``Couldn't run `<command>` for <name>. A file named HEAD or .git in this folder or one above it may not be yours``，來自注入動態上下文的 skill | [注入命令的權限檢查](https://code.claude.com/docs/zh-TW/skills.md#permission-checks-on-injected-commands) |

271| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [命令列錯誤](#security-review-fails-without-origin-head) |277| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [命令列錯誤](#security-review-fails-without-origin-head) |

272| `No shell command in <name> was run, because the <tool> tool does not accept one of them` | [命令列錯誤](#no-shell-command-was-run) |278| `No shell command in <name> was run, because the <tool> tool does not accept one of them` | [命令列錯誤](#no-shell-command-was-run) |

273| `Input must be provided either through stdin or as a prompt argument when using --print` | [命令列錯誤](#input-must-be-provided-when-using-print) |279| `Input must be provided either through stdin or as a prompt argument when using --print` | [命令列錯誤](#input-must-be-provided-when-using-print) |

426| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [背景工作階段錯誤](#eacces-when-starting-a-background-session) |432| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [背景工作階段錯誤](#eacces-when-starting-a-background-session) |

434| `Subprocess initialization did not complete within 60000ms` | [包裝程式與 IDE 錯誤](#subprocess-initialization-did-not-complete-within-60000ms) |

435| `Claude Code did not finish starting` | [包裝程式與 IDE 錯誤](#subprocess-initialization-did-not-complete-within-60000ms) |

428| `The connection to Claude Code ended before this message completed` | [包裝程式和 IDE 錯誤](#the-connection-to-claude-code-ended-before-this-message-completed) |436| `The connection to Claude Code ended before this message completed` | [包裝程式和 IDE 錯誤](#the-connection-to-claude-code-ended-before-this-message-completed) |

430| `The Claude Code program for this computer, the <build> build, could not be found` | [包裝程式與 IDE 錯誤](#the-claude-code-program-for-this-computer-could-not-be-found) |438| `The Claude Code program for this computer, the <build> build, could not be found` | [包裝程式與 IDE 錯誤](#the-claude-code-program-for-this-computer-could-not-be-found) |

560| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS` | 無上限 | 設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，單一請求等待您方案的[用量上限](#youve-hit-your-session-limit)（例如工作階段或每週上限）重設的最長時間（毫秒）。當重設時間比此等待上限更遠時，請求會立即失敗，除非用量點數仍有餘額或 API 無法檢查用量點數。在這些情況下，請求會被重試，如果在成功之前超過此等待上限則會失敗。需要 Claude Code v2.1.301 或更新版本。 |568| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS` | 無上限 | 設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，單一請求等待您方案的[用量上限](#youve-hit-your-session-limit)（例如工作階段或每週上限）重設的最長時間（毫秒）。當重設時間比此等待上限更遠時，請求會立即失敗，除非用量點數仍有餘額或 API 無法檢查用量點數。在這些情況下，請求會被重試，如果在成功之前超過此等待上限則會失敗。需要 Claude Code v2.1.301 或更新版本。 |

561| [`CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 未設定 | 設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，在請求等待[用量上限](#youve-hit-your-session-limit)重設期間，檢查該上限是否已解除的最短間隔（毫秒）。當檢查發現上限已解除時，請求會立即送出。請提供 `60000` 到 `10800000` 之間的純數字。未設定或超出該範圍時，不會進行任何檢查。關於 Claude Code 何時略過這些檢查，請參閱[環境變數參考](https://code.claude.com/docs/zh-TW/env-vars.md)。需要 Claude Code v2.1.305 或更新版本。 |569| [`CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 未設定 | 設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，在請求等待[用量上限](#youve-hit-your-session-limit)重設期間，檢查該上限是否已解除的最短間隔（毫秒）。當檢查發現上限已解除時，請求會立即送出。請提供 `60000` 到 `10800000` 之間的純數字。未設定或超出該範圍時，不會進行任何檢查。關於 Claude Code 何時略過這些檢查，請參閱[環境變數參考](https://code.claude.com/docs/zh-TW/env-vars.md)。需要 Claude Code v2.1.305 或更新版本。 |

562| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 500 | API 以 `529` 過載錯誤拒絕的請求，其重試之間退避的起始延遲（毫秒）。當 API 容量已滿時，可提高此值（最高 32000），以將重試分散在較長的時間範圍內。當 `CLAUDE_CODE_RETRY_WATCHDOG` 設定為 `1`，或被拒絕的請求是以[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#handle-rate-limits)發送時，此設定無效。需要 Claude Code v2.1.292 或更新版本。 |570| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 500 | API 以 `529` 過載錯誤拒絕的請求，其重試之間退避的起始延遲（毫秒）。當 API 容量已滿時，可提高此值（最高 32000），以將重試分散在較長的時間範圍內。當 `CLAUDE_CODE_RETRY_WATCHDOG` 設定為 `1`，或被拒絕的請求是以[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#handle-rate-limits)發送時，此設定無效。需要 Claude Code v2.1.292 或更新版本。 |

563| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 32000 | API 以 `529` 過載錯誤拒絕的請求，其重試之間退避的上限（毫秒）。當 API 容量已滿時，可提高此值（最高 64000），讓後續的重試間隔持續拉長。當 `CLAUDE_CODE_RETRY_WATCHDOG` 設定為 `1`，或被拒絕的請求是以[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#handle-rate-limits)發送時，此設定無效。需要 Claude Code v2.1.296 或更新版本。 |571| [`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 32000 | API 以 `529` 過載錯誤拒絕的請求，其重試之間退避的上限（毫秒）。當 API 容量已滿時，可提高此值（最高 300000），讓後續的重試間隔持續拉長。大於 64000 的值需要 v2.1.323 或更新版本。在與 `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` 相同的情況下，此設定無效。需要 Claude Code v2.1.296 或更新版本。 |

564| [`API_TIMEOUT_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 600000 | 每次請求嘗試接收其回應標頭的可用時間（毫秒）。它不會限制串流回應在此之後持續執行的時間。在慢速網路或代理伺服器上請提高此值。關於它如何限制首位元組截止時間，請參閱 [No response from API](#no-response-from-api)。 |572| [`API_TIMEOUT_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 600000 | 每次請求嘗試接收其回應標頭的可用時間（毫秒）。它不會限制串流回應在此之後持續執行的時間。在慢速網路或代理伺服器上請提高此值。關於它如何限制首位元組截止時間，請參閱 [No response from API](#no-response-from-api)。 |

565| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](https://code.claude.com/docs/zh-TW/env-vars) | 未設定 | 逾時的[非串流請求](#streaming-response-ended-before-any-complete-data-was-received)重新發送次數上限。達到上限時，請求會失敗。Claude 產生時間超過逾時的回應在每次重新發送時都會再次逾時，因此請設定較低的數字（例如 `0`）以便更快失敗。關於每次嘗試的逾時，請參閱[非串流嘗試的等待時間](#how-long-a-non-streaming-attempt-waits)。需要 Claude Code v2.1.285 或更新版本。 |573| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](https://code.claude.com/docs/zh-TW/env-vars) | 未設定 | 逾時的[非串流請求](#streaming-response-ended-before-any-complete-data-was-received)重新發送次數上限。達到上限時，請求會失敗。Claude 產生時間超過逾時的回應在每次重新發送時都會再次逾時，因此請設定較低的數字（例如 `0`）以便更快失敗。關於每次嘗試的逾時，請參閱[非串流嘗試的等待時間](#how-long-a-non-streaming-attempt-waits)。需要 Claude Code v2.1.285 或更新版本。 |

566| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 未設定 | 串流請求的第一個回應位元組的截止時間（毫秒）。需要 Claude Code v2.1.242 或更新版本。關於當此未設定時 Claude Code 如何選擇截止時間，請參閱 [No response from API](#no-response-from-api)。 |574| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](https://code.claude.com/docs/zh-TW/env-vars) | 未設定 | 串流請求的第一個回應位元組的截止時間（毫秒）。需要 Claude Code v2.1.242 或更新版本。關於當此未設定時 Claude Code 如何選擇截止時間，請參閱 [No response from API](#no-response-from-api)。 |

825同一個 Claude 回應中的後續呼叫可能會以此原因遭到拒絕：833同一個 Claude 回應中的後續呼叫可能會以此原因遭到拒絕：

826 834

827```text theme={null}835```text theme={null}

828another call in this response was changed by a hook after auto mode reviewed it, or could not be confirmed unchanged836another call in this response was changed after auto mode reviewed it, or could not be confirmed unchanged

829```837```

830 838

831Claude 接著可以再次發出每個遭拒絕的呼叫，讓伺服器進行審查。若出現權限提示，請回應它。除非 Claude 在回覆中表示自動模式無法檢查該呼叫，否則您不需要做其他任何事。屆時，請停止該變更或自行核准該呼叫，並請 Claude 再試一次該呼叫：839Claude 接著可以再次發出每個遭拒絕的呼叫，讓伺服器進行審查。若出現權限提示，請回應它。除非 Claude 在回覆中表示自動模式無法檢查該呼叫，否則您不需要做其他任何事。屆時，請停止該變更或自行核准該呼叫，並請 Claude 再試一次該呼叫：

978 986

979### You've hit your monthly spend limit987### You've hit your monthly spend limit

980 988

981您的方案包含的使用量無法涵蓋此請求，而原本會為其付費的[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)已達到支出限制。這發生在您的方案的其中一個使用視窗已用完時，或當請求是僅由用量點數支付的請求時，例如對[計費至用量點數](https://code.claude.com/docs/zh-TW/model-config.md#fable-and-usage-credits)的模型的請求。訊息會指出是誰的限制阻止了您。`·` 後面的文字說明如何提高該限制，並因您的方案和您是否管理計費而異：989您的方案包含的使用量無法涵蓋此請求，而原本會為其付費的[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)已達到支出限制。當您的方案的其中一個使用視窗已用完，或請求僅由用量點數支付時，您的方案便無法涵蓋該請求。其中一個例子是對[計費至用量點數](https://code.claude.com/docs/zh-TW/model-config.md#fable-and-usage-credits)的模型的請求。

990

991`·` 前面的文字指出阻止您的限制，例如您組織的每月支出限制，後面的文字則說明如何提高該限制。在雲端工作階段或 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 下，該文字不會提供 URL，而關於您自己的 `monthly spend limit` 的訊息不會說明如何提高它。其他工作階段會顯示如下形式：

982 992

983```text theme={null}993```text theme={null}

984You've hit your monthly spend limit · raise it at https://claude.ai/settings/usage?from=cc_cli_limit_message994You've hit your monthly spend limit · raise it at https://claude.ai/settings/usage?from=cc_cli_limit_message

1822 1832

1823在 v2.1.232 之前，Claude Code 只在逐步推出時或您設定 `MCP_SDK_GENERATION=v2` 時才使用 v2 執行階段。1833在 v2.1.232 之前，Claude Code 只在逐步推出時或您設定 `MCP_SDK_GENERATION=v2` 時才使用 v2 執行階段。

1824 1834

1835### Stopped an OAuth request

1836

1837此訊息表示 Claude Code 因 OAuth 端點將 [MCP 伺服器的 OAuth 請求](https://code.claude.com/docs/zh-TW/mcp.md#authenticate-with-remote-mcp-servers)重新導向，而停止了該請求。在此訊息的兩種形式中，第一個位址都是發出重新導向的位址：

1838

1839```text theme={null}

1840Stopped an OAuth request, which can hold secrets: https://auth.example.com redirected it to https://other.example.com. Ask the owner of https://auth.example.com to remove that redirect.

1841Stopped an OAuth request: https://auth.example.com redirected it more than 5 times. Ask the owner of https://auth.example.com to fix those redirects.

1842```

1843

1844**處理方式：**

1845

1846* 請第一個位址的營運者（例如 MCP 伺服器的營運者）移除或修正該重新導向。然後從 `/mcp` 再試一次。

1847

1825### 拒絕將憑證傳送至非 https 的 token 端點1848### 拒絕將憑證傳送至非 https 的 token 端點

1826 1849

1827在 [v2 執行階段](https://code.claude.com/docs/zh-TW/mcp.md#mcp-client-runtimes)上，Claude Code 只會將 [MCP OAuth](https://code.claude.com/docs/zh-TW/mcp.md#authenticate-with-remote-mcp-servers) token 請求傳送至透過 HTTPS 提供，或位於 `localhost`、`127.0.0.1` 或 `::1` 的 token 端點。此訊息表示伺服器的 token 端點兩者皆非，因此 Claude Code 在傳送請求之前停止了。這發生在瀏覽器登入之後，因此瀏覽器步驟會先成功，之後每當 Claude Code 重新整理該伺服器的 token 時也會再次發生。1850在 [v2 執行階段](https://code.claude.com/docs/zh-TW/mcp.md#mcp-client-runtimes)上，Claude Code 只會將 [MCP OAuth](https://code.claude.com/docs/zh-TW/mcp.md#authenticate-with-remote-mcp-servers) token 請求傳送至透過 HTTPS 提供，或位於 `localhost`、`127.0.0.1` 或 `::1` 的 token 端點。此訊息表示伺服器的 token 端點兩者皆非，因此 Claude Code 在傳送請求之前停止了。這發生在瀏覽器登入之後，因此瀏覽器步驟會先成功，之後每當 Claude Code 重新整理該伺服器的 token 時也會再次發生。

2207 2230

2208### 雲端工作階段中不允許主機2231### 雲端工作階段中不允許主機

2209 2232

2210來自雲端工作階段或雲端排程任務的出站 HTTP 請求被環境的網路原則阻止。2233在雲端工作階段或雲端排程任務中，`403` 或 DNS 錯誤（例如 `ENOTFOUND`）可能表示所請求的主機不在[雲端環境的允許清單](https://code.claude.com/docs/zh-TW/cloud-environments.md#access-levels)上。若要確認，請將該主機與該清單進行比對。帶有此標頭的 `403` 可確認遭到封鎖，但並非每個遭封鎖請求的 `403` 都帶有此標頭：

2211 2234

2212```text theme={null}2235```text theme={null}

2213HTTP 4032236HTTP 403

2290 2313

2291在 v2.1.296 之前，Claude Code 不會重試失敗的讀取，並且在讀取失敗後可能會以空白對話開啟該工作階段並回報成功，而不是列印此訊息。2314在 v2.1.296 之前，Claude Code 不會重試失敗的讀取，並且在讀取失敗後可能會以空白對話開啟該工作階段並回報成功，而不是列印此訊息。

2292 2315

2316### Couldn't load the history of cloud session

2317

2318此訊息表示 Claude Code 找到了[您要求拉取到終端機的雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#from-cloud-to-terminal)，但其對話記錄的請求傳回了找不到的結果：

2319

2320```text theme={null}

2321Couldn't load the history of cloud session session_01HJKLMNOPQRSTUVWXYZ. Check it at https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ?from=cli

2322```

2323

2324**該怎麼做：**

2325

2326* 開啟訊息中的連結，在瀏覽器中檢查該工作階段。如果它在瀏覽器中可以開啟，而相同的 teleport 再次以此方式失敗，請[回報問題](#report-an-error)。

2327

2293### Couldn't reconnect to your Remote Control session2328### Couldn't reconnect to your Remote Control session

2294 2329

2295```text theme={null}2330```text theme={null}

2565 2600

2566Claude Code 通常會自動調整大型影像的大小。這些錯誤意味著影像無法解碼或調整大小以符合 API 限制。2601Claude Code 通常會自動調整大型影像的大小。這些錯誤意味著影像無法解碼或調整大小以符合 API 限制。

2567 2602

2603您看到的錯誤可能會列出不同的像素上限，例如在這些範例顯示 `2000x2000px` 之處顯示 `2576x2576px`。

2604

2568**該怎麼辦：**2605**該怎麼辦：**

2569 2606

2570* 如果訊息要求您轉換影像，請將其轉換為 PNG、JPEG、GIF 或 WebP 並再次附加。Claude Code 可以從檔案標頭驗證這些格式的尺寸，而無需解碼影像。2607* 如果訊息要求您轉換影像，請將其轉換為 PNG、JPEG、GIF 或 WebP 並再次附加。Claude Code 可以從檔案標頭驗證這些格式的尺寸，而無需解碼影像。

2873* **hook 寫入的原因**：PreModelSwitch hook 在[拒絕切換或要求確認](https://code.claude.com/docs/zh-TW/hooks.md#premodelswitch-decision-control)時提供了該原因。解決它要求的內容，或選擇您的 hook 允許的模型。2910* **hook 寫入的原因**：PreModelSwitch hook 在[拒絕切換或要求確認](https://code.claude.com/docs/zh-TW/hooks.md#premodelswitch-decision-control)時提供了該原因。解決它要求的內容，或選擇您的 hook 允許的模型。

2874* **`PreModelSwitch hook <name> did not respond before its timeout`**：在其[逾時](https://code.claude.com/docs/zh-TW/hooks.md#timeouts)之前沒有回答的 hook 會阻止切換。修復掛起的命令或提高該 hook 的 `timeout`，然後再次切換。2911* **`PreModelSwitch hook <name> did not respond before its timeout`**：在其[逾時](https://code.claude.com/docs/zh-TW/hooks.md#timeouts)之前沒有回答的 hook 會阻止切換。修復掛起的命令或提高該 hook 的 `timeout`，然後再次切換。

2875* **`confirmation required, and this session cannot ask`**：hook 回答了 `ask` 而沒有原因，控制請求無法顯示確認提示。[`-p` 執行](https://code.claude.com/docs/zh-TW/headless)中的 `/model` 命令以 `(run /model interactively to confirm)` 報告相同狀況在原因之後。從互動式工作階段進行切換，或更改 hook 對此模型的決定。2912* **`confirmation required, and this session cannot ask`**：hook 回答了 `ask` 而沒有原因，控制請求無法顯示確認提示。[`-p` 執行](https://code.claude.com/docs/zh-TW/headless)中的 `/model` 命令以 `(run /model interactively to confirm)` 報告相同狀況在原因之後。從互動式工作階段進行切換，或更改 hook 對此模型的決定。

2876* **`so organization-managed PreModelSwitch hooks could not be checked`**：Claude Code 無法判斷您組織的[受管外掛](https://code.claude.com/docs/zh-TW/settings-reference.md#enabledplugins)提供哪些 PreModelSwitch hook，例如因為受管外掛無法載入。其中一個 hook 可能會阻止切換，因此 Claude Code 拒絕而不是應用未檢查的切換。原因的開始命名失敗的內容。Claude Code 在每次切換嘗試時重新檢查，因此已清除的失敗停止阻止；如果它繼續失敗，請執行 `claude --debug` 並再次切換以捕獲詳細資訊，然後修復外掛或要求您的管理員修復它。2913* **`so organization-managed PreModelSwitch hooks could not be checked`**：v2.1.323 之前的 Claude Code 在無法判斷您的[受管外掛](https://code.claude.com/docs/zh-TW/settings-reference.md#enabledplugins)提供了哪些 PreModelSwitch hook 時會拒絕切換。此片語之前的文字會指出失敗的項目。若要停止拒絕，請更新 Claude Code。若要讓失敗外掛的 hook 也能執行，請修正該外掛或詢問您的管理員。如需詳細資訊，請在 shell 中啟動 `claude --debug` 並切換模型，然後閱讀[偵錯日誌](https://code.claude.com/docs/zh-TW/hooks.md#debug-hooks)。

2877* **`a PreModelSwitch hook failed before answering`** 或 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**：hook 執行在沒有判決的情況下結束，Claude Code 不將其視為核准。執行 `claude --debug` 以查看失敗的內容，然後再次切換。2914* **`a PreModelSwitch hook failed before answering`** 或 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**：hook 執行在沒有判決的情況下結束，Claude Code 不將其視為核准。執行 `claude --debug` 以查看失敗的內容，然後再次切換。

2878 2915

2879在 v2.1.260 之前，受管外掛拒絕讀取 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`。Claude Code 重試外掛載入一次，然後在工作階段中拒絕後續切換，即使您的組織沒有受管外掛。在這些版本上重新啟動工作階段以再次執行外掛載入。2916在 v2.1.260 之前，受管外掛拒絕讀取 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`。Claude Code 重試外掛載入一次，然後在工作階段中拒絕後續切換，即使您的組織沒有受管外掛。在這些版本上重新啟動工作階段以再次執行外掛載入。

3499* **`Error: Workspace not trusted. <folder> is your home directory`**：由於對家目錄的信任永遠不會被儲存，先在那裡執行 `claude` 並沒有幫助。請改從專案目錄執行 `claude ultrareview`（事先在那裡執行一次 `claude` 以接受信任對話框），或附加 `--trust-workspace`。3536* **`Error: Workspace not trusted. <folder> is your home directory`**：由於對家目錄的信任永遠不會被儲存，先在那裡執行 `claude` 並沒有幫助。請改從專案目錄執行 `claude ultrareview`（事先在那裡執行一次 `claude` 以接受信任對話框），或附加 `--trust-workspace`。

3500* **`No answer in time.` 後接 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 問題在 5 分鐘內未獲回答。請再次執行 `claude ultrareview` 並回答它。3537* **`No answer in time.` 後接 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 問題在 5 分鐘內未獲回答。請再次執行 `claude ultrareview` 並回答它。

3501* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 問題中拒絕了，例如回答 `n` 或按下 Enter。若要啟動審查，請再次執行 `claude ultrareview` 並回答 `y`。3538* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 問題中拒絕了，例如回答 `n` 或按下 Enter。若要啟動審查，請再次執行 `claude ultrareview` 並回答 `y`。

3502* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 後面接了旗標以外的內容，例如 PR 編號或 `false`。若您不信任該資料夾，請省略此旗標。若要在本次執行中信任它，請將 PR 編號或基底分支放在旗標之前：`claude ultrareview 1234 --trust-workspace`。3539* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 後面接了旗標以外的內容，例如 PR 編號或 `false`。如果您不信任該資料夾，請省略此旗標。若要在此次執行中信任它，請將 PR 編號或基礎分支放在旗標之前：`claude ultrareview 1234 --trust-workspace`。

3503 3540

3504在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。3541在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。

3505 3542

3522您在 `remote-control` 動詞之前加上了全域 `claude` 旗標來啟動 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md)，而該旗標會限制或設定 Remote Control 所啟動的工作階段，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在動詞之前的旗標永遠不會傳到這些工作階段。Claude Code 會改為拒絕啟動，並指出該旗標：3559您在 `remote-control` 動詞之前加上了全域 `claude` 旗標來啟動 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md)，而該旗標會限制或設定 Remote Control 所啟動的工作階段，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在動詞之前的旗標永遠不會傳到這些工作階段。Claude Code 會改為拒絕啟動，並指出該旗標：

3523 3560

3524```text theme={null}3561```text theme={null}

3525Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).3562Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`). Pass settings with `claude remote-control --settings <file>`.

3526```3563```

3527 3564

3528對於捨棄後無害的全域旗標，例如 `--verbose`、`--model`，或由包裝程式注入的 `--session-id` 或 `--plugin-dir`，Claude Code 不會拒絕：它會忽略這些旗標，Remote Control 會照常啟動。3565對於捨棄後無害的全域旗標，例如 `--verbose`、`--model`，或由包裝程式注入的 `--session-id` 或 `--plugin-dir`，Claude Code 不會拒絕：它會忽略這些旗標，Remote Control 會照常啟動。

3536 3573

3537在 v2.1.248 之前，當全域旗標在前時，`claude remote-control` 不接受其自身的旗標，該命令會以 `unknown option` 錯誤失敗。3574在 v2.1.248 之前，當全域旗標在前時，`claude remote-control` 不接受其自身的旗標，該命令會以 `unknown option` 錯誤失敗。

3538 3575

3576### Remote Control 因 `--settings` 檔案而未啟動

3577

3578您傳給 [`claude remote-control --settings`](https://code.claude.com/docs/zh-TW/remote-control#start-a-remote-control-session) 的檔案有問題：

3579

3580```text theme={null}

3581Error: Remote Control did not start, because sessions would skip part or all of the --settings file ./rc-settings.json: Invalid or malformed JSON

3582```

3583

3584**處理方式：**

3585

3586* 修正訊息所指出的問題，然後重新執行您的 `claude remote-control` 命令

3587

3588### The settings file has changed since Remote Control started

3589

3590在執行 `claude remote-control` 的終端機中出現此訊息，表示工作階段不會以您傳給 [`--settings`](https://code.claude.com/docs/zh-TW/remote-control#start-a-remote-control-session) 之檔案的目前內容啟動：

3591

3592```text theme={null}

3593Session failed: Error: The settings file /path/to/settings.json has changed since Remote Control started, so this session did not start. Restart `claude remote-control` to use it as it is now.

3594```

3595

3596**處理方式：**

3597

3598* 若要使用該檔案的目前內容，請停止 `claude remote-control` 並重新執行相同的命令。若要找回它原本服務的工作階段，請參閱[停止伺服器後繼續工作階段](https://code.claude.com/docs/zh-TW/remote-control.md#resume-sessions-after-stopping-the-server)。

3599* 若要保留 Remote Control 啟動時所使用的設定，請將檔案內容還原為原本的樣子，若 `claude remote-control` 已結束，再重新執行命令

3600

3539### `--sandbox` or `--no-sandbox` is not supported by claude remote-control3601### `--sandbox` or `--no-sandbox` is not supported by claude remote-control

3540 3602

3541此錯誤表示啟動您 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 伺服器的命令在 `remote-control` 之後傳入了 `--sandbox` 或 `--no-sandbox`，而 `claude remote-control` 兩者皆不接受。伺服器會以退出碼 1 結束，而不會啟動：3603此錯誤表示啟動您 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 伺服器的命令在 `remote-control` 之後傳入了 `--sandbox` 或 `--no-sandbox`，而 `claude remote-control` 兩者皆不接受。伺服器會以退出碼 1 結束，而不會啟動：

3806 3868

3807以下同類字串會在命令執行之前就觸發：3869以下同類字串會在命令執行之前就觸發：

3808 3870

3809* `Shell command permission check failed for pattern "..."`：命令的權限檢查未允許它。[注入命令的權限檢查](https://code.claude.com/docs/zh-TW/skills.md#permission-checks-on-injected-commands)說明了在各權限模式下哪些結果會中止，以及如何以 `allowed-tools` 預先核准命令3871* `Shell command permission check failed for pattern "..."`：命令的權限檢查未允許它。請參閱[注入命令的權限檢查](https://code.claude.com/docs/zh-TW/skills.md#permission-checks-on-injected-commands)，了解在各權限模式下哪些結果會中止，以及 `allowed-tools` 何時會預先核准命令

3810* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：skill 的 frontmatter 要求 bash，但機器上沒有 bash。請安裝 Git for Windows，或將 frontmatter 改為 `shell: powershell`。請參閱[注入命令的執行方式](https://code.claude.com/docs/zh-TW/skills.md#how-injected-commands-run)3872* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：該 skill 的 frontmatter 要求 bash，但電腦上沒有 bash。請安裝 Git for Windows，或將 frontmatter 改為 `shell: powershell`。請參閱[注入命令的執行方式](https://code.claude.com/docs/zh-TW/skills.md#how-injected-commands-run)

3811 3873

3812**處理方式：**3874**處理方式：**

3813 3875

3960 4022

3961* **您沒有傳入基底分支**：Claude Code 與儲存庫的預設分支進行比較，並建議您明確傳入基底分支，如上例所示4023* **您沒有傳入基底分支**：Claude Code 與儲存庫的預設分支進行比較，並建議您明確傳入基底分支，如上例所示

3962* **您傳入的基底分支已存在於您的複製中**：提示內容為 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``4024* **您傳入的基底分支已存在於您的複製中**：提示內容為 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

3963* **您傳入的基礎分支不在您的複製中**：Claude Code 在比較前從 origin 擷取了該分支。提示內容為 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；當 Claude Code 無法判斷您的複製是否為淺層複製時，會改為建議 `git fetch --unshallow origin`。在 v2.1.221 之前，對於每個擷取的基礎分支，提示都會建議 `git fetch --unshallow origin`，而在完整的複製上，該命令會失敗並顯示 `fatal: --unshallow on a complete repository does not make sense`。4025* **您傳入的基礎分支不在您的 clone 中**：Claude Code 在比較之前會先從 origin 擷取它。提示內容為 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；當 Claude Code 無法判斷您的 clone 是否為淺層 clone 時，則會改為建議 `git fetch --unshallow origin`。在 v2.1.221 之前，提示會對每個擷取的基礎分支都建議 `git fetch --unshallow origin`，而在完整的 clone 上，該命令會以 `fatal: --unshallow on a complete repository does not make sense` 失敗。

3964 4026

3965**處理方式：**4027**處理方式：**

3966 4028

4490commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory4552commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

4491```4553```

4492 4554

4493如果訊息提供了 marketplace plugin 自身檔案之一（例如 `hooks/hooks.json`）的完整路徑，表示 Claude Code 略過了該檔案。當 Claude Code 無法確認該檔案位於 plugin 內，或者對於 [本機 marketplace](https://code.claude.com/docs/zh-TW/plugins/loading.md#in-place-and-copied-plugins) 中的 plugin，無法確認該檔案位於該 marketplace 內時，就會發生這種情況。訊息會以下列所示的元件名稱回報這些檔案：4555如果訊息提供了 marketplace plugin 自身檔案之一（例如 `hooks/hooks.json`）的完整路徑，表示 Claude Code 略過了該檔案。當 Claude Code 無法確認該檔案位於 plugin 內，或者對於 [本機 marketplace](https://code.claude.com/docs/zh-TW/plugins/loading.md#in-place-and-copied-plugins) 中的 plugin，無法確認該檔案位於該 marketplace 內時，就會略過該檔案。訊息會以下列所示的元件名稱回報這些檔案：

4494 4556

4495* `hooks/hooks.json`：`hooks`4557* `hooks/hooks.json`：`hooks`

4496* `monitors/monitors.json`：`monitors`4558* `monitors/monitors.json`：`monitors`

4497* `settings.json`：`settings`

4498* plugin 根目錄的 `SKILL.md`：`skills`4559* plugin 根目錄的 `SKILL.md`：`skills`

4499 4560

4500例如，以下訊息針對的是解析到 plugin 及其本機 marketplace 兩者之外的 `hooks/hooks.json`：4561例如，以下訊息針對的是解析到 plugin 及其本機 marketplace 兩者之外的 `hooks/hooks.json`：

5481您開啟了在背景服務關閉時結束的[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)，而[逐字稿清理](https://code.claude.com/docs/zh-TW/settings-reference.md#cleanupperioddays)已移除其已儲存的對話，例如在機器關閉數週後。通常開啟這樣的列會[繼續其已儲存的對話](https://code.claude.com/docs/zh-TW/agent-view.md#sessions-show-as-failed-after-shutdown)。由於沒有可繼續的內容，Claude Code 會拒絕，而不是在不詢問的情況下重新執行工作階段的原始提示詞：5542您開啟了在背景服務關閉時結束的[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)，而[逐字稿清理](https://code.claude.com/docs/zh-TW/settings-reference.md#cleanupperioddays)已移除其已儲存的對話，例如在機器關閉數週後。通常開啟這樣的列會[繼續其已儲存的對話](https://code.claude.com/docs/zh-TW/agent-view.md#sessions-show-as-failed-after-shutdown)。由於沒有可繼續的內容，Claude Code 會拒絕，而不是在不詢問的情況下重新執行工作階段的原始提示詞：

5482 5543

5483```text theme={null}5544```text theme={null}

5484This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.5545This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` removes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.

5485```5546```

5486 5547

5487`claude attach <id>` 列印此文字。在 agent 檢視中，頁腳較短，以 `ctrl+x deletes the row` 結尾。5548`claude attach <id>` 列印此文字。在 agent 檢視中，頁腳較短，以 `ctrl+x removes the row` 結尾。

5488 5549

5489**該怎麼做：**5550**該怎麼做：**

5490 5551

5503 push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef5564 push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef

5504```5565```

5505 5566

5506當 Claude Code 無法總結提交時，詳細行改為顯示 `The worktree has unpushed commits`。在 [agent 檢視](https://code.claude.com/docs/zh-TW/agent-view.md)中，工作階段的列顯示 `not deleted`，原因相同。5567當 Claude Code 無法總結提交時，詳細行改為顯示 `The worktree has unpushed commits`。在 [agent 檢視](https://code.claude.com/docs/zh-TW/agent-view.md)中，工作階段的列顯示 `not removed`，原因相同。

5507 5568

5508遠端上的提交不會阻止刪除。您的 `origin` 遠端預設分支的本機副本上的提交也不會，只要該分支在您的主簽出（即儲存庫目錄本身而不是 worktree）中簽出。5569遠端上的提交不會阻止刪除。您的 `origin` 遠端預設分支的本機副本上的提交也不會，只要該分支在您的主簽出（即儲存庫目錄本身而不是 worktree）中簽出。

5509 5570

5780 5841

5781這些錯誤來自啟動 Claude Code 的程式，例如 IDE 擴充功能或 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 應用程式，而不是來自 Claude Code 本身。5842這些錯誤來自啟動 Claude Code 的程式，例如 IDE 擴充功能或 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 應用程式，而不是來自 Claude Code 本身。

5782 5843

5844### Subprocess initialization did not complete within 60000ms

5845

5846此錯誤表示由 [VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md)或 Agent SDK 應用程式啟動的 Claude Code 程序，未能及時回報其已準備就緒。擴充功能或應用程式隨後將其停止。在 VS Code 對話中，錯誤以 `Claude Code did not finish starting` 開頭，例如：

5847

5848```text theme={null}

5849Claude Code did not finish starting: it did not answer in time. The output logs ("View output logs") show how far it got. Slow plugins, MCP servers, hooks, disks or network can each cause this.

5850```

5851

5852在擴充功能的輸出日誌、其登入畫面以及 Agent SDK 應用程式中，錯誤的措辭有所不同。它以 `Subprocess initialization did not complete within` 和時間限制開頭，接著提供 Claude Code 所回報的內容，例如：

5853

5854```text theme={null}

5855Subprocess initialization did not complete within 60000ms. Claude Code did not answer the initialize request and reported no SessionStart or Setup hook running. Slow plugins, MCP servers, hooks that Claude Code does not report, disks or network can each cause this.

5856```

5857

5858**該怎麼做：**

5859

5860* 若要在 VS Code 中重試，請傳送一則訊息。如果錯誤是在您登入時出現，請改為再次選擇登入方式。

5861* 若要查看 Claude Code 進行到哪個階段，請點擊對話錯誤下方的 **View output logs**，或從 Command Palette 執行 **Claude Code: Show Logs**。在[回報問題](https://github.com/anthropics/claude-code/issues)時，請附上 `Subprocess initialization` 那一行前後的項目。

5862* 若要檢查網路，請參閱[網路設定](https://code.claude.com/docs/zh-TW/network-config.md)。如果訊息要求您檢查登入或身分驗證，請參閱[登入和身分驗證](https://code.claude.com/docs/zh-TW/troubleshoot-install.md#login-and-authentication)。

5863* 如果訊息指出 [SessionStart](https://code.claude.com/docs/zh-TW/hooks.md#sessionstart) 或 [Setup](https://code.claude.com/docs/zh-TW/hooks.md#setup) hook 尚未完成，請[檢查您的 hook 執行多久](https://code.claude.com/docs/zh-TW/hooks.md#debug-hooks)。在 VS Code 中，Claude Code 回報這些 hook 正在執行的前 10 分鐘不計入 60 秒限制。請讓緩慢的 hook 更快完成、調低非非同步 hook 的 [`timeout`](https://code.claude.com/docs/zh-TW/hooks#common-fields)，或[移除該 hook](https://code.claude.com/docs/zh-TW/hooks.md#disable-or-remove-hooks)。

5864* 如果您的 Agent SDK 應用程式呼叫 [`startup()`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#startup)，請將 `initializeTimeoutMs` 設定為足以涵蓋整個啟動過程的長度，或保持不設定，使最多 10 分鐘的已回報 hook 時間不計入限制。

5865

5866在 VS Code 擴充功能 v2.1.304 和 TypeScript Agent SDK v0.3.304 之前，所有 hook 時間都會計入限制。在預設限制下，訊息包含 `Subprocess initialization did not complete within 60000ms — check authentication and network connectivity`。如果您看到該措辭，請更新擴充功能或 SDK。

5867

5783### Claude Code 程序以代碼 N 結束5868### Claude Code 程序以代碼 N 結束

5784 5869

5785底層 `claude` 程序以非零代碼結束。結束代碼本身不會說明失敗的原因：真正的錯誤在於程序自己的輸出，包裝程式會在捕獲時附加該輸出，否則將其保留在日誌中。5870底層 `claude` 程序以非零代碼結束。結束代碼本身不會說明失敗的原因：真正的錯誤在於程序自己的輸出，包裝程式會在捕獲時附加該輸出，否則將其保留在日誌中。

feature-availability.md +14 −4

Details

117 <td>✗</td>117 <td>✗</td>

118 </tr>118 </tr>

119 119

120 <tr>

121 <td>[Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md)</td>

122 <td>✓（實驗性功能，[有相關需求](https://code.claude.com/docs/zh-TW/code-mode.md#requirements)）</td>

123 <td>✓（實驗性功能，[有相關需求](https://code.claude.com/docs/zh-TW/code-mode.md#requirements)）</td>

124 <td>✗</td>

125 <td>✗</td>

126 <td>✗</td>

127 <td>✗</td>

128 </tr>

129

120 <tr>130 <tr>

121 <td>[跨工作階段訊息傳遞](https://code.claude.com/docs/zh-TW/cross-session-messaging.md)</td>131 <td>[跨工作階段訊息傳遞](https://code.claude.com/docs/zh-TW/cross-session-messaging.md)</td>

122 <td>✓ <sup>[5](#fn5)</sup></td>132 <td>✓ <sup>[5](#fn5)</sup></td>

231 241

232> [tab] Amazon Bedrock242> [tab] Amazon Bedrock

233>243>

234> \*\*無法使用：\*\*所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，以及[網頁搜尋](https://code.claude.com/docs/zh-TW/tools-reference.md#websearch-tool-behavior)、[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)、[Advisor](https://code.claude.com/docs/zh-TW/advisor.md)、[頻道](https://code.claude.com/docs/zh-TW/channels.md)、[分析儀表板](https://code.claude.com/docs/zh-TW/analytics.md)、[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，以及 [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)。244> \*\*無法使用：\*\*所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，以及[網頁搜尋](https://code.claude.com/docs/zh-TW/tools-reference.md#websearch-tool-behavior)、[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)、[Advisor](https://code.claude.com/docs/zh-TW/advisor.md)、[頻道](https://code.claude.com/docs/zh-TW/channels.md)、[Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md)、[分析儀表板](https://code.claude.com/docs/zh-TW/analytics.md)、[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，以及 [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)。

235>245>

236> **部分支援：**246> **部分支援：**

237>247>

244 254

245> [tab] Claude Platform on AWS255> [tab] Claude Platform on AWS

246>256>

247> \*\*無法使用：\*\*所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，以及[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)、[頻道](https://code.claude.com/docs/zh-TW/channels.md)、[GitHub Actions](https://code.claude.com/docs/zh-TW/github-actions.md)、[分析儀表板](https://code.claude.com/docs/zh-TW/analytics.md)、[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，以及 [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)。257> \*\*無法使用：\*\*所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，以及[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)、[頻道](https://code.claude.com/docs/zh-TW/channels.md)、[GitHub Actions](https://code.claude.com/docs/zh-TW/github-actions.md)、[Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md)、[分析儀表板](https://code.claude.com/docs/zh-TW/analytics.md)、[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，以及 [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)。

248>258>

249> **Amazon Bedrock 不支援但此處可用：**[網頁搜尋](https://code.claude.com/docs/zh-TW/tools-reference.md#websearch-tool-behavior)，以及 Claude Code v2.1.300 或更新版本中的 [Advisor](https://code.claude.com/docs/zh-TW/advisor.md)。259> **Amazon Bedrock 不支援但此處可用：**[網頁搜尋](https://code.claude.com/docs/zh-TW/tools-reference.md#websearch-tool-behavior)，以及 Claude Code v2.1.300 或更新版本中的 [Advisor](https://code.claude.com/docs/zh-TW/advisor.md)。

250>260>

256 266

257> [tab] Google Cloud's Agent Platform267> [tab] Google Cloud's Agent Platform

258>268>

259> \*\*無法使用：\*\*所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，以及 [Advisor](https://code.claude.com/docs/zh-TW/advisor.md)、[頻道](https://code.claude.com/docs/zh-TW/channels.md)、[分析儀表板](https://code.claude.com/docs/zh-TW/analytics.md)、[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，以及 [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)。269> \*\*無法使用：\*\*所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，以及 [Advisor](https://code.claude.com/docs/zh-TW/advisor.md)、[頻道](https://code.claude.com/docs/zh-TW/channels.md)、[Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md)、[分析儀表板](https://code.claude.com/docs/zh-TW/analytics.md)、[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，以及 [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)。

260>270>

261> **部分支援：**271> **部分支援：**

262>272>

271 281

272> [tab] Microsoft Foundry282> [tab] Microsoft Foundry

273>283>

274> \*\*無法使用：\*\*所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，以及[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)、[Advisor](https://code.claude.com/docs/zh-TW/advisor.md)、[頻道](https://code.claude.com/docs/zh-TW/channels.md)、[GitLab CI/CD](https://code.claude.com/docs/zh-TW/gitlab-ci-cd.md)、[分析儀表板](https://code.claude.com/docs/zh-TW/analytics.md)、[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，以及 [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)。284> \*\*無法使用：\*\*所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，以及[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)、[Advisor](https://code.claude.com/docs/zh-TW/advisor.md)、[頻道](https://code.claude.com/docs/zh-TW/channels.md)、[GitLab CI/CD](https://code.claude.com/docs/zh-TW/gitlab-ci-cd.md)、[Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md)、[分析儀表板](https://code.claude.com/docs/zh-TW/analytics.md)、[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，以及 [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)。

275>285>

276> **部分支援：**286> **部分支援：**

277>287>

gateways.md +1 −1

Details

63* **用戶端遙測**：當工作階段登入 Claude 應用程式閘道時，Claude Code 會停用其 Anthropic 繫結的用戶端分析。若要同時關閉登入前啟動分析，請在每個裝置上的 [用戶端側受管設定](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#client-side-managed-settings) 中傳遞 [`DISABLE_TELEMETRY`](https://code.claude.com/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization)。63* **用戶端遙測**：當工作階段登入 Claude 應用程式閘道時，Claude Code 會停用其 Anthropic 繫結的用戶端分析。若要同時關閉登入前啟動分析，請在每個裝置上的 [用戶端側受管設定](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#client-side-managed-settings) 中傳遞 [`DISABLE_TELEMETRY`](https://code.claude.com/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization)。

64* **其他閘道上的用戶端遙測**：Claude Code 是否傳送可選用戶端遙測流取決於您的提供者，[遙測預設值表](https://code.claude.com/docs/zh-TW/data-usage.md#default-behaviors-by-api-provider) 涵蓋每種情況。64* **其他閘道上的用戶端遙測**：Claude Code 是否傳送可選用戶端遙測流取決於您的提供者，[遙測預設值表](https://code.claude.com/docs/zh-TW/data-usage.md#default-behaviors-by-api-provider) 涵蓋每種情況。

65* **遙測目的地**：Claude Code 傳送閘道工作階段遙測的位置取決於工作階段如何登入，[開發人員上強制執行的項目](https://code.claude.com/docs/zh-TW/claude-apps-gateway#whats-enforced-on-developers) 說明每種工作階段的匯出位置。65* **遙測目的地**：Claude Code 傳送閘道工作階段遙測的位置取決於工作階段如何登入，[開發人員上強制執行的項目](https://code.claude.com/docs/zh-TW/claude-apps-gateway#whats-enforced-on-developers) 說明每種工作階段的匯出位置。

66* **公司 HTTP 代理**：`HTTPS_PROXY` 位於 Claude Code 和它與之通訊的每個伺服器之間，包括閘道。如果您的網路需要一個，[配置代理](https://code.claude.com/docs/zh-TW/network-config.md) 以及閘道。對於您託管的 Claude 應用程式閘道，[登入檢查代理主機也在私人網路上](https://code.claude.com/docs/zh-TW/claude-apps-gateway#prerequisites)；如果不是，將閘道主機新增到 `NO_PROXY`，以便 CLI 直接連接到它。66* **公司 HTTP 代理伺服器**：Claude Code 會透過 `HTTPS_PROXY` 中的代理伺服器傳送其請求，包括傳送至閘道的請求。如果您的網路需要代理伺服器，請[設定它](https://code.claude.com/docs/zh-TW/network-config.md)。如果代理伺服器適用於您託管的 Claude 應用程式閘道，[登入](https://code.claude.com/docs/zh-TW/claude-apps-gateway#prerequisites)需要代理伺服器的主機名稱解析為私人位址，或需要將閘道主機加入 `NO_PROXY`。

67 67

68## 後續步驟68## 後續步驟

69 69

github-actions.md +1 −0

Details

129| Administration | 讀取 |129| Administration | 讀取 |

130| Checks | 讀取和寫入 |130| Checks | 讀取和寫入 |

131| Contents | 讀取和寫入 |131| Contents | 讀取和寫入 |

132| Dependabot alerts | 讀取 |

132| Discussions | 讀取和寫入 |133| Discussions | 讀取和寫入 |

133| Issues | 讀取和寫入 |134| Issues | 讀取和寫入 |

134| Members | 讀取 |135| Members | 讀取 |

github-actions-cloud-providers.md +2 −2

Details

83>83>

84> 按照 [Microsoft 從 GitHub Actions 驗證指南](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect)，建立具有儲存庫聯盟認證的 Microsoft Entra 應用程式：84> 按照 [Microsoft 從 GitHub Actions 驗證指南](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect)，建立具有儲存庫聯盟認證的 Microsoft Entra 應用程式：

85>85>

86> * 註冊 Microsoft Entra 應用程式並新增聯盟身分識別認證，該認證信任 GitHub 向您的儲存庫發出的權杖。使用者指派的受管身分識別可以代替應用程式。兩者都有您在下面記下的用戶端 ID86> * 註冊 Microsoft Entra 應用程式並新增聯盟身分識別憑證，該憑證信任 GitHub 向您的儲存庫發出的權杖。使用者指派的受管身分識別可以代替應用程式。兩者都有您在下面記下的用戶端 ID

87> * 在您的 Foundry 資源上為應用程式指派 `Azure AI User` 角色。請參閱 [Azure RBAC 設定](https://code.claude.com/docs/zh-TW/microsoft-foundry.md#azure-rbac-configuration)以了解更窄的自訂角色87> * 在您的 Foundry 資源上為應用程式指派 `Foundry User` 角色。請參閱 [Azure RBAC 設定](https://code.claude.com/docs/zh-TW/microsoft-foundry.md#azure-rbac-configuration)以了解另一個內建角色和自訂角色

88>88>

89> 記下應用程式的用戶端 ID、您的租用戶 ID 和您的訂閱 ID。您將在下一步中將它們新增為密鑰。89> 記下應用程式的用戶端 ID、您的租用戶 ID 和您的訂閱 ID。您將在下一步中將它們新增為密鑰。

90 90

google-vertex-ai.md +8 −3

Details

228 228

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

230 230

231如果您的專案失去對工作階段執行所在模型的存取權，例如因為管理員在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中停用它，Claude Code 會將工作階段切換到另一個模型，而不是讓每個請求都失敗，並顯示 `Switched to <fallback> because <model> is not available`。它會嘗試與啟動回退相同的模型：先嘗試相同層級的較早版本，對於沒有可用 Opus 版本的 Opus 工作階段，則嘗試預設 Sonnet 模型。231當 Agent Platform 以工作階段的模型在您的專案或區域中無法使用為由拒絕時，Claude Code 會將您的工作階段切換到另一個模型，讓您可以繼續工作。您會看到一則以 `Switched to <fallback> because <model> is not available` 開頭的訊息。例如，當管理員在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中停用該模型，或該模型未在您的區域中提供時，就會發生這種情況。

232 232

233切換僅適用於您未固定的層級，這與啟動回退的條件相同。在您選擇的特定版本上的工作階段會保持其模型，且沒有回退模型鏈，請求會失敗。在 [auto mode](https://code.claude.com/docs/zh-TW/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry) 中，Claude Code 只會切換到 Agent Platform 上 auto mode 支援的模型。如果這些模型都無法使用，請求會失敗。233如果您設定了[備援模型鏈](https://code.claude.com/docs/zh-TW/model-config.md#fallback-model-chains)，Claude Code 會改為切換到您設定的備援。若沒有模型鏈，請求會在下列情況下失敗：

234 234

235您設定的[回退模型鏈](https://code.claude.com/docs/zh-TW/model-config.md#fallback-model-chains)會取代層級切換：在這些拒絕上，Claude Code 會切換到您設定的回退。若要讓被拒絕的請求失敗而不是切換，請設定 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/zh-TW/env-vars)。您設定的回退鏈仍會在這些拒絕上切換；如果您想讓每個被拒絕的請求都失敗，也請移除該鏈。235* 您的工作階段使用的是固定模型或您選擇的特定版本

236* [Claude Code 嘗試的模型](#startup-model-checks)都無法使用。在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry)中，Claude Code 只會切換到 Agent Platform 上自動模式支援的模型。

237

238若要繼續工作，請在工作階段中執行 `/model`，並在您的專案和區域中可用的模型上按 `s`，這樣不會變更您的預設值。

239

240若要讓被拒絕的請求失敗而不是切換，請設定 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/zh-TW/env-vars)。如果您設定了備援模型鏈，也請將其移除，因為 Claude Code 仍會切換到該備援。

236 241

237## IAM 設定242## IAM 設定

238 243

hooks.md +22 −7

Details

257管理員可以在[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中使用 [`allowManagedHooksOnly`](https://code.claude.com/docs/zh-TW/settings-reference#allowmanagedhooksonly) 來限制可執行的 hook：257管理員可以在[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中使用 [`allowManagedHooksOnly`](https://code.claude.com/docs/zh-TW/settings-reference#allowmanagedhooksonly) 來限制可執行的 hook：

258 258

259* 您的使用者、專案、本機及外掛 hook 會被封鎖。在受管設定 `enabledPlugins` 中強制啟用的外掛所提供的 hook 不受此限259* 您的使用者、專案、本機及外掛 hook 會被封鎖。在受管設定 `enabledPlugins` 中強制啟用的外掛所提供的 hook 不受此限

260* Claude Code 也會將您的 [`statusLine`](https://code.claude.com/docs/zh-TW/statusline)、[`fileSuggestion`](https://code.claude.com/docs/zh-TW/settings-reference#filesuggestion) 與 [`subagentStatusLine`](https://code.claude.com/docs/zh-TW/statusline#subagent-status-lines) 設定限縮為僅採用受管設定260* Claude Code 也會將您的 [`statusLine`](https://code.claude.com/docs/zh-TW/statusline) 與 [`fileSuggestion`](https://code.claude.com/docs/zh-TW/settings-reference#filesuggestion) 設定限縮為僅採用受管設定

261* 除非 [`disableCommandPluginSources`](https://code.claude.com/docs/zh-TW/settings-reference#disablecommandpluginsources) 明確設為 `false`，否則 Claude Code 也會停用具有 [`command` 來源](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)的外掛，包括在受管設定 `enabledPlugins` 中強制啟用的外掛。`command` 來源需要 Claude Code v2.1.229 或更新版本261* 除非 [`disableCommandPluginSources`](https://code.claude.com/docs/zh-TW/settings-reference#disablecommandpluginsources) 明確設為 `false`，否則 Claude Code 也會停用具有 [`command` 來源](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)的外掛，包括在受管設定 `enabledPlugins` 中強制啟用的外掛。`command` 來源需要 Claude Code v2.1.229 或更新版本

262* 除非 [`disableCommandPluginSources`](https://code.claude.com/docs/zh-TW/settings-reference#disablecommandpluginsources) 明確設為 `false`，否則 Claude Code 也會封鎖市集的 [`headersHelper` 命令](https://code.claude.com/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，但受管設定本身宣告的市集除外262* 除非 [`disableCommandPluginSources`](https://code.claude.com/docs/zh-TW/settings-reference#disablecommandpluginsources) 明確設為 `false`，否則 Claude Code 也會封鎖市集的 [`headersHelper` 命令](https://code.claude.com/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，但受管設定本身宣告的市集除外

263 263

505| `url` | 是 | POST 請求要傳送到的 URL |505| `url` | 是 | POST 請求要傳送到的 URL |

506| `headers` | 否 | 以鍵值對表示的額外 HTTP 標頭。值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法插入環境變數。只有列在 `allowedEnvVars` 中的變數會被解析 |506| `headers` | 否 | 以鍵值對表示的額外 HTTP 標頭。值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法插入環境變數。只有列在 `allowedEnvVars` 中的變數會被解析 |

507| `allowedEnvVars` | 否 | 可插入標頭值中的環境變數名稱清單。對未列出之變數的參照會被替換為空字串。任何環境變數插入都必須設定此欄位才能運作 |507| `allowedEnvVars` | 否 | 可插入標頭值中的環境變數名稱清單。對未列出之變數的參照會被替換為空字串。任何環境變數插入都必須設定此欄位才能運作 |

508| `onFailure` | 否 | hook 失敗時該動作的處理方式：`"continue"`（預設）或 `"block"`。請參閱[在 hook 失敗時封鎖動作](#block-the-action-when-a-hook-fails)。需要 Claude Code v2.1.295 或更新版本 |508| `onFailure` | 否 | hook 失敗時，觸發該 hook 的動作是否繼續進行：`"continue"` 或 `"block"`。關於 `"block"` 以及未設定此欄位時的行為，請參閱[在 hook 失敗時封鎖動作](#block-the-action-when-a-hook-fails)。需要 Claude Code v2.1.295 或更新版本 |

509 509

510Claude Code 會將 hook 的 [JSON 輸入](#hook-input-and-output)作為 POST 請求主體傳送，並帶有 `Content-Type: application/json`。回應主體使用與命令 hook 相同的 [JSON 輸出格式](#json-output)。510Claude Code 會將 hook 的 [JSON 輸入](#hook-input-and-output)作為 POST 請求主體傳送，並帶有 `Content-Type: application/json`。回應主體使用與命令 hook 相同的 [JSON 輸出格式](#json-output)。

511 511

901 901

902在 `PreToolUse` 上，逾時的 `command`、`http` 或 `mcp_tool` hook 不阻止工具呼叫，但 [失敗時會阻止操作的 hook](#block-the-action-when-a-hook-fails) 除外。呼叫透過正常 [權限流程](https://code.claude.com/docs/zh-TW/permissions.md) 繼續，因此不要指望停滯的 hook 充當閘門。要在 `command` 或 `http` hook 逾時時阻止呼叫，請設定 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)。超過其逾時的 [Agent SDK 回呼 hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md) [會阻止工具呼叫](#pretooluse)。902在 `PreToolUse` 上，逾時的 `command`、`http` 或 `mcp_tool` hook 不阻止工具呼叫，但 [失敗時會阻止操作的 hook](#block-the-action-when-a-hook-fails) 除外。呼叫透過正常 [權限流程](https://code.claude.com/docs/zh-TW/permissions.md) 繼續，因此不要指望停滯的 hook 充當閘門。要在 `command` 或 `http` hook 逾時時阻止呼叫，請設定 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)。超過其逾時的 [Agent SDK 回呼 hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md) [會阻止工具呼叫](#pretooluse)。

903 903

904> [!NOTE]

905>

906> 如果您使用 Code Mode，`PreToolUse` 上的逾時運作方式不同。請參閱[遭 hook 拒絕的工具呼叫](https://code.claude.com/docs/zh-TW/code-mode.md#tool-call-refused-by-a-hook)。

907

904#### 啟動背景程序的 hook908#### 啟動背景程序的 hook

905 909

906hook 可以啟動長時間執行的程式（例如開發伺服器），並在工作階段繼續進行時讓它保持執行。在 hook 的指令碼或 [shell 形式](#exec-form-and-shell-form) 命令中：910hook 可以啟動長時間執行的程式（例如開發伺服器），並在工作階段繼續進行時讓它保持執行。在 hook 的指令碼或 [shell 形式](#exec-form-and-shell-form) 命令中：

981* **`Stop`、`SubagentStop`、`TaskCompleted` 和 `TeammateIdle` hook**：在這些事件上，退出碼 2 會讓 Claude 回去繼續工作，而 Claude 無法修復無法執行的 hook985* **`Stop`、`SubagentStop`、`TaskCompleted` 和 `TeammateIdle` hook**：在這些事件上，退出碼 2 會讓 Claude 回去繼續工作，而 Claude 無法修復無法執行的 hook

982* **背景命令 hook**：設定 [`async` 或 `asyncRewake`](#run-hooks-in-the-background) 的命令 hook986* **背景命令 hook**：設定 [`async` 或 `asyncRewake`](#run-hooks-in-the-background) 的命令 hook

983 987

988> [!NOTE]

989>

990> 如果您使用 Code Mode，`PreToolUse` 上的失敗運作方式不同。請參閱[遭 hook 拒絕的工具呼叫](https://code.claude.com/docs/zh-TW/code-mode.md#tool-call-refused-by-a-hook)。

991

984#### Windows 上沒有 Git Bash 時失敗的 hook992#### Windows 上沒有 Git Bash 時失敗的 hook

985 993

986如果被阻止的工具呼叫的錯誤包含以下文字，表示某個 `PreToolUse` 或 `PermissionRequest` 命令 hook 失敗或逾時，並阻止了該呼叫：994如果被阻止的工具呼叫的錯誤包含以下文字，表示某個 `PreToolUse` 或 `PermissionRequest` 命令 hook 失敗或逾時，並阻止了該呼叫：

1512* [工作階段範圍的排程任務](https://code.claude.com/docs/zh-TW/scheduled-tasks.md)觸發時，包括 `/loop` 的每次迭代1520* [工作階段範圍的排程任務](https://code.claude.com/docs/zh-TW/scheduled-tasks.md)觸發時，包括 `/loop` 的每次迭代

1513* [背景 subagent](https://code.claude.com/docs/zh-TW/sub-agents.md#run-subagents-in-foreground-or-background) 向啟動它的工作階段回報時1521* [背景 subagent](https://code.claude.com/docs/zh-TW/sub-agents.md#run-subagents-in-foreground-or-background) 向啟動它的工作階段回報時

1514* [另一個工作階段傳送訊息](https://code.claude.com/docs/zh-TW/cross-session-messaging.md)到您的主要對話時1522* [另一個工作階段傳送訊息](https://code.claude.com/docs/zh-TW/cross-session-messaging.md)到您的主要對話時

1523* 在 [Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md#code-output-withheld-by-a-hook) 工作階段中，當程式碼可以在背景執行時，Claude 程式碼的輸出（適用於 `command`、`http` 與 `mcp_tool` hook）

1515 1524

1516`UserPromptSubmit` hook 對於 `command`、`http` 和 `mcp_tool` 類型的預設逾時為 30 秒，短於這些類型在大多數其他事件上的 600 秒預設值。由於此 hook 在每個提示詞之前執行，並會阻擋模型處理直到完成，卡住的 hook 會使工作階段停滯。若您的 hook 需要更多時間，請在 hook 項目中設定 `timeout` 欄位。1525`UserPromptSubmit` hook 對於 `command`、`http` 和 `mcp_tool` 類型的預設逾時為 30 秒，短於這些類型在大多數其他事件上的 600 秒預設值。由於此 hook 在每個提示詞之前執行，並會阻擋模型處理直到完成，卡住的 hook 會使工作階段停滯。若您的 hook 需要更多時間，請在 hook 項目中設定 `timeout` 欄位。

1517 1526

1560| 欄位 | 說明 |1569| 欄位 | 說明 |

1561| :- | :- |1570| :- | :- |

1566| `suppressOriginalPrompt` | 若 hook 阻擋提示詞時此值為 `true`，阻擋訊息中將不包含提示詞文字。請參閱[被阻擋的提示詞會留下什麼](#what-a-blocked-prompt-leaves-behind) |1575| `suppressOriginalPrompt` | 若 hook 阻擋提示詞時此值為 `true`，阻擋訊息中將不包含提示詞文字。請參閱[被阻擋的提示詞會留下什麼](#what-a-blocked-prompt-leaves-behind) |

1567 1576

1568以退出碼 2 阻擋的 hook，其處理方式與 `reason` 相同：阻擋訊息會向使用者顯示 stderr 文字，且不會加入情境。1577若您的 hook 以退出碼 2 阻擋，其 stderr 文字的處理方式與 `reason` 相同。

1569 1578

1570```json theme={null}1579```json theme={null}

1571{1580{

2999 3008

3000在工作階段期間設定檔變更時執行。可用於稽核設定變更、強制執行安全政策，或封鎖對設定檔的未經授權修改。3009在工作階段期間設定檔變更時執行。可用於稽核設定變更、強制執行安全政策，或封鎖對設定檔的未經授權修改。

3001 3010

3002當設定檔、受管政策檔案或 skill 檔案變更時，Claude Code 會執行 ConfigChange hook。對於受管政策，只有在 `managed-settings.json` 或 `managed-settings.d/` 中的檔案變更時才會執行。它會套用[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)以及 macOS 受管偏好設定或 Windows 登錄政策的變更，但不會執行這些 hook。在啟用 [`wslInheritsWindowsSettings`](https://code.claude.com/docs/zh-TW/settings-reference#wslinheritswindowssettings) 的 WSL 上，它也會在政策輪詢時套用已變更的 Windows 端受管設定檔，而不執行這些 hook。3011當設定檔、受管原則檔案或 skill 檔案變更時，Claude Code 會執行 ConfigChange hook。對於受管原則，只有在 `managed-settings.json` 或 `managed-settings.d/` 中的檔案變更時才會執行。

3003 3012

3004matcher 依設定來源進行篩選：3013matcher 依設定來源進行篩選：

3005 3014

3013 3022

3014以下範例會記錄所有設定變更以進行安全稽核：3023以下這類變更會在不執行 hook 的情況下生效：

3024

3025* 透過 **Yes, and don't ask again**、`/permissions` 或 `/model` 儲存的規則與設定，在您儲存它們的那個工作階段中。若另一個開啟中的工作階段載入同一個檔案，hook 會在該工作階段中執行。

3026* [伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)、macOS 受管偏好設定或 Windows 登錄檔原則的更新

3027* 在啟用 [`wslInheritsWindowsSettings`](https://code.claude.com/docs/zh-TW/settings-reference#wslinheritswindowssettings) 的 WSL 上，Windows 端受管設定檔的變更，Claude Code 會在其原則輪詢時取得該變更

3028

3029此範例會記錄設定變更以進行安全稽核：

3015 3030

3016```json theme={null}3031```json theme={null}

3017{3032{

3334 "hooks": [3349 "hooks": [

3335 {3350 {

3336 "type": "command",3351 "type": "command",

3337 "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"3352 "command": "bash -c 'p=$(jq -er .worktree_path) && rm -rf -- \"$p\"'"

3338 }3353 }

3339 ]3354 ]

3340 }3355 }

hooks-guide.md +4 −4

Details

50 "PostToolUse": [50 "PostToolUse": [

51 {51 {

52 "matcher": "Edit|Write",52 "matcher": "Edit|Write",

~~53 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]~~53 "hooks": [{ "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\"" }]

54 }54 }

55 ],55 ],

56 "Notification": [56 "Notification": [

221 "hooks": [221 "hooks": [

222 {222 {

223 "type": "command",223 "type": "command",

224 "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"224 "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""

225 }225 }

226 ]226 ]

227 }227 }

336 336

337追蹤工作階段期間設定檔或 skill 檔案的變更時間。`ConfigChange` 事件會在外部程序或編輯器修改設定檔時觸發，因此您可以記錄變更以符合法規要求，或封鎖未經授權的修改。337追蹤工作階段期間設定檔或 skill 檔案的變更時間。`ConfigChange` 事件會在外部程序或編輯器修改設定檔時觸發，因此您可以記錄變更以符合法規要求，或封鎖未經授權的修改。

338 338

339此範例會將每次變更附加至稽核日誌。將此內容新增至 `~/.claude/settings.json`：339此範例會將每個事件附加至稽核日誌。將此內容新增至 `~/.claude/settings.json`：

340 340

341```json theme={null}341```json theme={null}

342{342{

925您的端點會以與命令 hooks 相同的[輸出格式](https://code.claude.com/docs/zh-TW/hooks.md#json-output)傳回 JSON 回應主體，而 Claude Code 也會檢查回應狀態：925您的端點會以與命令 hooks 相同的[輸出格式](https://code.claude.com/docs/zh-TW/hooks.md#json-output)傳回 JSON 回應主體，而 Claude Code 也會檢查回應狀態：

926 926

927* **2xx 狀態**：若要阻止工具呼叫，請在主體中傳回適當的 `hookSpecificOutput` 欄位。927* **2xx 狀態**：若要阻止工具呼叫，請在主體中傳回適當的 `hookSpecificOutput` 欄位。

928* **任何其他狀態，或請求失敗**：Claude Code 會回報[非阻斷性錯誤](https://code.claude.com/docs/zh-TW/hooks.md#exit-code-output)並讓該動作繼續進行。若要讓失敗的端點阻止該動作，請在 hook 上設定 [`onFailure: "block"`](https://code.claude.com/docs/zh-TW/hooks#block-the-action-when-a-hook-fails)。928* **任何其他狀態，或請求失敗**：Claude Code 會回報[非阻斷性錯誤](https://code.claude.com/docs/zh-TW/hooks.md#exit-code-output)並讓該動作繼續進行，除非該 hook 屬於[失敗時會阻止動作](https://code.claude.com/docs/zh-TW/hooks.md#block-the-action-when-a-hook-fails)的 hook。若要讓失敗的端點阻止該動作，請在 hook 上設定 [`onFailure: "block"`](https://code.claude.com/docs/zh-TW/hooks#block-the-action-when-a-hook-fails)。

929 929

930標頭值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法的環境變數插值。只有在 `allowedEnvVars` 陣列中列出的變數才會被解析；所有其他 `$VAR` 參考保持為空。930標頭值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法的環境變數插值。只有在 `allowedEnvVars` 陣列中列出的變數才會被解析；所有其他 `$VAR` 參考保持為空。

931 931

interactive-mode.md +3 −7

Details

36| `Esc` | 中斷 Claude 或關閉對話框 | 停止目前的回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作。如果您有[訊息排隊](#queue-messages-while-claude-works)，Claude Code 會在下一步傳送它們。當對話框開啟時，`Esc` 會關閉對話框。當頁尾項目被選中時（例如提示下方的[子代理面板](https://code.claude.com/docs/zh-TW/sub-agents.md#run-subagents-in-foreground-or-background)中的一列），`Esc` 會[取消選中它](https://code.claude.com/docs/zh-TW/keybindings.md#footer-actions)而不是中斷。在權限提示上，`Esc` 會拒絕該操作，與[**否**（不含註解）](https://code.claude.com/docs/zh-TW/permissions.md#add-a-comment-when-you-answer-a-permission-prompt)相同 |36| `Esc` | 中斷 Claude 或關閉對話框 | 停止目前的回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作。如果您有[訊息排隊](#queue-messages-while-claude-works)，Claude Code 會在下一步傳送它們。當對話框開啟時，`Esc` 會關閉對話框。當頁尾項目被選中時（例如提示下方的[子代理面板](https://code.claude.com/docs/zh-TW/sub-agents.md#run-subagents-in-foreground-or-background)中的一列），`Esc` 會[取消選中它](https://code.claude.com/docs/zh-TW/keybindings.md#footer-actions)而不是中斷。在權限提示上，`Esc` 會拒絕該操作，與[**否**（不含註解）](https://code.claude.com/docs/zh-TW/permissions.md#add-a-comment-when-you-answer-a-permission-prompt)相同 |

37| `Esc` + `Esc` | 清除輸入草稿或回溯 | 當提示輸入包含文字時，雙 `Esc` 會清除它並將草稿儲存到歷史記錄，以便 `Up` 可以回憶它。當輸入為空時，雙 `Esc` 會開啟[回溯功能表](https://code.claude.com/docs/zh-TW/checkpointing.md)以從先前的時間點復原或摘要程式碼和對話 |37| `Esc` + `Esc` | 清除輸入草稿或回溯 | 當提示輸入包含文字時，雙 `Esc` 會清除它並將草稿儲存到歷史記錄，以便 `Up` 可以回憶它。當輸入為空時，雙 `Esc` 會開啟[回溯功能表](https://code.claude.com/docs/zh-TW/checkpointing.md)以從先前的時間點復原或摘要程式碼和對話 |

38| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即傳送排隊的訊息 | 傳送您的[排隊訊息](#queue-messages-while-claude-works)和您的草稿與它們一起立即發出。[Claude Code 何時傳送您排隊的內容](#when-claude-code-sends-what-you-queued)涵蓋了 Claude 正在處理的回合會發生什麼。在[shell 模式](#shell-mode-with-prefix)中，該鍵只會將您的命令排隊。在不報告延伸鍵的終端中，`Ctrl+Enter` 會以純 `Enter` 的形式到達；`Ctrl+X Ctrl+S` 在任何終端中都有效。需要 Claude Code v2.1.275 或更新版本 |38| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即傳送排隊的訊息 | 傳送您的[排隊訊息](#queue-messages-while-claude-works)和您的草稿與它們一起立即發出。[Claude Code 何時傳送您排隊的內容](#when-claude-code-sends-what-you-queued)涵蓋了 Claude 正在處理的回合會發生什麼。在[shell 模式](#shell-mode-with-prefix)中，該鍵只會將您的命令排隊。在不報告延伸鍵的終端中，`Ctrl+Enter` 會以純 `Enter` 的形式到達；`Ctrl+X Ctrl+S` 在任何終端中都有效。需要 Claude Code v2.1.275 或更新版本 |

39| `Shift+Tab` 或 `Alt+M`（當 Node 或 Bun 執行時間未啟用 VT 輸入模式時在 Windows 上） | 循環權限模式 | 循環通過 `default`（在模式指示器中標記為 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions`，然後是 `auto`。從 `auto`，第一次按下會切換到 `default`。請參閱[權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)。在檔案權限提示上，相同的鍵會關閉開啟的[註解欄位](https://code.claude.com/docs/zh-TW/permissions.md#add-a-comment-when-you-answer-a-permission-prompt)。沒有開啟欄位時，它會選擇允許該操作以供工作階段其餘部分的選項（當提示提供該選項時） |39| `Shift+Tab`，或在 Windows 上當 Node 或 Bun 執行環境未啟用 VT 輸入模式時使用 `Alt+M` | 循環權限模式 | 依序循環 `default`（在模式指示器中標記為 Manual）、`acceptEdits` 和 `plan`，然後在可用時循環 `bypassPermissions` 和 `auto`。請參閱[權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)。在檔案權限提示上，相同的鍵會關閉開啟的[註解欄位](https://code.claude.com/docs/zh-TW/permissions.md#add-a-comment-when-you-answer-a-permission-prompt)。沒有開啟欄位時，若提示提供該選項，它會選擇在工作階段其餘期間允許該操作的選項。在計畫核准提示上，它會核准該計畫 |

81| :- | :- | :- |81| :- | :- | :- |

84| Shift+Enter | `Shift+Enter` | 在 iTerm2、WezTerm、Ghostty、Kitty、Warp、Apple Terminal、Windows Terminal 中原生。對於其他終端，請參閱[輸入多行提示](https://code.claude.com/docs/zh-TW/terminal-config.md#enter-multiline-prompts) |84| Shift+Enter | `Shift+Enter` | 在 iTerm2、WezTerm、Ghostty、Kitty、Warp、Windows Terminal 中原生支援。對於其他終端機，請參閱[輸入多行提示詞](https://code.claude.com/docs/zh-TW/terminal-config.md#enter-multiline-prompts) |

87 87

137 137

138透過 `/config` → Editor mode 啟用 vim 風格的編輯。138透過 `/config` → Editor mode 啟用 vim 風格的編輯。

139 139

140Claude Code 會在您使用 `Ctrl+O` 切換[文字記錄檢視器](#transcript-viewer)或開啟和關閉面板（例如 `/config`）時保留您的 vim 模式和游標位置。如果您在 NORMAL 模式下離開提示，當您返回時它仍然處於 NORMAL 模式，游標位置與您離開時相同。

~~141~~

142### 模式切換140### 模式切換

143 141

144| 命令 | 動作 | 來自模式 |142| 命令 | 動作 | 來自模式 |

302 * 按 `Ctrl+C` 取消並還原您的原始輸入300 * 按 `Ctrl+C` 取消並還原您的原始輸入

303 * 在空搜尋上按 `Backspace` 取消301 * 在空搜尋上按 `Backspace` 取消

304 302

305接受符合項目或取消搜尋會立即生效，即使 Claude Code 仍在載入歷史。

~~306~~

307若要找出較早的提示詞，而您只記得曾在其中貼上某段很長的內容（例如錯誤日誌），請按 `Ctrl+R` 並輸入貼上內容中的某個字詞。需要 Claude Code v2.1.314 或更新版本。303若要找出較早的提示詞，而您只記得曾在其中貼上某段很長的內容（例如錯誤日誌），請按 `Ctrl+R` 並輸入貼上內容中的某個字詞。需要 Claude Code v2.1.314 或更新版本。

308 304

309## 背景 Bash 命令305## 背景 Bash 命令

600 596

601### Claude Code 加底線的內容597### Claude Code 加底線的內容

602 598

603在您暫停輸入後不久，Claude Code 會為字典不知道的單詞加上底線。它在您仍在輸入時不理會該單詞，直到您超過它，並且它永遠不會改變您的文字。它也會跳過看起來像程式碼的文字：599在您暫停輸入後不久，Claude Code 會為字典不知道的單詞加上底線。對於您仍在輸入的單詞，它會先不予理會，直到您輸入超過該單詞為止。它也會跳過看起來像程式碼的文字：

604 600

605* 命令，例如 `/help`、`@` 提及、URL、檔案路徑和旗標，例如 `--verbose`601* 命令，例如 `/help`、`@` 提及、URL、檔案路徑和旗標，例如 `--verbose`

606* 包含數字、底線或第一個字母後大寫字母的單詞，以及反引號中的文字602* 包含數字、底線或第一個字母後大寫字母的單詞，以及反引號中的文字

keybindings.md +7 −2

Details

581 581

582Claude Code 在 `ctrl+x` 前綴上繫結這些預設和弦，依內容分列如下：582Claude Code 在 `ctrl+x` 前綴上繫結這些預設和弦，依內容分列如下：

583 583

584* `Chat`：`ctrl+x ctrl+k`、`ctrl+x ctrl+e`、`ctrl+x enter`、`ctrl+x ctrl+a`、`ctrl+x ctrl+s` 和 `ctrl+x tab`584* `Chat`：`ctrl+x ctrl+k`、`ctrl+x ctrl+e`、`ctrl+x enter`、`ctrl+x ctrl+a`、`ctrl+x ctrl+s`、`ctrl+x tab`、`ctrl+x ctrl+=`、`ctrl+x ctrl+-`、`ctrl+x ctrl+_`、`ctrl+x =` 和 `ctrl+x -`

585* `Task`：`ctrl+x ctrl+b`585* `Task`：`ctrl+x ctrl+b`

586* `DiffPanel`：`ctrl+x b`586* `DiffPanel`：`ctrl+x b`

587* `Pane`：`ctrl+x left`、`ctrl+x right`、`ctrl+x up`、`ctrl+x down` 和 `ctrl+x x`587* `Pane`：`ctrl+x left`、`ctrl+x right`、`ctrl+x up`、`ctrl+x down` 和 `ctrl+x x`

631 "ctrl+x ctrl+a": null,631 "ctrl+x ctrl+a": null,

632 "ctrl+x ctrl+s": null,632 "ctrl+x ctrl+s": null,

633 "ctrl+x tab": null,633 "ctrl+x tab": null,

634 "ctrl+x ctrl+=": null,

635 "ctrl+x ctrl+-": null,

636 "ctrl+x ctrl+_": null,

637 "ctrl+x =": null,

638 "ctrl+x -": null,

634 "ctrl+x": "chat:newline"639 "ctrl+x": "chat:newline"

635 }640 }

636 }641 }

716Claude Code 驗證您的快捷鍵並為以下項目寫入警告到偵錯日誌：721Claude Code 驗證您的快捷鍵並為以下項目寫入警告到偵錯日誌：

717 722

718* 解析錯誤（無效的 JSON 或結構）723* 解析錯誤（無效的 JSON 或結構）

719* 拼寫錯誤的修飾鍵，例如 `ctl+k`。Claude Code 會捨棄它無法識別的部分，並將繫結應用於剩餘的按鍵，在此範例中為 `k`。724* 拼寫錯誤的修飾鍵，例如 `ctl+k`。Claude Code 會忽略整個繫結。請修正該修飾鍵，在此範例中應改為 `ctrl+k`。

720* 按鍵字串中 `+` 旁邊有空格，例如 `ctrl+ k`。Claude Code 會將該字串解讀為由 `ctrl+` 後接 `k` 組成的[組合鍵](#chords)。沒有任何按鍵會單獨符合 `ctrl+`，因此該繫結永遠不會觸發。請移除該空格。725* 按鍵字串中 `+` 旁邊有空格，例如 `ctrl+ k`。Claude Code 會將該字串解讀為由 `ctrl+` 後接 `k` 組成的[組合鍵](#chords)。沒有任何按鍵會單獨符合 `ctrl+`，因此該繫結永遠不會觸發。請移除該空格。

721* 無效的上下文名稱726* 無效的上下文名稱

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

llm-gateway.md +4 −0

Details

43 43

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

45 45

46> [!NOTE]

47>

48> 在 Desktop 已登入 claude.ai 的情況下，使用者機器上的 Cowork 工作階段會被視為 [`"anthropic"`](https://code.claude.com/docs/zh-TW/settings-reference#allowedproviders)。如果您在 MDM 原則或受管設定檔中未將其列入此清單，該工作階段會被拒絕。若將其列入，直接傳送至 Anthropic 的工作階段也會通過此清單。

46## 訂閱和 gateway50## 訂閱和 gateway

47 51

48當[gateway 憑證變數](https://code.claude.com/docs/zh-TW/llm-gateway-connect.md#set-the-credential-variable)或 `apiKeyHelper` 處於活動狀態時，請求會使用該憑證，而不是開發人員的 claude.ai 訂閱登錄，且訂閱的使用限制不適用於這些請求。Claude Code 在機器上保存了 claude.ai 登錄，但不會在這些請求中發送它。該流量按令牌計費給擁有 gateway 轉發的憑證的人，例如您的組織的 Anthropic Console 帳戶，或當 gateway 路由到那裡時您的 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 帳戶。52當[gateway 憑證變數](https://code.claude.com/docs/zh-TW/llm-gateway-connect.md#set-the-credential-variable)或 `apiKeyHelper` 處於活動狀態時，請求會使用該憑證，而不是開發人員的 claude.ai 訂閱登錄，且訂閱的使用限制不適用於這些請求。Claude Code 在機器上保存了 claude.ai 登錄，但不會在這些請求中發送它。該流量按令牌計費給擁有 gateway 轉發的憑證的人，例如您的組織的 Anthropic Console 帳戶，或當 gateway 路由到那裡時您的 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 帳戶。

llm-gateway-connect.md +3 −2

Details

156 156

157### 與現有登入的衝突157### 與現有登入的衝突

158 158

159閘道憑證變數優先於已保存的 claude.ai 登入或 Console 金鑰。使用 `ANTHROPIC_AUTH_TOKEN` 時，該變數會立即優先生效。使用 `ANTHROPIC_API_KEY` 時，系統會在互動模式下提示您一次以核准該金鑰，之後才會由其接管。159您的請求會使用閘道憑證變數，而非已儲存的 claude.ai 登入。使用 `ANTHROPIC_AUTH_TOKEN` 時，該變數會立即優先生效。使用 `ANTHROPIC_API_KEY` 時，系統會在互動模式下提示您一次以核准該金鑰，之後才會由其接管。

160 160

161執行 `/status` 以確認哪個認證來源處於活動狀態。如果啟動顯示命名兩個來源的身份驗證衝突警告，請參閱[故障排除表](#troubleshoot-gateway-errors)的第一行以了解要刪除哪一個。要清除已保存的登入，以便只有閘道認證保留，請執行 `/logout`。161執行 `/status` 以確認哪個認證來源處於活動狀態。如果啟動顯示命名兩個來源的身份驗證衝突警告，請參閱[故障排除表](#troubleshoot-gateway-errors)的第一行以了解要刪除哪一個。要清除已保存的登入，以便只有閘道認證保留，請執行 `/logout`。

162 162

506 506

507| 錯誤 | 原因 | 修復 |507| 錯誤 | 原因 | 修復 |

508| :- | :- | :- |508| :- | :- | :- |

509| 啟動警告命名兩個認證來源並以 `auth may not work as expected` 結尾。較舊的版本顯示 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` 代替。 | 閘道認證和已保存的登入都處於活動狀態；變數用於請求，但過時的登入可能導致意外的身份驗證行為 | 取消設定變數以使用已保存的登入，或執行 `/logout` 以使用閘道認證 |509| 啟動警告指出兩個憑證來源，並以 `auth may not work as expected` 結尾。較舊的版本則改為顯示 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set`。 | 閘道憑證和已儲存的登入同時處於作用中 | 取消設定該變數以使用已儲存的登入，或執行 `/logout` 以使用閘道憑證 |

511| `Your apiKeyHelper script is failing`，或在非互動模式下 stderr 上的 `apiKeyHelper failed:` | [`apiKeyHelper`](https://code.claude.com/docs/zh-TW/settings-reference#apikeyhelper) 設定中的命令未產生可用的金鑰，因此請求帶有預留位置金鑰 | 直接執行命令以查看失敗原因，並在認證提供者報告過期會話時重新驗證；請參閱[錯誤參考](https://code.claude.com/docs/zh-TW/errors.md#your-apikeyhelper-script-is-failing) |511| `Your apiKeyHelper script is failing`，或在非互動模式下 stderr 上的 `apiKeyHelper failed:` | [`apiKeyHelper`](https://code.claude.com/docs/zh-TW/settings-reference#apikeyhelper) 設定中的命令未產生可用的金鑰，因此請求帶有預留位置金鑰 | 直接執行命令以查看失敗原因，並在認證提供者報告過期會話時重新驗證；請參閱[錯誤參考](https://code.claude.com/docs/zh-TW/errors.md#your-apikeyhelper-script-is-failing) |

512| 當沒有任何東西在地址應答時 `Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)`，或當主機名無法解析時 `Can't reach the API server — check your internet or DNS (ENOTFOUND)`，通常在 Claude Code [使用退避重試](https://code.claude.com/docs/zh-TW/errors.md#automatic-retries)時無聲暫停後。括號中的代碼會有所不同；[Unable to connect to API](https://code.claude.com/docs/zh-TW/errors.md#unable-to-connect-to-api) 涵蓋代碼拼寫和較早的措辭 | 沒有任何東西在基礎 URL 應答：地址錯誤，或 VPN 或防火牆阻止了到閘道的路徑 | 執行上面的 [curl 測試](#verify-the-connection)，它立即以相同的原因失敗，並與您的閘道團隊確認 URL 和網路路徑 |512| 當沒有任何東西在地址應答時 `Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)`，或當主機名無法解析時 `Can't reach the API server — check your internet or DNS (ENOTFOUND)`，通常在 Claude Code [使用退避重試](https://code.claude.com/docs/zh-TW/errors.md#automatic-retries)時無聲暫停後。括號中的代碼會有所不同；[Unable to connect to API](https://code.claude.com/docs/zh-TW/errors.md#unable-to-connect-to-api) 涵蓋代碼拼寫和較早的措辭 | 沒有任何東西在基礎 URL 應答：地址錯誤，或 VPN 或防火牆阻止了到閘道的路徑 | 執行上面的 [curl 測試](#verify-the-connection)，它立即以相同的原因失敗，並與您的閘道團隊確認 URL 和網路路徑 |

520| `/fast` 回報 `Fast mode unavailable due to network connectivity issues`，但推理請求正常運作 | [快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)可用性檢查會直接連線到 `api.anthropic.com`，不遵循 `ANTHROPIC_BASE_URL`，因此被阻擋的直接出站連線會導致檢查失敗 | 如果出站連線被阻擋，請將 `api.anthropic.com` 加入允許清單，或設定跳過變數。請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |520| `/fast` 回報 `Fast mode unavailable due to network connectivity issues`，但推理請求正常運作 | [快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)可用性檢查會直接連線到 `api.anthropic.com`，不遵循 `ANTHROPIC_BASE_URL`，因此被阻擋的直接出站連線會導致檢查失敗 | 如果出站連線被阻擋，請將 `api.anthropic.com` 加入允許清單，或設定跳過變數。請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

521| 在以 `ANTHROPIC_API_KEY` 中閘道簽發的金鑰進行身分驗證的工作階段中，`/fast` 回報 `Fast mode is currently unavailable` | 當 `ANTHROPIC_BASE_URL` 指向您的閘道，且金鑰不是 Anthropic API 金鑰的格式時，Claude Code 不會送出[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)可用性檢查。若沒有先前成功檢查的快取結果，它會將快速模式視為不可用 | 設定 `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`；請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |521| 在以 `ANTHROPIC_API_KEY` 中閘道簽發的金鑰進行身分驗證的工作階段中，`/fast` 回報 `Fast mode is currently unavailable` | 當 `ANTHROPIC_BASE_URL` 指向您的閘道，且金鑰不是 Anthropic API 金鑰的格式時，Claude Code 不會送出[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)可用性檢查。若沒有先前成功檢查的快取結果，它會將快速模式視為不可用 | 設定 `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`；請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

522| 在以 `ANTHROPIC_AUTH_TOKEN` 進行身分驗證的工作階段中，`/fast` 回報 `Fast mode has been disabled by your organization`，儘管組織已啟用快速模式 | 可用性檢查需要 claude.ai 登入或 API 金鑰；若僅有 bearer token，Claude Code 會將快速模式視為已停用，而不送出檢查 | 設定 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`；請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |522| 在以 `ANTHROPIC_AUTH_TOKEN` 進行身分驗證的工作階段中，`/fast` 回報 `Fast mode has been disabled by your organization`，儘管組織已啟用快速模式 | 可用性檢查需要 claude.ai 登入或 API 金鑰；若僅有 bearer token，Claude Code 會將快速模式視為已停用，而不送出檢查 | 設定 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`；請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

523| 在使用 `ANTHROPIC_BASE_URL` 的工作階段中，`/feedback` 儲存了一個本機檔案 | 在閘道後方，`ANTHROPIC_AUTH_TOKEN` 以及不是 Anthropic API 金鑰格式的金鑰都不是 Anthropic 憑證。沒有 Anthropic 憑證時，Claude Code 會將報告寫入 `~/.claude/feedback-bundles/` 下的本機封存檔，而不是將其傳送出去 | 將該檔案傳送給您的 Anthropic 客戶代表，或將其附加到支援請求中。請參閱[遙測服務](https://code.claude.com/docs/zh-TW/data-usage.md#telemetry-services) |

523| Claude Code 要求您登入，儘管 [curl 測試](#verify-the-connection)成功 | CLI 沒有自己的認證：可達的基礎 URL 不是一個，在互動會話中，專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 區塊僅在首次執行嚮導和[信任提示](https://code.claude.com/docs/zh-TW/permissions.md#what-runs-before-you-trust-a-folder)後應用 | 在 Claude Code 在首次執行設定之前讀取的位置設定 `ANTHROPIC_AUTH_TOKEN`：shell 匯出、`~/.claude/settings.json` 中的 `env` 區塊或受管設定 |524| Claude Code 要求您登入，儘管 [curl 測試](#verify-the-connection)成功 | CLI 沒有自己的認證：可達的基礎 URL 不是一個，在互動會話中，專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 區塊僅在首次執行嚮導和[信任提示](https://code.claude.com/docs/zh-TW/permissions.md#what-runs-before-you-trust-a-folder)後應用 | 在 Claude Code 在首次執行設定之前讀取的位置設定 `ANTHROPIC_AUTH_TOKEN`：shell 匯出、`~/.claude/settings.json` 中的 `env` 區塊或受管設定 |

525| `This machine's managed settings require a first-party login`，或當受管設定將 `forceLoginMethod` 設定為 `"gateway"` 或也設定 `forceLoginGatewayUrl` 時的 [`Administrator policy requires a Cloud gateway sign-in`](https://code.claude.com/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in) | 受管設定包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，不能與 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理員必須從受管設定中移除 `forceLoginMethod`、`forceLoginOrgUUID` 和 `forceLoginGatewayUrl` 以使用閘道認證，或移除閘道認證以使用受管設定要求的登入。兩者無法結合 |526| `This machine's managed settings require a first-party login`，或當受管設定將 `forceLoginMethod` 設定為 `"gateway"` 或也設定 `forceLoginGatewayUrl` 時的 [`Administrator policy requires a Cloud gateway sign-in`](https://code.claude.com/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in) | 受管設定包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，不能與 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理員必須從受管設定中移除 `forceLoginMethod`、`forceLoginOrgUUID` 和 `forceLoginGatewayUrl` 以使用閘道認證，或移除閘道認證以使用受管設定要求的登入。兩者無法結合 |

llm-gateway-rollout.md +5 −5

Details

142claude -p "Reply with one word: connected"142claude -p "Reply with one word: connected"

143```143```

144 144

145**檢查點**：提示返回回應，請求出現在閘道的日誌中，作為對 `/v1/messages` 路徑的 `POST`，狀態為 `200`。Claude Code 附加查詢字串，例如 `?beta=true`，因此匹配路徑，而不是完整 URL。兩個失敗訊息指向不同的方向：145**檢查點**：提示詞回傳回應，請求出現在閘道的日誌中，作為對 `/v1/messages` 路徑的 `POST`，狀態為 `200`。Claude Code 會附加查詢字串，例如 `?beta=true`，因此請比對路徑，而不是完整 URL。請檢查失敗訊息：

146 146

147* `Not logged in`：檢查閘道日誌以區分兩個原因。如果它是空的，沒有認證到達工作階段，沒有請求離開機器；在您測試的殼層中重新執行匯出。如果它顯示被拒絕的請求，在 `401` 正文中有 `x-api-key`，閘道期望金鑰在該標頭中；改為切換到 `ANTHROPIC_API_KEY`147* `Not logged in`：檢查閘道日誌。如果它是空的，表示沒有憑證到達工作階段，也沒有請求離開機器；請在您測試的 shell 中重新執行匯出。如果它顯示來自閘道且指出 `x-api-key` 的 `401`，表示閘道期望金鑰在該標頭中；請改用 `ANTHROPIC_API_KEY`。如果它顯示來自 `api.anthropic.com` 或您的提供者端點的 `401`，請修正閘道持有的提供者憑證

148* `Failed to authenticate. API Error: 401` 表示認證已發送並被拒絕，閘道日誌說明位置：命名 `api.anthropic.com` 或您的提供者端點的 `401` 表示閘道到達上游但其提供者認證被拒絕，因此開發者金鑰有效，閘道持有的提供者認證有誤或是佔位符148* `Failed to authenticate. API Error: 401` 表示認證已發送並被拒絕，閘道日誌說明位置：命名 `api.anthropic.com` 或您的提供者端點的 `401` 表示閘道到達上游但其提供者認證被拒絕，因此開發者金鑰有效，閘道持有的提供者認證有誤或是佔位符

149 149

150錯誤或無法到達的基本 URL 會產生不同的症狀：Claude Code [以退避方式重試連接](https://code.claude.com/docs/zh-TW/errors.md#automatic-retries)，在報告錯誤之前可能會坐著沒有輸出幾分鐘。如果命令似乎掛起，請檢查閘道日誌而不是等待；沒有到達的請求表示 `ANTHROPIC_BASE_URL` 未指向閘道。150錯誤或無法到達的基本 URL 會產生不同的症狀：Claude Code [以退避方式重試連接](https://code.claude.com/docs/zh-TW/errors.md#automatic-retries)，在報告錯誤之前可能會坐著沒有輸出幾分鐘。如果命令似乎掛起，請檢查閘道日誌而不是等待；沒有到達的請求表示 `ANTHROPIC_BASE_URL` 未指向閘道。

247 247

248您應該看到 `data:` 行逐漸到達。整個回應在暫停後一次到達表示閘道正在緩衝，這會停滯 Claude Code；`404` 表示模型名稱未路由。針對每個模型名稱重複。248您應該看到 `data:` 行逐漸到達。整個回應在暫停後一次到達表示閘道正在緩衝，這會停滯 Claude Code；`404` 表示模型名稱未路由。針對每個模型名稱重複。

249 249

250然後啟動 `claude` 並發送訊息。此步驟的每個症狀都有一個原因：250然後啟動 `claude`，發送訊息，並比對您看到的情況：

251 251

252* 登入提示表示認證間隙。執行 `/status` 並開啟 **Status** 標籤：當 `Setting sources` 行不包括受管設定時，分發未到達機器；當它包括時，開發者認證未被傳遞，因此設定 `ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`252* 出現登入畫面，或出現 `Not logged in` 且閘道日誌中沒有新內容，表示憑證缺失。執行 `/status` 並開啟 **Status** 標籤：當 `Setting sources` 行不包括受管設定時，表示分發未到達機器；當它包括時，表示開發者憑證未被傳遞，因此請設定 `ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`

253* `Failed to authenticate` 錯誤表示閘道拒絕請求；其日誌說明哪個認證失敗。閘道自己記錄的拒絕命名開發者金鑰，而來自 `api.anthropic.com` 或您的提供者端點的 `401` 表示閘道持有的提供者認證被拒絕253* `Please run /login · API Error: 401`、`Not logged in` 或 `Invalid API key`，且閘道日誌中有 `401`：請檢查是誰產生了該 `401`。如果是閘道產生的，請修正開發者金鑰或其標頭；如果它來自 `api.anthropic.com` 或您的提供者端點，請修正閘道持有的提供者憑證

254* 當閘道期望金鑰在 `x-api-key` 標頭中（設定為 `ANTHROPIC_API_KEY`）時，首次使用時出現一次性的金鑰核准提示是預期的254* 當閘道期望金鑰在 `x-api-key` 標頭中（設定為 `ANTHROPIC_API_KEY`）時，首次使用時出現一次性的金鑰核准提示是預期的

255 255

256如果您的組織使用[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)，請在此處也執行 `/fast`：可用性檢查直接呼叫 `api.anthropic.com` 而不是遵循閘道基本 URL，因此閘道路由的工作階段可以報告快速模式為不可用或已停用，即使推理有效。[在代理和 LLM 閘道後面使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)將每個訊息對應到恢復它的變數，與[配置的其餘部分](#distribute-the-configuration)一起分發。256如果您的組織使用[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)，請在此處也執行 `/fast`：可用性檢查直接呼叫 `api.anthropic.com` 而不是遵循閘道基本 URL，因此閘道路由的工作階段可以報告快速模式為不可用或已停用，即使推理有效。[在代理和 LLM 閘道後面使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)將每個訊息對應到恢復它的變數，與[配置的其餘部分](#distribute-the-configuration)一起分發。

mcp.md +0 −2

Details

835 835

836您的組織透過 [`managedMcpServers`](https://code.claude.com/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings) 受管設定提供的伺服器，其優先順序高於上述所有來源，因此當其中任一來源與之重複時，Claude Code 會連線至組織的定義。需要 Claude Code v2.1.259 或更新版本。836您的組織透過 [`managedMcpServers`](https://code.claude.com/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings) 受管設定提供的伺服器，其優先順序高於上述所有來源，因此當其中任一來源與之重複時，Claude Code 會連線至組織的定義。需要 Claude Code v2.1.259 或更新版本。

837 837

838若您在 [Desktop 應用程式的 Code 分頁](https://code.claude.com/docs/zh-TW/desktop.md#mcp-servers-from-the-claude-desktop-chat-app)中開啟本機工作階段，且 `~/.claude.json` 的最上層（user 範圍）與 `.mcp.json` 中有相同名稱的 stdio 伺服器，Code 分頁會使用 `~/.claude.json` 的定義。

~~839~~

840### `.mcp.json` 中的環境變數展開838### `.mcp.json` 中的環境變數展開

841 839

842Claude Code 支援在 `.mcp.json` 檔案中展開環境變數，讓團隊能夠共享設定，同時保有針對特定機器路徑與 API 金鑰等敏感值的彈性。840Claude Code 支援在 `.mcp.json` 檔案中展開環境變數，讓團隊能夠共享設定，同時保有針對特定機器路徑與 API 金鑰等敏感值的彈性。

microsoft-foundry.md +2 −16

Details

147 147

148## Azure RBAC 配置148## Azure RBAC 配置

149 149

150`Azure AI User` 和 `Cognitive Services User` 預設角色包含叫用 Claude 模型所需的所有權限。150如果您使用 Microsoft Entra ID 或其核發的 bearer token 進行驗證，請在您的 Foundry 資源上為您的身分指派 `Foundry User` 或 `Cognitive Services User` 角色。您可能仍會看到 `Foundry User` 以其先前的名稱 `Azure AI User` 顯示。

151 151

152如需更嚴格的權限，請建立具有以下內容的自訂角色：152如果這些角色無法滿足您的需求，請參閱 [Microsoft Foundry RBAC 文件](https://learn.microsoft.com/en-us/azure/foundry/concepts/rbac-foundry)以了解自訂角色。

~~153~~

154```json theme={null}

155{

156 "permissions": [

157 {

158 "dataActions": [

159 "Microsoft.CognitiveServices/accounts/providers/*"

160 ]

161 }

162 ]

163}

164```

~~165~~

166如需詳細資訊，請參閱 [Microsoft Foundry RBAC 文件](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-foundry)。

167 153

168## 1M token 上下文視窗154## 1M token 上下文視窗

169 155

model-config.md +5 −3

Details

157 157

158當啟動時的作用中模型來自專案或受管設定，而非您自己的選擇時，啟動標頭會顯示是哪個設定檔設定了它。執行 `/model` 即可覆寫；專案或受管設定會在下次啟動時重新套用。在嵌入 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-TW/env-vars) 的平台上，主機的模型設定優先於受管模型設定，而受管的 `availableModels` 允許清單仍然有效，除非主機提供自己的允許清單；[受管設定優先順序的例外情況](https://code.claude.com/docs/zh-TW/settings.md#exceptions-to-managed-settings-precedence)說明了主機會覆寫哪些鍵和變數。158當啟動時的作用中模型來自專案或受管設定，而非您自己的選擇時，啟動標頭會顯示是哪個設定檔設定了它。執行 `/model` 即可覆寫；專案或受管設定會在下次啟動時重新套用。在嵌入 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-TW/env-vars) 的平台上，主機的模型設定優先於受管模型設定，而受管的 `availableModels` 允許清單仍然有效，除非主機提供自己的允許清單；[受管設定優先順序的例外情況](https://code.claude.com/docs/zh-TW/settings.md#exceptions-to-managed-settings-precedence)說明了主機會覆寫哪些鍵和變數。

159 159

160如果您或您的組織設定了 [PreModelSwitch hook](https://code.claude.com/docs/zh-TW/hooks.md#premodelswitch)，它們會在所請求的切換套用之前執行，並可以阻擋切換或要求您確認。160如果您或您的組織設定了 [PreModelSwitch hook](https://code.claude.com/docs/zh-TW/hooks.md#premodelswitch)，它們會在所請求的切換套用之前執行，並可以阻擋切換或要求您確認。若要了解 hook 為何阻擋了切換以及該如何處理，請參閱 [Model switch was blocked by a PreModelSwitch hook](https://code.claude.com/docs/zh-TW/errors.md#model-switch-was-blocked-by-a-premodelswitch-hook)。

161 161

162當 Claude Code 無法判斷您組織的[受管外掛](https://code.claude.com/docs/zh-TW/settings-reference.md#enabledplugins)提供了哪些 PreModelSwitch hook 時（例如因為某個受管外掛載入失敗），它會拒絕切換，而不是在未經檢查的情況下套用，並在每次新的嘗試時再次檢查。關於訊息和復原方式，請參閱 [Model switch was blocked by a PreModelSwitch hook](https://code.claude.com/docs/zh-TW/errors.md#model-switch-was-blocked-by-a-premodelswitch-hook)。162如果某個[受管外掛](https://code.claude.com/docs/zh-TW/settings-reference.md#enabledplugins)或其 hook 載入失敗，您仍然可以切換模型。該外掛的 PreModelSwitch hook 不會執行，因此原本會被其中某個 hook 阻擋的切換可以繼續進行。其他已載入的 PreModelSwitch hook 仍會執行，並可以阻擋切換。如果 v2.1.323 之前的 Claude Code 以 `so organization-managed PreModelSwitch hooks could not be checked` 拒絕切換，請更新 Claude Code。

163

164若要查看失敗的項目，請在工作階段中執行 `/plugin` 並開啟 [**Errors** 分頁](https://code.claude.com/docs/zh-TW/plugins/troubleshooting.md#failed-to-load-hooks-from-and-hooks-that-dont-fire)。如果其中沒有列出任何項目，請從您的 shell 以 `claude --debug` 啟動新的工作階段並切換至其他模型，然後閱讀[除錯日誌](https://code.claude.com/docs/zh-TW/hooks.md#debug-hooks)。在您修正外掛，或[外掛更新](https://code.claude.com/docs/zh-TW/plugins/install.md#keep-plugins-updated)將您管理員的修正帶到您的電腦之後，請在工作階段中執行 `/reload-plugins` 讓其 hook 開始執行。

163 165

164當您透過 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 的 `setModel()` 方法、透過 [Desktop 應用程式](https://code.claude.com/docs/zh-TW/desktop.md)等應用程式，或從透過 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 連線的裝置切換模型時，Claude Code 會在切換時檢查該值：166當您透過 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 的 `setModel()` 方法、透過 [Desktop 應用程式](https://code.claude.com/docs/zh-TW/desktop.md)等應用程式，或從透過 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 連線的裝置切換模型時，Claude Code 會在切換時檢查該值：

165 167

903 905

904### 為閘道或自訂模型 ID 修正視窗906### 為閘道或自訂模型 ID 修正視窗

905 907

906出現下列任一啟動警告，都表示 Claude Code 無法辨識您工作階段的模型 ID，因此無法得知該模型的上下文視窗，並假定其為 200K token：908出現下列任一警告，都表示 Claude Code 無法辨識您工作階段的模型 ID，因此無法得知該模型的上下文視窗，並假定其為 200K token：

907 909

908```text theme={null}910```text theme={null}

909⚠ Model "my-gateway-opus" isn't recognized · context assumed to be 200k tokens · ...911⚠ Model "my-gateway-opus" isn't recognized · context assumed to be 200k tokens · ...

monitoring-usage.md +199 −199

Details

97 97

98## 設定詳細資訊98## 設定詳細資訊

99 99

100### 常見設定變數100### 常用設定變數

101 101

102這些變數為所有部署設定匯出器、端點和匯出行為。102這些變數為所有部署設定匯出器、端點和匯出行為。

103 103

104如果您設定了每個信號的端點或協議變數，例如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`，Claude Code 會改用它而不是該信號的通用變數。如果您設定了每個信號的標頭變數，例如 `OTEL_EXPORTER_OTLP_METRICS_HEADERS`，Claude Code 會將其與該信號的通用 `OTEL_EXPORTER_OTLP_HEADERS` 合併。104如果您設定了個別訊號的端點或通訊協定變數（例如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`），Claude Code 會針對該訊號使用它，而不使用通用變數。如果您設定了個別訊號的標頭變數（例如 `OTEL_EXPORTER_OTLP_METRICS_HEADERS`），Claude Code 會針對該訊號將其與通用的 `OTEL_EXPORTER_OTLP_HEADERS` 合併。

105 105

106在具有受管設定的機器上，請參閱[受管設定如何鎖定 OTLP 目的地](#how-managed-settings-lock-the-otlp-destination)以了解 Claude Code 移除的內容。106在具有受管設定的機器上，請參閱[受管設定如何鎖定 OTLP 目的地](#how-managed-settings-lock-the-otlp-destination)，以了解 Claude Code 會移除哪些內容。

107 107

108| 環境變數 | 說明 | 範例值 |108| 環境變數 | 說明 | 範例值 |

109| - | - | - |109| - | - | - |

110| `CLAUDE_CODE_ENABLE_TELEMETRY` | 啟用遙測收集（必需） | `1` |110| `CLAUDE_CODE_ENABLE_TELEMETRY` | 啟用遙測收集（必要） | `1` |

113| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 匯出器的協議，適用於所有信號。Claude Code 沒有預設協議，因此請為您啟用的每個 `otlp` 匯出器設定此項或信號特定的協議變數 | `grpc`、`http/json`、`http/protobuf` |113| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 匯出器的通訊協定，套用於所有訊號。對於有效的 `http://` 或 `https://` 端點，預設為 `http/protobuf`。對於 gRPC 端點（例如 `http://localhost:4317`），請將此設為 `grpc`。此預設值需要 Claude Code v2.1.323 或更新版本 | `grpc`, `http/json`, `http/protobuf` |

122| `OTEL_METRIC_EXPORT_INTERVAL` | 匯出間隔（毫秒）（預設值：60000） | `5000`、`60000` |122| `OTEL_METRIC_EXPORT_INTERVAL` | 匯出間隔，以毫秒為單位（預設：60000） | `5000`, `60000` |

123| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設值：5000） | `1000`、`10000` |123| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔，以毫秒為單位（預設：5000） | `1000`, `10000` |

124| `OTEL_LOG_USER_PROMPTS` | 啟用使用者提示內容的日誌記錄（預設值：停用） | `1` 啟用 |124| `OTEL_LOG_USER_PROMPTS` | 啟用使用者提示詞內容的日誌記錄（預設：停用） | `1` 以啟用 |

126| `OTEL_LOG_TOOL_DETAILS` | 在工具事件和追蹤跨度屬性中啟用工具參數和輸入引數的日誌記錄：Bash 命令、MCP 伺服器和工具名稱、技能名稱、使用者撰寫的工作流程名稱和工具輸入。也在 `user_prompt` 事件上啟用自訂、外掛程式和 MCP 命令名稱，以及在[成本和令牌計數器](#cost-counter)上啟用真實代理、技能、外掛程式和 MCP 伺服器和工具名稱（預設值：停用）。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，即使關閉旗標，`mcp_server_name`/`mcp_tool_name` 也會在 `tool_decision`/`tool_result` 上發出。例外需要 Claude Code v2.1.214 或更新版本 | `1` 啟用 |126| `OTEL_LOG_TOOL_DETAILS` | 在工具事件和追蹤 span 屬性中啟用工具參數與輸入引數的日誌記錄：Bash 命令、MCP 伺服器與工具名稱、skill 名稱、使用者撰寫的工作流程名稱，以及工具輸入。也會在 `user_prompt` 事件上啟用自訂、外掛和 MCP 命令名稱，並在[成本與 token 計數器](#cost-counter)上啟用真實的 agent、skill、外掛、MCP 伺服器與工具名稱（預設：停用）。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，即使此旗標關閉，`mcp_server_name`/`mcp_tool_name` 仍會在 `tool_decision`/`tool_result` 上發出。此例外需要 Claude Code v2.1.214 或更新版本 | `1` 以啟用 |

127| `OTEL_LOG_TOOL_CONTENT` | 在 [`tool.output` 跨度事件](#tool-output-span-event)中啟用工具內容的日誌記錄（預設值：停用）。跨度屬性在[其自己的閘門](#new-context-gates)下攜帶工具內容。需要[追蹤](#traces-beta)。內容在內容限制處截斷（預設值 60 KB） | `1` 啟用 |127| `OTEL_LOG_TOOL_CONTENT` | 在 [`tool.output` span 事件](#tool-output-span-event)中啟用工具內容的日誌記錄（預設：停用）。Span 屬性會依[其各自的閘控](#new-context-gates)攜帶工具內容。需要[追蹤](#traces-beta)。內容會在內容上限（預設為 60 KB）處截斷 | `1` 以啟用 |

128| `OTEL_LOG_MANAGED_SETTINGS` | 將編輯的受管設定和設定編輯前的 SHA-256 摘要新增至[受管設定已解決](#managed-settings-resolved-event)事件（預設值：停用）。專案或本機設定中的值不會將其開啟。需要 Claude Code v2.1.274 或更新版本 | `1` 啟用 |128| `OTEL_LOG_MANAGED_SETTINGS` | 將已遮蔽的受管設定，以及遮蔽前設定的 SHA-256 摘要，加入 [managed settings resolved](#managed-settings-resolved-event) 事件（預設：停用）。專案或本機設定中的值不會啟用它。需要 Claude Code v2.1.274 或更新版本 | `1` 以啟用 |

129| `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` 指標 |129| `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` 指標 |

130| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 內容限制：內容承載屬性（例如模型回應、工具內容、系統提示詞和原始 API 主體）的最大長度，包括截斷標記，以 UTF-16 程式碼單位計（預設值：61440，即 60 KB）。預設值適用於將屬性值上限設為 64 KB 的後端；只有在您的後端接受更大的值時才提高它，或降低它以減少遙測量。當設定了 OpenTelemetry SDK 屬性限制 `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 或其日誌記錄和跨度變體之一且其值較小時，Claude Code 會在該較小的值處截斷，以便 `[TRUNCATED ...]` 標記保持在 SDK 限制內 | `262144` |130| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 內容上限：攜帶內容之屬性（例如模型回應、工具內容、系統提示詞和原始 API 主體）的最大長度，包含截斷標記，以 UTF-16 碼元為單位（預設：61440，即 60 KB）。預設值是針對將屬性值上限設為 64 KB 的後端而訂定；僅在您的後端接受更大的值時才調高，或調低以減少遙測量。當 OpenTelemetry SDK 屬性上限（`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 或其 logrecord 與 span 變體之一）設定得更低時，Claude Code 會在該較小的值處截斷，讓 `[TRUNCATED ...]` 標記維持在 SDK 上限之內 | `262144` |

132| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態標頭的間隔（預設值：1740000ms / 29 分鐘） | `900000` |132| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態標頭的間隔（預設：1740000ms / 29 分鐘） | `900000` |

~~133~~ 133

134對於 `http/protobuf` 和 `http/json` 協議，Claude Code 會使用 `Content-Length` 標頭傳送每個匯出請求。134對於 `http/protobuf` 和 `http/json` 通訊協定，Claude Code 會在每個匯出請求中附上 `Content-Length` 標頭。

~~135~~ 135

136### mTLS 驗證136### mTLS 身分驗證

~~137~~ 137

138您如何為 OTLP 匯出器設定用戶端憑證取決於用於該信號的 OTLP 協議，透過 `OTEL_EXPORTER_OTLP_PROTOCOL` 或每個信號的覆蓋設定。相同的設定適用於指標、日誌和追蹤。138如何為 OTLP 匯出器設定用戶端憑證，取決於該訊號所使用的 OTLP 通訊協定，此通訊協定透過 `OTEL_EXPORTER_OTLP_PROTOCOL` 或個別訊號的覆寫來設定。相同的設定適用於指標、日誌和追蹤。

~~139~~ 139

140| 協議 | 用戶端憑證變數 | 信任收集器的 CA 使用 |140| 通訊協定 | 用戶端憑證變數 | 用以信任收集器 CA 的變數 |

141| :- | :- | :- |141| :- | :- | :- |

142| `http/protobuf`、`http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和選擇性的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。請參閱[網路設定](https://code.claude.com/docs/zh-TW/network-config.md#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |142| `http/protobuf`, `http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY`，以及選用的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。請參閱[網路設定](https://code.claude.com/docs/zh-TW/network-config.md#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |

143| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或每個信號的變體，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以針對每個信號使用不同的憑證 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |143| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或個別訊號的變體（例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY`），以便為每個訊號使用不同的憑證 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |

144 144

145對於 `grpc`，OpenTelemetry SDK 直接讀取標準 OTLP 變數，因此設定每個信號指標變數的現有設定會繼續運作。在具有受管設定的機器上，Claude Code [可能在啟動時移除開發人員設定的每個信號認證和端點](#how-managed-settings-lock-the-otlp-destination)。145對於 `grpc`，OpenTelemetry SDK 會直接讀取標準 OTLP 變數，因此設定了個別訊號指標變數的現有設定仍可繼續運作。在具有受管設定的機器上，Claude Code 可能會在啟動時[移除開發人員設定的個別訊號憑證與端點](#how-managed-settings-lock-the-otlp-destination)。

146 146

147### 指標基數控制147### 指標基數控制

148 148

149以下環境變數控制指標和事件中包含哪些屬性以管理基數：149下列環境變數控制哪些屬性會包含在指標和事件中，以管理基數：

150 150

151| 環境變數 | 說明 | 預設值 | 停用範例 |151| 環境變數 | 說明 | 預設值 | 停用範例 |

152| - | - | - | - |152| - | - | - | - |

159 159

160較低的基數通常意味著更好的效能和更低的儲存成本，但分析的資料粒度較低。160較低的基數通常代表較佳的效能與較低的儲存成本，但用於分析的資料粒度也較粗。

161 161

162### Traces（測試版）162### 追蹤（beta）

163 163

164分散式追蹤匯出跨度，將每個使用者提示連結到它觸發的 API 請求和工具執行，因此您可以在追蹤後端中將完整請求檢視為單一追蹤。164分散式追蹤會匯出 span，將每個使用者提示詞連結到其觸發的 API 請求與工具執行，讓您可以在追蹤後端中將完整的請求檢視為單一追蹤。

165 165

166追蹤預設為關閉。若要啟用它，請同時設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然後設定 `OTEL_TRACES_EXPORTER` 以選擇跨度的傳送位置。追蹤重複使用[常見 OTLP 設定](#common-configuration-variables)以取得端點、協議、標頭和 [mTLS](#mtls-authentication)。在具有受管設定的機器上，Claude Code [可能在啟動時移除開發人員設定的每個信號認證和端點](#how-managed-settings-lock-the-otlp-destination)。166追蹤預設為關閉。若要啟用，請同時設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然後設定 `OTEL_TRACES_EXPORTER` 以選擇 span 的傳送目的地。追蹤會沿用[通用 OTLP 設定](#common-configuration-variables)中的端點、通訊協定、標頭和 [mTLS](#mtls-authentication)。在具有受管設定的機器上，Claude Code 可能會在啟動時[移除開發人員設定的個別訊號憑證與端點](#how-managed-settings-lock-the-otlp-destination)。

167 167

168| 環境變數 | 說明 | 範例值 |168| 環境變數 | 說明 | 範例值 |

169| - | - | - |169| - | - | - |

170| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | 啟用跨度追蹤（必需）。也接受 `ENABLE_ENHANCED_TELEMETRY_BETA` | `1` |170| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | 啟用 span 追蹤（必要）。也接受 `ENABLE_ENHANCED_TELEMETRY_BETA` | `1` |

175| `OTEL_TRACES_EXPORT_INTERVAL` | 跨度批次匯出間隔（毫秒）（預設值：5000） | `1000`、`10000` |175| `OTEL_TRACES_EXPORT_INTERVAL` | Span 批次匯出間隔，以毫秒為單位（預設：5000） | `1000`, `10000` |

176 176

177跨度預設會編輯使用者提示文字、工具輸入詳細資訊和工具內容。設定 `OTEL_LOG_USER_PROMPTS=1`、`OTEL_LOG_TOOL_DETAILS=1` 和 `OTEL_LOG_TOOL_CONTENT=1` 以包含它們。177Span 預設會遮蔽使用者提示詞文字、工具輸入詳細資訊和工具內容。設定 `OTEL_LOG_USER_PROMPTS=1`、`OTEL_LOG_TOOL_DETAILS=1` 和 `OTEL_LOG_TOOL_CONTENT=1` 即可將其包含在內。

178 178

179當追蹤處於作用中時，Bash 和 PowerShell 子程序會自動繼承包含作用中工具執行跨度的 W3C 追蹤內容的 `TRACEPARENT` 環境變數。這讓任何讀取 `TRACEPARENT` 的子程序都可以在相同追蹤下將其自己的跨度作為父項，啟用透過 Claude 執行的指令碼和命令的端對端分散式追蹤。179追蹤啟用時，Bash 和 PowerShell 子程序會自動繼承 `TRACEPARENT` 環境變數，其中包含作用中工具執行 span 的 W3C 追蹤上下文。這讓任何讀取 `TRACEPARENT` 的子程序都能將自己的 span 掛在同一個追蹤之下，從而透過 Claude 執行的指令碼和命令實現端對端分散式追蹤。

180 180

181當追蹤處於作用中且 Claude Code 直接連線到 Anthropic API 時，每個模型請求都會攜帶設定為 `claude_code.llm_request` 跨度內容的 W3C `traceparent` 標頭，API 的 `traceresponse` 標頭會記錄為跨度連結。這些一起透過任何相容的中介將 Claude Code 的用戶端跨度連線到伺服器端追蹤。出站 HTTP MCP 請求以相同方式攜帶 `traceparent`。標頭不會傳送給第三方提供者。181當追蹤啟用且 Claude Code 直接連線至 Anthropic API 時，每個模型請求都會攜帶一個 W3C `traceparent` 標頭，其值設為 `claude_code.llm_request` span 的上下文，而 API 的 `traceresponse` 標頭則會記錄為 span 連結。兩者共同透過任何相容的中介，將 Claude Code 的用戶端 span 連接到伺服器端的追蹤。對外的 HTTP MCP 請求也會以相同方式攜帶 `traceparent`。此標頭不會傳送給第三方供應商。

182 182

183預設情況下，模型和 HTTP MCP 請求上的 `traceparent` 標頭僅在 `ANTHROPIC_BASE_URL` 未設定或指向 Anthropic API 時傳送，因為某些代理會拒絕無法識別的標頭。子程序 `TRACEPARENT` 變數由相同的開關控制以保持一致性。如果您透過自訂 `ANTHROPIC_BASE_URL` 代理執行 Claude Code 並想要傳播追蹤內容，請設定 `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`。183預設情況下，模型請求與 HTTP MCP 請求上的 `traceparent` 標頭僅在 `ANTHROPIC_BASE_URL` 未設定或指向 Anthropic API 時才會傳送，因為部分代理伺服器會拒絕無法辨識的標頭。為求一致，子程序的 `TRACEPARENT` 變數也由同一個開關控制。如果您透過自訂的 `ANTHROPIC_BASE_URL` 代理伺服器執行 Claude Code，並希望傳播追蹤上下文，請設定 `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`。

184 184

185在 Agent SDK 和使用 `-p` 啟動的非互動式工作階段中，Claude Code 也會在啟動每個互動跨度時從其自己的環境讀取 `TRACEPARENT` 和 `TRACESTATE`。這讓嵌入程序將其作用中的 W3C 追蹤內容傳遞到子程序中，以便 Claude Code 的跨度顯示為呼叫者分散式追蹤的子項。互動式工作階段會忽略入站 `TRACEPARENT` 以避免意外繼承來自 CI 或容器環境的環境值。185在 Agent SDK 以及以 `-p` 啟動的非互動式工作階段中，Claude Code 在啟動每個互動 span 時，也會從自身環境讀取 `TRACEPARENT` 和 `TRACESTATE`。這讓嵌入的程序能將其作用中的 W3C 追蹤上下文傳入子程序，使 Claude Code 的 span 顯示為呼叫端分散式追蹤的子項。互動式工作階段會忽略傳入的 `TRACEPARENT`，以避免意外繼承來自 CI 或容器環境的既有值。

186 186

187入站追蹤內容也適用於[事件](#events)。在設定了 `TRACEPARENT` 的 Agent SDK 和 `-p` 工作階段中，每個 OTLP 事件日誌記錄都會攜帶 `trace_id` 和 `span_id` 值，將其連結到您的應用程式追蹤，即使未設定追蹤匯出器，您的日誌後端也可以將事件與追蹤的其餘部分相關聯。187傳入的追蹤上下文也適用於[事件](#events)。在設定了 `TRACEPARENT` 的 Agent SDK 和 `-p` 工作階段中，每筆 OTLP 事件日誌記錄都會攜帶 `trace_id` 和 `span_id` 值，將其連結到您應用程式的追蹤，即使未設定追蹤匯出器亦然，讓您的日誌後端能將事件與追蹤的其餘部分建立關聯。

188 188

189在互動跨度作用中時發出的記錄會攜帶互動跨度的 ID，即使 Claude Code 在跨度的非同步內容外發出它，例如在權限提示回呼或在啟動期間緩衝並稍後匯出的記錄中。在沒有作用中互動跨度的情況下發出的記錄會直接攜帶入站 `TRACEPARENT` ID。189在互動進行中發出的記錄會攜帶互動 span 的 ID，即使 Claude Code 是在 span 的非同步上下文之外發出它亦然，例如在權限提示的回呼中，或是啟動期間緩衝、稍後才匯出的記錄。在沒有作用中互動 span 時發出的記錄，則會直接攜帶傳入的 `TRACEPARENT` ID。

190 190

191#### 跨度階層191#### Span 階層

192 192

193每個使用者提示啟動一個 `claude_code.interaction` 根跨度。API 呼叫、工具呼叫和 hook 執行會記錄為其子項。工具跨度有兩個自己的子跨度：一個用於等待權限決定所花費的時間，一個用於執行本身。當 Agent 工具或舊版 Task 工具產生子代理時，子代理的 API 和工具跨度會巢狀在父項的 `claude_code.tool` 跨度下。193每個使用者提示詞都會啟動一個 `claude_code.interaction` 根 span。API 呼叫、工具呼叫和 hook 執行會記錄為其子項。工具 span 本身有兩個子 span：一個記錄等待權限決定所花的時間，另一個記錄執行本身。當 Agent 工具（或舊版的 Task 工具）產生 subagent 時，subagent 的 API 與工具 span 會巢狀於父項的 `claude_code.tool` span 之下。

194 194

195```text theme={null}195```text theme={null}

196claude_code.interaction196claude_code.interaction

202 └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans202 └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans

203```203```

204 204

205在 Agent SDK 和 `claude -p` 工作階段中，當環境中設定了 `TRACEPARENT` 時，`claude_code.interaction` 本身會成為呼叫者跨度的子項。205在 Agent SDK 和 `claude -p` 工作階段中，當環境中設定了 `TRACEPARENT` 時，`claude_code.interaction` 本身會成為呼叫端 span 的子項。

206 206

207當 `PreToolUse` hook [延遲工具呼叫](https://code.claude.com/docs/zh-TW/hooks.md#defer-a-tool-call-for-later)時，Claude Code 會儲存延遲它的轉向的追蹤內容。當您恢復工作階段且工具重新執行時，工具的跨度會作為該較早轉向的 `claude_code.interaction` 跨度的子項加入該較早轉向的追蹤。207當 `PreToolUse` hook [延後某個工具呼叫](https://code.claude.com/docs/zh-TW/hooks.md#defer-a-tool-call-for-later)時，Claude Code 會儲存延後該呼叫之回合的追蹤上下文。當您繼續該工作階段且工具重新執行時，工具的 span 會加入先前那個回合的追蹤，成為該回合 `claude_code.interaction` span 的子項。

208 208

209#### 跨度屬性209#### Span 屬性

210 210

211每個跨度都會攜帶[標準屬性](#standard-attributes)加上與其名稱相符的 `span.type` 屬性。下表列出在每個跨度上設定的其他屬性。`llm_request`、`tool.execution` 和 `hook` 跨度在記錄失敗時設定 OpenTelemetry 狀態 `ERROR`；其他跨度始終以狀態 `UNSET` 結束。211每個 span 都攜帶[標準屬性](#standard-attributes)，外加一個與其名稱相符的 `span.type` 屬性。下表列出每個 span 上設定的其他屬性。`llm_request`、`tool.execution` 和 `hook` span 在記錄到失敗時會設定 OpenTelemetry 狀態 `ERROR`；其他 span 一律以狀態 `UNSET` 結束。

212 212

213**`claude_code.interaction`**213**`claude_code.interaction`**

214 214

215| 屬性 | 說明 | 由以下閘門控制 |215| 屬性 | 說明 | 閘控變數 |

216| - | - | - |216| - | - | - |

219| `interaction.sequence` | 互動的 1 為基礎計數器，按 Claude Code 程序而不是按工作階段計數，如 [`event.sequence`](#event-correlation-attributes) 所述 | |219| `interaction.sequence` | 從 1 起算的互動計數器，依每個 Claude Code 程序而非每個工作階段計數，如 [`event.sequence`](#event-correlation-attributes) 所述 | |

222 222

223**`claude_code.llm_request`**223**`claude_code.llm_request`**

224 224

225| 屬性 | 說明 | 由以下閘門控制 |225| 屬性 | 說明 | 閘控變數 |

226| - | - | - |226| - | - | - |

231| `query_source_safe` | `query_source` 的有界形式，無論詳細測試版追蹤是否作用中都會發出，具有 `repl_main_thread` 或 `agent.builtin.general-purpose` 等值。`:` 變成 `.`，使用者命名的代理顯示為 `agent.custom`。需要 Claude Code v2.1.268 或更新版本 | |231| `query_source_safe` | `query_source` 的有限值形式，無論詳細 beta 追蹤是否啟用都會發出，其值例如 `repl_main_thread` 或 `agent.builtin.general-purpose`。`:` 會變成 `.`，使用者命名的 agent 會顯示為 `agent.custom`。需要 Claude Code v2.1.268 或更新版本 | |

234| `workflow.run_id` | 產生此代理的[工作流程](https://code.claude.com/docs/zh-TW/workflows.md)工具執行的執行識別碼，前綴為 `wf_`。對於不是由工作流程產生的代理不存在 | |234| `workflow.run_id` | 產生此 agent 的 [Workflow](https://code.claude.com/docs/zh-TW/workflows.md) 工具執行之執行識別碼，前綴為 `wf_`。對於非由工作流程產生的 agent 不存在 | |

237| `effort` | 套用於請求的[努力等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。當 Claude Code 不傳送努力等級時不存在，例如在不支援努力的模型上。需要 Claude Code v2.1.274 或更新版本 | |237| `effort` | 套用於請求的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。需要 Claude Code v2.1.274 或更新版本 | |

242| `input_tokens` | 來自 API 使用區塊的輸入 token 計數。不包括從提示詞快取讀取或寫入提示詞快取的 token，這些會在 `cache_read_tokens` 和 `cache_creation_tokens` 中報告 | |242| `input_tokens` | 來自 API 用量區塊的輸入 token 數。不包含從提示詞快取讀取或寫入的 token，這些會在 `cache_read_tokens` 和 `cache_creation_tokens` 中回報 | |

257 257

258每次重試嘗試也會記錄為具有 `attempt` 和 `client_request_id` 屬性的 `gen_ai.request.attempt` 跨度事件。258每次重試嘗試也會記錄為一個 `gen_ai.request.attempt` span 事件，帶有 `attempt` 和 `client_request_id` 屬性。

259 259

260**`claude_code.tool`**260**`claude_code.tool`**

261 261

262| 屬性 | 說明 | 由以下閘門控制 |262| 屬性 | 說明 | 閘控變數 |

263| - | - | - |263| - | - | - |

265| `tool_name_safe` | `tool_name` 的形式，不攜帶任何使用者選擇的名稱。內建工具名稱逐字傳遞。MCP 工具名稱顯示為 `mcp_other`，除了符合幾個固定形狀的工具名稱，例如名為 `browser_*` 的 `playwright` 工具，它們逐字傳遞。需要 Claude Code v2.1.268 或更新版本 | |265| `tool_name_safe` | 不攜帶任何使用者自選名稱的 `tool_name` 形式。內建工具名稱會原樣傳遞。MCP 工具名稱會顯示為 `mcp_other`，但符合少數固定形式的工具名稱除外，例如名為 `browser_*` 的 `playwright` 工具，會原樣傳遞。需要 Claude Code v2.1.268 或更新版本 | |

266| `bash_command_class` | 對於 Bash 工具：命令的第一個程式的類別，來自固定清單，例如 `vcs` 或 `package_manager`。`other` 用於清單外的程式，`unparsed` 當行無法解析時。需要 Claude Code v2.1.268 或更新版本 | |266| `bash_command_class` | 適用於 Bash 工具：命令的第一個程式在固定清單中的類別，例如 `vcs` 或 `package_manager`。程式不在清單中時為 `other`，該行無法剖析時為 `unparsed`。需要 Claude Code v2.1.268 或更新版本 | |

267| `bash_argv0` | 對於 Bash 工具：當命令的第一個程式在相同的固定清單上時，為該程式本身，例如 `git` 或 `npm`。`other` 用於清單外的任何程式。需要 Claude Code v2.1.268 或更新版本 | |267| `bash_argv0` | 適用於 Bash 工具：當命令的第一個程式位於同一份固定清單中時，即為該程式，例如 `git` 或 `npm`。任何不在清單中的程式皆為 `other`。需要 Claude Code v2.1.268 或更新版本 | |

274| `tool_use_id` | 此呼叫的模型 `tool_use` 區塊 id。與 [tool\_result](#tool-result-event) 和 [tool\_decision](#tool-decision-event) 事件上的 `tool_use_id` 以及 hook 承載中的相符，因此您可以將跨度連結到這些記錄 | |274| `tool_use_id` | 模型針對此呼叫的 `tool_use` 區塊 id。與 [tool\_result](#tool-result-event) 和 [tool\_decision](#tool-decision-event) 事件上以及 hook payload 中的 `tool_use_id` 相符，讓您可以將 span 與這些記錄關聯 | |

280 280

~~281**`claude_code.tool` 上的 `tool.output` 跨度事件**~~281**`claude_code.tool` 上的 `tool.output` span 事件**

282 282

283如果您設定 `OTEL_LOG_TOOL_CONTENT=1`，Read 和 Bash 呼叫可以在 `claude_code.tool` 跨度上記錄 `tool.output` 跨度事件。Edit 和 Write 呼叫只有在您也設定 `OTEL_LOG_TOOL_DETAILS=1` 時才會記錄一個。該變數不限於這兩個工具，因此請檢查其[設定表中的列](#common-configuration-variables)以了解它在其他地方新增的引數。283如果您設定 `OTEL_LOG_TOOL_CONTENT=1`，Read 和 Bash 呼叫可以在 `claude_code.tool` span 上記錄 `tool.output` span 事件。Edit 和 Write 呼叫僅在您同時設定 `OTEL_LOG_TOOL_DETAILS=1` 時才會記錄。該變數的範圍並不限於這兩個工具，因此請查看其[在設定表中的列](#common-configuration-variables)，了解它在其他地方新增的引數。

284 284

285MCP 工具、WebFetch 和 WebSearch 也會記錄此事件，在 Claude Code v2.1.283 或更新版本上。285在 Claude Code v2.1.283 或更新版本上，MCP 工具、WebFetch 和 WebSearch 也會記錄此事件。

286 286

287Claude Code 從工具呼叫的成功返回時寫入此事件，因此引發錯誤的呼叫不會記錄任何內容，無論工具如何。在確實返回的呼叫中，它不會為以下內容記錄 `tool.output` 事件：287Claude Code 會根據工具呼叫的成功傳回來寫入此事件，因此引發錯誤的呼叫不會記錄任何內容，無論是哪個工具。在確實有傳回的呼叫中，下列情況不會記錄 `tool.output` 事件：

288 288

289* 呼叫 Read、Edit、Write、Bash、WebFetch、WebSearch 和 MCP 工具以外的任何工具289* 對 Read、Edit、Write、Bash、WebFetch、WebSearch 和 MCP 工具以外之任何工具的呼叫

290* 返回檔案文字以外的任何內容的 Read，例如影片、PDF 或檔案內容未變更的重新讀取290* 傳回檔案文字以外內容的 Read，例如影像、PDF，或重新讀取內容未變更的檔案

291* Edit 或 Write 呼叫，除非您也設定 `OTEL_LOG_TOOL_DETAILS=1`291* Edit 或 Write 呼叫，除非您同時設定了 `OTEL_LOG_TOOL_DETAILS=1`

292* Claude Code 在執行期間將其移至背景，以便等待中的訊息能夠傳達給 Claude 的 WebFetch 或 WebSearch 呼叫。稍後到達的結果也不會被記錄。若要了解 Claude Code 何時移動呼叫，請參閱終端機的[Claude Code 何時傳送您佇列的內容](https://code.claude.com/docs/zh-TW/interactive-mode.md#when-claude-code-sends-what-you-queued)，以及 Agent SDK 工作階段的 [`priority` 欄位](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#sdkusermessage)292* Claude Code 在執行期間移至背景、以便讓等待中的訊息能傳達給 Claude 的 WebFetch 或 WebSearch 呼叫。稍後抵達的結果也不會記錄。若要了解 Claude Code 何時會移動呼叫，終端機請參閱 [Claude Code 何時傳送您排入佇列的內容](https://code.claude.com/docs/zh-TW/interactive-mode.md#when-claude-code-sends-what-you-queued)，Agent SDK 工作階段請參閱 [`priority` 欄位](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#sdkusermessage)

293 293

294該事件攜帶這些屬性，每個都在內容限制處截斷（預設值 60 KB）。`由以下閘門控制` 命名屬性在 `OTEL_LOG_TOOL_CONTENT=1` 之上需要的變數，對於 Edit 和 Write，該變數控制事件本身而不是屬性。294此事件攜帶下列屬性，每個屬性都會在內容上限（預設為 60 KB）處截斷。「閘控變數」欄列出屬性在 `OTEL_LOG_TOOL_CONTENT=1` 之外還需要的變數；對於 Edit 和 Write，該變數閘控的是事件本身而非屬性。

295 295

296| 屬性 | 說明 | 由以下閘門控制 |296| 屬性 | 說明 | 閘控變數 |

297| - | - | - |297| - | - | - |

299| `output` | 對於 Bash 工具，命令的組合輸出，stderr 交錯到 stdout。對於 MCP 工具、WebFetch 或 WebSearch，工具返回的結果：文字區塊由換行符連結，影片或文件被替換為 `[image]` 等佔位符 | |299| `output` | 對於 Bash 工具，為命令的合併輸出，stderr 會交錯併入 stdout。對於 MCP 工具、WebFetch 或 WebSearch，為工具傳回的結果：文字區塊以換行連接，影像或文件會替換為預留位置，例如 `[image]` | |

303 303

304父跨度的 `tool_name` 屬性告訴您事件來自哪個工具。在內容限制處切割的屬性伴隨著 `<attribute>_truncated` 和 `<attribute>_original_length`。304父 span 的 `tool_name` 屬性會告訴您事件來自哪個工具。在內容上限處被截斷的屬性會附帶 `<attribute>_truncated` 和 `<attribute>_original_length`。

305 305

306**`claude_code.tool.blocked_on_user`**306**`claude_code.tool.blocked_on_user`**

307 307

308| 屬性 | 說明 | 由以下閘門控制 |308| 屬性 | 說明 | 閘控變數 |

309| - | - | - |309| - | - | - |

312| `source` | 對於 `accept` 或 `reject`，表示決定的來源，例如 `config`、`hook` 或 `user_temporary`，其含義如[工具決定事件](#tool-decision-event)所述。對於 `cancelled`，表示在做出任何決定之前結束等待的原因，例如 `user_abort` | |312| `source` | 對於 `accept` 或 `reject`，為決定的來源，例如 `config`、`hook` 或 `user_temporary`，其含義如 [Tool decision 事件](#tool-decision-event)中所述。對於 `cancelled`，為在做出任何決定前結束等待的原因，例如 `user_abort` | |

313 313

314`source` 為 `user_abort` 的 `cancelled` 決定，表示在權限提示或[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)檢查仍待處理時，一則需要立即傳遞的訊息中斷了該回合。例如，在自動模式檢查期間，使用者有一則已排入佇列的訊息，並[立即傳送了它](https://code.claude.com/docs/zh-TW/interactive-mode.md#when-claude-code-sends-what-you-queued)。314`source` 為 `user_abort` 的 `cancelled` 決定，表示在權限提示或[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)檢查仍待處理時，有一則需要立即傳遞的訊息中斷了該回合。例如，在自動模式檢查期間，使用者有一則已排入佇列的訊息，並[立即傳送了它](https://code.claude.com/docs/zh-TW/interactive-mode.md#when-claude-code-sends-what-you-queued)。

315 315

316**`claude_code.tool.execution`**316**`claude_code.tool.execution`**

317 317

318| 屬性 | 說明 | 由以下閘門控制 |318| 屬性 | 說明 | 閘控變數 |

319| - | - | - |319| - | - | - |

325| `error_class` | 識別碼形式的錯誤類別，字母、數字和底線以外的字元被替換為 `_`，例如 `Error_ENOENT` 或 `ShellError`。即使 `error` 攜帶完整訊息也會攜帶類別。需要 Claude Code v2.1.268 或更新版本 | |325| `error_class` | 識別碼形式的錯誤類別，字母、數字和底線以外的字元會替換為 `_`，例如 `Error_ENOENT` 或 `ShellError`。即使 `error` 攜帶完整訊息，此屬性仍攜帶類別。需要 Claude Code v2.1.268 或更新版本 | |

326 326

327**`claude_code.hook`**327**`claude_code.hook`**

328 328

329此跨度僅在詳細測試版追蹤作用中時出現，這需要 `ENABLE_BETA_TRACING_DETAILED=1` 和 `BETA_TRACING_ENDPOINT`，一對也[變更日誌和追蹤的去向](https://code.claude.com/docs/zh-TW/env-vars.md#variables)。在您的殼層、使用者設定或受管設定中設定該對；兩個變數都在[專案和本機設定](https://code.claude.com/docs/zh-TW/settings-reference.md#variables-claude-code-ignores-in-env)中被忽略。`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 單獨不會產生它。329此 span 僅在詳細 beta 追蹤啟用時出現，這需要 `ENABLE_BETA_TRACING_DETAILED=1` 和 `BETA_TRACING_ENDPOINT`，這組變數也會[變更您日誌與追蹤的傳送目的地](https://code.claude.com/docs/zh-TW/env-vars.md#variables)。請在您的 shell、使用者設定或受管設定中設定這組變數；這兩個變數在[專案與本機設定](https://code.claude.com/docs/zh-TW/settings-reference.md#variables-claude-code-ignores-in-env)中會被忽略。單獨設定 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 不會產生此 span。

330 330

331在互動式 CLI 工作階段中，詳細測試版追蹤也需要您的組織被列入該功能的允許清單。Agent SDK 和非互動式 `-p` 工作階段不需要允許清單。331在互動式 CLI 工作階段中，詳細 beta 追蹤還需要您的組織已列入此功能的允許清單。Agent SDK 和非互動式 `-p` 工作階段不需要列入允許清單。

332 332

333> [!WARNING]333> [!WARNING]

334>334>

335> 僅在除錯時設定 `ENABLE_BETA_TRACING_DETAILED`，請勿在正式環境中設定。詳細測試版追蹤的匯出量很高，且其[內容屬性](#new-context-gates)不屬於穩定跨度 schema 的一部分。335> 僅在除錯時設定 `ENABLE_BETA_TRACING_DETAILED`，請勿用於正式環境。詳細 beta 追蹤的匯出量很大，且其[內容屬性](#new-context-gates)不屬於穩定的 span schema。

336 336

337| 屬性 | 說明 | 由以下閘門控制 |337| 屬性 | 說明 | 閘控變數 |

338| - | - | - |338| - | - | - |

348 348

349**詳細測試版追蹤下的內容屬性**349**詳細 beta 追蹤下的內容屬性**

350 350

351> [!NOTE]351> [!NOTE]

352>352>

353> 其他內容承載屬性，例如 `new_context`、`system_reminders`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，僅在詳細測試版追蹤作用中時發出。它們不是穩定跨度 schema 的一部分。353> 其他攜帶內容的屬性，例如 `new_context`、`system_reminders`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，僅在詳細 beta 追蹤啟用時才會發出。它們不屬於穩定的 span schema。

354 354

355這些屬性出現在以下跨度上，`由以下閘門控制` 命名屬性在詳細測試版追蹤之上需要的變數。長於內容限制（預設值 60 KB）的值會被截斷。355這些屬性出現在下列 span 上，「閘控變數」欄列出屬性在詳細 beta 追蹤之外還需要的變數。長度超過內容上限（預設為 60 KB）的值會被截斷。

356 356

357| 屬性 | 跨度 | 說明 | 由以下閘門控制 |357| 屬性 | Span | 說明 | 閘控變數 |

358| - | - | - | - |358| - | - | - | - |

367 367

368在詳細測試版追蹤下且設定 `OTEL_LOG_USER_PROMPTS=1` 時，Claude Code 也會發出 `claude_code.system_prompt` 事件，攜帶完整的系統提示詞，並在內容限制處截斷。它會在工作階段首次傳送每個不同的系統提示詞時到達，並在壓縮後再次到達。368在詳細 beta 追蹤下並設定 `OTEL_LOG_USER_PROMPTS=1` 時，Claude Code 也會發出 `claude_code.system_prompt` 事件，攜帶完整的系統提示詞，並在內容上限處截斷。此事件會在工作階段首次傳送每個不同的系統提示詞時送達，並在壓縮後再次送達。

369 369

370### 動態標頭370### 動態標頭

371 371

372對於需要動態驗證的企業環境，您可以設定指令碼以動態產生標頭。動態標頭僅適用於 `http/protobuf` 和 `http/json` 協議。使用 `grpc` 協議，Claude Code 僅使用靜態標頭變數 `OTEL_EXPORTER_OTLP_HEADERS` 及其每個信號的變體。372對於需要動態身分驗證的企業環境，您可以設定一個指令碼來動態產生標頭。動態標頭僅適用於 `http/protobuf` 和 `http/json` 通訊協定。使用 `grpc` 通訊協定時，Claude Code 只會使用靜態標頭變數，即 `OTEL_EXPORTER_OTLP_HEADERS` 及其個別訊號的變體。

373 373

374#### 設定設定374#### 設定組態

375 375

376新增至您的 `.claude/settings.json`，將路徑替換為您自己的指令碼：376加入到您的 `.claude/settings.json`，並將路徑替換為您自己的指令碼：

377 377

378```json theme={null}378```json theme={null}

379{379{

381}381}

382```382```

383 383

384該值可以是可執行檔的路徑，包括包含空格的路徑，或帶有引數的殼層命令列。在 Windows 上，該值始終透過殼層執行，因此在 JSON 值內引用包含空格的路徑。384此值可以是可執行檔的路徑（包括含有空格的路徑），或帶有引數的 shell 命令列。在 Windows 上，此值一律會透過 shell 執行，因此請在 JSON 值中為含有空格的路徑加上引號。

385 385

386#### 指令碼需求386#### 指令碼需求

387 387

388指令碼必須輸出有效的 JSON，其中包含代表 HTTP 標頭的字串鍵值對：388指令碼必須輸出有效的 JSON，以字串鍵值對表示 HTTP 標頭：

389 389

390```bash theme={null}390```bash theme={null}

391#!/bin/bash391#!/bin/bash

393echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"393echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

394```394```

395 395

396如果協助程式失敗或列印不符合這些需求的輸出，匯出會失敗，您的遙測後端在協助程式再次運作之前不會從工作階段接收任何內容。Claude Code 在以下位置報告失敗：396如果輔助程式失敗，或印出的輸出不符合這些需求，匯出就會失敗，在輔助程式恢復正常之前，您的遙測後端不會從該工作階段收到任何內容。Claude Code 會在下列位置回報此失敗：

397 397

398* 互動式工作階段中的警告通知，[`otelHeadersHelper failed; telemetry is not being exported`](https://code.claude.com/docs/zh-TW/errors#otelheadershelper-failed)，在協助程式首次失敗時每個工作階段顯示一次398* 互動式工作階段中的警告通知 [`otelHeadersHelper failed; telemetry is not being exported`](https://code.claude.com/docs/zh-TW/errors#otelheadershelper-failed)，在輔助程式首次失敗時，每個工作階段顯示一次

399* `/status` 輸出399* `/status` 輸出

400* 偵錯日誌，當使用 [`--debug`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 執行或在工作階段中執行 `/debug` 後400* 除錯日誌，在以 [`--debug`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 執行時，或在工作階段中執行 `/debug` 之後

401* stderr，在使用 `-p` 啟動的非互動式工作階段中401* stderr，在以 `-p` 啟動的非互動式工作階段中

402 402

403#### 重新整理行為403#### 重新整理行為

404 404

405標頭協助程式指令碼在啟動時執行，之後定期執行以支援令牌重新整理。預設情況下，指令碼每 29 分鐘執行一次。使用 `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` 環境變數自訂間隔。405標頭輔助指令碼會在啟動時執行，之後定期執行以支援 token 重新整理。預設情況下，指令碼每 29 分鐘執行一次。您可以使用 `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` 環境變數自訂間隔。

406 406

407### 多團隊組織支援407### 多團隊組織支援

408 408

409具有多個團隊或部門的組織可以使用 `OTEL_RESOURCE_ATTRIBUTES` 環境變數新增自訂屬性以區分不同的群組：409擁有多個團隊或部門的組織，可以使用 `OTEL_RESOURCE_ATTRIBUTES` 環境變數新增自訂屬性，以區分不同群組：

410 410

411```bash theme={null}411```bash theme={null}

412# Add custom attributes for team identification412# Add custom attributes for team identification

413export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"413export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

414```414```

415 415

416這些自訂屬性包含在所有指標和事件中，允許您：416這些自訂屬性會包含在所有指標和事件中，讓您能夠：

417 417

418* 按團隊或部門篩選指標418* 依團隊或部門篩選指標

419* 追蹤每個成本中心的成本419* 依成本中心追蹤成本

420* 建立團隊特定的儀表板420* 建立團隊專屬的儀表板

421* 為特定團隊設定警示421* 為特定團隊設定警示

422 422

423Claude Code 將這些值作為屬性附加到每個指標資料點和事件記錄，除了在 OTLP 資源區塊中傳送它們。因為大多數指標後端將資料點屬性公開為可查詢的標籤，您可以直接按自訂金鑰分組和篩選指標。除了 `vcs.*` [儲存庫屬性](#repository-attributes)，自訂金鑰永遠不會覆蓋[標準屬性](#standard-attributes)，例如 `user.id` 或 `session.id`：當金鑰衝突時，Claude Code 會保留內建值。423除了在 OTLP 資源區塊中傳送這些值之外，Claude Code 還會將它們作為屬性附加到每個指標資料點和事件記錄上。由於大多數指標後端會將資料點屬性公開為可查詢的標籤，您可以直接依自訂鍵將指標分組與篩選。除了 `vcs.*` [儲存庫屬性](#repository-attributes)之外，自訂鍵絕不會覆寫[標準屬性](#standard-attributes)，例如 `user.id` 或 `session.id`：當鍵發生衝突時，Claude Code 會保留內建值。

424 424

425每個自訂金鑰都會成為每個指標系列上的標籤，因此高基數值會增加指標後端中的儲存成本。若要僅在資源區塊中傳送自訂屬性並從資料點標籤中省略它們，請設定 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`。請參閱[指標基數控制](#metrics-cardinality-control)。425每個自訂鍵都會成為每個指標序列上的標籤，因此高基數的值會增加指標後端的儲存成本。若要只在資源區塊中傳送自訂屬性，並將其從資料點標籤中省略，請設定 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`。請參閱[指標基數控制](#metrics-cardinality-control)。

426 426

427> [!WARNING]427> [!WARNING]

428>428>

429> `OTEL_RESOURCE_ATTRIBUTES` 環境變數使用逗號分隔的鍵值對，具有嚴格的格式要求：429> `OTEL_RESOURCE_ATTRIBUTES` 環境變數使用以逗號分隔的 key=value 對，並有嚴格的格式需求：

430>430>

431> * **不允許空格**：值不能包含空格。例如，`user.organizationName=My Company` 無效431> * **不允許空格**：值不能包含空格。例如，`user.organizationName=My Company` 無效

432> * **格式**：必須是逗號分隔的鍵值對：`key1=value1,key2=value2`432> * **格式**：必須是以逗號分隔的 key=value 對：`key1=value1,key2=value2`

433> * **允許的字元**：僅限 US-ASCII 字元，不包括控制字元、空格、雙引號、逗號、分號和反斜線433> * **允許的字元**：僅限 US-ASCII 字元，但不包括控制字元、空白字元、雙引號、逗號、分號和反斜線

434> * **特殊字元**：允許範圍外的字元必須進行百分比編碼434> * **特殊字元**：允許範圍以外的字元必須經過百分比編碼，且值中的 `=` 必須寫成 `%3D`

435>435>

436> 對於需要空格的值，請改用底線或 camelCase。以下範例使用每種形式設定 `org.name`：436> 對於需要空格的值，請改用底線或 camelCase。下列範例分別以這兩種形式設定 `org.name`：

437>437>

438> ```bash theme={null}438> ```bash theme={null}

439> export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"439> export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"

440> export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"440> export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

441> ```441> ```

442>442>

443> 您可以百分比編碼任何字元，不僅是排除的字元。此範例對空格和撇號進行編碼：443> 您可以對任何字元進行百分比編碼，不限於被排除的字元。此範例同時編碼了空格和撇號：

444>444>

445> ```bash theme={null}445> ```bash theme={null}

446> export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"446> export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

447> ```447> ```

448>448>

449> 將值包裝在引號中不會逃脫空格。例如，`org.name="My Company"` 會導致文字值 `"My Company"`（包括引號），而不是 `My Company`。449> 將值包在引號中並不會跳脫空格。例如，`org.name="My Company"` 會產生包含引號的字面值 `"My Company"`，而不是 `My Company`。

450 450

451### 將遙測歸因至 Desktop SSH 工作階段451### 將遙測歸屬至 Desktop SSH 工作階段

452 452

453若要查看 [Desktop SSH 工作階段](https://code.claude.com/docs/zh-TW/desktop.md#ssh-sessions)在哪台遠端機器上執行，請在自訂屬性中為每台機器命名。指標和事件不會指明工作階段執行所在的機器。453若要查看 [Desktop SSH 工作階段](https://code.claude.com/docs/zh-TW/desktop.md#ssh-sessions)是在哪台遠端機器上執行，請在自訂屬性中為每台機器命名。指標和事件不會指出工作階段執行所在的機器。

454 454

455在每台遠端機器上，將 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) 新增至開啟遙測的 `env` 區塊，該區塊位於[工作階段讀取的受管設定檔](https://code.claude.com/docs/zh-TW/desktop.md#managed-settings)中。在每台機器的檔案中直接寫出名稱。Claude Code 不會展開該值，因此 `host.name=$(hostname)` 會以這些字元原樣到達。455在每台遠端機器上，將 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) 加入到開啟遙測的 `env` 區塊中，該區塊位於[工作階段所讀取的受管設定檔](https://code.claude.com/docs/zh-TW/desktop.md#managed-settings)中。請在每台機器的檔案中寫出名稱。Claude Code 不會展開該值，因此 `host.name=$(hostname)` 會以這些字元原樣送達。

456 456

457以下範例將機器命名為 `build-7`：457下列範例將機器命名為 `build-7`：

458 458

459```json theme={null}459```json theme={null}

460{460{

469}469}

470```470```

471 471

472當沒有其他項目設定此變數時，`host.name` 會出現在資源區塊中，無論是在 Desktop SSH 工作階段中，或是在該機器上的 CLI 中。關於自訂屬性還會出現在哪些地方，請參閱[多團隊組織支援](#multi-team-organization-support)。472當沒有其他來源設定此變數時，`host.name` 會出現在資源區塊中，無論是在 Desktop SSH 工作階段中，還是在該機器上的 CLI 中。關於自訂屬性還會出現在哪些地方，請參閱[多團隊組織支援](#multi-team-organization-support)。

473 473

474如果名稱沒有到達，請檢查是否為以下原因之一：474如果名稱沒有送達，請檢查是否為下列原因之一：

475 475

476* **您在執行 Desktop 的電腦上設定了它**：Desktop 不會將您在該處設定的值傳遞給 SSH 工作階段476* **您在執行 Desktop 的電腦上設定了它**：Desktop 不會將您在那裡設定的值傳遞給 SSH 工作階段

477* **您在 `/etc/profile` 或其他只有登入 shell 會讀取的檔案中匯出了它**：當您從登入 shell 執行 `claude` 時名稱會到達，但在 Desktop SSH 工作階段中不會。Desktop 不會透過登入 shell 啟動 Claude Code。請改為在遠端機器上的[受管設定檔](https://code.claude.com/docs/zh-TW/desktop.md#managed-settings)中，於 `env` 下設定此變數。477* **您在 `/etc/profile` 或其他只有登入 shell 才會讀取的檔案中匯出了它**：當您從登入 shell 執行 `claude` 時名稱會送達，但在 Desktop SSH 工作階段中則不會。Desktop 不會透過登入 shell 啟動 Claude Code。請改為在遠端機器上的[受管設定檔](https://code.claude.com/docs/zh-TW/desktop.md#managed-settings)中，於 `env` 下設定此變數。

478* **值中含有空格**：此時 Claude Code 不會將任何鍵複製到事件或資料點上，也不會回報錯誤。[移除值中的空格](#multi-team-organization-support)。478* **某個值中含有空格**：此時 Claude Code 不會將任何鍵複製到事件或資料點上。若要查看哪個值含有空格，請在遠端機器上的工作階段中執行 `/status`。[移除值中的空格](#multi-team-organization-support)。

479* **其他項目已設定此變數**：在桌面應用程式啟動的工作階段中，啟動環境中已設定的變數[優先於設定檔](https://code.claude.com/docs/zh-TW/settings-reference.md#how-env-values-interact-with-your-shell)。[除錯日誌](https://code.claude.com/docs/zh-TW/debug-your-config.md)會列出每個被忽略的變數。當第三方 Desktop 部署在其提供的環境中[指定 OTLP 端點](#how-managed-settings-lock-the-otlp-destination)時，該環境會攜帶 Desktop 自己的 `OTEL_RESOURCE_ATTRIBUTES`。479* **已有其他來源設定了此變數**：在桌面應用程式啟動的工作階段中，啟動環境中已設定的變數[優先於設定檔](https://code.claude.com/docs/zh-TW/settings-reference.md#how-env-values-interact-with-your-shell)。[除錯日誌](https://code.claude.com/docs/zh-TW/debug-your-config.md)會列出每個被忽略的變數。當第三方 Desktop 部署在其提供的環境中[指定 OTLP 端點](#how-managed-settings-lock-the-otlp-destination)時，該環境會攜帶 Desktop 自己的 `OTEL_RESOURCE_ATTRIBUTES`。

480 480

481### 範例設定481### 設定範例

482 482

483在執行 `claude` 之前設定這些環境變數。下面的每個案例都顯示完整的設定，每個變數都在[常見設定變數](#common-configuration-variables)下描述。若要確認設定生效，請在啟動工作階段後檢查您的後端是否有 `claude_code.session.count` 指標；[快速入門](#quick-start)涵蓋僅日誌驗證以及當沒有任何內容到達時要檢查的內容。483請在執行 `claude` 之前設定這些環境變數。下列每個情境都展示了完整的設定，每個變數的說明請見[常用設定變數](#common-configuration-variables)。若要確認設定已生效，請在啟動工作階段後檢查您的後端是否有 `claude_code.session.count` 指標；[快速入門](#quick-start)涵蓋僅日誌的驗證方式，以及在沒有任何資料送達時應檢查的項目。

484 484

485用於主控台偵錯，匯出間隔為 1 秒：485用於主控台除錯，匯出間隔為 1 秒：

486 486

487```bash theme={null}487```bash theme={null}

488export CLAUDE_CODE_ENABLE_TELEMETRY=1488export CLAUDE_CODE_ENABLE_TELEMETRY=1

506export OTEL_METRICS_EXPORTER=prometheus506export OTEL_METRICS_EXPORTER=prometheus

507```507```

508 508

509在[自託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference.md#pass-through-session-child-metrics)上，工作階段僅在執行器的預設容量為 1 時繫結連接埠 9464。在更高的容量下，執行器改為在其自己的 `/metrics` 端點上重新公開工作階段計數器和量表。509在[自行託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference.md#pass-through-session-child-metrics)中，僅當 runner 採用預設容量 1 時，工作階段才會繫結連接埠 9464。在較高容量下，runner 會改為在其自己的 `/metrics` 端點上重新公開工作階段的計數器與量測值。

510 510

511若要將指標傳送到多個匯出器：511將指標傳送到多個匯出器：

512 512

513```bash theme={null}513```bash theme={null}

514export CLAUDE_CODE_ENABLE_TELEMETRY=1514export CLAUDE_CODE_ENABLE_TELEMETRY=1

516export OTEL_EXPORTER_OTLP_PROTOCOL=http/json516export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

517```517```

518 518

519若要將指標和日誌傳送到不同的端點或後端：519將指標和日誌傳送到不同的端點或後端：

520 520

521```bash theme={null}521```bash theme={null}

522export CLAUDE_CODE_ENABLE_TELEMETRY=1522export CLAUDE_CODE_ENABLE_TELEMETRY=1

528export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317528export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

529```529```

530 530

531若要僅匯出指標，不匯出事件或日誌：531僅匯出指標，不匯出事件或日誌：

532 532

533```bash theme={null}533```bash theme={null}

534export CLAUDE_CODE_ENABLE_TELEMETRY=1534export CLAUDE_CODE_ENABLE_TELEMETRY=1

537export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317537export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

538```538```

539 539

540若要僅匯出事件和日誌，不匯出指標：540僅匯出事件和日誌，不匯出指標：

541 541

542```bash theme={null}542```bash theme={null}

543export CLAUDE_CODE_ENABLE_TELEMETRY=1543export CLAUDE_CODE_ENABLE_TELEMETRY=1

permission-modes.md +2 −1

Details

304claude --permission-mode plan304claude --permission-mode plan

305```305```

306 306

307再次按下 `Shift+Tab` 即可在不核准計畫的情況下離開 plan mode。307在沒有開啟核准提示的情況下，再次按下 `Shift+Tab` 即可離開 plan mode。在核准提示中，請先按下 `Esc`，因為在該處按下 `Shift+Tab` 會核准計畫。

308 308

309### 審查並核准計畫309### 審查並核准計畫

310 310

593> * 當 Claude 讀取[其他人製作的 artifact](https://code.claude.com/docs/zh-TW/artifacts.md#read-an-artifact-shared-with-you) 時，適用該章節所列的核准情況593> * 當 Claude 讀取[其他人製作的 artifact](https://code.claude.com/docs/zh-TW/artifacts.md#read-an-artifact-shared-with-you) 時，適用該章節所列的核准情況

594> * 從[網路路徑](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)讀取會提示您594> * 從[網路路徑](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)讀取會提示您

595> 3. 其他所有操作都會送交分類器，但採用預設處理方式的[關鍵路徑移除](#critical-paths)除外。在步驟 1 中直接提示您的連接器工具和 `requiresUserInteraction` MCP 工具也永遠不會送到分類器，因此組織要求的核准和同意步驟都不會被自動核准595> 3. 其他所有操作都會送交分類器，但採用預設處理方式的[關鍵路徑移除](#critical-paths)除外。在步驟 1 中直接提示您的連接器工具和 `requiresUserInteraction` MCP 工具也永遠不會送到分類器，因此組織要求的核准和同意步驟都不會被自動核准

596> * 啟用 [Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md#permission-checks) 時，Claude 的程式碼會在執行前送交分類器一次，而其中的工具呼叫則不會。您仍可使用 `deny` 規則阻止呼叫，或使用 `ask` 規則要求提示，但 Claude 可以用[規則無法比對的形式](https://code.claude.com/docs/zh-TW/permissions.md#bash-rule-limits)執行 Bash 命令

596> 4. 如果分類器阻止操作，Claude 會收到原因。在大多數工作階段中，原因會指明分類器比對到的規則，例如 `[Data Exfiltration]`，而不是提供書面說明；請參閱[檢視拒絕](https://code.claude.com/docs/zh-TW/auto-mode-config.md#review-denials)597> 4. 如果分類器阻止操作，Claude 會收到原因。在大多數工作階段中，原因會指明分類器比對到的規則，例如 `[Data Exfiltration]`，而不是提供書面說明；請參閱[檢視拒絕](https://code.claude.com/docs/zh-TW/auto-mode-config.md#review-denials)

597>598>

598> 您安裝的處理 `tool.check` 的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 也可以核准操作。關於其核准無法越過您的規則和 hook 的情況，請參閱[使用 hook 擴充權限](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)。599> 您安裝的處理 `tool.check` 的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 也可以核准操作。關於其核准無法越過您的規則和 hook 的情況，請參閱[使用 hook 擴充權限](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)。

permissions.md +1 −1

Details

784* 在儲存庫外，Claude Code 會以您啟動它的目錄作為信任的鍵，信任涵蓋該目錄的任何子目錄，除了巢狀在其中的 git 儲存庫（例如複製）。每個涵蓋的子目錄隨後都會計為一個您信任其父目錄的資料夾。784* 在儲存庫外，Claude Code 會以您啟動它的目錄作為信任的鍵，信任涵蓋該目錄的任何子目錄，除了巢狀在其中的 git 儲存庫（例如複製）。每個涵蓋的子目錄隨後都會計為一個您信任其父目錄的資料夾。

785* 當您在家目錄中啟動時，Claude Code 只在目前工作階段內保持信任，不會將其寫入磁碟；請參閱[額外保護措施](https://code.claude.com/docs/zh-TW/security.md#additional-safeguards)說明。785* 當您在家目錄中啟動時，Claude Code 只在目前工作階段內保持信任，不會將其寫入磁碟；請參閱[額外保護措施](https://code.claude.com/docs/zh-TW/security.md#additional-safeguards)說明。

786 786

787Claude Code 只在互動工作階段中顯示信任對話框。`claude -p` 執行或 SDK 工作階段永遠不會顯示它，信任父資料夾不會計入這些規則，因此[您信任資料夾前執行的內容](#what-runs-before-you-trust-a-folder)說明了在這兩種情況下 Claude Code 仍然使用的儲存庫內容。787VS Code 擴充功能在啟動工作階段之前，會以標題為 `Trust this folder in Claude Code?` 的對話框要求相同的信任。Claude Code 會在互動式終端機工作階段中顯示信任對話框，但不會在 `claude -p` 或 SDK 工作階段中顯示。信任父資料夾不會計入這些規則。[您信任資料夾前執行的內容](#what-runs-before-you-trust-a-folder)說明了在各種情況下 Claude Code 仍會使用哪些儲存庫內容。

788 788

789在啟動或重新啟動[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)之前，Claude Code 也會檢查工作階段執行所在目錄的工作區信任。如果您從未信任的目錄中的終端機執行 `claude --bg`，信任對話框會先出現，一旦您接受它，工作階段就會啟動。在無法出現對話框的地方（例如在指令碼中），命令會改為以[`Workspace not trusted`](https://code.claude.com/docs/zh-TW/errors#workspace-not-trusted-when-dispatching-a-background-session)錯誤結束。789在啟動或重新啟動[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)之前，Claude Code 也會檢查工作階段執行所在目錄的工作區信任。如果您從未信任的目錄中的終端機執行 `claude --bg`，信任對話框會先出現，一旦您接受它，工作階段就會啟動。在無法出現對話框的地方（例如在指令碼中），命令會改為以[`Workspace not trusted`](https://code.claude.com/docs/zh-TW/errors#workspace-not-trusted-when-dispatching-a-background-session)錯誤結束。

790 790

plugins/components.md +3 −38

Details

4 4

5# 新增元件至外掛程式5# 新增元件至外掛程式

6 6

~~7> 新增技能、hooks、MCP 伺服器及其他所有元件類型至 Claude Code 外掛程式，並提供每種元件的驗證範例。~~7> 新增 skill、hook、MCP 伺服器及其他元件類型至 Claude Code 外掛程式，並提供每種元件的驗證範例。

8 8

9Claude Code 外掛程式由多個元件組成，例如技能、代理、hooks 和 MCP 伺服器。每個元件在外掛程式中都有一個預設資料夾、`.claude-plugin/plugin.json` 中的選用資訊清單鍵（用於取代或新增至該資料夾），以及使用者看到的名稱。如需每個鍵的完整欄位表，請參閱[資訊清單參考](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md#fields)。9Claude Code 外掛程式由多個元件組成，例如技能、代理、hooks 和 MCP 伺服器。每個元件在外掛程式中都有一個預設資料夾、`.claude-plugin/plugin.json` 中的選用資訊清單鍵（用於取代或新增至該資料夾），以及使用者看到的名稱。如需每個鍵的完整欄位表，請參閱[資訊清單參考](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md#fields)。

10 10

22 22

23## 探索外掛程式目錄23## 探索外掛程式目錄

24 24

~~25探索器顯示一個範例外掛程式 `my-plugin`，在其預設位置中包含每種元件的一個：~~25探索器顯示一個範例外掛 `my-plugin`，其預設位置中包含以下元件：

26 26

27* 一個審查技能和一個 `about` 命令27* 一個審查技能和一個 `about` 命令

28* 一個安全審查子代理28* 一個安全審查子代理

31* 一個輸出樣式和一個色彩主題31* 一個輸出樣式和一個色彩主題

32* 一個路由審計工作流程32* 一個路由審計工作流程

33* 一個 `hello-plugin` 可執行檔33* 一個 `hello-plugin` 可執行檔

~~34* 預設設定~~

35* 一個本機 MCP 伺服器和一個 Go 語言伺服器34* 一個本機 MCP 伺服器和一個 Go 語言伺服器

36 35

37每個檔案都是其格式的最小有效範例，目的是展示形狀而不是實用性：真實的技能或代理包含完整的指示，通常還有支援檔案，真實的掛鉤或監視器執行真實的工作。探索器之後的章節使用相同的檔案作為範例，並連結到更完整的版本。選擇一個檔案或資料夾來閱讀它的用途、查看其中的內容，並找到涵蓋它的章節。36每個檔案都是其格式的最小有效範例，目的是展示形狀而不是實用性：真實的技能或代理包含完整的指示，通常還有支援檔案，真實的掛鉤或監視器執行真實的工作。探索器之後的章節使用相同的檔案作為範例，並連結到更完整的版本。選擇一個檔案或資料夾來閱讀它的用途、查看其中的內容，並找到涵蓋它的章節。

38 37

39What goes in a plugin38What goes in a plugin

40 39

~~41This example plugin, `my-plugin`, has one of every kind of component, each in its default location. Select a file or folder to read what it’s for and see what goes in it.~~40This example plugin, `my-plugin`, has the components listed here, each in its default location. Select a file or folder to read what it’s for and see what goes in it.

42 41

43Plugin directory42Plugin directory

44 43

178npx prettier --write .177npx prettier --write .

179```178```

180 179

181外掛程式根目錄中的 `settings.json` 包含在外掛程式啟用時適用的 [settings](https://code.claude.com/docs/zh-TW/settings-reference.md)，因此外掛程式可以改變工作階段的行為方式，而不僅僅是新增元件。只有兩個鍵從外掛程式生效，[`agent`](https://code.claude.com/docs/zh-TW/settings-reference#agent) 和 [`subagentStatusLine`](https://code.claude.com/docs/zh-TW/settings-reference#subagentstatusline)；所有其他鍵都被丟棄。請參閱 [Default settings](#default-settings)。

~~182~~

183這個設定 `agent`，它執行工作階段的主執行緒作為外掛程式自己的 `security-reviewer` 代理，因此該代理的系統提示、工具限制和模型適用於整個工作階段：

~~184~~

185```json theme={null}

186{

187 "agent": "security-reviewer"

188}

189```

~~190~~

191[MCP server](https://code.claude.com/docs/zh-TW/mcp.md) 從外部系統為 Claude 提供工具。在外掛程式根目錄的 `.mcp.json` 中宣告它。這個從外掛程式內的指令碼啟動本機伺服器，並在 `/mcp` 中顯示為 `plugin:my-plugin:db`：180[MCP server](https://code.claude.com/docs/zh-TW/mcp.md) 從外部系統為 Claude 提供工具。在外掛程式根目錄的 `.mcp.json` 中宣告它。這個從外掛程式內的指令碼啟動本機伺服器，並在 `/mcp` 中顯示為 `plugin:my-plugin:db`：

192 181

193```json theme={null}182```json theme={null}

484 473

485claude.ai 和 Cowork 不安裝具有頂層 `bin/` 目錄的外掛程式，包括您 [透過 claude.ai 組織設定分發](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory) 的外掛程式。474claude.ai 和 Cowork 不安裝具有頂層 `bin/` 目錄的外掛程式，包括您 [透過 claude.ai 組織設定分發](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory) 的外掛程式。

486 475

487### 預設設定

~~488~~

489若要設定在啟用外掛程式時適用的預設值，在外掛程式根目錄新增 `settings.json`，或將相同的物件內嵌放在 `settings` manifest 鍵中。兩個鍵生效，`agent` 和 `subagentStatusLine`，所有其他鍵都被丟棄。

~~490~~

491設定 `agent` 以執行外掛程式自己的一個 agents 作為主執行緒：

~~492~~

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

494{

495 "agent": "security-reviewer"

496}

497```

~~498~~

499載入外掛程式並啟動工作階段。Claude 然後使用 `security-reviewer` agent 的系統提示和模型在主對話中回答。

~~500~~

501如需鍵控制的所有內容，請參閱 [`agent` 設定](https://code.claude.com/docs/zh-TW/settings-reference#agent)。

~~502~~

503當相同的鍵在多個位置設定時，這些規則決定哪個值適用：

~~504~~

505* **檔案優於 manifest**：當兩者都存在且 `settings.json` 設定至少一個支援的鍵時，`settings.json` 適用，manifest 的 `settings` 被忽略

506* **使用者設定優於外掛程式預設值**：在設定來源中，外掛程式預設值是最低層，因此使用者自己在 `~/.claude/settings.json` 中的 `agent` 覆蓋您的

507* **兩個外掛程式設定相同的鍵**：來自最後載入的外掛程式的值適用，`claude --debug` 記錄 `overrides setting`

~~508~~

509如需 `subagentStatusLine` 形狀，請參閱 [子代理狀態行](https://code.claude.com/docs/zh-TW/statusline.md#subagent-status-lines)。

~~510~~

511### 主題和輸出樣式476### 主題和輸出樣式

512 477

513外掛程式可以包含色彩主題和輸出樣式。兩者都出現在與使用者自己相同的選擇器中。對於任一個，設定 manifest 鍵取代資料夾掃描。478外掛程式可以包含色彩主題和輸出樣式。兩者都出現在與使用者自己相同的選擇器中。對於任一個，設定 manifest 鍵取代資料夾掃描。

plugins/create.md +43 −43

Details

34 34

35若要將現有設定移到外掛程式中，請參閱[轉換現有的 `.claude/` 設定](#convert-an-existing-claude-setup)。35若要將現有設定移到外掛程式中，請參閱[轉換現有的 `.claude/` 設定](#convert-an-existing-claude-setup)。

36 36

~~37## 建立您的第一個外掛程式~~37## 建立您的第一個外掛

38 38

39在此逐步解說中，您建立一個外掛程式，其唯一元件是一個技能（問候），並使用 `--plugin-dir` 執行它，該選項會為一個工作階段載入外掛程式而不安裝它。外掛程式可以包含任何[元件](https://code.claude.com/docs/zh-TW/plugins/components.md)的組合，例如技能、代理、hooks 和 MCP 伺服器，且不需要任何一個；一個技能是展示佈局的最小範例。39在這個逐步教學中，您將建立一個外掛，其唯一的元件是一個 skill（打招呼），並使用 `--plugin-dir` 執行它；此旗標會在單一工作階段中載入外掛，而不需安裝。外掛可以包含任意組合的[元件](https://code.claude.com/docs/zh-TW/plugins/components.md)，例如 skill、agent、hook 和 MCP 伺服器，且沒有任何一種是必要的；單一 skill 是能展示目錄結構的最小範例。

40 40

~~41您需要 Claude Code [已安裝並登入](https://code.claude.com/docs/zh-TW/quickstart.md#step-1-install-claude-code)。~~41您需要已[安裝並登入](https://code.claude.com/docs/zh-TW/quickstart.md#step-1-install-claude-code) Claude Code。

42 42

43在您想保留外掛程式的目錄（例如 `~/projects`）中開啟終端機，並從該目錄執行這些步驟中的命令。您可以將外掛程式保留在任何地方，因為當您啟動工作階段時，您會將其路徑傳遞給 Claude Code。43在您想存放外掛的目錄（例如 `~/projects`）中開啟終端機，並從該目錄執行以下步驟中的命令。外掛可以存放在任何位置，因為您會在啟動工作階段時將其路徑傳給 Claude Code。

44 44

~~45**1. 建立外掛程式目錄**~~45**1. 建立外掛目錄**

46 46

~~47建立外掛程式目錄，其中包含一個 `.claude-plugin/` 資料夾來保存清單：~~47建立外掛目錄，並在其中建立一個 `.claude-plugin/` 資料夾來存放資訊清單：

48 48

49```bash theme={null}49```bash theme={null}

50mkdir -p my-first-plugin/.claude-plugin50mkdir -p my-first-plugin/.claude-plugin

51```51```

52 52

~~53**2. 編寫清單**~~53**2. 撰寫資訊清單**

54 54

55[清單](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md)是一個名為 `plugin.json` 的 JSON 檔案，它告訴 Claude Code 外掛程式的名稱並描述它。將此檔案儲存為 `my-first-plugin/.claude-plugin/plugin.json`：55[資訊清單](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md)是一個名為 `plugin.json` 的 JSON 檔案，用來告訴 Claude Code 外掛的名稱並加以描述。將以下內容儲存為 `my-first-plugin/.claude-plugin/plugin.json`：

56 56

57```json my-first-plugin/.claude-plugin/plugin.json theme={null}57```json my-first-plugin/.claude-plugin/plugin.json theme={null}

58{58{

67 67

68這四個欄位的作用如下：68這四個欄位的作用如下：

69 69

~~70* **`name`**：必需。它識別外掛程式並成為外掛程式提供的每個技能和代理的前綴。不要在其中放置空格。~~70* **`name`**：必填。用來識別外掛，並成為外掛所提供的每個 skill 和 agent 的前綴。其中請勿包含空格。

~~71* **`description`**：使用者在 `/plugin` 中看到的外掛程式文字。~~71* **`description`**：使用者在 `/plugin` 中看到的外掛說明文字。

72* **`version`**：選用。設定它會讓使用者保持在該版本，直到您更改它；[發佈新版本](https://code.claude.com/docs/zh-TW/plugins/host-marketplace.md#release-a-new-version)說明何時設定或省略它。72* **`version`**：選填。設定後，使用者會停留在該版本，直到您變更它為止；[發布新版本](https://code.claude.com/docs/zh-TW/plugins/host-marketplace.md#release-a-new-version)說明了何時應設定或省略此欄位。

~~73* **`author`**：要歸功於誰。其中的 `name` 是必需的；`email` 和 `url` 是選用的。~~73* **`author`**：署名對象。其中 `name` 為必填；`email` 和 `url` 為選填。

74 74

~~75每個其他欄位都在[清單參考](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md#fields)上。~~75其他欄位請參閱[資訊清單參考](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md#fields)。

76 76

~~77只有 `plugin.json` 放在 `.claude-plugin/` 內。您接下來添加的技能直接放在 `my-first-plugin/` 下，在該資料夾旁邊。~~77只有 `plugin.json` 放在 `.claude-plugin/` 內。接下來新增的 skill 直接放在 `my-first-plugin/` 下，與該資料夾並列。

78 78

~~79**3. 添加技能**~~79**3. 新增 skill**

80 80

~~81此外掛程式的一個元件是一個技能。每個技能是 `skills/` 下的一個目錄，包含一個 `SKILL.md` 檔案。建立技能的目錄：~~81這個外掛唯一的元件是一個 skill。每個 skill 都是 `skills/` 下的一個目錄，其中包含一個 `SKILL.md` 檔案。建立該 skill 的目錄：

82 82

83```bash theme={null}83```bash theme={null}

84mkdir -p my-first-plugin/skills/hello84mkdir -p my-first-plugin/skills/hello

85```85```

86 86

~~87然後使用此內容建立 `my-first-plugin/skills/hello/SKILL.md`：~~87接著建立 `my-first-plugin/skills/hello/SKILL.md`，內容如下：

88 88

89```markdown my-first-plugin/skills/hello/SKILL.md theme={null}89```markdown my-first-plugin/skills/hello/SKILL.md theme={null}

90---90---

96Greet the user warmly and ask how you can help them today.96Greet the user warmly and ask how you can help them today.

97```97```

98 98

99`disable-model-invocation: true` 行表示 Claude 不會自行執行該 skill。從您希望 Claude 自行執行的 skill 中移除該行。skill 的命令結合外掛程式名稱和 skill 的名稱，因此您將此 skill 執行為 `/my-first-plugin:hello`。對於其他 frontmatter 欄位，請參閱[skill frontmatter 參考](https://code.claude.com/docs/zh-TW/skills.md#frontmatter-reference)。99`disable-model-invocation: true` 這一行表示 Claude 不會自行執行此 skill。若希望 Claude 自行執行某個 skill，請從該 skill 中移除這一行。skill 的命令由外掛名稱與 skill 名稱組合而成，因此您要以 `/my-first-plugin:hello` 執行此 skill。其他 frontmatter 欄位請參閱 [skill frontmatter 參考](https://code.claude.com/docs/zh-TW/skills.md#frontmatter-reference)。

100 100

101**4. 驗證外掛程式**101**4. 驗證外掛**

102 102

103在執行任何操作之前檢查清單和 skill 的 frontmatter：103在執行任何內容之前，先檢查資訊清單和 skill 的 frontmatter：

104 104

105```bash theme={null}105```bash theme={null}

106claude plugin validate ./my-first-plugin106claude plugin validate ./my-first-plugin

107```107```

108 108

109該命令列印它檢查的清單路徑和 `✔ Validation passed`。如果它改為列印 `✘ Validation failed`，則該結果行上方的每一行都命名要修復的欄位。在[`claude plugin validate` 報告錯誤](https://code.claude.com/docs/zh-TW/plugins/troubleshooting#claude-plugin-validate-reports-errors)下查找每條訊息。109此命令會印出所檢查的資訊清單路徑以及 `✔ Validation passed`。如果改為印出 `✘ Validation failed`，則該結果行上方的每一行都會指出需要修正的欄位。請在 [`claude plugin validate` 回報錯誤](https://code.claude.com/docs/zh-TW/plugins/troubleshooting#claude-plugin-validate-reports-errors)中查閱每則訊息。

110 110

111**5. 使用外掛程式執行 Claude Code**111**5. 搭配外掛執行 Claude Code**

112 112

113啟動已載入外掛程式的工作階段：113啟動一個載入該外掛的工作階段：

114 114

115```bash theme={null}115```bash theme={null}

116claude --plugin-dir ./my-first-plugin116claude --plugin-dir ./my-first-plugin

117```117```

118 118

119Claude Code 啟動後，執行技能：119Claude Code 啟動後，執行該 skill：

120 120

121```text theme={null}121```text theme={null}

122/my-first-plugin:hello122/my-first-plugin:hello

123```123```

124 124

125Claude 會回覆一個問候。125Claude 會回覆一則問候。

126 126

127外掛程式只在您使用 `--plugin-dir` 啟動的工作階段中載入。若要在沒有該旗標的情況下繼續處理它，或測試 `.zip` 組建，請參閱[在沒有市集的情況下開發](#develop-without-a-marketplace)。127此外掛只會在您使用 `--plugin-dir` 啟動的工作階段中載入。若要在不使用此旗標的情況下繼續開發，或要測試 `.zip` 建置，請參閱[不透過市集進行開發](#develop-without-a-marketplace)。

128 128

129若要讓 Claude 為您建立並檢查更大的外掛程式，請從 `claude-plugins-official` 市集[安裝](https://code.claude.com/docs/zh-TW/plugins/install.md#install-a-plugin) Anthropic 的 `plugin-dev` 外掛程式，該外掛程式會新增用於編寫技能、hooks 和 MCP 伺服器等元件的技能和代理，以及用於驗證完成的外掛程式的技能和代理。安裝後，執行 `/plugin-dev:create-plugin` 後跟您想要的外掛程式的描述，Claude 會引導您完成設計、建立和驗證它。129若要讓 Claude 與您一起建立並檢查較大型外掛的骨架，請從 `claude-plugins-official` 市集[安裝](https://code.claude.com/docs/zh-TW/plugins/install.md#install-a-plugin) Anthropic 的 `plugin-dev` 外掛；它會新增 skill 和 agent，用於撰寫 skill、hook 和 MCP 伺服器等元件，以及驗證完成的外掛。安裝後，執行 `/plugin-dev:create-plugin` 並在後面加上您想要的外掛描述，Claude 就會引導您完成設計、建立和驗證。

130 130

131### 分享您的外掛程式131### 分享您的外掛

132 132

133使用[建立您的第一個外掛程式](#create-your-first-plugin)建立的外掛程式只存在於您的機器上。當它準備好供其他人使用時，有三種方式可以將其提供給他們：133您透過[建立您的第一個外掛](#create-your-first-plugin)所建置的外掛只存在於您的電腦上。當它準備好提供給其他人時，有三種方式可以交付給他們：

134 134

135* **直接將其發送給少數人**：給他們外掛程式的目錄或其 `.zip`，無需發佈任何內容。請參閱[在沒有市集的情況下分享外掛程式](https://code.claude.com/docs/zh-TW/plugins/publish.md#share-a-plugin-without-a-marketplace)。135* **直接傳送給少數人**：將外掛的目錄或其 `.zip` 提供給他們，不需要發布任何內容。請參閱[不透過市集分享外掛](https://code.claude.com/docs/zh-TW/plugins/publish.md#share-a-plugin-without-a-marketplace)。

136* **在您自己的市集中列出它**：隊友添加您的市集一次並按名稱安裝外掛程式，他們會收到您的更新。請參閱[透過您自己的市集發佈](https://code.claude.com/docs/zh-TW/plugins/publish.md#publish-through-your-own-marketplace)。136* **列在您自己的市集中**：團隊成員只需新增一次您的市集，即可依名稱安裝外掛，並接收您的更新。請參閱[透過您自己的市集發布](https://code.claude.com/docs/zh-TW/plugins/publish.md#publish-through-your-own-marketplace)。

137* **將其提交到 Anthropic 的社群市集**：列出後，任何添加該市集的人都可以安裝它。請參閱[提交到社群市集](https://code.claude.com/docs/zh-TW/plugins/publish.md#submit-to-anthropics-directory)。137* **提交至 Anthropic 的目錄**：通過審查後，使用者可以在 claude.ai 和 Cowork 中新增它，並透過其帳戶將它帶入 Claude Code。請參閱[提交至 Anthropic 的目錄](https://code.claude.com/docs/zh-TW/plugins/publish.md#submit-to-anthropics-directory)。

138 138

139### 外掛程式佈局139### 外掛結構

140 140

141每種[元件](https://code.claude.com/docs/zh-TW/plugins/components.md)（例如技能、代理、hooks 和 MCP 伺服器）都放在外掛程式根目錄下的固定目錄中，外掛程式根目錄是您傳遞給 `--plugin-dir` 的目錄。只添加您使用的目錄。若要點擊完整的外掛程式目錄並閱讀每個檔案的作用，請開啟[外掛程式瀏覽器](https://code.claude.com/docs/zh-TW/plugins/components.md#explore-the-plugin-directory)。141每種[元件](https://code.claude.com/docs/zh-TW/plugins/components.md)，例如 skill、agent、hook 和 MCP 伺服器，都放在外掛根目錄下的固定目錄中；外掛根目錄就是您傳給 `--plugin-dir` 的目錄。只需新增您會用到的目錄。若要逐一點選完整的外掛目錄並了解每個檔案的作用，請開啟[外掛瀏覽器](https://code.claude.com/docs/zh-TW/plugins/components.md#explore-the-plugin-directory)。

142 142

143該表列出了大多數外掛程式開始使用的目錄，[完整佈局](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md#standard-layout)列出了其餘的。143下表列出大多數外掛一開始會使用的目錄，其餘目錄請參閱[完整結構](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md#standard-layout)。

144 144

145| 位置 | 內容 |145| 位置 | 內容 |

146| :- | :- |146| :- | :- |

153 153

154> [!WARNING]154> [!WARNING]

155>155>

156> 只有 `plugin.json` 放在 `.claude-plugin/` 內。保存在那裡的元件不會載入。156> 只有 `plugin.json` 放在 `.claude-plugin/` 內。儲存在該處的元件不會載入。

157>157>

158> 外掛程式根目錄是外掛程式自己的目錄，不是 `~/.claude/` 本身。保存在 `~/.claude/.mcp.json` 的 `.mcp.json` 不會載入。158> 外掛根目錄是外掛本身的目錄，而非 `~/.claude/` 本身。儲存在 `~/.claude/.mcp.json` 的 `.mcp.json` 不會載入。

159 159

160## 在沒有市集的情況下開發160## 在沒有市集的情況下開發

161 161

344 "PostToolUse": [344 "PostToolUse": [

345 {345 {

346 "matcher": "Write|Edit",346 "matcher": "Write|Edit",

347 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]347 "hooks": [{ "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npm run lint:fix -- \"$f\"" }]

348 }348 }

349 ]349 ]

350 }350 }

plugins/manifest-reference.md +3 −10

Details

4 4

5# Plugin manifest 參考5# Plugin manifest 參考

6 6

~~7> plugin.json 的完整參考：每個欄位的類型和預設值、接受的路徑形式，以及 userConfig 和環境變數架構。~~7> plugin.json 的完整參考：每個欄位的類型和預設值、接受的路徑形式，以及 userConfig 和環境變數 schema。

8 8

9Plugin manifest 是位於 plugin 的 `.claude-plugin/` 目錄中的 `plugin.json` 檔案。它包含 plugin 的中繼資料和 Claude Code 提示使用者輸入的 [`userConfig`](#user-configuration) 值。它也宣告任何您內聯定義或保留在其[預設位置](#standard-layout)之外的元件。9Plugin manifest 是位於 plugin 的 `.claude-plugin/` 目錄中的 `plugin.json` 檔案。它包含 plugin 的中繼資料和 Claude Code 提示使用者輸入的 [`userConfig`](#user-configuration) 值。它也宣告任何您內聯定義或保留在其[預設位置](#standard-layout)之外的元件。

10 10

117 117

118## 欄位118## 欄位

119 119

120表格列出 `plugin.json` 中的頂層鍵。`name` 是唯一必需的鍵。其中欄位名稱是連結的地方，連結的部分有其完整規則。120下表列出 `plugin.json` 中的頂層鍵。`name` 是唯一必要的鍵。若欄位名稱為連結，連結的章節包含其完整規則。

121 121

122對於元件鍵（例如 `commands` 和 `hooks`），[元件路徑形式](#component-path-forms)顯示每個接受的形式及範例，每個路徑都遵循 `./` 前綴、副檔名和包含的[路徑規則](#path-rules)。122對於元件鍵（例如 `commands` 和 `hooks`），[元件路徑形式](#component-path-forms)顯示每個接受的形式及範例，每個路徑都遵循 `./` 前綴、副檔名和包含的[路徑規則](#path-rules)。

123 123

144| [`settings`](#settings) | Object | Claude Code 在 plugin 啟用時應用的設定。只有 `agent` 和 `subagentStatusLine` 生效 |

211 210

212此 plugin 運作所必須啟用的其他 plugin。每個項目是 `"name"`、`"name@marketplace"` 或 `{ "name": "...", "marketplace": "...", "version": "..." }`。裸名稱針對此 plugin 自己的 marketplace 解析。請參閱[依賴性約束](https://code.claude.com/docs/zh-TW/plugins/dependencies.md)。211此 plugin 運作所必須啟用的其他 plugin。每個項目是 `"name"`、`"name@marketplace"` 或 `{ "name": "...", "marketplace": "...", "version": "..." }`。裸名稱針對此 plugin 自己的 marketplace 解析。請參閱[依賴性約束](https://code.claude.com/docs/zh-TW/plugins/dependencies.md)。

213 212

214### `settings`

~~215~~

216Claude Code 在 plugin 啟用時應用的設定。只有 `agent` 和 `subagentStatusLine` 生效；其他鍵在載入時被丟棄。plugin 根目錄的 `settings.json` 優先於此鍵。請參閱[預設設定](https://code.claude.com/docs/zh-TW/plugins/components.md#default-settings)。

~~217~~

218## 元件路徑形式213## 元件路徑形式

219 214

220每個元件鍵接受相對於 plugin 根目錄的路徑。`hooks`、`mcpServers`、`lspServers` 和 `experimental.monitors` 也接受內聯設定，`commands` 也接受物件對應，`mcpServers` 也接受 MCP 套件路徑和 URL。以下範例各顯示一次每個接受的形式。有關每個元件在執行時的作用，請參閱 [Plugin 元件](https://code.claude.com/docs/zh-TW/plugins/components.md)。215每個元件鍵接受相對於 plugin 根目錄的路徑。`hooks`、`mcpServers`、`lspServers` 和 `experimental.monitors` 也接受內聯設定，`commands` 也接受物件對應，`mcpServers` 也接受 MCP 套件路徑和 URL。以下範例各顯示一次每個接受的形式。有關每個元件在執行時的作用，請參閱 [Plugin 元件](https://code.claude.com/docs/zh-TW/plugins/components.md)。

626| 主題 | `themes/` | 主題 JSON 檔案 |621| 主題 | `themes/` | 主題 JSON 檔案 |

628| 可執行檔 | `bin/` | 此處的檔案在 plugin 啟用時位於 Bash 工具的 `PATH` 上，因此 Claude 將它們作為裸命令執行。claude.ai 和 Cowork 不安裝具有此目錄的 plugin，包括您[通過 claude.ai 組織設定分發](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory)的 plugin |623| 可執行檔 | `bin/` | 此處的檔案在 plugin 啟用時位於 Bash 工具的 `PATH` 上，因此 Claude 將它們作為裸命令執行。claude.ai 和 Cowork 不安裝具有此目錄的 plugin，包括您[通過 claude.ai 組織設定分發](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory)的 plugin |

629| 設定 | `settings.json` | 在 plugin 啟用時應用的 `agent` 和 `subagentStatusLine` 預設值 |

630 624

631使用每個預設位置的 plugin，加上其 hooks 呼叫的 `scripts/` 資料夾，配置如下：625使用預設位置的 plugin，加上其 hooks 呼叫的 `scripts/` 資料夾，配置如下：

632 626

633```text theme={null}627```text theme={null}

634deploy-tools/628deploy-tools/

655│ └── deploy-tool649│ └── deploy-tool

656├── scripts/650├── scripts/

657│ └── format.sh651│ └── format.sh

658├── settings.json

659├── .mcp.json652├── .mcp.json

660└── .lsp.json653└── .lsp.json

661```654```

plugins/mods/admin.md +18 −8

Details

61 * 工作階段使用 Team 或 Enterprise 計畫的 [`/login` 憑證](https://code.claude.com/docs/zh-TW/authentication#authentication-precedence)執行61 * 工作階段使用 Team 或 Enterprise 計畫的 [`/login` 憑證](https://code.claude.com/docs/zh-TW/authentication#authentication-precedence)執行

62 62

63 使用 API 金鑰的使用者，或使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 的使用者，只有在具有受管設定或 `managed-mcp.json` 的機器上才能獲得防護。使用長期 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/zh-TW/authentication#generate-a-long-lived-token) 執行的工作階段也不算是該登入，即使機器上儲存了 Team 或 Enterprise 登入也是如此。63 使用 API 金鑰的使用者，或使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 的使用者，只有在具有受管設定或 `managed-mcp.json` 的機器上才能獲得防護。使用長期 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/zh-TW/authentication#generate-a-long-lived-token) 執行的工作階段也不算是該登入，即使機器上儲存了 Team 或 Enterprise 登入也是如此。

64* **防護保護您管理的內容。** 使用者的 mod 無法更改您的受管 hooks 接收或決定的內容、系統提示、您的受管 `CLAUDE.md` 和其他受管指示、任何 mod 讀取的設定內容，或您的受管 MCP 伺服器的工具和描述。64* **防護保護您管理的內容。** 使用者的 mod 無法更改您的受管 hook 接收或決定的內容、系統提示詞，或您的受管 `CLAUDE.md` 和其他受管指示。它也無法更改任何 mod 讀取的設定內容，或您的受管 MCP 伺服器連線後的工具和描述。

65* **在您管理的範圍之外，使用者的 mod 以該使用者的身分運作。** mod 保有該使用者的權限：它仍然可以讀取和寫入檔案、啟動程序，以及發出網路請求。它也可以重寫工具呼叫和提示詞、拒絕工具呼叫，以及在介面中繪製。65* **在 v2.1.323 或更新版本上，使用者的 mod 可以阻止受管 MCP 伺服器連線。** 在該使用者的工作階段中，`/mcp` 會將該伺服器列為被該 mod 擋下。若要防止這種情況，請[防止使用者安裝的 mod 載入](#stop-user-installed-mods-from-loading)。

66* **在您管理的範圍之外，使用者的 mod 以該使用者的身分運作。** mod 保有該使用者的權限：它仍然可以讀取和寫入檔案、啟動程序，以及發出網路請求。它也可以重寫工具呼叫和提示詞、拒絕工具呼叫、新增或移除工具，以及在介面中繪製。

66* **權限規則和 `PreToolUse` hook 優先於使用者的 mod。** 防護載入時，預設情況下，使用者的 mod 無法核准 `deny` 規則拒絕的呼叫或 `ask` 規則會提示確認的呼叫，無論哪個設定檔持有該規則。mod 也無法核准任何 `PreToolUse` hook 所封鎖的呼叫。67* **權限規則和 `PreToolUse` hook 優先於使用者的 mod。** 防護載入時，預設情況下，使用者的 mod 無法核准 `deny` 規則拒絕的呼叫或 `ask` 規則會提示確認的呼叫，無論哪個設定檔持有該規則。mod 也無法核准任何 `PreToolUse` hook 所封鎖的呼叫。

67 68

68 權限規則和 `PreToolUse` hook 適用於 Claude 的工具呼叫，而不適用於 mod 的 [`$.fs` 和 `$.process` 呼叫](https://code.claude.com/docs/zh-TW/plugins/mods/api#reach-files-processes-and-the-network)。拒絕 `Read(.env)` 後，mod 仍然可以使用 `$.fs.read` 讀取該檔案，或啟動執行該操作的程式。若要限制 mod 自己的 `$.fs` 和 `$.process` 呼叫，請[防止 mod 載入](#stop-user-installed-mods-from-loading)，或在[原則 mod](#enforce-a-policy-with-a-mod-of-your-own) 中處理這些呼叫。69 權限規則和 `PreToolUse` hook 適用於 Claude 的工具呼叫，而不適用於 mod 的 [`$.fs` 和 `$.process` 呼叫](https://code.claude.com/docs/zh-TW/plugins/mods/api#reach-files-processes-and-the-network)。拒絕 `Read(.env)` 後，mod 仍然可以使用 `$.fs.read` 讀取該檔案，或啟動執行該操作的程式。若要限制 mod 自己的 `$.fs` 和 `$.process` 呼叫，請[防止 mod 載入](#stop-user-installed-mods-from-loading)，或在[原則 mod](#enforce-a-policy-with-a-mod-of-your-own) 中處理這些呼叫。

159輸出中的 `hooks:` 和 `calls:` 行描述 mod 的程式碼：160輸出中的 `hooks:` 和 `calls:` 行描述 mod 的程式碼：

160 161

161```text theme={null}162```text theme={null}

162 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}163 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane} (default matcher key: plugin)

163 ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open164 ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

164```165```

165 166

166`hooks:` 行列出 mod 接收的事件。`calls:` 行列出其程式碼呼叫的 mods API 方法。[mods API](https://code.claude.com/docs/zh-TW/plugins/mods/api.md)（在 mod 的程式碼中寫為 `$`）是 mod 到達檔案、程序和網路的方式。Claude Code 拒絕載入以此命令無法讀取的方式使用 mods API 的 mod。167* **`hooks:`**：mod 接收的事件。`default matcher key: plugin` 註記表示其前面的 hook [會略過其他 mod 的控制項和繪製內容](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#hook-other-mods-drawings-and-controls)。

168* **`calls:`**：其程式碼呼叫的 mods API 方法

167 169

168查看 `calls:` 行以了解這些：170[mods API](https://code.claude.com/docs/zh-TW/plugins/mods/api.md)（在 mod 的程式碼中寫為 `$`）是 mod 到達檔案、程序和網路的方式。Claude Code 拒絕載入以此命令無法讀取的方式使用 mods API 的 mod。

171

172請勿核准未通過此命令檢查的 mod，因為某些失敗並不會阻止它載入。請在 Claude Code v2.1.323 或更新版本上執行此命令（在這些版本中，較長的清單會以相同標籤延續到更多行），並閱讀每一行 `hooks:` 和 `calls:`。在 `calls:` 行中，查看以下項目：

169 173

170| 呼叫 | 它的意思 |174| 呼叫 | 它的意思 |

171| :- | :- |175| :- | :- |

177| `$.mcp.call` | 在連接的 MCP 伺服器上呼叫工具，受工作階段的權限規則約束 |181| `$.mcp.call` | 在已連接的 MCP 伺服器上呼叫工具，且不會出現權限提示。若有拒絕規則或受管理的詢問規則，Claude Code 會拒絕該呼叫。對於標記為 [`requiresUserInteraction`](https://code.claude.com/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的工具，或您的組織[設定為 `ask`](https://code.claude.com/docs/zh-TW/mcp#organization-controls-on-connector-tools) 且該設定適用於 Claude Code 的工具，Claude Code 也會拒絕呼叫。 |

316 320

317Claude Code 每次即將採取行動（例如執行工具）時都會引發事件，並依次將其傳遞給每個 mod。被視為您的 mod [會在使用者的 mod 之前執行](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)，即使您在任何地方都沒有列出它。若要設定其位置，請在兩個設定之一中列出其 id。id 是外掛的名稱、`@` 和市集的名稱，例如 `acme-guard@acme-tools`。321Claude Code 每次即將採取行動（例如執行工具）時都會引發事件，並依次將其傳遞給每個 mod。被視為您的 mod [會在使用者的 mod 之前執行](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)，即使您在任何地方都沒有列出它。若要設定其位置，請在兩個設定之一中列出其 id。id 是外掛的名稱、`@` 和市集的名稱，例如 `acme-guard@acme-tools`。

318 322

319* **`prependPlugins`**：您的 mod 在任何使用者的 mod 之前看到每個事件，並在之後看到每個結果。它可以更改事件、拒絕它或跳過使用者的 mod。323* **`prependPlugins`**：您的 mod 在任何使用者的 mod 之前看到事件，並在它們之後看到該事件的結果。它可以更改事件、拒絕它或跳過使用者的 mod。在 v2.1.323 或更新版本上，請確認您的 hook 仍能[觸及其他 mod 的控制項和繪製內容](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#hook-other-mods-drawings-and-controls)。

320* **`appendPlugins`**：您的 mod 在每個使用者的 mod 之後執行，因此它只看到這些 mod 傳遞的事件，以及它們傳遞的形式324* **`appendPlugins`**：您的 mod 在每個使用者的 mod 之後執行，因此它只看到這些 mod 傳遞的事件，以及它們傳遞的形式

321 325

322此範例在 `/opt/acme/claude-plugins` 宣告 `acme-tools` 市集，從中啟用 `acme-guard`，並首先執行該 mod，內建防護在其後：326此範例在 `/opt/acme/claude-plugins` 宣告 `acme-tools` 市集，從中啟用 `acme-guard`，並首先執行該 mod，內建防護在其後：

359 363

360每次另一個 mod 即將載入時，您的 mod 會在名為 [`plugin.register`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#other-mods) 的事件中接收 `claude plugin validate` 列印的清單。`prependPlugins` 中的 mod 可以讀取該清單並拒絕該 mod。它也可以[按名稱處理任何 mods API 呼叫](https://code.claude.com/docs/zh-TW/plugins/mods/api.md#reach-files-processes-and-the-network)，以記錄或拒絕所有其他 mod 的該呼叫。名稱是不含 `$.` 的方法，因此 `fs.write` 上的 hook 會看到每個 `$.fs.write` 呼叫。364每次另一個 mod 即將載入時，您的 mod 會在名為 [`plugin.register`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#other-mods) 的事件中接收 `claude plugin validate` 列印的清單。`prependPlugins` 中的 mod 可以讀取該清單並拒絕該 mod。它也可以[按名稱處理任何 mods API 呼叫](https://code.claude.com/docs/zh-TW/plugins/mods/api.md#reach-files-processes-and-the-network)，以記錄或拒絕所有其他 mod 的該呼叫。名稱是不含 `$.` 的方法，因此 `fs.write` 上的 hook 會看到每個 `$.fs.write` 呼叫。

361 365

366> [!NOTE]

367>

368> 在 v2.1.323 或更新版本上，`ui.focus` hook 需要更寬的 matcher 才能接收其他 mod 的 `$.ui.focus` 呼叫。請參閱[對其他 mod 的繪製內容和控制項使用 hook](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#hook-other-mods-drawings-and-controls)。

369

362此原則 mod 會拒絕任何自身程式碼呼叫 `$.process.run` 或 `$.process.spawn` 的使用者 mod。它也會保留稽核日誌，將每個工具呼叫和每個 mod 寫入的檔案寫入偵錯日誌。因為它首先執行，日誌會在任何使用者的 mod 更改之前記錄所請求的內容。將其儲存為 `acme-guard/hooks/register.js`：370此原則 mod 會拒絕任何自身程式碼呼叫 `$.process.run` 或 `$.process.spawn` 的使用者 mod。它也會保留稽核日誌，將每個工具呼叫和每個 mod 寫入的檔案寫入偵錯日誌。因為它首先執行，日誌會在任何使用者的 mod 更改之前記錄所請求的內容。將其儲存為 `acme-guard/hooks/register.js`：

363 371

364```javascript acme-guard/hooks/register.js theme={null}372```javascript acme-guard/hooks/register.js theme={null}

403* **`e.tier`**：mod 將執行的位置，為 `prepend`、`user`、`append` 或 `builtin` 之一。使用者安裝的每個 mod 都是 `user`。411* **`e.tier`**：mod 將執行的位置，為 `prepend`、`user`、`append` 或 `builtin` 之一。使用者安裝的每個 mod 都是 `user`。

404* **`e.uses.calls`**：mod 呼叫的 mods API 方法，每個寫成 `namespace.method`（例如 `process.run`），不帶 `claude plugin validate` 列印的 `$.`412* **`e.uses.calls`**：mod 呼叫的 mods API 方法，每個寫成 `namespace.method`（例如 `process.run`），不帶 `claude plugin validate` 列印的 `$.`

405 413

406當使用者安裝呼叫 `$.process.run` 的 mod 時，該 mod 不會載入，其偵錯日誌中會有一行以 `refused by acme-guard:` 和您的原因結尾。在[熱重新載入外掛目錄的工作階段](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)中，拒絕訊息也會出現在逐字稿中。若要封鎖某個呼叫而不拒絕整個 mod，請從該呼叫名稱上的 hook 傳回 `{ deny: 'your reason' }`。414當使用者安裝呼叫 `$.process.run` 的 mod 時，該 mod 不會載入，其偵錯日誌中會有一行以 `refused by acme-guard:` 和您的原因結尾。在[熱重新載入外掛目錄的工作階段](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)中，拒絕訊息也會出現在逐字稿中。

415

416若要封鎖某個呼叫而不拒絕整個 mod，請在[確認是誰發出該呼叫](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#mods-api-calls)之後，從該呼叫名稱上的 hook 傳回 `{ deny: 'your reason' }`。

407 417

408若要將稽核行傳送到偵錯日誌以外的地方，請從相同的 hook 呼叫 `$.http.fetch`。418若要將稽核行傳送到偵錯日誌以外的地方，請從相同的 hook 呼叫 `$.http.fetch`。

409 419

plugins/mods/create.md +12 −6

Details

21 21

22在互動式 Claude Code 工作階段中描述你想要的 mod，Claude 會寫出來。Claude 使用名為 `plugin-authoring` 的內建 [skill](https://code.claude.com/docs/zh-TW/skills.md)，它告訴 Claude 在哪裡寫 mod、你的版本有哪些事件和方法，以及 mod 如何被載入。當你要求 mod 時，Claude 可以載入該 skill，或者你可以在 Claude Code 提示符處執行 `/plugin-authoring` 來自己載入它。22在互動式 Claude Code 工作階段中描述你想要的 mod，Claude 會寫出來。Claude 使用名為 `plugin-authoring` 的內建 [skill](https://code.claude.com/docs/zh-TW/skills.md)，它告訴 Claude 在哪裡寫 mod、你的版本有哪些事件和方法，以及 mod 如何被載入。當你要求 mod 時，Claude 可以載入該 skill，或者你可以在 Claude Code 提示符處執行 `/plugin-authoring` 來自己載入它。

23 23

24在 `auto` 和 `bypassPermissions` [權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)中，mod 可以在回合結束時執行。其他情況下，mod 會在您批准後執行，但[Claude 寫的 mod 無法載入的工作階段](#sessions-that-skip-the-approval)除外。24在 `auto` 和 `bypassPermissions` [權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)中，Claude Code [可以在不詢問您的情況下載入 mod](#sessions-that-skip-the-approval)。若要先經詢問，請以 `default` 或 `acceptEdits` 模式啟動新的工作階段，或在要求該工作階段的第一個 mod 之前[切換](https://code.claude.com/docs/zh-TW/permission-modes.md#switch-permission-modes)至其中任一模式。在[某些工作階段](#sessions-that-cant-load)中，mod 無法載入。

25 25

26**1. 描述 mod**26**1. 描述 mod**

27 27

33 33

34**2. 批准 mod**34**2. 批准 mod**

35 35

36當 Claude 儲存第一個檔案時，Claude Code 會詢問是否為此工作階段啟用熱重新載入。熱重新載入會執行 Claude 在此工作階段中寫的 mod，並套用之後的每次變更。如果沒有出現此詢問，請跳過此步驟。36當 Claude 儲存第一個檔案時，Claude Code 會詢問是否為此工作階段啟用熱重新載入。熱重新載入會執行 Claude 在此工作階段中寫的 mod，並套用之後的每次變更。在[不經詢問即載入新 mod](#sessions-that-skip-the-approval) 或[無法載入 mod](#sessions-that-cant-load) 的工作階段中，您不會看到此詢問。

37 37

38選擇以下其中一個答案：38選擇以下其中一個答案：

39 39

57* **在你啟動的工作階段中**：在你的 shell 中，執行 `claude --plugin-dir ~/mods/git-branch`57* **在你啟動的工作階段中**：在你的 shell 中，執行 `claude --plugin-dir ~/mods/git-branch`

58* **對於其他人**：[將其新增到市場](#share-your-mod)，以便他們可以安裝它58* **對於其他人**：[將其新增到市場](#share-your-mod)，以便他們可以安裝它

59 59

60### 不經詢問即載入 mod 的工作階段

62在 `auto` 和 `bypassPermissions` 模式中，Claude Code 可以不經詢問即啟用熱重新載入，mod 會在回合結束時載入。

64當您恢復工作階段時，無論是以互動方式或使用 `claude -p`，其 mod 資料夾中已有的 mod [都可以](#sessions-that-cant-load)不經詢問即載入。若要在恢復時避免某個 mod 載入，請刪除其目錄。

60### Claude 寫的 mod 無法載入的工作階段66### Claude 寫的 mod 無法載入的工作階段

61 67

~~62Claude 寫的 mod 會在允許 mod 執行的受信任工作區中載入；在會詢問的模式下，須經您批准後才會載入。在以下工作階段中，mod 不會載入：~~68在以下情況中，Claude 寫的 mod 不會載入，Claude Code 也不會詢問是否要載入：

63 69

64* **沒有人可以批准**：工作階段無法向您顯示權限提示，例如在 `auto` 和 `bypassPermissions` 模式以外執行的 `claude -p`，或 [`dontAsk` 模式](https://code.claude.com/docs/zh-TW/permission-modes)70* **沒有人可以批准**：工作階段處於 [`dontAsk` 模式](https://code.claude.com/docs/zh-TW/permission-modes)，或是以 `default` 或 `acceptEdits` 模式寫入該 mod 的 `claude -p` 執行，這種執行無法向您顯示熱重新載入的詢問。

~~65* **工作區不受信任**：你還沒有接受目錄的信任提示~~71* **工作區不受信任的互動式工作階段**：您尚未接受該目錄的信任提示

66* **Mod 已停用**：您以 `--safe-mode` 或 `--bare` 啟動、設定了 `disableAllHooks`，或您組織的[受管設定封鎖了它](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#choose-how-much-to-allow)72* **Mod 已停用**：您以 `--safe-mode` 或 `--bare` 啟動、設定了 `disableAllHooks`，或您組織的[受管設定封鎖了它](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#choose-how-much-to-allow)

67 73

68## 自己寫 mod74## 自己寫 mod

292 298

293請查看 `hooks:` 行，確認您的模組 hook 的事件，每個事件的篩選器都列在大括號中；並查看 `calls:` 行，確認它呼叫的每個 mod API 方法。如果您的模組會讀取或設定環境變數，也請留意 `env reads:` 和 `env writes:` 行；若使用了 [`$.state`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#keep-state)，則請留意 `state reads:` 和 `state writes:`。對於每個可以拒絕動作的 hook，您也會看到一行，例如 `gating hook without .catch: tool.call`，說明該 hook 是否具有 [`.catch` 處理常式](https://code.claude.com/docs/zh-TW/plugins/mods/events#handle-a-hook-that-fails)。299請查看 `hooks:` 行，確認您的模組 hook 的事件，每個事件的篩選器都列在大括號中；並查看 `calls:` 行，確認它呼叫的每個 mod API 方法。如果您的模組會讀取或設定環境變數，也請留意 `env reads:` 和 `env writes:` 行；若使用了 [`$.state`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#keep-state)，則請留意 `state reads:` 和 `state writes:`。對於每個可以拒絕動作的 hook，您也會看到一行，例如 `gating hook without .catch: tool.call`，說明該 hook 是否具有 [`.catch` 處理常式](https://code.claude.com/docs/zh-TW/plugins/mods/events#handle-a-hook-that-fails)。

294 300

295如果您想處理的事件沒有出現在第一行中，Claude Code 也不會呼叫該 hook。常見原因是事件名稱拼寫錯誤，命令會將其回報為錯誤，例如 `"tool.calls" is not an event`。301如果您想處理的事件沒有出現在 `hooks:` 行中，Claude Code 也不會呼叫該 hook。常見原因是事件名稱拼寫錯誤，命令會將其回報為錯誤，例如 `"tool.calls" is not an event`。

296 302

297遵循這些規則，以便靜態分析可以找到每個 hook 和呼叫：303遵循這些規則，以便靜態分析可以找到每個 hook 和呼叫：

298 304

plugins/mods/events.md +10 −0

Details

91 91

92為每個 matcher 註冊一次事件。如果您為 `session.start` 呼叫 `on` 兩次而沒有 matcher，模組將無法載入，並出現 `on("session.start") is registered twice without a matcher`。將您的 mod 在工作階段開始時執行的所有操作放在一個 hook 中。92為每個 matcher 註冊一次事件。如果您為 `session.start` 呼叫 `on` 兩次而沒有 matcher，模組將無法載入，並出現 `on("session.start") is registered twice without a matcher`。將您的 mod 在工作階段開始時執行的所有操作放在一個 hook 中。

93 93

94#### Hook 其他 mod 的繪製內容與控制項

96若要 hook 另一個 mod 的控制項、窗格或提示詞上方的列，請傳遞帶有 `plugin` 的 matcher。使用該 mod 不含市集的名稱，例如 `{ plugin: 'other-mod' }`，或使用 `{ plugin: '*' }` 來符合每個 mod。若沒有 `plugin`，`ui.press`、`ui.input`、`ui.select` 或 `ui.focus` 上的 hook 不會針對其他 mod 的控制項執行，而 `ui.render` hook 會略過其他 mod 的窗格以及其提示詞上方的列。

98沒有 matcher 的萬用字元 hook，例如 `on('*', hook)` 或 `on('ui.*', hook)`，仍會針對每個 mod 執行。帶有 matcher 的萬用字元也需要 `plugin`。

100> [!NOTE]

101>

102> `{ plugin: '*' }` 需要 Claude Code v2.1.323 或更新版本。在 v2.1.323 之前，沒有 `plugin` 的 hook 會針對每個 mod 執行，而帶有 `{ plugin: '*' }` 的 hook 則不會執行。若要在兩個版本上都符合每個 mod，請在 `ui.press`、`ui.input` 和 `ui.select` 上使用 `{ plugin: /./ }`。對於 `ui.focus` 和 `ui.render`，請使用 `on('ui.*', hook)` 並在 `next.event` 中檢查事件名稱，例如 `if (next.event !== 'ui.focus') return next(e)`。

103

94## 對 Claude 正在執行的動作設定 hook104## 對 Claude 正在執行的動作設定 hook

95 105

96處理這些事件，即可在工具呼叫、提示詞、回合或設定讀取發生時檢視或變更它們。如需所有事件以及 hook 可傳回的內容，請參閱[事件參考](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#events)。106處理這些事件，即可在工具呼叫、提示詞、回合或設定讀取發生時檢視或變更它們。如需所有事件以及 hook 可傳回的內容，請參閱[事件參考](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#events)。

plugins/mods/gallery.md +1 −1

Details

363 363

364### `Image` 和 `Client`364### `Image` 和 `Client`

365 365

366另有兩個元素在此沒有範例。`Image` 會在終端機中繪製 PNG 或原始像素。`Client` 是由您的第二個檔案負責繪製的區域，用於動畫和指標輸入。[元素參考](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#elements)列出了它們的 props。366`Image` 和 `Client` 在此沒有範例。`Image` 會在終端機中繪製 PNG 或原始像素。`Client` 是由您的第二個檔案負責繪製的區域，用於動畫和指標輸入。[元素參考](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#elements)列出了它們的 prop。

367 367

368`Image` 會在下列終端機中繪製為圖片：368`Image` 會在下列終端機中繪製為圖片：

369 369

plugins/mods/interface.md +18 −14

Details

177 177

178## 選擇繪製位置178## 選擇繪製位置

179 179

180除非您將 `ui.render` hook 限定在您想繪製的那一個轉譯位置，否則它會在每個轉譯位置都執行。若要選擇轉譯位置，請將一個篩選條件（稱為 [matcher](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#filter-which-events-a-hook-handles)）作為第二個引數傳給 `on`。`{ component: 'Pane' }` 會讓 hook 只在窗格中執行。在 hook 中，`e.component` 指出位置名稱，`e.surface` 說明是哪個應用程式在繪製，而 `e.props` 則存放該位置自身的資料。對於窗格，`e.requestId` 是您開啟它時所用的 `id`。180若要選擇 `ui.render` hook 要在哪個轉譯位置繪製，請將一個篩選條件（稱為 [matcher](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#filter-which-events-a-hook-handles)）作為第二個引數傳給 `on`。`{ component: 'Pane' }` 會讓 hook 只在窗格中執行。在 hook 中，`e.component` 指出位置名稱，`e.surface` 說明是哪個應用程式在繪製，而 `e.props` 則存放該位置自身的資料。對於窗格，`e.requestId` 是您開啟它時所用的 `id`。

181 181

182在 mod 填入內容之前，窗格和橫帶都是空的。選擇一個分頁，查看各自是什麼以及如何在其中繪製：182在 mod 填入內容之前，窗格和橫帶都是空的。選擇一個分頁，查看各自是什麼以及如何在其中繪製：

183 183

191 191

192> [tab] 提示詞上方的橫帶192> [tab] 提示詞上方的橫帶

193>193>

194> 橫帶是緊鄰提示詞輸入框上方的一條區域。它始終存在，且所有 mod 共用。194> 橫帶是緊鄰提示詞輸入框上方的一條區域。每個在此繪製的 mod 都會有自己的一列，這些列會依 [mod 的執行順序](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)從上往下堆疊。

195>195>

196> 您的 hook 回傳一棵樹以在橫帶中顯示內容，或回傳 `next(e)` 以不顯示任何內容。一棵樹會取代[在您之後](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)執行的 mod 在此處繪製的內容。若要保留它們的內容，請將 `await next(e)` 的結果放入您樹中某個 [`Box`](#build-a-tree-from-elements) 的子元素之中。196> 若要繪製您 mod 的那一列，請以 `{ component: 'AbovePrompt' }` 篩選並回傳一棵[樹](#build-a-tree-from-elements)。若不要繪製任何內容，請回傳 `next(e)`。

197>197>

198> 若要在橫帶中繪製，請以 `{ component: 'AbovePrompt' }` 篩選。198> 在 v2.1.323 之前，所有 mod 共用橫帶中的同一份繪製內容，而您的樹會取代在您之後執行的 mod 所繪製的內容。若也要支援這些版本，請將 `await next(e)` 的結果放入某個[維持有效的 `Box`](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot#another-mods-band-shows-and-yours-doesnt) 的子元素之中。在 v2.1.323 或更新版本中，該子元素不會繪製其他 mod 的列。

199 199

200mod 也可以[在逐字稿中放置自己的一列](#place-a-row-in-the-transcript)。200mod 也可以[在逐字稿中放置自己的一列](#place-a-row-in-the-transcript)。

201 201

281 281

282Claude 工作時，spinner 照常播放動畫，而 `under the spinner` 會出現在其下方。282Claude 工作時，spinner 照常播放動畫，而 `under the spinner` 會出現在其下方。

283 283

284權限提示不是轉譯位置，因此 mod 無法變更其顯示內容。問題對話框 `AskUserQuestion` 則是轉譯位置，因此 mod 可以變更它。對話框的樹必須恰好包含該參照一次，並將您的元素置於其上方。否則，Claude Code 會繪製它自己的對話框。284權限提示不是轉譯位置，因此 mod 無法變更其顯示內容。問題對話框 `AskUserQuestion` 則是轉譯位置，因此當 Claude 提出問題時，mod 可以變更該對話框。對話框的樹必須恰好包含該參照一次，並將您的元素置於其上方。否則，Claude Code 會繪製它自己的對話框。

285 285

286### 在適當時機開啟窗格286### 在適當時機開啟窗格

287 287

288窗格只有在您的 mod 開啟它時才會出現。您開啟窗格的方式與時機，決定了它是否取得鍵盤焦點、要求多少空間，以及在狹窄的終端機中是否會顯示。288窗格只有在您的 mod 開啟它時才會出現。您開啟窗格的方式與時機，決定了它是否取得鍵盤焦點、要求多少空間，以及在狹窄的終端機中是否會顯示。

289 289

290若要開啟窗格，請以您選擇的 `id` 呼叫 [`$.ui.open`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods)。`id` 是窗格的名稱：您的 `ui.render` hook 會檢查它，而您在關閉窗格時也要再次傳入它。290若要開啟窗格，請以您選擇的 `id` 呼叫 [`$.ui.open`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods)。`id` 是窗格的名稱：您的 `ui.render` hook 會檢查它，而您在關閉窗格時也要再次傳入它。若另一個 mod 已開啟具有相同 `id` 的窗格，此呼叫會被拒絕。

291 291

292```javascript theme={null}292```javascript theme={null}

293await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })293await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })

399 399

400> [!NOTE]400> [!NOTE]

401>401>

402> `$.theme.set` 和 `$.theme.clear` 取代了 `$.ui.backdrop`，後者已在 Claude Code v2.1.319 中移除。請將 `$.ui.backdrop({ id: 'your-backdrop' })` 改為 `$.theme.set({ backdrop: { id: 'your-backdrop' } })`，並將 `$.ui.backdrop(undefined)` 改為 `$.theme.clear()`，後者會移除任何 mod 的背景。402> `$.theme.set` 和 `$.theme.clear` 取代了 `$.ui.backdrop`，後者已在 Claude Code v2.1.319 中移除。請將 `$.ui.backdrop({ id: 'your-backdrop' })` 改為類似本節範例中的 `$.theme.set` 呼叫，並將 `$.ui.backdrop(undefined)` 改為 `$.theme.clear()`，後者會移除任何 mod 的背景。

403 403

404若要在 Desktop 應用程式或行動應用程式中於對話背後放置背景，請以 `backdrop` 呼叫 [`$.theme.set`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods)，然後在 [`Backdrop`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#render-sites) 轉譯位置繪製背景。若要移除背景，請呼叫 `$.theme.clear()`。終端機不會繪製背景。`$.theme.set` 和 `$.theme.clear` 需要 Claude Code v2.1.319 或更新版本。404若要在 Desktop 應用程式或行動應用程式中於對話背後放置背景，請以 `backdrop` 呼叫 [`$.theme.set`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods)，然後在 [`Backdrop`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#render-sites) 轉譯位置繪製背景。若要移除背景，請呼叫 `$.theme.clear()`。終端機不會繪製背景。`$.theme.set` 和 `$.theme.clear` 需要 Claude Code v2.1.319 或更新版本。

405 405

406此 mod 會在工作階段開始時設定背景、繪製背景，並新增一個移除背景的 `/plain` 命令：406此範例需要 Claude Code v2.1.323 或更新版本，因此請先[確認您的版本](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#turn-mods-on-or-off)。此 mod 會在工作階段開始時設定背景、繪製背景，並新增一個移除背景的 `/plain` 命令：

407 407

408```javascript theme={null}408```javascript theme={null}

409export function register(on) {409export function register(on) {

410 // Neither a reload of this mod nor --resume keeps the backdrop, so set it here410 // Neither a reload of this mod nor --resume keeps the backdrop, so set it here

411 on('session.start', async ($, e, next) => {411 on('session.start', async ($, e, next) => {

412 await $.theme.set({ backdrop: { id: 'night-sky', colorScheme: 'dark' } })412 await $.theme.set({ backdrop: { scene: 'night-sky' }, overrideColorScheme: 'dark' })

413 await $.command.register({ name: 'plain', description: 'Take the backdrop off' })413 await $.command.register({ name: 'plain', description: 'Take the backdrop off' })

414 return next(e)414 return next(e)

415 })415 })

416 416

417 on('ui.render', { component: 'Backdrop' }, async ($, e, next) => {417 on('ui.render', { component: 'Backdrop' }, async ($, e, next) => {

418 // This hook runs for every mod's backdrop, and another mod can use the same id418 // This hook runs for every mod's backdrop, and another mod can use the same scene

419 if (e.props.plugin !== $.plugin.name || e.props.id !== 'night-sky') return next(e)419 if (e.props.plugin !== $.plugin.name || e.props.scene !== 'night-sky') return next(e)

420 const { Box, Text } = $.ui.resolve(e)420 const { Box, Text } = $.ui.resolve(e)

421 return Box({ backgroundColor: 'blue', children: [Text({ children: ['Night sky'] })] })421 return Box({ backgroundColor: 'blue', children: [Text({ children: ['Night sky'] })] })

422 })422 })

428}428}

429```429```

430 430

431> [!NOTE]

432>

433> 在 v2.1.323 之前，請在 `$.theme.set` 呼叫和 `e.props` 中以 `id` 取代 `scene`，並將 `overrideColorScheme` 移入 `backdrop` 中，改為 `colorScheme`。

434

431若要試用此範例，請將這段程式碼放入一個 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md)，並在 Desktop 應用程式或行動應用程式中開始工作階段。若要移除背景，請在 Claude Code 提示詞執行 `/plain`。逐字稿會在 mod 名稱之後顯示 `the theme is cleared`，例如名為 `night-sky` 的 mod 會顯示 `night-sky: the theme is cleared`。435若要試用此範例，請將這段程式碼放入一個 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md)，並在 Desktop 應用程式或行動應用程式中開始工作階段。若要移除背景，請在 Claude Code 提示詞執行 `/plain`。逐字稿會在 mod 名稱之後顯示 `the theme is cleared`，例如名為 `night-sky` 的 mod 會顯示 `night-sky: the theme is cleared`。

432 436

433請確認 `backdrop` 接受哪些內容、呼叫結果告訴您什麼，以及其他 mod 可以變更什麼：437請確認 `backdrop` 接受哪些內容、呼叫結果告訴您什麼，以及其他 mod 可以變更什麼：

434 438

435* **`backdrop` 欄位**：`id` 是您選擇的[名稱](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)，為必填，其他欄位則為選用。`colorScheme` 為 `'light'` 或 `'dark'`，說明您的繪製內容是淺色還是深色。關於 `glass`，請參閱[適用於您建置版本的型別](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#get-the-types-for-your-build)。439* **`backdrop` 欄位**：`scene` 是您為 hook 所繪製的背景選擇的[名稱](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)。關於其他欄位與 `overrideColorScheme`，請參閱[適用於您建置版本的型別](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#get-the-types-for-your-build)。

436* **背景是否已繪製**：當連線到工作階段的 Desktop 或行動應用程式表示它會繪製背景時，`$.theme.set` 會以 `isDrawn: true` 解析。否則 `isDrawn` 為 `false`，而 `reason` 會說明原因。440* **背景是否已繪製**：當連線到工作階段的 Desktop 或行動應用程式表示它會繪製背景時，`$.theme.set` 會以 `isDrawn: true` 解析。否則 `isDrawn` 為 `false`，而 `reason` 會說明原因。

437* **每個工作階段一個背景**：`$.theme.set` 呼叫會取代工作階段的背景，而 `$.theme.clear()` 會移除該背景，無論是哪個 mod 設定的。請只在使用者要求時才呼叫 `$.theme.clear()`。441* **每個工作階段一個背景**：`$.theme.set` 呼叫會取代工作階段的背景，而 `$.theme.clear()` 會移除該背景，無論是哪個 mod 設定的。請只在使用者要求時才呼叫 `$.theme.clear()`。

438 442

510>514>

511> 將 `rows` 設為 2 或以上，即可取得[容納多行的欄位](https://code.claude.com/docs/zh-TW/plugins/mods/gallery.md#input)。515> 將 `rows` 設為 2 或以上，即可取得[容納多行的欄位](https://code.claude.com/docs/zh-TW/plugins/mods/gallery.md#input)。

512 516

513[介面圖庫](https://code.claude.com/docs/zh-TW/plugins/mods/gallery.md)提供大多數元素的範例和螢幕截圖。此表列出每個元素：517[介面圖庫](https://code.claude.com/docs/zh-TW/plugins/mods/gallery.md)提供大多數元素的範例和螢幕截圖。此表列出主要元素：

514 518

515| 元素 | 它繪製的內容 | 位置 |519| 元素 | 它繪製的內容 | 位置 |

516| :- | :- | :- |520| :- | :- | :- |

606測試和其他 mod 透過控制項的鍵來識別它：610測試和其他 mod 透過控制項的鍵來識別它：

607 611

608* **測試**：[測試](https://code.claude.com/docs/zh-TW/plugins/mods/test.md#test-a-drawing)透過控制項的鍵按下或輸入到該控制項。612* **測試**：[測試](https://code.claude.com/docs/zh-TW/plugins/mods/test.md#test-a-drawing)透過控制項的鍵按下或輸入到該控制項。

609* **其他 mod**：Claude Code 在執行控制項的回呼之前，會引發 [`ui.press`、`ui.input` 或 `ui.select`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface)，其中 `e.element` 中包含控制項的鍵。另一個 mod 針對該事件的 hook 會看到使用者輸入到您的 `Input` 中的內容，並可以更改該文字或阻止您的回呼執行。mods API 沒有提供該 mod 按下您按鈕的方法。613* **其他 mod**：Claude Code 在執行控制項的回呼之前，會引發 [`ui.press`、`ui.input` 或 `ui.select`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface)，其中 `e.element` 中包含控制項的鍵。另一個 mod 的 hook 也可以[針對該事件執行](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#hook-other-mods-drawings-and-controls)。該 hook 會看到使用者輸入到您的 `Input` 中的內容，並可以更改該文字或阻止您的回呼執行。mods API 沒有提供該 mod 按下您按鈕的方法。

610 614

611如果訊息顯示 `needs a key` 或 `is drawn twice`，請[依據該訊息找出原因](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#needs-a-key)。615如果訊息顯示 `needs a key` 或 `is drawn twice`，請[依據該訊息找出原因](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#needs-a-key)。

612 616

plugins/mods/reference.md +8 −4

Details

208 208

209### mods API 呼叫209### mods API 呼叫

210 210

211每個 [mods API 方法](#mods-api-methods)也是一個事件，以其命名空間與方法命名，例如 `fs.read`、`model.complete` 或 `ui.open`。其上的 hook 會攔截在它之後執行之 mod 的呼叫，並可回傳 `next(e)`、`{ deny: reason }` 或 `{ value }`。211每個 [mods API 方法](#mods-api-methods)也是一個事件，以其命名空間與方法命名，例如 `fs.read`、`model.complete` 或 `ui.open`。其上的 hook 可回傳 `next(e)`、`{ deny: reason }` 或 `{ value }`。

212

213其中部分事件也會針對 Claude Code 自身的動作觸發，因此在拒絕某個事件之前，請先檢查 `next.origin.plugin` 是否為 `engine`。

212 214

213## Mods API 方法215## Mods API 方法

214 216

249| :- | :- | :- | :- |251| :- | :- | :- | :- |

254| `AbovePromptList`，即 `AbovePrompt` 列的堆疊 | `rows`，一個清單，其中每個 mod 的列各有一個 `{ plugin, tree }`，另加上 `AbovePrompt` 的 prop | 單一實例 | 終端機、Desktop。需要 Claude Code v2.1.323 或更新版本。 |

253| [`Backdrop`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `id`、`plugin`、`glass`、`colorScheme` | `backdrop` | `desktop` 與 `mobile` 使用介面。當 Desktop 或行動應用程式要求繪製背景時，您的 hook 就會執行。 |256| [`Backdrop`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`、`plugin`、`glass`、`overrideColorScheme`。在 v2.1.323 之前，`scene` 為 `id`，`overrideColorScheme` 為 `colorScheme`。 | `backdrop` | `desktop` 與 `mobile` 使用介面。當 Desktop 或行動應用程式要求繪製背景時，您的 hook 就會執行。 |

297* **`action`**：指定 Claude Code 本身的某個[快捷鍵動作](https://code.claude.com/docs/zh-TW/keybindings.md)，當使用者對該動作的綁定為組合鍵或修飾鍵時，該綁定會按下此按鈕300* **`action`**：指定 Claude Code 本身的某個[快捷鍵動作](https://code.claude.com/docs/zh-TW/keybindings.md)，當使用者對該動作的綁定為組合鍵或修飾鍵時，該綁定會按下此按鈕

298* **橫帶上的數字 hotkey**：橫帶中按鈕上的數字 `hotkey`，在使用者於空白提示詞中單獨輸入該數字並停頓時也會觸發301* **橫帶上的數字 hotkey**：橫帶中按鈕上的數字 `hotkey`，在使用者於空白提示詞中單獨輸入該數字並停頓時也會觸發

299* **收合的橫帶**：當橫帶處於[收合](https://code.claude.com/docs/zh-TW/plugins/mods/interface.md#when-the-user-collapses-the-band)狀態時，`action` 綁定和 hotkey 都不會按下其中的按鈕302* **收合的橫帶**：當橫帶處於[收合](https://code.claude.com/docs/zh-TW/plugins/mods/interface.md#when-the-user-collapses-the-band)狀態時，`action` 綁定和 hotkey 都不會按下其中的按鈕

300* **兩個按鈕使用同一個 hotkey**：當同一次繪製中有兩個按鈕指定相同的 `hotkey` 時，由後者取得303* **兩個按鈕使用同一個 hotkey**：當同一次繪製中有兩個您的按鈕指定相同的 `hotkey` 時，由後者取得。若是其他 mod 的按鈕使用同一個按鍵，請參閱 [Hotkey 沒有作用](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#hotkeys-do-nothing)。

301* **`variant`**：`primary` 或 `secondary`，其他任何值都會拋出錯誤。在終端機中，`primary` 按鈕會以強調色繪製，除非它是 `plain`。304* **`variant`**：`primary` 或 `secondary`，其他任何值都會拋出錯誤。在終端機中，`primary` 按鈕會以強調色繪製，除非它是 `plain`。

302* **`role`**：`dismiss` 將按鈕標記為關閉按鈕，其他任何值都會拋出錯誤。請在您的 `onPress` 中執行關閉動作。在包含文字和一列按鈕的橫帶中，Desktop 應用程式可以將該列的第一個 `dismiss` 按鈕繪製為其專屬的關閉控制項。終端機則會以如同未設定 `role` 的方式繪製該按鈕。305* **`role`**：`dismiss` 將按鈕標記為關閉按鈕，其他任何值都會拋出錯誤。請在您的 `onPress` 中執行關閉動作。在包含文字和一列按鈕的橫帶中，Desktop 應用程式可以將該列的第一個 `dismiss` 按鈕繪製為其專屬的關閉控制項。終端機則會以如同未設定 `role` 的方式繪製該按鈕。

303 306

401| 單一樹狀結構的巢狀深度 | 根元素以下 32 層 |404| 單一樹狀結構的巢狀深度 | 根元素以下 32 層 |

402| 單一樹狀結構中的元素與文字子項 | 20,000 |405| 單一樹狀結構中的元素與文字子項 | 20,000 |

403| 單一樹狀結構中的 `Raster` 儲存格，即每個 `Raster` 的 `columns` 乘以其 `rows` | 262,144 |406| 單一樹狀結構中的 `Raster` 儲存格，即每個 `Raster` 的 `columns` 乘以其 `rows` | 262,144 |

407| 提示詞上方堆疊的列 | 元素、`Raster` 儲存格與 `Image` 位元組會跨這些列累加，並以單一樹狀結構的限制計算 |

404| 單一樹狀結構中所有 `Image` 的 PNG 或 RGBA 位元組 | 2 MiB |408| 單一樹狀結構中所有 `Image` 的 PNG 或 RGBA 位元組 | 2 MiB |

412| 傳給 `next` 的已變更事件之巢狀深度，[非同步產生器 hook](#events)（例如 `turn.step` 上的 hook）除外 | 28,000 層。超過此深度時，`next` 會被拒絕，訊息以 `nesting deeper than 28000 levels is not supported` 結尾。需要 Claude Code v2.1.299 或更新版本。 |416| 傳給 `next` 的已變更事件之巢狀深度，[非同步產生器 hook](#events)（例如 `turn.step` 上的 hook）除外 | 28,000 層。超過此深度時，`next` 會被拒絕，訊息以 `nesting deeper than 28000 levels is not supported` 結尾。需要 Claude Code v2.1.299 或更新版本。 |

413| hook 傳回值的巢狀深度，`ui.render`、`ui.resolve` 與非同步產生器 hook 除外 | 28,000 層。超過此深度時，hook 的結果會被拒絕，而[回報此情況的通知](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)會包含 `nesting deeper than 28000 levels is not supported`。需要 Claude Code v2.1.299 或更新版本。 |417| hook 傳回值的巢狀深度，`ui.render`、`ui.resolve` 與非同步產生器 hook 除外 | 28,000 層。超過此深度時，hook 的結果會被拒絕，而[回報此情況的通知](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)會包含 `nesting deeper than 28000 levels is not supported`。需要 Claude Code v2.1.299 或更新版本。 |

414| 在 hook 模組的單一檔案中彼此巢狀的作用域，例如函式、區塊與迴圈 | 2,000 |418| 在 hook 模組的單一檔案中彼此巢狀的作用域，例如函式、區塊與迴圈 | 2,000 |

417 421

418## 設定與環境變數422## 設定與環境變數

plugins/mods/test.md +3 −12

Details

139 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))139 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))

140 ```140 ```

141 141

142 註冊 stub 後，掛載成功，每當您的 hook 返回 `next(e)` 時，`ui.find({ type: 'Text' })` 都會返回該元素。142 註冊 stub 後，掛載成功，每當您的 hook 返回 `next(e)` 時，`ui.find({ type: 'Text' })` 都會返回該元素。在 v2.1.323 或更新版本中，若是針對 band，請將您的 mod 名稱作為第二個引數傳給 `on`，例如 `{ plugin: 'my-mod' }`。若未傳入，stub 不會回答您的 `next(e)`。

143 143

144* **`turn.step` 的 stub 是一個非同步生成器**，測試會讀取流直到結束以獲得結果：144* **`turn.step` 的 stub 是一個非同步生成器**，測試會讀取流直到結束以獲得結果：

145 145

192| `$.session.id`、`$.agent.list` | `() => ({ value: 'abc123' })`、`() => ({ value: [] })` |192| `$.session.id`、`$.agent.list` | `() => ({ value: 'abc123' })`、`() => ({ value: [] })` |

193| `session.send` | `() => ({ isDelivered: true })`。`e.to` 作為字串到達，即使您的 mod 傳遞了 `{ sessionId }`。 |193| `session.send` | `() => ({ isDelivered: true })`。`e.to` 作為字串到達，即使您的 mod 傳遞了 `{ sessionId }`。 |

194| `session.receive` | `($, e) => ({ text: e.text })`。使用 `$.session.receive({ origin: { kind: 'peer-send-message' }, text })` 觸發它。 |194| `session.receive` | `($, e) => ({ text: e.text })`。使用 `$.session.receive({ origin: { kind: 'peer-send-message' }, text })` 觸發它。 |

195| `ui.render` | `() => ({ type: 'Text', props: {}, children: ['...'] })` |195| `ui.render` | `() => ({ type: 'Text', props: {}, children: ['...'] })`。若是 band，請參閱[遵循測試套件的規則](#follow-the-test-kit’s-rules)中的 matcher。 |

196 196

197### 使用 `expect` 檢查結果197### 使用 `expect` 檢查結果

198 198

199套件提供以下斷言，您選用的斷言放在要檢查的值之後，例如 `expect(answer.text).toBe('ok')`：199`expect` 有一組自己的斷言，例如 `toEqual` 和 `toHaveLength`，這些斷言放在要檢查的值之後，例如 `expect(answer.text).toBe('ok')`。如需完整清單，請在[您的建置所對應的型別](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#get-the-types-for-your-build)中，於 `claude-code/index.d.ts` 搜尋 `type Matchers`。在斷言前加上 `.not` 可檢查相反的情況。若要檢查 promise 最終的結果，請在 `expect(...)` 之後緊接著加上 `.resolves` 或 `.rejects`，並對該行使用 `await`，例如 `await expect(promise).rejects.toThrow()`。

~~200~~

201* **相等**：`toBe` 用於相同的值或物件，`toEqual` 用於結構，`toStrictEqual` 用於結構加上 `undefined` 欄位與原型，`toMatchObject` 用於您指定的欄位

202* **文字**：`toMatch`（接受正規表示式或子字串）、`toStartWith` 和 `toEndWith`

203* **數字**：`toBeGreaterThan`、`toBeGreaterThanOrEqual`、`toBeLessThan`、`toBeLessThanOrEqual`

204* **內容**：`toContain` 用於子字串或成員，`toContainEqual` 用於依結構比較的成員，以及 `toHaveLength` 和 `toHaveProperty`

205* **存在與型別**：`toBeDefined`、`toBeUndefined`、`toBeNull`、`toBeTruthy`、`toBeFalsy`、`toBeNaN`、`toBeInstanceOf`

206* **拋出**：`toThrow`，用於由 `expect` 呼叫的函式，或用於您以 `.rejects` 檢查的 promise

~~207~~

208在斷言前加上 `.not` 可檢查相反的情況，加上 `.resolves` 或 `.rejects` 則可檢查 promise 最終的結果。

209 200

210當 `expect` 在您以一般函數（而非非同步生成器）傳給 `on` 的 stub 或 hook 內失敗時，測試會失敗。引擎會跳過該 hook，失敗輸出會指出它，例如 `in the test's store.set hook`。201當 `expect` 在您以一般函數（而非非同步生成器）傳給 `on` 的 stub 或 hook 內失敗時，測試會失敗。引擎會跳過該 hook，失敗輸出會指出它，例如 `in the test's store.set hook`。

211 202

plugins/mods/troubleshoot.md +15 −10

Details

223 223

224### 顯示的是另一個 mod 的帶狀，而不是您的224### 顯示的是另一個 mod 的帶狀，而不是您的

225 225

226提示詞上方只有一個帶狀，所有 mod 共用。在[您的 mod 之前](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)執行的 mod，若返回的樹中不包含 `next(e)` 的結果，就會取代您的帶狀。若要同時顯示兩個帶狀，請修改該 mod 的 hook，或請其作者修改：226每個在提示詞上方繪製的 mod 都有自己的一列，因此當您的列不見、而另一個 mod 的列有顯示時，請檢查以下原因：

227 227

228* **保留其後的帶狀**：將 `await next(e)` 的結果放在其樹中某個 `Box` 的子元素之間，如[選擇繪製位置](https://code.claude.com/docs/zh-TW/plugins/mods/interface.md#pick-where-to-draw)中「提示詞上方的帶狀」分頁所示228* **您的樹未通過驗證**：[寫入偵錯日誌](#read-the-debug-log)，在其中搜尋 [`ui.render hook skipped`](#a-pane-or-band-is-empty) 或 [`does not validate`](#ui-render-refused)，並修正該行所指出的問題。

229* **保持樹有效**：不要為該 `Box` 或其外圍的任何 `Box` 指定 `width`、`height`、`minWidth`、`minHeight`、`position`、`top`、`left`、`right`、`bottom`、`display` 或 `overflow` prop229* **各列合計超出限制**：[寫入偵錯日誌](#read-the-debug-log)，並在其中搜尋 `past the limits of the band`。這些列[共用同一個樹的限制](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)，因此請繪製較小的樹，或請其他 mod 的作者這麼做。

230* **另一個 mod 隱藏或覆蓋了您的列**：若日誌中沒有上述任何一行，請逐一[關閉](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#turn-mods-on-or-off)其他 mod。若您的列重新出現，請該 mod 的作者進行修改。

230 231

231若要找出該 mod，請[寫入偵錯日誌](#read-the-debug-log)，並在其中搜尋 `answered ui.render without next()`。像 `other-mod (user) answered ui.render without next()` 這樣的行會指出某個未呼叫 `next(e)` 就返回其樹的 mod。該行不會指出[轉譯位置](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)，因此僅使用窗格的 mod 也可能出現。呼叫了 `next(e)` 但捨棄其結果的 mod 不會產生任何行，因此也請檢查在您之前的 hook。232在 v2.1.323 之前，所有 mod 在帶狀中共用一個繪圖。在[您的 mod 之前](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)執行的 mod，若返回的樹中不包含 `next(e)` 的結果，就會取代您的繪圖。請更新 Claude Code，或請該 mod 的作者進行以下修改：

232 233

233當某個 mod 自身的 hook 返回的樹未通過驗證時，該 mod 的帶狀也會消失，而其他 mod 的帶狀則會保留。若要找出是哪個 mod 以及原因，請[寫入偵錯日誌](#read-the-debug-log)，並在其中搜尋 [`ui.render hook skipped`](#a-pane-or-band-is-empty)。234* **保留其後 mod 的繪圖**：將 `await next(e)` 的結果放在其樹中某個 `Box` 的子元素之間

235* **保持樹有效**：不要為該 `Box` 或其外圍的任何 `Box` 指定 `width`、`height`、`minWidth`、`minHeight`、`position`、`top`、`left`、`right`、`bottom`、`display` 或 `overflow` prop

234 236

235### 窗格或帶狀為空或顯示 Claude Code 的常見內容237### 窗格或帶狀為空或顯示 Claude Code 的常見內容

236 238

246 248

247### `ui.render` 行顯示 `refused`249### `ui.render` 行顯示 `refused`

248 250

249`ui.render (<site>) refused:`，或[偵錯日誌](#read-the-debug-log)中的 `ui.render (<site>): the chain settled on a tree that does not validate`，表示該位置的[樹](https://code.claude.com/docs/zh-TW/plugins/mods/interface.md#build-a-tree-from-elements)超出了[大小限制](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)。這兩行都會先指出[轉譯位置](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)，接著是原因，而原因會指出該限制。251`ui.render (<site>) refused:`，或[偵錯日誌](#read-the-debug-log)中的 `ui.render (<site>): the chain settled on a tree that does not validate`，表示該位置的[樹](https://code.claude.com/docs/zh-TW/plugins/mods/interface.md#build-a-tree-from-elements)超出了[大小限制](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)。這兩行都會先指出[轉譯位置](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)，接著是原因。

250 252

251請修改在該位置繪製的 mod，使其 [`ui.render`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface) hook 返回較小的樹，或請其作者修改。若逐字稿行以 `hooks` 開頭，表示有多個已載入的 mod 具有該位置的 `ui.render` hook，因此請檢查每個 mod 的樹。當多個 mod 在提示詞上方的帶狀巢狀組成超過 32 層深的樹時，該行如下：253請修改在該位置繪製的 mod，使其 [`ui.render`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface) hook 返回較小的樹，或請其作者修改。若逐字稿行以 `hooks` 開頭，表示有多個已載入的 mod 具有該位置的 `ui.render` hook，因此請檢查每個 mod 的樹。當提示詞上方的各列合計超出帶狀的限制時，該行如下：

252 254

253```text theme={null}255```text theme={null}

254hooks: ui.render (AbovePrompt) refused: deeper than 32; nothing was drawn256hooks: ui.render (AbovePrompt) refused: a row past the limits of the band; nothing was drawn

255```257```

256 258

259儘管該行如此結尾，符合限制的列仍會繪製。

260

257在 v2.1.307 之前，任何位置的 `refused:` 行都會回報任何未通過驗證的樹，且對於 `Pane` 與 `AbovePrompt`，其結尾為 `; the engine drew its own`。在這些版本中，請修正原因所指出的問題。261在 v2.1.307 之前，任何位置的 `refused:` 行都會回報任何未通過驗證的樹，且對於 `Pane` 與 `AbovePrompt`，其結尾為 `; the engine drew its own`。在這些版本中，請修正原因所指出的問題。

258 262

259### `needs a key`、`is drawn twice` 或 `key each once`263### `needs a key`、`is drawn twice` 或 `key each once`

307 311

308### 快捷鍵沒有作用312### 快捷鍵沒有作用

309 313

310您的窗格或帶狀沒有鍵盤焦點、您的按鈕位於已收合的帶狀中，或繪圖位於 VS Code 擴充功能中，而該處的按鈕沒有快捷鍵。請執行相符的操作：314您的窗格或帶狀沒有鍵盤焦點、您的按鈕位於已收合的帶狀中、另一個 mod 使用相同的按鍵，或繪圖位於 VS Code 擴充功能中。

311 315

312* **沒有鍵盤焦點**：按 Ctrl+X 然後 Tab，或在[全螢幕轉譯](https://code.claude.com/docs/zh-TW/fullscreen.md)中按一下窗格或帶狀。若要讓窗格在開啟時取得焦點，請從命令以 `focus: true` 開啟它。316* **沒有鍵盤焦點**：按 Ctrl+X 然後 Tab，或在[全螢幕轉譯](https://code.claude.com/docs/zh-TW/fullscreen.md)中按一下窗格或帶狀。若要讓窗格在開啟時取得焦點，請從命令以 `focus: true` 開啟它。

313* **按鈕位於已收合的帶狀中**：帶狀會顯示一列以 `▸ plugin panel hidden` 開頭的暗色列。按該列所指出的按鍵（預設為 Ctrl+X 然後 Ctrl+A）即可[將其展開](#plugin-panel-hidden)。317* **按鈕位於已收合的帶狀中**：帶狀會顯示一列以 `▸ plugin panel hidden` 開頭的暗色列。按該列所指出的按鍵（預設為 Ctrl+X 然後 Ctrl+A）即可[將其展開](#plugin-panel-hidden)。

314* **在 VS Code 擴充功能中**：按一下按鈕，或在按鈕取得焦點後按 Enter318* **帶狀中另一個 mod 的列使用相同的快捷鍵**：在終端機中，該按鍵不會按下任何一個按鈕。若要確認，請逐一[關閉](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#turn-mods-on-or-off)繪製列的其他 mod，直到該按鍵有作用為止。請變更您按鈕的 `hotkey`，或請該 mod 的作者變更其快捷鍵。

319* **在 VS Code 擴充功能中，該處的按鈕沒有快捷鍵**：按一下按鈕，或在按鈕取得焦點後按 Enter

315 320

316### 繪圖在終端機中有效，但在 Desktop 應用程式或 VS Code 中無效321### 繪圖在終端機中有效，但在 Desktop 應用程式或 VS Code 中無效

317 322

plugins/overview.md +1 −1

Details

36 36

37![Diagram in two columns joined by five straight arrows. Left, the directory of a plugin named my-plugin, holding a manifest at .claude-plugin/plugin.json, skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json, .mcp.json, and other components. Right, what each file gives you in your session: the manifest sets the plugin name, my-plugin; the skill runs as /my-plugin:review; the agent file is a subagent Claude can delegate to; the hooks file holds hooks that run on lifecycle events; and .mcp.json adds an MCP server that gives Claude tools.](https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max\&auto=format\&n=2Q_GtOEovg5qaBem\&q=85\&s=f623b64e82713b830e48174f0a922888)37![Diagram in two columns joined by five straight arrows. Left, the directory of a plugin named my-plugin, holding a manifest at .claude-plugin/plugin.json, skills/review/SKILL.md, agents/reviewer.md, hooks/hooks.json, .mcp.json, and other components. Right, what each file gives you in your session: the manifest sets the plugin name, my-plugin; the skill runs as /my-plugin:review; the agent file is a subagent Claude can delegate to; the hooks file holds hooks that run on lifecycle events; and .mcp.json adds an MCP server that gives Claude tools.](https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max\&auto=format\&n=2Q_GtOEovg5qaBem\&q=85\&s=f623b64e82713b830e48174f0a922888)

38 38

39如需 plugin 可以包含的每種元件類型及其示例，請參閱 [Plugin 元件](https://code.claude.com/docs/zh-TW/plugins/components.md)。若要查看每個部分在 plugin 目錄中的位置，請使用該頁面上的 [plugin 探索工具](https://code.claude.com/docs/zh-TW/plugins/components.md#explore-the-plugin-directory)。39如需外掛可以包含的元件類型及各類型的範例，請參閱[外掛元件](https://code.claude.com/docs/zh-TW/plugins/components.md)。若要查看每個部分在外掛目錄中的位置，請使用該頁面上的[外掛探索工具](https://code.claude.com/docs/zh-TW/plugins/components.md#explore-the-plugin-directory)。

40 40

41### 決定您是否需要 plugin41### 決定您是否需要 plugin

42 42

plugins/publish.md +1 −1

Details

59 59

60**5. 填入使用者看到的中繼資料**60**5. 填入使用者看到的中繼資料**

61 61

62在 `plugin.json` 中設定 `description`、`author`、`homepage` 和 `repository`，並在外掛程式根目錄新增 `README.md`。`homepage` 必須解析為 URL。[資訊清單參考](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md#fields) 列出每個欄位。62在 `plugin.json` 中設定 `description`、`author`、`homepage` 和 `repository`，並在外掛程式根目錄新增 `README.md`。`homepage` 必須解析為 URL。若要了解每個欄位接受的內容，請參閱 [資訊清單參考](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md#fields)。

63 63

64**6. 執行您的評估套件**64**6. 執行您的評估套件**

65 65

remote-control.md +3 −2

Details

67> | `--capacity <N>` | 同時進行的工作階段數量上限。預設為 32。不可與 `--spawn=session` 一起使用。 |67> | `--capacity <N>` | 同時進行的工作階段數量上限。預設為 32。不可與 `--spawn=session` 一起使用。 |

68> | `--[no-]create-session-in-dir` | 在伺服器啟動時於目前目錄預先建立一個工作階段，讓您可以立即開始輸入。在 `worktree` 模式下，此工作階段會留在目前目錄，而隨需建立的工作階段則會取得隔離的 worktree。預設為開啟。若您傳入 `--no-create-session-in-dir` 以不建立任何工作階段的方式啟動，Claude Code 會在您停止伺服器時封存伺服器的工作階段，因此將沒有可[恢復](#resume-sessions-after-stopping-the-server)的工作階段。 |68> | `--[no-]create-session-in-dir` | 在伺服器啟動時於目前目錄預先建立一個工作階段，讓您可以立即開始輸入。在 `worktree` 模式下，此工作階段會留在目前目錄，而隨需建立的工作階段則會取得隔離的 worktree。預設為開啟。若您傳入 `--no-create-session-in-dir` 以不建立任何工作階段的方式啟動，Claude Code 會在您停止伺服器時封存伺服器的工作階段，因此將沒有可[恢復](#resume-sessions-after-stopping-the-server)的工作階段。 |

69> | `--permission-mode <mode>` | 設定伺服器工作階段的起始[權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)，例如 `acceptEdits`。接受 `manual` 作為 `default` 的別名；無法辨識的模式會在啟動時停止伺服器並列出有效的模式。 |69> | `--permission-mode <mode>` | 設定伺服器工作階段的起始[權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)，例如 `acceptEdits`。接受 `manual` 作為 `default` 的別名；無法辨識的模式會在啟動時停止伺服器並列出有效的模式。 |

70> | `--settings <file>` | 將 JSON 設定檔套用至伺服器的工作階段，其[優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)與 `claude --settings` 相同。請提供檔案路徑，而非 JSON 字串。需要 Claude Code v2.1.321 或更新版本。 |

70> | `--chrome` / `--no-chrome` | 在伺服器建立的工作階段中開啟或關閉 [Chrome 整合](https://code.claude.com/docs/zh-TW/chrome.md)，讓 Claude 能在您從其他裝置工作時使用您機器上的 Chrome。若未使用任一旗標，伺服器預先建立的工作階段，以及您自行從 claude.ai/code 或 Claude 應用程式啟動的任何工作階段，都會以 Chrome 關閉的狀態開始，即使您已[預設啟用 Chrome](https://code.claude.com/docs/zh-TW/chrome.md#enable-chrome-by-default) 亦然。伺服器為您的某個[專案](https://code.claude.com/docs/zh-TW/claude-projects.md)執行緒啟動的工作階段則會改為遵循該設定，但 `bypassPermissions` 模式除外。需要 Claude Code v2.1.273 或更新版本。 |71> | `--chrome` / `--no-chrome` | 在伺服器建立的工作階段中開啟或關閉 [Chrome 整合](https://code.claude.com/docs/zh-TW/chrome.md)，讓 Claude 能在您從其他裝置工作時使用您機器上的 Chrome。若未使用任一旗標，伺服器預先建立的工作階段，以及您自行從 claude.ai/code 或 Claude 應用程式啟動的任何工作階段，都會以 Chrome 關閉的狀態開始，即使您已[預設啟用 Chrome](https://code.claude.com/docs/zh-TW/chrome.md#enable-chrome-by-default) 亦然。伺服器為您的某個[專案](https://code.claude.com/docs/zh-TW/claude-projects.md)執行緒啟動的工作階段則會改為遵循該設定，但 `bypassPermissions` 模式除外。需要 Claude Code v2.1.273 或更新版本。 |

72> | `--debug-file <path>` | 將除錯日誌寫入指定的檔案。 |73> | `--debug-file <path>` | 將除錯日誌寫入指定的檔案。 |

73> | `--verbose` | 顯示詳細的連線與工作階段日誌。 |74> | `--verbose` | 顯示詳細的連線與工作階段日誌。 |

74> | `--sandbox`, `--no-sandbox` | 已於 v2.1.300 移除。若您傳入任一旗標，伺服器會[以錯誤結束](https://code.claude.com/docs/zh-TW/errors.md#sandbox-is-not-supported-by-claude-remote-control)而不會啟動。 |75> | `--sandbox`, `--no-sandbox` | 已於 v2.1.300 移除。若您傳入任一旗標，伺服器會[以錯誤結束](https://code.claude.com/docs/zh-TW/errors.md#sandbox-is-not-supported-by-claude-remote-control)而不會啟動。 |

75>76>

76> 若您在 `remote-control` 之前傳入全域 `claude` 旗標，或包裝指令碼加入了此類旗標，Claude Code 不會將該旗標沿用至伺服器建立的工作階段。只有在已知捨棄該旗標不會改變這些工作階段的能力時，Claude Code 才會讓該旗標通過，例如 `--verbose` 或 `--model`。對於任何其他旗標，例如 `--settings`，Claude Code 會[拒絕啟動](https://code.claude.com/docs/zh-TW/errors.md#not-carried-over-to-the-sessions-remote-control-starts)，並指出需要移除的旗標名稱。77> 若您在 `remote-control` 之前傳入全域 `claude` 旗標，或包裝指令碼加入了此類旗標，Claude Code 不會將該旗標沿用至伺服器建立的工作階段。使用某些旗標時，例如 `--verbose` 或 `--model`，伺服器仍會啟動。使用任何其他旗標時，伺服器[不會啟動](https://code.claude.com/docs/zh-TW/errors.md#not-carried-over-to-the-sessions-remote-control-starts)。若要傳入設定檔，請將 `--settings` 放在 `remote-control` 之後。

77>78>

78> 若要將伺服器啟動的工作階段置於沙箱中，請在設定檔中開啟[沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md)。79> 若要將伺服器啟動的工作階段置於沙箱中，請在設定檔中開啟[沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md)。

79>80>

375* **轉發的對話框會過期**：Claude Code 會讓權限提示和 `AskUserQuestion` 問題保持開啟，直到您回答為止。當 Claude Code 將其他類型的對話框轉發到遠端工作階段時（例如在安全性拒絕後顯示的模型選擇提示），預設會等待五分鐘，然後關閉對話框並以該對話框的無動作預設值繼續。設定 [`dialogExpiry`](https://code.claude.com/docs/zh-TW/settings-reference#dialogexpiry) 以調整或停用此期限。需要 Claude Code v2.1.224 或更新版本。376* **轉發的對話框會過期**：Claude Code 會讓權限提示和 `AskUserQuestion` 問題保持開啟，直到您回答為止。當 Claude Code 將其他類型的對話框轉發到遠端工作階段時（例如在安全性拒絕後顯示的模型選擇提示），預設會等待五分鐘，然後關閉對話框並以該對話框的無動作預設值繼續。設定 [`dialogExpiry`](https://code.claude.com/docs/zh-TW/settings-reference#dialogexpiry) 以調整或停用此期限。需要 Claude Code v2.1.224 或更新版本。

376* **Fable 用量點數同意提示不會被轉發**：Claude Code 只會在工作階段執行的位置顯示工作階段中途的 [Fable 用量點數同意提示](https://code.claude.com/docs/zh-TW/model-config.md#fable-and-usage-credits)，而不會顯示在您的裝置上。當工作階段在終端機中執行，且在 Claude Code 關閉提示之前沒有人在那裡回答時，該回合會在未傳送請求的情況下結束；請參閱[需要確認的提示未獲回應](https://code.claude.com/docs/zh-TW/errors.md#the-prompt-to-confirm-went-unanswered)。377* **Fable 用量點數同意提示不會被轉發**：Claude Code 只會在工作階段執行的位置顯示工作階段中途的 [Fable 用量點數同意提示](https://code.claude.com/docs/zh-TW/model-config.md#fable-and-usage-credits)，而不會顯示在您的裝置上。當工作階段在終端機中執行，且在 Claude Code 關閉提示之前沒有人在那裡回答時，該回合會在未傳送請求的情況下結束；請參閱[需要確認的提示未獲回應](https://code.claude.com/docs/zh-TW/errors.md#the-prompt-to-confirm-went-unanswered)。

377* **部分命令僅限本機使用**：僅在終端機介面中執行的命令（例如 `/plugin` 或 `/resume`）只能從本機 CLI 使用，無論您是否傳入引數。從行動裝置或網頁輸入 `/claude-api` 時也無法使用。Claude 仍可在那裡[自行載入該 skill](https://code.claude.com/docs/zh-TW/skills.md#work-on-claude-api-projects)。以下命令可從行動裝置和網頁使用：378* **部分命令僅限本機使用**：僅在終端機介面中執行的命令（例如 `/plugin` 或 `/resume`）只能從本機 CLI 使用，無論您是否傳入引數。從行動裝置或網頁輸入 `/claude-api` 時也無法使用。Claude 仍可在那裡[自行載入該 skill](https://code.claude.com/docs/zh-TW/skills.md#work-on-claude-api-projects)。以下命令可從行動裝置和網頁使用：

378 * 文字輸出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`。`/usage-credits` 會輸出計費 URL，而不是開啟瀏覽器。`/reload-plugins` 僅在工作階段於互動式終端機中執行時才能運作；沒有互動式終端機的工作階段會拒絕此命令。379 * 文字輸出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`。`/usage-credits` 會以文字回覆，例如說明在哪裡管理用量點數。`/reload-plugins` 僅在工作階段於互動式終端機中執行時才能運作；沒有互動式終端機的工作階段會拒絕此命令。

379 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：以引數傳入值，例如 `/model sonnet` 或 `/effort high`。從行動裝置和網頁使用時，`/model` 和 `/effort` 會以引數取代終端機中的選擇器或滑桿。380 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：以引數傳入值，例如 `/model sonnet` 或 `/effort high`。從行動裝置和網頁使用時，`/model` 和 `/effort` 會以引數取代終端機中的選擇器或滑桿。

380 * `/mcp`：從行動應用程式使用時，會傳回伺服器狀態的文字摘要，而不是開啟選擇器。在網頁上，單獨使用 `/mcp` 會開啟 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)目錄，而不是傳回摘要。當工作階段於互動式終端機中執行時，`reconnect`、`enable` 和 `disable` [子命令](https://code.claude.com/docs/zh-TW/commands.md#all-commands)在兩者上皆可使用。不指定伺服器名稱的 `/mcp reconnect` 會重試所有失敗或需要身分驗證的伺服器。若要在不使用選擇器的情況下授權 claude.ai 連接器，請參閱[從您的 shell 再次授權連接器](#authorize-a-connector-again-from-your-shell)。381 * `/mcp`：從行動應用程式使用時，會傳回伺服器狀態的文字摘要，而不是開啟選擇器。在網頁上，單獨使用 `/mcp` 會開啟 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)目錄，而不是傳回摘要。當工作階段於互動式終端機中執行時，`reconnect`、`enable` 和 `disable` [子命令](https://code.claude.com/docs/zh-TW/commands.md#all-commands)在兩者上皆可使用。不指定伺服器名稱的 `/mcp reconnect` 會重試所有失敗或需要身分驗證的伺服器。若要在不使用選擇器的情況下授權 claude.ai 連接器，請參閱[從您的 shell 再次授權連接器](#authorize-a-connector-again-from-your-shell)。

381 * `/config`：從行動應用程式使用時，傳入 `key=value` 以設定某個設定項目，或不帶引數執行以列出您可以設定的設定鍵。在網頁上，`/config` 會改為開啟 **Settings > Code** 或 **Settings > Claude Code**。382 * `/config`：從行動應用程式使用時，傳入 `key=value` 以設定某個設定項目，或不帶引數執行以列出您可以設定的設定鍵。在網頁上，`/config` 會改為開啟 **Settings > Code** 或 **Settings > Claude Code**。

routines.md +1 −1

Details

431 431

432每個排程任務都使用一個[雲端環境](https://code.claude.com/docs/zh-TW/cloud-environments.md)，用來控制網路存取、環境變數和設定指令碼。任務在每次執行時都會繼承環境的網路政策。432每個排程任務都使用一個[雲端環境](https://code.claude.com/docs/zh-TW/cloud-environments.md)，用來控制網路存取、環境變數和設定指令碼。任務在每次執行時都會繼承環境的網路政策。

433 433

434**Default** 環境使用 **Limited** 存取，並已勾選 **Allow package managers**，因此其執行可以連線到[預設允許清單](https://code.claude.com/docs/zh-TW/cloud-environments.md#default-allowed-domains)中的主機。對遭封鎖主機的請求會失敗，並傳回 `403` 和 `x-deny-reason: host_not_allowed`。MCP 連接器的流量會經由 Anthropic 的伺服器路由，因此您新增到任務的連接器無需將其主機加入 **Allowed domains** 即可運作。請在[連接器](#connectors)下移除您不需要的連接器。434**Default** 環境使用 **Limited** 存取，並已勾選 **Allow package managers**，因此其執行可以連線到[預設允許清單](https://code.claude.com/docs/zh-TW/cloud-environments.md#default-allowed-domains)中的主機。對遭封鎖主機的請求會失敗，並出現[例如 `403` 或 `ENOTFOUND` 之類的錯誤](https://code.claude.com/docs/zh-TW/errors#host-not-allowed-in-a-cloud-session)。MCP 連接器的流量會經由 Anthropic 的伺服器路由，因此您新增到任務的連接器無需將其主機加入 **Allowed domains** 即可運作。請在[連接器](#connectors)下移除您不需要的連接器。

435 435

436若要在您自己的某個環境上允許其他網域，請依照以下步驟操作。[組織共用環境](https://code.claude.com/docs/zh-TW/cloud-environments.md#organization-shared-environments)在此處會以唯讀方式開啟，因此改由擁有者從[管理設定](https://claude.ai/admin-settings)中的 **Cloud environments** 頁面變更其網路存取。436若要在您自己的某個環境上允許其他網域，請依照以下步驟操作。[組織共用環境](https://code.claude.com/docs/zh-TW/cloud-environments.md#organization-shared-environments)在此處會以唯讀方式開啟，因此改由擁有者從[管理設定](https://claude.ai/admin-settings)中的 **Cloud environments** 頁面變更其網路存取。

437 437

sandboxing.md +5 −3

Details

276 276

277這些路徑在作業系統層級強制執行，因此所有在沙箱內執行的命令（包括其子程序）都會遵守這些路徑。當某個工具需要特定位置的寫入權限時，建議採用此方法，而不是使用 `excludedCommands` 將該工具完全排除在沙箱之外。277這些路徑在作業系統層級強制執行，因此所有在沙箱內執行的命令（包括其子程序）都會遵守這些路徑。當某個工具需要特定位置的寫入權限時，建議採用此方法，而不是使用 `excludedCommands` 將該工具完全排除在沙箱之外。

278 278

279在 Linux 和 WSL2 上，針對尚不存在之路徑的項目不會有任何作用，因此請先建立該路徑。

280

279當您在多個[設定範圍](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)中定義相同的檔案系統陣列時，Claude Code 會將它們合併，結合每個範圍中的路徑，而不是以某個範圍的陣列取代另一個範圍的陣列。當[防止開發人員擴大政策](#keep-developers-from-widening-the-policy)中所述的鎖定涵蓋某個項目時，Claude Code 會將該項目排除在合併之外。281當您在多個[設定範圍](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)中定義相同的檔案系統陣列時，Claude Code 會將它們合併，結合每個範圍中的路徑，而不是以某個範圍的陣列取代另一個範圍的陣列。當[防止開發人員擴大政策](#keep-developers-from-widening-the-policy)中所述的鎖定涵蓋某個項目時，Claude Code 會將該項目排除在合併之外。

280 282

281如果您在 CLI 上使用 [`--setting-sources`](https://code.claude.com/docs/zh-TW/cli-reference) 或在 Agent SDK 中使用 [`settingSources`](https://code.claude.com/docs/zh-TW/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 排除某個來源，Claude Code 在建置沙箱設定時會忽略該來源的 `sandbox.filesystem` 項目、其 `Edit` 權限規則，以及其 `Read` 拒絕規則。需要 Claude Code v2.1.246 或更新版本。283如果您在 CLI 上使用 [`--setting-sources`](https://code.claude.com/docs/zh-TW/cli-reference) 或在 Agent SDK 中使用 [`settingSources`](https://code.claude.com/docs/zh-TW/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 排除某個來源，Claude Code 在建置沙箱設定時會忽略該來源的 `sandbox.filesystem` 項目、其 `Edit` 權限規則，以及其 `Read` 拒絕規則。需要 Claude Code v2.1.246 或更新版本。

376 378

377由於關閉檔案系統隔離會擴大沙箱化命令能做的事，Claude Code 僅接受來自以下設定來源的 `filesystem.disabled`：379由於關閉檔案系統隔離會擴大沙箱化命令能做的事，Claude Code 僅接受來自以下設定來源的 `filesystem.disabled`：

378 380

379* 使用者設定、受管設定和 `--settings` CLI 旗標可以設定它。`.claude/settings.json` 和 `.claude/settings.local.json` 中的專案設定則不行，因此簽出的專案無法關閉檔案系統隔離。381* 使用者設定、受管設定和 `--settings` CLI 旗標可以設定它。`.claude/settings.json` 和 `.claude/settings.local.json` 中的專案設定則無法設定它。

380* 當受管設定有設定任何 `sandbox.filesystem`，或列出任何 `"mode": "deny"` 的 `sandbox.credentials.files` 項目時，只有受管設定可以設定此鍵。這可防止開發人員在此類部署中關閉檔案系統隔離；若要為所有人關閉檔案系統隔離，請在受管設定中設定 `"disabled": true`。382* 當受管設定有設定任何 `sandbox.filesystem`，或列出任何 `"mode": "deny"` 的 `sandbox.credentials.files` 項目時，只有受管設定可以設定此鍵。若要為所有人關閉檔案系統隔離，請在受管設定中設定 `"disabled": true`。

381* 當設定了 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](https://code.claude.com/docs/zh-TW/env-vars) 時，Claude Code 會忽略來自所有來源（包括受管設定）的 `filesystem.disabled`，並保持檔案系統隔離開啟。383* 當設定了 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](https://code.claude.com/docs/zh-TW/env-vars) 時，Claude Code 會忽略來自所有來源（包括受管設定）的 `filesystem.disabled`。

382 384

383[有效的](https://code.claude.com/docs/zh-TW/settings-reference.md#invalid-credential-entries-in-managed-settings) `mask` 項目不會鎖定此鍵，即使 Claude Code 在啟動時對其[退回 `deny`](#mask-credential-files) 也是如此。請將無法遮罩的路徑（例如憑證目錄）在受管設定中列為明確的 `deny` 項目，這樣會鎖定此鍵。385[有效的](https://code.claude.com/docs/zh-TW/settings-reference.md#invalid-credential-entries-in-managed-settings) `mask` 項目不會鎖定此鍵，即使 Claude Code 在啟動時對其[退回 `deny`](#mask-credential-files) 也是如此。請將無法遮罩的路徑（例如憑證目錄）在受管設定中列為明確的 `deny` 項目，這樣會鎖定此鍵。

384 386

self-hosted-environments-deploy.md +9 −3

Details

117 117

118* **偵聽器**：偵聽器是 `127.0.0.1` 上的轉發代理。執行器在向控制平面註冊之前啟動偵聽器，如果偵聽器無法啟動則在啟動時退出。118* **偵聽器**：偵聽器是 `127.0.0.1` 上的轉發代理。執行器在向控制平面註冊之前啟動偵聽器，如果偵聽器無法啟動則在啟動時退出。

119* **代理變數**：執行器重寫您設定的 `HTTPS_PROXY` 和 `HTTP_PROXY` 中的任一個，使其指向偵聽器。該重寫的值到達執行器本身、其生命週期鉤子和它執行的每個工作階段。119* **代理變數**：執行器重寫您設定的 `HTTPS_PROXY` 和 `HTTP_PROXY` 中的任一個，使其指向偵聽器。該重寫的值到達執行器本身、其生命週期鉤子和它執行的每個工作階段。

120* **令牌輪換**：輪換的令牌無需重新啟動即可生效。對於偵聽器打開到您的代理的每個連接，執行器再次執行您的命令或讀取您的檔案並將結果添加為標頭。120* **Token 輪換**：當您輪換 token 時，新連接會攜帶新的 token，無需重新啟動執行器。對於偵聽器打開到您的代理伺服器的每個連接，執行器再次執行您的命令或讀取您的檔案並將結果添加為標頭。已經打開的連接會繼續以舊 token 使用，直到您的代理伺服器關閉它或執行器退出為止。

121* **工作階段環境**：工作階段僅通過偵聽器到達您的代理。在每個工作階段的環境中，執行器移除 `ALL_PROXY`、移除您未設定的 `HTTPS_PROXY` 或 `HTTP_PROXY` 的任何拼寫，並將 `NO_PROXY` 固定到執行器自己的值。121* **工作階段環境**：工作階段僅通過偵聽器到達您的代理。在每個工作階段的環境中，執行器移除 `ALL_PROXY`、移除您未設定的 `HTTPS_PROXY` 或 `HTTP_PROXY` 的任何拼寫，並將 `NO_PROXY` 固定到執行器自己的值。

122* **日誌**：執行器永遠不會記錄標頭值。122* **日誌**：執行器永遠不會記錄標頭值。

123 123

840 840

841### 某些工作階段不計為閒置841### 某些工作階段不計為閒置

842 842

843持有持續執行中的背景任務的工作階段不計為閒置，因此 `--release-idle-session-min` 不會釋放該工作階段的插槽。等待從執行中工具呼叫內部請求的核准的工作階段也不計為閒置。請將 `--kill-session-after-min` 與其一起設定作為硬性後擋。843工作階段在不計為閒置的期間，會在超過 `--release-idle-session-min` 限制後仍保留其插槽，因此也請設定 `--kill-session-after-min`。

844

845工作階段在其回合結束後，或在其回合等待其使用者期間，會計為閒置，但在以下這類情況則不會：

846

847* 其回合已結束且未在等待其使用者，但有背景任務持續執行

848* 其回合正在等待非 MCP 工具在執行期間請求的核准

849* 其回合正在等待 MCP 伺服器的 [`elicitation/create` 請求](https://code.claude.com/docs/zh-TW/mcp#respond-to-mcp-elicitation-requests)

844 850

845`--kill-session-after-min` 是失控工作階段的後擋。在 v2.1.260 或更新版本上的執行器上，達到限制的工作階段不會立即終止。執行器給它一個寬限窗口，預設 15 分鐘，您可以使用 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#environment-variable-only-settings) 更改：851`--kill-session-after-min` 是失控工作階段的後擋。在 v2.1.260 或更新版本上的執行器上，達到限制的工作階段不會立即終止。執行器給它一個寬限窗口，預設 15 分鐘，您可以使用 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#environment-variable-only-settings) 更改：

846 852

847* 如果工作階段等待其使用者，執行器會釋放它。如果其轉向已結束並且它僅持有背景任務，執行器會等待最多 60 秒讓這些任務完成，然後釋放它。當其使用者發送下一條訊息時，工作階段會恢復。853* 如果工作階段等待其使用者，執行器會釋放它。如果其轉向已結束並且它僅持有背景任務，執行器會等待最多 60 秒讓這些任務完成，然後釋放它。當其使用者發送下一條訊息時，工作階段會恢復。

848* 如果轉向仍在執行，執行器等待轉向完成，或工作階段下一次等待其使用者，然後釋放它。854* 如果轉向仍在執行，執行器等待轉向完成，或工作階段下一次等待其使用者，然後釋放它。

849* 如果工作階段在寬限窗口結束時仍在執行器上，執行器終止它，任何執行中轉向的工作都會丟失。等待從執行中工具呼叫內部請求的批准的轉向是工作階段超過窗口的一種方式。855* 如果工作階段在寬限窗口結束時仍在執行器上，執行器會終止它，任何執行中回合的工作都會遺失。例如，如果工作階段的回合正在等待非 MCP 工具在執行期間請求的核准，該工作階段可能會一直留在執行器上直到那時。工作階段的回合在等待 MCP 伺服器的 `elicitation/create` 請求時，也可能留在執行器上。

850 856

851釋放的工作階段從新複製恢復，因此它未推送的工作無論如何都消失了；請參閱[恢復的工作階段遺失未推送的工作](#resumed-sessions-lose-unpushed-work)。在 v2.1.260 之前，執行器在限制處終止每個工作階段，最多等待寬限窗口以完成執行中的回合。857釋放的工作階段從新複製恢復，因此它未推送的工作無論如何都消失了；請參閱[恢復的工作階段遺失未推送的工作](#resumed-sessions-lose-unpushed-work)。在 v2.1.260 之前，執行器在限制處終止每個工作階段，最多等待寬限窗口以完成執行中的回合。

852 858

server-managed-settings.md +7 −1

Details

252 252

253快取 `env` 區塊中的其他所有鍵都會在啟動時套用。一旦伺服器確認了 payload，且若該 payload 需要[安全性核准](#security-approval-dialogs)而您已核准，暫緩的變數就會在工作階段的剩餘時間內套用。253快取 `env` 區塊中的其他所有鍵都會在啟動時套用。一旦伺服器確認了 payload，且若該 payload 需要[安全性核准](#security-approval-dialogs)而您已核准，暫緩的變數就會在工作階段的剩餘時間內套用。

254 254

255如果您的組織需要透過代理伺服器才能連線到 `api.anthropic.com`，暫緩只會影響伺服器傳遞的 `env` 區塊本身：透過 MDM 或 `managed-settings.json` 在[端點受管](https://code.claude.com/docs/zh-TW/managed-settings.md#delivery-mechanisms) `env` 區塊中設定的代理伺服器、在 shell 環境中設定的代理伺服器，或在[使用者設定](https://code.claude.com/docs/zh-TW/settings.md#where-settings-live)中設定的代理伺服器，都能用於設定擷取。端點受管來源需要 Claude Code v2.1.223 或更新版本：快取的伺服器受管代理伺服器值在擷取確認之前會被暫緩，因此端點受管的值會逐鍵補上，並用於擷取本身。在 v2.1.223 之前，請使用 shell 環境或使用者設定，讓代理伺服器能與快取的伺服器 payload 一起套用。首次啟動時沒有快取，因此初次擷取仍需要端點受管來源、shell 環境或使用者設定。255如果擷取需要透過代理伺服器，請在下列其中一處設定 `HTTPS_PROXY`：

256

257* 透過 MDM 或 `managed-settings.json` 設定的[端點受管](https://code.claude.com/docs/zh-TW/managed-settings.md#delivery-mechanisms) `env` 區塊。此來源需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，請使用 shell 環境或使用者設定，讓代理伺服器[與快取的伺服器 payload 一起套用](#per-key-exceptions-across-managed-sources)。

258* shell 環境

259* [使用者設定](https://code.claude.com/docs/zh-TW/settings.md#where-settings-live)

260

261即使 `ALL_PROXY` 已指定代理伺服器，仍請設定 `HTTPS_PROXY`。

256 262

257Claude Code 會在不需重新啟動的情況下，將大多數設定更新套用至執行中的工作階段。部分更新僅在下次啟動時套用，包括 OpenTelemetry 匯出器組態、`model` 鍵，以及從 `env` 區塊中移除變數。263Claude Code 會在不需重新啟動的情況下，將大多數設定更新套用至執行中的工作階段。部分更新僅在下次啟動時套用，包括 OpenTelemetry 匯出器組態、`model` 鍵，以及從 `env` 區塊中移除變數。

258 264

settings.md +1 −1

Details

177 177

178Claude Code 監視您的設定檔案並在它們變更時重新載入它們，因此它應用大多數編輯到執行中的工作階段而不需要重新啟動，包括對 `permissions`、`hooks` 和認證協助程式（例如 `apiKeyHelper`）的編輯。Claude Code 也在其資料夾在工作階段啟動時存在時載入您在中途建立的設定檔案。對於專案的 `.claude/` 資料夾，即使您在同一工作階段中建立資料夾，它也會載入檔案。178Claude Code 監視您的設定檔案並在它們變更時重新載入它們，因此它應用大多數編輯到執行中的工作階段而不需要重新啟動，包括對 `permissions`、`hooks` 和認證協助程式（例如 `apiKeyHelper`）的編輯。Claude Code 也在其資料夾在工作階段啟動時存在時載入您在中途建立的設定檔案。對於專案的 `.claude/` 資料夾，即使您在同一工作階段中建立資料夾，它也會載入檔案。

179 179

180重新載入涵蓋使用者、專案、本機和受管設定，Claude Code 為它偵測到的每個設定檔案變更執行 [`ConfigChange` hook](https://code.claude.com/docs/zh-TW/hooks#configchange)，而不是來自 MDM 或 claude.ai 主控台的受管設定。來自 MDM 或 claude.ai 主控台的受管設定按排程而不是保存時到達執行中的工作階段；[傳遞表](https://code.claude.com/docs/zh-TW/managed-settings.md#choose-a-delivery-mechanism)按來源給出它。180重新載入涵蓋使用者、專案、本機和受管設定。Claude Code 會針對直接編輯設定檔案執行 [`ConfigChange` hook](https://code.claude.com/docs/zh-TW/hooks#configchange)，而不會針對來自 MDM 或 claude.ai 主控台的受管設定執行。來自 MDM 或 claude.ai 主控台的受管設定按排程而不是保存時到達執行中的工作階段；[傳遞表](https://code.claude.com/docs/zh-TW/managed-settings.md#choose-a-delivery-mechanism)按來源給出它。

181 181

182Claude Code 只在工作階段啟動時讀取某些金鑰一次，因此對其中一個的編輯不會到達執行中的工作階段。也等待重新啟動的管理員端金鑰（例如 `requiredMinimumVersion`）列在[政策適用的位置和時間](https://code.claude.com/docs/zh-TW/managed-settings.md#where-and-when-a-policy-applies)下。您最可能在中途編輯的是：182Claude Code 只在工作階段啟動時讀取某些金鑰一次，因此對其中一個的編輯不會到達執行中的工作階段。也等待重新啟動的管理員端金鑰（例如 `requiredMinimumVersion`）列在[政策適用的位置和時間](https://code.claude.com/docs/zh-TW/managed-settings.md#where-and-when-a-policy-applies)下。您最可能在中途編輯的是：

183 183

settings-reference.md +10 −29

Details

885}884}

886```885```

887 886

888請參閱[將所有 shell 命令路由到分類器](https://code.claude.com/docs/zh-TW/auto-mode-config.md#route-all-shell-commands-through-the-classifier)。887此設定鍵在 Code Mode 工作階段中的運作方式不同。請參閱[將所有 shell 命令路由到分類器](https://code.claude.com/docs/zh-TW/auto-mode-config.md#route-all-shell-commands-through-the-classifier)。

889 888

890### `disableAutoMode`889### `disableAutoMode`

891 890

1533}1532}

1534```1533```

1535 1534

1535在 Linux 和 WSL2 上，針對尚不存在之路徑的項目不會生效，因此請先建立該路徑。

1536

1536Claude Code 會在工作階段載入的所有設定範圍之間合併 `allowWrite` 項目，以及您 `Edit(...)` 允許權限規則中的路徑；當 [`permissions.blockReadsOutsideWorkingDirectories`](#sandboxed-commands-under-the-block) 開啟時，會排除來自儲存庫設定的項目。[儲存庫鎖定](https://code.claude.com/docs/zh-TW/sandboxing.md#repository-settings-under-an-admin-required-sandbox)也可能排除儲存庫的項目。`allowWrite` 項目無法解除[受保護路徑](https://code.claude.com/docs/zh-TW/sandboxing.md#protected-paths)的限制。1537Claude Code 會在工作階段載入的所有設定範圍之間合併 `allowWrite` 項目，以及您 `Edit(...)` 允許權限規則中的路徑；當 [`permissions.blockReadsOutsideWorkingDirectories`](#sandboxed-commands-under-the-block) 開啟時，會排除來自儲存庫設定的項目。[儲存庫鎖定](https://code.claude.com/docs/zh-TW/sandboxing.md#repository-settings-under-an-admin-required-sandbox)也可能排除儲存庫的項目。`allowWrite` 項目無法解除[受保護路徑](https://code.claude.com/docs/zh-TW/sandboxing.md#protected-paths)的限制。

1537 1538

1538### `sandbox.filesystem.denyWrite`1539### `sandbox.filesystem.denyWrite`

2453 2454

2454#### `env` 值如何與您的 shell 相互作用2455#### `env` 值如何與您的 shell 相互作用

2455 2456

2456* 此處的值會覆蓋在您的 shell 中匯出的相同變數，當多個設定檔設定一個變數時，[最高優先級](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)的值適用。[Claude Code 在 `env` 中忽略的變數](#variables-claude-code-ignores-in-env)列出專案和本機設定的例外。2457* 此處的值會覆寫在您的 shell 中匯出的相同變數，當多個設定檔設定一個變數時，[最高優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)的值適用。[Claude Code 在 `env` 中忽略的變數](#variables-claude-code-ignores-in-env)列出例外情況。

2457* 當 Claude Desktop 應用程式或[自託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments)執行器啟動工作階段時，它建置的啟動環境優先：Claude Code 忽略任何設定檔中的 `env` 值，用於啟動環境已經設定的變數。[偵錯日誌](https://code.claude.com/docs/zh-TW/debug-your-config.md)命名每個被忽略的變數。2458* 當 Claude Desktop 應用程式或[自託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments)執行器啟動工作階段時，它建置的啟動環境優先：Claude Code 忽略任何設定檔中的 `env` 值，用於啟動環境已經設定的變數。[偵錯日誌](https://code.claude.com/docs/zh-TW/debug-your-config.md)命名每個被忽略的變數。

2458* 要取消 shell 匯出，請將變數設定為 `""`。Claude Code 將空值視為未設定以進行提供者選擇，子程序繼承空值。2459* 要取消 shell 匯出，請將變數設定為 `""`。Claude Code 將空值視為未設定以進行提供者選擇，子程序繼承空值。

2459* `NO_COLOR` 和 `FORCE_COLOR` 在此設定只到達子程序。要更改 Claude Code 自己的介面顏色，請在啟動 `claude` 之前在您的 shell 中設定它們。2460* `NO_COLOR` 和 `FORCE_COLOR` 在此設定只到達子程序。要更改 Claude Code 自己的介面顏色，請在啟動 `claude` 之前在您的 shell 中設定它們。

2494 * [`CLAUDE_CODE_DISABLE_FILE_MENTIONS`](https://code.claude.com/docs/zh-TW/env-vars#variables)，它會阻止 Claude Code 展開檔案和目錄的 `@` 提及。2495 * [`CLAUDE_CODE_DISABLE_FILE_MENTIONS`](https://code.claude.com/docs/zh-TW/env-vars#variables)，它會阻止 Claude Code 展開檔案和目錄的 `@` 提及。

2495 2496

2496 在 v2.1.251 之前，專案和本機設定也可以設定此清單中選擇 Claude Code 寫入其檔案位置或匯出工作階段內容的變數，除了 `HOME` 和 `XDG_CONFIG_HOME`。在 v2.1.290 之前，它們也可以設定對話框計時器變數和 `CLAUDE_CODE_DISABLE_ATTACHMENTS`。2497 在 v2.1.251 之前，專案和本機設定也可以設定此清單中選擇 Claude Code 寫入其檔案位置或匯出工作階段內容的變數，除了 `HOME` 和 `XDG_CONFIG_HOME`。在 v2.1.290 之前，它們也可以設定對話框計時器變數和 `CLAUDE_CODE_DISABLE_ATTACHMENTS`。

2498* 您可以從您的 shell、使用者設定或 `--settings` 檔案，使用 [`CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`](https://code.claude.com/docs/zh-TW/env-vars#variables) 開啟 [Code Mode](https://code.claude.com/docs/zh-TW/code-mode.md)，但無法從受管、專案或本機設定開啟。若前三者中任一處或受管設定中設為 `0`，無論您在其他地方如何設定，Code Mode 都會保持關閉。當受管設定包含 `1` 時，請在使用者設定中設定您自己的 `1`，因為 shell 中的 `1` 會被忽略

2497* Claude Code 的託管環境擁有的身份變數，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，從每個檔案中被忽略。2499* Claude Code 的託管環境擁有的身份變數，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，從每個檔案中被忽略。

2498* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](https://code.claude.com/docs/zh-TW/env-vars#variables)，Claude Code 自己匯出的，從每個檔案中被忽略。忽略 socket 變數需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。2500* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](https://code.claude.com/docs/zh-TW/env-vars#variables)，Claude Code 自己匯出的，從每個檔案中被忽略。忽略 socket 變數需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。

2499* [`CLAUDE_CODE_PROJECT_DIR_NAME`](https://code.claude.com/docs/zh-TW/sessions#name-the-project-directory-yourself)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略；需要 v2.1.234 或更高版本。2501* [`CLAUDE_CODE_PROJECT_DIR_NAME`](https://code.claude.com/docs/zh-TW/sessions#name-the-project-directory-yourself)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略；需要 v2.1.234 或更高版本。

3173 3175

3174此範例需要安裝 [`jq`](https://jqlang.org/)，並在 shell 中執行。關於 PowerShell 與 Git Bash 的對應寫法，請參閱 [Windows 設定](https://code.claude.com/docs/zh-TW/statusline.md#windows-configuration)；完整的設定方式請參閱[手動設定狀態列](https://code.claude.com/docs/zh-TW/statusline.md#manually-configure-a-status-line)。3176此範例需要安裝 [`jq`](https://jqlang.org/)，並在 shell 中執行。關於 PowerShell 與 Git Bash 的對應寫法，請參閱 [Windows 設定](https://code.claude.com/docs/zh-TW/statusline.md#windows-configuration)；完整的設定方式請參閱[手動設定狀態列](https://code.claude.com/docs/zh-TW/statusline.md#manually-configure-a-status-line)。

3175 3177

3176### `subagentStatusLine`

~~3177~~

3178當 Claude 執行 [subagent](https://code.claude.com/docs/zh-TW/sub-agents.md) 時，Claude Code 會在提示詞下方的任務顯示區中列出它們，每個 subagent 一列，顯示 `name · description · token count`。此設定鍵讓您執行自己的命令來改寫這些列，例如以百分比顯示每個 subagent 的上下文使用量。每次重新整理時，Claude Code 會將可見的列以一個 JSON 物件透過 stdin 傳送，其中的 `tasks` 陣列包含每個 subagent 的 `id`、`name`、`status`、`model`、`tokenCount` 等資訊，並以您回寫為 `{"id", "content"}` 行的內容取代對應 `id` 的列。您未回寫的列會保留預設渲染。

~~3179~~

3180* **範圍**：[`Any file`](#scopes)。當 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 開啟，或在受管設定之外設定了 [`disableAllHooks`](#disableallhooks) 時，只會執行受管設定的值。

3181* **類型**：物件，包含設為 `"command"` 的 `type` 和 `command` 字串

3182* **預設值**：未設定，因此 Claude Code 渲染預設的列

~~3183~~

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

3185{

3186 "subagentStatusLine": {

3187 "type": "command",

3188 "command": "jq -c '.tasks[] | {id, content: \"\\(.name): \\(.tokenCount) tokens\"}'"

3189 }

3190}

3191```

~~3192~~

3193請參閱 [Subagent 狀態列](https://code.claude.com/docs/zh-TW/statusline.md#subagent-status-lines)。

~~3194~~

3195### `syntaxHighlightingDisabled`3178### `syntaxHighlightingDisabled`

3196 3179

3197Claude Code 會以其內建的語法突顯器，依語言為終端機中顯示的差異、程式碼區塊與檔案預覽上色。將此設定鍵設為 `true` 即可改以純文字顯示，例如當色彩與您的終端機主題衝突或拖慢螢幕閱讀器時。3180Claude Code 會以其內建的語法突顯器，依語言為終端機中顯示的差異、程式碼區塊與檔案預覽上色。將此設定鍵設為 `true` 即可改以純文字顯示，例如當色彩與您的終端機主題衝突或拖慢螢幕閱讀器時。

3648* **其他所有內容被阻止**：使用者、專案和本機 hook、來自其他已安裝外掛的 hook 和 mod，以及在 agent frontmatter 中宣告的 hook。[內建於 Claude Code 的 mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#mods-built-into-claude-code) 會繼續執行。若只要阻止使用者的 mod，請改為設定 [`allowManagedModsOnly`](https://code.claude.com/docs/zh-TW/plugins/mods/admin#set-options-on-the-built-in-guard)。3631* **其他所有內容被阻止**：使用者、專案和本機 hook、來自其他已安裝外掛的 hook 和 mod，以及在 agent frontmatter 中宣告的 hook。[內建於 Claude Code 的 mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#mods-built-into-claude-code) 會繼續執行。若只要阻止使用者的 mod，請改為設定 [`allowManagedModsOnly`](https://code.claude.com/docs/zh-TW/plugins/mods/admin#set-options-on-the-built-in-guard)。

3649* **命令來源的外掛被停用**：Claude Code 也會停用具有 [`command` 來源](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)的外掛，包括在受管 `enabledPlugins` 中強制啟用的外掛，除非您明確將 [`disableCommandPluginSources`](#disablecommandpluginsources) 設定為 `false`3632* **命令來源的外掛被停用**：Claude Code 也會停用具有 [`command` 來源](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)的外掛，包括在受管 `enabledPlugins` 中強制啟用的外掛，除非您明確將 [`disableCommandPluginSources`](#disablecommandpluginsources) 設定為 `false`

3650* **市集 `headersHelper` 命令被阻止**：Claude Code 也會阻止市集 [`headersHelper` 命令](https://code.claude.com/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](#disablecommandpluginsources) 明確設定為 `false`，但受管設定本身宣告的市集除外。需要 Claude Code v2.1.238 或更新版本3633* **市集 `headersHelper` 命令被阻止**：Claude Code 也會阻止市集 [`headersHelper` 命令](https://code.claude.com/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](#disablecommandpluginsources) 明確設定為 `false`，但受管設定本身宣告的市集除外。需要 Claude Code v2.1.238 或更新版本

3651* **狀態列和檔案建議縮限為受管設定**：Claude Code 只從受管設定讀取 [`statusLine`](https://code.claude.com/docs/zh-TW/statusline)、[`fileSuggestion`](#filesuggestion) 和 [`subagentStatusLine`](https://code.claude.com/docs/zh-TW/statusline#subagent-status-lines)，遵循[狀態列和檔案建議閘道](#status-line-and-file-suggestion-gates)3634* **狀態列和檔案建議縮限為受管設定**：Claude Code 只從受管設定讀取 [`statusLine`](https://code.claude.com/docs/zh-TW/statusline) 和 [`fileSuggestion`](#filesuggestion)，遵循[狀態列和檔案建議閘道](#status-line-and-file-suggestion-gates)

3652 3635

3653設定此設定鍵時，[`/goal`](https://code.claude.com/docs/zh-TW/goal) 命令無法執行，因為它依賴於 hook。3636設定此設定鍵時，[`/goal`](https://code.claude.com/docs/zh-TW/goal) 命令無法執行，因為它依賴於 hook。

3654 3637

3687 3670

3688#### 狀態列和檔案建議閘道3671#### 狀態列和檔案建議閘道

3689 3672

3690Claude Code 會依下列順序，為 `statusLine`、`fileSuggestion` 和 `subagentStatusLine` 做出兩項決定：3673Claude Code 會依下列順序，為 `statusLine` 和 `fileSuggestion` 做出兩項決定：

3691 3674

3692* **完全關閉**：當受管設定設定了 `disableAllHooks` 時，或當資料夾在與[設定檔中的 hook 相同的工作區信任規則](https://code.claude.com/docs/zh-TW/permissions.md#what-runs-before-you-trust-a-folder)下不受信任時3675* **完全關閉**：當受管設定設定了 `disableAllHooks` 時，或當資料夾在與[設定檔中的 hook 相同的工作區信任規則](https://code.claude.com/docs/zh-TW/permissions.md#what-runs-before-you-trust-a-folder)下不受信任時

3693* **縮限為受管設定**：當設定了 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 時、當套用[設定優先順序](https://code.claude.com/docs/zh-TW/hooks.md#disable-or-remove-hooks)後 `disableAllHooks` 在受管設定以外為 `true` 時，或當您使用 `--safe-mode` 啟動 Claude Code 時3676* **縮限為受管設定**：當設定了 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 時、當套用[設定優先順序](https://code.claude.com/docs/zh-TW/hooks.md#disable-or-remove-hooks)後 `disableAllHooks` 在受管設定以外為 `true` 時，或當您使用 `--safe-mode` 啟動 Claude Code 時

4659 4642

4660* **Scope**: [`Any file`](#scopes)4643* **Scope**: [`Any file`](#scopes)

4661* **Type**: string，內建或自訂代理程式的名稱4644* **Type**: string，內建或自訂代理程式的名稱

4662* **Default**: 未設定，因此主執行緒以 Claude Code 的預設代理程式執行4645* **Default**: 未設定

4663* **Per-session overrides**: `--agent` 對一個工作階段優先於此金鑰4646* **Per-session overrides**: `--agent` 對一個工作階段優先於此金鑰

4664 4647

4665```json settings.json theme={null}4648```json settings.json theme={null}

4668}4651}

4669```4652```

4670 4653

4671外掛程式自己的 `settings.json` 也可以提供此金鑰；請參閱 [Ship default settings with your plugin](https://code.claude.com/docs/zh-TW/plugins/components.md#default-settings)。

~~4672~~

4673### `crossSessionInbound`4654### `crossSessionInbound`

4674 4655

4675選擇此工作階段如何處理 [來自您其他 Claude Code 工作階段的訊息](https://code.claude.com/docs/zh-TW/cross-session-messaging.md#control-inbound-messages)。當沒有值適用時，Claude Code 會根據兩個工作階段的權限模式類別逐個訊息決定。4656選擇此工作階段如何處理 [來自您其他 Claude Code 工作階段的訊息](https://code.claude.com/docs/zh-TW/cross-session-messaging.md#control-inbound-messages)。當沒有值適用時，Claude Code 會根據兩個工作階段的權限模式類別逐個訊息決定。

5207 5188

5208* **範圍**：[`受管`](#scopes)。機器自己的管理員來源設定的清單、MDM 原則和受管設定檔，在伺服器受管設定也提供一個時繼續適用：工作階段可能只使用兩個清單上的提供者，因此伺服器受管清單可以縮小機器允許的內容，但永遠無法擴大它。哪個機器來源的 `allowedProviders` 計數遵循[Claude Code 如何結合受管來源](https://code.claude.com/docs/zh-TW/managed-settings.md#how-claude-code-combines-managed-sources)。透過伺服器受管設定單獨提供的清單僅到達[擷取伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md#platform-availability)的工作階段。5189* **範圍**：[`受管`](#scopes)。機器自己的管理員來源設定的清單、MDM 原則和受管設定檔，在伺服器受管設定也提供一個時繼續適用：工作階段可能只使用兩個清單上的提供者，因此伺服器受管清單可以縮小機器允許的內容，但永遠無法擴大它。哪個機器來源的 `allowedProviders` 計數遵循[Claude Code 如何結合受管來源](https://code.claude.com/docs/zh-TW/managed-settings.md#how-claude-code-combines-managed-sources)。透過伺服器受管設定單獨提供的清單僅到達[擷取伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md#platform-availability)的工作階段。

5209* **類型**：字串陣列，每個都是以下之一：5190* **類型**：字串陣列，每個都是以下之一：

5210 * `"anthropic"`：Anthropic 自己的主機上的 Anthropic API，透過 claude.ai 或 Console 登入或 API 金鑰。將其與 [`forceLoginMethod`](#forceloginmethod) 或 [`forceLoginOrgUUID`](#forceloginorguuid) 配對以也限制登入5191 * `"anthropic"`：Anthropic 自己的主機上的 Anthropic API，透過 claude.ai 或 Console 登入或 API 金鑰。將其與 [`forceLoginMethod`](#forceloginmethod) 或 [`forceLoginOrgUUID`](#forceloginorguuid) 配對以也限制登入。[在使用者機器上](https://code.claude.com/docs/zh-TW/managed-settings.md#where-and-when-a-policy-applies)的 Desktop Cowork 在登入 claude.ai 時會計為 `"anthropic"`，因此若機器的清單中沒有它，Cowork [會在啟動時被拒絕](https://code.claude.com/docs/zh-TW/errors.md#managed-settings-dont-allow-this-api-provider)。若要讓 Cowork 啟動，請新增它，這也會讓此清單開放給直接的 Anthropic 工作階段。

5211 * `"bedrock"`：[Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)5192 * `"bedrock"`：[Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)

5212 * `"vertex"`：[Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md)，前身為 Vertex AI5193 * `"vertex"`：[Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md)，前身為 Vertex AI

5213 * `"foundry"`：[Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md)5194 * `"foundry"`：[Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md)

5214 * `"anthropicAws"`：[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md)5195 * `"anthropicAws"`：[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md)

5215 * `"mantle"`：Amazon Bedrock [Mantle 端點](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#use-the-mantle-endpoint)。[在 Invoke API 旁邊執行 Mantle](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#run-mantle-alongside-the-invoke-api) 的工作階段使用兩個提供者，因此將 `"bedrock"` 和 `"mantle"` 一起列出5196 * `"mantle"`：Amazon Bedrock [Mantle 端點](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#use-the-mantle-endpoint)。[在 Invoke API 旁邊執行 Mantle](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#run-mantle-alongside-the-invoke-api) 的工作階段使用兩個提供者，因此將 `"bedrock"` 和 `"mantle"` 一起列出

5216 * `"customEndpoint"`：Anthropic API 或雲端提供者的 API 傳送到另一個主機，例如由 `ANTHROPIC_BASE_URL` 或提供者的端點變數（例如 `ANTHROPIC_BEDROCK_BASE_URL`）命名的 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)。Claude Code 僅針對受管 [`env`](#env) 區塊固定的確切值允許它5197 * `"customEndpoint"`：Anthropic API 或雲端提供者的 API 傳送到另一個主機，例如由 `ANTHROPIC_BASE_URL` 或提供者的端點變數（例如 `ANTHROPIC_BEDROCK_BASE_URL`）命名的 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)。Claude Code 僅針對受管 [`env`](#env) 區塊固定的確切值允許它

5217 * `"gateway"`：[Cloud 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)登入5198 * `"gateway"`：[Cloud gateway](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 登入

5218* **預設**：未設定，所以可以使用任何提供者5199* **預設**：未設定，所以可以使用任何提供者

5219 5200

5220```json managed-settings.json theme={null}5201```json managed-settings.json theme={null}

setup.md +5 −23

Details

141 141

142### Alpine Linux 和 musl 型發行版142### Alpine Linux 和 musl 型發行版

143 143

144在 Alpine 和其他 musl/uClibc 型發行版上安裝 Claude Code 需要 `bash` 和 `curl` 用於安裝命令，以及 `libgcc`、`libstdc++` 和 `ripgrep` 用於執行時。Alpine 預設不包含 `bash` 或 `curl`，因此在您安裝它們之前，文件中的安裝命令會失敗並出現 `not found` 錯誤。使用您的發行版套件管理員安裝這些套件，然後設定 `USE_BUILTIN_RIPGREP=0`。144在 Alpine 和其他 musl 型發行版上，[安裝命令](#install-claude-code)需要 `bash` 和 `curl`，而 Claude Code 本身需要 `bash` 或 `zsh`。Alpine 預設不包含 `bash` 或 `curl`，因此在您安裝它們之前，文件中的安裝命令會失敗並出現 `not found` 錯誤。

145 145

146此範例在 Alpine 上安裝所需的套件：146此範例在 Alpine 上安裝所需的套件：

147 147

148```bash theme={null}148```bash theme={null}

149apk add bash curl libgcc libstdc++ ripgrep149apk add bash curl

150```

~~151~~

152在 Alpine 上，`ripgrep` 位於社群儲存庫中。如果 `apk` 報告套件遺失，請將社群儲存庫新增至 `/etc/apk/repositories`，使用您的 Alpine 版本：

~~153~~

154```bash theme={null}

155echo "https://dl-cdn.alpinelinux.org/alpine/v3.22/community" >> /etc/apk/repositories

156```

~~157~~

158執行 `apk update` 以重新整理套件索引，然後重試 `apk add` 命令。

~~159~~

160然後在您的 [`settings.json`](https://code.claude.com/docs/zh-TW/settings-reference#all-settings) 檔案中將 `USE_BUILTIN_RIPGREP` 設定為 `0`：

~~161~~

162```json theme={null}

163{

164 "env": {

165 "USE_BUILTIN_RIPGREP": "0"

166 }

167}

168```150```

169 151

170## 驗證您的安裝152## 驗證您的安裝

443> wget -O /etc/apk/keys/claude-code.rsa.pub \425> wget -O /etc/apk/keys/claude-code.rsa.pub \

444> https://downloads.claude.ai/keys/claude-code.rsa.pub426> https://downloads.claude.ai/keys/claude-code.rsa.pub

445> echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories427> echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories

446> apk add claude-code428> apk add bash claude-code

447> ```429> ```

448>430>

449> 若要切換至 `latest` 通道，移除 `stable` 儲存庫行並新增 `latest` 儲存庫：431> 若要切換至 `latest` 通道，移除 `stable` 儲存庫行並新增 `latest` 儲存庫：

463>445>

464> 如果 `npm --version` 在您的 shell 中列印以 `12` 開頭的版本，請改為依照[修正 npm 12 安裝](https://code.claude.com/docs/zh-TW/troubleshoot-install.md#fix-an-npm-12-install)進行操作。請勿使用 `sudo` 安裝。Claude Code 在自我更新時會以不使用 `sudo` 的方式執行 npm，因此需要 `sudo` 的安裝無法自動更新。446> 如果 `npm --version` 在您的 shell 中列印以 `12` 開頭的版本，請改為依照[修正 npm 12 安裝](https://code.claude.com/docs/zh-TW/troubleshoot-install.md#fix-an-npm-12-install)進行操作。請勿使用 `sudo` 安裝。Claude Code 在自我更新時會以不使用 `sudo` 的方式執行 npm，因此需要 `sudo` 的安裝無法自動更新。

465 447

466您也可以將 Claude Code 安裝為全域 npm 套件。npm 套件需要 [Node.js 22 或更新版本](https://nodejs.org/en/download)。在較舊的 Node.js 版本上，npm 在安裝期間列印 `EBADENGINE` 警告而不是失敗；安裝完成且 `claude` 仍然執行，因為該套件下載不使用您的 Node.js 的原生二進位檔案。448您也可以將 Claude Code 安裝為全域 npm 套件。npm 套件需要 [Node.js 22 或更新版本](https://nodejs.org/en/download)。在較舊的 Node.js 版本上，npm 預設會列印 `EBADENGINE` 警告並完成安裝，而不是失敗。已安裝的 `claude` 仍然可以執行，因為該套件下載的原生二進位檔案在執行時不會使用您的 Node.js。

467 449

468```bash theme={null}450```bash theme={null}

469npm install -g @anthropic-ai/claude-code451npm install -g @anthropic-ai/claude-code@latest

470```452```

471 453

472npm 套件安裝與獨立安裝程式相同的原生二進位檔案。npm 透過每個平台的選擇性依賴項（例如 `@anthropic-ai/claude-code-darwin-arm64`）提取二進位檔案，並透過 postinstall 步驟將其連結到位。已安裝的 `claude` 二進位檔案本身不會呼叫 Node。454npm 套件安裝與獨立安裝程式相同的原生二進位檔案。npm 透過每個平台的選擇性依賴項（例如 `@anthropic-ai/claude-code-darwin-arm64`）提取二進位檔案，並透過 postinstall 步驟將其連結到位。已安裝的 `claude` 二進位檔案本身不會呼叫 Node。

skills.md +5 −1

Details

787 787

788注入命令在技能呈現時永遠不會提示權限。Claude Code 首先根據您的[權限規則](https://code.claude.com/docs/zh-TW/permissions.md)檢查每一個。拒絕規則匹配的命令會中止呼叫，顯示 `Shell command permission check failed for pattern "..."`。788注入命令在技能呈現時永遠不會提示權限。Claude Code 首先根據您的[權限規則](https://code.claude.com/docs/zh-TW/permissions.md)檢查每一個。拒絕規則匹配的命令會中止呼叫，顯示 `Shell command permission check failed for pattern "..."`。

789 789

790在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)之外，當命令的權限檢查返回除允許以外的任何內容時，Claude Code 會以相同的錯誤中止呼叫。這包括通常會詢問您的規則。若要防止不匹配的命令在此處中止，請使用 [`allowed-tools`](#pre-approve-tools-for-a-skill) 預先核准它。如果您的組織將權限規則限制於受管設定，請參閱[僅套用受管權限規則時](#when-only-managed-permission-rules-apply)。拒絕和詢問規則仍會覆寫 `allowed-tools`。請參閱[管理權限](https://code.claude.com/docs/zh-TW/permissions.md#manage-permissions)。790在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)之外，當命令的權限檢查傳回允許以外的任何結果時，Claude Code 會中止呼叫。若要防止未匹配的命令中止，請使用 [`allowed-tools`](#pre-approve-tools-for-a-skill) 預先核准它，但有以下限制：

791

792* **拒絕和詢問規則**：其中任一規則匹配的命令仍會中止。若要找出該規則，請參閱[管理權限](https://code.claude.com/docs/zh-TW/permissions.md#manage-permissions)。

793* **僅限受管的規則**：如果工作階段中的 `/status` 將該 skill 列在 `allowed-tools ignored this session` 之下，請參閱[僅套用受管權限規則時](#when-only-managed-permission-rules-apply)。

794* **未經驗證的 Git 資料夾**：在 `HEAD` 或 `.git` 檔案可能不屬於您的位置，對於包含 `git` 或 Claude Code 無法解析的 Bash 命令，Claude Code 會忽略 `allowed-tools`。如果您信任該資料夾，例如您自己的 bare 儲存庫的 worktree，請在工作階段中使用 [`/permissions`](https://code.claude.com/docs/zh-TW/permissions#manage-permissions) 允許該命令。

791 795

792在自動模式中，原本需要您批准的命令不會中止呼叫。技能會載入一個指示，告訴 Claude 先執行命令，然後 Claude 自己的呼叫會通過[自動模式的常規檢查](https://code.claude.com/docs/zh-TW/permission-modes.md#how-the-classifier-evaluates-actions)。在設定 `agent` 的[分叉技能](#run-skills-in-a-subagent)中，以及在 Claude 沒有[執行注入命令的 shell 工具](#how-injected-commands-run)的工作階段中，呼叫仍會中止。796在自動模式中，原本需要您批准的命令不會中止呼叫。技能會載入一個指示，告訴 Claude 先執行命令，然後 Claude 自己的呼叫會通過[自動模式的常規檢查](https://code.claude.com/docs/zh-TW/permission-modes.md#how-the-classifier-evaluates-actions)。在設定 `agent` 的[分叉技能](#run-skills-in-a-subagent)中，以及在 Claude 沒有[執行注入命令的 shell 工具](#how-injected-commands-run)的工作階段中，呼叫仍會中止。

793 797

statusline.md +0 −40

Details

1085echo "$dirname [$model]"1085echo "$dirname [$model]"

1086```1086```

1087 1087

1088## 子代理狀態列

~~1089~~

1090`subagentStatusLine` 設定為[子代理](https://code.claude.com/docs/zh-TW/sub-agents.md)面板中顯示的每個子代理呈現自訂行主體。使用它來用您自己的格式化取代預設的 `name · description · token count` 行。

~~1091~~

1092```json theme={null}

1093{

1094 "subagentStatusLine": {

1095 "type": "command",

1096 "command": "~/.claude/subagent-statusline.sh"

1097 }

1098}

1099```

~~1100~~

1101命令在每個重新整理刻度上執行一次，並以單個 JSON 物件的形式在 stdin 上接收所有可見的 subagent 列。輸入包括[基本 hook 欄位](https://code.claude.com/docs/zh-TW/hooks.md#common-input-fields)、包含可用列寬度的 `columns` 欄位，以及每列一個項目的 `tasks` 陣列，詳見[任務欄位](#task-fields)。

~~1102~~

1103將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。

~~1104~~

1105適用於 `statusLine` 的相同信任、`disableAllHooks` 和 [`allowManagedHooksOnly`](https://code.claude.com/docs/zh-TW/settings-reference#allowmanagedhooksonly) 閘門也適用於此。外掛程式可以在其 [`settings.json`](https://code.claude.com/docs/zh-TW/plugins/manifest-reference#standard-layout) 中提供預設 `subagentStatusLine`，但與 hooks 不同，即使外掛程式在受管設定 `enabledPlugins` 中被強制啟用，外掛程式值也不會在 `allowManagedHooksOnly` 下執行。

~~1106~~

1107### 任務欄位

~~1108~~

1109`tasks` 陣列中的每個項目以下列欄位描述一個 subagent 列。標示為選用的欄位在沒有值時會被省略，因此請在指令碼中處理其不存在的情況。

~~1110~~

1111| 欄位 | 類型 | 說明 |

1112| :- | :- | :- |

1113| `id` | string | 任務的識別碼。在您為此列寫回的行中將其作為 `id` 回傳 |

1114| `name` | string，選用 | subagent 被[稱呼時使用](https://code.claude.com/docs/zh-TW/sub-agents.md#subagent-names)的名稱（如果有的話） |

1115| `type` | string | 任務的種類：`local_agent` |

1116| `agentType` | string | 任務執行時的 subagent 類型，例如內建的 [`Explore`](https://code.claude.com/docs/zh-TW/sub-agents#built-in-subagents) 或自訂的 `code-reviewer`。其值與 hook 接收的 [`agent_type`](https://code.claude.com/docs/zh-TW/hooks#subagentstart) 相同。需要 Claude Code v2.1.293 或更新版本 |

1117| `status` | string | 任務的狀態，例如 `running`、`completed`、`failed` 或 `killed` |

1118| `description` | string | 任務的簡短說明，例如 Claude 產生 subagent 時所提供的說明 |

1119| `label` | string | 當 Claude Code 有任務的簡短進度摘要時為該摘要，否則與 `description` 的文字相同 |

1120| `startTime` | number | 任務開始的時間，以自 Unix epoch 以來的毫秒數表示 |

1121| `model` | string，選用 | 任務執行所在的已解析模型 ID。在模型解析完成前會被省略 |

1122| `effort` | string 或 number，選用 | 在 subagent 的[定義 frontmatter](https://code.claude.com/docs/zh-TW/sub-agents.md#supported-frontmatter-fields) 或個別調用上為其設定的推理 effort：`low`、`medium`、`high`、`xhigh`、`max` 或數值 token 預算。這是設定的值，當模型不支援該等級時，Claude Code 實際套用的 effort 可能會有所不同。未設定 effort 時會被省略 |

1123| `contextWindowSize` | number，選用 | `model` 的上下文視窗（以 token 計），計算方式與主狀態列的 [`context_window.context_window_size`](#context-window-fields) 相同，因此您可以從 `tokenCount` 呈現每列的百分比。當 `model` 被省略時也會被省略 |

1124| `tokenCount` | number | subagent 的累計 token 數，即預設列所顯示的數字 |

1125| `tokenSamples` | array of numbers | 最多最近 16 次的 `tokenCount` 讀數，每個重新整理刻度一筆，由舊到新排列並以目前的讀數結尾 |

1126| `cwd` | string | subagent 的工作目錄：當其在自己的目錄中執行時（例如隔離的 worktree）為該目錄，否則為工作階段的工作目錄 |

~~1127~~

1128## 提示1088## 提示

1129 1089

1130* **使用模擬輸入測試**：`echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh`1090* **使用模擬輸入測試**：`echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh`

terminal-config.md +1 −1

Details

26 26

27| 終端機 | Shift+Enter 用於換行 |27| 終端機 | Shift+Enter 用於換行 |

28| :- | :- |28| :- | :- |

~~29| Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal、Windows Terminal | 無需設定即可使用 |~~29| Ghostty、Kitty、iTerm2、WezTerm、Warp、Windows Terminal | 無需設定即可使用 |

30| 支援 kitty 鍵盤協議的其他終端機，例如 foot 和 Alacritty 0.16 或更新版本 | 無需設定即可使用。需要 Claude Code v2.1.269 或更新版本 |30| 支援 kitty 鍵盤協議的其他終端機，例如 foot 和 Alacritty 0.16 或更新版本 | 無需設定即可使用。需要 Claude Code v2.1.269 或更新版本 |

31| VS Code、Cursor、Devin Desktop、Alacritty 0.16 之前的版本、Zed | 執行一次 `/terminal-setup` |31| VS Code、Cursor、Devin Desktop、Alacritty 0.16 之前的版本、Zed | 執行一次 `/terminal-setup` |

32| gnome-terminal、JetBrains IDE（例如 PyCharm 和 Android Studio） | 不可用；使用 Ctrl+J 或 `\` 然後 Enter |32| gnome-terminal、JetBrains IDE（例如 PyCharm 和 Android Studio） | 不可用；使用 Ctrl+J 或 `\` 然後 Enter |

third-party-integrations.md +4 −0

Details

173 173

174若要限制受管機器可以使用的部署選項，請在受管設定中設定 [`allowedProviders`](https://code.claude.com/docs/zh-TW/settings-reference#allowedproviders)。例如，`["bedrock"]` 只允許 Amazon Bedrock，不允許其他；同時啟用 Mantle 端點的 Bedrock 機隊也會列出 `"mantle"`。該項目說明哪些端點變數也需要受管 `env` 固定。需要 Claude Code v2.1.285 或更新版本。174若要限制受管機器可以使用的部署選項，請在受管設定中設定 [`allowedProviders`](https://code.claude.com/docs/zh-TW/settings-reference#allowedproviders)。例如，`["bedrock"]` 只允許 Amazon Bedrock，不允許其他；同時啟用 Mantle 端點的 Bedrock 機隊也會列出 `"mantle"`。該項目說明哪些端點變數也需要受管 `env` 固定。需要 Claude Code v2.1.285 或更新版本。

175 175

176> [!NOTE]

177>

178> 當 Desktop 已登入 claude.ai 時，使用者機器上的 Cowork 工作階段會被視為 [`"anthropic"`](https://code.claude.com/docs/zh-TW/settings-reference#allowedproviders)。如果您在 MDM 原則或受管設定檔中未將其列入此清單，該工作階段將被拒絕。若將其列入，直接傳送至 Anthropic 的工作階段也會通過此清單。

179

176### 使用 MCP 進行整合180### 使用 MCP 進行整合

177 181

178MCP 是為 Claude Code 提供更多資訊的絕佳方式，例如連接到票證管理系統或錯誤日誌。由一個中央團隊設定 MCP 伺服器，並將 `.mcp.json` 設定檔簽入程式碼庫，以便所有使用者受益。[瞭解更多](https://code.claude.com/docs/zh-TW/mcp.md)。182MCP 是為 Claude Code 提供更多資訊的絕佳方式，例如連接到票證管理系統或錯誤日誌。由一個中央團隊設定 MCP 伺服器，並將 `.mcp.json` 設定檔簽入程式碼庫，以便所有使用者受益。[瞭解更多](https://code.claude.com/docs/zh-TW/mcp.md)。

tools-reference.md +1 −3

Details

127 127

128Claude 使用 `AskUserQuestion` 在需要決策或澄清時向您提出多選題。透過選擇選項來回答，或透過 `Other` 列或備註欄位輸入您自己的文字。128Claude 使用 `AskUserQuestion` 在需要決策或澄清時向您提出多選題。透過選擇選項來回答，或透過 `Other` 列或備註欄位輸入您自己的文字。

129 129

130當您透過輸入自己的文字來回答時，Claude Code 會以中立的措辭轉達答案，以便 Claude 遵循您所寫的內容，包括等待或先解釋的請求。

~~131~~

132### 問題自動繼續逾時130### 問題自動繼續逾時

133 131

134問題會保持開啟，直到您回答為止。如果您想讓未回答的問題最終關閉並讓 Claude 在沒有您的情況下繼續，請在您的使用者 `settings.json` 中或從 `/config` 中的 **Question auto-continue timeout** 列將 [`askUserQuestionTimeout`](https://code.claude.com/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定為 `60s`、`5m` 或 `10m`。132問題會保持開啟，直到您回答為止。如果您想讓未回答的問題最終關閉並讓 Claude 在沒有您的情況下繼續，請在您的使用者 `settings.json` 中或從 `/config` 中的 **Question auto-continue timeout** 列將 [`askUserQuestionTimeout`](https://code.claude.com/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定為 `60s`、`5m` 或 `10m`。

525 523

526## Read 工具行為524## Read 工具行為

527 525

528Read 工具接受檔案路徑並傳回包含行號的內容。Claude 被指示始終傳遞絕對路徑。526Read 工具接受檔案路徑並傳回包含行號的內容。

529 527

530讀取空檔案會傳回通知，說明檔案存在但內容為空，而超過最後一行的 `offset` 會傳回通知，提供檔案的行數。528讀取空檔案會傳回通知，說明檔案存在但內容為空，而超過最後一行的 `offset` 會傳回通知，提供檔案的行數。

531 529

troubleshoot-install.md +8 −14

Details

388> Get-Command claude | Select-Object Source388> Get-Command claude | Select-Object Source

389> ```389> ```

390 390

391在 Linux 上，檢查遺失的共用程式庫。如果 `ldd` 顯示遺失的程式庫，您可能需要安裝系統套件。在 Alpine Linux 和其他 musl 型發行版上，請參閱 [Alpine Linux 設定](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)。391在 Linux 上，檢查遺失的共用程式庫。如果 `ldd` 顯示遺失的程式庫，您可能需要安裝系統套件。在 Alpine Linux 和其他 musl 型發行版上，請參閱 [Linux musl 或 glibc 二進位檔不符](#linux-musl-or-glibc-binary-mismatch)。

392 392

393```bash theme={null}393```bash theme={null}

394ldd "$(command -v claude)" | grep "not found"394ldd "$(command -v claude)" | grep "not found"

906 906

907### Linux musl 或 glibc 二進位不相符907### Linux musl 或 glibc 二進位不相符

908 908

909如果在安裝後看到有關遺失共用程式庫的錯誤，如 `libstdc++.so.6` 或 `libgcc_s.so.1`，安裝程式可能為您的系統下載了錯誤的二進位變體。909如果在安裝後看到有關遺失共用程式庫的錯誤，如 `ld-linux-x86-64.so.2` 或 `ld-linux-aarch64.so.1`，安裝程式可能為您的系統下載了錯誤的二進位變體。

910 910

911```text theme={null}911```text theme={null}

912Error loading shared library libstdc++.so.6: No such file or directory912Error loading shared library ld-linux-x86-64.so.2: No such file or directory

913```913```

914 914

915這可能發生在已安裝 musl 交叉編譯套件的基於 glibc 的系統上，導致安裝程式將系統誤檢測為 musl。

~~916~~

917**解決方案：**915**解決方案：**

918 916

9191. **檢查您的系統使用哪個 libc**：9171. **檢查您的系統使用哪個 libc**：

924 922

9252. **如果您在 glibc 上但得到了 musl 二進位檔**，移除安裝並重新安裝。您也可以使用 `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json` 上的清單手動下載正確的二進位檔。使用 `ldd --version` 和 `ls /lib/libc.musl*` 的輸出提交 [GitHub 問題](https://github.com/anthropics/claude-code/issues)。9232. **如果您在 glibc 上但得到了 musl 二進位檔**，移除安裝並重新安裝。您也可以使用 `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json` 上的清單手動下載正確的二進位檔。使用 `ldd --version` 和 `ls /lib/libc.musl*` 的輸出提交 [GitHub 問題](https://github.com/anthropics/claude-code/issues)。

926 924

9273. **如果您實際上在 musl 上**，例如 Alpine Linux，請安裝所需的套件：9253. **如果您在 musl 上但得到了 glibc 二進位檔**，請[移除安裝](https://code.claude.com/docs/zh-TW/setup.md#uninstall-claude-code)。在 Alpine Linux 上，請先安裝 [Alpine Linux 設定](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)中列出的套件。然後執行[安裝命令](https://code.claude.com/docs/zh-TW/setup.md#install-claude-code)，它會安裝 musl 二進位檔。

928 ```bash theme={null}

929 apk add libgcc libstdc++ ripgrep

930 ```

931 在 Alpine 上，`ripgrep` 在社群儲存庫中。如果 `apk` 報告套件遺失，請參閱 [Alpine Linux 設定](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)。

932 926

933### `Illegal instruction`927### `Illegal instruction`

934 928

1001 995

1002如果您在 WSL 內使用 `npm install -g` 安裝了 Claude Code，這些問題適用。如果您使用了[原生安裝程式](https://code.claude.com/docs/zh-TW/setup.md)，請跳過此部分。在 npm 12 上，請依照[修正 npm 12 安裝](#fix-an-npm-12-install)中的說明進行安裝。996如果您在 WSL 內使用 `npm install -g` 安裝了 Claude Code，這些問題適用。如果您使用了[原生安裝程式](https://code.claude.com/docs/zh-TW/setup.md)，請跳過此部分。在 npm 12 上，請依照[修正 npm 12 安裝](#fix-an-npm-12-install)中的說明進行安裝。

1003 997

1004**OS 或平台偵測問題。** 如果 npm 在安裝期間報告平台不相符，WSL 可能正在使用 Windows `npm`。首先執行 `npm config set os linux`，然後使用 `npm install -g @anthropic-ai/claude-code --force` 安裝。不要使用 `sudo`。998**OS 或平台偵測問題。** 如果 npm 在安裝期間報告平台不相符，請先執行 `npm config set os linux`，然後使用 `npm install -g @anthropic-ai/claude-code@latest --force` 安裝。不要使用 `sudo`。

1005 999

1006**執行 `claude` 時的 `exec: node: not found`。** 您的 WSL 環境可能使用 Windows 安裝的 Node.js。使用 `which npm` 和 `which node` 確認：以 `/mnt/c/` 開頭的路徑是 Windows 二進位檔，而 Linux 路徑以 `/usr/` 開頭。要修復此問題，請透過您的 Linux 發行版的套件管理器或透過 [`nvm`](https://github.com/nvm-sh/nvm) 安裝 Node。1000**執行 `claude` 時的 `exec: node: not found`。** 您的 WSL 環境可能使用 Windows 安裝的 Node.js。使用 `which npm` 和 `which node` 確認：以 `/mnt/c/` 開頭的路徑是 Windows 二進位檔，而 Linux 路徑以 `/usr/` 開頭。要修復此問題，請透過您的 Linux 發行版的套件管理器或透過 [`nvm`](https://github.com/nvm-sh/nvm) 安裝 Node。

1007 1001

1088 3. 重新安裝：1082 3. 重新安裝：

1089 1083

1090 ```bash theme={null}1084 ```bash theme={null}

1091 npm install -g @anthropic-ai/claude-code1085 npm install -g @anthropic-ai/claude-code@latest

1092 ```1086 ```

1093 1087

1094 如果此步驟或步驟 1 以 `EACCES` 失敗，請切換到原生安裝程式，而不是使用 `sudo` 重新執行。Claude Code 自行更新時會在不使用 `sudo` 的情況下執行 npm，因此自動更新也會以相同方式失敗。1088 如果此步驟或步驟 1 以 `EACCES` 失敗，請切換到原生安裝程式，而不是使用 `sudo` 重新執行。Claude Code 自行更新時會在不使用 `sudo` 的情況下執行 npm，因此自動更新也會以相同方式失敗。

1099 1093

1100### npm `ENOTEMPTY` 錯誤在更新或重新安裝期間1094### npm `ENOTEMPTY` 錯誤在更新或重新安裝期間

1101 1095

1102當您在現有安裝上執行 `npm install -g @anthropic-ai/claude-code` 時，npm 在移動舊套件目錄時可能失敗：1096當您在現有安裝上執行 `npm install -g @anthropic-ai/claude-code@latest` 時，npm 在移動舊套件目錄時可能失敗：

1103 1097

1104```text theme={null}1098```text theme={null}

1105npm error code ENOTEMPTY1099npm error code ENOTEMPTY

1133然後重新安裝。在 npm 12 上，請遵循[修正 npm 12 安裝](#fix-an-npm-12-install)。否則，請執行：1127然後重新安裝。在 npm 12 上，請遵循[修正 npm 12 安裝](#fix-an-npm-12-install)。否則，請執行：

1134 1128

1135```bash theme={null}1129```bash theme={null}

1136npm install -g @anthropic-ai/claude-code1130npm install -g @anthropic-ai/claude-code@latest

1137```1131```

1138 1132

1139使用 `claude --version` 確認，它列印版本號，例如 `2.1.211 (Claude Code)`。1133使用 `claude --version` 確認，它列印版本號，例如 `2.1.211 (Claude Code)`。

troubleshooting.md +1 −1

Details

152> apk add ripgrep152> apk add ripgrep

153> ```153> ```

154>154>

155> `ripgrep` 在 Alpine 的社群儲存庫中。如果 `apk` 報告套件遺失，請參閱 [Alpine Linux 設定](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)。155> `ripgrep` 在 Alpine 的社群儲存庫中。

156 156

157> [tab] Arch157> [tab] Arch

158>158>

vs-code.md +10 −0

Details

202 您既有的思考區塊會保持空白。在重新載入後的回應中，點擊區塊或按下 `Ctrl+O` 即可將其全部展開。202 您既有的思考區塊會保持空白。在重新載入後的回應中，點擊區塊或按下 `Ctrl+O` 即可將其全部展開。

203* **多行輸入**：按下 `Shift+Enter` 即可新增一行而不傳送。這在問題對話方塊的「Other」自由文字輸入中也適用。203* **多行輸入**：按下 `Shift+Enter` 即可新增一行而不傳送。這在問題對話方塊的「Other」自由文字輸入中也適用。

204 204

205### 使用或關閉建議的提示詞

206

207Claude 回覆後，面板可能會在空白的提示詞輸入框中，以灰色斜體文字顯示建議的下一個提示詞。每個建議都會使用一個[簡短的背景請求](https://code.claude.com/docs/zh-TW/interactive-mode.md#prompt-suggestions)，該請求會計入您方案的用量上限或 API 成本。

208

209* **使用建議**：按下 `Tab` 將其轉換為可編輯的文字，然後傳送。在接受建議之前按下 `Enter` 不會傳送該建議。

210* **撰寫您自己的提示詞**：開始輸入，建議即會隱藏。

211

212若要關閉建議，請在 `~/.claude/settings.json` 中將 [`promptSuggestionEnabled`](https://code.claude.com/docs/zh-TW/settings-reference#promptsuggestionenabled) 設為 `false`。您在新對話中將不會再看到建議；在已開啟的對話中，則是在您從命令選擇區執行 **Developer: Reload Window** 後不會再看到。如果您已將 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `true`，請在您設定它的位置將其改為 `false`，否則您會持續看到建議。

213

205### 參照檔案和資料夾214### 參照檔案和資料夾

206 215

207使用 @ 提及為 Claude 提供特定檔案或資料夾的上下文。當您輸入 `@` 後接檔案或資料夾名稱時，Claude 會讀取該內容，並可以回答相關問題或對其進行變更。Claude Code 支援模糊比對，因此您可以輸入部分名稱來找到所需內容：216使用 @ 提及為 Claude 提供特定檔案或資料夾的上下文。當您輸入 `@` 後接檔案或資料夾名稱時，Claude 會讀取該內容，並可以回答相關問題或對其進行變更。Claude Code 支援模糊比對，因此您可以輸入部分名稱來找到所需內容：

936| `SSL certificate verification failed` 或 `Self-signed certificate detected` | [SSL 憑證錯誤](https://code.claude.com/docs/zh-TW/errors.md#ssl-certificate-errors) |945| `SSL certificate verification failed` 或 `Self-signed certificate detected` | [SSL 憑證錯誤](https://code.claude.com/docs/zh-TW/errors.md#ssl-certificate-errors) |

937| `Dictation error: WebSocket error:` 後面接著憑證錯誤（例如 `unable to get local issuer certificate`），或 Web 分頁上出現 `Remote server is not connected` | [聽寫或 Web 分頁在 TLS 檢查代理伺服器後方失敗](#dictation-or-the-web-tab-fails-behind-a-tls-inspecting-proxy) |946| `Dictation error: WebSocket error:` 後面接著憑證錯誤（例如 `unable to get local issuer certificate`），或 Web 分頁上出現 `Remote server is not connected` | [聽寫或 Web 分頁在 TLS 檢查代理伺服器後方失敗](#dictation-or-the-web-tab-fails-behind-a-tls-inspecting-proxy) |

938| `Claude Code process exited with code 1` 或其他代碼 | [Claude Code process exited with code N](https://code.claude.com/docs/zh-TW/errors.md#claude-code-process-exited-with-code-n) |947| `Claude Code process exited with code 1` 或其他代碼 | [Claude Code process exited with code N](https://code.claude.com/docs/zh-TW/errors.md#claude-code-process-exited-with-code-n) |

948| `Claude Code did not finish starting` 或 `Subprocess initialization did not complete within 60000ms` | [Subprocess initialization did not complete within 60000ms](https://code.claude.com/docs/zh-TW/errors.md#subprocess-initialization-did-not-complete-within-60000ms) |

939| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](https://code.claude.com/docs/zh-TW/errors.md#could-not-locate-the-claude-cli-on-path) |949| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](https://code.claude.com/docs/zh-TW/errors.md#could-not-locate-the-claude-cli-on-path) |

940| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](https://code.claude.com/docs/zh-TW/errors.md#the-connection-to-claude-code-ended-before-this-message-completed) |950| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](https://code.claude.com/docs/zh-TW/errors.md#the-connection-to-claude-code-ended-before-this-message-completed) |

941| `The Claude Code program for this computer, the <build> build, could not be found` | [The Claude Code program for this computer could not be found](https://code.claude.com/docs/zh-TW/errors.md#the-claude-code-program-for-this-computer-could-not-be-found) |951| `The Claude Code program for this computer, the <build> build, could not be found` | [The Claude Code program for this computer could not be found](https://code.claude.com/docs/zh-TW/errors.md#the-claude-code-program-for-this-computer-could-not-be-found) |

workflows.md +0 −2

Details

75| :- | :- |75| :- | :- |

76| `/deep-research <question>` | 在多個角度上展開網路搜尋問題，獲取並交叉檢查它找到的來源，對每項聲明進行投票，並返回引用的報告，其中未通過交叉檢查的聲明已被篩選出去。需要 [WebSearch 工具](https://code.claude.com/docs/zh-TW/tools-reference.md#websearch-tool-behavior)可用 |76| `/deep-research <question>` | 在多個角度上展開網路搜尋問題，獲取並交叉檢查它找到的來源，對每項聲明進行投票，並返回引用的報告，其中未通過交叉檢查的聲明已被篩選出去。需要 [WebSearch 工具](https://code.claude.com/docs/zh-TW/tools-reference.md#websearch-tool-behavior)可用 |

77 77

~~78`/deep-research` 僅在您叫用時執行。~~

80[您自己儲存的工作流程](#save-the-workflow-for-reuse)以相同方式成為命令，並在 `/` 自動完成中與捆綁的命令一起出現。78[您自己儲存的工作流程](#save-the-workflow-for-reuse)以相同方式成為命令，並在 `/` 自動完成中與捆綁的命令一起出現。

81 79

82### 監視執行80### 監視執行

Documentation 2026-11-12 23:02 UTC to 2026-11-13 23:02 UTC