Documentation — Spybara

agent-sdk/hooks.md +10 −10

Details

24 </Step>24 </Step>

25 25

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

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

28 </Step>28 </Step>

29 29

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

225 225

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

227 227

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

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

230 * 當 hook 在子代理內觸發時，`agent_id` 和 `agent_type` 會被填充。在 TypeScript 中，這些在基本 hook 輸入上，可供所有 hook 類型使用。在 Python 中，它們僅在 `PreToolUse`、`PostToolUse` 和 `PostToolUseFailure` 上。230 * 當 hook 在子代理內觸發時，`agent_id` 和 `agent_type` 會被填充。在 TypeScript 中，這些在基本 hook 輸入上，可供所有 hook 類型使用。在 Python 中，它們僅在 `PreToolUse`、`PostToolUse` 和 `PostToolUseFailure` 上。

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

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

237 237

238* **頂級欄位**控制對話：`systemMessage` 將訊息注入對話中，模型可見，`continue`（Python 中的 `continue_`）決定此 hook 後代理是否繼續執行。238* **頂級欄位**控制對話：`systemMessage` 將訊息注入對話中，模型可見，`continue`（Python 中的 `continue_`）決定此 hook 後代理是否繼續執行。

239* **`hookSpecificOutput`** 控制目前操作。內部的欄位取決於 hook 事件類型。對於 `PreToolUse` hooks，這是您設定 `permissionDecision`（`"allow"`、`"deny"` 或 `"ask"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。在 TypeScript SDK 中，`permissionDecision` 也接受 `"defer"` 以結束查詢並[稍後繼續](/zh-TW/hooks#defer-a-tool-call-for-later)；此值在 Python SDK 中不可用。對於 `PostToolUse` hooks，您可以設定 `additionalContext` 以將資訊附加到工具結果，或設定 `updatedToolOutput` 以在 Claude 看到之前完全替換工具的輸出。239* **`hookSpecificOutput`** 控制目前操作。內部的欄位取決於 hook 事件類型。對於 `PreToolUse` hooks，這是您設定 `permissionDecision`（`"allow"`、`"deny"`、`"ask"` 或 `"defer"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。返回 `"defer"` 會結束查詢，以便您可以[稍後繼續](/zh-TW/hooks#defer-a-tool-call-for-later)。對於 `PostToolUse` hooks，您可以設定 `additionalContext` 以將資訊附加到工具結果，或設定 `updatedToolOutput` 以在 Claude 看到之前完全替換工具的輸出。

240 240

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

242 242

243<Note>243<Note>

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

326</CodeGroup>326</CodeGroup>

327 327

328<Note>328<Note>

329 使用 `updatedInput` 時，您還必須包括 `permissionDecision: 'allow'`。始終返回新物件，而不是改變原始 `tool_input`。329 使用 `updatedInput` 時，您還必須包括 `permissionDecision: 'allow'` 以自動批准修改的輸入，或 `permissionDecision: 'ask'` 以將其顯示給使用者。使用 `'defer'` 時，`updatedInput` 會被忽略。始終返回新物件，而不是改變原始 `tool_input`。

330</Note>330</Note>

331 331

332### 新增上下文並阻止工具332### 新增上下文並阻止工具

489 489

490### 追蹤子代理活動490### 追蹤子代理活動

491 491

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

493 493

494<CodeGroup>494<CodeGroup>

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

621 621

622### 將通知轉發到 Slack622### 將通知轉發到 Slack

623 623

624使用 `Notification` hooks 接收來自代理的系統通知並將其轉發到外部服務。通知針對特定事件類型觸發：`permission_prompt`（Claude 需要權限）、`idle_prompt`（Claude 等待輸入）、`auth_success`（認證完成）和 `elicitation_dialog`（Claude 提示使用者）。每個通知都包括帶有人類可讀描述的 `message` 欄位，以及可選的 `title`。624使用 `Notification` hooks 接收來自代理的系統通知並將其轉發到外部服務。通知針對特定事件類型觸發：`permission_prompt`（Claude 需要權限）、`idle_prompt`（Claude 等待輸入）、`auth_success`（認證完成）、`elicitation_dialog`（Claude 提示使用者）、`elicitation_response`（使用者回答了引導）和 `elicitation_complete`（引導已關閉）。每個通知都包括帶有人類可讀描述的 `message` 欄位，以及可選的 `title`。

625 625

626此範例將每個通知轉發到 Slack 頻道。它需要 [Slack 傳入 webhook URL](https://api.slack.com/messaging/webhooks)，您可以通過將應用程式新增到 Slack 工作區並啟用傳入 webhooks 來建立：626此範例將每個通知轉發到 Slack 頻道。它需要 [Slack 傳入 webhook URL](https://api.slack.com/messaging/webhooks)，您可以通過將應用程式新增到 Slack 工作區並啟用傳入 webhooks 來建立：

627 627

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

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

729* 對於非工具 hooks，如 `Stop` 和 `SubagentStop`，匹配器匹配不同的欄位（請參閱[匹配器模式](/zh-TW/hooks#matcher-patterns)）729* 對於非工具 hooks，如 `Stop` 和 `SubagentStop`，匹配器匹配不同的欄位（請參閱[匹配器模式](/zh-TW/hooks#matcher-patterns)）

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

731 731

732### 匹配器未按預期篩選732### 匹配器未按預期篩選

733 733

769 };769 };

770 ```770 ```

771 771

772* 您還必須返回 `permissionDecision: 'allow'` 以使輸入修改生效772* 您還必須返回 `permissionDecision: 'allow'` 或 `'ask'` 以使輸入修改生效

773 773

774* 在 `hookSpecificOutput` 中包括 `hookEventName` 以識別輸出適用於哪個 hook 類型774* 在 `hookSpecificOutput` 中包括 `hookEventName` 以識別輸出適用於哪個 hook 類型

775 775

776### Python 中不可用會話 hooks776### Python 中不可用會話 hooks

777 777

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

779 779

780<CodeGroup>780<CodeGroup>

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

agent-sdk/modifying-system-prompts.md +431 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 修改系統提示詞

7> 在 `claude_code` 預設和自訂系統提示詞之間選擇，並使用 CLAUDE.md、輸出樣式、append 或完全自訂提示詞來自訂行為。

9系統提示詞定義了 Claude 的行為、功能和回應風格。從 `claude_code` 預設開始，適用於 CLI 或類似 IDE 的編碼工具，其中人類監督並引導工作。為具有不同介面、身份或權限模型的代理編寫您自己的提示詞。

11本頁涵蓋：

13* [系統提示詞如何運作](#how-system-prompts-work)，包含一個決策表，用於在預設、帶有 `append` 的預設和自訂提示詞之間進行選擇

14* [自訂代理行為](#customize-agent-behavior)，使用 CLAUDE.md 檔案、輸出樣式、`append` 或自訂字串

15* [比較四種方法](#compare-the-four-approaches)，按持久性、範圍和它們保留的內容進行比較

16* [組合方法](#combine-approaches)，將自訂方法分層組合在一起

18## 系統提示詞如何運作

20系統提示詞是初始指令集，塑造了 Claude 在整個對話中的行為方式。Agent SDK 有三個起點：

22* **最小預設**：當您在 TypeScript 中未設定 `systemPrompt` 或在 Python 中未設定 `system_prompt` 時，SDK 使用最小提示詞，涵蓋工具呼叫但省略了 Claude Code 的編碼指南、回應風格和專案上下文。這與 `claude -p` 不同，後者預設使用完整的 Claude Code 提示詞。如果您正在從 CLI 遷移並想要相符的行為，請設定 `claude_code` 預設。

23* **`claude_code` 預設**：Claude Code CLI 使用的完整系統提示詞，包含工具使用指令、程式碼風格和格式化指南、回應語氣和詳細程度規則、安全和防護指令，以及關於工作目錄和環境的上下文。在 TypeScript 中設定 `systemPrompt: { type: "preset", preset: "claude_code" }`，或在 Python 中設定 `system_prompt={"type": "preset", "preset": "claude_code"}`，可選擇使用 `append` 在末尾新增您自己的指令。

24* **自訂字串**：您自己撰寫的提示詞。SDK 只會傳送您提供的內容。

26### 決定起點

28決定因素是您的代理與 Claude Code 的相似程度：一個在儲存庫中運作的編碼代理，有人類監看串流輸出並引導工作。您的產品離該情況越遠，您就越想撰寫自己的提示詞。

30| 您正在建置 | 使用 | 您會得到 |

31| :----------------------------------------------------- | :-------------------------- | :--------------------------------------------- |

32| 一個 CLI 或類似 IDE 的編碼工具，其中人類監看並引導，而 Claude Code 的預設值是您想要的 | `claude_code` 預設 | 完整的 Claude Code 提示詞：工具指導、安全規則、終端機友善的回應、儲存庫慣例感知 |

33| 相同類型的工具，加上產品特定的規則，如編碼標準、輸出格式或領域上下文 | `claude_code` 預設搭配 `append` | 上述所有內容，加上您的指令新增在預設之後。沒有任何內容被移除，所以這是風險最低的自訂 |

34| 具有不同表面、身份或權限模型的代理，或非編碼代理 | 自訂提示詞字串 | 僅您撰寫的內容。您負責替換您的代理仍需要的工具指導和安全指令 |

35| 一個薄型工具呼叫迴圈，沒有代理角色，您在使用者提示詞中提供所有行為 | 無 `systemPrompt` 選項 | 最小預設：工具呼叫支援，沒有其他 |

37「不同於 Claude Code」通常意味著以下其中之一：

39* **不同的表面**：輸出不是由觸發它的人在終端機中讀取。聊天 UI、結構化輸出消費者和非編碼自動化各自需要一個與其輸出呈現和審查方式相符的提示詞。無人值守的編碼自動化，如修復 lint 錯誤或審查差異的 CI 工作，仍然符合預設，因為工作本身是預設為其編寫的。

40* **不同的身份**：代理不應將自己呈現為 Claude Code。支援機器人、資料分析助手或任何特定領域的代理需要自己的名稱、範圍和角色。

41* **不同的權限模型**：代理自主運作，無需人類批准每一步，或在一組狹隘的資源上運作。Claude Code 的提示詞假設人類在迴圈中，可以存取完整的工具集。

42* **非編碼任務**：Claude Code 提示詞的大部分是編碼指導。對於研究、內容或運營代理，該指導與您實際需要的指令競爭。

44[比較表](#compare-the-four-approaches)顯示每種自訂方法保留的內容。

46## 自訂代理程式行為

48輸出樣式、`append` 和自訂提示詞字串各自直接改變系統提示詞。CLAUDE.md 採用不同的路徑：SDK 讀取它並將其內容作為專案上下文注入對話中，而不是注入系統提示詞，因此它與您選擇的任何系統提示詞一起塑造行為。[Skills](/zh-TW/agent-sdk/skills)、[hooks](/zh-TW/agent-sdk/hooks) 和 [permissions](/zh-TW/agent-sdk/permissions) 也在系統提示詞之外塑造行為，並在各自的頁面上涵蓋。

50### 專案級指令的 CLAUDE.md 檔案

52CLAUDE.md 檔案為 Claude 提供持久的專案上下文和指令。SDK 將其內容注入對話中，而不是注入系統提示詞，因此它們適用於任何系統提示詞配置。關於在 CLAUDE.md 中放入什麼、放在哪裡以及如何編寫有效的指令，請參閱 [Claude 如何記住您的專案](/zh-TW/memory)。本節涵蓋 SDK 特定的內容：CLAUDE.md 如何載入。

54當匹配的設定來源已啟用時，SDK 讀取 CLAUDE.md：`'project'` 從工作目錄載入 `CLAUDE.md` 或 `.claude/CLAUDE.md`，`'user'` 載入 `~/.claude/CLAUDE.md`。預設 `query()` 選項啟用兩個來源，因此 CLAUDE.md 會自動載入。如果您在 TypeScript 中明確設定 `settingSources` 或在 Python 中設定 `setting_sources`，請包含您需要的來源。CLAUDE.md 載入由設定來源控制，而不是由 `claude_code` 預設值控制。

56#### 使用 SDK 載入 CLAUDE.md

58要載入 CLAUDE.md，請設定 `settingSources` 以包含您的 CLAUDE.md 所在的級別。下面的範例載入專案級 CLAUDE.md 以及 `claude_code` 預設值，因此 Claude 同時具有完整的編碼代理程式提示詞和您專案的約定：

60<CodeGroup>

61 ```typescript TypeScript theme={null}

62 import { query } from "@anthropic-ai/claude-agent-sdk";

64 const messages = [];

66 for await (const message of query({

67 prompt: "Add a new React component for user profiles",

68 options: {

69 systemPrompt: {

70 type: "preset",

71 preset: "claude_code" // 使用 Claude Code 的系統提示詞

72 },

73 settingSources: ["project"] // 從專案載入 CLAUDE.md

74 }

75 })) {

76 messages.push(message);

77 }

79 // 現在 Claude 可以存取您來自 CLAUDE.md 的專案指南

80 ```

82 ```python Python theme={null}

83 from claude_agent_sdk import query, ClaudeAgentOptions

85 messages = []

87 async for message in query(

88 prompt="Add a new React component for user profiles",

89 options=ClaudeAgentOptions(

90 system_prompt={

91 "type": "preset",

92 "preset": "claude_code", # 使用 Claude Code 的系統提示詞

93 },

94 setting_sources=["project"], # 從專案載入 CLAUDE.md

95 ),

96 ):

97 messages.append(message)

99 # 現在 Claude 可以存取您來自 CLAUDE.md 的專案指南

100 ```

101</CodeGroup>

102

103CLAUDE.md 在專案的所有會話中持續存在，通過 git 與您的團隊共享，並自動發現而無需程式碼變更。如果您傳遞空的 `settingSources` 陣列，則不會載入。

104

105### 輸出樣式用於持久配置

106

107輸出樣式是修改 Claude 系統提示詞的已儲存配置。它們儲存為 markdown 檔案，可以在會話和專案中重複使用。

108

109#### 建立輸出樣式

110

111輸出樣式是一個 markdown 檔案，其 frontmatter 中有 `name` 和 `description`，後面跟著提示詞內容。將其儲存到 `~/.claude/output-styles/` 以獲得在每個專案中可用的使用者級樣式，或儲存到您的儲存庫中的 `.claude/output-styles/` 以獲得可以提交並與您的團隊共享的專案級樣式。

112

113下面的範例定義了程式碼審查角色。將其儲存為 `~/.claude/output-styles/code-reviewer.md` 以在專案中提供：

114

115```markdown ~/.claude/output-styles/code-reviewer.md theme={null}

116---

117name: Code Reviewer

118description: Thorough code review assistant

119---

120

121You are an expert code reviewer.

122

123For every code submission:

1241. Check for bugs and security issues

1252. Evaluate performance

1263. Suggest improvements

1274. Rate code quality (1-10)

128```

129

130#### 啟用輸出樣式

131

132建立後，通過以下方式啟用輸出樣式：

133

134* **CLI**：執行 `/config` 並選擇輸出樣式

135* **設定**：在 `.claude/settings.local.json` 中設定 `outputStyle`

136* **TypeScript SDK**：將 `options.outputStyle` 設定為樣式的名稱

137

138Python SDK 沒有以程式設計方式選擇輸出樣式的選項。對於無法寫入 `.claude/settings.local.json` 的僅程式碼部署，請改用 `append` 或自訂提示詞字串。

139

140**SDK 使用者注意：** 當您在選項中包含 `settingSources: ['user']` 或 `settingSources: ['project']`（TypeScript）/ `setting_sources=["user"]` 或 `setting_sources=["project"]`（Python）時，輸出樣式會被載入。

141

142### 附加到 `claude_code` 預設值

143

144您可以使用 Claude Code 預設值搭配 `append` 屬性來新增自訂指令，同時保留所有內建功能。

145

146<CodeGroup>

147 ```typescript TypeScript theme={null}

148 import { query } from "@anthropic-ai/claude-agent-sdk";

149

150 const messages = [];

151

152 for await (const message of query({

153 prompt: "Help me write a Python function to calculate fibonacci numbers",

154 options: {

155 systemPrompt: {

156 type: "preset",

157 preset: "claude_code",

158 append: "Always include detailed docstrings and type hints in Python code."

159 }

160 }

161 })) {

162 messages.push(message);

163 if (message.type === "assistant") {

164 console.log(message.message.content);

165 }

166 }

167 ```

168

169 ```python Python theme={null}

170 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

171

172 messages = []

173

174 async for message in query(

175 prompt="Help me write a Python function to calculate fibonacci numbers",

176 options=ClaudeAgentOptions(

177 system_prompt={

178 "type": "preset",

179 "preset": "claude_code",

180 "append": "Always include detailed docstrings and type hints in Python code.",

181 }

182 ),

183 ):

184 messages.append(message)

185 if isinstance(message, AssistantMessage):

186 print(message.content)

187 ```

188</CodeGroup>

189

190#### 改進跨使用者和機器的提示詞快取

191

192預設情況下，使用相同 `claude_code` 預設值和 `append` 文字的兩個會話，如果從不同的工作目錄執行，仍然無法共享提示詞快取項目。這是因為預設值在您的 `append` 文字之前在系統提示詞中嵌入了每個會話的上下文：工作目錄、它是否為 git 儲存庫、平台、活動 shell、OS 版本和自動記憶路徑。該上下文中的任何差異都會產生不同的系統提示詞和快取未命中。CLAUDE.md 內容不會影響系統提示詞快取，因為 SDK 將其注入對話中，而不是系統提示詞。

193

194要使系統提示詞在會話中相同，請在 TypeScript 中設定 `excludeDynamicSections: true`，或在 Python 中設定 `"exclude_dynamic_sections": True`。每個會話的上下文移動到第一個使用者訊息中，只在系統提示詞中保留靜態預設值和您的 `append` 文字，以便相同的配置可以在使用者和機器之間共享快取項目。

195

196<Note>

197 `excludeDynamicSections` 需要 `@anthropic-ai/claude-agent-sdk` v0.2.98 或更新版本，或 Python 的 `claude-agent-sdk` v0.1.58 或更新版本。它僅適用於預設物件形式，當 `systemPrompt` 是字串時無效。

198</Note>

199

200以下範例將共享 `append` 區塊與 `excludeDynamicSections` 配對，以便從不同目錄執行的代理程式群隊可以重複使用相同的快取系統提示詞：

201

202<CodeGroup>

203 ```typescript TypeScript theme={null}

204 import { query } from "@anthropic-ai/claude-agent-sdk";

205

206 for await (const message of query({

207 prompt: "Triage the open issues in this repo",

208 options: {

209 systemPrompt: {

210 type: "preset",

211 preset: "claude_code",

212 append: "You operate Acme's internal triage workflow. Label issues by component and severity.",

213 excludeDynamicSections: true

214 }

215 }

216 })) {

217 // ...

218 }

219 ```

220

221 ```python Python theme={null}

222 from claude_agent_sdk import query, ClaudeAgentOptions

223

224 async for message in query(

225 prompt="Triage the open issues in this repo",

226 options=ClaudeAgentOptions(

227 system_prompt={

228 "type": "preset",

229 "preset": "claude_code",

230 "append": "You operate Acme's internal triage workflow. Label issues by component and severity.",

231 "exclude_dynamic_sections": True,

232 },

233 ),

234 ):

235 ...

236 ```

237</CodeGroup>

238

239**權衡：** 工作目錄、git 儲存庫旗標、平台、活動 shell、OS 版本和自動記憶路徑仍然會到達 Claude，但作為第一個使用者訊息的一部分，而不是系統提示詞。使用者訊息中的指令比系統提示詞中的相同文字的權重略低，所以 Claude 在推理目前目錄或自動記憶路徑時可能會較少依賴它們。當跨會話快取重複使用比最大化權威環境上下文更重要時，請啟用此選項。

240

241對於非互動式 CLI 模式中的等效旗標，請參閱 [`--exclude-dynamic-system-prompt-sections`](/zh-TW/cli-reference)。

242

243### 自訂系統提示詞

244

245您可以提供自訂字串作為 `systemPrompt` 以完全用您自己的指令替換預設值。

246

247<CodeGroup>

248 ```typescript TypeScript theme={null}

249 import { query } from "@anthropic-ai/claude-agent-sdk";

250

251 const customPrompt = `You are a Python coding specialist.

252 Follow these guidelines:

253 - Write clean, well-documented code

254 - Use type hints for all functions

255 - Include comprehensive docstrings

256 - Prefer functional programming patterns when appropriate

257 - Always explain your code choices`;

258

259 const messages = [];

260

261 for await (const message of query({

262 prompt: "Create a data processing pipeline",

263 options: {

264 systemPrompt: customPrompt

265 }

266 })) {

267 messages.push(message);

268 if (message.type === "assistant") {

269 console.log(message.message.content);

270 }

271 }

272 ```

273

274 ```python Python theme={null}

275 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

276

277 custom_prompt = """You are a Python coding specialist.

278 Follow these guidelines:

279 - Write clean, well-documented code

280 - Use type hints for all functions

281 - Include comprehensive docstrings

282 - Prefer functional programming patterns when appropriate

283 - Always explain your code choices"""

284

285 messages = []

286

287 async for message in query(

288 prompt="Create a data processing pipeline",

289 options=ClaudeAgentOptions(system_prompt=custom_prompt),

290 ):

291 messages.append(message)

292 if isinstance(message, AssistantMessage):

293 print(message.content)

294 ```

295</CodeGroup>

296

297## 比較四種方法

298

299四種自訂方法在位置、共享方式和從 `claude_code` 預設保留的內容方面有所不同。

300

302| ---------- | --------- | -------- | ----------------- | ----------------- |

303| **持久性** | 每個專案檔案 | 儲存為檔案 | 僅限會話 | 僅限會話 |

304| **可重複使用性** | 每個專案 | 跨專案 | 程式碼重複 | 程式碼重複 |

305| **管理** | 在檔案系統上 | CLI + 檔案 | 在程式碼中 | 在程式碼中 |

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

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

308| **環境上下文** | 自動 | 自動 | 自動 | 必須提供 |

309| **自訂程度** | 僅新增 | 替換預設 | 僅新增 | 完全控制 |

310| **版本控制** | 與專案一起 | 是 | 與程式碼一起 | 與程式碼一起 |

311| **範圍** | 專案特定 | 使用者或專案 | 程式碼會話 | 程式碼會話 |

312

313「附加」是指在 TypeScript 中使用 `systemPrompt: { type: "preset", preset: "claude_code", append: "..." }`，或在 Python 中使用 `system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}`。CLAUDE.md 不會變更系統提示本身：SDK 會將其內容作為專案上下文注入到對話中。

314

315## 使用案例和最佳實踐

316

317### 何時使用 CLAUDE.md

318

319使用 CLAUDE.md 來記錄應該適用於專案中每個會話的指令，無論該會話使用哪個系統提示詞：編碼標準、常見命令、架構上下文和團隊約定。CLAUDE.md 被提交到您的儲存庫，因此它與它描述的程式碼保持同步。請參閱 [何時新增到 CLAUDE.md](/zh-TW/memory#when-to-add-to-claude-md) 以獲得完整指導。

320

321CLAUDE.md 檔案在啟用 `project` 設定來源時載入，預設 `query()` 選項已啟用此功能。如果您在 TypeScript 中明確設定 `settingSources` 或在 Python 中設定 `setting_sources`，請包含 `'project'` 以繼續載入專案級 CLAUDE.md。

322

323### 何時使用輸出樣式

324

325輸出樣式適用於您想在 CLI 和 SDK 中重複使用的角色，無需變更應用程式程式碼。因為它們作為檔案存在於 `.claude/output-styles` 中，相同的角色可從 CLI 中的 `/config` 以及載入相符設定來源的任何 SDK 會話中使用。

326

327**最適合：**

328

329* 跨會話的持久行為變更

330* 團隊共享配置

331* 專門助手，例如程式碼審查者、資料科學家或 DevOps 助手

332* 需要版本控制的複雜提示詞修改

333

334**範例：**

335

336* 建立專用的 SQL 最佳化助手

337* 建置安全焦點的程式碼審查者

338* 開發具有特定教學法的教學助手

339

340### 何時使用 `systemPrompt` 附加

341

342在 `claude_code` 預設已經符合您的產品需求，而您只需要疊加額外指令時，使用 `append`。您保留預設的工具指導、安全規則和編碼約定，無需重新實現它們。

343

344**最適合：**

345

346* 新增特定的編碼標準或偏好

347* 自訂輸出格式

348* 新增領域特定知識

349* 修改回應詳細程度

350* 在不失去工具指令的情況下增強 Claude Code 的預設行為

351

352### 何時使用自訂 `systemPrompt`

353

354當您的代理程式的表面、身份或權限模型與 Claude Code 的不同時，使用自訂提示詞，如 [決定起點](#decide-on-a-starting-point) 中所述。您定義完整的指令集，包括您的代理程式需要的任何工具指導和安全規則。

355

356**最適合：**

357

358* 完全控制 Claude 的行為

359* 專門的單一會話任務

360* 測試新的提示詞策略

361* 不需要預設工具的情況

362* 建置具有獨特行為的專門代理程式

363

364## 結合方法

365

366這些方法可以組合使用。持久輸出樣式或 CLAUDE.md 設定長期行為，而 `append` 在不觸及已保存配置的情況下，在頂部疊加會話特定的指令。

367

368### 結合輸出樣式與會話特定新增

369

370下面的範例假設 Code Reviewer 輸出樣式已經啟用。`append` 區塊在角色上疊加會話特定的焦點區域，因此單一審查會話可以優先考慮 OAuth 和令牌存儲，而無需更改已保存的輸出樣式：

371

372<CodeGroup>

373 ```typescript TypeScript theme={null}

374 import { query } from "@anthropic-ai/claude-agent-sdk";

375

376 // 假設「Code Reviewer」輸出樣式已啟用（通過 /config 或設定）

377 // 新增會話特定的焦點區域

378 const messages = [];

379

380 for await (const message of query({

381 prompt: "Review this authentication module",

382 options: {

383 systemPrompt: {

384 type: "preset",

385 preset: "claude_code",

386 append: `

387 For this review, prioritize:

388 - OAuth 2.0 compliance

389 - Token storage security

390 - Session management

391 `

392 }

393 }

394 })) {

395 messages.push(message);

396 }

397 ```

398

399 ```python Python theme={null}

400 from claude_agent_sdk import query, ClaudeAgentOptions

401

402 # 假設「Code Reviewer」輸出樣式已啟用（通過 /config 或設定）

403 # 新增會話特定的焦點區域

404 messages = []

405

406 async for message in query(

407 prompt="Review this authentication module",

408 options=ClaudeAgentOptions(

409 system_prompt={

410 "type": "preset",

411 "preset": "claude_code",

412 "append": """

413 For this review, prioritize:

414 - OAuth 2.0 compliance

415 - Token storage security

416 - Session management

417 """,

418 }

419 ),

420 ):

421 messages.append(message)

422 ```

423</CodeGroup>

424

425## 另請參閱

426

427* [輸出樣式](/zh-TW/output-styles)：為 CLI 建立、管理和分享輸出樣式，包括檔案格式和儲存位置

428* [Claude 如何記住您的專案](/zh-TW/memory)：CLAUDE.md 中應放入的內容、放置位置，以及如何撰寫有效的專案指示

429* [TypeScript SDK 參考](/zh-TW/agent-sdk/typescript)：完整的 `Options` 類型，包括 `systemPrompt`、`settingSources` 和 `outputStyle`

430* [Python SDK 參考](/zh-TW/agent-sdk/python)：完整的 `ClaudeAgentOptions` 類型，包括 `system_prompt` 和 `setting_sources`

431* [設定](/zh-TW/settings)：`settings.json` 參考，包括輸出樣式和其他配置的儲存位置

agent-sdk/typescript.md +1 −0

Details

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

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

399| `outputStyle` | `string` | `undefined` | 要為會話激活的 [輸出樣式](/zh-TW/output-styles) 的名稱。該樣式必須存在於已加載的 `settingSources` 位置，例如 `.claude/output-styles/`。見 [激活輸出樣式](/zh-TW/agent-sdk/modifying-system-prompts#activate-an-output-style) |

agent-sdk/user-input.md +47 −1

Details

12 12

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

14 14

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

16 16

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

18 18

232 232

233* **批准**：讓工具按 Claude 要求執行233* **批准**：讓工具按 Claude 要求執行

234* **批准並進行更改**：在執行前修改輸入（例如清理路徑、添加約束）234* **批准並進行更改**：在執行前修改輸入（例如清理路徑、添加約束）

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

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

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

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

297 </CodeGroup>298 </CodeGroup>

298 </Tab>299 </Tab>

299 300

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

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

303

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

305

306 <CodeGroup>

307 ```python Python theme={null}

308 async def can_use_tool(tool_name, input_data, context):

309 choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])

310

311 if choice == "always":

312 persist = [

313 s for s in context.suggestions if s.destination == "localSettings"

314 ]

315 return PermissionResultAllow(

316 updated_input=input_data, updated_permissions=persist

317 )

318 if choice == "once":

319 return PermissionResultAllow(updated_input=input_data)

320 return PermissionResultDeny(message="User declined")

321 ```

322

323 ```typescript TypeScript theme={null}

324 canUseTool: async (toolName, input, { suggestions = [] }) => {

325 const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);

326

327 if (choice === "always") {

328 const persist = suggestions.filter(

329 (s) => s.destination === "localSettings"

330 );

331 return {

332 behavior: "allow",

333 updatedInput: input,

334 updatedPermissions: persist

335 };

336 }

337 if (choice === "once") {

338 return { behavior: "allow", updatedInput: input };

339 }

340 return { behavior: "deny", message: "User declined" };

341 };

342 ```

343 </CodeGroup>

344 </Tab>

345

300 <Tab title="拒絕">346 <Tab title="拒絕">

301 使用者不希望發生此操作。阻止工具並提供說明原因的訊息。Claude 會看到此訊息並可能嘗試不同的方法。347 使用者不希望發生此操作。阻止工具並提供說明原因的訊息。Claude 會看到此訊息並可能嘗試不同的方法。

302 348

agent-teams.md +2 −0

Details

129Use Sonnet for each teammate.129Use Sonnet for each teammate.

130```130```

131 131

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

133

132### 要求隊友的計畫批准134### 要求隊友的計畫批准

133 135

134對於複雜或有風險的任務，您可以要求隊友在實施前進行計畫。隊友在唯讀計畫模式下工作，直到主管批准其方法：136對於複雜或有風險的任務，您可以要求隊友在實施前進行計畫。隊友在唯讀計畫模式下工作，直到主管批准其方法：

agent-view.md +34 −15

Details

38 </Step>38 </Step>

39 39

40 <Step title="分派工作階段">40 <Step title="分派工作階段">

41 在輸入框中輸入提示，然後按 `Enter`。新工作階段啟動並顯示為一行，顯示它是否正在工作、等待您或已完成。重複此操作以並行執行任意數量的工作階段。41 在輸入框中輸入提示，然後按 `Enter`。新工作階段啟動並顯示為一行，顯示它是否正在工作、等待您或已完成。重複此操作以並行執行任意數量的工作階段。每個工作階段獨立使用您的訂閱配額，因此在一次分派許多工作階段之前，請參閱[限制](#limitations)。

42 </Step>42 </Step>

43 43

44 <Step title="查看和回覆">44 <Step title="查看和回覆">

58 58

59執行 `claude agents` 開啟 agent view。它接管整個終端並列出按狀態分組的每個工作階段，固定的工作階段和需要您的工作階段在頂部。每行顯示工作階段的名稱、當前活動和上次更改的時間。59執行 `claude agents` 開啟 agent view。它接管整個終端並列出按狀態分組的每個工作階段，固定的工作階段和需要您的工作階段在頂部。每行顯示工作階段的名稱、當前活動和上次更改的時間。

60 60

61該列表對您的機器是全局的，包括每個背景工作階段，無論它在哪個專案或 worktree 中工作。您在其他終端中開啟的互動工作階段在您 [背景化它們](#from-inside-a-session) 之前不會出現，[subagents](/zh-TW/sub-agents) 在工作階段內執行時不會列為單獨的行。61該列表涵蓋您的 [config 目錄](#how-background-sessions-are-hosted) 下的每個背景工作階段，無論它在哪個專案或 worktree 中工作，因此在一個儲存庫中啟動的工作階段和在不同 worktree 中啟動的另一個工作階段都會一起出現。您在其他終端中開啟的互動工作階段在您 [背景化它們](#from-inside-a-session) 之前不會出現，[subagents](/zh-TW/sub-agents) 在工作階段內執行時不會列為單獨的行。

62 62

63```text theme={null}63```text theme={null}

64Pinned64Pinned

65 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m65 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

66 66

67Ready for review67Ready for review

~~68 ∙ jump physics github.com/anthropics/example/pull/2048 2h~~68 ∙ jump physics github.com/anthropics/example/pull/2048 ● 2h

69 69

70Needs input70Needs input

71 ✻ power-up design needs input: double jump or wall climb? 1m71 ✻ power-up design needs input: double jump or wall climb? 1m

80 … 6 more80 … 6 more

81```81```

82 82

~~83圖示告訴您工作階段的狀態：~~83每行的圖示傳達兩個信號。指示器告訴您工作階段的狀態，圖示的形狀告訴您底層程序是否仍在執行。狀態如下：

84 84

~~85| 圖示 | 狀態 | 含義 |~~85| 指示器 | 狀態 | 含義 |

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

87| 動畫 | 工作中 | Claude 正在主動執行工具或生成回應 |87| 動畫 | 工作中 | Claude 正在主動執行工具或生成回應 |

88| 黃色 | 需要輸入 | Claude 正在等待您的輸入，通常是權限決定或答案 |88| 黃色 | 需要輸入 | Claude 正在等待您的輸入，通常是權限決定或答案 |

89| 淡化 | 閒置 | 工作階段正在等待輸入，但不會被特定問題阻止 |89| 淡化 | 閒置 | 工作階段正在等待輸入，但不會被特定問題阻止 |

97 97

98工作階段在磁碟上持久化：關閉終端或自動更新不會丟失它們，重新開啟 `claude agents` 會顯示它們全部。如果您的機器進入睡眠或關閉，執行中的工作階段會停止；使用 `claude respawn --all` 重新啟動它們。98工作階段在磁碟上持久化：關閉終端或自動更新不會丟失它們，重新開啟 `claude agents` 會顯示它們全部。如果您的機器進入睡眠或關閉，執行中的工作階段會停止；使用 `claude respawn --all` 重新啟動它們。

99 99

100每行中的單行摘要由您配置的 [Haiku-class 模型](/zh-TW/model-config) 生成，因此該行可以告訴您工作階段正在做什麼、需要什麼或生成了什麼，無需開啟記錄。每個摘要是通過您的正常提供者的一個簡短 Haiku-class 請求，按照與工作階段本身相同的 [資料使用條款](/zh-TW/data-usage) 計費和處理。100每行中的單行摘要由您配置的 [Haiku-class 模型](/zh-TW/model-config) 生成，因此該行可以告訴您工作階段正在做什麼、需要什麼或生成了什麼，無需開啟記錄。當工作階段主動工作時，摘要最多每 15 秒刷新一次，加上每個回合結束時刷新一次。每次刷新都是通過您的正常提供者的一個簡短 Haiku-class 請求，按照與工作階段本身相同的 [資料使用條款](/zh-TW/data-usage) 計費和處理。

101 101

102當工作階段開啟拉取請求時，該行顯示 PR 連結和其 CI 檢查的狀態指示器。對於大多數任務，此行是您收集工作的方式：當其檢查通過時審查並合併拉取請求。102當工作階段開啟拉取請求時，狀態點會出現在該行的右邊緣，在支援超連結的終端中連結到拉取請求。當工作階段開啟了多個拉取請求時，計數會出現在點之前，顏色反映最需要關注的那個。

103

104| 點的顏色 | 拉取請求狀態 |

105| :--- | :------------ |

106| 黃色 | 等待檢查或審查，或檢查失敗 |

107| 綠色 | 檢查通過且沒有審查阻止 |

108| 紫色 | 已合併 |

109| 灰色 | 草稿或已關閉 |

110

111對於大多數任務，此行是您收集結果的地方：當點變綠時審查並合併拉取請求。

103 112

104### 查看和回覆113### 查看和回覆

105 114

119 128

120分離永遠不會停止背景工作階段：`←`、`Ctrl+C`、`Ctrl+D`、`Ctrl+Z` 和 `/exit` 都會讓它繼續執行。要從內部結束工作階段，執行 `/stop`。129分離永遠不會停止背景工作階段：`←`、`Ctrl+C`、`Ctrl+D`、`Ctrl+Z` 和 `/exit` 都會讓它繼續執行。要從內部結束工作階段，執行 `/stop`。

121 130

122使用 agent view 後，在空提示上按 `←` 可從任何 Claude Code 工作階段工作，而不僅僅是您附加的工作階段。它開啟 agent view，預先選擇您的當前工作階段，因此您可以在不離開終端的情況下切換工作階段。131在您分派或背景化工作階段後，在空提示上按 `←` 可從任何 Claude Code 工作階段工作，而不僅僅是您從 agent view 附加的工作階段。它背景化當前工作階段並開啟 agent view，預先選擇該工作階段，因此您可以在不離開終端的情況下切換工作階段。您可以在 `/config` 中關閉此快捷鍵。

123 132

124### 組織列表133### 組織列表

125 134

181 190

182輸入 `/` 分派 [skill](/zh-TW/skills)。將重複任務打包為 skill 可讓您從 agent view 多次啟動相同的工作流程，無需重新輸入提示。在空輸入上按 `Tab` 瀏覽每個可分派的 subagent，或在顯示建議時應用突出顯示的建議。191輸入 `/` 分派 [skill](/zh-TW/skills)。將重複任務打包為 skill 可讓您從 agent view 多次啟動相同的工作流程，無需重新輸入提示。在空輸入上按 `Tab` 瀏覽每個可分派的 subagent，或在顯示建議時應用突出顯示的建議。

183 192

193當相同的 `@name` 同時與 subagent 和同級存儲庫匹配時，subagent 優先。不帶 `@` 的第一個單詞形式也適用於任何 subagent 名稱，因此以與您的 subagent 名稱之一匹配的單詞開頭的提示會分派該 subagent。當您想要明確時，請使用 `@` 形式。

194

184#### 分派到特定目錄195#### 分派到特定目錄

185 196

186新工作階段在您開啟 agent view 的目錄中執行。要針對不同的目錄：197新工作階段在您開啟 agent view 的目錄中執行。要針對不同的目錄：

191 202

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

193 204

194#### 在 worktree 中隔離檔案編輯

~~195~~

196從 agent view 分派的工作階段預設共享您的工作目錄，因此兩個代理編輯相同檔案可能會衝突。為了防止這種情況，Claude Code 阻止從 agent view 分派的工作階段寫入檔案，直到它移動到隔離的 [git worktree](/zh-TW/worktrees)。當 Claude 需要編輯檔案時，它會自動處理此問題。worktree 在專案目錄內的 `.claude/worktrees/` 下建立，當您刪除工作階段時移除。刪除工作階段也會刪除其 worktree，因此在刪除前合併或推送您想保留的更改。

~~197~~

198要使 subagent 始終在其自己的 worktree 中執行，無論如何啟動，請在其 frontmatter 中設定 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)。

~~199~~

200### 從工作階段內部205### 從工作階段內部

201 206

202執行 `/background` 或其別名 `/bg` 分離當前對話並保持其執行。傳遞提示，例如 `/bg run the test suite and fix any failures`，在分離前發送一個額外的指令。207執行 `/background` 或其別名 `/bg` 分離當前對話並保持其執行。傳遞提示，例如 `/bg run the test suite and fix any failures`，在分離前發送一個額外的指令。

225 claude stop 7c5dcf5d stop this session230 claude stop 7c5dcf5d stop this session

226```231```

227 232

233### 檔案編輯如何隔離

234

235每個背景工作階段，無論是從 agent view、`/bg` 或 `claude --bg` 啟動，都在您的工作目錄中啟動，但被阻止在那裡寫入檔案。當工作階段需要編輯檔案時，Claude 會自動將其移動到 `.claude/worktrees/` 下的隔離 [git worktree](/zh-TW/worktrees) 中，因此並行工作階段可以讀取相同的檢出，但每個都寫入自己的。當工作階段已在 worktree 內、工作目錄不是 git 存儲庫或寫入工作目錄外時，該阻止不適用。

236

237當您刪除工作階段時，worktree 被移除，因此在刪除前合併或推送您想保留的更改。要找到工作階段的 worktree 路徑，查看工作階段或附加並檢查其工作目錄。

238

239要使 subagent 始終在其自己的 worktree 中執行，無論如何啟動，請在其 frontmatter 中設定 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)。

240

241### 權限模式和設定

242

243分派的工作階段從它執行的目錄讀取其 [settings](/zh-TW/settings) 和 [permission mode](/zh-TW/permissions)，就像您在那裡啟動了 `claude` 一樣。從 agent view 輸入分派不會傳遞權限模式，因此工作階段使用該目錄設定中的 `defaultMode` 或分派的 [subagent 的 frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`。

244

245要從 shell 設定模式，使用 `claude --bg` 傳遞 `--permission-mode`。使用 `bypassPermissions` 或 `auto` 這種方式被拒絕，直到您通過以互動方式運行 `claude` 接受該模式，因為這些模式讓您未監視的工作階段無需批准即可行動。

246

228## 從 shell 管理工作階段247## 從 shell 管理工作階段

229 248

230每個背景工作階段都有一個短 ID，您可以從 shell 使用。這些命令對於指令碼編寫或當您不想開啟 agent view 時很有用。249每個背景工作階段都有一個短 ID，您可以從 shell 使用。這些命令對於指令碼編寫或當您不想開啟 agent view 時很有用。

claude-directory.md +6 −3

Details

1465點擊檔案名稱以在上方的探索器中開啟該節點。1465點擊檔案名稱以在上方的探索器中開啟該節點。

1466 1466

1467| 檔案 | 範圍 | 提交 | 功能 | 參考 |1467| 檔案 | 範圍 | 提交 | 功能 | 參考 |

1468| --------------------------------------------------- | ----- | -- | ----------------------------- | ----------------------------------------------------------------------- |1468| --------------------------------------------------- | ----- | -- | ----------------------------- | ------------------------------------------------------------------ |

1470| [`rules/*.md`](#ce-rules) | 專案和全域 | ✓ | 主題範圍的指令，可選擇路徑限制 | [Rules](/zh-TW/memory#organize-rules-with-claude/rules/) |1470| [`rules/*.md`](#ce-rules) | 專案和全域 | ✓ | 主題範圍的指令，可選擇路徑限制 | [Rules](/zh-TW/memory#organize-rules-with-claude/rules/) |

1473| [`.mcp.json`](#ce-mcp-json) | 僅專案 | ✓ | 團隊共享的 MCP 伺服器 | [MCP scopes](/zh-TW/mcp#mcp-installation-scopes) |1473| [`.mcp.json`](#ce-mcp-json) | 僅專案 | ✓ | 團隊共享的 MCP 伺服器 | [MCP scopes](/zh-TW/mcp#mcp-installation-scopes) |

1474| [`.worktreeinclude`](#ce-worktreeinclude) | 僅專案 | ✓ | Gitignored 檔案以複製到新的 worktrees | [Worktrees](/zh-TW/common-workflows#copy-gitignored-files-to-worktrees) |1474| [`.worktreeinclude`](#ce-worktreeinclude) | 僅專案 | ✓ | Gitignored 檔案以複製到新的 worktrees | [Worktrees](/zh-TW/worktrees#copy-gitignored-files-into-worktrees) |

1476| [`commands/*.md`](#ce-commands) | 專案和全域 | ✓ | 單檔案提示；與 skills 相同的機制 | [Skills](/zh-TW/skills) |1476| [`commands/*.md`](#ce-commands) | 專案和全域 | ✓ | 單檔案提示；與 skills 相同的機制 | [Skills](/zh-TW/skills) |

1477| [`output-styles/*.md`](#ce-output-styles) | 專案和全域 | ✓ | 自訂系統提示部分 | [Output styles](/zh-TW/output-styles) |1477| [`output-styles/*.md`](#ce-output-styles) | 專案和全域 | ✓ | 自訂系統提示部分 | [Output styles](/zh-TW/output-styles) |

1510| `~/.claude/` 下的路徑 | 內容 |1510| `~/.claude/` 下的路徑 | 內容 |

1511| -------------------------------------------- | --------------------------------------------------------------------------------------- |1511| -------------------------------------------- | --------------------------------------------------------------------------------------- |

1513| `projects/<project>/<session>/subagents/` | [Subagent](/zh-TW/sub-agents) 對話文字記錄，當父工作階段文字記錄過期時一起移除 |

1525以下路徑不受自動清理覆蓋，並無限期保留。1526以下路徑不受自動清理覆蓋，並無限期保留。

1526 1527

1527| `~/.claude/` 下的路徑 | 內容 |1528| `~/.claude/` 下的路徑 | 內容 |

1528| ------------------ | ------------------------------ |1529| ---------------------- | --------------------------------------------------------------------------- |

1532| `remote-settings.json` | 您組織的[伺服器管理設定](/zh-TW/server-managed-settings)的快取副本。僅在您的組織已設定時出現。在每次啟動時重新整理。 |

1532 1534

1533其他小型快取和鎖定檔案會根據您使用的功能而出現，可安全刪除。1535其他小型快取和鎖定檔案會根據您使用的功能而出現，可安全刪除。

1588| `~/.claude/remote-settings.json` | 無。在下次啟動時重新擷取。 |

1586| `~/.claude/debug/`、`~/.claude/plans/`、`~/.claude/paste-cache/`、`~/.claude/image-cache/`、`~/.claude/session-env/`、`~/.claude/tasks/`、`~/.claude/shell-snapshots/`、`~/.claude/backups/` | 沒有面向使用者的內容 |1589| `~/.claude/debug/`、`~/.claude/plans/`、`~/.claude/paste-cache/`、`~/.claude/image-cache/`、`~/.claude/session-env/`、`~/.claude/tasks/`、`~/.claude/shell-snapshots/`、`~/.claude/backups/` | 沒有面向使用者的內容 |

1588 1591

cli-reference.md +3 −1

Details

124 124

125`--system-prompt` 和 `--system-prompt-file` 互斥。附加旗標可以與任一取代旗標組合。125`--system-prompt` 和 `--system-prompt-file` 互斥。附加旗標可以與任一取代旗標組合。

126 126

127對於大多數使用案例，請使用附加旗標。附加會保留 Claude Code 的內建功能，同時新增您的需求。僅當您需要對系統提示進行完全控制時，才使用取代旗標。127根據 Claude Code 的預設身份是否仍適合您的工作來選擇。當 Claude 應保持編碼助手身份並同時遵循您的額外規則時，請使用附加旗標：每次呼叫的指示、輸出格式或 `-p` 指令碼的領域內容。附加會保留預設工具指導、安全指示和編碼慣例，因此您只需提供不同的部分。當表面、身份或權限模型與 Claude Code 不同時，請使用取代旗標，例如管道中沒有人監看的非編碼代理程式。取代會移除整個預設提示，包括工具指導和安全指示，因此您需要負責您的工作仍然需要的任何內容。

128

129這些旗標僅適用於目前的呼叫。對於您可以在專案中切換和共享的持久人物，請使用 [output styles](/zh-TW/output-styles)。對於 Claude 應始終遵循的專案慣例，請使用 [CLAUDE.md](/zh-TW/memory)。[Agent SDK 系統提示指南](/zh-TW/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) 涵蓋了更深入的相同決策。

128 130

129## 另請參閱131## 另請參閱

130 132

commands.md +1 −0

Details

106| `/schedule [description]` | 建立、更新、列出或執行[例行工作](/zh-TW/routines)，在 Anthropic 管理的雲端基礎設施上執行。Claude 會以對話方式引導您完成設定。別名：`/routines` |106| `/schedule [description]` | 建立、更新、列出或執行[例行工作](/zh-TW/routines)，在 Anthropic 管理的雲端基礎設施上執行。Claude 會以對話方式引導您完成設定。別名：`/routines` |

107| `/scroll-speed` | 以互動方式調整滑鼠滾輪[捲動速度](/zh-TW/fullscreen#mouse-wheel-scrolling)，使用尺標，您可以在對話框開啟時捲動以預覽變更。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用，在 JetBrains IDE 終端機中不可用 |

108| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Bedrock 使用者也可以從登入螢幕訪問此精靈 |109| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Bedrock 使用者也可以從登入螢幕訪問此精靈 |

109| `/setup-vertex` | 通過互動式精靈配置 [Google Vertex AI](/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Vertex AI 使用者也可以從登入螢幕訪問此精靈 |110| `/setup-vertex` | 通過互動式精靈配置 [Google Vertex AI](/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Vertex AI 使用者也可以從登入螢幕訪問此精靈 |

data-usage.md +2 −2

Details

33* **否**：拒絕而不發送任何內容33* **否**：拒絕而不發送任何內容

34* **不再詢問**：拒絕並停止此後續提問在未來工作階段中出現34* **不再詢問**：拒絕並停止此後續提問在未來工作階段中出現

35 35

36除非您明確選擇**是**，否則不會上傳任何內容。具有[零資料保留](/zh-TW/zero-data-retention)的組織，或組織政策停用產品回饋的組織，永遠不會看到此後續提問。您對此調查的回應（包括評分提示後提交的工作階段文字記錄）不會影響您的資料訓練偏好設定，也不能用於訓練我們的 AI 模型。36除非您明確選擇**是**，否則不會上傳任何內容。具有[零資料保留](/zh-TW/zero-data-retention)的組織，或組織政策停用產品回饋的組織，或設定了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的組織，永遠不會看到此後續提問。您對此調查的回應（包括評分提示後提交的工作階段文字記錄）不會影響您的資料訓練偏好設定，也不能用於訓練我們的 AI 模型。

37 37

38若要停用這些調查，請設定 `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`。當設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，調查也會停用。若要控制頻率而不是停用，請在您的設定檔中設定 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 為 `0` 到 `1` 之間的機率。38若要停用這些調查，請設定 `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`。當設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，調查也會停用。具有[零資料保留](/zh-TW/zero-data-retention)的組織，或組織政策停用產品回饋的組織，或設定了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的組織，永遠不會看到此後續提問。阻止非必要流量但透過自己的 [OpenTelemetry 收集器](/zh-TW/monitoring-usage)捕獲調查回應的組織可以透過設定 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1` 選擇重新啟用調查。調查隨後只會將評分記錄到已設定的收集器。文字記錄共享後續提問和所有其他 Anthropic 相關的回饋流量保持停用。若要控制頻率而不是停用，請在您的設定檔中設定 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 為 `0` 到 `1` 之間的機率。

39 39

40### 資料保留40### 資料保留

41 41

env-vars.md +5 −2

Details

81| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [scheduled tasks](/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具變為不可用，任何已排程的任務停止觸發，包括已在工作階段中執行的任務 |81| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [scheduled tasks](/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具變為不可用，任何已排程的任務停止觸發，包括已在工作階段中執行的任務 |

82| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和 beta 工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現「Unexpected value(s) for the `anthropic-beta` header」或「Extra inputs are not permitted」之類的錯誤時，請使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）會保留。 |82| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和 beta 工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現「Unexpected value(s) for the `anthropic-beta` header」或「Extra inputs are not permitted」之類的錯誤時，請使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）會保留。 |

84| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查。若要改為設定樣本速率，請使用 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/zh-TW/data-usage#session-quality-surveys) |84| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇加入。若要改為設定樣本速率，請使用 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/zh-TW/data-usage#session-quality-surveys) |

86| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/zh-TW/settings#available-settings) 設定 |86| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/zh-TW/settings#available-settings) 設定 |

87| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Bedrock、Vertex 或 Foundry 上執行 |87| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Bedrock、Vertex 或 Foundry 上執行 |

96| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/zh-TW/model-config#adjust-effort-level) |96| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/zh-TW/model-config#adjust-effort-level) |

97| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |97| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |

98| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) 失效 |98| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) 失效 |

99| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry collector](/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料發送到 Anthropic。在設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品反饋政策優先 |

99| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。在 Bedrock 和 Vertex 上，按模型啟用，其中已部署的容器支援它。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Foundry 和 [gateway](/zh-TW/llm-gateway) 連線上預設關閉 |100| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。在 Bedrock 和 Vertex 上，按模型啟用，其中已部署的容器支援它。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Foundry 和 [gateway](/zh-TW/llm-gateway) 連線上預設關閉 |

100| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選 |101| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選 |

102| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | 設定為 `1` 以在 Claude Opus 4.7 上執行 [fast mode](/zh-TW/fast-mode) 而不是 Opus 4.6。設定此變數時，`/fast` 會切換到 Opus 4.7；沒有它，`/fast` 會繼續使用 Opus 4.6 |

101| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |103| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |

102| `CLAUDE_CODE_ENABLE_TASKS` | 設定為 `1` 以在非互動式模式（`-p` 旗標）中啟用任務追蹤系統。任務在互動式模式中預設為開啟。請參閱 [Task list](/zh-TW/interactive-mode#task-list) |104| `CLAUDE_CODE_ENABLE_TASKS` | 設定為 `1` 以在非互動式模式（`-p` 旗標）中啟用任務追蹤系統。任務在互動式模式中預設為開啟。請參閱 [Task list](/zh-TW/interactive-mode#task-list) |

103| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用 OpenTelemetry 資料收集以進行指標和日誌記錄。在配置 OTel 匯出器之前需要。請參閱 [Monitoring](/zh-TW/monitoring-usage) |105| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用 OpenTelemetry 資料收集以進行指標和日誌記錄。在配置 OTel 匯出器之前需要。請參閱 [Monitoring](/zh-TW/monitoring-usage) |

119| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值和上限因模型而異；請參閱 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值會減少在 [auto-compaction](/zh-TW/costs#reduce-token-usage) 觸發之前可用的有效上下文視窗。 |121| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值和上限因模型而異；請參閱 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值會減少在 [auto-compaction](/zh-TW/costs#reduce-token-usage) 觸發之前可用的有效上下文視窗。 |

124| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，限制代理回合的數量。相當於傳遞 [`--max-turns`](/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時會被拒絕並出現錯誤，而不是被視為無限制 |

124| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示。 |127| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示。 |

202| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用 |205| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用 |

203| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Bedrock](/zh-TW/amazon-bedrock)、[Vertex](/zh-TW/google-vertex-ai)、[Foundry](/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |206| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Bedrock](/zh-TW/amazon-bedrock)、[Vertex](/zh-TW/google-vertex-ai)、[Foundry](/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |

205| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search)。未設定：預設所有 MCP 工具延遲，但在 Vertex AI 上或當 `ANTHROPIC_BASE_URL` 指向非第一方主機時提前載入。值：`true`（始終延遲，包括代理和 Vertex AI）、`auto`（閾值模式：如果工具符合上下文的 10% 內則提前載入）、`auto:N`（自訂閾值，例如 `auto:5` 表示 5%）、`false`（提前載入全部） |208| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search)。未設定：預設所有 MCP 工具延遲，但在 Vertex AI 上或當 `ANTHROPIC_BASE_URL` 指向非第一方主機時提前載入。值：`true`（始終延遲並發送 beta 標頭，在 Vertex AI 或不支援 `tool_reference` 的代理上請求失敗）、`auto`（閾值模式：如果工具符合上下文的 10% 內則提前載入）、`auto:N`（自訂閾值，例如 `auto:5` 表示 5%）、`false`（提前載入全部） |

206| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值以在任何主要模型上重複過載錯誤後觸發回退至 [`--fallback-model`](/zh-TW/cli-reference#cli-flags)。預設情況下，僅 Opus 模型觸發回退 |209| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值以在任何主要模型上重複過載錯誤後觸發回退至 [`--fallback-model`](/zh-TW/cli-reference#cli-flags)。預設情況下，僅 Opus 模型觸發回退 |

fast-mode.md +51 −18

Details

4 4

5# 使用快速模式加快回應速度5# 使用快速模式加快回應速度

6 6

~~7> 在 Claude Code 中切換快速模式，以獲得更快的 Opus 4.6 回應。~~7> 在 Claude Code 中切換快速模式，以獲得更快的 Opus 回應。

8 8

9<Note>9<Note>

10 快速模式處於[研究預覽](#research-preview)階段。該功能、定價和可用性可能會根據反饋而改變。10 快速模式處於[研究預覽](#research-preview)階段。該功能、定價和可用性可能會根據反饋而改變。

11</Note>11</Note>

12 12

13快速模式是 Claude Opus 4.6 的高速配置，使模型速度提升 2.5 倍，但每個 token 的成本更高。當您需要速度進行互動式工作（如快速迭代或實時調試）時，使用 `/fast` 切換開啟，當成本比延遲更重要時，切換關閉。13快速模式是 Claude Opus 的高速配置，使模型速度提升 2.5 倍，但每個 token 的成本更高。當您需要速度進行互動式工作（如快速迭代或實時調試）時，使用 `/fast` 切換開啟，當成本比延遲更重要時，切換關閉。

14 14

15快速模式不是不同的模型。它使用相同的 Opus 4.6，但採用不同的 API 配置，優先考慮速度而非成本效率。您獲得相同的品質和功能，只是回應速度更快。15快速模式不是不同的模型。它使用 Claude Opus 搭配不同的 API 配置，優先考慮速度而非成本效率。您獲得相同的品質和功能，只是回應速度更快。快速模式在 Opus 4.6 和 Opus 4.7 上受支援。它在 Sonnet、Haiku 或其他模型上不可用。

16 16

17<Note>17<Note>

18 快速模式需要 Claude Code v2.1.36 或更新版本。使用 `claude --version` 檢查您的版本。18 快速模式需要 Claude Code v2.1.36 或更新版本。使用 `claude --version` 檢查您的版本。

21需要了解的事項：21需要了解的事項：

22 22

23* 使用 `/fast` 在 Claude Code CLI 中切換快速模式。也可在 Claude Code VS Code 擴充功能中透過 `/fast` 使用。23* 使用 `/fast` 在 Claude Code CLI 中切換快速模式。也可在 Claude Code VS Code 擴充功能中透過 `/fast` 使用。

~~24* Opus 4.6 快速模式定價起價為 \$30/150 MTok。快速模式在 2 月 16 日太平洋時間 11:59pm 之前以 50% 折扣提供給所有方案。~~24* 預設情況下，`/fast` 在 Opus 4.6 上執行。要改為在 Opus 4.7 上執行快速模式，請設定 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 環境變數。

25* 快速模式定價在 Opus 4.6 和 Opus 4.7 上都是 \$30/150 MTok。

25* 適用於訂閱方案（Pro/Max/Team/Enterprise）上的所有 Claude Code 使用者和 Claude Console。26* 適用於訂閱方案（Pro/Max/Team/Enterprise）上的所有 Claude Code 使用者和 Claude Console。

26* 對於訂閱方案（Pro/Max/Team/Enterprise）上的 Claude Code 使用者，快速模式僅透過額外使用提供，不包含在訂閱速率限制中。27* 對於訂閱方案（Pro/Max/Team/Enterprise）上的 Claude Code 使用者，快速模式僅透過額外使用提供，不包含在訂閱速率限制中。

27 28

28本頁涵蓋如何[切換快速模式](#toggle-fast-mode)、其[成本權衡](#understand-the-cost-tradeoff)、[何時使用](#decide-when-to-use-fast-mode)、[要求](#requirements)、[每個工作階段選擇加入](#require-per-session-opt-in)和[速率限制行為](#handle-rate-limits)。29本頁涵蓋如何[切換快速模式](#toggle-fast-mode)、[在 Opus 4.7 上使用快速模式](#use-fast-mode-on-opus-4-7)、[成本權衡](#understand-the-cost-tradeoff)、[何時使用](#decide-when-to-use-fast-mode)、[要求](#requirements)、[每個工作階段選擇加入](#require-per-session-opt-in)和[速率限制行為](#handle-rate-limits)。

29 30

30## 切換快速模式31## 切換快速模式

31 32

40 41

41當您啟用快速模式時：42當您啟用快速模式時：

42 43

~~43* 如果您使用不同的模型，Claude Code 會自動切換到 Opus 4.6~~44* 如果您使用不同的模型，Claude Code 會自動切換到快速模式模型：預設為 Opus 4.6，或在設定 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 時為 Opus 4.7。

44* 您會看到確認訊息："Fast mode ON"45* 您會看到確認訊息："Fast mode ON"

45* 快速模式啟用時，提示旁會出現一個小的 `↯` 圖示46* 快速模式啟用時，提示旁會出現一個小的 `↯` 圖示

46* 隨時再次執行 `/fast` 以檢查快速模式是否開啟或關閉47* 隨時再次執行 `/fast` 以檢查快速模式是否開啟或關閉

47 48

~~48當您再次使用 `/fast` 關閉快速模式時，您仍保持在 Opus 4.6 上。模型不會還原到您之前的模型。要切換到不同的模型，請使用 `/model`。~~49當您再次使用 `/fast` 關閉快速模式時，您仍保持在快速模式執行的相同 Opus 版本上。模型不會還原到您之前的模型。要切換到不同的模型，請使用 `/model`。

51## 在 Opus 4.7 上使用快速模式

53<Note>

54 Opus 4.7 上的快速模式需要 Claude Code v2.1.139 或更新版本。

55</Note>

57Claude Opus 4.7 的快速模式處於研究預覽階段。它以相同的 2.5 倍速度和與 Opus 4.6 快速模式相同的價格執行，沒有其他行為變更。

59<Note>

60 在 2026 年 5 月 14 日，Opus 4.7 成為預設快速模式模型。在此之前，透過設定 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1` 選擇加入。

61</Note>

63要選擇加入，在啟動 Claude Code 之前設定 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1`。設定該變數後，`/fast` 在 Opus 4.7 上執行。沒有它，`/fast` 繼續在 Opus 4.6 上執行。

65您可以將變數設定為 shell 匯出：

67```bash theme={null}

68export CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1

69```

71或在任何 Claude Code [設定檔案](/zh-TW/settings#settings-files)中，包括使用者、專案和受管設定，以限定選擇加入的範圍：

73```json theme={null}

74{

75 "env": {

76 "CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE": "1"

77 }

78}

79```

81Opus 4.6 的快速模式仍可與 Opus 4.7 並行使用。兩者共享相同的快速模式速率限制池：任一模型上的使用都會從相同的限制中扣除。

49 82

50## 了解成本權衡83## 了解成本權衡

51 84

~~52快速模式的每個 token 定價高於標準 Opus 4.6：~~85快速模式的每個 token 定價高於標準 Opus：

53 86

54| 模式 | 輸入 (MTok) | 輸出 (MTok) |87| 模式 | 輸入 (MTok) | 輸出 (MTok) |

~~55| ------------------------ | --------- | --------- |~~88| --------------- | --------- | --------- |

~~56| Opus 4.6 上的快速模式 (\<200K) | \$30 | \$150 |~~89| Opus 4.6 上的快速模式 | \$30 | \$150 |

~~57| Opus 4.6 上的快速模式 (>200K) | \$60 | \$225 |~~90| Opus 4.7 上的快速模式 | \$30 | \$150 |

58 91

~~59快速模式與 1M token 擴展上下文視窗相容。~~92快速模式定價在整個 1M token 上下文視窗中是固定的。

60 93

61當您在對話中途切換到快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。這比從一開始就啟用快速模式的成本更高。94當您在對話中途切換到快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。這比從一開始就啟用快速模式的成本更高。

62 95

90快速模式需要以下所有條件：123快速模式需要以下所有條件：

91 124

92* **第三方雲端提供商上不可用**：快速模式在 Amazon Bedrock、Google Vertex AI 或 Microsoft Azure Foundry 上不可用。快速模式可透過 Anthropic Console API 和使用額外使用的 Claude 訂閱方案取得。125* **第三方雲端提供商上不可用**：快速模式在 Amazon Bedrock、Google Vertex AI 或 Microsoft Azure Foundry 上不可用。快速模式可透過 Anthropic Console API 和使用額外使用的 Claude 訂閱方案取得。

93* **啟用額外使用**：您的帳戶必須啟用額外使用，這允許超出您方案包含使用量的計費。對於個人帳戶，在您的 [Console 計費設定](https://platform.claude.com/settings/organization/billing)中啟用此功能。對於 Teams 和 Enterprise，管理員必須為組織啟用額外使用。126* **啟用額外使用**：您的帳戶必須啟用額外使用，這允許超出您方案包含使用量的計費。對於個人帳戶，在您的 [Console 計費設定](https://platform.claude.com/settings/organization/billing)中啟用此功能。對於 Team 和 Enterprise，管理員必須為組織啟用額外使用。

94 127

95<Note>128<Note>

96 快速模式使用直接計費到額外使用，即使您的方案上還有剩餘使用量。這意味著快速模式 token 不計入您方案的包含使用量，並從第一個 token 開始按快速模式費率計費。129 快速模式使用直接計費到額外使用，即使您的方案上還有剩餘使用量。這意味著快速模式 token 不計入您方案的包含使用量，並從第一個 token 開始按快速模式費率計費。

97</Note>130</Note>

98 131

99* **Teams 和 Enterprise 的管理員啟用**：快速模式預設對 Teams 和 Enterprise 組織禁用。管理員必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。132* **Team 和 Enterprise 的管理員啟用**：快速模式預設對 Team 和 Enterprise 組織禁用。管理員必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。

100 133

101<Note>134<Note>

102 如果您的管理員尚未為您的組織啟用快速模式，`/fast` 命令將顯示「Fast mode has been disabled by your organization.」135 如果您的管理員尚未為您的組織啟用快速模式，`/fast` 命令將顯示「Fast mode has been disabled by your organization.」

107管理員可以在以下位置啟用快速模式：140管理員可以在以下位置啟用快速模式：

108 141

109* **Console**（API 客戶）：[Claude Code 偏好設定](https://platform.claude.com/claude-code/preferences)142* **Console**（API 客戶）：[Claude Code 偏好設定](https://platform.claude.com/claude-code/preferences)

110* **Claude AI**（Teams 和 Enterprise）：[管理員設定 > Claude Code](https://claude.ai/admin-settings/claude-code)143* **Claude AI**（Team 和 Enterprise）：[管理員設定 > Claude Code](https://claude.ai/admin-settings/claude-code)

111 144

112另一個完全禁用快速模式的選項是設定 `CLAUDE_CODE_DISABLE_FAST_MODE=1`。詳見[環境變數](/zh-TW/env-vars)。145另一個完全禁用快速模式的選項是設定 `CLAUDE_CODE_DISABLE_FAST_MODE=1`。詳見[環境變數](/zh-TW/env-vars)。

113 146

114### 要求每個工作階段選擇加入147### 要求每個工作階段選擇加入

115 148

116預設情況下，快速模式在工作階段之間保持：如果使用者啟用快速模式，它在未來工作階段中保持開啟。[Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 方案上的管理員可以透過在[受管設定](/zh-TW/settings#settings-files)或[伺服器受管設定](/zh-TW/server-managed-settings)中將 `fastModePerSessionOptIn` 設定為 `true` 來防止這種情況。這會導致每個工作階段以快速模式關閉開始，要求使用者使用 `/fast` 明確啟用它。149預設情況下，快速模式在工作階段之間保持：如果使用者啟用快速模式，它在未來工作階段中保持開啟。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 方案上的管理員可以透過在[受管設定](/zh-TW/settings#settings-files)或[伺服器受管設定](/zh-TW/server-managed-settings)中將 `fastModePerSessionOptIn` 設定為 `true` 來防止這種情況。這會導致每個工作階段以快速模式關閉開始，要求使用者使用 `/fast` 明確啟用它。

117 150

118```json theme={null}151```json theme={null}

119{152{

125 158

126## 處理速率限制159## 處理速率限制

127 160

128快速模式與標準 Opus 4.6 有不同的速率限制。當您達到快速模式速率限制或用完額外使用額度時：161快速模式與標準 Opus 有不同的速率限制。Opus 4.6 和 Opus 4.7 的快速模式共享相同的速率限制池：任一模型上的使用都會從相同的限制中扣除。當您達到快速模式速率限制或用完額外使用額度時：

129 162

1301. 快速模式自動回退到標準 Opus 4.61631. 快速模式自動回退到相同 Opus 版本上的標準速度

1312. `↯` 圖示變灰以指示冷卻1642. `↯` 圖示變灰以指示冷卻

1323. 您以標準速度和定價繼續工作1653. 您以標準速度和定價繼續工作

1334. 冷卻期過期時，快速模式自動重新啟用1664. 冷卻期過期時，快速模式自動重新啟用

fullscreen.md +2 −0

Details

93 93

94值 `3` 符合 `vim` 和類似應用程式中的預設值。該設定接受 1 到 20 的值。94值 `3` 符合 `vim` 和類似應用程式中的預設值。該設定接受 1 到 20 的值。

95 95

96若要以互動方式調整捲動速度，請執行 `/scroll-speed`。對話框顯示一個尺標，您可以在其開啟時捲動，以便您可以立即感受到變化。按 `←` 和 `→` 以調整，按 `r` 以重設為自動偵測的預設值，按 `Enter` 以儲存。該命令寫入與 `CLAUDE_CODE_SCROLL_SPEED` 環境變數設定相同的值，持久化到 `~/.claude/settings.json`。該命令在 JetBrains IDE 終端中不可用。

96### JetBrains IDE 終端中的捲動98### JetBrains IDE 終端中的捲動

97 99

98在 JetBrains IDE 終端中，Claude Code 應用其自己的捲動處理並忽略 `CLAUDE_CODE_SCROLL_SPEED`。終端以比其他模擬器高得多的速率傳送捲動事件，因此在其他地方調整的乘數會在此處超出。100在 JetBrains IDE 終端中，Claude Code 應用其自己的捲動處理並忽略 `CLAUDE_CODE_SCROLL_SPEED`。終端以比其他模擬器高得多的速率傳送捲動事件，因此在其他地方調整的乘數會在此處超出。

glossary.md +1 −1

Details

174 174

175### Output style175### Output style

176 176

177一個配置，修改 Claude 的系統提示以改變回應行為、語氣或格式。Output styles 關閉預設系統提示的軟體工程特定部分，與 [CLAUDE.md](#claude-md) 不同，後者作為系統提示後的使用者訊息傳遞。內建樣式包括 Default、Explanatory 和 Learning。177一個配置，修改 Claude 的系統提示以改變回應行為、語氣或格式。Output styles 關閉預設系統提示的軟體工程特定部分，與 [CLAUDE.md](#claude-md) 不同，後者作為系統提示後的使用者訊息傳遞。內建樣式包括 Default、Proactive、Explanatory 和 Learning。

178 178

179了解更多：[Output styles](/zh-TW/output-styles)179了解更多：[Output styles](/zh-TW/output-styles)

180 180

hooks.md +84 −21

Details

70 {70 {

71 "type": "command",71 "type": "command",

72 "if": "Bash(rm *)",72 "if": "Bash(rm *)",

~~73 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"~~73 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",

74 "args": []

74 }75 }

75 ]76 ]

76 }77 }

307除了 [通用欄位](#common-fields) 外，命令 hooks 還接受這些欄位：308除了 [通用欄位](#common-fields) 外，命令 hooks 還接受這些欄位：

308 309

309| 欄位 | 必需 | 描述 |310| 欄位 | 必需 | 描述 |

310| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |311| :------------ | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

311| `command` | 是 | 要執行的 shell 命令 |312| `command` | 是 | 要執行的 shell 命令。使用 `args` 時，要直接生成的可執行檔。請參閱 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |

313| `args` | 否 | 參數清單。存在時，`command` 被解析為可執行檔並直接使用 `args` 作為參數向量生成，不涉及 shell。請參閱 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |

312| `async` | 否 | 如果為 `true`，在背景執行而不阻止。請參閱 [在背景執行 hooks](#run-hooks-in-the-background) |314| `async` | 否 | 如果為 `true`，在背景執行而不阻止。請參閱 [在背景執行 hooks](#run-hooks-in-the-background) |

313| `asyncRewake` | 否 | 如果為 `true`，在背景執行並在退出代碼 2 時喚醒 Claude。暗示 `async`。Hook 的 stderr，或如果 stderr 為空則為 stdout，作為系統提醒顯示給 Claude，以便它可以對長時間執行的背景失敗做出反應 |315| `asyncRewake` | 否 | 如果為 `true`，在背景執行並在退出代碼 2 時喚醒 Claude。暗示 `async`。Hook 的 stderr，或如果 stderr 為空則為 stdout，作為系統提醒顯示給 Claude，以便它可以對長時間執行的背景失敗做出反應 |

314| `shell` | 否 | 用於此 hook 的 shell。接受 `"bash"`（預設）或 `"powershell"`。設定 `"powershell"` 在 Windows 上通過 PowerShell 執行命令。不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`，因為 hooks 直接生成 PowerShell |316| `shell` | 否 | 用於此 hook 的 shell。接受 `"bash"`（預設）或 `"powershell"`。設定 `"powershell"` 在 Windows 上通過 PowerShell 執行命令。不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`，因為 hooks 直接生成 PowerShell。設定 `args` 時被忽略 |

317

318<a id="exec-form-and-shell-form" />

319

320##### Exec 形式和 shell 形式

321

322當設定 `args` 時，命令 hook 以 exec 形式執行，當省略 `args` 時以 shell 形式執行。每當 hook 參考 [路徑佔位符](#reference-scripts-by-path) 時設定 `args`，因為每個元素作為一個參數傳遞，不進行引用。當您需要 shell 功能（如管道或 `&&`）時，或當兩個問題都不適用時，省略 `args`。

323

324**Exec 形式**在設定 `args` 時執行。Claude Code 在 `PATH` 上解析 `command` 作為可執行檔並直接使用 `args` 作為參數向量生成它。沒有 shell，因此每個 `args` 元素恰好是一個參數，完全按照編寫的方式，路徑佔位符如 `${CLAUDE_PLUGIN_ROOT}` 被替換為 `command` 和每個 `args` 元素中的純字串。特殊字元如撇號、`$` 和反引號逐字傳遞，因為沒有 shell 來解釋它們。任何平台上都不會發生 shell 標記化。

325

326**Shell 形式**在省略 `args` 時執行。`command` 字串被傳遞到 shell：macOS 和 Linux 上的 `sh -c`、Windows 上的 Git Bash，或未安裝 Git Bash 時的 PowerShell。設定 `shell` 欄位以明確選擇。Shell 標記化字串、展開變數並解釋管道、`&&`、重定向和 glob。

327

328<Note>

329 在 Windows 上，exec 形式需要 `command` 解析為真實可執行檔，如 `.exe`。npm、npx、eslint 和其他工具在 `node_modules/.bin` 中安裝的 `.cmd` 和 `.bat` 填充程式不是可執行檔，無法在沒有 shell 的情況下生成。要在 exec 形式中執行它們，直接使用 `node` 呼叫底層指令碼，例如 `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`。`node` 加上指令碼路徑模式在每個平台上都有效，因為 `node.exe` 是真實二進位檔。要按名稱執行 `.cmd` 或 `.bat` 填充程式，請使用 shell 形式。

330</Note>

331

332此範例執行與外掛程式一起打包的 Node 指令碼。Exec 形式將解析的指令碼路徑作為一個參數傳遞，不進行引用：

333

334```json theme={null}

335{

336 "type": "command",

337 "command": "node",

338 "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]

339}

340```

341

342等效的 shell 形式需要引用以處理包含空格或特殊字元的路徑：

343

344```json theme={null}

345{

346 "type": "command",

347 "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"

348}

349```

350

351兩種形式都支援相同的 [路徑佔位符](#reference-scripts-by-path)，並且都將它們作為環境變數 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA` 匯出到生成的程序，因此指令碼可以讀取 `process.env.CLAUDE_PLUGIN_ROOT`，無論它是如何啟動的。外掛程式 hooks 另外替換 `${user_config.*}` 值；請參閱 [使用者配置](/zh-TW/plugins-reference#user-configuration)。

352

353<Note>

354 在 exec 形式中，`command` 僅是可執行檔名稱或路徑。如果 `command` 是沒有路徑分隔符的裸名稱，並且與 `args` 一起包含空格，Claude Code 會記錄警告，因為生成將失敗：沒有名為 `node script.js` 的可執行檔。將額外的令牌移到 `args` 中。包含空格的絕對路徑，如 `C:\Program Files\nodejs\node.exe`，是單個有效的可執行檔，不會觸發警告。

355</Note>

315 356

316#### HTTP hook 欄位357#### HTTP hook 欄位

317 358

397| `prompt` | 是 | 要發送到模型的提示文字。使用 `$ARGUMENTS` 作為 hook 輸入 JSON 的佔位符 |438| `prompt` | 是 | 要發送到模型的提示文字。使用 `$ARGUMENTS` 作為 hook 輸入 JSON 的佔位符 |

398| `model` | 否 | 用於評估的模型。預設為快速模型 |439| `model` | 否 | 用於評估的模型。預設為快速模型 |

399 440

400所有匹配的 hooks 並行執行，相同的處理程式會自動去重。命令 hooks 按命令字串去重，HTTP hooks 按 URL 去重。處理程式在目前目錄中執行，使用 Claude Code 的環境。在遠端網路環境中，`$CLAUDE_CODE_REMOTE` 環境變數設定為 `"true"`，在本機 CLI 中未設定。441所有匹配的 hooks 並行執行，相同的處理程式會自動去重。命令 hooks 按命令字串和 `args` 去重，HTTP hooks 按 URL 去重。處理程式在目前目錄中執行，使用 Claude Code 的環境。在遠端網路環境中，`$CLAUDE_CODE_REMOTE` 環境變數設定為 `"true"`，在本機 CLI 中未設定。

401 442

402### 按路徑參考指令碼443### 按路徑參考指令碼

403 444

404使用環境變數按相對於專案或外掛程式根目錄的路徑參考 hook 指令碼，無論 hook 執行時的工作目錄如何：445使用這些佔位符按相對於專案或外掛程式根目錄的路徑參考 hook 指令碼，無論 hook 執行時的工作目錄如何：

405 446

406* `$CLAUDE_PROJECT_DIR`：專案根目錄。用引號括起來以處理包含空格的路徑。447* `${CLAUDE_PROJECT_DIR}`：專案根目錄。

407* `${CLAUDE_PLUGIN_ROOT}`：外掛程式的安裝目錄，用於與 [plugin](/zh-TW/plugins) 一起打包的指令碼。在每次外掛程式更新時變更。448* `${CLAUDE_PLUGIN_ROOT}`：外掛程式的安裝目錄，用於與 [plugin](/zh-TW/plugins) 一起打包的指令碼。在每次外掛程式更新時變更。

408* `${CLAUDE_PLUGIN_DATA}`：外掛程式的 [持久資料目錄](/zh-TW/plugins-reference#persistent-data-directory)，用於應該在外掛程式更新後保留的依賴項和狀態。449* `${CLAUDE_PLUGIN_DATA}`：外掛程式的 [持久資料目錄](/zh-TW/plugins-reference#persistent-data-directory)，用於應該在外掛程式更新後保留的依賴項和狀態。

409 450

451對於任何參考路徑佔位符的 hook，優先使用 [exec 形式](#exec-form-and-shell-form)。Exec 形式將每個 `args` 元素作為一個參數傳遞，不進行 shell 標記化，因此包含空格或特殊字元的路徑不需要引用。在 shell 形式中，用雙引號括起每個佔位符。

452

410<Tabs>453<Tabs>

411 <Tab title="專案指令碼">454 <Tab title="專案指令碼">

412 此範例使用 `$CLAUDE_PROJECT_DIR` 在任何 `Write` 或 `Edit` 工具呼叫後從專案的 `.claude/hooks/` 目錄執行樣式檢查器：455 此範例使用 `${CLAUDE_PROJECT_DIR}` 在任何 `Write` 或 `Edit` 工具呼叫後從專案的 `.claude/hooks/` 目錄執行樣式檢查器：

413 456

414 ```json theme={null}457 ```json theme={null}

415 {458 {

420 "hooks": [463 "hooks": [

421 {464 {

422 "type": "command",465 "type": "command",

423 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"466 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",

467 "args": []

424 }468 }

425 ]469 ]

426 }470 }

446 {490 {

447 "type": "command",491 "type": "command",

448 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",492 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",

493 "args": [],

449 "timeout": 30494 "timeout": 30

450 }495 }

451 ]496 ]

529使用 `--agent` 執行或在 subagent 內執行時，包括兩個額外欄位：574使用 `--agent` 執行或在 subagent 內執行時，包括兩個額外欄位：

530 575

531| 欄位 | 描述 |576| 欄位 | 描述 |

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

534| `agent_type` | 代理名稱（例如 `"Explore"` 或 `"security-reviewer"`）。當工作階段使用 `--agent` 或 hook 在 subagent 內觸發時出現。對於 subagents，subagent 的類型優先於工作階段的 `--agent` 值。 |579| `agent_type` | 代理名稱（例如 `"Explore"` 或 `"security-reviewer"`）。當工作階段使用 `--agent` 或 hook 在 subagent 內觸發時出現。對於 subagents，subagent 的類型優先於工作階段的 `--agent` 值。對於 [自訂 subagents](/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。 |

580

581只有 [`SessionStart`](#sessionstart) hooks 接收 `model` 欄位。沒有 `$CLAUDE_MODEL` 環境變數。Hook 程序繼承父環境，因此如果您在 shell 中設定它，它可以讀取 `$ANTHROPIC_MODEL`，但當您在工作階段期間使用 `/model` 切換模型時，該值不會改變。

535 582

536例如，Bash 命令的 `PreToolUse` hook 在 stdin 上接收此內容：583例如，Bash 命令的 `PreToolUse` hook 在 stdin 上接收此內容：

537 584

1153| `questions` | 陣列 | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈現的問題，每個都有 `question` 字串、簡短 `header`、`options` 陣列和可選的 `multiSelect` 標誌 |1200| `questions` | 陣列 | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈現的問題，每個都有 `question` 字串、簡短 `header`、`options` 陣列和可選的 `multiSelect` 標誌 |

1154| `answers` | 物件 | `{"Which framework?": "React"}` | 可選。將問題文字對應到選定的選項標籤。多選答案用逗號連接標籤。Claude 不設定此欄位；通過 `updatedInput` 提供它以以程式方式回答 |1201| `answers` | 物件 | `{"Which framework?": "React"}` | 可選。將問題文字對應到選定的選項標籤。多選答案用逗號連接標籤。Claude 不設定此欄位；通過 `updatedInput` 提供它以以程式方式回答 |

1155 1202

1203##### ExitPlanMode

1204

1205呈現一個計劃並要求使用者在 Claude 離開 [plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在呼叫工具之前將計劃寫入磁碟上的檔案，因此模型的字面 `tool_input` 僅攜帶 `allowedPrompts`。Claude Code 在將輸入傳遞給 hooks 之前注入計劃內容和檔案路徑。

1206

1207| 欄位 | 類型 | 範例 | 描述 |

1208| :--------------- | :- | :------------------------------------------ | :------------------------------------------------------- |

1211| `allowedPrompts` | 陣列 | `[{"tool": "Bash", "prompt": "run tests"}]` | 可選。Claude 要求實施計劃的基於提示的權限，每個都有 `tool` 名稱和描述操作類別的 `prompt` |

1212

1213在 `PostToolUse` 中，`tool_response` 是一個物件，其中包含 `plan` 和 `filePath` 欄位，保存批准的計劃，加上內部狀態標誌。讀取 `tool_response.plan` 以獲取計劃內容，而不是從磁碟重新讀取檔案。

1214

1156#### PreToolUse 決定控制1215#### PreToolUse 決定控制

1157 1216

1158`PreToolUse` hooks 可以控制工具呼叫是否進行。與使用頂層 `decision` 欄位的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 物件內返回其決定。這提供了更豐富的控制：四個結果（允許、拒絕、詢問或延遲）加上在執行前修改工具輸入的能力。1217`PreToolUse` hooks 可以控制工具呼叫是否進行。與使用頂層 `decision` 欄位的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 物件內返回其決定。這提供了更豐富的控制：四個結果（允許、拒絕、詢問或延遲）加上在執行前修改工具輸入的能力。

1599 1658

1600### SubagentStart1659### SubagentStart

1601 1660

1602當通過 Agent 工具生成 Claude Code subagent 時執行。支援匹配器以按代理類型名稱篩選（內建代理，如 `general-purpose`、`Explore`、`Plan` 或來自 `.claude/agents/` 的自訂代理名稱）。1661當通過 Agent 工具生成 Claude Code subagent 時執行。支援匹配器以按代理類型名稱篩選。對於內建代理，這是代理名稱，如 `general-purpose`、`Explore` 或 `Plan`。對於 [自訂 subagents](/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。

1603 1662

1604#### SubagentStart 輸入1663#### SubagentStart 輸入

1605 1664

1654}1713}

1655```1714```

1656 1715

1657SubagentStop hooks 使用與 [Stop hooks](#stop-decision-control) 相同的決定控制格式。1716SubagentStop hooks 使用與 [Stop hooks](#stop-decision-control) 相同的決定控制格式。它們不支援 `additionalContext`。返回 `decision: "block"` 與 `reason` 會保持 subagent 執行並將 `reason` 作為其下一個指令傳遞給 subagent。要在 subagent 返回後將上下文注入到父工作階段，請改用 `Agent` 工具上的 [`PostToolUse`](#posttooluse) hook。

1658 1717

1659### TaskCreated1718### TaskCreated

1660 1719

1908 "hooks": [1967 "hooks": [

1909 {1968 {

1910 "type": "command",1969 "type": "command",

1911 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/audit-config-change.sh"1970 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",

1971 "args": []

1912 }1972 }

1913 ]1973 ]

1914 }1974 }

2397```2457```

2398 2458

2399| 欄位 | 必需 | 描述 |2459| 欄位 | 必需 | 描述 |

2400| :-------- | :- | :------------------------------------------------------------------------------------- |2460| :---------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------- |

2401| `type` | 是 | 必須為 `"prompt"` |2461| `type` | 是 | 必須為 `"prompt"` |

2402| `prompt` | 是 | 要發送到 LLM 的提示文字。使用 `$ARGUMENTS` 作為 hook 輸入 JSON 的佔位符。如果 `$ARGUMENTS` 不存在，輸入 JSON 會附加到提示 |2462| `prompt` | 是 | 要發送到 LLM 的提示文字。使用 `$ARGUMENTS` 作為 hook 輸入 JSON 的佔位符。如果 `$ARGUMENTS` 不存在，輸入 JSON 會附加到提示 |

2403| `model` | 否 | 用於評估的模型。預設為快速模型 |2463| `model` | 否 | 用於評估的模型。預設為快速模型 |

2404| `timeout` | 否 | 逾時（秒）。預設值：30 |2464| `timeout` | 否 | 逾時（秒）。預設值：30 |

2465| `continueOnBlock` | 否 | 當提示返回 `ok: false` 時，將原因反饋給 Claude 並繼續轉換而不是停止。預設值：`false`。在結果 `decision: "block"` 上實現為 `continue: true`。請參閱[回應架構](#response-schema)以了解每個事件的行為 |

2405 2466

2406### 回應架構2467### 回應架構

2407 2468

2415```2476```

2416 2477

2417| 欄位 | 描述 |2478| 欄位 | 描述 |

2418| :------- | :----------------------------------- |2479| :------- | :------------------------------------------------------ |

2419| `ok` | `true` 允許操作，`false` 防止它。請參閱下面的每個事件行為 |2480| `ok` | `true` 允許操作。`false` 產生 `decision: "block"`。請參閱下面的每個事件行為 |

2421 2482

2422`ok: false` 時發生的情況取決於事件：2483`ok: false` 時發生的情況取決於事件：

2423 2484

2424* `Stop` 和 `SubagentStop`：原因被反饋給 Claude 作為其下一個指令，轉換繼續2485* `Stop` 和 `SubagentStop`：原因被反饋給 Claude 作為其下一個指令，轉換繼續

2425* `PreToolUse`：工具呼叫被拒絕，原因作為工具錯誤返回給 Claude，相當於命令 hook 的 `permissionDecision: "deny"`2486* `PreToolUse`：工具呼叫被拒絕，原因作為工具錯誤返回給 Claude，相當於命令 hook 的 `permissionDecision: "deny"`

2426* `PostToolUse`、`PostToolBatch`、`UserPromptSubmit` 和 `UserPromptExpansion`：轉換結束，原因在聊天中顯示為警告行，相當於從命令 hook 返回 `"continue": false`2487* `PostToolUse`：預設情況下轉換結束，原因在聊天中顯示為警告行。設定 `continueOnBlock: true` 以將原因反饋給 Claude 並繼續轉換

2488* `PostToolBatch`、`UserPromptSubmit` 和 `UserPromptExpansion`：轉換結束，原因顯示為警告行。這些事件在 `decision: "block"` 上結束轉換，無論 `continue` 如何

2427* `PostToolUseFailure`、`TaskCreated` 和 `TaskCompleted`：原因作為工具錯誤返回給 Claude，類似於 `PreToolUse`2489* `PostToolUseFailure`、`TaskCreated` 和 `TaskCompleted`：原因作為工具錯誤返回給 Claude，類似於 `PreToolUse`

2428* `PermissionRequest`：`ok: false` 沒有效果。要從 hook 拒絕批准，請使用[命令 hook](#command-hook-fields)返回 `hookSpecificOutput.decision.behavior: "deny"`2490* `PermissionRequest`：`ok: false` 沒有效果。要從 hook 拒絕批准，請使用[命令 hook](#command-hook-fields)返回 `hookSpecificOutput.decision.behavior: "deny"`

2429 2491

2582 "hooks": [2644 "hooks": [

2583 {2645 {

2584 "type": "command",2646 "type": "command",

2585 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",2647 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",

2648 "args": [],

2586 "async": true,2649 "async": true,

2587 "timeout": 3002650 "timeout": 300

2588 }2651 }

2619* **驗證和清理輸入**：永遠不要盲目信任輸入資料2682* **驗證和清理輸入**：永遠不要盲目信任輸入資料

2620* **始終引用 shell 變數**：使用 `"$VAR"` 而不是 `$VAR`2683* **始終引用 shell 變數**：使用 `"$VAR"` 而不是 `$VAR`

2621* **阻止路徑遍歷**：檢查檔案路徑中的 `..`2684* **阻止路徑遍歷**：檢查檔案路徑中的 `..`

2622* **使用絕對路徑**：為指令碼指定完整路徑，使用 `"$CLAUDE_PROJECT_DIR"` 作為專案根目錄2685* **使用絕對路徑**：為指令碼指定完整路徑。在 exec 形式中，使用 `${CLAUDE_PROJECT_DIR}` 且路徑不需要引用。在 shell 形式中，將其包裝在雙引號中

2623* **跳過敏感檔案**：避免 `.env`、`.git/`、金鑰等2686* **跳過敏感檔案**：避免 `.env`、`.git/`、金鑰等

2624 2687

2625## Windows PowerShell 工具2688## Windows PowerShell 工具

hooks-guide.md +2 −2

Details

895 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh895 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh

896 echo $? # 檢查退出代碼896 echo $? # 檢查退出代碼

897 ```897 ```

898* 如果您看到「command not found」，使用絕對路徑或 `$CLAUDE_PROJECT_DIR` 來參考指令898* 如果您看到「command not found」，使用絕對路徑或 `${CLAUDE_PROJECT_DIR}` 來參考指令。為了完全避免 shell 引用，添加 `"args": []` 以切換到 [exec 形式](/zh-TW/hooks#exec-form-and-shell-form)，它直接生成指令而不使用 shell

899* 如果您看到「jq: command not found」，安裝 `jq` 或使用 Python/Node.js 進行 JSON 解析899* 如果您看到「jq: command not found」，安裝 `jq` 或使用 Python/Node.js 進行 JSON 解析

900* 如果指令根本沒有執行，使其可執行：`chmod +x ./my-hook.sh`900* 如果指令根本沒有執行，使其可執行：`chmod +x ./my-hook.sh`

901 901

926 926

927Claude Code 顯示 JSON 解析錯誤，即使您的 hook 指令輸出有效的 JSON。927Claude Code 顯示 JSON 解析錯誤，即使您的 hook 指令輸出有效的 JSON。

928 928

929當 Claude Code 執行 hook 時，它生成一個 shell，該 shell 來源您的設定檔（`~/.zshrc` 或 `~/.bashrc`）。如果您的設定檔包含無條件的 `echo` 陳述式，該輸出會被前置到您的 hook 的 JSON：929當 Claude Code 執行 shell 形式的命令 hook（沒有 `args` 的）時，它在 macOS 和 Linux 上生成 `sh -c`，或在 Windows 上生成 Git Bash。此 shell 是非互動式的，但 Git Bash 和某些配置（例如 `BASH_ENV` 指向 `~/.bashrc`）仍然會來源您的設定檔。如果該設定檔包含無條件的 `echo` 陳述式，輸出會被前置到您的 hook 的 JSON：

930 930

931```text theme={null}931```text theme={null}

932Shell ready on arm64932Shell ready on arm64

interactive-mode.md +5 −2

Details

9## 鍵盤快捷鍵9## 鍵盤快捷鍵

10 10

11<Note>11<Note>

~~12 鍵盤快捷鍵可能因平台和終端而異。按 `?` 查看您環境中可用的快捷鍵。~~12 鍵盤快捷鍵可能因平台和終端而異。在[全螢幕渲染](/zh-TW/fullscreen)中，在文字記錄檢視器中按 `?` 以查看可用的快捷鍵。

13 13

14 **macOS 使用者**：Option/Alt 鍵快捷鍵（`Alt+B`、`Alt+F`、`Alt+Y`、`Alt+M`、`Alt+P`）需要在終端中將 Option 配置為 Meta：14 **macOS 使用者**：Option/Alt 鍵快捷鍵（`Alt+B`、`Alt+F`、`Alt+Y`、`Alt+M`、`Alt+P`）需要在終端中將 Option 配置為 Meta：

15 15

39| `Esc` | 中斷 Claude | 停止目前回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作 |

86 87

87### 文字記錄檢視器88### 文字記錄檢視器

88 89

~~89當文字記錄檢視器開啟時（使用 `Ctrl+O` 切換），這些快捷鍵可用。`Ctrl+E` 可以透過 [`transcript:toggleShowAll`](/zh-TW/keybindings) 重新繫結。~~90當文字記錄檢視器開啟時（使用 `Ctrl+O` 切換），這些快捷鍵可用。在[全螢幕渲染](/zh-TW/fullscreen)中，按 `?` 以在檢視器內顯示完整的快捷鍵參考面板。`Ctrl+E` 可以透過 [`transcript:toggleShowAll`](/zh-TW/keybindings) 重新繫結。

90 91

91| 快捷鍵 | 說明 |92| 快捷鍵 | 說明 |

92| :----------------- | :---------------------------------------------------------------------------------------------------------------- |93| :----------------- | :---------------------------------------------------------------------------------------------------------------- |

94| `?` | 切換鍵盤快捷鍵說明面板。需要[全螢幕渲染](/zh-TW/fullscreen) |

95| `{` / `}` | 跳至上一個或下一個使用者提示，類似 vim 段落動作。需要[全螢幕渲染](/zh-TW/fullscreen) |

93| `Ctrl+E` | 切換顯示所有內容 |96| `Ctrl+E` | 切換顯示所有內容 |

94| `[` | 將完整對話寫入終端的原生滾動回溯，以便 `Cmd+F`、tmux 複製模式和其他原生工具可以搜尋它。需要[全螢幕渲染](/zh-TW/fullscreen#search-and-review-the-conversation) |97| `[` | 將完整對話寫入終端的原生滾動回溯，以便 `Cmd+F`、tmux 複製模式和其他原生工具可以搜尋它。需要[全螢幕渲染](/zh-TW/fullscreen#search-and-review-the-conversation) |

95| `v` | 將對話寫入臨時檔案並在 `$VISUAL` 或 `$EDITOR` 中開啟它。需要[全螢幕渲染](/zh-TW/fullscreen) |98| `v` | 將對話寫入臨時檔案並在 `$VISUAL` 或 `$EDITOR` 中開啟它。需要[全螢幕渲染](/zh-TW/fullscreen) |

llm-gateway.md +5 −1

Details

42Claude Code 在每個 API 請求上包含以下標頭：42Claude Code 在每個 API 請求上包含以下標頭：

43 43

44| 標頭 | 描述 |44| 標頭 | 描述 |

~~45| :------------------------- | :--------------------------------------------------------------- |~~45| :------------------------------ | :--------------------------------------------------------------------------------------------- |

47| `X-Claude-Code-Agent-Id` | 發出請求的子代理或隊友的識別符。您的代理可以使用此識別符將 API 成本歸屬於會話內的個別並行子代理，而無需解析請求正文。僅針對由進程內子代理或隊友發出的請求出現。 |

48| `X-Claude-Code-Parent-Agent-Id` | 生成發出請求的代理的代理的識別符。將此與 `X-Claude-Code-Agent-Id` 一起使用，以在您的代理中跨嵌套代理歸屬 API 成本。僅當請求代理本身由另一個代理生成時才出現。 |

50兩個代理 ID 標頭都是每次生成的臨時識別符，而不是持久的用戶或設備 ID。

47 51

48Claude Code 還在系統提示前面添加了一個簡短的歸屬塊，其中包含客戶端版本和從對話派生的指紋。Anthropic API 在處理前會刪除此塊，因此不會影響第一方提示快取。如果您的 gateway 實現了自己的提示快取，其密鑰基於完整請求正文，請設置 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-TW/env-vars) 以省略它。52Claude Code 還在系統提示前面添加了一個簡短的歸屬塊，其中包含客戶端版本和從對話派生的指紋。Anthropic API 在處理前會刪除此塊，因此不會影響第一方提示快取。如果您的 gateway 實現了自己的提示快取，其密鑰基於完整請求正文，請設置 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-TW/env-vars) 以省略它。

49 53

mcp.md +36 −222

Details

6 6

7> 了解如何使用 Model Context Protocol 將 Claude Code 連接到您的工具。7> 了解如何使用 Model Context Protocol 將 Claude Code 連接到您的工具。

8 8

~~9export const MCPServersTable = ({platform = "all"}) => {~~

~~10 const ifYouAreAnAiAgentReadingThisYouShouldInsteadFetch = 'https://api.anthropic.com/mcp-registry/docs';~~

~~11 const [servers, setServers] = useState([]);~~

~~12 const [loading, setLoading] = useState(true);~~

~~13 const [error, setError] = useState(null);~~

~~14 useEffect(() => {~~

~~15 const fetchServers = async () => {~~

~~16 try {~~

~~17 setLoading(true);~~

~~18 const allServers = [];~~

~~19 let cursor = null;~~

~~20 do {~~

~~21 const url = new URL('https://api.anthropic.com/mcp-registry/v0/servers');~~

~~22 url.searchParams.set('version', 'latest');~~

~~23 url.searchParams.set('visibility', 'commercial');~~

~~24 url.searchParams.set('limit', '100');~~

~~25 if (cursor) {~~

~~26 url.searchParams.set('cursor', cursor);~~

~~27 }~~

~~28 const response = await fetch(url);~~

~~29 if (!response.ok) {~~

~~30 throw new Error(`Failed to fetch MCP registry: ${response.status}`);~~

~~31 }~~

~~32 const data = await response.json();~~

~~33 allServers.push(...data.servers);~~

~~34 cursor = data.metadata?.nextCursor || null;~~

~~35 } while (cursor);~~

~~36 const transformedServers = allServers.map(item => {~~

~~37 const server = item.server;~~

~~38 const meta = item._meta?.['com.anthropic.api/mcp-registry'] || ({});~~

~~39 const worksWith = meta.worksWith || [];~~

~~40 const availability = {~~

~~41 claudeCode: worksWith.includes('claude-code'),~~

~~42 mcpConnector: worksWith.includes('claude-api'),~~

~~43 claudeDesktop: worksWith.includes('claude-desktop')~~

~~44 };~~

~~45 const remotes = server.remotes || [];~~

~~46 const httpRemote = remotes.find(r => r.type === 'streamable-http');~~

~~47 const sseRemote = remotes.find(r => r.type === 'sse');~~

~~48 const preferredRemote = httpRemote || sseRemote;~~

~~49 const remoteUrl = preferredRemote?.url || meta.url;~~

~~50 const remoteType = preferredRemote?.type;~~

~~51 const isTemplatedUrl = remoteUrl?.includes('{');~~

~~52 let setupUrl;~~

~~53 if (isTemplatedUrl && meta.requiredFields) {~~

~~54 const urlField = meta.requiredFields.find(f => f.field === 'url');~~

~~55 setupUrl = urlField?.sourceUrl || meta.documentation;~~

~~56 }~~

~~57 const urls = {};~~

~~58 if (!isTemplatedUrl) {~~

~~59 if (remoteType === 'streamable-http') {~~

~~60 urls.http = remoteUrl;~~

~~61 } else if (remoteType === 'sse') {~~

~~62 urls.sse = remoteUrl;~~

~~63 }~~

~~64 }~~

~~65 let envVars = [];~~

~~66 if (server.packages && server.packages.length > 0) {~~

~~67 const npmPackage = server.packages.find(p => p.registryType === 'npm');~~

~~68 if (npmPackage) {~~

~~69 urls.stdio = `npx -y ${npmPackage.identifier}`;~~

~~70 if (npmPackage.environmentVariables) {~~

~~71 envVars = npmPackage.environmentVariables;~~

~~72 }~~

~~73 }~~

~~74 }~~

~~75 return {~~

~~76 name: meta.displayName || server.title || server.name,~~

~~77 description: meta.oneLiner || server.description,~~

~~78 documentation: meta.documentation,~~

~~79 urls: urls,~~

~~80 envVars: envVars,~~

~~81 availability: availability,~~

~~82 customCommands: meta.claudeCodeCopyText ? {~~

~~83 claudeCode: meta.claudeCodeCopyText~~

~~84 } : undefined,~~

~~85 setupUrl: setupUrl~~

~~86 };~~

~~87 });~~

~~88 setServers(transformedServers);~~

~~89 setError(null);~~

~~90 } catch (err) {~~

~~91 setError(err.message);~~

~~92 console.error('Error fetching MCP registry:', err);~~

~~93 } finally {~~

~~94 setLoading(false);~~

~~95 }~~

~~96 };~~

~~97 fetchServers();~~

~~98 }, []);~~

~~99 const generateClaudeCodeCommand = server => {~~

100 if (server.customCommands && server.customCommands.claudeCode) {

101 return server.customCommands.claudeCode.replace('--transport streamable-http', '--transport http');

102 }

103 const serverSlug = server.name.toLowerCase().replace(/[^a-z0-9]/g, '-');

104 if (server.urls.http) {

105 return `claude mcp add ${serverSlug} --transport http ${server.urls.http}`;

106 }

107 if (server.urls.sse) {

108 return `claude mcp add ${serverSlug} --transport sse ${server.urls.sse}`;

109 }

110 if (server.urls.stdio) {

111 const envFlags = server.envVars && server.envVars.length > 0 ? server.envVars.map(v => `--env ${v.name}=YOUR_${v.name}`).join(' ') : '';

112 const baseCommand = `claude mcp add ${serverSlug} --transport stdio`;

113 return envFlags ? `${baseCommand} ${envFlags} -- ${server.urls.stdio}` : `${baseCommand} -- ${server.urls.stdio}`;

114 }

115 return null;

116 };

117 if (loading) {

118 return <div>Loading MCP servers...</div>;

119 }

120 if (error) {

121 return <div>Error loading MCP servers: {error}</div>;

122 }

123 const filteredServers = servers.filter(server => {

124 if (platform === "claudeCode") {

125 return server.availability.claudeCode;

126 } else if (platform === "mcpConnector") {

127 return server.availability.mcpConnector;

128 } else if (platform === "claudeDesktop") {

129 return server.availability.claudeDesktop;

130 } else if (platform === "all") {

131 return true;

132 } else {

133 throw new Error(`Unknown platform: ${platform}`);

134 }

135 });

136 return <>

137 <style jsx>{`

138 .cards-container {

139 display: grid;

140 gap: 1rem;

141 margin-bottom: 2rem;

142 }

143 .server-card {

144 border: 1px solid var(--border-color, #e5e7eb);

145 border-radius: 6px;

146 padding: 1rem;

147 }

148 .command-row {

149 display: flex;

150 align-items: center;

151 gap: 0.25rem;

152 }

153 .command-row code {

154 font-size: 0.75rem;

155 overflow-x: auto;

156 }

157 `}</style>

~~158~~

159 <div className="cards-container">

160 {filteredServers.map(server => {

161 const claudeCodeCommand = generateClaudeCodeCommand(server);

162 const mcpUrl = server.urls.http || server.urls.sse;

163 const commandToShow = platform === "claudeCode" ? claudeCodeCommand : mcpUrl;

164 return <div key={server.name} className="server-card">

165 <div>

166 {server.documentation ? <a href={server.documentation}>

167 <strong>{server.name}</strong>

168 </a> : <strong>{server.name}</strong>}

169 </div>

~~170~~

171 <p style={{

172 margin: '0.5rem 0',

173 fontSize: '0.9rem'

174 }}>

175 {server.description}

176 </p>

~~177~~

178 {server.setupUrl && <p style={{

179 margin: '0.25rem 0',

180 fontSize: '0.8rem',

181 fontStyle: 'italic',

182 opacity: 0.7

183 }}>

184 Requires user-specific URL.{' '}

185 <a href={server.setupUrl} style={{

186 textDecoration: 'underline'

187 }}>

188 Get your URL here

189 </a>.

190 </p>}

~~191~~

192 {commandToShow && !server.setupUrl && <>

193 <p style={{

194 display: 'block',

195 fontSize: '0.75rem',

196 fontWeight: 500,

197 minWidth: 'fit-content',

198 marginTop: '0.5rem',

199 marginBottom: 0

200 }}>

201 {platform === "claudeCode" ? "Command" : "URL"}

202 </p>

203 <div className="command-row">

204 <code>

205 {commandToShow}

206 </code>

207 </div>

208 </>}

209 </div>;

210 })}

211 </div>

212 </>;

213};

~~214~~

215Claude Code 可以透過 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 連接到數百個外部工具和資料來源，這是一個開源標準，用於 AI 工具整合。MCP servers 讓 Claude Code 能夠存取您的工具、資料庫和 API。9Claude Code 可以透過 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 連接到數百個外部工具和資料來源，這是一個開源標準，用於 AI 工具整合。MCP servers 讓 Claude Code 能夠存取您的工具、資料庫和 API。

216 10

217當您發現自己從另一個工具（例如問題追蹤器或監控儀表板）複製資料到聊天中時，請連接一個 server。連接後，Claude 可以直接讀取和操作該系統，而不是根據您貼上的內容進行工作。11當您發現自己從另一個工具（例如問題追蹤器或監控儀表板）複製資料到聊天中時，請連接一個 server。連接後，Claude 可以直接讀取和操作該系統，而不是根據您貼上的內容進行工作。

227* **自動化工作流程**："建立 Gmail 草稿，邀請這 10 個使用者參加關於新功能的回饋會議。"21* **自動化工作流程**："建立 Gmail 草稿，邀請這 10 個使用者參加關於新功能的回饋會議。"

228* **回應外部事件**：MCP server 也可以充當 [channel](/zh-TW/channels)，將訊息推送到您的 session 中，因此當您不在時，Claude 可以回應 Telegram 訊息、Discord 聊天或 webhook 事件。22* **回應外部事件**：MCP server 也可以充當 [channel](/zh-TW/channels)，將訊息推送到您的 session 中，因此當您不在時，Claude 可以回應 Telegram 訊息、Discord 聊天或 webhook 事件。

229 23

230## 熱門 MCP servers24## 尋找並建立 MCP servers

231 25

232以下是一些您可以連接到 Claude Code 的常用 MCP servers：26在 [Anthropic Directory](https://claude.ai/directory) 中瀏覽已審核的連接器。Directory 連接器使用與 Claude Code 相同的 MCP 基礎設施，因此您可以使用 `claude mcp add` 新增任何列在其中的遠端伺服器。

233 27

234<Warning>28<Warning>

235 使用第三方 MCP servers 需自行承擔風險 - Anthropic 尚未驗證29 在連接伺服器之前，請驗證您信任每個伺服器。取得外部內容的伺服器可能會使您面臨[提示注入風險](/zh-TW/security#protect-against-prompt-injection)。

236 所有這些 servers 的正確性或安全性。

237 請確保您信任要安裝的 MCP servers。

238 使用可能會取得不受信任內容的 MCP servers 時要特別小心，

239 因為這些可能會使您面臨提示注入風險。

240</Warning>30</Warning>

241 31

242<MCPServersTable platform="claudeCode" />32若要建立您自己的伺服器，請參閱 [MCP server 指南](https://modelcontextprotocol.io/docs/develop/build-server) 以了解協議基礎知識，以及 [Claude 連接器建立文件](https://claude.com/docs/connectors/building) 以了解身份驗證、測試和 Directory 提交。

243 33

244<Note>34您也可以使用官方的 [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) 讓 Claude 為您建立伺服器。

245 **需要特定的整合？** [在 GitHub 上找到數百個更多 MCP servers](https://github.com/modelcontextprotocol/servers)，或使用 [MCP SDK](https://modelcontextprotocol.io/quickstart/server) 建立您自己的。35

246</Note>36<Steps>

37 <Step title="安裝 plugin">

38 在 Claude Code 工作階段中，執行：

40 ```

41 /plugin install mcp-server-dev@claude-plugins-official

42 ```

44 然後執行 `/reload-plugins` 以在目前工作階段中啟用它。

45 </Step>

47 <Step title="執行建立 skill">

48 ```

49 /mcp-server-dev:build-mcp-server

50 ```

52 Claude 會詢問您的使用案例，並建立遠端 HTTP 或本機 stdio 伺服器。

53 </Step>

54</Steps>

247 55

248## 安裝 MCP servers56## 安裝 MCP servers

249 57

289 97

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

291 99

100Claude Code 在生成的 server 環境中設定 `CLAUDE_PROJECT_DIR`，以指向專案根目錄，因此您的 server 可以解析專案相對路徑，而無需依賴工作目錄。這與 hooks 在其 `CLAUDE_PROJECT_DIR` 變數中接收的目錄相同。從您的 server 程序內部讀取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。您的 server 也可以呼叫 MCP `roots/list` 請求，該請求會傳回啟動 Claude Code 的目錄。

101

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

103

292```bash theme={null}104```bash theme={null}

293# 基本語法105# 基本語法

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

406**Plugin MCP 功能**：218**Plugin MCP 功能**：

407 219

408* **自動生命週期**：在 session 啟動時，已啟用 plugins 的 servers 會自動連接。如果您在 session 期間啟用或停用 plugin，請執行 `/reload-plugins` 以連接或斷開其 MCP servers220* **自動生命週期**：在 session 啟動時，已啟用 plugins 的 servers 會自動連接。如果您在 session 期間啟用或停用 plugin，請執行 `/reload-plugins` 以連接或斷開其 MCP servers

409* **環境變數**：使用 `${CLAUDE_PLUGIN_ROOT}` 表示 plugin 根目錄中的捆綁 plugin 檔案，以及 `${CLAUDE_PLUGIN_DATA}` 表示 [persistent state](/zh-TW/plugins-reference#persistent-data-directory) 在 plugin 更新後仍然存在221* **環境變數**：使用 `${CLAUDE_PLUGIN_ROOT}` 表示 plugin 根目錄中的捆綁 plugin 檔案，以及 `${CLAUDE_PLUGIN_DATA}` 表示 [persistent state](/zh-TW/plugins-reference#persistent-data-directory) 在 plugin 更新後仍然存在，以及 `${CLAUDE_PROJECT_DIR}` 表示穩定的專案根目錄

410* **使用者環境存取**：存取與手動配置的 servers 相同的環境變數222* **使用者環境存取**：存取與手動配置的 servers 相同的環境變數

411* **多種傳輸類型**：支援 stdio、SSE 和 HTTP 傳輸 (傳輸支援可能因 server 而異)223* **多種傳輸類型**：支援 stdio、SSE 和 HTTP 傳輸 (傳輸支援可能因 server 而異)

412 224

646 458

647許多雲端 MCP servers 需要驗證。Claude Code 支援 OAuth 2.0 以進行安全連接。459許多雲端 MCP servers 需要驗證。Claude Code 支援 OAuth 2.0 以進行安全連接。

648 460

461Claude Code 會在 server 以 `401 Unauthorized` 和指向其授權 server 的 `WWW-Authenticate` 標頭回應時，將遠端 server 標記為需要驗證。任何傳回該回應的自訂 server 都會獲得與任何其他遠端 server 相同的 `/mcp` 驗證流程。

462

649<Steps>463<Steps>

650 <Step title="新增需要驗證的 server">464 <Step title="新增需要驗證的 server">

651 例如：465 例如：

691 505

692### 使用預先配置的 OAuth 認證506### 使用預先配置的 OAuth 認證

693 507

694某些 MCP servers 不支援自動 OAuth 設定。如果您看到類似「Incompatible auth server: does not support dynamic client registration」的錯誤，server 需要預先配置的認證。Claude Code 也支援使用 Client ID Metadata Document (CIMD) 而不是 Dynamic Client Registration 的 servers，並自動探索這些。如果自動探索失敗，請先透過 server 的開發人員入口網站註冊 OAuth 應用程式，然後在新增 server 時提供認證。508某些 MCP servers 不支援透過 Dynamic Client Registration 進行自動 OAuth 設定。如果您看到類似「Incompatible auth server: does not support dynamic client registration」的錯誤，server 需要預先配置的認證。Claude Code 也支援使用 Client ID Metadata Document (CIMD) 而不是 Dynamic Client Registration 的 servers，並自動探索這些。如果自動探索失敗，請先透過 server 的開發人員入口網站註冊 OAuth 應用程式，然後在新增 server 時提供認證。

695 509

696<Steps>510<Steps>

697 <Step title="使用 server 註冊 OAuth 應用程式">511 <Step title="使用 server 註冊 OAuth 應用程式">

1139 953

1140### 配置 tool search954### 配置 tool search

1141 955

1142Tool search 預設啟用：MCP 工具被延遲並按需探索。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，tool search 預設停用，因為大多數代理不轉發 `tool_reference` 區塊。設定 `ENABLE_TOOL_SEARCH` 明確選擇加入。此功能需要支援 `tool_reference` 區塊的模型：Sonnet 4 及更新版本，或 Opus 4 及更新版本。Haiku 模型不支援 tool search。956Tool search 預設啟用：MCP 工具被延遲並按需探索。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，tool search 預設停用，因為大多數代理不轉發 `tool_reference` 區塊。如果您的代理轉發 `tool_reference` 區塊，請明確設定 `ENABLE_TOOL_SEARCH` 以覆蓋回退。此功能需要支援 `tool_reference` 區塊的模型：Sonnet 4 及更新版本，或 Opus 4 及更新版本。Haiku 模型不支援 tool search。

1143 957

1144使用 `ENABLE_TOOL_SEARCH` 環境變數控制 tool search 行為：958使用 `ENABLE_TOOL_SEARCH` 環境變數控制 tool search 行為：

1145 959

1146| 值 | 行為 |960| 值 | 行為 |

1147| :--------- | :------------------------------------------------------- |961| :--------- | :------------------------------------------------------------------------------------------ |

1148| (未設定) | 所有 MCP 工具被延遲並按需載入。當 `ANTHROPIC_BASE_URL` 是非第一方主機時回退到預先載入 |962| (未設定) | 所有 MCP 工具被延遲並按需載入。當 `ANTHROPIC_BASE_URL` 是非第一方主機時回退到預先載入 |

memory.md +16 −0

Details

272 </Step>272 </Step>

273</Steps>273</Steps>

274 274

275`claudeMd` 金鑰讓您將受管理的 CLAUDE.md 內容直接放入 `managed-settings.json` 中，而不是部署單獨的檔案。

276

277**範圍**：機器上的每個 Claude Code 工作階段，在每個儲存庫中。對於儲存庫特定的指導，請改為提交專案 CLAUDE.md。

278

279**優先級**：與受管理的 CLAUDE.md 檔案相同。在使用者和專案 CLAUDE.md 之前載入。

280

281**在何處被遵守**：僅受管理和原則設定。在使用者、專案或本地設定中設定 `claudeMd` 無效。

282

283下面的示例直接在受管理的設定檔案中新增行為指令：

284

285```json theme={null}

286{

287 "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."

288}

289```

290

275受管理的 CLAUDE.md 和 [受管理的設定](/zh-TW/settings#settings-files) 有不同的用途。使用設定進行技術強制執行，使用 CLAUDE.md 進行行為指導：291受管理的 CLAUDE.md 和 [受管理的設定](/zh-TW/settings#settings-files) 有不同的用途。使用設定進行技術強制執行，使用 CLAUDE.md 進行行為指導：

276 292

277| 關注 | 配置在 |293| 關注 | 配置在 |

monitoring-usage.md +75 −6

Details

174| `agent_id` | 發出請求的子代理或隊友的識別碼。在主工作階段上不存在 | |

175| `parent_agent_id` | 產生此代理的代理的識別碼。對於主工作階段和直接從其產生的代理不存在 | |

421 423

422#### 提取請求計數器424#### 提取請求計數器

423 425

424透過 Claude Code 建立提取請求時遞增。426透過 Claude Code 建立提取請求或合併請求時遞增。

425 427

426**屬性**：428**屬性**：

427 429

446* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一448* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

447* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在449* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

448* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。450* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。

451* `agent.name`：發出請求的子代理類型。內建代理名稱和官方市場 plugin 的代理按原樣出現。其他使用者定義的代理名稱被替換為 `"custom"`。當請求不是由命名的子代理類型發出時不存在。

452* `skill.name`：對請求有效的 Skill，由 Skill 工具、`/` 命令設定或由衍生的子代理繼承。內建、捆綁、使用者定義和官方市場 plugin skill 名稱按原樣出現。第三方 plugin skill 名稱被替換為 `"third-party"`。當沒有 skill 有效時不存在。

453* `plugin.name`：當活躍 skill 或子代理由 plugin 提供時的擁有 plugin。官方市場 plugin 名稱按原樣出現。第三方 plugin 名稱被替換為 `"third-party"`。當 skill 和子代理都沒有擁有 plugin 時不存在。

454* `marketplace.name`：擁有 plugin 的安裝市場。僅針對官方市場 plugin 發出。否則不存在。

449 455

450#### 權杖計數器456#### 權杖計數器

451 457

459* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一465* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

460* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在466* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

461* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)。詳見[成本計數器](#cost-counter)。467* `effort`：應用於請求的[努力等級](/zh-TW/model-config#adjust-effort-level)。詳見[成本計數器](#cost-counter)。

468* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`：請求的 Skill、plugin 和代理歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。

462 469

463#### 程式碼編輯工具決定計數器470#### 程式碼編輯工具決定計數器

464 471

647* `tool_use_id`：此工具叫用的唯一識別碼。符合傳遞給 hooks 的 `tool_use_id`，允許 OTel 事件和 hook 擷取資料之間的關聯。654* `tool_use_id`：此工具叫用的唯一識別碼。符合傳遞給 hooks 的 `tool_use_id`，允許 OTel 事件和 hook 擷取資料之間的關聯。

648* `decision`：`"accept"` 或 `"reject"`655* `decision`：`"accept"` 或 `"reject"`

649* `source`：決定來源：656* `source`：決定來源：

650 * `"config"`：根據專案設定、企業受管原則、`--allowedTools` 或 `--disallowedTools` 旗標、活躍權限模式或因為工具本身是安全的，自動決定而不提示。657 * `"config"`：根據專案設定、使用者個人設定中的允許規則、企業受管原則、`--allowedTools` 或 `--disallowedTools` 旗標、活躍權限模式、來自同一互動 CLI 工作階段中較早提示的工作階段範圍授予或因為工具本身是安全的，自動決定而不提示。該事件不指示這些來源中的哪一個相符。

651 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 傳回了決定。658 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 傳回了決定。

652 * `"user_permanent"`：當使用者在提示時選擇「始終允許」時發出，將規則儲存到其個人設定。也針對符合該儲存規則的後續呼叫發出。視為接受。659 * `"user_permanent"`：當使用者在權限提示時選擇「是，且不再詢問...」時發出，將允許規則儲存到其個人設定。在互動 CLI 中，僅針對該選擇本身發出；稍後符合儲存規則的呼叫發出 `"config"` 代替。在 Agent SDK 或非互動 `-p` 工作階段中，初始選擇和稍後的規則相符都發出 `"user_permanent"`。視為接受。

653 * `"user_temporary"`：當使用者在提示時選擇「是」或「是，此工作階段」時發出，不儲存規則。也針對同一工作階段中符合該工作階段範圍允許的後續呼叫發出。視為接受。660 * `"user_temporary"`：當使用者在權限提示時選擇「是」或在檔案編輯或讀取提示時選擇「...在此工作階段期間」選項之一時發出。在互動 CLI 中，僅針對選擇本身發出；稍後由該工作階段範圍授予允許的呼叫發出 `"config"` 代替。在 Agent SDK 或非互動 `-p` 工作階段中，選擇和稍後的相符都發出 `"user_temporary"`。視為接受。

654 * `"user_abort"`：當使用者關閉權限提示而不回答時發出。視為拒絕。661 * `"user_abort"`：當使用者關閉權限提示而不回答時發出。視為拒絕。

655 * `"user_reject"`：當使用者選擇「否」時發出，或呼叫符合其個人設定中的拒絕規則。視為拒絕。662 * `"user_reject"`：當使用者選擇「否」時發出，或呼叫符合其個人設定中的拒絕規則。視為拒絕。

656 663

741* `plugin.version`：Plugin 版本（如果在市場條目中宣告）。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含748* `plugin.version`：Plugin 版本（如果在市場條目中宣告）。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含

742* `marketplace.name`：安裝 plugin 的市場。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含749* `marketplace.name`：安裝 plugin 的市場。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含

743 750

751#### Plugin 已載入事件

752

753在工作階段開始時為每個啟用的 plugin 記錄一次。使用此事件來清點您的整個環境中哪些 plugin 是活躍的，作為記錄安裝動作本身的 `plugin_installed` 的補充。

754

755**事件名稱**：`claude_code.plugin_loaded`

756

757**屬性**：

758

759* 所有[標準屬性](#standard-attributes)

760* `event.name`：`"plugin_loaded"`

761* `event.timestamp`：ISO 8601 時間戳

762* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件

763* `plugin.name`：plugin 的名稱。對於官方市場和內建捆綁之外的 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`

764* `marketplace.name`：plugin 的安裝市場（如果已知）。在與 `plugin.name` 相同的條件下編輯為 `"third-party"`

765* `plugin.version`：來自 plugin 清單的版本。僅當名稱未被編輯且清單宣告版本時才包含

766* `plugin.scope`：plugin 的來源類別：`"official"`、`"org"`、`"user-local"` 或 `"default-bundle"`

767* `enabled_via`：plugin 如何被啟用的方式：`"default-enable"`、`"org-policy"`、`"seed-mount"` 或 `"user-install"`

768* `plugin_id_hash`：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算整個環境中載入了多少個不同的第三方 plugin，而無需記錄其名稱

769* `has_hooks`：plugin 是否貢獻 hooks

770* `has_mcp`：plugin 是否貢獻 MCP 伺服器

771* `skill_path_count`：plugin 宣告的 skill 目錄數

772* `command_path_count`：plugin 宣告的命令目錄數

773* `agent_path_count`：plugin 宣告的代理目錄數

774

744#### Skill 已啟動事件775#### Skill 已啟動事件

745 776

746當叫用 skill 時記錄，無論 Claude 是透過 Skill 工具呼叫它，還是您將其作為 `/` 命令執行。777當叫用 skill 時記錄，無論 Claude 是透過 Skill 工具呼叫它，還是您將其作為 `/` 命令執行。

793* `total_retry_duration_ms`：所有嘗試的總牆上時間824* `total_retry_duration_ms`：所有嘗試的總牆上時間

794* `speed`：`"fast"` 或 `"normal"`825* `speed`：`"fast"` 或 `"normal"`

795 826

827#### Hook 已註冊事件

828

829在工作階段開始時為每個配置的 hook 記錄一次。使用此事件來清點您的整個環境中哪些 hook 是活躍的，作為每次執行 `hook_execution_start` 和 `hook_execution_complete` 事件的補充。

830

831**事件名稱**：`claude_code.hook_registered`

832

833**屬性**：

834

835* 所有[標準屬性](#standard-attributes)

836* `event.name`：`"hook_registered"`

837* `event.timestamp`：ISO 8601 時間戳

838* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件

839* `hook_event`：hook 事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`

840* `hook_type`：hook 實作類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`

841* `hook_source`：hook 的定義位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`

842* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：hook 配置中的匹配器字串（如果已設定）

843* `plugin.name`（當 `hook_source` 是 `"pluginHook"` 時）：貢獻 plugin 的名稱。對於官方市場和內建捆綁之外的 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`

844* `plugin_id_hash`（當 `hook_source` 是 `"pluginHook"` 時）：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算不同的貢獻 plugin，而無需記錄其名稱

845

796#### Hook 執行開始事件846#### Hook 執行開始事件

797 847

798當一個或多個 hook 開始為 hook 事件執行時記錄。848當一個或多個 hook 開始為 hook 事件執行時記錄。

855* `post_tokens`：壓縮後的近似權杖計數905* `post_tokens`：壓縮後的近似權杖計數

856* `error`：壓縮失敗時的錯誤訊息906* `error`：壓縮失敗時的錯誤訊息

857 907

908#### 回饋調查事件

909

910當顯示或回答工作階段品質調查時記錄。詳見[工作階段品質調查](/zh-TW/data-usage#session-quality-surveys)以了解調查收集的內容以及如何控制它們。

911

912**事件名稱**：`claude_code.feedback_survey`

913

914**屬性**：

915

916* 所有[標準屬性](#standard-attributes)

917* `event.name`：`"feedback_survey"`

918* `event.timestamp`：ISO 8601 時間戳

919* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件

920* `event_type`：調查生命週期事件，例如 `"appeared"`、`"responded"` 或 `"transcript_prompt_appeared"`

921* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件

922* `survey_type`：哪個調查產生了事件。`"session"` 是「Claude 表現如何？」評分提示

923* `response`：使用者在 `responded` 事件上的選擇

924* `enabled_via_override`：當設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/zh-TW/env-vars) 時為 `true`。作為布林值而非字串發出。存在於 `session` 調查事件上。篩選此屬性以確認覆蓋在整個環境中應用

925

858## 解釋指標和事件資料926## 解釋指標和事件資料

859 927

860匯出的指標和事件支援一系列分析：928匯出的指標和事件支援一系列分析：

862### 使用情況監控930### 使用情況監控

863 931

864| 指標 | 分析機會 |932| 指標 | 分析機會 |

865| ------------------------------------------------------------- | ----------------------------- |933| ------------------------------------------------------------- | ------------------------------------------------------------------------ |

874 942

875* 追蹤跨團隊或個人的使用趨勢943* 追蹤跨團隊或個人的使用趨勢

876* 識別高使用量工作階段以進行最佳化944* 識別高使用量工作階段以進行最佳化

945* 透過 `skill.name`、`plugin.name` 和 `agent.name` 屬性將支出歸因於特定技能、外掛程式或子代理類型

877 946

878<Note>947<Note>

879 成本指標是近似值。如需官方帳單資料，請參閱您的 API 提供者（Claude Console、Amazon Bedrock 或 Google Cloud Vertex）。948 成本指標是近似值。如需官方帳單資料，請參閱您的 API 提供者（Claude Console、Amazon Bedrock 或 Google Cloud Vertex）。

output-styles.md +7 −3

Details

14 14

15Claude Code 的**預設**輸出樣式是現有的系統提示，旨在幫助您有效地完成軟體工程任務。15Claude Code 的**預設**輸出樣式是現有的系統提示，旨在幫助您有效地完成軟體工程任務。

16 16

~~17還有兩種額外的內建輸出樣式，專注於教您了解程式碼庫和 Claude 的運作方式：~~17還有三種額外的內建輸出樣式：

19* **Proactive**：Claude 立即執行，做出合理的假設而不是暫停進行例行決策，並偏好行動而非規劃。這應用與[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)相同的指導，而不改變您的權限模式，因此您在工具運行前仍會看到權限提示。

18 20

19* **Explanatory**：在幫助您完成軟體工程任務的同時提供教育性的「Insights」。幫助您理解實現選擇和程式碼庫模式。21* **Explanatory**：在幫助您完成軟體工程任務的同時提供教育性的「Insights」。幫助您理解實現選擇和程式碼庫模式。

20 22

88 90

89### 輸出樣式 vs. CLAUDE.md vs. --append-system-prompt91### 輸出樣式 vs. CLAUDE.md vs. --append-system-prompt

90 92

91輸出樣式完全「關閉」Claude Code 預設系統提示中特定於軟體工程的部分。CLAUDE.md 和 `--append-system-prompt` 都不會編輯 Claude Code 的預設系統提示。CLAUDE.md 將內容添加為 Claude Code 預設系統提示\_之後\_的使用者訊息。`--append-system-prompt` 將內容附加到系統提示。93根據 Claude 是否應該停止充當編碼助手或保持其預設角色並學習更多內容來選擇。輸出樣式用您自己的角色和聲音替換 Claude Code 系統提示中的軟體工程部分，因此當 Claude 應該採用不同的身份（例如寫作編輯或數據分析助手）時，請使用一個。CLAUDE.md 和 `--append-system-prompt` 都保持 Claude Code 的預設身份並添加到它，因此當 Claude 應該保持編碼助手身份同時遵循您的專案慣例或額外指示時，請使用它們。

95機制也不同。輸出樣式直接編輯系統提示。CLAUDE.md 在系統提示之後將其內容添加為使用者訊息。`--append-system-prompt` 將內容附加到系統提示的末尾，而不移除任何內容。

92 96

93### 輸出樣式 vs. [Agents](/zh-TW/sub-agents)97### 輸出樣式 vs. [Agents](/zh-TW/sub-agents)

94 98

95輸出樣式直接影響主代理迴圈，僅影響系統提示。Agents 被呼叫以處理特定任務，可以包括其他設定，例如要使用的模型、可用的工具以及有關何時使用代理的一些上下文。99使用輸出樣式在每個工作階段中改變主對話的回應方式。當您想要一個單獨作用域的幫助程式，由主對話委派給它時，請使用 [subagent](/zh-TW/sub-agents)。輸出樣式僅影響主代理迴圈的系統提示。Agents 處理特定任務，可以攜帶自己的模型、工具和有關何時呼叫它們的上下文。

96 100

97### 輸出樣式 vs. [Skills](/zh-TW/skills)101### 輸出樣式 vs. [Skills](/zh-TW/skills)

98 102

permission-modes.md +29 −1

Details

128 128

129再次按 `Shift+Tab` 離開 plan mode 而不批准計劃。129再次按 `Shift+Tab` 離開 plan mode 而不批准計劃。

130 130

131### 審查並批准計劃

132

131當計劃準備好時，Claude 呈現它並詢問如何進行。從該提示您可以：133當計劃準備好時，Claude 呈現它並詢問如何進行。從該提示您可以：

132 134

133* 批准並在 auto mode 中啟動135* 批准並在 auto mode 中啟動

136* 繼續規劃並提供反饋138* 繼續規劃並提供反饋

137* 使用 [Ultraplan](/zh-TW/ultraplan) 進行基於瀏覽器的審查進行細化139* 使用 [Ultraplan](/zh-TW/ultraplan) 進行基於瀏覽器的審查進行細化

138 140

139每個批准選項也提供首先清除規劃上下文的選項。141批准計劃會退出 plan mode 並將工作階段切換到每個批准選項描述的權限模式，因此 Claude 開始編輯。若要再次規劃，使用 `Shift+Tab` 循環回到 plan mode，或在您的下一個提示前加上 `/plan`。

142

143按 `Ctrl+G` 在您的預設文字編輯器中開啟提議的計劃並在 Claude 繼續之前直接編輯它。當啟用 [`showClearContextOnPlanAccept`](/zh-TW/settings#available-settings) 時，每個批准選項也提供首先清除規劃上下文的選項。

144

145接受計劃也會根據計劃內容自動命名工作階段，除非您已經使用 `--name` 或 `/rename` 設定了名稱。

146

147### 將 plan mode 設定為預設值

148

149若要將 plan mode 設定為專案的預設值，請在 `.claude/settings.json` 中設定 `defaultMode`：

150

151```json theme={null}

152{

153 "permissions": {

154 "defaultMode": "plan"

155 }

156}

157```

140 158

141## 使用 auto mode 消除提示159## 使用 auto mode 消除提示

142 160

146 164

147Auto mode 讓 Claude 執行而不顯示權限提示。單獨的分類器模型在執行前審查操作，阻止任何超出您要求的操作、針對無法識別的基礎設施的操作，或似乎由 Claude 讀到的敵對內容驅動的操作。165Auto mode 讓 Claude 執行而不顯示權限提示。單獨的分類器模型在執行前審查操作，阻止任何超出您要求的操作、針對無法識別的基礎設施的操作，或似乎由 Claude 讀到的敵對內容驅動的操作。

148 166

167Auto mode 也指示 Claude 立即執行並最小化澄清問題。若要在保持權限提示的情況下獲得該行為，請改為設定[主動輸出風格](/zh-TW/output-styles)。

168

149<Warning>169<Warning>

150 Auto mode 是研究預覽。它減少提示但不保證安全。將其用於您信任一般方向的任務，而不是作為敏感操作審查的替代品。170 Auto mode 是研究預覽。它減少提示但不保證安全。將其用於您信任一般方向的任務，而不是作為敏感操作審查的替代品。

151</Warning>171</Warning>

256 276

257`--dangerously-skip-permissions` 標誌等同於此。277`--dangerously-skip-permissions` 標誌等同於此。

258 278

279在 Linux 和 macOS 上，當以 root 身份或在 `sudo` 下執行時，Claude Code 拒絕以此模式啟動：

280

281```text theme={null}

282--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons

283```

284

285檢查在識別的沙箱內自動跳過。若要在容器中自主執行，請使用 [dev container](/zh-TW/devcontainer) 配置，該配置以非 root 使用者身份執行 Claude Code。

286

259<Warning>287<Warning>

260 `bypassPermissions` 不提供針對提示注入或意外操作的保護。對於沒有提示的背景安全檢查，請改為使用 [auto mode](#eliminate-prompts-with-auto-mode)。管理員可以通過在[受管設定](/zh-TW/permissions#managed-settings)中將 `permissions.disableBypassPermissionsMode` 設定為 `"disable"` 來阻止此模式。288 `bypassPermissions` 不提供針對提示注入或意外操作的保護。對於沒有提示的背景安全檢查，請改為使用 [auto mode](#eliminate-prompts-with-auto-mode)。管理員可以通過在[受管設定](/zh-TW/permissions#managed-settings)中將 `permissions.disableBypassPermissionsMode` 設定為 `"disable"` 來阻止此模式。

261</Warning>289</Warning>

permissions.md +5 −1

Details

28 28

29規則按順序評估：**deny -> ask -> allow**。第一個符合的規則獲勝，因此 deny 規則始終優先。29規則按順序評估：**deny -> ask -> allow**。第一個符合的規則獲勝，因此 deny 規則始終優先。

30 30

31<Note>

32 權限規則由 Claude Code 強制執行，而不是由模型強制執行。您的提示或 `CLAUDE.md` 中的指令會影響 Claude 嘗試執行的操作，但不會改變 Claude Code 允許的操作。若要授予或撤銷存取權限，請使用 `/permissions`、此處描述的規則、[permission mode](/zh-TW/permission-modes) 或 [PreToolUse hook](#extend-permissions-with-hooks)。

33</Note>

31## 權限模式35## 權限模式

32 36

33Claude Code 支援多種權限模式來控制工具的批准方式。請參閱 [Permission modes](/zh-TW/permission-modes) 以了解何時使用每一種。在您的 [settings files](/zh-TW/settings#settings-files) 中設定 `defaultMode`：37Claude Code 支援多種權限模式來控制工具的批准方式。請參閱 [Permission modes](/zh-TW/permission-modes) 以了解何時使用每一種。在您的 [settings files](/zh-TW/settings#settings-files) 中設定 `defaultMode`：

153 157

154 * **限制 Bash 網路工具**：使用 deny 規則阻止 `curl`、`wget` 和類似命令，然後使用 WebFetch 工具搭配 `WebFetch(domain:github.com)` 權限以允許的網域158 * **限制 Bash 網路工具**：使用 deny 規則阻止 `curl`、`wget` 和類似命令，然後使用 WebFetch 工具搭配 `WebFetch(domain:github.com)` 權限以允許的網域

155 * **使用 PreToolUse hooks**：實作一個 hook 來驗證 Bash 命令中的 URL 並阻止不允許的網域159 * **使用 PreToolUse hooks**：實作一個 hook 來驗證 Bash 命令中的 URL 並阻止不允許的網域

156 * 透過 CLAUDE.md 指示 Claude Code 關於您允許的 curl 模式160 * **新增 CLAUDE.md 指導**：在 `CLAUDE.md` 中描述您允許的 curl 模式。這會形塑 Claude 嘗試的內容，但不會強制執行邊界，所以請將其與上述選項之一配對

157 161

158 請注意，單獨使用 WebFetch 不會防止網路存取。如果允許 Bash，Claude 仍然可以使用 `curl`、`wget` 或其他工具來存取任何 URL。162 請注意，單獨使用 WebFetch 不會防止網路存取。如果允許 Bash，Claude 仍然可以使用 `curl`、`wget` 或其他工具來存取任何 URL。

159</Warning>163</Warning>

plugins.md +6 −0

Details

299claude --plugin-dir ./my-plugin299claude --plugin-dir ./my-plugin

300```300```

301 301

302該旗標也接受 plugin 目錄的 `.zip` 檔案，這需要 Claude Code v2.1.128 或更新版本。

303

304```bash theme={null}

305claude --plugin-dir ./my-plugin.zip

306```

307

302當 `--plugin-dir` plugin 與已安裝的市場 plugin 具有相同名稱時，本地副本在該工作階段中優先。這讓您可以測試已安裝的 plugin 的變更，而無需先卸載它。由受管設定強制啟用的市場 plugins 是唯一的例外，無法被覆蓋。308當 `--plugin-dir` plugin 與已安裝的市場 plugin 具有相同名稱時，本地副本在該工作階段中優先。這讓您可以測試已安裝的 plugin 的變更，而無需先卸載它。由受管設定強制啟用的市場 plugins 是唯一的例外，無法被覆蓋。

303 309

304當您對 plugin 進行變更時，執行 `/reload-plugins` 以取得更新，無需重新啟動。這會重新載入 plugins、skills、agents、hooks、plugin MCP servers 和 plugin LSP servers。測試您的 plugin 元件：310當您對 plugin 進行變更時，執行 `/reload-plugins` 以取得更新，無需重新啟動。這會重新載入 plugins、skills、agents、hooks、plugin MCP servers 和 plugin LSP servers。測試您的 plugin 元件：

plugins-reference.md +69 −9

Details

97 "hooks": [97 "hooks": [

98 {98 {

99 "type": "command",99 "type": "command",

100 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"100 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"

101 }101 }

102 ]102 ]

103 }103 }

289[289[

290 {290 {

291 "name": "deploy-status",291 "name": "deploy-status",

292 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",292 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",

293 "description": "Deployment status changes"293 "description": "Deployment status changes"

294 },294 },

295 {295 {

317| :----- | :----------------------------------------------------------------------------------------------------------------------- |317| :----- | :----------------------------------------------------------------------------------------------------------------------- |

318| `when` | 控制 monitor 何時啟動。`"always"` 在工作階段啟動和 plugin 重新載入時啟動它，是預設值。`"on-skill-invoke:<skill-name>"` 在此 plugin 中的命名 skill 首次被分派時啟動它 |318| `when` | 控制 monitor 何時啟動。`"always"` 在工作階段啟動和 plugin 重新載入時啟動它，是預設值。`"on-skill-invoke:<skill-name>"` 在此 plugin 中的命名 skill 首次被分派時啟動它 |

319 319

320`command` 值支援與 MCP 和 LSP server 設定相同的 [variable substitutions](#environment-variables)：`${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}`、`${user_config.*}` 和環境中的任何 `${ENV_VAR}`。如果指令碼需要從 plugin 自己的目錄執行，請在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。320`command` 值支援與 MCP 和 LSP server 設定相同的 [variable substitutions](#environment-variables)：`${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}`、`${CLAUDE_PROJECT_DIR}`、`${user_config.*}` 和環境中的任何 `${ENV_VAR}`。如果指令碼需要從 plugin 自己的目錄執行，請在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。

321 321

322在工作階段中途停用 plugin 不會停止已在執行的 monitors。它們在工作階段結束時停止。322在工作階段中途停用 plugin 不會停止已在執行的 monitors。它們在工作階段結束時停止。

323 323

540 540

541### 環境變數541### 環境變數

542 542

543Claude Code 提供兩個變數用於參考 plugin 路徑。兩者都在 skill 內容、agent 內容、hook 命令、monitor 命令以及 MCP 或 LSP server 設定中出現的任何地方內聯替換。兩者也會匯出為環境變數到 hook 程序和 MCP 或 LSP server 子程序。543Claude Code 提供三個變數用於參考路徑。所有變數都在 skill 內容、agent 內容、hook 命令、monitor 命令以及 MCP 或 LSP server 設定中出現的任何地方內聯替換。所有變數也會匯出為環境變數到 hook 程序和 MCP 或 LSP server 子程序。

544 544

545**`${CLAUDE_PLUGIN_ROOT}`**：plugin 安裝目錄的絕對路徑。使用此方法參考與 plugin 捆綁的指令碼、二進位檔和設定檔。此路徑在 plugin 更新時會變更。前一個版本的目錄在更新後約七天內保留在磁碟上，然後才進行清理，但應將其視為暫時性的，不要在此處寫入狀態。545**`${CLAUDE_PLUGIN_ROOT}`**：plugin 安裝目錄的絕對路徑。使用此方法參考與 plugin 捆綁的指令碼、二進位檔和設定檔。在 hook 命令中，使用[執行形式](/zh-TW/hooks#exec-form-and-shell-form)搭配 `args`，以便路徑作為一個引數傳遞，無需引號。在 shell 形式的 hooks 和 monitor 命令中，將其包裝在雙引號中，如 `"${CLAUDE_PLUGIN_ROOT}"`。此路徑在 plugin 更新時會變更。前一個版本的目錄在更新後約七天內保留在磁碟上，然後才進行清理，但應將其視為暫時性的，不要在此處寫入狀態。

546 546

547當 plugin 在工作階段中途更新時，hook 命令、monitors、MCP servers 和 LSP servers 會繼續使用前一個版本的路徑。執行 `/reload-plugins` 以將 hooks、MCP servers 和 LSP servers 切換到新路徑；monitors 需要工作階段重新啟動。547當 plugin 在工作階段中途更新時，hook 命令、monitors、MCP servers 和 LSP servers 會繼續使用前一個版本的路徑。執行 `/reload-plugins` 以將 hooks、MCP servers 和 LSP servers 切換到新路徑；monitors 需要工作階段重新啟動。

548 548

549**`${CLAUDE_PLUGIN_DATA}`**：用於在更新後保留的 plugin 狀態的持久目錄。使用此方法用於已安裝的依賴項，例如 `node_modules` 或 Python 虛擬環境、生成的程式碼、快取和任何應在 plugin 版本之間保留的其他檔案。首次參考此變數時會自動建立目錄。549**`${CLAUDE_PLUGIN_DATA}`**：用於在更新後保留的 plugin 狀態的持久目錄。使用此方法用於已安裝的依賴項，例如 `node_modules` 或 Python 虛擬環境、生成的程式碼、快取和任何應在 plugin 版本之間保留的其他檔案。首次參考此變數時會自動建立目錄。

550 550

551**`${CLAUDE_PROJECT_DIR}`**：專案根目錄。這是 hooks 在其 `CLAUDE_PROJECT_DIR` 變數中接收的相同目錄。使用此方法參考專案本地指令碼或設定檔。包裝在引號中以處理包含空格的路徑，例如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。MCP servers 也可以呼叫 MCP `roots/list` 請求，該請求會傳回啟動 Claude Code 的目錄。

552

551```json theme={null}553```json theme={null}

552{554{

553 "hooks": {555 "hooks": {

556 "hooks": [558 "hooks": [

557 {559 {

558 "type": "command",560 "type": "command",

559 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"561 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"

560 }562 }

561 ]563 ]

562 }564 }

629 631

630已安裝的 plugins 無法參考其目錄外的檔案。遍歷 plugin 根目錄外的路徑（例如 `../shared-utils`）在安裝後將無法運作，因為這些外部檔案不會複製到快取中。632已安裝的 plugins 無法參考其目錄外的檔案。遍歷 plugin 根目錄外的路徑（例如 `../shared-utils`）在安裝後將無法運作，因為這些外部檔案不會複製到快取中。

631 633

632### 使用外部依賴項634### 使用 symlinks 在 marketplace 內共享檔案

635

636如果您的 plugin 需要與同一 marketplace 的其他部分共享檔案，您可以在 plugin 目錄內建立符號連結。當 plugin 被複製到快取時，symlink 的處理方式取決於其目標的解析位置：

637

638* **在 plugin 自身目錄內：** symlink 在快取中被保留為相對 symlink，因此在執行時繼續解析到複製的目標。

639* **在同一 marketplace 內的其他位置：** symlink 被取消參考。目標的內容被複製到快取中以取代它。這讓 meta-plugin 的 `skills/` 目錄可以連結到 marketplace 中其他 plugins 定義的 skills。

640* **在 marketplace 外：** symlink 因安全考量而被跳過。這防止 plugins 將任意主機檔案（例如系統路徑）拉入快取。

633 641

634如果您的 plugin 需要存取其目錄外的檔案，您可以在 plugin 目錄中建立指向外部檔案的符號連結。符號連結在快取中被保留而不是被取消參考，並在執行時解析到其目標。以下命令從 plugin 目錄內建立到共享公用程式位置的連結：642對於使用 `--plugin-dir` 安裝或從本機路徑安裝的 plugins，只有解析在 plugin 自身目錄內的 symlinks 被保留。所有其他的都被跳過。

643

644以下命令從 marketplace plugin 內建立到由同級 plugin 定義的共享 skill 的連結。在 Windows 上，從提升的命令提示字元使用 `mklink /D` 或啟用開發人員模式：

635 645

636```bash theme={null}646```bash theme={null}

637ln -s /path/to/shared-utils ./shared-utils647ln -s ../../shared-plugin/skills/foo ./skills/foo

638```648```

639 649

640這在維持快取系統安全優勢的同時提供了靈活性。650這在維持快取系統安全優勢的同時提供了靈活性。

877 887

888### plugin details

889

890顯示 plugin 的元件清單和預計的 token 成本。輸出列出 plugin 貢獻的所有元件，分組為 Skills（技能和命令）、Agents、Hooks 和 MCP servers，以及它為每個工作階段新增多少 tokens 的估計。

891

892```bash theme={null}

893claude plugin details <name>

894```

895

896**引數：**

897

898* `<name>`：Plugin 名稱或 `plugin-name@marketplace-name`

899

900**選項：**

901

902| 選項 | 描述 | 預設 |

903| :----------- | :----- | :- |

904| `-h, --help` | 顯示命令說明 | |

905

906輸出為每個元件顯示兩個成本數字：

907

908* **Always-on：** plugin 的列表文字新增到每個工作階段的 tokens，例如技能描述、agent 描述和命令名稱，無論任何元件是否觸發。

909* **On-invoke：** 元件觸發時的成本。按元件顯示，而不是作為 plugin 總計，因為典型的工作階段只會呼叫元件的子集。

910

911此範例顯示具有兩個技能的 plugin 的輸出外觀：

912

913```

914security-guidance 1.2.0

915 Real-time security analysis for Claude Code sessions

916 Source: security-guidance@claude-code-marketplace

917

918Component inventory

919 Skills (2) scan-dependencies, review-changes

920 Agents (0)

921 Hooks (1) (harness-only — no model context cost)

922 MCP servers (0)

923

924Projected token cost

925 Always-on: ~180 tok added to every session

926

927Per-component (rounded)

928 component always-on on-invoke

929 scan-dependencies ~100 ~2400

930 review-changes ~80 ~1800

931

932 On-invoke cost is paid each time a skill or agent fires.

933 Token counts are estimates and may differ from actual usage.

934```

935

936always-on 總計是透過您的作用中模型的 `count_tokens` API 計算的。按元件的數字按比例從該總計縮放。如果 API 無法連線，該命令會回退到基於字元的估計。

937

878### plugin tag938### plugin tag

879 939

880為目前目錄中的 plugin 建立發行版 git 標籤。從 plugin 的資料夾內執行。請參閱 [Tag plugin releases](/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution)。940為目前目錄中的 plugin 建立發行版 git 標籤。從 plugin 的資料夾內執行。請參閱 [Tag plugin releases](/zh-TW/plugin-dependencies#tag-plugin-releases-for-version-resolution)。

quickstart.md +4 −4

Details

279 279

280<AccordionGroup>280<AccordionGroup>

281 <Accordion title="對您的請求要具體">281 <Accordion title="對您的請求要具體">

282 不要這樣做：'修復錯誤'282 不要這樣做："修復錯誤"

283 283

284 試試這樣：'修復登入錯誤，使用者輸入錯誤認證後看到空白畫面'284 試試這樣："修復登入錯誤，使用者輸入錯誤認證後看到空白畫面"

285 </Accordion>285 </Accordion>

286 286

287 <Accordion title="使用逐步說明">287 <Accordion title="使用逐步說明">

307 </Accordion>307 </Accordion>

308 308

309 <Accordion title="使用快捷方式節省時間">309 <Accordion title="使用快捷方式節省時間">

310 * 按 `?` 查看所有可用的快捷鍵310 * 輸入 `/` 查看所有命令和 skills

311 * 使用 Tab 進行命令完成311 * 使用 Tab 進行命令完成

312 * 按 ↑ 查看命令歷史312 * 按 ↑ 查看命令歷史

313 * 輸入 `/` 查看所有命令和 skills313 * 按 `Shift+Tab` 循環切換權限模式

314 </Accordion>314 </Accordion>

315</AccordionGroup>315</AccordionGroup>

316 316

routines.md +3 −1

Details

318 318

319例行程序可以使用您連接的 MCP connectors 在每次運行期間讀取和寫入外部服務。例如，分類支持請求的例行程序可能從 Slack 頻道讀取並在 Linear 中創建問題。319例行程序可以使用您連接的 MCP connectors 在每次運行期間讀取和寫入外部服務。例如，分類支持請求的例行程序可能從 Slack 頻道讀取並在 Linear 中創建問題。

320 320

321Connectors 是您帳戶上的 [claude.ai integrations](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。您在 CLI 中使用 `claude mcp add` 本地添加的 MCP 伺服器存儲在您的機器上而不是您的 claude.ai 帳戶上，因此它們不會出現在 connectors 列表中。要在例行程序中使用其中一個伺服器，請在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 添加它作為 connector，或在已提交的 [`.mcp.json`](/zh-TW/mcp#project-scope) 中聲明它，以便它是克隆存儲庫的一部分。

322

321當您創建例行程序時，默認情況下包括您所有當前連接的 connectors。移除任何不需要的以限制 Claude 在運行期間可以訪問的工具。您也可以直接從例行程序表單添加 connectors。323當您創建例行程序時，默認情況下包括您所有當前連接的 connectors。移除任何不需要的以限制 Claude 在運行期間可以訪問的工具。您也可以直接從例行程序表單添加 connectors。

322 324

323要在例行程序表單外管理或添加 connectors，請訪問 claude.ai 上的 **Settings > Connectors** 或在 CLI 中使用 `/schedule update`。325要在例行程序表單外管理或添加 connectors，請訪問 claude.ai 上的 **Settings > Connectors** 或在 CLI 中使用 `/schedule update`。

326 328

327每個例行程序在 [cloud environment](/zh-TW/claude-code-on-the-web#the-cloud-environment) 中運行，該環境控制網絡訪問、環境變量和設置腳本。例行程序在每次運行時繼承環境的網絡策略。329每個例行程序在 [cloud environment](/zh-TW/claude-code-on-the-web#the-cloud-environment) 中運行，該環境控制網絡訪問、環境變量和設置腳本。例行程序在每次運行時繼承環境的網絡策略。

328 330

329**Default** 環境使用 **Trusted** 網絡訪問：[默認允許列表](/zh-TW/claude-code-on-the-web#default-allowed-domains)中的包註冊表、雲提供商 API、容器註冊表和常見開發域是可達的，但任意域不可達。對其他主機的出站請求失敗，返回 `403` 和 `x-deny-reason: host_not_allowed`。MCP connector 流量通過 Anthropic 的服務器路由，因此您添加到例行程序的 connectors 無需將其主機添加到 **Allowed domains** 即可工作。移除您不需要的任何 connectors，詳見 [Connectors](#connectors)。331**Default** 環境使用 **Trusted** 網絡訪問：[默認允許列表](/zh-TW/claude-code-on-the-web#default-allowed-domains)中的包註冊表、雲提供商 API、容器註冊表和常見開發域是可達的，但任意域不可達。對其他主機的出站請求失敗，返回 `403` 和 `x-deny-reason: host_not_allowed`。MCP connector 流量通過 Anthropic 的伺服器路由，因此您添加到例行程序的 connectors 無需將其主機添加到 **Allowed domains** 即可工作。移除您不需要的任何 connectors，詳見 [Connectors](#connectors)。

330 332

331要允許其他域：333要允許其他域：

332 334

security.md +1 −1

Details

85 85

86Claude Code 允許使用者配置 Model Context Protocol (MCP) servers。允許的 MCP servers 列表在您的原始程式碼中配置，作為 Claude Code 設定的一部分，工程師將其簽入原始碼控制。86Claude Code 允許使用者配置 Model Context Protocol (MCP) servers。允許的 MCP servers 列表在您的原始程式碼中配置，作為 Claude Code 設定的一部分，工程師將其簽入原始碼控制。

87 87

88我們鼓勵編寫您自己的 MCP servers 或使用來自您信任的提供者的 MCP servers。您能夠為 MCP servers 配置 Claude Code 權限。Anthropic 不管理或審計任何 MCP servers。88我們鼓勵編寫您自己的 MCP servers 或使用來自您信任的提供者的 MCP servers。您能夠為 MCP servers 配置 Claude Code 權限。Anthropic 在將連接器新增至 [Anthropic Directory](https://claude.ai/directory) 之前，會根據其 [列表標準](https://claude.com/docs/connectors/building/review-criteria) 審查連接器，但不會對任何 MCP server 進行安全審計或管理。

89 89

90## IDE 安全性90## IDE 安全性

91 91

settings.md +3 −1

Details

179| `blockedMarketplaces` | （Managed 設定僅限）marketplace 來源的黑名單。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | （Managed 設定僅限）marketplace 來源的黑名單。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

180| `channelsEnabled` | （Managed 設定僅限）允許組織使用[頻道](/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上，當此設定未設定或為 `false` 時，頻道會被阻止。對於使用 API 金鑰驗證的 [Anthropic Console](/zh-TW/authentication#claude-console-authentication) 帳戶，除非您的組織部署 managed 設定（在這種情況下此金鑰必須設定為 `true`），否則預設允許頻道 | `true` |180| `channelsEnabled` | （Managed 設定僅限）允許組織使用[頻道](/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上，當此設定未設定或為 `false` 時，頻道會被阻止。對於使用 API 金鑰驗證的 [Anthropic Console](/zh-TW/authentication#claude-console-authentication) 帳戶，除非您的組織部署 managed 設定（在這種情況下此金鑰必須設定為 `true`），否則預設允許頻道 | `true` |

181| `claudeMd` | （Managed 設定僅限）CLAUDE.md 樣式的指示，作為組織管理的記憶注入。僅在 managed 或政策設定中設定時受尊重，在使用者、專案和本機設定中被忽略。請參閱[組織範圍的 CLAUDE.md](/zh-TW/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |

181| `claudeMdExcludes` | 載入[記憶](/zh-TW/memory)時要跳過的 `CLAUDE.md` 檔案的 Glob 模式或絕對路徑。模式與絕對檔案路徑相符。僅適用於使用者、專案和本機記憶；managed 政策檔案無法排除 | `["**/vendor/**/CLAUDE.md"]` |182| `claudeMdExcludes` | 載入[記憶](/zh-TW/memory)時要跳過的 `CLAUDE.md` 檔案的 Glob 模式或絕對路徑。模式與絕對檔案路徑相符。僅適用於使用者、專案和本機記憶；managed 政策檔案無法排除 | `["**/vendor/**/CLAUDE.md"]` |

182| `cleanupPeriodDays` | 非使用中超過此期間的工作階段在啟動時刪除（預設：30 天，最少 1 天）。設定為 `0` 會被拒絕並出現驗證錯誤。也控制[孤立 subagent worktrees](/zh-TW/worktrees#clean-up-worktrees) 在啟動時自動移除的年齡截止。若要完全停用文字記錄寫入，請設定 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數，或在非互動模式（`-p`）中使用 `--no-session-persistence` 旗標或 `persistSession: false` SDK 選項。 | `20` |183| `cleanupPeriodDays` | 非使用中超過此期間的工作階段在啟動時刪除（預設：30 天，最少 1 天）。設定為 `0` 會被拒絕並出現驗證錯誤。也控制[孤立 subagent worktrees](/zh-TW/worktrees#clean-up-worktrees) 在啟動時自動移除的年齡截止。若要完全停用文字記錄寫入，請設定 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數，或在非互動模式（`-p`）中使用 `--no-session-persistence` 旗標或 `persistSession: false` SDK 選項。 | `20` |

253</Note>254</Note>

254 255

255| 金鑰 | 說明 | 範例 |256| 金鑰 | 說明 | 範例 |

256| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |257| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------- |

257| `autoConnectIde` | 當 Claude Code 從外部終端機啟動時自動連線到執行中的 IDE。預設：`false`。在 VS Code 或 JetBrains 終端機外執行時在 `/config` 中顯示為**自動連線到 IDE（外部終端機）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/zh-TW/env-vars) 環境變數在設定時會覆蓋此設定 | `true` |258| `autoConnectIde` | 當 Claude Code 從外部終端機啟動時自動連線到執行中的 IDE。預設：`false`。在 VS Code 或 JetBrains 終端機外執行時在 `/config` 中顯示為**自動連線到 IDE（外部終端機）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/zh-TW/env-vars) 環境變數在設定時會覆蓋此設定 | `true` |

258| `autoInstallIdeExtension` | 從 VS Code 終端機執行時自動安裝 Claude Code IDE 擴充功能。預設：`true`。在 VS Code 或 JetBrains 終端機內執行時在 `/config` 中顯示為**自動安裝 IDE 擴充功能**。您也可以設定 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-TW/env-vars) 環境變數 | `false` |259| `autoInstallIdeExtension` | 從 VS Code 終端機執行時自動安裝 Claude Code IDE 擴充功能。預設：`true`。在 VS Code 或 JetBrains 終端機內執行時在 `/config` 中顯示為**自動安裝 IDE 擴充功能**。您也可以設定 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-TW/env-vars) 環境變數 | `false` |

261| `teammateDefaultModel` | [agent team](/zh-TW/agent-teams) 隊友在生成提示未指定時的預設模型。設定為模型別名（例如 `"sonnet"`），或 `null` 以繼承主管的目前 `/model` 選擇。在 `/config` 中顯示為**預設隊友模型** | `"sonnet"` |

260 262

261### Worktree 設定263### Worktree 設定

262 264

vs-code.md +5 −3

Details

233</Note>233</Note>

234 234

235| 命令 | 快捷鍵 | 描述 |235| 命令 | 快捷鍵 | 描述 |

236| -------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------- |236| -------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |

238| Open in Side Bar | - | 在左側邊欄中開啟 Claude |238| Open in Side Bar | - | 在左側邊欄中開啟 Claude |

239| Open in Terminal | - | 在終端機模式中開啟 Claude |239| Open in Terminal | - | 在終端機模式中開啟 Claude |

241| Open in New Window | - | 在單獨的視窗中開啟新對話 |241| Open in New Window | - | 在單獨的視窗中開啟新對話 |

243| Reopen Closed Session | `Cmd+Shift+T`（Mac）/ `Ctrl+Shift+T`（Windows/Linux） | 重新開啟最近關閉的 Claude 工作階段標籤。當最後關閉的標籤不是 Claude 工作階段時，會回退到 VS Code 的正常重新開啟關閉編輯器。使用 `enableReopenClosedSessionShortcut` 停用 |

244| Show Logs | - | 檢視擴充功能除錯日誌 |245| Show Logs | - | 檢視擴充功能除錯日誌 |

245| Logout | - | 登出您的 Anthropic 帳戶 |246| Logout | - | 登出您的 Anthropic 帳戶 |

307### 擴充功能設定308### 擴充功能設定

308 309

309| 設定 | 預設值 | 描述 |310| 設定 | 預設值 | 描述 |

310| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |311| ----------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

318| `enableReopenClosedSessionShortcut` | `true` | 使用 Cmd/Ctrl+Shift+T 重新開啟最近關閉的 Claude 工作階段標籤。當最後關閉的標籤不是 Claude 工作階段時，快捷鍵會改為執行 VS Code 的正常重新開啟已關閉編輯器命令。 |

320| `environmentVariables` | `[]` | 為 Claude 程序設定環境變數。改為使用 Claude Code 設定以進行共享配置。 |322| `environmentVariables` | `[]` | 為 Claude 程序設定環境變數。改為使用 Claude Code 設定以進行共享配置。 |

322| `allowDangerouslySkipPermissions` | `false` | 將 [Auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 和 Bypass permissions 添加到模式選擇器。Auto mode 有[計畫、管理員、模型和提供者要求](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，因此即使此切換打開，該選項也可能保持不可用。僅在沒有網際網路存取的沙箱中使用 Bypass permissions。 |324| `allowDangerouslySkipPermissions` | `false` | 將 [Auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 和 Bypass permissions 添加到模式選擇器。Auto mode 有[計畫、管理員、模型和提供者要求](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，因此即使此切換打開，該選項也可能保持不可用。僅在沒有網際網路存取的 sandbox 中使用 Bypass permissions。 |

323| `claudeProcessWrapper` | - | 用於啟動 Claude 程序的可執行檔。當存在時，捆綁的二進制檔案路徑會作為引數傳遞。如果擴充功能組建不包含您平台的二進制檔案，請將此設定為單獨安裝的 `claude` 二進制檔案。 |325| `claudeProcessWrapper` | - | 用於啟動 Claude 程序的可執行檔。當存在時，捆綁的二進制檔案路徑會作為引數傳遞。如果擴充功能組建不包含您平台的二進制檔案，請將此設定為單獨安裝的 `claude` 二進制檔案。 |

324 326

325## VS Code 擴充功能與 Claude Code CLI327## VS Code 擴充功能與 Claude Code CLI

Documentation 2026-05-11 23:00 UTC to 2026-05-12 22:57 UTC