Documentation 2026-05-08 22:00 UTC to 2026-05-09 04:57 UTC

309 </Tab>309 </Tab>

310</Tabs>310</Tabs>

311 311 

312对于 HTTP（非流式），请改用 `"type": "http"`。312对于可流式传输的 HTTP 传输，请改用 `"type": "http"`。在 `.mcp.json` 和其他 JSON 配置文件中，`"streamable-http"` 被接受作为 `"http"` 的别名。编程式 `mcpServers` 选项仅接受 `"http"`。

313 313 

314### SDK MCP 服务器314### SDK MCP 服务器

315 315 

2294 2294 

2295```python theme={null}2295```python theme={null}

2296{2296{

2297 "description": str, # A short (3-5 word) description of the task2297 "description": str, # 任务的简短描述（3-5 个单词）

2298 "prompt": str, # The task for the agent to perform2298 "prompt": str, # 代理要执行的任务

2299 "subagent_type": str, # The type of specialized agent to use2299 "subagent_type": str, # 要使用的专门代理的类型

2300}2300}

2301```2301```

2302 2302 

2304 2304 

2305```python theme={null}2305```python theme={null}

2306{2306{

2307 "result": str, # Final result from the subagent2307 "result": str, # 来自子代理的最终结果

2308 "usage": dict | None, # Token usage statistics2308 "usage": dict | None, # 令牌使用统计

2309 "total_cost_usd": float | None, # Estimated total cost in USD2309 "total_cost_usd": float | None, # 以美元计的估计总成本

2310 "duration_ms": int | None, # Execution duration in milliseconds2310 "duration_ms": int | None, # 执行持续时间（毫秒）

2311}2311}

2312```2312```

2313 2313 

2321 2321 

2322```python theme={null}2322```python theme={null}

2323{2323{

2324 "questions": [ # Questions to ask the user (1-4 questions)2324 "questions": [ # 要向用户提出的问题（1-4 个问题）

2325 {2325 {

2326 "question": str, # The complete question to ask the user2326 "question": str, # 要向用户提出的完整问题

2327 "header": str, # Very short label displayed as a chip/tag (max 12 chars)2327 "header": str, # 显示为芯片/标签的非常简短的标签（最多 12 个字符）

2328 "options": [ # The available choices (2-4 options)2328 "options": [ # 可用的选择（2-4 个选项）

2329 {2329 {

2330 "label": str, # Display text for this option (1-5 words)2330 "label": str, # 此选项的显示文本（1-5 个单词）

2331 "description": str, # Explanation of what this option means2331 "description": str, # 此选项含义的说明

2332 }2332 }

2333 ],2333 ],

2334 "multiSelect": bool, # Set to true to allow multiple selections2334 "multiSelect": bool, # 设置为 true 以允许多个选择

2335 }2335 }

2336 ],2336 ],

2337 "answers": dict | None, # User answers populated by the permission system2337 "answers": dict[str, str | list[str]] | None,

2338 # 由权限系统填充的用户答案。多选

2339 # 答案可能是标签列表或逗号连接的字符串

2338}2340}

2339```2341```

2340 2342 

2342 2344 

2343```python theme={null}2345```python theme={null}

2344{2346{

2345 "questions": [ # The questions that were asked2347 "questions": [ # 被提出的问题

2346 {2348 {

2347 "question": str,2349 "question": str,

2348 "header": str,2350 "header": str,

2350 "multiSelect": bool,2352 "multiSelect": bool,

2351 }2353 }

2352 ],2354 ],

2353 "answers": dict[str, str], # Maps question text to answer string2355 "answers": dict[str, str], # 将问题文本映射到答案字符串

2354 # Multi-select answers are comma-separated2356 # 多选答案以逗号分隔

2355}2357}

2356```2358```

2357 2359 

2363 2365 

2364```python theme={null}2366```python theme={null}

2365{2367{

2366 "command": str, # The command to execute2368 "command": str, # 要执行的命令

2367 "timeout": int | None, # Optional timeout in milliseconds (max 600000)2369 "timeout": int | None, # 可选的超时时间（毫秒）（最大 600000）

2368 "description": str | None, # Clear, concise description (5-10 words)2370 "description": str | None, # 清晰、简洁的描述（5-10 个单词）

2369 "run_in_background": bool | None, # Set to true to run in background2371 "run_in_background": bool | None, # 设置为 true 以在后台运行

2370}2372}

2371```2373```

2372 2374 

2374 2376 

2375```python theme={null}2377```python theme={null}

2376{2378{

2377 "output": str, # Combined stdout and stderr output2379 "output": str, # 合并的 stdout 和 stderr 输出

2378 "exitCode": int, # Exit code of the command2380 "exitCode": int, # 命令的退出代码

2379 "killed": bool | None, # Whether command was killed due to timeout2381 "killed": bool | None, # 命令是否因超时而被杀死

2380 "shellId": str | None, # Shell ID for background processes2382 "shellId": str | None, # 后台进程的 Shell ID

2381}2383}

2382```2384```

2383 2385 

2391 2393 

2392```python theme={null}2394```python theme={null}

2393{2395{

2394 "command": str, # Shell script; each stdout line is an event, exit ends the watch2396 "command": str, # Shell 脚本；每个 stdout 行是一个事件，退出结束监视

2395 "description": str, # Short description shown in notifications2397 "description": str, # 在通知中显示的简短描述

2396 "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000)2398 "timeout_ms": int | None, # 在此截止时间后杀死（默认 300000，最大 3600000）

2397 "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop2399 "persistent": bool | None, # 在会话的生命周期内运行；使用 TaskStop 停止

2398}2400}

2399```2401```

2400 2402 

2402 2404 

2403```python theme={null}2405```python theme={null}

2404{2406{

2405 "taskId": str, # ID of the background monitor task2407 "taskId": str, # 后台监视任务的 ID

2406 "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent)2408 "timeoutMs": int, # 超时截止时间（毫秒）（持久时为 0）

2407 "persistent": bool | None, # True when running until TaskStop or session end2409 "persistent": bool | None, # 当运行到 TaskStop 或会话结束时为 True

2408}2410}

2409```2411```

2410 2412 

2416 2418 

2417```python theme={null}2419```python theme={null}

2418{2420{

2419 "file_path": str, # The absolute path to the file to modify2421 "file_path": str, # 要修改的文件的绝对路径

2420 "old_string": str, # The text to replace2422 "old_string": str, # 要替换的文本

2421 "new_string": str, # The text to replace it with2423 "new_string": str, # 替换为的文本

2422 "replace_all": bool | None, # Replace all occurrences (default False)2424 "replace_all": bool | None, # 替换所有出现（默认 False）

2423}2425}

2424```2426```

2425 2427 

2427 2429 

2428```python theme={null}2430```python theme={null}

2429{2431{

2430 "message": str, # Confirmation message2432 "message": str, # 确认消息

2431 "replacements": int, # Number of replacements made2433 "replacements": int, # 进行的替换次数

2432 "file_path": str, # File path that was edited2434 "file_path": str, # 被编辑的文件路径

2433}2435}

2434```2436```

2435 2437 

2441 2443 

2442```python theme={null}2444```python theme={null}

2443{2445{

2444 "file_path": str, # The absolute path to the file to read2446 "file_path": str, # 要读取的文件的绝对路径

2445 "offset": int | None, # The line number to start reading from2447 "offset": int | None, # 开始读取的行号

2446 "limit": int | None, # The number of lines to read2448 "limit": int | None, # 要读取的行数

2447}2449}

2448```2450```

2449 2451 

2451 2453 

2452```python theme={null}2454```python theme={null}

2453{2455{

2454 "content": str, # File contents with line numbers2456 "content": str, # 带行号的文件内容

2455 "total_lines": int, # Total number of lines in file2457 "total_lines": int, # 文件中的总行数

2456 "lines_returned": int, # Lines actually returned2458 "lines_returned": int, # 实际返回的行数

2457}2459}

2458```2460```

2459 2461 

2461 2463 

2462```python theme={null}2464```python theme={null}

2463{2465{

2464 "image": str, # Base64 encoded image data2466 "image": str, # Base64 编码的图像数据

2465 "mime_type": str, # Image MIME type2467 "mime_type": str, # 图像 MIME 类型

2466 "file_size": int, # File size in bytes2468 "file_size": int, # 文件大小（字节）

2467}2469}

2468```2470```

2469 2471 

2475 2477 

2476```python theme={null}2478```python theme={null}

2477{2479{

2478 "file_path": str, # The absolute path to the file to write2480 "file_path": str, # 要写入的文件的绝对路径

2479 "content": str, # The content to write to the file2481 "content": str, # 要写入文件的内容

2480}2482}

2481```2483```

2482 2484 

2484 2486 

2485```python theme={null}2487```python theme={null}

2486{2488{

2487 "message": str, # Success message2489 "message": str, # 成功消息

2488 "bytes_written": int, # Number of bytes written2490 "bytes_written": int, # 写入的字节数

2489 "file_path": str, # File path that was written2491 "file_path": str, # 被写入的文件路径

2490}2492}

2491```2493```

2492 2494 

2498 2500 

2499```python theme={null}2501```python theme={null}

2500{2502{

2501 "pattern": str, # The glob pattern to match files against2503 "pattern": str, # 用于匹配文件的 glob 模式

2502 "path": str | None, # The directory to search in (defaults to cwd)2504 "path": str | None, # 要搜索的目录（默认为 cwd）

2503}2505}

2504```2506```

2505 2507 

2507 2509 

2508```python theme={null}2510```python theme={null}

2509{2511{

2510 "matches": list[str], # Array of matching file paths2512 "matches": list[str], # 匹配的文件路径数组

2511 "count": int, # Number of matches found2513 "count": int, # 找到的匹配数

2512 "search_path": str, # Search directory used2514 "search_path": str, # 使用的搜索目录

2513}2515}

2514```2516```

2515 2517 

2521 2523 

2522```python theme={null}2524```python theme={null}

