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-CN/agent-sdk/python#tool)（Python）或 [`tool()`](/zh-CN/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-CN/agent-sdk/tool-search)按需加载工具。 |

27## 创建自定义工具

29工具由四个部分定义，作为参数传递给 TypeScript 中的 [`tool()`](/zh-CN/agent-sdk/typescript#tool) 助手或 Python 中的 [`@tool`](/zh-CN/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-CN/agent-sdk/typescript#createsdkmcpserver)（TypeScript）或 [`create_sdk_mcp_server`](/zh-CN/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有关完整的参数详细信息，包括 JSON Schema 输入格式和返回值结构，请参阅 [`tool()`](/zh-CN/agent-sdk/typescript#tool) TypeScript 参考或 [`@tool`](/zh-CN/agent-sdk/python#tool) Python 参考。

126

127<Tip>

128 要使参数可选：在 TypeScript 中，向 Zod 字段添加 `.default()`。在 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下面的示例向[天气工具示例](#weather-tool-example)中的 `weatherServer` 添加第二个工具 `get_precipitation_chance`，并使用数组中的两个工具重建它。

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-CN/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此示例向[天气工具示例](#weather-tool-example)中的 `get_temperature` 工具添加 `readOnlyHint`。

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-CN/agent-sdk/typescript#toolannotations) 或 [Python](/zh-CN/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-CN/agent-sdk/permissions)进行。 |

333| 不允许的工具 | 权限 | 对列出的工具的每次调用都被拒绝。工具保留在 Claude 的上下文中，因此 Claude 可能仍会在调用被拒绝之前尝试它。 |

334

335要限制 Claude 可以使用哪些内置工具，优先使用 `tools` 而不是不允许的工具。从 `tools` 中省略工具会将其从上下文中删除，以便 Claude 永远不会尝试它；在 `disallowedTools` 中列出它（Python：`disallowed_tools`）会阻止调用但保留工具可见，因此 Claude 可能会浪费一个回合尝试它。有关完整的评估顺序，请参阅[配置权限](/zh-CN/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-CN/agent-sdk/mcp)而不是进程内 SDK 服务器。

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-CN/agent-sdk/tool-search)以延迟加载它们，直到 Claude 需要它们。

825* 要连接到外部 MCP 服务器（文件系统、GitHub、Slack）而不是构建自己的，请参阅[连接 MCP 服务器](/zh-CN/agent-sdk/mcp)。

826* 要控制哪些工具自动运行与需要批准，请参阅[配置权限](/zh-CN/agent-sdk/permissions)。

827

828## 相关文档

829

830* [TypeScript SDK 参考](/zh-CN/agent-sdk/typescript)

831* [Python SDK 参考](/zh-CN/agent-sdk/python)

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

833* [SDK 概述](/zh-CN/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"

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-CN/env-vars) 了解底层 CLI 读取的变量 |822| `env` | `dict[str, str]` | `{}` | 环境变量合并到继承的进程环境之上。见 [环境变量](/zh-CN/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` 并在会话间持久化。 |1116| `suggestions` | `list[PermissionUpdate]` | 来自 CLI 的权限更新建议。Bash 提示包括带有 `localSettings` 目标的建议，因此在 `updated_permissions` 中返回它会将规则写入 `.claude/settings.local.json` 并在会话间持久化。 |

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-CN/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-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |360| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。无论如何都会加载托管策略设置。请参阅[使用 Claude Code 功能](/zh-CN/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-CN/settings)而无需重新启动查询。当没有专用设置器的设置需要在会话中期更改时使用它，例如在代理读取不受信任的输入后收紧 `permissions`。`setModel()` 和 `setPermissionMode()` 是这两个键的专用设置器；`applyFlagSettings()` 是接受任何设置键子集的通用形式，在此处传递 `model` 的行为与 `setModel()` 相同。

448

449这些值被写入标志设置层，这是内联 `query()` 的 `settings` 选项在启动时填充的同一层。标志设置位于[设置优先级顺序](/zh-CN/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

783];831];

784```832```

785 833

786有关创建和使用插件的完整信息，请参阅[插件](/zh-CN/agent-sdk/plugins)。834有关创建和使用插件的完整信息，请参阅[plugins](/zh-CN/agent-sdk/plugins)。

787 835

788## 消息类型836## 消息类型

789 837

2443 2491

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

2445 2493

2446MCP 工具结果类型（来自 `@modelcontextprotocol/sdk/types.js`）。2494MCP 工具结果类型（来自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是一个 JSON 对象，可以与 `content` 一起返回，包括图像块。请参阅[返回结构化数据](/zh-CN/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-CN/model-config#pin-models-for-third-party-deployments)了解详情。463[设置向导](#sign-in-with-bedrock)在固定模型时提供 1M 上下文选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。请参阅[为第三方部署固定模型](/zh-CN/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-CN/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-CN/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-CN/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-CN/settings#available-settings) 设置可以配置为运行返回 API 密钥的 shell 脚本。123* **自定义凭证脚本**：[`apiKeyHelper`](/zh-CN/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-CN/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-CN/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 on the web 与你账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。云 VM 没有单独的计算费用。795* **速率限制**：Claude Code on the web 与你账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。云 VM 没有单独的计算费用。

762* **存储库身份验证**：你只能在认证到相同账户时将会话从网络移动到本地796* **存储库身份验证**：你只能在认证到相同账户时将会话从网络移动到本地

763* **平台限制**：存储库克隆和拉取请求创建需要 GitHub。自托管[GitHub Enterprise Server](/zh-CN/github-enterprise-server) 实例支持 Team 和 Enterprise 计划。GitLab、Bitbucket 和其他非 GitHub 存储库可以作为[本地捆绑](#send-local-repositories-without-github)发送到云会话，但会话无法将结果推送回远程797* **平台限制**：存储库克隆和拉取请求创建需要 GitHub。自托管[GitHub Enterprise Server](/zh-CN/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-CN/code-review)和[例程](/zh-CN/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-CN/permissions#additional-directories-grant-file-access-not-configuration)。验证每个路径是否存在为目录 | `claude --add-dir ../apps ../lib` |44| `--add-dir` | 为 Claude 添加额外的工作目录以读取和编辑文件。授予文件访问权限；大多数 `.claude/` 配置 [不会从这些目录中发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。验证每个路径是否存在为目录。要在会话间持久化这些目录，请在设置中设置 [`permissions.additionalDirectories`](/zh-CN/settings#permission-settings) | `claude --add-dir ../apps ../lib` |

46| `--agents` | 通过 JSON 动态定义自定义 subagents。使用与 subagent [frontmatter](/zh-CN/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-CN/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`。请参阅 [权限模式](/zh-CN/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`。请参阅 [权限模式](/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

62| `--effort` | 为当前会话设置 [工作量级别](/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。会话范围内，不会持久化到设置 | `claude --effort high` |62| `--effort` | 为当前会话设置 [工作量级别](/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。覆盖此会话的 [`effortLevel`](/zh-CN/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-CN/commands) 在会话中更改名称，也会在提示栏中显示 | `claude -n "my-feature-work"` |80| `--name`, `-n` | 为会话设置显示名称，显示在 `/resume` 和终端标题中。您可以使用 `claude --resume <name>` 恢复命名会话。<br /><br />[`/rename`](/zh-CN/commands) 在会话中更改名称，也会在提示栏中显示 | `claude -n "my-feature-work"` |

84| `--permission-mode` | 以指定的 [权限模式](/zh-CN/permission-modes) 开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆盖设置文件中的 `defaultMode` | `claude --permission-mode plan` |84| `--permission-mode` | 以指定的 [权限模式](/zh-CN/permission-modes) 开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆盖设置文件中的 `defaultMode` | `claude --permission-mode plan` |

87| `--plugin-url` | 仅为此会话从 URL 获取插件 `.zip` 存档。每个标志采用一个 URL。重复该标志以获取多个插件 | `claude --plugin-url https://example.com/plugin.zip` |

89| `--remote-control`, `--rc` | 启动启用了 [Remote Control](/zh-CN/remote-control#start-a-remote-control-session) 的交互式会话，以便您也可以从 claude.ai 或 Claude 应用控制它。可选地为会话传递名称 | `claude --remote-control "My Project"` |90| `--remote-control`, `--rc` | 启动启用了 [Remote Control](/zh-CN/remote-control#start-a-remote-control-session) 的交互式会话，以便您也可以从 claude.ai 或 Claude 应用控制它。可选地为会话传递名称 | `claude --remote-control "My Project"` |

100| `--teammate-mode` | 设置 [agent team](/zh-CN/agent-teams) 队友的显示方式：`auto`（默认）、`in-process` 或 `tmux`。请参阅 [选择显示模式](/zh-CN/agent-teams#choose-a-display-mode) | `claude --teammate-mode in-process` |101| `--teammate-mode` | 设置 [agent team](/zh-CN/agent-teams) 队友的显示方式：`auto`（默认）、`in-process` 或 `tmux`。覆盖此会话的 [`teammateMode`](/zh-CN/settings#available-settings) 设置。请参阅 [选择显示模式](/zh-CN/agent-teams#choose-a-display-mode) | `claude --teammate-mode in-process` |

105| `--worktree`, `-w` | 在隔离的 [git worktree](/zh-CN/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-CN/worktrees) 中启动 Claude，位于 `<repo>/.claude/worktrees/<name>`。如果未给出名称，则自动生成一个 | `claude -w feature-auth` |

106 107

107### 系统提示标志108### 系统提示标志

108 109

commands.md +6 −4

Details

10 10

11输入 `/` 可以查看所有可用命令，或输入 `/` 后跟字母来筛选。11输入 `/` 可以查看所有可用命令，或输入 `/` 后跟字母来筛选。

12 12

13命令只在您的消息开头被识别。命令名称后面的文本作为参数传递给它。

13下表列出了 Claude Code 中包含的所有命令。标记为 **[Skill](/zh-CN/skills#bundled-skills)** 的条目是捆绑的 skills。它们使用与您自己编写的 skills 相同的机制：一个提示交给 Claude，Claude 也可以在相关时自动调用。其他所有内容都是内置命令，其行为被编码到 CLI 中。要添加您自己的命令，请参阅 [skills](/zh-CN/skills)。15下表列出了 Claude Code 中包含的所有命令。标记为 **[Skill](/zh-CN/skills#bundled-skills)** 的条目是捆绑的 skills。它们使用与您自己编写的 skills 相同的机制：一个提示交给 Claude，Claude 也可以在相关时自动调用。其他所有内容都是内置命令，其行为被编码到 CLI 中。要添加您自己的命令，请参阅 [skills](/zh-CN/skills)。

14 16

15并非每个命令都对每个用户显示。可用性取决于您的平台、计划和环境。例如，`/desktop` 仅在 macOS 和 Windows 上显示，`/upgrade` 仅在 Pro 和 Max 计划上显示。17并非每个命令都对每个用户显示。可用性取决于您的平台、计划和环境。例如，`/desktop` 仅在 macOS 和 Windows 上显示，`/upgrade` 仅在 Pro 和 Max 计划上显示。

21| `/add-dir <path>` | 为当前会话期间的文件访问添加工作目录。大多数 `.claude/` 配置[不会从添加的目录中发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍后使用 `--continue` 或 `--resume` 从添加的目录恢复会话 |23| `/add-dir <path>` | 为当前会话期间的文件访问添加工作目录。大多数 `.claude/` 配置[不会从添加的目录中发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍后使用 `--continue` 或 `--resume` 从添加的目录恢复会话 |

23| `/autofix-pr [prompt]` | 生成一个[网络版 Claude Code](/zh-CN/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-CN/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |25| `/autofix-pr [prompt]` | 生成一个[网络版 Claude Code](/zh-CN/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-CN/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |

24| `/batch <instruction>` | **[Skill](/zh-CN/skills#bundled-skills).** 在整个代码库中并行编排大规模更改。研究代码库，将工作分解为 5 到 30 个独立单元，并呈现一个计划。获得批准后，在隔离的 [git worktree](/zh-CN/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-CN/skills#bundled-skills).** 在整个代码库中并行编排大规模更改。研究代码库，将工作分解为 5 到 30 个独立单元，并呈现一个计划。获得批准后，在隔离的 [git worktree](/zh-CN/worktrees) 中为每个单元生成一个后台 agent。每个 agent 实现其单元、运行测试并打开一个 pull request。需要一个 git 存储库。示例：`/batch migrate src/ from Solid to React` |

25| `/branch [name]` | 在此点创建当前对话的分支。切换到分支并保留原始分支，您可以使用 `/resume` 返回。别名：`/fork`。当设置 [`CLAUDE_CODE_FORK_SUBAGENT`](/zh-CN/env-vars) 时，`/fork` 改为生成一个[分叉的 subagent](/zh-CN/sub-agents#fork-the-current-conversation)，不再是此命令的别名 |27| `/branch [name]` | 在此点创建当前对话的分支。切换到分支并保留原始分支，您可以使用 `/resume` 返回。别名：`/fork`。当设置 [`CLAUDE_CODE_FORK_SUBAGENT`](/zh-CN/env-vars) 时，`/fork` 改为生成一个[分叉的 subagent](/zh-CN/sub-agents#fork-the-current-conversation)，不再是此命令的别名 |

28| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-CN/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-CN/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` 重置。当 [Remote Control](/zh-CN/remote-control) 连接时，颜色同步到 claude.ai/code |32| `/color [color\|default]` | 为当前会话设置提示栏颜色。可用颜色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重置，或不带参数运行以选择随机颜色。当 [Remote Control](/zh-CN/remote-control) 连接时，颜色同步到 claude.ai/code |

31| `/compact [instructions]` | 通过总结到目前为止的对话来释放上下文。可选择性地传递焦点说明以进行总结。请参阅[压缩如何处理规则、skills 和内存文件](/zh-CN/context-window#what-survives-compaction) |33| `/compact [instructions]` | 通过总结到目前为止的对话来释放上下文。可选择性地传递焦点说明以进行总结。请参阅[压缩如何处理规则、skills 和内存文件](/zh-CN/context-window#what-survives-compaction) |

83| `/setup-bedrock` | 通过交互式向导配置 [Amazon Bedrock](/zh-CN/amazon-bedrock) 身份验证、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_BEDROCK=1` 时可见。首次 Bedrock 用户也可以从登录屏幕访问此向导 |85| `/setup-bedrock` | 通过交互式向导配置 [Amazon Bedrock](/zh-CN/amazon-bedrock) 身份验证、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_BEDROCK=1` 时可见。首次 Bedrock 用户也可以从登录屏幕访问此向导 |

84| `/setup-vertex` | 通过交互式向导配置 [Google Vertex AI](/zh-CN/google-vertex-ai) 身份验证、项目、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_VERTEX=1` 时可见。首次 Vertex AI 用户也可以从登录屏幕访问此向导 |86| `/setup-vertex` | 通过交互式向导配置 [Google Vertex AI](/zh-CN/google-vertex-ai) 身份验证、项目、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_VERTEX=1` 时可见。首次 Vertex AI 用户也可以从登录屏幕访问此向导 |

85| `/simplify [focus]` | **[Skill](/zh-CN/skills#bundled-skills).** 审阅您最近更改的文件以查找代码重用、质量和效率问题，然后修复它们。并行生成三个审阅 agent，聚合其发现，并应用修复。传递文本以集中关注特定问题：`/simplify focus on memory efficiency` |87| `/simplify [focus]` | **[Skill](/zh-CN/skills#bundled-skills).** 审阅您最近更改的文件以查找代码重用、质量和效率问题，然后修复它们。并行生成三个审阅 agent，聚合其发现，并应用修复。传递文本以集中关注特定问题：`/simplify focus on memory efficiency` |

92| `/team-onboarding` | 从您的 Claude Code 使用历史记录生成团队入职指南。Claude 分析您过去 30 天的会话、命令和 MCP server 使用情况，并生成一个 markdown 指南，团队成员可以粘贴为第一条消息以快速设置 |94| `/team-onboarding` | 从您的 Claude Code 使用历史记录生成团队入职指南。Claude 分析您过去 30 天的会话、命令和 MCP server 使用情况，并生成一个 markdown 指南，团队成员可以粘贴为第一条消息以快速设置。对于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者，还返回一个共享链接，团队成员可以直接在 Claude Code 中打开 |

93| `/teleport` | 将[网络版 Claude Code](/zh-CN/claude-code-on-the-web#from-web-to-terminal) 会话拉入此终端：打开选择器，然后获取分支和对话。也可用作 `/tp`。需要 claude.ai 订阅 |95| `/teleport` | 将[网络版 Claude Code](/zh-CN/claude-code-on-the-web#from-web-to-terminal) 会话拉入此终端：打开选择器，然后获取分支和对话。也可用作 `/tp`。需要 claude.ai 订阅 |

95| `/theme` | 更改颜色主题。包括跟随您终端深色或浅色背景的 `auto` 选项、浅色和深色变体、色盲友好（道尔顿化）主题、使用您终端颜色调色板的 ANSI 主题，以及来自 `~/.claude/themes/` 或 plugins 的任何[自定义主题](/zh-CN/terminal-config#create-a-custom-theme)。选择\*\*新建自定义主题…\*\*以创建一个 |97| `/theme` | 更改颜色主题。包括跟随您终端深色或浅色背景的 `auto` 选项、浅色和深色变体、色盲友好（道尔顿化）主题、使用您终端颜色调色板的 ANSI 主题，以及来自 `~/.claude/themes/` 或 plugins 的任何[自定义主题](/zh-CN/terminal-config#create-a-custom-theme)。选择\*\*新建自定义主题…\*\*以创建一个 |

debug-your-config.md +24 −4

Details

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 服务器及其状态 |25| `/mcp` | 连接的 MCP 服务器及其状态 |

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-CN/memory#how-claude-md-files-load)检查其位置。子目录 `CLAUDE.md` 文件在 Claude 使用 Read 工具读取该目录中的文件时按需加载，而不是在会话开始时加载。31如果内存文件在 `/memory` 中缺失，请根据[CLAUDE.md 文件如何加载](/zh-CN/memory#how-claude-md-files-load)检查其位置。子目录 `CLAUDE.md` 文件在 Claude 使用 Read 工具读取该目录中的文件时按需加载，而不是在会话开始时加载。

41 42

42设置在托管、用户、项目和本地范围内合并。当存在时，托管设置总是优先。在其余的中，更接近的范围按本地、项目、用户的顺序覆盖更广泛的范围。某些设置也可以由命令行标志或[环境变量](/zh-CN/env-vars)设置，它们充当另一个覆盖层。当设置似乎不适用时，你设置的值通常被另一个范围或环境变量覆盖。43设置在托管、用户、项目和本地范围内合并。当存在时，托管设置总是优先。在其余的中，更接近的范围按本地、项目、用户的顺序覆盖更广泛的范围。某些设置也可以由命令行标志或[环境变量](/zh-CN/env-vars)设置，它们充当另一个覆盖层。当设置似乎不适用时，你设置的值通常被另一个范围或环境变量覆盖。

43 44

44运行 `/doctor` 来验证你的配置文件并显示无效的键或 schema 错误。运行 `/status` 来查看哪些设置源是活跃的，包括是否启用了托管设置。要了解给定键哪个范围优先，请参阅[范围如何交互](/zh-CN/settings#how-scopes-interact)。45运行 `/doctor` 来验证你的配置文件并显示无效的键或 schema 错误。当 `/doctor` 报告问题时，按 `f` 将诊断报告发送给 Claude，让它与你一起逐步解决问题。

47运行 `/status` 来查看哪些设置源是活跃的，包括是否启用了托管设置。要了解给定键哪个范围优先，请参阅[范围如何交互](/zh-CN/settings#how-scopes-interact)。

45 48

46## 检查 MCP 服务器49## 检查 MCP 服务器

47 50

63 66

64如果 `/hooks` 显示 hook 但它仍然没有触发，下一步是实时观察 hook 评估。使用 `claude --debug hooks` 启动会话并触发工具调用。调试日志记录每个事件、检查了哪些匹配器以及 hook 的退出代码和输出。有关日志格式，请参阅[调试 hooks](/zh-CN/hooks#debug-hooks)，有关常见失败模式，请参阅[hooks 故障排除](/zh-CN/hooks-guide#limitations-and-troubleshooting)。67如果 `/hooks` 显示 hook 但它仍然没有触发，下一步是实时观察 hook 评估。使用 `claude --debug hooks` 启动会话并触发工具调用。调试日志记录每个事件、检查了哪些匹配器以及 hook 的退出代码和输出。有关日志格式，请参阅[调试 hooks](/zh-CN/hooks#debug-hooks)，有关常见失败模式，请参阅[hooks 故障排除](/zh-CN/hooks-guide#limitations-and-troubleshooting)。

65 68

~~66## 常见原因~~69## 针对干净配置进行测试

71如果有针对性的检查无法隔离原因，或你的配置处于未知状态，请与从你的常规设置中不加载任何内容的会话进行比较。将 [`CLAUDE_CONFIG_DIR`](/zh-CN/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 服务器、插件或内存。

79* 如果你的组织部署了托管设置，它们仍然适用，因为它们位于 `~/.claude` 之外的系统路径中

80* 在 Linux 和 Windows 上，你将被提示再次登录，因为凭证存储在配置目录下

81* 在 macOS 上，凭证在 Keychain 中，会转移到干净会话

83如果问题在这里消失，原因在你的真实 `~/.claude` 或项目 `.claude` 文件中的某处。一次重新引入一个，通过将文件复制到临时目录或从你的项目启动，来找到哪一个。如果它在干净会话中持续存在，原因在你的用户和项目配置之外。运行 `/status` 来检查是否启用了托管设置，查找影响 Claude Code 的[环境变量](/zh-CN/env-vars)，然后参阅[故障排除](/zh-CN/troubleshooting)。

85## 检查常见原因

67 86

68大多数配置意外可以追溯到一小组位置和语法规则。在假设存在错误之前检查这些：87大多数配置意外可以追溯到一小组位置和语法规则。在假设存在错误之前检查这些：

69 88

70| 症状 | 原因 | 修复 |89| 症状 | 原因 | 修复 |

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

102| 在 `settings.json` 中的 `mcpServers` 下添加的 MCP 服务器永远不出现 | `settings.json` 不读取 `mcpServers` 键 | 在存储库根目录的 `.mcp.json` 中定义项目服务器，或运行 `claude mcp add --scope user` 来添加用户范围的服务器。请参阅[MCP 配置](/zh-CN/mcp)。 |

discover-plugins.md +21 −13

Details

4 4

5# 通过市场发现和安装预构建插件5# 通过市场发现和安装预构建插件

6 6

~~7> 从市场发现和安装插件，以使用新命令、代理和功能扩展 Claude Code。~~7> 从市场发现和安装插件，以使用新 skills、agents 和功能扩展 Claude Code。

8 8

9插件通过 skills、agents、hooks 和 MCP servers 扩展 Claude Code。插件市场是帮助您发现和安装这些扩展的目录，无需自己构建。9插件通过 skills、agents、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为常见开发任务添加 skills 和 agents 的插件：

99 101

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

101* **pr-review-toolkit**：用于审查拉取请求的专门代理103* **pr-review-toolkit**：用于审查拉取请求的专门 agents

102* **agent-sdk-dev**：使用 Claude Agent SDK 构建的工具104* **agent-sdk-dev**：使用 Claude Agent SDK 构建的工具

103* **plugin-dev**：用于创建您自己的插件的工具包105* **plugin-dev**：用于创建您自己的插件的工具包

104 106

142 * **项目范围**：为此存储库上的所有协作者安装144 * **项目范围**：为此存储库上的所有协作者安装

143 * **本地范围**：仅在此存储库中为自己安装145 * **本地范围**：仅在此存储库中为自己安装

144 146

145 例如，选择 **commit-commands**（添加 git 工作流命令的插件）并将其安装到您的用户范围。147 例如，选择 **commit-commands**（添加 git 工作流 skills 的插件）并将其安装到您的用户范围。

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` 以激活插件。插件 skills 由插件名称命名空间，因此 **commit-commands** 提供诸如 `/commit-commands:commit` 之类的 skills。

158 160

159 通过对文件进行更改并运行来尝试：161 通过对文件进行更改并运行来尝试：

160 162

164 166

165 这会暂存您的更改、生成提交消息并创建提交。167 这会暂存您的更改、生成提交消息并创建提交。

166 168

167 每个插件的工作方式不同。检查**发现**选项卡中的插件描述或其主页以了解它提供的命令和功能。169 每个插件的工作方式不同。检查**发现**选项卡中的插件描述或其主页以了解它提供的 skills 和功能。

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您也可能看到具有**托管**范围的插件——这些由管理员通过[托管设置](/zh-CN/settings#settings-files)安装，无法修改。260您也可能看到具有**托管**范围的插件——这些由管理员通过[托管设置](/zh-CN/settings#settings-files)安装，无法修改。

259 261

260运行 `/plugin` 并转到**已安装**选项卡以查看按范围分组的插件。

~~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` 并转到**已安装**选项卡以查看、启用、禁用或卸载您的插件。键入以按插件名称或描述筛选列表。268运行 `/plugin` 并转到**已安装**选项卡以查看、启用、禁用或卸载您的插件。该列表按范围分组并排序，以便您首先看到问题：具有加载错误或未解决依赖项的插件出现在顶部，然后是您的收藏夹，禁用的插件折叠在底部的折叠标题后面。

269

270从列表中您可以：

271

272* 按 `f` 以收藏或取消收藏选定的插件

273* 输入以按插件名称或描述筛选

274* 按 Enter 打开插件的详细视图并启用、禁用或卸载它

275

276当您安装声明依赖项的插件时，安装输出会列出哪些依赖项与其一起自动安装。

269 277

270您也可以使用直接命令管理插件。278您也可以使用直接命令管理插件。

271 279

302/reload-plugins310/reload-plugins

303```311```

304 312

305Claude Code 重新加载所有活跃插件，并显示重新加载的命令、skills、agents、hooks、插件 MCP servers 和插件 LSP servers 的计数。313Claude Code 重新加载所有活跃插件，并显示插件、skills、agents、hooks、插件 MCP servers 和插件 LSP servers 的计数。

306 314

307## 管理市场315## 管理市场

308 316

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-CN/setup)重新运行安装命令413 * **本地安装程序**：从[设置](/zh-CN/setup)重新运行安装命令

4063. **重启 Claude Code**：更新后，重启您的终端并再次运行 `claude`。4143. **重启 Claude Code**：更新后，重启您的终端并再次运行 `claude`。

407 415

env-vars.md +16 −10

Details

43| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Vertex AI 端点 URL。用于自定义 Vertex 端点或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |43| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Vertex AI 端点 URL。用于自定义 Vertex 端点或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |

44| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 的 GCP 项目 ID。使用 [Google Vertex AI](/zh-CN/google-vertex-ai) 时为必需 |44| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 请求的 GCP 项目 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 凭证文件中的项目覆盖。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |

46| `AWS_BEARER_TOKEN_BEDROCK` | 用于身份验证的 Bedrock API 密钥（请参阅 [Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |46| `AWS_BEARER_TOKEN_BEDROCK` | 用于身份验证的 Bedrock API 密钥（请参阅 [Bedrock API 密钥](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-CN/hooks) 或[状态行](/zh-CN/statusline)命令中未设置。用于检测脚本何时在 Claude Code 生成的 shell 内运行 |51| `CLAUDECODE` | 在 Claude Code 生成的 shell 环境中设置为 `1`（Bash 工具、tmux 会话）。在 [hooks](/zh-CN/hooks) 或[状态行](/zh-CN/statusline)命令中未设置。用于检测脚本何时在 Claude Code 生成的 shell 内运行 |

52| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [subagent](/zh-CN/sub-agents) 类型，如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于想要空白状态的 SDK 用户很有用 |52| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [subagent](/zh-CN/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。此百分比与[状态行](/zh-CN/statusline)中可用的 `context_window.used_percentage` 字段一致 |55| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩的上下文容量百分比（1-100）。默认情况下，自动压缩在大约 95% 容量时触发。使用较低的值（如 `50`）可更早进行压缩。高于默认阈值的值无效。适用于主对话和 subagents。此百分比与[状态行](/zh-CN/statusline)中可用的 `context_window.used_percentage` 字段一致 |

60| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 以从系统提示的开头省略归属块（客户端版本和提示指纹）。禁用它会改善通过 [LLM 网关](/zh-CN/llm-gateway)路由时的 prompt caching 命中率。Anthropic API 缓存不受影响 |61| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 以从系统提示的开头省略归属块（客户端版本和提示指纹）。禁用它会改善通过 [LLM 网关](/zh-CN/llm-gateway)路由时的 prompt caching 命中率。Anthropic API 缓存不受影响 |

61| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 设置用于自动压缩计算的上下文容量（以令牌为单位）。默认为模型的上下文窗口：标准模型为 200K，或[扩展上下文](/zh-CN/model-config#extended-context)模型为 1M。在 1M 模型上使用较低的值（如 `500000`）可将窗口视为 500K 用于压缩目的。该值上限为模型的实际上下文窗口。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作为此值的百分比应用。设置此变量会将压缩阈值与状态行的 `used_percentage` 解耦，后者始终使用模型的完整上下文窗口 |62| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 设置用于自动压缩计算的上下文容量（以令牌为单位）。默认为模型的上下文窗口：标准模型为 200K，或[扩展上下文](/zh-CN/model-config#extended-context)模型为 1M。在 1M 模型上使用较低的值（如 `500000`）可将窗口视为 500K 用于压缩目的。该值上限为模型的实际上下文窗口。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作为此值的百分比应用。设置此变量会将压缩阈值与状态行的 `used_percentage` 解耦，后者始终使用模型的完整上下文窗口 |

62| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/zh-CN/vs-code)。默认情况下，在支持的 IDE 的集成终端内启动时，Claude Code 会自动连接。设置为 `false` 以防止这种情况。设置为 `true` 以在自动检测失败时强制连接尝试，例如当 tmux 遮挡父终端时 |63| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/zh-CN/vs-code)。默认情况下，在支持的 IDE 的集成终端内启动时，Claude Code 会自动连接。设置为 `false` 以防止这种情况。设置为 `true` 以在自动检测失败时强制连接尝试，例如当 tmux 遮挡父终端时。优先于 [`autoConnectIde`](/zh-CN/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 上下文窗口](/zh-CN/model-config#extended-context)支持。设置后，1M 模型变体在模型选择器中不可用。对于具有合规要求的企业环境很有用 |70| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 以禁用[1M 上下文窗口](/zh-CN/model-config#extended-context)支持。设置后，1M 模型变体在模型选择器中不可用。对于具有合规要求的企业环境很有用 |

70| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 以禁用 Opus 4.6 和 Sonnet 4.6 的[自适应推理](/zh-CN/model-config#adjust-effort-level)并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。对 Opus 4.7 无效，它始终使用自适应推理 |71| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 以禁用 Opus 4.6 和 Sonnet 4.6 的[自适应推理](/zh-CN/model-config#adjust-effort-level)并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。对 Opus 4.7 无效，它始终使用自适应推理 |

72| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)并使用经典主屏幕渲染器。对话保持在您的终端的原生滚动条中，因此 `Cmd+f` 和 tmux 复制模式可以正常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-CN/settings#available-settings) 设置。您也可以使用 `/tui default` 切换 |

72| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 以禁用[自动内存](/zh-CN/memory#auto-memory)。设置为 `0` 以在逐步推出期间强制启用自动内存。禁用后，Claude 不会创建或加载自动内存文件 |74| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 以禁用[自动内存](/zh-CN/memory#auto-memory)。设置为 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-CN/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` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |77| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/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` 时也会禁用调查。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |80| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 表现如何？"会话质量调查。在设置 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时也会禁用调查。要设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |

80| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置的提交和 PR 工作流说明和 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。设置后优先于 [`includeGitInstructions`](/zh-CN/settings#available-settings) 设置 |82| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置的提交和 PR 工作流说明和 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。设置后优先于 [`includeGitInstructions`](/zh-CN/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` 设置。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |92| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置努力级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `/effort` 和 `effortLevel` 设置。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |

91| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/zh-CN/interactive-mode#session-recap)可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/zh-CN/settings#available-settings) 为 `false` 时强制启用回顾。优先于设置和 `/config` 切换 |93| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/zh-CN/interactive-mode#session-recap)可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/zh-CN/settings#available-settings) 为 `false` 时强制启用回顾。优先于设置和 `/config` 切换 |

92| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在[非交互模式](/zh-CN/headless)中的转换边界处刷新插件状态，在后台安装完成后。默认关闭，因为刷新会在会话中途更改系统提示，这会使该转换的 [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) 失效 |94| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在[非交互模式](/zh-CN/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` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于直接 Anthropic API 连接默认启用。设置为 `0` 以选择退出。设置为 `1` 以强制启用，即使服务器端默认值为关闭。对 Bedrock、Vertex、Foundry 或[网关](/zh-CN/llm-gateway)连接无效 |

96| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤 |

94| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以禁用提示建议（`/config` 中的"提示建议"切换）。这些是在 Claude 响应后出现在提示输入中的灰显预测。请参阅[提示建议](/zh-CN/interactive-mode#prompt-suggestions) |97| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以禁用提示建议（`/config` 中的"提示建议"切换）。这些是在 Claude 响应后出现在提示输入中的灰显预测。请参阅[提示建议](/zh-CN/interactive-mode#prompt-suggestions) |

104| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 设置为 `1` 以在您的终端支持但未自动检测到时强制启用 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。对于实现 BSU/ESU 但不回复能力探针的模拟器（如 Emacs `eat`）很有用。在 tmux 下无效 |

101| `CLAUDE_CODE_FORK_SUBAGENT` | 设置为 `1` 以启用[分叉 subagents](/zh-CN/sub-agents#fork-the-current-conversation)。分叉的 subagent 从主会话继承完整的对话上下文，而不是从头开始。启用后，`/fork` 生成分叉的 subagent 而不是充当 [`/branch`](/zh-CN/commands) 的别名，所有 subagent 生成在后台运行。在交互模式和通过 SDK 或 `claude -p` 中工作 |105| `CLAUDE_CODE_FORK_SUBAGENT` | 设置为 `1` 以启用[分叉 subagents](/zh-CN/sub-agents#fork-the-current-conversation)。分叉的 subagent 从主会话继承完整的对话上下文，而不是从头开始。启用后，`/fork` 生成分叉的 subagent 而不是充当 [`/branch`](/zh-CN/commands) 的别名，所有 subagent 生成在后台运行。在交互模式和通过 SDK 或 `claude -p` 中工作 |

102| `CLAUDE_CODE_GIT_BASH_PATH` | 仅限 Windows：Git Bash 可执行文件 (`bash.exe`) 的路径。当 Git Bash 已安装但不在您的 PATH 中时使用。请参阅 [Windows 设置](/zh-CN/setup#set-up-on-windows) |106| `CLAUDE_CODE_GIT_BASH_PATH` | 仅限 Windows：Git Bash 可执行文件 (`bash.exe`) 的路径。当 Git Bash 已安装但不在您的 PATH 中时使用。请参阅 [Windows 设置](/zh-CN/setup#set-up-on-windows) |

103| `CLAUDE_CODE_GLOB_HIDDEN` | 设置为 `false` 以在 Claude 调用 [Glob 工具](/zh-CN/tools-reference)时从结果中排除点文件。默认包含。不影响 `@` 文件自动完成、`ls`、Grep 或 Read |107| `CLAUDE_CODE_GLOB_HIDDEN` | 设置为 `false` 以在 Claude 调用 [Glob 工具](/zh-CN/tools-reference)时从结果中排除点文件。默认包含。不影响 `@` 文件自动完成、`ls`、Grep 或 Read |

120| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待处理 OpenTelemetry spans 的超时时间（以毫秒为单位）（默认值：5000）。请参阅[监控](/zh-CN/monitoring-usage) |124| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待处理 OpenTelemetry spans 的超时时间（以毫秒为单位）（默认值：5000）。请参阅[监控](/zh-CN/monitoring-usage) |

121| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态 OpenTelemetry 标头的间隔（以毫秒为单位）（默认值：1740000 / 29 分钟）。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) |125| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态 OpenTelemetry 标头的间隔（以毫秒为单位）（默认值：1740000 / 29 分钟）。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) |

122| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（以毫秒为单位）（默认值：2000）。如果在退出时丢弃指标，请增加此值。请参阅[监控](/zh-CN/monitoring-usage) |126| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（以毫秒为单位）（默认值：2000）。如果在退出时丢弃指标，请增加此值。请参阅[监控](/zh-CN/monitoring-usage) |

127| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 设置为 `1` 以让 Claude Code 在新版本可用时在后台运行您的包管理器的升级命令。适用于 Homebrew 和 WinGet 安装。其他包管理器继续显示升级命令而不运行它。请参阅[自动更新](/zh-CN/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 操作超时](/zh-CN/plugin-marketplaces#git-operations-time-out) |130| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安装或更新插件时 git 操作的超时（以毫秒为单位）（默认值：120000）。对于大型存储库或网络连接缓慢的情况，请增加此值。请参阅[Git 操作超时](/zh-CN/plugin-marketplaces#git-operations-time-out) |

131| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云会话](/zh-CN/claude-code-on-the-web)中自动设置为当前会话的 ID。读取此值以构造返回会话转录的链接。请参阅[将工件链接回会话](/zh-CN/claude-code-on-the-web#link-artifacts-back-to-the-session) |136| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云会话](/zh-CN/claude-code-on-the-web)中自动设置为当前会话的 ID。读取此值以构造返回会话转录的链接。请参阅[将工件链接回会话](/zh-CN/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` | 在[全屏渲染](/zh-CN/fullscreen)中设置鼠标滚轮滚动倍数。接受 1 到 20 的值。设置为 `3` 以匹配 `vim`（如果您的终端每个刻度线发送一个滚轮事件而不进行放大） |139| `CLAUDE_CODE_SCROLL_SPEED` | 在[全屏渲染](/zh-CN/fullscreen)中设置鼠标滚轮滚动倍数。接受 1 到 20 的值。设置为 `3` 以匹配 `vim`（如果您的终端每个刻度线发送一个滚轮事件而不进行放大）。在 JetBrains IDE 终端中被忽略，Claude Code 使用其自己的滚动处理 |

135| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/zh-CN/hooks#sessionend) hooks 的时间预算（以毫秒为单位）。适用于会话退出、`/clear` 和通过交互式 `/resume` 切换会话。默认预算为 1.5 秒，自动提高到设置文件中配置的最高每个 hook `timeout`，最高 60 秒。插件提供的 hooks 上的超时不会提高预算 |140| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | [SessionEnd](/zh-CN/hooks#sessionend) hooks 的时间预算（以毫秒为单位）。适用于会话退出、`/clear` 和通过交互式 `/resume` 切换会话。默认预算为 1.5 秒，自动提高到设置文件中配置的最高每个 hook `timeout`，最高 60 秒。插件提供的 hooks 上的超时不会提高预算 |

141| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程中自动设置为当前会话 ID。与传递给 [hooks](/zh-CN/hooks) 的 `session_id` 字段匹配。在 `/clear` 时更新。用于将脚本和外部工具与启动它们的 Claude Code 会话相关联 |

137| `CLAUDE_CODE_SHELL_PREFIX` | 命令前缀以包装 Claude Code 生成的所有 bash 命令：Bash 工具调用、[hook](/zh-CN/hooks) 命令和 stdio [MCP server](/zh-CN/mcp) 启动命令。对于日志记录或审计很有用。示例：设置 `/path/to/logger.sh` 将每个命令作为 `/path/to/logger.sh <command>` 运行 |143| `CLAUDE_CODE_SHELL_PREFIX` | 命令前缀以包装 Claude Code 生成的所有 bash 命令：Bash 工具调用、[hook](/zh-CN/hooks) 命令和 stdio [MCP server](/zh-CN/mcp) 启动命令。对于日志记录或审计很有用。示例：设置 `/path/to/logger.sh` 将每个命令作为 `/path/to/logger.sh <command>` 运行 |

138| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。MCP 工具来自 `--mcp-config` 仍然可用。禁用 hooks、skills、plugins、MCP servers、自动内存和 CLAUDE.md 的自动发现。[`--bare`](/zh-CN/headless#start-faster-with-bare-mode) CLI 标志设置此选项 |144| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。MCP 工具来自 `--mcp-config` 仍然可用。禁用 hooks、skills、plugins、MCP servers、自动内存和 CLAUDE.md 的自动发现。[`--bare`](/zh-CN/headless#start-faster-with-bare-mode) CLI 标志设置此选项 |

146| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 以从子进程环境（Bash 工具、hooks、MCP stdio 服务器）中删除 Anthropic 和云提供商凭证。父 Claude 进程为 API 调用保留这些凭证，但子进程无法读取它们，减少了通过 shell 扩展尝试窃取机密的提示注入攻击的暴露。在 Linux 上，这也在隔离的 PID 命名空间中运行 Bash 子进程，以便它们无法通过 `/proc` 读取主机进程环境；作为副作用，`ps`、`pgrep` 和 `kill` 无法看到或信号主机进程。当配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此选项 |152| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 以从子进程环境（Bash 工具、hooks、MCP stdio 服务器）中删除 Anthropic 和云提供商凭证。父 Claude 进程为 API 调用保留这些凭证，但子进程无法读取它们，减少了通过 shell 扩展尝试窃取机密的提示注入攻击的暴露。在 Linux 上，这也在隔离的 PID 命名空间中运行 Bash 子进程，以便它们无法通过 `/proc` 读取主机进程环境；作为副作用，`ps`、`pgrep` 和 `kill` 无法看到或信号主机进程。当配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此选项 |

147| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 设置为 `1` 在非交互模式（`-p` 标志）中等待插件安装完成后再进行第一个查询。没有这个，插件在后台安装，可能在第一个回合不可用。与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合以限制等待时间 |153| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 设置为 `1` 在非交互模式（`-p` 标志）中等待插件安装完成后再进行第一个查询。没有这个，插件在后台安装，可能在第一个回合不可用。与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合以限制等待时间 |

148| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（以毫秒为单位）。超过时，Claude Code 继续而不使用插件并记录错误。无默认值：没有此变量，同步安装会等待直到完成 |154| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（以毫秒为单位）。超过时，Claude Code 继续而不使用插件并记录错误。无默认值：没有此变量，同步安装会等待直到完成 |

150| `CLAUDE_CODE_TASK_LIST_ID` | 跨会话共享任务列表。在多个 Claude Code 实例中设置相同的 ID 以协调共享任务列表。请参阅[任务列表](/zh-CN/interactive-mode#task-list) |156| `CLAUDE_CODE_TASK_LIST_ID` | 跨会话共享任务列表。在多个 Claude Code 实例中设置相同的 ID 以协调共享任务列表。请参阅[任务列表](/zh-CN/interactive-mode#task-list) |

152| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 将 `/claude-{uid}/`（Unix）或 `/claude/`（Windows）附加到此路径。默认值：macOS 上为 `/tmp`，Linux/Windows 上为 `os.tmpdir()` |158| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 将 `/claude-{uid}/`（Unix）或 `/claude/`（Windows）附加到此路径。默认值：macOS 上为 `/tmp`，Linux/Windows 上为 `os.tmpdir()` |

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-CN/mcp#use-mcp-servers-from-claude-ai)。对于已登录的用户默认启用 |193| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以禁用 Claude Code 中的 [claude.ai MCP servers](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对于已登录的用户默认启用 |

198| `MAX_STRUCTURED_OUTPUT_RETRIES` | 当模型的响应无法针对非交互模式（`-p` 标志）中的 [`--json-schema`](/zh-CN/cli-reference#cli-flags) 进行验证时重试的次数。默认为 5 |204| `MAX_STRUCTURED_OUTPUT_RETRIES` | 当模型的响应无法针对非交互模式（`-p` 标志）中的 [`--json-schema`](/zh-CN/cli-reference#cli-flags) 进行验证时重试的次数。默认为 5 |

199| `MAX_THINKING_TOKENS` | 覆盖[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)令牌预算。上限是模型的[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)减一。设置为 `0` 以完全禁用思考。在具有[自适应推理](/zh-CN/model-config#adjust-effort-level)的模型上，除非通过 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 禁用自适应推理，否则预算被忽略 |205| `MAX_THINKING_TOKENS` | 覆盖[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)令牌预算。上限是模型的[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)减一。设置为 `0` 以完全禁用思考。在具有[自适应推理](/zh-CN/model-config#adjust-effort-level)的模型上，除非通过 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 禁用自适应推理，否则预算被忽略 |

200| `MCP_CLIENT_SECRET` | 需要[预配置凭证](/zh-CN/mcp#use-pre-configured-oauth-credentials)的 MCP 服务器的 OAuth 客户端密钥。在使用 `--client-secret` 添加服务器时避免交互式提示 |206| `MCP_CLIENT_SECRET` | 需要[预配置凭证](/zh-CN/mcp#use-pre-configured-oauth-credentials)的 MCP 服务器的 OAuth 客户端密钥。在使用 `--client-secret` 添加服务器时避免交互式提示 |

201| `MCP_CONNECTION_NONBLOCKING` | 设置为 `true` 在非交互模式（`-p`）中完全跳过 MCP 连接等待。对于不需要 MCP 工具的脚本化管道很有用。没有此变量，第一个查询会等待最多 5 秒以获得 `--mcp-config` 服务器连接 |207| `MCP_CONNECTION_NONBLOCKING` | 设置为 `true` 在非交互模式（`-p`）中完全跳过 MCP 连接等待。对于不需要 MCP 工具的脚本化管道很有用。没有此变量，第一个查询会等待最多 5 秒以获得 `--mcp-config` 服务器连接。服务器配置为 [`alwaysLoad: true`](/zh-CN/mcp#exempt-a-server-from-deferral) 始终阻止启动，无论此变量如何，因为它们的工具必须在构建第一个提示时存在 |

202| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重定向回调的固定端口，作为在使用[预配置凭证](/zh-CN/mcp#use-pre-configured-oauth-credentials)添加 MCP 服务器时 `--callback-port` 的替代方案 |208| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重定向回调的固定端口，作为在使用[预配置凭证](/zh-CN/mcp#use-pre-configured-oauth-credentials)添加 MCP 服务器时 `--callback-port` 的替代方案 |

errors.md +27 −5

Details

35| `does not meet scope requirement user:profile` | [身份验证](#oauth-scope-requirement) |35| `does not meet scope requirement user:profile` | [身份验证](#oauth-scope-requirement) |

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

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

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

38| `Prompt is too long` | [请求错误](#prompt-is-too-long) |39| `Prompt is too long` | [请求错误](#prompt-is-too-long) |

39| `Error during compaction: Conversation too long` | [请求错误](#error-during-compaction-conversation-too-long) |40| `Error during compaction: Conversation too long` | [请求错误](#error-during-compaction-conversation-too-long) |

40| `Request too large` | [请求错误](#request-too-large) |41| `Request too large` | [请求错误](#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

307* 确保您的防火墙允许[网络访问要求](/zh-CN/network-config#network-access-requirements)中列出的主机308* 确保您的防火墙允许[网络访问要求](/zh-CN/network-config#network-access-requirements)中列出的主机

308* 间歇性故障会[自动重试](#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* 有关完整设置说明，请参阅[网络配置](/zh-CN/network-config#custom-ca-certificates)329* 有关完整设置说明，请参阅[网络配置](/zh-CN/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这不是客户端网络问题。云会话和[例程](/zh-CN/routines)在沙箱环境内运行，其出站流量被过滤到环境的允许列表。**Default** 环境使用 **Trusted** 访问，允许[默认允许列表](/zh-CN/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-CN/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的访问，请改为选择 **Full**。

349* 单击 **Save changes**。下一次运行使用更新的允许列表。

350

351有关访问级别和默认允许列表，请参阅[网络访问](/zh-CN/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-CN/env-vars) 提高到思考预算之上511* 降低 `MAX_THINKING_TOKENS`，或将 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-CN/env-vars) 提高到思考预算之上

490* 有关预算如何与输出长度交互的信息，请参阅[扩展思考](/zh-CN/common-workflows#use-extended-thinking-thinking-mode)512* 有关预算如何与输出长度交互的信息，请参阅[扩展思考](/zh-CN/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-CN/skills#override-skill-visibility-from-settings) 以在不编辑其文件的情况下执行相同操作。

223 223

224### 了解功能如何加载224### 了解功能如何加载

225 225

233 233

234 **加载内容：** 所有 CLAUDE.md 文件的完整内容（托管、用户和项目级别）。234 **加载内容：** 所有 CLAUDE.md 文件的完整内容（托管、用户和项目级别）。

235 235

236 **继承：** Claude 从您的工作目录读取 CLAUDE.md 文件直到根目录，并在访问这些文件时发现子目录中的嵌套文件。有关详细信息，请参阅 [CLAUDE.md 文件如何加载](/zh-CN/memory#how-claudemd-files-load)。236 **继承：** Claude 从您的工作目录读取 CLAUDE.md 文件直到根目录，并在访问这些文件时发现子目录中的嵌套文件。有关详细信息，请参阅 [CLAUDE.md 文件如何加载](/zh-CN/memory#how-claude-md-files-load)。

237 237

238 <Tip>保持 CLAUDE.md 在 200 行以下。将参考材料移到 skills，这些 skills 按需加载。</Tip>238 <Tip>保持 CLAUDE.md 在 200 行以下。将参考材料移到 skills，这些 skills 按需加载。</Tip>

239 </Tab>239 </Tab>

282 </Tab>282 </Tab>

283 283

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

285 **何时：** 触发时。Hooks 在特定的生命周期事件上触发，如工具执行、会话边界、提示提交、权限请求和压缩。有关完整列表，请参阅 [Hooks](/zh-CN/hooks-guide)。285 **何时：** 触发时。Hooks 在特定的生命周期事件上触发，如工具执行、会话边界、提示提交、权限请求和压缩。有关完整列表，请参阅 [Hooks](/zh-CN/hooks)。

286 286

287 **加载内容：** 默认情况下无。Hooks 在主对话外执行。287 **加载内容：** 默认情况下无。Hooks 在主对话外执行。

288 288

fullscreen.md +11 −3

Details

77 77

78向上滚动会暂停自动跟随，以便新输出不会将您拉回底部。按 `Ctrl+End` 或滚动到底部以恢复跟随。78向上滚动会暂停自动跟随，以便新输出不会将您拉回底部。按 `Ctrl+End` 或滚动到底部以恢复跟随。

79 79

80要完全关闭自动跟随，以便视图保持在您离开的位置，请打开 `/config` 并将"自动滚动"设置为关闭。禁用自动滚动后，视图永远不会自动跳到底部。权限提示和其他需要响应的对话框仍然会滚动到视图中，无论此设置如何。80要完全关闭自动跟随，以便视图保持在您离开的位置，请打开 `/config` 并将自动滚动设置为关闭。禁用自动滚动后，视图永远不会自动跳到底部。权限提示和其他需要响应的对话框仍然会滚动到视图中，无论此设置如何。

81 81

82### 鼠标滚轮滚动82### 鼠标滚轮滚动

83 83

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` 会话中启用全屏渲染。常规 tmux 在 iTerm2 内，没有 `-CC`，工作正常。141全屏渲染与 iTerm2 的 tmux 集成模式不兼容，这是您使用 `tmux -CC` 进入的模式。在集成模式中，iTerm2 将每个 tmux 窗格渲染为原生分割，而不是让 tmux 绘制到终端。备用屏幕缓冲区和鼠标跟踪在那里无法正确工作：鼠标滚轮不起作用，双击可能会损坏终端状态。不要在 `tmux -CC` 会话中启用全屏渲染。常规 tmux 在 iTerm2 内，没有 `-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 +22 −1

Details

266Claude Code v2.1.121 或更高版本通过相同的应用默认凭证链支持[基于 X.509 证书的工作负载身份联合](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)。将 `GOOGLE_APPLICATION_CREDENTIALS` 设置为您的凭证配置文件的路径。266Claude Code v2.1.121 或更高版本通过相同的应用默认凭证链支持[基于 X.509 证书的工作负载身份联合](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>` |

~~57| 插件目录 | `--plugin-dir <path>` |~~57| 插件 | `--plugin-dir <path>`, `--plugin-url <url>` |

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-CN/costs)。

81<Note>

82 从 Claude Code v2.1.128 开始，管道 stdin 的上限为 10MB。如果超过上限，Claude Code 会以清晰的错误和非零状态退出。要处理更大的输入，请将内容写入文件并在提示中引用文件路径，而不是管道传输它。

83</Note>

85### 将 Claude 添加到构建脚本

87您可以在脚本中包装非交互调用，以将 Claude 用作项目特定的 linter 或审查者。

89此 `package.json` 脚本将针对 `main` 的 diff 管道传输到 Claude，并要求它报告拼写错误。管道传输 diff 意味着 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-CN/env-vars)，在这种情况下 `plugin_install` 事件在其之前。使用插件字段在插件未加载时使 CI 失败：167`system/init` 事件报告会话元数据，包括模型、工具、MCP 服务器和加载的插件。它是流中的第一个事件，除非设置了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-CN/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-CN/env-vars) 时，Claude Code 在第一轮之前安装市场插件时发出 `system/plugin_install` 事件。使用这些在您自己的 UI 中显示安装进度。174当设置了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-CN/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 在您工作时将您的对话保存在本地。每条消息、工具使用和结果都被写入 `~/.claude/projects/` 下的纯文本 JSONL 文件，这使得[回退](#undo-changes-with-checkpoints)、[恢复和分叉](#resume-or-fork-sessions)会话成为可能。在 Claude 进行代码更改之前，它还会对受影响的文件进行快照，以便您在需要时可以恢复。有关路径、保留和如何清除此数据，请参阅[`~/.claude` 中的应用数据](/zh-CN/claude-directory#application-data)。

98 98

99**会话是独立的。** 每个新会话都以新的上下文窗口开始，没有来自以前会话的对话历史。Claude 可以使用[自动内存](/zh-CN/memory#auto-memory)跨会话保持学习，您可以在 [CLAUDE.md](/zh-CN/memory) 中添加您自己的持久说明。99**会话是独立的。** 每个新会话都以新的上下文窗口开始，没有来自以前会话的对话历史。Claude 可以使用[自动内存](/zh-CN/memory#auto-memory)跨会话保持学习，您可以在 [CLAUDE.md](/zh-CN/memory) 中添加您自己的持久说明。

100 100

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

102 102

103每个 Claude Code 对话都是一个与您当前目录相关的会话。当您恢复时，您只会看到来自该目录的会话。103每个 Claude Code 对话都是一个与您当前目录相关的会话。`/resume` 选择器默认显示来自当前 worktree 的会话，带有键盘快捷键以扩展列表到其他 worktrees 或项目。有关选择器快捷键的完整列表以及名称解析如何工作，请参阅[管理会话](/zh-CN/sessions#use-the-session-picker)。

104 104

105Claude 看到您当前分支的文件。当您切换分支时，Claude 看到新分支的文件，但您的对话历史保持不变。Claude 记得您讨论过的内容，即使在切换后也是如此。105Claude 看到您当前分支的文件。当您切换分支时，Claude 看到新分支的文件，但您的对话历史保持不变。Claude 记得您讨论过的内容，即使在切换后也是如此。

106 106

107由于会话与目录相关，您可以通过使用 [git worktrees](/zh-CN/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) 运行并行 Claude 会话，这为各个分支创建单独的目录。107由于会话与目录相关，您可以通过使用 [git worktrees](/zh-CN/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-CN/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 会在几次尝试后停止自动压缩，并显示错误而不是循环。有关恢复步骤，请参阅[自动压缩停止并出现抖动错误](/zh-CN/troubleshooting#auto-compaction-stops-with-a-thrashing-error)。

130

137运行 `/context` 以查看什么在占用空间。MCP 工具定义默认被延迟，并通过[工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)按需加载，因此只有工具名称消耗上下文，直到 Claude 使用特定工具。运行 `/mcp` 以检查每个服务器的成本。131运行 `/context` 以查看什么在占用空间。MCP 工具定义默认被延迟，并通过[工具搜索](/zh-CN/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-CN/skills) 按需加载。Claude 在会话开始时看到 skill 描述，但完整内容仅在使用 skill 时加载。对于您手动调用的 skills，设置 `disable-model-invocation: true` 以将描述保留在上下文之外，直到您需要它们。137[Skills](/zh-CN/skills) 按需加载。Claude 在会话开始时看到 skill 描述，但完整内容仅在使用 skill 时加载。对于您手动调用的 skills，设置 `disable-model-invocation: true` 以将描述保留在上下文之外，直到您需要它们。对于您没有编写的 skills，使用 [`skillOverrides`](/zh-CN/skills#override-skill-visibility-from-settings) 从设置中执行相同操作。

144 138

145[Subagents](/zh-CN/sub-agents) 获得自己的新上下文，完全独立于您的主对话。他们的工作不会使您的上下文膨胀。完成后，他们返回一个摘要。这种隔离是为什么 subagents 有助于长会话。139[Subagents](/zh-CN/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* **自动模式**：Claude 使用后台安全检查评估所有操作。目前是研究预览160* **自动模式**：Claude 使用后台安全检查评估所有操作。目前是研究预览

167 161

interactive-mode.md +7 −6

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**：设置 → 配置文件 → 键 → 常规 → 将左/右 Option 键设置为"Esc+"16 * **iTerm2**：设置 → 配置文件 → 键 → 常规 → 将左/右 Option 键设置为"Esc+"

17 * **Apple Terminal**：设置 → 配置文件 → 键盘 → 勾选"使用 Option 作为 Meta 键"17 * **Apple Terminal**：设置 → 配置文件 → 键盘 → 勾选"使用 Option 作为 Meta 键"

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### 快速命令

81| 快捷键 | 描述 | 注释 |81| 快捷键 | 描述 | 注释 |

82| :------ | :-------- | :------------------------------------------ |82| :------ | :-------- | :------------------------------------------ |

83| `/` 在开始 | 命令或 skill | 请参阅[命令](#commands)和 [skills](/zh-CN/skills) |83| `/` 在开始 | 命令或 skill | 请参阅[命令](#commands)和 [skills](/zh-CN/skills) |

~~84| `!` 在开始 | Bash 模式 | 直接运行命令并将执行输出添加到会话 |~~84| `!` 在开始 | Shell 模式 | 直接运行命令并将执行输出添加到会话 |

85| `@` | 文件路径提及 | 触发文件路径自动完成 |85| `@` | 文件路径提及 | 触发文件路径自动完成 |

86 86

87### 转录查看器87### 转录查看器

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 格式的网关时，Claude Code 在启动时会查询网关的 `/v1/models` 端点，并将返回的模型添加到 `/model` 选择器中。每个发现的条目都标记为"From gateway"，并在响应中提供 `display_name` 字段时使用该字段。这需要 Claude Code v2.1.126 或更高版本。56当 `ANTHROPIC_BASE_URL` 指向一个公开 Anthropic Messages 格式的网关时，Claude Code 在启动时可以查询网关的 `/v1/models` 端点，并将返回的模型添加到 `/model` 选择器中。设置 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 来启用此功能。默认情况下发现功能是关闭的，以便由共享 API 密钥支持的网关不会向每个用户显示该密钥可以访问的每个模型。每个发现的条目都标记为"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 +14 −4

Details

325/mcp325/mcp

326```326```

327 327

328`/mcp` 面板在每个连接的服务器旁边显示工具计数，并标记声称工具功能但未公开任何工具的服务器。

329

330服务器名称 `workspace` 保留供内部使用。如果您的配置定义了具有该名称的服务器，Claude Code 会在加载时跳过它，并显示一条警告，要求您重命名它。

331

328### 动态工具更新332### 动态工具更新

329 333

330Claude Code 支持 MCP `list_changed` 通知，允许 MCP 服务器动态更新其可用工具、提示和资源，而无需您断开连接并重新连接。当 MCP 服务器发送 `list_changed` 通知时，Claude Code 会自动刷新来自该服务器的可用功能。334Claude Code 支持 MCP `list_changed` 通知，允许 MCP 服务器动态更新其可用工具、提示和资源，而无需您断开连接并重新连接。当 MCP 服务器发送 `list_changed` 通知时，Claude Code 会自动刷新来自该服务器的可用功能。

337 341

338### 使用频道推送消息342### 使用频道推送消息

339 343

340MCP 服务器也可以直接将消息推送到您的会话中，以便 Claude 可以对外部事件（如 CI 结果、监控警报或聊天消息）做出反应。要启用此功能，您的服务器声明 `claude/channel` 功能，并在启动时使用 `--channels` 标志选择加入。请参阅[频道](/zh-CN/channels)以使用官方支持的频道，或[频道参考](/zh-CN/channels-reference)以构建您自己的频道。344MCP 服务器也可以直接将消息推送到您的会话中，以便 Claude 可以对外部事件（如 CI 结果、监控警报或聊天消息）做出反应。要启用此功能，您的服务器声明 `claude/channel` 功能，并在启动时使用 `--channels` 标志选择加入。请参阅 [Channels](/zh-CN/channels) 以使用官方支持的频道，或 [Channels reference](/zh-CN/channels-reference) 以构建您自己的频道。

341 345

342<Tip>346<Tip>

343 提示：347 提示：

354 358

355### 插件提供的 MCP 服务器359### 插件提供的 MCP 服务器

356 360

357[插件](/zh-CN/plugins)可以捆绑 MCP 服务器，在启用插件时自动提供工具和集成。插件 MCP 服务器的工作方式与用户配置的服务器相同。361[Plugins](/zh-CN/plugins) 可以捆绑 MCP 服务器，在启用插件时自动提供工具和集成。插件 MCP 服务器的工作方式与用户配置的服务器相同。

358 362

359**插件 MCP 服务器的工作原理**：363**插件 MCP 服务器的工作原理**：

360 364

421 425

422## MCP 安装范围426## MCP 安装范围

423 427

424MCP 服务器可以在三个不同的范围级别进行配置。您选择的范围控制服务器在哪些项目中加载以及配置是否与您的团队共享。428MCP 服务器可以在三个不同的范围级别进行配置。您选择的范围控制服务器在哪些项目中加载以及配置是否与您的团队共享。管理员还可以通过[托管配置](#managed-mcp-configuration)在企业级别部署服务器。

425 429

426| 范围 | 加载位置 | 与团队共享 | 存储位置 |430| 范围 | 加载位置 | 与团队共享 | 存储位置 |

427| -------------------- | ------ | -------- | ------------------- |431| -------------------- | ------ | -------- | ------------------- |

445claude mcp add --transport http stripe --scope local https://mcp.stripe.com449claude mcp add --transport http stripe --scope local https://mcp.stripe.com

446```450```

447 451

448从 `/path/to/your/project` 运行时，该命令将服务器写入 `~/.claude.json` 中您当前项目的条目。下面的示例显示结果：452该命令将服务器写入 `~/.claude.json` 中您当前项目的条目。下面的示例显示从 `/path/to/your/project` 运行时的结果：

449 453

450```json theme={null}454```json theme={null}

451{455{

942 </Step>946 </Step>

943</Steps>947</Steps>

944 948

949您在 Claude Code 中添加的服务器优先于指向相同 URL 的 claude.ai 连接器。发生这种情况时，`/mcp` 会将连接器列为隐藏，并显示如何删除重复项（如果您更希望使用连接器）。

950

945要在 Claude Code 中禁用 claude.ai MCP 服务器，请将 `ENABLE_CLAUDEAI_MCP_SERVERS` 环境变量设置为 `false`：951要在 Claude Code 中禁用 claude.ai MCP 服务器，请将 `ENABLE_CLAUDEAI_MCP_SERVERS` 环境变量设置为 `false`：

946 952

947```bash theme={null}953```bash theme={null}

1181 1187

1182`alwaysLoad` 字段在所有服务器类型上可用，需要 Claude Code v2.1.121 或更高版本。MCP 服务器也可以通过在工具的 `_meta` 对象中包含 `"anthropic/alwaysLoad": true` 来标记单个工具为始终加载，这对该工具仅具有相同的效果。1188`alwaysLoad` 字段在所有服务器类型上可用，需要 Claude Code v2.1.121 或更高版本。MCP 服务器也可以通过在工具的 `_meta` 对象中包含 `"anthropic/alwaysLoad": true` 来标记单个工具为始终加载，这对该工具仅具有相同的效果。

1183 1189

1190设置 `alwaysLoad: true` 也会阻止启动直到服务器连接，上限为标准 5 秒连接超时。即使设置了 [`MCP_CONNECTION_NONBLOCKING=1`](/zh-CN/env-vars)，这也适用，因为工具必须在构建第一个提示时存在。当启用非阻塞时，其他服务器仍在后台连接。

1191

1184## 将 MCP 提示用作命令1192## 将 MCP 提示用作命令

1185 1193

1186MCP 服务器可以公开在 Claude Code 中作为命令可用的提示。1194MCP 服务器可以公开在 Claude Code 中作为命令可用的提示。

1349* `https://*.example.com/*` - 允许 example.com 的任何子域1357* `https://*.example.com/*` - 允许 example.com 的任何子域

1350* `http://localhost:*/*` - 允许 localhost 上的任何端口1358* `http://localhost:*/*` - 允许 localhost 上的任何端口

1351 1359

1360主机名匹配不区分大小写，忽略尾部 FQDN 点，匹配 DNS 语义。像 `*://Mcp.Example.com/*` 这样的模式匹配 `https://mcp.example.com/api`，`https://mcp.example.com.` 被视为与 `https://mcp.example.com` 相同。路径保持区分大小写。

1361

1352**远程服务器行为**：1362**远程服务器行为**：

1353 1363

1354* 当允许列表包含**任何** `serverUrl` 条目时，远程服务器**必须**匹配其中一个 URL 模式1364* 当允许列表包含**任何** `serverUrl` 条目时，远程服务器**必须**匹配其中一个 URL 模式

memory.md +2 −0

Details

378* 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。378* 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。

379* 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。379* 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。

380 380

381如果指令是必须在特定点运行的内容，例如在每次提交之前或每次文件编辑之后，请将其写成 [hook](/zh-CN/hooks-guide) 代替。Hooks 在固定的生命周期事件处作为 shell 命令执行，并且无论 Claude 决定做什么都适用。

382

381对于你想要在系统提示级别的指令，使用 [`--append-system-prompt`](/zh-CN/cli-reference#system-prompt-flags)。这必须在每次调用时传递，因此它更适合脚本和自动化而不是交互式使用。383对于你想要在系统提示级别的指令，使用 [`--append-system-prompt`](/zh-CN/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-CN/env-vars)。212在 Opus 4.6 和 Sonnet 4.6 上，您可以设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢复到由 `MAX_THINKING_TOKENS` 控制的先前固定思考预算。请参阅[环境变量](/zh-CN/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-CN/env-vars)。其他值仅适用于[固定思考预算](#adaptive-reasoning-and-fixed-thinking-budgets) |

223

224思考输出默认折叠。按 `Ctrl+O` 切换详细模式并将推理显示为灰色斜体文本。Anthropic API 上的交互式会话默认接收编辑后的思考块，因此如果您想在展开时获得完整摘要，请在[设置](/zh-CN/settings)中设置 `showThinkingSummaries: true`。您需要为所有生成的思考令牌付费，即使它们被折叠或编辑。

225

212### 扩展上下文226### 扩展上下文

213 227

214Opus 4.7、Opus 4.6 和 Sonnet 4.6 支持[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于包含大型代码库的长会话。228Opus 4.7、Opus 4.6 和 Sonnet 4.6 支持[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/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-CN/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-CN/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-CN/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 +16 −5

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-CN/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分布式跟踪导出 span，将每个用户提示链接到它触发的 API 请求和工具执行，因此您可以在跟踪后端中将完整请求视为单个 trace。119分布式跟踪导出 span，将每个用户提示链接到它触发的 API 请求和工具执行，因此您可以在跟踪后端中将完整请求视为单个 trace。

109 120

110跟踪默认关闭。要启用它，请同时设置 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然后设置 `OTEL_TRACES_EXPORTER` 以选择 span 的发送位置。Traces 重用 [常见 OTLP 配置](#common-configuration-variables) 用于端点、协议和标头。121跟踪默认关闭。要启用它，请同时设置 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然后设置 `OTEL_TRACES_EXPORTER` 以选择 span 的发送位置。Traces 重用 [常见 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

410 421

411#### 拉取请求计数器422#### 拉取请求计数器

412 423

413通过 Claude Code 创建拉取请求时递增。424通过 Claude Code 创建拉取请求或合并请求时递增。

414 425

415**属性**：426**属性**：

416 427

output-styles.md +12 −3

Details

6 6

7> 将 Claude Code 适配用于软件工程之外的用途7> 将 Claude Code 适配用于软件工程之外的用途

8 8

~~9输出样式允许你将 Claude Code 用作任何类型的代理，同时保留其核心功能，例如运行本地脚本、读取/写入文件和跟踪 TODO。~~9输出样式改变 Claude 的响应方式，而不是 Claude 知道什么。它们修改系统提示以设置角色、语气和输出格式，同时保留核心功能，如运行脚本、读取和写入文件以及跟踪 TODO。当你在每个回合中不断重新提示相同的语音或格式时，或者当你希望 Claude 充当软件工程师以外的角色时，请使用一个。

11有关你的项目、约定或代码库的说明，请改用 [CLAUDE.md](/zh-CN/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-CN/settings#settings-files)内的 `.claude/output-styles`

74[Plugins](/zh-CN/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 上的插件（例如 CI 构建工件），请改用 `--plugin-url`。Claude Code 在启动时获取存档并仅为该会话加载它。如果获取失败或存档无效，Claude Code 会报告插件加载错误并在没有它的情况下启动。与任何插件源相同的[信任考虑](/zh-CN/discover-plugins#security)适用：仅将此标志指向你控制或信任的存档。

319

320```bash theme={null}

321claude --plugin-url https://example.com/my-plugin.zip

322```

323

318### 调试插件问题324### 调试插件问题

319 325

320如果你的插件不按预期工作：326如果你的插件不按预期工作：

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-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-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 版本约束。请参阅[约束 plugin 依赖版本](/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |437| `dependencies` | array | 此 plugin 需要的其他 plugins，可选择带有 semver 版本约束。请参阅[约束 plugin 依赖版本](/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

436 438

439### 实验性组件

440

441`experimental` 键下的组件，`themes` 和 `monitors`，具有在稳定期间可能在版本之间更改的清单架构。您声明它们的位置是一个单独的迁移：顶级仍然有效，`claude plugin validate` 发出警告，未来的版本将需要 `experimental.*`。

442

437### 用户配置443### 用户配置

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`，自定义路径替换默认值。如果清单指定 `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`，自定义路径替换默认值。如果清单指定 `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* 通过市场，为将来的会话安装。615* 通过市场，为将来的会话安装。

610 616

611出于安全和验证目的，Claude Code 将\_市场\_ plugins 复制到用户的本地 **plugin 缓存**（`~/.claude/plugins/cache`），而不是就地使用它们。在开发引用外部文件的 plugins 时，理解此行为很重要。617出于安全和验证目的，Claude Code 将\_市场\_ plugins 复制到用户的本地 **plugin 缓存**（`~/.claude/plugins/cache`），而不是就地使用它们。在开发引用外部文件的 plugins 时，理解此行为很重要。

routines.md +70 −20

Details

14 14

15每个例程可以附加一个或多个触发器：15每个例程可以附加一个或多个触发器：

16 16

~~17* **Scheduled**：按照每小时、每晚或每周等定期节奏运行~~17* **Scheduled**：按照每小时、每晚或每周等定期节奏运行，或在特定的未来时间运行一次

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-CN/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-CN/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="选择环境">

76 * **Environment variables**：提供 Claude 可以使用的 API 密钥、令牌或其他机密76 * **Environment variables**：提供 Claude 可以使用的 API 密钥、令牌或其他机密

77 * **Setup script**：安装例程需要的依赖项和工具。结果是 [cached](/zh-CN/claude-code-on-the-web#environment-caching)，因此脚本不会在每个会话上重新运行77 * **Setup script**：安装例程需要的依赖项和工具。结果是 [cached](/zh-CN/claude-code-on-the-web#environment-caching)，因此脚本不会在每个会话上重新运行

78 78

~~79 提供了一个 **Default** 环境。要使用自定义环境，请在创建例程之前 [create one](/zh-CN/claude-code-on-the-web#the-cloud-environment)。~~79 提供了一个 **Default** 环境，具有 **Trusted** 网络访问，允许 [default set](/zh-CN/claude-code-on-the-web#default-allowed-domains) 的包注册表、云提供商 API、容器注册表和常见开发域，但阻止其他所有内容。如果您的例程需要到达您自己的服务或该列表之外的域，请在运行前编辑环境的 [network access](/zh-CN/claude-code-on-the-web#network-access)。要使用单独的环境，请先 [create one](/zh-CN/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-CN/mcp)。删除例程不需要的任何内容。Connectors 在每次运行期间让 Claude 可以访问外部服务，如 Slack、Linear 或 Google Drive。101 表单底部的 **Connectors** 和 **Permissions** 选项卡控制例程可以到达的内容。

102

103 在 Connectors 下，默认包括您所有连接的 [MCP connectors](/zh-CN/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-CN/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 是否来自 fork |

254 271

255每个过滤器将字段与运算符配对：equals、contains、starts with、is one of、is not one of 或 matches regex。272每个过滤器将字段与运算符配对：equals、contains、starts with、is one of、is not one of 或 matches regex。

256 273

259一些示例过滤器组合：276一些示例过滤器组合：

260 277

261* **Auth module review**：base branch `main`，head branch contains `auth-provider`。将任何涉及身份验证的 PR 发送给专注的审查者。278* **Auth module review**：base branch `main`，head branch contains `auth-provider`。将任何涉及身份验证的 PR 发送给专注的审查者。

262* **External contributor triage**：from fork is `true`。在人工查看之前，通过额外的安全和风格审查路由每个基于 fork 的 PR。

263* **Ready-for-review only**：is draft is `false`。跳过草稿，以便例程仅在 PR 准备好审查时运行。279* **Ready-for-review only**：is draft is `false`。跳过草稿，以便例程仅在 PR 准备好审查时运行。

264* **Label-gated backport**：labels include `needs-backport`。仅当维护者标记 PR 时才触发移植到另一个分支的例程。280* **Label-gated backport**：labels include `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-CN/claude-code-on-the-web#the-cloud-environment) 中运行，该环境控制网络访问、环境变量和设置脚本。例程在每次运行时继承环境的网络策略。

304 326

305每个例程在 [cloud environment](/zh-CN/claude-code-on-the-web#the-cloud-environment) 中运行，该环境控制网络访问、环境变量和设置脚本。在创建例程之前配置环境，以便让 Claude 访问 API、安装依赖项或限制网络范围。有关完整的设置指南，请参阅 [cloud environment](/zh-CN/claude-code-on-the-web#the-cloud-environment)。327**Default** 环境使用 **Trusted** 网络访问：[默认允许列表](/zh-CN/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-CN/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-CN/claude-code-on-the-web#network-access)。

306 354

307## 使用和限制355## 使用和限制

308 356

309Routines 以与交互式会话相同的方式消耗订阅使用量。除了标准订阅限制外，routines 还对每个账户每天可以启动多少次运行有上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您当前的消耗和剩余的每日例程运行次数。357Routines 以与交互式会话相同的方式消耗订阅使用量。除了标准订阅限制外，routines 还对每个账户每天可以启动多少次运行有上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您当前的消耗和剩余的每日 routine 运行次数。

358

359当 routine 达到每日上限或您的订阅使用限制时，启用了额外使用的组织可以继续在计量超额上运行 routines。没有额外使用，额外运行被拒绝，直到窗口重置。从 claude.ai 上的 **Settings > Billing** 启用额外使用。

310 360

311当例程达到每日上限或您的订阅使用限制时，启用了额外使用的组织可以继续在计量超额上运行例程。没有额外使用，额外运行被拒绝，直到窗口重置。从 claude.ai 上的 **Settings > Billing** 启用额外使用。361一次性运行不计入每日 routine 运行上限。它们像任何其他会话一样消耗您的常规订阅使用量，但它们不受每个账户每日 routine 运行配额的限制。

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 设置）可能推送消息的频道插件的允许列表。设置后替换默认 Anthropic 允许列表。未定义 = 回退到默认值，空数组 = 阻止所有频道插件。需要 `channelsEnabled: true`。请参阅[限制哪些频道插件可以运行](/zh-CN/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |161| `allowedChannelPlugins` | （仅 Managed 设置）可能推送消息的频道插件的允许列表。设置后替换默认 Anthropic 允许列表。未定义 = 回退到默认值，空数组 = 阻止所有频道插件。需要 `channelsEnabled: true`。请参阅[限制哪些频道插件可以运行](/zh-CN/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` 中强制启用的插件中的 hooks。用户、项目和所有其他插件 hooks 被阻止。请参阅 [Hook 配置](#hook-configuration) | `true` |164| `allowManagedHooksOnly` | （仅 Managed 设置）仅加载 managed hooks、SDK hooks 和在 managed 设置 `enabledPlugins` 中强制启用的插件中的 hooks。用户、项目和所有其他插件 hooks 被阻止。请参阅 [Hook 配置](#hook-configuration) | `true` |

165| `allowManagedMcpServersOnly` | （仅 Managed 设置）仅尊重来自 managed 设置的 `allowedMcpServers`。`deniedMcpServers` 仍从所有源合并。用户仍可以添加 MCP servers，但仅应用管理员定义的允许列表。请参阅 [Managed MCP 配置](/zh-CN/mcp#managed-mcp-configuration) | `true` |165| `allowManagedMcpServersOnly` | （仅 Managed 设置）仅尊重来自 managed 设置的 `allowedMcpServers`。`deniedMcpServers` 仍从所有源合并。用户仍可以添加 MCP servers，但仅应用管理员定义的允许列表。请参阅 [Managed MCP 配置](/zh-CN/mcp#managed-mcp-configuration) | `true` |

166| `allowManagedPermissionRulesOnly` | （仅 Managed 设置）防止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用 managed 设置中的规则。请参阅 [Managed 专用设置](/zh-CN/permissions#managed-only-settings) | `true` |166| `allowManagedPermissionRulesOnly` | （仅 Managed 设置）防止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用 managed 设置中的规则。请参阅 [Managed 专用设置](/zh-CN/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-CN/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-CN/memory#storage-location)存储的自定义目录。接受绝对路径或 `~/` 前缀的路径。从策略和用户设置以及 `--settings` 标志接受。不从项目或本地设置接受，因为克隆的存储库可能提供任一文件以将内存写入重定向到敏感位置 | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | [自动内存](/zh-CN/memory#storage-location)存储的自定义目录。接受绝对路径或 `~/` 前缀的路径。从策略和用户设置以及 `--settings` 标志接受。不从项目或本地设置接受，因为克隆的存储库可能提供任一文件以将内存写入重定向到敏感位置 | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | 启用[自动内存](/zh-CN/memory#enable-or-disable-auto-memory)。当为 `false` 时，Claude 不从自动内存目录读取或写入。默认：`true`。您也可以在会话期间使用 `/memory` 切换此选项 | `false` |171| `autoMemoryEnabled` | 启用[自动内存](/zh-CN/memory#enable-or-disable-auto-memory)。当为 `false` 时，Claude 不从自动内存目录读取或写入。默认：`true`。您也可以在会话期间使用 `/memory` 切换此选项。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/zh-CN/env-vars) | `false` |

172| `autoMode` | 自定义[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容。包含 `environment`、`allow` 和 `soft_deny` 散文规则数组。在数组中包含字面字符串 `"$defaults"` 以在该位置继承内置规则。请参阅[配置自动模式](/zh-CN/auto-mode-config)。不从共享项目设置读取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | 自定义[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容。包含 `environment`、`allow` 和 `soft_deny` 散文规则数组。在数组中包含字面字符串 `"$defaults"` 以在该位置继承内置规则。请参阅[配置自动模式](/zh-CN/auto-mode-config)。不从共享项目设置读取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

175| `availableModels` | 限制用户可以通过 `/model`、`--model` 或 `ANTHROPIC_MODEL` 选择的模型。不影响默认选项。请参阅[限制模型选择](/zh-CN/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |175| `availableModels` | 限制用户可以通过 `/model`、`--model` 或 `ANTHROPIC_MODEL` 选择的模型。不影响默认选项。请参阅[限制模型选择](/zh-CN/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |

179| `blockedMarketplaces` | （仅 Managed 设置）市场源的阻止列表。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | （仅 Managed 设置）市场源的阻止列表。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

180| `channelsEnabled` | （仅 Managed 设置）为组织允许 [channels](/zh-CN/channels)。在 claude.ai Team 和 Enterprise 计划上，当此项未设置或为 `false` 时，channels 被阻止。对于使用 API 密钥身份验证的 [Anthropic Console](/zh-CN/authentication#claude-console-authentication) 账户，channels 默认被允许，除非您的组织部署 managed 设置，在这种情况下此键必须设置为 `true` | `true` |180| `channelsEnabled` | （仅 Managed 设置）为组织允许 [channels](/zh-CN/channels)。在 claude.ai Team 和 Enterprise 计划上，当此项未设置或为 `false` 时，channels 被阻止。对于使用 API 密钥身份验证的 [Anthropic Console](/zh-CN/authentication#claude-console-authentication) 账户，channels 默认被允许，除非您的组织部署 managed 设置，在这种情况下此键必须设置为 `true` | `true` |

181| `claudeMdExcludes` | 加载[内存](/zh-CN/memory)时要跳过的 `CLAUDE.md` 文件的 Glob 模式或绝对路径。模式与绝对文件路径匹配。仅适用于用户、项目和本地内存；managed 策略文件无法被排除 | `["**/vendor/**/CLAUDE.md"]` |

181| `cleanupPeriodDays` | 非活跃时间超过此期间的会话在启动时被删除（默认：30 天，最少 1 天）。设置为 `0` 会被拒绝并显示验证错误。也控制[孤立 subagent worktrees](/zh-CN/worktrees#clean-up-worktrees) 在启动时自动删除的年龄截止。要完全禁用记录写入，请设置 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量，或在非交互模式（`-p`）中使用 `--no-session-persistence` 标志或 `persistSession: false` SDK 选项。 | `20` |182| `cleanupPeriodDays` | 非活跃时间超过此期间的会话在启动时被删除（默认：30 天，最少 1 天）。设置为 `0` 会被拒绝并显示验证错误。也控制[孤立 subagent worktrees](/zh-CN/worktrees#clean-up-worktrees) 在启动时自动删除的年龄截止。要完全禁用记录写入，请设置 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/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-CN/tools-reference#powershell-tool) | `"powershell"` |184| `defaultShell` | 输入框 `!` 命令的默认 shell。接受 `"bash"`（默认）或 `"powershell"`。设置 `"powershell"` 会在 Windows 上通过 PowerShell 路由交互式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。请参阅 [PowerShell tool](/zh-CN/tools-reference#powershell-tool) | `"powershell"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}禁用[远程控制](/zh-CN/remote-control)：阻止 `claude remote-control`、`--remote-control` 标志、自动启动和会话内切换。通常放在[managed 设置](/zh-CN/permissions#managed-settings)中用于每设备 MDM 强制执行，但适用于任何作用域。需要 Claude Code v2.1.128 或更高版本 | `true` |190| `disableRemoteControl` | {/* min-version: 2.1.128 */}禁用[远程控制](/zh-CN/remote-control)：阻止 `claude remote-control`、`--remote-control` 标志、自动启动和会话内切换。通常放在[managed 设置](/zh-CN/permissions#managed-settings)中用于每设备 MDM 强制执行，但适用于任何作用域。需要 Claude Code v2.1.128 或更高版本 | `true` |

190| `disableSkillShellExecution` | 禁用 [skills](/zh-CN/skills) 和来自用户、项目、插件或额外目录源的自定义命令中的 `` !`...` `` 和 ` ```! ` 块的内联 shell 执行。命令被替换为 `[shell command execution disabled by policy]` 而不是被运行。捆绑和 managed skills 不受影响。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `true` |191| `disableSkillShellExecution` | 禁用 [skills](/zh-CN/skills) 和来自用户、项目、插件或额外目录源的自定义命令中的 `` !`...` `` 和 ` ```! ` 块的内联 shell 执行。命令被替换为 `[shell command execution disabled by policy]` 而不是被运行。捆绑和 managed skills 不受影响。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `true` |

191| `editorMode` | 输入提示的快捷键模式：`"normal"` 或 `"vim"`。默认：`"normal"`。在 `/config` 中显示为**快捷键模式** | `"vim"` |192| `editorMode` | 输入提示的快捷键模式：`"normal"` 或 `"vim"`。默认：`"normal"`。在 `/config` 中显示为**快捷键模式** | `"vim"` |

192| `effortLevel` | 跨会话持久化[努力级别](/zh-CN/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。当您运行 `/effort` 时自动写入，带有这些值之一。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)了解支持的模型 | `"xhigh"` |193| `effortLevel` | 跨会话持久化[努力级别](/zh-CN/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。当您运行 `/effort` 时自动写入，带有这些值之一。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/zh-CN/env-vars) 覆盖此用于一个会话。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)了解支持的模型 | `"xhigh"` |

195| `env` | 将应用于每个会话的环境变量 | `{"FOO": "bar"}` |196| `env` | 将应用于每个会话的环境变量 | `{"FOO": "bar"}` |

196| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/zh-CN/fast-mode#require-per-session-opt-in) | `true` |197| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/zh-CN/fast-mode#require-per-session-opt-in) | `true` |

197| `feedbackSurveyRate` | 概率（0–1）[会话质量调查](/zh-CN/data-usage#session-quality-surveys)在符合条件时出现。设置为 `0` 以完全抑制。在使用 Bedrock、Vertex 或 Foundry 时很有用，其中默认采样率不适用 | `0.05` |198| `feedbackSurveyRate` | 概率（0–1）[会话质量调查](/zh-CN/data-usage#session-quality-surveys)在符合条件时出现。设置为 `0` 以完全抑制，或在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-CN/env-vars)。在使用 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-CN/server-managed-settings#enforce-fail-closed-startup) | `true` |202| `forceRemoteSettingsRefresh` | （仅 Managed 设置）阻止 CLI 启动，直到从服务器新鲜获取远程 managed 设置。如果获取失败，CLI 退出而不是继续使用缓存或无设置。未设置时，启动继续而不等待远程设置。请参阅[失败关闭强制执行](/zh-CN/server-managed-settings#enforce-fail-closed-startup) | `true` |

203| `gcpAuthRefresh` | 当 GCP Application Default Credentials 过期或无法加载时刷新它们的自定义脚本。请参阅[高级凭证配置](/zh-CN/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-CN/voice-dictation#change-the-dictation-language)语言 | `"japanese"` |208| `language` | 配置 Claude 的首选响应语言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 将默认以此语言响应。也设置[语音听写](/zh-CN/voice-dictation#change-the-dictation-language)语言 | `"japanese"` |

207| `minimumVersion` | 防止后台自动更新和 `claude update` 安装低于此版本的版本。从 `"latest"` 渠道切换到 `"stable"` 时通过 `/config` 提示您保持在当前版本或允许降级。选择保持设置此值。也在[managed 设置](/zh-CN/permissions#managed-settings)中有用，以固定组织范围的最低版本 | `"2.1.100"` |209| `minimumVersion` | 防止后台自动更新和 `claude update` 安装低于此版本的版本。从 `"latest"` 渠道切换到 `"stable"` 时通过 `/config` 提示您保持在当前版本或允许降级。选择保持设置此值。也在[managed 设置](/zh-CN/permissions#managed-settings)中有用，以固定组织范围的最低版本 | `"2.1.100"` |

209| `modelOverrides` | 将 Anthropic 模型 ID 映射到特定于提供商的模型 ID，例如 Bedrock 推理配置文件 ARN。每个模型选择器条目在调用提供商 API 时使用其映射值。请参阅[按版本覆盖模型 ID](/zh-CN/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |211| `modelOverrides` | 将 Anthropic 模型 ID 映射到特定于提供商的模型 ID，例如 Bedrock 推理配置文件 ARN。每个模型选择器条目在调用提供商 API 时使用其映射值。请参阅[按版本覆盖模型 ID](/zh-CN/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

210| `otelHeadersHelper` | 生成动态 OpenTelemetry 标头的脚本。在启动时和定期运行（请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers)） | `/bin/generate_otel_headers.sh` |212| `otelHeadersHelper` | 生成动态 OpenTelemetry 标头的脚本。在启动时和定期运行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-CN/env-vars) 设置刷新间隔。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |

215| `preferredNotifChannel` | 任务完成和权限提示通知的方法：`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。默认：`"auto"`，在 iTerm2、Ghostty 和 Kitty 中发送桌面通知，在其他终端中不执行任何操作。设置 `"terminal_bell"` 以在任何终端中响铃。在 `/config` 中显示为**通知**。请参阅[获取终端铃声或通知](/zh-CN/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |217| `preferredNotifChannel` | 任务完成和权限提示通知的方法：`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。默认：`"auto"`，在 iTerm2、Ghostty 和 Kitty 中发送桌面通知，在其他终端中不执行任何操作。设置 `"terminal_bell"` 以在任何终端中响铃。在 `/config` 中显示为**通知**。请参阅[获取终端铃声或通知](/zh-CN/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |

217| `prUrlTemplate` | PR 徽章的 URL 模板，显示在页脚和工具结果摘要中。替换来自 `gh` 报告的 PR URL 中的 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。使用指向内部代码审查工具而不是 `github.com` 的 PR 链接。不影响 Claude 散文中的 `#123` 自动链接 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |219| `prUrlTemplate` | PR 徽章的 URL 模板，显示在页脚和工具结果摘要中。替换来自 `gh` 报告的 PR URL 中的 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。使用指向内部代码审查工具而不是 `github.com` 的 PR 链接。不影响 Claude 散文中的 `#123` 自动链接 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |

220| `showThinkingSummaries` | 在交互式会话中显示[扩展思考](/zh-CN/model-config#extended-thinking)摘要。未设置或 `false`（交互模式中的默认值）时，思考块由 API 编辑并显示为折叠的存根。编辑仅改变您看到的内容，而不是模型生成的内容：要减少思考支出，[降低预算或禁用思考](/zh-CN/model-config#extended-thinking)。非交互模式（`-p`）和 SDK 调用者无论此设置如何都始终接收摘要 | `true` |222| `showThinkingSummaries` | 在交互式会话中显示[扩展思考](/zh-CN/model-config#extended-thinking)摘要。未设置或 `false`（交互模式中的默认值）时，思考块由 API 编辑并显示为折叠的存根。编辑仅改变您看到的内容，而不是模型生成的内容：要减少思考支出，[降低预算或禁用思考](/zh-CN/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。不适用于插件 skills，这些通过 `/plugin` 管理。`/skills` 菜单将这些写入 `.claude/settings.local.json`。请参阅[从设置覆盖 skill 可见性](/zh-CN/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更高版本 | `{"legacy-context": "name-only", "deploy": "off"}` |

222| `skipWebFetchPreflight` | 跳过[WebFetch 域安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，该检查在获取前将每个请求的主机名发送到 `api.anthropic.com`。在阻止到 Anthropic 的流量的环境中设置为 `true`，例如 Bedrock、Vertex AI 或 Foundry 部署，具有限制性出站。跳过时，WebFetch 尝试任何 URL 而不咨询阻止列表 | `true` |225| `skipWebFetchPreflight` | 跳过[WebFetch 域安全检查](/zh-CN/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-CN/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-CN/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-CN/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |230| `statusLine` | 配置自定义状态行以显示上下文。请参阅[`statusLine` 文档](/zh-CN/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

228| `strictKnownMarketplaces` | （仅 Managed 设置）插件市场源的允许列表。未定义 = 无限制，空数组 = 锁定。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |231| `strictKnownMarketplaces` | （仅 Managed 设置）插件市场源的允许列表。未定义 = 无限制，空数组 = 锁定。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

233| `teammateMode` | [agent team](/zh-CN/agent-teams) 队友的显示方式：`auto`（在 tmux 或 iTerm2 中选择分割窗格，否则进程内）、`in-process` 或 `tmux`。`--teammate-mode` 覆盖此用于一个会话。请参阅[选择显示模式](/zh-CN/agent-teams#choose-a-display-mode) | `"in-process"` |

231| `tui` | 终端 UI 渲染器。使用 `"fullscreen"` 获取无闪烁的[替代屏幕渲染器](/zh-CN/fullscreen)，具有虚拟化滚动条。使用 `"default"` 获取经典主屏幕渲染器。通过 `/tui` 设置 | `"fullscreen"` |235| `tui` | 终端 UI 渲染器。使用 `"fullscreen"` 获取无闪烁的[替代屏幕渲染器](/zh-CN/fullscreen)，具有虚拟化滚动条。使用 `"default"` 获取经典主屏幕渲染器。通过 `/tui` 设置。您也可以设置 [`CLAUDE_CODE_NO_FLICKER`](/zh-CN/env-vars) 环境变量 | `"fullscreen"` |

234| `voice` | [语音听写](/zh-CN/voice-dictation)设置：`enabled` 打开听写，`mode` 选择 `"hold"` 或 `"tap"`，`autoSubmit` 在保持模式下按键释放时发送提示。当您运行 `/voice` 时自动写入。需要 Claude.ai 账户 | `{ "enabled": true, "mode": "tap" }` |238| `voice` | [语音听写](/zh-CN/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` |

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 层内，优先级为：server-managed > MDM/OS 级别策略 > 基于文件（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 注册表（仅 Windows）。仅使用一个 managed 源；源不合并跨层。在基于文件的层内，放入文件和基础文件被合并在一起。476 * 在 managed 层内，优先级为：server-managed > MDM/OS 级别策略 > 基于文件（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 注册表（仅 Windows）。仅使用一个 managed 源；源不合并跨层。在基于文件的层内，放入文件和基础文件被合并在一起。

473 477

4742. **命令行参数**4782. **命令行参数**

475 * 特定会话的临时覆盖479 * 特定会话的临时覆盖。通过 `--settings <file-or-json>` 传递的 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-CN/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-CN/troubleshoot-install#check-for-conflicting-installations)以查找并删除它。

493 497

494### 原生安装498### 原生安装

495 499

skills.md +58 −27

Details

8 8

9Skills 扩展了 Claude 能做的事情。创建一个 `SKILL.md` 文件，其中包含说明，Claude 会将其添加到其工具包中。Claude 在相关时使用 skills，或者你可以使用 `/skill-name` 直接调用一个。9Skills 扩展了 Claude 能做的事情。创建一个 `SKILL.md` 文件，其中包含说明，Claude 会将其添加到其工具包中。Claude 在相关时使用 skills，或者你可以使用 `/skill-name` 直接调用一个。

10 10

11当你不断将相同的剧本、检查清单或多步骤程序粘贴到聊天中时，或者当 CLAUDE.md 的一部分已经演变成程序而不是事实时，创建一个 skill。与 CLAUDE.md 内容不同，skill 的正文仅在使用时加载，因此长参考资料在你需要它之前几乎不花费任何成本。11当你不断将相同的说明、检查清单或多步骤程序粘贴到聊天中时，或者当 CLAUDE.md 的一部分已经演变成程序而不是事实时，创建一个 skill。与 CLAUDE.md 内容不同，skill 的正文仅在使用时加载，因此长参考资料在你需要它之前几乎不花费任何成本。

12 12

13<Note>13<Note>

14 对于内置命令（如 `/help` 和 `/compact`）以及捆绑 skills（如 `/debug` 和 `/simplify`），请参阅[命令参考](/zh-CN/commands)。14 对于内置命令（如 `/help` 和 `/compact`）以及捆绑 skills（如 `/debug` 和 `/simplify`），请参阅[命令参考](/zh-CN/commands)。

20 20

21## 捆绑 skills21## 捆绑 skills

22 22

23Claude Code 包括一组捆绑 skills，在每个会话中都可用，包括 `/simplify`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。与大多数内置命令不同，内置命令直接执行固定逻辑，捆绑 skills 是基于提示的：它们为 Claude 提供详细的剧本，让它使用其工具来编排工作。你调用捆绑 skills 的方式与调用任何其他 skill 相同，输入 `/` 后跟 skill 名称。23Claude Code 包括一组捆绑 skills，在每个会话中都可用，包括 `/simplify`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。与大多数内置命令不同，内置命令直接执行固定逻辑，捆绑 skills 是基于提示的：它们为 Claude 提供详细的说明，让它使用其工具来编排工作。你调用捆绑 skills 的方式与调用任何其他 skill 相同，输入 `/` 后跟 skill 名称。

24 24

25捆绑 skills 在[命令参考](/zh-CN/commands)中与内置命令一起列出，在"目的"列中标记为 **Skill**。25捆绑 skills 在[命令参考](/zh-CN/commands)中与内置命令一起列出，在"目的"列中标记为 **Skill**。

26 26

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-CN/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 行为：

416要禁用来自用户、项目、插件或[其他目录](#skills-from-additional-directories)源的 skills 和自定义命令的此行为，请在[设置](/zh-CN/settings)中设置 `"disableSkillShellExecution": true`。每个命令都被替换为 `[shell command execution disabled by policy]` 而不是被运行。捆绑和托管 skills 不受影响。此设置在[托管设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它。419要禁用来自用户、项目、插件或[其他目录](#skills-from-additional-directories)源的 skills 和自定义命令的此行为，请在[设置](/zh-CN/settings)中设置 `"disableSkillShellExecution": true`。每个命令都被替换为 `[shell command execution disabled by policy]` 而不是被运行。捆绑和托管 skills 不受影响。此设置在[托管设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它。

417 420

418<Tip>421<Tip>

419 要在 skill 中启用[扩展思考](/zh-CN/common-workflows#use-extended-thinking-thinking-mode)，在你的 skill 内容中的任何地方包含单词"ultrathink"。422 要在 skill 运行时请求更深入的推理，在 skill 内容中的任何地方包含 `ultrathink`。请参阅[使用 ultrathink 进行一次性深度推理](/zh-CN/model-config#use-ultrathink-for-one-off-deep-reasoning)。

420</Tip>423</Tip>

421 424

422### 在 subagent 中运行 skills425### 在 subagent 中运行 skills

496 `user-invocable` 字段仅控制菜单可见性，不控制 Skill 工具访问。使用 `disable-model-invocation: true` 来阻止程序调用。499 `user-invocable` 字段仅控制菜单可见性，不控制 Skill 工具访问。使用 `disable-model-invocation: true` 来阻止程序调用。

497</Note>500</Note>

498 501

502### 从设置覆盖 skill 可见性

503

504`skillOverrides` 设置从你的[设置](/zh-CN/settings)控制 skill 可见性，而不是从 skill 自己的 frontmatter。将其用于你不想编辑 SKILL.md 的 skills，例如检入共享项目仓库或由 MCP 服务器提供的 skills。`/skills` 菜单为你编写它：突出显示一个 skill 并按 `Space` 循环切换状态，然后按 `Enter` 保存到 `.claude/settings.local.json`。

505

506每个键是一个 skill 名称，每个值是以下四种状态之一：

507

508| 值 | 列出给 Claude | 在 `/` 菜单中 |

509| :---------------------- | :--------- | :-------- |

510| `"on"` | 名称和描述 | 是 |

511| `"name-only"` | 仅名称 | 是 |

512| `"user-invocable-only"` | 隐藏 | 是 |

513| `"off"` | 隐藏 | 隐藏 |

514

515`skillOverrides` 中不存在的 skill 被视为 `"on"`。下面的示例将一个 skill 折叠为其名称，并完全关闭另一个：

516

517```json theme={null}

518{

519 "skillOverrides": {

520 "legacy-context": "name-only",

521 "deploy": "off"

522 }

523}

524```

525

526插件 skills 不受 `skillOverrides` 影响。通过 `/plugin` 管理这些。

527

499## 共享 skills528## 共享 skills

500 529

501Skills 可以根据你的受众在不同范围内分发：530Skills 可以根据你的受众在不同范围内分发：

516mkdir -p ~/.claude/skills/codebase-visualizer/scripts545mkdir -p ~/.claude/skills/codebase-visualizer/scripts

517```546```

518 547

519创建 `~/.claude/skills/codebase-visualizer/SKILL.md`。描述告诉 Claude 何时激活此 Skill，说明告诉 Claude 运行捆绑的脚本：548保存到 `~/.claude/skills/codebase-visualizer/SKILL.md`。描述告诉 Claude 何时激活此 Skill，说明告诉 Claude 运行捆绑的脚本。脚本路径使用 [`${CLAUDE_SKILL_DIR}`](#available-string-substitutions)，因此无论 skill 是在个人、项目还是插件级别安装，它都能正确解析：

520 549

521````yaml theme={null}550````yaml theme={null}

522---551---

523name: codebase-visualizer552name: 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.553description: 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 *)554allowed-tools: Bash(python3 *)

526---555---

527 556

528# Codebase Visualizer557# Codebase Visualizer

534Run the visualization script from your project root:563Run the visualization script from your project root:

535 564

536```bash565```bash

537python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .566python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

538```567```

539 568

540This creates `codebase-map.html` in the current directory and opens it in your default browser.569This creates `codebase-map.html` in the current directory and opens it in your default browser.

547- **Directory totals**: Shows aggregate size of each folder576- **Directory totals**: Shows aggregate size of each folder

548````577````

549 578

550创建 `~/.claude/skills/codebase-visualizer/scripts/visualize.py`。此脚本扫描目录树并生成一个自包含的 HTML 文件，包含：579保存到 `~/.claude/skills/codebase-visualizer/scripts/visualize.py`。此脚本扫描目录树并生成一个自包含的 HTML 文件，包含：

551 580

552* 一个**摘要侧边栏**，显示文件计数、目录计数、总大小和文件类型数量581* 一个**摘要侧边栏**，显示文件计数、目录计数、总大小和文件类型数量

553* 一个**条形图**，按文件类型（按大小排名前 8）分解代码库582* 一个**条形图**，按文件类型（按大小排名前 8）分解代码库

554* 一个**可折叠树**，你可以在其中展开和折叠目录，带有颜色编码的文件类型指示器583* 一个**可折叠树**，你可以在其中展开和折叠目录，带有颜色编码的文件类型指示器

555 584

556该脚本需要 Python，但仅使用内置库，因此无需安装包：585该脚本需要 Python 3，但仅使用内置库，因此无需安装包：

557 586

558```python expandable theme={null}587```python expandable theme={null}

559#!/usr/bin/env python3588#!/usr/bin/env python3

562import json591import json

563import sys592import sys

564import webbrowser593import webbrowser

594from html import escape

565from pathlib import Path595from pathlib import Path

566from collections import Counter596from collections import Counter

567 597

650 {lang_bars}680 {lang_bars}

651 </div>681 </div>

652 <div class="main">682 <div class="main">

653 <h1>📁 {data["name"]}</h1>683 <h1>📁 {escape(data["name"])}</h1>

654 <ul class="tree" id="root"></ul>684 <ul class="tree" id="root"></ul>

655 </div>685 </div>

656 </div>686 </div>

658 const data = {json.dumps(data)};688 const data = {json.dumps(data)};

659 const colors = {json.dumps(colors)};689 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'; }}690 function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}

691 function esc(s) {{ return s.replace(/[&<>"']/g, c => ({{"&":"&","<":"<",">":">",'"':""","'":"'"}}[c])); }}

661 function render(node, parent) {{692 function render(node, parent) {{

662 if (node.children) {{693 if (node.children) {{

663 const det = document.createElement('details');694 const det = document.createElement('details');

664 det.open = parent === document.getElementById('root');695 det.open = parent === document.getElementById('root');

665 det.innerHTML = `<summary><span class="folder">📁 ${{node.name}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;696 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';697 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));698 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));699 node.children.forEach(c => render(c, ul));

670 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);701 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);

671 }} else {{702 }} else {{

672 const li = document.createElement('li'); li.className = 'file';703 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>`;704 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);705 parent.appendChild(li);

675 }}706 }}

676 }}707 }}

715 746

716Skill 描述被加载到上下文中，以便 Claude 知道什么可用。所有 skill 名称始终包括，但如果你有许多 skills，描述会被缩短以适应字符预算，这可能会删除 Claude 需要匹配你的请求的关键字。预算在上下文窗口的 1% 处动态扩展，回退为 8,000 个字符。747Skill 描述被加载到上下文中，以便 Claude 知道什么可用。所有 skill 名称始终包括，但如果你有许多 skills，描述会被缩短以适应字符预算，这可能会删除 Claude 需要匹配你的请求的关键字。预算在上下文窗口的 1% 处动态扩展，回退为 8,000 个字符。

717 748

718要提高限制，设置 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量。或在源处修剪 `description` 和 `when_to_use` 文本：前置关键用例，因为每个条目的组合文本被限制为 1,536 个字符，无论预算如何。749要提高限制，设置 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量。要为其他 skills 释放预算，在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将低优先级条目设置为 `"name-only"`，以便它们列出而不显示描述。你也可以在源处修剪 `description` 和 `when_to_use` 文本：前置关键用例，因为每个条目的组合文本被限制为 1,536 个字符，无论预算如何。

719 750

720## 相关资源751## 相关资源

721 752

statusline.md +13 −14

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

141**你的脚本可以输出什么**141**你的脚本可以输出什么**

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

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 调用重新填充它为止为 `null`

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### 上下文窗口字段281### 上下文窗口字段

282 282

283`context_window` 对象提供了两种跟踪上下文使用情况的方式：283`context_window` 对象描述来自最近一次 API 响应的实时上下文窗口。从 v2.1.132 开始，`total_input_tokens` 和 `total_output_tokens` 反映当前上下文使用情况，而不是累积的会话总计。

284 284

285* **累积总计**（`total_input_tokens`, `total_output_tokens`）：整个会话中所有令牌的总和，用于跟踪总消耗285* **合并总计**（`total_input_tokens`, `total_output_tokens`）：当前在上下文窗口中的令牌。`total_input_tokens` 是 `input_tokens`、`cache_creation_input_tokens` 和 `cache_read_input_tokens` 的总和；`total_output_tokens` 是最近一次响应中的输出令牌。在第一次 API 响应之前，两者都是 `0`。

286* **当前使用情况**（`current_usage`）：来自最近一次 API 调用的令牌计数，使用此来获得准确的上下文百分比，因为它反映了实际的上下文状态286* **按组件使用情况**（`current_usage`）：相同的令牌计数按类别分解。当你需要将缓存命中与新输入分开时，使用此选项。

287 287

288`current_usage` 对象包含：288`current_usage` 对象包含：

289 289

296 296

297如果你从 `current_usage` 手动计算上下文百分比，使用相同的仅输入公式来匹配 `used_percentage`。297如果你从 `current_usage` 手动计算上下文百分比，使用相同的仅输入公式来匹配 `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**上下文百分比显示意外值**1012**上下文百分比显示意外值**

1013 1013

1014* 使用 `used_percentage` 获得准确的上下文状态，而不是累积总计1014* 使用 `used_percentage` 获得最简单的准确上下文状态

1015* `total_input_tokens` 和 `total_output_tokens` 在整个会话中是累积的，可能超过上下文窗口大小

1016* 上下文百分比可能与 `/context` 输出不同，因为每个的计算时间不同1015* 上下文百分比可能与 `/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-CN/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-CN/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