Documentation — Spybara

agent-sdk/custom-tools.md +833 −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# 為 Claude 提供自訂工具

7> 使用 Claude Agent SDK 的同程序 MCP 伺服器定義自訂工具，讓 Claude 可以呼叫您的函數、存取您的 API，並執行特定領域的操作。

9自訂工具透過讓您定義 Claude 在對話期間可以呼叫的自己的函數來擴展 Agent SDK。使用 SDK 的同程序 MCP 伺服器，您可以讓 Claude 存取資料庫、外部 API、特定領域邏輯或應用程式需要的任何其他功能。

11本指南涵蓋如何使用輸入結構描述和處理程式定義工具、將它們組合到 MCP 伺服器中、將它們傳遞給 `query`，以及控制 Claude 可以存取哪些工具。它也涵蓋錯誤處理、工具註解，以及傳回非文字內容（如影像）。

13## 快速參考

15| 如果您想要... | 執行此操作 |

16| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

17| 定義工具 | 使用 [`@tool`](/zh-TW/agent-sdk/python#tool)（Python）或 [`tool()`](/zh-TW/agent-sdk/typescript#tool)（TypeScript），搭配名稱、描述、結構描述和處理程式。請參閱[建立自訂工具](#create-a-custom-tool)。 |

18| 向 Claude 註冊工具 | 在 `create_sdk_mcp_server` / `createSdkMcpServer` 中包裝，並傳遞至 `query()` 中的 `mcpServers`。請參閱[呼叫自訂工具](#call-a-custom-tool)。 |

19| 預先核准工具 | 新增至您允許的工具。請參閱[設定允許的工具](#configure-allowed-tools)。 |

20| 從 Claude 的內容中移除內建工具 | 傳遞 `tools` 陣列，僅列出您想要的內建工具。請參閱[設定允許的工具](#configure-allowed-tools)。 |

21| 讓 Claude 平行呼叫工具 | 在沒有副作用的工具上設定 `readOnlyHint: true`。請參閱[新增工具註解](#add-tool-annotations)。 |

22| 處理錯誤而不停止迴圈 | 傳回 `isError: true` 而不是擲回。請參閱[處理錯誤](#handle-errors)。 |

23| 傳回影像或檔案 | 在內容陣列中使用 `image` 或 `resource` 區塊。請參閱[傳回影像和資源](#return-images-and-resources)。 |

24| 傳回機器可讀的 JSON 結果 | 在結果上設定 `structuredContent`。請參閱[傳回結構化資料](#return-structured-data)。 |

25| 擴展到許多工具 | 使用[工具搜尋](/zh-TW/agent-sdk/tool-search)按需載入工具。 |

27## 建立自訂工具

29工具由四個部分定義，作為 TypeScript 中 [`tool()`](/zh-TW/agent-sdk/typescript#tool) 協助程式或 Python 中 [`@tool`](/zh-TW/agent-sdk/python#tool) 裝飾器的引數傳遞：

31* **名稱：** Claude 用來呼叫工具的唯一識別碼。

32* **描述：** 工具的功能。Claude 讀取此項以決定何時呼叫它。

33* **輸入結構描述：** Claude 必須提供的引數。在 TypeScript 中，這始終是 [Zod 結構描述](https://zod.dev/)，處理程式的 `args` 會自動從中輸入。在 Python 中，這是將名稱對應到類型的字典，例如 `{"latitude": float}`，SDK 會為您轉換為 JSON Schema。Python 裝飾器也接受完整的 [JSON Schema](https://json-schema.org/understanding-json-schema/about) 字典，當您需要列舉、範圍、選用欄位或巢狀物件時。

34* **處理程式：** 當 Claude 呼叫工具時執行的非同步函數。它接收驗證的引數，並必須傳回具有以下內容的物件：

35 * `content`（必需）：結果區塊的陣列，每個區塊的 `type` 為 `"text"`、`"image"` 或 `"resource"`。請參閱[傳回影像和資源](#return-images-and-resources)以取得非文字區塊。

36 * `structuredContent`（選用）：保存結果作為機器可讀資料的 JSON 物件，與 `content` 一起傳回。請參閱[傳回結構化資料](#return-structured-data)。

37 * `isError`（選用）：設定為 `true` 以表示工具失敗，讓 Claude 可以對其做出反應。請參閱[處理錯誤](#handle-errors)。

39定義工具後，使用 [`createSdkMcpServer`](/zh-TW/agent-sdk/typescript#createsdkmcpserver)（TypeScript）或 [`create_sdk_mcp_server`](/zh-TW/agent-sdk/python#create_sdk_mcp_server)（Python）將其包裝在伺服器中。伺服器在應用程式內同程序執行，而不是作為單獨的程序。

41### 天氣工具範例

43此範例定義 `get_temperature` 工具並將其包裝在 MCP 伺服器中。它只設定工具；若要將其傳遞至 `query` 並執行它，請參閱下面的[呼叫自訂工具](#call-a-custom-tool)。

45<CodeGroup>

46 ```python Python theme={null}

47 from typing import Any

48 import httpx

49 from claude_agent_sdk import tool, create_sdk_mcp_server

52 # Define a tool: name, description, input schema, handler

53 @tool(

54 "get_temperature",

55 "Get the current temperature at a location",

56 {"latitude": float, "longitude": float},

57 )

58 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:

59 async with httpx.AsyncClient() as client:

60 response = await client.get(

61 "https://api.open-meteo.com/v1/forecast",

62 params={

63 "latitude": args["latitude"],

64 "longitude": args["longitude"],

65 "current": "temperature_2m",

66 "temperature_unit": "fahrenheit",

67 },

68 )

69 data = response.json()

71 # Return a content array - Claude sees this as the tool result

72 return {

73 "content": [

74 {

75 "type": "text",

76 "text": f"Temperature: {data['current']['temperature_2m']}°F",

77 }

78 ]

79 }

82 # Wrap the tool in an in-process MCP server

83 weather_server = create_sdk_mcp_server(

84 name="weather",

85 version="1.0.0",

86 tools=[get_temperature],

87 )

88 ```

90 ```typescript TypeScript theme={null}

91 import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

92 import { z } from "zod";

94 // Define a tool: name, description, input schema, handler

95 const getTemperature = tool(

96 "get_temperature",

97 "Get the current temperature at a location",

98 {

99 latitude: z.number().describe("Latitude coordinate"), // .describe() adds a field description Claude sees

100 longitude: z.number().describe("Longitude coordinate")

101 },

102 async (args) => {

103 // args is typed from the schema: { latitude: number; longitude: number }

104 const response = await fetch(

105 `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&current=temperature_2m&temperature_unit=fahrenheit`

106 );

107 const data: any = await response.json();

108

109 // Return a content array - Claude sees this as the tool result

110 return {

111 content: [{ type: "text", text: `Temperature: ${data.current.temperature_2m}°F` }]

112 };

113 }

114 );

115

116 // Wrap the tool in an in-process MCP server

117 const weatherServer = createSdkMcpServer({

118 name: "weather",

119 version: "1.0.0",

120 tools: [getTemperature]

121 });

122 ```

123</CodeGroup>

124

125請參閱 [`tool()`](/zh-TW/agent-sdk/typescript#tool) TypeScript 參考或 [`@tool`](/zh-TW/agent-sdk/python#tool) Python 參考，以取得完整的參數詳細資訊，包括 JSON Schema 輸入格式和傳回值結構。

126

127<Tip>

128 若要使參數成為選用：在 TypeScript 中，將 `.default()` 新增至 Zod 欄位。在 Python 中，字典結構描述將每個鍵視為必需，因此請將參數留出結構描述，在描述字串中提及它，並在處理程式中使用 `args.get()` 讀取它。下面的 [`get_precipitation_chance` 工具](#add-more-tools)顯示兩種模式。

129</Tip>

130

131### 呼叫自訂工具

132

133透過 `mcpServers` 選項將您建立的 MCP 伺服器傳遞至 `query`。`mcpServers` 中的鍵成為每個工具的完全限定名稱中的 `{server_name}` 區段：`mcp__{server_name}__{tool_name}`。在 `allowedTools` 中列出該名稱，以便工具執行而不會出現權限提示。

134

135這些程式碼片段重複使用上面[範例](#weather-tool-example)中的 `weatherServer`，以詢問 Claude 特定位置的天氣。

136

137<CodeGroup>

138 ```python Python theme={null}

139 import asyncio

140 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

141

142

143 async def main():

144 options = ClaudeAgentOptions(

145 mcp_servers={"weather": weather_server},

146 allowed_tools=["mcp__weather__get_temperature"],

147 )

148

149 async for message in query(

150 prompt="What's the temperature in San Francisco?",

151 options=options,

152 ):

153 # ResultMessage is the final message after all tool calls complete

154 if isinstance(message, ResultMessage) and message.subtype == "success":

155 print(message.result)

156

157

158 asyncio.run(main())

159 ```

160

161 ```typescript TypeScript theme={null}

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

163

164 for await (const message of query({

165 prompt: "What's the temperature in San Francisco?",

166 options: {

167 mcpServers: { weather: weatherServer },

168 allowedTools: ["mcp__weather__get_temperature"]

169 }

170 })) {

171 // "result" is the final message after all tool calls complete

172 if (message.type === "result" && message.subtype === "success") {

173 console.log(message.result);

174 }

175 }

176 ```

177</CodeGroup>

178

179### 新增更多工具

180

181伺服器在其 `tools` 陣列中列出的工具一樣多。如果有多個工具在伺服器上，您可以在 `allowedTools` 中個別列出每個工具，或使用萬用字元 `mcp__weather__*` 來涵蓋伺服器公開的每個工具。

182

183下面的範例將第二個工具 `get_precipitation_chance` 新增至[天氣工具範例](#weather-tool-example)中的 `weatherServer`，並使用陣列中的兩個工具重建它。

184

185<CodeGroup>

186 ```python Python theme={null}

187 # Define a second tool for the same server

188 @tool(

189 "get_precipitation_chance",

190 "Get the hourly precipitation probability for a location. "

191 "Optionally pass 'hours' (1-24) to control how many hours to return.",

192 {"latitude": float, "longitude": float},

193 )

194 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:

195 # 'hours' isn't in the schema - read it with .get() to make it optional

196 hours = args.get("hours", 12)

197 async with httpx.AsyncClient() as client:

198 response = await client.get(

199 "https://api.open-meteo.com/v1/forecast",

200 params={

201 "latitude": args["latitude"],

202 "longitude": args["longitude"],

203 "hourly": "precipitation_probability",

204 "forecast_days": 1,

205 },

206 )

207 data = response.json()

208 chances = data["hourly"]["precipitation_probability"][:hours]

209

210 return {

211 "content": [

212 {

213 "type": "text",

214 "text": f"Next {hours} hours: {'%, '.join(map(str, chances))}%",

215 }

216 ]

217 }

218

219

220 # Rebuild the server with both tools in the array

221 weather_server = create_sdk_mcp_server(

222 name="weather",

223 version="1.0.0",

224 tools=[get_temperature, get_precipitation_chance],

225 )

226 ```

227

228 ```typescript TypeScript theme={null}

229 // Define a second tool for the same server

230 const getPrecipitationChance = tool(

231 "get_precipitation_chance",

232 "Get the hourly precipitation probability for a location",

233 {

234 latitude: z.number(),

235 longitude: z.number(),

236 hours: z

237 .number()

238 .int()

239 .min(1)

240 .max(24)

241 .default(12) // .default() makes the parameter optional

242 .describe("How many hours of forecast to return")

243 },

244 async (args) => {

245 const response = await fetch(

246 `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1`

247 );

248 const data: any = await response.json();

249 const chances = data.hourly.precipitation_probability.slice(0, args.hours);

250

251 return {

252 content: [{ type: "text", text: `Next ${args.hours} hours: ${chances.join("%, ")}%` }]

253 };

254 }

255 );

256

257 // Rebuild the server with both tools in the array

258 const weatherServer = createSdkMcpServer({

259 name: "weather",

260 version: "1.0.0",

261 tools: [getTemperature, getPrecipitationChance]

262 });

263 ```

264</CodeGroup>

265

266此陣列中的每個工具在每個回合都會消耗內容視窗空間。如果您定義了數十個工具，請參閱[工具搜尋](/zh-TW/agent-sdk/tool-search)以改為按需載入它們。

267

268### 新增工具註解

269

270[工具註解](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations)是描述工具行為方式的選用中繼資料。在 TypeScript 中將它們作為 `tool()` 協助程式的第五個引數傳遞，或在 Python 中透過 `@tool` 裝飾器的 `annotations` 關鍵字引數傳遞。所有提示欄位都是布林值。

271

272| 欄位 | 預設值 | 意義 |

273| :---------------- | :------ | :----------------------------- |

274| `readOnlyHint` | `false` | 工具不會修改其環境。控制工具是否可以與其他唯讀工具平行呼叫。 |

275| `destructiveHint` | `true` | 工具可能執行破壞性更新。僅供參考。 |

276| `idempotentHint` | `false` | 使用相同引數重複呼叫沒有額外效果。僅供參考。 |

277| `openWorldHint` | `true` | 工具到達程序外的系統。僅供參考。 |

278

279註解是中繼資料，不是強制執行。標記為 `readOnlyHint: true` 的工具如果處理程式執行該操作，仍然可以寫入磁碟。保持註解準確反映處理程式。

280

281此範例將 `readOnlyHint` 新增至[天氣工具範例](#weather-tool-example)中的 `get_temperature` 工具。

282

283<CodeGroup>

284 ```python Python theme={null}

285 from claude_agent_sdk import tool, ToolAnnotations

286

287

288 @tool(

289 "get_temperature",

290 "Get the current temperature at a location",

291 {"latitude": float, "longitude": float},

292 annotations=ToolAnnotations(

293 readOnlyHint=True

294 ), # Lets Claude batch this with other read-only calls

295 )

296 async def get_temperature(args):

297 return {"content": [{"type": "text", "text": "..."}]}

298 ```

299

300 ```typescript TypeScript theme={null}

301 tool(

302 "get_temperature",

303 "Get the current temperature at a location",

304 { latitude: z.number(), longitude: z.number() },

305 async (args) => ({ content: [{ type: "text", text: `...` }] }),

306 { annotations: { readOnlyHint: true } } // Lets Claude batch this with other read-only calls

307 );

308 ```

309</CodeGroup>

310

311請參閱 [TypeScript](/zh-TW/agent-sdk/typescript#toolannotations) 或 [Python](/zh-TW/agent-sdk/python#toolannotations) 參考中的 `ToolAnnotations`。

312

313## 控制工具存取

314

315[天氣工具範例](#weather-tool-example)註冊了伺服器並在 `allowedTools` 中列出了工具。本節涵蓋工具名稱的構造方式，以及當您有多個工具或想要限制內建工具時如何限制存取。

316

317### 工具名稱格式

318

319當 MCP 工具公開給 Claude 時，它們的名稱遵循特定格式：

320

321* 模式：`mcp__{server_name}__{tool_name}`

322* 範例：伺服器 `weather` 中名為 `get_temperature` 的工具變成 `mcp__weather__get_temperature`

323

324### 設定允許的工具

325

326`tools` 選項和允許/不允許清單在不同層級上運作。`tools` 控制哪些內建工具出現在 Claude 的內容中。允許和不允許工具清單控制 Claude 嘗試呼叫後是否核准或拒絕呼叫。

327

328| 選項 | 層級 | 效果 |

329| :------------------------ | :-- | :--------------------------------------------------------------------- |

330| `tools: ["Read", "Grep"]` | 可用性 | 只有列出的內建工具在 Claude 的內容中。未列出的內建工具會被移除。MCP 工具不受影響。 |

331| `tools: []` | 可用性 | 所有內建工具都被移除。Claude 只能使用您的 MCP 工具。 |

332| 允許的工具 | 權限 | 列出的工具執行時不會出現權限提示。未列出的工具保持可用；呼叫會通過[權限流程](/zh-TW/agent-sdk/permissions)。 |

333| 不允許的工具 | 權限 | 對列出的工具的每次呼叫都被拒絕。工具保留在 Claude 的內容中，因此 Claude 可能仍會在呼叫被拒絕之前嘗試它。 |

334

335若要限制 Claude 可以使用哪些內建工具，請優先使用 `tools` 而不是不允許的工具。從 `tools` 中省略工具會將其從內容中移除，以便 Claude 永遠不會嘗試它；在 `disallowedTools` 中列出它（Python：`disallowed_tools`）會阻止呼叫，但保留工具可見，因此 Claude 可能會浪費一個回合嘗試它。請參閱[設定權限](/zh-TW/agent-sdk/permissions)以取得完整的評估順序。

336

337## 處理錯誤

338

339您的處理程式報告錯誤的方式決定代理迴圈是繼續還是停止：

340

341| 發生的情況 | 結果 |

342| :---------------------------------------------------------- | :--------------------------------------- |

343| 處理程式擲出未捕獲的例外 | 代理迴圈停止。Claude 永遠看不到錯誤，`query` 呼叫失敗。 |

344| 處理程式捕獲錯誤並傳回 `isError: true`（TS）/ `"is_error": True`（Python） | 代理迴圈繼續。Claude 將錯誤視為資料並可以重試、嘗試不同的工具或解釋失敗。 |

345

346下面的範例在處理程式內捕獲兩種失敗，而不是讓它們擲出。非 200 HTTP 狀態從回應中捕獲並作為錯誤結果傳回。網路錯誤或無效 JSON 由周圍的 `try/except`（Python）或 `try/catch`（TypeScript）捕獲，也作為錯誤結果傳回。在兩種情況下，處理程式正常傳回，代理迴圈繼續。

347

348<CodeGroup>

349 ```python Python theme={null}

350 import json

351 import httpx

352 from typing import Any

353

354

355 @tool(

356 "fetch_data",

357 "Fetch data from an API",

358 {"endpoint": str}, # Simple schema

359 )

360 async def fetch_data(args: dict[str, Any]) -> dict[str, Any]:

361 try:

362 async with httpx.AsyncClient() as client:

363 response = await client.get(args["endpoint"])

364 if response.status_code != 200:

365 # Return the failure as a tool result so Claude can react to it.

366 # is_error marks this as a failed call rather than odd-looking data.

367 return {

368 "content": [

369 {

370 "type": "text",

371 "text": f"API error: {response.status_code} {response.reason_phrase}",

372 }

373 ],

374 "is_error": True,

375 }

376

377 data = response.json()

378 return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}

379 except Exception as e:

380 # Catching here keeps the agent loop alive. An uncaught exception

381 # would end the whole query() call.

382 return {

383 "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],

384 "is_error": True,

385 }

386 ```

387

388 ```typescript TypeScript theme={null}

389 tool(

390 "fetch_data",

391 "Fetch data from an API",

392 {

393 endpoint: z.string().url().describe("API endpoint URL")

394 },

395 async (args) => {

396 try {

397 const response = await fetch(args.endpoint);

398

399 if (!response.ok) {

400 // Return the failure as a tool result so Claude can react to it.

401 // isError marks this as a failed call rather than odd-looking data.

402 return {

403 content: [

404 {

405 type: "text",

406 text: `API error: ${response.status} ${response.statusText}`

407 }

408 ],

409 isError: true

410 };

411 }

412

413 const data = await response.json();

414 return {

415 content: [

416 {

417 type: "text",

418 text: JSON.stringify(data, null, 2)

419 }

420 ]

421 };

422 } catch (error) {

423 // Catching here keeps the agent loop alive. An uncaught throw

424 // would end the whole query() call.

425 return {

426 content: [

427 {

428 type: "text",

429 text: `Failed to fetch data: ${error instanceof Error ? error.message : String(error)}`

430 }

431 ],

432 isError: true

433 };

434 }

435 }

436 );

437 ```

438</CodeGroup>

439

440## 傳回影像和資源

441

442工具結果中的 `content` 陣列接受 `text`、`image` 和 `resource` 區塊。您可以在同一回應中混合它們。

443

444### 影像

445

446影像區塊以 base64 編碼的方式內聯攜帶影像位元組。沒有 URL 欄位。若要傳回位於 URL 的影像，請在處理程式中擷取它、讀取回應位元組，並在傳回前進行 base64 編碼。結果作為視覺輸入進行處理。

447

448| 欄位 | 類型 | 備註 |

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

450| `type` | `"image"` | |

451| `data` | `string` | Base64 編碼的位元組。僅原始 base64，沒有 `data:image/...;base64,` 前綴 |

452| `mimeType` | `string` | 必需。例如 `image/png`、`image/jpeg`、`image/webp`、`image/gif` |

453

454<CodeGroup>

455 ```python Python theme={null}

456 import base64

457 import httpx

458

459

460 # Define a tool that fetches an image from a URL and returns it to Claude

461 @tool("fetch_image", "Fetch an image from a URL and return it to Claude", {"url": str})

462 async def fetch_image(args):

463 async with httpx.AsyncClient() as client: # Fetch the image bytes

464 response = await client.get(args["url"])

465

466 return {

467 "content": [

468 {

469 "type": "image",

470 "data": base64.b64encode(response.content).decode(

471 "ascii"

472 ), # Base64-encode the raw bytes

473 "mimeType": response.headers.get(

474 "content-type", "image/png"

475 ), # Read MIME type from the response

476 }

477 ]

478 }

479 ```

480

481 ```typescript TypeScript theme={null}

482 tool(

483 "fetch_image",

484 "Fetch an image from a URL and return it to Claude",

485 {

486 url: z.string().url()

487 },

488 async (args) => {

489 const response = await fetch(args.url); // Fetch the image bytes

490 const buffer = Buffer.from(await response.arrayBuffer()); // Read into a Buffer for base64 encoding

491 const mimeType = response.headers.get("content-type") ?? "image/png";

492

493 return {

494 content: [

495 {

496 type: "image",

497 data: buffer.toString("base64"), // Base64-encode the raw bytes

498 mimeType

499 }

500 ]

501 };

502 }

503 );

504 ```

505</CodeGroup>

506

507### 資源

508

509資源區塊嵌入由 URI 識別的內容片段。URI 是 Claude 參考的標籤；實際內容位於區塊的 `text` 或 `blob` 欄位中。當您的工具產生稍後按名稱尋址有意義的內容時使用此項，例如生成的檔案或來自外部系統的記錄。

510

511| 欄位 | 類型 | 備註 |

512| :------------------ | :----------- | :----------------------------- |

513| `type` | `"resource"` | |

514| `resource.uri` | `string` | 內容的識別碼。任何 URI 配置 |

515| `resource.text` | `string` | 內容，如果是文字。提供此項或 `blob`，不要同時提供兩者 |

516| `resource.blob` | `string` | 內容 base64 編碼，如果是二進位 |

517| `resource.mimeType` | `string` | 選用 |

518

519此範例顯示從工具處理程式內傳回的資源區塊。URI `file:///tmp/report.md` 是 Claude 稍後可以參考的標籤；SDK 不會從該路徑讀取。

520

521<CodeGroup>

522 ```typescript TypeScript theme={null}

523 return {

524 content: [

525 {

526 type: "resource",

527 resource: {

528 uri: "file:///tmp/report.md", // Label for Claude to reference, not a path the SDK reads

529 mimeType: "text/markdown",

530 text: "# Report\n..." // The actual content, inline

531 }

532 }

533 ]

534 };

535 ```

536

537 ```python Python theme={null}

538 return {

539 "content": [

540 {

541 "type": "resource",

542 "resource": {

543 "uri": "file:///tmp/report.md", # Label for Claude to reference, not a path the SDK reads

544 "mimeType": "text/markdown",

545 "text": "# Report\n...", # The actual content, inline

546 },

547 }

548 ]

549 }

550 ```

551</CodeGroup>

552

553這些區塊形狀來自 MCP `CallToolResult` 類型。請參閱 [MCP 規格](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result)以取得完整定義。

554

555## 傳回結構化資料

556

557`structuredContent` 是結果上的選用 JSON 物件，與 `content` 陣列分開。使用它傳回原始值，Claude 可以將其讀取為確切欄位，而不是從文字字串或影像中解析它們。

558

559設定 `structuredContent` 時，Claude 接收 JSON 加上 `content` 中的任何影像或資源區塊。`content` 中的文字區塊不會轉發，因為假設它們複製結構化資料。下面的範例將圖表呈現為影像區塊，並從同一處理程式在 `structuredContent` 中傳回其背後的資料點。

560

561```typescript TypeScript theme={null}

562return {

563 content: [

564 {

565 type: "image",

566 data: chartPngBuffer.toString("base64"),

567 mimeType: "image/png"

568 }

569 ],

570 structuredContent: {

571 series: "temperature_2m",

572 unit: "fahrenheit",

573 points: [62.1, 63.4, 65.0, 64.2]

574 }

575};

576```

577

578<Note>

579 Python `@tool` 裝飾器僅從處理程式的傳回字典轉發 `content` 和 `is_error`。若要從 Python 傳回 `structuredContent`，請改為執行[獨立 MCP 伺服器](/zh-TW/agent-sdk/mcp)。

580</Note>

581

582## 範例：單位轉換器

583

584此工具在長度、溫度和重量的單位之間轉換值。使用者可以詢問「將 100 公里轉換為英里」或「72°F 是多少攝氏度」，Claude 從請求中選擇正確的單位類型和單位。

585

586它演示了兩種模式：

587

588* **列舉結構描述：** `unit_type` 受限於一組固定值。在 TypeScript 中，使用 `z.enum()`。在 Python 中，字典結構描述不支援列舉，因此需要完整的 JSON Schema 字典。

589* **不支援的輸入處理：** 當找不到轉換對時，處理程式傳回 `isError: true`，以便 Claude 可以告訴使用者出了什麼問題，而不是將失敗視為正常結果。

590

591<CodeGroup>

592 ```python Python theme={null}

593 from typing import Any

594 from claude_agent_sdk import tool, create_sdk_mcp_server

595

596

597 # z.enum() in TypeScript becomes an "enum" constraint in JSON Schema.

598 # The dict schema has no equivalent, so full JSON Schema is required.

599 @tool(

600 "convert_units",

601 "Convert a value from one unit to another",

602 {

603 "type": "object",

604 "properties": {

605 "unit_type": {

606 "type": "string",

607 "enum": ["length", "temperature", "weight"],

608 "description": "Category of unit",

609 },

610 "from_unit": {

611 "type": "string",

612 "description": "Unit to convert from, e.g. kilometers, fahrenheit, pounds",

613 },

614 "to_unit": {"type": "string", "description": "Unit to convert to"},

615 "value": {"type": "number", "description": "Value to convert"},

616 },

617 "required": ["unit_type", "from_unit", "to_unit", "value"],

618 },

619 )

620 async def convert_units(args: dict[str, Any]) -> dict[str, Any]:

621 conversions = {

622 "length": {

623 "kilometers_to_miles": lambda v: v * 0.621371,

624 "miles_to_kilometers": lambda v: v * 1.60934,

625 "meters_to_feet": lambda v: v * 3.28084,

626 "feet_to_meters": lambda v: v * 0.3048,

627 },

628 "temperature": {

629 "celsius_to_fahrenheit": lambda v: (v * 9) / 5 + 32,

630 "fahrenheit_to_celsius": lambda v: (v - 32) * 5 / 9,

631 "celsius_to_kelvin": lambda v: v + 273.15,

632 "kelvin_to_celsius": lambda v: v - 273.15,

633 },

634 "weight": {

635 "kilograms_to_pounds": lambda v: v * 2.20462,

636 "pounds_to_kilograms": lambda v: v * 0.453592,

637 "grams_to_ounces": lambda v: v * 0.035274,

638 "ounces_to_grams": lambda v: v * 28.3495,

639 },

640 }

641

642 key = f"{args['from_unit']}_to_{args['to_unit']}"

643 fn = conversions.get(args["unit_type"], {}).get(key)

644

645 if not fn:

646 return {

647 "content": [

648 {

649 "type": "text",

650 "text": f"Unsupported conversion: {args['from_unit']} to {args['to_unit']}",

651 }

652 ],

653 "is_error": True,

654 }

655

656 result = fn(args["value"])

657 return {

658 "content": [

659 {

660 "type": "text",

661 "text": f"{args['value']} {args['from_unit']} = {result:.4f} {args['to_unit']}",

662 }

663 ]

664 }

665

666

667 converter_server = create_sdk_mcp_server(

668 name="converter",

669 version="1.0.0",

670 tools=[convert_units],

671 )

672 ```

673

674 ```typescript TypeScript theme={null}

675 import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

676 import { z } from "zod";

677

678 const convert = tool(

679 "convert_units",

680 "Convert a value from one unit to another",

681 {

682 unit_type: z.enum(["length", "temperature", "weight"]).describe("Category of unit"),

683 from_unit: z

684 .string()

685 .describe("Unit to convert from, e.g. kilometers, fahrenheit, pounds"),

686 to_unit: z.string().describe("Unit to convert to"),

687 value: z.number().describe("Value to convert")

688 },

689 async (args) => {

690 type Conversions = Record<string, Record<string, (v: number) => number>>;

691

692 const conversions: Conversions = {

693 length: {

694 kilometers_to_miles: (v) => v * 0.621371,

695 miles_to_kilometers: (v) => v * 1.60934,

696 meters_to_feet: (v) => v * 3.28084,

697 feet_to_meters: (v) => v * 0.3048

698 },

699 temperature: {

700 celsius_to_fahrenheit: (v) => (v * 9) / 5 + 32,

701 fahrenheit_to_celsius: (v) => ((v - 32) * 5) / 9,

702 celsius_to_kelvin: (v) => v + 273.15,

703 kelvin_to_celsius: (v) => v - 273.15

704 },

705 weight: {

706 kilograms_to_pounds: (v) => v * 2.20462,

707 pounds_to_kilograms: (v) => v * 0.453592,

708 grams_to_ounces: (v) => v * 0.035274,

709 ounces_to_grams: (v) => v * 28.3495

710 }

711 };

712

713 const key = `${args.from_unit}_to_${args.to_unit}`;

714 const fn = conversions[args.unit_type]?.[key];

715

716 if (!fn) {

717 return {

718 content: [

719 {

720 type: "text",

721 text: `Unsupported conversion: ${args.from_unit} to ${args.to_unit}`

722 }

723 ],

724 isError: true

725 };

726 }

727

728 const result = fn(args.value);

729 return {

730 content: [

731 {

732 type: "text",

733 text: `${args.value} ${args.from_unit} = ${result.toFixed(4)} ${args.to_unit}`

734 }

735 ]

736 };

737 }

738 );

739

740 const converterServer = createSdkMcpServer({

741 name: "converter",

742 version: "1.0.0",

743 tools: [convert]

744 });

745 ```

746</CodeGroup>

747

748定義伺服器後，以與天氣範例相同的方式將其傳遞至 `query`。此範例在迴圈中傳送三個不同的提示，以顯示同一工具處理不同的單位類型。對於每個回應，它檢查 `AssistantMessage` 物件（包含 Claude 在該回合期間進行的工具呼叫）並在列印最終 `ResultMessage` 文字之前列印每個 `ToolUseBlock`。這讓您看到 Claude 何時使用工具與從自己的知識回答。

749

750<CodeGroup>

751 ```python Python theme={null}

752 import asyncio

753 from claude_agent_sdk import (

754 query,

755 ClaudeAgentOptions,

756 ResultMessage,

757 AssistantMessage,

758 ToolUseBlock,

759 )

760

761

762 async def main():

763 options = ClaudeAgentOptions(

764 mcp_servers={"converter": converter_server},

765 allowed_tools=["mcp__converter__convert_units"],

766 )

767

768 prompts = [

769 "Convert 100 kilometers to miles.",

770 "What is 72°F in Celsius?",

771 "How many pounds is 5 kilograms?",

772 ]

773

774 for prompt in prompts:

775 async for message in query(prompt=prompt, options=options):

776 if isinstance(message, AssistantMessage):

777 for block in message.content:

778 if isinstance(block, ToolUseBlock):

779 print(f"[tool call] {block.name}({block.input})")

780 elif isinstance(message, ResultMessage) and message.subtype == "success":

781 print(f"Q: {prompt}\nA: {message.result}\n")

782

783

784 asyncio.run(main())

785 ```

786

787 ```typescript TypeScript theme={null}

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

789

790 const prompts = [

791 "Convert 100 kilometers to miles.",

792 "What is 72°F in Celsius?",

793 "How many pounds is 5 kilograms?"

794 ];

795

796 for (const prompt of prompts) {

797 for await (const message of query({

798 prompt,

799 options: {

800 mcpServers: { converter: converterServer },

801 allowedTools: ["mcp__converter__convert_units"]

802 }

803 })) {

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

805 for (const block of message.message.content) {

806 if (block.type === "tool_use") {

807 console.log(`[tool call] ${block.name}`, block.input);

808 }

809 }

810 } else if (message.type === "result" && message.subtype === "success") {

811 console.log(`Q: ${prompt}\nA: ${message.result}\n`);

812 }

813 }

814 }

815 ```

816</CodeGroup>

817

818## 後續步驟

819

820自訂工具在標準介面中包裝非同步函數。您可以在同一伺服器中混合本頁上的模式：單一伺服器可以並排保存資料庫工具、API 閘道工具和影像呈現器。

821

822從這裡：

823

824* 如果您的伺服器增長到數十個工具，請參閱[工具搜尋](/zh-TW/agent-sdk/tool-search)以延遲載入它們，直到 Claude 需要它們。

825* 若要連接到外部 MCP 伺服器（檔案系統、GitHub、Slack）而不是建立自己的，請參閱[連接 MCP 伺服器](/zh-TW/agent-sdk/mcp)。

826* 若要控制哪些工具自動執行與需要核准，請參閱[設定權限](/zh-TW/agent-sdk/permissions)。

827

828## 相關文件

829

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

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

832* [MCP 文件](https://modelcontextprotocol.io)

833* [SDK 概觀](/zh-TW/agent-sdk/overview)

agent-sdk/python.md +46 −7

Details

757 allowed_tools: list[str] = field(default_factory=list)757 allowed_tools: list[str] = field(default_factory=list)

758 system_prompt: str | SystemPromptPreset | None = None758 system_prompt: str | SystemPromptPreset | None = None

759 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)759 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)

760 strict_mcp_config: bool = False

760 permission_mode: PermissionMode | None = None761 permission_mode: PermissionMode | None = None

761 continue_conversation: bool = False762 continue_conversation: bool = False

762 resume: str | None = None763 resume: str | None = None

781 hooks: dict[HookEvent, list[HookMatcher]] | None = None782 hooks: dict[HookEvent, list[HookMatcher]] | None = None

782 user: str | None = None783 user: str | None = None

783 include_partial_messages: bool = False784 include_partial_messages: bool = False

785 include_hook_events: bool = False

784 fork_session: bool = False786 fork_session: bool = False

785 agents: dict[str, AgentDefinition] | None = None787 agents: dict[str, AgentDefinition] | None = None

786 setting_sources: list[SettingSource] | None = None788 setting_sources: list[SettingSource] | None = None

788 plugins: list[SdkPluginConfig] = field(default_factory=list)790 plugins: list[SdkPluginConfig] = field(default_factory=list)

789 max_thinking_tokens: int | None = None # Deprecated: use thinking instead791 max_thinking_tokens: int | None = None # Deprecated: use thinking instead

790 thinking: ThinkingConfig | None = None792 thinking: ThinkingConfig | None = None

791 effort: Literal["low", "medium", "high", "max"] | None = None793 effort: Literal["low", "medium", "high", "xhigh", "max"] | None = None

792 enable_file_checkpointing: bool = False794 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None795 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"796 session_store_flush: SessionStoreFlushMode = "batched"

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

801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 系統提示配置。傳遞字串以取得自訂提示，或使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示。新增 `"append"` 以擴展預設 |803| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 系統提示配置。傳遞字串以取得自訂提示，或使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示。新增 `"append"` 以擴展預設 |

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

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

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

838 842

843#### 處理緩慢或停滯的 API 回應

844

845CLI 子程序讀取多個環境變數，控制 API 逾時和停滯偵測。透過 `ClaudeAgentOptions.env` 傳遞它們：

846

847```python theme={null}

848options = ClaudeAgentOptions(

849 env={

850 "API_TIMEOUT_MS": "120000",

851 "CLAUDE_CODE_MAX_RETRIES": "2",

852 "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "120000",

853 },

854)

855```

856

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

858* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。預設 `10`。每次重試都有自己的 `API_TIMEOUT_MS` 視窗，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。

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

860* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但回應本體停止串流時中止請求。預設關閉。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000` 並限制在該最小值。中止的請求會經過正常重試路徑。

861

839### `OutputFormat`862### `OutputFormat`

840 863

841結構化輸出驗證的配置。將此作為 `dict` 傳遞給 `ClaudeAgentOptions` 上的 `output_format` 欄位：864結構化輸出驗證的配置。將此作為 `dict` 傳遞給 `ClaudeAgentOptions` 上的 `output_format` 欄位：

1015 initialPrompt: str | None = None1038 initialPrompt: str | None = None

1016 maxTurns: int | None = None1039 maxTurns: int | None = None

1017 background: bool | None = None1040 background: bool | None = None

1018 effort: Literal["low", "medium", "high", "max"] | int | None = None1041 effort: Literal["low", "medium", "high", "xhigh", "max"] | int | None = None

1019 permissionMode: PermissionMode | None = None1042 permissionMode: PermissionMode | None = None

1020```1043```

1021 1044

1080class ToolPermissionContext:1103class ToolPermissionContext:

1081 signal: Any | None = None # Future: abort signal support1104 signal: Any | None = None # Future: abort signal support

1082 suggestions: list[PermissionUpdate] = field(default_factory=list)1105 suggestions: list[PermissionUpdate] = field(default_factory=list)

1106 blocked_path: str | None = None

1107 decision_reason: str | None = None

1108 title: str | None = None

1109 display_name: str | None = None

1110 description: str | None = None

1083```1111```

1084 1112

1085| 欄位 | 類型 | 描述 |1113| 欄位 | 類型 | 描述 |

1086| :------------ | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |1114| :---------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |

1088| `suggestions` | `list[PermissionUpdate]` | 來自 CLI 的權限更新建議。Bash 提示包括具有 `localSettings` 目的地的建議，因此在 `updated_permissions` 中返回它會將規則寫入 `.claude/settings.local.json` 並在 sessions 中持久化。 |1116| `suggestions` | `list[PermissionUpdate]` | 來自 CLI 的權限更新建議。Bash 提示包括具有 `localSettings` 目的地的建議，因此在 `updated_permissions` 中返回它會將規則寫入 `.claude/settings.local.json` 並在 sessions 中持久化。 |

1089 1122

1090### `PermissionResult`1123### `PermissionResult`

1091 1124

1466 is_error: bool1499 is_error: bool

1467 num_turns: int1500 num_turns: int

1468 session_id: str1501 session_id: str

1502 stop_reason: str | None = None

1469 total_cost_usd: float | None = None1503 total_cost_usd: float | None = None

1470 usage: dict[str, Any] | None = None1504 usage: dict[str, Any] | None = None

1471 result: str | None = None1505 result: str | None = None

1472 stop_reason: str | None = None

1473 structured_output: Any = None1506 structured_output: Any = None

1474 model_usage: dict[str, Any] | None = None1507 model_usage: dict[str, Any] | None = None

1508 permission_denials: list[Any] | None = None

1509 deferred_tool_use: DeferredToolUse | None = None

1510 errors: list[str] | None = None

1511 api_error_status: int | None = None

1512 uuid: str | None = None

1475```1513```

1476 1514

1477`usage` 字典在出現時包含以下鍵：1515`usage` 字典在出現時包含以下鍵：

2128```python theme={null}2166```python theme={null}

2129class PreToolUseHookSpecificOutput(TypedDict):2167class PreToolUseHookSpecificOutput(TypedDict):

2130 hookEventName: Literal["PreToolUse"]2168 hookEventName: Literal["PreToolUse"]

2131 permissionDecision: NotRequired[Literal["allow", "deny", "ask"]]2169 permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]]

2132 permissionDecisionReason: NotRequired[str]2170 permissionDecisionReason: NotRequired[str]

2133 updatedInput: NotRequired[dict[str, Any]]2171 updatedInput: NotRequired[dict[str, Any]]

2134 additionalContext: NotRequired[str]2172 additionalContext: NotRequired[str]

2137class PostToolUseHookSpecificOutput(TypedDict):2175class PostToolUseHookSpecificOutput(TypedDict):

2138 hookEventName: Literal["PostToolUse"]2176 hookEventName: Literal["PostToolUse"]

2139 additionalContext: NotRequired[str]2177 additionalContext: NotRequired[str]

2178 updatedToolOutput: NotRequired[Any]

2140 updatedMCPToolOutput: NotRequired[Any]2179 updatedMCPToolOutput: NotRequired[Any]

2141 2180

2142 2181

agent-sdk/typescript.md +58 −9

Details

8 8

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

10 10

~~11<Note>~~

12 **試試新的 V2 介面（預覽版）：** 現在提供了一個簡化的介面，具有 `send()` 和 `stream()` 模式，使多輪對話更容易。[了解更多關於 TypeScript V2 預覽版](/zh-TW/agent-sdk/typescript-v2-preview)

~~13</Note>~~

15## 安裝11## 安裝

16 12

17```bash theme={null}13```bash theme={null}

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

363| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默認值（所有源） | 控制加載哪些文件系統設置。傳遞 `[]` 以禁用用戶、項目和本地設置。無論如何都會加載託管策略設置。見 [使用 Claude Code 功能](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |360| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默認值（所有源） | 控制加載哪些文件系統設置。傳遞 `[]` 以禁用用戶、項目和本地設置。無論如何都會加載託管策略設置。見 [使用 Claude Code 功能](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置。傳遞工具名稱數組或使用預設以獲得 Claude Code 的默認工具 |367| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置。傳遞工具名稱數組或使用預設以獲得 Claude Code 的默認工具 |

371 368

369#### 處理緩慢或停滯的 API 響應

370

371CLI 子進程讀取多個環境變量，這些變量控制 API 超時和停滯檢測。通過 `env` 選項傳遞它們：

372

373```typescript theme={null}

374const result = query({

375 prompt: "Analyze this code",

376 options: {

377 env: {

378 ...process.env,

379 API_TIMEOUT_MS: "120000",

380 CLAUDE_CODE_MAX_RETRIES: "2",

381 CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000",

382 },

383 },

384});

385```

386

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

388* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。默認 `10`。每次重試都有自己的 `API_TIMEOUT_MS` 窗口，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。

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

390* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但響應正文停止流式傳輸時中止請求。默認關閉。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默認為 `300000` 並被限制為該最小值。中止的請求通過正常重試路徑進行。

391

372### `Query` 對象392### `Query` 對象

373 393

374由 `query()` 函數返回的介面。394由 `query()` 函數返回的介面。

383 setPermissionMode(mode: PermissionMode): Promise<void>;403 setPermissionMode(mode: PermissionMode): Promise<void>;

384 setModel(model?: string): Promise<void>;404 setModel(model?: string): Promise<void>;

385 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;405 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;

406 applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;

386 initializationResult(): Promise<SDKControlInitializeResponse>;407 initializationResult(): Promise<SDKControlInitializeResponse>;

387 supportedCommands(): Promise<SlashCommand[]>;408 supportedCommands(): Promise<SlashCommand[]>;

388 supportedModels(): Promise<ModelInfo[]>;409 supportedModels(): Promise<ModelInfo[]>;

431| `applyFlagSettings(settings)` | 在運行時將設置合併到會話的標誌設置層中（僅在流式輸入模式下可用）。見 [`applyFlagSettings()`](#applyflagsettings) |

422 444

445#### `applyFlagSettings()`

446

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

448

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

450

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

452

453僅在流式輸入模式下可用，與 `setModel()` 和 `setPermissionMode()` 的約束相同。

454

455下面的示例在會話中期切換活動模型，然後清除覆蓋，以便模型回退到用戶或項目設置指定的任何內容。

456

457```typescript theme={null}

458const q = query({ prompt: messageStream });

459

460// 覆蓋會話其餘部分的模型

461await q.applyFlagSettings({ model: "claude-opus-4-6" });

462

463// 稍後：清除覆蓋並回退到較低優先級設置

464await q.applyFlagSettings({ model: null });

465```

466

467<Note>

468 `applyFlagSettings()` 僅適用於 TypeScript。Python SDK 不公開等效方法。

469</Note>

470

423### `WarmQuery`471### `WarmQuery`

424 472

425由 [`startup()`](#startup) 返回的句柄。子進程已生成並初始化，因此在此句柄上調用 `query()` 會直接將提示寫入準備好的進程，無需啟動延遲。473由 [`startup()`](#startup) 返回的句柄。子進程已生成並初始化，因此在此句柄上調用 `query()` 會直接將提示寫入準備好的進程，無需啟動延遲。

6172. 項目設置（`.claude/settings.json`）6652. 項目設置（`.claude/settings.json`）

6183. 用戶設置（`~/.claude/settings.json`）6663. 用戶設置（`~/.claude/settings.json`）

619 667

620編程選項（如 `agents` 和 `allowedTools`）覆蓋用戶、項目和本地文件系統設置。託管策略設置優先於編程選項。668編程選項（如 `agents`、`allowedTools` 和 `settings`）覆蓋用戶、項目和本地文件系統設置。託管策略設置優先於編程選項。

621 669

622### `PermissionMode`670### `PermissionMode`

623 671

626 | "default" // 標準權限行為674 | "default" // 標準權限行為

627 | "acceptEdits" // 自動接受文件編輯675 | "acceptEdits" // 自動接受文件編輯

628 | "bypassPermissions" // 繞過所有權限檢查676 | "bypassPermissions" // 繞過所有權限檢查

629 | "plan" // 規劃模式 - 無執行677 | "plan" // 規劃模式 - 僅讀取工具

630 | "dontAsk" // 不提示權限，如果未預批准則拒絕678 | "dontAsk" // 不提示權限，如果未預批准則拒絕

631 | "auto"; // 使用模型分類器批准或拒絕每個工具調用679 | "auto"; // 使用模型分類器批准或拒絕每個工具調用

632```680```

2443 2491

2444### `CallToolResult`2492### `CallToolResult`

2445 2493

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

2447 2495

2448```typescript theme={null}2496```typescript theme={null}

2449type CallToolResult = {2497type CallToolResult = {

2451 type: "text" | "image" | "resource";2499 type: "text" | "image" | "resource";

2452 // 其他字段因類型而異2500 // 其他字段因類型而異

2453 }>;2501 }>;

2502 structuredContent?: Record<string, unknown>;

2454 isError?: boolean;2503 isError?: boolean;

2455};2504};

2456```2505```

amazon-bedrock.md +11 −1

Details

361 361

362```bash theme={null}362```bash theme={null}

363# 使用推論設定檔 ID363# 使用推論設定檔 ID

364export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'364export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'

365export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'365export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

366 366

367# 使用應用程式推論設定檔 ARN367# 使用應用程式推論設定檔 ARN

462 462

463[設定精靈](#sign-in-with-bedrock)在固定模型時提供 1M 內容選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。請參閱[為第三方部署固定模型](/zh-TW/model-config#pin-models-for-third-party-deployments)以取得詳細資訊。463[設定精靈](#sign-in-with-bedrock)在固定模型時提供 1M 內容選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。請參閱[為第三方部署固定模型](/zh-TW/model-config#pin-models-for-third-party-deployments)以取得詳細資訊。

464 464

465## 服務層級

466

467[Amazon Bedrock 服務層級](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)可讓您在成本和延遲之間進行權衡。將 `ANTHROPIC_BEDROCK_SERVICE_TIER` 設定為 `default`、`flex` 或 `priority`：

468

469```bash theme={null}

470export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

471```

472

473Claude Code 在每個請求上將此作為 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。層級可用性因模型和區域而異。保留容量使用[佈建輸送量](https://docs.aws.amazon.com/bedrock/latest/userguide/prov-throughput.html) ARN 作為模型 ID，而不是此設定。

474

465## AWS Guardrails475## AWS Guardrails

466 476

467[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) 可讓您為 Claude Code 實施內容篩選。在 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)中建立 Guardrail，發佈版本，然後將 Guardrail 標頭新增至您的[設定檔](/zh-TW/settings)。如果您使用跨區域推論設定檔，請在 Guardrail 上啟用跨區域推論。477[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) 可讓您為 Claude Code 實施內容篩選。在 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)中建立 Guardrail，發佈版本，然後將 Guardrail 標頭新增至您的[設定檔](/zh-TW/settings)。如果您使用跨區域推論設定檔，請在 Guardrail 上啟用跨區域推論。

authentication.md +6 −1

Details

113 113

114Claude Code 安全地管理您的驗證認證：114Claude Code 安全地管理您的驗證認證：

115 115

116* **儲存位置**：在 macOS 上，認證儲存在加密的 macOS Keychain 中。在 Linux 和 Windows 上，認證儲存在 `~/.claude/.credentials.json` 中，或在設定了 `$CLAUDE_CONFIG_DIR` 變數時儲存在該位置下。在 Linux 上，檔案以模式 `0600` 寫入；在 Windows 上，它繼承您的使用者設定檔目錄的存取控制。116* **儲存位置**：

117 * 在 macOS 上，認證儲存在加密的 macOS Keychain 中。

118 * 在 Linux 上，認證儲存在 `~/.claude/.credentials.json` 中，檔案模式為 `0600`。

119 * 在 Windows 上，認證儲存在 `%USERPROFILE%\.claude\.credentials.json` 中，並繼承您的使用者設定檔目錄的存取控制，預設情況下將檔案限制為您的使用者帳戶。

120 * 如果您在 Linux 或 Windows 上設定了 `CLAUDE_CONFIG_DIR` 環境變數，`.credentials.json` 檔案將位於該目錄下。

121 * Claude Code 透過 `/login` 和 `/logout` 管理 `.credentials.json`。若要透過自訂 API 端點路由請求，請改為設定 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 環境變數。

117* **支援的驗證類型**：Claude.ai 認證、Claude API 認證、Azure Auth、Bedrock Auth 和 Vertex Auth。122* **支援的驗證類型**：Claude.ai 認證、Claude API 認證、Azure Auth、Bedrock Auth 和 Vertex Auth。

118* **自訂認證指令碼**：[`apiKeyHelper`](/zh-TW/settings#available-settings) 設定可以配置為執行傳回 API 金鑰的 shell 指令碼。123* **自訂認證指令碼**：[`apiKeyHelper`](/zh-TW/settings#available-settings) 設定可以配置為執行傳回 API 金鑰的 shell 指令碼。

119* **重新整理間隔**：根據預設，`apiKeyHelper` 在 5 分鐘後或在 HTTP 401 回應時呼叫。設定 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 環境變數以自訂重新整理間隔。124* **重新整理間隔**：根據預設，`apiKeyHelper` 在 5 分鐘後或在 HTTP 401 回應時呼叫。設定 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 環境變數以自訂重新整理間隔。

claude-code-on-the-web.md +38 −3

Details

113 113

114每個雲端工作階段在 claude.ai 上都有一個成績單 URL，工作階段可以從 `CLAUDE_CODE_REMOTE_SESSION_ID` 環境變數讀取自己的 ID。使用此在 PR 正文、提交訊息、Slack 貼文或生成的報告中放置可追蹤的連結，以便審查者可以開啟產生它們的執行。114每個雲端工作階段在 claude.ai 上都有一個成績單 URL，工作階段可以從 `CLAUDE_CODE_REMOTE_SESSION_ID` 環境變數讀取自己的 ID。使用此在 PR 正文、提交訊息、Slack 貼文或生成的報告中放置可追蹤的連結，以便審查者可以開啟產生它們的執行。

115 115

116要求 Claude 從環境變數構造連結。以下命令列印 URL：116變數的值使用 `cse_` 前綴，而成績單 URL 路徑採用相同的 ID，但使用 `session_` 前綴。建立連結時替換前綴。以下命令列印 URL：

117 117

118```bash theme={null}118```bash theme={null}

119echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}"119echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

120```120```

121 121

122### 執行測試、啟動服務和新增套件122### 執行測試、啟動服務和新增套件

156| 操作 | 方式 |156| 操作 | 方式 |

157| :----------------- | :-------------------------------------------------------------------------------- |157| :----------------- | :-------------------------------------------------------------------------------- |

158| 新增環境 | 選擇目前環境以開啟選擇器，然後選擇**新增環境**。對話框包括名稱、網路存取級別、環境變數和設定指令碼。 |158| 新增環境 | 選擇目前環境以開啟選擇器，然後選擇**新增環境**。對話框包括名稱、網路存取級別、環境變數和設定指令碼。 |

159| 編輯環境 | 選擇環境名稱右側的設定圖示。 |159| 編輯環境 | 選擇顯示目前環境名稱的雲端圖示以開啟選擇器，將滑鼠懸停在環境上，然後按一下右側出現的設定圖示。 |

160| 封存環境 | 開啟環境進行編輯並選擇**封存**。封存的環境隱藏在選擇器中，但現有工作階段繼續執行。 |160| 封存環境 | 開啟環境進行編輯並選擇**封存**。封存的環境隱藏在選擇器中，但現有工作階段繼續執行。 |

162 162

185 185

186如果指令碼以非零值退出，工作階段將無法啟動。將 `|| true` 附加到非關鍵命令以避免在不穩定的安裝失敗時阻止工作階段。186如果指令碼以非零值退出，工作階段將無法啟動。將 `|| true` 附加到非關鍵命令以避免在不穩定的安裝失敗時阻止工作階段。

187 187

188保持指令碼的總執行時間在大約五分鐘以下，以便[環境快取](#environment-caching)可以建置。使用 `&` 和 `wait` 並行執行獨立安裝。如果單一下載無法在五分鐘限制內完成，請將其移動到在背景啟動它的 [SessionStart hook](#setup-scripts-vs-sessionstart-hooks)。

189

188<Note>190<Note>

189 安裝套件的設定指令碼需要網路存取才能到達登錄。預設**信任**網路存取允許連接到[常見套件登錄](#default-allowed-domains)，包括 npm、PyPI、RubyGems 和 crates.io。如果您的環境使用**無**網路存取，指令碼將無法安裝套件。191 安裝套件的設定指令碼需要網路存取才能到達登錄。預設**信任**網路存取允許連接到[常見套件登錄](#default-allowed-domains)，包括 npm、PyPI、RubyGems 和 crates.io。如果您的環境使用**無**網路存取，指令碼將無法安裝套件。

190</Note>192</Note>

265 267

266網路存取控制來自雲端環境的出站連接。每個環境指定一個存取級別，您可以使用自訂允許的域擴展它。預設值為**信任**，允許套件登錄和其他[允許清單域](#default-allowed-domains)。268網路存取控制來自雲端環境的出站連接。每個環境指定一個存取級別，您可以使用自訂允許的域擴展它。預設值為**信任**，允許套件登錄和其他[允許清單域](#default-allowed-domains)。

267 269

270若要更改環境的網路存取，請[開啟它進行編輯](#configure-your-environment)並在對話框中使用**網路存取**選擇器。沒有單獨的環境頁面。雲端圖示出現在您啟動雲端工作階段或配置[例行工作](/zh-TW/routines#environments-and-network-access)的任何地方。

271

272<Note>

273 MCP 連接器流量通過 Anthropic 的伺服器路由，因此您在工作階段或例行工作上啟用的連接器無需將其主機新增到**允許的域**即可工作。連接器按工作階段或按例行工作配置；移除您不需要的任何連接器以限制 Claude 可以到達的工具。這依賴於[安全性和隔離](#security-and-isolation)下提到的相同 Anthropic 綁定通道。

274</Note>

275

268### 存取級別276### 存取級別

269 277

270在建立或編輯環境時選擇存取級別：278在建立或編輯環境時選擇存取級別：

754* **認證保護**：敏感認證（如 git 認證或簽署金鑰）永遠不在沙箱內與 Claude Code 一起。驗證通過使用限定認證的安全代理進行處理。762* **認證保護**：敏感認證（如 git 認證或簽署金鑰）永遠不在沙箱內與 Claude Code 一起。驗證通過使用限定認證的安全代理進行處理。

755* **安全分析**：程式碼在隔離的 VM 內進行分析和修改，然後建立 PR763* **安全分析**：程式碼在隔離的 VM 內進行分析和修改，然後建立 PR

756 764

765## 故障排除

766

767對於出現在對話中的執行時 API 錯誤，例如 `API Error: 500`、`529 Overloaded`、`429` 或 `Prompt is too long`，請參閱[錯誤參考](/zh-TW/errors)。這些錯誤及其修復與 CLI 和 Desktop 應用程式共享。下面的部分涵蓋特定於雲端工作階段的問題。

768

769### 工作階段建立失敗

770

771如果新工作階段無法啟動，出現 `Session creation failed` 或在佈建時停滯，Claude Code 無法分配雲端環境。

772

773* 檢查 [status.claude.com](https://status.claude.com) 以查找雲端工作階段事件

774* 一分鐘後重試，因為容量是按需佈建的

775* 確認您的儲存庫可到達。私人儲存庫需要在該儲存庫上安裝 GitHub App 存取，或通過 `/web-setup` 同步的 `gh` 令牌。請參閱 [GitHub 驗證選項](#github-authentication-options)。

776

777### 遠端控制工作階段已過期或存取被拒絕

778

779`--teleport` 通過與雲端工作階段使用的相同遠端控制工作階段基礎設施連接，因此驗證和工作階段過期錯誤會以遠端控制措辭出現。您可能會看到 `Remote Control session has expired` 或 `Access denied`。連接令牌是短期的，並限定於您的帳戶。

780

781* 在本機執行 `/login` 以刷新您的認證，然後重新連接

782* 確認您登入到擁有工作階段的相同帳戶

783* 如果您看到 `Remote Control may not be available for this organization`，您的管理員尚未為您的計畫啟用遠端工作階段

784

785### 環境已過期

786

787雲端工作階段在不活動一段時間後停止，基礎環境被回收。從本機終端，這會顯示為 `Could not resume session ... its environment has expired. Creating a fresh session instead.` 在網頁上，工作階段在工作階段清單中標記為已過期。

788

789從 [claude.ai/code](https://claude.ai/code) 重新開啟工作階段以佈建新環境，並恢復您的對話歷史記錄。

790

757## 限制791## 限制

758 792

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

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

762* **儲存庫驗證**：您只能在驗證到相同帳戶時將工作階段從網頁移動到本機796* **儲存庫驗證**：您只能在驗證到相同帳戶時將工作階段從網頁移動到本機

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

798* **組織 IP 允許清單**：雲端工作階段從 Anthropic 管理的基礎設施而不是您的網路呼叫 Anthropic API。如果您的組織啟用了 [IP 允許清單](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每個雲端工作階段都會失敗，出現驗證錯誤。這同樣適用於[程式碼審查](/zh-TW/code-review)和[例行工作](/zh-TW/routines)。聯絡 [Anthropic 支援](https://support.claude.com/)以從您的組織的 IP 允許清單中豁免 Anthropic 託管的服務。

764 799

765## 相關資源800## 相關資源

766 801

cli-reference.md +11 −10

Details

40使用這些命令列旗標自訂 Claude Code 的行為。`claude --help` 不會列出每個旗標，因此旗標在 `--help` 中的缺失並不表示它無法使用。40使用這些命令列旗標自訂 Claude Code 的行為。`claude --help` 不會列出每個旗標，因此旗標在 `--help` 中的缺失並不表示它無法使用。

41 41

42| 旗標 | 描述 | 範例 |42| 旗標 | 描述 | 範例 |

43| :---------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |43| :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |

44| `--add-dir` | 新增額外的工作目錄供 Claude 讀取和編輯檔案。授予檔案存取權；大多數 `.claude/` 設定 [未從這些目錄探索](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。驗證每個路徑是否存在為目錄 | `claude --add-dir ../apps ../lib` |44| `--add-dir` | 新增額外的工作目錄供 Claude 讀取和編輯檔案。授予檔案存取權；大多數 `.claude/` 設定 [未從這些目錄探索](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。驗證每個路徑是否存在為目錄。若要在工作階段之間持久化這些目錄，請在設定中設定 [`permissions.additionalDirectories`](/zh-TW/settings#permission-settings) | `claude --add-dir ../apps ../lib` |

46| `--agents` | 透過 JSON 動態定義自訂 subagents。使用與 subagent [frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields) 相同的欄位名稱，加上代理程式指示的 `prompt` 欄位 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |46| `--agents` | 透過 JSON 動態定義自訂 subagents。使用與 subagent [frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields) 相同的欄位名稱，加上代理程式指示的 `prompt` 欄位 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

47| `--allow-dangerously-skip-permissions` | 新增 `bypassPermissions` 到 `Shift+Tab` 模式循環而不立即啟動它。允許您以不同的模式（如 `plan`）開始，稍後切換到 `bypassPermissions`。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |47| `--allow-dangerously-skip-permissions` | 新增 `bypassPermissions` 到 `Shift+Tab` 模式循環而不立即啟動它。允許您以不同的模式（如 `plan`）開始，稍後切換到 `bypassPermissions`。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

62| `--effort` | 為目前工作階段設定 [effort level](/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型。工作階段範圍且不會持久化到設定 | `claude --effort high` |62| `--effort` | 為目前工作階段設定 [effort level](/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型。覆蓋此工作階段的 [`effortLevel`](/zh-TW/settings#available-settings) 設定，且不會持久化 | `claude --effort high` |

63| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 現在預設在 `Shift+Tab` 循環中；使用 `--permission-mode auto` 以它開始 | `claude --permission-mode auto` |63| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 現在預設在 `Shift+Tab` 循環中；使用 `--permission-mode auto` 以它開始 | `claude --permission-mode auto` |

64| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git 狀態）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |64| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git 狀態）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

80| `--name`, `-n` | 為工作階段設定顯示名稱，顯示在 `/resume` 和終端標題中。您可以使用 `claude --resume <name>` 繼續已命名的工作階段。<br /><br />[`/rename`](/zh-TW/commands) 在工作階段中途變更名稱，也會在提示列中顯示 | `claude -n "my-feature-work"` |80| `--name`, `-n` | 為工作階段設定顯示名稱，顯示在 `/resume` 和終端標題中。您可以使用 `claude --resume <name>` 繼續已命名的工作階段。<br /><br />[`/rename`](/zh-TW/commands) 在工作階段中途變更名稱，也會在提示列中顯示 | `claude -n "my-feature-work"` |

84| `--permission-mode` | 以指定的 [permission mode](/zh-TW/permission-modes) 開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆蓋設定檔案中的 `defaultMode` | `claude --permission-mode plan` |84| `--permission-mode` | 以指定的 [permission mode](/zh-TW/permission-modes) 開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆蓋設定檔案中的 `defaultMode` | `claude --permission-mode plan` |

87| `--plugin-url` | 為此工作階段僅從 URL 擷取 plugin `.zip` 封存。每個旗標採用一個 URL。重複旗標以使用多個 plugins | `claude --plugin-url https://example.com/plugin.zip` |

89| `--remote-control`, `--rc` | 啟動互動式工作階段，並啟用 [Remote Control](/zh-TW/remote-control#start-a-remote-control-session)，以便您也可以從 claude.ai 或 Claude 應用程式控制它。可選擇傳遞工作階段的名稱 | `claude --remote-control "My Project"` |90| `--remote-control`, `--rc` | 啟動互動式工作階段，並啟用 [Remote Control](/zh-TW/remote-control#start-a-remote-control-session)，以便您也可以從 claude.ai 或 Claude 應用程式控制它。可選擇傳遞工作階段的名稱 | `claude --remote-control "My Project"` |

100| `--teammate-mode` | 設定 [agent team](/zh-TW/agent-teams) 隊友的顯示方式：`auto`（預設）、`in-process` 或 `tmux`。請參閱 [選擇顯示模式](/zh-TW/agent-teams#choose-a-display-mode) | `claude --teammate-mode in-process` |101| `--teammate-mode` | 設定 [agent team](/zh-TW/agent-teams) 隊友的顯示方式：`auto`（預設）、`in-process` 或 `tmux`。覆蓋此工作階段的 [`teammateMode`](/zh-TW/settings#available-settings) 設定。請參閱 [選擇顯示模式](/zh-TW/agent-teams#choose-a-display-mode) | `claude --teammate-mode in-process` |

105| `--worktree`, `-w` | 在隔離的 [git worktree](/zh-TW/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) 中啟動 Claude，位於 `<repo>/.claude/worktrees/<name>`。如果未提供名稱，則會自動產生一個 | `claude -w feature-auth` |106| `--worktree`, `-w` | 在隔離的 [git worktree](/zh-TW/worktrees) 中啟動 Claude，位於 `<repo>/.claude/worktrees/<name>`。如果未提供名稱，則會自動產生一個 | `claude -w feature-auth` |

106 107

107### 系統提示旗標108### 系統提示旗標

108 109

commands.md +5 −3

Details

10 10

11輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟字母以篩選。11輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟字母以篩選。

12 12

13命令只有在您的訊息開始時才會被識別。命令名稱後面的文字會作為引數傳遞給它。

13下表列出了 Claude Code 中包含的所有命令。標記為 **[Skill](/zh-TW/skills#bundled-skills)** 的項目是捆綁的 skills。它們使用與您自己編寫的 skills 相同的機制：提示交給 Claude，Claude 也可以在相關時自動調用。其他所有項目都是內建命令，其行為被編碼到 CLI 中。若要添加您自己的命令，請參閱 [skills](/zh-TW/skills)。15下表列出了 Claude Code 中包含的所有命令。標記為 **[Skill](/zh-TW/skills#bundled-skills)** 的項目是捆綁的 skills。它們使用與您自己編寫的 skills 相同的機制：提示交給 Claude，Claude 也可以在相關時自動調用。其他所有項目都是內建命令，其行為被編碼到 CLI 中。若要添加您自己的命令，請參閱 [skills](/zh-TW/skills)。

14 16

15並非每個命令都對每個使用者顯示。可用性取決於您的平台、方案和環境。例如，`/desktop` 僅在 macOS 和 Windows 上顯示，`/upgrade` 僅在 Pro 和 Max 方案上顯示。17並非每個命令都對每個使用者顯示。可用性取決於您的平台、方案和環境。例如，`/desktop` 僅在 macOS 和 Windows 上顯示，`/upgrade` 僅在 Pro 和 Max 方案上顯示。

21| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。大多數 `.claude/` 配置[未從添加的目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |23| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。大多數 `.claude/` 配置[未從添加的目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |

23| `/autofix-pr [prompt]` | 生成一個[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web#auto-fix-pull-requests) 工作階段，監視目前分支的 PR 並在 CI 失敗或審閱者留下評論時推送修復。使用 `gh pr view` 檢測已簽出分支的開放 PR；若要監視不同的 PR，請先簽出其分支。預設情況下，遠端工作階段被告知修復每個 CI 失敗和審閱評論；傳遞提示以給予它不同的指示，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和訪問[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |25| `/autofix-pr [prompt]` | 生成一個[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web#auto-fix-pull-requests) 工作階段，監視目前分支的 PR 並在 CI 失敗或審閱者留下評論時推送修復。使用 `gh pr view` 檢測已簽出分支的開放 PR；若要監視不同的 PR，請先簽出其分支。預設情況下，遠端工作階段被告知修復每個 CI 失敗和審閱評論；傳遞提示以給予它不同的指示，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和訪問[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |

24| `/batch <instruction>` | **[Skill](/zh-TW/skills#bundled-skills).** 在整個程式碼庫中並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計劃。獲得批准後，在隔離的 [git worktree](/zh-TW/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) 中為每個單位生成一個背景 agent。每個 agent 實現其單位、運行測試並開啟 pull request。需要 git 存放庫。示例：`/batch migrate src/ from Solid to React` |26| `/batch <instruction>` | **[Skill](/zh-TW/skills#bundled-skills).** 在整個程式碼庫中並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計劃。獲得批准後，在隔離的 [git worktree](/zh-TW/worktrees) 中為每個單位生成一個背景 agent。每個 agent 實現其單位、運行測試並開啟 pull request。需要 git 存放庫。示例：`/batch migrate src/ from Solid to React` |

25| `/branch [name]` | 在此時刻建立目前對話的分支。切換到分支並保留原始分支，您可以使用 `/resume` 返回。別名：`/fork`。當設定 [`CLAUDE_CODE_FORK_SUBAGENT`](/zh-TW/env-vars) 時，`/fork` 改為生成[分叉的 subagent](/zh-TW/sub-agents#fork-the-current-conversation)，不再是此命令的別名 |27| `/branch [name]` | 在此時刻建立目前對話的分支。切換到分支並保留原始分支，您可以使用 `/resume` 返回。別名：`/fork`。當設定 [`CLAUDE_CODE_FORK_SUBAGENT`](/zh-TW/env-vars) 時，`/fork` 改為生成[分叉的 subagent](/zh-TW/sub-agents#fork-the-current-conversation)，不再是此命令的別名 |

28| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |30| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |

30| `/color [color\|default]` | 設定目前工作階段的提示列顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重設。當[遠端控制](/zh-TW/remote-control)已連接時，顏色會同步到 claude.ai/code |32| `/color [color\|default]` | 設定目前工作階段的提示列顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重設，或不帶引數執行以選擇隨機顏色。當[遠端控制](/zh-TW/remote-control)已連接時，顏色會同步到 claude.ai/code |

31| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選擇性地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、skills 和記憶體檔案](/zh-TW/context-window#what-survives-compaction) |33| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選擇性地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、skills 和記憶體檔案](/zh-TW/context-window#what-survives-compaction) |

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

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

85| `/simplify [focus]` | **[Skill](/zh-TW/skills#bundled-skills).** 審閱您最近變更的檔案以查找程式碼重用、品質和效率問題，然後修復它們。並行生成三個審閱 agent，聚合其發現並應用修復。傳遞文字以集中於特定關注點：`/simplify focus on memory efficiency` |87| `/simplify [focus]` | **[Skill](/zh-TW/skills#bundled-skills).** 審閱您最近變更的檔案以查找程式碼重用、品質和效率問題，然後修復它們。並行生成三個審閱 agent，聚合其發現並應用修復。傳遞文字以集中於特定關注點：`/simplify focus on memory efficiency` |

debug-your-config.md +25 −5

Details

8 8

9當 Claude 忽略您的指令或您設定的功能沒有出現時，通常是因為檔案沒有載入、從您預期以外的位置載入，或被另一個檔案覆蓋。本指南展示如何檢查 Claude Code 實際載入的內容，以便您縮小範圍。9當 Claude 忽略您的指令或您設定的功能沒有出現時，通常是因為檔案沒有載入、從您預期以外的位置載入，或被另一個檔案覆蓋。本指南展示如何檢查 Claude Code 實際載入的內容，以便您縮小範圍。

10 10

~~11如需安裝、驗證和連線問題的協助，請改為參閱 [Troubleshooting](/zh-TW/troubleshoot-install)。~~11如需安裝、驗證和連線問題的協助，請改為參閱 [Troubleshoot installation and login](/zh-TW/troubleshoot-install)。

12 12

13## 查看載入到 context 的內容13## 查看載入到 context 的內容

14 14

17如需特定類別的詳細資訊，請使用專用命令進行後續操作：17如需特定類別的詳細資訊，請使用專用命令進行後續操作：

18 18

19| 命令 | 顯示 |19| 命令 | 顯示 |

~~20| :------------- | :------------------------------- |~~20| :--------------- | :--------------------------------------- |

21| `/memory` | 載入了哪些 `CLAUDE.md` 和規則檔案，加上自動記憶項目 |21| `/memory` | 載入了哪些 `CLAUDE.md` 和規則檔案，加上自動記憶項目 |

22| `/skills` | 來自專案、使用者和外掛程式來源的可用 skills |22| `/skills` | 來自專案、使用者和外掛程式來源的可用 skills |

23| `/agents` | 已設定的子代理及其設定 |23| `/agents` | 已設定的子代理及其設定 |

25| `/mcp` | 已連線的 MCP servers 及其狀態 |25| `/mcp` | 已連線的 MCP servers 及其狀態 |

26| `/permissions` | 目前生效的已解析允許和拒絕規則 |26| `/permissions` | 目前生效的已解析允許和拒絕規則 |

27| `/doctor` | 設定診斷：無效的鍵、schema 錯誤、安裝健康狀況 |27| `/doctor` | 設定診斷：無效的鍵、schema 錯誤、安裝健康狀況 |

28| `/debug [issue]` | 啟用工作階段的偵錯日誌記錄，並提示 Claude 使用日誌輸出和設定路徑進行診斷 |

28| `/status` | 作用中的設定來源，包括是否啟用了受管設定 |29| `/status` | 作用中的設定來源，包括是否啟用了受管設定 |

29 30

30如果記憶檔案在 `/memory` 中遺失，請根據 [CLAUDE.md 檔案如何載入](/zh-TW/memory#how-claude-md-files-load) 檢查其位置。子目錄 `CLAUDE.md` 檔案在 Claude 使用 Read 工具讀取該目錄中的檔案時按需載入，而不是在工作階段開始時載入。31如果記憶檔案在 `/memory` 中遺失，請根據 [CLAUDE.md 檔案如何載入](/zh-TW/memory#how-claude-md-files-load) 檢查其位置。子目錄 `CLAUDE.md` 檔案在 Claude 使用 Read 工具讀取該目錄中的檔案時按需載入，而不是在工作階段開始時載入。

41 42

42設定在受管、使用者、專案和本機範圍之間合併。受管設定在存在時始終優先。在其餘的設定中，較近的範圍會按本機、專案、使用者的順序覆蓋較廣的範圍。某些設定也可以由命令列旗標或 [環境變數](/zh-TW/env-vars) 設定，這些變數充當另一個覆蓋層。當設定似乎不適用時，您設定的值通常被另一個範圍或環境變數覆蓋。43設定在受管、使用者、專案和本機範圍之間合併。受管設定在存在時始終優先。在其餘的設定中，較近的範圍會按本機、專案、使用者的順序覆蓋較廣的範圍。某些設定也可以由命令列旗標或 [環境變數](/zh-TW/env-vars) 設定，這些變數充當另一個覆蓋層。當設定似乎不適用時，您設定的值通常被另一個範圍或環境變數覆蓋。

43 44

44執行 `/doctor` 以驗證您的設定檔案並顯示無效的鍵或 schema 錯誤。執行 `/status` 以查看哪些設定來源處於作用中，包括是否啟用了受管設定。若要瞭解給定鍵的哪個範圍優先，請參閱 [範圍如何互動](/zh-TW/settings#how-scopes-interact)。45執行 `/doctor` 以驗證您的設定檔案並顯示無效的鍵或 schema 錯誤。當 `/doctor` 報告問題時，按 `f` 將診斷報告傳送給 Claude，讓它與您一起逐步進行修正。

47執行 `/status` 以查看哪些設定來源處於作用中，包括是否啟用了受管設定。若要瞭解給定鍵的哪個範圍優先，請參閱 [範圍如何互動](/zh-TW/settings#how-scopes-interact)。

45 48

46## 檢查 MCP servers49## 檢查 MCP servers

47 50

63 66

64如果 `/hooks` 顯示 hook 但它仍然不觸發，下一步是即時監視 hook 評估。使用 `claude --debug hooks` 啟動工作階段並觸發 tool 呼叫。偵錯日誌記錄每個事件、檢查了哪些 matchers 以及 hook 的結束代碼和輸出。如需日誌格式，請參閱 [Debug hooks](/zh-TW/hooks#debug-hooks)，如需常見失敗模式，請參閱 [hooks 疑難排解](/zh-TW/hooks-guide#limitations-and-troubleshooting)。67如果 `/hooks` 顯示 hook 但它仍然不觸發，下一步是即時監視 hook 評估。使用 `claude --debug hooks` 啟動工作階段並觸發 tool 呼叫。偵錯日誌記錄每個事件、檢查了哪些 matchers 以及 hook 的結束代碼和輸出。如需日誌格式，請參閱 [Debug hooks](/zh-TW/hooks#debug-hooks)，如需常見失敗模式，請參閱 [hooks 疑難排解](/zh-TW/hooks-guide#limitations-and-troubleshooting)。

65 68

~~66## 常見原因~~69## 針對乾淨的設定進行測試

71如果目標檢查無法隔離原因，或您的設定處於未知狀態，請與不從您常用設定載入任何內容的工作階段進行比較。將 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars) 指向空目錄以略過 `~/.claude` 下的所有內容，並從沒有 `.claude` 資料夾、`.mcp.json` 或 `CLAUDE.md` 的目錄啟動，以便也跳過專案設定。

73```bash theme={null}

74cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

75```

77乾淨的工作階段沒有使用者或專案設定、hooks、MCP servers、外掛程式或記憶。

79* 如果您的組織部署受管設定，它們仍然適用，因為它們位於 `~/.claude` 外的系統路徑

80* 在 Linux 和 Windows 上，您將被提示再次登入，因為認證儲存在設定目錄下

81* 在 macOS 上，認證在 Keychain 中，並會轉移到乾淨的工作階段

83如果問題在此消失，原因在於您的真實 `~/.claude` 或專案 `.claude` 檔案中的某處。一次一個地重新引入它們，方法是將檔案複製到臨時目錄或從您的專案啟動，以找到哪一個。如果它在乾淨的工作階段中持續存在，原因在於您的使用者和專案設定之外。執行 `/status` 以檢查是否啟用了受管設定，查找影響 Claude Code 的 [環境變數](/zh-TW/env-vars)，然後參閱 [Troubleshooting](/zh-TW/troubleshooting)。

85## 檢查常見原因

67 86

68大多數設定意外可以追溯到一小組位置和語法規則。在假設有 bug 之前檢查這些：87大多數設定意外可以追溯到一小組位置和語法規則。在假設有 bug 之前檢查這些：

69 88

70| 症狀 | 原因 | 修正 |89| 症狀 | 原因 | 修正 |

71| :---------------------------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |90| :------------------------------------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |

102| 新增在 `settings.json` 中的 `mcpServers` 下的 MCP servers 永遠不出現 | `settings.json` 不讀取 `mcpServers` 鍵 | 在儲存庫根目錄的 `.mcp.json` 中定義專案 servers，或執行 `claude mcp add --scope user` 以取得使用者範圍的 servers。請參閱 [MCP 設定](/zh-TW/mcp)。 |

discover-plugins.md +19 −11

Details

4 4

5# 透過市場探索和安裝預建外掛程式5# 透過市場探索和安裝預建外掛程式

6 6

~~7> 從市場探索和安裝外掛程式，以使用新命令、代理和功能擴展 Claude Code。~~7> 從市場探索和安裝外掛程式，以使用新技能、代理和功能擴展 Claude Code。

8 8

9外掛程式透過技能、代理、hooks 和 MCP servers 擴展 Claude Code。外掛程式市場是幫助您探索和安裝這些擴展的目錄，無需自己構建它們。9外掛程式透過技能、代理、hooks 和 MCP servers 擴展 Claude Code。外掛程式市場是幫助您探索和安裝這些擴展的目錄，無需自己構建它們。

10 10

36/plugin install github@claude-plugins-official36/plugin install github@claude-plugins-official

37```37```

38 38

39如果 Claude Code 報告在任何市場中找不到外掛程式，您的市場可能遺失或已過期。執行 `/plugin marketplace update claude-plugins-official` 以重新整理它，或如果您之前未新增過，執行 `/plugin marketplace add anthropics/claude-plugins-official`。然後重試安裝。

39<Note>41<Note>

40 官方市場由 Anthropic 維護。若要將外掛程式提交到官方市場，請使用其中一個應用內提交表單：42 官方市場由 Anthropic 維護。若要將外掛程式提交到官方市場，請使用其中一個應用內提交表單：

41 43

95 97

96### 開發工作流程98### 開發工作流程

97 99

~~98為常見開發任務新增命令和代理的外掛程式：~~100為常見開發任務新增技能和代理的外掛程式：

99 101

100* **commit-commands**：Git 提交工作流程，包括提交、推送和 PR 建立102* **commit-commands**：Git 提交工作流程，包括提交、推送和 PR 建立

101* **pr-review-toolkit**：用於審查拉取請求的專門代理103* **pr-review-toolkit**：用於審查拉取請求的專門代理

142 * **Project scope**：為此儲存庫上的所有協作者安裝144 * **Project scope**：為此儲存庫上的所有協作者安裝

143 * **Local scope**：僅在此儲存庫中為自己安裝145 * **Local scope**：僅在此儲存庫中為自己安裝

144 146

145 例如，選擇 **commit-commands**（新增 git 工作流程命令的外掛程式）並將其安裝到您的使用者範圍。147 例如，選擇 **commit-commands**（新增 git 工作流程技能的外掛程式）並將其安裝到您的使用者範圍。

146 148

147 您也可以直接從命令列安裝：149 您也可以直接從命令列安裝：

148 150

154 </Step>156 </Step>

155 157

156 <Step title="使用您的新外掛程式">158 <Step title="使用您的新外掛程式">

157 安裝後，執行 `/reload-plugins` 以啟動外掛程式。外掛程式命令由外掛程式名稱命名空間，因此 **commit-commands** 提供 `/commit-commands:commit` 之類的命令。159 安裝後，執行 `/reload-plugins` 以啟動外掛程式。外掛程式技能由外掛程式名稱命名空間，因此 **commit-commands** 提供 `/commit-commands:commit` 之類的技能。

158 160

159 透過對檔案進行變更並執行以下命令來試試看：161 透過對檔案進行變更並執行以下命令來試試看：

160 162

164 166

165 這會暫存您的變更、產生提交訊息並建立提交。167 這會暫存您的變更、產生提交訊息並建立提交。

166 168

167 每個外掛程式的工作方式不同。檢查 **Discover** 標籤中的外掛程式描述或其首頁，以瞭解它提供的命令和功能。169 每個外掛程式的工作方式不同。檢查 **Discover** 標籤中的外掛程式描述或其首頁，以瞭解它提供的技能和功能。

168 </Step>170 </Step>

169</Steps>171</Steps>

170 172

195 197

196### 從其他 Git 主機新增198### 從其他 Git 主機新增

197 199

198透過提供完整 URL 新增任何 git 儲存庫。這適用於任何 Git 主機，包括 GitLab、Bitbucket 和自託管伺服器：200透過提供完整 URL 新增任何 git 儲存庫。這適用於任何 Git 主機，包括 GitLab、Bitbucket 和自託管伺服器。包含 `.git` 後綴，以便 Claude Code 複製儲存庫，而不是將 URL 視為託管 `marketplace.json` 檔案的直接連結。

199 201

200使用 HTTPS：202使用 HTTPS：

201 203

257 259

258您也可能看到具有 **managed** 範圍的外掛程式，這些是由管理員透過[受管設定](/zh-TW/settings#settings-files)安裝的，無法修改。260您也可能看到具有 **managed** 範圍的外掛程式，這些是由管理員透過[受管設定](/zh-TW/settings#settings-files)安裝的，無法修改。

259 261

260執行 `/plugin` 並前往 **Installed** 標籤以查看按範圍分組的外掛程式。

~~261~~

262<Warning>262<Warning>

263 在安裝外掛程式之前，請確保您信任它。Anthropic 不控制外掛程式中包含的 MCP servers、檔案或其他軟體，也無法驗證它們是否按預期工作。檢查每個外掛程式的首頁以獲取更多資訊。263 在安裝外掛程式之前，請確保您信任它。Anthropic 不控制外掛程式中包含的 MCP servers、檔案或其他軟體，也無法驗證它們是否按預期工作。檢查每個外掛程式的首頁以獲取更多資訊。

264</Warning>264</Warning>

265 265

266## 管理已安裝的外掛程式266## 管理已安裝的外掛程式

267 267

268執行 `/plugin` 並前往 **Installed** 標籤以檢視、啟用、停用或解除安裝外掛程式。輸入以按外掛程式名稱或描述篩選清單。268執行 `/plugin` 並前往 **Installed** 標籤以檢視、啟用、停用或解除安裝外掛程式。清單按範圍分組，並排序以便您首先看到問題：具有載入錯誤或未解決依賴項的外掛程式出現在頂部，然後是您的最愛，停用的外掛程式摺疊在底部的摺疊標題後面。

269

270從清單中，您可以：

271

272* 按 `f` 以將選定的外掛程式加入最愛或取消加入最愛

273* 輸入以按外掛程式名稱或描述篩選

274* 按 Enter 以開啟外掛程式的詳細檢視並啟用、停用或解除安裝它

275

276當您安裝聲明依賴項的外掛程式時，安裝輸出會列出哪些依賴項與其一起自動安裝。

269 277

270您也可以使用直接命令管理外掛程式。278您也可以使用直接命令管理外掛程式。

271 279

400 408

4011. **檢查您的版本**：執行 `claude --version` 以查看已安裝的內容。4091. **檢查您的版本**：執行 `claude --version` 以查看已安裝的內容。

4022. **更新 Claude Code**：4102. **更新 Claude Code**：

403 * **Homebrew**：`brew upgrade claude-code`411 * **Homebrew**：`brew upgrade claude-code`（或如果您安裝了該 cask，執行 `brew upgrade claude-code@latest`）

404 * **npm**：`npm update -g @anthropic-ai/claude-code`412 * **npm**：`npm install -g @anthropic-ai/claude-code@latest`

405 * **原生安裝程式**：從[設定](/zh-TW/setup)重新執行安裝命令413 * **原生安裝程式**：從[設定](/zh-TW/setup)重新執行安裝命令

4063. **重新啟動 Claude Code**：更新後，重新啟動您的終端機並再次執行 `claude`。4143. **重新啟動 Claude Code**：更新後，重新啟動您的終端機並再次執行 `claude`。

407 415

env-vars.md +15 −9

Details

43| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Vertex AI 端點 URL。用於自訂 Vertex 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Google Vertex AI](/zh-TW/google-vertex-ai) |43| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Vertex AI 端點 URL。用於自訂 Vertex 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Google Vertex AI](/zh-TW/google-vertex-ai) |

44| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 的 GCP 專案 ID。使用 [Google Vertex AI](/zh-TW/google-vertex-ai) 時為必需 |44| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 的 GCP 專案 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 認證檔案中的專案覆蓋。請參閱 [Google Vertex AI](/zh-TW/google-vertex-ai) |

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

51| `CLAUDECODE` | 在 Claude Code 生成的 shell 環境中設定為 `1`（Bash 工具、tmux 工作階段）。未在 [hooks](/zh-TW/hooks) 或 [status line](/zh-TW/statusline) 命令中設定。用於偵測指令碼何時在 Claude Code 生成的 shell 內執行 |51| `CLAUDECODE` | 在 Claude Code 生成的 shell 環境中設定為 `1`（Bash 工具、tmux 工作階段）。未在 [hooks](/zh-TW/hooks) 或 [status line](/zh-TW/statusline) 命令中設定。用於偵測指令碼何時在 Claude Code 生成的 shell 內執行 |

52| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |52| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |

54| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 背景 subagents 的停滯逾時（以毫秒為單位）。預設 `600000`（10 分鐘）。計時器在每個串流進度事件時重設；如果在視窗內沒有進度到達，subagent 會被中止，任務會標記為失敗，將任何部分結果呈現給父級 |

54| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮觸發的上下文容量百分比 (1-100)。預設情況下，自動壓縮在約 95% 容量時觸發。使用較低的值（如 `50`）以更早進行壓縮。高於預設閾值的值無效。適用於主要對話和 subagents。此百分比與 [status line](/zh-TW/statusline) 中可用的 `context_window.used_percentage` 欄位一致 |55| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮觸發的上下文容量百分比 (1-100)。預設情況下，自動壓縮在約 95% 容量時觸發。使用較低的值（如 `50`）以更早進行壓縮。高於預設閾值的值無效。適用於主要對話和 subagents。此百分比與 [status line](/zh-TW/statusline) 中可用的 `context_window.used_percentage` 欄位一致 |

60| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |61| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |

61| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/zh-TW/model-config#extended-context) 模型為 1M。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |62| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/zh-TW/model-config#extended-context) 模型為 1M。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |

62| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時 |63| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時。優先於 [`autoConnectIde`](/zh-TW/settings#global-config-settings) 全域配置設定 |

63| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源逗號分隔清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區。預設為 `bundled,system`。系統存放區整合需要原生二進位分佈。在 Node.js 執行時，無論此值如何，只使用捆綁集 |64| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源逗號分隔清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區。預設為 `bundled,system` |

68| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷，例如完整狀態行命令輸出，或提高到 `error` 以減少雜訊 |69| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷，例如完整狀態行命令輸出，或提高到 `error` 以減少雜訊 |

69| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M context window](/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用。對於具有合規性要求的企業環境很有用 |70| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M context window](/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用。對於具有合規性要求的企業環境很有用 |

70| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 的 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。{/* min-version: 2.1.111 */}對 Opus 4.7 無效，其始終使用自適應推理 |71| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 的 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。{/* min-version: 2.1.111 */}對 Opus 4.7 無效，其始終使用自適應推理 |

72| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 並使用經典主螢幕渲染器。對話保留在您終端的原生捲動回溯中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-TW/settings#available-settings) 設定。您也可以使用 `/tui default` 切換 |

72| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [auto memory](/zh-TW/memory#auto-memory)。設定為 `0` 以在逐步推出期間強制啟用自動記憶體。停用時，Claude 不會建立或載入自動記憶體檔案 |74| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [auto memory](/zh-TW/memory#auto-memory)。設定為 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-TW/settings#available-settings) 會以其他方式停用時強制啟用自動記憶體。停用時，Claude 不會建立或載入自動記憶體檔案 |

73| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 以停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景執行和 Ctrl+B 快捷鍵 |75| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 以停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景執行和 Ctrl+B 快捷鍵 |

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

76| `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`）會保留。 |78| `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`）會保留。 |

78| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查。請參閱 [Session quality surveys](/zh-TW/data-usage#session-quality-surveys) |80| `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) |

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

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

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

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

92| `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) 失效 |94| `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) 失效 |

93| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 設定為 `1` 以強制啟用細粒度工具輸入串流。沒有此選項，API 會在發送 delta 事件之前完全緩衝工具輸入參數，這可能會延遲大型工具輸入的顯示。僅限 Anthropic API：對 Bedrock、Vertex 或 Foundry 無效 |95| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。預設為直接 Anthropic API 連線啟用。設定為 `0` 以選擇退出。設定為 `1` 以強制啟用，即使伺服器端預設為關閉。對 Bedrock、Vertex、Foundry 或 [gateway](/zh-TW/llm-gateway) 連線無效 |

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

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

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

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

104| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以強制啟用 DEC 私有模式 2026 [synchronized output](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)（當您的終端支援但未自動偵測時）。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效 |

101| `CLAUDE_CODE_FORK_SUBAGENT` | 設定為 `1` 以啟用 [forked subagents](/zh-TW/sub-agents#fork-the-current-conversation)。分叉的 subagent 從主工作階段繼承完整的對話上下文，而不是從頭開始。啟用時，`/fork` 會生成分叉的 subagent，而不是充當 [`/branch`](/zh-TW/commands) 的別名，所有 subagent 生成都在背景中執行。在互動式模式和透過 SDK 或 `claude -p` 中工作 |105| `CLAUDE_CODE_FORK_SUBAGENT` | 設定為 `1` 以啟用 [forked subagents](/zh-TW/sub-agents#fork-the-current-conversation)。分叉的 subagent 從主工作階段繼承完整的對話上下文，而不是從頭開始。啟用時，`/fork` 會生成分叉的 subagent，而不是充當 [`/branch`](/zh-TW/commands) 的別名，所有 subagent 生成都在背景中執行。在互動式模式和透過 SDK 或 `claude -p` 中工作 |

102| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔（`bash.exe`）的路徑。在 Git Bash 已安裝但不在您的 PATH 中時使用。請參閱 [Windows setup](/zh-TW/setup#set-up-on-windows) |106| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔（`bash.exe`）的路徑。在 Git Bash 已安裝但不在您的 PATH 中時使用。請參閱 [Windows setup](/zh-TW/setup#set-up-on-windows) |

103| `CLAUDE_CODE_GLOB_HIDDEN` | 設定為 `false` 以在 Claude 呼叫 [Glob tool](/zh-TW/tools-reference) 時從結果中排除隱藏檔案。預設包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |107| `CLAUDE_CODE_GLOB_HIDDEN` | 設定為 `false` 以在 Claude 呼叫 [Glob tool](/zh-TW/tools-reference) 時從結果中排除隱藏檔案。預設包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |

120| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待處理 OpenTelemetry spans 的逾時（以毫秒為單位）（預設值：5000）。請參閱 [Monitoring](/zh-TW/monitoring-usage) |124| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待處理 OpenTelemetry spans 的逾時（以毫秒為單位）（預設值：5000）。請參閱 [Monitoring](/zh-TW/monitoring-usage) |

121| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（以毫秒為單位）（預設值：1740000 / 29 分鐘）。請參閱 [Dynamic headers](/zh-TW/monitoring-usage#dynamic-headers) |125| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（以毫秒為單位）（預設值：1740000 / 29 分鐘）。請參閱 [Dynamic headers](/zh-TW/monitoring-usage#dynamic-headers) |

122| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成的逾時（以毫秒為單位）（預設值：2000）。如果指標在退出時被丟棄，請增加此值。請參閱 [Monitoring](/zh-TW/monitoring-usage) |126| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成的逾時（以毫秒為單位）（預設值：2000）。如果指標在退出時被丟棄，請增加此值。請參閱 [Monitoring](/zh-TW/monitoring-usage) |

127| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設定為 `1` 以讓 Claude Code 在新版本可用時在背景中執行您的套件管理員的升級命令。適用於 Homebrew 和 WinGet 安裝。其他套件管理員繼續顯示升級命令而不執行它。請參閱 [Auto updates](/zh-TW/setup#auto-updates) |

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

125| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安裝或更新外掛程式時 git 操作的逾時（以毫秒為單位）（預設值：120000）。對於大型儲存庫或網路連線緩慢，請增加此值。請參閱 [Git operations time out](/zh-TW/plugin-marketplaces#git-operations-time-out) |130| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安裝或更新外掛程式時 git 操作的逾時（以毫秒為單位）（預設值：120000）。對於大型儲存庫或網路連線緩慢，請增加此值。請參閱 [Git operations time out](/zh-TW/plugin-marketplaces#git-operations-time-out) |

131| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link artifacts back to the session](/zh-TW/claude-code-on-the-web#link-artifacts-back-to-the-session) |136| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link artifacts back to the session](/zh-TW/claude-code-on-the-web#link-artifacts-back-to-the-session) |

133| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時限制特定指令碼在每個工作階段中可被呼叫的次數。鍵是針對命令文字進行比對的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時扇出未被偵測；這是深度防禦控制 |138| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時限制特定指令碼在每個工作階段中可被呼叫的次數。鍵是針對命令文字進行比對的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時扇出未被偵測；這是深度防禦控制 |

134| `CLAUDE_CODE_SCROLL_SPEED` | 在 [fullscreen rendering](/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲動乘數。接受 1 到 20 的值。設定為 `3` 以符合 `vim`（如果您的終端在沒有放大的情況下每個刻度發送一個滾輪事件） |139| `CLAUDE_CODE_SCROLL_SPEED` | 在 [fullscreen rendering](/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲動乘數。接受 1 到 20 的值。設定為 `3` 以符合 `vim`（如果您的終端在沒有放大的情況下每個刻度發送一個滾輪事件）。在 JetBrains IDE 終端中被忽略，Claude Code 使用其自己的捲動處理 |

135| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/zh-TW/hooks#sessionend) hooks 的時間預算（以毫秒為單位）。適用於工作階段退出、`/clear` 和透過互動式 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔案中配置的最高每個 hook `timeout`，最高 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |140| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/zh-TW/hooks#sessionend) hooks 的時間預算（以毫秒為單位）。適用於工作階段退出、`/clear` 和透過互動式 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔案中配置的最高每個 hook `timeout`，最高 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |

141| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序中自動設定為目前工作階段 ID。符合傳遞給 [hooks](/zh-TW/hooks) 的 `session_id` 欄位。在 `/clear` 時更新。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |

137| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/zh-TW/hooks) 命令和 stdio [MCP server](/zh-TW/mcp) 啟動命令。對於日誌記錄或稽核很有用。範例：設定 `/path/to/logger.sh` 會將每個命令執行為 `/path/to/logger.sh <command>` |143| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/zh-TW/hooks) 命令和 stdio [MCP server](/zh-TW/mcp) 啟動命令。對於日誌記錄或稽核很有用。範例：設定 `/path/to/logger.sh` 會將每個命令執行為 `/path/to/logger.sh <command>` |

138| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。[`--bare`](/zh-TW/headless#start-faster-with-bare-mode) CLI 旗標設定此項 |144| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。[`--bare`](/zh-TW/headless#start-faster-with-bare-mode) CLI 旗標設定此項 |

185| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的管道分發 Claude Code 且使用者不應自行更新時使用 |191| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的管道分發 Claude Code 且使用者不應自行更新時使用 |

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

198| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法驗證非互動式模式（`-p` 旗標）中的 [`--json-schema`](/zh-TW/cli-reference#cli-flags) 時重試的次數。預設為 5 |204| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法驗證非互動式模式（`-p` 旗標）中的 [`--json-schema`](/zh-TW/cli-reference#cli-flags) 時重試的次數。預設為 5 |

199| `MAX_THINKING_TOKENS` | 覆蓋 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token 預算。上限是模型的 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 減一。設定為 `0` 以完全停用思考。在具有 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level) 的模型上，預算會被忽略，除非透過 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 停用自適應推理 |205| `MAX_THINKING_TOKENS` | 覆蓋 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token 預算。上限是模型的 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 減一。設定為 `0` 以完全停用思考。在具有 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level) 的模型上，預算會被忽略，除非透過 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 停用自適應推理 |

200| `MCP_CLIENT_SECRET` | 需要 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端密碼。在使用 `--client-secret` 新增伺服器時避免互動式提示 |206| `MCP_CLIENT_SECRET` | 需要 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端密碼。在使用 `--client-secret` 新增伺服器時避免互動式提示 |

201| `MCP_CONNECTION_NONBLOCKING` | 在非互動式模式（`-p`）中設定為 `true` 以完全跳過 MCP 連線等待。對於不需要 MCP 工具的指令碼化管道很有用。沒有此變數，第一個查詢會等待最多 5 秒以進行 `--mcp-config` 伺服器連線 |207| `MCP_CONNECTION_NONBLOCKING` | 在非互動式模式（`-p`）中設定為 `true` 以完全跳過 MCP 連線等待。對於不需要 MCP 工具的指令碼化管道很有用。沒有此變數，第一個查詢會等待最多 5 秒以進行 `--mcp-config` 伺服器連線。配置 [`alwaysLoad: true`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器始終會阻止啟動，無論此變數如何，因為其工具必須在建立第一個提示時存在 |

202| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，作為在使用 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |208| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，作為在使用 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |

errors.md +28 −6

Details

35| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |35| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |

36| `Unable to connect to API` | [Network](#unable-to-connect-to-api) |36| `Unable to connect to API` | [Network](#unable-to-connect-to-api) |

37| `SSL certificate verification failed` | [Network](#ssl-certificate-errors) |37| `SSL certificate verification failed` | [Network](#ssl-certificate-errors) |

38| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Network](#host-not-allowed-in-a-cloud-session) |

38| `Prompt is too long` | [Request errors](#prompt-is-too-long) |39| `Prompt is too long` | [Request errors](#prompt-is-too-long) |

39| `Error during compaction: Conversation too long` | [Request errors](#error-during-compaction-conversation-too-long) |40| `Error during compaction: Conversation too long` | [Request errors](#error-during-compaction-conversation-too-long) |

40| `Request too large` | [Request errors](#request-too-large) |41| `Request too large` | [Request errors](#request-too-large) |

282 283

283## 網路和連線錯誤284## 網路和連線錯誤

284 285

285這些錯誤表示 Claude Code 根本無法到達 API。它們幾乎總是源於您的本地網路、代理或防火牆，而不是 Anthropic 基礎設施。286這些錯誤表示 Claude Code 的網路請求無法到達其目的地。它們通常源於您的本地網路、代理或防火牆，或雲端環境的網路政策。

286 287

287### Unable to connect to API288### Unable to connect to API

288 289

305* 如果您在公司代理後面，請在啟動 Claude Code 之前設定 `HTTPS_PROXY` 並參閱 [Network configuration](/zh-TW/network-config)306* 如果您在公司代理後面，請在啟動 Claude Code 之前設定 `HTTPS_PROXY` 並參閱 [Network configuration](/zh-TW/network-config)

306* 如果您透過 LLM 閘道或中繼路由，請將 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 設定為其位址。請參閱 [LLM gateway configuration](/zh-TW/llm-gateway) 以了解設定。307* 如果您透過 LLM 閘道或中繼路由，請將 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 設定為其位址。請參閱 [LLM gateway configuration](/zh-TW/llm-gateway) 以了解設定。

307* 確保您的防火牆允許 [Network access requirements](/zh-TW/network-config#network-access-requirements) 中列出的主機308* 確保您的防火牆允許 [Network access requirements](/zh-TW/network-config#network-access-requirements) 中列出的主機

308* 間歇性失敗會 [retried automatically](#automatic-retries)；持續失敗指向本地網路問題309* 間歇性失敗會 [自動重試](#automatic-retries)；持續失敗指向本地網路問題

309 310

310如果 `curl` 成功但 Claude Code 仍然失敗，原因通常是 Node.js 和網路之間的某些東西，而不是網路本身：311如果 `curl` 成功但 Claude Code 仍然失敗，原因通常是執行時和網路之間的某些東西，而不是網路本身：

311 312

312* 在 Linux 和 WSL 上，檢查 `/etc/resolv.conf` 是否有無法到達的名稱伺服器。WSL 特別可以從主機繼承損壞的解析器。313* 在 Linux 和 WSL 上，檢查 `/etc/resolv.conf` 是否有無法到達的名稱伺服器。WSL 特別可以從主機繼承損壞的解析器。

313* 在 macOS 上，已斷開連線或卸載的 VPN 用戶端可能會留下隧道介面或路由規則。檢查 `ifconfig` 以了解過時的 `utun` 介面，並在系統設定中移除 VPN 的網路擴充功能。314* 在 macOS 上，已斷開連線或卸載的 VPN 用戶端可能會留下隧道介面或路由規則。檢查 `ifconfig` 以了解過時的 `utun` 介面，並在系統設定中移除 VPN 的網路擴充功能。

315 316

316### SSL certificate errors317### SSL certificate errors

317 318

318您網路上的代理或安全設備正在使用其自己的憑證攔截 TLS 流量，而 Node.js 不信任它。319您網路上的代理或安全設備正在使用其自己的憑證攔截 TLS 流量，而 Claude Code 不信任它。

319 320

320```text theme={null}321```text theme={null}

321Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates322Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

324 325

325**要做什麼：**326**要做什麼：**

326 327

327* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 指向 Node328* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 指向 Claude Code

328* 請參閱 [Network configuration](/zh-TW/network-config#custom-ca-certificates) 以了解完整的設定說明329* 請參閱 [Network configuration](/zh-TW/network-config#custom-ca-certificates) 以了解完整的設定說明

329* 不要設定 `NODE_TLS_REJECT_UNAUTHORIZED=0`，這會完全停用憑證驗證330* 不要設定 `NODE_TLS_REJECT_UNAUTHORIZED=0`，這會完全停用憑證驗證

330 331

332### Host not allowed in a cloud session

333

334來自雲端工作階段或例行程序的出站 HTTP 請求被環境的網路政策阻止。

335

336```text theme={null}

337HTTP 403

338x-deny-reason: host_not_allowed

339```

340

341您也可能看到與目的地實際憑證不符的 TLS 憑證。雲端環境透過代理路由出站流量以強制執行網路政策，因此不符的憑證表示代理終止了連線，而不是目的地。

342

343這不是用戶端網路問題。雲端工作階段和 [routines](/zh-TW/routines) 在沙箱環境內執行，其出站流量被篩選到環境的允許清單。**Default** 環境使用 **Trusted** 存取，允許 [預設允許清單](/zh-TW/claude-code-on-the-web#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域，但阻止其他所有內容。

344

345**要做什麼：**

346

347* 開啟例行程序進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱的雲端圖示，例如 **Default**，以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。

348* 在 **Update cloud environment** 對話方塊中，將 **Network access** 從 **Trusted** 變更為 **Custom**，然後將被阻止的網域新增至 **Allowed domains**。每行輸入一個網域。勾選 **Also include default list of common package managers** 以在自訂網域旁保留 [預設允許清單](/zh-TW/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇 **Full**。

349* 按一下 **Save changes**。下一次執行使用更新的允許清單。

350

351請參閱 [Network access](/zh-TW/claude-code-on-the-web#network-access) 以了解存取層級和預設允許清單。本地 CLI 工作階段不受此政策影響。

352

331## 請求錯誤353## 請求錯誤

332 354

333這些錯誤表示 API 收到了您的請求但拒絕了其內容。355這些錯誤表示 API 收到了您的請求但拒絕了其內容。

487**要做什麼：**509**要做什麼：**

488 510

489* 降低 `MAX_THINKING_TOKENS`，或將 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-TW/env-vars) 提高到思考預算之上511* 降低 `MAX_THINKING_TOKENS`，或將 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-TW/env-vars) 提高到思考預算之上

490* 請參閱 [Extended thinking](/zh-TW/common-workflows#use-extended-thinking-thinking-mode) 以了解預算如何與輸出長度互動512* 請參閱 [Extended thinking](/zh-TW/model-config#extended-thinking) 以了解預算如何與輸出長度互動

491 513

492### Tool use or thinking block mismatch514### Tool use or thinking block mismatch

493 515

features-overview.md +3 −3

Details

219| **Subagents** | 生成時 | 具有指定 skills 的新鮮上下文 | 與主會話隔離 |219| **Subagents** | 生成時 | 具有指定 skills 的新鮮上下文 | 與主會話隔離 |

220| **Hooks** | 觸發時 | 無（外部運行） | 零，除非 hook 返回額外上下文 |220| **Hooks** | 觸發時 | 無（外部運行） | 零，除非 hook 返回額外上下文 |

221 221

222\*預設情況下，skill 描述在會話開始時載入，以便 Claude 決定何時使用它們。在 skill 的 frontmatter 中設置 `disable-model-invocation: true` 以將其完全隱藏在 Claude 中，直到您手動調用它。這將 skills 的上下文成本降低到零，您只需自己觸發這些 skills。222\*預設情況下，skill 描述在會話開始時載入，以便 Claude 決定何時使用它們。在 skill 的 frontmatter 中設置 `disable-model-invocation: true` 以將其完全隱藏在 Claude 中，直到您手動調用它。這將 skills 的上下文成本降低到零，您只需自己觸發這些 skills。對於您未編寫的 skill，在設置中設置 [`skillOverrides`](/zh-TW/skills#override-skill-visibility-from-settings) 以執行相同操作，而無需編輯其檔案。

223 223

224### 了解功能如何載入224### 了解功能如何載入

225 225

282 </Tab>282 </Tab>

283 283

284 <Tab title="Hooks">284 <Tab title="Hooks">

285 **何時：** 觸發時。Hooks 在特定生命週期事件（如工具執行、會話邊界、提示提交、權限請求和壓縮）時觸發。有關完整清單，請參閱 [Hooks](/zh-TW/hooks-guide)。285 **何時：** 觸發時。Hooks 在特定生命週期事件（如工具執行、會話邊界、提示提交、權限請求和壓縮）時觸發。有關完整清單，請參閱 [Hooks](/zh-TW/hooks)。

286 286

287 **什麼載入：** 預設情況下無。Hooks 作為外部指令碼運行。287 **什麼載入：** 預設情況下無。Hooks 在主對話外執行。

288 288

289 **上下文成本：** 零，除非 hook 返回添加為訊息到您的對話的輸出。289 **上下文成本：** 零，除非 hook 返回添加為訊息到您的對話的輸出。

290 290

fullscreen.md +10 −2

Details

93 93

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

95 95

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

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

100在 2025.2 中，終端也有捲動滾輪錯誤，會產生虛假的方向鍵和錯誤方向的事件。Claude Code 在執行時偵測這些錯誤並自動減輕它們，因此觸控板和滑鼠滾輪捲動無需設定即可運作。為了獲得最佳捲動體驗，請升級到 2025.3 或更新版本。如果 Claude Code 偵測到該錯誤，它會在您第一次捲動時顯示提示。

101

96## 搜尋和檢閱對話102## 搜尋和檢閱對話

97 103

98`Ctrl+o` 在正常提示和文字記錄模式之間切換。若要取得更安靜的檢視，只顯示您的最後一個提示、工具呼叫的單行摘要（含編輯 diffstats）和最終回應，請執行 `/focus`。該設定在工作階段之間保持。再次執行 `/focus` 以關閉它。104`Ctrl+o` 在正常提示和文字記錄模式之間切換。若要取得更安靜的檢視，只顯示您的最後一個提示、工具呼叫的單行摘要（含編輯 diffstats）和最終回應，請執行 `/focus`。該設定在工作階段之間保持。再次執行 `/focus` 以關閉它。

122 128

123## 與 tmux 搭配使用129## 與 tmux 搭配使用

124 130

125全螢幕渲染在 tmux 內運作，有兩個注意事項。131全螢幕渲染在 tmux 內運作，有三個注意事項。

126 132

127滑鼠滾輪捲動需要 tmux 的滑鼠模式。如果您的 `~/.tmux.conf` 尚未啟用它，請新增此行並重新載入您的設定：133滑鼠滾輪捲動需要 tmux 的滑鼠模式。如果您的 `~/.tmux.conf` 尚未啟用它，請新增此行並重新載入您的設定：

128 134

134 140

135全螢幕渲染與 iTerm2 的 tmux 整合模式不相容，這是您使用 `tmux -CC` 進入的模式。在整合模式中，iTerm2 將每個 tmux 窗格渲染為原生分割，而不是讓 tmux 繪製到終端。替代螢幕緩衝區和滑鼠追蹤在那裡無法正確運作：滑鼠滾輪無法執行任何操作，雙擊可能會損壞終端狀態。不要在 `tmux -CC` 工作階段中啟用全螢幕渲染。在 iTerm2 內的常規 tmux（沒有 `-CC`）運作良好。141全螢幕渲染與 iTerm2 的 tmux 整合模式不相容，這是您使用 `tmux -CC` 進入的模式。在整合模式中，iTerm2 將每個 tmux 窗格渲染為原生分割，而不是讓 tmux 繪製到終端。替代螢幕緩衝區和滑鼠追蹤在那裡無法正確運作：滑鼠滾輪無法執行任何操作，雙擊可能會損壞終端狀態。不要在 `tmux -CC` 工作階段中啟用全螢幕渲染。在 iTerm2 內的常規 tmux（沒有 `-CC`）運作良好。

136 142

143tmux 不支援同步輸出，因此在重繪期間您可能會看到比直接在終端中執行 Claude Code 時更多的閃爍。如果閃爍明顯，特別是在 SSH 上，請在 tmux 外的自己的終端標籤中執行 Claude Code。

144

137## 保持原生文字選擇145## 保持原生文字選擇

138 146

139滑鼠捕捉是最常見的摩擦點，特別是在 SSH 上或 tmux 內。當 Claude Code 捕捉滑鼠事件時，您的終端的原生選擇時複製停止運作。您使用點擊並拖曳進行的選擇存在於 Claude Code 內，而不是在您的終端的選擇緩衝區中，因此 tmux 複製模式、Kitty 提示和類似工具看不到它。147滑鼠捕捉是最常見的摩擦點，特別是在 SSH 上或 tmux 內。當 Claude Code 捕捉滑鼠事件時，您的終端的原生選擇時複製停止運作。您使用點擊並拖曳進行的選擇存在於 Claude Code 內，而不是在您的終端的選擇緩衝區中，因此 tmux 複製模式、Kitty 提示和類似工具看不到它。

156 164

157如果您遇到問題，請在 Claude Code 內執行 `/feedback` 以報告它，或在 [claude-code GitHub 儲存庫](https://github.com/anthropics/claude-code/issues)上開啟問題。包括您的終端模擬器名稱和版本。165如果您遇到問題，請在 Claude Code 內執行 `/feedback` 以報告它，或在 [claude-code GitHub 儲存庫](https://github.com/anthropics/claude-code/issues)上開啟問題。包括您的終端模擬器名稱和版本。

158 166

159若要關閉全螢幕渲染，請執行 `/tui default`，或如果您以該方式啟用它，請取消設定環境變數。167若要關閉全螢幕渲染，請執行 `/tui default`，或如果您以該方式啟用它，請取消設定 `CLAUDE_CODE_NO_FLICKER`。若要不論已儲存的 `tui` 設定為何都強制使用經典渲染器，請設定 `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`。經典渲染器將對話保留在您終端的原生捲軸中，因此 `Cmd+f` 和 tmux 複製模式可以照常運作。

google-vertex-ai.md +23 −2

Details

253在 Vertex AI 中要求存取 Claude 模型：253在 Vertex AI 中要求存取 Claude 模型：

254 254

2551. 導覽至 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)2551. 導覽至 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)

2562. 搜尋「Claude」模型2562. 搜尋'Claude'模型

2573. 要求存取所需的 Claude 模型（例如 Claude Sonnet 4.6）2573. 要求存取所需的 Claude 模型（例如 Claude Sonnet 4.6）

2584. 等待核准（可能需要 24-48 小時）2584. 等待核准（可能需要 24-48 小時）

259 259

266Claude Code v2.1.121 或更新版本透過相同的 Application Default Credentials 鏈支援 [X.509 憑證型 Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)。將 `GOOGLE_APPLICATION_CREDENTIALS` 設定為您的認證設定檔案路徑。266Claude Code v2.1.121 或更新版本透過相同的 Application Default Credentials 鏈支援 [X.509 憑證型 Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)。將 `GOOGLE_APPLICATION_CREDENTIALS` 設定為您的認證設定檔案路徑。

267 267

268<Note>268<Note>

269 進行驗證時，Claude Code 將自動使用 `ANTHROPIC_VERTEX_PROJECT_ID` 環境變數中的專案 ID。若要覆寫此設定，請設定下列其中一個環境變數：`GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_APPLICATION_CREDENTIALS`。269 Claude Code 使用 `ANTHROPIC_VERTEX_PROJECT_ID` 作為 Vertex AI 要求的專案 ID。`GCLOUD_PROJECT` 和 `GOOGLE_CLOUD_PROJECT` 環境變數以及 `GOOGLE_APPLICATION_CREDENTIALS` 參考的認證檔案優先於它。如果這些都未設定，專案 ID 會從您的 `gcloud` 設定或附加的服務帳戶解析。

270</Note>270</Note>

271 271

272#### 進階認證設定

273

274Claude Code 透過 `gcpAuthRefresh` 設定支援 GCP 的自動認證重新整理。當 Claude Code 偵測到您的 GCP 認證已過期或無法載入時，它會執行設定的命令以在重試要求之前取得新認證。

275

276```json theme={null}

277{

278 "gcpAuthRefresh": "gcloud auth application-default login",

279 "env": {

280 "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"

281 }

282}

283```

284

285命令的輸出會顯示給使用者，但不支援互動式輸入。這適用於瀏覽器型驗證流程，其中 CLI 顯示 URL，您在瀏覽器中完成驗證。如果驗證未在三分鐘內完成，重新整理命令會逾時。如果您在專案設定（例如 `.claude/settings.json`）中設定 `gcpAuthRefresh`，命令只會在您接受工作區信任提示後執行。

286

272### 4. 設定 Claude Code287### 4. 設定 Claude Code

273 288

274設定下列環境變數：289設定下列環境變數：

363 378

364## 故障排除379## 故障排除

365 380

381如果您遇到「無法載入預設認證」錯誤：

382

383* 執行 `gcloud auth application-default login` 以設定應用程式預設認證

384* 將 `GOOGLE_APPLICATION_CREDENTIALS` 設定為服務帳戶金鑰檔案路徑

385* 請參閱 [設定 GCP 認證](#3-configure-gcp-credentials) 以了解所有選項

386

366如果您遇到配額問題：387如果您遇到配額問題：

367 388

368* 透過 [Cloud Console](https://cloud.google.com/docs/quotas/view-manage) 檢查目前配額或要求增加配額389* 透過 [Cloud Console](https://cloud.google.com/docs/quotas/view-manage) 檢查目前配額或要求增加配額

headless.md +33 −3

Details

54| 設定 | `--settings <file-or-json>` |54| 設定 | `--settings <file-or-json>` |

55| MCP 伺服器 | `--mcp-config <file-or-json>` |55| MCP 伺服器 | `--mcp-config <file-or-json>` |

56| 自訂 agents | `--agents <json>` |56| 自訂 agents | `--agents <json>` |

58 58

59裸機模式跳過 OAuth 和鑰匙圈讀取。Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或傳遞給 `--settings` 的 JSON 中的 `apiKeyHelper`。Bedrock、Vertex 和 Foundry 使用其通常的提供者認證。59裸機模式跳過 OAuth 和鑰匙圈讀取。Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或傳遞給 `--settings` 的 JSON 中的 `apiKeyHelper`。Bedrock、Vertex 和 Foundry 使用其通常的提供者認證。

60 60

66 66

67這些範例突出顯示常見的 CLI 模式。對於 CI 和其他指令碼呼叫，新增 [`--bare`](#start-faster-with-bare-mode) 以便它們不會選擇本地設定的任何內容。67這些範例突出顯示常見的 CLI 模式。對於 CI 和其他指令碼呼叫，新增 [`--bare`](#start-faster-with-bare-mode) 以便它們不會選擇本地設定的任何內容。

68 68

69### 透過 Claude 管道傳送資料

71非互動模式讀取 stdin，因此您可以像任何其他命令列工具一樣管道傳送資料並重新導向回應。

73此範例將建置日誌管道傳送至 Claude 並將說明寫入檔案：

75```bash theme={null}

76cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

77```

79使用 `--output-format json`，回應承載包括 `total_cost_usd` 和每個模型的成本明細，因此指令碼呼叫者可以追蹤每次叫用的支出，而無需查詢 [使用儀表板](/zh-TW/costs)。

81<Note>

82 自 Claude Code v2.1.128 起，管道傳送的 stdin 上限為 10MB。如果超過上限，Claude Code 會以清晰的錯誤和非零狀態代碼退出。若要處理更大的輸入，請將內容寫入檔案，並在提示中參考檔案路徑，而不是管道傳送它。

83</Note>

85### 將 Claude 新增至建置指令碼

87您可以在指令碼中包裝非互動呼叫，以將 Claude 用作專案特定的 linter 或審查者。

89此 `package.json` 指令碼將針對 `main` 的差異管道傳送至 Claude，並要求它報告拼寫錯誤。管道傳送差異意味著 Claude 不需要 Bash 權限來讀取它，而逸出的雙引號使指令碼可移植到 Windows：

91```json theme={null}

92{

93 "scripts": {

94 "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""

95 }

96}

97```

69### 取得結構化輸出99### 取得結構化輸出

70 100

71使用 `--output-format` 控制回應的傳回方式：101使用 `--output-format` 控制回應的傳回方式：

137`system/init` 事件報告工作階段中繼資料，包括模型、工具、MCP 伺服器和載入的外掛程式。除非設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars)，否則它是串流中的第一個事件，在這種情況下 `plugin_install` 事件在其之前。使用外掛程式欄位在外掛程式未載入時使 CI 失敗：167`system/init` 事件報告工作階段中繼資料，包括模型、工具、MCP 伺服器和載入的外掛程式。除非設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars)，否則它是串流中的第一個事件，在這種情況下 `plugin_install` 事件在其之前。使用外掛程式欄位在外掛程式未載入時使 CI 失敗：

138 168

139| 欄位 | 類型 | 描述 |169| 欄位 | 類型 | 描述 |

140| --------------- | -- | ------------------------------------------------------------------------------------------------ |170| --------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------- |

141| `plugins` | 陣列 | 成功載入的外掛程式，每個都有 `name` 和 `path` |171| `plugins` | 陣列 | 成功載入的外掛程式，每個都有 `name` 和 `path` |

142| `plugin_errors` | 陣列 | 外掛程式載入時間錯誤，例如不滿足的相依性版本，每個都有 `plugin`、`type` 和 `message`。受影響的外掛程式被降級並從 `plugins` 中缺失。當沒有錯誤時，金鑰被省略 |172| `plugin_errors` | 陣列 | 外掛程式載入時間錯誤，每個都有 `plugin`、`type` 和 `message`。包括不滿足的相依性版本和 `--plugin-dir` 載入失敗，例如遺失的路徑或無效的封存。受影響的外掛程式被降級並從 `plugins` 中缺失。當沒有錯誤時，金鑰被省略 |

143 173

144當設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars) 時，Claude Code 在第一次轉換前發出 `system/plugin_install` 事件，同時市場外掛程式安裝。使用這些在您自己的 UI 中顯示安裝進度。174當設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars) 時，Claude Code 在第一次轉換前發出 `system/plugin_install` 事件，同時市場外掛程式安裝。使用這些在您自己的 UI 中顯示安裝進度。

145 175

how-claude-code-works.md +9 −15

Details

94 94

95## 使用會話95## 使用會話

96 96

97Claude Code 在您工作時將您的對話儲存在本機。每條訊息、工具使用和結果都被儲存，這使得[重新開始](#undo-changes-with-checkpoints)、[恢復和分叉](#resume-or-fork-sessions)會話成為可能。在 Claude 進行程式碼變更之前，它還會快照受影響的檔案，以便您在需要時可以還原。97Claude Code 在您工作時將您的對話儲存在本機為純文字 JSONL 檔案，位於 `~/.claude/projects/` 下，這使得[重新開始](#undo-changes-with-checkpoints)、[恢復和分叉](#resume-or-fork-sessions)會話成為可能。在 Claude 進行程式碼變更之前，它還會快照受影響的檔案，以便您在需要時可以還原。如需路徑、保留期和如何清除此資料，請參閱[`~/.claude` 中的應用程式資料](/zh-TW/claude-directory#application-data)。

98 98

99**會話是獨立的。** 每個新會話都以新的上下文視窗開始，沒有來自先前會話的對話歷史。Claude 可以使用[自動記憶](/zh-TW/memory#auto-memory)跨會話保留學習內容，您可以在 [CLAUDE.md](/zh-TW/memory) 中新增自己的持久指示。99**會話是獨立的。** 每個新會話都以新的上下文視窗開始，沒有來自先前會話的對話歷史。Claude 可以使用[自動記憶](/zh-TW/memory#auto-memory)跨會話保留學習內容，您可以在 [CLAUDE.md](/zh-TW/memory) 中新增自己的持久指示。

100 100

101### 跨分支工作101### 跨分支工作

102 102

103每個 Claude Code 對話都是綁定到您目前目錄的會話。當您恢復時，您只會看到該目錄中的會話。103每個 Claude Code 對話都是綁定到您目前目錄的會話。`/resume` 選擇器預設顯示目前 worktree 中的會話，並具有鍵盤快捷鍵以擴展清單到其他 worktrees 或專案。請參閱[管理會話](/zh-TW/sessions#use-the-session-picker)以取得完整的選擇器快捷鍵清單以及名稱解析的工作方式。

104 104

105Claude 看到您目前分支的檔案。當您切換分支時，Claude 看到新分支的檔案，但您的對話歷史保持不變。Claude 記得您討論過的內容，即使在切換後也是如此。105Claude 看到您目前分支的檔案。當您切換分支時，Claude 看到新分支的檔案，但您的對話歷史保持不變。Claude 記得您討論過的內容，即使在切換後也是如此。

106 106

107由於會話綁定到目錄，您可以使用 [git worktrees](/zh-TW/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) 執行平行 Claude 會話，這會為個別分支建立單獨的目錄。107由於會話綁定到目錄，您可以使用 [git worktrees](/zh-TW/worktrees) 執行平行 Claude 會話，這會為個別分支建立單獨的目錄。

108 108

109### 恢復或分叉會話109### 恢復或分叉會話

110 110

111當您使用 `claude --continue` 或 `claude --resume` 恢復會話時，您使用相同的會話 ID 從中斷的地方繼續。新訊息附加到現有對話。您的完整對話歷史被還原，但會話範圍的許可不被還原。您需要重新批准這些。111使用 `claude --continue` 或 `claude --resume` 恢復會話會在相同的會話 ID 下重新開啟它，並將新訊息附加到現有對話。使用 `--fork-session` 或 `/branch` 分叉會將歷史複製到新的會話 ID 中，保持原始不變。

112 112

113<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/session-continuity.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=fa41d12bfb57579cabfeece907151d30" alt="會話連續性：恢復繼續相同的會話，分叉使用新 ID 建立新分支。" width="560" height="280" data-path="images/session-continuity.svg" />113<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/session-continuity.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=fa41d12bfb57579cabfeece907151d30" alt="會話連續性：恢復繼續相同的會話，分叉使用新 ID 建立新分支。" width="560" height="280" data-path="images/session-continuity.svg" />

114 114

115要分叉並嘗試不同的方法而不影響原始會話，請使用 `--fork-session` 旗標：115如需恢復旗標、`/resume` 選擇器、命名，以及當相同會話在兩個終端機中開啟時會發生什麼，請參閱[管理會話](/zh-TW/sessions)。

~~116~~

117```bash theme={null}

118claude --continue --fork-session

119```

~~120~~

121這會建立新的會話 ID，同時保留該點之前的對話歷史。原始會話保持不變。與恢復一樣，分叉的會話不會繼承會話範圍的許可。

~~122~~

123**在多個終端機中的相同會話**：如果您在多個終端機中恢復相同的會話，兩個終端機都會寫入相同的會話檔案。來自兩者的訊息會交錯，就像兩個人在同一個筆記本中寫字。沒有任何內容損壞，但對話變得混亂。每個終端機在會話期間只看到自己的訊息，但如果您稍後恢復該會話，您會看到所有內容交錯。對於從相同起點進行的平行工作，使用 `--fork-session` 為每個終端機提供自己的乾淨會話。

124 116

125### 上下文視窗117### 上下文視窗

126 118

134 126

135要控制在壓縮期間保留的內容，請在 CLAUDE.md 中新增「Compact Instructions」部分或使用焦點執行 `/compact`（如 `/compact focus on the API changes`）。127要控制在壓縮期間保留的內容，請在 CLAUDE.md 中新增「Compact Instructions」部分或使用焦點執行 `/compact`（如 `/compact focus on the API changes`）。

136 128

129如果單個檔案或工具輸出非常大，以至於在每次摘要後上下文立即重新填滿，Claude Code 會在幾次嘗試後停止自動壓縮，並顯示錯誤而不是迴圈。請參閱[自動壓縮停止並出現 thrashing 錯誤](/zh-TW/troubleshooting#auto-compaction-stops-with-a-thrashing-error)以取得恢復步驟。

130

137執行 `/context` 以查看什麼在使用空間。MCP 工具定義預設會延遲，並透過[工具搜尋](/zh-TW/mcp#scale-with-mcp-tool-search)按需載入，因此只有工具名稱會消耗上下文，直到 Claude 使用特定工具。執行 `/mcp` 以檢查每個伺服器的成本。131執行 `/context` 以查看什麼在使用空間。MCP 工具定義預設會延遲，並透過[工具搜尋](/zh-TW/mcp#scale-with-mcp-tool-search)按需載入，因此只有工具名稱會消耗上下文，直到 Claude 使用特定工具。執行 `/mcp` 以檢查每個伺服器的成本。

138 132

139#### 使用 skills 和 subagents 管理上下文133#### 使用 skills 和 subagents 管理上下文

140 134

141除了壓縮，您可以使用其他功能來控制什麼載入到上下文中。135除了壓縮，您可以使用其他功能來控制什麼載入到上下文中。

142 136

143[Skills](/zh-TW/skills) 按需載入。Claude 在會話開始時看到 skill 描述，但完整內容只在使用 skill 時載入。對於您手動呼叫的 skills，設定 `disable-model-invocation: true` 以將描述保留在上下文之外，直到您需要它們。137[Skills](/zh-TW/skills) 按需載入。Claude 在會話開始時看到 skill 描述，但完整內容只在使用 skill 時載入。對於您手動呼叫的 skills，設定 `disable-model-invocation: true` 以將描述保留在上下文之外，直到您需要它們。對於您沒有撰寫的 skills，使用 [`skillOverrides`](/zh-TW/skills#override-skill-visibility-from-settings) 從設定中執行相同操作。

144 138

145[Subagents](/zh-TW/sub-agents) 獲得自己的新上下文，完全與您的主要對話分開。他們的工作不會使您的上下文膨脹。完成後，他們返回摘要。這種隔離是 subagents 在長會話中有幫助的原因。139[Subagents](/zh-TW/sub-agents) 獲得自己的新上下文，完全與您的主要對話分開。他們的工作不會使您的上下文膨脹。完成後，他們返回摘要。這種隔離是 subagents 在長會話中有幫助的原因。

146 140

161按 `Shift+Tab` 循環通過許可模式：155按 `Shift+Tab` 循環通過許可模式：

162 156

163* **預設**：Claude 在檔案編輯和 shell 命令之前詢問157* **預設**：Claude 在檔案編輯和 shell 命令之前詢問

164* **自動接受編輯**：Claude 編輯檔案而不詢問，仍然詢問命令158* **自動接受編輯**：Claude 編輯檔案並執行常見的檔案系統命令（如 `mkdir` 和 `mv`）而不詢問，仍然詢問其他命令

165* **Plan Mode**：Claude 僅使用唯讀工具，建立您可以在執行前批准的計畫159* **Plan Mode**：Claude 僅使用唯讀工具，建立您可以在執行前批准的計畫

166* **Auto mode**：Claude 使用背景安全檢查評估所有操作。目前是研究預覽160* **Auto mode**：Claude 使用背景安全檢查評估所有操作。目前是研究預覽

167 161

interactive-mode.md +6 −5

Details

11<Note>11<Note>

12 鍵盤快捷鍵可能因平台和終端而異。按 `?` 查看您環境中可用的快捷鍵。12 鍵盤快捷鍵可能因平台和終端而異。按 `?` 查看您環境中可用的快捷鍵。

13 13

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

15 15

16 * **iTerm2**：設定 → Profiles → Keys → General → 將 Left/Right Option 鍵設定為「Esc+」16 * **iTerm2**：設定 → Profiles → Keys → General → 將 Left/Right Option 鍵設定為「Esc+」

17 * **Apple Terminal**：設定 → Profiles → Keyboard → 勾選「Use Option as Meta Key」17 * **Apple Terminal**：設定 → Profiles → Keyboard → 勾選「Use Option as Meta Key」

42| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切換擴展思考 | 啟用或停用擴展思考模式。在 macOS 上，配置您的終端以傳送 Option 作為 Meta，此快捷鍵才能運作 |42| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切換擴展思考 | 啟用或停用擴展思考模式。{/* min-version: 2.1.132 */}自 v2.1.132 起，此快捷鍵在 macOS 上無需配置 Option 為 Meta 即可運作 |

44 44

45### 文字編輯45### 文字編輯

68| :---------- | :------------- | :------------------------------------------------------------------------------------------- |68| :---------- | :------------- | :------------------------------------------------------------------------------------------- |

74 74

75<Tip>75<Tip>

76 Shift+Enter 在 iTerm2、WezTerm、Ghostty、Kitty、Warp 和 Apple Terminal 中無需配置即可使用。對於 VS Code、Cursor、Windsurf、Alacritty 和 Zed，執行 `/terminal-setup` 以安裝繫結。76 Shift+Enter 在 iTerm2、WezTerm、Ghostty、Kitty、Warp、Apple Terminal 和 Windows Terminal 中無需配置即可使用。對於 VS Code、Cursor、Windsurf、Alacritty 和 Zed，執行 `/terminal-setup` 以安裝繫結。

77</Tip>77</Tip>

78 78

79### 快速命令79### 快速命令

130| 命令 | 動作 |130| 命令 | 動作 |

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

133| `Space` | 向右移動 |

133| `w` | 下一個單字 |134| `w` | 下一個單字 |

134| `e` | 單字結尾 |135| `e` | 單字結尾 |

135| `b` | 上一個單字 |136| `b` | 上一個單字 |

2201. **開始搜尋**：按 `Ctrl+R` 啟動反向歷史搜尋2211. **開始搜尋**：按 `Ctrl+R` 啟動反向歷史搜尋

2212. **輸入查詢**：輸入文字以在先前的命令中搜尋。搜尋詞在匹配結果中醒目提示2222. **輸入查詢**：輸入文字以在先前的命令中搜尋。搜尋詞在匹配結果中醒目提示

2223. **導航匹配項**：再次按 `Ctrl+R` 以循環瀏覽較舊的匹配項2233. **導航匹配項**：再次按 `Ctrl+R` 以循環瀏覽較舊的匹配項

2234. **變更範圍**：按 `Ctrl+S` 以在此會話、此專案和所有專案之間循環2244. **變更範圍**：搜尋預設為所有專案的提示。按 `Ctrl+S` 以在此會話、此專案和所有專案之間循環範圍

2245. **接受匹配項**：2255. **接受匹配項**：

225 * 按 `Tab` 或 `Esc` 以接受目前匹配項並繼續編輯226 * 按 `Tab` 或 `Esc` 以接受目前匹配項並繼續編輯

226 * 按 `Enter` 以接受並立即執行命令227 * 按 `Enter` 以接受並立即執行命令

llm-gateway.md +1 −1

Details

53 53

54默認情況下，Claude Code 使用所選 API 格式的標準模型名稱。54默認情況下，Claude Code 使用所選 API 格式的標準模型名稱。

55 55

56當 `ANTHROPIC_BASE_URL` 指向公開 Anthropic Messages 格式的 gateway 時，Claude Code 在啟動時會查詢 gateway 的 `/v1/models` 端點，並將返回的模型添加到 `/model` 選擇器中。每個發現的條目都標記為「From gateway」，並在提供時使用響應中的 `display_name` 欄位。這需要 Claude Code v2.1.126 或更高版本。56當 `ANTHROPIC_BASE_URL` 指向公開 Anthropic Messages 格式的 gateway 時，Claude Code 在啟動時會查詢 gateway 的 `/v1/models` 端點，並將返回的模型添加到 `/model` 選擇器中。設置 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 以啟用此功能。發現功能默認關閉，以便由共享 API 金鑰支持的 gateway 不會向每個用戶公開該金鑰可以訪問的每個模型。每個發現的條目都標記為「From gateway」，並在提供時使用響應中的 `display_name` 欄位。這需要 Claude Code v2.1.129 或更高版本。

57 57

58發現功能僅適用於 Anthropic Messages 格式。它不會針對 Bedrock 或 Vertex 傳遞端點運行，也不會在 `ANTHROPIC_BASE_URL` 未設置或指向 `api.anthropic.com` 時運行。58發現功能僅適用於 Anthropic Messages 格式。它不會針對 Bedrock 或 Vertex 傳遞端點運行，也不會在 `ANTHROPIC_BASE_URL` 未設置或指向 `api.anthropic.com` 時運行。

59 59

mcp.md +12 −2

Details

327/mcp327/mcp

328```328```

329 329

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

331

332server 名稱 `workspace` 保留供內部使用。如果您的配置定義了具有該名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。

333

330### 動態工具更新334### 動態工具更新

331 335

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

423 427

424## MCP 安裝範圍428## MCP 安裝範圍

425 429

426MCP servers 可以在三個不同的範圍級別進行配置。您選擇的範圍控制 server 在哪些專案中載入，以及配置是否與您的團隊共享。430MCP servers 可以在三個不同的範圍級別進行配置。您選擇的範圍控制 server 在哪些專案中載入，以及配置是否與您的團隊共享。管理員也可以透過[受管配置](#managed-mcp-configuration)在企業級別部署 servers。

427 431

428| 範圍 | 載入位置 | 與團隊共享 | 儲存位置 |432| 範圍 | 載入位置 | 與團隊共享 | 儲存位置 |

429| ------------------------- | ------ | -------- | ------------------- |433| ------------------------- | ------ | -------- | ------------------- |

944 </Step>948 </Step>

945</Steps>949</Steps>

946 950

951您在 Claude Code 中新增的 server 優先於指向相同 URL 的 claude.ai connector。發生這種情況時，`/mcp` 會將 connector 列為隱藏，並顯示如何移除重複項（如果您寧願使用 connector）。

952

947若要在 Claude Code 中停用 claude.ai MCP servers，請將 `ENABLE_CLAUDEAI_MCP_SERVERS` 環境變數設定為 `false`：953若要在 Claude Code 中停用 claude.ai MCP servers，請將 `ENABLE_CLAUDEAI_MCP_SERVERS` 環境變數設定為 `false`：

948 954

949```bash theme={null}955```bash theme={null}

1183 1189

1184`alwaysLoad` 欄位在所有伺服器類型上可用，需要 Claude Code v2.1.121 或更新版本。MCP 伺服器也可以透過在工具的 `_meta` 物件中包含 `"anthropic/alwaysLoad": true` 來標記個別工具為始終載入，這對該工具只有相同的效果。1190`alwaysLoad` 欄位在所有伺服器類型上可用，需要 Claude Code v2.1.121 或更新版本。MCP 伺服器也可以透過在工具的 `_meta` 物件中包含 `"anthropic/alwaysLoad": true` 來標記個別工具為始終載入，這對該工具只有相同的效果。

1185 1191

1192設定 `alwaysLoad: true` 也會阻止啟動直到伺服器連線，上限為標準 5 秒連線逾時。即使設定了 [`MCP_CONNECTION_NONBLOCKING=1`](/zh-TW/env-vars)，這也適用，因為工具必須在建立第一個提示時存在。當啟用非阻塞時，其他伺服器仍在背景中連線。

1193

1186## 使用 MCP 提示作為命令1194## 使用 MCP 提示作為命令

1187 1195

1188MCP servers 可以公開提示，這些提示在 Claude Code 中變成可用的命令。1196MCP servers 可以公開提示，這些提示在 Claude Code 中變成可用的命令。

1231 1239

1232這些選項允許 IT 管理員：1240這些選項允許 IT 管理員：

1233 1241

1234* **控制 MCP servers 員工可以存取的內容**：在整個組織中部署一組標準化的已批准 MCP servers1242* **控制員工可以存取的 MCP servers**：在整個組織中部署一組標準化的已批准 MCP servers

1235* **防止未授權的 MCP servers**：限制使用者新增未批准的 MCP servers1243* **防止未授權的 MCP servers**：限制使用者新增未批准的 MCP servers

1236* **完全停用 MCP**：如果需要，完全移除 MCP 功能1244* **完全停用 MCP**：如果需要，完全移除 MCP 功能

1237 1245

1351* `https://*.example.com/*` - 允許 example.com 的任何子網域1359* `https://*.example.com/*` - 允許 example.com 的任何子網域

1352* `http://localhost:*/*` - 允許 localhost 上的任何連接埠1360* `http://localhost:*/*` - 允許 localhost 上的任何連接埠

1353 1361

1362主機名稱符合不區分大小寫，並忽略尾部 FQDN 點，符合 DNS 語義。像 `*://Mcp.Example.com/*` 這樣的模式符合 `https://mcp.example.com/api`，而 `https://mcp.example.com.` 的處理方式與 `https://mcp.example.com` 相同。配置和路徑保持區分大小寫。

1363

1354**遠端 server 行為**：1364**遠端 server 行為**：

1355 1365

1356* 當允許清單包含**任何** `serverUrl` 項目時，遠端 servers **必須**符合其中一個 URL 模式1366* 當允許清單包含**任何** `serverUrl` 項目時，遠端 servers **必須**符合其中一個 URL 模式

memory.md +2 −0

Details

378* 使指令更具體。「使用 2 空格縮排」比「正確格式化程式碼」效果更好。378* 使指令更具體。「使用 2 空格縮排」比「正確格式化程式碼」效果更好。

379* 查找跨 CLAUDE.md 檔案的衝突指令。如果兩個檔案為相同行為提供不同的指導，Claude 可能會任意選擇一個。379* 查找跨 CLAUDE.md 檔案的衝突指令。如果兩個檔案為相同行為提供不同的指導，Claude 可能會任意選擇一個。

380 380

381如果指令是必須在特定時間點執行的內容，例如在每次提交前或每次檔案編輯後，請改為將其寫成 [hook](/zh-TW/hooks-guide)。Hooks 在固定的生命週期事件中作為 shell 命令執行，並且無論 Claude 決定做什麼都適用。

382

381對於您想要在系統提示級別的指令，請使用 [`--append-system-prompt`](/zh-TW/cli-reference#system-prompt-flags)。這必須在每次呼叫時傳遞，因此它更適合指令碼和自動化，而不是互動式使用。383對於您想要在系統提示級別的指令，請使用 [`--append-system-prompt`](/zh-TW/cli-reference#system-prompt-flags)。這必須在每次呼叫時傳遞，因此它更適合指令碼和自動化，而不是互動式使用。

382 384

383<Tip>385<Tip>

model-config.md +19 −5

Details

184 184

185努力量表按模型進行校準，因此相同的等級名稱在模型之間不代表相同的基礎值。185努力量表按模型進行校準，因此相同的等級名稱在模型之間不代表相同的基礎值。

186 186

187對於一次性的深入推理而不改變您的會話設定，在您的提示中包含「ultrathink」。這會新增一個上下文指令，告訴模型在該輪上進行更多推理；它不會改變發送到 API 的努力等級。187#### 使用 ultrathink 進行一次性深入推理

188

189在您的提示中的任何地方包含 `ultrathink` 以請求在該輪上進行更深入的推理，而不改變您的會話努力設定。Claude Code 識別該關鍵字並新增一個上下文指令。發送到 API 的努力等級保持不變。其他短語如「think」、「think hard」和「think more」會作為普通提示文本傳遞，不被識別為關鍵字。

188 190

189#### 設定努力等級191#### 設定努力等級

190 192

209 211

210在 Opus 4.6 和 Sonnet 4.6 上，您可以設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢復到由 `MAX_THINKING_TOKENS` 控制的先前固定思考預算。請參閱[環境變數](/zh-TW/env-vars)。212在 Opus 4.6 和 Sonnet 4.6 上，您可以設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢復到由 `MAX_THINKING_TOKENS` 控制的先前固定思考預算。請參閱[環境變數](/zh-TW/env-vars)。

211 213

214### 擴展思考

215

216擴展思考是 Claude 在回應前發出的推理。在支援[自適應推理](#adjust-effort-level)的模型上，努力等級是控制發生多少思考的主要控制項；下面的設定會開啟或關閉思考，並控制其顯示方式。

217

218| 控制項 | 如何設定 |

219| :------- | :------------------------------------------------------------------------------------------------------------ |

220| 目前會話的切換 | 在 macOS 上按 `Option+T` 或在 Windows 和 Linux 上按 `Alt+T` |

221| 設定全域預設值 | 執行 `/config` 並切換思考模式。儲存為 `~/.claude/settings.json` 中的 `alwaysThinkingEnabled` |

222| 無論努力如何禁用 | 設定 [`MAX_THINKING_TOKENS=0`](/zh-TW/env-vars)。其他值僅適用於[固定思考預算](#adaptive-reasoning-and-fixed-thinking-budgets) |

223

224思考輸出預設為摺疊。按 `Ctrl+O` 以切換詳細模式並將推理視為灰色斜體文本。Anthropic API 上的互動式會話預設會收到編輯的思考區塊，因此如果您想要在展開時可用的完整摘要，請在[設定](/zh-TW/settings)中設定 `showThinkingSummaries: true`。您需要為所有生成的思考 token 付費，即使它們被摺疊或編輯。

225

212### 擴展 context226### 擴展 context

213 227

214Opus 4.7、Opus 4.6 和 Sonnet 4.6 支援[100 萬個 token 的 context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)，用於具有大型程式碼庫的長時間會話。228Opus 4.7、Opus 4.6 和 Sonnet 4.6 支援[100 萬個 token 的 context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)，用於具有大型程式碼庫的長時間會話。

247 261

248## 新增自訂模型選項262## 新增自訂模型選項

249 263

250使用 `ANTHROPIC_CUSTOM_MODEL_OPTION` 將單一自訂項目新增到 `/model` 選擇器，而無需取代內建別名。這對於測試 Claude Code 預設不列出的模型 ID 很有用。對於 LLM 閘道部署，Claude Code 會自動從閘道的 `/v1/models` 端點填入選擇器，因此只有在探索未傳回您想要的模型時，才需要此變數。請參閱 [LLM 閘道模型選擇](/zh-TW/llm-gateway#model-selection)。264使用 `ANTHROPIC_CUSTOM_MODEL_OPTION` 將單一自訂項目新增到 `/model` 選擇器，而無需取代內建別名。這對於測試 Claude Code 預設不列出的模型 ID 很有用。對於 LLM 閘道部署，當設定 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 時，Claude Code 可以從閘道的 `/v1/models` 端點填入選擇器，因此只有在探索被停用或未傳回您想要的模型時，才需要此變數。請參閱 [LLM 閘道模型選擇](/zh-TW/llm-gateway#model-selection)。

251 265

252此範例設定所有三個變數以使閘道路由的 Opus 部署可選擇：266此範例設定所有三個變數以使閘道路由的 Opus 部署可選擇：

253 267

320 334

321相同的 `_NAME`、`_DESCRIPTION` 和 `_SUPPORTED_CAPABILITIES` 後綴可用於 `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION`。335相同的 `_NAME`、`_DESCRIPTION` 和 `_SUPPORTED_CAPABILITIES` 後綴可用於 `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION`。

322 336

323Claude Code 透過將模型 ID 與已知模式進行匹配來啟用[努力等級](#adjust-effort-level)和[擴展思考](/zh-TW/common-workflows#use-extended-thinking-thinking-mode)等功能。提供者特定的 ID（例如 Bedrock ARN 或自訂部署名稱）通常不符合這些模式，導致支援的功能被禁用。設定 `_SUPPORTED_CAPABILITIES` 以告訴 Claude Code 模型實際支援的功能：337Claude Code 透過將模型 ID 與已知模式進行匹配來啟用[努力等級](#adjust-effort-level)和[擴展思考](#extended-thinking)等功能。提供者特定的 ID（例如 Bedrock ARN 或自訂部署名稱）通常不符合這些模式，導致支援的功能被禁用。設定 `_SUPPORTED_CAPABILITIES` 以告訴 Claude Code 模型實際支援的功能：

324 338

325| 能力值 | 啟用 |339| 能力值 | 啟用 |

326| ---------------------- | ------------------------------------------------------------------- |340| ---------------------- | ------------------------------------------ |

328| `xhigh_effort` | {/* min-version: 2.1.111 */}`xhigh` 努力等級 |342| `xhigh_effort` | {/* min-version: 2.1.111 */}`xhigh` 努力等級 |

333 347

monitoring-usage.md +76 −4

Details

64 受管設定可以透過 MDM（行動裝置管理）或其他裝置管理解決方案進行分發。在受管設定檔中定義的環境變數具有高優先順序，使用者無法覆蓋。64 受管設定可以透過 MDM（行動裝置管理）或其他裝置管理解決方案進行分發。在受管設定檔中定義的環境變數具有高優先順序，使用者無法覆蓋。

65</Note>65</Note>

66 66

67Claude Code 不會將 `OTEL_*` 環境變數傳遞給它產生的子程序，包括 Bash 工具、hooks、MCP 伺服器和語言伺服器。透過 Bash 工具執行的 OpenTelemetry 檢測應用程式不會繼承 Claude Code 的匯出器端點或標頭，因此如果該應用程式需要匯出自己的遙測，請直接在命令中設定這些變數。

67## 配置詳情69## 配置詳情

68 70

69### 常見配置變數71### 常見配置變數

83| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` | mTLS 身份驗證的用戶端金鑰 | 用戶端金鑰檔案的路徑 |

84| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE` | mTLS 身份驗證的用戶端憑證 | 用戶端憑證檔案的路徑 |

85| `OTEL_METRIC_EXPORT_INTERVAL` | 匯出間隔（毫秒）（預設：60000） | `5000`、`60000` |85| `OTEL_METRIC_EXPORT_INTERVAL` | 匯出間隔（毫秒）（預設：60000） | `5000`、`60000` |

86| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |86| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |

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

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

93 93

94### mTLS 身份驗證

96您為 OTLP 匯出器配置用戶端憑證的方式取決於該訊號使用的 OTLP 協議，透過 `OTEL_EXPORTER_OTLP_PROTOCOL` 或每個訊號的覆蓋設定。相同的配置適用於指標、日誌和追蹤。

98| 協議 | 用戶端憑證變數 | 信任收集器的 CA |

99| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |

100| `http/protobuf`、`http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和可選的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。請參閱[網路配置](/zh-TW/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |

101| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或每個訊號的變體，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以針對每個訊號使用不同的憑證 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |

102

103對於 `grpc`，OpenTelemetry SDK 直接讀取標準 OTLP 變數，因此設定每個訊號指標變數的現有配置會繼續運作。

104

94### 指標基數控制105### 指標基數控制

95 106

96以下環境變數控制指標中包含哪些屬性以管理基數：107以下環境變數控制指標中包含哪些屬性以管理基數：

107 118

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

109 120

110追蹤預設為關閉。若要啟用它，請同時設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然後設定 `OTEL_TRACES_EXPORTER` 以選擇跨度的傳送位置。追蹤重複使用[常見 OTLP 配置](#common-configuration-variables)以取得端點、協議和標頭。121追蹤預設為關閉。若要啟用它，請同時設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然後設定 `OTEL_TRACES_EXPORTER` 以選擇跨度的傳送位置。追蹤重複使用[常見 OTLP 配置](#common-configuration-variables)以取得端點、協議、標頭和 [mTLS](#mtls-authentication)。

111 122

112| 環境變數 | 描述 | 範例值 |123| 環境變數 | 描述 | 範例值 |

113| ------------------------------------- | ----------------------------------------------- | ---------------------------------- |124| ------------------------------------- | ----------------------------------------------- | ---------------------------------- |

233 244

234### 動態標頭245### 動態標頭

235 246

236對於需要動態身份驗證的企業環境，您可以配置指令碼來動態產生標頭：247對於需要動態身份驗證的企業環境，您可以配置指令碼來動態產生標頭。動態標頭僅適用於 `http/protobuf` 和 `http/json` 協議。`grpc` 匯出器僅使用靜態 `OTEL_EXPORTER_OTLP_HEADERS` 值。

237 248

238#### 設定配置249#### 設定配置

239 250

899 910

900**效能監控**：追蹤 API 請求持續時間和工具執行時間以識別效能瓶頸。911**效能監控**：追蹤 API 請求持續時間和工具執行時間以識別效能瓶頸。

901 912

913## 稽核安全事件

914

915OpenTelemetry 事件是 Claude Code 活動的稽核資料來源。每個事件都帶有身份屬性，將工具呼叫、MCP 活動和權限決定與觸發它們的使用者相關聯，OTLP 日誌匯出器可以將這些事件傳遞到任何具有 OTLP 接收器的安全資訊和事件管理 (SIEM) 平台或轉發到您的 SIEM 的 OpenTelemetry Collector。

916

917### 將屬性操作歸因於使用者

918

919每個事件上的[標準屬性](#standard-attributes)包括已驗證使用者的身份：使用 Claude 帳戶登入時的 `user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`，加上安裝範圍的 `user.id` 和每個工作階段的 `session.id`。

920

921MCP 工具呼叫、Bash 命令和檔案編輯因此歸因於啟動工作階段的開發人員。Claude Code 不在單獨的服務帳戶下運作；每個事件上記錄的身份是開發人員自己的 Claude 帳戶。

922

923當 Claude Code 使用直接 API 金鑰進行身份驗證，或針對 Bedrock、Vertex AI 或 Microsoft Foundry 進行身份驗證時，工作階段中沒有 Claude 帳戶，僅填充 `user.id` 和 `session.id`。在這些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自行附加使用者身份，透過[受管設定](#administrator-configuration)檔案或啟動包裝器按使用者設定：

924

925```bash theme={null}

926export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

927```

928

929### 稽核 MCP 活動

930

931若要使用完整呼叫詳情捕捉 MCP 伺服器活動，請啟用日誌匯出器並設定 `OTEL_LOG_TOOL_DETAILS=1`。每個 MCP 操作然後產生結構化事件，其中包含伺服器名稱、工具名稱和呼叫引數以及標準身份屬性：

932

933| 事件 | 它為 MCP 記錄的內容 |

934| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |

935| `mcp_server_connection` | 伺服器連線、斷開連線和連線失敗，包含 `server_name`、`transport_type`、`server_scope` 和錯誤詳情 |

936| `tool_result` | 每個 MCP 工具呼叫，包含 `tool_name` 和 `mcp_server_scope`、包含 `mcp_server_name` 和 `mcp_tool_name` 的 `tool_parameters` 承載，以及包含呼叫引數的 `tool_input` 承載 |

937| `tool_decision` | 呼叫是否被允許或拒絕，以及決定是來自配置、hook 還是使用者 |

938

939沒有 `OTEL_LOG_TOOL_DETAILS`，`tool_result` 事件仍然帶有 `tool_name` 和 `mcp_server_scope` 但省略 `mcp_server_name`/`mcp_tool_name` 細分和引數，`mcp_server_connection` 事件省略 `server_name` 和錯誤訊息。

940

941### 將安全問題對應到事件

942

943建立偵測規則時，查詢您想要監控的訊號並查詢您的後端以取得相應的事件和屬性：

944

945| 訊號 | 事件 | 關鍵屬性 |

946| ---------------- | -------------------------------------------- | ---------------------------------------------------------- |

947| 工具呼叫被允許或拒絕，以及由什麼 | `tool_decision` | `decision`、`source`、`tool_name` |

948| 權限模式升級 | `permission_mode_changed` | `from_mode`、`to_mode`、`trigger` |

949| 原則 hook 阻止了操作 | `hook_execution_complete` | `hook_event`、`num_blocking` |

950| 登入、登出和身份驗證失敗 | `auth` | `action`、`success`、`error_category` |

951| MCP 伺服器連線或失敗 | `mcp_server_connection` | `status`、`server_name`、`error_code` |

952| Plugin 已安裝及其來源 | `plugin_installed` | `plugin.name`、`marketplace.name`、`marketplace.is_official` |

953| 執行的命令和觸及的檔案 | `tool_result` with `OTEL_LOG_TOOL_DETAILS=1` | `tool_parameters`、`tool_input` |

954

955Claude Code 僅發出原始事件流。異常偵測、基線設定、跨工作階段關聯和警報是您的 SIEM 或可觀測性後端的責任。

956

957### 將事件傳送到 SIEM

958

959將 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` 指向您的 SIEM 的 OTLP 接收器，或指向轉發到您的 SIEM 的原生擷取 API 的 OpenTelemetry Collector。以下受管設定範例僅匯出事件，並啟用完整工具詳情以進行 MCP 和 Bash 稽核：

960

961```json theme={null}

962{

963 "env": {

964 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

965 "OTEL_LOGS_EXPORTER": "otlp",

966 "OTEL_LOG_TOOL_DETAILS": "1",

967 "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",

968 "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",

969 "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"

970 }

971}

972```

973

902## 後端考量974## 後端考量

903 975

904您選擇的指標、日誌和追蹤後端決定了您可以執行的分析類型：976您選擇的指標、日誌和追蹤後端決定了您可以執行的分析類型：

output-styles.md +12 −3

Details

6 6

7> 將 Claude Code 適配用於軟體工程以外的用途7> 將 Claude Code 適配用於軟體工程以外的用途

8 8

~~9輸出樣式允許您將 Claude Code 用作任何類型的代理，同時保留其核心功能，例如執行本地指令碼、讀取/寫入檔案和追蹤待辦事項。~~9輸出樣式改變 Claude 的回應方式，而不是 Claude 知道什麼。它們修改系統提示以設定角色、語氣和輸出格式，同時保留核心功能，例如執行指令碼、讀取和寫入檔案，以及追蹤待辦事項。當您每次都重新提示相同的語音或格式，或者當您希望 Claude 充當軟體工程師以外的角色時，請使用一個。

11有關您的專案、慣例或程式碼庫的說明，請改用 [CLAUDE.md](/zh-TW/memory)。

10 12

11## 內建輸出樣式13## 內建輸出樣式

12 14

63[Define how the assistant should behave in this style...]65[Define how the assistant should behave in this style...]

64```66```

65 67

~~66您可以在使用者層級 (`~/.claude/output-styles`) 或專案層級 (`.claude/output-styles`) 儲存這些檔案。~~68您可以在三個層級儲存這些檔案：

70* 使用者：`~/.claude/output-styles`

71* 專案：`.claude/output-styles`

72* 受管原則：[受管設定目錄](/zh-TW/settings#settings-files)內的 `.claude/output-styles`

74[Plugins](/zh-TW/plugins-reference) 也可以在 `output-styles/` 目錄中提供輸出樣式。

67 75

68### Frontmatter76### Frontmatter

69 77

70輸出樣式檔案支援 frontmatter 以指定中繼資料：78輸出樣式檔案支援 frontmatter 以指定中繼資料：

71 79

72| Frontmatter | 用途 | 預設 |80| Frontmatter | 用途 | 預設 |

~~73| :------------------------- | :------------------------------ | :------ |~~81| :------------------------- | :--------------------------------------------------------------------------------------------------- | :------ |

75| `description` | 輸出樣式的描述，在 `/config` 選擇器中顯示 | 無 |83| `description` | 輸出樣式的描述，在 `/config` 選擇器中顯示 | 無 |

85| `force-for-plugin` | 僅限 Plugin 輸出樣式：在啟用 plugin 時自動應用此樣式，無需要求使用者選擇它。覆蓋使用者的 `outputStyle` 設定。如果多個啟用的 plugin 設定此項，則第一個載入的獲勝。 | false |

77 86

78## 與相關功能的比較87## 與相關功能的比較

79 88

plugins.md +6 −0

Details

315 ```315 ```

316</Tip>316</Tip>

317 317

318若要測試已打包為 `.zip` 檔案並託管在 URL 上的 plugin（例如 CI 建置成品），請改用 `--plugin-url`。Claude Code 在啟動時擷取檔案並僅為該工作階段載入它。如果擷取失敗或檔案無效，Claude Code 會報告 plugin 載入錯誤並在沒有它的情況下啟動。與任何 plugin 來源相同的[信任考量](/zh-TW/discover-plugins#security)適用：只將此旗標指向您控制或信任的檔案。

319

320```bash theme={null}

321claude --plugin-url https://example.com/my-plugin.zip

322```

323

318### 偵錯 plugin 問題324### 偵錯 plugin 問題

319 325

320如果您的 plugin 未按預期工作：326如果您的 plugin 未按預期工作：

plugins-reference.md +15 −9

Details

301]301]

302```302```

303 303

304若要內聯宣告 monitors，請將 `plugin.json` 中的 `monitors` 金鑰設定為相同的陣列。若要從非預設路徑載入，請將 `monitors` 設定為相對路徑字串，例如 `"./config/monitors.json"`。304若要內聯宣告 monitors，請將 `plugin.json` 中的 `experimental.monitors` 設定為相同的陣列。若要從非預設路徑載入，請將 `experimental.monitors` 設定為相對路徑字串，例如 `"./config/monitors.json"`。Monitors 是 [experimental component](#experimental-components)。

305 305

306**必需欄位：**306**必需欄位：**

307 307

323 323

324### Themes324### Themes

325 325

326Plugins 可以提供顏色主題，這些主題與內建預設值和使用者的本機主題一起出現在 `/theme` 中。主題是 `themes/` 中的 JSON 檔案，具有 `base` 預設值和稀疏的 `overrides` 顏色令牌對應。326Plugins 可以提供顏色主題，這些主題與內建預設值和使用者的本機主題一起出現在 `/theme` 中。主題是 `themes/` 中的 JSON 檔案，具有 `base` 預設值和稀疏的 `overrides` 顏色令牌對應。Themes 是 [experimental component](#experimental-components)。

327 327

328```json theme={null}328```json theme={null}

329{329{

384 "hooks": "./config/hooks.json",384 "hooks": "./config/hooks.json",

385 "mcpServers": "./mcp-config.json",385 "mcpServers": "./mcp-config.json",

386 "outputStyles": "./styles/",386 "outputStyles": "./styles/",

387 "themes": "./themes/",

388 "lspServers": "./.lsp.json",387 "lspServers": "./.lsp.json",

389 "monitors": "./monitors.json",388 "experimental": {

389 "themes": "./themes/",

390 "monitors": "./monitors.json"

391 },

390 "dependencies": [392 "dependencies": [

391 "helper-lib",393 "helper-lib",

392 { "name": "secrets-vault", "version": "~2.1.0" }394 { "name": "secrets-vault", "version": "~2.1.0" }

420### 元件路徑欄位422### 元件路徑欄位

421 423

422| 欄位 | 類型 | 描述 | 範例 |424| 欄位 | 類型 | 描述 | 範例 |

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

435| `dependencies` | array | 此 plugin 需要的其他 plugins，可選擇使用 semver 版本限制。請參閱 [Constrain plugin dependency versions](/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |437| `dependencies` | array | 此 plugin 需要的其他 plugins，可選擇使用 semver 版本限制。請參閱 [Constrain plugin dependency versions](/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

436 438

439### 實驗性元件

440

441`experimental` 金鑰下的元件 `themes` 和 `monitors` 具有在版本之間穩定時可能會變更的 manifest 架構。您宣告它們的位置是一個單獨的遷移：頂層仍然有效，`claude plugin validate` 會發出警告，未來的版本將需要 `experimental.*`。

442

437### User configuration443### User configuration

438 444

439`userConfig` 欄位宣告 Claude Code 在啟用 plugin 時提示使用者的值。使用此方法而不是要求使用者手動編輯 `settings.json`。445`userConfig` 欄位宣告 Claude Code 在啟用 plugin 時提示使用者的值。使用此方法而不是要求使用者手動編輯 `settings.json`。

504 510

505### 路徑行為規則511### 路徑行為規則

506 512

507對於 `skills`、`commands`、`agents`、`outputStyles`、`themes` 和 `monitors`，自訂路徑取代預設值。如果 manifest 指定 `skills`，預設 `skills/` 目錄不會被掃描；如果它指定 `monitors`，預設 `monitors/monitors.json` 不會被載入。[Hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers) 有不同的語義來處理多個來源。513對於 `skills`、`commands`、`agents`、`outputStyles`、`experimental.themes` 和 `experimental.monitors`，自訂路徑取代預設值。如果 manifest 指定 `skills`，預設 `skills/` 目錄不會被掃描；如果它指定 `experimental.monitors`，預設 `monitors/monitors.json` 不會被載入。[Hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers) 有不同的語義來處理多個來源。

508 514

509* 所有路徑必須相對於 plugin 根目錄，並以 `./` 開頭515* 所有路徑必須相對於 plugin 根目錄，並以 `./` 開頭

510* 來自自訂路徑的元件使用相同的命名和命名空間規則516* 來自自訂路徑的元件使用相同的命名和命名空間規則

605 611

606Plugins 可以透過以下兩種方式之一指定：612Plugins 可以透過以下兩種方式之一指定：

607 613

608* 透過 `claude --plugin-dir`，在工作階段期間。614* 透過 `claude --plugin-dir` 或 `claude --plugin-url`，在工作階段期間。

609* 透過 marketplace，為未來的工作階段安裝。615* 透過 marketplace，為未來的工作階段安裝。

610 616

611出於安全和驗證目的，Claude Code 將 *marketplace* plugins 複製到使用者的本機 **plugin 快取**（`~/.claude/plugins/cache`），而不是就地使用它們。在開發參考外部檔案的 plugins 時，理解此行為很重要。617出於安全和驗證目的，Claude Code 將 *marketplace* plugins 複製到使用者的本機 **plugin 快取**（`~/.claude/plugins/cache`），而不是就地使用它們。在開發參考外部檔案的 plugins 時，理解此行為很重要。

routines.md +71 −21

Details

14 14

15每個例行程序可以附加一個或多個觸發器：15每個例行程序可以附加一個或多個觸發器：

16 16

~~17* **排程**：按照每小時、每晚或每週等定期節奏運行~~17* **排程**：按照每小時、每晚或每週等定期節奏運行，或在特定的未來時間運行一次

18* **API**：通過向每個例行程序端點發送帶有持有人令牌的 HTTP POST 來按需觸發18* **API**：通過向每個例行程序端點發送帶有持有人令牌的 HTTP POST 來按需觸發

19* **GitHub**：自動回應存儲庫事件，例如拉取請求或發佈19* **GitHub**：自動回應存儲庫事件，例如拉取請求或發佈

20 20

44 44

45## 創建例行程序45## 創建例行程序

46 46

47從 Web、Desktop 應用或 CLI 創建例行程序。所有三個界面都寫入同一個雲帳戶，因此您在 CLI 中創建的例行程序會立即顯示在 claude.ai/code/routines 上。在 Desktop 應用中，點擊 **New task** 並選擇 **New remote task**；選擇 **New local task** 會創建一個 [local Desktop scheduled task](/zh-TW/desktop-scheduled-tasks)，它在您的機器上運行，不是例行程序。47從 Web 的 [claude.ai/code/routines](https://claude.ai/code/routines)、Desktop 應用或 CLI 創建例行程序。所有三個界面都寫入同一個雲帳戶，因此您在其中一個創建的例行程序會立即顯示在其他界面中。在 Desktop 應用中，點擊側邊欄中的 **Routines**，然後點擊 **New routine**，並選擇 **Remote**；選擇 **Local** 會創建一個 [Desktop scheduled task](/zh-TW/desktop-scheduled-tasks)，它在您的機器上運行，而不是在雲中運行。

48 48

49創建表單設置例行程序的提示、存儲庫、環境、connectors 和觸發器。49創建表單設置例行程序的提示、存儲庫、環境、connectors 和觸發器。

50 50

66 </Step>66 </Step>

67 67

68 <Step title="選擇存儲庫">68 <Step title="選擇存儲庫">

69 添加一個或多個 GitHub 存儲庫供 Claude 在其中工作。每個存儲庫在運行開始時從默認分支克隆。Claude 為其更改創建 `claude/` 前綴的分支。要允許推送到任何分支，請為該存儲庫啟用 **Allow unrestricted branch pushes**。69 添加一個或多個 GitHub 存儲庫供 Claude 在其中工作。每個存儲庫在運行開始時從默認分支克隆。Claude 為其更改創建 `claude/` 前綴的分支。

70 </Step>70 </Step>

71 71

72 <Step title="選擇環境">72 <Step title="選擇環境">

74 74

75 * **Network access**：設置每次運行期間可用的互聯網訪問級別75 * **Network access**：設置每次運行期間可用的互聯網訪問級別

76 * **Environment variables**：提供 API 密鑰、令牌或其他 Claude 可以使用的機密76 * **Environment variables**：提供 API 密鑰、令牌或其他 Claude 可以使用的機密

77 * **Setup script**：在每個會話開始前運行安裝命令，例如安裝依賴項或配置工具。結果是 [cached](/zh-TW/claude-code-on-the-web#environment-caching)，因此腳本不會在每個會話上重新運行77 * **Setup script**：安裝例行程序需要的依賴項和工具。結果是 [cached](/zh-TW/claude-code-on-the-web#environment-caching)，因此腳本不會在每個會話上重新運行

78 78

~~79 提供了一個 **Default** 環境。要使用自定義環境，請在創建例行程序前 [create one](/zh-TW/claude-code-on-the-web#the-cloud-environment)。~~79 提供了一個 **Default** 環境，具有 **Trusted** 網絡訪問，允許 [default set](/zh-TW/claude-code-on-the-web#default-allowed-domains) 的包註冊表、雲提供商 API、容器註冊表和常見開發域，但阻止其他所有內容。如果您的例行程序需要到達您自己的服務或該列表之外的域，請在運行前編輯環境的 [network access](/zh-TW/claude-code-on-the-web#network-access)。要使用單獨的環境，請先 [create one](/zh-TW/claude-code-on-the-web#configure-your-environment)。

80 </Step>80 </Step>

81 81

82 <Step title="選擇觸發器">82 <Step title="選擇觸發器">

84 84

85 <Tabs>85 <Tabs>

86 <Tab title="Schedule">86 <Tab title="Schedule">

~~87 選擇預設頻率：每小時、每天、工作日或每週。有關時區處理、交錯和自定義 cron 間隔，請參閱 [Add a schedule trigger](#add-a-schedule-trigger)。~~87 選擇預設頻率進行定期運行，或在特定時間戳安排一次性運行。有關時區處理、交錯、自定義 cron 間隔和一次性運行，請參閱 [Add a schedule trigger](#add-a-schedule-trigger)。

88 </Tab>88 </Tab>

89 89

90 <Tab title="GitHub event">90 <Tab title="GitHub event">

97 </Tabs>97 </Tabs>

98 </Step>98 </Step>

99 99

100 <Step title="審查 connectors">100 <Step title="審查 connectors 和權限">

101 默認情況下包括您所有連接的 [MCP connectors](/zh-TW/mcp)。移除例行程序不需要的任何。Connectors 在每次運行期間讓 Claude 可以訪問外部服務，如 Slack、Linear 或 Google Drive。101 表單底部的 **Connectors** 和 **Permissions** 選項卡控制例行程序可以到達的內容。

102

103 在 Connectors 下，默認情況下包括您所有連接的 [MCP connectors](/zh-TW/mcp)。移除例行程序不需要的任何。Claude 可以使用包含的 connector 中的每個工具，包括寫入，無需在運行期間請求權限。

104

105 在 Permissions 下，為任何 Claude 應該能夠推送到現有分支而不是僅 `claude/` 前綴分支的存儲庫啟用 **Allow unrestricted branch pushes**。

102 </Step>106 </Step>

103 107

104 <Step title="創建例行程序">108 <Step title="創建例行程序">

110 114

111### 從 CLI 創建115### 從 CLI 創建

112 116

113在任何會話中運行 `/schedule` 以對話方式創建排程例行程序。您也可以直接傳遞描述，如 `/schedule daily PR review at 9am`。Claude 會逐步介紹 Web 表單收集的相同信息，然後將例行程序保存到您的帳戶。117在任何會話中運行 `/schedule` 以對話方式創建排程例行程序。您也可以直接傳遞描述，例如定期例行程序如 `/schedule daily PR review at 9am` 或一次性例行程序如 `/schedule clean up feature flag in one week`。Claude 會逐步介紹 Web 表單收集的相同信息，然後將例行程序保存到您的帳戶。

114 118

115CLI 中的 `/schedule` 僅創建排程例行程序。要添加 API 或 GitHub 觸發器，請在 [claude.ai/code/routines](https://claude.ai/code/routines) 的 Web 上編輯例行程序。119CLI 中的 `/schedule` 僅創建排程例行程序。要添加 API 或 GitHub 觸發器，請在 [claude.ai/code/routines](https://claude.ai/code/routines) 的 Web 上編輯例行程序。

116 120

117CLI 還支持管理現有例行程序。運行 `/schedule list` 查看所有例行程序，`/schedule update` 更改一個，或 `/schedule run` 立即觸發它。121CLI 還支持管理現有例行程序。運行 `/schedule list` 查看所有例行程序，`/schedule update` 更改一個，或 `/schedule run` 立即觸發它。

118 122

119### 從 Desktop 應用創建

~~120~~

121在 Desktop 應用中打開 **Schedule** 頁面，點擊 **New task**，並選擇 **New remote task**。Desktop 應用在同一網格中顯示本地排程任務和例行程序。有關本地選項的詳細信息，請參閱 [Desktop scheduled tasks](/zh-TW/desktop-scheduled-tasks)。

~~122~~

123## 配置觸發器123## 配置觸發器

124 124

125當其觸發器之一匹配時，例行程序啟動。您可以將排程、API 和 GitHub 觸發器的任何組合附加到同一例行程序，並可以隨時從例行程序編輯表單的 **Select a trigger** 部分添加或移除它們。125當其觸發器之一匹配時，例行程序啟動。您可以將排程、API 和 GitHub 觸發器的任何組合附加到同一例行程序，並可以隨時從例行程序編輯表單的 **Select a trigger** 部分添加或移除它們。

126 126

127### 添加排程觸發器127### 添加排程觸發器

128 128

129排程觸發器按定期節奏運行例行程序。在 **Select a trigger** 部分中選擇預設頻率：每小時、每天、工作日或每週。時間以您的本地時區輸入並自動轉換，因此例行程序在該掛鐘時間運行，無論雲端基礎設施位於何處。129排程觸發器按定期節奏運行例行程序，或在特定的未來時間運行一次。在 **Select a trigger** 部分中選擇預設頻率：每小時、每天、工作日或每週。時間以您的本地時區輸入並自動轉換，因此例行程序在該掛鐘時間運行，無論雲端基礎設施位於何處。

130 130

131運行可能在排程時間後幾分鐘開始，原因是交錯。每個例行程序的偏移是一致的。131運行可能在排程時間後幾分鐘開始，原因是交錯。每個例行程序的偏移是一致的。

132 132

133對於自定義間隔，例如每兩小時或每月的第一天，在表單中選擇最接近的預設，然後在 CLI 中運行 `/schedule update` 以設置特定的 cron 表達式。最小間隔是一小時；運行頻率更高的表達式會被拒絕。133對於自定義間隔，例如每兩小時或每月的第一天，在表單中選擇最接近的預設，然後在 CLI 中運行 `/schedule update` 以設置特定的 cron 表達式。最小間隔是一小時；運行頻率更高的表達式會被拒絕。

134 134

135#### 排程一次性運行

136

137一次性排程在特定時間戳處觸發例行程序一次。使用它來提醒自己本週稍後、在推出完成後打開清理 PR，或在上游更改到達時啟動後續任務。例行程序觸發後，它會自動禁用，Web UI 將其標記為 **Ran**。要再次運行它，編輯例行程序並設置新的一次性時間。

138

139通過在 CLI 中用自然語言描述時間來創建一次性運行。Claude 根據當前時間解析該短語，並在保存前確認絕對時間戳。

140

141```text theme={null}

142/schedule tomorrow at 9am, summarize yesterday's merged PRs

143```

144

145```text theme={null}

146/schedule in 2 weeks, open a cleanup PR that removes the feature flag

147```

148

149與定期排程相同的本地到 UTC 轉換適用於一次性時間戳。

150

151一次性運行不計入每日例行程序運行上限。它們像任何其他會話一樣消耗您計劃的常規訂閱使用量。有關詳細信息，請參閱 [Usage and limits](#usage-and-limits)。

152

135### 添加 API 觸發器153### 添加 API 觸發器

136 154

137API 觸發器為例行程序提供專用的 HTTP 端點。使用例行程序的持有人令牌 POST 到端點會啟動新會話並返回會話 URL。使用此功能將 Claude Code 連接到警報系統、部署管道、內部工具或任何可以進行身份驗證 HTTP 請求的地方。155API 觸發器為例行程序提供專用的 HTTP 端點。使用例行程序的持有人令牌 POST 到端點會啟動新會話並返回會話 URL。使用此功能將 Claude Code 連接到警報系統、部署管道、內部工具或任何可以進行身份驗證 HTTP 請求的地方。

144 </Step>162 </Step>

145 163

146 <Step title="添加 API 觸發器">164 <Step title="添加 API 觸發器">

147 滾動到提示下方的 **Select a trigger** 部分，點擊 **Add another trigger**，並選擇 **API**。165 滾動到 **Instructions** 框下方的 **Select a trigger** 部分，點擊 **Add another trigger**，並選擇 **API**。

148 </Step>166 </Step>

149 167

150 <Step title="複製 URL 並生成令牌">168 <Step title="複製 URL 並生成令牌">

250| Labels | 應用於 PR 的標籤 |268| Labels | 應用於 PR 的標籤 |

251| Is draft | PR 是否處於草稿狀態 |269| Is draft | PR 是否處於草稿狀態 |

252| Is merged | PR 是否已合併 |270| Is merged | PR 是否已合併 |

253| From fork | PR 是否來自分支 |

254 271

255每個篩選器將字段與運算符配對：等於、包含、開始於、是其中之一、不是其中之一或匹配正則表達式。272每個篩選器將字段與運算符配對：等於、包含、開始於、是其中之一、不是其中之一或匹配正則表達式。

256 273

259一些示例篩選器組合：276一些示例篩選器組合：

260 277

261* **Auth module review**：base branch `main`，head branch 包含 `auth-provider`。將任何涉及身份驗證的 PR 發送給專注的審查者。278* **Auth module review**：base branch `main`，head branch 包含 `auth-provider`。將任何涉及身份驗證的 PR 發送給專注的審查者。

262* **External contributor triage**：from fork 是 `true`。在人工查看前，通過額外的安全和風格審查路由每個基於分支的 PR。

263* **Ready-for-review only**：is draft 是 `false`。跳過草稿，以便例行程序僅在 PR 準備好審查時運行。279* **Ready-for-review only**：is draft 是 `false`。跳過草稿，以便例行程序僅在 PR 準備好審查時運行。

264* **Label-gated backport**：labels 包括 `needs-backport`。僅當維護者標記 PR 時才觸發移植到另一分支的例行程序。280* **Label-gated backport**：labels 包括 `needs-backport`。僅當維護者標記 PR 時才觸發移植到另一分支的例行程序。

265 281

275 291

276點擊任何運行以將其作為完整會話打開。從那裡您可以看到 Claude 做了什麼、審查更改、創建拉取請求或繼續對話。每個運行會話的工作方式與任何其他會話相同：使用會話標題旁邊的下拉菜單重命名、存檔或刪除它。292點擊任何運行以將其作為完整會話打開。從那裡您可以看到 Claude 做了什麼、審查更改、創建拉取請求或繼續對話。每個運行會話的工作方式與任何其他會話相同：使用會話標題旁邊的下拉菜單重命名、存檔或刪除它。

277 293

294<Note>

295 運行列表中的綠色狀態表示會話已啟動並退出，沒有基礎設施錯誤。這並不意味著您提示中的任務成功。打開運行以讀取記錄並確認 Claude 實際上做了什麼。被阻止的網絡請求、缺失的 connector 工具和任務級別的失敗都會在那裡顯示，而不是在狀態指示器中。

296</Note>

297

278### 編輯和控制例行程序298### 編輯和控制例行程序

279 299

280從例行程序詳細信息頁面，您可以：300從例行程序詳細信息頁面，您可以：

300 320

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

302 322

303### 環境323### 環境和網絡訪問

324

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

304 326

305每個例行程序在 [cloud environment](/zh-TW/claude-code-on-the-web#the-cloud-environment) 中運行，該環境控制網絡訪問、環境變量和設置腳本。在創建例行程序前配置環境，以便 Claude 訪問 API、安裝依賴項或限制網絡範圍。有關完整的設置指南，請參閱 [cloud environment](/zh-TW/claude-code-on-the-web#the-cloud-environment)。327**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)。

328

329要允許其他域：

330

331<Steps>

332 <Step title="打開例行程序進行編輯">

333 在例行程序的詳細信息頁面上，點擊鉛筆圖標打開 **Edit routine**。

334 </Step>

335

336 <Step title="打開環境選擇器">

337 在 **Instructions** 框下方，選擇顯示您環境名稱的雲圖標，例如 **Default**。

338 </Step>

339

340 <Step title="打開環境設置">

341 將滑鼠懸停在列表中的環境上，然後點擊右側出現的設置圖標。

342 </Step>

343

344 <Step title="更改網絡訪問級別">

345 在 **Update cloud environment** 對話框中，將 **Network access** 更改為 **Custom** 並在 **Allowed domains** 中輸入您的域。檢查 **Also include default list of common package managers** 以在自定義域旁邊保留 [默認允許列表](/zh-TW/claude-code-on-the-web#default-allowed-domains)。選擇 **Full** 以獲得不受限制的訪問。

346 </Step>

347

348 <Step title="保存">

349 點擊 **Save changes**。新策略從下一次運行開始應用。

350 </Step>

351</Steps>

352

353有關訪問級別和默認允許列表的詳細信息，請參閱 [Network access](/zh-TW/claude-code-on-the-web#network-access)。

306 354

307## 使用和限制355## 使用和限制

308 356

309例行程序以與交互式會話相同的方式消耗訂閱使用量。除了標準訂閱限制外，例行程序還有每個帳戶每天可以啟動多少次運行的每日上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您當前的消耗和剩餘的每日例行程序運行。357例行程序以與互動式工作階段相同的方式消耗訂閱使用量。除了標準訂閱限制外，例行程序還有每個帳戶每天可以啟動多少次執行的每日上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您目前的消耗和剩餘的每日例行程序執行。

358

359當例行程序達到每日上限或您的訂閱使用限制時，啟用了額外使用的組織可以繼續在計量超額上執行例行程序。沒有額外使用，額外執行會被拒絕，直到時間窗口重置。從 claude.ai 上的 **Settings > Billing** 啟用額外使用。

310 360

311當例行程序達到每日上限或您的訂閱使用限制時，啟用了額外使用的組織可以繼續在計量超額上運行例行程序。沒有額外使用，額外運行會被拒絕，直到窗口重置。從 claude.ai 上的 **Settings > Billing** 啟用額外使用。361一次性執行不計入每日例行程序執行上限。它們像任何其他工作階段一樣消耗您的常規訂閱使用量，但它們不受每個帳戶每日例行程序執行額度的限制。

312 362

313## 相關資源363## 相關資源

314 364

settings.md +20 −16

Details

156`settings.json` 支援多個選項：156`settings.json` 支援多個選項：

157 157

158| 金鑰 | 說明 | 範例 |158| 金鑰 | 說明 | 範例 |

159| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |159| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |

161| `allowedChannelPlugins` | （Managed 設定僅限）可能推送訊息的頻道 plugins 白名單。在設定時替換預設 Anthropic 白名單。未定義 = 回退到預設值，空陣列 = 阻止所有頻道 plugins。需要 `channelsEnabled: true`。請參閱[限制哪些頻道 plugins 可以執行](/zh-TW/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |161| `allowedChannelPlugins` | （Managed 設定僅限）可能推送訊息的頻道 plugins 白名單。在設定時替換預設 Anthropic 白名單。未定義 = 回退到預設值，空陣列 = 阻止所有頻道 plugins。需要 `channelsEnabled: true`。請參閱[限制哪些頻道 plugins 可以執行](/zh-TW/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |

162| `allowedHttpHookUrls` | HTTP hooks 可能針對的 URL 模式白名單。支援 `*` 作為萬用字元。設定時，具有不匹配 URL 的 hooks 會被阻止。未定義 = 無限制，空陣列 = 阻止所有 HTTP hooks。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["https://hooks.example.com/*"]` |162| `allowedHttpHookUrls` | HTTP hooks 可能針對的 URL 模式白名單。支援 `*` 作為萬用字元。設定時，具有不匹配 URL 的 hooks 會被阻止。未定義 = 無限制，空陣列 = 阻止所有 HTTP hooks。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["https://hooks.example.com/*"]` |

164| `allowManagedHooksOnly` | （Managed 設定僅限）僅載入 managed hooks、SDK hooks 和在 managed 設定 `enabledPlugins` 中強制啟用的 plugins 中的 hooks。使用者、專案和所有其他 plugin hooks 被阻止。請參閱 [Hook 設定](#hook-configuration) | `true` |164| `allowManagedHooksOnly` | （Managed 設定僅限）僅載入 managed hooks、SDK hooks 和在 managed 設定 `enabledPlugins` 中強制啟用的 plugins 中的 hooks。使用者、專案和所有其他 plugin hooks 被阻止。請參閱 [Hook 設定](#hook-configuration) | `true` |

165| `allowManagedMcpServersOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedMcpServers`。`deniedMcpServers` 仍從所有來源合併。使用者仍可新增 MCP servers，但僅適用管理員定義的白名單。請參閱 [Managed MCP 設定](/zh-TW/mcp#managed-mcp-configuration) | `true` |165| `allowManagedMcpServersOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedMcpServers`。`deniedMcpServers` 仍從所有來源合併。使用者仍可新增 MCP servers，但僅適用管理員定義的白名單。請參閱 [Managed MCP 設定](/zh-TW/mcp#managed-mcp-configuration) | `true` |

166| `allowManagedPermissionRulesOnly` | （Managed 設定僅限）防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅適用 managed 設定中的規則。請參閱 [Managed 專用設定](/zh-TW/permissions#managed-only-settings) | `true` |166| `allowManagedPermissionRulesOnly` | （Managed 設定僅限）防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅適用 managed 設定中的規則。請參閱 [Managed 專用設定](/zh-TW/permissions#managed-only-settings) | `true` |

168| `apiKeyHelper` | 自訂指令碼，在 `/bin/sh` 中執行，以產生驗證值。此值將作為 `X-Api-Key` 和 `Authorization: Bearer` 標頭傳送以進行模型請求 | `/bin/generate_temp_api_key.sh` |168| `apiKeyHelper` | 自訂指令碼，在 `/bin/sh` 中執行，以產生驗證值。此值將作為 `X-Api-Key` 和 `Authorization: Bearer` 標頭傳送以進行模型請求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/zh-TW/env-vars) 設定重新整理間隔 | `/bin/generate_temp_api_key.sh` |

169| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

170| `autoMemoryDirectory` | [自動記憶](/zh-TW/memory#storage-location)儲存的自訂目錄。接受絕對路徑或 `~/` 前綴的路徑。從政策和使用者設定以及 `--settings` 旗標接受。不從專案或本機設定接受，因為複製的儲存庫可能提供任一檔案以將記憶寫入重定向到敏感位置 | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | [自動記憶](/zh-TW/memory#storage-location)儲存的自訂目錄。接受絕對路徑或 `~/` 前綴的路徑。從政策和使用者設定以及 `--settings` 旗標接受。不從專案或本機設定接受，因為複製的儲存庫可能提供任一檔案以將記憶寫入重定向到敏感位置 | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | 啟用[自動記憶](/zh-TW/memory#enable-or-disable-auto-memory)。當為 `false` 時，Claude 不會從自動記憶目錄讀取或寫入。預設：`true`。您也可以在工作階段期間使用 `/memory` 切換此設定 | `false` |171| `autoMemoryEnabled` | 啟用[自動記憶](/zh-TW/memory#enable-or-disable-auto-memory)。當為 `false` 時，Claude 不會從自動記憶目錄讀取或寫入。預設：`true`。您也可以在工作階段期間使用 `/memory` 切換此設定。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/zh-TW/env-vars) | `false` |

172| `autoMode` | 自訂[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器阻止和允許的內容。包含 `environment`、`allow` 和 `soft_deny` 陣列的散文規則。在陣列中包含字面字串 `"$defaults"` 以在該位置繼承內建規則。請參閱[設定自動模式](/zh-TW/auto-mode-config)。不從共享專案設定讀取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | 自訂[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器阻止和允許的內容。包含 `environment`、`allow` 和 `soft_deny` 陣列的散文規則。在陣列中包含字面字串 `"$defaults"` 以在該位置繼承內建規則。請參閱[設定自動模式](/zh-TW/auto-mode-config)。不從共享專案設定讀取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

175| `availableModels` | 限制使用者可透過 `/model`、`--model` 或 `ANTHROPIC_MODEL` 選擇的模型。不影響預設選項。請參閱[限制模型選擇](/zh-TW/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |175| `availableModels` | 限制使用者可透過 `/model`、`--model` 或 `ANTHROPIC_MODEL` 選擇的模型。不影響預設選項。請參閱[限制模型選擇](/zh-TW/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |

179| `blockedMarketplaces` | （Managed 設定僅限）marketplace 來源的黑名單。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。請參閱 [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| `claudeMdExcludes` | 載入[記憶](/zh-TW/memory)時要跳過的 `CLAUDE.md` 檔案的 Glob 模式或絕對路徑。模式與絕對檔案路徑相符。僅適用於使用者、專案和本機記憶；managed 政策檔案無法排除 | `["**/vendor/**/CLAUDE.md"]` |

181| `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` |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| `defaultShell` | 輸入框 `!` 命令的預設 shell。接受 `"bash"`（預設）或 `"powershell"`。設定 `"powershell"` 會在 Windows 上透過 PowerShell 路由互動式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) | `"powershell"` |184| `defaultShell` | 輸入框 `!` 命令的預設 shell。接受 `"bash"`（預設）或 `"powershell"`。設定 `"powershell"` 會在 Windows 上透過 PowerShell 路由互動式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) | `"powershell"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}停用[遠端控制](/zh-TW/remote-control)：阻止 `claude remote-control`、`--remote-control` 旗標、自動啟動和工作階段內切換。通常放在[managed 設定](/zh-TW/permissions#managed-settings)中以進行每個裝置的 MDM 強制執行，但適用於任何範圍。需要 Claude Code v2.1.128 或更新版本 | `true` |190| `disableRemoteControl` | {/* min-version: 2.1.128 */}停用[遠端控制](/zh-TW/remote-control)：阻止 `claude remote-control`、`--remote-control` 旗標、自動啟動和工作階段內切換。通常放在[managed 設定](/zh-TW/permissions#managed-settings)中以進行每個裝置的 MDM 強制執行，但適用於任何範圍。需要 Claude Code v2.1.128 或更新版本 | `true` |

190| `disableSkillShellExecution` | 停用 [skills](/zh-TW/skills) 和來自使用者、專案、plugin 或其他目錄來源的自訂命令中的內嵌 shell 執行（`` !`...` `` 和 ` ```! ` 區塊）。命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。Bundled 和 managed skills 不受影響。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `true` |191| `disableSkillShellExecution` | 停用 [skills](/zh-TW/skills) 和來自使用者、專案、plugin 或其他目錄來源的自訂命令中的內嵌 shell 執行（`` !`...` `` 和 ` ```! ` 區塊）。命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。Bundled 和 managed skills 不受影響。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `true` |

191| `editorMode` | 輸入提示的快捷鍵模式：`"normal"` 或 `"vim"`。預設：`"normal"`。在 `/config` 中顯示為**編輯器模式** | `"vim"` |192| `editorMode` | 輸入提示的快捷鍵模式：`"normal"` 或 `"vim"`。預設：`"normal"`。在 `/config` 中顯示為**編輯器模式** | `"vim"` |

192| `effortLevel` | 跨工作階段持久化[努力等級](/zh-TW/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。當您執行 `/effort` 時自動寫入，其中包含其中一個值。請參閱[調整努力等級](/zh-TW/model-config#adjust-effort-level)以了解支援的模型 | `"xhigh"` |193| `effortLevel` | 跨工作階段持久化[努力等級](/zh-TW/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。當您執行 `/effort` 時自動寫入，其中包含其中一個值。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/zh-TW/env-vars) 會覆蓋此設定以進行一個工作階段。請參閱[調整努力等級](/zh-TW/model-config#adjust-effort-level)以了解支援的模型 | `"xhigh"` |

195| `env` | 將應用於每個工作階段的環境變數 | `{"FOO": "bar"}` |196| `env` | 將應用於每個工作階段的環境變數 | `{"FOO": "bar"}` |

196| `fastModePerSessionOptIn` | 當為 `true` 時，快速模式不會跨工作階段持久化。每個工作階段都以快速模式關閉開始，需要使用者使用 `/fast` 啟用它。使用者的快速模式偏好仍會儲存。請參閱[需要每個工作階段的選擇加入](/zh-TW/fast-mode#require-per-session-opt-in) | `true` |197| `fastModePerSessionOptIn` | 當為 `true` 時，快速模式不會跨工作階段持久化。每個工作階段都以快速模式關閉開始，需要使用者使用 `/fast` 啟用它。使用者的快速模式偏好仍會儲存。請參閱[需要每個工作階段的選擇加入](/zh-TW/fast-mode#require-per-session-opt-in) | `true` |

197| `feedbackSurveyRate` | [工作階段品質調查](/zh-TW/data-usage#session-quality-surveys)出現時符合條件的機率（0–1）。設定為 `0` 以完全抑制。在使用 Bedrock、Vertex 或 Foundry 時很有用，其中預設樣本率不適用 | `0.05` |198| `feedbackSurveyRate` | [工作階段品質調查](/zh-TW/data-usage#session-quality-surveys)出現時符合條件的機率（0–1）。設定為 `0` 以完全抑制，或設定 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-TW/env-vars) 在 `env` 中。在使用 Bedrock、Vertex 或 Foundry 時很有用，其中預設樣本率不適用 | `0.05` |

198| `fileSuggestion` | 為 `@` 檔案自動完成設定自訂指令碼。請參閱[檔案建議設定](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |199| `fileSuggestion` | 為 `@` 檔案自動完成設定自訂指令碼。請參閱[檔案建議設定](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

200| `forceLoginOrgUUID` | 要求登入屬於特定組織。接受單一 UUID 字串（也會在登入期間預先選擇該組織），或 UUID 陣列，其中接受任何列出的組織而不預先選擇。在 managed 設定中設定時，如果驗證帳戶不屬於列出的組織，登入會失敗；空陣列會失敗關閉並使用誤設定訊息阻止登入 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |201| `forceLoginOrgUUID` | 要求登入屬於特定組織。接受單一 UUID 字串（也會在登入期間預先選擇該組織），或 UUID 陣列，其中接受任何列出的組織而不預先選擇。在 managed 設定中設定時，如果驗證帳戶不屬於列出的組織，登入會失敗；空陣列會失敗關閉並使用誤設定訊息阻止登入 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

201| `forceRemoteSettingsRefresh` | （Managed 設定僅限）阻止 CLI 啟動，直到從伺服器新鮮擷取遠端 managed 設定。如果擷取失敗，CLI 會結束而不是繼續使用快取或無設定。未設定時，啟動會繼續而不等待遠端設定。請參閱[失敗關閉強制執行](/zh-TW/server-managed-settings#enforce-fail-closed-startup) | `true` |202| `forceRemoteSettingsRefresh` | （Managed 設定僅限）阻止 CLI 啟動，直到從伺服器新鮮擷取遠端 managed 設定。如果擷取失敗，CLI 會結束而不是繼續使用快取或無設定。未設定時，啟動會繼續而不等待遠端設定。請參閱[失敗關閉強制執行](/zh-TW/server-managed-settings#enforce-fail-closed-startup) | `true` |

203| `gcpAuthRefresh` | 當 GCP Application Default Credentials 過期或無法載入時重新整理它們的自訂指令碼。請參閱[進階認證設定](/zh-TW/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |

203| `httpHookAllowedEnvVars` | HTTP hooks 可能插入到標頭中的環境變數名稱白名單。設定時，每個 hook 的有效 `allowedEnvVars` 是與此清單的交集。未定義 = 無限制。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |205| `httpHookAllowedEnvVars` | HTTP hooks 可能插入到標頭中的環境變數名稱白名單。設定時，每個 hook 的有效 `allowedEnvVars` 是與此清單的交集。未定義 = 無限制。陣列跨設定來源合併。請參閱 [Hook 設定](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |

205| `includeGitInstructions` | 在 Claude 的系統提示中包含內建提交和 PR 工作流程指示和 git 狀態快照（預設：`true`）。設定為 `false` 以移除兩者，例如在使用您自己的 git 工作流程 skills 時。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 環境變數在設定時優先於此設定 | `false` |207| `includeGitInstructions` | 在 Claude 的系統提示中包含內建提交和 PR 工作流程指示和 git 狀態快照（預設：`true`）。設定為 `false` 以移除兩者，例如在使用您自己的 git 工作流程 skills 時。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 環境變數在設定時優先於此設定 | `false` |

206| `language` | 設定 Claude 的首選回應語言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 預設會以此語言回應。也設定[語音聽寫](/zh-TW/voice-dictation#change-the-dictation-language)語言 | `"japanese"` |208| `language` | 設定 Claude 的首選回應語言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 預設會以此語言回應。也設定[語音聽寫](/zh-TW/voice-dictation#change-the-dictation-language)語言 | `"japanese"` |

207| `minimumVersion` | 防止背景自動更新和 `claude update` 安裝低於此版本的版本。當從 `"latest"` 頻道切換到 `"stable"` 時透過 `/config` 提示您保持在目前版本或允許降級。選擇保持設定此值。也適用於[managed 設定](/zh-TW/permissions#managed-settings)以釘選組織範圍的最小值 | `"2.1.100"` |209| `minimumVersion` | 防止背景自動更新和 `claude update` 安裝低於此版本的版本。當從 `"latest"` 頻道切換到 `"stable"` 時透過 `/config` 提示您保持在目前版本或允許降級。選擇保持設定此值。也適用於[managed 設定](/zh-TW/permissions#managed-settings)以釘選組織範圍的最小值 | `"2.1.100"` |

209| `modelOverrides` | 將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Bedrock 推論設定檔 ARN。每個模型選擇器項目在呼叫提供者 API 時使用其對應的值。請參閱[按版本覆蓋模型 ID](/zh-TW/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |211| `modelOverrides` | 將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Bedrock 推論設定檔 ARN。每個模型選擇器項目在呼叫提供者 API 時使用其對應的值。請參閱[按版本覆蓋模型 ID](/zh-TW/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

210| `otelHeadersHelper` | 產生動態 OpenTelemetry 標頭的指令碼。在啟動時和定期執行（請參閱[動態標頭](/zh-TW/monitoring-usage#dynamic-headers)） | `/bin/generate_otel_headers.sh` |212| `otelHeadersHelper` | 產生動態 OpenTelemetry 標頭的指令碼。在啟動時和定期執行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-TW/env-vars) 設定重新整理間隔。請參閱[動態標頭](/zh-TW/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |

220| `showThinkingSummaries` | 在互動式工作階段中顯示[擴展思考](/zh-TW/model-config#extended-thinking)摘要。未設定或 `false`（互動模式中的預設值）時，思考區塊由 API 編輯並顯示為摺疊的存根。編輯只會改變您看到的內容，而不是模型生成的內容：若要減少思考支出，請[降低預算或停用思考](/zh-TW/model-config#extended-thinking)。非互動模式（`-p`）和 SDK 呼叫者無論此設定如何都始終接收摘要 | `true` |222| `showThinkingSummaries` | 在互動式工作階段中顯示[擴展思考](/zh-TW/model-config#extended-thinking)摘要。未設定或 `false`（互動模式中的預設值）時，思考區塊由 API 編輯並顯示為摺疊的存根。編輯只會改變您看到的內容，而不是模型生成的內容：若要減少思考支出，請[降低預算或停用思考](/zh-TW/model-config#extended-thinking)。非互動模式（`-p`）和 SDK 呼叫者無論此設定如何都始終接收摘要 | `true` |

224| `skillOverrides` | {/* min-version: 2.1.129 */}按 skill 名稱鍵入的每個 skill 可見性覆蓋。值為 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。讓您隱藏或摺疊 skill 而無需編輯其 SKILL.md。不適用於 plugin skills，這些由 `/plugin` 管理。`/skills` 功能表將這些寫入 `.claude/settings.local.json`。請參閱[從設定覆蓋 skill 可見性](/zh-TW/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更新版本 | `{"legacy-context": "name-only", "deploy": "off"}` |

222| `skipWebFetchPreflight` | 跳過[WebFetch 網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，該檢查在擷取前將每個請求的主機名稱傳送到 `api.anthropic.com`。在阻止流量到 Anthropic 的環境中設定為 `true`，例如 Bedrock、Vertex AI 或 Foundry 部署，具有限制性的出站。跳過時，WebFetch 嘗試任何 URL 而不諮詢黑名單 | `true` |225| `skipWebFetchPreflight` | 跳過[WebFetch 網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，該檢查在擷取前將每個請求的主機名稱傳送到 `api.anthropic.com`。在阻止流量到 Anthropic 的環境中設定為 `true`，例如 Bedrock、Vertex AI 或 Foundry 部署，具有限制性的出站。跳過時，WebFetch 嘗試任何 URL 而不諮詢黑名單 | `true` |

224| `spinnerTipsOverride` | 使用自訂字串覆蓋微調器提示。`tips`：提示字串陣列。`excludeDefault`：如果為 `true`，僅顯示自訂提示；如果為 `false` 或不存在，自訂提示會與內建提示合併 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |227| `spinnerTipsOverride` | 使用自訂字串覆蓋微調器提示。`tips`：提示字串陣列。`excludeDefault`：如果為 `true`，僅顯示自訂提示；如果為 `false` 或不存在，自訂提示會與內建提示合併 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

226| `sshConfigs` | 要在[桌面](/zh-TW/desktop#pre-configure-ssh-connections-for-your-team)環境下拉式清單中顯示的 SSH 連線。每個項目需要 `id`、`name` 和 `sshHost`；`sshPort`、`sshIdentityFile` 和 `startDirectory` 是選用的。在 managed 設定中設定時，連線對使用者是唯讀的。僅從 managed 和使用者設定讀取 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |229| `sshConfigs` | 要在[桌面](/zh-TW/desktop#pre-configure-ssh-connections-for-your-team)環境下拉式清單中顯示的 SSH 連線。每個項目需要 `id`、`name` 和 `sshHost`；`sshPort`、`sshIdentityFile` 和 `startDirectory` 是選用的。在 managed 設定中設定時，連線對使用者是唯讀的。僅從 managed 和使用者設定讀取 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |

227| `statusLine` | 設定自訂狀態行以顯示內容。請參閱 [`statusLine` 文件](/zh-TW/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |230| `statusLine` | 設定自訂狀態行以顯示內容。請參閱 [`statusLine` 文件](/zh-TW/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

228| `strictKnownMarketplaces` | （Managed 設定僅限）plugin marketplaces 白名單。未定義 = 無限制，空陣列 = 鎖定。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |231| `strictKnownMarketplaces` | （Managed 設定僅限）plugin marketplaces 白名單。未定義 = 無限制，空陣列 = 鎖定。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

233| `teammateMode` | [agent team](/zh-TW/agent-teams) 隊友的顯示方式：`auto`（在 tmux 或 iTerm2 中選擇分割窗格，否則為進程內）、`in-process` 或 `tmux`。`--teammate-mode` 會覆蓋此設定以進行一個工作階段。請參閱[選擇顯示模式](/zh-TW/agent-teams#choose-a-display-mode) | `"in-process"` |

231| `tui` | 終端機 UI 渲染器。使用 `"fullscreen"` 以取得無閃爍[替代螢幕渲染器](/zh-TW/fullscreen)，具有虛擬化捲軸。使用 `"default"` 以取得經典主螢幕渲染器。透過 `/tui` 設定 | `"fullscreen"` |235| `tui` | 終端機 UI 渲染器。使用 `"fullscreen"` 以取得無閃爍[替代螢幕渲染器](/zh-TW/fullscreen)，具有虛擬化捲軸。使用 `"default"` 以取得經典主螢幕渲染器。透過 `/tui` 設定。您也可以設定 [`CLAUDE_CODE_NO_FLICKER`](/zh-TW/env-vars) 環境變數 | `"fullscreen"` |

234| `voice` | [語音聽寫](/zh-TW/voice-dictation)設定：`enabled` 開啟聽寫，`mode` 選擇 `"hold"` 或 `"tap"`，`autoSubmit` 在保持模式中按鍵釋放時傳送提示。當您執行 `/voice` 時自動寫入。需要 Claude.ai 帳戶 | `{ "enabled": true, "mode": "tap" }` |238| `voice` | [語音聽寫](/zh-TW/voice-dictation)設定：`enabled` 開啟聽寫，`mode` 選擇 `"hold"` 或 `"tap"`，`autoSubmit` 在保持模式中按鍵釋放時傳送提示。當您執行 `/voice` 時自動寫入。需要 Claude.ai 帳戶 | `{ "enabled": true, "mode": "tap" }` |

236| `wslInheritsWindowsSettings` | （Windows managed 設定僅限）當為 `true` 時，WSL 上的 Claude Code 除了 `/etc/claude-code` 外還會從 Windows 政策鏈讀取 managed 設定，Windows 來源優先。僅在 HKLM 登錄機碼或 `C:\Program Files\ClaudeCode\managed-settings.json` 中設定時受尊重，兩者都需要 Windows 管理員才能寫入。為了讓 HKCU 政策也在 WSL 上適用，旗標必須另外在 HKCU 本身中設定。對原生 Windows 無效 | `true` |240| `wslInheritsWindowsSettings` | （Windows managed 設定僅限）當為 `true` 時，WSL 上的 Claude Code 除了 `/etc/claude-code` 外還會從 Windows 政策鏈讀取 managed 設定，Windows 來源優先。僅在 HKLM 登錄機碼或 `C:\Program Files\ClaudeCode\managed-settings.json` 中設定時受尊重，兩者都需要 Windows 管理員才能寫入。為了讓 HKCU 政策也在 WSL 上適用，旗標必須另外在 HKCU 本身中設定。對原生 Windows 無效 | `true` |

245 249

246| 金鑰 | 說明 | 範例 |250| 金鑰 | 說明 | 範例 |

247| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |251| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |

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

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

251 255

444 448

445**限制 HTTP hook URL：**449**限制 HTTP hook URL：**

446 450

447限制 HTTP hooks 可以針對的 URL。支援 `*` 作為匹配的萬用字元。定義陣列時，針對不匹配 URL 的 HTTP hooks 會被無聲地阻止。451限制 HTTP hooks 可以針對的 URL。支援 `*` 作為匹配的萬用字元。定義陣列時，針對不匹配 URL 的 HTTP hooks 會被無聲地阻止。主機名稱匹配不區分大小寫，並忽略尾部 FQDN 點，符合 DNS 語義。

448 452

449```json theme={null}453```json theme={null}

450{454{

472 * 在 managed 層級內，優先順序為：伺服器管理 > MDM/OS 層級政策 > 檔案型（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 登錄（僅限 Windows）。僅使用一個 managed 來源；來源不合併跨層級。在檔案型層級內，放入檔案和基礎檔案會合併在一起。476 * 在 managed 層級內，優先順序為：伺服器管理 > MDM/OS 層級政策 > 檔案型（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 登錄（僅限 Windows）。僅使用一個 managed 來源；來源不合併跨層級。在檔案型層級內，放入檔案和基礎檔案會合併在一起。

473 477

4742. **命令列引數**4782. **命令列引數**

475 * 特定工作階段的臨時覆蓋479 * 特定工作階段的臨時覆蓋。JSON 透過 `--settings <file-or-json>` 傳遞會與檔案型設定合併，使用與其他層級相同的規則：此處設定的金鑰會覆蓋本機、專案或使用者設定中的相同金鑰，省略金鑰會保留較低層級的值

476 480

4773. **本機專案設定**（`.claude/settings.local.json`）4813. **本機專案設定**（`.claude/settings.local.json`）

478 * 個人專案特定設定482 * 個人專案特定設定

setup.md +7 −3

Details

175 175

176## 更新 Claude Code176## 更新 Claude Code

177 177

178原生安裝會在背景自動更新。您可以[配置發行版本通道](#configure-release-channel)來控制您是立即接收更新還是按延遲穩定時間表接收，或[完全停用自動更新](#disable-auto-updates)。Homebrew、WinGet 和[Linux 套件管理員](#install-with-linux-package-managers)安裝需要手動更新。178原生安裝會在背景自動更新。您可以[配置發行版本通道](#configure-release-channel)來控制您是立即接收更新還是按延遲穩定時間表接收，或[完全停用自動更新](#disable-auto-updates)。Homebrew、WinGet 和[Linux 套件管理員](#install-with-linux-package-managers)安裝預設需要手動更新。

179 179

180### 自動更新180### 自動更新

181 181

182Claude Code 在啟動時和執行期間定期檢查更新。更新會在背景下載和安裝，然後在您下次啟動 Claude Code 時生效。182Claude Code 在啟動時和執行期間定期檢查更新。更新會在背景下載和安裝，然後在您下次啟動 Claude Code 時生效。

183 183

184<Note>184<Note>

185 Homebrew、WinGet、apt、dnf 和 apk 安裝不會自動更新。對於 Homebrew，執行 `brew upgrade claude-code` 或 `brew upgrade claude-code@latest`，取決於您安裝的 cask。對於 WinGet，執行 `winget upgrade Anthropic.ClaudeCode`。對於 Linux 套件管理員，請參閱[使用 Linux 套件管理員安裝](#install-with-linux-package-managers)中的升級命令。185 Homebrew、WinGet、apt、dnf 和 apk 安裝預設不會自動更新；請參閱下方以選擇加入 Homebrew 和 WinGet。若要手動升級 Homebrew，請執行 `brew upgrade claude-code` 或 `brew upgrade claude-code@latest`，取決於您安裝的 cask。對於 WinGet，請執行 `winget upgrade Anthropic.ClaudeCode`。對於 Linux 套件管理員，請參閱[使用 Linux 套件管理員安裝](#install-with-linux-package-managers)中的升級命令。

186

187 若要讓 Claude Code 在 Homebrew 或 WinGet 上為您執行升級命令，請將 [`CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE`](/zh-TW/env-vars) 設定為 `1`。Claude Code 會在有新版本可用時在背景執行升級，並在成功時顯示重新啟動提示。升級僅針對 Claude Code 套件，不會影響您已安裝的其他軟體。

188

189 在 WinGet 上，當 Claude Code 執行時升級可能會失敗，因為 Windows 會鎖定可執行檔。在這種情況下，Claude Code 會改為顯示手動命令。apt、dnf 和 apk 繼續需要手動升級，因為這些命令需要提升的權限。

186 190

187 **已知問題**：Claude Code 可能會在新版本在這些套件管理員中可用之前通知您有更新。如果升級失敗，請稍候並稍後重試。191 **已知問題**：Claude Code 可能會在新版本在這些套件管理員中可用之前通知您有更新。如果升級失敗，請稍候並稍後重試。

188 192

489 493

490## 卸載 Claude Code494## 卸載 Claude Code

491 495

492若要移除 Claude Code，請按照您的安裝方法的說明進行。496若要移除 Claude Code，請按照您的安裝方法的說明進行。如果之後 `claude` 仍然執行，您可能有第二個安裝或來自舊版安裝程式的遺留 shell 別名。請參閱[檢查衝突的安裝](/zh-TW/troubleshoot-install#check-for-conflicting-installations)以找到並移除它。

493 497

494### 原生安裝498### 原生安裝

495 499

skills.md +58 −25

Details

28 28

29### 建立您的第一個 skill29### 建立您的第一個 skill

30 30

31此範例建立一個 skill，教導 Claude 使用視覺圖表和類比來解釋程式碼。由於它使用預設 frontmatter，Claude 可以在您詢問某事如何運作時自動載入它，或者您可以直接使用 `/explain-code` 叫用它。31此範例建立一個 skill，總結您的 git 儲存庫中未提交的變更，並標記任何風險的內容。它在 Claude 讀取之前將即時 diff 拉入提示中，因此回應是基於您的實際工作樹，而不是 Claude 從開啟的檔案中猜測的內容。當您詢問您的變更時，Claude 會自動載入該 skill，或者您可以直接使用 `/summarize-changes` 叫用它。

32 32

33<Steps>33<Steps>

34 <Step title="建立 skill 目錄">34 <Step title="建立 skill 目錄">

35 在您的個人 skills 資料夾中為 skill 建立一個目錄。個人 skills 在您的所有專案中都可用。35 在您的個人 skills 資料夾中為 skill 建立一個目錄。個人 skills 在您的所有專案中都可用。

36 36

37 ```bash theme={null}37 ```bash theme={null}

~~38 mkdir -p ~/.claude/skills/explain-code~~38 mkdir -p ~/.claude/skills/summarize-changes

39 ```39 ```

40 </Step>40 </Step>

41 41

42 <Step title="編寫 SKILL.md">42 <Step title="編寫 SKILL.md">

43 每個 skill 都需要一個 `SKILL.md` 檔案，包含兩部分：YAML frontmatter（在 `---` 標記之間），告訴 Claude 何時使用該 skill，以及包含 Claude 在叫用該 skill 時遵循的說明的 markdown 內容。目錄名稱變成 `/slash-command`，`description` 幫助 Claude 決定何時自動載入它。43 每個 skill 都需要一個 `SKILL.md` 檔案，包含兩部分：YAML frontmatter（在 `---` 標記之間），告訴 Claude 何時使用該 skill，以及包含 Claude 在執行該 skill 時遵循的說明的 markdown 內容。目錄名稱變成您輸入的命令，`description` 幫助 Claude 決定何時自動載入該 skill。

44 44

~~45 建立 `~/.claude/skills/explain-code/SKILL.md`：~~45 將此儲存到 `~/.claude/skills/summarize-changes/SKILL.md`：

46 46

47 ```yaml theme={null}47 ```yaml theme={null}

48 ---48 ---

~~49 description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"~~49 description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.

50 ---50 ---

51 51

~~52 When explaining code, always include:~~52 ## Current changes

53 53

~~54 1. **Start with an analogy**: Compare the code to something from everyday life~~54 !`git diff HEAD`

~~55 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships~~

~~56 3. **Walk through the code**: Explain step-by-step what happens~~

~~57 4. **Highlight a gotcha**: What's a common mistake or misconception?~~

58 55

~~59 Keep explanations conversational. For complex concepts, use multiple analogies.~~56 ## Instructions

58 Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

60 ```59 ```

61 `` !`git diff HEAD` `` 這一行使用[動態上下文注入](#inject-dynamic-context)：Claude Code 執行該命令，並在 Claude 看到 skill 內容之前將該行替換為其輸出，因此說明會隨著目前的 diff 已內聯而到達。

61 </Step>62 </Step>

62 63

63 <Step title="測試 skill">64 <Step title="測試 skill">

~~64 您可以透過兩種方式測試它：~~65 開啟一個 git 專案，對任何檔案進行小編輯，並透過執行 `claude` 啟動 Claude Code。您可以透過兩種方式測試該 skill。

65 66

66 **讓 Claude 自動叫用它**，詢問與描述相符的內容：67 **讓 Claude 自動叫用它**，詢問與描述相符的內容：

67 68

68 ```text theme={null}69 ```text theme={null}

~~69 How does this code work?~~70 What did I change?

70 ```71 ```

71 72

72 **或直接使用 skill 名稱叫用它**：73 **或直接使用 skill 名稱叫用它**：

73 74

74 ```text theme={null}75 ```text theme={null}

~~75 /explain-code src/auth/login.ts~~76 /summarize-changes

76 ```77 ```

77 78

~~78 無論哪種方式，Claude 都應該在其解釋中包含類比和 ASCII 圖表。~~79 無論哪種方式，Claude 都應該以您編輯的簡短摘要和風險清單進行回應。

79 </Step>80 </Step>

80</Steps>81</Steps>

81 82

168 169

169您的 `SKILL.md` 可以包含任何內容，但思考您想如何叫用該 skill（由您、由 Claude 或兩者）以及您想在哪裡執行它（內聯或在 subagent 中）有助於指導要包含的內容。對於複雜的 skills，您也可以[新增支援檔案](#add-supporting-files)以保持主要 skill 的焦點。170您的 `SKILL.md` 可以包含任何內容，但思考您想如何叫用該 skill（由您、由 Claude 或兩者）以及您想在哪裡執行它（內聯或在 subagent 中）有助於指導要包含的內容。對於複雜的 skills，您也可以[新增支援檔案](#add-supporting-files)以保持主要 skill 的焦點。

170 171

172保持內容本身簡潔。一旦 skill 載入，其內容[在整個回合中保持在上下文中](#skill-content-lifecycle)，因此每一行都是一個重複的令牌成本。陳述要做什麼，而不是敘述如何或為什麼，並應用與您對[CLAUDE.md 內容](/zh-TW/best-practices#write-an-effective-claude-md)所做的相同簡潔性測試。

173

171### Frontmatter 參考174### Frontmatter 參考

172 175

173除了 markdown 內容外，您可以使用 `SKILL.md` 檔案頂部 `---` 標記之間的 YAML frontmatter 欄位來設定 skill 行為：176除了 markdown 內容外，您可以使用 `SKILL.md` 檔案頂部 `---` 標記之間的 YAML frontmatter 欄位來設定 skill 行為：

305 308

306`allowed-tools` 欄位在 skill 處於作用中時授予列出的工具的許可，因此 Claude 可以使用它們而無需提示您批准。它不會限制哪些工具可用：每個工具仍然可呼叫，您的[許可設定](/zh-TW/permissions)仍然管理未列出的工具。309`allowed-tools` 欄位在 skill 處於作用中時授予列出的工具的許可，因此 Claude 可以使用它們而無需提示您批准。它不會限制哪些工具可用：每個工具仍然可呼叫，您的[許可設定](/zh-TW/permissions)仍然管理未列出的工具。

307 310

311對於簽入到專案的 `.claude/skills/` 目錄的 skills，`allowed-tools` 在您接受該資料夾的工作區信任對話後生效，與 `.claude/settings.json` 中的許可規則相同。在信任存放庫之前檢查專案 skills，因為 skill 可以授予自己廣泛的工具存取權限。

312

308此 skill 讓 Claude 在您叫用它時執行 git 命令而無需每次使用批准：313此 skill 讓 Claude 在您叫用它時執行 git 命令而無需每次使用批准：

309 314

310```yaml theme={null}315```yaml theme={null}

416若要停用來自使用者、專案、外掛或[其他目錄](#skills-from-additional-directories)來源的 skills 和自訂命令的此行為，請在[設定](/zh-TW/settings)中設定 `"disableSkillShellExecution": true`。每個命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。捆綁和受管 skills 不受影響。此設定在[受管設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它。421若要停用來自使用者、專案、外掛或[其他目錄](#skills-from-additional-directories)來源的 skills 和自訂命令的此行為，請在[設定](/zh-TW/settings)中設定 `"disableSkillShellExecution": true`。每個命令會被替換為 `[shell command execution disabled by policy]` 而不是被執行。捆綁和受管 skills 不受影響。此設定在[受管設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它。

417 422

418<Tip>423<Tip>

419 若要在 skill 中啟用[擴展思考](/zh-TW/common-workflows#use-extended-thinking-thinking-mode)，請在您的 skill 內容中的任何位置包含「ultrathink」一詞。424 若要在 skill 執行時要求更深入的推理，請在 skill 內容中的任何位置包含 `ultrathink`。請參閱[使用 ultrathink 進行一次性深入推理](/zh-TW/model-config#use-ultrathink-for-one-off-deep-reasoning)。

420</Tip>425</Tip>

421 426

422### 在 subagent 中執行 skills427### 在 subagent 中執行 skills

496 `user-invocable` 欄位僅控制功能表可見性，不控制 Skill 工具存取。使用 `disable-model-invocation: true` 來阻止程式化叫用。501 `user-invocable` 欄位僅控制功能表可見性，不控制 Skill 工具存取。使用 `disable-model-invocation: true` 來阻止程式化叫用。

497</Note>502</Note>

498 503

504### 從設定覆蓋 skill 可見性

505

506`skillOverrides` 設定從您的[設定](/zh-TW/settings)控制 skill 可見性，而不是 skill 自己的 frontmatter。將其用於您不想編輯 SKILL.md 的 skills，例如簽入共享專案儲存庫或由 MCP 伺服器提供的 skills。`/skills` 功能表為您編寫：突出顯示 skill 並按 `Space` 循環狀態，然後按 `Enter` 儲存到 `.claude/settings.local.json`。

507

508每個鍵是 skill 名稱，每個值是四種狀態之一：

509

510| 值 | 列出給 Claude | 在 `/` 功能表中 |

511| :---------------------- | :--------- | :--------- |

512| `"on"` | 名稱和描述 | 是 |

513| `"name-only"` | 僅名稱 | 是 |

514| `"user-invocable-only"` | 隱藏 | 是 |

515| `"off"` | 隱藏 | 隱藏 |

516

517`skillOverrides` 中不存在的 skill 被視為 `"on"`。下面的範例將一個 skill 摺疊為其名稱，並完全關閉另一個：

518

519```json theme={null}

520{

521 "skillOverrides": {

522 "legacy-context": "name-only",

523 "deploy": "off"

524 }

525}

526```

527

528外掛 skills 不受 `skillOverrides` 影響。透過 `/plugin` 改為管理這些。

529

499## 分享 skills530## 分享 skills

500 531

501Skills 可以根據您的受眾在不同範圍內分發：532Skills 可以根據您的受眾在不同範圍內分發：

516mkdir -p ~/.claude/skills/codebase-visualizer/scripts547mkdir -p ~/.claude/skills/codebase-visualizer/scripts

517```548```

518 549

519建立 `~/.claude/skills/codebase-visualizer/SKILL.md`。描述告訴 Claude 何時啟動此 Skill，說明告訴 Claude 執行捆綁的指令碼：550將此儲存到 `~/.claude/skills/codebase-visualizer/SKILL.md`。描述告訴 Claude 何時啟動此 Skill，說明告訴 Claude 執行捆綁的指令碼。指令碼路徑使用 [`${CLAUDE_SKILL_DIR}`](#available-string-substitutions)，因此無論 skill 是安裝在個人、專案或外掛層級，它都能正確解析：

520 551

521````yaml theme={null}552````yaml theme={null}

522---553---

523name: codebase-visualizer554name: codebase-visualizer

524description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.555description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.

525allowed-tools: Bash(python *)556allowed-tools: Bash(python3 *)

526---557---

527 558

528# Codebase Visualizer559# Codebase Visualizer

534Run the visualization script from your project root:565Run the visualization script from your project root:

535 566

536```bash567```bash

537python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .568python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

538```569```

539 570

540This creates `codebase-map.html` in the current directory and opens it in your default browser.571This creates `codebase-map.html` in the current directory and opens it in your default browser.

547- **Directory totals**: Shows aggregate size of each folder578- **Directory totals**: Shows aggregate size of each folder

548````579````

549 580

550建立 `~/.claude/skills/codebase-visualizer/scripts/visualize.py`。此指令碼掃描目錄樹並生成一個自包含的 HTML 檔案，包含：581將此儲存到 `~/.claude/skills/codebase-visualizer/scripts/visualize.py`。此指令碼掃描目錄樹並生成一個自包含的 HTML 檔案，包含：

551 582

552* 一個**摘要側邊欄**，顯示檔案計數、目錄計數、總大小和檔案類型數量583* 一個**摘要側邊欄**，顯示檔案計數、目錄計數、總大小和檔案類型數量

553* 一個**長條圖**，按檔案類型（按大小排名前 8）分解程式碼庫584* 一個**長條圖**，按檔案類型（按大小排名前 8）分解程式碼庫

554* 一個**可摺疊樹**，您可以在其中展開和摺疊目錄，具有顏色編碼的檔案類型指示器585* 一個**可摺疊樹**，您可以在其中展開和摺疊目錄，具有顏色編碼的檔案類型指示器

555 586

556該指令碼需要 Python，但僅使用內建程式庫，因此無需安裝套件：587該指令碼需要 Python 3，但僅使用內建程式庫，因此無需安裝套件：

557 588

558```python expandable theme={null}589```python expandable theme={null}

559#!/usr/bin/env python3590#!/usr/bin/env python3

562import json593import json

563import sys594import sys

564import webbrowser595import webbrowser

596from html import escape

565from pathlib import Path597from pathlib import Path

566from collections import Counter598from collections import Counter

567 599

650 {lang_bars}682 {lang_bars}

651 </div>683 </div>

652 <div class="main">684 <div class="main">

653 <h1>📁 {data["name"]}</h1>685 <h1>📁 {escape(data["name"])}</h1>

654 <ul class="tree" id="root"></ul>686 <ul class="tree" id="root"></ul>

655 </div>687 </div>

656 </div>688 </div>

658 const data = {json.dumps(data)};690 const data = {json.dumps(data)};

659 const colors = {json.dumps(colors)};691 const colors = {json.dumps(colors)};

660 function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}692 function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}

693 function esc(s) {{ return s.replace(/[&<>"']/g, c => ({{"&":"&","<":"<",">":">",'"':""","'":"'"}}[c])); }}

661 function render(node, parent) {{694 function render(node, parent) {{

662 if (node.children) {{695 if (node.children) {{

663 const det = document.createElement('details');696 const det = document.createElement('details');

664 det.open = parent === document.getElementById('root');697 det.open = parent === document.getElementById('root');

665 det.innerHTML = `<summary><span class="folder">📁 ${{node.name}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;698 det.innerHTML = `<summary><span class="folder">📁 ${{esc(node.name)}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;

666 const ul = document.createElement('ul'); ul.className = 'tree';699 const ul = document.createElement('ul'); ul.className = 'tree';

667 node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));700 node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));

668 node.children.forEach(c => render(c, ul));701 node.children.forEach(c => render(c, ul));

670 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);703 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);

671 }} else {{704 }} else {{

672 const li = document.createElement('li'); li.className = 'file';705 const li = document.createElement('li'); li.className = 'file';

673 li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{node.name}}<span class="size">${{fmt(node.size)}}</span>`;706 li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{esc(node.name)}}<span class="size">${{fmt(node.size)}}</span>`;

674 parent.appendChild(li);707 parent.appendChild(li);

675 }}708 }}

676 }}709 }}

715 748

716Skill 描述會載入上下文，以便 Claude 知道可用的內容。所有 skill 名稱始終包含在內，但如果您有許多 skills，描述會被縮短以適應字元預算，這可能會去除 Claude 需要匹配您的請求的關鍵字。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 個字元。749Skill 描述會載入上下文，以便 Claude 知道可用的內容。所有 skill 名稱始終包含在內，但如果您有許多 skills，描述會被縮短以適應字元預算，這可能會去除 Claude 需要匹配您的請求的關鍵字。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 個字元。

717 750

718若要提高限制，請設定 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 環境變數。或在來源處修剪描述和 `when_to_use` 文字：前置關鍵使用案例，因為每個項目的結合文字無論預算如何都限制在 1,536 個字元。751若要提高限制，請設定 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 環境變數。若要為其他 skills 釋放預算，請在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將低優先順序項目設定為 `"name-only"`，以便它們列出而不顯示描述。您也可以在來源處修剪 `description` 和 `when_to_use` 文字：前置關鍵使用案例，因為每個項目的結合文字無論預算如何都限制在 1,536 個字元。

719 752

720## 相關資源753## 相關資源

721 754

statusline.md +12 −13

Details

130 130

131## 狀態列如何運作131## 狀態列如何運作

132 132

133Claude Code 執行您的指令碼並透過 stdin 將 [JSON 工作階段資料](#available-data)傳送給它。您的指令碼讀取 JSON、提取所需內容並將文字列印到 stdout。Claude Code 顯示您的指令碼列印的任何內容。133Claude Code 執行您的指令碼並透過 stdin 將 [JSON 工作階段資料](#available-data) 傳送給它。您的指令碼讀取 JSON、提取所需內容並將文字列印到 stdout。Claude Code 顯示您的指令碼列印的任何內容。

134 134

135**何時更新**135**何時更新**

136 136

137您的指令碼在每個新的助手訊息之後、權限模式變更時或 vim 模式切換時執行。更新在 300ms 處進行去抖動，這意味著快速變更會批次在一起，您的指令碼在事情穩定後執行一次。如果在您的指令碼仍在執行時觸發新的更新，則會取消進行中的執行。如果您編輯指令碼，變更在您與 Claude Code 的下一次互動觸發更新之前不會出現。137您的指令碼在每個新的助手訊息之後、`/compact` 完成後、權限模式變更時或 vim 模式切換時執行。更新在 300ms 處進行去抖動，這意味著快速變更會批次在一起，您的指令碼在事情穩定後執行一次。如果在您的指令碼仍在執行時觸發新的更新，則會取消進行中的執行。如果您編輯指令碼，變更在您與 Claude Code 的下一次互動觸發更新之前不會出現。

138 138

139這些觸發器在主工作階段閒置時可能會安靜，例如當協調器等待背景子代理時。為了在閒置期間保持基於時間或外部來源的片段最新，請將 [`refreshInterval`](#manually-configure-a-status-line) 設定為也在固定計時器上重新執行命令。139這些觸發器在主工作階段閒置時可能會安靜，例如當協調器等待背景子代理時。為了在閒置期間保持基於時間或外部來源的片段最新，請將 [`refreshInterval`](#manually-configure-a-status-line) 設定為也在固定計時器上重新執行命令。

140 140

142 142

143* **多行**：每個 `echo` 或 `print` 陳述式顯示為單獨的行。請參閱[多行範例](#display-multiple-lines)。143* **多行**：每個 `echo` 或 `print` 陳述式顯示為單獨的行。請參閱[多行範例](#display-multiple-lines)。

144* **顏色**：使用 [ANSI 逃逸碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)，例如 `\033[32m` 表示綠色（終端必須支援它們）。請參閱 [git 狀態範例](#git-status-with-colors)。144* **顏色**：使用 [ANSI 逃逸碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)，例如 `\033[32m` 表示綠色（終端必須支援它們）。請參閱 [git 狀態範例](#git-status-with-colors)。

145* **連結**：使用 [OSC 8 逃逸序列](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC)使文字可點擊（macOS 上為 Cmd+click，Windows/Linux 上為 Ctrl+click）。需要支援超連結的終端，例如 iTerm2、Kitty 或 WezTerm。請參閱[可點擊連結範例](#clickable-links)。145* **連結**：使用 [OSC 8 逃逸序列](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) 使文字可點擊（macOS 上為 Cmd+click，Windows/Linux 上為 Ctrl+click）。需要支援超連結的終端，例如 iTerm2、Kitty 或 WezTerm。請參閱[可點擊連結範例](#clickable-links)。

146 146

147<Note>狀態列在本地執行，不消耗 API 令牌。在某些 UI 互動期間，它會暫時隱藏，包括自動完成建議、說明功能表和權限提示。</Note>147<Note>狀態列在本地執行，不消耗 API 令牌。在某些 UI 互動期間，它會暫時隱藏，包括自動完成建議、說明功能表和權限提示。</Note>

148 148

164| `context_window.total_input_tokens`, `context_window.total_output_tokens` | 整個工作階段中的累積令牌計數 |164| `context_window.total_input_tokens`, `context_window.total_output_tokens` | 目前在 context window 中的令牌計數，來自最近的 API 回應。輸入包括快取讀取和寫入。{/* min-version: 2.1.132 */}v2.1.132 之前這些是累積工作階段總計 |

215 "total_lines_removed": 23215 "total_lines_removed": 23

216 },216 },

217 "context_window": {217 "context_window": {

218 "total_input_tokens": 15234,218 "total_input_tokens": 15500,

219 "total_output_tokens": 4521,219 "total_output_tokens": 1200,

220 "context_window_size": 200000,220 "context_window_size": 200000,

221 "used_percentage": 8,221 "used_percentage": 8,

222 "remaining_percentage": 92,222 "remaining_percentage": 92,

272 272

273 **可能為 `null` 的欄位**：273 **可能為 `null` 的欄位**：

274 274

275 * `context_window.current_usage`：在工作階段中第一次 API 呼叫之前為 `null`275 * `context_window.current_usage`：在工作階段中第一次 API 呼叫之前為 `null`，以及在 `/compact` 之後直到下一次 API 呼叫重新填入為止

276 * `context_window.used_percentage`, `context_window.remaining_percentage`：在工作階段早期可能為 `null`276 * `context_window.used_percentage`, `context_window.remaining_percentage`：在工作階段早期可能為 `null`

277 277

278 在您的指令碼中使用條件存取處理遺漏的欄位，並使用後備預設值處理 null 值。278 在您的指令碼中使用條件存取處理遺漏的欄位，並使用後備預設值處理 null 值。

280 280

281### Context window 欄位281### Context window 欄位

282 282

283`context_window` 物件提供兩種追蹤 context 使用情況的方式：283`context_window` 物件描述來自最近 API 回應的即時 context window。自 v2.1.132 起，`total_input_tokens` 和 `total_output_tokens` 反映目前 context 使用情況，而非累積工作階段總計。

284 284

285* **累積總計**（`total_input_tokens`, `total_output_tokens`）：整個工作階段中所有令牌的總和，用於追蹤總消耗285* **合併總計**（`total_input_tokens`, `total_output_tokens`）：目前在 context window 中的令牌。`total_input_tokens` 是 `input_tokens`、`cache_creation_input_tokens` 和 `cache_read_input_tokens` 的總和；`total_output_tokens` 是最近回應中的輸出令牌。在第一次 API 回應之前兩者都是 `0`。

286* **目前使用情況**（`current_usage`）：最後一次 API 呼叫中的令牌計數，使用此來取得準確的 context 百分比，因為它反映實際的 context 狀態286* **按元件使用情況**（`current_usage`）：相同的令牌計數按類別分解。當您需要將快取命中與新輸入分開時，請使用此項。

287 287

288`current_usage` 物件包含：288`current_usage` 物件包含：

289 289

296 296

297如果您從 `current_usage` 手動計算 context 百分比，請使用相同的僅輸入公式以符合 `used_percentage`。297如果您從 `current_usage` 手動計算 context 百分比，請使用相同的僅輸入公式以符合 `used_percentage`。

298 298

299`current_usage` 物件在工作階段中第一次 API 呼叫之前為 `null`。299`current_usage` 物件在工作階段中第一次 API 呼叫之前為 `null`，以及在 `/compact` 之後直到下一次 API 呼叫重新填入為止再次為 `null`。

300 300

301## 範例301## 範例

302 302

1011 1011

1012**Context 百分比顯示意外值**1012**Context 百分比顯示意外值**

1013 1013

1014* 使用 `used_percentage` 以取得準確的 context 狀態，而不是累積總計1014* 使用 `used_percentage` 以取得最簡單的準確 context 狀態

1015* `total_input_tokens` 和 `total_output_tokens` 在整個工作階段中累積，可能超過 context window 大小

1016* Context 百分比可能與 `/context` 輸出不同，因為每個計算時間不同1015* Context 百分比可能與 `/context` 輸出不同，因為每個計算時間不同

1017 1016

1018**OSC 8 連結不可點擊**1017**OSC 8 連結不可點擊**

terminal-config.md +3 −3

Details

24在大多數終端機中，您也可以按 Shift+Enter，但支援因終端機模擬器而異：24在大多數終端機中，您也可以按 Shift+Enter，但支援因終端機模擬器而異：

25 25

26| 終端機 | Shift+Enter 用於換行符 |26| 終端機 | Shift+Enter 用於換行符 |

~~27| :------------------------------------------------------------------------- | :--------------------------- |~~27| :---------------------------------------------------------------- | :--------------------------- |

~~28| Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal | 無需設置即可運作 |~~28| Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal、Windows Terminal | 無需設置即可運作 |

29| VS Code、Cursor、Windsurf、Alacritty、Zed | 執行一次 `/terminal-setup` |29| VS Code、Cursor、Windsurf、Alacritty、Zed | 執行一次 `/terminal-setup` |

31 31

32對於 VS Code、Cursor、Windsurf、Alacritty 和 Zed，`/terminal-setup` 將 Shift+Enter 和其他快捷鍵寫入終端機的配置檔案。在 VS Code、Cursor 和 Windsurf 中，它也會在編輯器設定中設定 `terminal.integrated.mouseWheelScrollSensitivity`，以在[全螢幕模式](/zh-TW/fullscreen)中實現更平順的滾動。現有的綁定和設定會保留在原位；如果您看到類似 `VSCode terminal Shift+Enter key binding already configured` 的訊息，則未進行任何變更。直接在主機終端機中執行 `/terminal-setup` 而不是在 tmux 或 screen 內，因為它需要寫入主機終端機的配置。32對於 VS Code、Cursor、Windsurf、Alacritty 和 Zed，`/terminal-setup` 將 Shift+Enter 和其他快捷鍵寫入終端機的配置檔案。在 VS Code、Cursor 和 Windsurf 中，它也會在編輯器設定中設定 `terminal.integrated.mouseWheelScrollSensitivity`，以在[全螢幕模式](/zh-TW/fullscreen)中實現更平順的滾動。現有的綁定和設定會保留在原位；如果您看到類似 `VSCode terminal Shift+Enter key binding already configured` 的訊息，則未進行任何變更。直接在主機終端機中執行 `/terminal-setup` 而不是在 tmux 或 screen 內，因為它需要寫入主機終端機的配置。

33 33

Documentation 2026-05-05 23:00 UTC to 2026-05-07 22:59 UTC