options 对象读取配置。本页面展示如何组合 options 对象以及哪些设置文件和环境变量控制配置。
有关每个选项的类型和默认值,请参阅 Options(TypeScript)和 ClaudeAgentOptions(Python)参考。
将选项传递给会话
每个query() 调用都接受一个选项对象:TypeScript 中的 Options,Python 中的 ClaudeAgentOptions。每个字段都是可选的,使用无选项启动的会话以 SDK 的默认值运行。下面的示例配置了一个只读会话,用于总结项目的开放 TODO。对中读作 TypeScript / Python,其中拼写不同:
model:选择模型allowedTools/allowed_tools:预先批准只读工具列表maxTurns/max_turns:限制轮次数cwd:设置工作目录
cwd 指向你自己的一个项目并运行示例。该项目的开放 TODO 的摘要在结果消息到达时打印。
allowedTools(TypeScript)或 allowed_tools(Python)预先批准列出的工具,因此对它们的调用无需停止等待批准即可运行。列表外的工具保持可用。当 Claude 调用未列出的工具时,权限模式决定调用是否运行。有关更多信息,请参阅允许和拒绝规则。
加载设置文件
设置文件提供超出选项对象的配置。两个选项控制它们的加载方式:settingSources/setting_sources:控制加载哪些文件系统源:用户、项目和本地。设置文件和 CLAUDE.md 文件通过这些源到达。settings:加载设置文件路径或任一语言的内联 JSON 字符串,TypeScript 也接受设置对象。无论你传递什么形式,都会覆盖用户、项目和本地文件系统设置;只有托管策略设置排名更高。参考文档在 TypeScript 的设置优先级和 Python 的设置优先级下记录了完整的优先级顺序。
[] 以禁用用户、项目和本地设置。有关更多信息,请参阅在 SDK 中使用 Claude Code 功能。
选择模型
除非model 选项、你的设置或你的环境选择了模型,否则新会话在Claude Code 的默认模型上启动。有关这些源的顺序,请参阅设置你的模型。设置 model 以固定特定模型,或选择较小的模型以获得更快、更便宜的代理。该值采用模型别名或完整模型名称;别名及其解析到的版本列在模型别名下。
设置 fallbackModel(TypeScript)或 fallback_model(Python)以命名备份模型。当主模型过载或不可用时,会话切换到备份。在每个用户轮次开始时重试主模型,因此一旦中断通过,会话就会返回到它。
在任一语言中,该选项接受单个模型或逗号分隔的备份列表。有关顺序和链上限,请参阅备用模型链。在 TypeScript 中,等于 model 的备用模型在启动时会抛出错误。
下面的示例显示 TypeScript 中的备用列表和 Python 中的单个备用:
Messages API 请求参数
temperature、top_p 和 max_tokens 在任一语言的选项对象上都没有字段。改为设置努力级别或支出上限,或在需要这些参数时直接调用 Messages API。设置环境变量
env 选项为运行你的会话的 Claude Code 进程设置环境变量。你的值是替换继承的环境还是合并到它上面因语言而异:
- TypeScript:
env替换子进程环境 - Python:SDK 将你的值合并到继承的环境上,你的值覆盖继承的值
process.env 展开到 env 中以保留继承的变量,如 PATH、HOME 和 ANTHROPIC_API_KEY。当你不设置 env 时,子进程在两种语言中都继承你的环境。
该示例通过设置 ANTHROPIC_BASE_URL 将 API 流量路由通过网关。
设置工作目录
设置cwd 以在特定目录中运行会话。当你不设置 cwd 时,会话在你的进程的工作目录中运行。两个 SDK 都没有 cwd 的设置器。要在不同目录中运行,请使用该 cwd 启动另一个会话。
Claude Code 读取工作目录以确定:
- 项目设置和 hooks:哪个项目的设置和 hooks 加载
- Skills:会话 skills 在哪里被发现
- 会话存储:存储的会话属于哪个项目
additionalDirectories(TypeScript)或 add_dirs(Python)添加路径。有关该授予的范围,请参阅其他目录授予文件访问权限,而不是配置。
限制轮次和支出
使用maxTurns / max_turns 和 maxBudgetUsd / max_budget_usd 限制轮次和支出。当未设置时,两个上限都关闭。当会话达到上限时,运行以结果消息结束,其子类型命名上限,error_max_turns 或 error_max_budget_usd。接下来发生的事情因输入模式而异:
- 单次
query():SDK 产生上限结果,然后抛出,因此将循环包装在 try 块中以继续通过错误 - 流式输入:会话在上限结果之后保持活动,最大轮次计数对每个排队的消息重新开始。预算总额在消息中累积,一旦支出达到上限,同一对话中的后续消息以相同的预算结果结束。
/clear重新开始预算
0 的处理方式不同:
maxTurns/max_turns:0在没有轮次限制的情况下运行会话,与不设置选项相同maxBudgetUsd/max_budget_usd:CLI 在启动时拒绝0作为无效金额,会话永远不会运行
在会话中途更改配置
当你使用流式输入启动会话时,你可以在它运行时切换其模型和权限模式。你调用设置器的位置因语言而异:- TypeScript:
query()返回的对象上的方法 - Python:
ClaudeSDKClient上的方法,因为query()返回没有控制方法的普通迭代器
setModel()/set_model():切换模型。不带模型调用它以切换到Claude Code 的默认模型,而不是你在选项中传递的model。setPermissionMode()/set_permission_mode():切换权限模式
applyFlagSettings() 和 updateSettings():
applyFlagSettings():在运行时应用设置,如await session.applyFlagSettings({ effortLevel: "high" })。该方法采用设置文件键而不是选项字段,因此检查applyFlagSettings()参考以了解架构以及哪些键在会话中途生效。updateSettings():将允许列表中的一组键写入项目的本地设置文件,如await session.updateSettings("localSettings", { outputStyle: "Explanatory" })。写入的键在会话的下一个请求时生效,并为加载local设置的后续会话持久化。该方法在方法表中的行命名允许列表中的键和版本下限。
First turn model: claude-sonnet-5,然后在切换后打印 Second turn model: claude-opus-5。
每个模型都有自己的提示缓存,因此在会话中途切换后,下一个请求以新模型的费率重新计算完整对话而不缓存。有关更多信息,请参阅切换模型。