2523{2525{

2524 "pattern": str, # The regular expression pattern2526 "pattern": str, # 正则表达式模式

2525 "path": str | None, # File or directory to search in2527 "path": str | None, # 要搜索的文件或目录

2526 "glob": str | None, # Glob pattern to filter files2528 "glob": str | None, # 用于过滤文件的 glob 模式

2527 "type": str | None, # File type to search2529 "type": str | None, # 要搜索的文件类型

2528 "output_mode": str | None, # "content", "files_with_matches", or "count"2530 "output_mode": str | None, # "content"、"files_with_matches" 或 "count"

2529 "-i": bool | None, # Case insensitive search2531 "-i": bool | None, # 不区分大小写的搜索

2530 "-n": bool | None, # Show line numbers2532 "-n": bool | None, # 显示行号

2531 "-B": int | None, # Lines to show before each match2533 "-B": int | None, # 每个匹配前显示的行数

2532 "-A": int | None, # Lines to show after each match2534 "-A": int | None, # 每个匹配后显示的行数

2533 "-C": int | None, # Lines to show before and after2535 "-C": int | None, # 每个匹配前后显示的行数

2534 "head_limit": int | None, # Limit output to first N lines/entries2536 "head_limit": int | None, # 将输出限制为前 N 行/条目

2535 "multiline": bool | None, # Enable multiline mode2537 "multiline": bool | None, # 启用多行模式

2536}2538}

2537```2539```

2538 2540 

2557 2559 

2558```python theme={null}2560```python theme={null}

2559{2561{

2560 "files": list[str], # Files containing matches2562 "files": list[str], # 包含匹配的文件

2561 "count": int, # Number of files with matches2563 "count": int, # 包含匹配的文件数

2562}2564}

2563```2565```

2564 2566 

2570 2572 

2571```python theme={null}2573```python theme={null}

2572{2574{

2573 "notebook_path": str, # Absolute path to the Jupyter notebook2575 "notebook_path": str, # Jupyter 笔记本的绝对路径

2574 "cell_id": str | None, # The ID of the cell to edit2576 "cell_id": str | None, # 要编辑的单元格的 ID

2575 "new_source": str, # The new source for the cell2577 "new_source": str, # 单元格的新源代码

2576 "cell_type": "code" | "markdown" | None, # The type of the cell2578 "cell_type": "code" | "markdown" | None, # 单元格的类型

2577 "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type2579 "edit_mode": "replace" | "insert" | "delete" | None, # 编辑操作类型

2578}2580}

2579```2581```

2580 2582 

2582 2584 

2583```python theme={null}2585```python theme={null}

2584{2586{

2585 "message": str, # Success message2587 "message": str, # 成功消息

2586 "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed2588 "edit_type": "replaced" | "inserted" | "deleted", # 执行的编辑类型

2587 "cell_id": str | None, # Cell ID that was affected2589 "cell_id": str | None, # 受影响的单元格 ID

2588 "total_cells": int, # Total cells in notebook after edit2590 "total_cells": int, # 编辑后笔记本中的总单元格数

2589}2591}

2590```2592```

2591 2593 

2597 2599 

2598```python theme={null}2600```python theme={null}

2599{2601{

2600 "url": str, # The URL to fetch content from2602 "url": str, # 要从中获取内容的 URL

2601 "prompt": str, # The prompt to run on the fetched content2603 "prompt": str, # 在获取的内容上运行的提示

2602}2604}

2603```2605```

2604 2606 

2606 2608 

2607```python theme={null}2609```python theme={null}

2608{2610{

2609 "response": str, # AI model's response to the prompt2611 "response": str, # AI 模型对提示的响应

2610 "url": str, # URL that was fetched2612 "url": str, # 被获取的 URL

2611 "final_url": str | None, # Final URL after redirects2613 "final_url": str | None, # 重定向后的最终 URL

2612 "status_code": int | None, # HTTP status code2614 "status_code": int | None, # HTTP 状态代码

2613}2615}

2614```2616```

2615 2617 

2621 2623 

2622```python theme={null}2624```python theme={null}

2623{2625{

2624 "query": str, # The search query to use2626 "query": str, # 要使用的搜索查询

2625 "allowed_domains": list[str] | None, # Only include results from these domains2627 "allowed_domains": list[str] | None, # 仅包含来自这些域的结果

2626 "blocked_domains": list[str] | None, # Never include results from these domains2628 "blocked_domains": list[str] | None, # 永远不包含来自这些域的结果

2627}2629}

2628```2630```

2629 2631 

2647{2649{

2648 "todos": [2650 "todos": [

2649 {2651 {

2650 "content": str, # The task description2652 "content": str, # 任务描述

2651 "status": "pending" | "in_progress" | "completed", # Task status2653 "status": "pending" | "in_progress" | "completed", # 任务状态

2652 "activeForm": str, # Active form of the description2654 "activeForm": str, # 描述的活跃形式

2653 }2655 }

2654 ]2656 ]

2655}2657}

2659 2661 

2660```python theme={null}2662```python theme={null}

2661{2663{

2662 "message": str, # Success message2664 "message": str, # 成功消息

2663 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},2665 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},

2664}2666}

2665```2667```

2672 2674 

2673```python theme={null}2675```python theme={null}

2674{2676{

2675 "bash_id": str, # The ID of the background shell2677 "bash_id": str, # 后台 shell 的 ID

2676 "filter": str | None, # Optional regex to filter output lines2678 "filter": str | None, # 用于过滤输出行的可选正则表达式

2677}2679}

2678```2680```

2679 2681 

2681 2683 

2682```python theme={null}2684```python theme={null}

2683{2685{

2684 "output": str, # New output since last check2686 "output": str, # 自上次检查以来的新输出

2685 "status": "running" | "completed" | "failed", # Current shell status2687 "status": "running" | "completed" | "failed", # 当前 shell 状态

2686 "exitCode": int | None, # Exit code when completed2688 "exitCode": int | None, # 完成时的退出代码

2687}2689}

2688```2690```

2689 2691 

2695 2697 

2696```python theme={null}2698```python theme={null}

2697{2699{

2698 "shell_id": str # The ID of the background shell to kill2700 "shell_id": str # 要杀死的后台 shell 的 ID

2699}2701}

2700```2702```

2701 2703 

2703 2705 

2704```python theme={null}2706```python theme={null}

2705{2707{

2706 "message": str, # Success message2708 "message": str, # 成功消息

2707 "shell_id": str, # ID of the killed shell2709 "shell_id": str, # 被杀死的 shell 的 ID

2708}2710}

2709```2711```

2710 2712 

2716 2718 

2717```python theme={null}2719```python theme={null}

2718{2720{

2719 "plan": str # The plan to run by the user for approval2721 "plan": str # 用户要运行以获得批准的计划

2720}2722}

2721```2723```

2722 2724 

2724 2726 

2725```python theme={null}2727```python theme={null}

2726{2728{

2727 "message": str, # Confirmation message2729 "message": str, # 确认消息

2728 "approved": bool | None, # Whether user approved the plan2730 "approved": bool | None, # 用户是否批准了计划

2729}2731}

2730```2732```

2731 2733 

2737 2739 

2738```python theme={null}2740```python theme={null}

2739{2741{

2740 "server": str | None # Optional server name to filter resources by2742 "server": str | None # 可选的服务器名称以按其过滤资源

2741}2743}

2742```2744```

2743 2745 

2766 2768 

2767```python theme={null}2769```python theme={null}

2768{2770{

2769 "server": str, # The MCP server name2771 "server": str, # MCP 服务器名称

2770 "uri": str, # The resource URI to read2772 "uri": str, # 要读取的资源 URI

2771}2773}

2772```2774```

2773 2775 

308| `tag` | `string \| null` | 必需 | 标签字符串，或 `null` 以清除 |308| `tag` | `string \| null` | 必需 | 标签字符串，或 `null` 以清除 |

309| `options.dir` | `string` | `undefined` | 项目目录路径。省略时，搜索所有项目目录 |309| `options.dir` | `string` | `undefined` | 项目目录路径。省略时，搜索所有项目目录 |

310 310 

311### `resolveSettings()`

312 

313使用与 CLI 相同的合并引擎为给定目录解析有效的 Claude Code 设置，无需生成 Claude CLI。在调用 `query()` 之前使用它来检查 `query()` 调用将看到的配置。

314 

315<Note>

316 此函数处于 alpha 阶段，其 API 在稳定之前可能会更改。它读取 MDM 源，包括 macOS plist 和 Windows HKLM/HKCU，以与 CLI 启动保持一致，但不执行管理员配置的 `policyHelper` 子进程。`permissions.defaultMode` 字段从所有层级（包括项目设置）按原样返回。CLI 在遵守升级权限模式之前应用的信任过滤器不被应用。

317</Note>

318 

319```typescript theme={null}

320function resolveSettings(

321 options?: ResolveSettingsOptions

322): Promise<ResolvedSettings>;

323```

324 

325#### 参数

326 

327`resolveSettings()` 接受单个选项对象。所有字段都是可选的。

328 

329| 参数 | 类型 | 默认值 | 描述 |

330| :------------------------------ | :------------------------------------ | :-------------- | :-------------------------------------------------------- |

331| `options.cwd` | `string` | `process.cwd()` | 用于解析项目和本地设置的相对目录 |

332| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 所有源 | 要加载的文件系统源。传递 `[]` 以跳过用户、项目和本地设置。托管策略设置在所有情况下都会加载 |

333| `options.managedSettings` | `Settings` | `undefined` | 在托管策略优先级别合并的限制性策略层设置。非限制性密钥（如 `model`）会被静默删除 |

334| `options.serverManagedSettings` | `Settings` | `undefined` | 来自 `/api/claude_code/settings` 的服务器托管设置有效负载。非限制性密钥不经过滤地通过 |

335 

336#### 返回类型：`ResolvedSettings`

337 

338`resolveSettings()` 返回一个对象，描述合并的设置和为每个密钥提供的源。

339 

340| 属性 | 类型 | 描述 |

341| :----------- | :-------------------------------------------------- | :------------------------------- |

342| `effective` | `Settings` | 在按优先级顺序应用所有启用的源后合并的设置 |

343| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | 对于 `effective` 中的每个顶级密钥，哪个源提供了该值 |

344| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 每个源的原始设置，按从最低到最高优先级排序 |

345 

346#### 示例

347 

348下面的示例为项目目录解析设置，并打印控制清理周期的源。

349 

350```typescript theme={null}

351import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";

352 

353const { effective, provenance } = await resolveSettings({

354 cwd: "/path/to/project",

355 settingSources: ["user", "project", "local"],

356});

357 

358console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);

359console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

360```

361 

311## 类型362## 类型

312 363 

313### `Options`364### `Options`

864 | SDKFilesPersistedEvent915 | SDKFilesPersistedEvent

865 | SDKToolUseSummaryMessage916 | SDKToolUseSummaryMessage

866 | SDKRateLimitEvent917 | SDKRateLimitEvent

918 | SDKPermissionDeniedMessage

867 | SDKPromptSuggestionMessage;919 | SDKPromptSuggestionMessage;

868```920```

869 921 

1052};1104};

1053```1105```

1054 1106 

1107### `SDKPermissionDeniedMessage`

1108 

