Documentation — Spybara

agent-sdk/modifying-system-prompts.md +2 −2

Details

126 126

127輸出樣式是一個 markdown 檔案，其 [frontmatter](/docs/zh-TW/output-styles#frontmatter) 中有中繼資料，後面跟著提示詞內容。將其儲存到 `~/.claude/output-styles/` 以獲得在每個專案中可用的使用者級樣式，或儲存到您的儲存庫中的 `.claude/output-styles/` 以獲得可以提交並與您的團隊共享的專案級樣式。127輸出樣式是一個 markdown 檔案，其 [frontmatter](/docs/zh-TW/output-styles#frontmatter) 中有中繼資料，後面跟著提示詞內容。將其儲存到 `~/.claude/output-styles/` 以獲得在每個專案中可用的使用者級樣式，或儲存到您的儲存庫中的 `.claude/output-styles/` 以獲得可以提交並與您的團隊共享的專案級樣式。

128 128

129自訂輸出樣式會省略 `claude_code` 預設值的軟體工程指令，並使用您自己的指令。要保留它們並在其上分層您的指令，請在 frontmatter 中設定 `keep-coding-instructions: true`。這些指令僅在 Claude Code 的完整系統提示詞中，因此該設定在較短系統提示詞的會話中無效，您可以使用 [`CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT`](/docs/zh-TW/env-vars#variables) 來開啟或關閉。當您的代理程式仍在進行軟體工程工作時保留它們。當您完全替換角色時省略它們。129自訂輸出風格會省略 `claude_code` 預設值的軟體工程指令，並使用您自己的指令。要保留它們並在其上分層您的指令，請在 frontmatter 中設定 `keep-coding-instructions: true`。這些指令僅存在於 Claude Code 的完整系統提示詞中，因此該設定在使用較短系統提示詞的工作階段中無效；將 [`CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT`](/docs/zh-TW/env-vars#variables) 設定為 `0` 即可在任何模型上選用完整提示詞。當您的 agent 仍在進行軟體工程工作時保留它們。當您完全替換角色時省略它們。

130 130

131下面的範例定義了程式碼審查角色，該角色保留編碼指令，因為審查程式碼仍然受益於 Claude Code 的安全性和程式碼品質指導。將其儲存為 `~/.claude/output-styles/code-reviewer.md` 以在專案中提供：131下面的範例定義了程式碼審查角色，該角色保留編碼指令，因為審查程式碼仍然受益於 Claude Code 的安全性和程式碼品質指導。將其儲存為 `~/.claude/output-styles/code-reviewer.md` 以在專案中提供：

132 132

548| **預設工具** | 保留 | 保留 | 保留 | 遺失（除非包含） |548| **預設工具** | 保留 | 保留 | 保留 | 遺失（除非包含） |

549| **內建安全** | 維持 | 維持 | 維持 | 必須新增 |549| **內建安全** | 維持 | 維持 | 維持 | 必須新增 |

550| **自訂程度** | 僅新增 | 替換或擴展預設 | 僅新增 | 完全控制 |550| **自訂程度** | 僅新增 | 新增；可省略程式設計指示 | 僅新增 | 完全控制 |

553 553

agent-sdk/python.md +8 −7

Details

2783```python theme={null}2783```python theme={null}

2784{2784{

2785 "description": str, # 任務的簡短描述（3-5 個單詞）2785 "description": str, # 任務的簡短描述（3-5 個單詞）

2786 "prompt": str, # 代理要執行的任務2786 "prompt": str, # agent 要執行的任務

2787 "subagent_type": str | None, # 要使用的專門代理類型2787 "subagent_type": str | None, # 要使用的專門 agent 類型

2790 "name": str | None, # 生成的代理的名稱2790 "run_in_background": bool | None, # agent 預設在背景執行；設定為 False 以同步執行

2791 "name": str | None, # 生成的 agent 的名稱

2791 "team_name": str | None, # 已棄用；被忽略2792 "team_name": str | None, # 已棄用；被忽略

2793 "isolation": "worktree" | "remote" | None, # 代理變更的隔離模式2794 "isolation": "worktree" | "remote" | None, # agent 變更的隔離模式

2794}2795}

2795```2796```

2796 2797

agent-sdk/typescript.md +64 −54

Details

1756* `ttft_stream_ms`：直到第一個 `message_start` 串流事件（即回應串流開啟時）的時間（毫秒）。低於 `ttft_ms`；兩者之間的差距是串流第一個訊息所花費的時間。僅在成功分支上存在。1756* `ttft_stream_ms`：直到第一個 `message_start` 串流事件（即回應串流開啟時）的時間（毫秒）。低於 `ttft_ms`；兩者之間的差距是串流第一個訊息所花費的時間。僅在成功分支上存在。

1757* `user_message_uuid`：此回合所回答的、您傳送之訊息的 `uuid`。請參閱 [`user_message_uuid`](#user_message_uuid) 以了解哪些結果會攜帶它。1757* `user_message_uuid`：此回合所回答的、您傳送之訊息的 `uuid`。請參閱 [`user_message_uuid`](#user_message_uuid) 以了解哪些結果會攜帶它。

1758* `user_message_uuids`：Claude Code 在此回合中回答的、您傳送之每則訊息的 `uuid`。請參閱 [`user_message_uuids`](#user_message_uuids)。1758* `user_message_uuids`：Claude Code 在此回合中回答的、您傳送之每則訊息的 `uuid`。請參閱 [`user_message_uuids`](#user_message_uuids)。

1759* `resume_reason`：Claude Code 在重新啟動中斷此回合後重新執行此回合的原因。在兩個分支上都存在，且僅在此類重新執行上出現。請參閱 [`resume_reason`](#resume_reason)。1759* `resume_reason`：Claude Code 在重新啟動中斷此回合後重新執行它的原因。存在於兩個分支。請參閱 [`resume_reason`](#resume_reason)。

1760* `local_command`：回合所分派之命令的名稱，出現在由命令完成、未進入 agent 迴圈之回合的成功結果上，例如 `/compact`。名稱會轉為小寫字母和底線，因此 `/reload-plugins` 回報為 `reload_plugins`。由 MCP 伺服器提供的命令以及內建的 `/mcp` 回報為 `mcp`。您自行定義的命令回報為 `custom`。引數永遠不會包含在內。在每個進入 agent 迴圈的回合上，以及在未執行任何命令的傳送上，此欄位不存在。需要 Agent SDK v0.3.268 或更新版本。1760* `local_command`：回合所分派之命令的名稱，出現在由命令完成、未進入 agent 迴圈之回合的成功結果上，例如 `/compact`。名稱會轉為小寫字母和底線，因此 `/reload-plugins` 回報為 `reload_plugins`。由 MCP 伺服器提供的命令以及內建的 `/mcp` 回報為 `mcp`。您自行定義的命令回報為 `custom`。引數永遠不會包含在內。在每個進入 agent 迴圈的回合上，以及在未執行任何命令的傳送上，此欄位不存在。需要 Agent SDK v0.3.268 或更新版本。

1761* `request_sent_wall_ms`：Claude Code 分派 API 請求時的紀元毫秒，用於與伺服器端時間戳記進行對照。僅與 [`user_message_uuid`](#user_message_uuid) 一起存在，出現在 `is_error` 為 false、且其回合傳送了 API 請求的成功結果上。1761* `request_sent_wall_ms`：Claude Code 分派 API 請求時的紀元毫秒，用於與伺服器端時間戳記進行對照。僅與 [`user_message_uuid`](#user_message_uuid) 一起存在，出現在 `is_error` 為 false、且其回合傳送了 API 請求的成功結果上。

1762* `first_content_frame_ms`：直到第一個 `content_block_start` 或 `content_block_delta` 串流事件的時間（毫秒），思考區塊也計為內容。僅在成功分支上、`is_error` 為 false 時存在。需要 Agent SDK v0.3.260 或更新版本。1762* `first_content_frame_ms`：直到第一個 `content_block_start` 或 `content_block_delta` 串流事件的時間（毫秒），思考區塊也計為內容。僅在成功分支上、`is_error` 為 false 時存在。需要 Agent SDK v0.3.260 或更新版本。

1845* **重新執行的結果**：在成功和錯誤分支上皆然，無論結果是否攜帶 `user_message_uuid`。1845* **重新執行的結果**：在成功和錯誤分支上皆然，無論結果是否攜帶 `user_message_uuid`。

1846* **重新執行的回覆框架**：即攜帶 [`user_message_uuid`](#user_message_uuid) 的那些框架。1846* **重新執行的回覆框架**：即攜帶 [`user_message_uuid`](#user_message_uuid) 的那些框架。

1847 1847

1848其值是一個簡短的小寫 token，指名回合重新執行的原因，例如 `interrupted_turn`。在所有其他回合上，此欄位不存在。1848其值是一個簡短的小寫 token，指名回合被重新執行的原因，例如 `interrupted_turn`。

1849 1849

1850<h4 id="queued_turn_count">1850<h4 id="queued_turn_count">

1851 `queued_turn_count`1851 `queued_turn_count`

1887 | "worktree_resume_refused"1887 | "worktree_resume_refused"

1888 | "worktree_unverified"1888 | "worktree_unverified"

1889 | "cli_version_too_old"1889 | "cli_version_too_old"

1890 | "bypass_root";1890 | "bypass_root"

1891 | "org_config_required_unavailable"

1892 | "org_config_refused";

1891```1893```

1892 1894

1893每個值指名一種拒絕：1895每個值指名一種拒絕：

1916| `org_config_required_unavailable` | 工作階段在啟動前需要組織的原則和受管設定，但無法載入它們，例如因為網路失敗或 Anthropic 伺服器錯誤。需要 Agent SDK v0.3.293 或更新版本 |

1917| `org_config_refused` | Anthropic 拒絕為此登入提供組織的原則和受管設定，例如因為登入已過期或已被撤銷，或組織不允許此帳戶使用 Claude Code。需要 Agent SDK v0.3.293 或更新版本 |

1914 1918

1915<h3 id="sdksystemmessage">1919<h3 id="sdksystemmessage">

1916 `SDKSystemMessage`1920 `SDKSystemMessage`

3125 工具輸入類型3129 工具輸入類型

3126</h2>3130</h2>

3127 3131

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

3129 3133

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

3131 `ToolInputSchemas`3135 `ToolInputSchemas`

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

3183 3187

3184<Note>3188<Note>

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

3186</Note>3190</Note>

3187 3191

3188```typescript theme={null}3192```typescript theme={null}

3199};3203};

3200```3204```

3201 3205

3202啟動新代理以自主處理複雜的多步驟任務。3206啟動新 agent 以自主處理複雜的多步驟任務。

3203 3207

3204<h3 id="askuserquestion">3208<h3 id="askuserquestion">

3205 AskUserQuestion3209 AskUserQuestion

3239};3243};

3240```3244```

3241 3245

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

3243 3247

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

3245 Monitor3249 Monitor

3263 3267

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

3265 3269

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

3267 3271

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

3269 3273

3307};3311};

3308```3312```

3309 3313

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

3311 3315

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

3313 3317

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

3315 Write3319 Write

3382};3386};

3383```3387```

3384 3388

3385按 ID 停止執行中的背景任務或 shell。自 v2.1.198 起，`task_id` 也接受代理團隊隊友或按代理 ID 或名稱的具名背景代理。3389按 ID 停止執行中的背景任務或 shell。自 v2.1.198 起，`task_id` 也接受 agent team 隊友，或依 agent ID 或名稱指定的具名背景 agent。

3386 3390

3387<h3 id="notebookedit">3391<h3 id="notebookedit">

3388 NotebookEdit3392 NotebookEdit

3451};3455};

3452```3456```

3453 3457

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

3455 3459

3456| 欄位 | 類型 | 描述 |3460| 欄位 | 類型 | 描述 |

3457| - | - | - |3461| - | - | - |

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

3579};3583};

3580```3584```

3581 3585

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

3583 3587

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

3585 ListMcpResources3589 ListMcpResources

3650type EnterPlanModeInput = {};3654type EnterPlanModeInput = {};

3651```3655```

3652 3656

3653進入 Plan Mode，Claude 在其中研究並在進行變更前提出計畫。3657進入 plan mode，Claude 在其中研究並在進行變更前提出計畫。

3654 3658

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

3656 CronCreate3660 CronCreate

3667};3671};

3668```3672```

3669 3673

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

3671 3675

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

3673 3677

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

3675 CronDelete3679 CronDelete

3713};3717};

3714```3718```

3715 3719

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

3717 3721

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

3719 RemoteTrigger3723 RemoteTrigger

3741};3745};

3742```3746```

3743 3747

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

3745 3749

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

3747 3751

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

3749 3753

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

3751 3755

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

3753 PushNotification3757 PushNotification

3768 REPL3772 REPL

3769</h3>3773</h3>

3770 3774

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

3772 3776

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

3774 ReportFindings3778 ReportFindings

3829};3833};

3830```3834```

3831 3835

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

3833 3837

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

3835* `favicon`：已棄用，Claude 省略它。3839* `favicon`：已棄用，Claude 省略它。

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

3837* `url`：目標是現有成品以就地更新，而不是建立新的。3841* `url`：目標是現有 artifact 以就地更新，而不是建立新的。

3838 3842

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

3840 3844

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

3842 3846

3843* `capabilities`：已發佈頁面使用的執行時功能，按功能名稱鍵入，例如[頁面可能呼叫的連接器](/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors)。成品服務驗證宣告並拒絕命名帳戶無法使用的功能或給予一個無效設定的發佈。傳遞 `{}` 以清除儲存的宣告，在重新部署時省略欄位以保留它。需要 Agent SDK v0.3.235 或更新版本。3847`limit` 設定列表傳回的 artifact 數量上限，範圍為 1 到 200。`limit` 大於 50 需要 Agent SDK v0.3.292 或更新版本。未指定 `limit` 時，列表最多傳回 25 個。

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

3845 3848

3846類型已匯出，但工具在 Agent SDK 工作階段中預設為關閉。發佈也需要[成品可用性表](/docs/zh-TW/artifacts#availability)中的每個條件，使用 API 金鑰驗證的工作階段不符合。3849* `capabilities`：已發佈頁面使用的執行時功能，按功能名稱鍵入，例如[頁面可能呼叫的連接器](/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors)。artifact 服務驗證宣告並拒絕命名帳戶無法使用的功能或給予一個無效設定的發佈。傳遞 `{}` 以清除儲存的宣告，在重新部署時省略欄位以保留它。需要 Agent SDK v0.3.235 或更新版本。

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

3851

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

3847 3853

3848<h3 id="projects">3854<h3 id="projects">

3849 Projects3855 Projects

3929};3935};

3930```3936```

3931 3937

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

3933 3939

3934<h2 id="tool-output-types">3940<h2 id="tool-output-types">

3935 工具輸出類型3941 工具輸出類型

3936</h2>3942</h2>

3937 3943

3938所有內建 Claude Code 工具的輸出架構文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，代表每個工具傳回的實際回應資料。3944所有內建 Claude Code 工具的輸出 schema 文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，代表每個工具傳回的實際回應資料。

3939 3945

3940<h3 id="tooloutputschemas">3946<h3 id="tooloutputschemas">

3941 `ToolOutputSchemas`3947 `ToolOutputSchemas`

4060 };4066 };

4061```4067```

4062 4068

4063傳回子代理的結果。根據 `status` 欄位進行區分：`"completed"` 表示已完成的工作，`"async_launched"` 表示背景工作，`"remote_launched"` 表示 Claude Code 分派到遠端雲端工作階段的工作，其中 `sessionUrl` 連結到該工作階段，`taskId` 識別它。4069傳回 subagent 的結果。根據 `status` 欄位進行區分：`"completed"` 表示已完成的工作，`"async_launched"` 表示背景任務，`"remote_launched"` 表示 Claude Code 分派到雲端工作階段的工作，其中 `sessionUrl` 連結到該工作階段，`taskId` 識別它。

4064 4070

4065在 `completed` 變體上，`resolvedModel` 命名子代理啟動時使用的模型，當套用 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 或其他覆蓋時，可能與要求的 `model` 輸入不同。此欄位需要 Claude Code v2.1.174 或更新版本。在 `async_launched` 上，它命名工作移至背景時使用的模型。4071在 `completed` 變體上，`resolvedModel` 命名 subagent 啟動時使用的模型，當套用 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 或其他覆寫時，可能與請求的 `model` 輸入不同。此欄位需要 Claude Code v2.1.174 或更新版本。在 `async_launched` 上，它命名工作移至背景時使用的模型。

4066 4072

4067`modelsUsed` 列出子代理使用的模型，按順序排列。此欄位僅在發生中途交換時出現，當執行交換回該模型時，模型會再次出現。在 `async_launched` 上，列表涵蓋背景化前使用的模型。`modelsUsed` 和 `resolvedModel` 的背景化行為都需要 Claude Code v2.1.212 或更新版本。4073`modelsUsed` 列出 subagent 使用的模型，按順序排列。此欄位僅在發生中途交換時出現，當執行交換回該模型時，模型會再次出現。在 `async_launched` 上，列表涵蓋背景化前使用的模型。`modelsUsed` 和 `resolvedModel` 的背景化行為都需要 Claude Code v2.1.212 或更新版本。

4068 4074

4069如果 Claude Code [保留了子代理的隔離 worktree](/docs/zh-TW/worktrees#isolate-subagents-with-worktrees)，`completed` 結果上的 `worktreePath` 是找到它的位置。`worktreeBranch` 是其分支，當 Claude Code 使用 git 建立 worktree 時出現。4075如果 Claude Code [保留了 subagent 的隔離 worktree](/docs/zh-TW/worktrees#isolate-subagents-with-worktrees)，`completed` 結果上的 `worktreePath` 是找到它的位置。`worktreeBranch` 是其分支，當 Claude Code 使用 git 建立 worktree 時出現。

4070 4076

4071Claude Code 從 subagent 的最終 API 請求填充 `usage` 和 `totalTokens`，而不是從整個執行，所以 `usage.service_tier` 是 API 在該請求上報告的服務層級字串。當存在時，`usage.output_tokens_details.thinking_tokens` 是該請求的輸出 token 中作為思考 token 的數量。`output_tokens_details` 欄位需要 TypeScript SDK v0.3.228 或更新版本，該版本包含 Claude Code v2.1.228。`fallback_credit` 欄位需要 TypeScript SDK v0.3.285 或更新版本，該版本包含 Claude Code v2.1.285。4077Claude Code 從 subagent 的最終 API 請求填充 `usage` 和 `totalTokens`，而不是從整個執行，所以 `usage.service_tier` 是 API 在該請求上報告的服務層級字串。當存在時，`usage.output_tokens_details.thinking_tokens` 是該請求的輸出 token 中作為思考 token 的數量。`output_tokens_details` 欄位需要 TypeScript SDK v0.3.228 或更新版本，該版本包含 Claude Code v2.1.228。`fallback_credit` 欄位需要 TypeScript SDK v0.3.285 或更新版本，該版本包含 Claude Code v2.1.285。

4072 4078

4073`usage.output_tokens_details` 在意義上與 [`Usage.output_tokens_details`](#usage) 相符，範圍限於該最終要求，但其每個層級都是選擇性的。保護物件和欄位，例如 `usage.output_tokens_details?.thinking_tokens ?? 0`，而不是直接讀取它。4079`usage.output_tokens_details` 在意義上與 [`Usage.output_tokens_details`](#usage) 相符，範圍限於該最終請求，但其每個層級都是選擇性的。保護物件和欄位，例如 `usage.output_tokens_details?.thinking_tokens ?? 0`，而不是直接讀取它。

4074 4080

4075在 v2.1.207 之前，發佈的類型更窄。它省略了 `worktreePath`、`worktreeBranch`、`citations`、`toolStats.frameCount` 和 `inference_geo`、`speed` 和 `iterations` 使用欄位，並將 `service_tier` 類型化為 `"standard" | "priority" | "batch"`。類型標記為選擇性的欄位可能在較早版本記錄的結果中不存在。4081在 v2.1.207 之前，發佈的類型更窄。它省略了 `worktreePath`、`worktreeBranch`、`citations`、`toolStats.frameCount` 和 `inference_geo`、`speed` 和 `iterations` 使用欄位，並將 `service_tier` 類型化為 `"standard" | "priority" | "batch"`。類型標記為選擇性的欄位可能在較早版本記錄的結果中不存在。

4076 4082

4146 4152

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

4148 4154

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

4150 4156

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

4152 4158

4164};4170};

4165```4171```

4166 4172

4167傳回執行中監視器的背景工作 ID。使用此 ID 搭配 `TaskStop` 以提前取消監視。4173傳回執行中監視器的背景任務 ID。使用此 ID 搭配 `TaskStop` 以提前取消監視。

4168 4174

4169<h3 id="edit-2">4175<h3 id="edit-2">

4170 Edit4176 Edit

4217 numLines: number;4223 numLines: number;

4218 startLine: number;4224 startLine: number;

4219 totalLines: number;4225 totalLines: number;

4220 /** 當整個檔案讀取因超過令牌上限而自動分頁時為真（內容是部分第一頁）。 */4226 /** 當整個檔案讀取因超過 token 上限而自動分頁時為真（內容是部分第一頁）。 */

4221 truncatedByTokenCap?: boolean;4227 truncatedByTokenCap?: boolean;

4222 };4228 };

4223 }4229 }

4314傳回寫入結果及結構化差異資訊。`originalFile` 和 `structuredPatch` 持有的內容取決於寫入：4320傳回寫入結果及結構化差異資訊。`originalFile` 和 `structuredPatch` 持有的內容取決於寫入：

4315 4321

4316* 對於新建立的檔案，`originalFile` 為 null，`structuredPatch` 為空4322* 對於新建立的檔案，`originalFile` 為 null，`structuredPatch` 為空

4317* 在覆蓋時，`originalFile` 攜帶先前的內容，除非該內容大於約 10 MB：Claude Code 會跳過差異並傳回 `originalFile` null 和 `structuredPatch` 空4323* 在覆寫檔案時，`originalFile` 攜帶先前的內容，除非該內容大於約 10 MB：Claude Code 會跳過差異並傳回 `originalFile` null 和 `structuredPatch` 空

4318* 當寫入未變更任何內容或差異逾時時，`structuredPatch` 也為空4324* 當寫入未變更任何內容或差異逾時時，`structuredPatch` 也為空

4319 4325

4320<h3 id="glob-2">4326<h3 id="glob-2">

4378};4384};

4379```4385```

4380 4386

4381傳回停止背景工作後的確認。4387傳回停止背景任務後的確認。

4382 4388

4383<h3 id="notebookedit-2">4389<h3 id="notebookedit-2">

4384 NotebookEdit4390 NotebookEdit

4427 4433

4428傳回提取的內容及 HTTP 狀態和中繼資料。4434傳回提取的內容及 HTTP 狀態和中繼資料。

4429 4435

4430`artifactRead` 是 Claude Code 自己的成品讀取記錄，僅當 Claude 提取工作階段可以發佈的成品時出現。Claude Code 在工作階段恢復時讀取它回來，以便稍後發佈基於正確版本；您的程式碼不需要對其採取行動。`slug` 命名成品，`ver` 是讀取記錄的版本，當它未記錄任何內容時不存在，`seeded: false` 標記其完整來源未到達 Claude 的讀取。`seeded` 欄位需要 Agent SDK v0.3.239 或更新版本。4436`artifactRead` 是 Claude Code 自己的 artifact 讀取記錄，僅當 Claude 提取工作階段可以發佈的 artifact 時出現。Claude Code 在工作階段恢復時讀取它回來，以便稍後發佈基於正確版本；您的程式碼不需要對其採取行動。`slug` 命名 artifact，`ver` 是讀取記錄的版本，當它未記錄任何內容時不存在，`seeded: false` 標記其完整來源未到達 Claude 的讀取。`seeded` 欄位需要 Agent SDK v0.3.239 或更新版本。

4431 4437

4432<h3 id="websearch-2">4438<h3 id="websearch-2">

4433 WebSearch4439 WebSearch

4468 summary?: string;4474 summary?: string;

4469 transcriptDir?: string;4475 transcriptDir?: string;

4470 scriptPath?: string;4476 scriptPath?: string;

4471 sessionUrl?: string; // 當工作流程作為遠端工作階段啟動時設定4477 sessionUrl?: string; // 當工作流程作為雲端工作階段啟動時設定

4472 warning?: string;4478 warning?: string;

4473 error?: string;4479 error?: string;

4474};4480};

4478 4484

4479| 欄位 | 類型 | 描述 |4485| 欄位 | 類型 | 描述 |

4480| - | - | - |4486| - | - | - |

4626};4632};

4627```4633```

4628 4634

4629傳回退出計畫模式後的計畫狀態。4635傳回退出 plan mode 後的計畫狀態。

4630 4636

4631<h3 id="listmcpresources-2">4637<h3 id="listmcpresources-2">

4632 ListMcpResources4638 ListMcpResources

4664};4670};

4665```4671```

4666 4672

4667傳回要求的 MCP 資源的內容。4673傳回請求的 MCP 資源的內容。

4668 4674

4669<h3 id="enterworktree-2">4675<h3 id="enterworktree-2">

4670 EnterWorktree4676 EnterWorktree

4715};4721};

4716```4722```

4717 4723

4718傳回進入計畫模式的確認。4724傳回進入 plan mode 的確認。

4719 4725

4720<h3 id="croncreate-2">4726<h3 id="croncreate-2">

4721 CronCreate4727 CronCreate

4785};4791};

4786```4792```

4787 4793

4788傳回喚醒將觸發的時間（作為紀元毫秒時間戳記）、實際使用的延遲以及要求的延遲是否被限制。`stopped` 欄位在呼叫以 `stop: true` 結束迴圈時為 `true`。它需要 Claude Code v2.1.202 或更新版本。`cancelledWakeups` 欄位計算 `stop: true` 呼叫取消了多少個待處理喚醒。值 0 表示沒有待處理，重複 `/loop` cron 不會被 `stop: true` 取消。它需要 Claude Code v2.1.206 或更新版本。4794傳回喚醒將觸發的時間（作為紀元毫秒時間戳記）、實際使用的延遲以及請求的延遲是否被限制。`stopped` 欄位在呼叫以 `stop: true` 結束迴圈時為 `true`。它需要 Claude Code v2.1.202 或更新版本。`cancelledWakeups` 欄位計算 `stop: true` 呼叫取消了多少個待處理喚醒。值 0 表示沒有待處理，重複 `/loop` cron 不會被 `stop: true` 取消。它需要 Claude Code v2.1.206 或更新版本。

4789 4795

4790<h3 id="remotetrigger-2">4796<h3 id="remotetrigger-2">

4791 RemoteTrigger4797 RemoteTrigger

4877 rel?: "mine" | "shared";4883 rel?: "mine" | "shared";

4878 }>;4884 }>;

4879 truncated?: boolean;4885 truncated?: boolean;

4886 total?: number;

4887 total_at_least?: true;

4880 scope?: "shared" | "all";4888 scope?: "shared" | "all";

4881 };4889 };

4882```4890```

4883 4891

4884傳回已發佈頁面的 `url` 和為發佈動作發佈的本機 `path`，當發佈重新部署現有成品時 `updated` 設定為 true，`warnings` 攜帶任何發佈時間建議。清單動作改為傳回 `artifacts` 列，當存在超過要求限制的成品時 `truncated` 設定。在其範圍不是 `"mine"` 的清單上，每列攜帶 `rel` 標記使用者是否擁有成品或與他們共享，輸出的 `scope` 記錄哪個非預設範圍產生清單；兩者在預設清單上不存在。4892傳回已發佈頁面的 `url` 和為發佈動作發佈的本機 `path`，當發佈重新部署現有 artifact 時 `updated` 設定為 true，`warnings` 攜帶任何發佈時間建議。清單動作改為傳回 `artifacts` 列，當存在超過請求限制的 artifact 時 `truncated` 設定。在其範圍不是 `"mine"` 的清單上，每列攜帶 `rel` 標記使用者是否擁有 artifact 或與他們共享，輸出的 `scope` 記錄哪個非預設範圍產生清單；兩者在預設清單上不存在。

4893

4894清單結果也會報告 `total`，即符合所列範圍的 artifact 數量，包括超出 `limit` 的項目。當設定 `total_at_least` 時，該數字為下限，可能還有更多 artifact 存在。兩個欄位都需要 Agent SDK v0.3.292 或更新版本。

4885 4895

4886<h3 id="projects-2">4896<h3 id="projects-2">

4887 Projects4897 Projects

agent-teams.md +2 −0

Details

1593. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-TW/model-config#environment-variables)，當它設定為 `inherit` 以外的任何值時。1593. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-TW/model-config#environment-variables)，當它設定為 `inherit` 以外的任何值時。

1604. 主管的目前模型。1604. 主管的目前模型。

161 161

162如果已安裝的 [mod](/docs/zh-TW/plugins/mods/overview) 在其 [`agent.spawn`](/docs/zh-TW/plugins/mods/reference#subagents) hook 中設定了模型，Claude Code 會使用該模型取代第一個來源。

163

162如果您設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)，前兩個來源不適用。當 `CLAUDE_CODE_SUBAGENT_MODEL` 設定為 `inherit` 以外的任何值時，Claude Code 從該環境變數為每個隊友選擇模型，否則從主管的目前模型選擇。需要 Claude Code v2.1.257 或更新版本。164如果您設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)，前兩個來源不適用。當 `CLAUDE_CODE_SUBAGENT_MODEL` 設定為 `inherit` 以外的任何值時，Claude Code 從該環境變數為每個隊友選擇模型，否則從主管的目前模型選擇。需要 Claude Code v2.1.257 或更新版本。

163 165

164在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此順序中排在第一位。166在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此順序中排在第一位。

agent-view.md +12 −7

Details

226 226

227在查看面板中輸入回覆，然後按 `Enter` 將其發送到該工作階段。在回覆前加上 `!` 則改為發送 Bash 命令。回覆的處理方式取決於工作階段以及您發送的內容：227在查看面板中輸入回覆，然後按 `Enter` 將其發送到該工作階段。在回覆前加上 `!` 則改為發送 Bash 命令。回覆的處理方式取決於工作階段以及您發送的內容：

228 228

229* 工作中的工作階段：回覆會加入工作階段的 [訊息佇列](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works)，而不會中斷回應，並在 [佇列中的輸入生效時](/docs/zh-TW/interactive-mode#when-claude-code-sends-what-you-queued) 生效。[命令](/docs/zh-TW/commands) 會等到回合結束才執行，即使是在工作階段自身的提示詞輸入中一輸入就會立即執行的命令也是如此229* 工作中的工作階段：`/model`、`/effort`、`/rename` 和 `/usage` 會立即執行。其他回覆會加入工作階段的 [訊息佇列](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works)，而不會中斷回應，並在 [佇列中的輸入生效時](/docs/zh-TW/interactive-mode#when-claude-code-sends-what-you-queued) 生效。其他 [命令](/docs/zh-TW/commands) 會等到回合結束才執行，即使是在工作階段自身的提示詞輸入中一輸入就會立即執行的命令也是如此

230* 內容恰好為 `/stop` 的回覆：無論工作階段正在工作或正在等待您，都會立即停止工作階段，而不會傳遞給它230* 內容恰好為 `/stop` 的回覆：無論工作階段正在工作或正在等待您，都會立即停止工作階段，而不會傳遞給它

231* [Shell 工作](#run-a-shell-command)：回覆（包括 `/stop`）會作為輸入內容送到該命令的終端機231* [Shell 工作](#run-a-shell-command)：回覆（包括 `/stop`）會作為輸入內容送到該命令的終端機

232 232

238 238

239當 [`PermissionRequest`](/docs/zh-TW/hooks#permissionrequest) 或 [`PreToolUse`](/docs/zh-TW/hooks#pretooluse) hook 針對工作階段所詢問的呼叫傳回 Claude Code 無法驗證的輸出時，列會在待處理請求的文字之前顯示 hook 事件，以及 `hook output invalid:` 和驗證錯誤。對於以其他方式失敗的 hook，列會顯示該 hook 失敗。工作階段仍會等待同一個請求。239當 [`PermissionRequest`](/docs/zh-TW/hooks#permissionrequest) 或 [`PreToolUse`](/docs/zh-TW/hooks#pretooluse) hook 針對工作階段所詢問的呼叫傳回 Claude Code 無法驗證的輸出時，列會在待處理請求的文字之前顯示 hook 事件，以及 `hook output invalid:` 和驗證錯誤。對於以其他方式失敗的 hook，列會顯示該 hook 失敗。工作階段仍會等待同一個請求。

240 240

241因背景服務無法連線或發送失敗而無法傳遞的回覆會被儲存，並在工作階段的程序再次啟動時作為其下一個提示詞發送，錯誤訊息也會說明回覆已儲存。以 `!` 為前綴的回覆不會被儲存，因為儲存的文字會以純提示詞的形式送達工作階段，而不會作為 Bash 命令執行。241當回覆無法傳遞時，錯誤訊息會說明該回覆是否已儲存。以 `!` 或 `/` 為前綴的回覆一律不會被儲存。下次您重新啟動工作階段時，Claude Code 會將已儲存的回覆作為工作階段的下一個提示詞發送；其他回覆請再次發送。

242 242

243在 [按住模式](/docs/zh-TW/voice-dictation#hold-to-record) 下啟用 [語音聽寫](/docs/zh-TW/voice-dictation) 後，在回覆輸入聚焦時按住您的按鍵通話鍵，即可以聽寫代替輸入回覆。相同的方式也適用於 agent 檢視底部的分派輸入。243在 [按住模式](/docs/zh-TW/voice-dictation#hold-to-record) 下啟用 [語音聽寫](/docs/zh-TW/voice-dictation) 後，在回覆輸入聚焦時按住您的按鍵通話鍵，即可以聽寫代替輸入回覆。相同的方式也適用於 agent 檢視底部的分派輸入。

244 244

288 288

289您按下 `←` 的來源列，在您使用方向鍵或滑鼠移動選擇後，名稱仍會保持粗體且不變暗，讓您能分辨自己來自哪個工作階段。289您按下 `←` 的來源列，在您使用方向鍵或滑鼠移動選擇後，名稱仍會保持粗體且不變暗，讓您能分辨自己來自哪個工作階段。

290 290

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

292 292

293當 Claude 在對話中啟動的 [前景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 仍在執行時，十秒限制不適用。Claude Code 會持續等待，讓它們的工作得以轉移，並在等待期間顯示 `Still backgrounding after the current tool` 通知。再按一次 `←` 即可不等待直接移至背景，這會讓這些 subagent 從頭重新開始。Claude Code 不會等待 [動態工作流程](/docs/zh-TW/workflows) 正在執行的 subagent。當工作流程有 subagent 正在執行時，Claude Code 會改為顯示 `Background this session?` 對話框。293約十秒後，Claude Code 會不再等待，直接將工作階段移至背景，但以下這類情況除外：

294 294

295當您的提示詞輸入中有未發送的文字時，Claude Code 不會將工作階段移至背景，因為該文字會留在您終端機的輸入框中，不會移至背景工作階段。如果您在 Claude Code 等待將工作階段移至背景時於輸入框中輸入文字，它會以 `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.` 取消切換。295* **前景 subagent 仍在執行**：Claude Code 會持續等待，讓 Claude 啟動的 [前景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 的工作得以轉移，並顯示 `Still backgrounding after the current tool`。再按一次 `←` 即可不等待直接移至背景，這會讓這些 subagent 從頭重新開始。

296* **權限提示或問題正在等待您的回答**：當權限提示或 Claude 提出的問題正在等待時，Claude Code 會持續等待並顯示 `Still backgrounding after the current tool — a question is waiting for your answer.`

297* **您在提示詞輸入中輸入文字**：Claude Code 會取消切換，因為未發送的文字會留在您終端機的輸入框中，不會移至背景工作階段。它會顯示 `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.`

298* **佇列中的訊息無法移動**：您 [在 Claude 工作時加入佇列](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works) 的訊息會隨對話移至背景工作階段。當其中某則訊息無法移動時，工作階段會留在前景，而 Claude Code 會顯示如 `Cannot open agents — 1 queued message can't move to the background. Press ← again once Claude has read it.` 的通知。

296 299

297即使對話尚無任何訊息，按 `←` 也會建立該工作階段的列，因此 `→` 仍可返回該工作階段。300即使對話尚無任何訊息，按 `←` 也會建立該工作階段的列，因此 `→` 仍可返回該工作階段。

298 301

876 879

877每個工作階段都是監督程序下的自己的 Claude Code 程序，該程序發生的情況取決於工作階段的狀態：880每個工作階段都是監督程序下的自己的 Claude Code 程序，該程序發生的情況取決於工作階段的狀態：

878 881

879* **工作中、暫停在權限提示或其他對話框上，或已連接**：程序保持執行。執行中的 subagent、工作流程或監視器計為工作中。882* **工作中、暫停在權限提示或其他對話框上，或已連接**：程序保持執行。執行中的 subagent、工作流程或監視器計為工作中，待處理的[工作階段範圍排程任務](/docs/zh-TW/scheduled-tasks)（例如 `/loop` 喚醒）也是如此。

880* **已完成或等待您的下一條訊息，且未連接約一小時**：監督程序停止程序以釋放資源。透過提出問題結束其回合的工作階段計為等待您的下一條訊息。對話保存在磁碟上，下次您連接或回覆時，工作階段從中斷的地方恢復。使用 `Ctrl+T` 釘選工作階段以保持其程序執行。883* **已完成或等待您的下一條訊息，且未連接約一小時**：監督程序停止程序以釋放資源。透過提出問題結束其回合的工作階段計為等待您的下一條訊息。對話保存在磁碟上，下次您連接或回覆時，工作階段從中斷的地方恢復。使用 `Ctrl+T` 釘選工作階段以保持其程序執行。

881* **在監督程序執行時意外退出**：監督程序重新啟動程序。結束您自己使用 `←` 或 `/background` 背景化的工作階段（例如使用 `kill`）會將其標記為已停止而不是重新啟動。對於以關閉結束的工作階段，請參閱[工作階段在關閉後顯示為失敗或已停止](#sessions-show-as-failed-after-shutdown)。884* **在監督程序執行時意外退出**：監督程序重新啟動程序。結束您自己使用 `←` 或 `/background` 背景化的工作階段（例如使用 `kill`）會將其標記為已停止而不是重新啟動。對於以關閉結束的工作階段，請參閱[工作階段在關閉後顯示為失敗或已停止](#sessions-show-as-failed-after-shutdown)。

882* **自動更新後**：監督程序重新啟動自身到新版本，並在背景中移動閒置工作階段。正在工作、等待您或已連接的工作階段不會被中斷。885* **自動更新後**：監督程序重新啟動自身到新版本，並在背景中移動閒置工作階段。正在工作、等待您或已連接的工作階段不會被中斷。

970* 您恢復對話的終端機，例如使用 `claude --resume` 或 `/resume`：該列顯示 `Open in a terminal`，並提示在那裡繼續，開啟該列會顯示 `Can't open — this session is running in another terminal`。在該終端機中繼續，或退出它並再次開啟該列。973* 您恢復對話的終端機，例如使用 `claude --resume` 或 `/resume`：該列顯示 `Open in a terminal`，並提示在那裡繼續，開啟該列會顯示 `Can't open — this session is running in another terminal`。在該終端機中繼續，或退出它並再次開啟該列。

971* 另一個非互動式 Claude Code 程序，例如同一對話的背景工作階段程序尚未退出：開啟該列會顯示 `This conversation is already open in another running Claude session`。使用該程序，或等待它退出後再次開啟該列。974* 另一個非互動式 Claude Code 程序，例如同一對話的背景工作階段程序尚未退出：開啟該列會顯示 `This conversation is already open in another running Claude session`。使用該程序，或等待它退出後再次開啟該列。

972 975

973Claude Code 會儲存您在被拒絕的嘗試中輸入的回覆，並在工作階段下次啟動時傳送它。976Claude Code 會儲存您在被拒絕的嘗試中輸入的回覆（以 `!` 或 `/` 開頭的回覆除外），並在工作階段下次啟動時傳送它。

974 977

975<h3 id="opening-a-session-says-it-has-no-saved-transcript">978<h3 id="opening-a-session-says-it-has-no-saved-transcript">

976 開啟工作階段時顯示它沒有已儲存的逐字稿979 開啟工作階段時顯示它沒有已儲存的逐字稿

1093| 版本 | 變更 |1096| 版本 | 變更 |

1094| - | - |1097| - | - |

1095| v2.1.290 | [`claude attach` 和 `claude logs`](#manage-sessions-from-the-shell) 可以接受執行中工作階段名稱的一部分來取代 ID。 |1098| v2.1.290 | [`claude attach` 和 `claude logs`](#manage-sessions-from-the-shell) 可以接受執行中工作階段名稱的一部分來取代 ID。 |

1099| v2.1.290 | 作為[查看回覆](#peek-and-reply)傳送給工作中工作階段的 `/model`、`/effort`、`/rename` 和 `/usage` 會立即執行。 |

1100| v2.1.290 | 無法傳遞的[查看回覆](#peek-and-reply)在以 `/` 開頭時，或在工作階段的程序執行期間回答具有預定義選項的問題時，不再被儲存以供下次重新啟動時使用。 |

1096| v2.1.288 | `Ctrl+F` 會依名稱尋找工作階段，`Alt+↑` / `Alt+↓` 會在群組標題之間跳轉。這兩者以及 `Ctrl+R` 都可以[重新繫結](/docs/zh-TW/keybindings#agents-actions)。 |1101| v2.1.288 | `Ctrl+F` 會依名稱尋找工作階段，`Alt+↑` / `Alt+↓` 會在群組標題之間跳轉。這兩者以及 `Ctrl+R` 都可以[重新繫結](/docs/zh-TW/keybindings#agents-actions)。 |

1097| v2.1.287 | [`n:<text>` 篩選器](#filter-sessions)會依名稱或第一個提示詞尋找工作階段。當任何篩選器作用中時，您摺疊的群組會展開以顯示其符合項目，並選取第一個符合項目，因此 `Enter` 會開啟它。 |1102| v2.1.287 | [`n:<text>` 篩選器](#filter-sessions)會依名稱或第一個提示詞尋找工作階段。當任何篩選器作用中時，您摺疊的群組會展開以顯示其符合項目，並選取第一個符合項目，因此 `Enter` 會開啟它。 |

1098| v2.1.287 | 作為[查看回覆](#peek-and-reply)傳送的命令會在工作階段目前的回合結束時執行，包括在工作階段自己的輸入中一輸入就會立即執行的命令。內容恰好為 `/stop` 的回覆會立即停止工作階段。 |1103| v2.1.287 | 作為[查看回覆](#peek-and-reply)傳送的命令會在工作階段目前的回合結束時執行，包括在工作階段自己的輸入中一輸入就會立即執行的命令。內容恰好為 `/stop` 的回覆會立即停止工作階段。 |

amazon-bedrock.md +49 −12

Details

136 2. 設定 AWS 認證136 2. 設定 AWS 認證

137</h3>137</h3>

138 138

139Claude Code 使用預設 AWS SDK 認證鏈。使用下列其中一種方法設定您的認證：139Claude Code 使用預設 AWS SDK 憑證鏈。如果機器已向該鏈提供憑證，例如 Amazon EC2 執行個體設定檔或 Amazon ECS 任務憑證，請直接跳至[步驟 3](#3-configure-claude-code)。

140 140

141**選項 A：AWS CLI 設定**141AWS [警告不要在開發專用軟體或處理真實資料時使用 IAM 使用者的存取金鑰](https://docs.aws.amazon.com/cli/latest/userguide/cli-authentication-user.html)。使用下列其中一種方法設定您的憑證：

142

143* [`aws configure`](#use-aws-configure)：將 IAM 使用者的存取金鑰儲存至您 `~/.aws` 目錄中的設定檔

144* [存取金鑰環境變數](#export-an-access-key)：僅在目前的 shell 中設定存取金鑰，或搭配工作階段 token 的臨時憑證

145* [SSO 設定檔](#use-an-sso-profile)：在瀏覽器中透過 IAM Identity Center 登入並取得臨時憑證。如果您透過 IAM Identity Center 存取 AWS 帳戶，請使用此方法。

146* [AWS Management Console 憑證](#use-aws-management-console-credentials)：在瀏覽器中使用您的 AWS Management Console 憑證登入並取得臨時憑證。如果您以根使用者、IAM 使用者身分或透過與 IAM 的聯合存取 AWS 帳戶，AWS [建議使用此方法](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html)。

147* [Amazon Bedrock API 金鑰](#use-an-amazon-bedrock-api-key)：使用僅適用於 Amazon Bedrock 的 bearer token 進行身分驗證，而非使用 AWS 憑證

148

149<h4 id="use-aws-configure">

150 使用 `aws configure`

151</h4>

152

153執行 `aws configure`，並在出現提示時輸入您的存取金鑰 ID、秘密存取金鑰和預設區域：

142 154

143```bash theme={null}155```bash theme={null}

144aws configure156aws configure

145```157```

146 158

147**選項 B：環境變數（存取金鑰）**159AWS CLI 會將金鑰儲存至 `~/.aws/credentials` 中的 `default` 設定檔，憑證鏈會從該處讀取。

160

161<h4 id="export-an-access-key">

162 匯出存取金鑰

163</h4>

164

165將您的存取金鑰匯出為環境變數。`AWS_SESSION_TOKEN` 僅在使用臨時憑證時需要，因此如果您的存取金鑰屬於 IAM 使用者，請省略該行：

148 166

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

150export AWS_ACCESS_KEY_ID=your-access-key-id168export AWS_ACCESS_KEY_ID=your-access-key-id

152export AWS_SESSION_TOKEN=your-session-token170export AWS_SESSION_TOKEN=your-session-token

153```171```

154 172

155**選項 C：環境變數（SSO 設定檔）**173<h4 id="use-an-sso-profile">

174 使用 SSO 設定檔

175</h4>

156 176

157在執行這些命令之前，將 `your-profile-name` 替換為您的 AWS 設定檔名稱。177如果您還沒有設定檔，請使用 `aws configure sso` 建立一個。然後登入 IAM Identity Center 並設定 `AWS_PROFILE`，讓憑證鏈使用該設定檔。在執行這些命令之前，將 `your-profile-name` 替換為您的 AWS 設定檔名稱。

158 178

159```bash theme={null}179```bash theme={null}

160aws sso login --profile=your-profile-name180aws sso login --profile=your-profile-name

164 184

165Claude Code 從設定檔的 `sso_region` 命名的 IAM Identity Center 區域要求角色認證，這不需要與您執行 Amazon Bedrock 的區域相符。在 v2.1.207 中，Amazon Bedrock 區域覆寫了 `sso_region`，因此設定檔的 IAM Identity Center 執行個體位於不同區域時，驗證失敗並出現 `Session token not found or invalid` 錯誤。185Claude Code 從設定檔的 `sso_region` 命名的 IAM Identity Center 區域要求角色認證，這不需要與您執行 Amazon Bedrock 的區域相符。在 v2.1.207 中，Amazon Bedrock 區域覆寫了 `sso_region`，因此設定檔的 IAM Identity Center 執行個體位於不同區域時，驗證失敗並出現 `Session token not found or invalid` 錯誤。

166 186

167**選項 D：AWS Management Console 認證**187<h4 id="use-aws-management-console-credentials">

188 使用 AWS Management Console 憑證

189</h4>

190

191`aws login` 命令需要 AWS CLI 2.32.0 或更新版本。如需您的身分所需的 IAM 政策，請參閱 [AWS 的 `aws login` 說明](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html)。

192

193執行此命令，在瀏覽器中使用您的 AWS Management Console 憑證登入：

168 194

169```bash theme={null}195```bash theme={null}

170aws login196aws login

171```197```

172 198

173[深入瞭解](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html) `aws login`。199工作階段的有效期最長為 12 小時，之後您需要再次執行 `aws login`。

200

201<h4 id="use-an-amazon-bedrock-api-key">

202 使用 Amazon Bedrock API 金鑰

203</h4>

204

205Amazon Bedrock API 金鑰是一種 bearer token，可取代 AWS 憑證來驗證您的請求。AWS 提供[兩種類型的金鑰](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html)：

174 206

175**選項 E：Amazon Bedrock API 金鑰**207* **短期金鑰**：最長持續 12 小時。在生產環境中，AWS 偏好使用短期金鑰而非長期金鑰。

208* **長期金鑰**：持續至您設定的到期日。AWS 建議僅將其用於探索用途。

209

210將金鑰匯出為 `AWS_BEARER_TOKEN_BEDROCK`：

176 211

177```bash theme={null}212```bash theme={null}

178export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key213export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

179```214```

180 215

181Amazon Bedrock API 金鑰提供更簡單的驗證方法，無需完整的 AWS 認證。[深入瞭解 Amazon Bedrock API 金鑰](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)。216設定 `AWS_BEARER_TOKEN_BEDROCK` 時，Claude Code 會使用該金鑰進行身分驗證，且不會解析憑證鏈，即使存在其他 AWS 憑證也是如此。[深入瞭解 Amazon Bedrock API 金鑰](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)。

182 217

183<h4 id="credential-caching-and-resolution-timeout">218<h4 id="credential-caching-and-resolution-timeout">

184 認證快取和解析逾時219 認證快取和解析逾時

186 221

187Claude Code 解析 AWS 預設認證提供者鏈一次，並將解析的認證保留在記憶體中。它會重複使用這些認證，直到它們過期前五分鐘，或在沒有過期時間時使用一小時，因此 SSO 支援的設定檔大約每個認證生命週期向 IAM Identity Center 要求一次認證。來自 API 的認證錯誤會清除快取，重試會解析新認證。需要 Claude Code v2.1.207 或更新版本。222Claude Code 解析 AWS 預設認證提供者鏈一次，並將解析的認證保留在記憶體中。它會重複使用這些認證，直到它們過期前五分鐘，或在沒有過期時間時使用一小時，因此 SSO 支援的設定檔大約每個認證生命週期向 IAM Identity Center 要求一次認證。來自 API 的認證錯誤會清除快取，重試會解析新認證。需要 Claude Code v2.1.207 或更新版本。

188 223

189快取涵蓋上述所有認證選項，除了 Amazon Bedrock API 金鑰（不使用提供者鏈）。若要改為在每個要求上解析鏈，請設定 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-TW/env-vars)。224快取涵蓋此步驟開頭列出的所有憑證方法，除了 Amazon Bedrock API 金鑰（不使用提供者鏈）。若要改為在每個請求上解析鏈，請設定 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-TW/env-vars)。

190 225

191填入快取的解析會在 60 秒後逾時。如果鏈中的步驟停滯，例如等待無法接收的輸入的 `credential_process` 協助程式，請求會失敗並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)。如果您的鏈執行合法需要更長時間的互動式登入，例如透過 `aws-vault` 之類的包裝程式進行瀏覽器型 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制。設定 `CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1` 時，每個 API 請求都會在沒有此限制的情況下解析鏈。226填入快取的解析會在 60 秒後逾時。如果鏈中的步驟停滯，例如等待無法接收的輸入的 `credential_process` 協助程式，請求會失敗並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)。如果您的鏈執行合法需要更長時間的互動式登入，例如透過 `aws-vault` 之類的包裝程式進行瀏覽器型 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制。設定 `CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1` 時，每個 API 請求都會在沒有此限制的情況下解析鏈。

192 227

509 1M 權杖內容視窗544 1M 權杖內容視窗

510</h2>545</h2>

511 546

512Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Amazon Bedrock 上支援 [1M 權杖內容視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)。Sonnet 5 在 Invoke API 和 [Mantle 端點](#use-the-mantle-endpoint)上始終以 1M 視窗執行，沒有 `[1m]` 變體可選擇。對於 Invoke API 上的其他模型，當您選取 1M 模型變體時，Claude Code 會自動啟用擴展內容視窗。547Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本，在 Amazon Bedrock 上預設以 [1M token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)執行，Invoke API 和 [Mantle 端點](#use-the-mantle-endpoint)皆是如此，不需要 `[1m]` 後綴。當 [`modelOverrides`](#map-each-model-version-to-an-inference-profile) 項目將模型對應至應用程式推論設定檔 ARN 時，該 ARN 會取得 1M 視窗。若要改為保留 200K 視窗，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/model-config#turn-off-1m-context)。

548

549Invoke API 上的 Opus 4.6 和 Sonnet 4.6 在您選取其 `[1m]` 變體時可使用 1M 視窗。[設定精靈](#sign-in-with-bedrock)在固定模型時提供 1M 上下文選項。若要改為為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。請參閱[為第三方部署固定模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)以取得詳細資訊，包括如何在不變更固定的情況下使用 1M 視窗。

513 550

514[設定精靈](#sign-in-with-bedrock)在固定模型時提供 1M 內容選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。請參閱[為第三方部署固定模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)以取得詳細資訊，包括如何在不變更固定的情況下使用 1M 視窗。551在 v2.1.287 之前，Fable 模型以及 Opus 4.7 及更新版本在 Invoke API 上預設以 200K 視窗執行，並透過 `[1m]` 後綴在該處使用 1M 視窗。

515 552

516<h2 id="service-tiers">553<h2 id="service-tiers">

517 服務層級554 服務層級

artifacts.md +1 −1

Details

391| 驗證 | 工作階段由 claude.ai 帳戶支援：在 CLI 或桌面應用程式中使用 `/login` 登入。Claude Tag 工作階段透過代理程式的身分登入，因此不需要任何步驟。使用 API 金鑰、[閘道令牌](/docs/zh-TW/llm-gateway)或雲端提供者認證的工作階段無法發佈。 |391| 驗證 | 工作階段由 claude.ai 帳戶支援：在 CLI 或桌面應用程式中使用 `/login` 登入。Claude Tag 工作階段透過代理程式的身分登入，因此不需要任何步驟。使用 API 金鑰、[閘道令牌](/docs/zh-TW/llm-gateway)或雲端提供者認證的工作階段無法發佈。 |

392| 模型提供者 | Anthropic API。在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上不可用。 |392| 模型提供者 | Anthropic API。在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上不可用。 |

393| 組織政策 | 客戶管理的加密金鑰 (CMEK)、HIPAA 和[零資料保留](/docs/zh-TW/zero-data-retention)未為組織啟用。 |393| 組織政策 | 客戶管理的加密金鑰 (CMEK)、HIPAA 和[零資料保留](/docs/zh-TW/zero-data-retention)未為組織啟用。 |

394| 表面 | Claude Code CLI，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在 Claude Tag 和成品都為組織啟用時也可以發佈成品。在 [Agent SDK](/docs/zh-TW/agent-sdk/overview)、GitHub Action 和 MCP 伺服器上下文中預設關閉，以及當設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 時。 |394| 使用介面 | Claude Code CLI，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在 Claude Tag 和 artifact 都為組織啟用時也可以發佈 artifact。在 [Agent SDK](/docs/zh-TW/agent-sdk/overview)、GitHub Action 和 MCP 伺服器情境中預設關閉，當您從自己的終端機或指令碼以 [`-p`](/docs/zh-TW/headless) 執行 Claude Code 時，以及設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 時亦同。 |

395 395

396您的組織是否允許成品來自您組織的政策，Claude Code 從 `api.anthropic.com` 載入。當 Claude Code 無法載入政策時，成品不可用。當您要求一個時，Claude 會說明原因。396您的組織是否允許成品來自您組織的政策，Claude Code 從 `api.anthropic.com` 載入。當 Claude Code 無法載入政策時，成品不可用。當您要求一個時，Claude 會說明原因。

397 397

authentication.md +0 −2

Details

142* **它簽出的內容**：Claude Code 簽出儲存在機器上的任何 claude.ai 登入142* **它簽出的內容**：Claude Code 簽出儲存在機器上的任何 claude.ai 登入

143* **如何復原它**：執行 `/logout`，它會移除並撤銷此登入寫入的認證143* **如何復原它**：執行 `/logout`，它會移除並撤銷此登入寫入的認證

144 144

145如果您的組織使用 [伺服器受管設定](/docs/zh-TW/server-managed-settings)，它們會在 Claude Code v2.1.257 或更新版本上套用到此登入。

~~146~~

147有關設定檔的所有其他內容都適用於此登入，包括它在您其他認證中的排名、您在 `/status` 中獲得的 `Profile` 列，以及需要 claude.ai 登入的功能。請參閱 [Anthropic 設定檔和聯盟認證](#anthropic-profiles-and-federation-credentials)。145有關設定檔的所有其他內容都適用於此登入，包括它在您其他認證中的排名、您在 `/status` 中獲得的 `Profile` 列，以及需要 claude.ai 登入的功能。請參閱 [Anthropic 設定檔和聯盟認證](#anthropic-profiles-and-federation-credentials)。

148 146

149<h3 id="cloud-provider-authentication">147<h3 id="cloud-provider-authentication">

claude-apps-gateway.md +2 −1

Details

303 允許您擁有的公開位址空間上的閘道303 允許您擁有的公開位址空間上的閘道

304</h3>304</h3>

305 305

306某些組織從他們擁有的公開 IPv4 區塊（例如電信業者自己的位址空間或舊版 `/8`）對其內部網路進行編號，因此他們的閘道無法擁有私人位址。在 `gatewayInternalNetworks` 受管設定中列出這些區塊。`/login` 然後在開發人員的機器從同一區塊內的位址連接到它時，接受位於列出區塊內的閘道。這需要開發人員機器上的 Claude Code v2.1.268 或更新版本；較早的版本忽略該設定鍵並套用私人位址規則。306某些組織從他們擁有的公開 IPv4 區塊（例如電信業者自己的位址空間或舊版 `/8`）對其內部網路進行編號，因此他們的閘道沒有私人位址。在 `gatewayInternalNetworks` 受管設定中列出這些區塊。`/login` 然後在開發人員的機器從同一區塊內的位址連接到它時，接受位於列出區塊內的閘道。這需要開發人員機器上的 Claude Code v2.1.268 或更新版本；較早的版本忽略該設定鍵並套用私人位址規則。

307 307

308<Warning>308<Warning>

309 `gatewayInternalNetworks` 適用於恰好從公開位址空間編號的內部網路。它不會使將閘道暴露到網際網路變得安全：受信任的閘道可以推送在開發人員機器上執行命令的設定。309 `gatewayInternalNetworks` 適用於恰好從公開位址空間編號的內部網路。它不會使將閘道暴露到網際網路變得安全：受信任的閘道可以推送在開發人員機器上執行命令的設定。

521| 功能 | 狀態 | 備註 |521| 功能 | 狀態 | 備註 |

522| - | - | - |522| - | - | - |

523| 推理轉發 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) | 可用 | 具有按上游模型轉換和故障轉移。Amazon Bedrock 上游使用 `bedrock-runtime` 端點和 AWS 預設憑證鏈。[Amazon Bedrock Mantle 上游](/docs/zh-TW/claude-apps-gateway-config#amazon-bedrock-mantle-endpoint)需要閘道伺服器上的 Claude Code v2.1.283 或更新版本，而 [Claude Platform on AWS 上游](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)需要 v2.1.198 或更新版本。 |523| 推理轉發 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) | 可用 | 具有按上游模型轉換和故障轉移。Amazon Bedrock 上游使用 `bedrock-runtime` 端點和 AWS 預設憑證鏈。[Amazon Bedrock Mantle 上游](/docs/zh-TW/claude-apps-gateway-config#amazon-bedrock-mantle-endpoint)需要閘道伺服器上的 Claude Code v2.1.283 或更新版本，而 [Claude Platform on AWS 上游](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)需要 v2.1.198 或更新版本。 |

524| 1M token 上下文視窗 | 可用 | Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本預設以 1M 視窗執行；請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)。Fable 和 Opus 模型的 1M 預設需要開發人員機器上的 Claude Code v2.1.287 或更新版本 |

524| 按 IdP 群組的模型存取和受管設定 | 可用 | 模型存取在伺服器端強制執行；受管設定按 IdP 群組傳遞，由 CLI 在[受管設定層級](/docs/zh-TW/settings#settings-precedence)應用 |525| 按 IdP 群組的模型存取和受管設定 | 可用 | 模型存取在伺服器端強制執行；受管設定按 IdP 群組傳遞，由 CLI 在[受管設定層級](/docs/zh-TW/settings#settings-precedence)應用 |

525| Claude Desktop | 可用（需要選擇加入） | 閘道在 `/user/bootstrap` 提供 Claude Desktop 的設定，一旦原則[使用 `desktop` 金鑰選擇加入](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)，Claude Desktop 從其 Cowork 和 Code 標籤以及從 Chat 標籤（當您啟用它時）發送模型請求透過閘道。若要開啟 Chat 標籤，請參閱[連接 Claude Desktop](#connect-claude-desktop)。需要閘道伺服器上的 Claude Code v2.1.203 或更新版本。 |526| Claude Desktop | 可用（需要選擇加入） | 閘道在 `/user/bootstrap` 提供 Claude Desktop 的設定，一旦原則[使用 `desktop` 金鑰選擇加入](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)，Claude Desktop 從其 Cowork 和 Code 標籤以及從 Chat 標籤（當您啟用它時）發送模型請求透過閘道。若要開啟 Chat 標籤，請參閱[連接 Claude Desktop](#connect-claude-desktop)。需要閘道伺服器上的 Claude Code v2.1.203 或更新版本。 |

526| 遙測扇出 (OTLP/HTTP) | 可用 | 按匯出標識戳記；protobuf 和 JSON 編碼 |527| 遙測扇出 (OTLP/HTTP) | 可用 | 按匯出標識戳記；protobuf 和 JSON 編碼 |

claude-apps-gateway-deploy.md +22 −7

Details

6 6

7> 向您的身份提供者註冊閘道、建置容器、在 Kubernetes 或 Cloud Run 上部署，並運營它：健康檢查、祕密輪換、升級和安全性。7> 向您的身份提供者註冊閘道、建置容器、在 Kubernetes 或 Cloud Run 上部署，並運營它：健康檢查、祕密輪換、升級和安全性。

8 8

9<Info>

10 **先規劃閘道的網路。** 登入時，Claude Code 會拒絕主機名稱解析為公用 IP 位址的 Claude 應用程式閘道，即使該位址無法從網際網路存取也一樣。

12 Claude 應用程式閘道可以將設定推送到使用者的機器，包括執行 shell 命令的 hook。此檢查有助於防止使用者意外登入公用網際網路上的惡意閘道。也請讓您自己的閘道遠離網際網路。

14 在選擇閘道的執行位置之前，請先選擇閘道的位址。通常這是使用者在您的內部網路上或透過 VPN 存取的私人位址。如果您的內部網路使用公用 IPv4 範圍，您可以列出一個同時包含閘道和使用者機器的範圍。Claude Code 會將該相符結果視為閘道位於您內部網路上的跡象。請參閱[為閘道選擇位址](#choose-an-address-for-the-gateway)。如果兩者都不適合您的網路，請聯絡您的 Anthropic 客戶團隊。

15</Info>

9本頁涵蓋執行 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 的運營方面：在您的身份提供者 (IdP) 中註冊 OAuth 用戶端、將閘道部署為容器，以及日常運營。關於閘道在啟動時讀取的 `gateway.yaml` 檔案中的每個選項，請參閱 [設定參考](/docs/zh-TW/claude-apps-gateway-config)。17本頁涵蓋執行 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 的運營方面：在您的身份提供者 (IdP) 中註冊 OAuth 用戶端、將閘道部署為容器，以及日常運營。關於閘道在啟動時讀取的 `gateway.yaml` 檔案中的每個選項，請參閱 [設定參考](/docs/zh-TW/claude-apps-gateway-config)。

10 18

11生產部署按順序遵循四個步驟，下面的章節與之相符。前兩個是您做出選擇的地方；後兩個是一旦運行時要查閱的參考資料。19生產部署按順序遵循四個步驟，下面的章節與之相符。前兩個是您做出選擇的地方；後兩個是一旦運行時要查閱的參考資料。

17 25

18如果沿途簽入或啟動失敗，請直接前往 [故障排除](#troubleshooting)，該部分根據您看到的錯誤進行索引。26如果沿途簽入或啟動失敗，請直接前往 [故障排除](#troubleshooting)，該部分根據您看到的錯誤進行索引。

19 27

~~20<Note>~~

21 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，請參閱 [允許閘道在您擁有的公開位址空間上](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。

~~22</Note>~~

24<h2 id="identity-provider-setup">28<h2 id="identity-provider-setup">

25 身份提供者設定29 身份提供者設定

26</h2>30</h2>

51 部署55 部署

52</h2>56</h2>

53 57

54閘道是單一無狀態 Linux 二進位檔案，透過 Postgres 進行協調，因此以您在環境中部署任何其他無狀態服務的方式部署它。將其保持在您的網路內，您的開發人員和 IdP 可以透過 HTTPS 到達它，並將其視為任何持有生產認證的服務。58閘道是單一無狀態 Linux 二進位檔案，透過 Postgres 進行協調，因此以您在環境中部署任何其他無狀態服務的方式部署它。將其保持在您的網路內，讓您的開發人員可以透過 HTTPS 到達它，且它可以到達您的 IdP，並將其視為任何持有生產憑證的服務。

55 59

56除了它執行的位置之外，還有一些決策塑造部署：60除了它執行的位置之外，還有一些決策塑造部署：

57 61

71 75

72預設值（例如 ALB 的 60 秒）足以保持安靜的串流開啟。[AWS 實際工作範例](/docs/zh-TW/claude-apps-gateway-on-aws#troubleshooting)無論如何將其提高到一小時，其故障排除列涵蓋早於 v2.1.229 的閘道，它在現在獲得 ping 的上游上的安靜期間沒有發送任何內容。76預設值（例如 ALB 的 60 秒）足以保持安靜的串流開啟。[AWS 實際工作範例](/docs/zh-TW/claude-apps-gateway-on-aws#troubleshooting)無論如何將其提高到一小時，其故障排除列涵蓋早於 v2.1.229 的閘道，它在現在獲得 ping 的上游上的安靜期間沒有發送任何內容。

73 77

78<h3 id="choose-an-address-for-the-gateway">

79 為閘道選擇位址

80</h3>

82Claude Code 以下列兩種方式之一接受閘道的位址：

84* **私有位址**：將閘道放在內部負載平衡器或 VPN 後方，並使用僅解析為私有位址（例如 RFC 1918 或 CGNAT `100.64.0.0/10`）的主機名稱。使用者的機器可以使用任何位址。[私有網路先決條件](/docs/zh-TW/claude-apps-gateway#prerequisites)列出接受的範圍。

85* **宣告的區塊**：如果您的內部網路使用您組織擁有的公用 IPv4 空間，請在 `gatewayInternalNetworks` 受管設定中列出該區塊。閘道與使用者的機器都必須位於該區塊內。請參閱[允許位於您擁有的公用位址空間上的閘道](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。

87如果沒有任何單一區塊同時包含兩者，請改為給閘道一個私有位址。

74<h3 id="container-image">89<h3 id="container-image">

75 容器映像90 容器映像

76</h3>91</h3>

375 疑難排解390 疑難排解

376</h2>391</h2>

377 392

378如有問題和意見回饋，請使用 [Claude Code 支援](https://support.claude.com/en/collections/14445694-claude-code)，或在 [Claude Code GitHub 儲存庫](https://github.com/anthropics/claude-code/issues)上開啟議題。回報問題時，請包含：393如有問題和意見回饋，請使用 [Claude Code 支援](https://support.claude.com/en/collections/14445694-claude-code)，或在 [Claude Code GitHub 儲存庫](https://github.com/anthropics/claude-code/issues)上開啟議題。您也可以聯絡您的 Anthropic 客戶團隊。回報問題時，請包含：

379 394

380* **Gateway 問題**：gateway 的 stderr（針對相關視窗）、您的 `gateway.yaml`（已隱蔽機密）、gateway 版本（顯示在 `/` 的登陸頁面和 `/managed/settings` 上的 `x-cc-gateway-version` 回應標頭中），以及最近有什麼變更395* **Gateway 問題**：gateway 的 stderr（針對相關視窗）、您的 `gateway.yaml`（已隱蔽機密）、gateway 版本（顯示在 `/` 的登陸頁面和 `/managed/settings` 上的 `x-cc-gateway-version` 回應標頭中），以及最近有什麼變更

381* **登入問題**：開發者執行 `claude --debug-file ./claude-debug.txt`、重現問題，然後傳送該檔案加上 gateway 針對同一視窗的稽核日誌396* **登入問題**：開發者執行 `claude --debug-file ./claude-debug.txt`、重現問題，然後傳送該檔案加上 gateway 針對同一視窗的稽核日誌

394| CLI `/login`：`The gateway is limiting sign-in attempts right now`，或在較舊版本上 `Request failed with status code 429`。`/device` 頁面可能對尚未嘗試過的開發者顯示 `Too many attempts` | 達到了每個 IP 的登入速率限制。要麼 `listen.trusted_proxies` 不涵蓋負載平衡器，所以每個開發者共享其位址，要麼許多開發者共享 NAT 或 VPN 出口位址。具有 `result: rate_limited` 的稽核事件顯示相同的一個或幾個 `client_ip` 值。 | 首先將 `listen.trusted_proxies` 設定為負載平衡器的來源範圍，然後如果開發者仍然共享位址，請提高 `rate_limits`。請參閱[大規模推出](#large-rollouts)。 |409| CLI `/login`：`The gateway is limiting sign-in attempts right now`，或在較舊版本上 `Request failed with status code 429`。`/device` 頁面可能對尚未嘗試過的開發者顯示 `Too many attempts` | 達到了每個 IP 的登入速率限制。要麼 `listen.trusted_proxies` 不涵蓋負載平衡器，所以每個開發者共享其位址，要麼許多開發者共享 NAT 或 VPN 出口位址。具有 `result: rate_limited` 的稽核事件顯示相同的一個或幾個 `client_ip` 值。 | 首先將 `listen.trusted_proxies` 設定為負載平衡器的來源範圍，然後如果開發者仍然共享位址，請提高 `rate_limits`。請參閱[大規模推出](#large-rollouts)。 |

395| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 主機名稱解析為至少一個公開 IP 位址。Claude Code 檢查每個已解析的位址，並要求每個位址都是私有的。常見原因是雙堆疊名稱，其中一個系列解析為公開位址，包括 AWS 內部雙堆疊負載平衡器，它們傳回公開範圍的 AAAA 位址。 | 讓 gateway 名稱在開發者機器上只解析為私有位址。對於雙堆疊名稱，請刪除公開範圍記錄或提供單獨的僅限內部 DNS 名稱。請參閱[私有網路先決條件](/docs/zh-TW/claude-apps-gateway#prerequisites)。如果位址是您的組織擁有並在內部使用的公開空間，請改為[宣告該區塊](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。 |410| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 主機名稱解析為至少一個公開 IP 位址。Claude Code 檢查每個已解析的位址，並要求每個位址都是私有的。常見原因是雙堆疊名稱，其中一個系列解析為公開位址，包括 AWS 內部雙堆疊負載平衡器，它們傳回公開範圍的 AAAA 位址。 | 讓 gateway 名稱在開發者機器上只解析為私有位址。對於雙堆疊名稱，請刪除公開範圍記錄或提供單獨的僅限內部 DNS 名稱。請參閱[私有網路先決條件](/docs/zh-TW/claude-apps-gateway#prerequisites)。如果位址是您的組織擁有並在內部使用的公開空間，請改為[宣告該區塊](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。 |

396| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於 gateway 主機，且代理伺服器的主機名稱解析為公開位址。主機名稱只解析為私有位址的代理伺服器是允許的，不會觸發此錯誤 | 在開發者的機器上將 gateway 主機新增到 `NO_PROXY`，以便連線是直接的，或使用主機名稱解析為私有位址的代理伺服器。訊息會命名要新增的確切 `NO_PROXY` 項目 |411| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於 gateway 主機，且代理伺服器的主機名稱解析為公開位址。主機名稱只解析為私有位址的代理伺服器是允許的，不會觸發此錯誤 | 在開發者的機器上將 gateway 主機新增到 `NO_PROXY`，以便連線是直接的，或使用主機名稱解析為私有位址的代理伺服器。訊息會命名要新增的確切 `NO_PROXY` 項目 |

397| CLI `/login`：`Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway 位於 [`gatewayInternalNetworks`](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中宣告的區塊上，開發者的機器從該區塊外的位址到達它：VPN 位址池、容器或 WSL2 NAT 區段，或不是您的網路 | 讓開發者從您網路上的主機 OS 執行 `/login`。如果顯示的位址也是您組織自己的公開空間，請將 gateway 的項目替換為涵蓋兩者的區塊，最多 `/8`；第二個重疊項目會被拒絕 |412| CLI `/login`：`Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway 位於 [`gatewayInternalNetworks`](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中宣告的區塊上，開發者的機器從該區塊外的位址到達它：VPN 位址池、容器或 WSL2 NAT 區段，或不是您的網路 | 讓開發者從您網路上的主機 OS 執行 `/login`。如果顯示的位址也是您組織自己的公開空間，請將 gateway 的項目替換為涵蓋兩者的區塊，最多 `/8`；第二個重疊項目會被拒絕。如果沒有區塊能涵蓋兩者，請參閱[為 gateway 選擇位址](#choose-an-address-for-the-gateway) |

398| CLI `/login`：`Every address for gateway host <host> must be inside its declared network <block>, and it also resolves to <ip>` | gateway 的名稱解析為 [`gatewayInternalNetworks`](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中宣告的區塊外的位址：第二個網站，或雙堆疊名稱上的 IPv6 記錄。在宣告的區塊下，每條記錄都必須在該一個 IPv4 區塊內，包括私有和 IPv6 位址 | 在開發者機器上的 gateway 名稱只發佈區塊內的記錄，或提供單獨的僅限內部名稱 |413| CLI `/login`：`Every address for gateway host <host> must be inside its declared network <block>, and it also resolves to <ip>` | gateway 的名稱解析為 [`gatewayInternalNetworks`](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中宣告的區塊外的位址：第二個網站，或雙堆疊名稱上的 IPv6 記錄。在宣告的區塊下，每條記錄都必須在該一個 IPv4 區塊內，包括私有和 IPv6 位址 | 在開發者機器上的 gateway 名稱只發佈區塊內的記錄，或提供單獨的僅限內部名稱 |

399| CLI `/login`：`<host> is on the declared network <block>, which Claude Code checks over a direct connection, not through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於宣告區塊上的 gateway | 在開發者的機器上，新增訊息命名的 `NO_PROXY` 項目 |414| CLI `/login`：`<host> is on the declared network <block>, which Claude Code checks over a direct connection, not through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於宣告區塊上的 gateway | 在開發者的機器上，新增訊息命名的 `NO_PROXY` 項目 |

400| CLI `/login`：訊息開頭為 `gatewayInternalNetworks in managed settings` | 該值違反了[驗證規則](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)之一，訊息會命名哪一個。在您修正它之前，Claude Code 拒絕機器上的每個新 gateway `/login`，包括私有位址上的 gateway；現有登入保持工作 | 在您部署的受管設定來源中，更正訊息命名的項目，然後重新執行 `/login` |415| CLI `/login`：訊息開頭為 `gatewayInternalNetworks in managed settings` | 該值違反了[驗證規則](/docs/zh-TW/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)之一，訊息會命名哪一個。在您修正它之前，Claude Code 拒絕機器上的每個新 gateway `/login`，包括私有位址上的 gateway；現有登入保持工作 | 在您部署的受管設定來源中，更正訊息命名的項目，然後重新執行 `/login` |

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

Details

4 4

5# 在雲端使用 Claude Code5# 在雲端使用 Claude Code

6 6

~~7> 從您的瀏覽器、手機、桌面應用程式或終端在雲端執行 Claude Code 工作階段，使用 `--cloud` 和 `--teleport` 移動工作階段，以及自動修復拉取請求。~~7> 從您的瀏覽器、手機、桌面應用程式或終端機在雲端執行 Claude Code 工作階段，使用 `--cloud` 和 `--teleport` 移動工作階段，以及自動修復 pull request。

8 8

9<Note>9<Note>

10 雲端工作階段適用於 Pro、Max 和 Team 方案，以及具有高級席位或 Chat + Claude Code 席位的 Enterprise 使用者。10 雲端工作階段適用於 Pro、Max 和 Team 方案，以及具有高級席位或 Chat + Claude Code 席位的 Enterprise 使用者。

11</Note>11</Note>

12 12

13雲端工作階段是在雲端基礎設施上執行的 Claude Code 工作階段，而不是在您的機器上執行。預設情況下，它在 Anthropic 管理的基礎設施上執行，或在您的組織的[自託管環境](/docs/zh-TW/self-hosted-environments)上執行（如果路由到那裡）。工作階段在您關閉筆記型電腦後仍會繼續執行，您可以從任何裝置檢查或控制它。13雲端工作階段是在雲端基礎設施上執行的 Claude Code 工作階段，而不是在您的機器上執行。預設情況下，它在 Anthropic 管理的基礎設施上執行，或在您的組織的[自託管環境](/docs/zh-TW/self-hosted-environments)上執行（如果路由到那裡）。工作階段在您關閉筆記型電腦後仍會繼續執行，您可以從任何裝置檢查或控制它。它會與您其餘的 Claude 和 Claude Code 使用量一起計入您方案的用量上限，雲端 VM 不另外收費。

14 14

15若要讓雲端工作階段從 GitHub 複製您的程式碼並推送分支，請使用其中一種 [GitHub 連接方式](#github-authentication-options)連接 GitHub。如果您的儲存庫位於 GitLab、Bitbucket 或其他主機上，請參閱[平台限制](#limitations)以了解可用的功能。15若要讓雲端工作階段從 GitHub 複製您的程式碼並推送分支，請使用其中一種 [GitHub 連接方式](#github-authentication-options)連接 GitHub。如果您的儲存庫位於 GitLab、Bitbucket 或其他主機上，請參閱[平台限制](#limitations)以了解可用的功能。

16 16

415 415

416* **隔離的虛擬機器**：每個工作階段在隔離的 Anthropic 管理的 VM 中執行。您的組織路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段改為在您自己的基礎設施上執行，其中隔離是您的部署的責任416* **隔離的虛擬機器**：每個工作階段在隔離的 Anthropic 管理的 VM 中執行。您的組織路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段改為在您自己的基礎設施上執行，其中隔離是您的部署的責任

417* <span id="default-allowed-domains" />**網路存取控制**：在 Anthropic 託管的環境中，網路存取預設受限，可以禁用。請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)以了解存取層級、[預設允許的網域](/docs/zh-TW/cloud-environments#default-allowed-domains)，以及不通過允許清單的流量。在自託管環境中，您在自己的網路邊界限制工作階段出口。當以禁用的網路存取執行時，Claude Code 仍然可以與 Anthropic API 通訊，這可能允許資料離開 VM。417* <span id="default-allowed-domains" />**網路存取控制**：在 Anthropic 託管的環境中，網路存取預設受限，可以禁用。請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)以了解存取層級、[預設允許的網域](/docs/zh-TW/cloud-environments#default-allowed-domains)，以及不通過允許清單的流量。在自託管環境中，您在自己的網路邊界限制工作階段出口。當以禁用的網路存取執行時，Claude Code 仍然可以與 Anthropic API 通訊，這可能允許資料離開 VM。

418* **認證保護**：在 Anthropic 託管的環境中，git 認證和簽署金鑰保持在沙箱外，代理使用限定認證代表工作階段進行驗證。在自託管環境中，您的部署提供 git 認證；請參閱[配置 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)418* **憑證保護**：在 Anthropic 託管的環境中，git 憑證和簽署金鑰保持在沙箱外，代理伺服器使用限定範圍的憑證代表工作階段進行驗證。在自託管環境中，您的部署提供 git 憑證；請參閱[設定 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)

419* **網路機密**：在 Pro 和 Max 計畫的 Anthropic 託管環境中，您[新增到雲端環境](/docs/zh-TW/cloud-environments#add-api-credentials)的金鑰同樣保持在沙箱外，並在符合的請求離開工作階段後附加到這些請求上。自託管環境沒有網路機密，Team 和 Enterprise 計畫目前也尚未提供419* **網路機密**：在 Pro 和 Max 計畫的 Anthropic 託管環境中，您[新增到雲端環境](/docs/zh-TW/cloud-environments#add-network-secrets)的金鑰同樣保持在沙箱外，並在符合的請求離開工作階段後附加到這些請求上。自託管環境沒有網路機密，Team 和 Enterprise 計畫目前也尚未提供

420* **安全分析**：程式碼在隔離的工作階段環境內進行分析和修改，然後建立 PR420* **安全分析**：程式碼在隔離的工作階段環境內進行分析和修改，然後建立 PR

421 421

422<h2 id="troubleshooting">422<h2 id="troubleshooting">

491 491

492在依賴雲端工作階段進行工作流程之前，請考慮這些限制：492在依賴雲端工作階段進行工作流程之前，請考慮這些限制：

493 493

494* **速率限制**：雲端工作階段與您帳戶內所有其他 Claude 和 Claude Code 使用共享速率限制。並行執行多個任務會按比例消耗更多速率限制。雲端 VM 沒有單獨的計算費用。494* **速率限制**：雲端工作階段與您帳戶內所有其他 Claude 和 Claude Code 使用共享速率限制。並行執行多個任務會按比例消耗更多速率限制。

495* **時間限制**：Claude 執行的命令和 SessionStart hooks 有您可以變更的預設逾時，且設定指令碼只有在大約五分鐘內完成時才會被快取。請參閱[時間限制](/docs/zh-TW/cloud-environments#time-limits)495* **時間限制**：Claude 執行的命令和 SessionStart hooks 有您可以變更的預設逾時，且設定指令碼只有在大約五分鐘內完成時才會被快取。請參閱[時間限制](/docs/zh-TW/cloud-environments#time-limits)

496* **儲存庫驗證**：您只能在驗證到相同帳戶時將雲端工作階段拉入您的終端機496* **儲存庫驗證**：您只能在驗證到相同帳戶時將雲端工作階段拉入您的終端機

497* **平台限制**：儲存庫複製和拉取請求建立需要 GitHub。自託管 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體支援 Team 和 Enterprise 計畫。您可以透過設定 `CCR_FORCE_BUNDLE=1`，將 GitLab、Bitbucket 或其他非 GitHub 儲存庫作為[本機捆綁](#send-local-repositories-without-github)發送到雲端工作階段，但工作階段無法將結果推送回該遠端497* **平台限制**：儲存庫複製和拉取請求建立需要 GitHub。自託管 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體支援 Team 和 Enterprise 計畫。您可以透過設定 `CCR_FORCE_BUNDLE=1`，將 GitLab、Bitbucket 或其他非 GitHub 儲存庫作為[本機捆綁](#send-local-repositories-without-github)發送到雲端工作階段，但工作階段無法將結果推送回該遠端

claude-platform-on-aws.md +10 −3

Details

217 1. 設定 AWS 認證217 1. 設定 AWS 認證

218</h3>218</h3>

219 219

220Claude Code 支援 AWS 上的 Claude Platform 的兩種驗證方法。選擇適合您的團隊如何管理存取的方法。220Claude Code 支援 AWS 上的 Claude Platform 的兩種驗證方法。選擇適合您的團隊如何管理存取的方法：

221 221

222**選項 A：使用 SigV4 的 AWS 認證**222* [使用 SigV4 的 AWS 憑證](#use-aws-credentials-with-sigv4)：以 IAM 主體身分進行身分驗證，憑證來自標準 AWS 憑證鏈

223* [工作區 API 金鑰](#use-a-workspace-api-key)：使用您在 AWS Console 中產生的長期有效金鑰進行身分驗證

224

225<h4 id="use-aws-credentials-with-sigv4">

226 使用 SigV4 的 AWS 憑證

227</h4>

223 228

224Claude Code 使用標準 AWS 認證鏈使用 SigV4 簽署請求：環境變數、`~/.aws/credentials` 中的共享認證、IAM 角色、AWS SSO 工作階段，以及 AWS SDK 支援的任何其他來源。229Claude Code 使用標準 AWS 認證鏈使用 SigV4 簽署請求：環境變數、`~/.aws/credentials` 中的共享認證、IAM 角色、AWS SSO 工作階段，以及 AWS SDK 支援的任何其他來源。

225 230

244 249

245設定 `awsAuthRefresh` 後，執行 `/login`，選取**第三方平台**，然後在**使用第三方平台**下選取 **Claude Platform on AWS · 重新整理認證**。Claude Code 會執行已設定的命令，並重新讀取您的 AWS 認證，而無需重新啟動。250設定 `awsAuthRefresh` 後，執行 `/login`，選取**第三方平台**，然後在**使用第三方平台**下選取 **Claude Platform on AWS · 重新整理認證**。Claude Code 會執行已設定的命令，並重新讀取您的 AWS 認證，而無需重新啟動。

246 251

247**選項 B：工作區 API 金鑰**252<h4 id="use-a-workspace-api-key">

253 使用工作區 API 金鑰

254</h4>

248 255

249工作區 API 金鑰是長期有效的祕密，在您不想管理聯合 AWS 認證時很有用。在 AWS Console 中的 **Claude Platform on AWS → API keys** 下產生一個，並將其設定為 `ANTHROPIC_AWS_API_KEY`：256工作區 API 金鑰是長期有效的祕密，在您不想管理聯合 AWS 認證時很有用。在 AWS Console 中的 **Claude Platform on AWS → API keys** 下產生一個，並將其設定為 `ANTHROPIC_AWS_API_KEY`：

250 257

claude-projects.md +9 −9

Details

118 <Step title="建立 project">118 <Step title="建立 project">

119 點擊 **Create project**。project 的對話打開，底部有一個訊息框，您可以在其中描述 Claude 的工作。119 點擊 **Create project**。project 的對話打開，底部有一個訊息框，您可以在其中描述 Claude 的工作。

120 120

121 在您的第一個 project 上，除非您先發送訊息，否則 Claude 在建立 project 後會自己進行一次轉換。該轉換使用您的方案。在其中，Claude 可能會：121 在您的第一個 project 上，除非您先發送訊息，否則 Claude 在建立 project 後會自己進行一個回合。該回合使用您的方案。在其中，Claude 可能會：

122 122

123 * 啟動一個執行緒，探索儲存庫而不改變任何內容，並提議後續步驟，如果 project 有它可以讀取的儲存庫。123 * 啟動一個執行緒，探索儲存庫而不改變任何內容，並提議後續步驟，如果 project 有它可以讀取的儲存庫。

124 * 發佈從您最近的雲端工作階段中提取的 **Setup recommendations**：要添加的儲存庫、要建立的 routines 和它可以啟動的執行緒。每個推薦的儲存庫和 routine 都預設開啟。關閉您不想要的，然後點擊 **Update setup** 添加其餘部分，或忽略建議並自己描述工作。124 * 發佈從您最近的雲端工作階段中提取的 **Setup recommendations**：要添加的儲存庫、要建立的 routines 和它可以啟動的執行緒。每個推薦的儲存庫和 routine 都預設開啟。關閉您不想要的，然後點擊 **Update setup** 添加其餘部分，或忽略建議並自己描述工作。

133 133

134如果您已經有一個雲端工作階段在執行屬於 project 的工作，請打開側邊欄中工作階段的功能表，然後選擇 **Continue as project** 或 **Move to project**：134如果您已經有一個雲端工作階段在執行屬於 project 的工作，請打開側邊欄中工作階段的功能表，然後選擇 **Continue as project** 或 **Move to project**：

135 135

136* **Continue as project** 建立一個以工作階段命名的新 project 並打開它。Claude 讀取工作階段並在對話中發佈 **Setup recommendations** 供您確認。原始工作階段保留在您的工作階段清單中，如果它在轉換中途，它會繼續執行，因此如果您不想兩者同時工作，請自己停止它。如果您改為使用可能出現在雲端工作階段訊息框上方的 **Set up project** 橫幅，結果是相同的，除了工作階段的執行轉換在 project 打開後停止。136* **Continue as project** 建立一個以工作階段命名的新 project 並打開它。Claude 讀取工作階段並在對話中發佈 **Setup recommendations** 供您確認。原始工作階段保留在您的工作階段清單中，如果它在回合中途，它會繼續執行，因此如果您不想兩者同時工作，請自己停止它。如果您改為使用可能出現在雲端工作階段訊息框上方的 **Set up project** 橫幅，結果是相同的，除了工作階段正在執行的回合會在 project 打開後停止。

137* **Move to project** 將工作階段的工作帶入現有 project。它在該 project 的對話中發佈一條訊息，要求 Claude 讀取工作階段並從它停止的地方繼續，新工作在 project 自己的執行緒中繼續。原始工作階段保留在您的工作階段清單中，未改變。137* **Move to project** 將工作階段的工作帶入現有 project。它在該 project 的對話中發佈一條訊息，要求 Claude 讀取工作階段並從它停止的地方繼續，新工作在 project 自己的執行緒中繼續。原始工作階段保留在您的工作階段清單中，未改變。

138 138

139本地工作階段沒有這些選項。若要在 project 中繼續其工作，請在 project 對話中描述工作，或推送其分支、將該儲存庫添加到 project，並在任務中命名分支。139本地工作階段沒有這些選項。若要在 project 中繼續其工作，請在 project 對話中描述工作，或推送其分支、將該儲存庫添加到 project，並在任務中命名分支。

217 217

218**Overview** 窗格在對話旁邊跟蹤 project 的執行緒。它在您第一次打開新 project 時已經打開。project 標題中的 **Overview** 按鈕關閉並重新打開它，並在執行緒等待您時顯示一個點。218**Overview** 窗格在對話旁邊跟蹤 project 的執行緒。它在您第一次打開新 project 時已經打開。project 標題中的 **Overview** 按鈕關閉並重新打開它，並在執行緒等待您時顯示一個點。

219 219

220在桌面應用程式中，當 Claude 在對話中發佈、執行緒遇到錯誤或執行緒需要您的輸入時，您還會收到桌面通知，因此您不必保持 project 打開來找出。要在每次執行緒完成轉換時也收到一個，或為 project 關閉它們，請在 project 的側邊欄功能表中選擇 **Notifications**。這些通知僅限桌面：在瀏覽器中，檢查 **Overview** 按鈕上的點。220在桌面應用程式中，當 Claude 在對話中發佈、執行緒遇到錯誤或執行緒需要您的輸入時，您還會收到桌面通知，因此您不必保持 project 打開來找出。要在每次執行緒完成一個回合時也收到一個，或為 project 關閉它們，請在 project 的側邊欄功能表中選擇 **Notifications**。這些通知僅限桌面：在瀏覽器中，檢查 **Overview** 按鈕上的點。

221 221

222窗格的 **Threads** 標籤按狀態對執行緒進行分組：222窗格的 **Threads** 標籤按狀態對執行緒進行分組：

223 223

252* **Thread model** 和 **Thread effort** 適用於執行緒。要為一個任務使用不同的模型，在任務中要求它；對於已在執行的執行緒，使用該執行緒的模型選擇器。252* **Thread model** 和 **Thread effort** 適用於執行緒。要為一個任務使用不同的模型，在任務中要求它；對於已在執行的執行緒，使用該執行緒的模型選擇器。

253* **Coordinator model** 和 **Coordinator effort** 適用於 project 對話中的 Claude。253* **Coordinator model** 和 **Coordinator effort** 適用於 project 對話中的 Claude。

254 254

255您不在 project 中管理上下文視窗。執行緒自動壓縮，對話從最近的訊息、最近的執行緒和 project 記憶而不是其完整歷史工作，因此它只要 project 執行就繼續。將任何必須永遠不被丟棄的內容放在 [project 記憶](#give-a-project-standing-context) 中。如果一個執行緒超出其上下文，它會顯示 [Claude 在此轉換上用完了上下文](#context-limit)。255您不在 project 中管理上下文視窗。執行緒自動壓縮，對話從最近的訊息、最近的執行緒和 project 記憶而不是其完整歷史工作，因此它只要 project 執行就繼續。將任何必須永遠不被丟棄的內容放在 [project 記憶](#give-a-project-standing-context) 中。如果一個執行緒超出其上下文，它會顯示 [Claude ran out of context on this turn](#context-limit)。

256 256

257<h3 id="tune-how-claude-runs-a-project">257<h3 id="tune-how-claude-runs-a-project">

258 調整 Claude 執行 project 的方式258 調整 Claude 執行 project 的方式

398 398

399每個新雲端執行緒都在專案的[雲端環境](/docs/zh-TW/cloud-environments)中啟動。環境會設定執行緒可以連線到哪些網域、它們擁有哪些環境變數、哪些網路密鑰會被加入到它們的請求中，以及設定指令碼在 Claude 啟動前安裝什麼。在您於**專案設定 > 環境**中選擇環境之前，雲端執行緒使用預設的 Anthropic 託管環境。399每個新雲端執行緒都在專案的[雲端環境](/docs/zh-TW/cloud-environments)中啟動。環境會設定執行緒可以連線到哪些網域、它們擁有哪些環境變數、哪些網路密鑰會被加入到它們的請求中，以及設定指令碼在 Claude 啟動前安裝什麼。在您於**專案設定 > 環境**中選擇環境之前，雲端執行緒使用預設的 Anthropic 託管環境。

400 400

401如果雲端執行緒需要連線到內部 API 或私有套件登錄，或需要您的機器通常持有的 token，請變更環境而不是專案：請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)、[新增網路密鑰](/docs/zh-TW/cloud-environments#add-api-credentials)和[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)。401如果雲端執行緒需要連線到內部 API 或私有套件登錄，或需要您的機器通常持有的 token，請變更環境而不是專案：請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)、[新增網路密鑰](/docs/zh-TW/cloud-environments#add-network-secrets)和[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)。

402 402

403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">

404 將技能、外掛程式、連接器和工具引入執行緒404 將技能、外掛程式、連接器和工具引入執行緒

503* Projects 在 claude.ai/code、桌面應用程式和 Claude 行動應用程式中可用，不在終端機 CLI、VS Code 擴充功能或 JetBrains 外掛中，也不通過 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。503* Projects 在 claude.ai/code、桌面應用程式和 Claude 行動應用程式中可用，不在終端機 CLI、VS Code 擴充功能或 JetBrains 外掛中，也不通過 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

504* Project 執行緒是 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，或通過 [Remote Control](/docs/zh-TW/remote-control) 在您自己的機器上的工作階段，兩種情況下 Anthropic 都是模型提供者。[安全](/docs/zh-TW/security) 和 [資料使用](/docs/zh-TW/data-usage) 涵蓋了雲端工作階段如何隔離以及保留什麼，[連線和安全](/docs/zh-TW/remote-control#connection-and-security) 涵蓋了您機器上的執行緒如何連線以及儲存什麼。504* Project 執行緒是 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，或通過 [Remote Control](/docs/zh-TW/remote-control) 在您自己的機器上的工作階段，兩種情況下 Anthropic 都是模型提供者。[安全](/docs/zh-TW/security) 和 [資料使用](/docs/zh-TW/data-usage) 涵蓋了雲端工作階段如何隔離以及保留什麼，[連線和安全](/docs/zh-TW/remote-control#connection-and-security) 涵蓋了您機器上的執行緒如何連線以及儲存什麼。

505* 您無法將自己在機器上啟動的工作階段新增到 project。Project 只能通過 [Remote Control 在您的機器上執行執行緒](#run-a-thread-on-your-own-computer)到達您的機器，該部分列出了它需要的內容。505* 您無法將自己在機器上啟動的工作階段新增到 project。Project 只能通過 [Remote Control 在您的機器上執行執行緒](#run-a-thread-on-your-own-computer)到達您的機器，該部分列出了它需要的內容。

506* 雲端執行緒的沙箱在轉換之間暫停，並在執行緒繼續時恢復。如果沙箱無法恢復，執行緒從新克隆繼續，因此未提交的變更可能會遺失。在長任務上，要求 Claude 提交並推送進行中的工作。506* 雲端執行緒的沙箱在回合之間暫停，並在執行緒繼續時恢復。如果沙箱無法恢復，執行緒從新克隆繼續，因此未提交的變更可能會遺失。在長任務上，要求 Claude 提交並推送進行中的工作。

507* project 屬於一個使用者。您無法與另一個使用者共享 project 或其執行緒，執行緒記錄沒有其他雲端工作階段具有的共享選項。在測試版期間，projects 沒有組織級控制。507* project 屬於一個使用者。您無法與另一個使用者共享 project 或其執行緒，執行緒記錄沒有其他雲端工作階段具有的共享選項。在測試版期間，projects 沒有組織級控制。

508* 執行緒屬於啟動它的一個 project。您無法將執行緒移動或複製到另一個 project，或將其移出以獨立存在。[**Move to project**](#start-from-an-existing-cloud-session) 僅以另一種方式進行：它將雲端工作階段的工作帶入 project。您無法將兩個 projects 合併為一個。508* 執行緒屬於啟動它的一個 project。您無法將執行緒移動或複製到另一個 project，或將其移出以獨立存在。[**Move to project**](#start-from-an-existing-cloud-session) 僅以另一種方式進行：它將雲端工作階段的工作帶入 project。您無法將兩個 projects 合併為一個。

509 509

545* **「Unable to access your repository」**，由執行緒報告，當其克隆失敗時：GitHub 拒絕克隆、在 project 具有的名稱下找不到儲存庫，或執行緒被要求啟動的分支不存在。545* **「Unable to access your repository」**，由執行緒報告，當其克隆失敗時：GitHub 拒絕克隆、在 project 具有的名稱下找不到儲存庫，或執行緒被要求啟動的分支不存在。

546* **「Claude can't access」** 儲存庫，在您在 **New project** 對話框或 **Project settings** 中保存儲存庫時顯示。訊息繼續帶有安裝連結和重新連接連結。如果 Claude GitHub App 不在該儲存庫上，使用安裝連結，如果它是，使用重新連接連結，因為 GitHub App 可以在 GitHub 上安裝而不連結到您連接到 Claude 的帳戶。如果訊息說 GitHub App 已暫停或不包括此儲存庫，請遵循其連結到 GitHub 以修復它。546* **「Claude can't access」** 儲存庫，在您在 **New project** 對話框或 **Project settings** 中保存儲存庫時顯示。訊息繼續帶有安裝連結和重新連接連結。如果 Claude GitHub App 不在該儲存庫上，使用安裝連結，如果它是，使用重新連接連結，因為 GitHub App 可以在 GitHub 上安裝而不連結到您連接到 Claude 的帳戶。如果訊息說 GitHub App 已暫停或不包括此儲存庫，請遵循其連結到 GitHub 以修復它。

547 547

548要修復任何一個，點擊訊息提供的按鈕，例如 **Install GitHub App** 或 **Select repositories on GitHub**，然後 **Check again**。當塊在 GitHub 組織一側時，例如尚未批准應用程式的所有者或排除 Claude 的 IP 允許清單，訊息改為顯示 **See how to fix** 連結。如果沒有按鈕，請遵循 [設定 GitHub 存取](#set-up-github-access)，然後發送另一條訊息重試。548要修復任何一個，點擊訊息提供的按鈕，例如 **Install GitHub App** 或 **Select repositories on GitHub**，然後 **Check again**。當受阻的原因在 GitHub 組織一側時，例如尚未批准應用程式的所有者或排除 Claude 的 IP 允許清單，訊息改為顯示 **See how to fix** 連結。如果沒有按鈕，請遵循 [設定 GitHub 存取](#set-up-github-access)，然後發送另一條訊息重試。

549 549

550<h3 id="usage-limit-reached">550<h3 id="usage-limit-reached">

551 執行緒達到使用限制551 執行緒達到使用限制

552</h3>552</h3>

553 553

554當執行緒或 project 對話達到您方案的五小時或每週限制時，它自己保持重試並在限制重置時繼續。在它等待時，執行緒顯示 **Service is busy**，帶有「Claude is still retrying and will continue automatically。」您不需要做任何事情讓工作繼續。如果您寧願它不使用您的下一個使用視窗，點擊執行緒中的 **Stop**，或 [暫停 project](#pause-archive-or-delete-a-project) 以保持每個執行緒。routine 啟動的執行緒不等待：其轉換停止，帶有限制錯誤，您在限制重置後發送它訊息。554當執行緒或 project 對話達到您方案的五小時或每週限制時，它自己保持重試並在限制重置時繼續。在它等待時，執行緒顯示 **Service is busy**，帶有「Claude is still retrying and will continue automatically。」您不需要做任何事情讓工作繼續。如果您寧願它不使用您的下一個使用視窗，點擊執行緒中的 **Stop**，或 [暫停 project](#pause-archive-or-delete-a-project) 以擱置每個執行緒。routine 啟動的執行緒不等待：其回合會因限制錯誤而停止，您在限制重置後發送它訊息。

555 555

556[使用限制錯誤](/docs/zh-TW/errors#youve-hit-your-session-limit) 解釋了限制以及何時重置。556[使用限制錯誤](/docs/zh-TW/errors#youve-hit-your-session-limit) 解釋了限制以及何時重置。

557 557

583| 「Claude ran out of context on this turn」 | 執行緒填滿了其上下文視窗。如果訊息說執行緒在新工作階段中繼續，它自己進行；否則在 project 對話中要求 Claude 為剩餘工作啟動新執行緒 |583| 「Claude ran out of context on this turn」 | 執行緒填滿了其上下文視窗。如果訊息說執行緒在新工作階段中繼續，它自己進行；否則在 project 對話中要求 Claude 為剩餘工作啟動新執行緒 |

584| 「Couldn't start in」後面跟著您的資料夾名稱 | 您允許執行緒在您的電腦上執行，但工作階段無法在那裡啟動。當訊息下的一行給出原因時，修復它，然後要求 Claude 再次執行任務 |584| 「Couldn't start in」後面跟著您的資料夾名稱 | 您允許執行緒在您的電腦上執行，但工作階段無法在那裡啟動。當訊息下的一行給出原因時，修復它，然後要求 Claude 再次執行任務 |

585| 「Claude is out of date on your device」 | 您選擇執行執行緒的電腦具有比 v2.1.280 更舊的 Claude Code 版本。在那裡更新 Claude Code，或如果那是連接資料夾的內容，請更新桌面應用程式，然後要求 Claude 再次執行任務 |585| 「Claude is out of date on your device」 | 您選擇執行執行緒的電腦具有比 v2.1.280 更舊的 Claude Code 版本。在那裡更新 Claude Code，或如果那是連接資料夾的內容，請更新桌面應用程式，然後要求 Claude 再次執行任務 |

587 587

588<h2 id="related-resources">588<h2 id="related-resources">

589 相關資源589 相關資源

cloud-environments.md +36 −34

Details

10 雲端環境適用於 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，該功能適用於 Pro、Max 和 Team 方案，以及具有 [premium seats 或 Chat + Claude Code seats](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan) 的 Enterprise 使用者。10 雲端環境適用於 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，該功能適用於 Pro、Max 和 Team 方案，以及具有 [premium seats 或 Chat + Claude Code seats](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan) 的 Enterprise 使用者。

11</Note>11</Note>

12 12

13每個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 都在雲端環境中執行。您可以設定環境以允許或拒絕 [網路存取](#access-levels)、[為工作階段設定環境變數](#set-environment-variables)，在 Pro 和 Max 方案上儲存工作階段可使用但無法看到的 [網路機密](#add-api-credentials)，以及在 Claude 開始工作前執行 [設定指令碼](#setup-scripts)。13每個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 都在雲端環境中執行。您可以設定環境以允許或拒絕 [網路存取](#access-levels)、[為工作階段設定環境變數](#set-environment-variables)，在 Pro 和 Max 方案上儲存工作階段可使用但無法看到的 [網路機密](#add-network-secrets)，以及在 Claude 開始工作前執行 [設定指令碼](#setup-scripts)。

14 14

15相同的環境適用於您啟動雲端工作階段的任何地方：[Desktop 應用程式](/docs/zh-TW/desktop)、[Claude 行動應用程式](/docs/zh-TW/mobile)、您的瀏覽器在 [claude.ai/code](https://claude.ai/code)、終端機搭配 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud)、[routines](/docs/zh-TW/routines) 和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。這些介面中的每一個也可以路由到 [自託管環境](/docs/zh-TW/self-hosted-environments)。[可用性和限制](/docs/zh-TW/self-hosted-environments#availability-and-limitations) 涵蓋當 Claude Tag 工作階段在其中執行時 Claude 尚無法使用的內容。15相同的環境適用於您啟動雲端工作階段的任何地方：[Desktop 應用程式](/docs/zh-TW/desktop)、[Claude 行動應用程式](/docs/zh-TW/mobile)、您的瀏覽器在 [claude.ai/code](https://claude.ai/code)、終端機搭配 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud)、[routines](/docs/zh-TW/routines) 和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。這些使用介面中的每一個也可以路由到 [自託管環境](/docs/zh-TW/self-hosted-environments)。[可用性和限制](/docs/zh-TW/self-hosted-environments#availability-and-limitations) 涵蓋當 Claude Tag 工作階段在其中執行時 Claude 尚無法使用的內容。

16 16

17<Info>17<Info>

18 [Remote Control](/docs/zh-TW/remote-control) 工作階段將網頁和行動介面連接到您自己機器上的工作階段，該工作階段使用您機器的網路和檔案，而不是雲端環境。Claude Tag 頻道工作階段僅使用組織層級環境，可以是 [共用環境](#organization-shared-environments) 或 [自託管環境](/docs/zh-TW/self-hosted-environments)。18 [Remote Control](/docs/zh-TW/remote-control) 工作階段將網頁和行動介面連接到您自己機器上的工作階段，該工作階段使用您機器的網路和檔案，而不是雲端環境。Claude Tag 頻道工作階段僅使用組織層級環境，可以是 [共用環境](#organization-shared-environments) 或 [自託管環境](/docs/zh-TW/self-hosted-environments)。

44 設定您的環境44 設定您的環境

45</h2>45</h2>

46 46

47在 [claude.ai/code](https://claude.ai/code) 上建立、編輯和封存環境，您可以在 [Web 快速入門](/docs/zh-TW/web-quickstart)後或從 [Desktop 應用程式](/docs/zh-TW/desktop#cloud-sessions)的提示框中存取環境選擇器。您建立的環境是您帳戶的個人環境；由擁有者建立的[共用環境](#organization-shared-environments)會出現在相同的選擇器中。請參閱[已安裝的工具](#installed-tools)以了解無需任何設定即可使用的工具。47您可以從環境選擇器建立、編輯和封存環境，您可以在完成 [Web 快速入門](/docs/zh-TW/web-quickstart)後於 [claude.ai/code](https://claude.ai/code) 存取環境選擇器，或從 [Desktop 應用程式](/docs/zh-TW/desktop#cloud-sessions)的提示詞輸入框中存取。您建立的環境是您帳戶的個人環境；由擁有者建立的[共用環境](#organization-shared-environments)會出現在相同的選擇器中。請參閱[已安裝的工具](#installed-tools)以了解無需任何設定即可使用的工具。

48 48

49<Steps>49<Steps>

50 <Step title="開啟環境選擇器">50 <Step title="開啟環境選擇器">

51 在 [claude.ai/code](https://claude.ai/code) 上，選擇顯示目前環境名稱的雲端圖示，位於訊息框上方的列中。選擇器沒有設定頁面或直接 URL。51 在 [claude.ai/code](https://claude.ai/code) 上，選擇顯示目前環境名稱的雲端圖示，位於訊息框上方的列中。選擇器沒有設定頁面或直接 URL。

52 52

53 <Frame>53 <Frame>

54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="環境選擇器在 claude.ai/code 的訊息框上方開啟。顯示環境名稱「預設」的雲端按鈕位於訊息框上方的列中。開啟的選單列出本機列（僅顯示「下載」和「Desktop」標籤）、雲端區段（其中「預設」環境被選中並顯示核取記號，滑鼠懸停時顯示設定齒輪圖示）、「新增雲端環境」選項，以及「遠端控制」區段（包含設定說明）。" width="1672" height="682" data-path="images/cloud-environment-selector.png" />54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="環境選擇器在 claude.ai/code 的訊息框上方開啟。顯示環境名稱「預設」的雲端按鈕位於訊息框上方的列中。開啟的選單列出本機列（僅顯示「下載」和「Desktop」標籤）、雲端區段（其中「預設」環境被選中並顯示核取記號，滑鼠懸停時顯示設定齒輪圖示）、「新增雲端環境」選項，以及 Remote Control 區段（包含設定說明）。" width="1672" height="682" data-path="images/cloud-environment-selector.png" />

55 </Frame>55 </Frame>

56 </Step>56 </Step>

57 57

58 <Step title="新增或編輯環境">58 <Step title="新增或編輯環境">

59 選擇**雲端**以列出您的環境。然後選擇**新增雲端環境**，或將滑鼠懸停在現有環境上，然後選擇右側出現的設定圖示。59 選擇**雲端**以列出您的環境。然後選擇**新增雲端環境**，或將滑鼠懸停在現有環境上，然後選擇右側出現的設定圖示。

60 60

61 對話框包括名稱、網路存取層級、環境變數和設定指令碼。當您在 Pro 或 Max 方案上編輯現有的雲端環境時，對話框還包括[網路機密](#add-api-credentials)。61 對話框包括名稱、網路存取層級、環境變數和設定指令碼。當您在 Pro 或 Max 方案上編輯現有的雲端環境時，對話框還包括[網路機密](#add-network-secrets)。

62 62

63 <Frame>63 <Frame>

64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="新增雲端環境對話框。名稱欄位，預留位置為「預設」；網路存取選擇器設定為「信任」，並包含網路政策和存取層級的連結；環境變數框顯示 .env 格式的預留位置文字，並附註值對使用該環境的任何人都可見；設定指令碼框描述為 Bash 指令碼，在新工作階段啟動時執行，在 Claude Code 啟動前執行；以及「取消」和「建立環境」按鈕。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="新增雲端環境對話框。名稱欄位，預留位置為「預設」；網路存取選擇器設定為「信任」，並包含網路政策和存取層級的連結；環境變數框顯示 .env 格式的預留位置文字，並附註值對使用該環境的任何人都可見；設定指令碼框描述為 Bash 指令碼，在新工作階段啟動時執行，在 Claude Code 啟動前執行；以及「取消」和「建立環境」按鈕。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

80DATABASE_URL=postgres://localhost:5432/myapp80DATABASE_URL=postgres://localhost:5432/myapp

81```81```

82 82

83工作階段在建立時將環境的值讀入普通環境變數中，Claude 執行的任何命令都可以讀取，除了 `OTEL_*` 變數。Claude Code 使用這些變數進行自己的[遙測匯出](/docs/zh-TW/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，不會將它們傳遞給它執行的命令。83工作階段會將環境的值讀入普通環境變數中，Claude 執行的任何命令都可以讀取，除了 `OTEL_*` 變數。Claude Code 使用這些變數進行自己的[遙測匯出](/docs/zh-TW/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，不會將它們傳遞給它執行的命令。

84 84

85在 Anthropic 託管的環境中，工作階段在您建立時讀取環境的值，以及之後每次 Claude Code 在工作階段的 VM 中啟動時讀取，這發生在兩種情況下：85在 Anthropic 託管的環境中，工作階段在您建立時讀取環境的值，以及之後每次 Claude Code 在工作階段的 VM 中啟動時讀取，這發生在兩種情況下：

86 86

89 89

90編輯、新增或移除變數後，Anthropic 託管環境中的現有工作階段會保留它最後讀取的值，直到其 VM 下次被還原或重新建立，然後使用您的變更。其 VM 在工作階段閒置後會自動暫停，您無法自行暫停。若要立即使用新值，請要求 Claude 在它執行的命令上設定它，例如 `LOG_LEVEL=trace npm test`，或啟動新工作階段。90編輯、新增或移除變數後，Anthropic 託管環境中的現有工作階段會保留它最後讀取的值，直到其 VM 下次被還原或重新建立，然後使用您的變更。其 VM 在工作階段閒置後會自動暫停，您無法自行暫停。若要立即使用新值，請要求 Claude 在它執行的命令上設定它，例如 `LOG_LEVEL=trace npm test`，或啟動新工作階段。

91 91

92雲端工作階段在啟動時也會自行設定一些變數。對於 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-TW/claude-code-on-the-web#manage-context)，工作階段設定的值會覆蓋您在此新增的值，因此在此新增該金鑰沒有效果。92雲端工作階段在啟動時也會自行設定一些變數。對於 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-TW/claude-code-on-the-web#manage-context)，工作階段設定的值會覆寫您在此新增的值，因此在此新增該鍵沒有效果。

93 93

94使用該環境的任何人都可以讀取這些值。在 Pro 和 Max 方案上，對於 agent 代理伺服器可以附加到請求的金鑰，請改用[網路機密](#add-api-credentials)。[永遠不會取得機密的請求](#requests-that-never-get-the-credential)列在那裡。94使用該環境的任何人都可以讀取這些值。在 Pro 和 Max 方案上，對於 agent 代理伺服器可以附加到請求的金鑰，請改用[網路機密](#add-network-secrets)。[永遠不會取得機密的請求](#requests-that-never-get-the-credential)列在那裡。

95 95

~~96<h3 id="add-api-credentials">~~96<span id="add-api-credentials" />

98<h3 id="add-network-secrets">

97 新增網路機密99 新增網路機密

98</h3>100</h3>

99 101

156 158

157* **GitHub**：[GitHub 代理伺服器](#github-proxy)改為驗證對 GitHub 的請求，因此您不需要為其提供網路機密159* **GitHub**：[GitHub 代理伺服器](#github-proxy)改為驗證對 GitHub 的請求，因此您不需要為其提供網路機密

158* **Anthropic API 和公開套件登錄**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io` 和 `proxy.golang.org`160* **Anthropic API 和公開套件登錄**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io` 和 `proxy.golang.org`

159* **設定指令碼請求**：Claude Code 在啟動時連線到代理程式，在[設定指令碼](#setup-scripts)執行後161* **設定指令碼請求**：Claude Code 在啟動時連線到 agent 代理伺服器，這發生在[設定指令碼](#setup-scripts)執行之後

160* **Claude Code 的遙測匯出**：Claude Code 自行傳送其[遙測匯出](/docs/zh-TW/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是透過它執行的命令，該請求不會通過代理程式162* **Claude Code 的遙測匯出**：Claude Code 自行傳送其[遙測匯出](/docs/zh-TW/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是透過它執行的命令，該請求不會通過 agent 代理伺服器

161 163

162<h3 id="select-an-environment-from-the-cli">164<h3 id="select-an-environment-from-the-cli">

163 從 CLI 選擇環境165 從 CLI 選擇環境

164</h3>166</h3>

165 167

166在您的終端中執行 `/remote-env` 以選擇您從 CLI 建立的雲端工作階段的預設環境，例如 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud)。該命令開啟現有環境的選擇器，並將您的選擇儲存到[使用者設定](/docs/zh-TW/settings#where-settings-live)中的 `remote.defaultEnvironmentId` 金鑰，因此它適用於您機器上的每個專案，直到您變更它，除非在更高優先順序的[設定層](/docs/zh-TW/settings#settings-precedence)（例如儲存庫的專案設定）上設定相同的金鑰。168在您的終端機中執行 `/remote-env` 以選擇您從 CLI 建立的雲端工作階段的預設環境，例如 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud)。該命令開啟現有環境的選擇器，並將您的選擇儲存到[使用者設定](/docs/zh-TW/settings#where-settings-live)中的 `remote.defaultEnvironmentId` 鍵，因此它適用於您機器上的每個專案，直到您變更它，除非在更高優先順序的[設定層級](/docs/zh-TW/settings#settings-precedence)（例如儲存庫的專案設定）上設定相同的鍵。

167 169

168[自託管環境](/docs/zh-TW/self-hosted-environments) ID（形式為 `ccpool_...`）遵循更嚴格的來源規則。請參閱 [`remote.defaultEnvironmentId`](/docs/zh-TW/settings-reference#remote-defaultenvironmentid) 以了解 Claude Code 從中接受它的設定層。170[自託管環境](/docs/zh-TW/self-hosted-environments) ID（形式為 `ccpool_...`）遵循更嚴格的來源規則。請參閱 [`remote.defaultEnvironmentId`](/docs/zh-TW/settings-reference#remote-defaultenvironmentid) 以了解 Claude Code 從哪些設定層級接受它。

169 171

170`/remote-env` 只設定預設值：它不啟動工作階段，也無法新增或編輯環境。從[環境選擇器](#configure-your-environment)管理它們。172`/remote-env` 只設定預設值：它不啟動工作階段，也無法新增或編輯環境。從[環境選擇器](#configure-your-environment)管理它們。

171 173

180* 已在環境中執行的工作階段會繼續工作。182* 已在環境中執行的工作階段會繼續工作。

181* 環境從選擇器和 `/remote-env` 中消失，因此您無法為新工作階段選擇它。183* 環境從選擇器和 `/remote-env` 中消失，因此您無法為新工作階段選擇它。

182* 環境上的網路機密在其執行中的工作階段中保持附加。在封存前刪除您不再需要的任何機密。184* 環境上的網路機密在其執行中的工作階段中保持附加。在封存前刪除您不再需要的任何機密。

183* 沒有新工作階段可以在任何表面上的封存環境中啟動。如果環境是您儲存的 [CLI 預設](#select-an-environment-from-the-cli)，當您的清單有一個時，Claude Code 會在 Anthropic 託管環境中啟動 CLI 雲端工作階段，否則在清單中不是[遠端控制橋接環境](#the-default-environment)的第一個環境中啟動。任何明確使用環境設定的內容，例如[例行程序](/docs/zh-TW/routines#environments-and-network-access)，無法在其中啟動新工作階段。將其指向另一個環境。185* 在任何使用介面上，都沒有新工作階段可以在封存的環境中啟動。如果環境是您儲存的 [CLI 預設](#select-an-environment-from-the-cli)，當您的清單有 Anthropic 託管環境時，Claude Code 會在其中啟動 CLI 雲端工作階段，否則在清單中第一個不是 [Remote Control 橋接環境](#the-default-environment)的環境中啟動。任何明確設定使用該環境的項目，例如 [routine](/docs/zh-TW/routines#environments-and-network-access)，無法在其中啟動新工作階段。請將其指向另一個環境。

184 186

185<h3 id="organization-shared-environments">187<h3 id="organization-shared-environments">

186 組織共用環境188 組織共用環境

193擁有者以兩種方式之一將環境提供給組織：195擁有者以兩種方式之一將環境提供給組織：

194 196

195* **建立共用環境**：使用[管理設定](https://claude.ai/admin-settings)中的**雲端環境**頁面，這也是擁有者編輯和封存共用環境的地方。每個都有一個名稱、一個[網路存取層級](#access-levels)、`.env` 格式的[環境變數](#set-environment-variables)和一個[設定指令碼](#setup-scripts)。197* **建立共用環境**：使用[管理設定](https://claude.ai/admin-settings)中的**雲端環境**頁面，這也是擁有者編輯和封存共用環境的地方。每個都有一個名稱、一個[網路存取層級](#access-levels)、`.env` 格式的[環境變數](#set-environment-variables)和一個[設定指令碼](#setup-scripts)。

196* **共用個人環境**：在環境選擇器中開啟您自己的環境之一進行編輯，然後從**誰可以使用它**列共用它。環境保留其 ID，因此已使用它的工作階段和例行程序不受影響，每個成員都可以看到它並在其中啟動工作階段。198* **共用個人環境**：在環境選擇器中開啟您自己的環境之一進行編輯，然後從**誰可以使用它**列共用它。環境保留其 ID，因此已使用它的工作階段和 routine 不受影響，每個成員都可以看到它並在其中啟動工作階段。

197 199

198擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 分別選擇組織的[預設環境](#the-default-environment)。200擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 分別選擇組織的[預設環境](#the-default-environment)。

199 201

200每個成員在共用環境中的工作階段都會讀取其變數，因此不要在其中包含機密。[網路機密](#add-api-credentials)（為工作階段提供它們無法讀取的金鑰）在 Team 或 Enterprise 方案上尚不可用。202每個成員在共用環境中的工作階段都會讀取其變數，因此不要在其中包含機密。[網路機密](#add-network-secrets)（為工作階段提供它們無法讀取的金鑰）在 Team 或 Enterprise 方案上尚不可用。

201 203

202<h3 id="set-the-environment-a-claude-tag-channel-uses">204<h3 id="set-the-environment-a-claude-tag-channel-uses">

203 設定 Claude Tag 頻道使用的環境205 設定 Claude Tag 頻道使用的環境

204</h3>206</h3>

205 207

206在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 頻道中，Claude 作為您組織的共用身分工作，而不是任何成員，因此頻道工作階段只使用組織級別的環境，即共用環境或[自託管環境](/docs/zh-TW/self-hosted-environments)。若要為頻道提供不是[預先安裝](#installed-tools)的工具鏈（例如 .NET），擁有者可以從**雲端環境** admin 頁面建立[共用環境](#organization-shared-environments)，其中包含[設定指令碼](#setup-scripts)來安裝它。以兩種方式之一將頻道指向環境：208在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 頻道中，Claude 作為您組織的共用身分工作，而不是任何成員，因此頻道工作階段只使用組織層級的環境，即共用環境或[自託管環境](/docs/zh-TW/self-hosted-environments)。若要為頻道提供不是[預先安裝](#installed-tools)的工具鏈（例如 .NET），擁有者可以從**雲端環境**管理頁面建立[共用環境](#organization-shared-environments)，其中包含安裝它的[設定指令碼](#setup-scripts)。以兩種方式之一將頻道指向環境：

207 209

208* 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 將共用或自託管環境設定為組織的[預設環境](#the-default-environment)。210* 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 將共用或自託管環境設定為組織的[預設環境](#the-default-environment)。

209* 在 Claude Tag admin 設定中[將其釘選到頻道](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)。211* 在 Claude Tag 管理設定中[將其釘選到頻道](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)。

210 212

211<h2 id="network-access">213<h2 id="network-access">

212 網路存取214 網路存取

214 216

215每個環境設定一個網路存取層級，控制其工作階段可以進行的出站連線。預設層級 **Trusted** 允許套件登錄和其他[允許清單中的網域](#default-allowed-domains)；**Custom** 採用您自己的網域清單。217每個環境設定一個網路存取層級，控制其工作階段可以進行的出站連線。預設層級 **Trusted** 允許套件登錄和其他[允許清單中的網域](#default-allowed-domains)；**Custom** 採用您自己的網域清單。

216 218

217若要變更環境的網路存取，[開啟它進行編輯](#configure-your-environment)並在對話框中使用 **Network access** 選擇器。[共用環境](#organization-shared-environments)在該處以唯讀方式開啟，因此擁有者改為從[管理設定](https://claude.ai/admin-settings)中的 **Cloud environments** 頁面變更其網路存取。開啟選擇器的雲端圖示出現在[預設環境](#the-default-environment)下列出的應用程式表面上，以及在[例行編輯器](/docs/zh-TW/routines#environments-and-network-access)中；個人環境在您的 claude.ai 帳戶設定中沒有單獨的頁面。219若要變更環境的網路存取，[開啟它進行編輯](#configure-your-environment)並在對話框中使用 **Network access** 選擇器。[共用環境](#organization-shared-environments)在該處以唯讀方式開啟，因此擁有者改為從[管理設定](https://claude.ai/admin-settings)中的 **Cloud environments** 頁面變更其網路存取。開啟選擇器的雲端圖示出現在[預設環境](#the-default-environment)下列出的應用程式使用介面上，以及在 [routine 編輯器](/docs/zh-TW/routines#environments-and-network-access)中；個人環境在您的 claude.ai 帳戶設定中沒有單獨的頁面。

218 220

219當您變更 Anthropic 託管環境的網路存取時，其現有工作階段在約一分鐘內遵循新設定，用於通過工作階段的[網路允許清單](#access-levels)的請求。您不需要啟動新的工作階段。221當您變更 Anthropic 託管環境的網路存取時，其現有工作階段在約一分鐘內遵循新設定，用於通過工作階段的[網路允許清單](#access-levels)的請求。您不需要啟動新的工作階段。

220 222

221<Note>223<Note>

222 您在工作階段或例行上啟用的 MCP 連接器無需將其主機新增到 **Allowed domains**，因為連接器流量通過 Anthropic 的伺服器而不是工作階段的網路。這依賴於[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下提到的相同 Anthropic 繫結通道。關閉任何您不需要的連接器，以限制 Claude 可以到達的工具。224 您在工作階段或 routine 上啟用的 MCP 連接器無需將其主機新增到 **Allowed domains**，因為連接器流量通過 Anthropic 的伺服器而不是工作階段的網路。這依賴於[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下提到的相同 Anthropic 繫結通道。關閉任何您不需要的連接器，以限制 Claude 可以到達的工具。

223</Note>225</Note>

224 226

225<h3 id="access-levels">227<h3 id="access-levels">

237 239

238無論您選擇哪個層級，工作階段仍然可以到達這些，因為每個都採用不通過工作階段網路允許清單的路徑：240無論您選擇哪個層級，工作階段仍然可以到達這些，因為每個都採用不通過工作階段網路允許清單的路徑：

239 241

240* GitHub，透過其[單獨的代理](#github-proxy)242* GitHub，透過其[單獨的代理伺服器](#github-proxy)

241* 您啟用的 [MCP 連接器](#network-access)，其流量通過 Anthropic 的伺服器243* 您啟用的 [MCP 連接器](#network-access)，其流量通過 Anthropic 的伺服器

242* 您在環境的[網路密鑰](#add-api-credentials)上列出的主機，除了[永遠不會取得密鑰的主機](#requests-that-never-get-the-credential)244* 您在環境的[網路密鑰](#add-network-secrets)上列出的主機，除了[永遠不會取得密鑰的主機](#requests-that-never-get-the-credential)

243* Anthropic API，用於 Claude Code 自己的請求，即使在 **None** 時，如[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下所述245* Anthropic API，用於 Claude Code 自己的請求，即使在 **None** 時，如[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下所述

244 246

245<h3 id="allow-specific-domains">247<h3 id="allow-specific-domains">

254registry.example.com256registry.example.com

255```257```

256 258

257此環境中的工作階段現在可以到達 `api.example.com`、`internal.example.com` 的任何子網域和 `registry.example.com`，以及透過工作階段網路沒有其他網域。[GitHub 流量](#github-proxy)、[MCP 連接器流量](#network-access)和對環境[網路密鑰](#add-api-credentials)主機的請求（除了[永遠不會取得密鑰的主機](#requests-that-never-get-the-credential)）不通過此允許清單。前導 `*.` 符合每個子網域。若要也保留[Trusted 網域](#default-allowed-domains)，請勾選 **Also include default list of common package managers**；取消勾選以僅允許您列出的內容。259此環境中的工作階段現在可以到達 `api.example.com`、`internal.example.com` 的任何子網域和 `registry.example.com`，以及透過工作階段網路沒有其他網域。[GitHub 流量](#github-proxy)、[MCP 連接器流量](#network-access)和對環境[網路密鑰](#add-network-secrets)主機的請求（除了[永遠不會取得密鑰的主機](#requests-that-never-get-the-credential)）不通過此允許清單。前導 `*.` 符合每個子網域。若要也保留[Trusted 網域](#default-allowed-domains)，請勾選 **Also include default list of common package managers**；取消勾選以僅允許您列出的內容。

258 260

259如果您的組織使用[成品](/docs/zh-TW/artifacts#availability)，工作階段讀取它們不需要 `*.frame.claudeusercontent.com` 在清單中。當清單省略該主機時，Claude Code 改為透過工作階段與 Anthropic 的連線讀取成品內容。在兩種情況下將主機保留在允許清單中：261如果您的組織使用 [artifact](/docs/zh-TW/artifacts#availability)，工作階段讀取它們不需要 `*.frame.claudeusercontent.com` 在清單中。當清單省略該主機時，Claude Code 改為透過工作階段與 Anthropic 的連線讀取 artifact 內容。在兩種情況下將主機保留在允許清單中：

260 262

261* **此環境中的工作階段開啟另一個組織的公開成品**：Claude Code 直接從主機擷取這些，因此將其新增到此清單。263* **此環境中的工作階段開啟另一個組織的公開 artifact**：Claude Code 直接從主機擷取這些，因此將其新增到此清單。

262* **您正在設定本機 CLI 或自託管執行器**：將主機保留在該允許清單中。請參閱[網路存取需求](/docs/zh-TW/network-config#network-access-requirements)和自託管[網路需求](/docs/zh-TW/self-hosted-environments-deploy#network-requirements)。264* **您正在設定本機 CLI 或自託管執行器**：將主機保留在該允許清單中。請參閱[網路存取需求](/docs/zh-TW/network-config#network-access-requirements)和自託管[網路需求](/docs/zh-TW/self-hosted-environments-deploy#network-requirements)。

263 265

264每個環境都有自己的允許網域清單；沒有組織層級的允許清單，管理員可以推送到每個成員的環境。沒有[伺服器管理的設定](/docs/zh-TW/server-managed-settings)將網域新增到環境的網路允許清單。若要為團隊提供一個標準清單，擁有者可以建立一個具有 **Custom** 網路存取和該清單的[組織共用環境](#organization-shared-environments)。266每個環境都有自己的允許網域清單；沒有組織層級的允許清單，管理員可以推送到每個成員的環境。沒有[伺服器管理的設定](/docs/zh-TW/server-managed-settings)將網域新增到環境的網路允許清單。若要為團隊提供一個標準清單，擁有者可以建立一個具有 **Custom** 網路存取和該清單的[組織共用環境](#organization-shared-environments)。

265 267

266<h3 id="github-proxy">268<h3 id="github-proxy">

267 GitHub 代理269 GitHub 代理伺服器

268</h3>270</h3>

269 271

270在 Anthropic 託管的環境中，所有 GitHub 操作都通過專用代理進行，該代理將您的真實 GitHub 認證保留在工作階段的 VM 外，獨立於環境的[存取層級](#access-levels)。自託管環境中的工作階段使用您的部署提供的認證進行 git 操作驗證；[設定 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git) 涵蓋選項，包括每個工作階段鑄造的認證和選擇加入此相同代理。代理提供：272在 Anthropic 託管的環境中，所有 GitHub 操作都通過專用代理伺服器進行，該代理伺服器將您的真實 GitHub 憑證保留在工作階段的 VM 外，獨立於環境的[存取層級](#access-levels)。自託管環境中的工作階段使用您的部署提供的憑證進行 git 操作驗證；[設定 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git) 涵蓋選項，包括每個工作階段鑄造的憑證和選擇加入此相同代理伺服器。代理伺服器提供：

271 273

272* **Git 認證**：VM 內的 git 用戶端使用範圍認證，代理驗證並將其交換為您的實際 GitHub 令牌。274* **Git 憑證**：VM 內的 git 用戶端使用範圍憑證，代理伺服器驗證並將其交換為您的實際 GitHub token。

273* **API 請求**：來自內建 GitHub 工具的請求，以及來自 [`proxy-injected` 預留位置](#work-with-github-issues-and-pull-requests)下的 `gh` 的請求，使用您的真實認證進行。275* **API 請求**：來自內建 GitHub 工具的請求，以及來自 [`proxy-injected` 預留位置](#work-with-github-issues-and-pull-requests)下的 `gh` 的請求，使用您的真實憑證進行。

274* **推送限制**：代理伺服器會拒絕分支刪除，以及推送分支以外的任何內容（例如標籤）。它不限制推送可以更新哪些分支。若要進行此限制，請在 GitHub 上使用分支保護規則或規則集。276* **推送限制**：代理伺服器會拒絕分支刪除，以及推送分支以外的任何內容（例如標籤）。它不限制推送可以更新哪些分支。若要進行此限制，請在 GitHub 上使用分支保護規則或規則集。

275* **儲存庫範圍**：代理伺服器僅為附加到工作階段的儲存庫提供 GitHub API 請求服務。針對其他儲存庫的 API 請求會收到 403，其訊息以 `GitHub access to` 開頭並包含 `is not enabled for this session`。277* **儲存庫範圍**：代理伺服器僅為附加到工作階段的儲存庫提供 GitHub API 請求服務。針對其他儲存庫的 API 請求會收到 403，其訊息以 `GitHub access to` 開頭並包含 `is not enabled for this session`。

276* **GraphQL 限制**：代理伺服器會以 403 拒絕對 GitHub GraphQL 端點的請求，其訊息以 `GitHub GraphQL is not available from Claude Code sessions` 開頭，並指出 REST 備援 `gh api repos/{owner}/{repo}/...`。使用 GraphQL 的 `gh` 子命令（例如 `gh pr` 和 `gh issue`）會收到相同的 403。限制適用於通過代理伺服器的每個請求，無論您提供的憑證如何，因此您設定的 `GH_TOKEN` 會收到相同的 403。Claude 無法通過代理伺服器到達僅存在於 GraphQL 中的 GitHub API，例如 Projects v2。278* **GraphQL 限制**：代理伺服器會以 403 拒絕對 GitHub GraphQL 端點的請求，其訊息以 `GitHub GraphQL is not available from Claude Code sessions` 開頭，並指出 REST 備援 `gh api repos/{owner}/{repo}/...`。使用 GraphQL 的 `gh` 子命令（例如 `gh pr` 和 `gh issue`）會收到相同的 403。限制適用於通過代理伺服器的每個請求，無論您提供的憑證如何，因此您設定的 `GH_TOKEN` 會收到相同的 403。Claude 無法通過代理伺服器到達僅存在於 GraphQL 中的 GitHub API，例如 Projects v2。

277 279

278來自公開儲存庫的已提交檔案通過 `raw.githubusercontent.com` 到達，[安全代理](#security-proxy)改為處理。該網域在預設[Trusted 清單](#default-allowed-domains)中，因此除非環境的[存取層級](#access-levels)排除它，否則這些檔案保持可到達。280來自公開儲存庫的已提交檔案通過 `raw.githubusercontent.com` 到達，[安全代理伺服器](#security-proxy)改為處理。該網域在預設[Trusted 清單](#default-allowed-domains)中，因此除非環境的[存取層級](#access-levels)排除它，否則這些檔案保持可到達。

279 281

280<h3 id="security-proxy">282<h3 id="security-proxy">

281 安全代理283 安全代理伺服器

282</h3>284</h3>

283 285

284Anthropic 託管環境中的雲端工作階段在 HTTP/HTTPS 網路代理後面執行，用於安全和濫用防止目的；在[自託管環境](/docs/zh-TW/self-hosted-environments-deploy#default-deny-egress)中，出站流量改為通過您自己的網路邊界。來自 Anthropic 託管工作階段的所有出站網際網路流量都通過此代理，該代理提供：286Anthropic 託管環境中的雲端工作階段在 HTTP/HTTPS 網路代理伺服器後面執行，用於安全和濫用防止目的；在[自託管環境](/docs/zh-TW/self-hosted-environments-deploy#default-deny-egress)中，出站流量改為通過您自己的網路邊界。來自 Anthropic 託管工作階段的所有出站網際網路流量都通過此代理伺服器，該代理伺服器提供：

285 287

286* 防止惡意請求288* 防止惡意請求

287* 速率限制和濫用防止289* 速率限制和濫用防止

316| 僅在您的使用者設定中啟用的外掛程式 | 否 | 使用者範圍的 `enabledPlugins` 位於您機器上的 `~/.claude/settings.json` 中 |318| 僅在您的使用者設定中啟用的外掛程式 | 否 | 使用者範圍的 `enabledPlugins` 位於您機器上的 `~/.claude/settings.json` 中 |

317| 您使用 `claude mcp add` 在預設本機範圍或使用者範圍新增的 MCP 伺服器 | 否 | 這些寫入您機器上的 `~/.claude.json`，不是儲存庫。使用 `claude mcp add --scope project` 新增伺服器，它會寫入儲存庫的 [`.mcp.json`](/docs/zh-TW/mcp#project-scope)，並提交該檔案。具有一個儲存庫的工作階段會載入它 |319| 您使用 `claude mcp add` 在預設本機範圍或使用者範圍新增的 MCP 伺服器 | 否 | 這些寫入您機器上的 `~/.claude.json`，不是儲存庫。使用 `claude mcp add --scope project` 新增伺服器，它會寫入儲存庫的 [`.mcp.json`](/docs/zh-TW/mcp#project-scope)，並提交該檔案。具有一個儲存庫的工作階段會載入它 |

318| 您儲存庫的 `.claude/settings.json` `env` 區塊中的傳輸變數，例如 `NODE_EXTRA_CA_CERTS` 和[mTLS 用戶端憑證變數](/docs/zh-TW/network-config#mtls-authentication) | 否 | 代管環境管理工作階段的 API 連線，因此 Claude Code 會忽略這些金鑰，並在工作階段的偵錯日誌中記錄每個被忽略的金鑰 |320| 您儲存庫的 `.claude/settings.json` `env` 區塊中的傳輸變數，例如 `NODE_EXTRA_CA_CERTS` 和[mTLS 用戶端憑證變數](/docs/zh-TW/network-config#mtls-authentication) | 否 | 代管環境管理工作階段的 API 連線，因此 Claude Code 會忽略這些金鑰，並在工作階段的偵錯日誌中記錄每個被忽略的金鑰 |

319| Claude 呼叫的服務的 API 金鑰和 token | 在 Pro 和 Max 方案上，作為[網路機密](#add-api-credentials) | 您在環境上新增金鑰一次，agent 代理伺服器會將其附加到您列出的主機的請求。agent 代理伺服器[無法附加](#requests-that-never-get-the-credential)的金鑰，或 Team 或 Enterprise 方案上的任何金鑰，都保留在環境變數中 |321| Claude 呼叫的服務的 API 金鑰和 token | 在 Pro 和 Max 方案上，作為[網路機密](#add-network-secrets) | 您在環境上新增金鑰一次，agent 代理伺服器會將其附加到您列出的主機的請求。agent 代理伺服器[無法附加](#requests-that-never-get-the-credential)的金鑰，或 Team 或 Enterprise 方案上的任何金鑰，都保留在環境變數中 |

320| 像 AWS SSO 這樣的互動式驗證 | 否 | 不支援。SSO 需要無法在雲端工作階段中執行的瀏覽器型登入 |322| 像 AWS SSO 這樣的互動式驗證 | 否 | 不支援。SSO 需要無法在雲端工作階段中執行的瀏覽器型登入 |

321 323

322若要在雲端工作階段中提供您自己的設定，請將其提交到儲存庫。324若要在雲端工作階段中提供您自己的設定，請將其提交到儲存庫。

323 325

324任何使用環境的人都可以讀取其環境變數和設定指令碼。**環境變數**下的對話方塊註記會說明這一點，並警告不要在那裡放置機密。在 Pro 和 Max 方案上，改為將 agent 代理伺服器可以附加的金鑰儲存為[網路機密](#add-api-credentials)。326任何使用環境的人都可以讀取其環境變數和設定指令碼。**環境變數**下的對話方塊註記會說明這一點，並警告不要在那裡放置機密。在 Pro 和 Max 方案上，改為將 agent 代理伺服器可以附加的金鑰儲存為[網路機密](#add-network-secrets)。

325 327

326<h4 id="add-personal-preferences-without-committing-to-the-repo">328<h4 id="add-personal-preferences-without-committing-to-the-repo">

327 在不提交到儲存庫的情況下新增個人偏好設定329 在不提交到儲存庫的情況下新增個人偏好設定

commands.md +1 −1

Details

87| `/design-sync [hint]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 轉換您的儲存庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它生成的設計使用您的真實元件。可選地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型儲存庫上可能需要幾個小時。在 Anthropic API 上可用。它需要 claude.ai，而 CLI 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上，或通過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway#availability-and-limitations)時不會聯絡它，因此命令在那裡不可用 |87| `/design-sync [hint]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 轉換您的儲存庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它生成的設計使用您的真實元件。可選地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型儲存庫上可能需要幾個小時。在 Anthropic API 上可用。它需要 claude.ai，而 CLI 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上，或通過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway#availability-and-limitations)時不會聯絡它，因此命令在那裡不可用 |

88| `/desktop` | 在 Claude Code Desktop 應用程式中繼續目前工作階段。需要 macOS 或 x64 Windows 以及 Claude 訂閱。別名：`/app` |88| `/desktop` | 在 Claude Code Desktop 應用程式中繼續目前工作階段。需要 macOS 或 x64 Windows 以及 Claude 訂閱。別名：`/app` |

89| `/diff` | 檢查工作樹中的變更，包括 Claude 到目前為止所做的編輯。請參閱[使用 /diff 檢查變更](/docs/zh-TW/interactive-mode#review-changes-with-%2Fdiff) |89| `/diff` | 檢查工作樹中的變更，包括 Claude 到目前為止所做的編輯。請參閱[使用 /diff 檢查變更](/docs/zh-TW/interactive-mode#review-changes-with-%2Fdiff) |

90| `/doctor [prompt-audit [path]]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 運行設定檢查以診斷問題並可修復它們。檢查安裝健康狀況，包括重複或遺留的安裝、`PATH` 問題和無法解析的設定檔。查找未使用的 skill、MCP 伺服器和外掛與其上下文成本，標記緩慢的 [hook](/docs/zh-TW/hooks)，並檢查您的[發布通道](/docs/zh-TW/setup#configure-release-channel)上是否有較新版本。根據簽入的檔案對本地 `CLAUDE.md` 檔案進行重複資料刪除，通過切割 Claude 可以從程式碼庫衍生的內容來修剪簽入的 [`CLAUDE.md`](/docs/zh-TW/memory#my-claude-md-is-too-large) 檔案，並將保留的始終載入的指導遷移到 [skill](/docs/zh-TW/skills) 和按需載入的嵌套 `CLAUDE.md` 檔案中。還提供使[自動模式](/docs/zh-TW/permissions#permission-modes)成為您的預設值的選項，以及[預先批准](/docs/zh-TW/permissions)經常被拒絕的唯讀命令。首先報告發現並在進行任何變更前要求確認。從終端機，`claude doctor` 列印唯讀安裝診斷而不啟動工作階段。別名：`/checkup`。運行 `/doctor prompt-audit` 以讓 Claude [審計您的 `CLAUDE.md` 檔案、skill 和其他設定](/docs/zh-TW/memory#audit-your-instruction-files)以查找過時或衝突的指示，而不是運行檢查。`prompt-audit` 子命令需要 Claude Code v2.1.283 或更新版本。`CLAUDE.md` 修剪檢查需要 Claude Code v2.1.206 或更新版本。在 v2.1.205 之前，`/doctor` 打開唯讀診斷螢幕，按 `f` 將報告發送給 Claude |90| `/doctor [prompt-audit [path]]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 運行設定檢查，診斷安裝、設定、擴充功能和 `CLAUDE.md` 問題，並提出修復建議，Claude 會在您確認後應用這些修復。有關檢查涵蓋的內容，或改用 `prompt-audit` 審計您的指示，請參閱[使用 `/doctor` 檢查您的設定](/docs/zh-TW/skills#check-your-setup-with-/doctor)。`prompt-audit` 子命令需要 Claude Code v2.1.283 或更新版本。別名：`/checkup` |

91| `/effort [level\|auto\|status\|ultracode [on\|off]]` | 設定 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)：`low` 到 `xhigh`、`max` 或 `auto`；`status` 列印它。`ultracode` 或 `ultracode on` 在目前等級為工作階段打開 [ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)，`ultracode off` 關閉它；[`ultracode`](/docs/zh-TW/settings-reference#ultracode) 鍵持續存在。`max` 僅限工作階段。`on` 和 `off` 引數以及保持目前等級需要 Claude Code v2.1.284 或更新版本。在 v2.1.284 之前，`/effort ultracode` 將工作階段設定為 `xhigh`，`/effort ultracode off` 失敗並出現 `Invalid argument`。在 Claude 回應時運行它，一旦您確認[快取警告](/docs/zh-TW/prompt-caching#changing-effort-level)（如果 Claude Code 顯示一個），Claude Code 會將新等級應用於該回合中的下一個請求。在 v2.1.242 之前，Claude Code 從它從 Anthropic 擷取的功能旗標決定是在回合中途運行命令還是將其排隊直到該回合完成，並始終在不[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中排隊，例如在[第三方提供者](/docs/zh-TW/third-party-integrations)上。在 `-p` 中工作 |91| `/effort [level\|auto\|status\|ultracode [on\|off]]` | 設定 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)：`low` 到 `xhigh`、`max` 或 `auto`；`status` 列印它。`ultracode` 或 `ultracode on` 在目前等級為工作階段打開 [ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)，`ultracode off` 關閉它；[`ultracode`](/docs/zh-TW/settings-reference#ultracode) 鍵持續存在。`max` 僅限工作階段。`on` 和 `off` 引數以及保持目前等級需要 Claude Code v2.1.284 或更新版本。在 v2.1.284 之前，`/effort ultracode` 將工作階段設定為 `xhigh`，`/effort ultracode off` 失敗並出現 `Invalid argument`。在 Claude 回應時運行它，一旦您確認[快取警告](/docs/zh-TW/prompt-caching#changing-effort-level)（如果 Claude Code 顯示一個），Claude Code 會將新等級應用於該回合中的下一個請求。在 v2.1.242 之前，Claude Code 從它從 Anthropic 擷取的功能旗標決定是在回合中途運行命令還是將其排隊直到該回合完成，並始終在不[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中排隊，例如在[第三方提供者](/docs/zh-TW/third-party-integrations)上。在 `-p` 中工作 |

92| `/exit` | 退出 CLI。在附加的[背景工作階段](/docs/zh-TW/agent-view#attach-to-a-session)中，這會分離並且工作階段保持運行。別名：`/quit` |92| `/exit` | 退出 CLI。在附加的[背景工作階段](/docs/zh-TW/agent-view#attach-to-a-session)中，這會分離並且工作階段保持運行。別名：`/quit` |

93| `/export [filename]` | 將目前對話匯出為純文字。使用檔案名，直接寫入該檔案。沒有，打開對話框以複製到剪貼簿或保存到檔案 |93| `/export [filename]` | 將目前對話匯出為純文字。使用檔案名，直接寫入該檔案。沒有，打開對話框以複製到剪貼簿或保存到檔案 |

common-workflows.md +2 −3

Details

391 Explain the logic in @src/utils/auth.js391 Explain the logic in @src/utils/auth.js

392 ```392 ```

393 393

394 這會在對話中包含檔案的完整內容。394 當檔案符合 [Read 工具](/docs/zh-TW/tools-reference#read-tool-behavior)的 token 限制（預設為 25,000 個 token）時，這會在對話中包含檔案的內容。大於 256KB 的文字檔案不會被包含。

395 </Step>395 </Step>

396 396

397 <Step title="參考目錄">397 <Step title="參考目錄">

446 詢問 Claude 其功能446 詢問 Claude 其功能

447</h3>447</h3>

448 448

449Claude 內建存取其文件，可以回答有關其自身功能和限制的問題。449Claude 可以回答有關其自身功能和限制的問題。它會在當前的 Claude Code 文件中查找答案，因此答案不受限於您正在執行的版本。

450 450

451<h4 id="example-questions">451<h4 id="example-questions">

452 範例問題452 範例問題

483<Tip>483<Tip>

484 提示：484 提示：

485 485

486 * Claude 始終可以存取最新的 Claude Code 文件，無論您使用的版本如何

487 * 提出具體問題以獲得詳細答案486 * 提出具體問題以獲得詳細答案

488 * Claude 可以解釋複雜的功能，如 MCP 整合、企業設定和進階工作流程487 * Claude 可以解釋複雜的功能，如 MCP 整合、企業設定和進階工作流程

489</Tip>488</Tip>

context-window.md +0 −2

Details

1634 1634

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

1636 1636

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

~~1638~~

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

1640 1638

1641<h2 id="check-your-own-session">1639<h2 id="check-your-own-session">

corporate-launcher.md +1 −0

Details

128* **在啟動程式每次執行時約三秒內到達 `exec`。** 冷背景分派在第一個輸出位元組前連續執行啟動程式兩次，因此請懶惰地或從快取執行緩慢的工作，例如單一登入交換。128* **在啟動程式每次執行時約三秒內到達 `exec`。** 冷背景分派在第一個輸出位元組前連續執行啟動程式兩次，因此請懶惰地或從快取執行緩慢的工作，例如單一登入交換。

129* **容忍從內部叫用自身。** Claude Code 將啟動程式應用於每個嵌套的自我產生，因此獲取獨佔資源的啟動程式必須偵測它是否已持有它。129* **容忍從內部叫用自身。** Claude Code 將啟動程式應用於每個嵌套的自我產生，因此獲取獨佔資源的啟動程式必須偵測它是否已持有它。

130* **在 Claude Code 啟動前不要寫入終端。** 在 `exec` 前列印的任何內容都會在工作階段在初始化前死亡時報告為當機原因。130* **在 Claude Code 啟動前不要寫入終端。** 在 `exec` 前列印的任何內容都會在工作階段在初始化前死亡時報告為當機原因。

131* **不要依賴引數的拼寫方式。** 旗標的值可能作為獨立的引數傳入（`--flag value`），也可能與旗標連接在一起（`--flag=value`）。旗標使用哪種形式可能會在不同版本之間變更。

131 132

132<h3 id="format-of-the-launcher-value">133<h3 id="format-of-the-launcher-value">

133 啟動程式值的格式134 啟動程式值的格式

debug-your-config.md +12 −1

Details

85 針對乾淨的設定進行測試85 針對乾淨的設定進行測試

86</h2>86</h2>

87 87

88使用 [`claude --safe-mode`](/docs/zh-TW/cli-reference#cli-flags) 開始，它會啟動一個工作階段，其中所有自訂項目都被停用，包括 `CLAUDE.md`、skills、plugins、hooks、MCP servers 和自訂命令與代理程式。驗證、模型選擇、內建工具和權限正常運作。如果問題在安全模式中消失，則其中一個表面是原因；使用上面的目標檢查來找出是哪一個。安全模式仍然會套用來自您組織的受管 hooks 和設定原則。受管 plugins、skills、`CLAUDE.md` 和 MCP servers 會被關閉。88使用 [`claude --safe-mode`](/docs/zh-TW/cli-reference#cli-flags) 開始，它會啟動一個停用您自訂項目的工作階段，包括：

90* `CLAUDE.md`

91* Skills、外掛和 hook

92* MCP 伺服器

93* 自訂命令和 agent

94* 自訂輸出風格

95* 自訂快捷鍵

97身分驗證、模型選擇、內建工具和權限正常運作。如果問題在安全模式中消失，表示您已將原因縮小到您關閉的其中一個項目。若要找出是哪一個，請使用該項目對應的檢查，例如[查看載入到上下文中的內容](#see-what-loaded-into-context)、[檢查 MCP 伺服器](#check-mcp-servers)或[檢查 hook](#check-hooks)。

99安全模式仍然會套用來自您組織的受管 hook 和設定原則。受管外掛、skills、`CLAUDE.md` 和 MCP 伺服器會被關閉。

89 100

90如果問題在安全模式中持續存在，或您的設定本身令人懷疑，請與不從您常用設定載入任何內容的工作階段進行比較。將 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 指向空目錄以略過 `~/.claude` 下的所有內容，並從沒有 `.claude` 資料夾、`.mcp.json` 或 `CLAUDE.md` 的目錄啟動，以便也跳過專案設定。101如果問題在安全模式中持續存在，或您的設定本身令人懷疑，請與不從您常用設定載入任何內容的工作階段進行比較。將 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 指向空目錄以略過 `~/.claude` 下的所有內容，並從沒有 `.claude` 資料夾、`.mcp.json` 或 `CLAUDE.md` 的目錄啟動，以便也跳過專案設定。

91 102

desktop.md +115 −67

Details

60提供 Claude 正確的背景資訊、控制它自主執行的程度，並檢查它所做的變更。60提供 Claude 正確的背景資訊、控制它自主執行的程度，並檢查它所做的變更。

61 61

62<h3 id="use-the-prompt-box">62<h3 id="use-the-prompt-box">

~~63 使用提示框~~63 使用提示詞輸入框

64</h3>64</h3>

65 65

66輸入您想讓 Claude 執行的操作，然後按 **Enter** 鍵傳送。Claude 會讀取您的專案檔案、進行變更，並根據您的[權限模式](#choose-a-permission-mode)執行命令。您可以隨時重新導向 Claude：點擊停止按鈕立即中斷，或輸入更正並按 **Enter** 鍵傳送，無需停止執行中的操作。Claude 會在目前操作完成後立即讀取更正，並在下一步之前進行調整。66輸入您想讓 Claude 執行的操作，然後按 **Enter** 鍵傳送。Claude 會讀取您的專案檔案、進行變更，並根據您的[權限模式](#choose-a-permission-mode)執行命令。您可以隨時重新導向 Claude：點擊停止按鈕立即中斷，或輸入更正並按 **Enter** 鍵傳送，無需停止執行中的操作。Claude 會在目前操作完成後立即讀取更正，並在下一步之前進行調整。

67 67

~~68提示框旁的 **+** 按鈕可讓您存取檔案附件、[skills](#use-skills)、[connectors](#connect-external-tools) 和 [plugins](#install-plugins)。~~68提示詞輸入框旁的 **+** 按鈕可讓您存取檔案附件、[skills](#use-skills)、[connectors](#connect-external-tools) 和 [plugins](#install-plugins)。

70<h3 id="accept-a-suggested-prompt">

71 接受建議的提示詞

72</h3>

74Claude 回覆後，Code 標籤可能會在空白的提示詞輸入框中以灰色文字顯示建議的下一個提示詞。Claude Code 會透過一個簡短的背景請求，根據您的對話[產生每個建議](/docs/zh-TW/interactive-mode#prompt-suggestions)，此請求會計入您方案的用量上限或您的 API 費用。

76* **使用建議**：按 **Tab** 或**向右鍵**將其放入提示詞輸入框，視需要進行編輯，然後按 **Enter** 傳送。在接受建議之前按 **Enter** 不會傳送該建議。

77* **撰寫您自己的提示詞**：直接開始輸入。建議只會在提示詞輸入框為空且沒有附加檔案時顯示。

79前往**設定 > Claude Code**，並在**工作階段**下關閉**提示詞建議**，即可讓每個工作階段從下次啟動或繼續時起不再顯示建議。

69 80

70<h3 id="add-files-and-context-to-prompts">81<h3 id="add-files-and-context-to-prompts">

~~71 將檔案和背景資訊新增至提示~~82 將檔案和背景資訊新增至提示詞

72</h3>83</h3>

73 84

~~74提示框支援兩種方式來引入外部背景資訊：~~85提示詞輸入框支援兩種方式來引入外部背景資訊：

75 86

76* **@mention 檔案**：輸入 `@` 後跟檔案名稱，將檔案新增至對話背景資訊。Claude 隨後可以讀取並參考該檔案。@mention 在雲端或 WSL 工作階段中不可用。87* **@mention 檔案**：輸入 `@` 後跟檔案名稱，將檔案新增至對話背景資訊。Claude 隨後可以讀取並參考該檔案。@mention 在雲端或 WSL 工作階段中不可用。

77* **附加檔案**：使用附件按鈕將影像、PDF 和其他檔案附加到您的提示，或直接將檔案拖放到提示中。這對於分享錯誤的螢幕截圖、設計模型或參考文件很有用。88* **附加檔案**：使用附件按鈕將影像、PDF 和其他檔案附加到您的提示詞，或直接將檔案拖放到提示詞中。這對於分享錯誤的螢幕截圖、設計模型或參考文件很有用。

78 89

79<h3 id="choose-a-permission-mode">90<h3 id="choose-a-permission-mode">

80 選擇權限模式91 選擇權限模式

87| 模式 | 設定鍵 | 行為 |98| 模式 | 設定鍵 | 行為 |

88| - | - | - |99| - | - | - |

89| **手動** | `default` | Claude 在編輯檔案或執行命令之前詢問。您會看到差異，並可以接受或拒絕每項變更。 |100| **手動** | `default` | Claude 在編輯檔案或執行命令之前詢問。您會看到差異，並可以接受或拒絕每項變更。 |

92| **自動** | `auto` | Claude 執行時不會出現常規提示；在殼層命令和網路請求等操作執行之前，背景分類器會檢查它們是否與您的請求一致。當[自動模式可用](#auto-mode-availability)時出現；沒有單獨的設定切換。 |103| **自動** | `auto` | Claude 執行時不會出現例行提示；在 shell 命令和網路請求等操作執行之前，背景分類器會檢查它們是否與您的請求一致。當[自動模式可用](#auto-mode-availability)時出現；沒有單獨的設定切換。 |

93| **略過權限** | `bypassPermissions` | Claude 執行時不會出現權限提示，除了[任何模式都不會自動核准的操作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)、當 Claude [在外部網站上執行操作](#browse-external-sites)時的安全分類器，或桌面操作（Claude 始終先詢問），例如[封存工作階段](#work-across-sessions)。相當於 CLI 中的 `--dangerously-skip-permissions`。在 Pro 和 Max 方案上，在您的設定 → Claude Code 中的「允許略過權限模式」下啟用它；在 Team 和 Enterprise 方案上沒有設定切換，組織政策會控制它。僅在沙箱容器或虛擬機中使用此選項。 |104| **略過權限** | `bypassPermissions` | Claude 執行時不會出現權限提示，除了[任何模式都不會自動核准的操作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)、當 Claude [在外部網站上執行操作](#browse-external-sites)時的安全分類器，或桌面操作（Claude 始終先詢問），例如[封存工作階段](#work-across-sessions)。相當於 CLI 中的 `--dangerously-skip-permissions`。在 Pro 和 Max 方案上，在您的設定 → Claude Code 中的「允許略過權限模式」下啟用它；在 Team 和 Enterprise 方案上沒有設定切換，組織政策會控制它。僅在沙箱容器或虛擬機中使用此選項。 |

94 105

95Code 標籤的早期版本將這些模式標記為「詢問權限」、「自動接受編輯」和「Plan 模式」。106Code 標籤的早期版本將這些模式標記為「詢問權限」、「自動接受編輯」和「Plan 模式」。

118 129

119Claude 可以啟動開發伺服器並在「瀏覽器」窗格中開啟它以驗證其變更。這適用於前端網路應用程式以及後端伺服器：Claude 可以測試 API 端點、檢視伺服器日誌，並對它發現的問題進行迭代。在大多數情況下，Claude 在編輯專案檔案後會自動啟動伺服器。您也可以隨時要求 Claude 進行預覽。預設情況下，Claude [自動驗證](#auto-verify-changes)每次編輯後的變更。130Claude 可以啟動開發伺服器並在「瀏覽器」窗格中開啟它以驗證其變更。這適用於前端網路應用程式以及後端伺服器：Claude 可以測試 API 端點、檢視伺服器日誌，並對它發現的問題進行迭代。在大多數情況下，Claude 在編輯專案檔案後會自動啟動伺服器。您也可以隨時要求 Claude 進行預覽。預設情況下，Claude [自動驗證](#auto-verify-changes)每次編輯後的變更。

120 131

121「瀏覽器」窗格也可以從您的專案中開啟靜態 HTML 檔案、PDF、影片和影片。在聊天中點擊 HTML、PDF、影像或影片路徑以在那裡開啟它。132「瀏覽器」窗格也可以從您的專案中開啟靜態 HTML 檔案、PDF、影像和影片。在聊天中點擊 HTML、PDF、影像或影片路徑以在那裡開啟它。

122 133

123從「瀏覽器」窗格，您可以：134從「瀏覽器」窗格，您可以：

124 135

170 使用差異檢視檢查變更181 使用差異檢視檢查變更

171</h3>182</h3>

172 183

173Claude 對您的程式碼進行變更後，差異檢視可讓您在建立提取請求之前逐個檔案檢查修改。184Claude 對您的程式碼進行變更後，差異檢視可讓您在建立 pull request 之前逐個檔案檢查修改。

174 185

175當 Claude 變更檔案時，會出現差異統計指示器，顯示新增和移除的行數，例如 `+12 -1`。點擊此指示器以開啟差異檢視器，它在左側顯示檔案清單，在右側顯示每個檔案的變更。186當 Claude 變更檔案時，會出現差異統計指示器，顯示新增和移除的行數，例如 `+12 -1`。點擊此指示器以開啟差異檢視器，它在左側顯示檔案清單，在右側顯示每個檔案的變更。

176 187

195在任何工作階段中，您也可以在提示詞輸入框中要求 Claude 修正審查發現的問題。若要了解 `/code-review` 檢查的內容及其接受的引數，請參閱[在本機審查差異](/docs/zh-TW/code-review#review-a-diff-locally)。206在任何工作階段中，您也可以在提示詞輸入框中要求 Claude 修正審查發現的問題。若要了解 `/code-review` 檢查的內容及其接受的引數，請參閱[在本機審查差異](/docs/zh-TW/code-review#review-a-diff-locally)。

196 207

197<h3 id="monitor-pull-request-status">208<h3 id="monitor-pull-request-status">

198 監控提取請求狀態209 監控 pull request 狀態

199</h3>210</h3>

200 211

201開啟提取請求後，CI 狀態列會出現在工作階段中。Claude Code 使用 GitHub CLI 輪詢檢查結果並顯示失敗。212開啟 pull request 後，CI 狀態列會出現在工作階段中。Claude Code 使用 GitHub CLI 輪詢檢查結果並顯示失敗。

202 213

203* **自動修復 CI 並處理評論**：啟用後，Claude 會自動嘗試透過讀取失敗輸出並進行迭代來修復失敗的 CI 檢查。在本機工作階段中，當作者是儲存庫擁有者、組織成員、協作者或 GitHub App 時，Claude 也會處理由您以外的人留下的新審查評論。214* **自動修復 CI 並處理評論**：啟用後，Claude 會自動嘗試透過讀取失敗輸出並進行迭代來修復失敗的 CI 檢查。在本機工作階段中，當作者是儲存庫擁有者、組織成員、協作者或 GitHub App 時，Claude 也會處理由您以外的人留下的新審查評論。

204* **就緒時自動合併**：啟用後，Claude 會在所有檢查通過後合併 PR。合併方法是壓縮。首先在您的 [GitHub 儲存庫設定](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)中啟用自動合併；沒有它，Claude 無法合併 PR。215* **就緒時自動合併**：啟用後，Claude 會在所有檢查通過後合併 PR。合併方法是壓縮。首先在您的 [GitHub 儲存庫設定](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)中啟用自動合併；沒有它，Claude 無法合併 PR。

231 開啟和編輯檔案242 開啟和編輯檔案

232</h3>243</h3>

233 244

234點擊聊天或差異檢視器中的檔案路徑以在檔案窗格中開啟它。HTML、PDF、影像和影片路徑改為在[瀏覽器窗格](#preview-your-app)中開啟。進行現場編輯並點擊 **Save** 以寫回。如果自您開啟檔案以來檔案在磁碟上已變更，窗格會警告您並讓您覆蓋或放棄。點擊 **Discard** 以還原您的編輯，或點擊窗格標題中的路徑以複製絕對路徑。245點擊聊天或差異檢視器中的檔案路徑以在檔案窗格中開啟它。HTML、PDF、影像和影片路徑改為在[瀏覽器窗格](#preview-your-app)中開啟。進行現場編輯並點擊 **Save** 以寫回。如果自您開啟檔案以來檔案在磁碟上已變更，窗格會警告您並讓您覆寫或放棄。點擊 **Discard** 以還原您的編輯，或點擊窗格標題中的路徑以複製絕對路徑。

235 246

236檔案窗格在本機和 SSH 會話中可用。對於雲端會話，要求 Claude 進行變更。247檔案窗格在本機和 SSH 工作階段中可用。對於雲端工作階段，請要求 Claude 進行變更。

237 248

238<h3 id="open-files-in-other-apps">249<h3 id="open-files-in-other-apps">

239 在其他應用程式中開啟檔案250 在其他應用程式中開啟檔案

241 252

242右鍵點擊聊天、差異檢視器或檔案窗格中的任何檔案路徑以開啟上下文選單：253右鍵點擊聊天、差異檢視器或檔案窗格中的任何檔案路徑以開啟上下文選單：

243 254

244* **Attach as context**：將檔案新增到您的下一個提示255* **Attach as context**：將檔案新增到您的下一個提示詞

245* **Open in**：在已安裝的編輯器（如 VS Code、Cursor 或 Zed）中開啟檔案256* **Open in**：在已安裝的編輯器（如 VS Code、Cursor 或 Zed）中開啟檔案

246* **Show in Finder**（在 macOS 上），**Show in Explorer**（在 Windows 上）：開啟包含資料夾257* **Show in Finder**（在 macOS 上），**Show in Explorer**（在 Windows 上）：開啟包含資料夾

247* **Copy path**：將絕對路徑複製到您的剪貼簿258* **Copy path**：將絕對路徑複製到您的剪貼簿

258| **Thinking** | 工具呼叫摺疊成摘要，加上 Claude 的思考 |269| **Thinking** | 工具呼叫摺疊成摘要，加上 Claude 的思考 |

259| **Verbose** | Claude 採取的每個工具呼叫、檔案讀取和中間步驟，加上 Claude 的思考 |270| **Verbose** | Claude 採取的每個工具呼叫、檔案讀取和中間步驟，加上 Claude 的思考 |

260 271

261使用 Thinking 來追蹤 Claude 的推理，工具呼叫仍然摺疊。在調試 Claude 為什麼採取特定操作時使用 Verbose。Claude Desktop 1.46388.1 之前的版本也列出 Summary 模式，而仍設定為 Summary 的會話在您更新後會以 Normal 開啟。272使用 Thinking 來追蹤 Claude 的推理，工具呼叫仍然摺疊。在除錯 Claude 為什麼採取特定操作時使用 Verbose。Claude Desktop 1.46388.1 之前的版本也列出 Summary 模式，而仍設定為 Summary 的工作階段在您更新後會以 Normal 開啟。

262 273

263<h3 id="keyboard-shortcuts">274<h3 id="keyboard-shortcuts">

264 快捷鍵275 鍵盤快捷鍵

265</h3>276</h3>

266 277

267在 macOS 上按 **Cmd+/** 或在 Windows 上按 **Ctrl+/** 以查看 Code 標籤中可用的所有快捷鍵。在 Windows 上，對下面的快捷鍵使用 **Ctrl** 代替 **Cmd**。會話循環、終端機切換和檢視模式切換在每個平台上都使用 **Ctrl**。278在 macOS 上按 **Cmd+/** 或在 Windows 上按 **Ctrl+/** 以查看 Code 標籤中可用的所有快捷鍵。在 Windows 上，對下面的快捷鍵使用 **Ctrl** 代替 **Cmd**。工作階段循環、終端機切換和檢視模式切換在每個平台上都使用 **Ctrl**。

268 279

269| 快捷鍵 | 操作 |280| 快捷鍵 | 操作 |

270| - | - |281| - | - |

271| `Cmd` `/` | 顯示快捷鍵 |282| `Cmd` `/` | 顯示鍵盤快捷鍵 |

272| `Cmd` `N` | 新會話 |283| `Cmd` `N` | 新工作階段 |

276| `Esc` | 停止 Claude 的回應 |287| `Esc` | 停止 Claude 的回應 |

288| `Tab` / `Right arrow` | 在空白的提示詞輸入框中[接受建議的提示詞](#accept-a-suggested-prompt) |

287| `1`–`9` | 在開啟的選單中選擇項目 |299| `1`–`9` | 在開啟的選單中選擇項目 |

288 300

289這些快捷鍵僅適用於 Code 標籤。終端機型 [interactive mode 快捷鍵](/docs/zh-TW/interactive-mode#keyboard-shortcuts)（如 `Shift+Tab` 以循環權限模式）不適用於 Desktop。301這些快捷鍵適用於 Code 標籤。在 Desktop 中，`Shift+Tab` 不會像在終端機的 [interactive mode](/docs/zh-TW/interactive-mode#keyboard-shortcuts) 中那樣循環切換權限模式。

290 302

291<h3 id="check-usage">303<h3 id="check-usage">

292 檢查使用情況304 檢查使用情況

293</h3>305</h3>

294 306

295點擊模型選擇器旁的使用情況環以查看您目前的上下文視窗使用情況和您計畫在該期間的使用情況。上下文使用情況是按會話的；計畫使用情況在您所有 Claude Code 介面中共用。307點擊模型選擇器旁的使用情況環，以查看您目前的上下文視窗使用情況，以及您的方案在該期間的使用情況。上下文使用情況是按工作階段計算的；方案使用情況在您所有的 Claude Code 使用介面中共用。

296 308

297<h2 id="let-claude-use-your-computer">309<h2 id="let-claude-use-your-computer">

298 讓 Claude 使用您的電腦310 讓 Claude 使用您的電腦

458* 選擇 **Cloud** 以將工作階段作為[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)繼續，您的對話會以摘要形式帶過去。在您確認之前，對話框會說明您的檔案是否也會一併移動，以及雲端工作階段準備就緒後是否會存檔此工作階段。透過 [SSH](#ssh-sessions) 或在 [WSL](/docs/zh-TW/desktop-wsl) 中執行的工作階段無法以此方式移動。470* 選擇 **Cloud** 以將工作階段作為[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)繼續，您的對話會以摘要形式帶過去。在您確認之前，對話框會說明您的檔案是否也會一併移動，以及雲端工作階段準備就緒後是否會存檔此工作階段。透過 [SSH](#ssh-sessions) 或在 [WSL](/docs/zh-TW/desktop-wsl) 中執行的工作階段無法以此方式移動。

459* 選擇已安裝的編輯器或您的檔案管理器，以在其中開啟該工作階段在磁碟上的資料夾。471* 選擇已安裝的編輯器或您的檔案管理器，以在其中開啟該工作階段在磁碟上的資料夾。

460 472

473<h3 id="control-which-sessions-appear-on-your-other-devices">

474 控制哪些工作階段會出現在您的其他裝置上

475</h3>

476

477本機工作階段在 [Remote Control](/docs/zh-TW/remote-control) 將其連線後，就會出現在您的其他裝置上。已連線的工作階段會出現在 [claude.ai/code](https://claude.ai/code) 的工作階段清單中，以及已登入您 claude.ai 帳戶之裝置上的 Claude 應用程式中。

478

479本機工作階段會在您為其開啟 Remote Control 時連線，或在啟動時自動連線：

480

481* **您為該工作階段開啟**：使用該工作階段的 **Remote Control** 開關，或在其提示詞輸入框中輸入 `/remote-control`。

482* **在啟動時連線**：當 **Settings > Claude Code** 中的 **Connect new sessions to Remote Control** 開啟時，新工作階段會自動連線。如果您從未變更該設定，Desktop 會遵循您使用者設定或受管設定中的 [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup)，其次是您組織的預設值。

483

484若要查看工作階段是否已連線，請查看工具列中工作階段標題前的筆記型電腦圖示。當工作階段已連線或正在連線時，該圖示會反白顯示。點擊它以開啟該工作階段的 **Remote Control** 開關。

485

486若要讓工作階段不出現在您的其他裝置上，請在您需要的層級關閉 Remote Control：

487

488* **單一工作階段**：關閉其 **Remote Control** 開關。在啟動時即已連線的工作階段中，輸入 `/remote-control` 會讓 Remote Control 保持開啟，並顯示 `Remote Control is already on. This session connected automatically when it started.`。點擊該行上的 **Turn off** 以中斷連線。

489* **此電腦上的新 Desktop 工作階段**：在 **Settings > Claude Code** 中關閉 **Connect new sessions to Remote Control**。如果它已顯示為關閉，請先將其開啟再關閉，讓 Desktop 儲存您的選擇。儲存後，它會優先於 `remoteControlAtStartup` 和預設值。

490* **此電腦上的任何工作階段，包括 CLI**：在 `~/.claude/settings.json` 中將 [`disableRemoteControl`](/docs/zh-TW/settings-reference#disableremotecontrol) 設定為 `true`，以阻止工作階段連線。在您儲存該檔案時已連線的工作階段會保持連線，直到您為其關閉 Remote Control。

491

492若要隱藏已出現在您其他裝置上的工作階段，請在 Desktop 中將其存檔。Desktop 也會存檔該工作階段的 Remote Control 副本，使其離開那些裝置上的預設工作階段清單。若要在那裡檢視或刪除它，請參閱[存檔工作階段](/docs/zh-TW/claude-code-on-the-web#archive-sessions)。

493

461<h3 id="sessions-from-dispatch">494<h3 id="sessions-from-dispatch">

462 來自 Dispatch 的工作階段495 來自 Dispatch 的工作階段

463</h3>496</h3>

836 為您的團隊預先配置 SSH 連線869 為您的團隊預先配置 SSH 連線

837</h4>870</h4>

838 871

839管理員可以透過將 `sshConfigs` 新增到[受管設定](/docs/zh-TW/managed-settings)檔案來將 SSH 連線分發給團隊成員。以這種方式定義的連線會自動出現在每個使用者的環境下拉式選單中，並顯示為受管，因此使用者可以選擇它們，但無法在應用程式中編輯或刪除它們。872管理員可以透過在[受管設定](/docs/zh-TW/managed-settings)中設定 `sshConfigs`，將 SSH 連線分發給團隊成員。以這種方式定義的連線會自動出現在每個使用者的環境下拉式選單中，並顯示為受管，因此使用者可以選擇它們，但無法在應用程式中編輯或刪除它們。

840 873

841以下範例預先配置了一個單一連線：874以下範例預先配置了一個單一連線：

842 875

860 限制使用者可以連接的 SSH 主機893 限制使用者可以連接的 SSH 主機

861</h4>894</h4>

862 895

863管理員可以透過將 `sshHostAllowlist` 新增到[受管設定](/docs/zh-TW/managed-settings)檔案來限制 Desktop 的 SSH 會話到已核准的主機集合。設定後，使用者只能連接到其解析的主機名稱與其中一個模式相符的主機。將其設定為空陣列以完全停用 SSH 會話。896管理員可以透過在[受管設定](/docs/zh-TW/managed-settings)中設定 `sshHostAllowlist`，將 Desktop 的 SSH 工作階段限制在已核准的主機集合。設定後，使用者只能連接到其解析的主機名稱與其中一個模式相符的主機。將其設定為空陣列以停用 SSH 工作階段。[`sshHostAllowlist` 參考項目](/docs/zh-TW/settings-reference#sshhostallowlist)說明了空陣列如何與其他受管來源中的清單結合。

864 897

865以下範例允許連接到 `devboxes.example.com` 下的任何主機以及單一命名的堡壘主機：898以下範例允許連接到 `devboxes.example.com` 下的任何主機以及單一命名的堡壘主機：

866 899

870}903}

871```904```

872 905

906<Warning>

907 如果您的組織提供[伺服器管理設定](/docs/zh-TW/server-managed-settings)，請在那裡設定 `sshHostAllowlist`。預設情況下，Desktop 只會從[提供政策鍵的最高優先順序受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)讀取此鍵。如果該來源未設定此鍵，Desktop 會忽略較低優先順序的 MDM 政策或受管設定檔中的清單，並將此鍵視為[未設定](/docs/zh-TW/settings-reference#sshhostallowlist)。Desktop 不會顯示任何警告。

908

909 此外，也請在每位使用者的機器上，於該處最高優先順序的 MDM 政策或受管設定檔中保留相同的清單。Desktop 會在啟動時擷取伺服器管理設定，且不保留快取副本，因此在擷取成功之前，套用的是該機器上的清單。

910</Warning>

911

873模式不區分大小寫。`*` 符合任何主機，`*.example.com` 符合 `example.com` 和任何子網域。其他任何內容都是精確符合。檢查會針對透過 `ssh -G` 進行 `~/.ssh/config` 解析後的主機名稱執行，因此允許 `Host` 別名和 `ProxyCommand`/`ProxyJump` 項目，只要解析的 `HostName` 相符即可。912模式不區分大小寫。`*` 符合任何主機，`*.example.com` 符合 `example.com` 和任何子網域。其他任何內容都是精確符合。檢查會針對透過 `ssh -G` 進行 `~/.ssh/config` 解析後的主機名稱執行，因此允許 `Host` 別名和 `ProxyCommand`/`ProxyJump` 項目，只要解析的 `HostName` 相符即可。

874 913

875`sshHostAllowlist` 僅從受管設定讀取；使用者或專案設定中的值會被忽略。只有 Claude Desktop 應用程式遵守此設定；Claude Code CLI 和 IDE 擴充功能不讀取它，它也不限制透過 Bash 工具執行的 `ssh` 命令。它控制 Desktop 應用程式連接的主機，而不是網路出口，因此如果您需要硬邊界，請將其與您組織的網路或零信任控制配對。914`sshHostAllowlist` 僅從受管設定讀取；使用者或專案設定中的值會被忽略。只有 Claude Desktop 應用程式遵守此設定；Claude Code CLI 和 IDE 擴充功能不讀取它，它也不限制透過 Bash 工具執行的 `ssh` 命令。它控制 Desktop 應用程式連接的主機，而不是網路出口，因此如果您需要硬邊界，請將其與您組織的網路或零信任控制配對。

913| `disableMobileSimulatorTools` | 設定為 `true` 以封鎖 Claude 在 [iOS Simulator 窗格](/docs/zh-TW/desktop-ios-simulator#turn-off-simulator-access)中控制和擷取裝置的工具。該窗格仍可供使用者自行點擊使用；只有 Claude 的存取被移除。該值必須是 JSON 布林值 `true`；字串 `"true"` 會被忽略。 |952| `disableMobileSimulatorTools` | 設定為 `true` 以封鎖 Claude 在 [iOS Simulator 窗格](/docs/zh-TW/desktop-ios-simulator#turn-off-simulator-access)中控制和擷取裝置的工具。該窗格仍可供使用者自行點擊使用；只有 Claude 的存取被移除。該值必須是 JSON 布林值 `true`；字串 `"true"` 會被忽略。 |

914| `disableBrowserExternalNavigation` | 設定為 `true` 以完全關閉[瀏覽器窗格](#browse-external-sites)中的外部瀏覽。使用者和 Claude 都無法瀏覽外部網站，localhost 開發伺服器預覽不受影響。該值必須是 JSON 布林值 `true`；字串 `"true"` 會被忽略。 |953| `disableBrowserExternalNavigation` | 設定為 `true` 以完全關閉[瀏覽器窗格](#browse-external-sites)中的外部瀏覽。使用者和 Claude 都無法瀏覽外部網站，localhost 開發伺服器預覽不受影響。該值必須是 JSON 布林值 `true`；字串 `"true"` 會被忽略。 |

916| `sshHostAllowlist` | 將 [SSH 工作階段](#restrict-which-ssh-hosts-users-can-connect-to)限制在已解析主機名稱符合這些模式之一的主機。空陣列會停用 SSH 工作階段。僅從受管設定讀取。 |955| `sshHostAllowlist` | 將 [SSH 工作階段](#restrict-which-ssh-hosts-users-can-connect-to)限制在已解析主機名稱符合這些模式之一的主機。僅從受管設定讀取。 |

917| `disableDesktopLocalSessions` | 設定為 `true` 以關閉[在裝置上執行的 Code 工作階段](#local-sessions-on-managed-devices)，僅保留連線到其他主機的 SSH 工作階段和雲端工作階段。該值必須是 JSON 布林值 `true`。僅從受管設定讀取。需要 Claude Desktop v1.37937.0 或更新版本。 |956| `disableDesktopLocalSessions` | 設定為 `true` 以關閉[在裝置上執行的 Code 工作階段](#local-sessions-on-managed-devices)，僅保留連線到其他主機的 SSH 工作階段和雲端工作階段。該值必須是 JSON 布林值 `true`。僅從受管設定讀取。需要 Claude Desktop v1.37937.0 或更新版本。 |

918| `disableSshSavedPasswords` | 設定為 `true` 以停止 Desktop 提供記住 SSH 密碼的選項，並停止使用或顯示先前已儲存的密碼。開啟此設定不會刪除這些密碼。僅從受管設定讀取。需要 Claude Desktop v1.49585.0 或更新版本。 |957| `disableSshSavedPasswords` | 設定為 `true` 以停止 Desktop 提供記住 SSH 密碼的選項，並停止使用或顯示先前已儲存的密碼。開啟此設定不會刪除這些密碼。僅從受管設定讀取。需要 Claude Desktop v1.49585.0 或更新版本。 |

919| `managedMcpServers` | 將 MCP 伺服器設定推送給所有使用者。僅在第三方 (3P) Desktop 部署中可用。在每個項目中，設定 `"http"`、`"sse"` 或 `"stdio"` 的傳輸方式、連線詳細資訊，以及可選的 `toolPolicy` 對應，以限制使用者可以叫用該伺服器的哪些工具。請透過受管設定檔案、MDM 或 Claude apps gateway 原則的 [`desktop` 區塊](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)傳遞，因為第三方部署不會收到管理員主控台設定。若要透過閘道傳遞，您需要在閘道伺服器上使用 Claude Code v2.1.232 或更新版本。這是桌面應用程式自己的鍵；Claude Code 會讀取自己的[同名受管設定](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)，其項目結構不同。 |958| `managedMcpServers` | 將 MCP 伺服器設定推送給所有使用者。僅在第三方 (3P) Desktop 部署中可用。在每個項目中，設定 `"http"`、`"sse"` 或 `"stdio"` 的傳輸方式、連線詳細資訊，以及可選的 `toolPolicy` 對應，以限制使用者可以叫用該伺服器的哪些工具。請透過受管設定檔案、MDM 或 Claude apps gateway 原則的 [`desktop` 區塊](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)傳遞，因為第三方部署不會收到管理員主控台設定。若要透過閘道傳遞，您需要在閘道伺服器上使用 Claude Code v2.1.232 或更新版本。這是桌面應用程式自己的鍵；Claude Code 會讀取自己的[同名受管設定](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)，其項目結構不同。 |

920 959

921哪些受管設定會套用到 Desktop 工作階段，取決於該工作階段執行的位置。模型限制（例如 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 工作階段中的強制方式與終端機 CLI 相同；請參閱[使用介面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)。960哪些受管設定會套用到 Desktop 工作階段，取決於該工作階段執行的位置。模型限制（例如 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 工作階段中的強制方式與終端機 CLI 相同；請參閱[使用介面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)。

922 961

923* **此機器上的本機工作階段**：部署到磁碟的受管設定檔案會套用。當工作階段使用[符合條件的登入或金鑰](/docs/zh-TW/server-managed-settings#platform-availability)向 Anthropic 的 API 進行身分驗證時，透過管理員主控台遠端推送的受管設定也會套用到這些工作階段，並遵循與終端機 CLI 相同的[設定優先順序](/docs/zh-TW/settings#settings-precedence)。962* **此機器上的本機工作階段**：部署到磁碟的受管設定檔案會套用。當工作階段使用[符合條件的登入](/docs/zh-TW/server-managed-settings#platform-availability)向 Anthropic 的 API 進行身分驗證時，透過管理員主控台遠端推送的受管設定也會套用到這些工作階段，並遵循與終端機 CLI 相同的[設定優先順序](/docs/zh-TW/settings#settings-precedence)。

924* **[雲端工作階段](#cloud-sessions)**：接收[伺服器管理的設定](/docs/zh-TW/server-managed-settings)；裝置部署的檔案不會套用到它們，因為它們在 Anthropic 管理的 VM 上執行。路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段也會讀取執行器映像中的受管設定檔案。[Claude Code 如何結合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明該檔案何時適用。963* **[雲端工作階段](#cloud-sessions)**：接收[伺服器管理的設定](/docs/zh-TW/server-managed-settings)；裝置部署的檔案不會套用到它們，因為它們在 Anthropic 管理的 VM 上執行。路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段也會讀取執行器映像中的受管設定檔案。[Claude Code 如何結合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明該檔案何時適用。

925* **[SSH 工作階段](#ssh-sessions)**：工作階段從遠端主機讀取受管設定檔案。Desktop 本身會從本機的受管設定讀取 `sshConfigs`、`sshHostAllowlist`、`disableSshSavedPasswords` 和 `disableDesktopLocalSessions`。964* **[SSH 工作階段](#ssh-sessions)**：工作階段從遠端主機讀取受管設定檔案。Desktop 本身會在本機上讀取 `sshConfigs`、`sshHostAllowlist`、`disableSshSavedPasswords` 和 `disableDesktopLocalSessions`。如果您傳遞多個受管來源，它[預設只從其中一個讀取](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)。

926* **[Cowork](https://claude.com/docs/cowork/overview) 工作階段**：在此機器上的 Cowork 工作階段中，即使使用者以 Team 或 Enterprise 帳戶登入，Claude Code 也永遠不會擷取管理員主控台設定，並且會讀取部署到機器的原則，除非您的 Claude Desktop 設定設有 `requireCoworkFullVmSandbox`。遠端 Cowork 工作階段兩者皆不會接收。請參閱[原則適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)以了解哪些裝置檔案會套用到 Cowork，以及 [MCP 權限規則](/docs/zh-TW/permissions#mcp)以了解 `Bash` 和 `WebFetch` 規則如何套用於 Cowork 的工具。965* **[Cowork](https://claude.com/docs/cowork/overview) 工作階段**：在此機器上的 Cowork 工作階段中，即使使用者以 Team 或 Enterprise 帳戶登入，Claude Code 也永遠不會擷取管理員主控台設定，並且會讀取部署到機器的原則，除非您的 Claude Desktop 設定設有 `requireCoworkFullVmSandbox`。遠端 Cowork 工作階段兩者皆不會接收。請參閱[原則適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)以了解哪些裝置檔案會套用到 Cowork，以及 [MCP 權限規則](/docs/zh-TW/permissions#mcp)以了解 `Bash` 和 `WebFetch` 規則如何套用於 Cowork 的工具。

927 966

928在本機和 SSH 工作階段中，桌面應用程式會直接將每個使用者已連線的 claude.ai 連接器傳遞給 Claude Code。無論您使用哪個設定來源或檔案位置，任何 MCP 設定或 `managed-mcp.json` 都不會影響這些連接器。若要在這些工作階段中封鎖連接器的工具，請使用您組織的[連接器工具控制](/docs/zh-TW/mcp#organization-controls-on-connector-tools)。[連接器如何到達 Claude Code](/docs/zh-TW/mcp#how-connectors-reach-claude-code) 說明在每種工作階段中由哪些設定管理連接器。967在本機和 SSH 工作階段中，桌面應用程式會直接將每個使用者已連線的 claude.ai 連接器傳遞給 Claude Code。無論您使用哪個設定來源或檔案位置，任何 MCP 設定或 `managed-mcp.json` 都不會影響這些連接器。若要在這些工作階段中封鎖連接器的工具，請使用您組織的[連接器工具控制](/docs/zh-TW/mcp#organization-controls-on-connector-tools)。[連接器如何到達 Claude Code](/docs/zh-TW/mcp#how-connectors-reach-claude-code) 說明在每種工作階段中由哪些設定管理連接器。

975assets-proxy.anthropic.com1014assets-proxy.anthropic.com

976claude.ai1015claude.ai

977a.claude.ai1016a.claude.ai

978a-cdn.claude.ai

979assets.claude.ai1017assets.claude.ai

980downloads.claude.ai1018downloads.claude.ai

981*.livepreview.claude.ai1019*.livepreview.claude.ai

1023 來自 CLI？1061 來自 CLI？

1024</h2>1062</h2>

1025 1063

1026如果您已經使用 Claude Code CLI，Desktop 執行相同的基礎引擎，具有圖形介面。您可以在同一機器上同時執行兩者，甚至在同一專案上執行。每個都維護單獨的會話清單，您可以將 CLI 會話帶入 Desktop。它們透過 CLAUDE.md 檔案共用設定和專案記憶。1064如果您已經使用 Claude Code CLI，Desktop 執行相同的基礎引擎，具有圖形介面。您可以在同一機器上同時執行兩者，甚至在同一專案上執行。每個都維護單獨的工作階段清單，您可以將 CLI 工作階段帶入 Desktop。它們透過 CLAUDE.md 檔案共用設定和專案記憶。

1027 1065

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

1029 1067

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

1031 1069

1032```bash theme={null}1070```bash theme={null}

1033claude --desktop --resume <session-id>1071claude --desktop --resume <session-id>

1034```1072```

1035 1073

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

1037 1075

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

1039 1077

1040若要在 Desktop 中繼續終端機會話：1078若要在 Desktop 中繼續終端機工作階段：

1041 1079

10421. 在終端機中關閉會話。10801. 在終端機中關閉工作階段。

10432. 在 Desktop 提示框中，輸入 `/resume`。Desktop 列出您從此電腦上的 CLI 啟動的會話。按標題、資料夾或分支搜尋，並預覽每個會話停止的位置。10812. 在 Desktop 提示詞方塊中，輸入 `/resume`。Desktop 列出您從此電腦上的 CLI 啟動的工作階段。按標題、資料夾或分支搜尋，並預覽每個工作階段停止的位置。

10443. 選擇會話。它在應用程式中繼續進行，具有完整的對話和內容。10823. 選擇工作階段。它在應用程式中繼續進行，具有完整的對話和內容。

1045 1083

1046Desktop 繼續相同的會話而不是副本，因此之後在終端機中執行 `claude --resume` 仍然會找到它。1084Desktop 繼續相同的工作階段而不是副本，因此之後在終端機中執行 `claude --resume` 仍然會找到它。

1047 1085

1048<Tip>1086<Tip>

1049 何時使用 Desktop 與 CLI：當您想要在一個視窗中管理並行會話、並排排列窗格或視覺化檢查變更時，使用 Desktop。當您需要指令碼、自動化或偏好終端機工作流程時，使用 CLI。1087 何時使用 Desktop 與 CLI：當您想要在一個視窗中管理並行工作階段、並排排列窗格或視覺化檢查變更時，使用 Desktop。當您需要指令碼、自動化或偏好終端機工作流程時，使用 CLI。

1050</Tip>1088</Tip>

1051 1089

1052<h3 id="cli-flag-equivalents">1090<h3 id="cli-flag-equivalents">

1053 CLI 標誌等效項1091 CLI 旗標等效項

1054</h3>1092</h3>

1055 1093

1056此表顯示常見 CLI 標誌的桌面應用程式等效項。未列出的標誌沒有桌面等效項，因為它們是為指令碼或自動化設計的。1094此表顯示常見 CLI 旗標的桌面應用程式等效項。未列出的旗標沒有桌面等效項，因為它們是為指令碼或自動化設計的。

1057 1095

1058| CLI | Desktop 等效項 |1096| CLI | Desktop 等效項 |

1059| - | - |1097| - | - |

1063| `--dangerously-skip-permissions` | 略過權限模式。在 Pro 和 Max 方案上，在「設定」→「Claude Code」→「允許略過權限模式」中啟用它；在 Team 和 Enterprise 方案上，組織政策控制它 |1101| `--dangerously-skip-permissions` | 略過權限模式。在 Pro 和 Max 方案上，在「設定」→「Claude Code」→「允許略過權限模式」中啟用它；在 Team 和 Enterprise 方案上，組織政策控制它 |

1070 1108

1071<h3 id="shared-configuration">1109<h3 id="shared-configuration">

1072 共用設定1110 共用設定

1073</h3>1111</h3>

1074 1112

1075Desktop 和 CLI 讀取相同的設定檔案，因此您的設定會轉移：1113Desktop 和 CLI 讀取相同的設定檔，因此您的設定會轉移：

1076 1114

1077* **[CLAUDE.md](/docs/zh-TW/memory)** 和 `CLAUDE.local.md` 檔案在您的專案中由兩者使用1115* **[CLAUDE.md](/docs/zh-TW/memory)** 和 `CLAUDE.local.md` 檔案在您的專案中由兩者使用

1078* **[MCP servers](/docs/zh-TW/mcp)** 在 `~/.claude.json` 或 `.mcp.json` 中設定的在兩者中都有效1116* 在 `~/.claude.json` 或 `.mcp.json` 中設定的 **[MCP 伺服器](/docs/zh-TW/mcp)** 在兩者中都有效

1079* **[Hooks](/docs/zh-TW/hooks)** 和 **[skills](/docs/zh-TW/skills)** 在設定中定義的適用於兩者1117* 在設定中定義的 **[Hooks](/docs/zh-TW/hooks)** 和 **[skills](/docs/zh-TW/skills)** 適用於兩者

1080* **[Settings](/docs/zh-TW/settings)** 在 `~/.claude.json` 和 `~/.claude/settings.json` 中是共用的。`settings.json` 中的權限規則、允許的工具和其他設定適用於 Desktop 會話。1118* `~/.claude.json` 和 `~/.claude/settings.json` 中的 **[設定](/docs/zh-TW/settings)** 是共用的。`settings.json` 中的權限規則、允許的工具和其他設定適用於 Desktop 工作階段。

1081* **Models**：相同的[模型](/docs/zh-TW/model-config#available-models)在兩者中都可用。在 Desktop 中，從傳送按鈕旁的下拉式選單中選擇模型。您可以在會話期間從相同的下拉式選單變更模型。1119* **模型**：相同的[模型](/docs/zh-TW/model-config#available-models)在兩者中都可用。在 Desktop 中，從傳送按鈕旁的下拉式選單中選擇模型。您可以在工作階段期間從相同的下拉式選單變更模型。

1082 1120

1083<h4 id="mcp-servers-from-the-claude-desktop-chat-app">1121<h4 id="mcp-servers-from-the-claude-desktop-chat-app">

1084 Claude Desktop 聊天應用程式中的 MCP servers1122 Claude Desktop 聊天應用程式中的 MCP 伺服器

1085</h4>1123</h4>

1086 1124

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

1088 1126

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

1090 1128

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

1092 1130

1093<Note>1131<Note>

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

1095</Note>1133</Note>

1096 1134

1097<h3 id="feature-comparison">1135<h3 id="feature-comparison">

1098 功能比較1136 功能比較

1099</h3>1137</h3>

1100 1138

1101此表比較 CLI 和 Desktop 之間的核心功能。有關 CLI 標誌的完整清單，請參閱 [CLI 參考](/docs/zh-TW/cli-reference)。1139此表比較 CLI 和 Desktop 之間的核心功能。有關 CLI 旗標的完整清單，請參閱 [CLI 參考](/docs/zh-TW/cli-reference)。

1102 1140

1103| 功能 | CLI | Desktop |1141| 功能 | CLI | Desktop |

1104| - | - | - |1142| - | - | - |

1106| [第三方提供者](/docs/zh-TW/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 預設。若要進行閘道路由，請參閱[將桌面應用程式連接到閘道](/docs/zh-TW/llm-gateway-connect#desktop-app)。若要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |1144| [第三方提供者](/docs/zh-TW/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 預設。若要進行閘道路由，請參閱[將桌面應用程式連接到閘道](/docs/zh-TW/llm-gateway-connect#desktop-app)。若要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |

1109| @mention 檔案 | 文字型 | 具有自動完成；本機和 SSH 會話僅 |1147| @mention 檔案 | 文字型 | 具有自動完成；僅限本機和 SSH 工作階段 |

1110| 檔案附件 | 不可用 | 影像、PDF |1148| 檔案附件 | 不可用 | 影像、PDF |

1116| Dispatch 整合 | 不可用 | [Dispatch 會話](#sessions-from-dispatch)在側邊欄中 |1154| Dispatch 整合 | 不可用 | [Dispatch 工作階段](#sessions-from-dispatch)在側邊欄中 |

1117| 指令碼和自動化 | [`--print`](/docs/zh-TW/cli-reference)、[Agent SDK](/docs/zh-TW/headless) | 不可用 |1155| 指令碼和自動化 | [`--print`](/docs/zh-TW/cli-reference)、[Agent SDK](/docs/zh-TW/headless) | 不可用 |

1118 1156

1119<h3 id="what’s-not-available-in-desktop">1157<h3 id="what’s-not-available-in-desktop">

1124 1162

1125* **第三方提供者**：Desktop 預設連接到 Anthropic 的 API。若要透過閘道路由 Desktop，或在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請遵循[第三方提供者列](#feature-comparison)中的連結。1163* **第三方提供者**：Desktop 預設連接到 Anthropic 的 API。若要透過閘道路由 Desktop，或在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請遵循[第三方提供者列](#feature-comparison)中的連結。

1126* **Linux (beta)**：Linux 桌面應用程式中尚未提供電腦使用。請參閱 [Claude Desktop on Linux](/docs/zh-TW/desktop-linux)。1164* **Linux (beta)**：Linux 桌面應用程式中尚未提供電腦使用。請參閱 [Claude Desktop on Linux](/docs/zh-TW/desktop-linux)。

1127* **內嵌程式碼建議**：Desktop 不提供自動完成樣式的建議。它透過對話提示和明確的程式碼變更進行工作。1165* **內嵌程式碼建議**：Desktop 不提供自動完成樣式的程式碼補全。它透過對話式提示詞和明確的程式碼變更進行工作，並可在 Claude 回覆後[建議您的下一個提示詞](#accept-a-suggested-prompt)。

1128* **Agent teams**：協調的團隊，其中 Claude 作為團隊主管從共用任務清單中指派任務給隊友，在 [CLI](/docs/zh-TW/agent-teams) 中可用，不在 Desktop 中。若要在一個會話內進行多代理工作，請使用 [dynamic workflows](/docs/zh-TW/workflows)，它們在 Desktop 中執行；Claude 也可以[直接傳遞訊息和管理您的其他會話](#work-across-sessions)。1166* **Agent teams**：協調的團隊，其中 Claude 作為團隊組長從共用任務清單中指派任務給隊員，在 [CLI](/docs/zh-TW/agent-teams) 中可用，不在 Desktop 中。若要在一個工作階段內進行多 agent 工作，請使用 [dynamic workflows](/docs/zh-TW/workflows)，它們在 Desktop 中執行；Claude 也可以[直接傳遞訊息和管理您的其他工作階段](#work-across-sessions)。

1129* **Terminal-dialog 命令**：在終端機中開啟互動式面板的內建命令，在 Code 標籤中的行為不同。直接編輯[設定檔案](/docs/zh-TW/settings)以管理權限規則和設定，或從獨立 CLI 執行命令。1167* **Terminal-dialog 命令**：在終端機中開啟互動式面板的內建命令，在 Code 標籤中的行為不同。直接編輯[設定檔](/docs/zh-TW/settings)以管理權限規則和設定，或從獨立 CLI 執行命令。

1130 * 沒有引數形式的命令，例如 `/permissions`，回覆 `isn't available in this environment`。1168 * 沒有引數形式的命令，例如 `/permissions`，回覆 `isn't available in this environment`。

1131 * `/config` 開啟「設定」→「Claude Code」。命令後的文字被忽略，因此 `/config theme=dark` 不會設定主題。1169 * `/config` 開啟「設定」→「Claude Code」。命令後的文字被忽略，因此 `/config theme=dark` 不會設定主題。

1132 1170

1147 1185

1148點擊版本號以將其複製到您的剪貼簿。1186點擊版本號以將其複製到您的剪貼簿。

1149 1187

1188<h4 id="claude-code-version-in-the-code-tab">

1189 Code 標籤中的 Claude Code 版本

1190</h4>

1191

1192若要查看工作階段執行的 Claude Code 版本，請在 **Code** 標籤的本機工作階段中輸入 `/status`，並查看 **Claude Code** 列，其中會顯示如 `2.1.286` 的版本。

1193

1194若要為本機工作階段取得較新的版本，請在 macOS 上開啟 **Claude → Check for Updates**，或在 Windows 上開啟 **Help → Check for Updates**，然後啟動新的工作階段。

1195

1196在本機工作階段中，**Code** 標籤會執行其自己的 Claude Code 副本，該副本有自己的版本號。桌面應用程式會下載並更新該副本，因此它可能與您終端機中的 `claude` 命令不同，且更新其中一個不會更新另一個。

1197

1150<h3 id="403-or-authentication-errors-in-the-code-tab">1198<h3 id="403-or-authentication-errors-in-the-code-tab">

1151 Code 標籤中的 403 或驗證錯誤1199 Code 標籤中的 403 或驗證錯誤

1152</h3>1200</h3>

env-vars.md +332 −330

Details

126 變數126 變數

127</h2>127</h2>

128 128

129數值型變數（例如逾時、token 預算與重試次數）除了純數字之外，也接受科學記號與數字分隔符號寫法，除非該變數所在列註明僅接受純數字。例如，Claude Code 會將 `2e3` 讀取為 2000，將 `64_000` 讀取為 64000。在 v2.1.211 之前，這些寫法可能會在沒有任何提示的情況下設定為小得多的值，例如 `1e6` 會將逾時設定為 1。129數值型變數（例如逾時、token 預算和重試次數）除了純數字之外，也接受科學記號和數字分隔符寫法，但變數列中註明僅接受純數字者除外。例如，Claude Code 會將 `2e3` 讀為 2000，將 `64_000` 讀為 64000。在 v2.1.211 之前，這些寫法可能會在無任何提示的情況下設定為小得多的值，例如 `1e6` 會將逾時設為 1。

130 130

131<Note>131<Note>

132 對於開啟或關閉某項行為的變數，設定 `1`、`true`、`yes` 或 `on` 即可開啟，設定 `0`、`false`、`no` 或 `off` 即可關閉，不區分大小寫。132 對於開啟或關閉某項行為的變數，設定 `1`、`true`、`yes` 或 `on` 即可開啟，設定 `0`、`false`、`no` 或 `off` 即可關閉，不分大小寫。

133 133

134 部分變數只會判斷您是否有設定它們，因此任何非空值（包括 `0`）都會開啟該行為，若要關閉該行為，需取消設定該變數或將其設為空值。以下變數即以此方式運作：134 有些變數只讀取您是否有設定它們，因此任何非空值（包括 `0`）都會開啟該行為，若要關閉該行為，需取消設定該變數或將其設為空值。以下變數採用此方式：

135 135

136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

137 * `DISABLE_TELEMETRY`137 * `DISABLE_TELEMETRY`

140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

141 * `IS_DEMO`141 * `IS_DEMO`

142 142

143 另有一個變數有其專屬規則：`FORCE_HYPERLINK` 讀取的是數字，因此只有 `0` 會將其關閉。每個變數所在列也會說明其自身的規則。143 另有一個變數有自己的規則：`FORCE_HYPERLINK` 讀取的是數字，因此只有 `0` 會將其關閉。每個變數的列也會說明其自身的規則。

144</Note>144</Note>

145 145

146| 變數 | 用途 |146| 變數 | 用途 |

147| :- | :- |147| :- | :- |

148| `ANTHROPIC_API_KEY` | 以 `X-Api-Key` 標頭傳送的 API 金鑰。設定後，即使您已登入，也會使用此金鑰，而非您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式（`-p`）中，只要有此金鑰就一律使用。在互動模式中，系統會提示您核准一次該金鑰，之後它才會取代您的訂閱。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |148| `ANTHROPIC_API_KEY` | 以 `X-Api-Key` 標頭傳送的 API 金鑰。設定後，即使您已登入，也會使用此金鑰，而非您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式（`-p`）中，只要存在此金鑰就一律使用。在互動模式中，系統會提示您核准此金鑰一次，之後它才會覆寫您的訂閱。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |

150| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，於 AWS Console 中產生。以 `x-api-key` 傳送，且優先於 AWS SigV4 |150| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，於 AWS Console 中產生。以 `x-api-key` 傳送，且優先於 AWS SigV4 |

151| `ANTHROPIC_AWS_BASE_URL` | 覆寫 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。預設為 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 會以[與 Amazon Bedrock 相同的優先順序](/docs/zh-TW/amazon-bedrock#3-configure-claude-code)解析區域 |151| `ANTHROPIC_AWS_BASE_URL` | 覆寫 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。預設為 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 解析區域時採用[與 Amazon Bedrock 相同的優先順序](/docs/zh-TW/amazon-bedrock#3-configure-claude-code) |

152| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的必要設定。每個請求都會以 `anthropic-workspace-id` 標頭傳送 |152| `ANTHROPIC_AWS_WORKSPACE_ID` | 使用 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 時為必填。在每個請求中以 `anthropic-workspace-id` 標頭傳送 |

153| `ANTHROPIC_BASE_URL` | 覆寫 API 端點，以透過代理伺服器或閘道路由請求。設定為非第一方主機時，[MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設為停用。若您的代理伺服器會轉送 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此變數指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 會停用，與其在 Amazon Bedrock、Google Cloud's Agent Platform 及 Microsoft Foundry 上的行為一致 |153| `ANTHROPIC_BASE_URL` | 覆寫 API 端點，以透過代理伺服器或閘道路由請求。設定為非第一方主機時，預設會停用 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。如果您的代理伺服器會轉送 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此變數指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 會停用，與其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為一致 |

154| `ANTHROPIC_BEDROCK_BASE_URL` | 覆寫 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |154| `ANTHROPIC_BEDROCK_BASE_URL` | 覆寫 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |

155| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆寫 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |155| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆寫 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |

156| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 優先嘗試的跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），而非由 AWS 區域推導出的前綴。在 AWS GovCloud 區域中會被忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |156| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 優先嘗試的跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），用以取代從 AWS 區域推導出的前綴。在 AWS GovCloud 區域中會被忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |

157| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層級](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。以 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |157| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層級](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。以 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |

158| `ANTHROPIC_BETAS` | 以逗號分隔的額外 `anthropic-beta` 標頭值清單，會包含在 API 請求中。Claude Code 已會傳送其所需的 beta 標頭；在 Claude Code 加入原生支援之前，可使用此變數選擇加入某項 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。與需要 API 金鑰身分驗證的 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)不同，此變數適用於所有驗證方式，包括 Claude.ai 訂閱 |158| `ANTHROPIC_BETAS` | 要包含在 API 請求中的其他 `anthropic-beta` 標頭值，以逗號分隔。Claude Code 已會傳送其所需的 beta 標頭；使用此變數可在 Claude Code 加入原生支援之前，選擇加入 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。與需要 API 金鑰身分驗證的 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)不同，此變數適用於所有驗證方式，包括 Claude.ai 訂閱 |

159| `ANTHROPIC_CUSTOM_HEADERS` | 要新增至請求的自訂標頭（`Name: Value` 格式，多個標頭以換行分隔）。若名稱或值包含 HTTP 標頭無法承載的字元（例如彎引號或零寬空格），請求會失敗，並顯示依位置指出該組標頭的錯誤。需要 Claude Code v2.1.227 或更新版本。[Invalid request header value](/docs/zh-TW/errors#invalid-request-header-value) 列出確切的字元集以及檢查執行的位置。若值設定的是憑證、組織或租用戶、路由或 API 行為相關標頭（例如 `Authorization` 或 `Host`），當由伺服器管理設定傳遞時，會被視為[需要核准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。若來自專案或本機設定，此類值會遵循[`env` 值何時套用的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |159| `ANTHROPIC_CUSTOM_HEADERS` | 要加入請求的自訂標頭（`Name: Value` 格式，多個標頭以換行分隔）。如果名稱或值包含 HTTP 標頭無法承載的字元，例如彎引號或零寬空格，請求會失敗，並出現依位置指出該組標頭的錯誤。需要 Claude Code v2.1.227 或更新版本。[Invalid request header value](/docs/zh-TW/errors#invalid-request-header-value) 列出了確切的字元集以及檢查執行的位置。當伺服器管理的設定傳遞設定了憑證、組織或租用戶、路由或 API 行為標頭（例如 `Authorization` 或 `Host`）的值時，該值會被視為[需要核准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。若來自專案或本機設定，此類值會遵循 [`env` 值何時套用的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。可用於讓非標準或閘道專屬的模型可供選擇，而不必取代內建別名。請參閱[模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |160| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此變數可讓非標準或閘道專屬的模型變為可選取，而不需取代內建別名。請參閱[模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |

162| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，若 Claude Code [能辨識該 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，該項目會顯示模型名稱，否則顯示模型 ID |162| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，如果 Claude Code [能辨識該 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，項目會顯示模型名稱，否則顯示模型 ID |

163| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 以逗號分隔的自訂模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |163| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 自訂模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名所解析的模型 ID，也是 Claude Code 在第三方供應商上為[自動模型備援](/docs/zh-TW/model-config#automatic-model-fallback)辨識為 Fable 模型的 ID。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |164| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名解析成的模型 ID，也是 Claude Code 在第三方供應商上為[自動模型備援](/docs/zh-TW/model-config#automatic-model-fallback)辨識為 Fable 模型的 ID。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中已固定之 Fable 模型的顯示描述。未設定時，該列會顯示以 `Custom Fable model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |165| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Fable 模型的顯示說明。未設定時，該列會顯示以 `Custom Fable model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

166| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中已固定之 Fable 模型的顯示名稱。未設定時，若 Claude Code 能辨識所固定的 ID，該列會顯示模型名稱，否則顯示所固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |166| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中固定 Fable 模型的顯示名稱。未設定時，如果 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

167| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的已固定 Fable 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |167| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 固定 Fable 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名所解析的模型 ID，也用於[背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |168| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名解析成的模型 ID，也用於[背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 選擇器中已固定之 Haiku 模型的顯示描述。未設定時，該列會顯示以 `Custom Haiku model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Haiku 模型的顯示說明。未設定時，該列會顯示以 `Custom Haiku model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

170| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中已固定之 Haiku 模型的顯示名稱。未設定時，若 Claude Code 能辨識所固定的 ID，該列會顯示模型名稱，否則顯示所固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |170| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中固定 Haiku 模型的顯示名稱。未設定時，如果 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

171| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的已固定 Haiku 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |171| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 固定 Haiku 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

172| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動時使用的模型。需要 Claude Code v2.1.236 或更新版本。請參閱[為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |172| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動時使用的模型。需要 Claude Code v2.1.236 或更新版本。請參閱[為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |

173| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名所解析的模型 ID，也是 `opusplan` 在 Plan Mode 啟用時所使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |173| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名解析成的模型 ID，也是 Plan Mode 啟用時 `opusplan` 使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 選擇器中已固定之 Opus 模型的顯示描述。未設定時，該列會顯示以 `Custom Opus model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Opus 模型的顯示說明。未設定時，該列會顯示以 `Custom Opus model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

175| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中已固定之 Opus 模型的顯示名稱。未設定時，若 Claude Code 能辨識所固定的 ID，該列會顯示模型名稱，否則顯示所固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |175| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中固定 Opus 模型的顯示名稱。未設定時，如果 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

176| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的已固定 Opus 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |176| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 固定 Opus 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名所解析的模型 ID，也是 `opusplan` 在 Plan Mode 未啟用時所使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |177| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名解析成的模型 ID，也是 Plan Mode 未啟用時 `opusplan` 使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 選擇器中已固定之 Sonnet 模型的顯示描述。未設定時，該列會顯示以 `Custom Sonnet model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |178| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Sonnet 模型的顯示說明。未設定時，該列會顯示以 `Custom Sonnet model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

179| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中已固定之 Sonnet 模型的顯示名稱。未設定時，若 Claude Code 能辨識所固定的 ID，該列會顯示模型名稱，否則顯示所固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |179| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中固定 Sonnet 模型的顯示名稱。未設定時，如果 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

180| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的已固定 Sonnet 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |180| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 固定 Sonnet 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

181| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯合規則 ID。當您將其與 `ANTHROPIC_ORGANIZATION_ID` 一同設定時，Claude Code 會選用聯合憑證，其優先順序高於您的 `/login` 憑證。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |181| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯合規則 ID。當您將其與 `ANTHROPIC_ORGANIZATION_ID` 一起設定時，Claude Code 會選取聯合憑證，其排名高於您的 `/login` 憑證。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

182| `ANTHROPIC_FOUNDRY_API_KEY` | 用於 Microsoft Foundry 身分驗證的 API 金鑰（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |182| `ANTHROPIC_FOUNDRY_API_KEY` | 用於 Microsoft Foundry 身分驗證的 API 金鑰（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

183| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用於 Microsoft Foundry 身分驗證的 Bearer token，例如 Microsoft Entra 存取 token。Claude Code 會以 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 及 Azure 預設憑證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |183| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用於 Microsoft Foundry 身分驗證的 Bearer token，例如 Microsoft Entra 存取 token。Claude Code 會將其作為 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 及 Azure 預設憑證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |

184| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。為 `ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |184| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。為 `ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

185| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。Claude Code [會拒絕 URL 或主機名稱](/docs/zh-TW/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。若未設定 `ANTHROPIC_FOUNDRY_BASE_URL` 則為必要設定（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |185| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。Claude Code [會拒絕 URL 或主機名稱](/docs/zh-TW/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。若未設定 `ANTHROPIC_FOUNDRY_BASE_URL` 則為必填（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

187| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。請與 `ANTHROPIC_FEDERATION_RULE_ID` 一同設定。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |187| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。請與 `ANTHROPIC_FEDERATION_RULE_ID` 一起設定。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

188| `ANTHROPIC_PROFILE` | 用於身分驗證的 Anthropic 設定檔名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立的設定檔，或透過[不使用 API 金鑰登入 Console 帳戶](/docs/zh-TW/authentication#sign-in-without-an-api-key)所建立的設定檔。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |188| `ANTHROPIC_PROFILE` | 用於身分驗證的 Anthropic 設定檔（profile）名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 或[在沒有 API 金鑰的情況下登入 Console 帳戶](/docs/zh-TW/authentication#sign-in-without-an-api-key)所建立的設定檔。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

190| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時，覆寫 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，僅在同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才會生效，因為否則 Amazon Bedrock 會在工作階段區域中以[預設 Sonnet 模型或主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions)執行背景任務 |190| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時，覆寫 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，只有同時設定了 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才會生效，因為否則 Amazon Bedrock 會在工作階段區域中以[預設 Sonnet 模型或主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions)執行背景任務 |

191| `ANTHROPIC_VERTEX_BASE_URL` | 覆寫 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |191| `ANTHROPIC_VERTEX_BASE_URL` | 覆寫 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |

192| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 請求所指向的 GCP 專案 ID。請參閱[設定 GCP 憑證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |192| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 請求所指向的 GCP 專案 ID。請參閱[設定 GCP 憑證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |

193| `ANTHROPIC_WORKSPACE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯合規則涵蓋多個工作區時請設定此變數，讓 token 交換知道要以哪個工作區為目標 |193| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯合規則範圍涵蓋多個工作區時，請設定此變數，讓 token 交換知道要以哪個工作區為目標 |

194| `API_FORCE_IDLE_TIMEOUT` | 覆寫 5 分鐘的主體閒置逾時，該逾時會在沒有位元組抵達時中止串流模型回應。設為 `0` 可關閉逾時，例如當緩慢的[閘道](/docs/zh-TW/llm-gateway)或本機模型在區塊之間暫停超過 5 分鐘時；設為 `1` 則對所有供應商都保持開啟。未設定時，除了直接使用 Anthropic API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)，以及設定了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 之外，其他供應商都會啟用此逾時。[串流監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs)獨立於此運作，即使您在此設為 `0`，仍會中止長時間的無回應暫停 |194| `API_FORCE_IDLE_TIMEOUT` | 覆寫 5 分鐘的本文閒置逾時，此逾時會在沒有任何位元組抵達時中止串流模型回應。設為 `0` 可關閉此逾時，例如當緩慢的[閘道](/docs/zh-TW/llm-gateway)或本機模型在區塊之間暫停超過 5 分鐘時；設為 `1` 則可對所有供應商保持開啟。未設定時，此逾時會在直接 Anthropic API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 以及設定了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 以外的供應商上啟用。[串流監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs)獨立於此運作，即使您在此設定 `0`，仍會中止長時間的靜默暫停 |

195| `API_TIMEOUT_MS` | API 請求的逾時時間，以毫秒為單位（預設：600000，即 10 分鐘；最大值：2147483647）。當請求在緩慢的網路上逾時，或透過代理伺服器路由時，請調高此值。超過最大值的值會使底層計時器溢位，導致請求立即失敗 |195| `API_TIMEOUT_MS` | API 請求的逾時時間，以毫秒為單位（預設：600000，即 10 分鐘；最大值：2147483647）。當請求在緩慢的網路上逾時，或透過代理伺服器路由時，請調高此值。超過最大值的值會使底層計時器溢位，導致請求立即失敗 |

196| `AWS_BEARER_TOKEN_BEDROCK` | 用於身分驗證的 Amazon Bedrock API 金鑰（請參閱 [Amazon Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |196| `AWS_BEARER_TOKEN_BEDROCK` | 用於身分驗證的 Amazon Bedrock API 金鑰（請參閱 [Amazon Bedrock API 金鑰](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |

197| `BASH_DEFAULT_TIMEOUT_MS` | 前景 Bash 或 PowerShell 工具命令的預設逾時，以毫秒為單位（預設：120000，即 2 分鐘）。若預設值超過 30 分鐘，在無人值守的工作階段中，也會成為[背景命令的時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)預設值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |197| `BASH_DEFAULT_TIMEOUT_MS` | 前景 Bash 或 PowerShell 工具命令的預設逾時，以毫秒為單位（預設：120000，即 2 分鐘）。高於[背景命令預設時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)的值，會在無人值守的工作階段中取代該預設值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |

198| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果中的 bash 輸出最大字元數（預設：30000；最大值：150000）。若您設定了 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱[輸出限制](/docs/zh-TW/tools-reference#output-limits) |198| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果中的 bash 輸出字元數上限（預設：30000；最大值：150000）。如果您設定了 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱[輸出限制](/docs/zh-TW/tools-reference#output-limits) |

199| `BASH_MAX_TIMEOUT_MS` | 模型可為前景 Bash 或 PowerShell 工具命令設定的最大逾時，以毫秒為單位（預設：600000，即 10 分鐘）。實際上限為此值與 `BASH_DEFAULT_TIMEOUT_MS` 中較大者。若實際上限超過 2 小時，在無人值守的工作階段中，也會成為[背景命令的時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)最大值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |199| `BASH_MAX_TIMEOUT_MS` | 模型可為前景 Bash 或 PowerShell 工具命令設定的最大逾時，以毫秒為單位（預設：600000，即 10 分鐘）。實際上限為此值與 `BASH_DEFAULT_TIMEOUT_MS` 中較大者。超過 2 小時的實際上限，也會成為無人值守工作階段中[背景命令時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)的最大值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |

200| `BETA_TRACING_ENDPOINT` | [詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)的 OTLP/HTTP 端點：搭配 `ENABLE_BETA_TRACING_DETAILED=1` 時，日誌與追蹤會傳送至該處，而非已設定的匯出器。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |200| `BETA_TRACING_ENDPOINT` | [詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)的 OTLP/HTTP 端點：搭配 `ENABLE_BETA_TRACING_DETAILED=1` 時，日誌和追蹤會傳送至此處，而非已設定的匯出器。請在您的 shell、使用者設定或受管設定中設定此變數。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

201| `CCR_FORCE_BUNDLE` | 設為 `1` 可強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 打包並上傳您的本機儲存庫，而非從其遠端複製 |201| `CCR_FORCE_BUNDLE` | 設為 `1` 可強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 將您的本機儲存庫打包並上傳，而非從其遠端複製 |

202| `CLAUDECODE` | 在 Claude Code 產生的子程序（Bash 與 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令、stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序）中設為 `1`。IDE 擴充功能也會在其整合式終端機中設定此變數。可用於偵測指令碼是否在 Claude Code 產生的子程序中執行。若要檢查目前程序是否由工具呼叫或 hook 直接產生，而非在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |202| `CLAUDECODE` | 在 Claude Code 產生的子程序中設為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令、stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序）。IDE 擴充功能也會在其整合式終端機中設定此變數。用於偵測指令碼是否在 Claude Code 產生的子程序中執行。若要檢查目前程序是否由工具呼叫或 hook 直接產生，而非在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |

203| `CLAUDE_AFK_COUNTDOWN_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框自動繼續之前，畫面上倒數計時出現的毫秒數。預設為 `20000`（20 秒），上限為自動繼續逾時。除非已開啟自動繼續，否則沒有作用；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定與 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |203| `CLAUDE_AFK_COUNTDOWN_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在自動繼續之前多少毫秒顯示畫面上的倒數計時。預設 `20000`（20 秒），上限為自動繼續逾時。除非自動繼續已開啟，否則不會生效；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |

204| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在閒置多少毫秒後，會在無您參與的情況下自動繼續。自動繼續預設為關閉；請透過 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定選擇加入。此變數是用於示範與自動化測試的覆寫：設定後，它會優先於該設定，即使該設定未設定或為 `never`，也會開啟自動繼續。設為 `0` 並不會關閉逾時，而是會立即關閉對話框。在 v2.1.198 與 v2.1.199 中，自動繼續預設為開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |204| `CLAUDE_AFK_TIMEOUT_MS` | 閒置多少毫秒後，未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框會在沒有您的情況下自動繼續。自動繼續預設為關閉；請透過 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定選擇加入。此變數是供示範和自動化測試使用的覆寫：設定後，它會優先於該設定，即使該設定未設定或為 `never`，也會開啟自動繼續。設定 `0` 不會關閉逾時，而是會立即關閉對話框。在 v2.1.198 和 v2.1.199 中，自動繼續預設為開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |

205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設為 `1` 可停用所有內建 [subagent](/docs/zh-TW/sub-agents) 類型，例如 Explore 與 Plan。僅適用於非互動模式（`-p` 旗標）。適合想要從零開始的 SDK 使用者。這也會移除 `general-purpose`，即 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 所執行的 subagent。此類呼叫隨後會以 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) 失敗 |205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設為 `1` 可停用所有內建 [subagent](/docs/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動模式（`-p` 旗標）。對於想要從零開始的 SDK 使用者很有用。這也會移除 `general-purpose`，也就是當 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 執行的 subagent。此類呼叫隨後會失敗並出現 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) |

207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | subagent 的停滯逾時，以毫秒為單位。預設為 `600000`（10 分鐘）；若您在串流監控程式開啟時調高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設值也會隨之提高，如[處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述。計時器會在每個串流進度事件時重設；若在時間範圍內沒有任何進度，Claude Code 會中止該 subagent 並向上層回報停滯 |207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | subagent 的停滯逾時，以毫秒為單位。預設 `600000`（10 分鐘）；如果您在串流監控程式開啟時調高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設值會隨之提高，如[處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述。計時器會在每個串流進度事件發生時重設；如果在時間範圍內沒有任何進度，Claude Code 會中止該 subagent，並向父層回報停滯 |

208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮視窗中觸發自動壓縮的百分比（1-100）。使用較低的值（例如 `50`）可提早壓縮；此變數無法提高閾值，因此高於預設百分比的值會被忽略。僅適用於[在模型上下文限制之前壓縮](/docs/zh-TW/model-config#context-window-and-auto-compaction)的工作階段。同時適用於主要對話與 subagent |208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定觸發自動壓縮時自動壓縮視窗的百分比（1-100）。使用較低的值（例如 `50`）可提早壓縮；此變數無法提高閾值，因此高於預設百分比的值會被忽略。僅適用於[在模型上下文限制之前壓縮](/docs/zh-TW/model-config#context-window-and-auto-compaction)的工作階段。同時適用於主要對話和 subagent |

209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設為 `1` 可強制啟用長時間執行之 agent 任務的自動背景化。啟用後，subagent 在執行約兩分鐘後會移至背景。在 Claude Code v2.1.212 或更新版本中，也會在非互動模式下啟用[長時間 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設為 `1` 可強制啟用長時間執行 agent 任務的自動背景化。啟用後，subagent 在執行約兩分鐘後會移至背景。在 Claude Code v2.1.212 或更新版本上，也會在非互動模式中啟用[長時間 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |

210| `CLAUDE_AX_PREPARK_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 寫入新行或已變更行之前等待的毫秒數。預設為 `0`，因此 Claude Code 不會等待。在 v2.1.287 之前，預設值為 `50`。Claude Code 將等待上限設為 `5000`。需要 Claude Code v2.1.233 或更新版本 |210| `CLAUDE_AX_PREPARK_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 在寫入新行或已變更的行之前等待多少毫秒。預設 `0`，因此 Claude Code 不會等待。在 v2.1.287 之前，預設值為 `50`。Claude Code 將等待上限設為 `5000`。需要 Claude Code v2.1.233 或更新版本 |

211| `CLAUDE_AX_SCREEN_READER` | 設為 `1` 可呈現適合螢幕閱讀器的輸出：不含裝飾性邊框或動畫的純文字。設為 `0` 可強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true` 亦然。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先於此變數。需要 Claude Code v2.1.181 或更新版本 |211| `CLAUDE_AX_SCREEN_READER` | 設為 `1` 可呈現適合螢幕閱讀器的輸出：不含裝飾性邊框或動畫的純文字。設為 `0` 可強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |

212| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 在啟動確認行之後暫緩第一次介面呈現的毫秒數，讓您的螢幕閱讀器能在新輸出中斷之前完整唸出該行。預設為 `3000`。設為 `0` 可立即呈現。Claude Code 將暫緩上限設為 `600000`（10 分鐘）。您的第一次按鍵會提早結束暫緩。需要 Claude Code v2.1.217 或更新版本 |212| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 在啟動確認行之後延後第一次介面呈現的毫秒數，讓您的螢幕閱讀器能在新輸出打斷之前完整念出該行。預設 `3000`。設為 `0` 可立即呈現。Claude Code 將延後上限設為 `600000`（10 分鐘）。您的第一次按鍵會提前結束延後。需要 Claude Code v2.1.217 或更新版本 |

214| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組層級串流閒置監控程式的逾時，以毫秒為單位；設定後，對該監控程式而言會優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，且不影響事件層級監控程式。Claude Code 會將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |214| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組層級串流閒置監控程式的逾時，以毫秒為單位；設定後，對於該監控程式，它會優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，並保持事件層級監控程式不變。Claude Code 會將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |

215| `CLAUDE_CLIENT_PRESENCE_FILE` | 一個檔案的路徑，由外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立、鎖定螢幕時刪除。當該檔案存在時，Claude Code 會略過 [Remote Control 行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)，讓您在正在使用電腦時不會收到推播。當檔案不存在或無法讀取時，通知會照常傳送。Claude Code 會在每個觸發推播的事件時檢查一次該檔案，而非輪詢。需要 Claude Code v2.1.181 或更新版本 |215| `CLAUDE_CLIENT_PRESENCE_FILE` | 一個檔案的路徑，由外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立、在您鎖定螢幕時刪除。檔案存在期間，Claude Code 會略過 [Remote Control 行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)，讓您在主動使用電腦時不再收到推播。當檔案不存在或無法讀取時，通知會照常傳送。Claude Code 會在每個觸發推播的事件發生時檢查該檔案一次，而非輪詢。需要 Claude Code v2.1.181 或更新版本 |

217| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設為 `1` 可從以 `--add-dir` 指定的目錄載入記憶檔案。會載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 與 `CLAUDE.local.md`。預設情況下，額外目錄不會載入記憶檔案 |217| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設為 `1` 可從以 `--add-dir` 指定的目錄載入記憶檔案。會載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。預設情況下，額外目錄不會載入記憶檔案 |

218| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中每一影格都重繪整個畫面，而非傳送增量更新。若全螢幕模式顯示過時或錯位的文字片段，請使用此設定。Claude Code 會在 Windows 上的背景工作階段與 [agent view](/docs/zh-TW/agent-view) 自動啟用此設定 |218| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中每一幀重繪整個畫面，而非傳送增量更新。如果全螢幕模式顯示過時或錯位的文字片段，請使用此變數。Claude Code 會在 Windows 上的背景工作階段和 [agent view](/docs/zh-TW/agent-view) 中自動啟用此功能 |

219| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設為 `1` 可在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 無法將該模型 ID 辨識為支援 effort。當透過以自訂識別碼提供模型的 [LLM 閘道](/docs/zh-TW/llm-gateway)或第三方供應商路由時，請使用此設定。在 API 層級拒絕 effort 參數的模型（包括 Claude 3 模型、Sonnet 4.0 與 4.5、Opus 4.0 與 4.1，以及 Haiku 4.5）仍會被排除，以免請求失敗 |219| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設為 `1` 可在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 無法將模型 ID 辨識為支援 effort。當透過以自訂識別碼提供模型的 [LLM 閘道](/docs/zh-TW/llm-gateway)或第三方供應商路由時使用。在 API 層級拒絕 effort 參數的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍會被排除，以免請求失敗 |

220| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 憑證重新整理的間隔，以毫秒為單位（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |220| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 重新整理憑證的間隔，以毫秒為單位（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |

221| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設為 `0` 可在新的 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 發佈時，不讓 Claude Code 自動開啟瀏覽器 |221| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設為 `0` 可在發布新的 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 時，阻止 Claude Code 自動開啟瀏覽器 |

222| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設為 `0` 可讓 Claude 停止讀取及回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[關閉 artifact](/docs/zh-TW/artifacts#availability) 時沒有作用。需要 Claude Code v2.1.221 或更新版本 |222| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設為 `0` 可阻止 Claude 讀取和回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[關閉 artifact](/docs/zh-TW/artifacts#availability) 時不會生效。需要 Claude Code v2.1.221 或更新版本 |

223| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設為 `0` 可讓 Claude 停止[自行回覆傳送給它的留言](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |223| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設為 `0` 可阻止 Claude [自行回覆傳送給它的留言](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |

224| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設為 `0` 可從系統提示詞開頭省略[歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊包含用戶端版本與提示詞指紋。無論如何，直接連線至 Anthropic API 時的快取都不受影響。在某些直接連線設定中，即使您設為 `0`，Claude Code 仍會在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器請求中保留該區塊。請在[系統提示詞歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)中查看此情況涵蓋哪些連線與憑證。在 v2.1.181 之前，該區塊在自訂基礎 URL 與 Microsoft Foundry 連線中包含每個請求各自的 token，因此在這些版本上，若您的 LLM 閘道會依請求主體進行快取或將請求轉送至第三方供應商，或您直接連線至 Microsoft Foundry，請將其設為 `0` |224| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設為 `0` 可從系統提示詞開頭省略[歸因區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊帶有用戶端版本和提示詞指紋。無論如何設定，直接連線至 Anthropic API 時的快取都不受影響。在某些直接連線設定中，即使您設定 `0`，Claude Code 仍會在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器請求上保留該區塊。請在[系統提示詞歸因區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)中查看此情況涵蓋哪些連線和憑證。在 v2.1.181 之前，該區塊在自訂基礎 URL 和 Microsoft Foundry 連線上包含每個請求專屬的 token，因此在這些版本上，當您的 LLM 閘道依請求本文進行快取或將請求轉送給第三方供應商時，或當您直接連線至 Microsoft Foundry 時，請將其設為 `0` |

226| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 以 token 為單位設定[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，範圍從 `100000` 到 `1000000`。僅接受純整數，例如 `500000`：像 `500k` 這樣的值會被讀取為 `500`，並被限制為最小值 100K。實際視窗也以模型的上下文視窗為上限。優先於 `/autocompact` 命令、`--autocompact` 旗標與 `autoCompactWindow` 設定。狀態列的 `used_percentage` 一律以模型的完整上下文視窗為基準計算，因此一旦設定此變數，該百分比就不再能表示壓縮何時執行 |226| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 以 token 為單位設定[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，範圍為 `100000` 到 `1000000`。僅接受純整數，例如 `500000`：像 `500k` 這樣的值會被讀為 `500`，並限制為 100K 的最小值。實際視窗也以模型的上下文視窗為上限。優先於 `/autocompact` 命令、`--autocompact` 旗標和 `autoCompactWindow` 設定。狀態列的 `used_percentage` 一律以模型的完整上下文視窗為基準衡量，因此一旦設定此變數，該百分比就不再能表示何時會執行壓縮 |

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

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

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

230| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設為 `0` 可關閉 [Bash 命令執行期間所變更檔案的差異](/docs/zh-TW/hooks#bash)，設為 `1` 則可在所有權限模式中記錄該差異。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |230| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設為 `0` 可關閉 [Bash 命令執行期間變更之檔案的差異](/docs/zh-TW/hooks#bash)，或設為 `1` 可在每種權限模式中記錄它。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |

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

232| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 當工作階段有作用中的 [Remote Control](/docs/zh-TW/remote-control) 連線時，會自動在 Bash 工具與 [hook 命令](/docs/zh-TW/hooks)子程序中設定，並在連線結束時移除。其值為 `session_` 格式的工作階段 ID，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，請改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |232| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 當工作階段有作用中的 [Remote Control](/docs/zh-TW/remote-control) 連線時，會在 Bash 工具和 [hook 命令](/docs/zh-TW/hooks)子程序中自動設定，並在連線結束時移除。其值為 `session_` 形式的工作階段 ID，與工作階段 `claude.ai/code` URL 中出現的識別碼相同，讓指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，請改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

233| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設為 `0` 可讓 Claude Code 將 `0x08` 位元組（亦寫作 `^H`）讀取為一般 Backspace，設為 `1` 則讀取為 Ctrl+Backspace。任一值都會取代平台預設值。預設情況下，Claude Code 在 Windows 上將其讀取為 Ctrl+Backspace（`TERM_PROGRAM` 為 `mintty` 或 `TERM` 為 `cygwin` 時除外），在 macOS 與 Linux 上則讀取為一般 Backspace。在 [Backspace 會刪除整個單字](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 終端機中，請設為 `0` |233| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設為 `0` 可讓 Claude Code 將 `0x08` 位元組（也寫作 `^H`）讀為一般 Backspace，設為 `1` 則讀為 Ctrl+Backspace。任一值都會取代平台預設值。預設情況下，Claude Code 在 Windows 上將其讀為 Ctrl+Backspace（`TERM_PROGRAM` 為 `mintty` 或 `TERM` 為 `cygwin` 時除外），在 macOS 和 Linux 上則讀為一般 Backspace。在 [Backspace 會刪除整個字詞](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 終端機中，請設定 `0` |

234| `CLAUDE_CODE_CERT_STORE` | 以逗號分隔的 TLS 連線 CA 憑證來源清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集合。`system` 是作業系統信任存放區，僅在具備 `tls.getCACertificates` 的執行環境中讀取：原生二進位檔，或 npm 安裝時的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |234| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源清單，以逗號分隔。`bundled` 是 Claude Code 隨附的 Mozilla CA 集。`system` 是作業系統信任存放區，僅在具有 `tls.getCACertificates` 的執行環境中讀取：原生二進位檔，或 npm 安裝的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |

235| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 與 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令及[狀態列](/docs/zh-TW/statusline)命令所產生的子程序中設為 `1`。stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序不會設定此變數，因為它們是長期存在的程序，會比產生它們的工作階段存活得更久。與 `CLAUDECODE` 不同，此變數僅由 Claude Code 本身在啟動子程序時設定，IDE 擴充功能不會設定，因此能可靠地區分巢狀工作階段與在 IDE 整合式終端機中啟動的頂層 `claude`。以此方式啟動的巢狀互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上鍵歷史記錄及 `claude agents` 清單中排除。非互動的 `claude -p` 工作階段仍會保存。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆寫此排除。需要 Claude Code v2.1.172 或更新版本 |235| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令以及[狀態列](/docs/zh-TW/statusline)命令產生的子程序中設為 `1`。stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序不會設定，因為它們長時間存在，且存活時間超過產生它們的工作階段。與 `CLAUDECODE` 不同，此變數只會由 Claude Code 本身在啟動子程序時設定，不會由 IDE 擴充功能設定，因此能可靠地區分巢狀工作階段與在 IDE 整合式終端機中啟動的頂層 `claude`。以此方式啟動的巢狀互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上鍵歷史記錄和 `claude agents` 清單中排除。非互動式 `claude -p` 工作階段仍會保存。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆寫此排除。需要 Claude Code v2.1.172 或更新版本 |

239| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已於 v2.1.186 移除，現在不會有任何作用。先前用於為串流 API 請求的連線、TLS 與回應標頭階段設定個別逾時。請使用 `API_TIMEOUT_MS` 設定每個請求的逾時。關於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |239| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已於 v2.1.186 移除，現在不會產生任何作用。先前用於為串流 API 請求的連線、TLS 和回應標頭階段設定個別逾時。請使用 `API_TIMEOUT_MS` 設定每個請求的逾時。關於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

240| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆寫偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑而非目錄。需透過 `--debug`、`/debug` 或 `DEBUG` 環境變數另外啟用偵錯模式：僅設定此變數並不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標可同時完成兩者。預設為 `~/.claude/debug/<session-id>.txt` |240| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆寫偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑而非目錄。需要另外透過 `--debug`、`/debug` 或 `DEBUG` 環境變數啟用偵錯模式：僅設定此變數不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標可同時完成兩者。預設為 `~/.claude/debug/<session-id>.txt` |

241| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最低日誌等級。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設為 `verbose` 可包含大量診斷資訊，例如完整的狀態列命令輸出；或提高至 `error` 以減少雜訊 |241| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最低日誌等級。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設為 `verbose` 可包含大量診斷資訊，例如完整的狀態列命令輸出；或提高至 `error` 以減少雜訊 |

242| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設為 `1` 可停用 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context)支援。設定後，模型選擇器中將無法使用 1M 模型變體，且 Claude Code 會將使用原生 1M 視窗之模型（例如 [Sonnet 5.5](/docs/zh-TW/model-config#sonnet-5-5-and-sonnet-5-context-window) 與 Fable 模型）的工作階段限制在 200K 視窗；關於如何強制執行此限制，請參閱[延伸上下文](/docs/zh-TW/model-config#extended-context)。適用於有法規遵循要求的企業環境。關於此變數在修正無法辨識之 `[1m]` 模型 ID 視窗時的作用，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |242| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設為 `1` 可關閉 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context)支援。Claude Code 會從模型選擇器中移除 `[1m]` 模型變體，並將預設以 1M 視窗執行的模型限制為 200K 視窗。請參閱[關閉 1M 上下文](/docs/zh-TW/model-config#turn-off-1m-context)。適用於有合規需求的企業環境。關於其在修正無法辨識之 `[1m]` 模型 ID 視窗中的作用，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

243| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設為 `1` 可在 Opus 4.6 與 Sonnet 4.6 上停用[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並改用由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 及更新版本、Haiku 5.5，或 Opus 4.7 及更新版本沒有作用，這些模型一律使用自適應推理 |243| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設為 `1` 可停用 Opus 4.6 和 Sonnet 4.6 上的[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並改用由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 及更新版本、Haiku 5.5 或 Opus 4.7 及更新版本沒有作用，這些模型一律使用自適應推理 |

244| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設為 `1` 可讓 Claude Code 停止跨管理來源依鍵合併[受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)的 `env` 區塊，因此只會套用最高優先順序來源的整個 `env` 區塊，與 v2.1.223 之前相同。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |244| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設為 `1` 可阻止 Claude Code 跨管理來源逐鍵合併[受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)的 `env` 區塊，使只有最高優先順序來源的整個 `env` 區塊生效，如同 v2.1.223 之前的行為。請在啟動 Claude Code 的環境中設定此變數，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |

245| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設為 `1` 可停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令將無法使用，任何已設定的 `advisorModel` 都會被忽略，而 `--advisor` 旗標仍會被接受但沒有作用，因此傳入該旗標的現有指令碼可繼續正常運作而不會出錯 |245| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設為 `1` 可停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令會變為無法使用，任何已設定的 `advisorModel` 都會被忽略，且 `--advisor` 旗標雖會被接受但不會產生作用，因此傳遞該旗標的現有指令碼可繼續運作而不會出錯 |

246| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設為 `1` 可關閉[背景 agent 與 agent view](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 及隨需 supervisor。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |246| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設為 `1` 可關閉[背景 agent 和 agent view](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 以及隨需 supervisor。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |

247| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設為 `1` 可停用[全螢幕呈現](/docs/zh-TW/fullscreen)並使用傳統的主畫面呈現器。對話會保留在終端機的原生捲動緩衝區中，因此 `Cmd+f` 與 tmux 複製模式可照常運作。優先於 `CLAUDE_CODE_NO_FLICKER` 與 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/docs/zh-TW/agent-view) 開啟的背景工作階段，這些工作階段一律使用全螢幕呈現 |247| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設為 `1` 可停用[全螢幕呈現](/docs/zh-TW/fullscreen)，並使用傳統的主畫面呈現器。對話會保留在終端機的原生捲動緩衝區中，因此 `Cmd+f` 和 tmux 複製模式可照常運作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/docs/zh-TW/agent-view) 開啟的背景工作階段，這些工作階段一律使用全螢幕呈現 |

248| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設為 `1` 可關閉 [Artifact](/docs/zh-TW/artifacts) 工具，該工具會將工作階段輸出發佈為 claude.ai 上的私人網頁。設定後，任何設定檔都無法重新開啟此工具。若要改從設定檔關閉此工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 鍵也能將其關閉 |248| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設為 `1` 可關閉 [Artifact](/docs/zh-TW/artifacts) 工具，該工具會將工作階段輸出發布為 claude.ai 上的私人網頁。一旦設定，任何設定檔都無法重新開啟該工具。若要改從設定檔關閉該工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 鍵也可將其關閉 |

250| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 設為 `1` 可讓 Claude Code 程序自行執行其 [`gcpAuthRefresh`](/docs/zh-TW/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-TW/settings-reference#awsauthrefresh) 命令，而非在另一個程序執行時等待。需要 Claude Code v2.1.286 或更新版本 |250| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 設為 `1` 可讓 Claude Code 程序自行執行其 [`gcpAuthRefresh`](/docs/zh-TW/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-TW/settings-reference#awsauthrefresh) 命令，而不是在另一個程序執行該命令時等待。需要 Claude Code v2.1.286 或更新版本 |

251| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設為 `1` 可停用[自動記憶](/docs/zh-TW/memory#auto-memory)。設為 `0` 可強制開啟自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 原本會將其停用。停用時，Claude 不會建立或載入自動記憶檔案 |251| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設為 `1` 可停用[自動記憶](/docs/zh-TW/memory#auto-memory)。設為 `0` 可強制開啟自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 原本會將其停用。停用時，Claude 不會建立或載入自動記憶檔案 |

252| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設為 `1` 可停用所有背景任務功能，包括 Bash 與 subagent 工具上的 `run_in_background` 參數、自動背景化，以及 Ctrl+B 快速鍵 |252| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設為 `1` 可停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景化以及 Ctrl+B 快捷鍵 |

253| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設為 `1` 可讓 Claude Code 停止將缺少或為空 `Content-Type` 標頭的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。預設情況下，Claude Code 會假設是閘道從原本未修改的回應中移除了該標頭，因此會解碼主體，讓串流持續運作。僅在閘道同時將串流重新以 server-sent events 發出時才設定此變數；屆時 Claude Code 會改將無標頭的主體讀取為 server-sent events。需要 Claude Code v2.1.239 或更新版本 |253| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設為 `1` 可阻止 Claude Code 將缺少 `Content-Type` 標頭或該標頭為空的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。預設情況下，Claude Code 會假設閘道從原本未經修改的回應中移除了該標頭，因此會解碼本文，讓串流持續運作。僅在閘道也將串流重新輸出為 server-sent events 時才設定此變數；Claude Code 隨後會將沒有標頭的本文讀為 server-sent events。需要 Claude Code v2.1.239 或更新版本 |

254| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設為 `1` 可略過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` content-type。若未設定此變數，當回應帶有不同的 content-type 時，Claude Code 會使請求失敗並顯示指出該類型的錯誤，這表示有[閘道或代理伺服器正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。請設定閘道不加修改地轉送 `Content-Type` 標頭與主體，而非設定此變數。需要 Claude Code v2.1.208 或更新版本 |254| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設為 `1` 可略過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` content-type。若沒有此變數，當回應帶有不同的 content-type 時，Claude Code 會使請求失敗，並顯示指出該類型的錯誤，這表示[閘道或代理伺服器正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。請將閘道設定為不經修改地轉送 `Content-Type` 標頭和本文，而不是設定此變數。需要 Claude Code v2.1.208 或更新版本 |

255| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設為 `1` 可在 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新[背景工作階段](/docs/zh-TW/agent-view)的程序時，停止該工作階段正在執行的背景 shell 命令、動態工作流程，以及自 v2.1.198 起的背景 subagent，而非將它們交給該工作階段的下一個程序。僅影響此交接：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化時，仍會延續進行中的工作，而 `CLAUDE_DISABLE_ADOPT` 會同時關閉兩者。需要 Claude Code v2.1.196 或更新版本 |255| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設為 `1` 可在 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新[背景工作階段](/docs/zh-TW/agent-view)的程序時，停止該工作階段正在執行的背景 shell 命令、動態工作流程，以及（自 v2.1.198 起）背景 subagent，而不是將它們移交給該工作階段的下一個程序。僅影響該移交：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，仍會將進行中的工作帶過去，而 `CLAUDE_DISABLE_ADOPT` 會同時關閉兩者。需要 Claude Code v2.1.196 或更新版本 |

256| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設為 `1` 可讓 Claude Code 停止在記憶體壓力下終止[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 與 Linux 上，當作業系統回報嚴重記憶體壓力，且工作階段已閒置 30 分鐘、沒有任何回合或 subagent 在執行時，Claude Code 會終止背景 shell。Windows 沒有記憶體壓力訊號，因此此變數在該平台上沒有作用。需要 Claude Code v2.1.193 或更新版本 |256| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設為 `1` 可阻止 Claude Code 在記憶體壓力下終止[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 和 Linux 上，當作業系統回報嚴重記憶體壓力，且工作階段已閒置 30 分鐘、沒有任何回合或 subagent 在執行時，Claude Code 會終止背景 shell。Windows 沒有記憶體壓力訊號，因此此變數在 Windows 上沒有作用。需要 Claude Code v2.1.193 或更新版本 |

257| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設為 `1` 可停用 Claude Code 隨附的 [skill](/docs/zh-TW/skills) 與工作流程：隨附 skill 與工作流程會被完全移除，而 `/init` 等內建命令仍可輸入，但會對模型隱藏。`/doctor` 與內建命令一樣仍可輸入；請改用 `DISABLE_DOCTOR_COMMAND` 將其隱藏。來自外掛、`.claude/skills/` 與 `.claude/commands/` 的 skill 不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |257| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設為 `1` 可停用 Claude Code 隨附的 [skill](/docs/zh-TW/skills) 和工作流程：隨附 skill 和工作流程會被完全移除，而 `/init` 等內建命令仍可輸入，但會對模型隱藏。`/doctor` 與內建命令一樣仍可輸入；請改用 `DISABLE_DOCTOR_COMMAND` 將其隱藏。來自外掛、`.claude/skills/` 和 `.claude/commands/` 的 skill 不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |

258| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設為 `1` 可保留 [Claude in Chrome](/docs/zh-TW/chrome) 瀏覽器工具，同時省略系統提示詞中的 Chrome 章節與 `/claude-in-chrome` [隨附 skill](/docs/zh-TW/skills#bundled-skills)。適用於嵌入 Claude Code 並提供自有瀏覽器指引的主機。需要 Claude Code v2.1.257 或更新版本 |258| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設為 `1` 可保留 [Claude in Chrome](/docs/zh-TW/chrome) 瀏覽器工具，同時省略系統提示詞中的 Chrome 區段以及 `/claude-in-chrome` [隨附 skill](/docs/zh-TW/skills#bundled-skills)。適用於嵌入 Claude Code 並提供自有瀏覽器指引的主機。需要 Claude Code v2.1.257 或更新版本 |

260| `CLAUDE_CODE_DISABLE_CRON` | 設為 `1` 可停用[排程任務](/docs/zh-TW/scheduled-tasks)。`/loop` skill 與 cron 工具將無法使用，且任何已排程的任務都會停止觸發，包括在工作階段中已在執行的任務 |260| `CLAUDE_CODE_DISABLE_CRON` | 設為 `1` 可停用[排程任務](/docs/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具會變為無法使用，任何已排程的任務都會停止觸發，包括已在工作階段中途執行的任務 |

261| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 設為 `1` 可關閉[關鍵路徑移除](/docs/zh-TW/permission-modes#critical-paths)提示的時間限制。在 `auto` 模式中，Claude Code 會改將這些移除操作傳送給分類器；在 `bypassPermissions` 模式中，提示會等待您的回答。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |261| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 設為 `1` 可關閉[關鍵路徑移除](/docs/zh-TW/permission-modes#critical-paths)提示的時間限制。在 `auto` 模式中，Claude Code 隨後會改將這些移除操作傳送給分類器；在 `bypassPermissions` 模式中，提示會等待您的回答。請在啟動 Claude Code 的環境中設定此變數，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |

262| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設為 `1` 可從 API 請求中移除搶先體驗版的 `anthropic-beta` 請求標頭、與其搭配的主體欄位，以及 `defer_loading` 與 `eager_input_streaming` 等 beta 工具結構描述欄位。當代理伺服器閘道以 `anthropic-beta` 標頭的 `Unexpected value(s)` 錯誤或 `Extra inputs are not permitted` 錯誤拒絕請求時，請使用此設定。[停用搶先體驗功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities)列出此變數移除的項目（包括 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)），以及 Claude Code 仍會持續傳送的項目 |262| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設為 `1` 可從 API 請求中移除預先發布的 `anthropic-beta` 請求標頭、與之搭配的本文欄位，以及 `defer_loading` 和 `eager_input_streaming` 等 beta 工具結構描述欄位。當代理伺服器閘道因 `anthropic-beta` 標頭而以 `Unexpected value(s)` 錯誤拒絕請求，或出現 `Extra inputs are not permitted` 錯誤時使用。[停用預先發布功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities)列出此變數移除的項目（包括 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)），以及 Claude Code 仍會繼續傳送的項目 |

263| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設為 `1` 可停用內建的 [Explore 與 Plan subagent](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 會改用其搜尋工具或 general-purpose subagent 進行探索，而 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 會直接讀取檔案，而非啟動 Explore 與 Plan agent。名為 `Explore` 或 `Plan` 的自訂 subagent 不受影響。若要在 Agent SDK 或非互動模式中移除所有內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |263| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設為 `1` 可停用內建的 [Explore 和 Plan subagent](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 會改用其搜尋工具或 general-purpose subagent 進行探索，而 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 會直接讀取檔案，而不是啟動 Explore 和 Plan agent。名為 `Explore` 或 `Plan` 的自訂 subagent 不受影響。若要在 Agent SDK 或非互動模式中移除所有內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |

265| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設為 `1` 可停用「How is Claude doing?」工作階段品質調查。當設定了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，調查也會停用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新選擇加入。若要設定抽樣率而非完全停用，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys) |265| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設為 `1` 可停用「How is Claude doing?」工作階段品質調查。當設定了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，調查也會停用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新選擇加入。若要設定取樣率而非完全停用，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys) |

266| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設為 `1` 可停用檔案[檢查點功能](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆寫 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |266| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設為 `1` 可停用檔案[檢查點功能](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆寫 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |

267| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設為 `1` 可從 Claude 的上下文中移除內建的提交與 PR 工作流程指令，以及 git 狀態快照。適用於使用您自己的 git 工作流程 skill 時。設定後，優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |267| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設為 `1` 可從 Claude 的上下文中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skill 時很有用。設定後優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |

268| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 設為 `1` 可讓 Claude Code 停止讀取以 `-c` 傳給 shell 的指令碼（例如 `bash -c 'rm -rf ~'`）來檢查[關鍵路徑](/docs/zh-TW/permission-modes#removals-inside-nested-commands-and-inline-scripts)移除操作。Claude Code 仍會檢查這些指令碼中的 shell 變數與位置參數目標，其他關鍵路徑檢查也會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.288 或更新版本 |268| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 設為 `1` 可阻止 Claude Code 讀取以 `-c` 傳遞給 shell 的指令碼（例如 `bash -c 'rm -rf ~'`）來檢查[關鍵路徑](/docs/zh-TW/permission-modes#removals-inside-nested-commands-and-inline-scripts)移除。Claude Code 仍會檢查這些指令碼中的 shell 變數和位置參數目標，其他關鍵路徑檢查也會繼續執行。請在啟動 Claude Code 的環境中設定此變數，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.288 或更新版本 |

269| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設為 `1` 可防止在 Anthropic API 上將 Opus 4.0 與 4.1 自動重新對應至目前的 Opus 版本。當您刻意想固定較舊的模型時使用。此重新對應不會在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |269| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設為 `1` 可防止在 Anthropic API 上將 Opus 4.0 和 4.1 自動重新對應至目前的 Opus 版本。當您刻意要固定使用較舊模型時使用。在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上不會執行重新對應 |

270| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 設為 `1` 可讓 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#when-a-model-is-disabled-mid-session) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai#when-a-model-is-disabled-mid-session) 上的 Claude Code，在您的帳戶於工作階段中途失去該工作階段模型的存取權時，不改用較舊的模型；被拒絕的請求會立即失敗。您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)在遭到此拒絕時仍會切換，而[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)在啟動時仍會改用備援模型。需要 Claude Code v2.1.285 或更新版本 |270| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 設為 `1` 可阻止 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#when-a-model-is-disabled-mid-session) 和 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai#when-a-model-is-disabled-mid-session) 上的 Claude Code 在您的帳戶於工作階段中途失去工作階段模型的存取權時切換至較舊模型；被拒絕的請求會改為立即失敗。您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)仍會在該拒絕發生時切換，而[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)仍會在啟動時改用備援。需要 Claude Code v2.1.285 或更新版本 |

271| `CLAUDE_CODE_DISABLE_MOUSE` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用滑鼠追蹤。使用 `PgUp` 與 `PgDn` 的鍵盤捲動仍可運作。使用此設定可保留終端機原生的選取即複製行為 |271| `CLAUDE_CODE_DISABLE_MOUSE` | 設為 `1` 可停用[全螢幕呈現](/docs/zh-TW/fullscreen)中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍可運作。使用此變數可保留終端機原生的選取即複製行為 |

272| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用點擊、拖曳與懸停處理，同時保留滑鼠滾輪捲動。當您希望在 Claude Code 中使用滾輪捲動，但不希望點擊會移動游標、展開工具輸出或開啟連結時，請使用此設定。兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |272| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設為 `1` 可停用[全螢幕呈現](/docs/zh-TW/fullscreen)中的點擊、拖曳和懸停處理，同時保留滑鼠滾輪捲動。當您希望在 Claude Code 中使用滾輪捲動，但不希望點擊時定位游標、展開工具輸出或開啟連結時使用。兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |

273| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設為 `1` 可讓 Claude Code 在 API 請求因連線層級錯誤（例如連線重設或 TLS 交握錯誤）失敗時，停止重新讀取 [mTLS 用戶端憑證與金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 只會在下次套用設定時或下次啟動時載入已輪替的檔案。需要 Claude Code v2.1.232 或更新版本 |273| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設為 `1` 可阻止 Claude Code 在 API 請求因連線層級錯誤（例如連線重設或 TLS 交握錯誤）而失敗時重新讀取 [mTLS 用戶端憑證和金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 只會在下次套用設定時或下次啟動時載入輪替後的檔案。需要 Claude Code v2.1.232 或更新版本 |

274| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設為任何非空值（例如 `1`）可停用非必要的網路流量：自動更新、遙測、錯誤回報、`/feedback` 命令、[Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、版本資訊、[PR 與 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status)檢查，以及[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)檢查等可用性檢查。它也會停止[外掛 `command` 來源的背景執行](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)，這些是本機命令而非網路流量，但因為它們可能觸發相依套件安裝，所以一併停止。**設為 `0` 或 `false` 仍會停用此流量**，這與大多數開關型變數不同；請取消設定此變數才能再次允許。也會停用功能旗標擷取，這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 及其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。不涵蓋官方外掛市集的自動安裝；請使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 將其停用。不影響[閘道模型探索](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，該功能有其自己的選擇加入機制 |274| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設為任何非空值（例如 `1`）可停用非必要的網路流量：自動更新、遙測、錯誤回報、`/feedback` 命令、[Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、版本資訊、[PR 和 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status)檢查，以及可用性檢查，例如[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)檢查。它也會停止[外掛 `command` 來源的背景執行](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)；這些是本機命令而非網路流量，但因為它們可能觸發相依套件安裝而一併停止。**設為 `0` 或 `false` 仍會停用此流量**，這與大多數開關變數不同；請取消設定此變數以重新允許。也會停用功能旗標擷取，使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。不涵蓋官方外掛市集自動安裝；請使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 將其停用。不影響[閘道模型探索](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，該功能有自己的選擇加入機制 |

276| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設為 `1` 可讓 `PushNotification` 工具即使在您正在終端機中輸入或終端機處於焦點時，仍傳送桌面通知。預設情況下，當偵測到近期的鍵盤活動或終端機焦點時，該工具會同時略過桌面通知與[行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此當伺服器偵測到您處於活動狀態時，仍可能抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |276| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設為 `1` 可在您正在終端機中輸入或聚焦於終端機時，仍傳送 `PushNotification` 工具的桌面通知。預設情況下，當該工具偵測到最近的鍵盤活動或終端機焦點時，會同時略過桌面通知和[行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此當伺服器偵測到您處於活動狀態時，仍可抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |

277| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設為 `1` 可停用官方外掛市集的自動註冊。Claude Code 會在即將註冊市集時讀取此變數，通常是在機器首次互動式啟動期間。若當時已設定此變數，Claude Code 會永久略過註冊。之後取消設定此變數並不會撤銷略過。您可以隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 來註冊市集 |277| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設為 `1` 可停用官方外掛市集的自動註冊。Claude Code 會在即將註冊市集時讀取此變數，通常是在機器第一次互動式啟動期間。如果當時已設定此變數，Claude Code 會永久略過註冊。之後取消設定此變數不會撤銷此略過。隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 即可註冊市集 |

278| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設為 `1` 可讓 Claude Code 在將權限請求傳送至 Agent SDK 的 `canUseTool` 回呼的工作階段中，停止執行您的[針對未回答權限請求的 `Notification` hook](/docs/zh-TW/hooks#notification)；Claude Desktop 與 VS Code 擴充功能即是以此方式承載 Claude Code。在終端機工作階段中沒有作用。需要 Claude Code v2.1.233 或更新版本 |278| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設為 `1` 可在 Claude Code 將權限請求傳送至 Agent SDK `canUseTool` 回呼的工作階段中（Claude Desktop 和 VS Code 擴充功能即以此方式承載 Claude Code），阻止 Claude Code 執行您[針對未回答權限請求的 `Notification` hook](/docs/zh-TW/hooks#notification)。在終端機工作階段中沒有作用。需要 Claude Code v2.1.233 或更新版本 |

280| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 設為 `1` 可關閉 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)的檢查，該檢查會拒絕在[系統路徑](/docs/zh-TW/permission-modes#remove-item-in-powershell)（例如磁碟機根目錄或您的家目錄）上使用 `cmd` 內建命令 `rd`、`rmdir`、`del` 與 `erase`。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.283 或更新版本 |280| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 設為 `1` 可關閉 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)在[系統路徑](/docs/zh-TW/permission-modes#remove-item-in-powershell)（例如磁碟機根目錄或您的家目錄）上拒絕 `cmd` 內建命令 `rd`、`rmdir`、`del` 和 `erase` 的檢查。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.283 或更新版本 |

281| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 設為 `1` 可關閉[安全分類器標記請求時的自動模型切換](/docs/zh-TW/model-config#automatic-model-fallback)，即由 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設定所控制的行為 |281| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 設為 `1` 可關閉[安全分類器標記請求時的自動模型切換](/docs/zh-TW/model-config#automatic-model-fallback)，也就是 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設定所控制的行為 |

282| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 設為 `1` 可讓 Claude Code 停止傳送結構化輸出的 `output_config.format` 欄位及與其搭配的 `anthropic-beta` 值，適用於上游會拒絕這些內容的 [LLM 閘道](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)。這會保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 會關閉的其他搶先體驗功能。需要 Claude Code v2.1.288 或更新版本 |282| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 設為 `1` 可阻止 Claude Code 傳送結構化輸出的 `output_config.format` 欄位以及與之搭配的 `anthropic-beta` 值，適用於上游會拒絕它們的 [LLM 閘道](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)。這會保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 所關閉的其他預先發布功能。需要 Claude Code v2.1.288 或更新版本 |

283| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 設為 `1` 可關閉針對遞迴 `rm` 的[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)檢查，該 `rm` 的目標完全是命令替換的輸出，例如 `rm -rf "$(pwd)"`。其他關鍵路徑檢查會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |283| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 設為 `1` 可關閉針對目標完全為命令替換輸出之遞迴 `rm`（例如 `rm -rf "$(pwd)"`）的[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)檢查。其他關鍵路徑檢查會繼續執行。請在啟動 Claude Code 的環境中設定此變數，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |

284| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設為 `1` 可停用根據對話上下文自動更新終端機標題。這也會略過[產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions)的背景小型/快速模型請求 |284| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設為 `1` 可停用根據對話上下文自動更新終端機標題。這也會略過[產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions)的背景小型/快速模型請求 |

285| `CLAUDE_CODE_DISABLE_THINKING` | 設為 `1` 可從 API 請求中完全省略 `thinking` 參數。這是針對會拒絕該參數之代理伺服器與閘道的相容性選項。在預設會思考的模型上，省略該參數代表模型仍可能會思考。若要在 Anthropic API 上明確停用[延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。這兩個變數都無法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上關閉思考，這些模型無法關閉思考。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同樣會省略該參數，因此兩個變數在該處的行為相同 |285| `CLAUDE_CODE_DISABLE_THINKING` | 設為 `1` 可從 API 請求中完全省略 `thinking` 參數。這是針對會拒絕此參數之代理伺服器和閘道的相容性選項。在預設會思考的模型上，省略此參數表示模型仍可能思考。若要在 Anthropic API 上明確停用[延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上，兩個變數都無法關閉思考，因為這些模型的思考無法關閉。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同樣會省略此參數，因此兩個變數在那裡的行為相同 |

286| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設為 `1` 可在 Claude Code 無法辨識模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）時，略過主動[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)。若未設定此變數，Claude Code 會依其為該 ID 假設的上下文視窗進行壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 則可改為修正所假設的視窗；關於各變數的適用時機，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更新版本 |286| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設為 `1` 可在 Claude Code 無法辨識模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）時略過主動[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)。若沒有此變數，Claude Code 會依其為該 ID 假設的上下文視窗進行壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 則可改為修正假設的視窗；關於各變數的適用時機，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更新版本 |

287| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用虛擬捲動，並呈現逐字稿中的每一則訊息。若在全螢幕模式中捲動時，應出現訊息的地方顯示為空白區域，請使用此設定 |287| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設為 `1` 可停用[全螢幕呈現](/docs/zh-TW/fullscreen)中的虛擬捲動，並呈現逐字稿中的每則訊息。如果在全螢幕模式中捲動時，應出現訊息的位置顯示為空白區域，請使用此變數 |

288| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 設為 `1` 可關閉 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 工具仍可使用。需要 Claude Code v2.1.285 或更新版本 |288| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 設為 `1` 可關閉 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 工具仍可使用。需要 Claude Code v2.1.285 或更新版本 |

289| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 設為 `1` 可在 Windows 上直接啟動 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)命令，而非透過 `cmd.exe` 啟動器。預設情況下，啟動器能讓[在背景執行](/docs/zh-TW/tools-reference#background-commands)的 PowerShell 命令[延續至工作階段的下一個程序](/docs/zh-TW/agent-view#the-supervisor-process)，例如當您[將工作階段背景化](/docs/zh-TW/agent-view#from-inside-a-session)時。若您設定此變數，背景化的 PowerShell 命令會在工作階段的程序結束時停止。Bash 命令不受影響。需要 Claude Code v2.1.269 或更新版本 |289| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 設為 `1` 可在 Windows 上直接啟動 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)命令，而不透過 `cmd.exe` 啟動器。預設情況下，啟動器可讓[在背景執行](/docs/zh-TW/tools-reference#background-commands)的 PowerShell 命令[延續至工作階段的下一個程序](/docs/zh-TW/agent-view#the-supervisor-process)，例如當您[將工作階段移至背景](/docs/zh-TW/agent-view#from-inside-a-session)時。如果設定此變數，移至背景的 PowerShell 命令會在工作階段程序結束時停止。Bash 命令不受影響。需要 Claude Code v2.1.269 或更新版本 |

290| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設為 `1` 可停用[工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |290| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設為 `1` 可停用[工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |

291| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定 effort 等級。值：`low`、`medium`、`high`、`xhigh`、`max`，或 `auto` 以使用模型預設值。可用等級取決於模型。優先於 `--effort`、`/effort`，以及 `modelSettings` 與 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍會套用。請參閱[調整 effort 等級](/docs/zh-TW/model-config#adjust-effort-level) |291| `CLAUDE_CODE_EFFORT_LEVEL` | 設定支援模型的 effort 等級。值：`low`、`medium`、`high`、`xhigh`、`max`，或 `auto` 以使用模型預設值。可用等級取決於模型。優先於 `--effort`、`/effort` 以及 `modelSettings` 和 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍然適用。請參閱[調整 effort 等級](/docs/zh-TW/model-config#adjust-effort-level) |

292| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 設為 `1` 可在訊息串流中加入帶有工作階段狀態的 [`session_state_changed`](/docs/zh-TW/agent-sdk/typescript#sdksessionstatechangedmessage) 訊息。需要 [Agent SDK](/docs/zh-TW/agent-sdk/overview)，或同時使用 `--print`、`--output-format stream-json` 與 `--verbose` |292| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 設為 `1` 可將帶有工作階段狀態的 [`session_state_changed`](/docs/zh-TW/agent-sdk/typescript#sdksessionstatechangedmessage) 訊息加入訊息串流。需要 [Agent SDK](/docs/zh-TW/agent-sdk/overview)，或同時使用 `--print`、`--output-format stream-json` 和 `--verbose` |

293| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為了與舊版相容而接受，但沒有任何作用。自動模式在每個供應商上皆預設可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry，以及已登入的 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)工作階段。在 v2.1.158 至 v2.1.206 中，必須將此設為 `1`，才能在這些供應商上使用[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) |293| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為了與舊版相容而接受，但不會產生任何效果。自動模式在每個提供者上預設皆可使用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry，以及已登入的 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 至 v2.1.206 中，必須將此變數設為 `1`，才能讓 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 在這些提供者上可用 |

294| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆寫[工作階段回顧](/docs/zh-TW/interactive-mode#session-recap)的可用性。設為 `0` 可強制關閉回顧，不論 `/config` 切換開關為何。當 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時，設為 `1` 可強制開啟回顧。優先於該設定與 `/config` 切換開關 |294| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆寫 [工作階段回顧](/docs/zh-TW/interactive-mode#session-recap) 的可用性。設為 `0` 可強制關閉回顧，不論 `/config` 切換開關為何。設為 `1` 可在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制開啟回顧。優先於該設定與 `/config` 切換開關 |

295| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設為 `1` 可在[非互動模式](/docs/zh-TW/headless)中，於背景安裝完成後在回合邊界重新整理外掛狀態。預設為關閉，因為重新整理會在工作階段中途變更系統提示詞，導致該回合的[提示快取](/docs/zh-TW/prompt-caching)失效 |295| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設為 `1` 可在背景安裝完成後，於 [非互動模式](/docs/zh-TW/headless) 的回合邊界重新整理外掛狀態。預設關閉，因為重新整理會在工作階段中途變更系統提示詞，導致該回合的 [提示快取](/docs/zh-TW/prompt-caching) 失效 |

296| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設為 `1` 可在傳送至 Anthropic 的非必要流量遭封鎖時，將「How is Claude doing?」工作階段品質調查導向您自己的 [OpenTelemetry collector](/docs/zh-TW/monitoring-usage)。調查評分僅會以 OTEL 事件的形式傳送至您設定的 collector。在此模式下，不會有任何調查資料傳送給 Anthropic。適用於已設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 的情況，否則沒有作用。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 與組織的產品意見回饋政策優先於此變數 |296| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設為 `1` 可在傳送至 Anthropic 的非必要流量遭封鎖時，將「How is Claude doing?」工作階段品質問卷導向您自己的 [OpenTelemetry collector](/docs/zh-TW/monitoring-usage)。問卷評分僅會以 OTEL 事件的形式傳送至您設定的 collector。在此模式下，不會有任何問卷資料傳送至 Anthropic。適用於已設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 的情況，否則不會產生任何效果。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 與組織的產品意見回饋政策優先 |

297| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 產生時即從 API 串流傳送。關閉時，大型工具輸入（例如寫入長檔案）只會在 Claude 產生完畢後才送達，看起來可能像是停滯不動。在 Anthropic API 上預設啟用。在 Amazon Bedrock 與 Google Cloud's Agent Platform 上，會依模型在已部署容器支援時啟用。設為 `0` 可選擇退出。當透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 經由代理伺服器路由時，設為 `1` 可強制啟用。在 Microsoft Foundry 與[閘道](/docs/zh-TW/llm-gateway)連線上預設為關閉 |297| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 產生時就從 API 串流傳送。關閉時，大型工具輸入（例如長檔案寫入）只會在 Claude 完成產生後才送達，看起來可能像是停滯不動。在 Anthropic API 上預設啟用。在 Amazon Bedrock 與 Google Cloud's Agent Platform 上，會在部署的容器支援時依模型啟用。設為 `0` 可選擇退出。透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 經由代理伺服器路由時，設為 `1` 可強制開啟。在 Microsoft Foundry 與 [閘道](/docs/zh-TW/llm-gateway) 連線上預設關閉 |

298| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 當 `ANTHROPIC_BASE_URL` 指向與 Anthropic 相容的閘道（例如 LiteLLM、Kong 或內部代理伺服器）時，設為 `1` 可從閘道的 `/v1/models` 端點填入 `/model` 選擇器。預設為關閉，因為以共用 API 金鑰支援的閘道否則會向每位使用者顯示該金鑰可存取的所有模型。探索到的模型仍會依工作階段收到的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單篩選；請透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)傳遞該清單，因為[伺服器受管傳遞在閘道設定中無法使用](/docs/zh-TW/server-managed-settings#platform-availability) |298| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設為 `1` 可在 `ANTHROPIC_BASE_URL` 指向與 Anthropic 相容的閘道（例如 LiteLLM、Kong 或內部代理伺服器）時，從閘道的 `/v1/models` 端點填入 `/model` 選擇器。預設關閉，因為若非如此，以共用 API 金鑰支援的閘道會向每位使用者顯示該金鑰可存取的所有模型。探索到的模型仍會依工作階段收到的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單進行篩選；請透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms) 提供該清單，因為 [伺服器管理的提供方式不適用於閘道設定](/docs/zh-TW/server-managed-settings#platform-availability) |

300| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設為 `false` 可關閉提示詞建議，即出現在提示詞輸入框中的灰色預測文字。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，也就是 `/config` 中 **Prompt suggestions** 切換開關所寫入的設定。當您的帳戶接近或已達用量上限時，Claude Code 也會[暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設為 `true` 可讓建議持續開啟，直到您達到上限為止。需要 Claude Code v2.1.238 或更新版本。請參閱[提示詞建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |300| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設為 `false` 可關閉提示詞建議，也就是出現在提示詞輸入中的灰色預測文字。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，也就是 `/config` 中 **Prompt suggestions** 切換開關所寫入的設定。當您的帳戶接近或已達用量上限時，Claude Code 也會 [暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設為 `true` 可讓建議持續開啟，直到您達到上限為止。需要 Claude Code v2.1.238 或更新版本。請參閱 [提示詞建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |

301| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在[具備任務追蹤工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中提供哪些任務追蹤工具。預設情況下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 與 `TaskList`。設為 `0` 則改為使用舊版的 `TodoWrite` 工具。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |301| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在 [具備這些工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability) 中提供哪些任務追蹤工具。預設情況下，Claude Code 會提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 與 `TaskList`。設為 `0` 可改用舊版的 `TodoWrite` 工具。請參閱 [任務清單](/docs/zh-TW/interactive-mode#task-list) |

302| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設為 `1` 可啟用 OpenTelemetry 資料收集，用於指標與日誌。必須先設定此變數，才能設定 OTel exporter。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage) |302| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設為 `1` 可啟用 OpenTelemetry 的指標與日誌資料收集。設定 OTel exporter 之前必須先設定此變數。請在您的 shell、使用者設定或受管設定中設定。在 [專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中會被忽略。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

303| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設為 `1` 可在每個模型上取得任務追蹤工具。若未設定，Claude Code 預設只在 [Task 工具可用性](/docs/zh-TW/tools-reference#task-tool-availability)下列出的模型上提供這些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍會選擇 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |303| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設為 `1` 可在每個模型上取得任務追蹤工具。若未設定，Claude Code 只會在 [Task 工具可用性](/docs/zh-TW/tools-reference#task-tool-availability) 下列出的模型上預設提供這些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍會決定使用 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |

306| `CLAUDE_CODE_EXTRA_BODY` | 要合併至每個 API 請求本文最上層的 JSON 物件。適用於傳遞 Claude Code 未直接公開的供應商特定參數。在您的 shell 中匯出的值，也會套用至您以 `claude agents` 或 `--bg` 派送的[背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段會忽略 shell 匯出的值，而使用背景監督程序所繼承的副本 |306| `CLAUDE_CODE_EXTRA_BODY` | 要合併至每個 API 請求本文最上層的 JSON 物件。適用於傳遞 Claude Code 未直接提供的提供者特定參數。在 shell 中匯出的值也會套用至您以 `claude agents` 或 `--bg` 派送的 [背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段會忽略 shell 匯出的值，而改用背景監督程序所繼承的副本 |

308| `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 中沒有作用，因為這兩個版本已移除它所覆寫的巢狀工作階段偵測 |308| `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 上則沒有效果，因為這兩個版本移除了它所覆寫的巢狀工作階段偵測 |

309| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 當您的終端機支援刪除線但未被自動偵測到時（例如透過 SSH 連線且未轉送 `TERM_PROGRAM`），設為 `1` 可強制將 Claude 回應中的 `~~text~~` 呈現為刪除線。若未設定，未被偵測到的終端機會顯示字面的 `~~` 標記，而不會將文字呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |309| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設為 `1` 可在終端機支援但未被自動偵測到時（例如透過 SSH 且未轉送 `TERM_PROGRAM`），強制以刪除線呈現 Claude 回應中的 `~~text~~`。若未設定，未偵測到的終端機會顯示字面上的 `~~` 標記，而不是將文字呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |

310| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 當您的終端機支援 DEC private mode 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)但未被自動偵測到時，設為 `1` 可強制啟用。適用於實作 BSU/ESU 但不回應功能探測的模擬器，例如 Emacs `eat`。在 tmux 下沒有作用。與會切換至[全螢幕呈現](/docs/zh-TW/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此變數不會變更呈現器 |310| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設為 `1` 可在終端機支援但未被自動偵測到時，強制啟用 DEC private mode 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。適用於實作了 BSU/ESU 但不回應功能探測的模擬器，例如 Emacs `eat`。在 tmux 下沒有效果。與會切換至 [全螢幕呈現](/docs/zh-TW/fullscreen) 的 `CLAUDE_CODE_NO_FLICKER` 不同，此變數不會變更渲染器 |

311| `CLAUDE_CODE_FORK_SUBAGENT` | 控制[分叉模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，此模式可讓 Claude 自行產生[分叉 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且預設僅在互動式工作階段中開啟。設為 `1` 可在 `claude -p` 與 Agent SDK 中也開啟，設為 `0` 則在所有類型的工作階段中關閉。無論分叉模式是否開啟，您都可以執行 `/subtask`。互動式預設需要 Claude Code v2.1.232 或更新版本；在較早版本中，請將此變數設為 `1` 以開啟分叉模式 |311| `CLAUDE_CODE_FORCE_TERMINAL_IMAGES` | 設為 `1` 可在終端機以 Unicode 預留位置繪製 kitty 圖形協定圖片但未被自動偵測到時，將 [mod `Image` 元素](/docs/zh-TW/plugins/mods/reference#elements) 繪製為圖片。請參閱 [Claude Code 會偵測哪些終端機](/docs/zh-TW/plugins/mods/gallery#image-and-client)，以及為何此變數在 tmux 或 screen 內無效 |

312| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設為 `1` 可在 `claude -p --output-format stream-json` 輸出中傳出 [subagent](/docs/zh-TW/sub-agents) 的文字與思考區塊，行為與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同。當測試框架呼叫 `claude` 且無法自行傳遞旗標時，請使用此變數。此旗標在非互動模式搭配 stream-json 輸出以外的情況下會以錯誤結束，而此變數在這些情況下會被忽略，因此在整個程序範圍設定時，巢狀呼叫仍可正常運作。需要 Claude Code v2.1.211 或更新版本 |312| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [fork 模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，此模式讓 Claude 能自行產生 [分支 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且僅在互動式工作階段中預設開啟。設為 `1` 可同時在 `claude -p` 與 Agent SDK 中開啟，設為 `0` 則可在所有類型的工作階段中關閉。無論 fork 模式是否開啟，您都可以執行 `/subtask`。互動式的預設行為需要 Claude Code v2.1.232 或更新版本；在較早的版本上，請將此變數設為 `1` 以開啟 fork 模式 |

313| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 設為 `1` 可在自訂代理伺服器或第三方供應商（例如 Amazon Bedrock 或 Claude Platform on AWS）上傳送[閘道提示標頭](/docs/zh-TW/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 與 `x-claude-code-compaction`。設為 `0` 可在所有連線上停止傳送這些標頭，包括直接連線至 Anthropic API 的情況，Claude Code 在該情況下預設會傳送。需要 Claude Code v2.1.273 或更新版本 |313| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設為 `1` 可在 `claude -p --output-format stream-json` 輸出中發出 [subagent](/docs/zh-TW/sub-agents) 的文字與思考區塊，行為與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同。當 harness 呼叫 `claude` 且無法自行傳遞旗標時，請使用此變數。旗標在搭配 stream-json 輸出的非互動模式以外會以錯誤結束，而此變數在這些情況下會被忽略，因此在整個程序範圍內設定時，巢狀呼叫仍能正常運作。需要 Claude Code v2.1.211 或更新版本 |

314| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 開啟的[閘道模型探索](/docs/zh-TW/llm-gateway-protocol#model-discovery)請求的逾時（毫秒）（預設：`3000`）。當您的閘道在啟動時需要超過三秒才能回應 `/v1/models` 時，請調高此值。只接受純數字；`0`、負值及其他寫法會保留預設值。需要 Claude Code v2.1.269 或更新版本 |314| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 設為 `1` 可在自訂代理伺服器或第三方提供者（例如 Amazon Bedrock 或 Claude Platform on AWS）上傳送 [閘道提示標頭](/docs/zh-TW/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 與 `x-claude-code-compaction`。設為 `0` 可在所有連線上停止傳送這些標頭，包括直接連線至 Anthropic API 的情況（Claude Code 預設會在此傳送）。需要 Claude Code v2.1.273 或更新版本 |

315| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 執行檔（`bash.exe`）的路徑。當 Git Bash 已安裝但不在您的 PATH 中時使用。若路徑不存在，或檔案名稱不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略此變數並如同未設定一般自動偵測 Git Bash，同時記錄一則可透過 `--debug` 檢視的警告。在 v2.1.219 之前，當路徑不存在時 Claude Code 會在啟動時結束，且會將任何既有檔案當作 shell 使用，而不檢查其是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |315| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 開啟的 [閘道模型探索](/docs/zh-TW/llm-gateway-protocol#model-discovery) 請求的逾時（毫秒）（預設：`3000`）。當您的閘道在啟動時需要超過三秒才能回應 `/v1/models` 時，請調高此值。僅接受純數字；`0`、負值及其他寫法會維持預設值。需要 Claude Code v2.1.269 或更新版本 |

316| `CLAUDE_CODE_GLOB_HIDDEN` | 設為 `false` 可在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)時，從結果中排除點檔案。預設會包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |316| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 執行檔（`bash.exe`）的路徑。在已安裝 Git Bash 但不在您的 PATH 中時使用。如果路徑不存在，或檔案名稱不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略此變數，並如同未設定一樣自動偵測 Git Bash，同時記錄一則可透過 `--debug` 看到的警告。在 v2.1.219 之前，路徑不存在時 Claude Code 會在啟動時結束，並且會將任何現有檔案當作 shell 使用，而不檢查它是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |

317| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設為 `false` 可讓 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)遵循 `.gitignore` 模式。預設情況下，Glob 會傳回所有符合的檔案，包括被 gitignore 的檔案。不影響 `@` 檔案自動完成，其有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |317| `CLAUDE_CODE_GLOB_HIDDEN` | 設為 `false` 可在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior) 時從結果中排除點檔案。預設會包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |

318| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設為 `false` 可讓 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior) 遵循 `.gitignore` 模式。預設情況下，Glob 會傳回所有符合的檔案，包括被 gitignore 的檔案。不影響 `@` 檔案自動完成，其有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |

319| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可讓進行中的目標等待多少分鐘，之後 Claude Code 會[請 Claude 檢查該目標](/docs/zh-TW/goal#background-work-defers-evaluation)。預設為 `30`。設為 `0` 可關閉檢查。請以純數字提供整數分鐘，最多 `10080`，即一週。Claude Code 會將任何其他值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |320| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可讓進行中的目標等待多少分鐘，之後 Claude Code 會 [要求 Claude 檢查它](/docs/zh-TW/goal#background-work-defers-evaluation)。預設為 `30`。設為 `0` 可關閉檢查。請以純數字提供整數分鐘數，最多 `10080`，也就是一週。Claude Code 會將其他任何值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |

320| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 設為 `0` 可關閉傳送至 `api.anthropic.com` 的 Claude API、遙測與 [artifact](/docs/zh-TW/artifacts) 發布請求本文的 gzip 壓縮。預設情況下，Claude Code 會在直接連線上壓縮大型請求本文，並在您透過代理伺服器傳送請求、設定用戶端憑證或設定 `NODE_EXTRA_CA_CERTS` 時略過壓縮。若 Claude Code 無法偵測的 [TLS 檢查代理伺服器](/docs/zh-TW/network-config#ca-certificate-store)錯誤處理壓縮的請求，請使用 `0` |321| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 設為 `0` 可關閉傳送至 `api.anthropic.com` 的 Claude API、遙測與 [artifact](/docs/zh-TW/artifacts) 發布請求本文的 gzip 壓縮。預設情況下，Claude Code 會在直接連線時壓縮大型請求本文，並在您透過代理伺服器傳送請求、設定用戶端憑證或設定 `NODE_EXTRA_CA_CERTS` 時略過壓縮。如果 Claude Code 無法偵測的 [TLS 檢查代理伺服器](/docs/zh-TW/network-config#ca-certificate-store) 無法正確處理壓縮的請求，請使用 `0` |

323| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設為 `1` 可略過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設為 `false` |324| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設為 `1` 可略過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設為 `false` |

325| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 一個工作階段中可同時執行多少個 [subagent](/docs/zh-TW/sub-agents#concurrent-subagent-limit)，超過後 Agent 工具將拒絕再產生新的 subagent（預設：20）。接受以純數字表示的正整數；其他任何值都會被忽略，因此此變數可以調整上限，但無法停用上限。需要 Claude Code v2.1.217 或更新版本 |326| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在 Agent 工具拒絕再產生另一個之前，一個工作階段中可同時執行多少個 [subagent](/docs/zh-TW/sub-agents#concurrent-subagent-limit)（預設：20）。接受純數字的正整數；其他任何值都會被忽略，因此此變數可以調整上限，但無法停用上限。需要 Claude Code v2.1.217 或更新版本 |

326| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆寫 Claude Code 為目前使用中的模型所假設的上下文視窗大小。自 v2.1.193 起，其套用方式取決於 Claude Code 如何解析模型 ID；請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。當透過 `ANTHROPIC_BASE_URL` 路由至某個模型，而其上下文視窗與該名稱的內建大小不符時，請使用此變數 |327| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆寫 Claude Code 為使用中模型假設的上下文視窗大小。從 v2.1.193 起，其套用方式取決於 Claude Code 如何解析模型 ID；請參閱 [為閘道或自訂模型 ID 修正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。當透過 `ANTHROPIC_BASE_URL` 路由至上下文視窗與其名稱對應之內建大小不符的模型時使用 |

327| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 傳送給模型的每個 MCP 工具描述與每個 MCP 伺服器指令的最大長度（字元數）（預設：2048）。Claude Code 會[截斷較長的文字](/docs/zh-TW/mcp#for-mcp-server-authors)。接受以純數字表示的正整數。其他任何值都會被忽略並套用預設值。需要 Claude Code v2.1.280 或更新版本 |328| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 傳送給模型的每個 MCP 工具描述與每個 MCP 伺服器指令的最大長度（字元）（預設：2048）。Claude Code 會 [截斷較長的文字](/docs/zh-TW/mcp#for-mcp-server-authors)。接受純數字的正整數。其他任何值都會被忽略並套用預設值。需要 Claude Code v2.1.280 或更新版本 |

328| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值與上限因模型而異；請參閱[最大輸出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 會將超過模型上限的值降至上限。對於 Claude Code 無法解析為已知模型的模型 ID，預設值為 32000，上限為 128000。提高此值會減少觸發[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)前可用的有效上下文視窗 |329| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值與上限因模型而異；請參閱 [最大輸出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 會將超過模型上限的值降至上限。對於 Claude Code 無法解析為已知模型的模型 ID，預設值為 32000，上限為 128000。增加此值會減少觸發 [自動壓縮](/docs/zh-TW/costs#reduce-token-usage) 之前可用的有效上下文視窗 |

329| `CLAUDE_CODE_MAX_RETRIES` | 覆寫失敗 API 請求的重試次數（預設：10）。自 v2.1.186 起上限為 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要撐過較長中斷時間的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |330| `CLAUDE_CODE_MAX_RETRIES` | 覆寫失敗 API 請求的重試次數（預設：10）。從 v2.1.186 起上限為 15；從 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要撐過較長服務中斷的無人看管工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |

330| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已於 v2.1.224 移除，現在不具作用。先前用於限制 Claude 在一個工作階段中可透過 Agent 工具產生的 [subagent](/docs/zh-TW/sub-agents) 總數（預設：200）；超過上限時產生會以 `Subagent spawn limit reached` 失敗。[同時 subagent 上限](/docs/zh-TW/sub-agents#concurrent-subagent-limit)與[深度上限](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)仍然適用 |331| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已於 v2.1.224 移除，現在不會產生任何作用。先前用於限制 Claude 在一個工作階段中可使用 Agent 工具產生的 [subagent](/docs/zh-TW/sub-agents) 總數（預設：200）；超過上限時，產生作業會失敗並顯示 `Subagent spawn limit reached`。[同時執行 subagent 限制](/docs/zh-TW/sub-agents#concurrent-subagent-limit) 與 [深度限制](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 仍然適用 |

331| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主對話之下允許的 [subagent 層數](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)（預設：3）。在預設值下，subagent 可以產生自己的 subagent，而第三層的 subagent 無法再往下產生；設為 `1` 可關閉巢狀。在 v2.1.217 至 v2.1.218 中，預設值為 1，因此除非您提高上限，否則 subagent 無法產生自己的 subagent；v2.1.219 將預設值提高為 3。接受以純數字表示的正整數；其他任何值都會被忽略，因此上限可以調整但無法移除。需要 Claude Code v2.1.217 或更新版本 |332| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主要對話之下允許的 [subagent 層數](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) （預設：3）。在預設值下，subagent 可以產生自己的 subagent，而位於第三層的 subagent 無法再繼續產生；設為 `1` 可關閉巢狀。在 v2.1.217 至 v2.1.218 中，預設值為 1，因此除非您提高限制，否則 subagent 無法產生自己的 subagent；v2.1.219 將預設值提高為 3。接受純數字的正整數；其他任何值都會被忽略，因此限制可以調整，但無法移除。需要 Claude Code v2.1.217 或更新版本 |

333| `CLAUDE_CODE_MAX_TURNS` | 在未傳遞明確上限時，限制 agentic 回合的數量。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，兩者皆設定時以旗標為優先。非正整數的值會在啟動時以錯誤拒絕，而不會被視為無上限 |334| `CLAUDE_CODE_MAX_TURNS` | 在未傳遞明確限制時，限制 agentic 回合數。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，兩者都設定時以旗標優先。不是正整數的值會在啟動時以錯誤拒絕，而不是視為沒有上限 |

334| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一個工作階段可進行的 [WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 呼叫總數上限（預設：200）。當 Claude 達到上限時，後續的 WebSearch 呼叫會傳回通知，告知它以已收集到的資訊繼續進行。接受沒有上限的正整數。其他任何值都會被忽略並套用預設值，因此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |335| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | [WebSearch](/docs/zh-TW/tools-reference#session-search-limit) 呼叫次數的上限（預設：200）。當 Claude 達到上限時，後續的 WebSearch 呼叫會傳回通知，告訴它以已收集到的資訊繼續進行。接受沒有上限的正整數。其他任何值都會被忽略並套用預設值，因此上限可以提高，但無法關閉。需要 Claude Code v2.1.212 或更新版本 |

336| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行中的 MCP 工具呼叫[移至背景任務](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls)前經過的時間（毫秒）（預設：120000，即 2 分鐘）。設為 `0` 可關閉自動背景化。需要 Claude Code v2.1.212 或更新版本 |337| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行的 MCP 工具呼叫 [移至背景任務](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) 前所經過的時間（毫秒）（預設：120000，即 2 分鐘）。設為 `0` 可關閉自動移至背景。需要 Claude Code v2.1.212 或更新版本 |

337| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非互動](/docs/zh-TW/headless)工作階段的第一個回合等待仍在連線中的 MCP 伺服器的時間（毫秒），取代預設的[第一回合等待](/docs/zh-TW/agent-sdk/mcp#connection-timing)。設定後，等待會涵蓋所有待處理的伺服器。設為 `0` 可略過等待。[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 伺服器無論此值為何，都會保留自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更新版本 |338| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非互動](/docs/zh-TW/headless) 工作階段的第一個回合等待仍在連線中之 MCP 伺服器的時間（毫秒），取代預設的 [第一回合等待](/docs/zh-TW/agent-sdk/mcp#connection-timing)。設定後，等待會涵蓋所有擱置中的伺服器。設為 `0` 可略過等待。無論此值為何，[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 伺服器都會保留自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更新版本 |

338| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在這段時間內未傳送任何回應或進度通知時，工具呼叫會以錯誤中止，而不會等待整體的 `MCP_TOOL_TIMEOUT`。覆寫各傳輸方式的預設值：網路伺服器為 300000（5 分鐘），stdio 伺服器為 1800000（30 分鐘）。設為 `0` 可停用閒置檢查。低於 1000 的值會提高為一秒，且此值的上限為實際生效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少為 1000 的個別伺服器 `timeout`，會將該伺服器的閒置時間窗提高至至少為 `timeout` 值。不適用於 IDE 伺服器或 SDK 程序內伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |339| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在這段時間內未傳送任何回應或進度通知時，工具呼叫會以錯誤中止，而不是等待整體的 `MCP_TOOL_TIMEOUT`。覆寫各傳輸方式的預設值：網路伺服器為 300000（5 分鐘），stdio 伺服器為 1800000（30 分鐘）。設為 `0` 可停用閒置檢查。低於 1000 的值會提高至一秒，且此值的上限為有效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少為 1000 的個別伺服器 `timeout`，會將該伺服器的閒置時間窗口提高至至少為 `timeout` 值。不適用於 IDE 伺服器或 SDK 程序內伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |

339| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，而非由您設定：在繫結[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會在繫結 socket 時將該 socket 的路徑匯出給 hook 與 Bash 命令。在啟動時即開啟訊息功能的工作階段中，Claude Code 會在任何 hook 執行前繫結 socket。機器上的其他工作階段會將訊息傳遞至此路徑。每個工作階段都會匯出自己的 socket，而非從父工作階段繼承，且抵達該 socket 的訊息會經過該工作階段的[傳入控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.224 或更新版本 |340| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，而非由您設定：在繫結 [收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會在繫結 socket 時將該 socket 的路徑匯出給 hook 與 Bash 命令。在啟動時即開啟訊息功能的工作階段中，Claude Code 會在任何 hook 執行之前繫結 socket。機器上的其他工作階段會將訊息傳遞至此路徑。每個工作階段都會匯出自己的 socket，而不是從父項繼承的 socket，且抵達此 socket 的訊息會經過該工作階段的 [傳入控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.224 或更新版本 |

340| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，而非由您設定：在繫結[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會將此每個工作階段專屬的 token 連同 `CLAUDE_CODE_MESSAGING_SOCKET` 一起匯出給 hook 與 Bash 命令。向 socket 發送訊息的指令碼可以將 `{"type":"auth","token":"<token>"}` 作為第一行傳送，以證明其屬於該工作階段。在原生 Windows 上，Claude Code 要求這一行，並會關閉任何未以有效的這一行開頭的連線。[自身子程序規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket)說明 Claude Code 何時會查驗此 token。每個工作階段都會匯出自己的 token，絕不會使用從父工作階段繼承的 token。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.228 或更新版本 |341| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，而非由您設定：在繫結 [收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會將此工作階段專屬的 token 與 `CLAUDE_CODE_MESSAGING_SOCKET` 一起匯出給 hook 與 Bash 命令。張貼至 socket 的指令碼可以傳送 `{"type":"auth","token":"<token>"}` 作為第一行，以證明它屬於該工作階段。在原生 Windows 上，Claude Code 要求必須有此行，並會關閉任何未以有效的此行開頭的連線。[自身子程序規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 說明 Claude Code 何時會參考此 token。每個工作階段都會匯出自己的 token，絕不會從父工作階段繼承。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.228 或更新版本 |

341| `CLAUDE_CODE_NATIVE_CURSOR` | 設為 `1` 可在輸入插入點顯示終端機本身的游標，而非繪製的區塊。游標會遵循終端機的閃爍、形狀與焦點設定。設為 `0` 的效果與不設定此變數相同，因此在終端機本身游標已開啟的工作階段中，這不會恢復繪製的區塊 |342| `CLAUDE_CODE_NATIVE_CURSOR` | 設為 `1` 可在輸入插入點顯示終端機本身的游標，而非繪製的方塊。游標會遵循終端機的閃爍、形狀與焦點設定。設為 `0` 的效果與未設定此變數相同，因此在已開啟終端機本身游標的工作階段中，不會恢復繪製的方塊 |

342| `CLAUDE_CODE_NEW_INIT` | 設為 `1` 可讓 `/init` 執行互動式設定流程。此流程會在探索程式碼庫並寫入檔案之前，詢問要產生哪些檔案，包括 CLAUDE.md、skill 與 hook。若未設定此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |343| `CLAUDE_CODE_NEW_INIT` | 設為 `1` 可讓 `/init` 執行互動式設定流程。此流程會在探索程式碼庫並寫入檔案之前，詢問要產生哪些檔案，包括 CLAUDE.md、skill 與 hook。若未設定此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |

343| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設為 `1` 可透過第二個非阻塞檔案描述元寫入終端機輸出，讓停止讀取的終端機（例如暫停的 tmux control-mode 窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。在 stdout 為終端機時，適用於 macOS、Linux 與 WSL。需要 Claude Code v2.1.261 或更新版本 |344| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設為 `1` 可透過第二個非阻塞檔案描述元寫入終端機輸出，讓停止讀取的終端機（例如暫停的 tmux control-mode 窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。當 stdout 為終端機時，適用於 macOS、Linux 與 WSL。需要 Claude Code v2.1.261 或更新版本 |

344| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新傳送逾時的[非串流請求](/docs/zh-TW/errors#streaming-response-ended-before-any-complete-data-was-received)的次數。設為 `0` 時，請求會在第一次逾時即失敗。預設為未設定，因此由 `CLAUDE_CODE_MAX_RETRIES` 限制這些重新傳送。關於逾時，請參閱[調整重試行為](/docs/zh-TW/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更新版本 |345| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新傳送逾時的[非串流請求](/docs/zh-TW/errors#streaming-response-ended-before-any-complete-data-was-received)的次數。設為 `0` 時，請求會在第一次逾時就失敗。關於逾時時間，請參閱[調整重試行為](/docs/zh-TW/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更新版本 |

345| `CLAUDE_CODE_NO_FLICKER` | 設為 `1` 可啟用[全螢幕呈現](/docs/zh-TW/fullscreen)，這是一項研究預覽功能，可減少閃爍並在長對話中維持記憶體用量平穩。覆寫 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |346| `CLAUDE_CODE_NO_FLICKER` | 設為 `1` 可啟用 [全螢幕呈現](/docs/zh-TW/fullscreen)，這是一項研究預覽功能，可減少閃爍並在長對話中保持記憶體用量穩定。覆寫 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |

346| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用於 Claude.ai 身分驗證的 OAuth refresh token。設定後，`claude auth login` 會直接交換此 token，而不會開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。適用於在自動化環境中佈建身分驗證 |347| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用於 Claude.ai 身分驗證的 OAuth refresh token。設定後，`claude auth login` 會直接交換此 token，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。適用於在自動化環境中佈建身分驗證 |

347| `CLAUDE_CODE_OAUTH_SCOPES` | 簽發 refresh token 時所用的 OAuth 範圍，以空格分隔，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必要 |348| `CLAUDE_CODE_OAUTH_SCOPES` | 發出 refresh token 時所使用的 OAuth 範圍，以空格分隔，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必要項目 |

348| `CLAUDE_CODE_OAUTH_TOKEN` | 用於 claude.ai 身分驗證的 OAuth access token。在 SDK 與自動化環境中可取代 `/login`。優先於儲存在鑰匙圈中的憑證。可使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，否則 Claude Code 會在整個工作階段中使用您設定的 token。若要替換已過期的 token，請產生新的 token 並重新啟動 |349| `CLAUDE_CODE_OAUTH_TOKEN` | 用於 claude.ai 身分驗證的 OAuth 存取 token。在 SDK 與自動化環境中可作為 `/login` 的替代方案。優先於儲存在鑰匙圈中的憑證。可使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，否則 Claude Code 會在整個工作階段中使用您設定的 token。若要取代已過期的 token，請產生新的 token 並重新啟動 |

349| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已於 v2.1.160 移除，現在不具作用。先前用於將[快速模式](/docs/zh-TW/fast-mode)固定為 Claude Opus 4.6，而非目前的預設值。Opus 4.6 已不再支援快速模式 |350| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已於 v2.1.160 移除，現在不會產生任何作用。先前用於將 [快速模式](/docs/zh-TW/fast-mode) 固定為 Claude Opus 4.6，而非目前的預設值。Opus 4.6 已不再支援快速模式 |

350| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承載內容的 OpenTelemetry 屬性（模型回應、工具內容、系統提示詞、原始 API 本文）的最大長度，包含截斷標記，以 UTF-16 程式碼單位計算（預設：61440，即 60 KB）。僅在您的遙測後端接受大於 64 KB 的屬性值時才調高此值，或調低此值以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |351| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承載內容之 OpenTelemetry 屬性（模型回應、工具內容、系統提示詞、原始 API 本文）的最大長度，包含截斷標記，以 UTF-16 程式碼單元計算（預設：61440，即 60 KB）。僅在您的遙測後端接受大於 64 KB 的屬性值時才調高此值，或調低此值以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

351| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設為 `1` 可將 OpenTelemetry exporter 的診斷錯誤寫入 stderr。預設情況下，這些錯誤只會在使用 `--debug` 時出現，因此設定錯誤的 exporter（例如 Prometheus 連接埠衝突）否則會無聲失敗。需要 Claude Code v2.1.179 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |352| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設為 `1` 可將 OpenTelemetry exporter 的診斷錯誤寫入 stderr。預設情況下，這些錯誤只會在使用 `--debug` 時出現，因此設定錯誤的 exporter（例如 Prometheus 連接埠衝突）在其他情況下會無聲地失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

353| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |354| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱 [動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |

354| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry exporter 在關閉時完成作業的逾時（毫秒）（預設：2000）。若結束時遺失指標，請調高此值。請參閱[監控](/docs/zh-TW/monitoring-usage) |355| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry exporter 在關閉時完成作業的逾時（毫秒）（預設：2000）。如果結束時有指標遭到捨棄，請調高此值。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

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

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

358| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛目錄，每個目錄的載入方式與 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標相同。多個路徑在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。每個路徑請以絕對路徑提供或以 `~` 開頭，因為 Claude Code 會略過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱[為單一工作階段載入外掛](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) |359| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛目錄，每個目錄都會以 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標的方式載入。在 Unix 上以 `:` 分隔多個路徑，在 Windows 上則以 `;` 分隔。請將每個路徑指定為絕對路徑或以 `~` 開頭，因為 Claude Code 會略過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱 [為單一工作階段載入外掛](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) |

359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](/docs/zh-TW/plugins/mods/overview) 的檔案變更時重新載入該 mod。重新載入適用於您以 `--plugin-dir` 從目錄載入的 mod，且在互動式工作階段中預設為開啟。設為 `1` 可在非互動式工作階段中也開啟，設為 `0` 則在所有工作階段中關閉。需要 Claude Code v2.1.287 或更新版本。請參閱 [mod 設定與環境變數](/docs/zh-TW/plugins/mods/reference#settings-and-environment-variables) |360| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](/docs/zh-TW/plugins/mods/overview) 的檔案變更時重新載入該 mod。重新載入適用於您以 `--plugin-dir` 從目錄載入的 mod，且在互動式工作階段中預設開啟。設為 `1` 可同時在非互動式工作階段中開啟，設為 `0` 則可在所有工作階段中關閉。需要 Claude Code v2.1.287 或更新版本。請參閱 [mod 設定與環境變數](/docs/zh-TW/plugins/mods/reference#settings-and-environment-variables) |

360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請調高此值。請參閱 [Git clone 逾時](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |361| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請調高此值。請參閱 [Git clone timed out](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |

361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法通過遠端身分驗證時，略過重新複製的嘗試並繼續使用既有的市集 checkout。適用於重新複製也會以相同方式失敗的離線或氣隙隔離環境。請參閱[市集更新在離線環境中失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |362| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法通過遠端身分驗證時，略過重新複製的嘗試，並繼續使用現有的市集簽出。適用於重新複製也會以相同方式失敗的離線或氣隙環境。請參閱 [市集更新在離線環境中失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI runner、容器，或任何未針對 `github.com` 設定 SSH 金鑰的環境 |363| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛的安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI runner、容器，或任何未為 `github.com` 設定 SSH 金鑰的環境 |

363| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一或多個唯讀外掛種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此變數可將預先填入的外掛目錄打包至容器映像中。Claude Code 會在啟動時從這些目錄註冊市集，並使用預先快取的外掛而不重新複製。請參閱[為容器預先填入外掛](/docs/zh-TW/plugins/org#seed-containers-and-ci) |364| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一或多個唯讀外掛種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。可用於將預先填入的外掛目錄打包至容器映像中。Claude Code 會在啟動時從這些目錄註冊市集，並使用預先快取的外掛，而不重新複製。請參閱 [為容器預先填入外掛](/docs/zh-TW/plugins/org#seed-containers-and-ci) |

364| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設為 `1` 可讓 Claude Code 在為工具呼叫、hook 與狀態列命令啟動 PowerShell 時不再傳遞 `-ExecutionPolicy Bypass`，而改為遵循機器實際生效的執行原則。預設情況下，Claude Code 會在程序範圍繞過執行原則，讓 `.ps1` 指令碼與模組匯入能在預設為 Restricted 的 Windows 安裝上運作。無論此設定為何，程序範圍的繞過絕不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy` |365| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設為 `1` 可讓 Claude Code 在為工具呼叫、hook 與狀態列命令啟動 PowerShell 時不傳遞 `-ExecutionPolicy Bypass`，改為遵循機器的有效執行原則。預設情況下，Claude Code 會在程序範圍內略過執行原則，讓 `.ps1` 指令碼與模組匯入能在預設為 Restricted 的 Windows 安裝上運作。無論此設定為何，程序範圍的略過絕不會覆寫群組原則的 `MachinePolicy` 或 `UserPolicy` |

365| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless#background-tasks-at-exit)中，最後一個回合之後閒置等待背景工作（例如 subagent 與工作流程）的上限（毫秒）。每當 Claude 進行一個回合來處理背景結果時，閒置等待都會重新開始計算。預設：`600000`，即 10 分鐘。當閒置等待達到上限時，Claude Code 會停止等待剩餘的背景任務並結束。設為 `0` 可無限期等待。此上限與適用於一般背景 shell 的五秒寬限期是分開的。需要 Claude Code v2.1.182 或更新版本 |366| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 旗標的 [非互動模式](/docs/zh-TW/headless#background-tasks-at-exit) 中，最後一個回合結束後閒置等待背景工作（例如 subagent 與工作流程）的上限（毫秒）。每當 Claude 進行一個回合來處理背景結果時，閒置等待就會重新開始計算。預設：`600000`，即 10 分鐘。當閒置等待達到上限時，Claude Code 會停止等待剩餘的背景任務。由主要對話啟動且仍在執行的背景命令，會讓執行持續超過此上限。設為 `0` 可無限期等待。需要 Claude Code v2.1.182 或更新版本 |

366| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過以 argv 前綴（例如 `/opt/corp/launcher`）指定的企業啟動器，啟動 Claude Code 從自身二進位檔啟動的程序，例如承載 [agent view](/docs/zh-TW/agent-view) 工作階段的背景服務。請在使用者設定或[受管設定](/docs/zh-TW/managed-settings)的 `env` 區塊中設定，而非以 shell 匯出，讓分離的背景服務能夠繼承；專案與本機設定無法設定此變數。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，該設定需要 Claude Code v2.1.210 或更新版本；兩者皆設定時以此變數為優先。VS Code 擴充功能會透過其 `claudeProcessWrapper` 設定另行設定自己的啟動器。在 Windows 上會被忽略。關於值的格式、啟動器涵蓋的範圍以及啟動器必須滿足的約定，請參閱[在企業啟動器後方執行 Claude Code](/docs/zh-TW/corporate-launcher)。需要 Claude Code v2.1.208 或更新版本 |367| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過以 argv 前綴（例如 `/opt/corp/launcher`）指定的企業啟動器，啟動 Claude Code 從其自身二進位檔啟動的程序，例如承載 [agent view](/docs/zh-TW/agent-view) 工作階段的背景服務。請在使用者設定或 [受管設定](/docs/zh-TW/managed-settings) 的 `env` 區塊中設定，而非以 shell 匯出的方式設定，讓分離的背景服務能夠繼承它；專案與本機設定無法設定此變數。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，該設定需要 Claude Code v2.1.210 或更新版本；兩者都設定時，此變數優先。VS Code 擴充功能會透過其 `claudeProcessWrapper` 設定另外設定自己的啟動器。在 Windows 上會被忽略。關於值的格式、啟動器涵蓋的範圍，以及啟動器必須符合的約定，請參閱 [在企業啟動器後方執行 Claude Code](/docs/zh-TW/corporate-launcher)。需要 Claude Code v2.1.208 或更新版本 |

367| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定，可選擇 Claude Code 儲存該工作階段逐字稿與自動記憶的 `projects/` 目錄名稱，取代從工作目錄路徑衍生的名稱。例如，以 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code，會將它們儲存在 `/srv/tenant-a/projects/work/` 下。當 `CLAUDE_CONFIG_DIR` 未設定時，Claude Code 會忽略此變數，且只會從您啟動 `claude` 的環境讀取，絕不會從[設定檔的 `env` 區塊](#in-settings-files)讀取。請參閱[自行命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |368| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定，以選擇 Claude Code 儲存該工作階段逐字稿與自動記憶的 `projects/` 目錄名稱，取代從工作目錄路徑衍生的名稱。例如，以 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code，會將這些內容儲存在 `/srv/tenant-a/projects/work/` 下。未設定 `CLAUDE_CONFIG_DIR` 時，Claude Code 會忽略此變數，且只會從您啟動 `claude` 的環境中讀取此變數，絕不會從 [設定檔的 `env` 區塊](#in-settings-files) 讀取。請參閱 [自行命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |

368| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設為 `5m` 或 `1h`（Claude Code 僅接受這兩個值），可選擇主對話的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：包括您的互動式、`-p` 與 SDK 回合，以及與其內嵌執行的輔助程式。優先於 `promptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫此變數。API 會以較高費率計費 1 小時的快取寫入。需要 Claude Code v2.1.242 或更新版本 |369| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設為 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主要對話的 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：包括您的互動式、`-p` 與 SDK 回合，以及與其一同執行的輔助程式。優先於 `promptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫此變數。API 會以較高的費率計算 1 小時快取寫入的費用。需要 Claude Code v2.1.242 或更新版本 |

369| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 當 `ANTHROPIC_BASE_URL` 指向自訂代理伺服器時，設為 `1` 可傳播 W3C trace context。傳播涵蓋模型與 HTTP MCP 請求上的 `traceparent` 標頭，以及 Bash、PowerShell 與 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，僅在直接連線至 Anthropic API 時啟用傳播。於 v2.1.152 新增。請參閱[追蹤（beta）](/docs/zh-TW/monitoring-usage#traces-beta) |370| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設為 `1` 可在 `ANTHROPIC_BASE_URL` 指向自訂代理伺服器時傳播 W3C 追蹤上下文。傳播涵蓋模型與 HTTP MCP 請求上的 `traceparent` 標頭，以及 Bash、PowerShell 與 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，只有在直接連線至 Anthropic API 時才會啟用傳播。於 v2.1.152 新增。請參閱 [追蹤（beta）](/docs/zh-TW/monitoring-usage#traces-beta) |

370| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由內嵌 Claude Code 並代其管理模型供應商路由的主機平台所設定。設定後，Claude Code 會忽略設定檔中的供應商選擇、端點與身分驗證變數，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`，因此使用者設定無法覆寫主機的路由。Claude Code 也會忽略[受管設定](/docs/zh-TW/managed-settings)中的模型選擇鍵，例如 `model`、`fallbackModel` 與 `modelOverrides`，無論由哪個受管來源傳遞，讓主機的模型設定優先於過時的受管模型固定設定。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 與 `ANTHROPIC_DEFAULT_*_MODEL` 系列；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍然適用，除非主機提供自己的清單。Claude Code 也會略過它在第三方供應商（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 與 Microsoft Foundry）上原本會套用的自動遙測退出，因此遙測會遵循標準的 `DISABLE_TELEMETRY` 退出機制。請參閱[各 API 供應商的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |371| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由內嵌 Claude Code 並代為管理模型提供者路由的主機平台設定。設定後，Claude Code 會忽略設定檔中的提供者選擇、端點與身分驗證變數，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`，因此使用者設定無法覆寫主機的路由。Claude Code 也會忽略 [受管設定](/docs/zh-TW/managed-settings) 中的模型選擇鍵，例如 `model`、`fallbackModel` 與 `modelOverrides`，無論由哪個受管來源提供，因此主機的模型設定會優先於過時的受管模型固定設定。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 與 `ANTHROPIC_DEFAULT_*_MODEL` 系列；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍然適用，除非主機提供自己的允許清單。Claude Code 也會略過它原本會在第三方提供者（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 與 Microsoft Foundry）上套用的自動遙測退出，因此遙測會遵循標準的 `DISABLE_TELEMETRY` 退出方式。請參閱 [各 API 提供者的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |

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

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

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

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

376| `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](/docs/zh-TW/agent-view) 工作階段時，會自行設定一小時的界限。需要 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](/docs/zh-TW/agent-view) 工作階段時，會自行設定一小時的界限。需要 Claude Code v2.1.211 或更新版本 |

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

378| `CLAUDE_CODE_RETRY_WATCHDOG` | 針對無人值守的工作階段（例如評估測試框架、CI 作業或遠端 worker）設為 `1`。會無限期重試 `429` 與 `529` 容量錯誤，而不會在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。當標準速度的請求收到回報支出上限或用量點數耗盡的 `429` 時，Claude Code 會立即失敗，即使是來自依排程重設的[閘道支出上限](/docs/zh-TW/errors#spend-limit-reached)也一樣。在 v2.1.239 之前，watchdog 會無限期重試這些錯誤。關於快速模式請求，請參閱[處理速率限制](/docs/zh-TW/fast-mode#handle-rate-limits)。watchdog 會在嘗試之間最多退避 5 分鐘，或在回應帶有速率限制重設時間時等到限制重設為止，因此達到用量上限的工作階段會等待剩餘的時間窗結束。在 v2.1.199 或更新版本中，它也會將其他暫時性錯誤（例如伺服器錯誤、逾時與中斷的連線）的預設重試次數提高到 300，約為三小時的退避時間，並在您明確設定 `CLAUDE_CODE_MAX_RETRIES` 時移除其 15 次的上限。需要 Claude Code v2.1.186 或更新版本 |379| `CLAUDE_CODE_RETRY_WATCHDOG` | 針對無人看管的工作階段（例如評估 harness、CI 作業或遠端 worker）設為 `1`。會無限期重試 `429` 與 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。當標準速度的請求收到回報支出上限或用量點數已用盡的 `429` 時，Claude Code 會立即失敗，即使該錯誤來自依排程重設的 [閘道支出上限](/docs/zh-TW/errors#spend-limit-reached) 也一樣。在 v2.1.239 之前，watchdog 會無限期重試這些錯誤。關於快速模式請求，請參閱 [處理速率限制](/docs/zh-TW/fast-mode#handle-rate-limits)。watchdog 在每次嘗試之間最多退避 5 分鐘，或在回應帶有速率限制重設時間時退避至限制重設為止，因此達到用量上限的工作階段會等到剩餘的時間窗口結束。在 v2.1.199 或更新版本上，它也會將其他暫時性錯誤（例如伺服器錯誤、逾時與中斷的連線）的預設重試次數提高至 300，約三小時的退避時間，並在您明確設定 `CLAUDE_CODE_MAX_RETRIES` 時移除其 15 次的上限。需要 Claude Code v2.1.186 或更新版本 |

379| `CLAUDE_CODE_SAFE_MODE` | 設為 `1` 可在安全模式下啟動：CLAUDE.md、skill、外掛、hook、MCP 伺服器、自訂命令與 agent、輸出風格、工作流程、自訂主題、自訂快捷鍵、狀態列與檔案建議命令、LSP 伺服器以及自動記憶都不會載入，以便對損壞的設定進行疑難排解。受管設定原則仍然適用，包括原則所設定的 hook、狀態列與檔案建議命令；受管外掛、受管 skill、受管 CLAUDE.md 以及原則所設定的 MCP 伺服器則不適用。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接產生的子程序會繼承此變數 |380| `CLAUDE_CODE_SAFE_MODE` | 設為 `1` 可以安全模式啟動：CLAUDE.md、skill、外掛、hook、MCP 伺服器、自訂命令與 agent、輸出風格、工作流程、自訂主題、自訂快捷鍵、狀態列與檔案建議命令、LSP 伺服器以及自動記憶都不會載入，以便對損壞的設定進行疑難排解。受管設定政策仍然適用，包括政策設定的 hook、狀態列與檔案建議命令；受管外掛、受管 skill、受管 CLAUDE.md 與政策設定的 MCP 伺服器則不會載入。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接啟動的子程序會繼承此變數 |

380| `CLAUDE_CODE_SCRIPT_CAPS` | 在設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，限制特定指令碼每個工作階段可被呼叫次數的 JSON 物件。鍵是與命令文字比對的子字串；值是整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這樣的 shell 展開技巧仍會計入上限。透過 `xargs` 或 `find -exec` 的執行期擴散無法偵測；這是一種縱深防禦控制 |381| `CLAUDE_CODE_SCRIPT_CAPS` | 在設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，限制特定指令碼在每個工作階段中可被呼叫次數的 JSON 物件。鍵是與命令文字比對的子字串；值是整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這類 shell 展開技巧仍會計入上限。不會偵測透過 `xargs` 或 `find -exec` 的執行階段擴散；這是一項縱深防禦控制 |

381| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最大 20 的任何正值，包括小於 1 的小數值（例如 `0.5`），以在已放大滾輪事件的終端機中減緩加速的觸控板與滾輪捲動。若您的終端機每個刻度傳送一個滾輪事件且未放大，請設為 `3` 以符合 `vim`。在 JetBrains IDE 終端機中會被忽略，因為 Claude Code 在該處使用自己的捲動處理 |382| `CLAUDE_CODE_SCROLL_SPEED` | 設定 [全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling) 中的滑鼠滾輪捲動倍數。接受最高 20 的任何正值，包括低於 1 的小數值（例如 `0.5`），以便在已放大滾輪事件的終端機中減慢加速的觸控板與滾輪捲動。如果您的終端機每格只傳送一個滾輪事件且未放大，請設為 `3` 以與 `vim` 一致。在 JetBrains IDE 終端機中會被忽略，因為 Claude Code 在該處使用自己的捲動處理 |

382| `CLAUDE_CODE_SEND_FEEDBACK` | 設為 `0` 可為工作階段關閉 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。設為 `1` 可在您的帳戶已具有存取權時開啟；此變數本身無法授予存取權，且其他關閉意見回饋的開關（例如 `DISABLE_FEEDBACK_COMMAND` 以及 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值）仍然適用 |383| `CLAUDE_CODE_SEND_FEEDBACK` | 設為 `0` 可為工作階段關閉 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。設為 `1` 可在您的帳戶已有存取權時開啟；此變數本身無法授予存取權，且其他會關閉意見回饋的開關（例如 `DISABLE_FEEDBACK_COMMAND` 與 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值）仍然適用 |

383| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆寫 [SessionEnd](/docs/zh-TW/hooks#sessionend) hook 的時間預算（毫秒）。此值也是每個未自行設定 `timeout` 的 hook 的逾時。適用於工作階段結束、`/clear`，以及透過互動式 `/resume` 切換工作階段。預設預算為 1.5 秒，並會自動提高至設定檔中所設定的最高個別 hook `timeout`，最多 60 秒。外掛提供的 hook 上的逾時不會提高預算 |384| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆寫 [SessionEnd](/docs/zh-TW/hooks#sessionend) hook 的時間預算（毫秒）。此值也是每個未自行設定 `timeout` 之 hook 的逾時。適用於工作階段結束、`/clear`，以及透過互動式 `/resume` 切換工作階段。預設預算為 1.5 秒，會自動提高至設定檔中所設定的最高個別 hook `timeout`，最多 60 秒。外掛提供之 hook 上的逾時不會提高預算 |

384| `CLAUDE_CODE_SESSION_ID` | 在 Bash 與 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks)子程序以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序中，自動設為目前的工作階段 ID。對於 Bash、PowerShell 與 hook，此值與 hook JSON 輸入中的 `session_id` 欄位相符，並會在 `/clear` 時更新。MCP 伺服器子程序會保留其產生時的 ID。在 `--resume <session-id>` 時，它會收到繼續的 ID，與 hook 和 Bash 相符。在未指定明確 ID 的 `--continue` 或 `--resume` 時，它可能會改為收到初始啟動的 ID。可用於將指令碼與外部工具關聯至啟動它們的 Claude Code 工作階段 |385| `CLAUDE_CODE_SESSION_ID` | 在 Bash 與 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks) 子程序以及 stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序中，會自動設為目前的工作階段 ID。對於 Bash、PowerShell 與 hook，此值與 hook JSON 輸入中的 `session_id` 欄位相符，並會在 `/clear` 時更新。MCP 伺服器子程序會保留其啟動時的 ID。在 `--resume <session-id>` 時，它會收到恢復後的 ID，與 hook 和 Bash 一致。在 `--continue` 或未指定明確 ID 的 `--resume` 時，它可能會改為收到初始啟動時的 ID。可用於將指令碼與外部工具關聯至啟動它們的 Claude Code 工作階段 |

385| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用於執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援其他 shell，例如 `fish`。若此值不是可運作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並改用自動偵測。自動偵測會在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則會在您的 `PATH` 與標準安裝位置中，依序挑選第一個可運作的 `zsh`，再來是 `bash` |386| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援其他 shell，例如 `fish`。如果值不是可運作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並改用自動偵測。自動偵測會在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則會挑選在您的 `PATH` 與標準安裝位置中找到的第一個可運作的 `zsh`，其次是 `bash` |

386| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 所產生之 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)啟動命令。PowerShell hook 與 exec 形式的 hook 不會加上前綴執行。適用於記錄或稽核。設定像 `/path/to/logger.sh` 這樣的單純執行檔路徑，會將每個命令以 `/path/to/logger.sh '<command>'` 的形式執行。包裝程式會在 `$1` 中以單一經 shell 引號處理的引數接收命令列，因此包裝程式必須以 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為單純執行檔路徑，會導致傳遞引數（例如 `npx -y <package>`）的 stdio MCP 伺服器無法運作。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組合的完整 shell 呼叫，包括環境設定，而不僅是 Claude 執行的命令 |387| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 所啟動之 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline) 命令，以及 stdio [MCP 伺服器](/docs/zh-TW/mcp) 啟動命令。PowerShell hook 與 exec 形式的 hook 執行時不會使用前綴。適用於日誌記錄或稽核。設定如 `/path/to/logger.sh` 的單純執行檔路徑，會以 `/path/to/logger.sh '<command>'` 執行每個命令。包裝程式會在 `$1` 中以單一 shell 引號引數接收命令列，因此包裝程式必須以 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為單純的執行檔路徑，會導致傳遞 `npx -y <package>` 等引數的 stdio MCP 伺服器無法運作。對於 Bash 工具呼叫，`$1` 包含 Claude Code 所組合的完整 shell 呼叫，包括環境設定，而不僅是 Claude 執行的命令 |

387| `CLAUDE_CODE_SIMPLE` | 設為 `1` 可以最精簡的系統提示詞執行，且只使用 Bash、檔案讀取與檔案編輯工具。來自 `--mcp-config` 的 MCP 工具仍可使用。停用 hook、skill、自訂命令、subagent、已安裝外掛、MCP 伺服器、自動記憶以及 CLAUDE.md 的自動探索。您以 `--add-dir` 傳入之目錄中的 skill 仍會載入。不會讀取 OAuth token 與鑰匙圈憑證，因此 Anthropic 身分驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |388| `CLAUDE_CODE_SIMPLE` | 設為 `1` 可使用最精簡的系統提示詞執行，且只提供 Bash、檔案讀取與檔案編輯工具。來自 `--mcp-config` 的 MCP 工具仍可使用。會停用 hook、skill、自訂命令、subagent、已安裝外掛、MCP 伺服器、自動記憶與 CLAUDE.md 的自動探索。您以 `--add-dir` 傳遞之目錄中的 skill 仍會載入。不會讀取 OAuth token 與鑰匙圈憑證，因此 Anthropic 身分驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |

388| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設為 `1` 可在任何模型上使用較短的系統提示詞與精簡的工具描述。設為 `0`、`false`、`no` 或 `off` 可選擇退出，即使在實驗或伺服器設定原本會啟用它的模型上也一樣。完整的工具集、hook、MCP 伺服器以及 CLAUDE.md 探索仍保持啟用 |389| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 在 Claude Code 的完整系統提示詞與使用縮略工具描述的較短系統提示詞之間選擇。未設定時，Haiku 4.5、Sonnet 5、Opus 4.7 以及這些系列中較早的模型預設使用完整提示詞，較新的模型則使用較短的提示詞。設為 `1` 可在任何模型上使用較短的提示詞。設為 `0`、`false`、`no` 或 `off` 可在任何模型上使用完整提示詞，即使實驗或伺服器設定原本會選擇較短的提示詞也一樣。兩種提示詞都會保留完整的工具集、hook、MCP 伺服器與 CLAUDE.md 探索 |

389| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 略過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端身分驗證，適用於自行簽署請求的閘道 |390| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 略過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端身分驗證，適用於自行簽署請求的閘道 |

390| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設為 `1` 可關閉從 AWS 預設憑證提供者鏈所解析之憑證的程序內快取，讓 Claude Code 在每個 API 請求時都解析該鏈。關閉快取後，以 SSO 為基礎的設定檔會在每個請求時向 IAM Identity Center 請求憑證。請參閱[憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |391| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設為 `1` 可關閉從 AWS 預設憑證提供者鏈解析出之憑證的程序內快取，讓 Claude Code 在每個 API 請求時都重新解析該鏈。關閉快取時，以 SSO 為基礎的設定檔會在每個請求時向 IAM Identity Center 請求憑證。請參閱 [憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

392| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設為 `1` 可將失敗的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查視為可用，適用於封鎖該檢查直接連往 `api.anthropic.com` 之請求的網路。Claude Code 仍會遵循「disabled by your organization」回應 |393| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設為 `1` 可將失敗的 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性檢查視為可用，適用於會封鎖該檢查直接傳送至 `api.anthropic.com` 之請求的網路。Claude Code 仍會遵循「disabled by your organization」回應 |

393| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設為 `1` 可略過用戶端的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查，適用於攔截而非拒絕該檢查請求的代理伺服器。當您的組織已停用快速模式時，API 仍會拒絕快速模式請求 |394| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設為 `1` 可略過用戶端的 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性檢查，適用於會攔截而非拒絕該檢查請求的代理伺服器。當您的組織已停用快速模式時，API 仍會拒絕快速模式請求 |

394| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 略過 Microsoft Foundry 的 Azure 身分驗證，適用於注入自己 `Authorization` 標頭的代理伺服器或閘道。Claude Code 會在不帶 Azure 憑證的情況下傳送請求，並保留您提供的 `Authorization` 標頭（例如透過 `ANTHROPIC_CUSTOM_HEADERS`）。當設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時會被忽略。在 v2.1.203 之前，除非同時設定 API 金鑰，否則此變數會導致 Microsoft Foundry 用戶端無法傳送請求 |395| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 略過 Microsoft Foundry 的 Azure 身分驗證，適用於會注入自己 `Authorization` 標頭的代理伺服器或閘道。Claude Code 會在不附 Azure 憑證的情況下傳送請求，並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS` 提供的標頭。設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時會被忽略。在 v2.1.203 之前，除非同時設定 API 金鑰，否則此變數會導致 Microsoft Foundry 用戶端無法傳送請求 |

396| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 上的[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)，會在此機器上記住它們發現您的帳戶無法呼叫的模型，最長一天。設為 `1` 可關閉此記憶。需要 Claude Code v2.1.285 或更新版本 |397| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 上的 [啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)，會在此機器上記住它們發現您的帳戶無法呼叫的模型，最多保留一天。設為 `1` 可關閉此記憶。需要 Claude Code v2.1.285 或更新版本 |

397| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設為 `1` 可略過將提示詞歷史記錄與工作階段逐字稿寫入磁碟。設定此變數後啟動的工作階段不會出現在 `--resume`、`--continue` 或向上鍵歷史記錄中。適用於短暫的指令碼化工作階段 |398| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設為 `1` 可略過將提示詞歷史記錄與工作階段逐字稿寫入磁碟。在設定此變數時啟動的工作階段不會出現在 `--resume`、`--continue` 或向上鍵歷史記錄中。適用於臨時的指令碼工作階段 |

399| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 設為 `1` 可讓以 `--output-format stream-json` 啟動的工作階段，針對原本只以 stderr 結束的啟動失敗，寫入一則[說明 Claude Code 拒絕啟動原因的結果訊息](/docs/zh-TW/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更新版本 |400| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 設為 `1` 可讓以 `--output-format stream-json` 啟動的工作階段，針對原本只會以 stderr 輸出結束的啟動失敗，寫入一則 [說明 Claude Code 拒絕啟動原因的結果訊息](/docs/zh-TW/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更新版本 |

400| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可連續阻止回合結束的最大次數，超過後 Claude Code 會覆寫它並仍然結束回合（預設：8）。設為 `0` 可停用上限。若您的 hook 確實需要更多次迭代才能解決，請調高此值 |401| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可連續阻止回合結束的最大次數，超過後 Claude Code 會覆寫它並仍然結束回合（預設：8）。設為 `0` 可停用上限。如果您的 hook 確實需要更多次迭代才能解決，請調高此值 |

401| `CLAUDE_CODE_SUBAGENT_MODEL` | 未透過其他方式指定模型的 [subagent](/docs/zh-TW/sub-agents#choose-a-model)、[agent team](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊員以及[工作流程](/docs/zh-TW/workflows) agent 的預設模型。接受別名（例如 `haiku`）或完整模型名稱。有兩個來源優先於此變數：Claude 產生 agent 時傳遞的模型，以及 agent 定義中的 `model` 欄位（包括 `inherit`）。若要改變這一點，請設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。完整順序請參閱[選擇模型](/docs/zh-TW/sub-agents#choose-a-model)。設為 `inherit` 與不設定相同。在 v2.1.251 之前，此變數會覆寫每次呼叫的模型與定義的 `model` 欄位 |402| `CLAUDE_CODE_SUBAGENT_MODEL` | [subagent](/docs/zh-TW/sub-agents#choose-a-model)、[agent team](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊員以及 [工作流程](/docs/zh-TW/workflows) agent 在未以其他方式指定模型時所使用的預設模型。接受 `haiku` 等別名或完整模型名稱。有兩個來源優先於此變數：Claude 產生 agent 時傳遞的模型，以及 agent 定義中的 `model` 欄位（包括 `inherit`）。若要改變這一點，請設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。完整的優先順序請參閱 [選擇模型](/docs/zh-TW/sub-agents#choose-a-model)。將其設為 `inherit` 與未設定相同。在 v2.1.251 之前，此變數會覆寫每次呼叫的模型與定義中的 `model` 欄位 |

402| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設為 `1` 可強制 subagent、隊員與工作流程 agent 使用同一個模型。[讓每個 subagent 都在同一個模型上執行](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)說明了是哪一個模型。需要 Claude Code v2.1.257 或更新版本 |403| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設為 `1` 可對 subagent、隊員與工作流程 agent 強制使用單一模型。[讓每個 subagent 使用同一個模型](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model) 說明該模型為何。需要 Claude Code v2.1.257 或更新版本 |

403| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設為 `5m` 或 `1h`（Claude Code 僅接受這兩個值），可選擇主對話以外之請求的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，例如 [subagent](/docs/zh-TW/sub-agents)、工作流程與背景工作。優先於 `subagentPromptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫此變數。API 會以較高費率計費 1 小時的快取寫入。需要 Claude Code v2.1.242 或更新版本 |404| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設為 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主要對話以外之請求的 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，例如 [subagent](/docs/zh-TW/sub-agents)、工作流程與背景工作。優先於 `subagentPromptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫此變數。API 會以較高的費率計算 1 小時快取寫入的費用。需要 Claude Code v2.1.242 或更新版本 |

404| `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` 會自動設定此變數 |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` 會自動設定此變數 |

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

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

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

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

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

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

411| `CLAUDE_CODE_TASK_LIST_ID` | 在多個工作階段之間共用任務清單。在多個 Claude Code 執行個體中設定相同的 ID，即可在[具備 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中協調共用的任務清單。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |412| `CLAUDE_CODE_TASK_LIST_ID` | 在多個工作階段之間共用任務清單。在多個 Claude Code 執行個體中設定相同的 ID，即可在 [具備 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability) 中協調共用的任務清單。請參閱 [任務清單](/docs/zh-TW/interactive-mode#task-list) |

412| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒覆寫非互動式工作階段在結束時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆除的時間。接受 1000 至 60000；超出範圍的值會被忽略並套用預設值 10000。需要 Claude Code v2.1.206 或更新版本 |413| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒為單位，覆寫非互動式工作階段在結束時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆除的時間。接受 1000 至 60000；超出範圍的值會被忽略，並套用預設值 10000。需要 Claude Code v2.1.206 或更新版本 |

413| `CLAUDE_CODE_TMPDIR` | 覆寫用於內部暫存檔案的暫存目錄。Claude Code 會在 Unix 上於此路徑後附加 `/claude-{uid}/`，在 Windows 上附加 `/claude/`。預設：macOS 上為 `/tmp`，Linux 與 Windows 上為 `os.tmpdir()`。在 macOS 與 Linux 上，當您的覆寫值是較長的路徑時，[沙箱化](/docs/zh-TW/sandboxing)的 Bash 子程序會收到位於系統預設值下的較短備援 `$TMPDIR`，因為某些工具在暫存路徑過長時會失敗。未沙箱化的 Bash 命令會在您的 shell 已設定 `$TMPDIR` 時繼承它。在原生 Windows 上，當您的 shell 未設定 `$TMPDIR` 時，參照 `$TMPDIR` 的 Bash 命令會收到您的覆寫值，若您未設定則收到 `%TEMP%`。Claude Code 自身的暫存檔案一律使用您的覆寫值。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |414| `CLAUDE_CODE_TMPDIR` | 覆寫用於內部暫存檔案的暫存目錄。在 Unix 上，Claude Code 會在此路徑後附加 `/claude-{uid}/`，在 Windows 上則附加 `/claude/`。預設：macOS 上為 `/tmp`，Linux 與 Windows 上為 `os.tmpdir()`。在 macOS 與 Linux 上，當您的覆寫值是很長的路徑時，[沙箱化](/docs/zh-TW/sandboxing) 的 Bash 子程序會收到位於系統預設目錄下的簡短備援 `$TMPDIR`，因為某些工具會在暫存路徑過長時失敗。未沙箱化的 Bash 命令會在您的 shell 設定了 `$TMPDIR` 時繼承它。在原生 Windows 上，當您的 shell 未設定 `$TMPDIR` 時，參照 `$TMPDIR` 的 Bash 命令會收到您的覆寫值，若您未設定覆寫值則收到 `%TEMP%`。Claude Code 自己的暫存檔案一律使用您的覆寫值。請在您的 shell、使用者設定或受管設定中設定。在 [專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中會被忽略 |

414| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設為任何非空值（例如 `1`）可允許在 tmux 內輸出 24 位元真彩色。**設為 `0` 或 `false` 仍會允許真彩色**，這與大多數開關型變數不同；請取消設定此變數以恢復 256 色限制。預設情況下，當設定了 `$TMUX` 時，Claude Code 會限制為 256 色，因為除非經過設定，否則 tmux 不會傳遞真彩色跳脫序列。請在將 `set -ga terminal-overrides ',*:Tc'` 加入您的 `~/.tmux.conf` 後設定此變數。其他 tmux 設定請參閱[終端機設定](/docs/zh-TW/terminal-config) |415| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設為任何非空值（例如 `1`），可允許在 tmux 中輸出 24 位元 truecolor。**設為 `0` 或 `false` 仍會允許 truecolor**，這與大多數開關變數不同；請取消設定此變數以恢復 256 色限制。預設情況下，當設定了 `$TMUX` 時，Claude Code 會限制為 256 色，因為除非經過設定，否則 tmux 不會傳遞 truecolor 跳脫序列。請在將 `set -ga terminal-overrides ',*:Tc'` 加入您的 `~/.tmux.conf` 之後設定此變數。其他 tmux 設定請參閱 [終端機設定](/docs/zh-TW/terminal-config) |

415| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 與 WSL 上，設為以逗號分隔的程序種類清單，指定 Claude Code [從工具記憶體上限中排除](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)的程序種類，例如 `mcp` 或 `lsp`。設為 `none` 可限制每一種程序，設為 `all-new` 則只限制 Bash、PowerShell 與 Monitor 工具命令。無論您列出什麼，Claude Code 都會將 Bash、PowerShell 與 Monitor 工具命令保留在上限之內。需要 Claude Code v2.1.246 或更新版本 |416| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 與 WSL 上，設為以逗號分隔的程序種類清單，Claude Code 會將這些種類 [排除在工具記憶體上限之外](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，例如 `mcp` 或 `lsp`。設為 `none` 可限制所有種類，或設為 `all-new` 以只限制 Bash、PowerShell 與 Monitor 工具命令。無論您列出什麼，Claude Code 都會讓 Bash、PowerShell 與 Monitor 工具命令受此上限約束。需要 Claude Code v2.1.246 或更新版本 |

416| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 與 WSL 上，設為像 `4G` 這樣的大小，可[限制 Bash 與 PowerShell 工具命令可使用的記憶體](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更新版本中也包括 Monitor 工具命令。請以純數字撰寫大小，單獨表示位元組數，或加上 `K`、`M`、`G` 或 `T` 後綴。設為 `0` 或 `off` 可關閉上限。一旦 Claude Code 啟動的第一個程序已開啟或關閉上限，變更後的值會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |417| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 與 WSL 上，設為如 `4G` 的大小，以 [限制 Bash 與 PowerShell 工具命令可使用的記憶體](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更新版本上也包括 Monitor 工具命令。請以純數字撰寫大小，單獨使用時表示位元組數，或加上 `K`、`M`、`G` 或 `T` 後綴。設為 `0` 或 `off` 可關閉上限。一旦 Claude Code 啟動的第一個程序已開啟或關閉上限，變更後的值會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |

417| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 設為 `1` 可限制長時間 `-p` 或 Agent SDK 工作階段的[逐字稿檔案](/docs/zh-TW/sessions#where-transcripts-are-stored)成長大小。每次壓縮後，一旦檔案大於 5 MB，Claude Code 就會移除該次壓縮之前的歷史記錄。無論檔案是否經過修剪，繼續工作階段都會還原相同的對話。請在您啟動 Claude Code 的環境中設定，因為設定的 `env` 區塊無法開啟此變數。需要 Claude Code v2.1.287 或更新版本 |418| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 設為 `1` 可限制長時間執行之 `-p` 或 Agent SDK 工作階段的 [逐字稿檔案](/docs/zh-TW/sessions#where-transcripts-are-stored) 增長的大小。每次壓縮後，一旦檔案大於 5 MB，Claude Code 就會移除該次壓縮之前的歷史記錄。無論檔案是否經過修剪，恢復工作階段都會還原相同的對話。請在您啟動 Claude Code 的環境中設定，因為設定的 `env` 區塊無法開啟此功能。需要 Claude Code v2.1.287 或更新版本 |

418| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消轉送至遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）的對話方塊，或[暫留之跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)的核准對話方塊之前的期限（毫秒）；權限提示與 `AskUserQuestion` 問題使用各自的流程，不受此變數管轄。在 Claude Code v2.1.236 或更新版本中，它也會限制可能在無人值守情況下執行之工作階段中，於工作階段中途出現的 [Fable 用量點數同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制傳入訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)與[非互動式工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions)涵蓋完整的暫留訊息到期規則，包括期限不適用的情況。覆寫 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值會停用期限 |419| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消其轉送至遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）之對話方塊，或 [保留的跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 之核准對話方塊前的期限（毫秒）；權限提示與 `AskUserQuestion` 問題使用各自的流程，不受此變數控制。在 Claude Code v2.1.236 或更新版本上，它也會限制可能在無人看管情況下執行的工作階段中，於工作階段中途出現的 [Fable 用量點數同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制傳入訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 與 [非互動式工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions) 涵蓋完整的保留訊息到期規則，包括期限不適用的情況。覆寫 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值會停用期限 |

423| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設為 `1` 可使用 Node.js 檔案 API 而非 ripgrep 來探索自訂命令、subagent 與輸出風格。若隨附的 ripgrep 二進位檔在您的環境中無法使用或遭到封鎖，請設定此變數。不影響 Grep 或檔案搜尋工具 |424| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設為 `1` 可使用 Node.js 檔案 API 而非 ripgrep 來探索自訂命令、subagent 與輸出風格。如果隨附的 ripgrep 二進位檔在您的環境中無法使用或遭到封鎖，請設定此變數。不影響 Grep 或檔案搜尋工具 |

424| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安裝 Git Bash 的 Windows 上，此工具會自動啟用；設為 `0` 可將其停用。在已安裝 Git Bash 的 Windows 上，claude.ai 與 Console 帳戶預設會開啟此工具；設為 `1` 可在 Amazon Bedrock、Google Cloud's Agent Platform 與 Microsoft Foundry 工作階段中啟用，或設為 `0` 將其關閉。在 Linux、macOS 與 WSL 上，設為 `1` 即可啟用，但需要 `PATH` 中有 `pwsh`。在 Windows 上啟用後，Claude 可以原生執行 PowerShell 命令，而不需透過 Git Bash 轉送。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |425| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安裝 Git Bash 的 Windows 上，此工具會自動啟用；設定為 `0` 可停用。在已安裝 Git Bash 的 Windows 上，claude.ai 與 Console 帳戶預設會開啟此工具；在 Amazon Bedrock、Google Cloud's Agent Platform 與 Microsoft Foundry 工作階段中設定為 `1` 可啟用，或設定為 `0` 可關閉。在 Linux、macOS 與 WSL 上，設定為 `1` 可啟用，這需要 `PATH` 中有 `pwsh`。在 Windows 上啟用後，Claude 可以原生執行 PowerShell 命令，而不必透過 Git Bash 轉送。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |

426| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設定 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 將每個已擷取 URL 的回應保留在快取中的毫秒數。預設值為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他寫法都會維持預設值。Claude Code 每次啟動只讀取此值一次，因此在設定的 `env` 區塊中所做的變更，會在下次啟動 `claude` 時套用。需要 Claude Code v2.1.233 或更新版本 |427| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設定 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 將每個擷取之 URL 的回應保留在快取中的毫秒數。預設值為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他寫法都會維持預設值。Claude Code 每次啟動時只讀取一次此值，因此在設定的 `env` 區塊中所做的變更，會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |

427| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載完成的時間上限（毫秒），包含其所跟隨的任何重新導向。屆時仍未完成的下載會以截止期限錯誤失敗。預設值為 `300000`，即五分鐘。設為 `0` 可移除此限制。僅接受純數字；小數或任何其他寫法都會維持預設值。需要 Claude Code v2.1.268 或更新版本 |428| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載完成的時間上限（毫秒），包括其跟隨的任何重新導向。屆時仍未完成的下載會以期限錯誤失敗。預設值為 `300000`，即五分鐘。設定為 `0` 可移除此限制。僅接受純數字；小數或任何其他寫法都會維持預設值。需要 Claude Code v2.1.268 或更新版本 |

428| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 當 `CLAUDE_AUTO_BACKGROUND_TASKS` 設為 `1` 時，Claude Code 每次提醒 Claude 檢查仍在執行中的[背景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之前要等待多久。接受一個或多個以逗號分隔、介於 `1` 到 `86400` 之間的整數秒數等待時間，例如 `600` 或 `600,1800,3600`。每個值代表下一次提醒前的等待時間，最後一個值會重複使用。僅接受純數字；任何其他值或寫法都會視為未設定。未設定時不會有任何提醒。需要 Claude Code v2.1.283 或更新版本 |429| `CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR` | 工作階段的 [WebSearch 上限](/docs/zh-TW/tools-reference#session-search-limit) 的補充速率，以每小時呼叫次數計。在互動式終端機工作階段中，預設值為 `100`。在[非互動](/docs/zh-TW/headless)工作階段中，預設值為 `0`，即關閉補充。僅接受純數字；任何其他寫法都視為未設定。需要 Claude Code v2.1.290 或更新版本 |

429| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 單次[工作流程](/docs/zh-TW/workflows)執行同時執行的 agent 數量，範圍從 `1` 到 `256`。預設情況下，一次執行最多同時執行 16 個 agent，當 Claude Code 可用的 CPU 較少時則更少；排隊中的 `agent()` 呼叫會等待空出的位置。每個執行中 agent 的逐字稿都會保留在 Claude Code 的記憶體中，因此較高的值會增加記憶體用量。僅接受純數字；超出範圍的值與其他寫法都會維持預設值。需要 Claude Code v2.1.269 或更新版本 |430| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 當 `CLAUDE_AUTO_BACKGROUND_TASKS` 設定為 `1` 時，Claude Code 在每次提醒 Claude 檢查仍在執行的[背景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之前等待的時間。接受一個或多個以逗號分隔、介於 `1` 到 `86400` 之間的整數秒數，例如 `600` 或 `600,1800,3600`。每個值是下一次提醒前的等待時間，最後一個值會重複使用。僅接受純數字；任何其他值或寫法都視為未設定。未設定時不會有提醒。需要 Claude Code v2.1.283 或更新版本 |

430| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流程](/docs/zh-TW/workflows) agent 在送出自己的第一個請求前，等待具有相同前綴的同層 agent 開始第一個回應的時間上限（毫秒）。當一次扇出啟動數個共用[提示快取前綴](/docs/zh-TW/workflows#prompt-caching-in-a-fan-out)的 agent 時，Claude Code 會讓第一個以外的所有 agent 最多等待這麼久，讓其餘 agent 讀取已快取的前綴，而不是各自在未快取的情況下處理。預設值為 `5000`。設為 `0` 可停用等待。設定 `DISABLE_PROMPT_CACHING` 時，agent 永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |431| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 單一[工作流程](/docs/zh-TW/workflows)執行同時執行的 agent 數量，範圍為 `1` 到 `256`。預設情況下，一次執行最多同時執行 16 個 agent，當 Claude Code 可用的 CPU 較少時則更少；排入佇列的 `agent()` 呼叫會等待空閒的位置。每個執行中 agent 的逐字稿都會保留在 Claude Code 的記憶體中，因此較高的值會增加記憶體用量。僅接受純數字；超出範圍的值與其他寫法都會維持預設值。需要 Claude Code v2.1.269 或更新版本 |

431| `CLAUDE_CONFIG_DIR` | 覆寫設定目錄（預設值：`~/.claude`）。所有設定、工作階段歷史記錄與外掛都儲存在此路徑下。關於憑證，請參閱 [Claude Code 儲存憑證的位置](/docs/zh-TW/authentication#credential-management)。適合同時執行多個帳戶：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。請在 shell、使用者設定或受管設定中設定此變數。在設定檔中，請寫入[絕對路徑](#in-settings-files)。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |432| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流程](/docs/zh-TW/workflows) agent 在傳送自己的第一個請求之前，等待具有相同前綴的同層 agent 的第一個回應開始的時間上限（毫秒）。當扇出啟動數個共用[提示快取前綴](/docs/zh-TW/workflows#prompt-caching-in-a-fan-out)的 agent 時，Claude Code 會讓第一個 agent 以外的所有 agent 最多等待這段時間，使其餘 agent 讀取已快取的前綴，而不是各自在未快取的情況下處理它。預設值為 `5000`。設定為 `0` 可停用等待。設定 `DISABLE_PROMPT_CACHING` 時，agent 永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |

432| `CLAUDE_DISABLE_ADOPT` | 設為 `1` 可在您按下 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，停止進行中的背景工作，而不是將其延續下去。Claude Code 會在移至背景前要求您確認，然後停止原本會延續下去的任務。需要 Claude Code v2.1.195 或更新版本 |433| `CLAUDE_CONFIG_DIR` | 覆寫設定目錄（預設值：`~/.claude`）。所有設定、工作階段歷程記錄與外掛都儲存在此路徑下。關於憑證，請參閱 [Claude Code 儲存憑證的位置](/docs/zh-TW/authentication#credential-management)。適用於同時執行多個帳戶：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。請在 shell、使用者設定或受管設定中設定。在設定檔中，請寫入[絕對路徑](#in-settings-files)。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

434| `CLAUDE_DISABLE_ADOPT` | 設定為 `1` 時，在您按下 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，會停止進行中的背景工作，而不是將其延續下去。Claude Code 會在移至背景前請您確認，然後停止原本會延續的任務。需要 Claude Code v2.1.195 或更新版本 |

433| `CLAUDE_EFFORT` | 在 Bash 工具子程序與 hook 命令中自動設定為子程序啟動時生效的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。與傳遞給 [hook](/docs/zh-TW/hooks) 的 `effort.level` 欄位相符。僅在目前模型支援 effort 參數時設定 |435| `CLAUDE_EFFORT` | 在 Bash 工具子程序與 hook 命令中自動設定為子程序啟動時生效的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。與傳遞給 [hook](/docs/zh-TW/hooks) 的 `effort.level` 欄位相符。僅在目前模型支援 effort 參數時設定 |

434| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設為 `1` 可強制啟用位元組層級的串流閒置監視器，或設為 `0` 強制停用。`0` 也會在執行[第一位元組截止期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上關閉該截止期限。未設定時，此監視器預設會在直接 Anthropic API 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線上啟用，也會針對透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 連線的[閘道](/docs/zh-TW/gateways)串流回應啟用；在 v2.1.222 之前，它不會在這些閘道連線上執行，因此即使 keep-alive ping 持續送達，事件層級監視器仍可能在那裡回報停滯。關於逾時以及各計時器之間的互動方式，請參閱[串流閒置監視器](/docs/zh-TW/network-config#streaming-idle-watchdogs) |436| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 可強制啟用位元組層級的串流閒置監控程式，設定為 `0` 則可強制停用。`0` 也會在執行[首位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上關閉該期限。未設定時，監控程式預設會在直接 Anthropic API 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線上啟用，並且在透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 連線的[閘道](/docs/zh-TW/gateways)連線的串流回應上啟用；在 v2.1.222 之前，它不會在這些閘道連線上執行，因此即使 keep-alive ping 持續抵達，事件層級監控程式仍可能在該處回報停滯。關於逾時以及計時器之間的互動方式，請參閱[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

435| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設為 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組層級的串流閒置監視器，這也會在 Bedrock 串流請求上啟用[第一位元組截止期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)。預設為關閉。請使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |437| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組層級的串流閒置監控程式，這也會在 Bedrock 串流請求上啟用[首位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)。預設為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |

436| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設為 `0` 可強制停用事件層級的串流閒置監視器，或設為 `1` 強制啟用。未設定時，此監視器預設對所有供應商開啟。在 v2.1.196 之前，未設定時的預設值在直接 Anthropic API 上由伺服器控制，在其他供應商上則為關閉。請使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時；關於與此監視器並行運作的其他停滯計時器，請參閱[串流閒置監視器](/docs/zh-TW/network-config#streaming-idle-watchdogs) |438| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `0` 可強制停用事件層級的串流閒置監控程式，設定為 `1` 則可強制啟用。未設定時，監控程式預設對所有提供者開啟。在 v2.1.196 之前，未設定時的預設值在直接 Anthropic API 上由伺服器控制，在其他提供者上則為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時；關於與此監控程式一起執行的其他停滯計時器，請參閱[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

437| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，Claude Code 會在每個 Bash 命令之前於同一個 shell 程序中執行其內容，因此檔案中的 export 對該命令可見。可用於在各命令之間保留 virtualenv 或 conda 的啟用狀態。也會由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 與 [FileChanged](/docs/zh-TW/hooks#filechanged) hook 動態填入 |439| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，Claude Code 會在同一個 shell 程序中於每個 Bash 命令之前執行其內容，因此檔案中的 export 對命令可見。用於在命令之間保留 virtualenv 或 conda 的啟用狀態。也會由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 與 [FileChanged](/docs/zh-TW/hooks#filechanged) hook 動態填入 |

438| `CLAUDE_JOB_DIR` | 由 Claude Code 在每個[背景工作階段](/docs/zh-TW/agent-view)中設定為該工作階段的 `~/.claude/jobs/<id>` 目錄。該工作階段執行的 shell 命令會繼承此變數。請將暫存檔案寫入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-TW/agent-view#where-state-is-stored)。Claude 在該處的 `Write` 與 `Edit` 呼叫不會要求權限，且刪除工作階段時會移除此目錄 |440| `CLAUDE_JOB_DIR` | 由 Claude Code 在每個[背景工作階段](/docs/zh-TW/agent-view)中設定為該工作階段的 `~/.claude/jobs/<id>` 目錄。工作階段執行的 shell 命令會繼承此變數。請將暫存檔案寫入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-TW/agent-view#where-state-is-stored)。Claude 在該處的 `Write` 與 `Edit` 呼叫不會提示權限，且刪除工作階段時會移除此目錄 |

439| `CLAUDE_PID` | Claude Code 會在其產生的子程序中將此變數設定為自己的程序 ID：包括 Bash 與 PowerShell 工具命令以及 hook 命令。在 Linux 上，Bash 工具的 shell 整合會使用它來拒絕會比對到 Claude Code 程序本身的 `pkill` 模式；請參閱[錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。您可以在自己的指令碼中讀取它，以刻意識別上層 Claude Code 程序或向其傳送訊號。需要 Claude Code v2.1.214 或更新版本 |441| `CLAUDE_PID` | Claude Code 會在其產生的子程序中將此變數設定為自身的程序 ID：包括 Bash 與 PowerShell 工具命令以及 hook 命令。在 Linux 上，Bash 工具的 shell 整合會使用它來拒絕會比對到 Claude Code 程序本身的 `pkill` 模式；請參閱[錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。您可以在自己的指令碼中讀取它，以刻意識別父 Claude Code 程序或向其傳送訊號。需要 Claude Code v2.1.214 或更新版本 |

440| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您電腦的主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。`--remote-control-session-name-prefix` CLI 旗標可為單次呼叫設定相同的值 |442| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供明確名稱時，自動產生之 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您電腦的主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。`--remote-control-session-name-prefix` CLI 旗標會為單次呼叫設定相同的值 |

441| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在執行[第一位元組截止期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上，串流請求第一個回應位元組的截止期限（毫秒）。關於 Claude Code 如何限制此值、針對大型請求主體額外增加的時間，以及未設定此變數時如何選擇截止期限，請參閱 [No response from API](/docs/zh-TW/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更新版本 |443| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在執行[首位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上，串流請求第一個回應位元組的期限（毫秒）。關於 Claude Code 如何限制此值、為大型請求主體增加的額外時間，以及您未設定此變數時它如何選擇期限，請參閱 [No response from API](/docs/zh-TW/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更新版本 |

442| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件層級與位元組層級的串流閒置監視器關閉停滯連線前的逾時時間（毫秒）。明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會被自動調整，以容納延伸思考的停頓與代理伺服器緩衝，且位元組層級監視器會將此值上限設為 30 分鐘。對於位元組層級監視器，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數。關於各監視器在未設定時的預設值，請參閱[串流閒置監視器](/docs/zh-TW/network-config#streaming-idle-watchdogs) |444| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件層級與位元組層級串流閒置監控程式關閉停滯連線前的逾時（毫秒）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會被靜默調整，以容納延伸思考的暫停與代理伺服器緩衝，而位元組層級監控程式會將值上限設為 30 分鐘。對於位元組層級監控程式，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數。關於各監控程式未設定時的預設值，請參閱[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

443| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已於 v2.1.260 移除，現在不起任何作用。先前用於限制由 [subagent](/docs/zh-TW/sub-agents) 啟動的[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)可執行的時間（毫秒），預設為 60 分鐘。請參閱[背景命令生命週期規則](/docs/zh-TW/tools-reference#background-commands) |445| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已在 v2.1.260 中移除，現在不具任何作用。先前用於限制 [subagent](/docs/zh-TW/sub-agents) 啟動的[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)可執行的時間（毫秒），預設為 60 分鐘。請參閱[背景命令生命週期規則](/docs/zh-TW/tools-reference#background-commands) |

444| `DEBUG` | 設為 `1` 可啟用除錯模式，等同於使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。除錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 所設定的路徑。只有真值 `1`、`true`、`yes` 與 `on` 會啟用除錯模式，因此為其他工具設定的命名空間模式（例如 `DEBUG=express:*`）不會觸發它 |446| `DEBUG` | 設定為 `1` 可啟用偵錯模式，等同於使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。只有真值 `1`、`true`、`yes` 與 `on` 會啟用偵錯模式，因此為其他工具設定的命名空間模式（例如 `DEBUG=express:*`）不會觸發它 |

446| `DISABLE_AUTO_COMPACT` | 設為 `1` 可停用接近上下文上限時的自動壓縮。手動 `/compact` 命令仍可使用。適合想要明確控制壓縮時機的情況。會覆寫 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |448| `DISABLE_AUTO_COMPACT` | 設定為 `1` 可停用接近上下文上限時的自動壓縮。手動 `/compact` 命令仍可使用。當您想明確控制壓縮發生的時機時使用。會覆寫 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |

449| `DISABLE_DOCTOR_COMMAND` | 設為 `1` 可隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。適用於不希望使用者在工作階段中執行設定診斷的受管部署。不影響 `claude doctor` 終端機命令。在 v2.1.205 之前，此變數會隱藏 `/doctor` 診斷畫面命令 |451| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 可隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。適用於使用者不應從工作階段中執行設定診斷的受管部署。不影響 `claude doctor` 終端機命令。在 v2.1.205 之前，此變數會隱藏 `/doctor` 診斷畫面命令 |

452| `DISABLE_FEEDBACK_COMMAND` | 設為 `1` 可停用 `/feedback` 命令與 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也會停用透過相同途徑回報的 `/bug` 與 `/share`；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此該命令在所有名稱下都會被停用。也接受舊名稱 `DISABLE_BUG_COMMAND` |454| `DISABLE_FEEDBACK_COMMAND` | 設定為 `1` 可停用 `/feedback` 命令與 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也會停用透過相同路徑回報的 `/bug` 與 `/share`；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此該命令在每個名稱下都會被停用。也接受舊名稱 `DISABLE_BUG_COMMAND` |

453| `DISABLE_GROWTHBOOK` | 設為 `1` 或 `true` 可停用 GrowthBook 功能旗標擷取，並對每個旗標使用程式碼中的預設值。這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 以及其他[需要擷取功能旗標的功能](#features-that-need-feature-flag-fetching)無法使用。設為 `0` 或 `false` 會維持擷取開啟。除非同時設定 `DISABLE_TELEMETRY`，否則遙測事件記錄仍會保持開啟 |455| `DISABLE_GROWTHBOOK` | 設定為 `1` 或 `true` 可停用 GrowthBook 功能旗標擷取，並對每個旗標使用程式碼預設值。這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 與其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。設定為 `0` 或 `false` 會讓擷取保持開啟。除非同時設定 `DISABLE_TELEMETRY`，否則遙測事件記錄會保持開啟 |

455| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設為 `1` 可隱藏 `/install-github-app` 命令。使用第三方供應商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已預設隱藏 |457| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設定為 `1` 可隱藏 `/install-github-app` 命令。使用第三方提供者（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已預設隱藏 |

456| `DISABLE_INTERLEAVED_THINKING` | 設為 `1` 可避免傳送 interleaved-thinking beta 標頭。適用於您的 LLM 閘道或供應商不支援[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情況 |458| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 可避免傳送 interleaved-thinking beta 標頭。當您的 LLM 閘道或提供者不支援[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)時很有用 |

461| `DISABLE_PROMPT_CACHING_HAIKU` | 設為 `1` 可對[預設 Haiku 模型](/docs/zh-TW/prompt-caching#disable-prompt-caching)停用提示快取，無論其在何處執行 |463| `DISABLE_PROMPT_CACHING_HAIKU` | 設定為 `1` 可為[預設 Haiku 模型](/docs/zh-TW/prompt-caching#disable-prompt-caching)停用提示快取，無論其在何處執行 |

464| `DISABLE_TELEMETRY` | 設為任何非空值（例如 `1`）可選擇不參與遙測。**設為 `0` 或 `false` 仍會選擇不參與**，這與大多數開關變數不同；取消設定此變數才能重新開啟遙測。遙測事件不包含程式碼、檔案路徑或 Bash 命令等使用者資料。也會停用[功能旗標擷取](#features-that-need-feature-flag-fetching)。請參閱[為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |466| `DISABLE_TELEMETRY` | 設定為任何非空值（例如 `1`）可選擇退出遙測。與大多數開關變數不同，**設定為 `0` 或 `false` 仍會選擇退出**；請取消設定此變數以重新開啟遙測。遙測事件不包含程式碼、檔案路徑或 Bash 命令等使用者資料。也會停用[功能旗標擷取](#features-that-need-feature-flag-fetching)。請參閱[為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |

465| `DISABLE_UPDATES` | 設為 `1` 可封鎖所有更新，包括手動執行 `claude update` 與 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。適用於透過您自己的管道發布 Claude Code，且使用者不應自行更新的情況 |467| `DISABLE_UPDATES` | 設定為 `1` 可封鎖所有更新，包括手動 `claude update` 與 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。當您透過自己的通道散布 Claude Code 且使用者不應自行更新時使用 |

467| `DO_NOT_TRACK` | 設為 `1` 可選擇不參與遙測，效果與 `DISABLE_TELEMETRY` 相同，包括對[功能旗標擷取](#features-that-need-feature-flag-fetching)的影響。Claude Code 會將此變數當作標準布林值讀取，因此 `0` 會維持遙測開啟，並將其視為許多開發者 CLI 共同認可的跨工具慣例來遵循 |469| `DO_NOT_TRACK` | 設定為 `1` 可選擇退出遙測，效果與 `DISABLE_TELEMETRY` 相同，包括對[功能旗標擷取](#features-that-need-feature-flag-fetching)的影響。Claude Code 將此變數視為標準布林值讀取，因此 `0` 會讓遙測保持開啟，並將其視為許多開發者 CLI 所認可的跨工具慣例加以遵循 |

468| `ENABLE_BETA_TRACING_DETAILED` | 設為 `1`，並將 `BETA_TRACING_ENDPOINT` 設為您的 OTLP/HTTP 收集器端點，即可開啟[詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，這會加入包含內容的 span 屬性以及 `claude_code.hook` span。互動式 CLI 工作階段還需要您的組織已列入此 beta 的允許清單。這兩個變數在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中都會被忽略 |470| `ENABLE_BETA_TRACING_DETAILED` | 設定為 `1`，並將 `BETA_TRACING_ENDPOINT` 設定為您的 OTLP/HTTP 收集器端點，即可開啟[詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，這會新增包含內容的 span 屬性與 `claude_code.hook` span。互動式 CLI 工作階段還需要您的組織已列入 beta 允許清單。這兩個變數在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中都會被忽略 |

469| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設為 `false` 可讓 Claude Code 停止擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對已登入的使用者預設為啟用。若要依專案或依組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |471| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 可讓 Claude Code 停止擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對已登入的使用者預設為啟用。若要依專案或依組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |

470| `ENABLE_PROMPT_CACHING_1H` | 設為 `1` 可請求 1 小時的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而非預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 使用者。在內含用量範圍內的訂閱使用者，會在[主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)上自動獲得 1 小時 TTL。使用[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的訂閱使用者可以設定此變數以保留 1 小時 TTL。1 小時快取寫入會以較高費率計費。若要改為依請求類別選擇 TTL，請使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 與 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，這兩者優先於此變數 |472| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 可請求 1 小時的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而非預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 使用者。在內含用量範圍內的訂閱使用者會在[主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)上自動獲得 1 小時 TTL。使用[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的訂閱使用者可以設定此變數以保留 1 小時 TTL。1 小時快取寫入會以較高費率計費。若要改為依請求類別選擇 TTL，請使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 與 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它們優先於此變數 |

472| `ENABLE_TOOL_SEARCH` | 控制 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設會延後載入所有 MCP 工具。但在早於 Claude 4.5 世代的 Google Cloud's Agent Platform 模型、託管於 Azure 的 Microsoft Foundry 部署，以及 `ANTHROPIC_BASE_URL` 指向非第一方主機時，仍會預先載入這些工具。`true` 一律延後載入並傳送 beta 標頭，但上述相同的 Agent Platform 模型與 Microsoft Foundry 部署除外；在不支援 `tool_reference` 的代理伺服器上，請求會失敗。`auto` 會在工具定義可容納於上下文的 10% 以內時預先載入。`auto:N` 可設定自訂閾值，例如 `auto:5` 代表 5%。`false` 會預先載入所有工具。設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時，您自行設定的值會被忽略。在 v2.1.221 之前，除非您將此變數設為 `true`，否則 Claude Code 會對 Google Cloud's Agent Platform 上的所有模型停用工具搜尋 |474| `ENABLE_TOOL_SEARCH` | 控制 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設會延遲載入所有 MCP 工具。但在早於 Claude 4.5 世代的 Google Cloud's Agent Platform 模型上、在託管於 Azure 的 Microsoft Foundry 部署上，以及當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，仍會預先載入這些工具。`true` 一律延遲載入並傳送 beta 標頭，但上述相同的 Agent Platform 模型與 Microsoft Foundry 部署除外；在不支援 `tool_reference` 的代理伺服器上，請求會失敗。`auto` 會在工具定義可容納於上下文的 10% 以內時預先載入。`auto:N` 可設定自訂門檻，例如 `auto:5` 代表 5%。`false` 會預先載入所有工具。設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時，您自行設定的值會被忽略。在 v2.1.221 之前，除非您將此變數設定為 `true`，否則 Claude Code 會為 Google Cloud's Agent Platform 上的所有模型停用工具搜尋 |

473| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設為任何非空值（例如 `1`），可在未設定備援模型時，讓 Claude Code 對所有模型在重複發生過載錯誤時停止重試。**設為 `0` 或 `false` 仍會啟用此行為**，這與大多數開關變數不同；取消設定此變數才能恢復預設的重試行為。未設定時，只有當您使用 API 金鑰或[第三方供應商](/docs/zh-TW/third-party-integrations)而非 Claude 訂閱進行身分驗證時，Claude Code 才會對其識別為 Opus、Fable 或 Mythos 的模型以此方式停止重試。在 Claude Code v2.1.160 或更新版本中，Claude Code 會在任何主要模型重複發生過載錯誤時切換至您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不影響切換至備援模型 |475| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值（例如 `1`），可讓 Claude Code 在未設定備援模型時，針對每個模型在重複的過載錯誤上停止重試。與大多數開關變數不同，**設定為 `0` 或 `false` 仍會啟用此行為**；請取消設定此變數以還原預設的重試行為。若未設定，當您使用 API 金鑰或[第三方提供者](/docs/zh-TW/third-party-integrations)而非 Claude 訂閱進行身分驗證時，Claude Code 只會在其識別為 Opus、Fable 或 Mythos 的模型上以此方式停止重試。在 Claude Code v2.1.160 或更新版本中，Claude Code 會在任何主要模型發生重複過載錯誤時切換至您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不會影響切換至備援模型 |

475| `FORCE_HYPERLINK` | 設為 `1` 可在您的終端機支援但未被自動偵測到時，啟用可點擊的 OSC 8 超連結，或設為 `0` 將其停用。未設定時，Claude Code 只有在偵測到終端機支援時才會啟用超連結。Claude Code 會將此值解析為數字而非布林值，因此 `false`、`no` 或 `off` 等值會啟用超連結，而不是停用。即使 Claude Code 無法偵測到終端機支援（例如透過 SSH 時），頁尾的 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status)仍會顯示為超連結。設為 `0` 可將徽章顯示為純文字 |477| `FORCE_HYPERLINK` | 當您的終端機支援可點擊的 OSC 8 超連結但未被自動偵測到時，設定為 `1` 可啟用它們，設定為 `0` 則可停用。未設定時，Claude Code 只在偵測到終端機支援時才啟用超連結。Claude Code 將此值解析為數字而非布林值，因此 `false`、`no` 或 `off` 等值會啟用超連結，而不是停用它們。即使 Claude Code 無法偵測到終端機支援（例如透過 SSH 時），頁尾的 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status)仍會以超連結呈現。設定 `0` 可將徽章呈現為純文字 |

476| `FORCE_PROMPT_CACHING_5M` | 設為 `1` 可強制使用 5 分鐘的提示快取 TTL，即使原本會套用 1 小時 TTL。會覆寫 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H`，以及 `promptCacheTtl` 與 `subagentPromptCacheTtl` 設定 |478| `FORCE_PROMPT_CACHING_5M` | 設定為 `1` 可強制使用 5 分鐘的提示快取 TTL，即使原本會套用 1 小時 TTL。會覆寫 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H`，以及 `promptCacheTtl` 與 `subagentPromptCacheTtl` 設定 |

479| `IS_DEMO` | 設為任何非空值（例如 `1`）可啟用示範模式：在標頭與 `/status` 輸出中隱藏您的電子郵件與組織名稱，並略過初始設定流程。**設為 `0` 或 `false` 仍會啟用示範模式**，這與大多數開關變數不同；取消設定此變數才能將其關閉。適用於直播或錄製工作階段的情況 |481| `IS_DEMO` | 設定為任何非空值（例如 `1`）可啟用示範模式：在標頭與 `/status` 輸出中隱藏您的電子郵件與組織名稱，並略過新手引導。與大多數開關變數不同，**設定為 `0` 或 `false` 仍會啟用示範模式**；請取消設定此變數以將其關閉。在直播或錄製工作階段時很有用 |

480| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數（預設值：25000）。當輸出超過 10,000 個 token 時，Claude Code 會顯示警告。宣告了 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具會改用該字元上限處理文字內容，但這些工具的圖片內容仍受此變數限制。來自未帶有該註解之工具、長度超過 50,000 個字元的成功文字結果，無論此變數為何，都會[儲存至檔案](/docs/zh-TW/mcp#mcp-output-limits-and-warnings) |482| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數（預設值：25000）。當輸出超過 10,000 個 token 時，Claude Code 會顯示警告。宣告 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具會改為對文字內容使用該字元上限，但這些工具的圖片內容仍受此變數限制。來自未具該註解之工具、長度超過 50,000 個字元的成功文字結果，無論此變數為何，都會被[儲存至檔案](/docs/zh-TW/mcp#mcp-output-limits-and-warnings) |

481| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 旗標的非互動模式下，當模型回應未通過 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；在達到該次數的失敗嘗試且沒有有效輸出後，執行即告失敗。當[工作流程](/docs/zh-TW/workflows) subagent 的結構化輸出未通過驗證時，也套用相同的上限。預設為 5，即第一次嘗試加上四次重試 |483| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 旗標的非互動模式中，當模型的回應未通過 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；在達到該失敗次數且沒有有效輸出後，執行會失敗。當[工作流程](/docs/zh-TW/workflows) subagent 的結構化輸出未通過驗證時，也適用相同的上限。預設為 5，即第一次嘗試加上四次重試 |

482| `MAX_THINKING_TOKENS` | [延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 預算。Claude Code 會將其上限設為比請求的最大輸出 token 數少一個 token，且永遠不低於 1,024。關於該上限的設定方式，請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未設定且已啟用思考時，具備[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型會自行選擇思考深度，其他模型則使用上限值。設為 `0` 可在 Anthropic API 上停用思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 與 Fable 模型除外，這些模型無法關閉思考。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，`0` 則會改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，對於 Claude Code 已知[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 會傳送 effort `high`，而不是更高的等級。若為正值，Claude Code 在自適應推理模型上會忽略該數字本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 關閉了自適應推理 |484| `MAX_THINKING_TOKENS` | [延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 預算。Claude Code 會將其上限設為比請求的最大輸出 token 數少一個 token，且絕不低於 1,024。關於該上限如何設定，請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未設定且啟用思考時，具備[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型會自行選擇思考深度，其他模型則使用上限。設定為 `0` 可在 Anthropic API 上停用思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 與 Fable 模型除外，這些模型無法關閉思考。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，`0` 會改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，對於 Claude Code 已知[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 會傳送 effort `high`，而不是更高的等級。對於正值，Claude Code 在自適應推理模型上會忽略數字本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 關閉了自適應推理 |

483| `MCP_CLIENT_SECRET` | 需要[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)之 MCP 伺服器的 OAuth 用戶端密鑰。可在使用 `--client-secret` 新增伺服器時避免互動式提示 |485| `MCP_CLIENT_SECRET` | 需要[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)之 MCP 伺服器的 OAuth 用戶端密碼。可避免在使用 `--client-secret` 新增伺服器時出現互動式提示 |

484| `MCP_CONNECTION_NONBLOCKING` | 控制啟動時是否在第一次查詢前等待 MCP 伺服器連線。MCP 啟動預設為非阻塞：伺服器會在背景連線，其工具會在完成時陸續可用。設為 `0` 可讓 Claude Code 在第一次查詢前等待伺服器連線。以 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 設定的伺服器無論如何仍會讓啟動等待，除非是從[探索快取](/docs/zh-TW/mcp#server-status-detail)提供，因為建立第一個提示詞時其工具必須已存在。在未使用 `--input-format stream-json` 的非互動模式（`-p`）下，無論此變數為何，Claude Code 也會在第一個回合前等待仍在擱置中的伺服器。當您明確傳入 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，等待的截止期限會較長；關於已快取伺服器的例外情況，請參閱該旗標的說明 |486| `MCP_CONNECTION_NONBLOCKING` | 控制啟動時是否在第一個查詢之前等待 MCP 伺服器連線。MCP 啟動預設為非阻塞：伺服器會在背景連線，其工具會在連線完成時變為可用。設定為 `0` 可讓 Claude Code 在第一個查詢之前等待伺服器連線。設定 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器無論如何仍會讓啟動等待，但從[探索快取](/docs/zh-TW/mcp#server-status-detail)提供時除外，因為在建立第一個提示詞時其工具必須存在。在未使用 `--input-format stream-json` 的非互動模式（`-p`）中，無論此變數為何，Claude Code 也會在第一個回合之前等待仍在等候中的伺服器。當您明確傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，等待的期限會較長；關於已快取伺服器的例外，請參閱該旗標的說明 |

485| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 啟動在擷取工具清單快照前，等待連線批次的時間（毫秒）（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 時，或標示為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。截止期限到時仍在擱置中的伺服器會繼續在背景連線。與 `MCP_TIMEOUT` 不同，後者限制的是個別伺服器的連線嘗試 |487| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 啟動在擷取工具清單快照前等待連線批次的時間（毫秒）（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 時，或標記為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。在期限時仍在等候中的伺服器會繼續在背景連線。與 `MCP_TIMEOUT` 不同，後者限制的是個別伺服器的連線嘗試 |

486| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 探索快取](/docs/zh-TW/mcp#server-status-detail)。快取開啟時，您先前使用過的遠端 HTTP 或 SSE 伺服器可能會顯示 [`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，且 Claude Code 會在其第一次工具呼叫時才連線，而不是在啟動時連線。除非漸進式推出已為您的帳戶啟用，否則快取預設為關閉。設為 `1` 可將其開啟，或設為 `0` 讓其即使在推出已啟用時仍保持關閉。在 v2.1.238 之前，快取預設為開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |488| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 探索快取](/docs/zh-TW/mcp#server-status-detail)。開啟快取時，您先前使用過的遠端 HTTP 或 SSE 伺服器可以顯示 [`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，且 Claude Code 會在其第一次工具呼叫時才連線，而不是在啟動時連線。除非漸進式推出已為您的帳戶啟用，否則快取預設為關閉。設定為 `1` 可將其開啟，設定為 `0` 則即使推出已啟用也會保持關閉。在 v2.1.238 之前，快取預設為開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |

487| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [探索快取](/docs/zh-TW/mcp#server-status-detail)項目的最大存留時間（秒）（預設值：14400，即 4 小時）。在項目超過此存留時間的啟動中，Claude Code 會捨棄該項目並在啟動時連線伺服器，就像快取關閉時一樣。Claude Code 會將此值上限設為 7 天。在 v2.1.238 之前，預設值為 86400，即 24 小時，且 Claude Code 不會限制此值 |489| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [探索快取](/docs/zh-TW/mcp#server-status-detail)項目的最大存留時間（秒）（預設值：14400，即 4 小時）。在項目比此時間更舊的啟動時，Claude Code 會將其捨棄並在啟動時連線伺服器，如同關閉快取時的行為。Claude Code 會將此值上限設為 7 天。在 v2.1.238 之前，預設值為 86400，即 24 小時，且 Claude Code 不會限制此值 |

488| `MCP_DISCOVERY_CACHE_STRIKES` | 在[探索快取](/docs/zh-TW/mcp#server-status-detail)項目超過 `MCP_DISCOVERY_CACHE_TTL_S` 的啟動中，Claude Code 會在背景重新整理該項目。此變數設定在 Claude Code 捨棄該項目並改為在下次啟動時連線伺服器之前，可以連續失敗幾次重新整理（預設值：1）。如果您的網路連線偶爾中斷，可以提高此值，讓單次重新整理失敗不會導致項目被捨棄。需要 Claude Code v2.1.238 或更新版本 |490| `MCP_DISCOVERY_CACHE_STRIKES` | 在[探索快取](/docs/zh-TW/mcp#server-status-detail)項目比 `MCP_DISCOVERY_CACHE_TTL_S` 更舊的啟動時，Claude Code 會在背景重新整理它。此變數設定在 Claude Code 捨棄該項目並改為於下次啟動時連線伺服器之前，可以連續失敗的重新整理次數（預設值：1）。如果您的網路連線偶爾會中斷，請提高此值，以免一次重新整理失敗就捨棄項目。需要 Claude Code v2.1.238 或更新版本 |

489| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用[探索快取](/docs/zh-TW/mcp#server-status-detail)項目而不重新整理的秒數（預設值：900）。在項目超過此時間的啟動中，Claude Code 仍會使用它，但會在背景重新整理。一旦項目超過 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，Claude Code 就會改為捨棄它。Claude Code 會將此值上限設為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 不會限制此值 |491| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用[探索快取](/docs/zh-TW/mcp#server-status-detail)項目而不重新整理的秒數（預設值：900）。在項目比此時間更舊的啟動時，Claude Code 仍會使用它，但會在背景重新整理。一旦項目比 `MCP_DISCOVERY_CACHE_MAX_STALE_S` 更舊，Claude Code 就會改為將其捨棄。Claude Code 會將此值上限設為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 不會限制此值 |

490| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，可在新增具有[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)的 MCP 伺服器時作為 `--callback-port` 的替代方案 |492| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，在新增具有[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)的 MCP 伺服器時，可作為 `--callback-port` 的替代方案 |

491| `MCP_PROTOCOL_NEGOTIATION` | 僅在 [v2 MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)上，決定 Claude Code 是否探測伺服器是否支援 MCP 協定修訂版 2026-07-28。設為 `auto` 可探測 HTTP、claude.ai 連接器與 stdio 伺服器，或設為 `legacy` 不探測任何伺服器。未設定此變數時，Claude Code 會探測 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)中所述的伺服器。任何其他值都會被忽略，並在除錯日誌中留下警告。需要 Claude Code v2.1.221 或更新版本 |493| `MCP_PROTOCOL_NEGOTIATION` | 僅適用於 [v2 MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)，控制 Claude Code 是否探測伺服器是否支援 MCP 協定修訂版 2026-07-28。設定 `auto` 可探測 HTTP、claude.ai 連接器與 stdio 伺服器，設定 `legacy` 則不探測任何伺服器。未設定此變數時，Claude Code 會探測 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)中所述的伺服器。任何其他值都會被忽略，並在偵錯日誌中記錄警告。需要 Claude Code v2.1.221 或更新版本 |

493| `MCP_SDK_GENERATION` | 固定此程序用來連線 MCP 伺服器的 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1`，建構於 MCP TypeScript SDK 1.x；或 `v2`，建構於 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)。未設定此變數時，Claude Code 會從該節列出的版本開始使用 v2。在 Claude Code v2.1.221 或更新版本中，v2 執行環境會檢查 MCP OAuth 伺服器在其授權回應中傳回的簽發者，若不相符，則登入會失敗並顯示以 `Issuer mismatch in authorization response` 開頭的錯誤。v1 執行環境不會執行此檢查。如果您設定了無法識別的值，Claude Code 會忽略它並將警告寫入除錯日誌。Claude Code 每個程序只讀取此值一次。需要 Claude Code v2.1.218 或更新版本 |495| `MCP_SDK_GENERATION` | 固定此程序用來連線至 MCP 伺服器的 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1`（建構於 MCP TypeScript SDK 1.x）或 `v2`（建構於 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)）。未設定此變數時，Claude Code 會使用 v2，從該章節所列的版本開始。在 Claude Code v2.1.221 或更新版本中，v2 執行環境會檢查 MCP OAuth 伺服器在其授權回應中傳回的簽發者，若不相符，則會以開頭為 `Issuer mismatch in authorization response` 的錯誤使登入失敗。v1 執行環境不會執行此檢查。如果您設定了無法識別的值，Claude Code 會將其忽略並在偵錯日誌中寫入警告。Claude Code 每個程序只讀取一次此值。需要 Claude Code v2.1.218 或更新版本 |

496| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時時間（毫秒）（預設值：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai 連接器伺服器，每個請求預設也會在 60 秒後逾時；將此變數或個別伺服器的 `timeout` 設為高於 60000，即可提高該單一請求上限。較低的值仍會縮短整體工具執行逾時，但單一請求上限維持 60 秒。Stdio 與 WebSocket 伺服器沒有單一請求計時器。`.mcp.json` 中個別伺服器的 `timeout` 欄位會針對該伺服器覆寫此值。至少為 1000 的個別伺服器 `timeout` 也會設定該伺服器工具呼叫的最小閒置時間窗口，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永遠不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會被調整為一秒；對於個別伺服器欄位，低於 1000 的值會被忽略 |498| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（毫秒）（預設值：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai 連接器伺服器，每個請求預設也會在 60 秒後逾時；將此變數或個別伺服器的 `timeout` 設定為高於 60000，即可提高該每次請求的上限。較低的值仍會縮短整體工具執行逾時，但每次請求的上限會維持在 60 秒。Stdio 與 WebSocket 伺服器沒有每次請求的計時器。`.mcp.json` 中個別伺服器的 `timeout` 欄位會為該伺服器覆寫此值。至少為 1000 的個別伺服器 `timeout` 也會設定該伺服器工具呼叫的最小閒置時間窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永遠不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會被調整為一秒；對於個別伺服器欄位，低於 1000 的值會被忽略 |

498| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 的屬性值長度上限。Claude Code 會將包含內容的遙測屬性上限設為此值與 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中較小者，讓截斷標記保持在 SDK 限制之內。Claude Code 會以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 與 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，並將已設定的最小值套用至所有訊號。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#common-configuration-variables) |500| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 的屬性值長度限制。Claude Code 會將包含內容的遙測屬性上限設為此值與 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中較小者，使截斷標記保持在 SDK 限制內。Claude Code 會以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 與 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，且設定的最小值會套用至所有訊號。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#common-configuration-variables) |

499| `OTEL_LOG_ASSISTANT_RESPONSES` | 設為 `1` 可在 `assistant_response` OpenTelemetry 日誌事件中包含模型的回應文字。未設定時，Claude Code 會改用 `OTEL_LOG_USER_PROMPTS` 的值。設為 `0` 可在即使已設定 `OTEL_LOG_USER_PROMPTS` 時仍保持回應遮蔽。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。需要 Claude Code v2.1.193 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#assistant-response-event) |501| `OTEL_LOG_ASSISTANT_RESPONSES` | 設定為 `1` 可在 `assistant_response` OpenTelemetry 日誌事件中包含模型的回應文字。未設定時，Claude Code 會改用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 可在即使設定了 `OTEL_LOG_USER_PROMPTS` 時仍保持回應遮蔽。請在 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。需要 Claude Code v2.1.193 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#assistant-response-event) |

500| `OTEL_LOG_MANAGED_SETTINGS` | 設為 `1` 可在 `managed_settings_resolved` OpenTelemetry 日誌事件中加入遮蔽後的受管設定，以及遮蔽前設定的 SHA-256 摘要。預設為停用。請在 shell、使用者設定或受管設定中設定此變數；專案或本機設定中的值不會將其開啟。需要 Claude Code v2.1.274 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#managed-settings-resolved-event) |502| `OTEL_LOG_MANAGED_SETTINGS` | 設定為 `1` 可將遮蔽後的受管設定，以及遮蔽前設定的 SHA-256 摘要，新增至 `managed_settings_resolved` OpenTelemetry 日誌事件。預設為停用。請在 shell、使用者設定或受管設定中設定；專案或本機設定中的值不會將其開啟。需要 Claude Code v2.1.274 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#managed-settings-resolved-event) |

501| `OTEL_LOG_RAW_API_BODIES` | 將 Anthropic Messages API 請求與回應的 JSON 以 `api_request_body` / `api_response_body` 日誌事件發出。設為 `1` 可內嵌在內容上限處截斷的主體，或設為 `file:<dir>` 將未截斷的主體寫入磁碟，並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 用於設定內容上限，預設為 60 KB。預設為停用；主體包含完整的對話記錄。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage#api-request-body-event) |503| `OTEL_LOG_RAW_API_BODIES` | 將 Anthropic Messages API 請求與回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出。設定為 `1` 可發出在內容上限處截斷的內嵌主體，或設定為 `file:<dir>` 將未截斷的主體寫入磁碟並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 可設定內容上限，預設為 60 KB。預設為停用；主體包含完整的對話記錄。請在 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage#api-request-body-event) |

502| `OTEL_LOG_TOOL_CONTENT` | 設為 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具內容。Span 屬性會在[其各自的閘門](/docs/zh-TW/monitoring-usage#new-context-gates)下攜帶工具內容。需要啟用[追蹤](/docs/zh-TW/monitoring-usage#traces-beta)。預設為停用以保護敏感資料。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage#tool-output-span-event) |504| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具內容。Span 屬性會在[其各自的閘門](/docs/zh-TW/monitoring-usage#new-context-gates)下攜帶工具內容。需要[追蹤](/docs/zh-TW/monitoring-usage#traces-beta)。預設為停用以保護敏感資料。請在 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage#tool-output-span-event) |

503| `OTEL_LOG_TOOL_DETAILS` | 設為 `1` 可在 OpenTelemetry 指標、追蹤與日誌中包含工具輸入引數；MCP 伺服器名稱；使用者撰寫的工作流程名稱；工具失敗時的原始錯誤字串；`api_refusal` 事件中的拒絕 `category`；[費用與 token 指標](/docs/zh-TW/monitoring-usage#cost-counter)中真實的 agent、skill、外掛與 MCP 伺服器名稱；以及其他工具詳細資訊。預設為停用以保護 PII。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |505| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 可在 OpenTelemetry 指標、追蹤與日誌中包含工具輸入引數；MCP 伺服器名稱；使用者撰寫的工作流程名稱；工具失敗時的原始錯誤字串；`api_refusal` 事件上的拒絕 `category`；[費用與 token 指標](/docs/zh-TW/monitoring-usage#cost-counter)上真實的 agent、skill、外掛與 MCP 伺服器名稱；以及其他工具詳細資訊。預設為停用以保護 PII。請在 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |

504| `OTEL_LOG_USER_PROMPTS` | 設為 `1` 可在 OpenTelemetry 追蹤與日誌中包含使用者提示詞文字。預設為停用（提示詞會被遮蔽）。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |506| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 可在 OpenTelemetry 追蹤與日誌中包含使用者提示詞文字。預設為停用（提示詞會被遮蔽）。請在 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |

506| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設為 `true` 可在指標屬性中包含工作階段進入點（預設值：排除）。於 v2.1.152 新增。請參閱[監控](/docs/zh-TW/monitoring-usage) |508| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設定為 `true` 可在指標屬性中包含工作階段進入點（預設值：排除）。於 v2.1.152 新增。請參閱[監控](/docs/zh-TW/monitoring-usage) |

507| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設為 `true` 可為 OpenTelemetry 指標與事件加上識別工作階段儲存庫的 `vcs.*` 屬性（預設值：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱[儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |509| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設定為 `true` 可為 OpenTelemetry 指標與事件加上識別工作階段儲存庫的 `vcs.*` 屬性（預設值：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱[儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |

508| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 會將 `OTEL_RESOURCE_ATTRIBUTES` 的鍵附加至指標資料點標籤。設為 `false` 可將其排除（預設值：包含）。請參閱[監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |510| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 會將 `OTEL_RESOURCE_ATTRIBUTES` 鍵附加至指標資料點標籤。設定為 `false` 可將其排除（預設值：包含）。請參閱[監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |

511| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆寫提供給 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill)之 skill 中繼資料的字元預算。此預算會以上下文視窗的 1% 動態調整，備援值為 8,000 個字元。為了向後相容而保留舊名稱 |513| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆寫顯示給 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill)之 skill 中繼資料的字元預算。預算會動態調整為上下文視窗的 1%，備援值為 8,000 個字元。保留舊名稱以維持回溯相容性 |

512| `TASK_MAX_OUTPUT_LENGTH` | 已於 v2.1.277 移除，現在不起任何作用，其所設定大小的 `TaskOutput` 工具也一併移除。先前用於設定 `TaskOutput` 工具保留的[背景任務](/docs/zh-TW/tools-reference#background-commands)輸出最大字元數。Claude 現在改用 `Read` 讀取背景任務的輸出檔案 |514| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中移除，現在不具任何作用，與其所調整大小的 `TaskOutput` 工具一併移除。先前用於設定 `TaskOutput` 工具保留之[背景任務](/docs/zh-TW/tools-reference#background-commands)輸出的最大字元數。Claude 現在改用 `Read` 讀取背景任務的輸出檔案 |

534 536

535也支援標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 以及各訊號專屬的變體）。關於設定細節，請參閱[監控](/docs/zh-TW/monitoring-usage)。537也支援標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 以及特定訊號的變體）。設定詳細資訊請參閱[監控](/docs/zh-TW/monitoring-usage)。

536 538

537請在 shell、使用者設定或受管設定中設定 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用於開啟匯出、選擇匯出目的地或擷取內容的 OpenTelemetry 變數。Claude Code [會在專案與本機設定中忽略這些變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，但該節所述的關閉值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及匯出間隔、逾時與壓縮相關變數（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在專案與本機設定中仍會套用。539請在 shell、使用者設定或受管設定中設定 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用於開啟匯出、選擇其目的地或擷取內容的 OpenTelemetry 變數。Claude Code [會在專案與本機設定中忽略它們](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，但該章節所述的關閉值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及匯出間隔、逾時與壓縮變數（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在專案與本機設定中仍然適用。

538 540

539<h2 id="what-the-subprocess-environment-scrub-removes">541<h2 id="what-the-subprocess-environment-scrub-removes">

540 子程序環境清除會移除哪些內容542 子程序環境清除會移除哪些內容

587* 使用 [advisor 工具](/docs/zh-TW/advisor#requirements)589* 使用 [advisor 工具](/docs/zh-TW/advisor#requirements)

588* 閱讀或回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)590* 閱讀或回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)

589* 讓 Claude 讀取[其他組織的公開 artifact](/docs/zh-TW/artifacts#read-an-artifact-shared-with-you)591* 讓 Claude 讀取[其他組織的公開 artifact](/docs/zh-TW/artifacts#read-an-artifact-shared-with-you)

590* 讓 Claude Code 探測 claude.ai 連接器伺服器或 stdio 伺服器是否支援 [MCP 協定修訂版 2026-07-28](/docs/zh-TW/mcp#mcp-client-runtimes)，除非您設定 `MCP_PROTOCOL_NEGOTIATION=auto`592* 讓 Claude Code 探測 claude.ai 連接器伺服器是否支援 [MCP 協定修訂版 2026-07-28](/docs/zh-TW/mcp#mcp-client-runtimes)，除非您設定 `MCP_PROTOCOL_NEGOTIATION=auto`

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

592* 取得 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)，Claude Code 是透過擷取的旗標來啟用此功能594* 取得 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)，Claude Code 是透過擷取的旗標來啟用此功能

593* 讓 Claude [將大量貼上內容視為貼上的文字，而非輸入的文字](/docs/zh-TW/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 預留位置背後的內容會未經標記地傳送給 Claude595* 讓 Claude [將大量貼上內容視為貼上的文字，而非輸入的文字](/docs/zh-TW/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 預留位置背後的內容會未經標記地傳送給 Claude

errors.md +53 −57

Details

703當速率限制、過載或伺服器錯誤中斷已經產生文字輸出的前景 subagent 時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。其唯一輸出是工具呼叫的 subagent 也會收到此錯誤；在 v2.1.199 中，該形狀返回了空部分結果。請參閱 [subagent 中的 API 錯誤](/docs/zh-TW/sub-agents#api-errors-in-subagents)。703當速率限制、過載或伺服器錯誤中斷已經產生文字輸出的前景 subagent 時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。其唯一輸出是工具呼叫的 subagent 也會收到此錯誤；在 v2.1.199 中，該形狀返回了空部分結果。請參閱 [subagent 中的 API 錯誤](/docs/zh-TW/sub-agents#api-errors-in-subagents)。

704 704

705<h2 id="usage-limits">705<h2 id="usage-limits">

706 使用限制706 用量上限

707</h2>707</h2>

708 708

709本節中的大多數錯誤表示與您的帳戶或方案相關的配額已達到。其中三個的運作方式不同：[`伺服器暫時限制請求`](#server-is-temporarily-limiting-requests) 是與您的方案配額無關的伺服器端節流，[`1M 上下文需要使用額度`](#usage-credits-required-for-1m-context) 是權利檢查而非耗盡的配額，[`確認提示未獲回應`](#the-prompt-to-confirm-went-unanswered) 表示使用額度同意提示已關閉且未獲回應，無論是否達到配額。709本節中的大多數錯誤表示與您的帳戶或方案相關的配額已達到。其中三個的運作方式不同：[`Server is temporarily limiting requests`](#server-is-temporarily-limiting-requests) 是與您的方案配額無關的伺服器端節流，[`Usage credits required for 1M context`](#usage-credits-required-for-1m-context) 是權利檢查而非耗盡的配額，[`The prompt to confirm went unanswered`](#the-prompt-to-confirm-went-unanswered) 表示用量點數同意提示已在未獲回應的情況下關閉，無論是否達到配額。

710 710

711<h3 id="youve-hit-your-session-limit">711<h3 id="youve-hit-your-session-limit">

712 您已達到工作階段限制712 You've hit your session limit

713</h3>713</h3>

714 714

715訂閱方案包括滾動使用額度。當額度用完時，您會看到以下其中一條訊息：715訂閱方案包括滾動使用額度。當額度用完時，您會看到以下其中一條訊息：

730**該怎麼做：**730**該怎麼做：**

731 731

732* 等待錯誤中顯示的重設時間732* 等待錯誤中顯示的重設時間

733* 在[桌面應用程式](/docs/zh-TW/desktop)的 Code 標籤中，工作階段限制卡片提供**達到限制時自動繼續**核取方塊。每週限制卡片則不提供。勾選後，桌面應用程式會在重設後重試中斷的回合，並在卡片上顯示重試時間。桌面核取方塊和 CLI 在 `/config` 中的**達到使用限制時自動繼續**設定是分開的，因此請分別關閉每一個。733* 在[桌面應用程式](/docs/zh-TW/desktop)的 Code 標籤中，工作階段限制卡片提供 **Auto-continue when limits reset** 核取方塊。每週限制卡片則不提供。勾選後，桌面應用程式會在重設後重試中斷的回合，並在卡片上顯示重試時間。桌面核取方塊和 CLI 在 `/config` 中的 **Continue automatically at usage limit** 設定是分開的，因此請分別關閉每一個。

734* 對於 Opus 或 Sonnet 限制，執行 `/model` 並切換到該系列外的模型以繼續工作。每個模型都有自己的提示快取，因此下一個請求會重新讀取整個對話，沒有快取命中；請參閱[切換模型](/docs/zh-TW/prompt-caching#switching-models)734* 對於 Opus 或 Sonnet 限制，執行 `/model` 並切換到該系列外的模型以繼續工作。每個模型都有自己的提示快取，因此下一個請求會重新讀取整個對話，沒有快取命中；請參閱[切換模型](/docs/zh-TW/prompt-caching#switching-models)

735* 執行 `/usage` 以查看您的方案限制和重設時間735* 執行 `/usage` 以查看您的方案限制和重設時間

736* 執行 `/usage-credits` 以在 Pro 和 Max 上購買額外使用量，或在 Team 和 Enterprise 上向您的管理員請求。請參閱[付費方案的使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)以了解如何計費。736* 執行 `/usage-credits` 以在 Pro 和 Max 上購買額外使用量，或在 Team 和 Enterprise 上向您的管理員請求。請參閱[付費方案的用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)以了解如何計費。

737* 若要升級您的方案以獲得更高的基本限制，請參閱 [claude.com/pricing](https://claude.com/pricing)737* 若要升級您的方案以獲得更高的基本限制，請參閱 [claude.com/pricing](https://claude.com/pricing)

738 738

739在視窗用完之前，Claude Code 可以警告您已使用大部分額度，訊息例如 `You've used 85% of your session limit · resets 3:45pm`。若要持續監視您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態行](/docs/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/docs/zh-TW/desktop#check-usage)。739在視窗用完之前，Claude Code 可以警告您已使用大部分額度，訊息例如 `You've used 85% of your session limit · resets 3:45pm`。若要持續監視您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態列](/docs/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/docs/zh-TW/desktop#check-usage)。

740 740

741<h3 id="usage-credits-required-for-1m-context">741<h3 id="usage-credits-required-for-1m-context">

742 1M 上下文需要使用額度742 Usage credits required for 1M context

743</h3>743</h3>

744 744

745選定的模型使用 1M 權杖擴展上下文視窗，而您的方案僅透過使用額度包括它。745選定的模型使用 1M token 擴展上下文視窗，而您的方案僅透過用量點數包括它。

746 746

747```text theme={null}747```text theme={null}

748API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context748API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

749```749```

750 750

751在 Claude 桌面應用程式執行的工作階段中，提示不會命名任何命令：它指向 claude.ai 使用量設定頁面，或在 Team 和 Enterprise 方案上說在 claude.ai/admin-settings/usage 開啟使用額度，或要求您的管理員。751在 Claude 桌面應用程式執行的工作階段中，提示不會命名任何命令：它指向 claude.ai 使用量設定頁面，或在 Team 和 Enterprise 方案上說在 claude.ai/admin-settings/usage 開啟用量點數，或請您的管理員處理。

752 752

753這是權利檢查，而非配額耗盡。即使您的工作階段和每週額度有剩餘容量，它也會觸發。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解哪些方案直接包括 1M 上下文，哪些需要使用額度。753這是權利檢查，而非配額耗盡。即使您的工作階段和每週額度有剩餘容量，它也會觸發。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解哪些方案直接包括 1M 上下文，哪些需要用量點數。

754 754

755當此錯誤在對話中期出現，因為上下文增長超過 200K 權杖時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 `/compact`）上重複；在這些版本上執行 `/clear` 以恢復。以下步驟適用於您明確選擇 `[1m]` 模型的情況。755當此錯誤在對話中途出現，因為上下文增長超過 200K token 時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 `/compact`）上重複；在這些版本上執行 `/clear` 以恢復。以下步驟適用於您明確選擇 `[1m]` 模型的情況。

756 756

757**該怎麼做：**757**該怎麼做：**

758 758

759* 執行 `/model` 並選擇不帶 `[1m]` 後綴的變體以回退到標準上下文視窗759* 執行 `/model` 並選擇不帶 `[1m]` 後綴的變體以回退到標準上下文視窗

760* 訊息提及 `/usage-credits` 的地方，執行它以在 Pro 和 Max 上為 1M 變體開啟計量計費，或在 Team 和 Enterprise 上向您的管理員請求使用額度。一旦使用額度開啟，重新啟動 Claude Code 或開始新的工作階段，取決於訊息所說的。在您重新啟動之前，工作階段會保持在標準上下文限制。760* 訊息提及 `/usage-credits` 的地方，執行它以在 Pro 和 Max 上為 1M 變體開啟計量計費，或在 Team 和 Enterprise 上向您的管理員請求用量點數。一旦用量點數開啟，請依訊息所說重新啟動 Claude Code 或開始新的工作階段。在此之前，工作階段會保持在標準上下文限制。

761* 如果 `/model` 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱[設定您的模型](/docs/zh-TW/model-config#setting-your-model)以按優先順序檢查設定位置。761* 如果 `/model` 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱[設定您的模型](/docs/zh-TW/model-config#setting-your-model)以按優先順序檢查設定位置。

762* 若要從模型選擇器中完全移除 1M 變體，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars)762* 若要從模型選擇器中完全移除 1M 變體，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars)

763 763

764在 v2.1.268 之前，訊息以 `run /usage-credits to turn them on, or /model to switch to standard context` 結尾，並未提及重新啟動。764在 v2.1.268 之前，訊息以 `run /usage-credits to turn them on, or /model to switch to standard context` 結尾，並未提及重新啟動。

765 765

766<h3 id="the-prompt-to-confirm-went-unanswered">766<h3 id="the-prompt-to-confirm-went-unanswered">

767 確認提示未獲回應767 The prompt to confirm went unanswered

768</h3>768</h3>

769 769

770如果您的帳戶需要 [Fable 使用額度同意](/docs/zh-TW/model-config#fable-and-usage-credits)，Claude Code 會要求您在 Fable 請求計費使用額度之前確認。當沒有人在工作階段執行所在的終端回應該同意提示時，Claude Code 會以以下其中一條訊息結束回合：770如果您的帳戶需要 [Fable 用量點數同意](/docs/zh-TW/model-config#fable-and-usage-credits)，Claude Code 會要求您在 Fable 請求計費用量點數之前確認。當同意提示在無人回應的情況下關閉時，Claude Code 會以以下其中一條訊息結束回合：

771 771

772```text theme={null}772```text theme={null}

773Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change773Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

776 776

777訊息會命名工作階段的 Fable 模型，因此在 Fable 5 上它們會讀作 `continuing on Fable 5` 和 `Fable 5 now uses usage credits`。在 v2.1.257 之前，第一條訊息以 `Fable 5 limit reached` 開頭。777訊息會命名工作階段的 Fable 模型，因此在 Fable 5 上它們會讀作 `continuing on Fable 5` 和 `Fable 5 now uses usage credits`。在 v2.1.257 之前，第一條訊息以 `Fable 5 limit reached` 開頭。

778 778

779這發生在[遠端控制](/docs/zh-TW/remote-control)工作階段、[背景工作階段](/docs/zh-TW/agent-view)、[代理團隊](/docs/zh-TW/agent-teams)隊友工作階段，以及另一個應用程式透過 Agent SDK 託管的工作階段中。如需 Claude Code 何時關閉提示，請參閱 [Fable 和使用額度](/docs/zh-TW/model-config#fable-and-usage-credits)。779這發生在 [Remote Control](/docs/zh-TW/remote-control) 工作階段、[背景工作階段](/docs/zh-TW/agent-view)、[agent team](/docs/zh-TW/agent-teams) 隊友工作階段，以及另一個應用程式透過 Agent SDK 託管的工作階段中。如需 Claude Code 何時關閉提示，請參閱 [Fable 和用量點數](/docs/zh-TW/model-config#fable-and-usage-credits)。

780 780

781**該怎麼做：**781**該怎麼做：**

782 782

783* 在工作階段執行所在的終端或託管它的應用程式中，發送另一個提示，當同意提示重新出現時回答它。對於背景工作階段，請先從[代理檢視](/docs/zh-TW/agent-view)附加到它。從遠端控制用戶端重新發送會再次顯示此訊息，因為用戶端無法顯示提示。783* 在工作階段執行所在的終端機或託管它的應用程式中，發送另一個提示詞，當同意提示重新出現時回答它。對於背景工作階段，請先從 [agents 檢視](/docs/zh-TW/agent-view)附加到它。從 Remote Control 用戶端重新發送會再次顯示此訊息，因為用戶端無法顯示提示。

784* 執行 `/model` 以切換到不計費使用額度的模型784* 執行 `/model` 以切換到不計費用量點數的模型

785* 若要給自己更多時間，請將 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定為更長的值或 `"never"`785* 若要給自己更多時間，請將 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定為更長的值或 `"never"`

786 786

787在 v2.1.236 之前，此訊息不會出現：當遠端控制用戶端已連接時，Claude Code 會等待 60 秒以獲得答案，然後在您的預設模型上繼續回合。787在 v2.1.236 之前，此訊息不會出現：當 Remote Control 用戶端已連接時，Claude Code 會等待 60 秒以獲得答案，然後在您的預設模型上繼續回合。

788 788

789<h3 id="server-is-temporarily-limiting-requests">789<h3 id="server-is-temporarily-limiting-requests">

790 伺服器暫時限制請求790 Server is temporarily limiting requests

791</h3>791</h3>

792 792

793API 應用了與您的方案配額無關的短期節流。793API 應用了與您的方案配額無關的短期節流。

796API Error: Server is temporarily limiting requests (not your usage limit)796API Error: Server is temporarily limiting requests (not your usage limit)

797```797```

798 798

799Claude Code 通過真實限制回應所攜帶的統一配額標頭的缺失來區分這些。自 v2.1.199 起，無論您如何驗證，這都會[自動重試](#automatic-retries)並進行退避，然後才顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗回合；只有 API 金鑰和 Enterprise 登入重試它。799Claude Code 透過真實限制回應所攜帶的統一配額標頭是否缺失來區分這些情況。自 v2.1.199 起，無論您如何驗證，這都會[自動重試](#automatic-retries)並進行退避，然後才顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時即讓回合失敗；只有 API 金鑰和 Enterprise 登入會重試它。

800 800

801**該怎麼做：**801**該怎麼做：**

802 802

804* 如果問題持續，請檢查 [status.claude.com](https://status.claude.com)804* 如果問題持續，請檢查 [status.claude.com](https://status.claude.com)

805 805

806<h3 id="request-rejected-429">806<h3 id="request-rejected-429">

807 請求被拒絕 (429)807 Request rejected (429)

808</h3>808</h3>

809 809

810您已達到為您的 API 金鑰、Amazon Bedrock 專案或 Google Cloud 專案設定的速率限制。810您已達到為您的 API 金鑰、Amazon Bedrock 專案或 Google Cloud 專案設定的速率限制。

813API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.813API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

814```814```

815 815

816尾部句子命名檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 設定會命名該提供者的服務狀態，而不是 Anthropic 狀態頁面。自訂 `ANTHROPIC_BASE_URL` 會命名閘道主機。816結尾的句子指出檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 設定會指出該提供者的服務狀態，而不是 Anthropic 狀態頁面。自訂 `ANTHROPIC_BASE_URL` 會指出閘道主機。

817 817

818當代理、負載平衡器或 Claude Code 與 API 之間的閘道以其自己的 HTML 429 頁面回應時，`·` 後面的文字是該頁面的標題（如果有的話），例如 `Too Many Requests`。在 v2.1.281 之前，整個頁面的標記被列印在 `·` 後面。818當代理伺服器、負載平衡器或 Claude Code 與 API 之間的閘道以其自己的 HTML 429 頁面回應時，`·` 後面的文字是該頁面的標題（如果有的話），例如 `Too Many Requests`。在 v2.1.281 之前，整個頁面的標記會被列印在 `·` 後面。

819 819

820**該怎麼做：**820**該怎麼做：**

821 821

822* 執行 `/status` 並確認作用中的認證是您預期的認證。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱路由請求。822* 執行 `/status` 並確認作用中的憑證是您預期的憑證。環境中殘留的 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱路由請求。

823* 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級823* 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級

824* 對於 Anthropic API 金鑰，請參閱[速率限制參考](https://platform.claude.com/docs/en/api/rate-limits)以了解層級如何運作以及如何設定每個工作區的上限824* 對於 Anthropic API 金鑰，請參閱[速率限制參考](https://platform.claude.com/docs/en/api/rate-limits)以了解層級如何運作以及如何設定每個工作區的上限

825* 降低並行性：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-TW/env-vars)、避免執行許多平行子代理，或使用 `/model` 切換到較小的模型以進行高容量指令碼執行825* 降低並行性：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-TW/env-vars)、避免執行許多平行 subagent，或使用 `/model` 切換到較小的模型以進行高容量指令碼執行

826 826

827<h3 id="youve-hit-your-monthly-spend-limit">827<h3 id="youve-hit-your-monthly-spend-limit">

828 您已達到每月支出限制828 You've hit your monthly spend limit

829</h3>829</h3>

830 830

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

832 832

833```text theme={null}833```text theme={null}

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

835You've hit your individual spend limit · ask your admin for a higher limit835You've hit your individual spend limit · ask your admin for a higher limit

836You've hit your org's monthly spend limit · visit claude.ai/admin-settings/usage to raise it836You've hit your org's monthly spend limit · visit https://claude.ai/admin-settings/usage to raise it

837You've hit your team's shared budget · ask your admin to raise it at claude.ai/admin-settings/usage837You've hit your team's shared budget · ask your admin to raise it at https://claude.ai/admin-settings/usage

838You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings838You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

839```839```

840 840

841`team's shared budget` 是管理員分配給您所屬群組的集區預算；訊息不會命名該群組。`channel's monthly spend limit` 是工作階段執行所在的 Slack 頻道的預算，因此您的組織可能在其外仍有預算。841`team's shared budget` 是管理員分配給您所屬群組的集區預算；訊息不會命名該群組。`channel's monthly spend limit` 是工作階段執行所在的 Slack 頻道的預算，因此您的組織可能在其外仍有預算。

842 842

843當您的方案的其中一個視窗是用完的視窗時，訊息也會說明該視窗何時重設，例如 `· your session limit resets 3:45pm`，存取會在那時返回，無需任何人提高限制。在具有基於使用量的計費的組織上，訊息會說 `usage limit` 而不是 `spend limit`，如 `You've hit your individual usage limit`。843當您的方案的其中一個視窗是用完的視窗時，訊息也會說明該視窗何時重設，例如 `· your session limit resets 3:45pm`，存取會在那時恢復，無需任何人提高限制。在採用基於使用量計費的組織上，訊息會說 `usage limit` 而不是 `spend limit`，如 `You've hit your individual usage limit`。

844 844

845在 v2.1.239 之前，訊息不會命名方案視窗的重設時間。在 v2.1.268 之前，群組的集區預算產生了 `individual spend limit` 訊息，而不是 `team's shared budget`。845如果您透過 Claude 應用程式閘道連接並看到小寫 `spend limit reached`，那是您的閘道營運者設定的上限；請參閱 [Spend limit reached](#spend-limit-reached)。

~~846~~

847如果您透過 Claude 應用程式閘道連接並看到小寫 `spend limit reached`，那是您的閘道運營商的上限；請參閱[支出限制已達到](#spend-limit-reached)。

848 846

849**該怎麼做：**847**該怎麼做：**

850 848

851* 在 Pro 和 Max 上，在 claude.ai 的[**設定 > 使用量**](https://claude.ai/settings/usage)中提高您的每月支出限制，或執行 `/usage-credits`849* 在 Pro 和 Max 上，在 claude.ai 的[**設定 > 使用量**](https://claude.ai/settings/usage)中提高您的每月支出限制，或執行 `/usage-credits`

852* 在 Team 和 Enterprise 上，如果您管理計費，請在[**組織設定 > 使用量**](https://claude.ai/admin-settings/usage)中提高限制，或請管理員提高。`/usage-credits` 會為您向管理員發送該請求850* 在 Team 和 Enterprise 上，如果您管理計費，請在[**組織設定 > 使用量**](https://claude.ai/admin-settings/usage)中提高限制，或請管理員提高。`/usage-credits` 會為您向管理員發送該請求

853* 對於頻道的限制，要求組織擁有者或頻道的管理員在 claude.ai 上提高它。請參閱 Claude Tag 文件中的[每頻道限制](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)851* 對於頻道的限制，請組織擁有者或頻道的管理員在 claude.ai 上提高它。請參閱 Claude Tag 文件中的[每頻道限制](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)

854* 如果訊息命名您的方案視窗的重設時間，您可以改為等待它852* 如果訊息指出您的方案視窗的重設時間，您可以改為等待它

855* 執行 `/usage` 以查看您的方案視窗和每個視窗何時重設853* 執行 `/usage` 以查看您的方案視窗和每個視窗何時重設

856 854

857<h3 id="spend-limit-reached">855<h3 id="spend-limit-reached">

858 已達到支出限制856 Spend limit reached

859</h3>857</h3>

860 858

861您透過[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)連接，並已超過閘道運營商設定的[支出上限](/docs/zh-TW/claude-apps-gateway-spend-limits)。閘道會阻止您的請求，直到命名的期間重設或運營商提高上限。它將每個被阻止的 `429` 回應標記為 `x-should-retry: false`，因此 Claude Code 會顯示此訊息而不重試。859您透過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)連接，並已超過閘道營運者設定的[支出上限](/docs/zh-TW/claude-apps-gateway-spend-limits)。閘道會阻止您的請求，直到指定的期間重設或營運者提高上限。它將每個被阻止的 `429` 回應標記為 `x-should-retry: false`，因此 Claude Code 會顯示此訊息而不重試。

862 860

863```text theme={null}861```text theme={null}

864spend limit reached (daily; resets 2026-08-09 00:00 UTC)862spend limit reached (daily; resets 2026-08-09 00:00 UTC)

865```863```

866 864

867訊息會命名上限的期間和重設時間，當運營商設定了 `blocked_message` 時，他們的指示會跟在它後面。在 v2.1.225 之前，訊息只讀 `spend limit reached`；較舊版本上的閘道仍會發送該較短的形式。865訊息會指出上限的期間和重設時間，當營運者設定了 `blocked_message` 時，他們的指示會跟在後面。在 v2.1.225 之前，訊息只顯示 `spend limit reached`；較舊版本上的閘道仍會發送該較短的形式。

868 866

869**該怎麼做：**867**該怎麼做：**

870 868

871* 等待訊息命名的重設時間，或如果訊息包含運營商的指示，請遵循它們869* 等待訊息指出的重設時間，或如果訊息包含營運者的指示，請遵循它們

872* 如果您經常達到上限，請要求您的閘道運營商提高上限870* 如果您經常達到上限，請要求您的閘道營運者提高上限

873 871

874相關訊息 `spend limit unavailable` 表示閘道無法讀取其支出記錄，並作為預防措施而不是超過您的上限而阻止了請求。它通常會自行清除；如果它持續，請告訴您的閘道運營商。872相關訊息 `spend limit unavailable` 表示閘道無法讀取其支出記錄，並作為預防措施阻止了請求，而不是因為超過您的上限。它通常會自行解除；如果持續發生，請告知您的閘道營運者。

875 873

876<h3 id="credit-balance-is-too-low">874<h3 id="credit-balance-is-too-low">

877 信用額度餘額過低875 Credit balance is too low

878</h3>876</h3>

879 877

880您的 Console 組織已用完預付額度，或 Claude Code 正在使用 Console API 金鑰發送您的請求，而您打算使用您的訂閱。878您的 Console 組織已用完預付點數，或 Claude Code 正在使用 Console API 金鑰發送您的請求，而您原本打算使用您的訂閱。

881 879

882```text theme={null}880```text theme={null}

883Credit balance is too low881Credit balance is too low

886**該怎麼做：**884**該怎麼做：**

887 885

888* 如果您有 Pro、Max、Team 或 Enterprise 方案並看到此訊息，執行 `/status` 並檢查 `API key` 列。環境中已核准的 `ANTHROPIC_API_KEY` 會透過該金鑰而不是您的訂閱路由請求。在目前的 shell 中取消設定它，並從您的 shell 設定檔中移除它，然後重新啟動 `claude`。如果您還沒有使用您的訂閱登入，請執行 `/login`。886* 如果您有 Pro、Max、Team 或 Enterprise 方案並看到此訊息，執行 `/status` 並檢查 `API key` 列。環境中已核准的 `ANTHROPIC_API_KEY` 會透過該金鑰而不是您的訂閱路由請求。在目前的 shell 中取消設定它，並從您的 shell 設定檔中移除它，然後重新啟動 `claude`。如果您還沒有使用您的訂閱登入，請執行 `/login`。

889* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 新增額度，並考慮在那裡啟用自動重新載入，以便在餘額達到零之前重新填充887* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 新增點數，並考慮在那裡啟用自動儲值，以便在餘額歸零之前自動補充

890* 在 Console 中設定每個工作區的支出上限，以防止單個專案耗盡組織餘額。請參閱[有效管理成本](/docs/zh-TW/costs)。888* 在 Console 中設定每個工作區的支出上限，以防止單個專案耗盡組織餘額。請參閱[有效管理成本](/docs/zh-TW/costs)。

891 889

892<h3 id="could-not-update-your-spend-limit">890<h3 id="could-not-update-your-spend-limit">

893 無法更新您的支出限制891 Could not update your spend limit

894</h3>892</h3>

895 893

896伺服器拒絕了您從達到支出限制時出現的提示中進行的支出限制變更。894伺服器拒絕了您從達到支出限制時出現的提示中進行的支出限制變更。

899Could not update your spend limit: <reason from the server>897Could not update your spend limit: <reason from the server>

900```898```

901 899

902當伺服器解釋拒絕時，訊息以該原因結尾，重試相同值會再次失敗。當失敗沒有伺服器提供的原因（例如連接中斷）時，訊息會讀作 `Could not update your spend limit. Press Enter to retry.`，重試可能會成功。在 v2.1.216 之前，Claude Code 為每個失敗顯示通用形式。900當伺服器解釋拒絕原因時，訊息以該原因結尾，重試相同值會再次失敗。當失敗沒有伺服器提供的原因（例如連線中斷）時，訊息會顯示 `Could not update your spend limit. Press Enter to retry.`，重試可能會成功。在 v2.1.216 之前，Claude Code 對每個失敗都顯示通用形式。

903 901

904**該怎麼做：**902**該怎麼做：**

905 903

2861 2859

2862如果訊息包含 `` Details: `[reasoning_extraction]` `` 這一行，請參閱[安全措施標記了要求提供 Claude 推理過程的請求](#safeguards-flagged-a-request-for-claudes-reasoning)。2860如果訊息包含 `` Details: `[reasoning_extraction]` `` 這一行，請參閱[安全措施標記了要求提供 Claude 推理過程的請求](#safeguards-flagged-a-request-for-claudes-reasoning)。

2863 2861

2864訊息連結到[網路安全驗證計畫](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，該計畫為合法網路安全工作授予存取權限。在 Opus 5.5 和 Sonnet 5.5 上，訊息以 `<model>'s safeguards flagged this session` 開頭。當標記的類別有可用的備援模型時，Claude Code [切換模型](/docs/zh-TW/model-config#automatic-model-fallback)而不是顯示此錯誤。2862此訊息連結到[網路安全驗證計畫](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，該計畫為合法網路安全工作授予存取權限。具有[自動模型備援](/docs/zh-TW/model-config#automatic-model-fallback)的模型會印出不含此連結的不同訊息；在 Opus 5.5 和 Sonnet 5.5 上，該訊息以 `<model>'s safeguards flagged this session` 開頭。該章節也說明了 Claude Code 何時改為切換模型。

2865 2863

2866在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，網路安全標記會產生[使用政策拒絕](#usage-policy-refusal)訊息。2864在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，網路安全標記會產生[使用政策拒絕](#usage-policy-refusal)訊息。

2867 2865

4817* 要刻意作用於主簽出，請在工作階段外的終端機中自己執行命令4815* 要刻意作用於主簽出，請在工作階段外的終端機中自己執行命令

4818 4816

4819<h3 id="this-session-has-no-saved-transcript">4817<h3 id="this-session-has-no-saved-transcript">

4820 此工作階段沒有已儲存的逐字稿4818 This session has no saved transcript

4821</h3>4819</h3>

4822 4820

4823您附加到已停止的[背景工作階段](/docs/zh-TW/agent-view)，該工作階段使用 `←` 或 `/background` 從另一個對話背景化，並在其第一個回應完成之前停止。在該第一個回應完成之前，對話仍然只存在於背景化它的工作階段中，因此 `claude attach` 拒絕啟動已停止的工作階段，而不是在相同工作階段 ID 下開始空白對話。訊息以此工作階段的 `claude respawn` 命令結尾：4821您附加到已停止的[背景工作階段](/docs/zh-TW/agent-view)，該工作階段使用 `←` 或 `/background` 從另一個對話背景化，並在其第一個回應完成之前停止。在該第一個回應完成之前，對話仍然只存在於背景化它的工作階段中，因此 `claude attach` 拒絕啟動已停止的工作階段，而不是在相同工作階段 ID 下開始空白對話。訊息以此工作階段的 `claude respawn` 命令結尾：

4826This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.4824This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

4827```4825```

4828 4826

4829在 [agent 檢視](/docs/zh-TW/agent-view)中開啟相同工作階段的列，會改為在清單下方顯示 `Press enter again to restart this session fresh`，在該列上第二次按 `Enter` 會使用空白對話重新啟動工作階段。在 v2.1.212 之前，開啟列會顯示拒絕訊息，無法從 agent 檢視重新啟動。在 v2.1.211 之前，開啟已停止的工作階段會無聲地啟動該空白對話，並可能重新執行工作階段的原始提示詞。4827在 [agent 檢視](/docs/zh-TW/agent-view)中開啟相同工作階段的列，會改為在清單下方顯示 `Press enter again to restart this session fresh`，在該列上第二次按 `Enter` 會使用空白對話重新啟動工作階段。

4830 4828

4831**該怎麼做：**4829**該怎麼做：**

4832 4830

4835* 如果工作階段確實完成了回應，而您在 v2.1.214 之前的版本上仍看到此拒絕，`~/.claude/projects` 中的不可讀資料夾可能會使逐字稿掃描遺漏已儲存的對話；請更新到 v2.1.214 或更新版本，其在掃描期間容許不可讀資料夾4833* 如果工作階段確實完成了回應，而您在 v2.1.214 之前的版本上仍看到此拒絕，`~/.claude/projects` 中的不可讀資料夾可能會使逐字稿掃描遺漏已儲存的對話；請更新到 v2.1.214 或更新版本，其在掃描期間容許不可讀資料夾

4836 4834

4837<h3 id="this-session-is-running-in-another-terminal">4835<h3 id="this-session-is-running-in-another-terminal">

4838 此工作階段在另一個終端機中執行4836 This session is running in another terminal

4839</h3>4837</h3>

4840 4838

4841您在 [agent 檢視](/docs/zh-TW/agent-view)中開啟了已停止工作階段的列，而其已儲存的對話已在此機器上的另一個執行中 Claude Code 程序中開啟，因此 Claude Code 拒絕啟動將寫入相同逐字稿的第二個程序。您看到的訊息取決於[持有該對話的是什麼](/docs/zh-TW/agent-view#opening-a-session-says-the-conversation-is-already-open)：4839您在 [agent 檢視](/docs/zh-TW/agent-view)中開啟了已停止工作階段的列，而其已儲存的對話已在此機器上的另一個執行中 Claude Code 程序中開啟，因此 Claude Code 拒絕啟動將寫入相同逐字稿的第二個程序。您看到的訊息取決於[持有該對話的是什麼](/docs/zh-TW/agent-view#opening-a-session-says-the-conversation-is-already-open)：

4848* **`running in another terminal`**：終端機持有該對話，例如您使用 `claude --resume` 或 `/resume` 繼續它的終端機。列也會顯示 `Open in a terminal`。4846* **`running in another terminal`**：終端機持有該對話，例如您使用 `claude --resume` 或 `/resume` 繼續它的終端機。列也會顯示 `Open in a terminal`。

4849* **`already open in another running Claude session`**：另一個非互動式 Claude Code 程序持有它，例如相同對話中尚未退出的[背景工作階段](/docs/zh-TW/agent-view#the-supervisor-process)程序。4847* **`already open in another running Claude session`**：另一個非互動式 Claude Code 程序持有它，例如相同對話中尚未退出的[背景工作階段](/docs/zh-TW/agent-view#the-supervisor-process)程序。

4850 4848

4851Claude Code 會儲存您在開啟列時輸入的回覆，並在工作階段下次啟動時將其作為工作階段的下一個提示詞傳送。

~~4852~~

4853**該怎麼做：**4849**該怎麼做：**

4854 4850

4855* 在開啟該對話的程序中繼續對話，或退出該程序並再次開啟列4851* 在開啟該對話的程序中繼續對話，或退出該程序並再次開啟列

4857在 v2.1.248 之前，只有 `already open in another running Claude session` 拒絕存在：在終端機中繼續的對話不計為開啟，開啟列會啟動寫入相同對話的第二個 Claude Code 程序。4853在 v2.1.248 之前，只有 `already open in another running Claude session` 拒絕存在：在終端機中繼續的對話不計為開啟，開啟列會啟動寫入相同對話的第二個 Claude Code 程序。

4858 4854

4859<h3 id="this-sessions-saved-conversation-is-no-longer-on-disk">4855<h3 id="this-sessions-saved-conversation-is-no-longer-on-disk">

4860 此工作階段的已儲存對話不再在磁碟上4856 This session's saved conversation is no longer on disk

4861</h3>4857</h3>

4862 4858

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

4904在 v2.1.248 之前，在主簽出中簽出的預設分支不計算在內：您已經合併到那裡的分支仍然會觸發此拒絕，直到其提交到達遠端。4900在 v2.1.248 之前，在主簽出中簽出的預設分支不計算在內：您已經合併到那裡的分支仍然會觸發此拒絕，直到其提交到達遠端。

4905 4901

4906<h3 id="terminal-host-process-died">4902<h3 id="terminal-host-process-died">

4907 終端機主機程序已死亡4903 Terminal host process died

4908</h3>4904</h3>

4909 4905

4910每個[背景工作階段的](/docs/zh-TW/agent-view)終端機在背景服務下的主機程序中執行，該程序在服務仍保持其連線時死亡，因此無法連線到工作階段。4906每個[背景工作階段的](/docs/zh-TW/agent-view)終端機在背景服務下的主機程序中執行，該程序在服務仍保持其連線時死亡，因此無法連線到工作階段。

4934在 v2.1.247 之前，已死亡的主機程序可能通過背景服務執行的每個活躍性檢查，因此開啟工作階段會無限期地顯示 `opening… · esc to cancel`，而 `claude attach <id>` 會等待而不報告錯誤。4930在 v2.1.247 之前，已死亡的主機程序可能通過背景服務執行的每個活躍性檢查，因此開啟工作階段會無限期地顯示 `opening… · esc to cancel`，而 `claude attach <id>` 會等待而不報告錯誤。

4935 4931

4936<h3 id="session-isnt-responding">4932<h3 id="session-isnt-responding">

4937 工作階段沒有回應4933 Session isn't responding

4938</h3>4934</h3>

4939 4935

4940您開啟了[背景工作階段](/docs/zh-TW/agent-view)，背景服務接受了開啟，但約十秒內沒有輸出到達，因此 Claude Code 判定中繼工作階段終端機的程序無法傳遞輸出，並結束嘗試而不是繼續等待。4936您開啟了[背景工作階段](/docs/zh-TW/agent-view)，背景服務接受了開啟，但約十秒內沒有輸出到達，因此 Claude Code 判定中繼工作階段終端機的程序無法傳遞輸出，並結束嘗試而不是繼續等待。

4960* 對於 shell 命令列，在 agent 檢視中按 `Ctrl+X` 或執行 `claude stop <id>` 停止它；再次分派命令以重新執行它4956* 對於 shell 命令列，在 agent 檢視中按 `Ctrl+X` 或執行 `claude stop <id>` 停止它；再次分派命令以重新執行它

4961 4957

4962<h3 id="session-was-stopped-while-the-respawn-was-in-flight">4958<h3 id="session-was-stopped-while-the-respawn-was-in-flight">

4963 工作階段在重新生成進行中時被停止4959 Session was stopped while the respawn was in flight

4964</h3>4960</h3>

4965 4961

4966您開啟了[背景工作階段](/docs/zh-TW/agent-view)，其程序未執行，而當 Claude Code 重新啟動它時，另一個 Claude Code 程序停止了它，例如在另一個終端機中的 `claude stop`。Claude Code 保持工作階段停止：4962您開啟了[背景工作階段](/docs/zh-TW/agent-view)，其程序未執行，而當 Claude Code 重新啟動它時，另一個 Claude Code 程序停止了它，例如在另一個終端機中的 `claude stop`。Claude Code 保持工作階段停止：

feature-availability.md +3 −4

Details

92 <td>✗</td>92 <td>✗</td>

93 <td>✓</td>93 <td>✓</td>

94 <td>請參閱備註 <sup><a href="#fn1">1</a></sup></td>94 <td>請參閱備註 <sup><a href="#fn1">1</a></sup></td>

~~95 <td>✓ ([部署於 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options))</td>~~95 <td>✓</td>

96 </tr>96 </tr>

97 97

98 <tr>98 <tr>

200 <tr>200 <tr>

201 <td>[伺服器管理的設定](/docs/zh-TW/server-managed-settings)</td>201 <td>[伺服器管理的設定](/docs/zh-TW/server-managed-settings)</td>

202 <td>✓ (Team 和 Enterprise)</td>202 <td>✓ (Team 和 Enterprise)</td>

203 <td>✓ (Team 和 Enterprise)</td>203 <td>請參閱[平台可用性](/docs/zh-TW/server-managed-settings#platform-availability)</td>

204 <td>✗</td>204 <td>✗</td>

205 <td>✗</td>205 <td>✗</td>

206 <td>✗</td>206 <td>✗</td>

283 **部分支援：**283 **部分支援：**

284 284

285 * [Desktop](/docs/zh-TW/desktop)：僅透過 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)285 * [Desktop](/docs/zh-TW/desktop)：僅透過 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

286 * [Web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)：[部署於 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)僅限

287 * [Auto mode](/docs/zh-TW/auto-mode-config)：僅限 Sonnet 5 或更新版本、Opus 4.7 或更新版本、Haiku 5.5，以及 Fable 模型286 * [Auto mode](/docs/zh-TW/auto-mode-config)：僅限 Sonnet 5 或更新版本、Opus 4.7 或更新版本、Haiku 5.5，以及 Fable 模型

288 * [Cross-session messaging](/docs/zh-TW/cross-session-messaging)：僅限此機器上的您的工作階段 <sup><a href="#fn5">5</a></sup>287 * [Cross-session messaging](/docs/zh-TW/cross-session-messaging)：僅限此機器上的您的工作階段 <sup><a href="#fn5">5</a></sup>

289 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 Azure 協議約束288 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 Azure 協議約束

294 <Tab title="Anthropic Console">293 <Tab title="Anthropic Console">

295 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)。294 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)。

296 295

297 [按提供者變化的 CLI 功能](#cli-capabilities-that-vary-by-provider)中的所有功能都可用，除了 [fast mode](/docs/zh-TW/fast-mode) 需要[已佈建的存取](/docs/zh-TW/fast-mode#enable-fast-mode-for-your-organization)。當您的 API 金鑰屬於 Team 或 Enterprise 組織時，[伺服器管理的設定](/docs/zh-TW/server-managed-settings)也可用。296 [按提供者變化的 CLI 功能](#cli-capabilities-that-vary-by-provider)中的所有功能都可用，除了 [fast mode](/docs/zh-TW/fast-mode) 需要[已佈建的存取](/docs/zh-TW/fast-mode#enable-fast-mode-for-your-organization)。您在 claude.ai Team 或 Enterprise 組織中設定的[伺服器管理的設定](/docs/zh-TW/server-managed-settings)不會套用到使用 Console API 金鑰進行身分驗證的工作階段。如需如何涵蓋這些工作階段，請參閱[平台可用性](/docs/zh-TW/server-managed-settings#platform-availability)。

298 </Tab>297 </Tab>

299</Tabs>298</Tabs>

300 299

github-actions.md +2 −0

Details

140| 權限 | 存取 |140| 權限 | 存取 |

141| - | - |141| - | - |

142| Actions | 讀取和寫入 |142| Actions | 讀取和寫入 |

143| Administration | 讀取 |

143| Checks | 讀取和寫入 |144| Checks | 讀取和寫入 |

144| Contents | 讀取和寫入 |145| Contents | 讀取和寫入 |

145| Discussions | 讀取和寫入 |146| Discussions | 讀取和寫入 |

146| Issues | 讀取和寫入 |147| Issues | 讀取和寫入 |

147| Members | 讀取 |148| Members | 讀取 |

149| Merge queues | 讀取 |

148| Metadata | 讀取 |150| Metadata | 讀取 |

149| Pull requests | 讀取和寫入 |151| Pull requests | 讀取和寫入 |

150| Repository hooks | 讀取和寫入 |152| Repository hooks | 讀取和寫入 |

glossary.md +1 −1

Details

294 Output style294 Output style

295</h3>295</h3>

296 296

297一個設定，改變 Claude Code 提供給 Claude 的指示，以設定回應行為、語氣或格式。與 [CLAUDE.md](#claude-md) 不同，後者在 Claude Code 的預設指示旁邊新增專案內容，自訂輸出樣式可以取代預設軟體工程指示。297一個設定，改變 Claude Code 提供給 Claude 的指示，以設定回應行為、語氣或格式。與 [CLAUDE.md](#claude-md) 不同，後者在 Claude Code 的預設指示旁邊新增專案內容，自訂輸出風格則會加入自己的指示，並且可以省略預設軟體工程指示。

298 298

299了解更多：[Output styles](/docs/zh-TW/output-styles)299了解更多：[Output styles](/docs/zh-TW/output-styles)

300 300

google-vertex-ai.md +4 −2

Details

342 1M token context window342 1M token context window

343</h2>343</h2>

344 344

345Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Google Cloud 的 Agent Platform 上支援 [1M token context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#context-window-sizes-by-model)。Sonnet 5 始終以 1M 視窗執行，沒有 `[1m]` 變體可選擇。對於其他模型，Claude Code 會在您選擇 1M 模型變體時自動啟用擴展 context window。345Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本，在 Google Cloud 的 Agent Platform 上預設以 [1M token 上下文視窗](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#context-window-sizes-by-model)執行，無需 `[1m]` 後綴。若要改為維持 200K 視窗，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/model-config#turn-off-1m-context)。

346 346

347[設定精靈](#sign-in-with-agent-platform)在固定模型時提供 1M context 選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。如需詳細資訊，請參閱[為第三方部署固定模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)，包括如何在不變更固定設定的情況下使用 1M 視窗。347Opus 4.6 和 Sonnet 4.6 在您選擇其 `[1m]` 變體時可使用 1M 視窗。[設定精靈](#sign-in-with-agent-platform)在固定模型時提供 1M context 選項。若要改為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。如需詳細資訊，請參閱[為第三方部署固定模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)，包括如何在不變更固定設定的情況下使用 1M 視窗。

348

349在 v2.1.287 之前，Fable 模型以及 Opus 4.7 及更新版本在 Google Cloud 的 Agent Platform 上預設以 200K 視窗執行，並透過 `[1m]` 後綴使用 1M 視窗。

348 350

349<h2 id="troubleshooting">351<h2 id="troubleshooting">

350 故障排除352 故障排除

headless.md +9 −4

Details

78 退出時的背景任務78 退出時的背景任務

79</h3>79</h3>

80 80

81如果 Claude 在 `claude -p` 執行期間啟動 [背景 Bash 任務](/docs/zh-TW/tools-reference#bash-tool-behavior)（例如開發伺服器或監視組建），該 shell 會在 Claude 傳回其最終結果且 stdin 已關閉後約五秒鐘終止。寬限期允許在結果之後立即完成的任務仍然傳遞其輸出。81在 Claude 完成其回合且 stdin 已關閉後，`claude -p` 執行可能會保持開啟，以等待 Claude 啟動的背景工作。

82 82

~~83如果 Claude 啟動背景 [subagent](/docs/zh-TW/sub-agents) 或工作流程，`claude -p` 會改為保持開啟，直到該工作完成，因為其結果是最終輸出的一部分。~~83除非主對話啟動的背景命令仍在執行，否則預設情況下，Claude Code 會在連續閒置等待 10 分鐘後停止仍在執行的任何內容，並捨棄其部分結果。要變更 10 分鐘上限，請設定 [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/docs/zh-TW/env-vars)，或將其設定為 `0` 以不設上限地等待。

84 84

85預設情況下，等待在 10 分鐘的連續空閒等待後結束，因此卡住的 subagent 或工作流程無法無限期地保持程序開啟。此時 Claude Code 會停止仍在執行的任何內容並捨棄其部分結果。要變更限制，請設定 [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/docs/zh-TW/env-vars)，或將其設定為 `0` 以無限期等待。85執行會等待背景工作，例如背景命令、subagent 和工作流程、Monitor 監視，以及待處理的 `/loop` 喚醒：

86 86

87如果 Claude 在 `claude -p` 執行期間啟動 [Monitor](/docs/zh-TW/tools-reference#monitor-tool) 監視，Claude Code 會等待監視直到其逾時或十分鐘上限結束等待，以先發生者為準。在等待期間，Claude 會持續回應監視報告的內容。預設情況下，監視在 Claude 啟動後五分鐘逾時。87* **[背景命令](/docs/zh-TW/tools-reference#background-commands)**：對於主對話啟動的命令，例如開發伺服器或監視建置，執行會等待直到該命令退出或達到其 [時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)。接著 Claude 會依據結果再進行一個回合，而該回合的結果會成為執行的最後一個結果，也就是 `text` 和 `json` 輸出所列印的結果。在命令執行期間，10 分鐘上限不會結束等待。

88* **背景 [subagent](/docs/zh-TW/sub-agents) 和工作流程**：執行會保持開啟，直到該工作完成，因為其結果是最終輸出的一部分。

89* **[Monitor](/docs/zh-TW/tools-reference#monitor-tool) 監視**：執行會等待直到監視逾時或 10 分鐘上限結束等待，以先發生者為準。在等待期間，Claude 會持續回應監視報告的內容。預設情況下，監視在 Claude 啟動後五分鐘逾時。

90* **待處理的喚醒**：在以文字傳遞提示詞（而非使用 `--input-format stream-json`）的執行中，當 Claude 已排定 [自訂節奏的 `/loop` 喚醒](/docs/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 時，執行會等待每次喚醒觸發並執行其迭代，直到 [迴圈結束](/docs/zh-TW/scheduled-tasks#stop-a-loop)，即使超過 10 分鐘上限也是如此。

92如果執行達到其 [`--max-budget-usd`](/docs/zh-TW/cli-reference#cli-flags) 上限，Claude Code 會停止剩餘的背景工作，而不是繼續等待。

88 93

89<h3 id="stop-a-run-with-sigterm">94<h3 id="stop-a-run-with-sigterm">

90 使用 SIGTERM 停止執行95 使用 SIGTERM 停止執行

hooks.md +2 −0

Details

3861 3861

3862將 `type` 設定為 `"prompt"` 並提供 `prompt` 字串而不是 `command`。使用 `$ARGUMENTS` 佔位符將 hook 的 JSON 輸入資料注入到您的提示文字中。3862將 `type` 設定為 `"prompt"` 並提供 `prompt` 字串而不是 `command`。使用 `$ARGUMENTS` 佔位符將 hook 的 JSON 輸入資料注入到您的提示文字中。

3863 3863

3864在提示詞 hook 或 [agent hook](#agent-based-hooks) 中，您可以將 `prompt` 寫成關於要阻止或允許什麼的規則，例如「Block any Bash command that reads `.env` files」，或寫成必須成立的條件，例如「All unit tests pass」。

3865

3864此 `Stop` hook 詢問 LLM 在允許 Claude 完成之前是否應該評估所有任務是否完成：3866此 `Stop` hook 詢問 LLM 在允許 Claude 完成之前是否應該評估所有任務是否完成：

3865 3867

3866```json theme={null}3868```json theme={null}

keybindings.md +49 −0

Details

68| `EffortSlider` | 由 `/effort` 開啟的努力滑桿 |68| `EffortSlider` | 由 `/effort` 開啟的努力滑桿 |

69| `Select` | 通用選取/清單元件 |69| `Select` | 通用選取/清單元件 |

70| `Plugin` | Plugin 對話框 (瀏覽、探索、管理) |70| `Plugin` | Plugin 對話框 (瀏覽、探索、管理) |

71| `AbovePrompt` | [提示詞上方的區域](#above-prompt-actions)或其中的按鈕擁有鍵盤焦點 |

72| `AbovePromptInput` | 提示詞上方區域或 mod 窗格中的輸入欄位擁有鍵盤焦點 |

73| `AbovePromptSelect` | 提示詞上方區域或 mod 窗格中的選取元件擁有鍵盤焦點 |

71| `Pane` | 由 [mod](/docs/zh-TW/plugins/mods/interface#know-which-keys-your-mod-can-receive) 繪製的窗格擁有鍵盤焦點 |74| `Pane` | 由 [mod](/docs/zh-TW/plugins/mods/interface#know-which-keys-your-mod-can-receive) 繪製的窗格擁有鍵盤焦點 |

72| `PaneField` | mod 窗格中的輸入欄位或選取元件擁有鍵盤焦點 |75| `PaneField` | mod 窗格中的輸入欄位或選取元件擁有鍵盤焦點 |

73| `Agents` | [Agent 檢視](/docs/zh-TW/agent-view) (`claude agents`) |76| `Agents` | [Agent 檢視](/docs/zh-TW/agent-view) (`claude agents`) |

442| `plugin:install` | I | 安裝選定的外掛程式 |445| `plugin:install` | I | 安裝選定的外掛程式 |

443| `plugin:favorite` | F | 將選定的外掛程式設為最愛，使其在已安裝標籤附近排序 |446| `plugin:favorite` | F | 將選定的外掛程式設為最愛，使其在已安裝標籤附近排序 |

444 447

448<h3 id="above-prompt-actions">

449 提示詞上方動作

450</h3>

451

452用於提示詞上方區帶的動作，這是 [mod](/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) 繪製按鈕、輸入欄位和選單的共用區域。`abovePrompt:toggle` 和 `abovePrompt:focus` 適用於 `Chat` 上下文。其他動作適用於區帶或窗格中具有鍵盤焦點之元素的 [上下文](#contexts)。

453

454| 動作 | 預設 | 說明 |

455| :- | :- | :- |

456| `abovePrompt:toggle` | Ctrl+X Ctrl+A | 將區帶摺疊為單列提示，或再次展開 |

457| `abovePrompt:focus` | Ctrl+X Tab | 將鍵盤焦點移入區帶，然後移至每個開啟的 [窗格](#pane-actions)，並從最後一個窗格返回提示詞 |

458| `abovePrompt:next` | Tab | 聚焦下一個控制項 |

459| `abovePrompt:previous` | Shift+Tab | 聚焦上一個控制項 |

460| `abovePrompt:press` | Enter | 按下聚焦的按鈕、提交聚焦的輸入欄位，或在選單中選擇突出顯示的選項 |

461| `abovePrompt:leave` | Escape | 將鍵盤焦點返回提示詞 |

462| `abovePrompt:highlightNext` | Down | 在聚焦的選單中突出顯示下一個選項 |

463| `abovePrompt:highlightPrevious` | Up | 在聚焦的選單中突出顯示上一個選項 |

464

465有兩個上下文預設會將更多按鍵綁定到這些動作：

466

467* **`AbovePrompt`**：Right 和 Left 也會執行 `abovePrompt:next` 和 `abovePrompt:previous`，Space 也會執行 `abovePrompt:press`

468* **`AbovePromptInput`**：Down 和 Up 也會執行 `abovePrompt:next` 和 `abovePrompt:previous`

469

470`AbovePrompt` 上下文也將 Up、Down、PageUp、PageDown、Home 和 End 綁定到 [窗格捲動動作](#pane-actions) `pane:scrollUp` 至 `pane:bottom`，因此若要為區帶變更其中一個按鍵，請在 `AbovePrompt` 區塊中綁定該捲動動作。

471

472<h3 id="pane-actions">

473 窗格動作

474</h3>

475

476用於由 [mod](/docs/zh-TW/plugins/mods/interface#know-which-keys-your-mod-can-receive) 繪製之窗格的動作。捲動、調整大小和關閉動作適用於 `Pane` [上下文](#contexts)。`pane:close` 也適用於 `PaneField` 上下文，因此在窗格的某個欄位有焦點時也能運作。當開啟多個窗格時，`pane:next` 和 `pane:previous` 適用於 `Global` 上下文。

477

478| 動作 | 預設 | 說明 |

479| :- | :- | :- |

480| `pane:scrollUp` | Up | 當窗格的列數超過可顯示範圍時向上捲動窗格 |

481| `pane:scrollDown` | Down | 當窗格的列數超過可顯示範圍時向下捲動窗格 |

482| `pane:pageUp` | PageUp | 將窗格向上捲動一頁 |

483| `pane:pageDown` | PageDown | 將窗格向下捲動一頁 |

484| `pane:top` | Home | 跳到窗格頂部 |

485| `pane:bottom` | End | 跳到窗格底部 |

486| `pane:grow` | Ctrl+X Left, Ctrl+X Up | 給予窗格更多空間：位於逐字稿旁時增加寬度，位於提示詞上方時增加高度 |

487| `pane:shrink` | Ctrl+X Right, Ctrl+X Down | 給予窗格較少空間：位於逐字稿旁時減少寬度，位於提示詞上方時減少高度 |

488| `pane:close` | Ctrl+X X | 關閉窗格 |

489| `pane:next` | (未綁定) | 顯示下一個開啟的窗格 |

490| `pane:previous` | (未綁定) | 顯示上一個開啟的窗格 |

491

492`Pane` 上下文也將 Tab、Shift+Tab、Enter 和 Escape 綁定到與區帶相同的 [提示詞上方動作](#above-prompt-actions)，而窗格的輸入欄位和選單使用 `AbovePromptInput` 和 `AbovePromptSelect` 上下文。[鍵盤焦點與快速鍵](/docs/zh-TW/plugins/mods/interface#know-which-keys-your-mod-can-receive) 列出了每個按鍵在窗格中的作用。

493

445<h3 id="settings-actions">494<h3 id="settings-actions">

446 設定動作495 設定動作

447</h3>496</h3>

llm-gateway-protocol.md +1 −1

Details

200 200

201| 標頭 | 應返回的內容及原因 |201| 標頭 | 應返回的內容及原因 |

202| :- | :- |202| :- | :- |

203| `content-type` | 在串流的 Anthropic Messages 格式回應上返回 `text/event-stream`，在 Amazon Bedrock 格式回應上返回 `application/vnd.amazon.eventstream`（未修改），其中[不同的類型會導致請求失敗](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。[串流](#streaming)列出哪些連線在這些串流上執行停滯偵測 |203| `content-type` | 在串流的 Anthropic Messages 格式回應上返回 `text/event-stream`，在 Amazon Bedrock 格式回應上返回 `application/vnd.amazon.eventstream`（未修改），其中[不同的類型會導致請求失敗](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy) |

204| `retry-after` | 返回整數秒數而非 HTTP 日期。Claude Code 在下一次[自動重試](/docs/zh-TW/errors#automatic-retries)之前至少等待該時間長度，在 [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-TW/env-vars) 工作階段外，超過 60 的值會停止重試並立即顯示錯誤 |204| `retry-after` | 返回整數秒數而非 HTTP 日期。Claude Code 在下一次[自動重試](/docs/zh-TW/errors#automatic-retries)之前至少等待該時間長度，在 [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-TW/env-vars) 工作階段外，超過 60 的值會停止重試並立即顯示錯誤 |

205| `x-should-retry` | 未修改地傳遞上游的值。Claude Code 在決定是否重試失敗的請求時將此標頭讀取為一個輸入：`true` 標記回應為可重試，`false` 標記為不可重試。如需重試計數、退避和 Claude Code 重試的失敗，請參閱[自動重試](/docs/zh-TW/errors#automatic-retries) |205| `x-should-retry` | 未修改地傳遞上游的值。Claude Code 在決定是否重試失敗的請求時將此標頭讀取為一個輸入：`true` 標記回應為可重試，`false` 標記為不可重試。如需重試計數、退避和 Claude Code 重試的失敗，請參閱[自動重試](/docs/zh-TW/errors#automatic-retries) |

206| `anthropic-ratelimit-unified-*` | 在每個回應上未修改地轉發上游的值。Claude Code 在成功回應上讀取它們以向使用 claude.ai 登入的開發人員顯示針對計畫限制的使用量，在 `429` 上讀取以區分計畫限制或支出上限與暫時性節流；請參閱[使用量限制](/docs/zh-TW/errors#usage-limits) |206| `anthropic-ratelimit-unified-*` | 在每個回應上未修改地轉發上游的值。Claude Code 在成功回應上讀取它們以向使用 claude.ai 登入的開發人員顯示針對計畫限制的使用量，在 `429` 上讀取以區分計畫限制或支出上限與暫時性節流；請參閱[使用量限制](/docs/zh-TW/errors#usage-limits) |

managed-settings.md +1 −1

Details

154 154

155Claude Code 按此順序檢查來源，最高優先順序優先：155Claude Code 按此順序檢查來源，最高優先順序優先：

156 156

1571. 遠端設定，從 claude.ai 作為 [伺服器管理的設定](/docs/zh-TW/server-managed-settings) 或通過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 提供。Claude Code 僅在工作階段使用 [符合條件的登入或金鑰](/docs/zh-TW/server-managed-settings#platform-availability) 直接向 Anthropic 的 API 進行身份驗證，或使用 `/login` 登入閘道時才會擷取此來源。在其他提供者上，或當 `ANTHROPIC_BASE_URL` 指向 Anthropic API 以外的地方時，它從下一個來源開始1571. 遠端設定，從 claude.ai 作為 [伺服器管理的設定](/docs/zh-TW/server-managed-settings) 或通過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 提供。Claude Code 僅在工作階段使用 [符合條件的憑證](/docs/zh-TW/server-managed-settings#platform-availability) 直接向 Anthropic 的 API 進行身份驗證，或使用 `/login` 登入閘道時才會擷取此來源。在其他提供者上，或當 `ANTHROPIC_BASE_URL` 指向 Anthropic API 以外的地方時，它從下一個來源開始

1582. MDM 或作業系統層級原則：macOS plist 或 HKLM 登錄金鑰1582. MDM 或作業系統層級原則：macOS plist 或 HKLM 登錄金鑰

1593. 受管設定檔，`managed-settings.d/*.json` 和 `managed-settings.json` 合併在一起1593. 受管設定檔，`managed-settings.d/*.json` 和 `managed-settings.json` 合併在一起

1604. HKCU 登錄，在 Windows 上，以及在 WSL 上，一旦 HKLM 登錄或 Windows 受管設定檔開啟 [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings) 並且 HKCU 值也設定它。Claude Code 僅在 [其上方沒有存在的管理員文件](#present-admin-documents) 且沒有 [主機提供的父設定](#let-an-embedding-host-add-policy) 提供限制性金鑰時才讀取它1604. HKCU 登錄，在 Windows 上，以及在 WSL 上，一旦 HKLM 登錄或 Windows 受管設定檔開啟 [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings) 並且 HKCU 值也設定它。Claude Code 僅在 [其上方沒有存在的管理員文件](#present-admin-documents) 且沒有 [主機提供的父設定](#let-an-embedding-host-add-policy) 提供限制性金鑰時才讀取它

mcp.md +8 −15

Details

142```142```

143 143

144<Note>144<Note>

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

~~146~~

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

148 146

149 例如：147 例如：

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

276* `⊘ Disabled for this project (re-enable via /mcp)`：專案的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的伺服器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都顯示它。從 `/mcp` 面板重新開啟伺服器。274* `⊘ Disabled for this project (re-enable via /mcp)`：專案的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的伺服器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都顯示它。從 `/mcp` 面板重新開啟伺服器。

277 275

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

~~279~~

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

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

282</h4>278</h4>

371 367

372在 v2 上，Claude Code 也：368在 v2 上，Claude Code 也：

373 369

374* 詢問 HTTP 伺服器他們是否支援較新的修訂，並與支援的伺服器一起使用它。在擷取功能旗標的工作階段中，它也會詢問 claude.ai 連接器伺服器，並且隨著 Anthropic 推出該變更，在 Claude Code v2.1.285 或更新版本上它會詢問 stdio 伺服器。若要讓它在每個工作階段中詢問連接器和 stdio 伺服器，請設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto`。它連接到每個其他伺服器，如 v1 所做的那樣。370* 詢問 HTTP 和 stdio 伺服器是否支援較新的修訂，並與支援的伺服器一起使用它。在擷取功能旗標的工作階段中，它也會詢問 claude.ai 連接器伺服器。它連接到每個其他伺服器，如 v1 所做的那樣。

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

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

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

458 454

459在 [v2 執行時](#mcp-client-runtimes)上，協商 MCP 協議修訂 2026-07-28 的頻道伺服器無法傳遞頻道訊息，因此 Claude Code 不會將其註冊為頻道。不支援該修訂的頻道伺服器會在較早的握手上連接，並如以往一樣註冊。455在 [v2 執行時](#mcp-client-runtimes)上，協商 MCP 協議修訂 2026-07-28 的頻道伺服器無法傳遞頻道訊息，因此 Claude Code 不會將其註冊為頻道。不支援該修訂的頻道伺服器會在較早的握手上連接，並如以往一樣註冊。

460 456

461當您設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto` 時，Claude Code 會向 stdio 伺服器詢問該修訂。Anthropic 也正在 Claude Code [擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中，針對 Claude Code v2.1.285 或更新版本預設開啟此行為。若要將 stdio 頻道伺服器保持在較早的握手上，請設定 `MCP_PROTOCOL_NEGOTIATION` 為 `legacy`，這會將每個伺服器都保持在較早的握手上。457Claude Code 預設會向 stdio 伺服器詢問該修訂。若要將 stdio 頻道伺服器保持在較早的握手上，請設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `legacy`，這會將每個伺服器都保持在較早的握手上。

462 458

463<Tip>459<Tip>

464 提示：460 提示：

1400 MCP 輸出限制和警告1396 MCP 輸出限制和警告

1401</h2>1397</h2>

1402 1398

1403當 MCP 工具產生大量輸出時，Claude Code 會幫助管理權杖使用量，以防止淹沒您的對話上下文：1399當 MCP 工具產生大量輸出時，Claude Code 會幫助管理 token 使用量，以防止淹沒您的對話上下文：

1404 1400

1405* **輸出警告閾值**：當任何 MCP 工具輸出超過 10,000 個權杖時，Claude Code 會顯示警告1401* **輸出警告閾值**：當任何 MCP 工具輸出超過 10,000 個 token 時，Claude Code 會顯示警告

1406* **可配置的限制**：您可以使用 `MAX_MCP_OUTPUT_TOKENS` 環境變數調整允許的最大 MCP 輸出權杖數1402* **可設定的限制**：您可以使用 `MAX_MCP_OUTPUT_TOKENS` 環境變數調整允許的最大 MCP 輸出 token 數

1407* **預設限制**：預設最大值為 25,000 個權杖1403* **預設限制**：預設最大值為 25,000 個 token

1408* **範圍**：環境變數適用於未聲明自己限制的工具。設定 [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) 的工具會針對文字內容使用該值，無論 `MAX_MCP_OUTPUT_TOKENS` 設定為何。傳回影像資料的工具仍受 `MAX_MCP_OUTPUT_TOKENS` 限制1404* **範圍**：環境變數適用於未聲明自己限制的工具。設定 [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) 的工具會針對文字內容使用該值，無論 `MAX_MCP_OUTPUT_TOKENS` 設定為何。傳回影像資料的工具仍受 `MAX_MCP_OUTPUT_TOKENS` 限制

1409* **超過限制**：當沒有影像內容的成功結果超過 token 限制時，Claude Code 會將其儲存到檔案，並在對話中用命名檔案路徑的訊息取代它，以便 Claude 在需要內容時讀取該檔案。該檔案位於 [`~/.claude/projects/`](/docs/zh-TW/claude-directory#cleaned-up-automatically) 下的工作階段 `tool-results` 目錄中。1405* **超過限制**：當沒有影像內容的成功結果超過 token 限制時，Claude Code 會將其儲存到檔案，並在對話中用命名檔案路徑的訊息取代它，以便 Claude 在需要內容時讀取該檔案。該檔案位於 [`~/.claude/projects/`](/docs/zh-TW/claude-directory#cleaned-up-automatically) 下的工作階段 `tool-results` 目錄中。

1406* **來自 HTTP 和 SSE 伺服器的回應大小**：一旦單一 JSON 回應主體或事件串流中的單一事件在解壓縮後超過 16 MB，Claude Code 就會停止讀取來自 [HTTP](#option-1-add-a-remote-http-server) 或 [SSE](#option-2-add-a-remote-sse-server) 伺服器的回應。該回應所對應的請求會失敗。如果您負責維護該伺服器，請減少每個回應傳回的資料量以維持在限制之內，例如將結果分頁

1410 1407

1411Claude Code 已[移至背景任務](#automatic-backgrounding-of-long-tool-calls)的呼叫會透過任務通知回報其結果。對於在前景完成的呼叫，另有兩項限制適用：1408Claude Code 已[移至背景任務](#automatic-backgrounding-of-long-tool-calls)的呼叫會透過任務通知回報其結果。對於在前景完成的呼叫，另有兩項限制適用：

1412 1409

1438}1435}

1439```1436```

1440 1437

1441該註解對文字內容獨立於 `MAX_MCP_OUTPUT_TOKENS` 應用，因此使用者不需要為聲明它的工具提高環境變數。傳回影像資料的工具仍受權杖限制。1438該註解對文字內容獨立於 `MAX_MCP_OUTPUT_TOKENS` 應用，因此使用者不需要為聲明它的工具提高環境變數。傳回影像資料的工具仍受 token 限制。

~~1442~~

1443<Warning>

1444 如果您經常遇到特定 MCP 伺服器的輸出警告，而您無法控制這些伺服器，請考慮增加 `MAX_MCP_OUTPUT_TOKENS` 限制。您也可以要求伺服器作者新增 `anthropic/maxResultSizeChars` 註解或對其回應進行分頁。該註解對傳回影像內容的工具無效；對於這些工具，提高 `MAX_MCP_OUTPUT_TOKENS` 是唯一的選項。

1445</Warning>

1446 1439

1447<h3 id="images-in-tool-results">1440<h3 id="images-in-tool-results">

1448 工具結果中的影像1441 工具結果中的影像

memory.md +5 −3

Details

161 161

162所有發現的檔案都會串聯到背景中，而不是相互覆寫。在目錄樹中，內容從檔案系統根目錄向下排序到您的工作目錄。對於 `foo/bar/` 範例，`foo/CLAUDE.md` 在背景中出現在 `foo/bar/CLAUDE.md` 之前，因此更接近您啟動 Claude 的位置的指令最後讀取。在每個目錄中，`CLAUDE.local.md` 附加在 `CLAUDE.md` 之後，因此您的個人筆記是 Claude 在該級別讀取的最後一件事。162所有發現的檔案都會串聯到背景中，而不是相互覆寫。在目錄樹中，內容從檔案系統根目錄向下排序到您的工作目錄。對於 `foo/bar/` 範例，`foo/CLAUDE.md` 在背景中出現在 `foo/bar/CLAUDE.md` 之前，因此更接近您啟動 Claude 的位置的指令最後讀取。在每個目錄中，`CLAUDE.local.md` 附加在 `CLAUDE.md` 之後，因此您的個人筆記是 Claude 在該級別讀取的最後一件事。

163 163

164Claude 也會發現您目前工作目錄下子目錄中的 `CLAUDE.md` 和 `CLAUDE.local.md` 檔案。它們不是在啟動時載入，而是在 Claude 對這些子目錄中的檔案使用 [Read](/docs/zh-TW/tools-reference#read-tool-behavior)、[Write](/docs/zh-TW/tools-reference#write-tool-behavior) 或 [Edit](/docs/zh-TW/tools-reference#edit-tool-behavior) 工具時，由 Claude Code 將其納入。如果 Claude 已對子目錄的 `CLAUDE.md` 本身使用過其中一個工具，該檔案就不會以這種方式載入，因為 Claude Code 將其視為已在對話中。關於 `.claude/worktrees/` 下 worktree 中的檔案，請參閱 [使用 worktree 隔離 subagent](/docs/zh-TW/worktrees#isolate-subagents-with-worktrees)。164Claude 也會發現您目前工作目錄下子目錄中的 `CLAUDE.md` 和 `CLAUDE.local.md` 檔案。它們不是在啟動時載入，而是在 Claude 讀取、寫入或編輯該子目錄中的另一個檔案時，由 Claude Code 逐一載入。讀取包括使用 [算作讀取](/docs/zh-TW/tools-reference#edit-tool-behavior) 的 Bash 命令檢視檔案，例如對單一檔案執行 `cat` 或 `head`。關於 `.claude/worktrees/` 下 worktree 中的檔案，請參閱 [使用 worktree 隔離 subagent](/docs/zh-TW/worktrees#isolate-subagents-with-worktrees)。

165 165

166如果您在大型 monorepo 中工作，其中其他團隊的 CLAUDE.md 檔案被拾取，請使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳過它們。有關根目錄和每個目錄 CLAUDE.md 檔案和規則的完整配置，請參閱 [Monorepos 和大型儲存庫](/docs/zh-TW/large-codebases)。166如果您在大型 monorepo 中工作，其中其他團隊的 CLAUDE.md 檔案被拾取，請使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳過它們。有關根目錄和每個目錄 CLAUDE.md 檔案和規則的完整配置，請參閱 [Monorepos 和大型儲存庫](/docs/zh-TW/large-codebases)。

167 167

232- Include OpenAPI documentation comments232- Include OpenAPI documentation comments

233```233```

234 234

235沒有 `paths` 欄位的規則無條件載入並適用於所有檔案。路徑範圍規則在 Claude 對與模式匹配的檔案使用 Read、Write 或 Edit 工具時觸發，而不是在每次工具使用時觸發。當 Claude 透過到專案目錄的符號連結路徑到達檔案時，匹配也有效，例如在符號連結簽出中。235沒有 `paths` 欄位的規則無條件載入並適用於所有檔案。當 Claude 對匹配的檔案使用 Read、Write 或 Edit 工具時，路徑範圍規則就會載入。當 Claude 使用 [算作讀取](/docs/zh-TW/tools-reference#edit-tool-behavior) 的 Bash 命令檢視匹配的檔案時（例如對單一檔案執行 `cat` 或 `head`），該規則也會載入。當 Claude 透過到專案目錄的符號連結路徑到達檔案時，匹配也有效，例如在符號連結簽出中。

236 236

237在 `paths` 欄位中使用 glob 模式以按副檔名、目錄或任何組合匹配檔案：237在 `paths` 欄位中使用 glob 模式以按副檔名、目錄或任何組合匹配檔案：

238 238

278 278

279`.claude/rules/` 目錄支援符號連結，因此您可以維護一組共享規則並將它們連結到多個專案。循環符號連結會被偵測並妥善處理。279`.claude/rules/` 目錄支援符號連結，因此您可以維護一組共享規則並將它們連結到多個專案。循環符號連結會被偵測並妥善處理。

280 280

281Claude Code 將其目標在工作目錄外的符號連結視為 [external import](#import-additional-files)。連結的規則在您核准專案的外部匯入之前不會載入，之後僅載入沒有 [`paths` 欄位](#path-specific-rules) 的規則。Claude Code 僅在專案記憶檔案使用 `@path` 匯入工作目錄外的檔案時要求該核准，而不是僅針對符號連結。若要載入共享規則而不需要該核准，請將它們保留在 [`~/.claude/rules/`](#user-level-rules) 中，其中它們適用於您機器上的每個專案。281Claude Code 將其目標在工作目錄外的符號連結視為 [external import](#import-additional-files)。連結的規則在您核准專案的外部匯入之前不會載入，之後僅載入沒有 [`paths` 欄位](#path-specific-rules) 的規則。

282

283Claude Code 每個專案只會要求一次該核准，方式是在互動式工作階段開始時顯示對話框。該對話框會列出連結的規則檔案，以及任何外部 `@path` 匯入。若要載入共享規則而不需要該核准，請將它們保留在 [`~/.claude/rules/`](#user-level-rules) 中，其中它們適用於您機器上的每個專案。

282 284

283此範例連結共享目錄和個別檔案：285此範例連結共享目錄和個別檔案：

284 286

microsoft-foundry.md +45 −11

Details

116 2) 設定 Azure 憑證116 2) 設定 Azure 憑證

117</h3>117</h3>

118 118

119Claude Code 支援 Microsoft Foundry 的三種驗證方法。選擇最適合您安全性要求的方法。119Claude Code 支援 Microsoft Foundry 的三種驗證方法。選擇最適合您安全性要求的方法：

120 120

121**選項 A：API 金鑰驗證**121* [API 金鑰](#use-an-api-key)：您從 Microsoft Foundry 入口網站複製金鑰，並將其設定為 `ANTHROPIC_FOUNDRY_API_KEY`

122* [Microsoft Entra ID](#use-microsoft-entra-id)：Claude Code 透過 Azure SDK 預設憑證鏈取得 token，例如從 `az login` 工作階段取得，因此不需要儲存 API 金鑰

123* [Bearer 權杖](#use-a-bearer-token)：由另一個程序取得 Microsoft Entra ID 存取權杖，您再透過 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 傳入

124

125<Note>

126 使用 Microsoft Foundry 時，`/logout` 命令無法使用，因為身分驗證是透過 Azure 憑證處理的。

127</Note>

128

129<h4 id="use-an-api-key">

130 使用 API 金鑰

131</h4>

132

133從 Microsoft Foundry 入口網站複製金鑰，然後將其設定為環境變數：

122 134

1231. 在 Microsoft Foundry 入口網站中瀏覽至您的資源1351. 在 Microsoft Foundry 入口網站中瀏覽至您的資源

1242. 前往 **端點和金鑰** 部分1362. 開啟 **端點和金鑰** 部分

1253. 複製 **API 金鑰**1373. 複製 **API 金鑰**

1264. 設定環境變數，將 `your-azure-api-key` 替換為您複製的金鑰：1384. 設定環境變數，將 `your-azure-api-key` 替換為您複製的金鑰：

127 139

129export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key141export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

130```142```

131 143

132**選項 B：Microsoft Entra ID 驗證**144<h4 id="use-microsoft-entra-id">

145 使用 Microsoft Entra ID

146</h4>

133 147

134當未設定 `ANTHROPIC_FOUNDRY_API_KEY` 和 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時，Claude Code 會自動使用 Azure SDK [預設憑證鏈](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)。148請勿設定 `ANTHROPIC_FOUNDRY_API_KEY` 和 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`。Claude Code 接著會使用 Azure SDK [預設憑證鏈](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)。

135這支援多種方法來驗證本機和遠端工作負載。149這支援多種方法來驗證本機和遠端工作負載。

136 150

137在本機環境中，您通常可以使用 Azure CLI：151在本機上，使用 Azure CLI 登入：

138 152

139```bash theme={null}153```bash theme={null}

140az login154az login

141```155```

142 156

143**選項 C：Bearer 權杖驗證**157如需您的身分所需的角色，請參閱 [Azure RBAC 設定](#azure-rbac-configuration)。

158

159<h4 id="use-a-bearer-token">

160 使用 Bearer 權杖

161</h4>

144 162

145Claude Code 在每個請求上將 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 的值作為 `Authorization: Bearer` 標頭傳送。當另一個程序（例如主應用程式或登入指令碼）已為您取得存取權杖時，請使用此選項。需要 Claude Code v2.1.203 或更新版本。163Claude Code 在每個請求上將 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 的值作為 `Authorization: Bearer` 標頭傳送。當另一個程序（例如主應用程式或登入指令碼）已為您取得存取權杖時，請使用此選項。需要 Claude Code v2.1.203 或更新版本。

146 164

152 170

153`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和預設憑證鏈。171`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和預設憑證鏈。

154 172

155<Note>

156 使用 Microsoft Foundry 時，`/logout` 命令無法使用，因為身分驗證是透過 Azure 憑證處理的。

157</Note>

~~158~~

159<h3 id="3-configure-claude-code">173<h3 id="3-configure-claude-code">

160 3. 設定 Claude Code174 3. 設定 Claude Code

161</h3>175</h3>

240 254

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

242 256

257<h2 id="1m-token-context-window">

258 1M token 上下文視窗

259</h2>

260

261在 Microsoft Foundry 上，當 Claude Code 能夠判斷您的部署所提供的模型時，Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本預設會以 [1M token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)執行，無需加上 `[1m]` 後綴。Claude Code 會從模型變數中的部署名稱讀取模型。請以模型 ID 為每個部署命名，例如 `claude-opus-4-8`，或使用 [`modelOverrides`](/docs/zh-TW/model-config#override-model-ids-per-version) 將模型對應到您的部署名稱。對於無法對應到任何模型的部署名稱，Claude Code 會假設為 200K 視窗，除非您[宣告不同的視窗大小](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。

262

263以下 `settings.json` 項目會告知 Claude Code，名為 `team-opus-prod` 的部署提供的是 Opus 4.8：

264

265```json theme={null}

266{

267 "modelOverrides": {

268 "claude-opus-4-8": "team-opus-prod"

269 }

270}

271```

272

273若要改為保留 200K 視窗，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/model-config#turn-off-1m-context)。

274

275當您在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中的部署名稱後方加上 `[1m]` 時，Opus 4.6 與 Sonnet 4.6 即可使用 1M 視窗，詳見[為第三方部署固定模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)的說明。在 v2.1.287 之前，Fable 模型以及 Opus 4.7 及更新版本在 Microsoft Foundry 上同樣需要該後綴，若未加上則預設以 200K 視窗執行。

276

243<h2 id="troubleshooting">277<h2 id="troubleshooting">

244 故障排除278 故障排除

245</h2>279</h2>

model-config.md +51 −41

Details

40| **`opus`** | 使用最新的 Opus 模型處理複雜的推理任務 |40| **`opus`** | 使用最新的 Opus 模型處理複雜的推理任務 |

41| **`haiku`** | 使用快速且高效的 Haiku 模型處理簡單任務 |41| **`haiku`** | 使用快速且高效的 Haiku 模型處理簡單任務 |

42| **`sonnet[1m]`** | 使用具有 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)的 Sonnet 進行長時間工作階段。當 `sonnet` 已解析為原生具備 1M 視窗的 Sonnet 5.5 或 Sonnet 5 時沒有作用 |42| **`sonnet[1m]`** | 使用具有 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)的 Sonnet 進行長時間工作階段。當 `sonnet` 已解析為原生具備 1M 視窗的 Sonnet 5.5 或 Sonnet 5 時沒有作用 |

43| **`opus[1m]`** | 使用具有 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)的 Opus 進行長時間工作階段 |43| **`opus[1m]`** | 使用具有 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)的 Opus 進行長時間工作階段。當 `opus` 已解析為原生具備 1M 視窗的 Opus 4.7 或更新版本時沒有作用 |

44| **`opusplan`** | 特殊模式，在 plan mode 期間使用 `opus`，然後在執行時切換至 `sonnet` |44| **`opusplan`** | 特殊模式，在 plan mode 期間使用 `opus`，然後在執行時切換至 `sonnet` |

45 45

46`opus`、`sonnet` 和 `haiku` 別名在 Anthropic API 上會解析為最新版本，在部分其他供應商上則會解析為較早的版本：46`opus`、`sonnet` 和 `haiku` 別名在 Anthropic API 上會解析為最新版本，在部分其他供應商上則會解析為較早的版本：

310* [Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在雲端環境中執行，但不會收到伺服器管理設定；在[自行託管環境](/docs/zh-TW/self-hosted-environments)中，這些工作階段仍會讀取 runner 映像檔中的受管設定檔。若要為這些工作階段設定模型，請參閱 Claude Tag 管理員指南中的[為範圍選擇模型](https://claude.com/docs/claude-tag/admins/customize#choose-the-model-for-a-scope)。310* [Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在雲端環境中執行，但不會收到伺服器管理設定；在[自行託管環境](/docs/zh-TW/self-hosted-environments)中，這些工作階段仍會讀取 runner 映像檔中的受管設定檔。若要為這些工作階段設定模型，請參閱 Claude Tag 管理員指南中的[為範圍選擇模型](https://claude.com/docs/claude-tag/admins/customize#choose-the-model-for-a-scope)。

311* Cowork 是 Claude Desktop 應用程式中的 agentic 工作分頁，其工作階段在 Claude Code 上執行，但依設計不會收到來自 claude.ai 管理主控台的伺服器管理設定。當您伺服器管理設定中的 `availableModels` 清單不為空，且使用者選擇了清單以外的模型時，伺服器會在遠端 Cowork 工作階段中拒絕該模型。當受管設定檔存在於工作階段執行的位置時，該檔案即適用於 Cowork 工作階段；遠端 Cowork 工作階段在 Anthropic 管理的 VM 上執行，部署到裝置上的檔案不會存在於該處。311* Cowork 是 Claude Desktop 應用程式中的 agentic 工作分頁，其工作階段在 Claude Code 上執行，但依設計不會收到來自 claude.ai 管理主控台的伺服器管理設定。當您伺服器管理設定中的 `availableModels` 清單不為空，且使用者選擇了清單以外的模型時，伺服器會在遠端 Cowork 工作階段中拒絕該模型。當受管設定檔存在於工作階段執行的位置時，該檔案即適用於 Cowork 工作階段；遠端 Cowork 工作階段在 Anthropic 管理的 VM 上執行，部署到裝置上的檔案不會存在於該處。

312* 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 等[第三方提供者](/docs/zh-TW/server-managed-settings#platform-availability)上的工作階段不會收到伺服器管理設定，因此在這些環境中請透過 MDM 或受管設定檔傳遞允許清單。312* 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 等[第三方提供者](/docs/zh-TW/server-managed-settings#platform-availability)上的工作階段不會收到伺服器管理設定，因此在這些環境中請透過 MDM 或受管設定檔傳遞允許清單。

313* 伺服器管理的傳遞方式還需要工作階段使用[符合資格的登入或金鑰](/docs/zh-TW/server-managed-settings#platform-availability)進行驗證。僅透過 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼產生金鑰的裝置群組，應透過 MDM 或受管設定檔傳遞允許清單。313* 從管理主控台傳遞還需要工作階段以登入您組織的[符合資格的登入](/docs/zh-TW/server-managed-settings#platform-availability)，或為該組織核發的 OAuth token 來擷取設定。對於以 API 金鑰驗證的裝置群組，無論金鑰是直接設定或由 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼產生，請透過 MDM 或受管設定檔傳遞允許清單。

314* Desktop 的 Code 分頁也承載 [SSH 工作階段](/docs/zh-TW/desktop#ssh-sessions)，這些工作階段會從其執行所在的遠端主機讀取受管設定檔。請參閱 [Desktop 受管設定](/docs/zh-TW/desktop#managed-settings)。314* Desktop 的 Code 分頁也承載 [SSH 工作階段](/docs/zh-TW/desktop#ssh-sessions)，這些工作階段會從其執行所在的遠端主機讀取受管設定檔。請參閱 [Desktop 受管設定](/docs/zh-TW/desktop#managed-settings)。

315* claude.ai 與 Desktop 應用程式中的模型選擇器會隱藏或以灰色顯示被組織允許清單排除的模型。選擇器狀態僅是為使用者提供的便利，並不會強制執行允許清單。315* claude.ai 與 Desktop 應用程式中的模型選擇器會隱藏或以灰色顯示被組織允許清單排除的模型。選擇器狀態僅是為使用者提供的便利，並不會強制執行允許清單。

316 316

562 562

563本節說明從 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 進行的基於內容的備援。關於模型過載或無法使用時基於可用性的備援，請參閱[備援模型鏈](#fallback-model-chains)。563本節說明從 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 進行的基於內容的備援。關於模型過載或無法使用時基於可用性的備援，請參閱[備援模型鏈](#fallback-model-chains)。

564 564

565Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 會搭配安全分類器執行，這些分類器最常標記網路安全和生物學內容。當分類器標記某個請求，且被標記的類別有備援模型時，Claude Code 會在該模型上重新執行請求，並在逐字稿中顯示通知。對於這兩個類別，備援模型取決於拒絕的模型：565Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 會搭配安全分類器執行，這些分類器最常標記網路安全和生物學內容。對於這兩個類別，備援模型取決於拒絕的模型：

566 566

567* **Fable 5.1、Fable 5 和 Opus 5.5**：被標記為生物學的請求會在 Opus 5 上重新執行，被標記為網路安全的請求會在 Opus 4.8 上重新執行。567* **Fable 5.1、Fable 5 和 Opus 5.5**：被標記為生物學的請求會在 Opus 5 上重新執行，被標記為網路安全的請求會在 Opus 4.8 上重新執行。

568* **Sonnet 5.5**：被標記為網路安全的請求會在 Sonnet 5 上重新執行。被標記為生物學的請求則會以拒絕結束，因為 Sonnet 5.5 沒有生物學備援模型。568* **Sonnet 5.5**：被標記為網路安全的請求會在 Sonnet 5 上重新執行。被標記為生物學的請求則會以拒絕結束，因為 Sonnet 5.5 沒有生物學備援模型。

570 570

571在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，Claude Code 改為透過您部署的模型 ID 解析這些目標。請參閱[在 Bedrock、Agent Platform 和 Foundry 上啟用備援](#enable-fallback-on-bedrock-agent-platform-and-foundry)。571在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，Claude Code 改為透過您部署的模型 ID 解析這些目標。請參閱[在 Bedrock、Agent Platform 和 Foundry 上啟用備援](#enable-fallback-on-bedrock-agent-platform-and-foundry)。

572 572

573當 Claude Code 將被標記的請求切換至其類別的備援模型時，會在該模型上重新執行請求。在您的主要對話中，它會在逐字稿中顯示通知。若要在切換前先被詢問，請參閱[切換前先詢問](#ask-before-switching)。

574

573發生備援後，工作階段會在備援模型上繼續。若要返回原始模型，請執行 [`/model`](#setting-your-model)。575發生備援後，工作階段會在備援模型上繼續。若要返回原始模型，請執行 [`/model`](#setting-your-model)。

574 576

575基於類別的備援需要 Claude Code v2.1.219 或更新版本。在 v2.1.219 之前，每個被標記的 Fable 5 請求都會在您供應商的預設 Opus 模型上重新執行，而 Opus 5 不是備援來源。577基於類別的備援需要 Claude Code v2.1.219 或更新版本。在 v2.1.219 之前，每個被標記的 Fable 5 請求都會在您供應商的預設 Opus 模型上重新執行，而 Opus 5 不是備援來源。

580 備援後的 effort 等級582 備援後的 effort 等級

581</h4>583</h4>

582 584

583當 Claude Code 將您的工作階段切換至備援模型時，會保留被標記請求執行時的 effort 等級，而不是使用該模型的預設 effort。例如，在 Opus 5.5 上以其預設 `medium` 執行、備援至 Opus 4.8 的工作階段會維持在 `medium`，儘管 Opus 4.8 預設為 `high`。585當 Claude Code 將您的工作階段切換至備援模型時，會保留被標記請求執行時的 effort 等級。例如，在 Opus 5.5 上以其預設 `medium` 執行、備援至 Opus 4.8 的工作階段會維持在 `medium`，儘管 Opus 4.8 預設為 `high`。

584 586

585在下列情況中，會套用不同的等級：587在下列情況中，會套用不同的等級：

586 588

587* **設定或組織預設值**：您設定中適用於備援模型的等級，或您組織為其設定的預設 effort，會改為適用。

588* **您自己的變更**：一旦您選擇 effort 等級、在 `/model` 中挑選模型，或稍後恢復工作階段，被標記請求的等級就不再沿用。589* **您自己的變更**：一旦您選擇 effort 等級、在 `/model` 中挑選模型，或稍後恢復工作階段，被標記請求的等級就不再沿用。

589* **Skill effort**：skill 的 `effort` frontmatter 為被標記請求設定的等級會套用於該回合，之後的回合則以 [effort 解析順序](#adjust-effort-level)為備援模型給出的等級執行。590* **Skill effort**：skill 的 `effort` frontmatter 為被標記請求設定的等級會套用於該回合，之後的回合則以 [effort 解析順序](#adjust-effort-level)為備援模型給出的等級執行。

590 591

591工作階段標頭會在模型名稱旁顯示目前生效的等級。若要變更，請在工作階段中執行 `/effort`。592在工作階段中，執行 `/effort status` 以查看目前生效的等級，或執行 `/effort` 以變更等級。

592 593

593<h4 id="check-what-triggered-fallback">594<h4 id="check-what-triggered-fallback">

594 檢查觸發備援的原因595 檢查觸發備援的原因

602 切換前先詢問603 切換前先詢問

603</h4>604</h4>

604 605

605若要在每次請求被標記時自行決定如何處理，而非自動切換，請執行 `/config` 並關閉 **Switch models when a message is flagged**，或在您的設定檔中將 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設為 `false`。之後被標記的請求會暫停工作階段，並提供兩個選項：切換至備援模型，或編輯提示詞並在目前模型上重試。606若要在每次請求被標記時自行決定如何處理，請執行 `/config`，選擇 **Switch models when a message is flagged**，然後選擇 **Ask each time**。您也可以在設定檔中將 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設為 `false`。之後，Claude Code 會在會切換模型的被標記請求處暫停，並提供兩個選項：切換至備援模型，或編輯提示詞並重試。

607

608在互動式工作階段中，第一次有被標記的請求會切換模型時，Claude Code 可能會詢問您之後是否要自動切換。只有在您尚未設定 `switchModelsOnFlag` 時才會詢問，並會將您的選擇以該鍵儲存在您的使用者設定中。

606 609

607某些情況的行為有所不同：610如果您選擇改為留在目前模型，儲存的值為 `false`，與 **Ask each time** 相同。如果您關閉此詢問，Claude Code 不會儲存任何內容，並會在下次有被標記的請求會切換模型時再次詢問。

611

612當您選擇了 **Ask each time** 時，某些情況的行為有所不同：

608 613

609* 當被標記的類別沒有備援模型時（例如 Opus 5 或 Sonnet 5.5 上的生物學標記），Claude Code 不會顯示提示，請求會以拒絕結束。614* 當被標記的類別沒有備援模型時（例如 Opus 5 或 Sonnet 5.5 上的生物學標記），Claude Code 不會顯示提示，請求會以拒絕結束。

610* 如果兩個模型都標記同一個請求，您可以編輯提示詞並重試，或開始新的工作階段。615* 如果兩個模型都標記同一個請求，您可以編輯提示詞並重試，或開始新的工作階段。

611* 在行動應用程式上的[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，不支援編輯並重試。請切換模型，或從桌面瀏覽器或桌面應用程式繼續工作階段。616* 在行動應用程式上的[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，不支援編輯並重試。請切換模型，或從桌面瀏覽器或桌面應用程式繼續工作階段。

612* 在無法顯示提示的[非互動模式](/docs/zh-TW/cli-reference#cli-flags)和 SDK 整合中，被標記的請求會改以拒絕結束該回合。617* 在無法顯示提示的[非互動模式](/docs/zh-TW/cli-reference#cli-flags)和 SDK 整合中，被標記的請求會改以拒絕結束該回合。

618* 在 [subagent](/docs/zh-TW/sub-agents) 中，Claude Code 不會顯示提示，會切換模型的被標記請求會在備援模型上重新執行。

613* 當備援目標被 [`availableModels`](#restrict-model-selection) 封鎖時，Claude Code 不會顯示提示。被標記的請求會以拒絕結束，與目標被封鎖時的自動備援相同。619* 當備援目標被 [`availableModels`](#restrict-model-selection) 封鎖時，Claude Code 不會顯示提示。被標記的請求會以拒絕結束，與目標被封鎖時的自動備援相同。

614 620

615<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">621<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">

628* **每個來源模型**：將 `ANTHROPIC_DEFAULT_OPUS_MODEL` 設定為 Opus 模型 ID，以開啟備援並為被標記的類別提供目標。若釘選的是 Opus 家族以外的模型，或是拒絕的那個模型本身，拒絕將維持不變。634* **每個來源模型**：將 `ANTHROPIC_DEFAULT_OPUS_MODEL` 設定為 Opus 模型 ID，以開啟備援並為被標記的類別提供目標。若釘選的是 Opus 家族以外的模型，或是拒絕的那個模型本身，拒絕將維持不變。

629* **Sonnet 5.5**：除了 Opus 釘選外，請設定 `ANTHROPIC_DEFAULT_SONNET_MODEL`，或在供應商的模型清單中保留 Sonnet 5 項目，以提供重新執行請求的模型。若 Sonnet 釘選的是 Sonnet 家族以外的模型，或是 Sonnet 5.5 本身，拒絕將維持不變。635* **Sonnet 5.5**：除了 Opus 釘選外，請設定 `ANTHROPIC_DEFAULT_SONNET_MODEL`，或在供應商的模型清單中保留 Sonnet 5 項目，以提供重新執行請求的模型。若 Sonnet 釘選的是 Sonnet 家族以外的模型，或是 Sonnet 5.5 本身，拒絕將維持不變。

630 636

637備援模型的上下文視窗也必須至少與工作階段的一樣大，否則 Claude Code 不會切換，被標記的請求會以相同的拒絕結束。在這些供應商上，來源模型預設以 [1M 上下文視窗](#extended-context)執行。請釘選同樣以 1M 視窗執行的模型，例如在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 中釘選 Opus 4.8，或在 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中釘選 Sonnet 5，並使用 Claude Code [能對應至該模型](#pin-models-for-third-party-deployments)的 ID。

638

631<h4 id="security-research-and-biology-workloads">639<h4 id="security-research-and-biology-workloads">

632 安全研究與生物學工作負載640 安全研究與生物學工作負載

633</h4>641</h4>

634 642

635攻擊性安全或生物學方面的工作負載，包括滲透測試、Capture the Flag (CTF) 練習和與生物學相關的程式碼庫，經常會觸發備援，而且通常在第一個請求就觸發。對於在 Fable 5.1、Fable 5 或 Opus 5.5 上進行的實質生物學工作，Claude Code 會在第一個被標記的請求時將工作階段移至 Opus 5，之後被標記為生物學的請求會在那裡以拒絕結束，因為 Opus 5 沒有生物學備援。在 Opus 5 和 Sonnet 5.5 上，您從第一個被標記的請求開始就會收到這些拒絕。643攻擊性安全或生物學方面的工作負載，包括滲透測試、Capture the Flag (CTF) 練習和與生物學相關的程式碼庫，經常會觸發備援，而且通常在第一個請求就觸發。對於在 Fable 5.1、Fable 5 或 Opus 5.5 上進行的實質生物學工作，第一個會切換模型的被標記請求會將工作階段移至 Opus 5，之後被標記為生物學的請求會在那裡以拒絕結束，因為 Opus 5 沒有生物學備援。在 Opus 5 和 Sonnet 5.5 上，您從第一個被標記的請求開始就會收到這些拒絕。

636 644

637這是這些領域的預期路由，而非帳戶被標記。如果您的組織需要 Fable 等級的能力來進行此類工作，請向您的 Anthropic 客戶團隊詢問受信任存取計畫。645這是這些領域的預期路由，而非帳戶被標記。如果您的組織需要 Fable 等級的能力來進行此類工作，請向您的 Anthropic 客戶團隊詢問受信任存取計畫。

638 646

656 664

6571. 明確的選擇：[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-TW/env-vars#variables) 環境變數、以 `--effort` 啟動，或在工作階段中使用 `/effort`（[非互動式的 `/effort` 影響範圍較窄](#non-interactive-effort)）6651. 明確的選擇：[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-TW/env-vars#variables) 環境變數、以 `--effort` 啟動，或在工作階段中使用 `/effort`（[非互動式的 `/effort` 影響範圍較窄](#non-interactive-effort)）

6582. 您的設定：您為模型儲存的等級或 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 鍵，兩者之間以及各設定檔之間的優先順序說明於 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings)6662. 您的設定：您為模型儲存的等級或 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 鍵，兩者之間以及各設定檔之間的優先順序說明於 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings)

6593. 模型的預設 effort：所有支援 effort 的模型都預設為 `high`，但 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 預設為 `medium`、Opus 4.7 預設為 `xhigh`，而當您的組織為其[組織預設模型](#organization-default-model)設定預設 effort 等級時，該等級就是您執行該模型時的預設值。自動模型備援後適用的等級，請參閱[備援後的 effort 等級](#effort-level-after-a-fallback)。6673. 模型的預設 effort：所有支援 effort 的模型都預設為 `high`，但 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 預設為 `medium`、Opus 4.7 預設為 `xhigh`，而當您的組織為其[組織預設模型](#organization-default-model)設定預設 effort 等級時，該等級就是您執行該模型時的預設值

668

669自動模型備援後適用的等級，請參閱[備援後的 effort 等級](#effort-level-after-a-fallback)。

660 670

661除非上述來源之一為 Opus 5.5 設定了等級，否則 Opus 5.5 會從 `medium` 開始，且您使用者設定檔中的頂層 `effortLevel` 不會計入 Opus 5.5。該鍵是 Claude Code 開始按模型儲存等級之前 `/effort` 寫入的舊形式：它會繼續在先前適用的地方適用，即 Opus 5、Fable 5.1 及更早的模型，而 Opus 5.5 及其後發布的模型則會從自己的預設值開始，直到您使用 `/effort` 或 `/model` 選擇器為其選擇等級為止。專案、本機或受管設定中的頂層 `effortLevel`，或透過 `--settings` 傳入的 `effortLevel`，則適用於所有模型。671除非上述來源之一為 Opus 5.5 設定了等級，否則 Opus 5.5 會從 `medium` 開始，且您使用者設定檔中的頂層 `effortLevel` 不會計入 Opus 5.5。該鍵是 Claude Code 開始按模型儲存等級之前 `/effort` 寫入的舊形式：它會繼續在先前適用的地方適用，即 Opus 5、Fable 5.1 及更早的模型，而 Opus 5.5 及其後發布的模型則會從自己的預設值開始，直到您使用 `/effort` 或 `/model` 選擇器為其選擇等級為止。專案、本機或受管設定中的頂層 `effortLevel`，或透過 `--settings` 傳入的 `effortLevel`，則適用於所有模型。

662 672

777 787

778<a id="extended-context-with-1m" />788<a id="extended-context-with-1m" />

779 789

790<span id="sonnet-5-5-and-sonnet-5-context-window" />

791

780<h3 id="extended-context">792<h3 id="extended-context">

781 延伸上下文793 延伸上下文

782</h3>794</h3>

783 795

784Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5、Opus 4.6 及更新版本，以及 Sonnet 4.6 支援 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，適用於處理大型程式碼庫的長時間工作階段。796Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5、Opus 4.6 及更新版本，以及 Sonnet 4.6 支援 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，適用於處理大型程式碼庫的長時間工作階段。

785 797

786在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本在每個方案（包括 Pro）上都以 1M 視窗執行。在這些模型上，您不需要選擇 `[1m]` 變體，也不需要為 1M 視窗開啟用量點數。在某些方案上，Fable 的使用本身可能會計入用量點數；請參閱 [Fable 與用量點數](#fable-and-usage-credits)。798Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本預設以 1M 視窗執行，不需要 `[1m]` 後綴。這也包括 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的工作階段，以及 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段。若要改以 200K 視窗執行這些模型，請參閱[關閉 1M 上下文](#turn-off-1m-context)。

787 799

788Opus 4.6 和 Sonnet 4.6 只能透過其 `[1m]` 變體達到 1M，而能否使用該變體取決於您的方案。在 Max、Team 和 Enterprise 方案上（包括 Team Standard 和 Team Premium 席位），具有 1M 上下文的 Opus 4.6 已包含在您的訂閱中。具有 1M 上下文的 Sonnet 4.6 在每個訂閱方案（包括 Max）上都需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。800Opus 4.6 和 Sonnet 4.6 只能透過其 `[1m]` 變體達到 1M，而能否使用該變體取決於您的方案。在 Max、Team 和 Enterprise 方案上（包括 Team Standard 和 Team Premium 席位），具有 1M 上下文的 Opus 4.6 已包含在您的訂閱中。具有 1M 上下文的 Sonnet 4.6 在每個訂閱方案（包括 Max）上都需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

789 801

795 807

796Claude Code 只有在直接連線至 Anthropic API 時才會檢查這些方案要求。如果您將 `ANTHROPIC_BASE_URL` 指向 [LLM 閘道](/docs/zh-TW/llm-gateway#subscriptions-and-gateways)，且您已儲存的 claude.ai 登入仍是作用中的憑證，Claude Code 不會檢查您方案的用量點數。`[1m]` 選項在 `/model` 中仍可使用，由閘道決定請求是否成功。在 v2.1.229 之前，在該設定下，當 Claude Code 無法確認帳戶上的用量點數時，會拒絕 `/model sonnet[1m]`。808Claude Code 只有在直接連線至 Anthropic API 時才會檢查這些方案要求。如果您將 `ANTHROPIC_BASE_URL` 指向 [LLM 閘道](/docs/zh-TW/llm-gateway#subscriptions-and-gateways)，且您已儲存的 claude.ai 登入仍是作用中的憑證，Claude Code 不會檢查您方案的用量點數。`[1m]` 選項在 `/model` 中仍可使用，由閘道決定請求是否成功。在 v2.1.229 之前，在該設定下，當 Claude Code 無法確認帳戶上的用量點數時，會拒絕 `/model sonnet[1m]`。

797 809

798<span id="context-window-behind-a-gateway" />810在 Anthropic API 上，1M 上下文視窗採用標準模型定價，超過 200K 的 token 不收取額外費用，但 Haiku 5.5 除外，其[提示詞超過 100K token 時費用較高](#haiku-5-5-context-window-and-pricing)。對於延伸上下文已包含在訂閱中的方案，用量仍由您的訂閱涵蓋。對於透過用量點數使用延伸上下文的方案，token 會計入用量點數。

~~799~~

800如果您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](/docs/zh-TW/llm-gateway)或其他代理伺服器，Claude Code 會為它能識別的每個模型提供與該模型在 Anthropic API 上相同的上下文視窗。Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本會取得 1M 視窗，無需選擇 `[1m]` 變體；而只能透過 `[1m]` 變體達到 1M 的模型（例如 Opus 4.6），在未使用該變體時會以 200K 執行。Claude Code 無法偵測閘道或其後方伺服器所強制執行的較低限制。如果您的閘道會拒絕超過 200K token 的請求，請在啟動 Claude Code 的環境中設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-TW/env-vars)，讓所有模型上的工作階段都[在該邊界進行壓縮](#set-the-auto-compact-window)。

~~801~~

802若要關閉 1M 上下文，請設定 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 會從模型選擇器中移除 1M 模型變體。對於具有原生 1M 視窗的模型（例如 Sonnet 5 和 Fable 模型），它也會將該模型視為具有 200K 上下文視窗：

~~803~~

804* 開啟自動壓縮時，工作階段會透過[自動壓縮](#set-the-auto-compact-window)在 200K 邊界進行壓縮。將自動壓縮視窗設定為高於 200K 並不會解除此限制，因為 Claude Code 會將該視窗上限設為模型的上下文視窗。

805* 關閉自動壓縮時，工作階段會在 200K 邊界以[上下文限制錯誤](/docs/zh-TW/errors#prompt-is-too-long)停止，而不是進行壓縮。

806 811

807在 v2.1.223 之前，Claude Code 只會將 Sonnet 5、Opus 4.8 和 Opus 5 工作階段限制在 200K。請參閱[環境變數](/docs/zh-TW/env-vars)。812<h4 id="select-1m-context-for-opus-4-6-or-sonnet-4-6">

~~808~~ 813 為 Opus 4.6 或 Sonnet 4.6 選擇 1M 上下文

8091M 上下文視窗採用標準模型定價，超過 200K 的 token 不收取額外費用，但 Haiku 5.5 除外，其[提示詞超過 100K token 時費用較高](#haiku-5-5-context-window-and-pricing)。對於延伸上下文已包含在訂閱中的方案，用量仍由您的訂閱涵蓋。對於透過用量點數使用延伸上下文的方案，token 會計入用量點數。814</h4>

~~810~~

811如果您的帳戶支援 1M 上下文，該選項會出現在最新版 Claude Code 的 `/model` 選擇器中。如果您沒有看到它，請重新啟動工作階段；若使用第三方供應商，請檢查您的部署是否已透過 `ANTHROPIC_DEFAULT_*_MODEL` 變數[釘選模型](#pin-models-for-third-party-deployments)。

812 815

813您也可以將 `[1m]` 後綴與模型別名或完整模型名稱搭配使用：816若要依名稱選擇 1M 變體，請在模型別名或完整模型名稱後加上 `[1m]` 後綴：

814 817

815```text theme={null}818```text theme={null}

816# Use the opus[1m] or sonnet[1m] alias819# Append [1m] to a full model name

817/model opus[1m]820/model claude-opus-4-6[1m]

818/model sonnet[1m]821/model claude-sonnet-4-6[1m]

819 822

820# Or append [1m] to a full model name823# Or to an alias: the suffix applies to the model the alias resolves to

821/model claude-opus-4-8[1m]824/model opus[1m]

822```825```

823 826

824<h4 id="sonnet-5-5-and-sonnet-5-context-window">827<span id="context-window-behind-a-gateway" />

825 Sonnet 5.5 和 Sonnet 5 上下文視窗828

829<h4 id="context-window-behind-an-llm-gateway">

830 LLM 閘道後方的上下文視窗

826</h4>831</h4>

827 832

828在 Anthropic API 上，Sonnet 5.5 和 Sonnet 5 一律以 1M 上下文視窗執行。沒有 200K 變體、沒有需要選擇的 `[1m]` 後綴，且任何方案都不需要用量點數。工作階段會在視窗填滿前自動壓縮，預設約在 967K token 時進行；設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-TW/env-vars) 以選擇不同的閾值。833如果您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](/docs/zh-TW/llm-gateway)或其他代理伺服器，Claude Code 會為它能識別的每個模型提供與該模型在 Anthropic API 上相同的上下文視窗。Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本會取得 1M 視窗，無需選擇 `[1m]` 變體；而只能透過 `[1m]` 變體達到 1M 的模型（例如 Opus 4.6），在未使用該變體時會以 200K 執行。Claude Code 無法偵測閘道或其後方伺服器所強制執行的較低限制。如果您的閘道會拒絕超過 200K token 的請求，請在啟動 Claude Code 的環境中設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-TW/env-vars)，讓所有模型上的工作階段都[在該邊界進行壓縮](#set-the-auto-compact-window)。

829 834

830在 [LLM 閘道](/docs/zh-TW/llm-gateway)或其他自訂 `ANTHROPIC_BASE_URL` 後方，Claude Code 也會為 Sonnet 5.5 和 Sonnet 5 提供相同的 1M 視窗。如果您的閘道強制執行較低的限制，請參閱[閘道後方的上下文視窗](#context-window-behind-a-gateway)。835<h4 id="turn-off-1m-context">

836 關閉 1M 上下文

837</h4>

831 838

832下列設定會改以 200K 作為視窗預算：839若要讓工作階段維持在 200K 視窗，請在您的 shell 或[設定檔](/docs/zh-TW/env-vars#set-environment-variables)中設定 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 會從模型選擇器中移除 `[1m]` 模型變體。對於預設以 1M 視窗執行的模型（例如 Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本），它也會將該模型視為具有 200K 上下文視窗：

833 840

834* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：將所有具有原生 1M 視窗之模型的工作階段限制在 200K 視窗；關於如何強制執行此限制，請參閱[延伸上下文](#extended-context)。適用於需要限制上下文的部署。841* 開啟自動壓縮時，工作階段會透過[自動壓縮](#set-the-auto-compact-window)在 200K 邊界進行壓縮。將自動壓縮視窗設定為高於 200K 並不會解除此限制，因為 Claude Code 會將該視窗上限設為模型的上下文視窗。

842* 關閉自動壓縮時，工作階段會在 200K 邊界以[上下文限制錯誤](/docs/zh-TW/errors#prompt-is-too-long)停止，而不是進行壓縮。

835 843

836<h4 id="haiku-5-5-context-window-and-pricing">844<h4 id="haiku-5-5-context-window-and-pricing">

837 Haiku 5.5 上下文視窗與定價845 Haiku 5.5 上下文視窗與定價

875若您未設定自動壓縮視窗，Claude Code 會在對話達到模型的上下文限制時進行壓縮，但下列工作階段除外：883若您未設定自動壓縮視窗，Claude Code 會在對話達到模型的上下文限制時進行壓縮，但下列工作階段除外：

876 884

877* [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)會在對話接近模型限制時進行壓縮885* [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)會在對話接近模型限制時進行壓縮

878* 未啟用[擴充上下文](#extended-context)的 Sonnet 4.6 與 Opus 4.6 會在 200K 邊界進行壓縮；Opus 4.8 及更新版本以 200K 上下文視窗執行時（例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 與 Microsoft Foundry 上）也是如此886* 未啟用[擴充上下文](#extended-context)的 Sonnet 4.6 與 Opus 4.6 會在 200K 邊界進行壓縮

879* 當您設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars) 時，具有原生 1M 視窗的模型（例如 Sonnet 5 與 Fable 模型）會在 200K 邊界進行壓縮887* 當您設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars) 時，具有原生 1M 視窗的模型（例如 Sonnet 5 與 Fable 模型）會在 200K 邊界進行壓縮

880* 以原生 1M 視窗執行的模型會在視窗填滿前進行壓縮，預設約為 967K token。在 Anthropic API 上，這些模型包括 Sonnet 5、Haiku 5.5、Fable 模型，以及 Opus 4.7 及更新版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform 與 Microsoft Foundry 上，哪些模型以該視窗執行，請參閱[為第三方部署固定模型](#pin-models-for-third-party-deployments)。若位於自訂 `ANTHROPIC_BASE_URL` 之後，請參閱[閘道後方的上下文視窗](#context-window-behind-a-gateway)888* 以原生 1M 視窗執行的模型會在視窗填滿前進行壓縮，預設約為 967K token。這些模型包括 Fable 模型、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本。若位於自訂 `ANTHROPIC_BASE_URL` 之後，請參閱[閘道後方的上下文視窗](#context-window-behind-a-gateway)

881* 使用 Claude Code 無法辨識之模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）的工作階段，會在 Claude Code 為該 ID 假定的上下文視窗進行壓縮；請參閱[為閘道或自訂模型 ID 修正視窗](#correct-the-window-for-a-gateway-or-custom-model-id)889* 使用 Claude Code 無法辨識之模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）的工作階段，會在 Claude Code 為該 ID 假定的上下文視窗進行壓縮；請參閱[為閘道或自訂模型 ID 修正視窗](#correct-the-window-for-a-gateway-or-custom-model-id)

882 890

883<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">891<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

981 989

982對 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 套用相同的模式。如需所有供應商目前與舊版的模型 ID，請參閱[模型概覽](https://platform.claude.com/docs/en/about-claude/models/overview)。若要將使用者升級至新的模型版本，請更新這些環境變數並重新部署。990對 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 套用相同的模式。如需所有供應商目前與舊版的模型 ID，請參閱[模型概覽](https://platform.claude.com/docs/en/about-claude/models/overview)。若要將使用者升級至新的模型版本，請更新這些環境變數並重新部署。

983 991

984若要為固定模型啟用[延伸上下文](#extended-context)，請在 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 或 `ANTHROPIC_DEFAULT_FABLE_MODEL` 中的模型 ID 後方附加 `[1m]`：992具有原生 1M 視窗的固定模型（例如 Opus 4.8 或 Sonnet 5），在 Claude Code 能將固定的 ID 對應到該模型時，無需任何後綴即可以 [1M 上下文視窗](#extended-context)執行。當 ID 包含該模型的 Anthropic API ID（例如 `us.anthropic.claude-opus-4-8` 包含 `claude-opus-4-8`），或有 [`modelOverrides`](#override-model-ids-per-version) 項目將該模型對應到此 ID 時，即視為相符。對於 Claude Code 無法對應到任何模型的固定 ID，除非該 ID 帶有 `[1m]` 後綴，否則工作階段預設會以 200K 視窗執行。

993

994對於透過其 `[1m]` 變體達到 1M 的模型（例如 Opus 4.6 或 Sonnet 4.6），請在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中的模型 ID 後方附加 `[1m]` 以啟用延伸上下文：

985 995

986```bash theme={null}996```bash theme={null}

987export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'997export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6[1m]'

988```998```

989 999

990加上 `[1m]` 後綴後，1M 上下文視窗會套用於該固定別名的所有使用情境，包括 [`opusplan`](#opusplan-model-setting) 的 plan mode Opus 階段，以及 `model` frontmatter 指定該別名的 [subagent](/docs/zh-TW/sub-agents#choose-a-model)。1000加上 `[1m]` 後綴後，1M 上下文視窗會套用於該固定別名的所有使用情境，包括 [`opusplan`](#opusplan-model-setting) 的 plan mode Opus 階段，以及 `model` frontmatter 指定該別名的 [subagent](/docs/zh-TW/sub-agents#choose-a-model)。

991 1001

992* Claude Code 會在將模型 ID 傳送給您的供應商之前移除此後綴。1002* Claude Code 會在將模型 ID 傳送給您的供應商之前移除此後綴。

993* 僅在底層模型[支援 1M 上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)時才附加 `[1m]`。1003* 僅在底層模型[支援 1M 上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)時才附加 `[1m]`。

994* 後綴是依變數讀取，而非依模型讀取。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，某個變數中不含 `[1m]` 的模型 ID 會使用 200K 上下文，即使另一個變數以後綴設定了相同的模型亦然。Sonnet 5 在這些供應商上一律以 1M 視窗執行，永遠不需要後綴。1004* 後綴是依變數讀取，而非依模型讀取。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，某個變數中不含 `[1m]` 的 Opus 4.6 或 Sonnet 4.6 ID 會使用 200K 上下文，即使另一個變數以後綴設定了相同的模型亦然。

995 1005

996當您設定 `ANTHROPIC_DEFAULT_*_MODEL` 變數時，`/model` 選擇器會以該模型的單一列取代該系列的內建列，包括所有 1M 上下文列。若要在不為該變數加上後綴的情況下使用 1M 視窗，使用者可執行 `/model opus[1m]`，Claude Code 會將後綴套用至該變數所指定的模型。`/model sonnet[1m]` 的運作方式相同。1006當您設定 `ANTHROPIC_DEFAULT_*_MODEL` 變數時，`/model` 選擇器會以該模型的單一列取代該系列的內建列，包括所有 1M 上下文列。若要在不為該變數加上後綴的情況下使用 1M 視窗，使用者可執行 `/model opus[1m]`，Claude Code 會將後綴套用至該變數所指定的模型。`/model sonnet[1m]` 的運作方式相同。

997 1007

monitoring-usage.md +4 −4

Details

551* **伺服器受管設定**：將它們新增至組織的[伺服器受管設定](/docs/zh-TW/server-managed-settings)的 `env` 區塊。Claude Code 在[伺服器受管設定適用](/docs/zh-TW/model-config#surface-coverage)的任何位置啟動時會擷取這些設定，包括使用者的機器和 Claude Tag 頻道工作階段以外的雲端工作階段。Claude Tag 工作階段不會接收伺服器受管設定，因此此路由不會設定它們。551* **伺服器受管設定**：將它們新增至組織的[伺服器受管設定](/docs/zh-TW/server-managed-settings)的 `env` 區塊。Claude Code 在[伺服器受管設定適用](/docs/zh-TW/model-config#surface-coverage)的任何位置啟動時會擷取這些設定，包括使用者的機器和 Claude Tag 頻道工作階段以外的雲端工作階段。Claude Tag 工作階段不會接收伺服器受管設定，因此此路由不會設定它們。

552* **環境的變數**：將它們新增至雲端環境的[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)，以僅設定在該環境中執行的工作階段。這是到達 Claude Tag 工作階段的路由。552* **環境的變數**：將它們新增至雲端環境的[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)，以僅設定在該環境中執行的工作階段。這是到達 Claude Tag 工作階段的路由。

553 553

554任何使用環境的人都可以讀取其變數，因此不要在其中放置憑證，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器 token。環境上的[網路密鑰](/docs/zh-TW/cloud-environments#add-api-credentials)也無法幫助，因為 Claude Code 自己的遙測匯出是[永遠不會取得密鑰的請求](/docs/zh-TW/cloud-environments#requests-that-never-get-the-credential)之一。如果收集器需要憑證，請改為透過伺服器受管設定設定整個匯出，因為當您在該處設定憑證時，[Claude Code 會移除在受管設定外設定的端點變數](#how-managed-settings-lock-the-otlp-destination)。554任何使用環境的人都可以讀取其變數，因此不要在其中放置憑證，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器 token。環境上的[網路密鑰](/docs/zh-TW/cloud-environments#add-network-secrets)也無法幫助，因為 Claude Code 自己的遙測匯出是[永遠不會取得密鑰的請求](/docs/zh-TW/cloud-environments#requests-that-never-get-the-credential)之一。如果收集器需要憑證，請改為透過伺服器受管設定設定整個匯出，因為當您在該處設定憑證時，[Claude Code 會移除在受管設定外設定的端點變數](#how-managed-settings-lock-the-otlp-destination)。

555 555

556在為雲端工作階段設定遙測時，請記住這些限制：556在為雲端工作階段設定遙測時，請記住這些限制：

557 557

1314* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1314* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述

1315* `plugin_id`：`<name>@<marketplace>` 形式的外掛程式識別碼1315* `plugin_id`：`<name>@<marketplace>` 形式的外掛程式識別碼

1316* `hook_event`：發出指標的鉤子事件類型1316* `hook_event`：發出指標的鉤子事件類型

1317* 最多 20 個外掛程式發出的指標鍵。名稱與 `^[a-z][a-z0-9_]{0,39}$` 相符。值是布林值或數字。1317* 最多 20 個由外掛發出的指標鍵。名稱符合 `^[a-z][a-z0-9_]{0,39}$`。值為布林值或數字。

1318 1318

1319<h4 id="compaction-event">1319<h4 id="compaction-event">

1320 壓縮事件1320 壓縮事件

1382* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件1382* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件

1383* `survey_type`：哪個調查產生事件。`"session"` 是「Claude 做得如何？」評分提示1383* `survey_type`：哪個調查產生事件。`"session"` 是「Claude 做得如何？」評分提示

1384* `response`：使用者在 `responded` 事件上的選擇1384* `response`：使用者在 `responded` 事件上的選擇

1385* `enabled_via_override`：當設定了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。作為布林值而不是字串發出。存在於 `session` 調查事件上。在此屬性上篩選以確認整個車隊中應用了覆蓋。1385* `enabled_via_override`：設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。以布林值而非字串發出。出現在 `session` 調查事件上。可依此屬性篩選，以確認覆寫已套用至整個機群

1386 1386

1387<h4 id="retention-sweep-event">1387<h4 id="retention-sweep-event">

1388 保留掃描事件1388 保留掃描事件

1473 例如，具有 `apiKeyHelper`、兩個 `env` 變數和拒絕規則的管理設定匯出為 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.1473 例如，具有 `apiKeyHelper`、兩個 `env` 變數和拒絕規則的管理設定匯出為 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.

1474 1474

1475 Claude Code 在 8 KB UTF-8 處切割值，切割值不是有效的 JSON1475 Claude Code 在 8 KB UTF-8 處切割值，切割值不是有效的 JSON

1476* `managed_settings.settings_truncated`（當 `managed_settings.settings` 存在時）：當 Claude Code 在 8 KB 處切割 `managed_settings.settings` 時為 `true`，否則為 `false`。作為布林值而不是字串發出1476* `managed_settings.settings_truncated`（當 `managed_settings.settings` 存在時）：當 Claude Code 在 8 KB 處截斷 `managed_settings.settings` 時為 `true`，否則為 `false`。以布林值而非字串發出

1477 1477

1478<h2 id="interpret-metrics-and-events-data">1478<h2 id="interpret-metrics-and-events-data">

1479 解釋指標和事件資料1479 解釋指標和事件資料

network-config.md +1 −1

Details

209| :- | :- | :- | :- |209| :- | :- | :- | :- |

210| 首位元組期限 | Claude Code 傳送請求後沒有回應標頭到達 | 直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)，包括透過 HTTPS 代理，但不包括當 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 透過 [gateway](/docs/zh-TW/gateways) 路由時。在 Amazon Bedrock 上選擇加入，使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`；不在 Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行 | 直接 Anthropic API 上 180 秒，其他位置 300 秒，加上每 32KB 請求本體一秒 |210| 首位元組期限 | Claude Code 傳送請求後沒有回應標頭到達 | 直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)，包括透過 HTTPS 代理，但不包括當 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 透過 [gateway](/docs/zh-TW/gateways) 路由時。在 Amazon Bedrock 上選擇加入，使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`；不在 Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行 | 直接 Anthropic API 上 180 秒，其他位置 300 秒，加上每 32KB 請求本體一秒 |

211| 事件層級監視狗 | 沒有回應事件解析。在位元組層級監視狗執行於 Amazon Bedrock 以外的連線上時，到達的位元組（包括保活 ping）也會重設此監視狗，最多約五分鐘內沒有解析事件 | 每個提供者 | 300 秒 |211| 事件層級監視狗 | 沒有回應事件解析。在位元組層級監視狗執行於 Amazon Bedrock 以外的連線上時，到達的位元組（包括保活 ping）也會重設此監視狗，最多約五分鐘內沒有解析事件 | 每個提供者 | 300 秒 |

212| 位元組層級監視狗 | 網路上沒有位元組到達，包括 SSE 保活 ping | 直接 Anthropic API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和 [gateway](/docs/zh-TW/gateways) 連線，包括自訂 `ANTHROPIC_BASE_URL`。在 Amazon Bedrock `vnd.amazon.eventstream` 回應上選擇加入，使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`；不在 Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行 | 直接 Anthropic API 上 180 秒，其他位置 300 秒 |212| 位元組層級監視狗 | 網路上沒有位元組到達，包括 SSE 保活 ping | 直接 Anthropic API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和 [閘道](/docs/zh-TW/gateways) 連線，包括自訂 `ANTHROPIC_BASE_URL`。在 Amazon Bedrock `vnd.amazon.eventstream` 回應上選擇加入，使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`；不在 Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行 | 直接 Anthropic API 上 180 秒。透過自訂 `ANTHROPIC_BASE_URL` 時，若 Claude Code 已[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)則為 180 秒，若尚未擷取則為 300 秒。其他位置 300 秒 |

214 214

215如果您設定 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`，位元組層級監視狗會在 Bedrock 上取代本體閒置逾時，而不是與其並行執行。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 隨後也會控制 Bedrock 串流在 Claude Code 將連線視為死連線之前可以保持安靜多長時間，在下列列出的限制範圍內。到達的位元組仍不會在 Bedrock 上重設事件層級監視狗。啟用偵錯記錄時，每個 Bedrock 串流隨後會記錄一條以 `wire-heartbeat: _chunkTimes absent` 開頭的偵錯訊息。215如果您設定 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`，位元組層級監視狗會在 Bedrock 上取代本體閒置逾時，而不是與其並行執行。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 隨後也會控制 Bedrock 串流在 Claude Code 將連線視為死連線之前可以保持安靜多長時間，在下列列出的限制範圍內。到達的位元組仍不會在 Bedrock 上重設事件層級監視狗。啟用偵錯記錄時，每個 Bedrock 串流隨後會記錄一條以 `wire-heartbeat: _chunkTimes absent` 開頭的偵錯訊息。

output-styles.md +3 −3

Details

183| :- | :- | :- |183| :- | :- | :- |

184| `name` | 否 | 輸出樣式的名稱，在 `/config` 選擇器中顯示。預設：檔案名稱 |184| `name` | 否 | 輸出樣式的名稱，在 `/config` 選擇器中顯示。預設：檔案名稱 |

185| `description` | 否 | 輸出樣式的描述，在 `/config` 選擇器中顯示 |185| `description` | 否 | 輸出樣式的描述，在 `/config` 選擇器中顯示 |

186| `keep-coding-instructions` | 否 | 設定為 `true` 以將 Claude Code 的內建軟體工程指令與您的樣式一起保留。預設：`false` |186| `keep-coding-instructions` | 否 | 設定為 `true` 以將 Claude Code 內建軟體工程指令的區段（僅完整系統提示詞包含此區段）與您的風格一起保留。請參閱[輸出風格的運作方式](#how-output-styles-work)。預設：`false` |

187| `force-for-plugin` | 否 | 僅限 Plugin 輸出樣式。設定為 `true` 以在啟用 plugin 時自動應用此樣式，無需要求使用者選擇它。覆蓋使用者的 `outputStyle` 設定。如果多個啟用的 plugin 設定此項，Claude Code 會使用第一個載入的。預設：`false` |187| `force-for-plugin` | 否 | 僅限 Plugin 輸出樣式。設定為 `true` 以在啟用 plugin 時自動應用此樣式，無需要求使用者選擇它。覆蓋使用者的 `outputStyle` 設定。如果多個啟用的 plugin 設定此項，Claude Code 會使用第一個載入的。預設：`false` |

188 188

189<span id="comparisons-to-related-features" />189<span id="comparisons-to-related-features" />

214輸出樣式會變更 Claude Code 提供給 Claude 的指令。214輸出樣式會變更 Claude Code 提供給 Claude 的指令。

215 215

216* Claude Code 在每個請求中都會傳送作用中樣式的指令。216* Claude Code 在每個請求中都會傳送作用中樣式的指令。

217* 自訂輸出樣式會省略 Claude Code 的內建軟體工程指令，例如如何限定變更範圍、撰寫註解和驗證工作，除非 `keep-coding-instructions` 設定為 `true`。217* 在完整系統提示詞中，自訂輸出風格會省略 Claude Code 的內建軟體工程指令區段，例如如何限定變更範圍、撰寫註解和驗證工作，除非 `keep-coding-instructions` 設定為 `true`。較短的系統提示詞不包含該區段，因此該欄位在那裡沒有作用。若要依賴該欄位，請將 [`CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT`](/docs/zh-TW/env-vars#variables) 設定為 `0`，這會在任何模型上選用完整提示詞。

218 218

219輸出樣式適用於主對話和[分支](/docs/zh-TW/sub-agents#fork-the-current-conversation)，分支會繼承父代的完整對話和系統提示。其他[子代理會執行自己的系統提示](/docs/zh-TW/sub-agents#what-loads-at-startup)，因此樣式不會改變它們的回應方式。219輸出風格適用於主對話和[分支](/docs/zh-TW/sub-agents#fork-the-current-conversation)，分支會繼承父代的完整對話和系統提示詞。其他 [subagent 會執行自己的系統提示詞](/docs/zh-TW/sub-agents#what-loads-at-startup)，因此風格不會改變它們的回應方式。

220 220

221權杖使用量取決於樣式。樣式的指令會增加輸入權杖，不過提示快取會在工作階段中的第一個請求之後降低此成本。221權杖使用量取決於樣式。樣式的指令會增加輸入權杖，不過提示快取會在工作階段中的第一個請求之後降低此成本。

222 222

overview.md +8 −8

Details

24 <Tab title="原生安裝（建議）">24 <Tab title="原生安裝（建議）">

25 **macOS、Linux、WSL：**25 **macOS、Linux、WSL：**

26 26

~~27 ```bash theme={null}~~27 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

28 curl -fsSL https://claude.ai/install.sh | bash28 curl -fsSL https://claude.ai/install.sh | bash

29 ```29 ```

30 30

32 32

33 **Windows PowerShell：**33 **Windows PowerShell：**

34 34

~~35 ```powershell theme={null}~~35 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

36 irm https://claude.ai/install.ps1 | iex36 irm https://claude.ai/install.ps1 | iex

37 ```37 ```

38 38

39 **Windows CMD：**39 **Windows CMD：**

40 40

~~41 ```batch theme={null}~~41 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

42 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd42 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

43 ```43 ```

44 44

45 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。45 安裝命令在下載 Claude Code 時不會顯示進度。當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的 shell 說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。

46 46

47 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。47 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。

48 48

56 </Tab>56 </Tab>

57 57

58 <Tab title="Homebrew">58 <Tab title="Homebrew">

~~59 ```bash theme={null}~~59 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

60 brew install --cask claude-code60 brew install --cask claude-code

61 ```61 ```

62 62

68 </Tab>68 </Tab>

69 69

70 <Tab title="WinGet">70 <Tab title="WinGet">

~~71 ```powershell theme={null}~~71 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

72 winget install Anthropic.ClaudeCode72 winget install Anthropic.ClaudeCode

73 ```73 ```

74 74

97 <Tab title="VS Code">97 <Tab title="VS Code">

98 VS Code 擴充功能在您的編輯器中直接提供內嵌差異、@-提及、計畫審查和對話歷史記錄。98 VS Code 擴充功能在您的編輯器中直接提供內嵌差異、@-提及、計畫審查和對話歷史記錄。

99 99

100 * [安裝 VS Code](vscode:extension/anthropic.claude-code)100 * [為 VS Code 安裝](vscode:extension/anthropic.claude-code)

101 * [安裝 Cursor](cursor:extension/anthropic.claude-code)101 * [為 Cursor 安裝](cursor:extension/anthropic.claude-code)

102 102

103 或在擴充功能檢視中搜尋「Claude Code」（Mac 上為 `Cmd+Shift+X`，Windows/Linux 上為 `Ctrl+Shift+X`）。安裝後，開啟命令選擇板（`Cmd+Shift+P` / `Ctrl+Shift+P`），輸入「Claude Code」，然後選擇**在新標籤中開啟**。103 或在擴充功能檢視中搜尋「Claude Code」（Mac 上為 `Cmd+Shift+X`，Windows/Linux 上為 `Ctrl+Shift+X`）。安裝後，開啟命令選擇板（`Cmd+Shift+P` / `Ctrl+Shift+P`），輸入「Claude Code」，然後選擇**在新標籤中開啟**。

104 104

permissions.md +1 −1

Details

700權限和 [sandboxing](/docs/zh-TW/sandboxing) 是互補的安全層：700權限和 [sandboxing](/docs/zh-TW/sandboxing) 是互補的安全層：

701 701

702* **權限**控制 Claude Code 可以使用哪些工具以及它可以存取哪些檔案或網域。它們適用於 Bash、Read、Edit、WebFetch、MCP 和其他所有工具，除了 deny 或 ask 規則無法阻止 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。702* **權限**控制 Claude Code 可以使用哪些工具以及它可以存取哪些檔案或網域。它們適用於 Bash、Read、Edit、WebFetch、MCP 和其他所有工具，除了 deny 或 ask 規則無法阻止 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。

703* **沙箱**提供作業系統級別的強制執行，限制 shell 命令的檔案系統和網路存取。它僅適用於 Bash、PowerShell 和 [Monitor](/docs/zh-TW/tools-reference#monitor-tool) 命令及其子程序。703* **沙箱**提供作業系統級別的強制執行，限制 shell 命令的檔案系統和網路存取。它適用於 Bash、PowerShell 和 [Monitor](/docs/zh-TW/tools-reference#monitor-tool) 工具命令及其子程序。

704 704

705使用兩者進行深度防禦，因為即使提示注入繞過 Claude 的決策制定，沙箱限制仍然適用。來自沙箱設定和權限規則的路徑和網域會 [合併到最終沙箱設定](/docs/zh-TW/sandboxing#permission-rules)。705使用兩者進行深度防禦，因為即使提示注入繞過 Claude 的決策制定，沙箱限制仍然適用。來自沙箱設定和權限規則的路徑和網域會 [合併到最終沙箱設定](/docs/zh-TW/sandboxing#permission-rules)。

706 706

plugin-evals.md +61 −38

Details

335* **替換**：使用 `{{input.<field>}}` 從呼叫的輸入插入欄位，使用 `{{file:fixtures/{input.<field>}.json}}` 插入 mock 旁邊的 fixture 檔案的內容。335* **替換**：使用 `{{input.<field>}}` 從呼叫的輸入插入欄位，使用 `{{file:fixtures/{input.<field>}.json}}` 插入 mock 旁邊的 fixture 檔案的內容。

336* **`expect:`**：`expect:` 區塊保護輸入。如果呼叫違反它，執行會中止，分數為 0，並記錄原因，因此案例可以斷言您的 plugin 要求伺服器執行的操作。336* **`expect:`**：`expect:` 區塊保護輸入。如果呼叫違反它，執行會中止，分數為 0，並記錄原因，因此案例可以斷言您的 plugin 要求伺服器執行的操作。

337* **`error: true`**：設定 `error: true` 以改為將主體作為工具錯誤返回。337* **`error: true`**：設定 `error: true` 以改為將主體作為工具錯誤返回。

338* **`type: agent`**：設定 `type: agent` 讓評判模型依據主體中的指令扮演伺服器回應。338* **`type: agent`**：設定 `type: agent` 讓評判模型依據主體中的指令扮演伺服器回應。對 agent mocks 的呼叫共用一個[每次執行的預算](#mock-call-budget-exceeded)，為案例 `max_turns` 的四倍，超過預算的呼叫會中止執行，分數為 0。

339 339

340[mock file reference](#mock-files) 列出每個鍵和 `_server.md` 和 `_tools.json` 檔案。340[mock file reference](#mock-files) 列出每個鍵和 `_server.md` 和 `_tools.json` 檔案。

341 341

370| :- | :- |370| :- | :- |

373| 已安裝的外掛程式（按名稱），`name` 或 `name@marketplace` | 已安裝副本的 eval 目錄中的案例，並載入已安裝的副本。結果寫入您目前目錄下的 `./evals/results/`，或使用 `--eval-dir` 時寫入 `./<dir>/results/` |373| 已安裝的外掛程式（按名稱），`name` 或 `name@marketplace` | 該外掛程式及其 eval 目錄中的案例，[就地讀取或從已安裝的副本讀取](/docs/zh-TW/plugins/loading#in-place-and-copied-plugins)。結果寫入您目前目錄下的 `./evals/results/`，或使用 `--eval-dir` 時寫入 `./<dir>/results/` |

375| 省略 | 目前目錄作為路徑 |375| 省略 | 目前目錄作為路徑 |

376 376

503| `cases[].aggregates.delta` | With-arm score minus without-arm score. Omitted when the case ran one arm or the arms aren't comparable |503| `cases[].aggregates.delta` | With-arm score minus without-arm score. Omitted when the case ran one arm or the arms aren't comparable |

504| `cases[].arms.with[].error` | `null`, or why a run ended abnormally, such as `timed out after 300s`. A run that started but ended badly is still graded on what it produced, so a non-null error doesn't imply score 0 |504| `cases[].arms.with[].error` | `null`, or why a run ended abnormally, such as `timed out after 300s`. A run that started but ended badly is still graded on what it produced, so a non-null error doesn't imply score 0 |

505| `cases[].arms.with[].aborted` | Present when a [mock](#mock-mcp-servers)'s `expect:` or `abort_when` stopped the run, with `server`, `tool`, and `reason`. The run scores 0 and `error` stays `null` |505| `cases[].arms.with[].aborted` | 當 [mock](#mock-mcp-servers) 透過 `expect:`、`abort_when` 或 [agent-mock 呼叫預算](#mock-call-budget-exceeded) 停止執行時出現，包含 `server`、`tool` 和 `reason`。該執行得分為 0，且 `error` 維持 `null` |

506| `cases[].arms.with[].skippedPaidGraders` | `true` when the cost ceiling skipped this run's judge graders, so its score isn't comparable |506| `cases[].arms.with[].skippedPaidGraders` | `true` when the cost ceiling skipped this run's judge graders, so its score isn't comparable |

507| `costUsd`, `durationSeconds`, `claudeVersion` | Estimated cost at list price including judge calls, wall-clock seconds, and the Claude Code version that ran the suite |507| `costUsd`, `durationSeconds`, `claudeVersion` | Estimated cost at list price including judge calls, wall-clock seconds, and the Claude Code version that ran the suite |

508 508

656| Key | Default | Purpose |656| Key | Default | Purpose |

657| :- | :- | :- |657| :- | :- | :- |

659| `expect` | 未設定 | 從點分輸入路徑到類型名稱（例如 `string`、`number`、`boolean`、`array` 或 `object`）、`/regex/`、字面值或允許的字面值清單的對應。違反它的呼叫會以分數 0 中止執行，並報告為 `aborted`，包含伺服器、工具和原因 |659| `expect` | 未設定 | 從點分輸入路徑到類型名稱（例如 `string`、`number`、`boolean`、`array` 或 `object`）、[`/regex/`](#expect-patterns)、字面值或允許的字面值清單的對應。違反它的呼叫會以分數 0 中止執行，並報告為 `aborted`，包含伺服器、工具和原因 |

661| `abort_when` | 未設定 | 僅 `agent`。散文列出代理可能中止執行的唯一條件 |661| `abort_when` | 未設定 | 僅 `agent`。散文列出代理可能中止執行的唯一條件 |

662 662

663兩個可選檔案位於伺服器目錄中的工具檔案旁邊：663兩個可選檔案位於伺服器目錄中的工具檔案旁邊：

664 664

665* **`_server.md`**：一個單一的 `type: agent` mock，回答多個工具，在其 `tools:` frontmatter 鍵中列出。相同工具的 `<tool>.md` 優先。在個別 `<tool>.md` 上放置 `expect:` 保護，而不是這裡665* **`_server.md`**：一個單一的 `type: agent` mock，回答多個工具，在其 `tools:` frontmatter 鍵中列出。相同工具的 `<tool>.md` 優先。除非 `tools:` 只列出單一工具，否則在此處放置 `expect:` 保護會造成載入錯誤，因此請改為在個別 `<tool>.md` 上放置保護

666* **`_tools.json`**：來自真實伺服器的已保存 `tools/list` 回應，因此 mocked 工具帶有其真實描述和輸入架構，而不是寬鬆的佔位符666* **`_tools.json`**：來自真實伺服器的已保存 `tools/list` 回應，因此 mocked 工具帶有其真實描述和輸入架構，而不是寬鬆的佔位符

667 667

668案例自己的 `mocks/` 目錄使用相同的佈局並逐檔案覆蓋套件的 mocks。668案例自己的 `mocks/` 目錄使用相同的佈局並逐檔案覆蓋套件的 mocks。

669 669

670<h4 id="expect-patterns">

671 Regex patterns in expect

672</h4>

673

674`expect:` 中的 `/regex/` 值使用一種小型方言，Claude Code 會在載入套件時檢查它：

675

676* 字面字元、`.`、跳脫序列（例如 `\d`），以及字元類別（例如 `[a-z]`）

677* 量詞 `*`、`+`、`?` 以及 `{m,n}` 形式，每個都作用於單一字元、跳脫序列或類別

678* 開頭可選的 `^` 與結尾可選的 `$`

679* 僅限旗標 `i` 和 `s`

680

681超出此方言的模式，例如含有群組、選擇（alternation）、反向參照、環視或其他旗標的模式，會使案例無法載入：該案例得分為 0，其錯誤會指出該模式。若要允許多個確切值，請改寫為字面值清單，而不是使用選擇。

682

683每個模式只會檢查到某個最大長度為止的值，較長的值會被視為違反。量詞可能會降低該長度，而開頭的 `^` 會提高該長度，因此請以 `^` 錨定模式，並盡量減少量詞。

684

670<h2 id="troubleshooting">685<h2 id="troubleshooting">

671 Troubleshooting686 疑難排解

672</h2>687</h2>

673 688

674這些是作者最常遇到的問題，按您看到的內容鍵入。689以下是作者最常遇到的問題，依您看到的內容分類。

675 690

676<h3 id="plugin-eval-is-currently-in-early-access">691<h3 id="plugin-eval-is-currently-in-early-access">

677 "plugin eval is currently in early access"692 "plugin eval is currently in early access"

678</h3>693</h3>

679 694

680您的建置早於命令的正式發佈。執行 `claude update`，然後在新工作階段中再次執行命令。695您的建置早於此命令的正式發佈。請執行 `claude update`，然後在新的工作階段中再次執行此命令。

681 696

682<h3 id="plugin-eval-is-currently-unavailable">697<h3 id="plugin-eval-is-currently-unavailable">

683 "plugin eval is currently unavailable"698 "plugin eval is currently unavailable"

684</h3>699</h3>

685 700

686Anthropic 已在伺服器端關閉命令。您的機器上沒有任何內容將其打開；執行 `claude update` 並稍後在新工作階段中重試。701Anthropic 已在伺服器端關閉此命令。您的機器上沒有任何設定能將其重新開啟；請執行 `claude update`，並稍後在新的工作階段中重試。

687 702

688<h3 id="is-not-a-trusted-plugin-directory-and-this-run-cannot-stop-to-ask-you-about-it">703<h3 id="is-not-a-trusted-plugin-directory-and-this-run-cannot-stop-to-ask-you-about-it">

689 "is not a trusted plugin directory, and this run cannot stop to ask you about it"704 "is not a trusted plugin directory, and this run cannot stop to ask you about it"

690</h3>705</h3>

691 706

692這是針對目錄的第一次執行，Claude Code 還不信任，並且因為 stdin 或 stdout 不是終端或您傳遞了 `--json` 而無法詢問。在終端中執行 `claude plugin eval <dir>` 一次並回答提示，或如果您信任 plugin 的程式碼和套件，請傳遞 `--trust-plugin`。請參閱 [What a run can access](#security)。707這是第一次針對 Claude Code 尚未信任的目錄執行，而且由於 stdin 或 stdout 不是終端機，或您傳遞了 `--json`，因此無法詢問您。請在終端機中執行一次 `claude plugin eval <dir>` 並回答提示，或者如果您信任該外掛的程式碼和套件，請傳遞 `--trust-plugin`。請參閱[執行可存取的內容](#security)。

693 708

694<h3 id="git-is-too-old-for-claude-plugin-eval">709<h3 id="git-is-too-old-for-claude-plugin-eval">

695 "is too old for claude plugin eval"710 "is too old for claude plugin eval"

696</h3>711</h3>

697 712

698您 `PATH` 上的 `git` 早於 2.31，所以 `claude plugin eval` 在執行任何案例之前停止並以退出代碼 1 和命名您版本的訊息退出：713您 `PATH` 上的 `git` 早於 2.31，因此 `claude plugin eval` 在執行任何案例之前就已停止，並以代碼 1 結束，同時顯示指出您版本的訊息：

699 714

700```text theme={null}715```text theme={null}

701git 2.30 is too old for claude plugin eval: it ignores the environment configuration (GIT_CONFIG_COUNT, added in git 2.31) that switches off the repository's git hooks and helper programs for the run. Install git 2.31 or newer.716git 2.30 is too old for claude plugin eval: it ignores the environment configuration (GIT_CONFIG_COUNT, added in git 2.31) that switches off the repository's git hooks and helper programs for the run. Install git 2.31 or newer.

702```717```

703 718

704對於每次執行，Claude Code 會關閉 git hooks、認證助手和其他程式，存放庫的 git 設定可以啟動。它透過 git 僅從版本 2.31 讀取的環境設定來執行此操作。較舊的 git 會忽略該設定，因此套件會停止，而不是對那些程式可能執行的執行進行評分。安裝 git 2.31 或更新版本並再次執行套件。719每次執行時，Claude Code 都會關閉 git hook、憑證輔助程式，以及儲存庫的 git 設定可啟動的其他程式。它是透過 git 從 2.31 版起才會讀取的環境設定來達成此目的。較舊的 git 會忽略該設定，因此套件會停止，而不是對那些程式可能執行的執行進行評分。請安裝 git 2.31 或更新版本，然後再次執行套件。

705 720

706在 v2.1.283 之前，`claude plugin eval` 沒有檢查 git 版本，在較舊的 git 上，套件執行時這些程式保持開啟。721在 v2.1.283 之前，`claude plugin eval` 不會檢查 git 版本，在較舊的 git 上，套件執行時這些程式會保持開啟。

707 722

708<h3 id="no-eval-cases-found">723<h3 id="no-eval-cases-found">

709 "No eval cases found"724 "No eval cases found"

710</h3>725</h3>

711 726

712eval 目錄下沒有 `<case>/prompt.md` 或 `<case>/case.yaml` 存在，或您的 `--case` 和 `--tag` 篩選器沒有匹配任何案例。從 plugin 根目錄執行，或執行 `claude plugin eval init` 以建立套件。727目前生效的 eval 目錄下不存在任何 `<case>/prompt.md` 或 `<case>/case.yaml`，或是您的 `--case` 和 `--tag` 篩選器沒有符合任何案例。請從外掛根目錄執行，或執行 `claude plugin eval init` 以建立套件。

713 728

714<h3 id="the-baseline-arm-shows-no-plugin-or-delta-is-zero">729<h3 id="the-baseline-arm-shows-no-plugin-or-delta-is-zero">

715 The baseline arm shows no plugin, or delta is zero730 基準 arm 未顯示外掛，或 delta 為零

716</h3>731</h3>

717 732

718如果摘要沒有 `W/OUT` 列，或案例失敗並顯示「ablation requested but no plugin resolved」，則沒有為案例找到 plugin。如果每個案例都透過 `context.history_file` 繼續進行文字記錄，則缺少列是預期的，因為這些案例預設執行 [one arm](#compare-against-a-no-plugin-baseline)。否則，將 `plugins: ["../.."]` 新增到案例，給出從案例目錄到 plugin 目錄的路徑。733如果摘要中沒有 `W/OUT` 欄，或案例失敗並顯示「ablation requested but no plugin resolved」，常見原因是沒有為該案例找到外掛。如果每個案例都透過 `context.history_file` 接續逐字稿，則缺少該欄是預期的，因為這些案例[預設只執行一個 arm](#compare-against-a-no-plugin-baseline)。否則，請將 `plugins: ["../.."]` 新增到案例中，提供從案例目錄到外掛目錄的路徑。

719 734

720如果 plugin 確實載入並且 `Δ` 仍然接近零，您的 `tool_used: Skill` 評分器失敗，這通常是真實發現，意味著 skill 的 `description` 不會在提示的措辭上觸發。調整描述並重新執行相同的套件。735如果外掛確實已載入，但 `Δ` 仍接近零，且您的 `tool_used: Skill` 評分器失敗，這通常是一個真實的發現，表示該 skill 的 `description` 不會因提示詞的措辭而觸發。請調整描述，然後重新執行相同的套件。

721 736

722<h3 id="agent-type-’-’-not-found-for-one-of-your-plugin’s-agents">737<h3 id="agent-type-’-’-not-found-for-one-of-your-plugin’s-agents">

723 "Agent type '...' not found" for one of your plugin's agents738 您外掛的某個 agent 出現 "Agent type '...' not found"

724</h3>739</h3>

725 740

726根據預設，每個案例都會同時執行您的 plugin 和不執行它，不執行它的執行是 [no-plugin baseline](#the-no-plugin-baseline)。當 Claude 在基準執行中分派您的 plugin 的其中一個代理時，Agent 工具呼叫失敗，並顯示 `Agent type '<plugin>:<agent-name>' not found. Available agents: ...`。該列表僅命名不含 plugin 的代理，例如 [built-in subagents](/docs/zh-TW/sub-agents#built-in-subagents)。741根據預設，每個案例都會在載入您的外掛和不載入外掛的情況下各執行一次，而不載入外掛的執行即為[無外掛基準](#the-no-plugin-baseline)。當 Claude 在基準執行中分派您外掛的某個 agent 時，Agent 工具呼叫會失敗，並顯示 `Agent type '<plugin>:<agent-name>' not found. Available agents: ...`。該清單只列出不需外掛即存在的 agent，例如[內建 subagent](/docs/zh-TW/sub-agents#built-in-subagents)。

727 742

728該錯誤是預期的，因為 `Δ` 將您的 plugin 執行與基準進行比較。在 JSON 結果中，基準執行位於 `cases[].arms.without` 下。743此錯誤是預期的，因為 `Δ` 會將您外掛的執行與基準進行比較。在 JSON 結果中，基準執行位於 `cases[].arms.without` 下。

729 744

730在載入您的 plugin 的執行中，在 `allowed_tools` 中列出 `Agent` 的案例可以透過其命名空間名稱分派您的 plugin 的其中一個代理，例如 `my-plugin:code-reviewer` 用於名為 `my-plugin` 的 plugin 中的 `code-reviewer` 代理。若要跳過基準執行，請傳遞 `--ablation none`。745在載入您外掛的執行中，在 `allowed_tools` 中列出 `Agent` 的案例可以透過命名空間名稱分派您外掛的某個 agent，例如名為 `my-plugin` 的外掛中的 `code-reviewer` agent 為 `my-plugin:code-reviewer`。若要略過基準執行，請傳遞 `--ablation none`。

731 746

732<h3 id="everything-scores-zero-although-the-right-files-were-produced">747<h3 id="everything-scores-zero-although-the-right-files-were-produced">

733 Everything scores zero although the right files were produced748 已產生正確的檔案，但所有項目都評分為零

734</h3>749</h3>

735 750

736您的評分器目標 `files`（建立的路徑列表），當您指的是檔案的內容時。使用 `{ source: file, path: <path> }` 作為 `target` 或 `focus`。另外，`file_exists` 僅計算執行期間建立的檔案，因此 scaffold 建立或 Claude 僅編輯的檔案對它不可見；評分其內容，或在 `Edit` 上使用 `tool_used`。751您的評分器以 `files`（已建立路徑的清單）為目標，但您實際想要的是檔案的內容。請使用 `{ source: file, path: <path> }` 作為 `target` 或 `focus`。

752

753另外，`file_exists` 只計算執行期間建立的檔案，因此由 scaffold 建立或 Claude 僅編輯過的檔案對它而言是不可見的；請對其內容評分，或對 `Edit` 使用 `tool_used`。

737 754

738<h3 id="a-regex-over-the-trace-doesn’t-match-text-i-can-see">755<h3 id="a-regex-over-the-trace-doesn’t-match-text-i-can-see">

739 A regex over the trace doesn't match text I can see756 針對 trace 的正規表示式無法比對我看得到的文字

740</h3>757</h3>

741 758

742* **錯誤的目標**：預設 `target` 是 `last_message`，不是 trace。759* **目標錯誤**：預設的 `target` 是 `last_message`，而不是 trace。

743* **JSON 逸出**：當您確實目標 `trace` 時，它是每行 JSON，因此引號顯示為 `\"`。760* **JSON 逸出**：當您確實以 `trace` 為目標時，它是每行一筆 JSON，因此引號會顯示為 `\"`。

744* **正規表達式語法**：正規表達式使用 JavaScript 語法，因此在 `flags` 中放置 `i` 而不是編寫 `(?i)`。761* **正規表示式語法**：正規表示式使用 JavaScript 語法，因此請在 `flags` 中放入 `i`，而不是寫成 `(?i)`。

745 762

746<h3 id="tools-are-denied-mcp-tools-are-missing-or-bash-won’t-run">763<h3 id="tools-are-denied-mcp-tools-are-missing-or-bash-won’t-run">

747 Tools are denied, MCP tools are missing, or Bash won't run764 工具遭拒、MCP 工具遺失，或 Bash 無法執行

748</h3>765</h3>

749 766

750超過唯讀集的任何內容都需要您的授予，例如 `--allow-tools Bash Write`。您的個人 MCP 伺服器永遠不會在執行中載入。plugin 自己的伺服器不會啟動，除非您 [opt in](#mock-mcp-servers)，其工具也需要 `--allow-tools "mcp__plugin_<plugin>_<server>__*"` 授予；mocked 工具不需要任何一個。767唯讀集合以外的任何項目都需要您授予權限，例如 `--allow-tools Bash Write`。您的個人 MCP 伺服器永遠不會在執行中載入。外掛本身的伺服器除非您[選擇啟用](#mock-mcp-servers)否則不會啟動，而且其工具還需要 `--allow-tools "mcp__plugin_<plugin>_<server>__*"` 授權；mock 工具則兩者都不需要。

751 768

752<h3 id="the-run-exits-1-but-the-results-look-fine">769<h3 id="the-run-exits-1-but-the-results-look-fine">

753 The run exits 1 but the results look fine770 執行以 1 結束，但結果看起來正常

754</h3>771</h3>

755 772

756預設 `--threshold` 是 1.0，因此當任何案例評分低於完美時，命令退出 1。設定與您的標準相符的閾值。退出 1 也涵蓋案例檔案無法載入，在表格上方的 stderr 上報告。773預設的 `--threshold` 是 1.0，因此只要任何案例的分數低於滿分，命令就會以 1 結束。請設定符合您要求分數的閾值。結束代碼 1 也涵蓋無法載入的案例檔案，這會在表格上方的 stderr 中回報。

757 774

758<h3 id="json-output-path-must-end-in-json">775<h3 id="json-output-path-must-end-in-json">

759 `--json output path must end in .json`776 `--json output path must end in .json`

760</h3>777</h3>

761 778

762您將目標放在 `--json` 之後，因此它被讀取為輸出路徑。將目標放在首位，如 `claude plugin eval . --json`，或給 `--json` 一個明確的 `.json` 路徑。779您將目標放在 `--json` 之後，因此它被讀取為輸出路徑。請將目標放在前面，例如 `claude plugin eval . --json`，或為 `--json` 提供明確的 `.json` 路徑。

763 780

764<h3 id="a-grader-shows-passed-false-under-a-run-that-scored-1-0">781<h3 id="a-grader-shows-passed-false-under-a-run-that-scored-1-0">

765 A grader shows passed: false under a run that scored 1.0782 在評分為 1.0 的執行下，評分器顯示 passed: false

766</h3>783</h3>

767 784

768該評分器在兩個 arm 執行中按設計從分數中排除，其 `scored` 欄位為 `false`。請參閱 [Score against the no-plugin baseline](#compare-against-a-no-plugin-baseline)。785在雙 arm 執行中，該評分器依設計會被排除在分數之外，其 `scored` 欄位為 `false`。請參閱[與無外掛基準比較評分](#compare-against-a-no-plugin-baseline)。

769 786

770<h3 id="runs-fail-with-a-usage-limit-or-rate-limit-error-partway-through">787<h3 id="runs-fail-with-a-usage-limit-or-rate-limit-error-partway-through">

771 Runs fail with a usage-limit or rate-limit error partway through788 執行中途因用量上限或速率限制錯誤而失敗

789</h3>

790

791如果您的帳戶在套件執行期間達到其方案的用量上限或 API 速率限制，之後的每次執行都會以該錯誤結束，並根據其產生的內容進行評分，通常會得到 0 分。套件仍會完成，且不會被標記為 `partial`，因此結果可能看起來像是迴歸。在信任分數之前，請先檢查 `NOTES` 欄或 JSON 中的 `cases[].arms.with[].error` 是否有限制訊息，然後在限制重設後重新執行；如果需要維持在限制之內，請使用 `--runs 1` 或 `--case` 篩選器。

792

793<h3 id="mock-call-budget-exceeded">

794 "mock call budget exceeded"

772</h3>795</h3>

773 796

774如果您的帳戶在套件執行時達到其方案的使用限制或 API 速率限制，每次後續執行都會以該錯誤結束，根據其產生的內容進行評分，通常評分為 0。套件仍然完成並未標記為 `partial`，因此結果可能看起來像迴歸。在信任分數之前檢查 `NOTES` 列或 JSON 中的 `cases[].arms.with[].error` 以獲取限制訊息，然後在限制重置後重新執行，如果您需要保持在其下方，則使用 `--runs 1` 或 `--case` 篩選器。797一次執行中的每個 `type: agent` [mock](#mock-mcp-servers) 都會共用一份呼叫預算，其大小為案例 `max_turns` 的四倍，以預設值 10 計算即為 40 次呼叫。從 `.replay/` 錄製內容回應的呼叫也會計入，而案例的 `mock budget` 進度行會顯示該預算。超出預算的呼叫會中止執行，並以此原因記為 0 分，因此對於會多次呼叫 agent mock 的 skill，請在案例中提高 `max_turns`。

775 798

776<h3 id="runs-time-out-or-hit-the-turn-cap">799<h3 id="runs-time-out-or-hit-the-turn-cap">

777 Runs time out or hit the turn cap800 執行逾時或達到回合上限

778</h3>801</h3>

779 802

780預設值是 10 轉和 300 秒。在案例中提高 `max_turns` 和 `timeout_seconds` 以進行需要更多的任務，並使用 `--max-cost-usd` 作為成本上限而不是緊密的每次執行限制。803預設值為 10 個回合和 300 秒。對於需要更多資源的任務，請在案例中提高 `max_turns` 和 `timeout_seconds`，並使用 `--max-cost-usd` 作為成本上限，而不是設定嚴格的每次執行限制。

781 804

782<h2 id="see-also">805<h2 id="see-also">

783 See also806 See also

plugins/cli-reference.md +59 −37

Details

129 129

130使用錯誤（例如無效的 `--scope`）不列印結果行，結束 `1`，stderr 上有原因。130使用錯誤（例如無效的 `--scope`）不列印結果行，結束 `1`，stderr 上有原因。

131 131

132<h4 id="json-result-for-marketplace-commands">

133 市集命令的 JSON 結果

134</h4>

135

136在 `plugin marketplace add`、`plugin marketplace remove` 和 `plugin marketplace update` 上，`--json` 會在 stdout 的最後一行列印一個 JSON 物件，其中包含 `command`、`outcome` 和 `message` 欄位。以下是 `claude plugin marketplace remove your-marketplace --json` 的結果：

137

138```json theme={null}

139{"command":"marketplace-remove","outcome":"ok","marketplace":"your-marketplace","message":"Successfully removed marketplace: your-marketplace"}

140```

141

142`command` 值為 `marketplace-add`、`marketplace-remove` 或 `marketplace-update`。以下欄位僅在適用時出現：

143

144* `marketplace`：命令所作用的市集名稱

145* `failureCode`：說明命令失敗原因的代碼，例如 `invalid_source`

146

147當引數為 [保留名稱](/docs/zh-TW/plugins/marketplace-reference#reserved-names) `anthropic-plugin-directory` 時，`plugin marketplace add` 和 `plugin marketplace remove` 可能不列印結果行，因此對於該名稱，請檢查結束代碼。

148

132<h4 id="accept-a-displayed-install-command">149<h4 id="accept-a-displayed-install-command">

133 接受顯示的安裝命令150 接受顯示的安裝命令

134</h4>151</h4>

672* `target`：Claude Code 驗證的解析路徑689* `target`：Claude Code 驗證的解析路徑

673* `manifest`：manifest 自己的結果，或沒有 manifest 的執行為 `null`690* `manifest`：manifest 自己的結果，或沒有 manifest 的執行為 `null`

674* `contents`：每個檔案的結果，命名其 `file` 並帶有 `errors`、`warnings` 和 `notes` 陣列691* `contents`：每個檔案的結果，命名其 `file` 並帶有 `errors`、`warnings` 和 `notes` 陣列

692 * `gatingHooks`：每個可以拒絕動作的 [mod](/docs/zh-TW/plugins/mods/overview) hook（例如 `tool.call` hook）是否具有 [`.catch` 處理常式](/docs/zh-TW/plugins/mods/events#handle-a-hook-that-fails)。每個項目提供 `module`、`pattern`、`hook` 和 `hasCatch`。需要 Claude Code v2.1.290 或更新版本

675 693

676在結束 `2` 時，命令不向 stdout 寫入任何內容。錯誤訊息進入 stderr。694在結束 `2` 時，命令不向 stdout 寫入任何內容。錯誤訊息進入 stderr。

677 695

679 claude plugin marketplace 命令697 claude plugin marketplace 命令

680</h2>698</h2>

681 699

682從 shell 執行 `claude plugin marketplace <subcommand>` 以新增、列出、重新整理和移除您安裝 plugins 的市場。700從 shell 執行 `claude plugin marketplace <subcommand>` 以新增、列出、重新整理和移除您安裝外掛所用的市集。

683 701

684* **結束代碼**：這些子命令遵循 plugin 命令的 [exit-code convention](#claude-plugin-commands)702* **結束代碼**：這些子命令遵循外掛命令的[結束代碼慣例](#claude-plugin-commands)

685* **範圍**：它們的 `--scope` 旗標沒有 `-s` 短形式703* **範圍**：它們的 `--scope` 旗標沒有 `-s` 短形式

686 704

687有關市場是什麼以及 Claude Code 如何快取它，請參閱 [Plugin 載入參考](/docs/zh-TW/plugins/loading)。705有關市集是什麼以及 Claude Code 如何快取它，請參閱[外掛載入參考](/docs/zh-TW/plugins/loading)。

688 706

689<h3 id="plugin-marketplace-add">707<h3 id="plugin-marketplace-add">

690 plugin marketplace add708 plugin marketplace add

691</h3>709</h3>

692 710

693從 GitHub 儲存庫、git URL、託管 `marketplace.json` 或本地路徑新增市場，並在設定檔中宣告它。711從 GitHub 儲存庫、git URL、託管的 `marketplace.json` 或本地路徑新增市集，並在設定檔中宣告它。

694 712

695新增後，Claude Code 安裝您已安裝 plugins 遺漏的任何 [dependencies](/docs/zh-TW/plugins/dependencies)。713新增後，Claude Code 會安裝您已安裝的外掛所缺少的任何[相依套件](/docs/zh-TW/plugins/dependencies)。

696 714

697```bash theme={null}715```bash theme={null}

698claude plugin marketplace add <source> [options]716claude plugin marketplace add <source> [options]

700 718

701| 旗標 | 說明 |719| 旗標 | 說明 |

702| :- | :- |720| :- | :- |

705| `--claudeai` | 將引數讀作 [claude.ai 上託管的市場](/docs/zh-TW/plugins/install#add-from-claude-ai) 的名稱，而不是來源。需要 Claude Code v2.1.273 或更新版本 |723| `--claudeai` | 將引數讀作 [claude.ai 上託管的市集](/docs/zh-TW/plugins/install#add-from-claude-ai) 的名稱，而不是來源。需要 Claude Code v2.1.273 或更新版本 |

724| `--json` | 將命令是否成功及其訊息，以一個 JSON 物件的形式列印在 stdout 的最後一行，採用 [JSON 結果格式](#plugin-json-result)。搭配 `--claudeai` 時無效。需要 Claude Code v2.1.287 或更新版本 |

706 725

707`<source>` 採用下表中的任何形式，其形式決定來源類型以及 Claude Code 如何擷取市場。對於結果來源物件，請參閱 [市場參考](/docs/zh-TW/plugins/marketplace-reference)。726`<source>` 採用下表中的任何形式，其形式決定來源類型以及 Claude Code 如何擷取市集。對於結果來源物件，請參閱[市集參考](/docs/zh-TW/plugins/marketplace-reference)。

708 727

709| 您輸入 | 來源類型 | Claude Code 如何擷取它 |728| 您輸入 | 來源類型 | Claude Code 如何擷取它 |

710| :- | :- | :- |729| :- | :- | :- |

718 737

719對於其複製 URL 不帶 `.git` 尾碼的主機（例如 AWS CodeCommit），改為在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 中將市場新增為 git 項目。Claude Code 複製 git 項目，無論其 URL 是否以 `.git` 結尾。738對於其複製 URL 不帶 `.git` 尾碼的主機（例如 AWS CodeCommit），改為在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 中將市集新增為 git 項目。Claude Code 複製 git 項目，無論其 URL 是否以 `.git` 結尾。

720 739

721Claude Code 也複製具有嵌套子群組的 `gitlab.com` URL，例如 `https://gitlab.com/group/subgroup/project`。740Claude Code 也複製具有嵌套子群組的 `gitlab.com` URL，例如 `https://gitlab.com/group/subgroup/project`。

722 741

723新增市場並與專案共享：742新增市集並與專案共享：

724 743

725```bash theme={null}744```bash theme={null}

726claude plugin marketplace add your-org/your-marketplace --scope project745claude plugin marketplace add your-org/your-marketplace --scope project

727```746```

728 747

729Claude Code 列印 `Successfully added marketplace: your-marketplace (declared in project settings)`，使用市場自己的 manifest 中的 `name`。重複新增或無效來源列印以下結果之一：748Claude Code 列印 `Successfully added marketplace: your-marketplace (declared in project settings)`，使用市集自己的 manifest 中的 `name`。重複新增或無效來源則會列印以下結果之一：

730 749

731* **市場已在磁碟上**：輸出為 `Marketplace 'your-marketplace' already on disk — declared in project settings`，結束代碼為 `0`750* **市集已在磁碟上**：輸出為 `Marketplace 'your-marketplace' already on disk — declared in project settings`，結束代碼為 `0`

732* **無法識別的來源**：輸出為 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`，結束代碼為 `1`751* **無法識別的來源**：輸出為 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`，結束代碼為 `1`

733* **裸主機，例如 `gitlab.example.com/team/plugins`**：新增失敗，因為無效的 `owner/repo` 速記，訊息告訴您新增 `https://` 或使用本地路徑752* **裸主機，例如 `gitlab.example.com/team/plugins`**：新增失敗，因為是無效的 `owner/repo` 速記，訊息告訴您新增 `https://` 或使用本地路徑

734 753

735按 `claude plugin marketplace list` 的 `From claude.ai:` 部分中列印的名稱新增 [claude.ai 上託管的市場](/docs/zh-TW/plugins/install#add-from-claude-ai)：754按 `claude plugin marketplace list` 的 `From claude.ai:` 部分中列印的名稱新增 [claude.ai 上託管的市集](/docs/zh-TW/plugins/install#add-from-claude-ai)：

736 755

737```bash theme={null}756```bash theme={null}

738claude plugin marketplace add --claudeai claudeai-organization-library757claude plugin marketplace add --claudeai claudeai-organization-library

739```758```

740 759

741使用 `--claudeai`，命令拒絕 `--scope` 和 `--sparse`。市場為您的帳戶託管，未在設定檔中宣告，因此您無法透過專案的 `.claude/settings.json` 共享它。760使用 `--claudeai` 時，命令拒絕 `--scope` 和 `--sparse`。市集為您的帳戶託管，未在設定檔中宣告，因此您無法透過專案的 `.claude/settings.json` 共享它。

742 761

743<h3 id="plugin-marketplace-list">762<h3 id="plugin-marketplace-list">

744 plugin marketplace list763 plugin marketplace list

745</h3>764</h3>

746 765

747列出您新增的每個市場及其來源。766列出您新增的每個市集及其來源。

748 767

749```bash theme={null}768```bash theme={null}

750claude plugin marketplace list [options]769claude plugin marketplace list [options]

754| :- | :- |773| :- | :- |

756 775

757Claude Code 列印 `Configured marketplaces:` 和每個市場一個 `Source:` 行，或 `No marketplaces configured`。776Claude Code 列印 `Configured marketplaces:` 和每個市集一個 `Source:` 行，或 `No marketplaces configured`。

758 777

759使用 `--json`，Claude Code 列印一個陣列，每個市場一個物件，帶有下面的欄位。每個欄位都是字串。778使用 `--json` 時，Claude Code 列印一個陣列，每個市集一個物件，帶有下面的欄位。每個欄位都是字串。

760 779

761| 欄位 | 說明 |780| 欄位 | 說明 |

762| :- | :- |781| :- | :- |

766| `url` | 複製或擷取 URL。僅 `git` 和 `url` 來源 |785| `url` | 複製或擷取 URL。僅 `git` 和 `url` 來源 |

768| `ref` | 固定的分支或標籤。`github` 和 `git` 來源，僅當固定時 |787| `ref` | 固定的分支或標籤。`github` 和 `git` 來源，僅當固定時 |

770 789

771已新增的 [claude.ai 市場](/docs/zh-TW/plugins/install#add-from-claude-ai) 沒有本地複製，因此其項目帶有其 claude.ai 識別碼 `marketplaceId` 和 `organizationUuid`，代替 `installLocation`。它也帶有 `scope`（當記錄時）和 `status`。790已新增的 [claude.ai 市集](/docs/zh-TW/plugins/install#add-from-claude-ai) 沒有本地複製，因此其項目帶有其 claude.ai 識別碼 `marketplaceId` 和 `organizationUuid`，代替 `installLocation`。它也帶有 `scope`（當有記錄時）和 `status`。

772 791

773如果您的終端工作階段 [從您的 claude.ai 帳戶同步 plugins](/docs/zh-TW/plugins/loading#synced-plugins)，文字列表以 `From claude.ai:` 部分結尾。該部分命名 claude.ai 為您的帳戶列出的市場，您未新增的市場，包括基於 git 的和託管的。它需要 Claude Code v2.1.273 或更新版本。792如果您的終端機工作階段[從您的 claude.ai 帳戶同步外掛](/docs/zh-TW/plugins/loading#synced-plugins)，文字列表以 `From claude.ai:` 部分結尾。該部分列出 claude.ai 為您的帳戶列出但您尚未新增的市集，包括基於 git 的和託管的。它需要 Claude Code v2.1.273 或更新版本。

774 793

775若要從該部分新增市場，請參閱 [從 claude.ai 新增市場](/docs/zh-TW/plugins/install#add-from-claude-ai)。794若要從該部分新增市集，請參閱[從 claude.ai 新增市集](/docs/zh-TW/plugins/install#add-from-claude-ai)。

776 795

777`--json` 輸出僅涵蓋已配置的市場，並將部分留出。796`--json` 輸出僅涵蓋已設定的市集，並省略該部分。

778 797

779<h3 id="plugin-marketplace-remove">798<h3 id="plugin-marketplace-remove">

780 plugin marketplace remove799 plugin marketplace remove

781</h3>800</h3>

782 801

783從您的設定中移除市場的宣告。`rm` 是 `remove` 的別名。802從您的設定中移除市集的宣告。`rm` 是 `remove` 的別名。

784 803

785<Warning>804<Warning>

786 當您從最後一個宣告它的範圍移除市場時，Claude Code 也刪除其快取並卸載您從它安裝的每個 plugin。它也刪除它們已儲存的 [options 和 secrets](/docs/zh-TW/plugins/manifest-reference#user-configuration) 和 [資料](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)（如果可以的話）。805 當您從最後一個宣告它的範圍移除市集時，Claude Code 也會刪除其快取並解除安裝您從它安裝的每個外掛。它也會盡可能刪除它們已儲存的[選項和密鑰](/docs/zh-TW/plugins/manifest-reference#user-configuration)和[資料](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)。

787 806

788 若要重新整理市場而不失去其 plugins，改為執行 `plugin marketplace update`。807 若要重新整理市集而不失去其外掛，請改為執行 `plugin marketplace update`。

789</Warning>808</Warning>

790 809

791```bash theme={null}810```bash theme={null}

792claude plugin marketplace remove <name> [options]811claude plugin marketplace remove <name> [options]

793```812```

794 813

795`<name>` 是 `plugin marketplace list` 顯示的市場名稱，而不是您傳遞給 `add` 的來源。814`<name>` 是 `plugin marketplace list` 顯示的市集名稱，而不是您傳遞給 `add` 的來源。

796 815

797| 旗標 | 說明 |816| 旗標 | 說明 |

798| :- | :- |817| :- | :- |

819| `--json` | 將命令是否成功及其訊息，以一個 JSON 物件的形式列印在 stdout 的最後一行，採用 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.287 或更新版本 |

800 820

801從每個範圍移除市場：821從每個範圍移除市集：

802 822

803```bash theme={null}823```bash theme={null}

804claude plugin marketplace remove your-marketplace824claude plugin marketplace remove your-marketplace

805```825```

806 826

807Claude Code 列印 `Successfully removed marketplace: your-marketplace`。當命令卸載 plugins 時，輸出在例如 `Also uninstalled 2 plugins from this marketplace:` 的行下列出它們。若要再次使用其中一個，請新增市場並重新安裝 plugin。827Claude Code 列印 `Successfully removed marketplace: your-marketplace`。當命令解除安裝外掛時，輸出會在例如 `Also uninstalled 2 plugins from this marketplace:` 的行下列出它們。若要再次使用其中一個，請重新新增市集並重新安裝該外掛。

808 828

809如果您限定範圍到不宣告市場的設定檔，命令失敗，訊息為 `Marketplace 'your-marketplace' is not declared in project settings. Omit --scope to remove it from all scopes.`829如果您將範圍限定到未宣告該市集的設定檔，命令會失敗，訊息為 `Marketplace 'your-marketplace' is not declared in project settings. Omit --scope to remove it from all scopes.`

810 830

811<h3 id="plugin-marketplace-update">831<h3 id="plugin-marketplace-update">

812 plugin marketplace update832 plugin marketplace update

813</h3>833</h3>

814 834

815重新整理一個市場或每個市場，從其來源擷取新 plugins 和版本。使用分支或標籤 `ref` 新增的市場更新到該 ref 的最新提交，而不是儲存庫的預設分支。835重新整理一個市集或每個市集，從其來源擷取新外掛和版本。使用分支或標籤 `ref` 新增的市集會更新到該 ref 的最新提交，而不是儲存庫的預設分支。

816 836

817```bash theme={null}837```bash theme={null}

818claude plugin marketplace update [name]838claude plugin marketplace update [name] [options]

819```839```

820 840

821命令除了 `--help` 外不接受任何旗標。841| 旗標 | 說明 |

842| :- | :- |

843| `--json` | 將命令是否成功及其訊息，以一個 JSON 物件的形式列印在 stdout 的最後一行，採用 [JSON 結果格式](#plugin-json-result)。未指定名稱時，命令會拒絕 `--json` 並以 `1` 結束。需要 Claude Code v2.1.287 或更新版本 |

822 844

823重新整理一個市場：845重新整理一個市集：

824 846

825```bash theme={null}847```bash theme={null}

826claude plugin marketplace update your-marketplace848claude plugin marketplace update your-marketplace

827```849```

828 850

829Claude Code 列印 `Successfully updated marketplace: your-marketplace`。當您省略名稱時，它列印計數，例如 `Successfully updated 2 marketplaces`。沒有新增市場時，它列印 `No marketplaces configured` 並結束 `0`。851Claude Code 列印 `Successfully updated marketplace: your-marketplace`。當您省略名稱時，它列印計數，例如 `Successfully updated 2 marketplaces`。

830 852

831<h2 id="plugin-in-a-session">853<h2 id="plugin-in-a-session">

832 /plugin 在工作階段中854 /plugin 在工作階段中

plugins/components.md +1 −1

Details

1034]1034]

1035```1035```

1036 1036

1037命令在 shell 中執行，在工作階段啟動的工作目錄中。1037命令在 shell 中執行，位於工作階段目前的工作目錄。它以您完整的使用者權限執行，且在 [沙箱](/docs/zh-TW/sandboxing) 之外執行。

1038 1038

1039監視器的命令在其啟動位置和可以參考的內容方面受到限制：1039監視器的命令在其啟動位置和可以參考的內容方面受到限制：

1040 1040

plugins/marketplace-reference.md +4 −1

Details

52* **Claude Code 用於不來自 marketplace 的外掛程式的名稱**：`inline` 用於使用 [`--plugin-dir`](/docs/zh-TW/cli-reference) 載入的外掛程式，`builtin` 用於內建外掛程式，`skills-dir` 用於從 [`.claude/skills/`](/docs/zh-TW/skills) 自動載入的外掛程式，`synced` 用於從您的 claude.ai 帳戶同步的外掛程式。`claude-plugin-test` 也被保留。`skills-dir` 也在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中顯示為 `{"source": "skills-dir"}`，在 [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists) 下描述。52* **Claude Code 用於不來自 marketplace 的外掛程式的名稱**：`inline` 用於使用 [`--plugin-dir`](/docs/zh-TW/cli-reference) 載入的外掛程式，`builtin` 用於內建外掛程式，`skills-dir` 用於從 [`.claude/skills/`](/docs/zh-TW/skills) 自動載入的外掛程式，`synced` 用於從您的 claude.ai 帳戶同步的外掛程式。`claude-plugin-test` 也被保留。`skills-dir` 也在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中顯示為 `{"source": "skills-dir"}`，在 [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists) 下描述。

53* **`npm`、`pip`、`uv`、`cargo`、`github` 和 `gh`**：以任何大小寫保留。此檢查需要 Claude Code v2.1.275 或更新版本。53* **`npm`、`pip`、`uv`、`cargo`、`github` 和 `gh`**：以任何大小寫保留。此檢查需要 Claude Code v2.1.275 或更新版本。

54* **以 `claudeai-` 開頭的名稱**：為託管在 claude.ai 上的 marketplace 保留。`claude plugin marketplace add` 拒絕任何其他使用一個的 marketplace，錯誤為 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`。54* **以 `claudeai-` 開頭的名稱**：為託管在 claude.ai 上的 marketplace 保留。`claude plugin marketplace add` 拒絕任何其他使用一個的 marketplace，錯誤為 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`。

55* **已註冊 GitHub marketplace 的下載資料夾 `<owner>-<repo>`**：對於從 `github` 來源（例如 `acme/x-tools`）新增的 marketplace，無論該 marketplace 本身的 `name` 為何，Claude Code 都會透過名為 `acme-x-tools` 的資料夾下載它。當該 marketplace 以 `acme-x-tools` 以外的名稱註冊時，`claude plugin marketplace add` 會在下載另一個名為 `acme-x-tools` 的 marketplace 後拒絕它，並報告 `Can't use the marketplace name "acme-x-tools"`。此檢查需要 Claude Code v2.1.290 或更新版本。

55 56

56當已註冊的 marketplace 因其名稱模仿官方名稱而停止載入時，`claude plugin list` 和 `/plugin` 報告 `Claude Code refuses the marketplace name "<name>"`。該訊息告訴您移除 marketplace。移除它也會解除安裝其外掛程式並刪除其已儲存的資料。此具名拒絕訊息需要 Claude Code v2.1.282 或更新版本。57當已註冊的 marketplace 因其名稱模仿官方名稱而停止載入時，`claude plugin list` 和 `/plugin` 報告 `Claude Code refuses the marketplace name "<name>"`。該訊息告訴您移除 marketplace。移除它也會解除安裝其外掛程式並刪除其已儲存的資料。此具名拒絕訊息需要 Claude Code v2.1.282 或更新版本。

57 58

498| `Claude Code cannot install plugin "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".` | 錯誤 | `plugins[i].name` |499| `Claude Code cannot install plugin "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".` | 錯誤 | `plugins[i].name` |

499| `Duplicate plugin name "x" found in marketplace` | 錯誤 | 兩個項目共享一個 `name` |500| `Duplicate plugin name "x" found in marketplace` | 錯誤 | 兩個項目共享一個 `name` |

500| `plugins.i.source: Invalid input` | 錯誤 | 該項目的 `source` 不符合任何類型。請參閱[來源上的無效輸入](#invalid-input-on-a-source) |501| `plugins.i.source: Invalid input` | 錯誤 | 該項目的 `source` 不符合任何類型。請參閱[來源上的無效輸入](#invalid-input-on-a-source) |

502| `plugins.i.source: Invalid string: must start with "./"` | 錯誤 | 缺少開頭 `./` 的相對路徑 `source`。在 v2.1.285 之前，此錯誤會改為列印 `Invalid input` |

501| `plugins[i].source: Path contains "..": <path>` | 錯誤 | 逃逸 marketplace 根目錄的相對 `source` |503| `plugins[i].source: Path contains "..": <path>` | 錯誤 | 逃逸 marketplace 根目錄的相對 `source` |

502| `source.source: 'unsupported' is a parse-time placeholder and cannot be authored` | 錯誤 | `plugins[i].source` |504| `source.source: 'unsupported' is a parse-time placeholder and cannot be authored` | 錯誤 | `plugins[i].source` |

503| `Plugin "x" sets headersHelper but is not "strict": false` | 錯誤 | `plugins[i].headersHelper`，在 `archive` 項目上 |505| `Plugin "x" sets headersHelper but is not "strict": false` | 錯誤 | `plugins[i].headersHelper`，在 `archive` 項目上 |

524 526

525`source` 上的 `Invalid input` 表示該物件不符合任何來源類型。檢查這些原因：527`source` 上的 `Invalid input` 表示該物件不符合任何來源類型。檢查這些原因：

526 528

527* 不以 `./` 開頭的相對路徑，除了 `"."` 或 [bare name](#relative-path-plugin-source)

528* 包含 `..` 的 `npm` `package`529* 包含 `..` 的 `npm` `package`

529* 不是[外掛程式來源](#plugin-sources)之一的 `source` 類型530* 不是[外掛程式來源](#plugin-sources)之一的 `source` 類型

530* 已知類型但缺少必需欄位或類型錯誤，例如沒有 `repo` 的 `github`531* 已知類型但缺少必需欄位或類型錯誤，例如沒有 `repo` 的 `github`

531 532

533不以 `./` 開頭的相對路徑（`"."` 或 [`metadata.pluginRoot` 下的 bare name](#relative-path-plugin-source) 除外）會以 `Invalid string: must start with "./"` 失敗。在 v2.1.285 之前，它會像上述原因一樣列印 `Invalid input`。

534

532<h3 id="failures-that-validation-doesn’t-catch">535<h3 id="failures-that-validation-doesn’t-catch">

533 驗證未捕捉的失敗536 驗證未捕捉的失敗

534</h3>537</h3>

plugins/mods/admin.md +57 −57

Details

22</Note>22</Note>

23 23

24<h2 id="stop-user-installed-mods-from-loading">24<h2 id="stop-user-installed-mods-from-loading">

~~25 停止使用者安裝的 mods 載入~~25 停止使用者安裝的 mod 載入

26</h2>26</h2>

27 27

28若要防止使用者帶來的每個 mod 載入，請在[內建防護](#know-what-happens-by-default)上設定 `allowManagedModsOnly` 選項，這是一個政策 mod，Claude Code 在使用者安裝的每個 mod 之前載入。該選項位於受管設定中的 `pluginConfigs` 下，由 `cc-plugin-sec-default@builtin` 鍵入：28若要防止使用者帶來的每個 mod 執行其 hook，請在[內建防護](#know-what-happens-by-default)上設定 `allowManagedModsOnly` 選項，這是一個原則 mod，Claude Code 會在使用者安裝的每個 mod 之前載入它。該選項位於受管設定中的 `pluginConfigs` 下，以 `cc-plugin-sec-default@builtin` 為鍵：

29 29

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

31{31{

39}39}

40```40```

41 41

~~42設定受管設定中的選項後：~~42在受管設定中設定此選項後：

43 43

44* **使用者帶來的任何 mod 都不會載入**：這涵蓋使用者安裝的外掛程式中的 mod、使用 `--plugin-dir` 載入的 mod，以及 [Claude 在工作階段期間編寫的 mod](/docs/zh-TW/plugins/mods/create#ask-claude-for-a-mod)44* **使用者帶來的任何 mod 都不會執行其 hook**：這涵蓋使用者安裝的外掛中的 mod、使用 `--plugin-dir` 載入的 mod，以及 [Claude 在工作階段期間編寫的 mod](/docs/zh-TW/plugins/mods/create#ask-claude-for-a-mod)

45* **您組織的 mods 仍然會載入**：[計為您組織的](#install-your-organizations-mods) mod 不會被檢查。所有其他 mod 都計為使用者的 mod，不會載入。這包括您從 GitHub 或其他遠端市場啟用的外掛程式中的 mod，以及您的組織為其成員在 claude.ai 上開啟的 mod。如果沒有計為您的，則不會載入任何已安裝的 mod。45* **您組織的 mod 仍會執行**：[計為您組織的](#install-your-organizations-mods) mod 不會被檢查。所有其他 mod 都計為使用者的 mod，並會遭到拒絕。這包括您從 GitHub 或其他遠端市集啟用的外掛中的 mod，以及您的組織為其成員在 claude.ai 上開啟的 mod。如果沒有任何 mod 計為您的，則不會有任何已安裝的 mod 執行其 hook。

46* **使用者無法撤銷它**：防護只從受管設定讀取選項，因此使用者、專案或本機設定檔中的相同項目，或使用 `--settings` 傳遞的檔案中的項目，不會改變任何內容46* **使用者無法撤銷它**：防護只從受管設定讀取選項，因此使用者、專案或本機設定檔中的相同項目，或使用 `--settings` 傳遞的檔案中的項目，不會改變任何內容

47* **檔案或 MDM 政策涵蓋每個提供者**：當您以檔案或透過 MDM 方式提供選項時，它在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的工作方式相同。如需從 claude.ai 管理員主控台進行交付，請參閱[平台可用性](/docs/zh-TW/server-managed-settings#platform-availability)47* **檔案或 MDM 原則涵蓋每個提供者**：當您以檔案或透過 MDM 方式提供選項時，它在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的運作方式相同。如需從 claude.ai 管理員主控台進行交付，請參閱[平台可用性](/docs/zh-TW/server-managed-settings#platform-availability)

~~48* **使用者的其他自訂設定保持有效**：他們[設定檔中的 hooks](/docs/zh-TW/hooks)、狀態行和 `/goal` 不受影響~~48* **使用者的其他自訂設定保持有效**：他們[設定檔中的 hook](/docs/zh-TW/hooks) 以及外掛 `hooks/hooks.json` 中的 hook、狀態列和 `/goal` 不受影響

~~49* **內建 mods 保持執行**：內建於 Claude Code 的 mods（例如 `AGENTS.md` 支援）各有[自己的開關](/docs/zh-TW/plugins/mods/overview#mods-built-into-claude-code)~~49* **內建 mod 保持執行**：內建於 Claude Code 的 mod（例如 `AGENTS.md` 支援）各有[自己的開關](/docs/zh-TW/plugins/mods/overview#mods-built-into-claude-code)

50 50

51若要確認使用者機器上的選項，請使用 `--plugin-dir` 和包含 mod 的目錄路徑（例如 `claude --plugin-dir ./first-mod`）在該處啟動 Claude Code。mod 的 hooks 不會執行，文字記錄和偵錯日誌會有[防護的訊息](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)，其中命名 mod 和 `allowManagedModsOnly`。如果 mod 載入，請參閱[檢查政策是否有效](/docs/zh-TW/managed-settings#check-that-a-policy-is-in-force)和[決定選項是否生效的規則](#set-options-on-the-built-in-guard)。51若要確認使用者機器上的選項，請使用 `--plugin-dir` 和包含 mod 的目錄路徑（例如 `claude --plugin-dir ./first-mod`）在該處啟動 Claude Code。mod 的 hook 不會執行，逐字稿和偵錯日誌中會有[防護的訊息](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)，其中會指出該 mod 和 `allowManagedModsOnly`。如果沒有出現該訊息，請參閱[檢查原則是否有效](/docs/zh-TW/managed-settings#check-that-a-policy-is-in-force)和[決定選項是否生效的規則](#set-options-on-the-built-in-guard)。

52 52

53如果您在早期存取期間將 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` 設定為 `0`，請用此選項替換它。Claude Code v2.1.287 及更新版本在任何值下都會忽略該變數，因此其中的 `0` 會保持 mods 開啟。53如果您在早期存取期間將 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` 設定為 `0`，請用此選項替換它。Claude Code v2.1.287 及更新版本在任何值下都會忽略該變數，因此其中的 `0` 會讓 mod 保持開啟。

54 54

55<h2 id="know-what-happens-by-default">55<h2 id="know-what-happens-by-default">

56 了解預設情況下會發生什麼56 了解預設情況下會發生什麼

117claude plugin validate ./some-mod117claude plugin validate ./some-mod

118```118```

119 119

120輸出中的兩行描述 mod 的程式碼：120輸出中的 `hooks:` 和 `calls:` 行描述 mod 的程式碼：

121 121

122```text theme={null}122```text theme={null}

123 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}123 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}

146 選擇允許的程度146 選擇允許的程度

147</h2>147</h2>

148 148

149Mod 政策的範圍從根本沒有已安裝的 mods 到使用者選擇的任何 mod，以及您自己的 mod 檢查其他 mods，每一個都是幾個受管設定。在第一列中找到您想要的政策，並設定第二列命名的內容。[部署受管設定](/docs/zh-TW/managed-settings)涵蓋受管設定的位置。149Mod 政策的範圍從根本沒有已安裝的 mod 到使用者選擇的任何 mod，以及您自己的 mod 檢查其他 mod，每一個都是幾個受管設定。在第一列中找到您想要的政策，並設定第二列命名的內容。[部署受管設定](/docs/zh-TW/managed-settings)涵蓋受管設定的位置。

150 150

151| 您想要的 | 設定 |151| 您想要的 | 設定 |

152| :- | :- |152| :- | :- |

155| 僅您組織的 mods | 設定防護的 [`allowManagedModsOnly` 選項](#stop-user-installed-mods-from-loading)，並[安裝您的 mods](#install-your-organizations-mods) 使其計為您的 |155| 僅您組織的 mod | 設定防護的 [`allowManagedModsOnly` 選項](#stop-user-installed-mods-from-loading)，並[安裝您的 mod](#install-your-organizations-mods) 使其計為您的 |

156| 來自您批准的市場的任何 mod | 保持您的[市場限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)，並將 `disableSideloadFlags` 設定為 `true` |156| 來自您批准的市集的任何 mod | 保持您的[市集限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)，並將 `disableSideloadFlags` 設定為 `true` |

157| 任何 mod，您自己的 mod 檢查其他 mods | [安裝您的 mod](#install-your-organizations-mods)，並在 `prependPlugins` 中與 `sec-default@builtin` 一起列出它 |157| 任何 mod，您自己的 mod 檢查其他 mod | [安裝您的 mod](#install-your-organizations-mods)，並在 `prependPlugins` 中與 `sec-default@builtin` 一起列出它 |

158 158

159每個設定的作用：159每個設定的作用：

160 160

161* **`allowManagedModsOnly`**：內建防護上的選項。使用者自己的 mods 不會載入，他們的設定 hooks、狀態行和 `/goal` 保持有效。[停止使用者安裝的 mods 載入](#stop-user-installed-mods-from-loading)列出它涵蓋的內容。161* **`allowManagedModsOnly`**：內建防護上的選項。Claude Code 會拒絕使用者自己的 mod，因此他們的 hook 都不會執行。使用者的設定 hook、狀態列和 `/goal` 保持有效。[停止使用者安裝的 mod 載入](#stop-user-installed-mods-from-loading)列出它涵蓋的內容。

162* **`allowManagedHooksOnly`**：更廣泛的設定。只有[您組織的 mods](#install-your-organizations-mods) 和內建於 Claude Code 的 mods 載入。使用者自己安裝的 mod 不會。該設定也會阻止使用者自己設定檔中的 hooks。在設定之前，請閱讀[在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)。162* **`allowManagedHooksOnly`**：更廣泛的設定。只有[您組織的 mod](#install-your-organizations-mods) 和內建於 Claude Code 的 mod 載入。使用者自己安裝的 mod 不會。該設定也會阻止使用者自己設定檔中的 hook。在設定之前，請閱讀[在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)。

163* **`disableAllHooks`**：最廣泛的設定。在受管設定中，它停止每個已安裝外掛程式中的 mods，包括您的，並關閉設定檔中的每個 hook，因此您受管設定中的 `PreToolUse` hook 不再阻止任何內容。自訂狀態行和 `/goal` 也停止工作。在設定之前，請閱讀 [`disableAllHooks`](/docs/zh-TW/settings-reference#disableallhooks)。163* **`disableAllHooks`**：最廣泛的設定。在受管設定中，它停止每個已安裝外掛中的 mod，包括您的，並關閉設定檔中的每個 hook，因此您受管設定中的 `PreToolUse` hook 不再阻止任何內容。自訂狀態列和 `/goal` 也停止工作。在設定之前，請閱讀 [`disableAllHooks`](/docs/zh-TW/settings-reference#disableallhooks)。

164* **`disableSideloadFlags`**：在啟動時拒絕 `--plugin-dir` 和 `--plugin-url`，並防止 Claude 在工作階段期間編寫的 mods 載入。該設定也拒絕 `--agents` 和 `--mcp-config`。在設定之前，請閱讀 [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags)。164* **`disableSideloadFlags`**：在啟動時拒絕 `--plugin-dir` 和 `--plugin-url`，並防止 Claude 在工作階段期間編寫的 mod 載入。該設定也拒絕 `--agents` 和 `--mcp-config`。在設定之前，請閱讀 [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags)。

165 165

166內建於 Claude Code 的 Mods（例如 `AGENTS.md` 支援）不受這些設定影響。每個都有[自己的開關](/docs/zh-TW/plugins/mods/overview#mods-built-into-claude-code)。166內建於 Claude Code 的 mod（例如 `AGENTS.md` 支援）不受這些設定影響。每個都有[自己的開關](/docs/zh-TW/plugins/mods/overview#mods-built-into-claude-code)。

167 167

168未載入 mod 的使用者在其偵錯日誌中找到原因。[拒絕訊息](/docs/zh-TW/plugins/mods/troubleshoot#refusal-messages)列出 `allowManagedHooksOnly` 和 `disableAllHooks` 的行，[來自內建防護的訊息](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)有 `allowManagedModsOnly` 的行。168mod 遭到拒絕或未載入的使用者，可在其偵錯日誌中找到原因。[拒絕訊息](/docs/zh-TW/plugins/mods/troubleshoot#refusal-messages)列出 `allowManagedHooksOnly` 和 `disableAllHooks` 的行，[來自內建防護的訊息](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)有 `allowManagedModsOnly` 的行。

169 169

170<h3 id="allow-only-your-organization’s-mods">170<h3 id="allow-only-your-organization’s-mods">

171 僅允許您組織的 mods171 僅允許您組織的 mod

172</h3>172</h3>

173 173

174若要執行您組織的 mods 並阻止使用者帶來的 mods，請部署[政策表格](#choose-how-much-to-allow)中 **僅您組織的 mods** 一列的設定，再加上 `disableSideloadFlags`。使用這份完整的 `managed-settings.json`，Claude Code 會拒絕使用者自己的 mods，因此他們的 hooks 都不會執行，而您的政策 mod 會在其他 mods 之前執行：174若要執行您組織的 mod 並阻止使用者帶來的 mod，請部署[政策表格](#choose-how-much-to-allow)中 **僅您組織的 mod** 一列的設定，再加上 `disableSideloadFlags`。使用這份完整的 `managed-settings.json`，Claude Code 會拒絕使用者自己的 mod，因此他們的 hook 都不會執行，而您的原則 mod 會在其他 mod 之前執行：

175 175

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

177{177{

193 193

194每組鍵各負責一項工作：194每組鍵各負責一項工作：

195 195

196* **`extraKnownMarketplaces`、`enabledPlugins` 和 `prependPlugins`**：安裝您的 mod 使其計為您的，並讓它最先執行，防護在其後執行。[安裝您組織的 mods 並設定順序](#install-your-organizations-mods)涵蓋這些鍵所指向的目錄。196* **`extraKnownMarketplaces`、`enabledPlugins` 和 `prependPlugins`**：安裝您的 mod 使其計為您的，並讓它最先執行，防護在其後執行。[安裝您組織的 mod 並設定順序](#install-your-organizations-mods)涵蓋這些鍵所指向的目錄。

197* **`pluginConfigs`**：設定防護的 `allowManagedModsOnly` 選項，使 Claude Code 拒絕使用者自己的 mods。他們的設定 hooks、狀態列和 `/goal` 保持有效。197* **`pluginConfigs`**：設定防護的 `allowManagedModsOnly` 選項，使 Claude Code 拒絕使用者自己的 mod。他們的設定 hook、狀態列和 `/goal` 保持有效。

198* **`disableSideloadFlags`**：請參閱 [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags) 了解它在啟動時拒絕的旗標198* **`disableSideloadFlags`**：請參閱 [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags) 了解它在啟動時拒絕的旗標

199 199

200若要在測試機器上確認政策，請在您的 shell 中以 `claude --debug` 啟動工作階段並閱讀偵錯日誌：200若要在測試機器上確認政策，請在您的 shell 中以 `claude --debug` 啟動工作階段並閱讀偵錯日誌：

201 201

202* **您的 mod**：其 `hooks module` 行含有 `tier prepend`202* **您的 mod**：其 `hooks module` 行含有 `tier prepend`

203* **使用者安裝的 mod**：有一行顯示 `refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly)`。較早的一行會顯示該 mod 的 hooks module 為 `loaded`，因此請尋找拒絕訊息。203* **使用者安裝的 mod**：有一行顯示 `refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly)`。較早的一行會顯示該 mod 的 hook 模組為 `loaded`，因此請尋找拒絕訊息。

204* **外掛目錄**：`claude --plugin-dir ./any-mod` 會結束並顯示以 `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)` 開頭的訊息204* **外掛目錄**：`claude --plugin-dir ./any-mod` 會結束並顯示以 `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)` 開頭的訊息

205 205

206若也要限制使用者可以新增哪些市集，請將此檔案與您的[市集限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)結合使用。206若也要限制使用者可以新增哪些市集，請將此檔案與您的[市集限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)結合使用。

207 207

208<h3 id="apply-your-plugin-controls-to-mods">208<h3 id="apply-your-plugin-controls-to-mods">

209 將您的外掛控制套用至 mods209 將您的外掛控制套用至 mod

210</h3>210</h3>

211 211

212Mod 是一種外掛，因此您[為組織管理外掛](/docs/zh-TW/plugins/org)的方式也適用於包含 mod 的外掛：212Mod 是一種外掛，因此您[為組織管理外掛](/docs/zh-TW/plugins/org)的方式也適用於包含 mod 的外掛：

216* **為某個群組（例如試行群組）提供不同的政策**：[為受管設定無法強制執行的部分做規劃](/docs/zh-TW/plugins/org#plan-for-what-managed-settings-can’t-enforce)216* **為某個群組（例如試行群組）提供不同的政策**：[為受管設定無法強制執行的部分做規劃](/docs/zh-TW/plugins/org#plan-for-what-managed-settings-can’t-enforce)

217* **檢查哪些應用程式和工作階段類型會套用外掛鍵**：[各使用介面何時套用外掛鍵](/docs/zh-TW/plugins/org#when-each-surface-applies-the-plugin-keys)217* **檢查哪些應用程式和工作階段類型會套用外掛鍵**：[各使用介面何時套用外掛鍵](/docs/zh-TW/plugins/org#when-each-surface-applies-the-plugin-keys)

218* **設定 CI 和容器**：[預先配置容器和 CI](/docs/zh-TW/plugins/org#seed-containers-and-ci)218* **設定 CI 和容器**：[預先配置容器和 CI](/docs/zh-TW/plugins/org#seed-containers-and-ci)

219* **提供使用者可以安裝的 mods**：[託管市集](/docs/zh-TW/plugins/host-marketplace)。Claude Code 從 GitHub、git、URL 或 npm 來源複製的 mod 會計為使用者的，而不是[您組織的](#install-your-organizations-mods)。219* **提供使用者可以安裝的 mod**：[託管市集](/docs/zh-TW/plugins/host-marketplace)。Claude Code 從 GitHub、git、URL 或 npm 來源複製的 mod 會計為使用者的，而不是[您組織的](#install-your-organizations-mods)。

220 220

221<h3 id="set-options-on-the-built-in-guard">221<h3 id="set-options-on-the-built-in-guard">

222 在內建防護上設定選項222 在內建防護上設定選項

223</h3>223</h3>

224 224

225內建防護接受選項。在受管設定中的 `pluginConfigs` 下設定它們，由 `cc-plugin-sec-default@builtin` 鍵入，如[停止使用者安裝的 mods 載入](#stop-user-installed-mods-from-loading)中的範例所示。225內建防護接受選項。在受管設定中的 `pluginConfigs` 下設定它們，以 `cc-plugin-sec-default@builtin` 為鍵，如[停止使用者安裝的 mod 載入](#stop-user-installed-mods-from-loading)中的範例所示。

226 226

227該表格給出您的使用者在每個選項未設定和設定為 `true` 時獲得的內容：227下表列出每個選項未設定和設定為 `true` 時，您的使用者會得到的結果：

228 228

229| 選項 | 未設定 | `true` |229| 選項 | 未設定 | `true` |

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

231| `allowManagedModsOnly` | 使用者自己的 mods 載入 | 只有[您組織的 mods](#install-your-organizations-mods) 和內建於 Claude Code 的 mods 載入。Claude Code 拒絕所有其他 mods，包括使用者安裝的或使用 `--plugin-dir` 命名的。 |231| `allowManagedModsOnly` | 使用者自己的 mod 會執行 | 只有[您組織的 mod](#install-your-organizations-mods) 和內建於 Claude Code 的 mod 會執行其 hook。Claude Code 拒絕所有其他 mod，包括使用者安裝的或使用 `--plugin-dir` 命名的。 |

233 233

234這些規則決定選項是否生效：234這些規則決定選項是否生效：

235 235

236* **id 在這裡有一個拼寫**：Claude Code 只在 `cc-plugin-sec-default@builtin` 下讀取選項。`prependPlugins` 也接受 `sec-default@builtin`，而 `pluginConfigs` 不接受。236* **id 在這裡只有一種形式**：Claude Code 只在 `cc-plugin-sec-default@builtin` 下讀取選項。`prependPlugins` 也接受 `sec-default@builtin`，而 `pluginConfigs` 不接受。

237* **只有受管設定計數**：使用者、專案或本機設定檔中的相同項目，或使用 `--settings` 傳遞的檔案中的項目，既不設定選項也不鬆動選項237* **只有受管設定才算數**：使用者、專案或本機設定檔中的相同項目，或使用 `--settings` 傳遞的檔案中的項目，既不會設定選項，也不會放寬選項

238* **防護必須載入**：如果您設定 `prependPlugins`，[在清單中命名防護](#install-your-organizations-mods)。防護不載入的地方，選項都不適用。238* **防護必須載入**：如果您設定 `prependPlugins`，請[在清單中列出防護](#install-your-organizations-mods)。防護未載入之處，兩個選項都不適用。

239* **防護失敗關閉**：如果防護無法讀取受管設定，它拒絕每個使用者的 mod 在載入時。如果它無法檢查使用者的 mod 批准的呼叫的拒絕規則，它拒絕呼叫。239* **防護採失敗即關閉**：如果防護無法讀取受管設定，它會在載入時拒絕每個使用者的 mod。如果它無法針對使用者的 mod 所批准的呼叫檢查拒絕規則，它會拒絕該呼叫。

240 240

241[來自內建防護的訊息](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)是您的使用者在任一選項適用時看到的。241[來自內建防護的訊息](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)是您的使用者在任一選項適用時看到的內容。

242 242

243<h2 id="run-your-organization’s-own-mods">243<h2 id="run-your-organization’s-own-mods">

244 執行您組織自己的 mods244 執行您組織自己的 mod

245</h2>245</h2>

246 246

247您可以將您自己的 mods 部署到每個使用者，選擇它們相對於使用者 mods 的執行位置，並使用一個來強制執行政策。247您可以將您自己的 mod 部署到每個使用者，選擇它們相對於使用者 mod 的執行位置，並使用一個來強制執行原則。

248 248

249<h3 id="install-your-organizations-mods">249<h3 id="install-your-organizations-mods">

250 安裝您組織的 mods 並設定順序250 安裝您組織的 mod 並設定順序

251</h3>251</h3>

252 252

253您組織的 mods 在使用者 mods 不載入的地方載入，並可以在它們之前執行，因此 Claude Code 必須能夠判斷 mod 來自您。它只在以下所有條件都成立時才將 mod 視為您組織的：253您組織的 mod 在使用者 mod 不載入的地方載入，並可以在它們之前執行，因此 Claude Code 必須能夠判斷 mod 來自您。它只在以下所有條件都成立時才將 mod 視為您組織的：

254 254

255* 受管 `enabledPlugins` 將 mod 的外掛設定為 `true`255* 受管 `enabledPlugins` 將 mod 的外掛設定為 `true`

256* 受管設定以絕對路徑將外掛的[市集](/docs/zh-TW/plugins/create-marketplace)指定為使用者機器上的目錄。`extraKnownMarketplaces` 項目可做到這一點，並同時為使用者註冊該市集。256* 受管設定以絕對路徑將外掛的[市集](/docs/zh-TW/plugins/create-marketplace)指定為使用者機器上的目錄。`extraKnownMarketplaces` 項目可做到這一點，並同時為使用者註冊該市集。

285}285}

286```286```

287 287

288Claude Code 複製到其快取中的外掛會被視為使用者的，即使受管 `enabledPlugins` 啟用了它。這涵蓋來自 GitHub、git、URL 或 npm 來源的每個外掛。其 mod 在使用者 mods 之間執行，`prependPlugins` 和 `appendPlugins` 會跳過它，且它不會在 `allowManagedModsOnly` 或 `allowManagedHooksOnly` 下載入。使用者的偵錯日誌中會有一行以外掛的 id 和 `is enabled by managed settings, but` 開頭。288Claude Code 複製到其快取中的外掛會被視為使用者的，即使受管 `enabledPlugins` 啟用了它。這涵蓋來自 GitHub、git、URL 或 npm 來源的每個外掛。其 mod 在使用者的 mod 之間執行，`prependPlugins` 和 `appendPlugins` 會跳過它，`allowManagedModsOnly` 會拒絕它，而 `allowManagedHooksOnly` 會使它無法載入。使用者的偵錯日誌中會有一行以外掛的 id 和 `is enabled by managed settings, but` 開頭。

289 289

290Claude Code 每次即將採取行動（例如執行工具）時都會引發事件，並依次將其傳遞給每個 mod。被視為您的 mod [會在使用者 mods 之前執行](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in)，即使您在任何地方都沒有列出它。若要設定其位置，請在兩個設定之一中列出其 id。id 是外掛的名稱、`@` 和市集的名稱，例如 `acme-guard@acme-tools`。290Claude Code 每次即將採取行動（例如執行工具）時都會引發事件，並依次將其傳遞給每個 mod。被視為您的 mod [會在使用者的 mod 之前執行](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in)，即使您在任何地方都沒有列出它。若要設定其位置，請在兩個設定之一中列出其 id。id 是外掛的名稱、`@` 和市集的名稱，例如 `acme-guard@acme-tools`。

291 291

292* **`prependPlugins`**：您的 mod 在任何使用者的 mod 之前看到每個事件，並在之後看到每個結果。它可以更改事件、拒絕它或跳過使用者的 mods。292* **`prependPlugins`**：您的 mod 在任何使用者的 mod 之前看到每個事件，並在之後看到每個結果。它可以更改事件、拒絕它或跳過使用者的 mod。

293* **`appendPlugins`**：您的 mod 在每個使用者的 mod 之後執行，因此它只看到這些 mods 傳遞的事件，以及它們傳遞的形式293* **`appendPlugins`**：您的 mod 在每個使用者的 mod 之後執行，因此它只看到這些 mod 傳遞的事件，以及它們傳遞的形式

294 294

295此範例在 `/opt/acme/claude-plugins` 宣告 `acme-tools` 市集，從中啟用 `acme-guard`，並首先執行該 mod，內建防護在其後：295此範例在 `/opt/acme/claude-plugins` 宣告 `acme-tools` 市集，從中啟用 `acme-guard`，並首先執行該 mod，內建防護在其後：

296 296

312* **`enabledPlugins`**：為接收這些受管設定的每個使用者開啟 `acme-guard`312* **`enabledPlugins`**：為接收這些受管設定的每個使用者開啟 `acme-guard`

313* **`prependPlugins`**：將 `acme-guard` 放在首位，內建防護放在第二位，兩者都在使用者安裝的任何 mod 之前。Claude Code 遵循您列出的順序。313* **`prependPlugins`**：將 `acme-guard` 放在首位，內建防護放在第二位，兩者都在使用者安裝的任何 mod 之前。Claude Code 遵循您列出的順序。

314 314

315若要確認使用者的機器收到了設定，請參閱[檢查政策是否有效](/docs/zh-TW/managed-settings#check-that-a-policy-is-in-force)。315若要確認使用者的機器收到了設定，請參閱[檢查原則是否有效](/docs/zh-TW/managed-settings#check-that-a-policy-is-in-force)。

316 316

317若要確認 mod 執行的位置，請在該機器上使用 `claude --debug` 啟動工作階段，並在[偵錯日誌](/docs/zh-TW/plugins/mods/troubleshoot#read-the-debug-log)中搜尋 mod 的 id：317若要確認 mod 執行的位置，請在該機器上使用 `claude --debug` 啟動工作階段，並在[偵錯日誌](/docs/zh-TW/plugins/mods/troubleshoot#read-the-debug-log)中搜尋 mod 的 id：

318 318

323 323

324* **清單取代預設值**：當您在受管設定中設定 `prependPlugins` 時，請在其中列出 `sec-default@builtin` 以保留內建防護。防護是內建的，不需要 `enabledPlugins` 項目。324* **清單取代預設值**：當您在受管設定中設定 `prependPlugins` 時，請在其中列出 `sec-default@builtin` 以保留內建防護。防護是內建的，不需要 `enabledPlugins` 項目。

325* **您自己的 id 必須被視為您的**：在受管設定中，Claude Code 會跳過其外掛不符合組織 mod 條件的 id325* **您自己的 id 必須被視為您的**：在受管設定中，Claude Code 會跳過其外掛不符合組織 mod 條件的 id

326* **儲存庫無法設定它們**：Claude Code 從受管設定讀取這兩個設定，從不從儲存庫的設定檔讀取。使用者只有在沒有受管設定的機器上，且未以 Team 或 Enterprise 方案登入時，才能在 `~/.claude/settings.json` 中設定它們以排序自己的 mods。在其他任何情況下，Claude Code 會忽略使用者設定中的這兩個設定鍵。那裡的清單既不會加入也不會移除內建防護。326* **儲存庫無法設定它們**：Claude Code 從受管設定讀取這兩個設定，從不從儲存庫的設定檔讀取。使用者只有在沒有受管設定的機器上，且未以 Team 或 Enterprise 方案登入時，才能在 `~/.claude/settings.json` 中設定它們以排序自己的 mod。在其他任何情況下，Claude Code 會忽略使用者設定中的這兩個設定鍵。那裡的清單既不會加入也不會移除內建防護。

327 327

328<h3 id="enforce-a-policy-with-a-mod-of-your-own">328<h3 id="enforce-a-policy-with-a-mod-of-your-own">

329 使用您自己的 mod 強制執行政策329 使用您自己的 mod 強制執行原則

330</h3>330</h3>

331 331

332若要排除每個使用者的 mod，您不需要自己的 mod。請設定 [`allowManagedModsOnly`](#stop-user-installed-mods-from-loading)。當您想要允許某些使用者的 mods 並拒絕其他的，或記錄 mods 執行的操作時，請編寫政策 mod。332若要排除每個使用者的 mod，您不需要自己的 mod。請設定 [`allowManagedModsOnly`](#stop-user-installed-mods-from-loading)。當您想要允許某些使用者的 mod 並拒絕其他的，或記錄 mod 執行的操作時，請編寫原則 mod。

333 333

334每次另一個 mod 即將載入時，您的 mod 會在名為 [`plugin.register`](/docs/zh-TW/plugins/mods/reference#other-mods) 的事件中接收 `claude plugin validate` 列印的清單。`prependPlugins` 中的 mod 可以讀取該清單並拒絕該 mod。它也可以[按名稱處理任何 mods API 呼叫](/docs/zh-TW/plugins/mods/api#reach-files-processes-and-the-network)，以記錄或拒絕所有其他 mod 的該呼叫。名稱是不含 `$.` 的方法，因此 `fs.write` 上的 hook 會看到每個 `$.fs.write` 呼叫。334每次另一個 mod 即將載入時，您的 mod 會在名為 [`plugin.register`](/docs/zh-TW/plugins/mods/reference#other-mods) 的事件中接收 `claude plugin validate` 列印的清單。`prependPlugins` 中的 mod 可以讀取該清單並拒絕該 mod。它也可以[按名稱處理任何 mods API 呼叫](/docs/zh-TW/plugins/mods/api#reach-files-processes-and-the-network)，以記錄或拒絕所有其他 mod 的該呼叫。名稱是不含 `$.` 的方法，因此 `fs.write` 上的 hook 會看到每個 `$.fs.write` 呼叫。

335 335

336此政策 mod 會拒絕任何自身程式碼呼叫 `$.process.run` 或 `$.process.spawn` 的使用者 mod。它也會保留稽核日誌，將每個工具呼叫和每個 mod 寫入的檔案寫入偵錯日誌。因為它首先執行，日誌會在任何使用者的 mod 更改之前記錄所請求的內容。將其儲存為 `acme-guard/hooks/register.js`：336此原則 mod 會拒絕任何自身程式碼呼叫 `$.process.run` 或 `$.process.spawn` 的使用者 mod。它也會保留稽核日誌，將每個工具呼叫和每個 mod 寫入的檔案寫入偵錯日誌。因為它首先執行，日誌會在任何使用者的 mod 更改之前記錄所請求的內容。將其儲存為 `acme-guard/hooks/register.js`：

337 337

338```javascript acme-guard/hooks/register.js theme={null}338```javascript acme-guard/hooks/register.js theme={null}

339// The methods no user's mod may call, each spelled namespace.method339// The methods no user's mod may call, each spelled namespace.method

381 381

382若要將稽核行傳送到偵錯日誌以外的地方，請從相同的 hook 呼叫 `$.http.fetch`。382若要將稽核行傳送到偵錯日誌以外的地方，請從相同的 hook 呼叫 `$.http.fetch`。

383 383

384工作階段可能在沒有您的 mod 的情況下執行。如果執行已安裝 mods 的工作執行緒[當機三次](/docs/zh-TW/plugins/mods/troubleshoot#mods-that-run-in-the-hooks-worker-are-off-for-this-session)，Claude Code 會卸載所有非內建的 mod（包括您的），直到使用者執行 `/reload-plugins` 或啟動新工作階段。而使用 `--safe-mode` 啟動 Claude Code 的使用者，會在沒有已安裝 mods 的情況下執行，包括您的。384工作階段可能在沒有您的 mod 的情況下執行。如果執行已安裝 mod 的工作執行緒[當機三次](/docs/zh-TW/plugins/mods/troubleshoot#mods-that-run-in-the-hooks-worker-are-off-for-this-session)，Claude Code 會卸載所有非內建的 mod（包括您的），直到使用者執行 `/reload-plugins` 或啟動新工作階段。而使用 `--safe-mode` 啟動 Claude Code 的使用者，會在沒有已安裝 mod 的情況下執行，包括您的。

385 385

386[建立 mod](/docs/zh-TW/plugins/mods/create) 涵蓋 mod 需要的檔案。[測試政策 mod](/docs/zh-TW/plugins/mods/test#test-a-mod-that-judges-other-mods) 提供此政策 mod 的測試檔案。386[建立 mod](/docs/zh-TW/plugins/mods/create) 涵蓋 mod 需要的檔案。[測試原則 mod](/docs/zh-TW/plugins/mods/test#test-a-mod-that-judges-other-mods) 提供此原則 mod 的測試檔案。

387 387

388<h4 id="refuse-mods-when-your-check-fails">388<h4 id="refuse-mods-when-your-check-fails">

389 當您的檢查失敗時拒絕 mods389 當您的檢查失敗時拒絕 mod

390</h4>390</h4>

391 391

392如果您的 `plugin.register` hook 拋出例外或超過其時間限制，Claude Code 會跳過該 hook，因此檢查會以開放方式失敗，正在檢查的 mod 會載入。若要以關閉方式失敗並拒絕使用者的 mods，請將檢查移到具名函式中，並加入傳回拒絕的 `.catch` 處理程式。此版本的檔案僅顯示 `plugin.register` hook，因此請在 `register` 中保留第一個版本的兩個稽核 hook：392如果您的 `plugin.register` hook 拋出例外或超過其時間限制，Claude Code 會跳過該 hook，因此檢查會以開放方式失敗，正在檢查的 mod 會載入。若要以關閉方式失敗並拒絕使用者的 mod，請將檢查移到具名函式中，並加入傳回拒絕的 `.catch` 處理程式。此版本的檔案僅顯示 `plugin.register` hook，因此請在 `register` 中保留第一個版本的兩個稽核 hook：

393 393

394```javascript acme-guard/hooks/register.js theme={null}394```javascript acme-guard/hooks/register.js theme={null}

395const BLOCKED_CALLS = ['process.run', 'process.spawn']395const BLOCKED_CALLS = ['process.run', 'process.spawn']

414}414}

415```415```

416 416

417處理程式就位後，在檢查拋出例外或逾時時正在被檢查的 mod 不會載入，拒絕行會帶有第二個原因，如 `refused by acme-guard: Acme policy check failed, so this mod was not loaded`。處理程式將 `user` 層以外的每個 mod 傳遞給 `next(e)`，因此失敗的檢查不會阻止您組織列出的 mods。[處理失敗的 hook](/docs/zh-TW/plugins/mods/events#handle-a-hook-that-fails) 涵蓋其他事件的 `.catch`。417處理程式就位後，在檢查拋出例外或逾時時正在被檢查的 mod 不會載入，拒絕行會帶有第二個原因，如 `refused by acme-guard: Acme policy check failed, so this mod was not loaded`。處理程式將 `user` 層以外的每個 mod 傳遞給 `next(e)`，因此失敗的檢查不會阻止您組織列出的 mod。[處理失敗的 hook](/docs/zh-TW/plugins/mods/events#handle-a-hook-that-fails) 涵蓋其他事件的 `.catch`。

418 418

419<h2 id="next-steps">419<h2 id="next-steps">

420 後續步驟420 後續步驟

plugins/mods/api.md +13 −4

Details

71 71

72當您詢問票證時，Claude 可以使用其 id 呼叫 `mcp__my-mod__ticket`。第二個 hook 會擷取票證並傳回回應本文，Claude 會將其讀取為工具的結果。當伺服器以錯誤狀態回答時，Claude 會讀取 `Lookup failed with status` 和數字。72當您詢問票證時，Claude 可以使用其 id 呼叫 `mcp__my-mod__ticket`。第二個 hook 會擷取票證並傳回回應本文，Claude 會將其讀取為工具的結果。當伺服器以錯誤狀態回答時，Claude 會讀取 `Lookup failed with status` 和數字。

73 73

74<Tip>

75 當 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 延遲載入已註冊的工具時，Claude 會看到其名稱，但在搜尋該工具之前看不到其描述。若 Claude 應在每個回合都考慮此工具，請在註冊中新增 [`isDeferred: false`](/docs/zh-TW/plugins/mods/reference#tools)，以[預先載入完整工具](/docs/zh-TW/mcp#exempt-a-server-from-deferral)。此欄位需要 Claude Code v2.1.293 或更新版本，較早的版本會忽略它。

76</Tip>

74<h2 id="call-a-model">78<h2 id="call-a-model">

75 呼叫模型79 呼叫模型

76</h2>80</h2>

187 存取檔案、程序和網路191 存取檔案、程序和網路

188</h2>192</h2>

189 193

190mod 透過 mods API 存取檔案系統、程序和網路，具有與執行 Claude Code 的使用者相同的權限。hooks 模組本身沒有 Node.js API、沒有計時器全域變數（例如 `setTimeout`），也沒有自己的網路或檔案存取。標準 JavaScript 和網路 API（例如 `URL`、`TextEncoder`、`AbortController` 和 `crypto.subtle`）可用。下面的每個命名空間涵蓋一種存取：194mod 透過 mods API 存取檔案系統、程序和網路，具有與執行 Claude Code 的使用者相同的權限。hook 模組本身沒有 Node.js API、沒有計時器全域變數（例如 `setTimeout`），也沒有自己的網路或檔案存取。標準 JavaScript 和網路 API（例如 `URL`、`TextEncoder`、`AbortController` 和 `crypto.subtle`）可用。下面的每個命名空間涵蓋一種存取：

191 195

192| 命名空間 | 它的作用 |196| 命名空間 | 它的作用 |

193| :- | :- |197| :- | :- |

194| `$.fs` | `read(path)`、`write(path, text)`、`exists(path)`、`stat(path)` 和 `list(path)` 在檔案和目錄上工作 |198| `$.fs` | `read(path)`、`write(path, text)`、`exists(path)`、`stat(path)` 和 `list(path)` 在檔案和目錄上工作 |

196| `$.http` | `fetch(url, init)` 透過 `http` 或 `https`。它在讀取本文後解析為 `{ status, ok, headers, text }`。 |200| `$.http` | `fetch(url, init)` 透過 `http` 或 `https`。它在讀取本文後解析為 `{ status, ok, headers, text }`。 |

198| `$.env` | `get` 和 `set` 環境變數。將名稱寫為文字字串。 |202| `$.env` | `get` 和 `set` 環境變數。將名稱寫為文字字串。 |

200| `$.session` | `messages()` 將文字記錄傳回為 `{ role, text, toolUses }` 的列表。也是工作目錄、模型等。[`usage()`](/docs/zh-TW/plugins/mods/reference#mods-api-methods) 傳回內容視窗使用和計畫限制。 |204| `$.session` | `messages()` 將逐字稿傳回為 `{ role, text, toolUses }` 的列表。也是工作目錄、模型等。[`usage()`](/docs/zh-TW/plugins/mods/reference#mods-api-methods) 傳回上下文視窗使用和計畫限制。 |

201| `$.mcp` | `call` 連接的 MCP 伺服器上的工具 |205| `$.mcp` | `call` 連接的 MCP 伺服器上的工具 |

202 206

203檔案和程序有幾個自己的規則：207檔案和程序有幾個自己的規則：

204 208

205* **路徑**：相對路徑會相對於工作階段的工作目錄解析209* **路徑**：相對路徑會相對於工作階段的工作目錄解析

206* **`$.fs.list`**：將一個目錄的項目傳回為 `{ name, kind, size, isLink }`，不會遞迴210* **`$.fs.list`**：將一個目錄的項目傳回為 `{ name, kind, size, isLink }`，不會遞迴

207* **`$.process.run`**：採用引數列表，不使用 shell。無論退出代碼如何，它都解析為 `{ exitCode, stdout, stderr }`。如果程式無法啟動或在逾時時仍在執行，它會拒絕，預設為 30 秒，因此將其包裝在 `try` 和 `catch` 中。211* **`$.process.run`**：採用引數列表，不使用 shell。無論退出碼如何，它都解析為 `{ exitCode, stdout, stderr }`。如果程式無法啟動或在逾時時仍在執行，它會拒絕，預設為 30 秒，因此將其包裝在 `try` 和 `catch` 中。

208 212

209這些呼叫中的每一個本身都是一個事件，以其命名空間和方法命名，不帶 `$.`，例如 `$.fs.read` 的 `fs.read`。鏈中[較早的](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in) mod 可以觀察、重寫或拒絕您的呼叫，這是組織限制 mod 到達的方式。213這些呼叫中的每一個本身都是一個事件，以其命名空間和方法命名，不帶 `$.`，例如 `$.fs.read` 的 `fs.read`。鏈中[較早的](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in) mod 可以觀察、重寫或拒絕您的呼叫，這是組織限制 mod 到達的方式。

210 214

215mod 可以在命令已產生輸出或已退出之後拒絕您的 `$.process.spawn` 呼叫，而命令已執行的任何動作都不會被復原。此時該呼叫會以一則訊息拒絕，訊息結尾為下列其中一個字串以及拒絕的 mod 所給的原因：

216

217* **`$.process.spawn started, and a plugin withheld its result:`**：拒絕的 mod 尚未將命令的輸出讀取到結尾。如果命令仍在執行，Claude Code 會將其停止。

218* **`$.process.spawn ran, and a plugin withheld its result:`**：拒絕的 mod 已將命令的輸出讀取到結尾，因此命令已經退出

219

211<h2 id="next-steps">220<h2 id="next-steps">

212 後續步驟221 後續步驟

213</h2>222</h2>

plugins/mods/create.md +1 −1

Details

316✔ Validation passed316✔ Validation passed

317```317```

318 318

319`hooks:` 行列出你的模組 hook 的事件，每個都在大括號中有其篩選器。`calls:` 行列出它呼叫的每個 mod API 方法。讀取或設定環境變數的模組也會取得 `env reads:` 和 `env writes:` 行，使用 [`$.state`](/docs/zh-TW/plugins/mods/interface#keep-state) 的模組會取得 `state reads:` 和 `state writes:`。319請查看 `hooks:` 行，確認您的模組 hook 的事件，每個事件的篩選器都列在大括號中；並查看 `calls:` 行，確認它呼叫的每個 mod API 方法。如果您的模組會讀取或設定環境變數，也請留意 `env reads:` 和 `env writes:` 行；若使用了 [`$.state`](/docs/zh-TW/plugins/mods/interface#keep-state)，則請留意 `state reads:` 和 `state writes:`。對於每個可以拒絕動作的 hook，您也會看到一行，例如 `gating hook without .catch: tool.call`，說明該 hook 是否具有 [`.catch` 處理常式](/docs/zh-TW/plugins/mods/events#handle-a-hook-that-fails)。

320 320

321如果您想處理的事件沒有出現在第一行中，Claude Code 也不會呼叫該 hook。常見原因是事件名稱拼寫錯誤，命令會將其回報為錯誤，例如 `"tool.calls" is not an event`。321如果您想處理的事件沒有出現在第一行中，Claude Code 也不會呼叫該 hook。常見原因是事件名稱拼寫錯誤，命令會將其回報為錯誤，例如 `"tool.calls" is not an event`。

322 322

plugins/mods/events.md +21 −5

Details

245 245

246當您送出如 `open a PR for this change` 之類的提示詞時，您的訊息在逐字稿中看起來不變，而 Claude 還會在其後讀到如 `Current branch: feature/auth` 之類的一行。未提及 pull request 的提示詞會原封不動地通過，且不會執行 `git`。246當您送出如 `open a PR for this change` 之類的提示詞時，您的訊息在逐字稿中看起來不變，而 Claude 還會在其後讀到如 `Current branch: feature/auth` 之類的一行。未提及 pull request 的提示詞會原封不動地通過，且不會執行 `git`。

247 247

248若要阻止提示詞，請在不呼叫 `next` 的情況下傳回 `{ drop: 'the reason' }`。如果您的 hook 在其 `next(e)` 呼叫已讓提示詞通過之後才傳回 `drop`，回合仍會執行，且該 hook 會[失敗](#handle-a-hook-that-fails)，並顯示包含 `a drop after its next() was answered` 的訊息。

249

248[其他事件](/docs/zh-TW/plugins/mods/reference#prompts-and-what-claude-reads)涵蓋 Claude 讀取的其餘內容：`prompt.section` 用於系統提示詞的每個區段，`prompt.context` 用於隨第一則訊息送出的上下文，而 `skill.prompt` 用於 skill 的文字。來自這些 hook、且在請求之間有所變動的文字，會[使提示快取失效](/docs/zh-TW/prompt-caching)。250[其他事件](/docs/zh-TW/plugins/mods/reference#prompts-and-what-claude-reads)涵蓋 Claude 讀取的其餘內容：`prompt.section` 用於系統提示詞的每個區段，`prompt.context` 用於隨第一則訊息送出的上下文，而 `skill.prompt` 用於 skill 的文字。來自這些 hook、且在請求之間有所變動的文字，會[使提示快取失效](/docs/zh-TW/prompt-caching)。

249 251

250<h3 id="follow-a-turn">252<h3 id="follow-a-turn">

312 314

313Claude Code 按每個 mod 的來源順序排列鏈：315Claude Code 按每個 mod 的來源順序排列鏈：

314 316

3151. 內建保護 `sec-default@builtin`，一個內建於 Claude Code 的 mod，`/plugin` 列為 `cc-plugin-sec-default`，其中[它載入](/docs/zh-TW/plugins/mods/admin#know-what-happens-by-default)，您的組織在 [`prependPlugins`](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods) 中列出的 mod，然後是任何其他計為您的組織的 mod，且不在 `appendPlugins` 中3171. 內建防護 `sec-default@builtin`，一個內建於 Claude Code 的 mod，`/plugin` 列為 `cc-plugin-sec-default`，其中[它載入](/docs/zh-TW/plugins/mods/admin#know-what-happens-by-default)，您的組織在 [`prependPlugins`](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods) 中列出的 mod，然後是任何其他計為您的組織的 mod，且不在 `appendPlugins` 中

3162. 您安裝的 mod3182. 您安裝的 mod

3173. 您的組織在 `appendPlugins` 中列出的 mod3193. 您的組織在 `appendPlugins` 中列出的 mod

3184. 內建於 Claude Code 的其他 mod3204. 內建於 Claude Code 的其他 mod

334 處理失敗的 hook336 處理失敗的 hook

335</h3>337</h3>

336 338

337失敗的 hook 不會破壞工作階段，您可以決定接下來會發生什麼。當沒有 `.catch` 處理程式的 hook 擲回、超時或傳回錯誤形狀的結果時，接下來會發生什麼取決於它是否已呼叫 `next`：339失敗的 hook 不會破壞工作階段，您可以決定接下來會發生什麼。當沒有 `.catch` 處理程式的 hook 擲回、逾時或傳回錯誤形狀的結果時，接下來會發生什麼取決於它是否已呼叫 `next`：

338 340

339* **它在呼叫 `next` 之前失敗**：Claude Code 跳過它，下一個處理程式代替執行341* **它在呼叫 `next` 之前失敗**：Claude Code 跳過它，下一個處理程式代替執行

340* **它在 `next` 解析後失敗**：該結果成立，沒有任何東西執行第二次342* **它在 `next` 解析後失敗**：該結果成立，沒有任何東西執行第二次

341 343

342一行命名 mod、事件和原因，例如 `my-mod: tool.call hook skipped: threw Error: boom`。您讀取它的位置取決於工作階段，如[找出 mod 為什麼不執行任何操作](/docs/zh-TW/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)所列。其繪圖不驗證的 `ui.render` hook 的報告方式不同，如[從元素建立樹](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)所述。344一行命名 mod、事件和原因，例如 `my-mod: tool.call hook skipped: threw Error: boom`。您讀取它的位置取決於工作階段，如[找出 mod 為什麼不執行任何操作](/docs/zh-TW/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)所列。其繪圖不驗證的 `ui.render` hook 的報告方式不同，如[從元素建立樹](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)所述。

343 345

344若要使阻止呼叫的 hook 失敗關閉，請新增 `.catch` 錯誤處理程式以代替回答。此處，`guard` 是您的 hook 函式：346若要使阻止呼叫的 hook 失敗關閉，請新增 `.catch` 錯誤處理程式以代替回答。此處，`guard` 是您的 hook 函式，處理程式會檢查 [`next.called`](/docs/zh-TW/plugins/mods/reference#the-hook-function)，以判斷 `guard` 失敗時是否已呼叫 `next`：

345 347

346```javascript theme={null}348```javascript theme={null}

347// on 傳回註冊，.catch 將處理程式附加到該 hook349// on 傳回註冊，.catch 將處理程式附加到該 hook

348on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {350on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {

349 // next.error.kind 是 'throw' 或 'timeout'，說明 guard 如何失敗351 // guard 已呼叫 next，因此傳回所得到的結果

352 if (next.called) return next(e)

353 // next.error.kind 說明呼叫處理程式的原因，例如 'throw' 或 'timeout'

350 return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }354 return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }

351})355})

352```356```

353 357

354當 `guard` 有效時，處理程式永遠不會執行。當 `guard` 在 Bash 呼叫上擲回或逾時時，Claude Code 使用相同的事件呼叫處理程式。處理程式傳回 `{ deny }`，因此命令不會執行，Claude 讀取末尾帶有 `throw` 或 `timeout` 的文字。沒有處理程式，Claude Code 會跳過 `guard` 並執行命令。處理程式有其自己較短的[時間限制](/docs/zh-TW/plugins/mods/reference#limits)。358當 `guard` 在 Bash 呼叫上擲回或逾時時，Claude Code 使用相同的事件呼叫處理程式：

359

360* **`guard` 在呼叫 `next` 之前失敗**：命令不會執行，Claude 讀取末尾帶有該種類的 `deny` 文字

361* **`guard` 在呼叫 `next` 之後失敗**：處理程式的 `next(e)` 會解析為 `guard` 的呼叫所產生的結果，而不會再次執行命令，Claude 讀取該結果

362

363處理程式有其自己較短的[時間限制](/docs/zh-TW/plugins/mods/reference#limits)。如果處理程式本身擲回或逾時，Claude Code 會跳過該 hook，如同它沒有處理程式一樣。若 `guard` 尚未呼叫 `next`，命令接著會如同沒有該 mod 時一樣繼續執行。

364

365相同的處理程式形式也適用於 `prompt.submit` 或 `config.set` 上的防護。當 `next.called` 為 false 時，傳回[事件參考](/docs/zh-TW/plugins/mods/reference#events)針對該事件列出的拒絕：`prompt.submit` 為 `{ drop: 'the reason' }`，`config.set` 為 `{ deny: 'the reason' }`。

366

367在 `tool.check` 和 `plugin.register`，於 `next` 解析後傳回的拒絕仍然有效，因此直接傳回它，無需檢查 `next.called`：

368

369* **`tool.check`**：傳回 `{ decision: 'deny', reason: 'the reason' }`

370* **`plugin.register`**：傳回 `{ refuse: 'the reason' }`，如[在檢查失敗時拒絕 mod](/docs/zh-TW/plugins/mods/admin#refuse-mods-when-your-check-fails) 所示

355 371

356<h2 id="next-steps">372<h2 id="next-steps">

357 後續步驟373 後續步驟

plugins/mods/gallery.md +8 −0

Details

415 415

416另有兩個元素在此沒有範例。`Image` 會在終端機中繪製 PNG 或原始像素。`Client` 是由您的第二個檔案負責繪製的區域，用於動畫和指標輸入。[元素參考](/docs/zh-TW/plugins/mods/reference#elements)列出了它們的 props。416另有兩個元素在此沒有範例。`Image` 會在終端機中繪製 PNG 或原始像素。`Client` 是由您的第二個檔案負責繪製的區域，用於動畫和指標輸入。[元素參考](/docs/zh-TW/plugins/mods/reference#elements)列出了它們的 props。

417 417

418除非 Claude Code 偵測到終端機能以 Unicode 預留位置字元繪製 kitty 圖形協定影像，否則使用者看到的會是 `Image` 的 `alt` 文字（以暗色顯示），而非圖片。請撰寫能獨立表達意思的 `alt` 文字。偵測會在啟動時執行：在 kitty 0.28 或更新版本以及 Ghostty 中，只要終端機回應 Claude Code 的圖形查詢，偵測即會成功；在下列情況下則會失敗：

419

420* **其他終端機**：不屬於上述兩者的任何終端機，或未回應查詢的終端機。

421* **tmux 和 screen**：在 tmux 或 screen 內執行的工作階段，無論使用哪種終端機，包括 kitty 和 Ghostty。

422* **背景工作階段**：每個[背景工作階段](/docs/zh-TW/agent-view)，無論是從哪個終端機附加的。

423

424如果您的 mod 使用者在確實能繪製這類預留位置影像的終端機中看到暗色文字，可以將 [`CLAUDE_CODE_FORCE_TERMINAL_IMAGES`](/docs/zh-TW/env-vars) 設為 `1`，以略過偵測。在 tmux 或 screen 內這樣做並無幫助：`alt` 文字會消失，且 Claude Code 傳送圖片時不會針對 tmux 或 screen 的直通（passthrough）加以包裝。

425

418<h2 id="see-where-a-mod-can-draw">426<h2 id="see-where-a-mod-can-draw">

419 了解 mod 可以繪製的位置427 了解 mod 可以繪製的位置

420</h2>428</h2>

plugins/mods/interface.md +9 −0

Details

443 443

444在使用 `--plugin-dir` 啟動的工作階段中，逐字稿中會有一行說明這一點，例如 `ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own`。[偵錯日誌](/docs/zh-TW/plugins/mods/troubleshoot#read-the-debug-log)將其記錄為 `ui.render (Pane): a hook returned a tree that does not validate` 並提供相同的原因。工作階段中沒有其他內容出現，因此當繪製不顯示時，請檢查該行或日誌。444在使用 `--plugin-dir` 啟動的工作階段中，逐字稿中會有一行說明這一點，例如 `ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own`。[偵錯日誌](/docs/zh-TW/plugins/mods/troubleshoot#read-the-debug-log)將其記錄為 `ui.render (Pane): a hook returned a tree that does not validate` 並提供相同的原因。工作階段中沒有其他內容出現，因此當繪製不顯示時，請檢查該行或日誌。

445 445

446<h3 id="when-a-client-fails">

447 當 `Client` 失敗時

448</h3>

449

450在終端機中，當 `Client` 執行的檔案失敗時，會有一行變暗的文字（例如 `my-mod: Client client/spinner.js: boom`）取代 `Client` 的位置，而您繪製的其餘部分仍會顯示。

451

452如果您的 mod 處理 [`ui.fault`](/docs/zh-TW/plugins/mods/reference#interface)，Claude Code 接著會[再次繪製該位置](#when-claude-code-redraws-without-being-asked)。

453

446<h3 id="draw-a-grid-of-colored-cells">454<h3 id="draw-a-grid-of-colored-cells">

447 繪製彩色儲存格網格455 繪製彩色儲存格網格

448</h3>456</h3>

806以下規則適用於程式碼：814以下規則適用於程式碼：

807 815

808* **將 `plugin` 和 `key` 寫成文字字串**：`claude plugin validate` 從您的來源讀取它們816* **將 `plugin` 和 `key` 寫成文字字串**：`claude plugin validate` 從您的來源讀取它們

817* **將每個 `atom` 呼叫的結果保存在 `const` 中**：如果您使用 `let` 宣告 `count`，驗證會失敗，出現 `takes a source the scan can read`

809* **在類型宣告檔案中宣告每個值**：否則驗證失敗，出現 `hello-tabs.count is not declared`818* **在類型宣告檔案中宣告每個值**：否則驗證失敗，出現 `hello-tabs.count is not declared`

810* **從回呼或另一個事件的 hook 寫入**：`ui.render` hook 可以讀取狀態，無法寫入它，因此從 `onPress`、`onSubmit` 或另一個事件的 hook 寫入819* **從回呼或另一個事件的 hook 寫入**：`ui.render` hook 可以讀取狀態，無法寫入它，因此從 `onPress`、`onSubmit` 或另一個事件的 hook 寫入

811 820

plugins/mods/overview.md +1 −1

Details

113mod 預設為開啟。在終端機中，請使用 Claude Code v2.1.287 或更新版本。Desktop 應用程式內含自己的 Claude Code 副本，mod 從 v2.1.286 起即可在其中運作。請在您使用 mod 的地方檢查版本：113mod 預設為開啟。在終端機中，請使用 Claude Code v2.1.287 或更新版本。Desktop 應用程式內含自己的 Claude Code 副本，mod 從 v2.1.286 起即可在其中運作。請在您使用 mod 的地方檢查版本：

114 114

115* **終端機**：在您的 shell 中執行 `claude --version`。如果您的版本較舊，請[更新 Claude Code](/docs/zh-TW/setup#update-claude-code)。115* **終端機**：在您的 shell 中執行 `claude --version`。如果您的版本較舊，請[更新 Claude Code](/docs/zh-TW/setup#update-claude-code)。

116* **Desktop 應用程式**：在 Code 標籤的本機工作階段中，輸入 `/status` 並查看 **Claude Code** 列，其中會顯示版本，例如 `2.1.286`。如果您的版本較舊，請更新 Desktop 應用程式。116* **Desktop 應用程式**：在 Code 標籤的本機工作階段中，輸入 `/status` 並查看 **Claude Code** 列，其中會顯示版本，例如 `2.1.286`。如果您的版本較舊，請[更新 Desktop 應用程式](/docs/zh-TW/desktop#claude-code-version-in-the-code-tab)。

117 117

118若要關閉 mods，請選擇要停止多少個，以及停止多長時間。若要將它們重新開啟，請撤銷相同的變更：118若要關閉 mods，請選擇要停止多少個，以及停止多長時間。若要將它們重新開啟，請撤銷相同的變更：

119 119

plugins/mods/reference.md +7 −5

Details

43| `next.origin` | 觸發事件者的 `{ plugin, tier }`。Claude Code 本身為 `{ plugin: 'engine', tier: 'core' }`。mod 的 `tier` 是它在 [mod 執行順序](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in)中的優先群組：`prepend`、`user`、`append` 或 `builtin`。 |43| `next.origin` | 觸發事件者的 `{ plugin, tier }`。Claude Code 本身為 `{ plugin: 'engine', tier: 'core' }`。mod 的 `tier` 是它在 [mod 執行順序](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in)中的優先群組：`prepend`、`user`、`append` 或 `builtin`。 |

44| `next.budget` | hook 的時間限制（毫秒）：`next.budget.ms` 為整體限制，`next.budget.remainingMs` 為目前剩餘時間 |44| `next.budget` | hook 的時間限制（毫秒）：`next.budget.ms` 為整體限制，`next.budget.remainingMs` 為目前剩餘時間 |

45| `next.to(e, tier)` | 跳至較後面的層級，即 `append`、`builtin` 或 `core`。`next.to(e, 'append')` 會略過使用者安裝的 mod。只有 `prependPlugins` 或 `appendPlugins` 中的 mod 可以呼叫它。 |45| `next.to(e, tier)` | 跳至較後面的層級，即 `append`、`builtin` 或 `core`。`next.to(e, 'append')` 會略過使用者安裝的 mod。只有 `prependPlugins` 或 `appendPlugins` 中的 mod 可以呼叫它。 |

46| `next.error`、`next.called` | 僅限 `.catch` 處理常式中。`next.error.kind` 為 `throw` 或 `timeout`，`next.error.message` 為錯誤文字，當失敗的 hook 曾呼叫 `next` 時，`next.called` 為 `true`。 |46| `next.error` | 僅限 `.catch` 處理常式中。當 hook 失敗時，`kind` 為 `throw` 或 `timeout`，`message` 為錯誤文字。當 hook 因事件來自其自身某個 mods API 呼叫內部而被略過時，`kind` 為 `re-entry`；若觸發該事件的是另一個 mod 新增至 mods API 的方法，`cause` 為 `lent`。`re-entry` 與 `cause` 需要 Claude Code v2.1.292 或更新版本。 |

47| `next.called` | 僅限 `.catch` 處理常式中。當 hook 曾呼叫 `next` 時為 `true`。 |

47 48

48<h2 id="events">49<h2 id="events">

49 事件50 事件

259| [`Text`](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |260| [`Text`](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |

260| [`Button`](/docs/zh-TW/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ |261| [`Button`](/docs/zh-TW/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ |

261| `Link` | `href`、`label` | ✓ | ✓ |262| `Link` | `href`、`label` | ✓ | ✓ |

262| `Code` | 程式碼 | ✓ | ✓ |263| [`Code`](/docs/zh-TW/plugins/mods/gallery#show-code-and-changes) | `source`、`language`、`path`、`startLine`、`format`、`wrap` | ✓ | ✓ |

263| `Markdown` | `text`、`key`、`dimColor`、`onLinkPress`、`pressableLinks` | ✓ | ✓ |264| `Markdown` | `text`、`key`、`dimColor`、`onLinkPress`、`pressableLinks` | ✓ | ✓ |

264| [`Input`](/docs/zh-TW/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`、`label`、`placeholder`、`value`、`submitLabel`、`onSubmit`、`onInput`、`autoFocus` | ✓ | ✓ |265| [`Input`](/docs/zh-TW/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`、`label`、`placeholder`、`value`、`submitLabel`、`onSubmit`、`onInput`、`autoFocus` | ✓ | ✓ |

265| `Select` | `key`、`label`、`options`、`value`、`onSelect`、`autoFocus` | ✓ | ✓ |266| `Select` | `key`、`label`、`options`、`value`、`onSelect`、`autoFocus` | ✓ | ✓ |

266| `Svg` | SVG 文件，最多 131,072 個字元 | | ✓ |267| `Svg` | SVG 文件，最多 131,072 個字元 | | ✓ |

267| [`Client`](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements) | `module`、`key` | ✓ | ✓ |268| [`Client`](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements) | `module`、`key` | ✓ | ✓ |

268| [`Raster`](/docs/zh-TW/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`、最多 512 的 `columns`、最多 256 的 `rows`、`cells`。請參閱[繪製彩色儲存格網格](/docs/zh-TW/plugins/mods/interface#draw-a-grid-of-colored-cells)。 | ✓ | |269| [`Raster`](/docs/zh-TW/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`、最多 512 的 `columns`、最多 256 的 `rows`、`cells`。請參閱[繪製彩色儲存格網格](/docs/zh-TW/plugins/mods/interface#draw-a-grid-of-colored-cells)。 | ✓ | |

269| `Image` | 最多 2 MiB 的 PNG 或 RGBA 位元組，或檔案路徑 | ✓ | |270| `Image` | 最多 2 MiB 的 PNG 或 RGBA 位元組，或檔案路徑、最多 255 的 `columns` 和 `rows`，以及 `alt` 文字。 | ✓ | |

270 271

271更多 `Button` 規則：`action` 指定 Claude Code 本身的某個[快捷鍵動作](/docs/zh-TW/keybindings)，當使用者對該動作的綁定為組合鍵或修飾鍵時，該綁定會按下此按鈕。橫帶中按鈕上的數字 `hotkey`，在使用者於空白提示詞中單獨輸入該數字並停頓時也會觸發。當同一次繪製中有兩個按鈕指定相同的 `hotkey` 時，由後者取得。`autoFocus` 在任何控制項上都只接受 `true`，因此若要關閉，請省略此 prop。272更多 `Button` 規則：`action` 指定 Claude Code 本身的某個[快捷鍵動作](/docs/zh-TW/keybindings)，當使用者對該動作的綁定為組合鍵或修飾鍵時，該綁定會按下此按鈕。橫帶中按鈕上的數字 `hotkey`，在使用者於空白提示詞中單獨輸入該數字並停頓時也會觸發。當同一次繪製中有兩個按鈕指定相同的 `hotkey` 時，由後者取得。`autoFocus` 在任何控制項上都只接受 `true`，因此若要關閉，請省略此 prop。

272 273

295 限制296 限制

296</h2>297</h2>

297 298

298hook 與 mods API 呼叫都在時間與大小限制下執行。Claude Code 會略過超過時間限制的 hook，並拒絕超過大小限制的呼叫。299hook 與 mods API 呼叫都在時間與大小限制下執行。Claude Code 會略過超過時間限制的 hook。

299 300

300| 限制 | 值 |301| 限制 | 值 |

301| :- | :- |302| :- | :- |

308| 單一樹狀結構中的文字 | 只繪製前 100,000 個字元 |309| 單一樹狀結構中的文字 | 只繪製前 100,000 個字元 |

310| `Code` 的 `language` 或 `path`、`Select` 選項的 `value`，或 `Client` 的 `module` | 10,000 個字元。若其中任一項較長，Claude Code 會[自行繪製該位置的版本](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)。 |

326| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 環境 | `1` 會讓長時間執行的非互動式工作階段在儲存時重新載入 `--plugin-dir` mod |328| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 環境 | `1` 會讓長時間執行的非互動式工作階段在儲存時重新載入 `--plugin-dir` mod |

327| `prependPlugins`、`appendPlugins` | 受管設定。僅在沒有受管設定的機器上、且使用者未以 Team 或 Enterprise 方案登入時，才可使用使用者設定。 | 外掛 id 的清單，例如 `acme-guard@acme-tools`。`prependPlugins` 中的 mod 會在使用者安裝的每個 mod 之前執行，`appendPlugins` 中的 mod 則在之後執行，並依列出的順序。請參閱 [mod 執行順序](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in)。 |329| `prependPlugins`、`appendPlugins` | 受管設定。僅在沒有受管設定的機器上、且使用者未以 Team 或 Enterprise 方案登入時，才可使用使用者設定。 | 外掛 id 的清單，例如 `acme-guard@acme-tools`。`prependPlugins` 中的 mod 會在使用者安裝的每個 mod 之前執行，`appendPlugins` 中的 mod 則在之後執行，並依列出的順序。請參閱 [mod 執行順序](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in)。 |

328| `allowManagedModsOnly` | 受管設定，作為[內建防護的選項](/docs/zh-TW/plugins/mods/admin#set-options-on-the-built-in-guard) | 只有[屬於您組織的](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods) mod，以及內建於 Claude Code 的 mod 會載入。使用者的設定 hook 會繼續執行。 |330| `allowManagedModsOnly` | 受管設定，作為[內建防護的選項](/docs/zh-TW/plugins/mods/admin#set-options-on-the-built-in-guard) | 只有[屬於您組織的](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods) mod，以及內建於 Claude Code 的 mod，會執行其 hook。使用者的設定 hook 會繼續執行。 |

plugins/mods/test.md +3 −1

Details

107 107

108mods API 呼叫的 stub 返回一個具有 `value` 欄位的物件，該欄位保存呼叫在您的 mod 中解析的內容：`{ value: 7 }` 使 `$.store.get` 解析為 `7`。Claude Code 事件（例如 [`turn.step`](/docs/zh-TW/plugins/mods/reference#turns) 或 `tool.call`）的 stub 返回該事件自己的結果，例如 `{ result: 'ok' }`。`$.session.send` 和 `$.prompt.fill` 也採用其事件的結果，如表所示。[Look up what a stub returns](#look-up-what-a-stub-returns) 顯示每個常見名稱採用的形式。這些錯誤表示 stub 有誤或遺漏。失敗的測試的輸出包括一個以 `the engine reported:` 開頭的區塊，每個錯誤都出現在那裡：108mods API 呼叫的 stub 返回一個具有 `value` 欄位的物件，該欄位保存呼叫在您的 mod 中解析的內容：`{ value: 7 }` 使 `$.store.get` 解析為 `7`。Claude Code 事件（例如 [`turn.step`](/docs/zh-TW/plugins/mods/reference#turns) 或 `tool.call`）的 stub 返回該事件自己的結果，例如 `{ result: 'ok' }`。`$.session.send` 和 `$.prompt.fill` 也採用其事件的結果，如表所示。[Look up what a stub returns](#look-up-what-a-stub-returns) 顯示每個常見名稱採用的形式。這些錯誤表示 stub 有誤或遺漏。失敗的測試的輸出包括一個以 `the engine reported:` 開頭的區塊，每個錯誤都出現在那裡：

109 109

110* `returned neither { value } nor { deny }`：mods API 呼叫的 stub 返回了一個裸值110* `returned neither { value } nor { deny }`：mods API 呼叫的 stub 返回了一個裸值，這會使測試失敗

111* `no implementation for` 後跟一個名稱：您的 mod 進行了該呼叫，沒有 stub 回答它111* `no implementation for` 後跟一個名稱：您的 mod 進行了該呼叫，沒有 stub 回答它

112 112

113該套件還在記憶體中匯出 mocks，為您回答整個命名空間。`mock.clock(on)` 回答 [`$.clock`](/docs/zh-TW/plugins/mods/api#run-work-in-the-background)，`mock.store(on, { count: 7 })` 從以這些項目開始的存儲中回答 `$.store`，`mock.env(on, { CI: 'true' })` 從這些變數中回答 `$.env.get`。`mock.clock` 返回一個您的測試可以推進的模擬時鐘，因此計時器測試不會等待。`mock.store` 不返回任何內容，因此要檢查您的 mod 保存了什麼，請自己編寫兩個 `store` stubs，如 [drawing test](#test-a-drawing) 所做的那樣。113該套件還在記憶體中匯出 mocks，為您回答整個命名空間。`mock.clock(on)` 回答 [`$.clock`](/docs/zh-TW/plugins/mods/api#run-work-in-the-background)，`mock.store(on, { count: 7 })` 從以這些項目開始的存儲中回答 `$.store`，`mock.env(on, { CI: 'true' })` 從這些變數中回答 `$.env.get`。`mock.clock` 返回一個您的測試可以推進的模擬時鐘，因此計時器測試不會等待。`mock.store` 不返回任何內容，因此要檢查您的 mod 保存了什麼，請自己編寫兩個 `store` stubs，如 [drawing test](#test-a-drawing) 所做的那樣。

198 198

199`expect` 有斷言 `toBe`、`toEqual`、`toMatch`、`toMatchObject`、`toContain`、`toBeDefined`、`toBeUndefined` 和 `toThrow`，以及任何斷言之前的 `.not`。199`expect` 有斷言 `toBe`、`toEqual`、`toMatch`、`toMatchObject`、`toContain`、`toBeDefined`、`toBeUndefined` 和 `toThrow`，以及任何斷言之前的 `.not`。

200 200

201當 `expect` 在您以一般函數（而非非同步生成器）傳給 `on` 的 stub 或 hook 內失敗時，測試會失敗。引擎會跳過該 hook，失敗輸出會指出它，例如 `in the test's store.set hook`。

202

201<h2 id="test-a-timer">203<h2 id="test-a-timer">

202 測試計時器204 測試計時器

203</h2>205</h2>

plugins/mods/troubleshoot.md +33 −11

Details

6 6

7> 找出 Claude Code mod 為什麼沒有作用：將症狀或訊息與其原因相符，查詢拒絕訊息，並閱讀偵錯日誌。7> 找出 Claude Code mod 為什麼沒有作用：將症狀或訊息與其原因相符，查詢拒絕訊息，並閱讀偵錯日誌。

8 8

9當 mod 的模組或其中一個 hooks 失敗時，Claude Code 會跳過它，工作階段會繼續進行，因此損壞的 mod 看起來可能像沒有作用的 mod。首先檢查 Claude Code 從您的 mod 讀取了什麼，以及它在哪裡報告問題，然後找到您遇到的症狀或訊息。9當 mod 的模組或其中一個 hook 失敗時，Claude Code 會跳過它，工作階段會繼續進行，因此損壞的 mod 看起來可能像沒有作用的 mod。首先檢查 Claude Code 從您的 mod 讀取了什麼，以及它在哪裡報告問題，然後找到您遇到的症狀或訊息。

10 10

11<h2 id="find-out-why-a-mod-does-nothing">11<h2 id="find-out-why-a-mod-does-nothing">

12 找出 mod 為什麼沒有作用12 找出 mod 為什麼沒有作用

30| :- | :- |30| :- | :- |

31| `no hooks module to load` | Mod 可以載入。該命令在此目錄中找不到要測試的 mod。 |31| `no hooks module to load` | Mod 可以載入。該命令在此目錄中找不到要測試的 mod。 |

32| `hooks modules are turned off here` | 設定正在阻止您的 mod：您自己設定中的 `disableAllHooks`，或您的組織的原則 |32| `hooks modules are turned off here` | 設定正在阻止您的 mod：您自己設定中的 `disableAllHooks`，或您的組織的原則 |

34| `hooks modules are turned off in this process: the rollout switch was saved off by an earlier session` | 該命令使用了先前工作階段儲存的值，該值可能已過時。請啟動 `claude` 一次以重新整理它，然後再次執行該命令。 |

34 35

35組織也可以設定 `allowManagedModsOnly` 以僅允許其自己的 mod，此命令不會報告。在這種情況下，您安裝的 mod 不會載入，並且[訊息會說明原因](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)。36組織也可以設定 `allowManagedModsOnly` 以僅允許其自己的 mod，此命令不會報告。在這種情況下，Claude Code 會拒絕您安裝的 mod，並且[訊息會說明原因](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)。

36 37

37<h2 id="the-mod-doesn’t-load">38<h2 id="the-mod-doesn’t-load">

38 mod 不載入39 mod 不載入

72 73

73| 訊息開頭為 | 這表示什麼 |74| 訊息開頭為 | 這表示什麼 |

74| :- | :- |75| :- | :- |

77| `hooks modules are turned off for installed plugins in this process: the rollout switch was saved off by an earlier session` | 該工作階段使用了先前工作階段儲存的值，該值可能已過時。請重新啟動 Claude Code 以重新整理它。 |

76| `disableAllHooks in managed settings` | 您的組織關閉了已安裝 plugin 的 hooks |78| `disableAllHooks in managed settings` | 您的組織關閉了已安裝 plugin 的 hooks |

77| `only managed plugins and built-in plugins run` | 設定了 `allowManagedHooksOnly`，或在受管設定以外的設定檔中設定了 `disableAllHooks` |79| `only managed plugins and built-in plugins run` | 設定了 `allowManagedHooksOnly`，或在受管設定以外的設定檔中設定了 `disableAllHooks` |

78| `installed plugins that are not managed load no hooks module in this mode (--bare)` | 您使用 `--bare` 啟動了 Claude Code |80| `installed plugins that are not managed load no hooks module in this mode (--bare)` | 您使用 `--bare` 啟動了 Claude Code |

86 88

88| :- | :- | :- |90| :- | :- | :- |

89| `mods are limited to your organization's by policy (allowManagedModsOnly)` | 您的組織僅允許[其自己的 mod](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods)，因此您的 mod 未被載入 | 偵錯日誌，以及[熱重新載入 plugin 目錄的工作階段](#find-out-why-a-mod-does-nothing)中的文字記錄 |91| `mods are limited to your organization's by policy (allowManagedModsOnly)` | 您的組織僅允許[其自己的 mod](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods)，因此您的 mod 被拒絕 | 偵錯日誌，以及[熱重新載入外掛目錄的工作階段](#find-out-why-a-mod-does-nothing)中的逐字稿 |

90| `tried to lift a deny rule in your settings` | 您的 mod 的 [`tool.check`](/docs/zh-TW/plugins/mods/reference#tools) hook 批准了 `deny` 規則拒絕的呼叫。呼叫保持被拒絕。 | 文字記錄和偵錯日誌，每個工作階段中的每個 mod 一次。在 `claude -p` 執行中，僅偵錯日誌。 |92| `tried to lift a deny rule in your settings` | 您的 mod 的 [`tool.check`](/docs/zh-TW/plugins/mods/reference#tools) hook 批准了 `deny` 規則拒絕的呼叫。呼叫保持被拒絕。 | 文字記錄和偵錯日誌，每個工作階段中的每個 mod 一次。在 `claude -p` 執行中，僅偵錯日誌。 |

92 94

163 165

164修復 hook。166修復 hook。

165 167

168<h3 id="its-session-start-ran-again-in-a-fresh-copy">

169 `its session.start ran again in a fresh copy`

170</h3>

171

172該行以 mod 的名稱開頭，並命名一個 `$.prompt.submit`、`$.command.run` 或 `$.agent.spawn` 呼叫，例如 `first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again`。Claude Code 再次載入了 mod 的模組，例如在 hook 工作執行緒崩潰並被取代之後，而新副本的 [`session.start`](/docs/zh-TW/plugins/mods/reference#session) hook 執行了。該行命名的呼叫以其第一次執行的結果解析，而不是再次執行，因此您的 mod 不會重複提交提示詞、執行命令或啟動 subagent。hook 的其餘部分照常執行。

173

174無需修復任何內容。

175

176在 v2.1.292 之前，該呼叫會執行第二次，因此提示詞會被提交兩次、命令會被執行兩次，或 subagent 會被啟動兩次。

177

166<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">178<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">

167 `mods that run in the hooks worker are off for this session`179 `mods that run in the hooks worker are off for this session`

168</h3>180</h3>

203 窗格或帶狀為空或顯示 Claude Code 的常見內容215 窗格或帶狀為空或顯示 Claude Code 的常見內容

204</h3>216</h3>

205 217

206您的 hook 返回的[樹](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)未驗證。使用 `--plugin-dir`，文字記錄說 `ui.render (Pane) refused:` 並帶有原因，例如 `first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own`。偵錯日誌有 `a hook returned a tree that does not validate` 並帶有相同的原因。218您的 hook 返回的[樹](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)未通過驗證。使用 `--plugin-dir` 時，逐字稿會顯示 `ui.render (Pane) refused:` 並附上原因，例如 `first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own`。偵錯日誌中會有 `a hook returned a tree that does not validate` 並附上相同的原因。

207 219

208讀取該行上的原因。常見原因是元素不接受的 prop 和應用程式沒有的元素。220讀取該行上的原因。常見原因是元素不接受的 prop 和應用程式沒有的元素。

209 221

222<h3 id="the-module-failed-without-a-message">

223 `the module failed without a message`

224</h3>

225

226某個 [`Client`](/docs/zh-TW/plugins/mods/interface#when-a-client-fails) 因沒有訊息的錯誤而失敗，例如 `throw new Error()`。在其位置顯示的那一行類似 `my-mod: Client client/spinner.js: the module failed without a message`。

227

228在您的 `Client` 程式碼中找到該 throw，並為錯誤加上訊息。該行隨後便會顯示該訊息。

229

230在 v2.1.289 之前，該行會改為顯示 `Error` 作為原因。

231

210<h3 id="$-ui-open-runs-and-no-pane-appears">232<h3 id="$-ui-open-runs-and-no-pane-appears">

211 `$.ui.open` 執行且沒有窗格出現233 `$.ui.open` 執行且沒有窗格出現

212</h3>234</h3>

227 繪圖在終端機中有效，但在 Desktop 應用程式中無效249 繪圖在終端機中有效，但在 Desktop 應用程式中無效

228</h3>250</h3>

229 251

230該網站或元素在那裡不可用。252該位置或元素在那裡不可用。

231 253

232檢查[呈現網站](/docs/zh-TW/plugins/mods/reference#render-sites)和[元素](/docs/zh-TW/plugins/mods/reference#elements)表。254檢查[轉譯位置](/docs/zh-TW/plugins/mods/reference#render-sites)和[元素](/docs/zh-TW/plugins/mods/reference#elements)表。

233 255

234<h2 id="an-edit-or-a-value-is-lost">256<h2 id="an-edit-or-a-value-is-lost">

235 編輯或值遺失257 編輯或值遺失

265 讀取偵錯日誌287 讀取偵錯日誌

266</h2>288</h2>

267 289

268偵錯日誌對 Claude Code 載入或拒絕的每個模組、失敗的每個 hook 和它拒絕的每個結果都有一行，因此當文字記錄顯示沒有內容時，這是要查看的地方。若要寫入一個，在您的 shell 中使用 `--debug` 啟動 Claude Code，或使用 `--debug-file <path>` 選擇它的位置：290偵錯日誌對 Claude Code 載入或拒絕的每個模組、失敗的每個 hook 和它拒絕的每個結果都有一行，因此當逐字稿顯示沒有內容時，這是要查看的地方。若要寫入一個，在您的 shell 中使用 `--debug` 啟動 Claude Code，或使用 `--debug-file <path>` 選擇它的位置：

269 291

270```bash theme={null}292```bash theme={null}

271claude --debug-file ./mod-debug.log --plugin-dir ./first-mod293claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

283hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render305hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

284```306```

285 307

286未驗證的繪圖計為被拒絕的結果，也會得到一行。若要在日誌中寫入您自己的行，請呼叫 [`$.ui.log`](/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn)，並帶有第二個引數，例如 `$.ui.log('message', { to: 'debug' })`。沒有第二個引數，`$.ui.log` 會在文字記錄中新增暗淡行。308未驗證的繪圖計為被拒絕的結果，也會得到一行。若要在日誌中寫入您自己的行，請呼叫 [`$.ui.log`](/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn)，並帶有第二個引數，例如 `$.ui.log('message', { to: 'debug' })`。沒有第二個引數，`$.ui.log` 會在逐字稿中新增暗淡行。

287 309

288當您編輯使用 `--plugin-dir` 載入的 mod 時，文字記錄會為每次重新載入顯示一行，其命名 mod 並列出其 hook。如果儲存破壞了模組，該行說 `reload failed, the previous version stays loaded:` 並帶有原因，最後一個工作版本保持執行。310當您編輯使用 `--plugin-dir` 載入的 mod 時，逐字稿會為每次重新載入顯示一行，其命名 mod 並列出其 hook。如果儲存破壞了模組，該行說 `reload failed, the previous version stays loaded:` 並帶有原因，最後一個可運作的版本會保持執行，直到 Claude Code 下次重新載入外掛為止，例如當您執行 `/reload-plugins` 時。

289 311

290<h2 id="next-steps">312<h2 id="next-steps">

291 後續步驟313 後續步驟

plugins/org.md +1 −1

Details

214| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/zh-TW/env-vars) | 停止互動式終端機工作階段自動註冊官方市場 | 不移除已註冊的市場。允許清單和封鎖清單在沒有它的情況下控制相同的自動註冊。在設定它的情況下啟動一次的機器在您取消設定後不會恢復自動註冊 |214| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/zh-TW/env-vars) | 停止互動式終端機工作階段自動註冊官方市場 | 不移除已註冊的市場。允許清單和封鎖清單在沒有它的情況下控制相同的自動註冊。在設定它的情況下啟動一次的機器在您取消設定後不會恢復自動註冊 |

215| [`allowManagedModsOnly`](/docs/zh-TW/plugins/mods/admin#stop-user-installed-mods-from-loading) | 停止每個已安裝的[mod](/docs/zh-TW/plugins/mods/overview)，其不[計為您組織的](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods)從載入 | 不停止包含 mod 的外掛程式安裝。為此，使用此表中的市場金鑰 |215| [`allowManagedModsOnly`](/docs/zh-TW/plugins/mods/admin#stop-user-installed-mods-from-loading) | 阻止每個不[屬於您組織](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods)的已安裝 [mod](/docs/zh-TW/plugins/mods/overview) 執行其 hook | 不會阻止包含 mod 的外掛安裝。若要這麼做，請使用此表中的市集鍵 |

216 216

217表中的每個金鑰都是受管設定，除了 `enabledPlugins`、`syncClaudeAiPlugins`、`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 和 `allowManagedModsOnly`：217表中的每個金鑰都是受管設定，除了 `enabledPlugins`、`syncClaudeAiPlugins`、`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 和 `allowManagedModsOnly`：

218 218

plugins/security.md +2 −1

Details

29Plugin 可以攜帶在您的機器上使用您的使用者權限執行程式碼的內容，以及進入 Claude 上下文作為指令的內容，所以[在安裝前檢查 plugin](#review-a-plugin-before-you-install)。以下是已安裝的 plugin 可以執行的操作：29Plugin 可以攜帶在您的機器上使用您的使用者權限執行程式碼的內容，以及進入 Claude 上下文作為指令的內容，所以[在安裝前檢查 plugin](#review-a-plugin-before-you-install)。以下是已安裝的 plugin 可以執行的操作：

30 30

31* **Hooks**：plugin 的 [hooks](/docs/zh-TW/hooks) 在 Claude Code 生命週期中的特定點（例如工具呼叫之前或之後）作為 shell 命令執行。31* **Hooks**：plugin 的 [hooks](/docs/zh-TW/hooks) 在 Claude Code 生命週期中的特定點（例如工具呼叫之前或之後）作為 shell 命令執行。

32* **Monitors**：plugin 的 [monitors](/docs/zh-TW/plugins/components#monitors) 作為背景 shell 命令執行，Claude Code 會在工作階段開始時、您重新載入 plugin 時，或指定的 skill 首次執行時自行啟動它們。

32* **Mods**：plugin 的 [mod](/docs/zh-TW/plugins/mods/overview) 在 Claude Code 內使用您的權限執行 JavaScript。要在安裝前列出 mod 執行的操作，請參閱[決定是否信任 mod](/docs/zh-TW/plugins/mods/overview#decide-whether-to-trust-a-mod)。33* **Mods**：plugin 的 [mod](/docs/zh-TW/plugins/mods/overview) 在 Claude Code 內使用您的權限執行 JavaScript。要在安裝前列出 mod 執行的操作，請參閱[決定是否信任 mod](/docs/zh-TW/plugins/mods/overview#decide-whether-to-trust-a-mod)。

33* **MCP 和 LSP 伺服器**：Claude Code 連接到已啟用的 plugin 聲明的 [MCP 伺服器](/docs/zh-TW/mcp)，並為 Claude 提供它們的工具。Stdio MCP 伺服器作為 Claude Code 在您的機器上啟動的程序執行。Claude Code 也啟動 plugin 聲明的語言伺服器。34* **MCP 和 LSP 伺服器**：Claude Code 連接到已啟用的 plugin 聲明的 [MCP 伺服器](/docs/zh-TW/mcp)，並為 Claude 提供它們的工具。Stdio MCP 伺服器作為 Claude Code 在您的機器上啟動的程序執行。Claude Code 也啟動 plugin 聲明的語言伺服器。

34* **`bin/` 目錄**：Claude Code 將每個已啟用的 plugin 的 `bin/` 目錄新增到 Bash 工具的 shell 的 `PATH`，所以 Claude 的 Bash 命令可以執行那裡的任何可執行檔。35* **`bin/` 目錄**：Claude Code 將每個已啟用的 plugin 的 `bin/` 目錄新增到 Bash 工具的 shell 的 `PATH`，所以 Claude 的 Bash 命令可以執行那裡的任何可執行檔。

37 38

38Claude Code 的[權限規則](/docs/zh-TW/permissions)和[沙箱](/docs/zh-TW/sandboxing)涵蓋 Claude 進行的工具呼叫，而不是 plugin 自己執行的程式碼：39Claude Code 的[權限規則](/docs/zh-TW/permissions)和[沙箱](/docs/zh-TW/sandboxing)涵蓋 Claude 進行的工具呼叫，而不是 plugin 自己執行的程式碼：

39 40

40* **Hooks 和伺服器程序**：命令 hooks 使用您的完整使用者權限執行 shell 命令。Claude Code 在沙箱外執行 hooks、MCP 伺服器，以及 [mod](/docs/zh-TW/plugins/mods/overview#what-a-mod-can-reach) 啟動的程序。41* **Hooks、monitors 和伺服器程序**：命令 hooks 和 monitors 是使用您的完整使用者權限執行的 shell 命令。Claude Code 在沙箱外執行 hooks、monitors、MCP 伺服器、LSP 伺服器，以及 [mod](/docs/zh-TW/plugins/mods/overview#what-a-mod-can-reach) 啟動的程序。

41* **Claude 的工具呼叫**：對 plugin 的 MCP 工具之一的呼叫，以及執行 plugin 的 `bin/` 中的可執行檔的 Bash 命令，都是工具呼叫，所以您的權限規則適用於它們。如需 mod 可以對工具呼叫執行的操作，請參閱[決定是否信任 mod](/docs/zh-TW/plugins/mods/overview#decide-whether-to-trust-a-mod)。42* **Claude 的工具呼叫**：對 plugin 的 MCP 工具之一的呼叫，以及執行 plugin 的 `bin/` 中的可執行檔的 Bash 命令，都是工具呼叫，所以您的權限規則適用於它們。如需 mod 可以對工具呼叫執行的操作，請參閱[決定是否信任 mod](/docs/zh-TW/plugins/mods/overview#decide-whether-to-trust-a-mod)。

42 43

43安裝 plugin 也會啟用它，除非其 manifest 或 marketplace 項目設定了 [`defaultEnabled: false`](/docs/zh-TW/plugins/install#choose-an-install-scope)，且您自己還沒有啟用它。44安裝 plugin 也會啟用它，除非其 manifest 或 marketplace 項目設定了 [`defaultEnabled: false`](/docs/zh-TW/plugins/install#choose-an-install-scope)，且您自己還沒有啟用它。

quickstart.md +16 −14

Details

53 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd53 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

54 ```54 ```

55 55

56 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。56 安裝命令在下載 Claude Code 時不會顯示進度。當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的 shell 說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。

57 57

58 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。58 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。

59 59

229 步驟 7：試用其他常見工作流程229 步驟 7：試用其他常見工作流程

230</h2>230</h2>

231 231

232與 Claude 協作的方式有很多種：232再試試幾個提示詞。您可以請 Claude 重構程式碼、撰寫測試、更新文件，或審查您的變更：

~~233~~

234**重構程式碼**

235 233

236```text wrap theme={null}234```text wrap theme={null}

237refactor the authentication module to use async/await instead of callbacks235refactor the authentication module to use async/await instead of callbacks

238```236```

239 237

240**撰寫測試**

~~241~~

242```text wrap theme={null}238```text wrap theme={null}

243write unit tests for the calculator functions239write unit tests for the calculator functions

244```240```

245 241

246**更新文件**

~~247~~

248```text wrap theme={null}242```text wrap theme={null}

249update the README with installation instructions243update the README with installation instructions

250```244```

251 245

252**程式碼審查**

~~253~~

254```text wrap theme={null}246```text wrap theme={null}

255review my changes and suggest improvements247review my changes and suggest improvements

256```248```

263 基本命令255 基本命令

264</h2>256</h2>

265 257

266以下是日常使用中最重要的命令。Shell 命令從您的終端機執行以啟動或繼續 Claude Code。工作階段命令在 Claude Code 啟動後在其內部執行。258以下是日常使用中最重要的命令，依執行位置分組。

267 259

268**Shell 命令**260<h3 id="shell-commands">

261 Shell 命令

262</h3>

263

264從您的終端機執行這些命令以啟動或繼續 Claude Code。

269 265

270| 命令 | 功能 | 範例 |266| 命令 | 功能 | 範例 |

271| - | - | - |267| - | - | - |

277 273

278**工作階段命令**274請參閱 [CLI 參考](/docs/zh-TW/cli-reference)以取得完整的 shell 命令清單。

275

276<h3 id="session-commands">

277 工作階段命令

278</h3>

279

280在 Claude Code 啟動後於其內部執行這些命令。

279 281

280| 命令 | 功能 | 範例 |282| 命令 | 功能 | 範例 |

281| - | - | - |283| - | - | - |

285 287

286請參閱 [CLI 參考](/docs/zh-TW/cli-reference)以取得完整的 shell 命令清單，以及 [命令參考](/docs/zh-TW/commands)以取得完整的工作階段命令清單。288請參閱 [命令參考](/docs/zh-TW/commands)以取得完整的工作階段命令清單。

287 289

288<h2 id="pro-tips-for-beginners">290<h2 id="pro-tips-for-beginners">

289 初學者的專業提示291 初學者的專業提示

remote-control.md +2 −2

Details

201* **`false`**：關閉自動連接，儘管來自[受管設定](/docs/zh-TW/managed-settings)的 `true` 會優先，因為 Claude Code 會將選擇儲存到您的使用者設定。專案或本地設定（`.claude/settings.json`、`.claude/settings.local.json`）中的 `false` 會關閉自動連接，即使是受管 `true` 也是如此。201* **`false`**：關閉自動連接，儘管來自[受管設定](/docs/zh-TW/managed-settings)的 `true` 會優先，因為 Claude Code 會將選擇儲存到您的使用者設定。專案或本地設定（`.claude/settings.json`、`.claude/settings.local.json`）中的 `false` 會關閉自動連接，即使是受管 `true` 也是如此。

202* **`default`**：清除您的選擇並遵循您組織的管理員預設值（如果已設定），否則遵循 Claude Code 的目前預設值。202* **`default`**：清除您的選擇並遵循您組織的管理員預設值（如果已設定），否則遵循 Claude Code 的目前預設值。

203 203

204相同的切換也會出現在 CLI 外：204VS Code 擴充功能和 Desktop 應用程式也有自動連接切換：

205 205

206* **Desktop 應用程式**：**設定 > Claude Code > 預設啟用遠端控制**。

207* **VS Code 擴充功能**：[命令選單](/docs/zh-TW/vs-code#use-the-prompt-box)的設定部分中的**為所有會話啟用 Remote Control**。206* **VS Code 擴充功能**：[命令選單](/docs/zh-TW/vs-code#use-the-prompt-box)的設定部分中的**為所有會話啟用 Remote Control**。

207* **Desktop 應用程式**：**設定 > Claude Code > 將新工作階段連接到 Remote Control**。請參閱[控制哪些工作階段出現在您的其他裝置上](/docs/zh-TW/desktop#control-which-sessions-appear-on-your-other-devices)。

208 208

209要改為從設定檔案開啟自動連接，請在您的使用者 `~/.claude/settings.json` 或[受管設定](/docs/zh-TW/managed-settings)中將 [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) 設定為 `true`。在專案或本地設定（`.claude/settings.json`、`.claude/settings.local.json`）中，Claude Code 會遵守 `false` 並為該儲存庫關閉自動連接，但會忽略 `true`，因此已簽入的檔案無法為打開儲存庫的每個人開啟 Remote Control。209要改為從設定檔案開啟自動連接，請在您的使用者 `~/.claude/settings.json` 或[受管設定](/docs/zh-TW/managed-settings)中將 [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) 設定為 `true`。在專案或本地設定（`.claude/settings.json`、`.claude/settings.local.json`）中，Claude Code 會遵守 `false` 並為該儲存庫關閉自動連接，但會忽略 `true`，因此已簽入的檔案無法為打開儲存庫的每個人開啟 Remote Control。

210 210

routines.md +1 −1

Details

93 為例行工作選擇 [cloud environment](/docs/zh-TW/cloud-environments)。環境控制雲端工作階段可以存取的內容：93 為例行工作選擇 [cloud environment](/docs/zh-TW/cloud-environments)。環境控制雲端工作階段可以存取的內容：

94 94

95 * **Network access**：設定每次執行期間可用的網際網路存取級別95 * **Network access**：設定每次執行期間可用的網際網路存取級別

96 * **Environment variables**：提供 Claude 在每次執行期間可以使用的值。這些值[對使用該環境的任何人都可見](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 方案上，請改將 Claude 在執行期間呼叫的 API 金鑰儲存為 [網路機密](/docs/zh-TW/cloud-environments#add-api-credentials)。該章節也列出了永遠不會取得機密的請求96 * **Environment variables**：提供 Claude 在每次執行期間可以使用的值。這些值[對使用該環境的任何人都可見](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 方案上，請改將 Claude 在執行期間呼叫的 API 金鑰儲存為 [網路機密](/docs/zh-TW/cloud-environments#add-network-secrets)。該章節也列出了永遠不會取得機密的請求

97 * **Setup script**：安裝例行工作需要的相依性和工具。結果是 [cached](/docs/zh-TW/cloud-environments#environment-caching)，因此指令碼不會在每個工作階段上重新執行97 * **Setup script**：安裝例行工作需要的相依性和工具。結果是 [cached](/docs/zh-TW/cloud-environments#environment-caching)，因此指令碼不會在每個工作階段上重新執行

98 98

99 提供了 **Default** 環境，具有 **Trusted** 網路存取，它只允許 [default allowlist](/docs/zh-TW/cloud-environments#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域透過工作階段的網路。您新增到例行工作的連接器透過 Anthropic 的伺服器存取其服務，因此不需要更改允許清單。如果您的例行工作需要直接存取您自己的服務或該清單外的網域，請在執行前編輯環境的 [network access](/docs/zh-TW/cloud-environments#network-access)。若要使用單獨的環境，請先 [create one](/docs/zh-TW/cloud-environments#configure-your-environment)。99 提供了 **Default** 環境，具有 **Trusted** 網路存取，它只允許 [default allowlist](/docs/zh-TW/cloud-environments#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域透過工作階段的網路。您新增到例行工作的連接器透過 Anthropic 的伺服器存取其服務，因此不需要更改允許清單。如果您的例行工作需要直接存取您自己的服務或該清單外的網域，請在執行前編輯環境的 [network access](/docs/zh-TW/cloud-environments#network-access)。若要使用單獨的環境，請先 [create one](/docs/zh-TW/cloud-environments#configure-your-environment)。

sandbox-environments.md +3 −3

Details

22 22

23| 方法 | 隔離的內容 | 需要 Docker | 設定工作量 |23| 方法 | 隔離的內容 | 需要 Docker | 設定工作量 |

24| :- | :- | :- | :- |24| :- | :- | :- | :- |

~~25| [Sandboxed Bash tool](#sandboxed-bash-tool) | Bash、PowerShell 和 Monitor 命令及其子進程 | 否 | macOS 上最少；Linux 和 WSL2 上較少 |~~25| [Sandboxed Bash tool](#sandboxed-bash-tool) | Bash、PowerShell 和 Monitor 工具命令及其子程序 | 否 | macOS 上最少；Linux 和 WSL2 上較少 |

26| [Sandbox runtime](#sandbox-runtime) | 整個 Claude Code 進程，包括檔案工具、MCP 伺服器和 hooks | 否 | 較少 |26| [Sandbox runtime](#sandbox-runtime) | 整個 Claude Code 進程，包括檔案工具、MCP 伺服器和 hooks | 否 | 較少 |

27| [Dev container](#dev-containers) | 完整開發環境 | 是 | 中等 |27| [Dev container](#dev-containers) | 完整開發環境 | 是 | 中等 |

28| [Custom container](#custom-container) | 完整開發環境 | 是 | 中等到高 |28| [Custom container](#custom-container) | 完整開發環境 | 是 | 中等到高 |

76 此選項不支援原生 Windows。在 Windows 主機上，使用 WSL2 或下面的容器或虛擬機方法之一。76 此選項不支援原生 Windows。在 Windows 主機上，使用 WSL2 或下面的容器或虛擬機方法之一。

77</Note>77</Note>

78 78

~~79Sandboxed Bash tool 內建於 Claude Code 中。它使用作業系統原語來限制 Claude 執行的每個 Bash、PowerShell 或 Monitor 命令的檔案系統和網路存取。~~79Sandboxed Bash tool 內建於 Claude Code 中。它使用作業系統原語來限制 Claude 執行的 Bash、PowerShell 和 Monitor 工具命令的檔案系統和網路存取。

80 80

81執行 `/sandbox` 命令以開啟沙箱面板並選擇一個模式。[Sandboxing](/docs/zh-TW/sandboxing) 指南涵蓋批准模式、預設邊界以及如何擴大或縮小它。81執行 `/sandbox` 命令以開啟沙箱面板並選擇一個模式。[Sandboxing](/docs/zh-TW/sandboxing) 指南涵蓋批准模式、預設邊界以及如何擴大或縮小它。

82 82

83每個命令沙箱不涵蓋在會話中執行的所有內容：83每個命令沙箱不涵蓋在會話中執行的所有內容：

84 84

85* 其他 [built-in tools](/docs/zh-TW/tools-reference)（如 Read、Edit 和 WebFetch）在 Claude Code 進程內執行，不會生成任意程式碼。[Permission rules](/docs/zh-TW/permissions) 用於路徑或域來控制它們。85* 其他 [built-in tools](/docs/zh-TW/tools-reference)（如 Read、Edit 和 WebFetch）在 Claude Code 進程內執行，不會生成任意程式碼。[Permission rules](/docs/zh-TW/permissions) 用於路徑或域來控制它們。

~~86* [MCP](/docs/zh-TW/mcp) 伺服器和 [command hooks](/docs/zh-TW/hooks#command-hook-fields) 是在主機上無約束執行的獨立進程。~~86* [MCP](/docs/zh-TW/mcp) 伺服器、[command hook](/docs/zh-TW/hooks#command-hook-fields) 和[外掛監視器](/docs/zh-TW/plugins/components#monitors)是在主機上不受限制執行的獨立程序。關於以此方式執行的其他程序，請參閱[在沙箱外執行的內容](/docs/zh-TW/sandboxing#what-runs-outside-the-sandbox)。

87 87

88要將內建工具、MCP 伺服器和 hooks 全部放在一個作業系統邊界後面，請在 [sandbox runtime](#sandbox-runtime)、[dev container](#dev-containers) 或 [custom container](#custom-container) 內執行整個 Claude Code 進程。88要將內建工具、MCP 伺服器和 hooks 全部放在一個作業系統邊界後面，請在 [sandbox runtime](#sandbox-runtime)、[dev container](#dev-containers) 或 [custom container](#custom-container) 內執行整個 Claude Code 進程。

89 89

sandboxing.md +1 −1

Details

698權限規則和沙箱隔離控制不同的事項：698權限規則和沙箱隔離控制不同的事項：

699 699

700* **權限規則**控制 Claude Code 可以使用哪些工具，並在任何工具執行前進行評估。它們適用於每個工具：Bash、Read、Edit、WebFetch、MCP 和其他工具，除了拒絕或詢問規則無法阻止 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior)，而其他任何工具仍然存在。700* **權限規則**控制 Claude Code 可以使用哪些工具，並在任何工具執行前進行評估。它們適用於每個工具：Bash、Read、Edit、WebFetch、MCP 和其他工具，除了拒絕或詢問規則無法阻止 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior)，而其他任何工具仍然存在。

701* **沙箱隔離**提供作業系統層級的強制執行，限制 shell 命令在檔案系統和網路層級可以存取的內容。它僅適用於 Bash、PowerShell 和 [Monitor](/docs/zh-TW/tools-reference#monitor-tool) 命令及其子程序。701* **沙箱機制**提供作業系統層級的強制執行，限制 shell 命令在檔案系統和網路層級可以存取的內容。它適用於 Bash、PowerShell 和 [Monitor](/docs/zh-TW/tools-reference#monitor-tool) 工具命令及其子程序。

702 702

703這兩個層級在強制執行方式上也有所不同。Claude Code 在命令執行前根據命令字串評估權限決定，在自動模式下，還會根據單獨分類器對命令是否安全的判斷。作業系統在執行中的程序上強制執行沙箱邊界，因此無論模型選擇執行什麼，即使允許的命令執行的操作超出其名稱所示，它都會保持有效。703這兩個層級在強制執行方式上也有所不同。Claude Code 在命令執行前根據命令字串評估權限決定，在自動模式下，還會根據單獨分類器對命令是否安全的判斷。作業系統在執行中的程序上強制執行沙箱邊界，因此無論模型選擇執行什麼，即使允許的命令執行的操作超出其名稱所示，它都會保持有效。

704 704

server-managed-settings.md +16 −11

Details

339 平台可用性339 平台可用性

340</h2>340</h2>

341 341

342伺服器管理的設定需要直接連線到 `api.anthropic.com`。傳遞也需要工作階段使用以下其中一個認證進行驗證：342伺服器受管設定需要直接連線至 `api.anthropic.com`。傳遞設定還需要工作階段使用下列其中一種憑證進行身分驗證：

343 343

344* Team 或 Enterprise OAuth 登入344* Team 或 Enterprise OAuth 登入

345* 透過 `CLAUDE_CODE_OAUTH_TOKEN` 提供的 OAuth 權杖345* 透過 `CLAUDE_CODE_OAUTH_TOKEN` 提供的 OAuth token

346* 直接配置的 API 金鑰346* 直接設定的 API 金鑰

347* 一個 `user_oauth` [Anthropic 設定檔](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)，除非設定檔設定了 `base_url` 不同於 Anthropic API。需要 Claude Code v2.1.257 或更新版本。347* `user_oauth` [Anthropic 設定檔](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)，除非該設定檔將 `base_url` 設為 Anthropic API 以外的位址。需要 Claude Code v2.1.257 或更新版本。

348 348

349由 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼傳回的金鑰和[工作負載身分識別聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)認證都不會觸發設定擷取。349由 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼傳回的金鑰，以及 [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 憑證，都不會觸發設定擷取。

350 350

351在 Claude Desktop 應用程式中的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中，Claude Code 不會從 claude.ai 管理員主控台擷取伺服器管理的設定，即使使用者使用 Team 或 Enterprise 帳戶登入也是如此。[原則適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)涵蓋了哪些原則會到達使用者機器上的 Cowork 工作階段和遠端 Cowork 工作階段。claude.ai 在 Cowork 使用者從 git 儲存庫或從 Cowork 標籤中的**自訂**新增市集時，仍會套用您的 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) 清單。[限制如何運作](/docs/zh-TW/plugins/org#restrict-what-users-can-install)說明了該檢查。351工作階段會收到其用於身分驗證之憑證所屬組織的受管設定。來自 [Claude Console](https://platform.claude.com) 的 API 金鑰屬於建立該金鑰的 Console 組織，而該組織與您的 claude.ai Team 或 Enterprise 組織是不同的組織。因此，您在 claude.ai 管理設定中設定的內容，不會套用至使用該金鑰進行身分驗證的工作階段，例如使用貴公司 Console API 金鑰的 CI 作業。若要將這些設定套用至該作業，請使用下列其中一個選項。OAuth token 選項不適用於以 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) 執行的作業，因為 bare 模式不會讀取 `CLAUDE_CODE_OAUTH_TOKEN`。

352 352

353如果您在殼層中匯出 `CLAUDE_CODE_USE_*` 提供者變數或非預設的 `ANTHROPIC_BASE_URL`，Claude Code 會略過您工作階段的設定擷取。[`claude doctor` 和 `/status` 報告略過的擷取及其原因](#verify-settings-delivery)。353* **OAuth token**：使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生 token，為您的 Team 或 Enterprise 組織授權該 token，並在作業的環境中將其設為 `CLAUDE_CODE_OAUTH_TOKEN`。從該環境中移除任何[優先於](/docs/zh-TW/authentication#authentication-precedence)該 token 的憑證，例如 `ANTHROPIC_API_KEY`。

354* **端點受管設定**：將[受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)部署至執行該作業的機器。

354 355

355您無法使用伺服器管理的 `env` 區塊清除匯出，因為該區塊是透過匯出所防止的擷取來傳遞的。[端點管理的設定](/docs/zh-TW/managed-settings#delivery-mechanisms) `env` 區塊也不會還原擷取：Claude Code 在套用管理的 `env` 區塊之前會檢查合格性，因此端點管理的值會變更工作階段的提供者選擇，但擷取仍會被略過。356在 Claude Desktop 應用程式的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中，即使使用者以 Team 或 Enterprise 帳戶登入，Claude Code 也不會從 claude.ai 管理主控台擷取伺服器受管設定。[政策的套用位置與時機](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)說明了哪些政策會套用至使用者機器上的 Cowork 工作階段以及遠端 Cowork 工作階段。當 Cowork 使用者在 claude.ai 上從 git 儲存庫新增市集，或從 Cowork 分頁中的 **Customize** 新增市集時，claude.ai 仍會自行套用您的 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) 清單。[限制的運作方式](/docs/zh-TW/plugins/org#restrict-what-users-can-install)說明了該檢查。

356 357

357若要還原伺服器管理的傳遞，請從殼層移除匯出，或在您的使用者設定 `env` 區塊中將變數設定為 `""`，這會在合格性檢查之前套用。若要在不依賴使用者變更其殼層的情況下強制執行原則，請改為透過端點管理的通道傳遞設定。358如果您在 shell 中匯出 `CLAUDE_CODE_USE_*` 提供者變數或非預設的 `ANTHROPIC_BASE_URL`，Claude Code 會為您的工作階段略過設定擷取。[`claude doctor` 和 `/status` 會回報已略過的擷取及其原因](#verify-settings-delivery)。

358 359

359對於 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws)部署，自託管的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)提供等效的遠端管理設定傳遞：閘道登入的用戶端從閘道而不是 `api.anthropic.com` 擷取管理設定。啟動時的失敗語義不同：無法到達閘道的閘道用戶端會以錯誤結束，而不是回退到快取的設定，而每小時的背景重新整理在兩個通道上都是開放失敗的。360您無法使用伺服器受管的 `env` 區塊清除該匯出，因為該區塊是透過被該匯出阻止的擷取而送達的。[端點受管設定](/docs/zh-TW/managed-settings#delivery-mechanisms)的 `env` 區塊也無法恢復擷取：Claude Code 會在套用受管 `env` 區塊之前檢查資格，因此端點受管的值會變更工作階段的提供者選擇，但擷取仍會被略過。

361

362若要恢復伺服器受管的傳遞，請從您的 shell 中移除該匯出，或在您的使用者設定 `env` 區塊中將該變數設為 `""`，該區塊會在資格檢查之前套用。若要在不依賴使用者變更其 shell 的情況下強制執行政策，請改為透過端點受管頻道傳遞設定。

363

364對於 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 以及 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 部署，自行託管的 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)提供等效的遠端受管設定傳遞：透過閘道登入的用戶端會從閘道而非 `api.anthropic.com` 擷取受管設定。啟動時的失敗處理方式有所不同：無法連線至閘道的閘道用戶端會以錯誤結束，而不會退回使用快取的設定；而每小時的背景重新整理在兩個頻道上都採用失敗開放（fail-open）模式，也就是重新整理失敗時仍允許工作階段繼續運作。

360 365

361<h2 id="audit-logging">366<h2 id="audit-logging">

362 稽核記錄367 稽核記錄

379| 使用者執行修改過的 Claude Code 二進位檔 | 能夠執行修改過用戶端的使用者可以略過任何用戶端控制 |384| 使用者執行修改過的 Claude Code 二進位檔 | 能夠執行修改過用戶端的使用者可以略過任何用戶端控制 |

380| 使用者執行較舊的 Claude Code 版本 | 早於伺服器管理設定的版本不會擷取或套用它們 |385| 使用者執行較舊的 Claude Code 版本 | 早於伺服器管理設定的版本不會擷取或套用它們 |

381| API 無法使用 | 如果可用，快取設定會套用，但 Claude Code 會[保留某些值](#fetch-and-caching-behavior)直到擷取成功。沒有快取的情況下，Claude Code 在下次成功擷取之前不會強制執行任何伺服器管理的設定，但仍會在裝置上套用任何[端點管理的設定](/docs/zh-TW/managed-settings#delivery-mechanisms)。使用 `forceRemoteSettingsRefresh: true` 時，CLI 會結束而不是繼續，但 [`claude auth` 子命令](#enforce-fail-closed-startup)除外。透過[Claude 應用程式閘道](#platform-availability)登入的用戶端在啟動時會結束而沒有該設定，具有相同的 `claude auth` 豁免 |386| API 無法使用 | 如果可用，快取設定會套用，但 Claude Code 會[保留某些值](#fetch-and-caching-behavior)直到擷取成功。沒有快取的情況下，Claude Code 在下次成功擷取之前不會強制執行任何伺服器管理的設定，但仍會在裝置上套用任何[端點管理的設定](/docs/zh-TW/managed-settings#delivery-mechanisms)。使用 `forceRemoteSettingsRefresh: true` 時，CLI 會結束而不是繼續，但 [`claude auth` 子命令](#enforce-fail-closed-startup)除外。透過[Claude 應用程式閘道](#platform-availability)登入的用戶端在啟動時會結束而沒有該設定，具有相同的 `claude auth` 豁免 |

382| 使用者使用不同的組織進行身份驗證 | 不會為受管組織外的帳戶傳遞設定 |387| 使用者使用不同的組織進行身份驗證 | 不會為受管組織外的帳戶傳遞設定，包括使用 [Console API 金鑰](#platform-availability)進行身份驗證的工作階段 |

383| 使用者設定[第三方模型提供者](#platform-availability) | 伺服器管理的設定會被略過。這包括設定 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非預設的 `ANTHROPIC_BASE_URL` |388| 使用者設定[第三方模型提供者](#platform-availability) | 伺服器管理的設定會被略過。這包括設定 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非預設的 `ANTHROPIC_BASE_URL` |

384| 網路流量被攔截或重新導向 | 停用的 TLS 驗證或攔截的流量可以改變用戶端接收的設定 |389| 網路流量被攔截或重新導向 | 停用的 TLS 驗證或攔截的流量可以改變用戶端接收的設定 |

385 390

settings-reference.md +19 −10

Details

1266Claude Code 從行的金鑰決定行適用於哪些模型：1266Claude Code 從行的金鑰決定行適用於哪些模型：

1267 1267

1268* **內建模型的 ID**: Claude Code 本身為內建模型使用的金鑰，無論該金鑰是模型自己的 ID（例如 `claude-sonnet-4-6`）還是其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 將行應用於該模型的每個日期快照 ID 和提供者特定 ID。1268* **內建模型的 ID**: Claude Code 本身為內建模型使用的金鑰，無論該金鑰是模型自己的 ID（例如 `claude-sonnet-4-6`）還是其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 將行應用於該模型的每個日期快照 ID 和提供者特定 ID。

1269* **任何其他金鑰**: 不是內建模型 ID 的金鑰，例如閘道模型別名。Claude Code 僅將行應用於該一個 ID。當模型 ID 完全符合您的一個金鑰，也落在由內建模型 ID 鍵入的行下時，Claude Code 使用完全符合。1269* **任何其他金鑰**: 不是內建模型 ID 的金鑰，例如閘道模型別名。Claude Code 僅將行應用於該一個 ID。當模型 ID 完全符合您的一個金鑰，也落在以內建模型 ID 為鍵的行下時，Claude Code 使用完全符合。

1270* **Bedrock 應用程式推論設定檔**: 一旦 Claude Code 透過您的 [`modelOverrides`](#modeloverrides) 對應或 [`bedrock:GetInferenceProfile` 查詢](/docs/zh-TW/amazon-bedrock#iam-configuration)將設定檔解析為它路由到的模型，Claude Code 將該模型的行應用於設定檔。1270* **Bedrock 應用程式推論設定檔**: 一旦 Claude Code 透過您的 [`modelOverrides`](#modeloverrides) 對應或 [`bedrock:GetInferenceProfile` 查詢](/docs/zh-TW/amazon-bedrock#iam-configuration)將設定檔解析為它路由到的模型，Claude Code 將該模型的行應用於設定檔。

1271 1271

1272<h3 id="modelsettings">1272<h3 id="modelsettings">

1399 1399

1400選擇當[安全分類器標記請求](/docs/zh-TW/model-config#automatic-model-fallback)時會發生什麼：切換到備用模型並繼續，或暫停以便您可以在切換和編輯提示之間選擇。1400選擇當[安全分類器標記請求](/docs/zh-TW/model-config#automatic-model-fallback)時會發生什麼：切換到備用模型並繼續，或暫停以便您可以在切換和編輯提示之間選擇。

1401 1401

1402* **範圍**: [`任何檔案`](#scopes)。在 `/config` 中顯示為**訊息被標記時切換模型**。1402* **範圍**: [`任何檔案`](#scopes)。在 `/config` 中顯示為**訊息被標示時切換模型**，選項為**自動切換**和**每次詢問**。

1403* **類型**: 布林值1403* **類型**: 布林值

1404 * `true`: Claude Code 切換到備用模型並繼續1404 * `true`: Claude Code 切換到備用模型並繼續

1405 * `false`: 在互動工作階段中，Claude Code 暫停以便您可以在切換和編輯提示之間選擇；在無法顯示對話框的地方，例如 `-p` 執行，標記的請求以錯誤結束1405 * `false`: 在互動工作階段中，Claude Code 暫停以便您可以在切換和編輯提示之間選擇；在無法顯示對話框的地方，例如 `-p` 執行，標記的請求以錯誤結束

1406* **預設**: `true`，自動切換1406* **預設**: 未設定。Claude Code 會自動切換，但在互動工作階段中可能會[先詢問](/docs/zh-TW/model-config#ask-before-switching)

1407 1407

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

1409{1409{

3164 `plansDirectory`3164 `plansDirectory`

3165</h3>3165</h3>

3166 3166

3167選擇 Claude Code 在 [Plan Mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 中寫入的計畫檔案的儲存位置。Claude Code 相對於專案根目錄解析路徑，當路徑解析在其外部時保持預設值。3167選擇 Claude Code 在 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 中寫入的計畫檔案的儲存位置。Claude Code 相對於專案根目錄解析路徑。

3168 3168

3169* **範圍**：[`任何檔案`](#scopes)3169* **範圍**：[`任何檔案`](#scopes)

3170* **類型**：字串，相對於專案根目錄的路徑3170* **類型**：字串，相對於專案根目錄的路徑

3176}3176}

3177```3177```

3178 3178

3179在以下這類情況中，Claude Code 會將計畫儲存在 `~/.claude/plans`，而非您設定的目錄：

3180

3181* **位於專案根目錄之外**：路徑解析到專案根目錄之外，例如 `"../plans"`。

3182* **在 macOS、Linux 和 WSL 上使用反斜線**：解析後的路徑包含反斜線，例如 Windows 風格的 `"docs\\plans"`。請改寫為 `"docs/plans"`，這在 Windows 上也適用。

3183

3179<h3 id="skilllistingbudgetfraction">3184<h3 id="skilllistingbudgetfraction">

3180 `skillListingBudgetFraction`3185 `skillListingBudgetFraction`

3181</h3>3186</h3>

5145 `pluginConfigs`5150 `pluginConfigs`

5146</h3>5151</h3>

5147 5152

5148儲存您為 plugin 的 [`userConfig`](/docs/zh-TW/plugins/manifest-reference#user-configuration) 配置對話框提供的非敏感答案，按 plugin ID 鍵入。當您填寫對話框時，Claude Code 將此鍵寫入您的使用者設定，因此您無需手動編輯它。Claude Code 將敏感選項儲存在 macOS Keychain 中，當 Keychain 拒絕寫入時回退到 `~/.claude/.credentials.json`；在沒有支援的 keychain 的平台上，它將它們儲存在 `~/.claude/.credentials.json` 中。5153儲存您為 plugin 的 [`userConfig`](/docs/zh-TW/plugins/manifest-reference#user-configuration) 配置對話框提供的非敏感答案，以 plugin ID 為鍵。當您填寫對話框時，Claude Code 將此鍵寫入您的使用者設定，因此您無需手動編輯它。Claude Code 將敏感選項儲存在 macOS Keychain 中，當 Keychain 拒絕寫入時回退到 `~/.claude/.credentials.json`；在沒有支援的 keychain 的平台上，它將它們儲存在 `~/.claude/.credentials.json` 中。

5149 5154

5150* **Scope**: [`User or managed`](#scopes)5155* **Scope**: [`User or managed`](#scopes)

5151* **Type**: 將 plugin ID 對應到具有 `options` 欄位的物件的物件，將每個選項名稱對應到字串、數字、Boolean 或字串陣列，以及可選的 `mcpServers` 欄位，以相同形狀持有每伺服器使用者配置值5156* **Type**: 將 plugin ID 對應到具有 `options` 欄位的物件的物件，將每個選項名稱對應到字串、數字、Boolean 或字串陣列，以及可選的 `mcpServers` 欄位，以相同形狀持有每伺服器使用者配置值

5416從受管設定為每個使用者提供遠端 MCP 伺服器。使用者保留他們自己新增的伺服器，無法編輯或移除您提供的伺服器。需要 Claude Code v2.1.259 或更新版本。5421從受管設定為每個使用者提供遠端 MCP 伺服器。使用者保留他們自己新增的伺服器，無法編輯或移除您提供的伺服器。需要 Claude Code v2.1.259 或更新版本。

5417 5422

5418* **範圍**：[`Managed`](#scopes)。Claude Code 在使用者、專案和本機設定中以警告方式捨棄該金鑰，並且不在第三方部署上的 Claude Desktop 應用程式的 Code 標籤中或在應用程式的 Cowork 工作階段中讀取它，其中 Claude Desktop 會供應並鎖定這些工作階段的 MCP 伺服器本身。5423* **範圍**：[`Managed`](#scopes)。Claude Code 在使用者、專案和本機設定中以警告方式捨棄該金鑰，並且不在第三方部署上的 Claude Desktop 應用程式的 Code 標籤中或在應用程式的 Cowork 工作階段中讀取它，其中 Claude Desktop 會供應並鎖定這些工作階段的 MCP 伺服器本身。

5419* **類型**：按伺服器名稱鍵入的物件。每個條目都具有 `http` 或 `sse` 伺服器的 `.mcp.json` 形狀：必需的 `https://` `url`，以及可選的 `headers`、`oauth` 和其他 HTTP 和 SSE 選項。Claude Code 捨棄驗證失敗的條目，[條目可以包含的內容](/docs/zh-TW/managed-mcp#what-an-entry-can-contain)列出了條件5424* **類型**：以伺服器名稱為鍵的物件。每個條目都具有 `http` 或 `sse` 伺服器的 `.mcp.json` 形狀：必需的 `https://` `url`，以及可選的 `headers`、`oauth` 和其他 HTTP 和 SSE 選項。Claude Code 捨棄驗證失敗的條目，[條目可以包含的內容](/docs/zh-TW/managed-mcp#what-an-entry-can-contain)列出了條件

5420* **預設**：未設定，因此受管設定不提供伺服器5425* **預設**：未設定，因此受管設定不提供伺服器

5421 5426

5422此範例提供一個名為 `search` 的 HTTP 伺服器：5427此範例提供一個名為 `search` 的 HTTP 伺服器：

5768 5773

5769在[桌面應用程式](/docs/zh-TW/desktop#local-sessions-on-managed-devices)中關閉在裝置上執行的 Code 工作階段，適用於開發人員應該透過 SSH 在遠端機器上工作的部署。在 Code 標籤中，**本機**環境保留在環境下拉式選單中，但呈灰色且無法選擇，工具提示顯示您的組織已將其關閉；在 Windows 上，WSL 項目以相同方式呈灰色，儘管 WSL 工作階段是否在受管理裝置上執行[由另外管理](/docs/zh-TW/admin-setup#wsl-sessions-in-claude-code-desktop)。新工作階段預設為第一個[SSH 連線](/docs/zh-TW/desktop#ssh-sessions)（如果已設定），應用程式拒絕在裝置上啟動或繼續工作階段，包括回到同一機器的 SSH 連線。到其他主機的 SSH 工作階段和雲端工作階段不受影響。桌面應用程式讀取此金鑰；終端機 CLI 忽略它。需要 Claude Desktop v1.37937.0 或更新版本。5774在[桌面應用程式](/docs/zh-TW/desktop#local-sessions-on-managed-devices)中關閉在裝置上執行的 Code 工作階段，適用於開發人員應該透過 SSH 在遠端機器上工作的部署。在 Code 標籤中，**本機**環境保留在環境下拉式選單中，但呈灰色且無法選擇，工具提示顯示您的組織已將其關閉；在 Windows 上，WSL 項目以相同方式呈灰色，儘管 WSL 工作階段是否在受管理裝置上執行[由另外管理](/docs/zh-TW/admin-setup#wsl-sessions-in-claude-code-desktop)。新工作階段預設為第一個[SSH 連線](/docs/zh-TW/desktop#ssh-sessions)（如果已設定），應用程式拒絕在裝置上啟動或繼續工作階段，包括回到同一機器的 SSH 連線。到其他主機的 SSH 工作階段和雲端工作階段不受影響。桌面應用程式讀取此金鑰；終端機 CLI 忽略它。需要 Claude Desktop v1.37937.0 或更新版本。

5770 5775

5771* **範圍**：[`受管理`](#scopes)5776* **範圍**：[`受管理`](#scopes)。預設情況下，桌面應用程式會從[單一受管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)讀取此金鑰。

5772* **類型**：布林值；只有 JSON 布林值 `true` 才會生效5777* **類型**：布林值；只有 JSON 布林值 `true` 才會生效

5773 * `true`：桌面應用程式不提供裝置上的 Code 工作階段；現有本機工作階段保留在列表中但無法繼續5778 * `true`：桌面應用程式不提供裝置上的 Code 工作階段；現有本機工作階段保留在列表中但無法繼續

5774 * `false`：本機工作階段保持可用5779 * `false`：本機工作階段保持可用

5915 5920

5916將 SSH 連線新增到[桌面](/docs/zh-TW/desktop#pre-configure-ssh-connections-for-your-team)環境下拉式選單。管理員使用它來向團隊分發共用連線。您在受管理設定中定義的連線顯示為受管理，因此使用者可以選擇它們，但無法在應用程式中編輯或刪除它們。5921將 SSH 連線新增到[桌面](/docs/zh-TW/desktop#pre-configure-ssh-connections-for-your-team)環境下拉式選單。管理員使用它來向團隊分發共用連線。您在受管理設定中定義的連線顯示為受管理，因此使用者可以選擇它們，但無法在應用程式中編輯或刪除它們。

5917 5922

5918* **範圍**：[`使用者或受管理`](#scopes)。桌面應用程式讀取此金鑰。5923* **範圍**：[`使用者或受管理`](#scopes)。桌面應用程式讀取此金鑰。預設情況下，它會從[單一受管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)讀取受管理的連線。

5919* **類型**：物件陣列，每個物件具有必需的 `id`、`name` 和 `sshHost` 以及選用的 `sshPort` 和 `sshIdentityFile`5924* **類型**：物件陣列，每個物件具有必需的 `id`、`name` 和 `sshHost` 以及選用的 `sshPort` 和 `sshIdentityFile`

5920* **預設**：未設定5925* **預設**：未設定

5921 5926

5939 5944

5940限制[桌面 SSH 工作階段](/docs/zh-TW/desktop#restrict-which-ssh-hosts-users-can-connect-to)可以連線到的主機。只有桌面應用程式讀取此金鑰；CLI 不讀取。模式不區分大小寫：`*` 符合任何主機，`*.example.com` 符合 `example.com` 和每個子網域，其他任何內容都是針對 `~/.ssh/config` 解析後的主機名稱的精確符合。空陣列會關閉 SSH 工作階段。5945限制[桌面 SSH 工作階段](/docs/zh-TW/desktop#restrict-which-ssh-hosts-users-can-connect-to)可以連線到的主機。只有桌面應用程式讀取此金鑰；CLI 不讀取。模式不區分大小寫：`*` 符合任何主機，`*.example.com` 符合 `example.com` 和每個子網域，其他任何內容都是針對 `~/.ssh/config` 解析後的主機名稱的精確符合。空陣列會關閉 SSH 工作階段。

5941 5946

5942* **範圍**：[`受管理`](#scopes)5947* **範圍**：[`受管理`](#scopes)。預設情況下，Desktop 會從[單一受管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)讀取此金鑰。

5943* **類型**：主機名稱模式陣列5948* **類型**：主機名稱模式陣列

5944* **預設**：未設定，因此允許任何主機5949* **預設**：未設定，因此允許任何主機

5945 5950

5951}5956}

5952```5957```

5953 5958

5959Desktop 無法讀取為主機清單的值（例如 `true` 或物件），在您修正之前會被視為空陣列，但 `null` 除外，它會被視為未設定。需要 Claude Desktop v2.26454.0 或更新版本。

5960

5961如果您在排名最高的來源中將 [`managedSourcesBehavior`](#managedsourcesbehavior) 設定為 `"merge"`，Desktop 會合併來自每個[管理員來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)的清單，並允許符合其中任何一個清單的主機。如果您在某個來源中設定空陣列，對於另一個來源所列出的主機，SSH 工作階段仍會保持開啟。

5962

5954<span id="authentication-and-login" />5963<span id="authentication-and-login" />

5955 5964

5956<h2 id="authentication-and-providers">5965<h2 id="authentication-and-providers">

6115 `forceLoginOrgUUID`6124 `forceLoginOrgUUID`

6116</h3>6125</h3>

6117 6126

6118從受管來源，要求 claude.ai 帳戶登入屬於一個 Anthropic 組織（以單一 UUID 給定）或屬於多個組織（以陣列給定）。從任何設定檔，Claude Code 也使用單一 UUID 在 claude.ai 或 Claude Console 登入期間預先選擇該組織，而對於陣列則不預先選擇任何組織。如果您在任何設定檔中設定金鑰，Claude Code 也會停止在該檔案適用的工作階段中提供[無金鑰 Console 登入](/docs/zh-TW/authentication#sign-in-without-an-api-key)，並改為建立 API 金鑰。6127從受管來源，要求 claude.ai 帳戶登入屬於一個 Anthropic 組織（以單一 UUID 給定）或屬於多個組織中的任一個（以陣列給定）。從任何設定檔，Claude Code 也使用單一 UUID 在 claude.ai 或 Claude Console 登入期間預先選擇該組織，而對於陣列則不預先選擇任何組織。如果您在任何設定檔中設定此鍵，Claude Code 也會停止在該檔案適用的工作階段中提供[無金鑰 Console 登入](/docs/zh-TW/authentication#sign-in-without-an-api-key)，並改為建立 API 金鑰。

6119 6128

6120* **範圍**：[`任何檔案`](#scopes)。僅受管來源強制執行限制；任何其他設定檔中的單一 UUID 在登入期間預先選擇組織而不限制它。6129* **範圍**：[`任何檔案`](#scopes)。僅受管來源強制執行限制；任何其他設定檔中的單一 UUID 在登入期間預先選擇組織而不限制它。

6121* **類型**：字串，一個 UUID，或字串陣列，多個 UUID6130* **類型**：字串，一個 UUID，或字串陣列，多個 UUID

setup.md +12 −8

Details

63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

64 ```64 ```

65 65

66 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。66 安裝命令在下載 Claude Code 時不會顯示進度。當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的 shell 說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。

67 67

68 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。68 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。

69 69

119 119

120| 選項 | 需要 | [沙箱](/docs/zh-TW/sandboxing) | 何時使用 |120| 選項 | 需要 | [沙箱](/docs/zh-TW/sandboxing) | 何時使用 |

121| - | - | - | - |121| - | - | - | - |

122| 原生 Windows | 無；[Git for Windows](https://git-scm.com/downloads/win) 為選用 | 不支援 | Windows 原生專案和工具 |122| [原生 Windows](#install-on-native-windows) | 無；[Git for Windows](https://git-scm.com/downloads/win) 為選用 | 不支援 | Windows 原生專案和工具 |

123| WSL 2 | WSL 2 已啟用 | 支援 | Linux 工具鏈或沙箱化命令執行 |123| [WSL 2](#install-in-wsl) | WSL 2 已啟用 | 支援 | Linux 工具鏈或沙箱化命令執行 |

124| WSL 1 | WSL 1 已啟用 | 不支援 | 如果 WSL 2 無法使用 |124| [WSL 1](#install-in-wsl) | WSL 1 已啟用 | 不支援 | 如果 WSL 2 無法使用 |

125 125

126**選項 1：原生 Windows**126<h4 id="install-on-native-windows">

127 在原生 Windows 上安裝

128</h4>

127 129

128從 PowerShell 或 CMD 執行安裝命令。您不需要以系統管理員身分執行。安裝 [Git for Windows](https://git-scm.com/downloads/win) 為選用。它提供 Git Bash，這是 [Bash 工具](/docs/zh-TW/tools-reference#bash-tool-behavior)和 [Monitor 工具](/docs/zh-TW/tools-reference#monitor-tool)所需的。130從 PowerShell 或 CMD 執行[安裝命令](#install-claude-code)。您不需要以系統管理員身分執行。安裝 [Git for Windows](https://git-scm.com/downloads/win) 為選用。它提供 Git Bash，這是 [Bash 工具](/docs/zh-TW/tools-reference#bash-tool-behavior)和 [Monitor 工具](/docs/zh-TW/tools-reference#monitor-tool)所需的。

129 131

130無論您從 PowerShell 還是 CMD 安裝，只會影響您執行的安裝命令。您的提示在 PowerShell 中顯示 `PS C:\Users\YourName>`，在 CMD 中顯示 `C:\Users\YourName>`（沒有 `PS`）。如果您是終端機新手，[終端機指南](/docs/zh-TW/terminal-guide#windows)會逐步說明每個步驟。132無論您從 PowerShell 還是 CMD 安裝，只會影響您執行的安裝命令。您的提示在 PowerShell 中顯示 `PS C:\Users\YourName>`，在 CMD 中顯示 `C:\Users\YourName>`（沒有 `PS`）。如果您是終端機新手，[終端機指南](/docs/zh-TW/terminal-guide#windows)會逐步說明每個步驟。

131 133

144 146

145安裝 Git for Windows 時，PowerShell 工具可在 claude.ai 和 Console 帳戶上預設啟用，並在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 工作階段中使用 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` 啟用。將其設定為 `0` 以關閉工具。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)以了解設定和限制。147安裝 Git for Windows 時，PowerShell 工具可在 claude.ai 和 Console 帳戶上預設啟用，並在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 工作階段中使用 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` 啟用。將其設定為 `0` 以關閉工具。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)以了解設定和限制。

146 148

147**選項 2：WSL**149<h4 id="install-in-wsl">

150 在 WSL 中安裝

151</h4>

148 152

149開啟您的 WSL 發行版本並從上面的[安裝說明](#install-claude-code)執行 Linux 安裝程式。您在 WSL 終端機內安裝和啟動 `claude`，而不是從 PowerShell 或 CMD。153開啟您的 WSL 發行版本並從[安裝說明](#install-claude-code)執行 Linux 安裝程式。您在 WSL 終端機內安裝和啟動 `claude`，而不是從 PowerShell 或 CMD。

150 154

151<h3 id="alpine-linux-and-musl-based-distributions">155<h3 id="alpine-linux-and-musl-based-distributions">

152 Alpine Linux 和 musl 型發行版156 Alpine Linux 和 musl 型發行版

skills.md +15 −0

Details

36 36

37捆綁技能與內建命令一起列在[命令參考](/docs/zh-TW/commands)中，在「用途」欄中標記為**技能**。37捆綁技能與內建命令一起列在[命令參考](/docs/zh-TW/commands)中，在「用途」欄中標記為**技能**。

38 38

39<h3 id="check-your-setup-with-/doctor">

40 使用 `/doctor` 檢查您的設定

41</h3>

43在 Claude Code 提示字元處執行 `/doctor`，即可進行設定檢查，診斷問題並可加以修復。Claude 會先回報其發現，並在變更任何內容之前要求確認。檢查涵蓋以下領域：

45* **安裝健康狀態**：重複或殘留的安裝、`PATH` 問題、無法解析的設定檔，以及您的[更新通道](/docs/zh-TW/setup#configure-release-channel)上是否有較新版本可用

46* **擴充功能**：未使用的 skill、MCP 伺服器和外掛與其 context 成本的比較，以及緩慢的 [hook](/docs/zh-TW/hooks)

47* **`CLAUDE.md` 檔案**：與已簽入檔案重複的本機 `CLAUDE.md` 檔案、已簽入的 [Claude 可從程式碼庫推導出的 `CLAUDE.md` 內容](/docs/zh-TW/memory#my-claude-md-is-too-large)，以及其餘一律載入的指引，Claude 會提議將其遷移至按需載入的 skill 和巢狀 `CLAUDE.md` 檔案

48* **權限**：提議將[自動模式](/docs/zh-TW/permissions#permission-modes)設為您的預設權限模式，並[預先核准](/docs/zh-TW/permissions)您經常拒絕的唯讀命令

50若要在不啟動工作階段的情況下進行唯讀的安裝診斷，請改為在終端機中執行 `claude doctor`。

52若要稽核您的指示而非設定，請在 Claude Code 提示字元處執行 `/doctor prompt-audit`。Claude 會[檢查您的 `CLAUDE.md` 檔案、skill 和其他設定](/docs/zh-TW/memory#audit-your-instruction-files)中是否有過時或衝突的指示，而不是執行設定檢查。`prompt-audit` 子命令需要 Claude Code v2.1.283 或更新版本。

39<h3 id="run-and-verify-your-app">54<h3 id="run-and-verify-your-app">

40 執行並驗證您的應用程式55 執行並驗證您的應用程式

41</h3>56</h3>

statusline.md +84 −35

Details

148 148

149Claude Code 會在 stdin 上執行您的指令碼，並傳入 [JSON 工作階段資料](#available-data)，然後顯示指令碼列印到 stdout 的任何內容。149Claude Code 會在 stdin 上執行您的指令碼，並傳入 [JSON 工作階段資料](#available-data)，然後顯示指令碼列印到 stdout 的任何內容。

150 150

151**何時更新**151<Note>狀態列在本機執行，不會消耗 API token。它會在某些 UI 互動期間暫時隱藏，包括說明功能表和權限提示。</Note>

152

153<h3 id="when-the-status-line-updates">

154 狀態列何時更新

155</h3>

152 156

153您的指令碼會在工作階段開始時執行一次，包括當您復原工作階段時。之後，它會在以下情況下再次執行：157您的指令碼會在工作階段開始時執行一次，包括當您復原工作階段時。之後，它會在以下情況下再次執行：

154 158

159* 您變更 `statusLine` 設定中的 `command`163* 您變更 `statusLine` 設定中的 `command`

160* 如果您設定了 [`refreshInterval`](#manually-configure-a-status-line)，計時器會經過164* 如果您設定了 [`refreshInterval`](#manually-configure-a-status-line)，計時器會經過

161* 您的指令碼最後接收的資料中的[速率限制視窗](#rate-limit-usage)達到其 `resets_at` 時間165* 您的指令碼最後接收的資料中的[速率限制視窗](#rate-limit-usage)達到其 `resets_at` 時間

162* 您的指令碼最後接收的資料中的[預熱 prompt 快取](#prompt-cache-fields)達到其 `expires_at` 時間166* 您的指令碼最後接收的資料中的[預熱提示詞快取](#prompt-cache-fields)達到其 `expires_at` 時間

163 167

164Claude Code 會在 300ms 時進行去抖動，因此快速變更會批次處理，您的指令碼會在變更停止後執行一次。對 `command` 本身的變更會跳過去抖動：Claude Code 會立即執行新命令。如果在您的指令碼仍在執行時觸發新的更新，Claude Code 會取消執行中的指令碼。如果您編輯指令碼，變更會在下次更新觸發重新執行時出現。168Claude Code 會在 300ms 時進行去抖動，因此快速變更會批次處理，您的指令碼會在變更停止後執行一次。對 `command` 本身的變更會跳過去抖動：Claude Code 會立即執行新命令。如果在您的指令碼仍在執行時觸發新的更新，Claude Code 會取消執行中的指令碼。如果您編輯指令碼，變更會在下次更新觸發重新執行時出現。

165 169

166當主工作階段閒置時，事件驅動的觸發器可能會安靜下來，例如當協調器等待背景子代理時。若要在閒置期間保持基於時間或外部來源的區段為最新狀態，請設定 [`refreshInterval`](#manually-configure-a-status-line) 以同時在固定計時器上重新執行命令。170當主工作階段閒置時，事件驅動的觸發器可能會安靜下來，例如當協調器等待背景 subagent 時。若要在閒置期間保持基於時間或外部來源的區段為最新狀態，請設定 [`refreshInterval`](#manually-configure-a-status-line) 以同時在固定計時器上重新執行命令。

171

172<h3 id="what-your-script-can-output">

173 您的指令碼可以輸出什麼

174</h3>

167 175

168**您的指令碼可以輸出什麼**176您的指令碼可以列印的不只是單行純文字：

169 177

170* **多行**：每個 `echo` 或 `print` 陳述式會顯示為單獨的列。請參閱[多行範例](#display-multiple-lines)。178* **多行**：每個 `echo` 或 `print` 陳述式會顯示為單獨的列。請參閱[多行範例](#display-multiple-lines)。

171* **顏色**：使用 [ANSI 逸出碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)，例如 `\033[32m` 表示綠色（終端機必須支援）。請參閱 [git 狀態範例](#git-status-with-colors)。179* **顏色**：使用 [ANSI 逸出碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)，例如 `\033[32m` 表示綠色（終端機必須支援）。請參閱 [git 狀態範例](#git-status-with-colors)。

172* **連結**：使用 [OSC 8 逸出序列](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) 使文字可點擊（macOS 上為 Cmd+click，Windows/Linux 上為 Ctrl+click）。需要支援超連結的終端機，例如 iTerm2、Kitty 或 WezTerm。請參閱[可點擊連結範例](#clickable-links)。180* **連結**：使用 [OSC 8 逸出序列](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) 使文字可點擊（macOS 上為 Cmd+click，Windows/Linux 上為 Ctrl+click）。需要支援超連結的終端機，例如 iTerm2、Kitty 或 WezTerm。請參閱[可點擊連結範例](#clickable-links)。

173 181

174**調整輸出大小以符合終端機**182<h3 id="size-output-to-the-terminal">

183 調整輸出大小以符合終端機

184</h3>

175 185

176Claude Code 會擷取您的指令碼輸出，而不是直接將其連接到終端機，因此 `tput cols` 和語言層級的寬度偵測無法從指令碼內部讀取終端機大小。請改為讀取 `COLUMNS` 和 `LINES` 環境變數。Claude Code 會在執行您的指令碼之前將這些設定為目前的終端機尺寸。186Claude Code 會擷取您的指令碼輸出，而不是直接將其連接到終端機，因此 `tput cols` 和語言層級的寬度偵測無法從指令碼內部讀取終端機大小。請改為讀取 `COLUMNS` 和 `LINES` 環境變數。Claude Code 會在執行您的指令碼之前將這些設定為目前的終端機尺寸。

177 187

178<Note>狀態列在本機執行，不會消耗 API 權杖。它會在某些 UI 互動期間暫時隱藏，包括說明功能表和權限提示。</Note>

~~179~~

180<h2 id="available-data">188<h2 id="available-data">

181 可用資料189 可用資料

182</h2>190</h2>

1168}1176}

1169```1177```

1170 1178

1171命令在每個重新整理刻度上執行一次，所有可見的子代理行作為單個 JSON 物件在 stdin 上傳遞。輸入包括[基本 hook 欄位](/docs/zh-TW/hooks#common-input-fields)、`columns` 欄位（可用行寬度）和 `tasks` 陣列。每個任務具有 `id`、`name`、`type`、`status`、`description`、`label`、`startTime`、`model`、`effort`、`contextWindowSize`、`tokenCount`、`tokenSamples` 和 `cwd`。1179命令在每個重新整理刻度上執行一次，並以單個 JSON 物件的形式在 stdin 上接收所有可見的 subagent 列。輸入包括[基本 hook 欄位](/docs/zh-TW/hooks#common-input-fields)、包含可用列寬度的 `columns` 欄位，以及每列一個項目的 `tasks` 陣列，詳見[任務欄位](#task-fields)。

~~1172~~

1173每個任務的 `model` 欄位是任務執行所在的已解析模型 ID。`contextWindowSize` 是該模型的內容視窗（以 token 計），計算方式與主狀態列的 `context_window.context_window_size` 相同，因此您可以從 `tokenCount` 呈現每行百分比。兩個欄位都需要 Claude Code v2.1.205 或更新版本，並且對於模型尚未解析的任務會被省略。

~~1174~~

1175每個任務的 `effort` 欄位是為該 subagent 設定的推理 effort，在其[定義 frontmatter](/docs/zh-TW/sub-agents#supported-frontmatter-fields) 或個別調用上設定。該值是 effort 等級字串 `low`、`medium`、`high`、`xhigh` 或 `max` 之一，或數值 token 預算。該欄位報告設定的值（如所寫）：如果模型不支援該等級，Claude Code 實際應用的 effort 可能會有所不同。該欄位需要 Claude Code v2.1.214 或更新版本，當未為該 subagent 設定任何等級時不存在。

1176 1180

1177將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。1181將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。

1178 1182

1179適用於 `statusLine` 的相同信任、`disableAllHooks` 和 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 閘門也適用於此。外掛程式可以在其 [`settings.json`](/docs/zh-TW/plugins/manifest-reference#standard-layout) 中提供預設 `subagentStatusLine`，但與 hooks 不同，即使外掛程式在受管設定 `enabledPlugins` 中被強制啟用，外掛程式值也不會在 `allowManagedHooksOnly` 下執行。1183適用於 `statusLine` 的相同信任、`disableAllHooks` 和 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 閘門也適用於此。外掛程式可以在其 [`settings.json`](/docs/zh-TW/plugins/manifest-reference#standard-layout) 中提供預設 `subagentStatusLine`，但與 hooks 不同，即使外掛程式在受管設定 `enabledPlugins` 中被強制啟用，外掛程式值也不會在 `allowManagedHooksOnly` 下執行。

1180 1184

1185<h3 id="task-fields">

1186 任務欄位

1187</h3>

1188

1189`tasks` 陣列中的每個項目以下列欄位描述一個 subagent 列。標示為選用的欄位在沒有值時會被省略，因此請在指令碼中處理其不存在的情況。

1190

1191| 欄位 | 類型 | 說明 |

1192| :- | :- | :- |

1193| `id` | string | 任務的識別碼。在您為此列寫回的行中將其作為 `id` 回傳 |

1194| `name` | string，選用 | subagent 被[稱呼時使用](/docs/zh-TW/sub-agents#subagent-names)的名稱（如果有的話） |

1195| `type` | string | 任務的種類：`local_agent` |

1196| `agentType` | string | 任務執行時的 subagent 類型，例如內建的 [`Explore`](/docs/zh-TW/sub-agents#built-in-subagents) 或自訂的 `code-reviewer`。其值與 hook 接收的 [`agent_type`](/docs/zh-TW/hooks#subagentstart) 相同。需要 Claude Code v2.1.293 或更新版本 |

1197| `status` | string | 任務的狀態，例如 `running`、`completed`、`failed` 或 `killed` |

1198| `description` | string | 任務的簡短說明，例如 Claude 產生 subagent 時所提供的說明 |

1199| `label` | string | 當 Claude Code 有任務的簡短進度摘要時為該摘要，否則與 `description` 的文字相同 |

1200| `startTime` | number | 任務開始的時間，以自 Unix epoch 以來的毫秒數表示 |

1201| `model` | string，選用 | 任務執行所在的已解析模型 ID。在模型解析完成前會被省略。需要 Claude Code v2.1.205 或更新版本 |

1202| `effort` | string 或 number，選用 | 在 subagent 的[定義 frontmatter](/docs/zh-TW/sub-agents#supported-frontmatter-fields) 或個別調用上為其設定的推理 effort：`low`、`medium`、`high`、`xhigh`、`max` 或數值 token 預算。這是設定的值，當模型不支援該等級時，Claude Code 實際套用的 effort 可能會有所不同。未設定 effort 時會被省略。需要 Claude Code v2.1.213 或更新版本 |

1203| `contextWindowSize` | number，選用 | `model` 的上下文視窗（以 token 計），計算方式與主狀態列的 [`context_window.context_window_size`](#context-window-fields) 相同，因此您可以從 `tokenCount` 呈現每列的百分比。當 `model` 被省略時也會被省略。需要 Claude Code v2.1.205 或更新版本 |

1204| `tokenCount` | number | subagent 的累計 token 數，即預設列所顯示的數字 |

1205| `tokenSamples` | array of numbers | 最多最近 16 次的 `tokenCount` 讀數，每個重新整理刻度一筆，由舊到新排列並以目前的讀數結尾 |

1206| `cwd` | string | subagent 的工作目錄：當其在自己的目錄中執行時（例如隔離的 worktree）為該目錄，否則為工作階段的工作目錄 |

1207

1181<h2 id="tips">1208<h2 id="tips">

1182 提示1209 提示

1183</h2>1210</h2>

1192 疑難排解1219 疑難排解

1193</h2>1220</h2>

1194 1221

1195**狀態列未出現**1222如果狀態列是空白的，請從[狀態列未出現](#status-line-not-appearing)開始。尚未信任的資料夾以及執行失敗的指令碼也會使狀態列保持空白，如[需要工作區信任](#workspace-trust-required)和[指令碼錯誤或掛起](#script-errors-or-hangs)所述。

1223

1224<h3 id="status-line-not-appearing">

1225 狀態列未出現

1226</h3>

1227

1228如果您已設定狀態列，但介面底部沒有顯示任何內容，請逐一進行以下檢查：

1196 1229

1197* 驗證您的指令碼是否可執行：`chmod +x ~/.claude/statusline.sh`1230* 驗證您的指令碼是否可執行：`chmod +x ~/.claude/statusline.sh`

1198* 檢查您的指令碼是否輸出到 stdout 而不是 stderr1231* 檢查您的指令碼是否輸出到 stdout 而不是 stderr

1201* 如果在套用[設定優先順序](/docs/zh-TW/hooks#disable-or-remove-hooks)後 `disableAllHooks` 在受管設定外為 `true`，Claude Code 只會執行來自受管設定的 `statusLine`，且沒有受管 `statusLine` 時狀態列會被停用。移除此設定或在設定它的檔案中將其設定為 `false` 以重新啟用。請參閱 [`disableAllHooks`](/docs/zh-TW/settings-reference#disableallhooks)。1234* 如果在套用[設定優先順序](/docs/zh-TW/hooks#disable-or-remove-hooks)後 `disableAllHooks` 在受管設定外為 `true`，Claude Code 只會執行來自受管設定的 `statusLine`，且沒有受管 `statusLine` 時狀態列會被停用。移除此設定或在設定它的檔案中將其設定為 `false` 以重新啟用。請參閱 [`disableAllHooks`](/docs/zh-TW/settings-reference#disableallhooks)。

1202* 如果您的組織在受管設定中設定 `allowManagedHooksOnly`，您的自訂狀態列會無警告地消失：您只能從那些受管設定中的 `statusLine` 值取得狀態列。請參閱[在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以了解完整行為，並詢問您的管理員此設定是否適用於您。1235* 如果您的組織在受管設定中設定 `allowManagedHooksOnly`，您的自訂狀態列會無警告地消失：您只能從那些受管設定中的 `statusLine` 值取得狀態列。請參閱[在 `allowManagedHooksOnly` 下執行的內容](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以了解完整行為，並詢問您的管理員此設定是否適用於您。

1203* 執行 `claude --debug` 以在每次狀態列呼叫時記錄您的指令碼的 stderr，以及在工作階段中第一次呼叫時記錄其結束代碼1236* 執行 `claude --debug` 以在每次狀態列呼叫時記錄您的指令碼的 stderr，以及在工作階段中第一次呼叫時記錄其結束代碼

1204* 要求 Claude 讀取您的設定檔案並直接執行 `statusLine` 命令以顯示錯誤1237* 要求 Claude 讀取您的設定檔並直接執行 `statusLine` 命令以顯示錯誤

1238

1239<h3 id="status-line-shows-or-empty-values">

1240 狀態列顯示 `--` 或空值

1241</h3>

1205 1242

~~1206**狀態列顯示 `--` 或空值**~~1243欄位在第一次 API 回應完成之前可能為 `null`，因此請在您的指令碼中使用備援值（例如 jq 中的 `// 0`）處理 null 值。如果多則訊息後值仍為空，請重新啟動 Claude Code。

1207 1244

1208* 欄位在第一次 API 回應完成之前可能為 `null`1245<h3 id="context-percentage-shows-unexpected-values">

1209* 在您的指令碼中使用後備（例如 jq 中的 `// 0`）處理 null 值1246 上下文百分比顯示意外值

1210* 如果多個訊息後值仍為空，請重新啟動 Claude Code1247</h3>

1211 1248

1212**Context 百分比顯示意外值**1249狀態列報告來自最後一次 API 回應的計數，而 `/context` 會加上自該回應以來新增訊息的估計值，因此 `/context` 在下一次回應前可能顯示較高的值。使用 `used_percentage` 以取得最簡單且準確的上下文狀態。關於 `used_percentage` 背後的公式，請參閱[上下文視窗欄位](#context-window-fields)。

1213 1250

1214* 使用 `used_percentage` 以取得最簡單的準確 context 狀態1251<h3 id="osc-8-links-not-clickable">

1215* 狀態列報告來自最後一次 API 回應的計數，而 `/context` 新增自該回應以來新增的訊息的估計值，因此 `/context` 在下一次回應前可能讀取更高的值1252 OSC 8 連結不可點擊

1253</h3>

1216 1254

1217**OSC 8 連結不可點擊**1255連結是否可點擊，取決於您的終端機、Claude Code 是否在其中偵測到超連結支援、SSH 或 tmux 是否去除逃逸序列，以及您的指令碼如何輸出它：

1218 1256

1219* 驗證您的終端支援 OSC 8 超連結（iTerm2、Kitty、WezTerm）1257* 驗證您的終端機支援 OSC 8 超連結（iTerm2、Kitty、WezTerm）

1220 1258

1221* Terminal.app 不支援可點擊連結1259* Terminal.app 不支援可點擊連結

1222 1260

1223* 如果連結文字出現但不可點擊，Claude Code 可能未在您的終端中偵測到超連結支援。設定 `FORCE_HYPERLINK` 環境變數以在啟動 Claude Code 之前覆蓋偵測：1261* 如果連結文字出現但不可點擊，Claude Code 可能未在您的終端機中偵測到超連結支援。設定 `FORCE_HYPERLINK` 環境變數以在啟動 Claude Code 之前覆寫偵測：

1224 1262

1225 ```bash theme={null}1263 ```bash theme={null}

1226 FORCE_HYPERLINK=1 claude1264 FORCE_HYPERLINK=1 claude

1236 1274

1237* 如果逃逸序列顯示為文字（如 `\e]8;;`），請使用 `printf '%b'` 而不是 `echo -e` 以獲得更可靠的逃逸處理1275* 如果逃逸序列顯示為文字（如 `\e]8;;`），請使用 `printf '%b'` 而不是 `echo -e` 以獲得更可靠的逃逸處理

1238 1276

1239**逃逸序列的顯示故障**1277<h3 id="display-glitches-with-escape-sequences">

1278 逃逸序列的顯示故障

1279</h3>

1280

1281複雜的逃逸序列（ANSI 顏色、OSC 8 連結）如果與其他 UI 更新重疊，偶爾會導致輸出損壞。帶有逃逸碼的多行狀態列比單行純文字更容易出現呈現問題。

1282

1283如果您看到損壞的文字，請嘗試簡化您的指令碼為純文字輸出。

1284

1285<h3 id="workspace-trust-required">

1286 需要工作區信任

1287</h3>

1240 1288

1241* 複雜的逃逸序列（ANSI 顏色、OSC 8 連結）如果與其他 UI 更新重疊，偶爾會導致輸出損壞1289在您接受工作區信任對話框之前，狀態列會保持空白。因為 `statusLine` 執行 shell 命令，Claude Code 在與[設定檔中的 hook 相同的工作區信任規則](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)下執行它。接受該資料夾的對話框，或接受其信任延伸到該資料夾的父目錄的對話框，就足夠了。

1242* 如果您看到損壞的文字，請嘗試簡化您的指令碼為純文字輸出

1243* 帶有逃逸碼的多行狀態列比單行純文字更容易出現呈現問題

1244 1290

1245**工作區信任必需**1291在此之前，`claude --debug` 會記錄 `Status line command skipped: workspace trust not accepted`。重新啟動 Claude Code 並接受信任對話框以啟用它。

1246 1292

1247* 因為 `statusLine` 執行 shell 命令，Claude Code 在與[設定檔案中的 hooks 相同的工作區信任規則](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)下執行它。接受資料夾的對話，或接受其信任延伸到它的父目錄，就足夠了。1293<h3 id="script-errors-or-hangs">

1248* 在此之前，狀態列保持空白，且 `claude --debug` 記錄 `Status line command skipped: workspace trust not accepted`。重新啟動 Claude Code 並接受信任對話以啟用它。1294 指令碼錯誤或掛起

1295</h3>

1249 1296

1250**指令碼錯誤或掛起**1297Claude Code 只會在您的指令碼以代碼 0 結束後才顯示其輸出：

1251 1298

1252* 以非零代碼結束或不產生輸出的指令碼會導致狀態列變為空白1299* 以非零代碼結束或不產生輸出的指令碼會導致狀態列變為空白

1253* 慢速指令碼會阻止狀態列更新，直到它們完成。保持指令碼快速以避免過時的輸出。1300* 慢速指令碼會阻止狀態列更新，直到它們完成。保持指令碼快速以避免過時的輸出。

1254* 如果在慢速指令碼執行時觸發新的更新，進行中的指令碼會被取消1301* 如果在慢速指令碼執行時觸發新的更新，進行中的指令碼會被取消

1255* 在設定之前使用模擬輸入獨立測試您的指令碼1302* 在設定之前使用模擬輸入獨立測試您的指令碼

1256 1303

1257**通知共享狀態列行**1304<h3 id="notifications-share-the-status-line-row">

1305 通知共享狀態列行

1306</h3>

1258 1307

1259在[全螢幕呈現](/docs/zh-TW/fullscreen)外，Claude Code 在與您的狀態列相同行上顯示通知。在全螢幕呈現中，Claude Code 為通知提供自己的行。1308在[全螢幕呈現](/docs/zh-TW/fullscreen)外，Claude Code 在與您的狀態列相同行上顯示通知。在全螢幕呈現中，Claude Code 為通知提供自己的行。

1260 1309

1261* 系統通知（如 MCP 伺服器錯誤和自動更新）顯示在行的右側。暫時性通知（例如 context-low 警告）也會在此區域循環。1310* 系統通知（如 MCP 伺服器錯誤和自動更新）顯示在行的右側。暫時性通知（例如 context-low 警告）也會在此區域循環。

1262* 啟用詳細模式會在此區域新增令牌計數器1311* 啟用詳細模式會在此區域新增 token 計數器

1263* 在狹窄的終端上，這些通知可能會截斷您的狀態列輸出1312* 在狹窄的終端機上，這些通知可能會截斷您的狀態列輸出

sub-agents.md +2 −0

Details

3793. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-TW/model-config#environment-variables) 環境變數，當您將其設定為模型別名或模型 ID 時3793. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-TW/model-config#environment-variables) 環境變數，當您將其設定為模型別名或模型 ID 時

3804. 主對話的模型3804. 主對話的模型

381 381

382如果已安裝的 [mod](/docs/zh-TW/plugins/mods/overview) 在其 [`agent.spawn`](/docs/zh-TW/plugins/mods/reference#subagents) hook 中設定了模型，Claude Code 會以該模型取代每次叫用的參數。

383

382在兩種情況下，每次叫用參數或 frontmatter 中的家族別名（例如 `opus`）解析為主對話的模型，而不是[別名指向的版本](/docs/zh-TW/model-config#model-aliases)：384在兩種情況下，每次叫用參數或 frontmatter 中的家族別名（例如 `opus`）解析為主對話的模型，而不是[別名指向的版本](/docs/zh-TW/model-config#model-aliases)：

383 385

384* **主對話的模型屬於該家族**：子代理在主對話的確切模型上執行，包括任何 `[1m]` 尾碼，因此它獲得與主對話相同的[擴展上下文](/docs/zh-TW/model-config#extended-context)視窗。386* **主對話的模型屬於該家族**：子代理在主對話的確切模型上執行，包括任何 `[1m]` 尾碼，因此它獲得與主對話相同的[擴展上下文](/docs/zh-TW/model-config#extended-context)視窗。

tools-reference.md +27 −17

Details

155</h3>155</h3>

156 156

157* 當 Claude 在主工作階段中執行 `cd` 時，新的工作目錄會延續到後續的 Bash 命令，只要它保持在專案目錄或您使用 `--add-dir`、`/add-dir` 或設定中的 `additionalDirectories` 新增的[額外工作目錄](/docs/zh-TW/permissions#working-directories)內。這包括 Claude 為回應您後續訊息而執行的命令。157* 當 Claude 在主工作階段中執行 `cd` 時，新的工作目錄會延續到後續的 Bash 命令，只要它保持在專案目錄或您使用 `--add-dir`、`/add-dir` 或設定中的 `additionalDirectories` 新增的[額外工作目錄](/docs/zh-TW/permissions#working-directories)內。這包括 Claude 為回應您後續訊息而執行的命令。

158 * 子代理工作階段永遠不會延續工作目錄變更。158 * subagent 工作階段永遠不會延續工作目錄變更。

159 * 如果 `cd` 落在這些目錄之外，Claude Code 會重設為專案目錄，並在工具結果中附加 `Shell cwd was reset to <dir>`。159 * 如果 `cd` 落在這些目錄之外，Claude Code 會重設為專案目錄，並在工具結果中附加 `Shell cwd was reset to <dir>`。

160 * 若要停用此延續功能，使每個 Bash 命令都在專案目錄中啟動，請設定 `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`。160 * 若要停用此延續功能，使每個 Bash 命令都在專案目錄中啟動，請設定 `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`。

161* 環境變數不會保留。一個命令中的 `export` 在下一個命令中將無法使用。161* 環境變數不會保留。一個命令中的 `export` 在下一個命令中將無法使用。

187| 有效 | 內聯最多約 30,000 個字元（預設）；超過該值，為儲存到工作階段目錄的檔案的路徑（檔案超過 64 MiB 的部分會被截斷），加上最多前 2,000 個字元的預覽，Claude 在需要其餘部分時讀取或搜尋該檔案 |187| 有效 | 內聯最多約 30,000 個字元（預設）；超過該值，為儲存到工作階段目錄的檔案的路徑（檔案超過 64 MiB 的部分會被截斷），加上最多前 2,000 個字元的預覽，Claude 在需要其餘部分時讀取或搜尋該檔案 |

188| 失敗 | 內聯最多約 10,000 個字元；超過該值，從讀回視窗中切割的該大小的頭尾摘錄，沒有檔案路徑 |188| 失敗 | 內聯最多約 10,000 個字元；超過該值，從讀回視窗中切割的該大小的頭尾摘錄，沒有檔案路徑 |

189 189

190命令退出代碼為 1 只有在 Claude Code 將退出代碼 1 識別為該命令的良性結果時，才算作 Bash 工具的有效結果：`grep`、`rg`、`egrep`、`fgrep`、`find`、`diff`、`test` 和 `[`，加上 `git diff` 和 `git grep`。每個其他退出代碼為 1 的命令都算作失敗，即使退出代碼 1 是良性的資訊結果：`pgrep` 和 `jq -e` 沒有符合項，`cmp` 的檔案不同。190命令退出碼為 1 只有在 Claude Code 將退出碼 1 識別為該命令的良性結果時，才算作 Bash 工具的有效結果：`grep`、`rg`、`egrep`、`fgrep`、`find`、`diff`、`test` 和 `[`，加上 `git diff` 和 `git grep`。每個其他退出碼為 1 的命令都算作失敗，即使退出碼 1 是良性的資訊結果：`pgrep` 和 `jq -e` 沒有符合項，`cmp` 的檔案不同。

191 191

192[`BASH_MAX_OUTPUT_LENGTH`](/docs/zh-TW/env-vars) 設定 Claude Code 從工作檔案讀回到命令結果中的輸出字元數：預設 30,000，最多硬上限 150,000。當您的命令經常超過該視窗時提高它，例如詳細的建置或完整的測試套件日誌。提高它會擴大讀回視窗，這也是失敗命令的摘錄被切割的視窗。它不會提高內聯上限：超過內聯上限的有效結果會作為檔案路徑加預覽到達，無論此變數如何。192[`BASH_MAX_OUTPUT_LENGTH`](/docs/zh-TW/env-vars) 設定 Claude Code 從工作檔案讀回到命令結果中的輸出字元數：預設 30,000，最多硬上限 150,000。當您的命令經常超過該視窗時提高它，例如詳細的建置或完整的測試套件日誌。提高它會擴大讀回視窗，這也是失敗命令的摘錄被切割的視窗。它不會提高內聯上限：超過內聯上限的有效結果會作為檔案路徑加預覽到達，無論此變數如何。

193 193

197 背景命令197 背景命令

198</h3>198</h3>

199 199

200對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 `run_in_background: true` 以將命令作為背景工作啟動並在其執行時繼續工作。使用 `/tasks` 列出並停止背景工作。在您從那裡停止一個後，或從連接的用戶端（例如桌面應用程式）停止後，Claude 會繼續而不是等待。如果子代理啟動了命令，則是該子代理繼續。200對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 `run_in_background: true` 以將命令作為背景任務啟動並在其執行時繼續工作。使用 `/tasks` 列出並停止背景任務。在您從那裡停止一個後，或從連接的用戶端（例如桌面應用程式）停止後，Claude 會繼續而不是等待。如果 subagent 啟動了命令，則是該 subagent 繼續。

201 201

202<h4 id="when-a-background-command-stops">202<h4 id="when-a-background-command-stops">

203 背景命令何時停止203 背景命令何時停止

204</h4>204</h4>

205 205

206[前景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的命令在該子代理的執行結束時停止，無論它完成、失敗或被中斷。主對話或背景子代理啟動的命令在最終回應後繼續執行，直到它退出、被停止或達到其[時間限制](#time-limit-for-background-commands)。在使用 `-p` 旗標的非互動模式中，[背景命令在執行的最終結果後不久結束](/docs/zh-TW/headless#background-tasks-at-exit)。206[前景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 啟動的命令在該 subagent 的執行結束時停止，無論它完成、失敗或被中斷。主對話或背景 subagent 啟動的命令在最終回應後繼續執行，直到它退出、被停止或達到其[時間限制](#time-limit-for-background-commands)。

207

208當主對話啟動的命令仍在執行時，使用 `-p` 旗標的非互動模式執行會[在其結果之後保持開啟](/docs/zh-TW/headless#background-tasks-at-exit)，直到該命令退出或達到其時間限制。背景 subagent 啟動的命令會在執行退出時被停止。

207 209

208<h4 id="time-limit-for-background-commands">210<h4 id="time-limit-for-background-commands">

209 背景命令的時間限制211 背景命令的時間限制

218* Claude 在背景啟動的命令獲得 30 分鐘，或 Claude 使用 `run_in_background` 傳遞的 `timeout`，最多 2 小時220* Claude 在背景啟動的命令獲得 30 分鐘，或 Claude 使用 `run_in_background` 傳遞的 `timeout`，最多 2 小時

219* 在前景啟動然後移至背景的命令，例如在其逾時時，從移動時獲得 30 分鐘221* 在前景啟動然後移至背景的命令，例如在其逾時時，從移動時獲得 30 分鐘

220 222

223在使用 `-p` 旗標、且提示詞以文字傳遞而非使用 `--input-format stream-json` 的執行中，兩個預設值都是 10 分鐘而非 30 分鐘，因為該執行會[在其結果之後等待背景命令](/docs/zh-TW/headless#background-tasks-at-exit)。

224

221當背景命令達到其時間限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動命令，如果工作仍然需要的話。停止通知讀作 `Background command "<description>" was stopped after reaching its background time limit`。225當背景命令達到其時間限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動命令，如果工作仍然需要的話。停止通知讀作 `Background command "<description>" was stopped after reaching its background time limit`。

222 226

223<h4 id="raise-the-time-limit-for-background-commands">227<h4 id="raise-the-time-limit-for-background-commands">

224 提高背景命令的時間限制228 提高背景命令的時間限制

225</h4>229</h4>

226 230

227兩個[環境變數](/docs/zh-TW/env-vars)提高這些限制，對於 Bash 和 PowerShell 命令一樣。兩者都採用毫秒，且都不能縮短限制：較低的值會保留 30 分鐘的預設值和 2 小時的最大值。231兩個[環境變數](/docs/zh-TW/env-vars)提高這些限制，對於 Bash 和 PowerShell 命令一樣。兩者都採用毫秒，且都不能縮短限制：較低的值會保留預設值和 2 小時的最大值。

228 232

229* 將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `1800000` 以用該值替換 30 分鐘的預設值，無論是對於 Claude 啟動時不帶 `timeout` 的命令還是對於移動的命令233* 將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `1800000` 以用該值替換 30 分鐘的預設值，無論是對於 Claude 啟動時不帶 `timeout` 的命令還是對於移動的命令。在提示詞以文字傳遞的 `-p` 執行中，任何高於 `600000` 的值都會替換其 10 分鐘的預設值

230* 將 `BASH_MAX_TIMEOUT_MS` 設定為高於 `7200000` 以將 2 小時的最大值提高到該值。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `7200000` 以相同方式提高最大值234* 將 `BASH_MAX_TIMEOUT_MS` 設定為高於 `7200000` 以將 2 小時的最大值提高到該值。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `7200000` 以相同方式提高最大值

231 235

232<h4 id="foreground-commands-that-move-to-the-background">236<h4 id="foreground-commands-that-move-to-the-background">

233 移至背景的前景命令237 移至背景的前景命令

234</h4>238</h4>

235 239

236當前景命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它，除非命令以 `sleep` 開頭。移動的命令的[時間限制](#time-limit-for-background-commands)從移動時開始計算，前景子代理的移動命令仍然在該子代理的執行結束時停止。240當前景命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它，除非命令以 `sleep` 開頭。移動的命令的[時間限制](#time-limit-for-background-commands)從移動時開始計算，前景 subagent 的移動命令仍然在該 subagent 的執行結束時停止。

237 241

238設定 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-TW/env-vars#variables) 或在 [bare 模式](/docs/zh-TW/headless#start-faster-with-bare-mode)中執行，會停用自動背景化以及其餘的背景任務功能，因此達到逾時的命令會改為停止。242設定 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-TW/env-vars#variables) 或在 [bare 模式](/docs/zh-TW/headless#start-faster-with-bare-mode)中執行，會停用自動背景化以及其餘的背景任務功能，因此達到逾時的命令會改為停止。

239 243

240移至背景的命令的結果說明發生了什麼：244移至背景的命令的結果說明發生了什麼：

241 245

242* 當逾時觸發移動時，結果明確報告它：`Command did not complete within its 120s timeout and was moved to the background`，秒數與應用的逾時相符，後跟工作 ID 和輸出正在寫入的檔案路徑。246* 當逾時觸發移動時，結果明確報告它：`Command did not complete within its 120s timeout and was moved to the background`，秒數與應用的逾時相符，後跟任務 ID 和輸出正在寫入的檔案路徑。

243* 移至背景的命令內的 `cd`、`pushd`、`popd` 或 `chdir` 永遠不會延續：結果說明 `Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands.`，所以 Claude 不會對未發生的目錄變更採取行動。247* 移至背景的命令內的 `cd`、`pushd`、`popd` 或 `chdir` 永遠不會延續：結果說明 `Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands.`，所以 Claude 不會對未發生的目錄變更採取行動。

244 248

245<h3 id="memory-limit-on-linux-and-wsl">249<h3 id="memory-limit-on-linux-and-wsl">

251* 將大小寫成位元組數或帶有 `K`、`M`、`G` 或 `T` 後綴。設定 `0`、`off`、`false`、`no` 或 `none` 以關閉上限。Claude Code 會忽略任何無法讀取為大小的其他值，例如 `4e9`。255* 將大小寫成位元組數或帶有 `K`、`M`、`G` 或 `T` 後綴。設定 `0`、`off`、`false`、`no` 或 `none` 以關閉上限。Claude Code 會忽略任何無法讀取為大小的其他值，例如 `4e9`。

252* Claude Code 將工作階段的所有 Bash、PowerShell 和 Monitor 命令計入一個上限，而不是每個命令各自計入。256* Claude Code 將工作階段的所有 Bash、PowerShell 和 Monitor 命令計入一個上限，而不是每個命令各自計入。

253* Claude Code 使用記憶體 cgroup 套用上限。當無法設定 cgroup 時，命令在沒有上限的情況下執行，來自 `claude --debug` 的偵錯日誌會說明原因。257* Claude Code 使用記憶體 cgroup 套用上限。當無法設定 cgroup 時，命令在沒有上限的情況下執行，來自 `claude --debug` 的偵錯日誌會說明原因。

254* 在 Claude Code 啟動的第一個程序已開啟上限或因為關閉值或失敗的 cgroup 設定而關閉上限後，Claude Code 會保留該結果直到您重新啟動。若要套用已變更或移除的值或固定的設定，請再次啟動 `claude`。258* 在 Claude Code 啟動的第一個程序已開啟上限或因為關閉值或失敗的 cgroup 設定而關閉上限後，Claude Code 會保留該結果直到您重新啟動。若要套用已變更或移除的值或修正後的設定，請再次啟動 `claude`。

255* 當命令無法保持在上限以下時，核心會終止命令，其結果中沒有任何內容命名上限。259* 當命令無法保持在上限以下時，核心會終止命令，其結果中沒有任何內容指出上限。

256 260

257Claude Code 也可以將它啟動的其他類型的程序計入相同的限制。將 [`CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE`](/docs/zh-TW/env-vars#variables) 設定為要從上限中豁免的類型的逗號分隔清單；Claude Code 將上限套用到不在您清單上的每種類型。將其設定為 `none` 以限制每種類型，或設定為 `all-new` 以僅限制 Bash、PowerShell 和 Monitor 工具命令。需要 Claude Code v2.1.246 或更新版本。您可以命名的類型：261Claude Code 也可以將它啟動的其他類型的程序計入相同的限制。將 [`CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE`](/docs/zh-TW/env-vars#variables) 設定為要從上限中豁免的類型的逗號分隔清單；Claude Code 將上限套用到不在您清單上的每種類型。將其設定為 `none` 以限制每種類型，或設定為 `all-new` 以僅限制 Bash、PowerShell 和 Monitor 工具命令。需要 Claude Code v2.1.246 或更新版本。您可以指定的類型：

258 262

259* `mcp`: 本機 [MCP 伺服器](/docs/zh-TW/mcp)263* `mcp`: 本機 [MCP 伺服器](/docs/zh-TW/mcp)

260* `lsp`: [語言伺服器](#lsp-tool-behavior)264* `lsp`: [語言伺服器](#lsp-tool-behavior)

261* `hooks`: [hook](/docs/zh-TW/hooks) 命令265* `hooks`: [hook](/docs/zh-TW/hooks) 命令

262* `plugin`: [外掛程式](/docs/zh-TW/plugins/overview)執行的命令266* `plugin`: [外掛](/docs/zh-TW/plugins/overview)執行的命令

263* `helper`: Claude Code 自己的協助程式命令，例如 `git`267* `helper`: Claude Code 自己的協助程式命令，例如 `git`

264* `agent`: 子 Claude Code 程序，例如[代理隊友](/docs/zh-TW/agent-teams)268* `agent`: 子 Claude Code 程序，例如 [agent 隊友](/docs/zh-TW/agent-teams)

265 269

266無論您列出什麼，這些規則都適用：270無論您列出什麼，這些規則都適用：

267 271

285 289

286使用 Bash 檢視檔案也滿足編輯前讀取要求，當命令是 `cat`、`nl`、`bat`、`batcat`、`head`、`tail`、`sed -n 'X,Yp'`、`grep`、`egrep`、`fgrep` 或 `rg` 在單一檔案上且沒有管道或重新導向時。管道輸出和其他 Bash 命令不計入編輯前讀取檢查。290使用 Bash 檢視檔案也滿足編輯前讀取要求，當命令是 `cat`、`nl`、`bat`、`batcat`、`head`、`tail`、`sed -n 'X,Yp'`、`grep`、`egrep`、`fgrep` 或 `rg` 在單一檔案上且沒有管道或重新導向時。管道輸出和其他 Bash 命令不計入編輯前讀取檢查。

287 291

288使用 Bash 檢視檔案僅影響編輯資格，不影響權限。請參閱 [Read 和 Edit 權限規則](/docs/zh-TW/permissions#read-and-edit)，了解您的 `Read` 和 `Edit` 拒絕規則涵蓋哪些 Bash 命令。292當 Claude 以這種方式檢視檔案時，Claude Code 也會載入適用於該檔案的任何[子目錄 `CLAUDE.md`](/docs/zh-TW/memory#how-claude-md-files-load) 和[路徑範圍規則](/docs/zh-TW/memory#path-specific-rules)。請參閱 [Read 和 Edit 權限規則](/docs/zh-TW/permissions#read-and-edit)，了解您的 `Read` 和 `Edit` 拒絕規則涵蓋哪些 Bash 命令。

289 293

290<h2 id="endconversation-tool-behavior">294<h2 id="endconversation-tool-behavior">

291 EndConversation 工具行為295 EndConversation 工具行為

709搜尋後端不可設定。若要使用不同的提供者進行搜尋，請新增公開搜尋工具的 [MCP 伺服器](/docs/zh-TW/mcp)。713搜尋後端不可設定。若要使用不同的提供者進行搜尋，請新增公開搜尋工具的 [MCP 伺服器](/docs/zh-TW/mcp)。

710 714

711<Note>715<Note>

712 WebSearch 在 Claude API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 上可用。在 Microsoft Foundry 上，它需要[部署在 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)：部署在 Azure 上的部署不支援伺服器端工具，因此 WebSearch 呼叫失敗。在 Google Cloud 的 Agent Platform 上，它適用於 Claude 4 及更新版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公開伺服器端網路搜尋工具。716 WebSearch 在 Claude API、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud 的 Agent Platform 上，它適用於 Claude 4 及更新版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公開伺服器端網路搜尋工具。

713</Note>717</Note>

714 718

715<h3 id="session-search-limit">719<h3 id="session-search-limit">

716 工作階段搜尋限制720 工作階段搜尋限制

717</h3>721</h3>

718 722

719一個工作階段最多可進行 200 次 WebSearch 呼叫，計算跨越主對話和它產生的每個[子代理](/docs/zh-TW/sub-agents)，因此平行研究展開所進行的搜尋會計入相同的限制。該限制需要 Claude Code v2.1.212 或更新版本。當 Claude 達到限制時，進一步的呼叫會傳回通知，告訴 Claude 繼續使用它已經收集的資訊，而不是會邀請重試的錯誤。您看不到通知：受限的呼叫在對話中顯示為未執行任何操作的搜尋，如果 Claude 需要更多搜尋，通知會告訴它要求您提高限制。723互動式終端機工作階段的 WebSearch 呼叫限制為 200 次。來自主對話和 [subagent](/docs/zh-TW/sub-agents) 的搜尋（例如平行研究展開）都會計入相同的限制。該限制需要 Claude Code v2.1.212 或更新版本。

724

725當工作階段達到限制時，搜尋在對話中會顯示為未執行任何操作的呼叫。Claude 會收到通知，告訴它繼續使用已經收集的資訊，如果需要更多搜尋，則要求您提高限制。

726

727若要取得更多搜尋次數，請提高上限、等待限制回補，或開始新的對話：

720 728

721設定 [`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`](/docs/zh-TW/env-vars) 環境變數以變更上限；它接受正整數，因此上限可以提高但無法關閉。執行 [`/clear`](/docs/zh-TW/commands#all-commands) 會重設計數。如果仍然可以產生[子代理](/docs/zh-TW/sub-agents)的工作（例如執行中的工作流程）在清除後存留，計數會改為進行。729* **提高上限**：將 [`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`](/docs/zh-TW/env-vars#variables) 環境變數設定為正整數，例如 `500`。上限可以提高但無法關閉。

730* **等待回補**：在 Claude Code v2.1.290 或更新版本中，互動式終端機工作階段的限制大約每小時回補 100 次呼叫。若要變更速率，請將 [`CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR`](/docs/zh-TW/env-vars#variables) 設定為每小時的呼叫次數，例如 `50`。

731* **開始新的對話**：在 Claude Code 提示字元執行 [`/clear`](/docs/zh-TW/commands#all-commands) 也會重設計數。如果仍然可以產生 subagent 的工作（例如執行中的工作流程）在清除後存留，計數則會延續。

722 732

723<h2 id="write-tool-behavior">733<h2 id="write-tool-behavior">

724 Write 工具行為734 Write 工具行為

vs-code.md +1 −0

Details

623* **Claude 的回覆**：擴充功能會在回覆完成時宣佈一次，並在文字串流進入時保持沉默。您的螢幕閱讀器會將程式碼區塊讀作行數摘要，按標籤讀取連結，並逐個儲存格讀取表格；完整回覆在文字記錄中保持可讀。623* **Claude 的回覆**：擴充功能會在回覆完成時宣佈一次，並在文字串流進入時保持沉默。您的螢幕閱讀器會將程式碼區塊讀作行數摘要，按標籤讀取連結，並逐個儲存格讀取表格；完整回覆在文字記錄中保持可讀。

624* **權限要求和問題**：當擴充功能的權限提示出現時，擴充功能會宣佈要求，並命名 Claude 想要使用的工具。當 Claude 詢問您問題以及當 Claude 完成計畫並等待您的審查時，它也會以相同方式宣佈。624* **權限要求和問題**：當擴充功能的權限提示出現時，擴充功能會宣佈要求，並命名 Claude 想要使用的工具。當 Claude 詢問您問題以及當 Claude 完成計畫並等待您的審查時，它也會以相同方式宣佈。

625* **狀態變更**：擴充功能會在 Claude 開始工作時、Claude 準備好接收您的輸入時以及 Claude Code 開始壓縮對話時宣佈。625* **狀態變更**：擴充功能會在 Claude 開始工作時、Claude 準備好接收您的輸入時以及 Claude Code 開始壓縮對話時宣佈。

626* **已排入佇列的訊息**：當您在 Claude 工作時傳送訊息，擴充功能會為該訊息宣佈「Message queued.」。

626* **錯誤和模型提示**：擴充功能會宣佈對話中的錯誤，並在 [使用額度同意提示](/docs/zh-TW/model-config#fable-and-usage-credits) 或 [標記要求提示](/docs/zh-TW/model-config#ask-before-switching) 出現時宣佈。627* **錯誤和模型提示**：擴充功能會宣佈對話中的錯誤，並在 [使用額度同意提示](/docs/zh-TW/model-config#fable-and-usage-credits) 或 [標記要求提示](/docs/zh-TW/model-config#ask-before-switching) 出現時宣佈。

627 628

628當 Claude 工作時，您的螢幕閱讀器會讀取文字標籤來代替進度微調器的動畫。629當 Claude 工作時，您的螢幕閱讀器會讀取文字標籤來代替進度微調器的動畫。

web-quickstart.md +1 −1

Details

12 12

13雲端會話在雲端基礎設施上執行 Claude Code，而不是在您的機器上，預設由 Anthropic 管理。此快速入門從瀏覽器中的 [claude.ai/code](https://claude.ai/code) 啟動一個會話。您也可以從 Claude 行動應用程式、Desktop 應用程式或終端機使用 `claude --cloud` 啟動一個會話。13雲端會話在雲端基礎設施上執行 Claude Code，而不是在您的機器上，預設由 Anthropic 管理。此快速入門從瀏覽器中的 [claude.ai/code](https://claude.ai/code) 啟動一個會話。您也可以從 Claude 行動應用程式、Desktop 應用程式或終端機使用 `claude --cloud` 啟動一個會話。

14 14

15您需要一個 GitHub 儲存庫來[開始使用](#connect-github)。Claude 將其複製到隔離的虛擬機器中、進行更改，並為您推送一個分支以供檢查。會話在設備間持續存在，因此您在筆記型電腦上開始的任務可以稍後從手機上檢查。15您需要一個 GitHub 儲存庫來[開始使用](#connect-github)。Claude 將其複製到隔離的虛擬機器中、進行更改，並為您推送一個分支以供檢查。工作階段在裝置間持續存在，因此您在筆記型電腦上開始的任務可以稍後從手機上檢查。每個工作階段都會與您其餘的 Claude 和 Claude Code 使用量一起計入方案的用量上限，雲端虛擬機器不會另外收費。

16 16

17雲端會話適用於：17雲端會話適用於：

18 18

Documentation 2026-10-07 23:59 UTC to 2026-10-08 20:59 UTC