1109当权限系统自动拒绝工具调用而不显示交互式提示时发出的流事件。使用它在发生时在您的 UI 中呈现拒绝，而不仅仅观察随后的 `is_error` 工具结果。交互式询问路径通过 [`canUseTool`](#canusetool) 回调单独到达您的应用程序。由 `PreToolUse` hook 发出的拒绝不会通过此事件报告。

1110 

1111此事件需要 Claude Code v2.1.136 或更高版本。

1112 

1113```typescript theme={null}

1114type SDKPermissionDeniedMessage = {

1115 type: "system";

1116 subtype: "permission_denied";

1117 tool_name: string;

1118 tool_use_id: string;

1119 agent_id?: string;

1120 decision_reason_type?: string;

1121 decision_reason?: string;

1122 message: string;

1123 uuid: UUID;

1124 session_id: string;

1125};

1126```

1127 

1128| 字段 | 类型 | 描述 |

1129| ---------------------- | -------- | ------------------------------------------------------------- |

1130| `tool_name` | `string` | 被拒绝的工具的名称 |

1131| `tool_use_id` | `string` | 此拒绝回答的 `tool_use` 块的 ID |

1132| `agent_id` | `string` | 当拒绝的调用源自子代理内部时的子代理 ID。镜像 `can_use_tool` 上的字段以进行主机端路由 |

1133| `decision_reason_type` | `string` | 决定组件的鉴别器，例如 `"rule"`、`"mode"`、`"classifier"` 或 `"asyncAgent"` |

1134| `decision_reason` | `string` | 来自决定组件的人类可读原因（如果可用） |

1135| `message` | `string` | 在 `tool_result` 中返回给模型的拒绝消息 |

1136 

1055### `SDKPermissionDenial`1137### `SDKPermissionDenial`

1056 1138 

1057有关被拒绝的工具使用的信息。1139有关被拒绝的工具使用的信息。

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.

4 

5# 处理批准和用户输入

6 

7> 向用户显示 Claude 的批准请求和澄清问题，然后将他们的决定返回给 SDK。

8 

9在处理任务时，Claude 有时需要与用户进行沟通。它可能需要在删除文件前获得许可，或需要询问为新项目使用哪个数据库。您的应用程序需要向用户显示这些请求，以便 Claude 可以继续使用他们的输入。

10 

11Claude 在两种情况下请求用户输入：当它需要**使用工具的权限**（如删除文件或运行命令）时，以及当它有**澄清问题**（通过 `AskUserQuestion` 工具）时。两者都会触发您的 `canUseTool` 回调，该回调会暂停执行，直到您返回响应。这与普通对话轮次不同，在普通对话轮次中 Claude 完成后等待您的下一条消息。

12 

13对于澄清问题，Claude 生成问题和选项。您的角色是向用户呈现这些问题，并返回他们的选择。您不能向此流程添加自己的问题；如果您需要自己询问用户某些内容，请在应用程序逻辑中单独进行。

14 

15回调可以无限期地保持待处理状态。执行保持暂停状态，直到您的回调返回，SDK 仅在查询本身被取消时才取消等待。如果用户可能需要比您的进程能够合理保持运行的时间更长的时间来响应，TypeScript SDK 支持 [`defer` hook 决定](/zh-CN/hooks#defer-a-tool-call-for-later)，它允许进程退出并稍后从持久化会话恢复；此选项在 Python SDK 中不可用。

16 

17本指南向您展示如何检测每种类型的请求并做出适当的响应。

18 

19## 检测 Claude 何时需要输入

20 

21在您的查询选项中传递 `canUseTool` 回调。每当 Claude 需要用户输入时，回调就会触发，接收工具名称和输入作为参数：

22 

23<CodeGroup>

24 ```python Python theme={null}

25 async def handle_tool_request(tool_name, input_data, context):

26 # 提示用户并返回允许或拒绝

27 ...

28 

29 

30 options = ClaudeAgentOptions(can_use_tool=handle_tool_request)

31 ```

32 

33 ```typescript TypeScript theme={null}

34 async function handleToolRequest(toolName, input, options) {

35 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }

36 // 提示用户并返回允许或拒绝

37 }

38 

39 const options = { canUseTool: handleToolRequest };

40 ```

41</CodeGroup>

42 

43回调在两种情况下触发：

44 

451. **工具需要批准**：Claude 想要使用不被[权限规则](/zh-CN/agent-sdk/permissions)或模式自动批准的工具。检查 `tool_name` 以获取工具（例如 `"Bash"`、`"Write"`）。

462. **Claude 提出问题**：Claude 调用 `AskUserQuestion` 工具。检查 `tool_name == "AskUserQuestion"` 以不同方式处理它。如果您指定 `tools` 数组，请包含 `AskUserQuestion` 以使其工作。有关详细信息，请参阅[处理澄清问题](#handle-clarifying-questions)。

47 

48<Note>

49 要自动允许或拒绝工具而不提示用户，请改用 [hooks](/zh-CN/agent-sdk/hooks)。Hooks 在 `canUseTool` 之前执行，可以根据您自己的逻辑允许、拒绝或修改请求。您还可以使用 [`PermissionRequest` hook](/zh-CN/agent-sdk/hooks#available-hooks) 在 Claude 等待批准时发送外部通知（Slack、电子邮件、推送）。

50</Note>

51 

52## 处理工具批准请求

53 

54一旦您在查询选项中传递了 `canUseTool` 回调，当 Claude 想要使用不被自动批准的工具时，它就会触发。您的回调接收三个参数：

55 

56| 参数 | 描述 |

57| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

58| `toolName` | Claude 想要使用的工具的名称（例如 `"Bash"`、`"Write"`、`"Edit"`） |

59| `input` | Claude 传递给工具的参数。内容因工具而异。 |

60| `options` (TS) / `context` (Python) | 附加上下文，包括可选的 `suggestions`（建议的 `PermissionUpdate` 条目以避免重新提示）和取消信号。在 TypeScript 中，`signal` 是 `AbortSignal`；在 Python 中，信号字段保留供将来使用。有关 Python，请参阅 [`ToolPermissionContext`](/zh-CN/agent-sdk/python#toolpermissioncontext)。 |

61 

62`input` 对象包含工具特定的参数。常见示例：

63 

64| 工具 | 输入字段 |

65| ------- | ------------------------------------- |

66| `Bash` | `command`、`description`、`timeout` |

67| `Write` | `file_path`、`content` |

68| `Edit` | `file_path`、`old_string`、`new_string` |

69| `Read` | `file_path`、`offset`、`limit` |

70 

71有关完整的输入架构，请参阅 SDK 参考：[Python](/zh-CN/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/zh-CN/agent-sdk/typescript#tool-input-types)。

72 

73您可以向用户显示此信息，以便他们可以决定是否允许或拒绝该操作，然后返回适当的响应。

74 

75以下示例要求 Claude 创建和删除测试文件。当 Claude 尝试每个操作时，回调会将工具请求打印到终端并提示进行 y/n 批准。

76 

77<CodeGroup>

78 ```python Python theme={null}

79 import asyncio

80 

81 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

82 from claude_agent_sdk.types import (

83 HookMatcher,

84 PermissionResultAllow,

85 PermissionResultDeny,

86 ToolPermissionContext,

87 )

88 

89 

90 async def can_use_tool(

91 tool_name: str, input_data: dict, context: ToolPermissionContext

92 ) -> PermissionResultAllow | PermissionResultDeny:

93 # 显示工具请求

94 print(f"\nTool: {tool_name}")

95 if tool_name == "Bash":

96 print(f"Command: {input_data.get('command')}")

97 if input_data.get("description"):

98 print(f"Description: {input_data.get('description')}")

99 else:

100 print(f"Input: {input_data}")

101 

102 # 获取用户批准

103 response = input("Allow this action? (y/n): ")

104 

105 # 根据用户的响应返回允许或拒绝

106 if response.lower() == "y":

107 # 允许：工具使用原始（或修改的）输入执行

108 return PermissionResultAllow(updated_input=input_data)

109 else:

110 # 拒绝：工具不执行，Claude 看到该消息

111 return PermissionResultDeny(message="User denied this action")

112 

113 

114 # 必需的解决方法：虚拟 hook 保持流打开以供 can_use_tool 使用

115 async def dummy_hook(input_data, tool_use_id, context):

116 return {"continue_": True}

117 

118 

119 async def prompt_stream():

120 yield {

121 "type": "user",

122 "message": {

123 "role": "user",

124 "content": "Create a test file in /tmp and then delete it",

125 },

126 }

127 

128 

129 async def main():

130 async for message in query(

131 prompt=prompt_stream(),

132 options=ClaudeAgentOptions(

133 can_use_tool=can_use_tool,

134 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},

135 ),

136 ):

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

138 print(message.result)

139 

140 

141 asyncio.run(main())

142 ```

143 

144 ```typescript TypeScript theme={null}

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

146 import * as readline from "readline";

147 

148 // 帮助程序在终端中提示用户输入

149 function prompt(question: string): Promise<string> {

150 const rl = readline.createInterface({

151 input: process.stdin,

152 output: process.stdout

153 });

154 return new Promise((resolve) =>

155 rl.question(question, (answer) => {

156 rl.close();

157 resolve(answer);

158 })

159 );

160 }

161 

162 for await (const message of query({

163 prompt: "Create a test file in /tmp and then delete it",

164 options: {

165 canUseTool: async (toolName, input) => {

166 // 显示工具请求

167 console.log(`\nTool: ${toolName}`);

168 if (toolName === "Bash") {

169 console.log(`Command: ${input.command}`);

170 if (input.description) console.log(`Description: ${input.description}`);

171 } else {

172 console.log(`Input: ${JSON.stringify(input, null, 2)}`);

173 }

174 

175 // 获取用户批准

176 const response = await prompt("Allow this action? (y/n): ");

177 

178 // 根据用户的响应返回允许或拒绝

179 if (response.toLowerCase() === "y") {

180 // 允许：工具使用原始（或修改的）输入执行

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

182 } else {

183 // 拒绝：工具不执行，Claude 看到该消息

184 return { behavior: "deny", message: "User denied this action" };

185 }

186 }

187 }

188 })) {

189 if ("result" in message) console.log(message.result);

190 }

191 ```

192</CodeGroup>

193 

194<Note>

195 在 Python 中，`can_use_tool` 需要[流模式](/zh-CN/agent-sdk/streaming-vs-single-mode)和返回 `{"continue_": True}` 的 `PreToolUse` hook 以保持流打开。没有此 hook，流会在权限回调被调用之前关闭。

196</Note>

197 

198此示例使用 y/n 流，其中除 `y` 之外的任何输入都被视为拒绝。在实践中，您可能会构建一个更丰富的 UI，让用户修改请求、提供反馈或完全重定向 Claude。有关所有响应方式，请参阅[响应工具请求](#respond-to-tool-requests)。

199 

200### 响应工具请求

201 

202您的回调返回两种响应类型之一：

203 

204| 响应 | Python | TypeScript |

205| ------ | ------------------------------------------ | ------------------------------------- |

206| **允许** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` |

207| **拒绝** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` |

208 

209允许时，传递工具输入（原始或修改的）。拒绝时，提供说明原因的消息。Claude 会看到此消息并可能调整其方法。

210 

211<CodeGroup>

212 ```python Python theme={null}

213 from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

214 

215 # 允许工具执行

216 return PermissionResultAllow(updated_input=input_data)

217 

218 # 阻止工具

219 return PermissionResultDeny(message="User rejected this action")

220 ```

221 

222 ```typescript TypeScript theme={null}

223 // 允许工具执行

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

225 

226 // 阻止工具

227 return { behavior: "deny", message: "User rejected this action" };

228 ```

229</CodeGroup>

230 

231除了允许或拒绝之外，您还可以修改工具的输入或提供帮助 Claude 调整其方法的上下文：

232 

233* **批准**：让工具按 Claude 请求的方式执行

234* **批准并进行更改**：在执行前修改输入（例如，清理路径、添加约束）

235* **拒绝**：阻止工具并告诉 Claude 原因

236* **建议替代方案**：阻止但指导 Claude 朝向用户想要的方向

237* **完全重定向**：使用[流输入](/zh-CN/agent-sdk/streaming-vs-single-mode)向 Claude 发送全新指令

238 

239<Tabs>

240 <Tab title="批准">

241 用户按原样批准该操作。从您的回调中传递 `input` 不变，工具完全按 Claude 请求的方式执行。

242 

243 <CodeGroup>

244 ```python Python theme={null}

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

246 print(f"Claude wants to use {tool_name}")

247 approved = await ask_user("Allow this action?")

248 

249 if approved:

250 return PermissionResultAllow(updated_input=input_data)

251 return PermissionResultDeny(message="User declined")

252 ```

253 

254 ```typescript TypeScript theme={null}

255 canUseTool: async (toolName, input) => {

256 console.log(`Claude wants to use ${toolName}`);

257 const approved = await askUser("Allow this action?");

258 

259 if (approved) {

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

261 }

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

263 };

264 ```

265 </CodeGroup>

266 </Tab>

267 

268 <Tab title="批准并进行更改">

269 用户批准但想先修改请求。您可以在工具执行前更改输入。Claude 会看到结果，但不会被告知您更改了任何内容。对于清理参数、添加约束或限制访问范围很有用。

270 

271 <CodeGroup>

272 ```python Python theme={null}

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

274 if tool_name == "Bash":

275 # 用户批准，但将所有命令限制在沙箱中

276 sandboxed_input = {**input_data}

277 sandboxed_input["command"] = input_data["command"].replace(

278 "/tmp", "/tmp/sandbox"

279 )

280 return PermissionResultAllow(updated_input=sandboxed_input)

281 return PermissionResultAllow(updated_input=input_data)

282 ```

283 

284 ```typescript TypeScript theme={null}

285 canUseTool: async (toolName, input) => {

286 if (toolName === "Bash") {

287 // 用户批准，但将所有命令限制在沙箱中

288 const sandboxedInput = {

289 ...input,

290 command: input.command.replace("/tmp", "/tmp/sandbox")

291 };

292 return { behavior: "allow", updatedInput: sandboxedInput };

293 }

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

295 };

296 ```

297 </CodeGroup>

298 </Tab>

299 

300 <Tab title="拒绝">

301 用户不希望发生此操作。阻止工具并提供说明原因的消息。Claude 会看到此消息并可能尝试不同的方法。

302 

303 <CodeGroup>

304 ```python Python theme={null}

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

306 approved = await ask_user(f"Allow {tool_name}?")

307 

308 if not approved:

309 return PermissionResultDeny(message="User rejected this action")

310 return PermissionResultAllow(updated_input=input_data)

311 ```

312 

313 ```typescript TypeScript theme={null}

314 canUseTool: async (toolName, input) => {

315 const approved = await askUser(`Allow ${toolName}?`);

316 

317 if (!approved) {

318 return {

319 behavior: "deny",

320 message: "User rejected this action"

321 };

322 }

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

324 };

325 ```

326 </CodeGroup>

327 </Tab>

328 

329 <Tab title="建议替代方案">

330 用户不想要此特定操作，但有不同的想法。阻止工具并在您的消息中包含指导。Claude 将阅读此内容并根据您的反馈决定如何继续。

331 

332 <CodeGroup>

333 ```python Python theme={null}

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

335 if tool_name == "Bash" and "rm" in input_data.get("command", ""):

336 # 用户不想删除，建议改为存档

337 return PermissionResultDeny(

338 message="User doesn't want to delete files. They asked if you could compress them into an archive instead."

339 )

340 return PermissionResultAllow(updated_input=input_data)

341 ```

342 

343 ```typescript TypeScript theme={null}

344 canUseTool: async (toolName, input) => {

345 if (toolName === "Bash" && input.command.includes("rm")) {

346 // 用户不想删除，建议改为存档

347 return {

348 behavior: "deny",

349 message:

350 "User doesn't want to delete files. They asked if you could compress them into an archive instead."

351 };

352 }

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

354 };

355 ```

356 </CodeGroup>

357 </Tab>

358 

359 <Tab title="完全重定向">

360 对于完全改变方向（不仅仅是轻推），使用[流输入](/zh-CN/agent-sdk/streaming-vs-single-mode)向 Claude 发送新指令。这绕过当前工具请求并为 Claude 提供全新指令来遵循。

361 </Tab>

362</Tabs>

363 

364## 处理澄清问题

365 

366当 Claude 需要在具有多个有效方法的任务上获得更多指导时，它会调用 `AskUserQuestion` 工具。这会触发您的 `canUseTool` 回调，其中 `toolName` 设置为 `AskUserQuestion`。输入包含 Claude 的问题作为多选选项，您向用户显示这些问题并返回他们的选择。

367 

368<Tip>

369 澄清问题在 [`plan` 模式](/zh-CN/agent-sdk/permissions#plan-mode-plan)中特别常见，其中 Claude 探索代码库并在提出计划前提出问题。这使 plan 模式非常适合交互式工作流，您希望 Claude 在进行更改前收集需求。

370</Tip>

371 

372以下步骤显示如何处理澄清问题：

373 

374<Steps>

375 <Step title="传递 canUseTool 回调">

376 在您的查询选项中传递 `canUseTool` 回调。默认情况下，`AskUserQuestion` 可用。如果您指定 `tools` 数组来限制 Claude 的功能（例如，仅具有 `Read`、`Glob` 和 `Grep` 的只读代理），请在该数组中包含 `AskUserQuestion`。否则，Claude 将无法提出澄清问题：

377 

378 <CodeGroup>

379 ```python Python theme={null}

380 async for message in query(

381 prompt="Analyze this codebase",

382 options=ClaudeAgentOptions(

383 # 在您的工具列表中包含 AskUserQuestion

384 tools=["Read", "Glob", "Grep", "AskUserQuestion"],

385 can_use_tool=can_use_tool,

386 ),

387 ):

388 print(message)

389 ```

390 

391 ```typescript TypeScript theme={null}

392 for await (const message of query({

393 prompt: "Analyze this codebase",

394 options: {

395 // 在您的工具列表中包含 AskUserQuestion

396 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],

397 canUseTool: async (toolName, input) => {

398 // 在此处处理澄清问题

399 }

400 }

401 })) {

402 console.log(message);

403 }

404 ```

405 </CodeGroup>

406 </Step>

407 

408 <Step title="检测 AskUserQuestion">

409 在您的回调中，检查 `toolName` 是否等于 `AskUserQuestion` 以不同方式处理它与其他工具：

410 

411 <CodeGroup>

412 ```python Python theme={null}

413 async def can_use_tool(tool_name: str, input_data: dict, context):

414 if tool_name == "AskUserQuestion":

415 # 您从用户收集答案的实现

416 return await handle_clarifying_questions(input_data)

417 # 正常处理其他工具

418 return await prompt_for_approval(tool_name, input_data)

419 ```

420 

421 ```typescript TypeScript theme={null}

422 canUseTool: async (toolName, input) => {

423 if (toolName === "AskUserQuestion") {

424 // 您从用户收集答案的实现

425 return handleClarifyingQuestions(input);

426 }

427 // 正常处理其他工具

428 return promptForApproval(toolName, input);

429 };

430 ```

431 </CodeGroup>

432 </Step>

433 

434 <Step title="解析问题输入">

435 输入包含 Claude 在 `questions` 数组中的问题。每个问题都有 `question`（要显示的文本）、`options`（选择）和 `multiSelect`（是否允许多个选择）：

436 

437 ```json theme={null}

438 {

439 "questions": [

440 {

441 "question": "How should I format the output?",

442 "header": "Format",

443 "options": [

444 { "label": "Summary", "description": "Brief overview" },

445 { "label": "Detailed", "description": "Full explanation" }

446 ],

447 "multiSelect": false

448 },

449 {

450 "question": "Which sections should I include?",

451 "header": "Sections",

452 "options": [

453 { "label": "Introduction", "description": "Opening context" },

454 { "label": "Conclusion", "description": "Final summary" }

455 ],

456 "multiSelect": true

457 }

458 ]

459 }

460 ```

461 

462 有关完整字段描述，请参阅[问题格式](#question-format)。

463 </Step>

464 

465 <Step title="从用户收集答案">

466 向用户呈现问题并收集他们的选择。您如何执行此操作取决于您的应用程序：终端提示、Web 表单、移动对话框等。

467 </Step>

468 

469 <Step title="将答案返回给 Claude">

470 将 `answers` 对象构建为记录，其中每个键是 `question` 文本，每个值是所选选项的 `label`：

471 

472 | 来自问题对象 | 用作 |

473 | ----------------------------------------------------- | -- |

474 | `question` 字段（例如 `"How should I format the output?"`） | 键 |

475 | 所选选项的 `label` 字段（例如 `"Summary"`） | 值 |

476 

477 对于多选问题，传递标签数组或用 `", "` 连接它们。如果您[支持自由文本输入](#support-free-text-input)，使用用户的自定义文本作为值。

478 

479 <CodeGroup>

480 ```python Python theme={null}

481 return PermissionResultAllow(

482 updated_input={

483 "questions": input_data.get("questions", []),

484 "answers": {

485 "How should I format the output?": "Summary",

486 "Which sections should I include?": ["Introduction", "Conclusion"],

487 },

488 }

489 )

490 ```

491 

492 ```typescript TypeScript theme={null}

493 return {

494 behavior: "allow",

495 updatedInput: {

496 questions: input.questions,

497 answers: {

498 "How should I format the output?": "Summary",

499 "Which sections should I include?": "Introduction, Conclusion"

500 }

501 }

502 };

503 ```

504 </CodeGroup>

505 </Step>

506</Steps>

507 

508### 问题格式

509 

510输入包含 Claude 在 `questions` 数组中生成的问题。每个问题都有这些字段：

511 

512| 字段 | 描述 |

513| ------------- | ------------------------------------------------------------------------------------------------------ |

514| `question` | 要显示的完整问题文本 |

515| `header` | 问题的短标签（最多 12 个字符） |

516| `options` | 2-4 个选择的数组，每个都有 `label` 和 `description`。TypeScript：可选 `preview`（请参阅[下文](#option-previews-type-script)） |

517| `multiSelect` | 如果为 `true`，用户可以选择多个选项 |

518 

519您的回调接收的结构：

520 

521```json theme={null}

522{

523 "questions": [

524 {

525 "question": "How should I format the output?",

526 "header": "Format",

527 "options": [

528 { "label": "Summary", "description": "Brief overview of key points" },

529 { "label": "Detailed", "description": "Full explanation with examples" }

530 ],

531 "multiSelect": false

532 }

533 ]

534}

535```

536 

537#### 选项预览 (TypeScript)

538 

539`toolConfig.askUserQuestion.previewFormat` 向每个选项添加 `preview` 字段，以便您的应用可以在标签旁显示视觉模型。没有此设置，Claude 不会生成预览，该字段不存在。

540 

541| `previewFormat` | `preview` 包含 |

542| :-------------- | :----------------------------------------------------------------- |

543| 未设置（默认） | 字段不存在。Claude 不会生成预览。 |

544| `"markdown"` | ASCII 艺术和围栏代码块 |

545| `"html"` | 样式的 `<div>` 片段（SDK 在您的回调运行前拒绝 `<script>`、`<style>` 和 `<!DOCTYPE>`） |

546 

547该格式适用于会话中的所有问题。Claude 在视觉比较有帮助的选项上包含 `preview`（布局选择、配色方案），并在不会的地方省略它（是/否确认、仅文本选择）。在呈现前检查 `undefined`。

548 

549```typescript theme={null}

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

551 

552for await (const message of query({

553 prompt: "Help me choose a card layout",

554 options: {

555 toolConfig: {

556 askUserQuestion: { previewFormat: "html" }

557 },

558 canUseTool: async (toolName, input) => {

559 // input.questions[].options[].preview 是 HTML 字符串或 undefined

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

561 }

562 }

563})) {

564 // ...

565}

566```

567 

568带有 HTML 预览的选项：

569 

570```json theme={null}

571{

572 "label": "Compact",

573 "description": "Title and metric value only",

574 "preview": "<div style=\"padding:12px;border:1px solid #ddd;border-radius:8px\"><div style=\"font-size:12px;color:#666\">Active users</div><div style=\"font-size:28px;font-weight:600\">1,284</div></div>"

575}

576```

577 

578### 响应格式

579 

580返回 `answers` 对象，将每个问题的 `question` 字段映射到所选选项的 `label`：

581 

582| 字段 | 描述 |

583| ----------- | ------------------ |

584| `questions` | 传递原始问题数组（工具处理需要） |

585| `answers` | 对象，其中键是问题文本，值是所选标签 |

586 

587对于多选问题，传递标签数组或用 `", "` 连接它们。对于自由文本输入，直接使用用户的自定义文本。

588 

589```json theme={null}

590{

591 "questions": [

592 // ...

593 ],

594 "answers": {

595 "How should I format the output?": "Summary",

596 "Which sections should I include?": ["Introduction", "Conclusion"]

597 }

598}

599```

600 

601#### 支持自由文本输入

602 

603Claude 的预定义选项并不总是涵盖用户想要的内容。要让用户输入自己的答案：

604 

605* 在 Claude 的选项后显示额外的"其他"选择，接受文本输入

606* 使用用户的自定义文本作为答案值（不是单词"其他"）

607 

608有关完整实现，请参阅下面的[完整示例](#complete-example)。

609 

610### 完整示例

611 

612当 Claude 需要用户输入来继续时，它会提出澄清问题。例如，当被要求帮助为移动应用程序决定技术栈时，Claude 可能会询问跨平台与原生、后端偏好或目标平台。这些问题帮助 Claude 做出与用户偏好相匹配的决定，而不是猜测。

613 

614此示例在终端应用程序中处理这些问题。以下是每个步骤发生的情况：

615 

6161. **路由请求**：`canUseTool` 回调检查工具名称是否为 `"AskUserQuestion"` 并路由到专用处理程序

6172. **显示问题**：处理程序循环遍历 `questions` 数组并打印每个问题及编号选项

6183. **收集输入**：用户可以输入数字来选择选项，或直接输入自由文本（例如"jquery"、"i don't know"）

6194. **映射答案**：代码检查输入是数字（使用选项的标签）还是自由文本（使用文本直接）

6205. **返回给 Claude**：响应包括原始 `questions` 数组和 `answers` 映射

621 

622<CodeGroup>

623 ```python Python theme={null}

624 import asyncio

625 

626 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

627 from claude_agent_sdk.types import HookMatcher, PermissionResultAllow

628 

629 

630 def parse_response(response: str, options: list) -> str:

631 """将用户输入解析为选项编号或自由文本。"""

632 try:

633 indices = [int(s.strip()) - 1 for s in response.split(",")]

634 labels = [options[i]["label"] for i in indices if 0 <= i < len(options)]

635 return ", ".join(labels) if labels else response

636 except ValueError:

637 return response

638 

639 

640 async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow:

641 """显示 Claude 的问题并收集用户答案。"""

642 answers = {}

643 

644 for q in input_data.get("questions", []):

645 print(f"\n{q['header']}: {q['question']}")

646 

647 options = q["options"]

648 for i, opt in enumerate(options):

649 print(f" {i + 1}. {opt['label']} - {opt['description']}")

650 if q.get("multiSelect"):

651 print(" (Enter numbers separated by commas, or type your own answer)")

652 else:

653 print(" (Enter a number, or type your own answer)")

654 

655 response = input("Your choice: ").strip()

656 answers[q["question"]] = parse_response(response, options)

657 

658 return PermissionResultAllow(

659 updated_input={

660 "questions": input_data.get("questions", []),

661 "answers": answers,

662 }

663 )

664 

665 

666 async def can_use_tool(

667 tool_name: str, input_data: dict, context

668 ) -> PermissionResultAllow:

669 # 将 AskUserQuestion 路由到我们的问题处理程序

670 if tool_name == "AskUserQuestion":

671 return await handle_ask_user_question(input_data)

672 # 为此示例自动批准其他工具

673 return PermissionResultAllow(updated_input=input_data)

674 

675 

676 async def prompt_stream():

677 yield {

678 "type": "user",

679 "message": {

680 "role": "user",

681 "content": "Help me decide on the tech stack for a new mobile app",

682 },

683 }

684 

685 

686 # 必需的解决方法：虚拟 hook 保持流打开以供 can_use_tool 使用

687 async def dummy_hook(input_data, tool_use_id, context):

688 return {"continue_": True}

689 

690 

691 async def main():

692 async for message in query(

693 prompt=prompt_stream(),

694 options=ClaudeAgentOptions(

695 can_use_tool=can_use_tool,

696 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},

697 ),

698 ):

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

700 print(message.result)

701 

702 

703 asyncio.run(main())

704 ```

705 

706 ```typescript TypeScript theme={null}

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

708 import * as readline from "readline/promises";

709 

710 // 帮助程序在终端中提示用户输入

711 async function prompt(question: string): Promise<string> {

712 const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

713 const answer = await rl.question(question);

714 rl.close();

715 return answer;

716 }

717 

718 // 将用户输入解析为选项编号或自由文本

719 function parseResponse(response: string, options: any[]): string {

720 const indices = response.split(",").map((s) => parseInt(s.trim()) - 1);

721 const labels = indices

722 .filter((i) => !isNaN(i) && i >= 0 && i < options.length)

723 .map((i) => options[i].label);

724 return labels.length > 0 ? labels.join(", ") : response;

725 }

726 

727 // 显示 Claude 的问题并收集用户答案

728 async function handleAskUserQuestion(input: any) {

729 const answers: Record<string, string> = {};

730 

731 for (const q of input.questions) {

732 console.log(`\n${q.header}: ${q.question}`);

733 

734 const options = q.options;

735 options.forEach((opt: any, i: number) => {

736 console.log(` ${i + 1}. ${opt.label} - ${opt.description}`);

737 });

738 if (q.multiSelect) {

739 console.log(" (Enter numbers separated by commas, or type your own answer)");

740 } else {

741 console.log(" (Enter a number, or type your own answer)");

742 }

743 

744 const response = (await prompt("Your choice: ")).trim();

745 answers[q.question] = parseResponse(response, options);

746 }

747 

748 // 将答案返回给 Claude（必须包括原始问题）

749 return {

750 behavior: "allow",

751 updatedInput: { questions: input.questions, answers }

752 };

753 }

754 

755 async function main() {

756 for await (const message of query({

757 prompt: "Help me decide on the tech stack for a new mobile app",

758 options: {

759 canUseTool: async (toolName, input) => {

760 // 将 AskUserQuestion 路由到我们的问题处理程序

761 if (toolName === "AskUserQuestion") {

762 return handleAskUserQuestion(input);

763 }

764 // 为此示例自动批准其他工具

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

766 }

767 }

768 })) {

769 if ("result" in message) console.log(message.result);

770 }

771 }

772 

773 main();

774 ```

775</CodeGroup>

776 

777## 限制

778 

779* **子代理**：`AskUserQuestion` 目前在通过 Agent 工具生成的子代理中不可用

780* **问题限制**：每个 `AskUserQuestion` 调用支持 1-4 个问题，每个 2-4 个选项

781 

782## 获取用户输入的其他方式

783 

784`canUseTool` 回调和 `AskUserQuestion` 工具涵盖了大多数批准和澄清场景，但 SDK 提供了其他从用户获取输入的方式：

785 

786### 流输入

787 

788当您需要以下情况时，使用[流输入](/zh-CN/agent-sdk/streaming-vs-single-mode)：

789 

790* **在任务中断代理**：在 Claude 工作时发送取消信号或改变方向

791* **提供额外上下文**：添加 Claude 需要的信息而无需等待它提出问题

792* **构建聊天界面**：让用户在长时间运行的操作期间发送后续消息

793 

794流输入非常适合对话式 UI，用户在整个执行过程中与代理交互，而不仅仅在批准检查点。

795 

796### 自定义工具

797 

798当您需要以下情况时，使用[自定义工具](/zh-CN/agent-sdk/custom-tools)：

799 

800* **收集结构化输入**：构建超越 `AskUserQuestion` 多选格式的表单、向导或多步工作流

801* **集成外部批准系统**：连接到现有的票务、工作流或批准平台

802* **实现特定领域的交互**：创建针对您的应用程序需求定制的工具，如代码审查界面或部署清单

803 

804自定义工具让您完全控制交互，但需要比使用内置 `canUseTool` 回调更多的实现工作。

805 

806## 相关资源

807 

808* [配置权限](/zh-CN/agent-sdk/permissions)：设置权限模式和规则

809* [使用 hooks 控制执行](/zh-CN/agent-sdk/hooks)：在代理生命周期的关键点运行自定义代码

810* [TypeScript SDK 参考](/zh-CN/agent-sdk/typescript#canusetool)：完整的 canUseTool API 文档

39 39 

40分类器不从 `.claude/settings.json` 中的共享项目设置读取 `autoMode`，因此已检入的代码库无法注入其自己的允许规则。40分类器不从 `.claude/settings.json` 中的共享项目设置读取 `autoMode`，因此已检入的代码库无法注入其自己的允许规则。

41 41 

42来自每个范围的条目被合并。开发者可以使用个人条目扩展 `environment`、`allow` 和 `soft_deny`，但无法删除托管设置提供的条目。因为允许规则在分类器内充当阻止规则的例外，开发者添加的 `allow` 条目可以覆盖组织 `soft_deny` 条目：组合是累加的，而不是硬策略边界。42来自每个范围的条目被合并。开发者可以使用个人条目扩展 `environment`、`allow`、`soft_deny` 和 `hard_deny`，但无法删除托管设置提供的条目。因为允许规则在分类器内充当软阻止规则的例外，开发者添加的 `allow` 条目可以覆盖组织 `soft_deny` 条目：组合是累加的，而不是硬策略边界。

43 43 

44<Note>44<Note>

45 分类器是在[权限系统](/zh-CN/permissions)之后运行的第二道门。对于无论用户意图或分类器配置如何都必须永远不运行的操作，请在托管设置中使用 `permissions.deny`，它在咨询分类器之前阻止操作，无法被覆盖。45 分类器是在[权限系统](/zh-CN/permissions)之后运行的第二道门。对于无论用户意图或分类器配置如何都必须永远不运行的操作，请在托管设置中使用 `permissions.deny`，它在咨询分类器之前阻止操作，无法被覆盖。

99 99 

100## 覆盖阻止和允许规则100## 覆盖阻止和允许规则

101 101 

102两个额外的字段让您替换分类器的内置规则列表：`autoMode.soft_deny` 控制被阻止的内容，`autoMode.allow` 控制应用哪些例外。每个都是散文描述的数组，读作自然语言规则。没有 `autoMode.deny` 字段；要硬阻止一个操作而不管意图，请使用 [`permissions.deny`](/zh-CN/permissions)，它在分类器之前运行。102三个额外的字段让您替换分类器的内置规则列表：`autoMode.hard_deny` 用于无条件安全边界，`autoMode.soft_deny` 用于用户意图可以清除的破坏性操作，以及 `autoMode.allow` 用于例外。每个都是散文描述的数组，读作自然语言规则。对于在分类器之前运行的基于工具模式的硬阻止，请使用 [`permissions.deny`](/zh-CN/permissions)。

103 103 

104在分类器内，优先级分为三个层级：104在分类器内，优先级分为四个层级：

105 105 

106* `soft_deny` 规则首先阻止106* `hard_deny` 规则无条件阻止。用户意图和 `allow` 例外不适用。

107* `allow` 规则然后覆盖匹配的阻止作为例外107* `soft_deny` 规则接下来阻止。用户意图和 `allow` 例外可以覆盖这些。

108* 明确的用户意图覆盖两者：如果用户的消息直接且具体地描述 Claude 即将采取的确切操作，分类器允许它，即使 `soft_deny` 规则匹配108* `allow` 规则然后覆盖匹配的 `soft_deny` 规则作为例外。

109* 明确的用户意图覆盖剩余的软阻止：如果用户的消息直接且具体地描述 Claude 即将采取的确切操作，分类器允许它，即使 `soft_deny` 规则匹配。

109 110 

110一般请求不算作明确意图。要求 Claude"清理代码库"不授权强制推送，但要求 Claude"强制推送此分支"则授权。111一般请求不算作明确意图。要求 Claude"清理代码库"不授权强制推送，但要求 Claude"强制推送此分支"则授权。

111 112 

112要放松，当分类器重复标记默认例外不涵盖的常规模式时，添加到 `allow`。要收紧，为您的环境特定的风险添加到 `soft_deny`，默认值会遗漏。要保持内置规则同时添加您自己的规则，请在数组中包含字面字符串 `"$defaults"`。默认规则会在该位置拼接，因此您的自定义规则可以在它们之前或之后，并且当内置列表在版本发布中更改时，您继续继承更新。113要放松，当分类器重复标记默认例外不涵盖的常规模式时，添加到 `allow`。要收紧，为您的环境特定的破坏性风险添加到 `soft_deny`（默认值会遗漏），或为必须永远不能跨越的安全边界添加到 `hard_deny`。要保持内置规则同时添加您自己的规则，请在数组中包含字面字符串 `"$defaults"`。默认规则会在该位置拼接，因此您的自定义规则可以在它们之前或之后，并且当内置列表在版本发布中更改时，您继续继承更新。

113 114 

114```json theme={null}115```json theme={null}

115{116{

127 "$defaults",128 "$defaults",

128 "Never run database migrations outside the migrations CLI, even against dev databases",129 "Never run database migrations outside the migrations CLI, even against dev databases",

129 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"130 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"

131 ],

132 "hard_deny": [

133 "$defaults",

134 "Never send repository contents to third-party code-review APIs"

130 ]135 ]

131 }136 }

132}137}

133```138```

134 139 

135<Danger>140<Danger>

136 设置 `environment`、`allow` 或 `soft_deny` 中的任何一个而不包含 `"$defaults"` 会替换该部分的整个默认列表。如果您设置 `soft_deny` 为单个条目并省略 `"$defaults"`，每个内置阻止规则都会被丢弃：强制推送、数据泄露、`curl | bash`、生产部署以及所有其他默认阻止规则都变为允许。仅在您打算完全拥有该列表时才省略 `"$defaults"`。在这种情况下，运行 `claude auto-mode defaults` 打印内置规则，将它们复制到您的设置文件中，然后根据您自己的管道和风险容限审查每条规则。141 在不包含 `"$defaults"` 的情况下设置 `environment`、`allow`、`soft_deny` 或 `hard_deny` 中的任何一个会替换该部分的整个默认列表。没有 `"$defaults"` 的 `soft_deny` 数组会丢弃每个内置软阻止规则，包括强制推送、`curl | bash` 和生产部署。没有 `"$defaults"` 的 `hard_deny` 数组会丢弃内置的数据泄露和安全检查绕过规则。

137</Danger>142</Danger>

138 143 

139每个部分独立评估，因此单独设置 `environment` 会保持默认 `allow` 和 `soft_deny` 列表完整。144每个部分独立评估，因此单独设置 `environment` 会保持默认 `allow`、`soft_deny` 和 `hard_deny` 列表完整。仅在您打算完全拥有该列表时才省略 `"$defaults"`。要安全地执行此操作，请运行 `claude auto-mode defaults` 打印内置规则，将它们复制到您的设置文件中，然后根据您自己的管道和风险容限审查每条规则。

140 145 

141## 检查默认值和您的有效配置146## 检查默认值和您的有效配置

142 147 

143三个 CLI 子命令帮助您检查和验证您的配置。148三个 CLI 子命令帮助您检查和验证您的配置。

144 149 

145将内置 `environment`、`allow` 和 `soft_deny` 规则打印为 JSON：150将内置 `environment`、`allow`、`soft_deny` 和 `hard_deny` 规则打印为 JSON：

146 151 

147```bash theme={null}152```bash theme={null}

148claude auto-mode defaults153claude auto-mode defaults

154claude auto-mode config159claude auto-mode config

155```160```

156 161 

157获取关于您的自定义 `allow` 和 `soft_deny` 规则的 AI 反馈：162获取关于您的自定义 `allow`、`soft_deny` 和 `hard_deny` 规则的 AI 反馈：

158 163 

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

160claude auto-mode critique165claude auto-mode critique

46| `/btw <question>` | 提出快速[附加问题](/zh-CN/interactive-mode#side-questions-with-%2Fbtw)，无需添加到对话中 |46| `/btw <question>` | 提出快速[附加问题](/zh-CN/interactive-mode#side-questions-with-%2Fbtw)，无需添加到对话中 |

47| `/chrome` | 配置 [Claude in Chrome](/zh-CN/chrome) 设置 |47| `/chrome` | 配置 [Claude in Chrome](/zh-CN/chrome) 设置 |

48| `/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 |48| `/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 |

49| `/clear` | 使用空上下文启动新对话。之前的对话在 `/resume` 中保持可用。要在继续同一对话的同时释放上下文，请改用 `/compact`。别名：`/reset`、`/new` |49| `/clear [name]` | 使用空上下文启动新对话。之前的对话在 `/resume` 中保持可用。传递一个名称以在 `/resume` 选择器中标记之前的对话。要在继续同一对话的同时释放上下文，请改用 `/compact`。别名：`/reset`、`/new` |

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

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

52| `/config` | 打开[设置](/zh-CN/settings)界面以调整主题、模型、[输出样式](/zh-CN/output-styles)和其他偏好设置。别名：`/settings` |52| `/config` | 打开[设置](/zh-CN/settings)界面以调整主题、模型、[输出样式](/zh-CN/output-styles)和其他偏好设置。别名：`/settings` |

53| `/context` | 将当前上下文使用情况可视化为彩色网格。显示上下文密集型工具、内存膨胀和容量警告的优化建议 |53| `/context [all]` | 将当前上下文使用情况可视化为彩色网格。显示上下文密集型工具、内存膨胀和容量警告的优化建议。在[全屏模式](/zh-CN/fullscreen)中，每项的分解被折叠以保持网格可见。传递 `all` 以展开它 |

54| `/copy [N]` | 将最后一个助手响应复制到剪贴板。传递数字 `N` 以复制第 N 个最新响应：`/copy 2` 复制倒数第二个。当存在代码块时，显示交互式选择器以选择单个块或完整响应。在选择器中按 `w` 将选择内容写入文件而不是剪贴板，这在 SSH 上很有用 |54| `/copy [N]` | 将最后一个助手响应复制到剪贴板。传递数字 `N` 以复制第 N 个最新响应：`/copy 2` 复制倒数第二个。当存在代码块时，显示交互式选择器以选择单个块或完整响应。在选择器中按 `w` 将选择内容写入文件而不是剪贴板，这在 SSH 上很有用 |

55| `/cost` | `/usage` 的别名 |55| `/cost` | `/usage` 的别名 |

56| `/debug [description]` | **[Skill](/zh-CN/skills#bundled-skills).** 为当前会话启用调试日志记录并通过读取会话调试日志来排查问题。调试日志默认关闭，除非您使用 `claude --debug` 启动，因此在会话中途运行 `/debug` 会从该点开始捕获日志。可选择性地描述问题以集中分析 |56| `/debug [description]` | **[Skill](/zh-CN/skills#bundled-skills).** 为当前会话启用调试日志记录并通过读取会话调试日志来排查问题。调试日志默认关闭，除非您使用 `claude --debug` 启动，因此在会话中途运行 `/debug` 会从该点开始捕获日志。可选择性地描述问题以集中分析 |

88| `/powerup` | 通过带有动画演示的快速交互式课程发现 Claude Code 功能 |88| `/powerup` | 通过带有动画演示的快速交互式课程发现 Claude Code 功能 |

89| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。改为直接询问 Claude 以查看 pull request 评论。在早期版本中，从 GitHub pull request 获取并显示评论；自动检测当前分支的 PR，或传递 PR URL 或编号。需要 `gh` CLI |89| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。改为直接询问 Claude 以查看 pull request 评论。在早期版本中，从 GitHub pull request 获取并显示评论；自动检测当前分支的 PR，或传递 PR URL 或编号。需要 `gh` CLI |

90| `/privacy-settings` | 查看和更新您的隐私设置。仅对 Pro 和 Max 计划订阅者可用 |90| `/privacy-settings` | 查看和更新您的隐私设置。仅对 Pro 和 Max 计划订阅者可用 |

91| `/radio` | 在浏览器中打开 Claude FM lo-fi 电台。当浏览器不可用时打印流 URL。在 Bedrock、Vertex 或 Foundry 上不可用 |

91| `/recap` | 按需生成当前会话的单行摘要。请参阅[会话摘要](/zh-CN/interactive-mode#session-recap)以了解您离开后出现的自动摘要 |92| `/recap` | 按需生成当前会话的单行摘要。请参阅[会话摘要](/zh-CN/interactive-mode#session-recap)以了解您离开后出现的自动摘要 |

92| `/release-notes` | 在交互式版本选择器中查看更改日志。选择特定版本以查看其发布说明，或选择显示所有版本 |93| `/release-notes` | 在交互式版本选择器中查看更改日志。选择特定版本以查看其发布说明，或选择显示所有版本 |

93| `/reload-plugins` | 重新加载所有活跃 [plugins](/zh-CN/plugins) 以应用待处理的更改，无需重启。报告每个已重新加载组件的计数并标记任何加载错误 |94| `/reload-plugins` | 重新加载所有活跃 [plugins](/zh-CN/plugins) 以应用待处理的更改，无需重启。报告每个已重新加载组件的计数并标记任何加载错误 |

92| `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) |

93| `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` 切换 |

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

95| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于 Anthropic API 默认启用。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由到代理时强制启用。对 Foundry 和[网关](/zh-CN/llm-gateway)连接默认关闭 |95| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于 Anthropic API 默认启用。在 Bedrock 和 Vertex 上，按模型启用，其中部署的容器支持它。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由到代理时强制启用。对 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) 允许列表过滤 |96| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤 |

97| `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) |

98| `CLAUDE_CODE_ENABLE_TASKS` | 设置为 `1` 以在非交互模式（`-p` 标志）中启用任务跟踪系统。任务在交互模式中默认启用。请参阅[任务列表](/zh-CN/interactive-mode#task-list) |98| `CLAUDE_CODE_ENABLE_TASKS` | 设置为 `1` 以在非交互模式（`-p` 标志）中启用任务跟踪系统。任务在交互模式中默认启用。请参阅[任务列表](/zh-CN/interactive-mode#task-list) |

116| `CLAUDE_CODE_MAX_RETRIES` | 覆盖重试失败 API 请求的次数（默认值：10） |116| `CLAUDE_CODE_MAX_RETRIES` | 覆盖重试失败 API 请求的次数（默认值：10） |

117| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 可以并行执行的只读工具和 subagents 的最大数量（默认值：10）。更高的值增加并行性但消耗更多资源 |117| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 可以并行执行的只读工具和 subagents 的最大数量（默认值：10）。更高的值增加并行性但消耗更多资源 |

118| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | 设置为 `1` 以使用仅安全基线环境加上服务器的配置 `env` 生成 stdio MCP 服务器，而不是继承您的 shell 环境 |118| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | 设置为 `1` 以使用仅安全基线环境加上服务器的配置 `env` 生成 stdio MCP 服务器，而不是继承您的 shell 环境 |

119| `CLAUDE_CODE_NATIVE_CURSOR` | 设置为 `1` 以在输入插入符处显示终端自己的光标，而不是绘制的块。光标尊重终端的闪烁、形状和焦点设置 |

119| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。该流程会询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks，然后再探索代码库并编写它们。没有此变量，`/init` 会自动生成 CLAUDE.md 而不提示。 |120| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。该流程会询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks，然后再探索代码库并编写它们。没有此变量，`/init` 会自动生成 CLAUDE.md 而不提示。 |

120| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 以启用[全屏渲染](/zh-CN/fullscreen)，这是一个研究预览，可减少闪烁并在长对话中保持内存平坦。等同于 [`tui`](/zh-CN/settings#available-settings) 设置；您也可以使用 `/tui fullscreen` 切换 |121| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 以启用[全屏渲染](/zh-CN/fullscreen)，这是一个研究预览，可减少闪烁并在长对话中保持内存平坦。等同于 [`tui`](/zh-CN/settings#available-settings) 设置；您也可以使用 `/tui fullscreen` 切换 |

121| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 直接交换此令牌，而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。对于在自动化环境中配置身份验证很有用 |122| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 直接交换此令牌，而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。对于在自动化环境中配置身份验证很有用 |

191| `DISABLE_TELEMETRY` | 设置为 `1` 以选择退出遥测。遥测事件不包括用户数据，如代码、文件路径或 bash 命令 |192| `DISABLE_TELEMETRY` | 设置为 `1` 以选择退出遥测。遥测事件不包括用户数据，如代码、文件路径或 bash 命令 |

192| `DISABLE_UPDATES` | 设置为 `1` 以阻止所有更新，包括手动 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。当通过您自己的渠道分发 Claude Code 且用户不应自行更新时使用 |193| `DISABLE_UPDATES` | 设置为 `1` 以阻止所有更新，包括手动 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。当通过您自己的渠道分发 Claude Code 且用户不应自行更新时使用 |

193| `DISABLE_UPGRADE_COMMAND` | 设置为 `1` 以隐藏 `/upgrade` 命令 |194| `DISABLE_UPGRADE_COMMAND` | 设置为 `1` 以隐藏 `/upgrade` 命令 |

195| `DO_NOT_TRACK` | 设置为 `1` 以选择退出遥测。等同于设置 `DISABLE_TELEMETRY`。作为[标准跨工具约定](https://consoledonottrack.com/)被遵守 |

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

195| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的 prompt cache TTL 而不是默认的 5 分钟。适用于 API 密钥、[Bedrock](/zh-CN/amazon-bedrock)、[Vertex](/zh-CN/google-vertex-ai) 和 [Foundry](/zh-CN/microsoft-foundry) 用户。订阅用户自动获得 1 小时 TTL。1 小时缓存写入按更高费率计费 |197| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的 prompt cache TTL 而不是默认的 5 分钟。适用于 API 密钥、[Bedrock](/zh-CN/amazon-bedrock)、[Vertex](/zh-CN/google-vertex-ai) 和 [Foundry](/zh-CN/microsoft-foundry) 用户。订阅用户自动获得 1 小时 TTL。1 小时缓存写入按更高费率计费 |

196| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | 已弃用。改用 `ENABLE_PROMPT_CACHING_1H` |198| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | 已弃用。改用 `ENABLE_PROMPT_CACHING_1H` |

31| `Not logged in · Please run /login` | [身份验证](#not-logged-in) |31| `Not logged in · Please run /login` | [身份验证](#not-logged-in) |

32| `Invalid API key` | [身份验证](#invalid-api-key) |32| `Invalid API key` | [身份验证](#invalid-api-key) |

33| `This organization has been disabled` | [身份验证](#this-organization-has-been-disabled) |33| `This organization has been disabled` | [身份验证](#this-organization-has-been-disabled) |

34| `Routines are disabled by your organization's policy` | [身份验证](#routines-are-disabled-by-your-organizations-policy) |

34| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |35| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |

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

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

230**要做什么：**231**要做什么：**

231 232 

232* 检查拼写错误，并确认密钥未在 [Console](https://platform.claude.com/settings/keys) 中被撤销233* 检查拼写错误，并确认密钥未在 [Console](https://platform.claude.com/settings/keys) 中被撤销

233* 在同一 shell 中运行 `env | grep ANTHROPIC`。direnv、dotenv shell 插件和 IDE 终端等工具可以从项目中的 `.env` 文件加载过时的密钥，而无需您显式设置它。234* 在同一 shell 中运行 `env | grep ANTHROPIC`。direnv、dotenv shell 插件和 IDE 终端等工具可以从项目中的 `.env` 文件加载过时的密钥，而无需您显式设置它

234* 取消设置 `ANTHROPIC_API_KEY` 并运行 `/login` 以改用订阅身份验证235* 取消设置 `ANTHROPIC_API_KEY` 并运行 `/login` 以改用订阅身份验证

235* 如果密钥来自 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，请直接运行脚本以确认它在 stdout 上打印有效的密钥236* 如果密钥来自 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，请直接运行脚本以确认它在 stdout 上打印有效的密钥

236* 运行 `/status` 以确认 Claude Code 实际使用的凭证源237* 运行 `/status` 以确认 Claude Code 实际使用的凭证源

252* 之后运行 `/status` 以确认活跃凭证是您的订阅253* 之后运行 `/status` 以确认活跃凭证是您的订阅

253* 如果未设置环境变量且错误仍然存在，则禁用的组织是与您的 `/login` 相关联的组织。联系支持或使用不同的帐户登录。254* 如果未设置环境变量且错误仍然存在，则禁用的组织是与您的 `/login` 相关联的组织。联系支持或使用不同的帐户登录。

254 255 

256### Routines are disabled by your organization's policy

257 

258您的团队或企业管理员已在组织级别关闭了例程。当您尝试创建或运行例程时会出现该错误，包括从 `/schedule` 和 claude.ai/code 上的 [Routines](/zh-CN/routines) UI。

259 

260```text theme={null}

261Routines are disabled by your organization's policy.

262```

263 

264这是一个服务器端设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。

265 

266**要做什么：**

267 

268* 要求您的管理员在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用**例程**切换

269* 对于不需要组织级别例程的一次性计划工作，请参阅[计划任务](/zh-CN/scheduled-tasks)

270 

255### OAuth token revoked or expired271### OAuth token revoked or expired

256 272 

257您保存的登录不再有效。撤销的令牌意味着您在任何地方都签出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中途失败。273您保存的登录不再有效。撤销的令牌意味着您在任何地方都签出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中途失败。

289 289 

290Claude 响应后，建议会根据您的对话历史继续出现，例如多部分请求的后续步骤或工作流的自然延续。290Claude 响应后，建议会根据您的对话历史继续出现，例如多部分请求的后续步骤或工作流的自然延续。

291 291 

292* 按 **Tab** 或 **Right arrow** 接受建议，或按 **Enter** 接受并提交292* 按 **Tab** 或 **Right arrow** 将建议放入提示输入中，然后按 **Enter** 提交

293* 开始输入以关闭它293* 开始输入以关闭它

294 294 

295建议作为后台请求运行，该请求重用父对话的提示缓存，因此额外成本最小。当缓存冷时，Claude Code 会跳过建议生成以避免不必要的成本。295建议作为后台请求运行，该请求重用父对话的提示缓存，因此额外成本最小。当缓存冷时，Claude Code 会跳过建议生成以避免不必要的成本。

263 --header "Authorization: Bearer your-token"263 --header "Authorization: Bearer your-token"

264```264```

265 265 

266在通过 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 配置 MCP 服务器时，`type` 字段接受 `streamable-http` 作为 `http` 的别名。MCP 规范对此传输使用名称 `streamable-http`，因此从服务器文档复制的配置无需修改即可工作。

267 

266### 选项 2：添加远程 SSE 服务器268### 选项 2：添加远程 SSE 服务器

267 269 

268<Warning>270<Warning>

210* `Edit(//tmp/scratch.txt)`：编辑绝对路径 `/tmp/scratch.txt`210* `Edit(//tmp/scratch.txt)`：编辑绝对路径 `/tmp/scratch.txt`

211* `Read(src/**)`：从 `<current-directory>/src/` 读取211* `Read(src/**)`：从 `<current-directory>/src/` 读取

212 212 

213一个规则只匹配其锚点下的文件，因此锚点决定了 deny 规则的范围。裸文件名遵循 gitignore 语义并在任何深度匹配，因此 `Read(.env)` 和 `Read(**/.env)` 是等价的：

214 

215| Deny 规则 | 阻止 | 不阻止 |

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

217| `Read(.env)` 或 `Read(**/.env)` | 当前目录或其下的任何 `.env` | 父目录或另一个项目中的 `.env` |

218| `Read(//**/.env)` | 文件系统上任何地方的任何 `.env` | 无；规则锚定在文件系统根目录 |

219 

213<Note>220<Note>

214 在 gitignore 模式中，`*` 匹配单个目录中的文件，而 `**` 递归匹配目录。要允许所有文件访问，只需使用工具名称而不带括号：`Read`、`Edit` 或 `Write`。221 在 gitignore 模式中，`*` 匹配单个目录中的文件，而 `**` 递归匹配目录。要允许所有文件访问，只需使用工具名称而不带括号：`Read`、`Edit` 或 `Write`。

215</Note>222</Note>

423 423 

424| 字段 | 类型 | 描述 | 示例 |424| 字段 | 类型 | 描述 | 示例 |

425| :---------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |425| :---------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

426| `skills` | string\|array | 包含 `<name>/SKILL.md` 的自定义 skill 目录（替换默认 `skills/`） | `"./custom/skills/"` |426| `skills` | string\|array | 包含 `<name>/SKILL.md` 的自定义 skill 目录（除了默认 `skills/`） | `"./custom/skills/"` |

427| `commands` | string\|array | 自定义平面 `.md` skill 文件或目录（替换默认 `commands/`） | `"./custom/cmd.md"` 或 `["./cmd1.md"]` |427| `commands` | string\|array | 自定义平面 `.md` skill 文件或目录（替换默认 `commands/`） | `"./custom/cmd.md"` 或 `["./cmd1.md"]` |

428| `agents` | string\|array | 自定义 agent 文件（替换默认 `agents/`） | `"./custom/agents/reviewer.md"` |428| `agents` | string\|array | 自定义 agent 文件（替换默认 `agents/`） | `"./custom/agents/reviewer.md"` |

429| `hooks` | string\|array\|object | Hook 配置路径或内联配置 | `"./my-extra-hooks.json"` |429| `hooks` | string\|array\|object | Hook 配置路径或内联配置 | `"./my-extra-hooks.json"` |

510 510 

511### 路径行为规则511### 路径行为规则

512 512 

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)对处理多个源有不同的语义。513自定义路径是否替换或扩展 plugin 的默认目录取决于该字段：

514 

515* **替换默认值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，当清单指定 `commands` 时，不会扫描默认 `commands/` 目录。要保留默认值并添加更多，请明确列出它：`"commands": ["./commands/", "./extras/"]`

516* **添加到默认值**：`skills`。默认 `skills/` 目录始终被扫描，`skills` 中列出的目录与其一起加载

517* **自己的合并规则**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。请参阅每个部分了解多个源如何组合

518 

519对于所有路径字段：

514 520 

515* 所有路径必须相对于 plugin 根目录，并以 `./` 开头521* 所有路径必须相对于 plugin 根目录，并以 `./` 开头

516* 来自自定义路径的组件使用相同的命名和命名空间规则522* 来自自定义路径的组件使用相同的命名和命名空间规则

517* 可以将多个路径指定为数组523* 可以将多个路径指定为数组

518* 要保留默认目录并为 skills、commands、agents 或 output styles 添加更多路径，请在数组中包含默认值：`"skills": ["./skills/", "./extras/"]`

519* 当 skill 路径指向直接包含 `SKILL.md` 的目录时，例如 `"skills": ["./"]` 指向 plugin 根目录，frontmatter 中的 `name` 字段确定 skill 的调用名称。这提供了一个稳定的名称，无论安装目录如何。如果 frontmatter 中未设置 `name`，则使用目录基名作为后备。524* 当 skill 路径指向直接包含 `SKILL.md` 的目录时，例如 `"skills": ["./"]` 指向 plugin 根目录，frontmatter 中的 `name` 字段确定 skill 的调用名称。这提供了一个稳定的名称，无论安装目录如何。如果 frontmatter 中未设置 `name`，则使用目录基名作为后备。

520 525 

521**路径示例**：526**路径示例**：

22 22 

23Routines 在启用了 [Claude Code on the web](/zh-CN/claude-code-on-the-web) 的 Pro、Max、Team 和 Enterprise 计划上可用。在 [claude.ai/code/routines](https://claude.ai/code/routines) 创建和管理它们，或从 CLI 使用 `/schedule`。23Routines 在启用了 [Claude Code on the web](/zh-CN/claude-code-on-the-web) 的 Pro、Max、Team 和 Enterprise 计划上可用。在 [claude.ai/code/routines](https://claude.ai/code/routines) 创建和管理它们，或从 CLI 使用 `/schedule`。

24 24 

25Team 和 Enterprise 管理员可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 处使用 Routines 切换为所有成员禁用例程。禁用后，现有例程停止运行，成员无法创建新例程。

26 

25本页涵盖创建例程、配置每种触发器类型、管理运行以及使用限制如何应用。27本页涵盖创建例程、配置每种触发器类型、管理运行以及使用限制如何应用。

26 28 

27## 示例用例29## 示例用例

360 362 

361一次性运行不计入每日 routine 运行上限。它们像任何其他会话一样消耗您的常规订阅使用量，但它们不受每个账户每日 routine 运行配额的限制。363一次性运行不计入每日 routine 运行上限。它们像任何其他会话一样消耗您的常规订阅使用量，但它们不受每个账户每日 routine 运行配额的限制。

362 364 

365## 故障排除

366 

367### "Routines 被您的组织的策略禁用"

368 

369您的 Team 或 Enterprise 管理员可能已在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 处关闭了 **Routines** 切换。这是一个服务器端组织设置，因此无法从您的本地配置中覆盖。请联系您的管理员以请求为您的组织启用 routines。

370 

363## 相关资源371## 相关资源

364 372 

365* [`/loop` and in-session scheduling](/zh-CN/scheduled-tasks)：在打开的 CLI 会话中计划本地任务373* [`/loop` and in-session scheduling](/zh-CN/scheduled-tasks)：在打开的 CLI 会话中计划本地任务

59* **网络请求批准**：进行网络请求的工具默认需要用户批准59* **网络请求批准**：进行网络请求的工具默认需要用户批准

60* **隔离的上下文窗口**：Web fetch 使用单独的上下文窗口以避免注入潜在恶意提示60* **隔离的上下文窗口**：Web fetch 使用单独的上下文窗口以避免注入潜在恶意提示

61* **信任验证**：首次代码库运行和新 MCP servers 需要信任验证61* **信任验证**：首次代码库运行和新 MCP servers 需要信任验证

62 * 注意：使用 `-p` 标志以非交互方式运行时，信任验证被禁用62 * 注意：使用 `-p` 标志以非交互方式运行时，信任验证被禁用。例外是 [`--worktree`](/zh-CN/worktrees)，它仍然要求已接受该目录的信任

63* **命令注入检测**：即使之前已白名单，可疑的 bash 命令也需要手动批准63* **命令注入检测**：即使之前已白名单，可疑的 bash 命令也需要手动批准

64* **故障关闭匹配**：不匹配的命令默认需要手动批准64* **故障关闭匹配**：不匹配的命令默认需要手动批准

65* **自然语言描述**：复杂的 bash 命令包括用户理解的说明65* **自然语言描述**：复杂的 bash 命令包括用户理解的说明

41 </Step>41 </Step>

42 42