设置环境变量

env 选项为运行你的会话的 Claude Code 进程设置环境变量。你的值是替换继承的环境还是合并到它上面因语言而异：

• TypeScript：env 替换子进程环境
• Python：SDK 将你的值合并到继承的环境上，你的值覆盖继承的值

在 TypeScript 中，将 process.env 展开到 env 中以保留继承的变量，如 PATH、HOME 和 ANTHROPIC_API_KEY。当你不设置 env 时，子进程在两种语言中都继承你的环境。

该示例通过设置 ANTHROPIC_BASE_URL 将 API 流量路由通过网关。

const options = {
env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

options = ClaudeAgentOptions(
env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},
)

你传递的变量也可以配置 Claude Code 本身。有关 Claude Code 进程读取的变量，请参阅环境变量。要以这种方式调整 API 超时和停滞检测，请按照TypeScript 参考或Python 参考中的处理缓慢或停滞的 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()：切换权限模式

TypeScript 还有 applyFlagSettings() 和 updateSettings()：

• applyFlagSettings()：在运行时应用设置，如 await session.applyFlagSettings({ effortLevel: "high" })。该方法采用设置文件键而不是选项字段，因此检查applyFlagSettings() 参考以了解架构以及哪些键在会话中途生效。
• updateSettings()：将一个允许列表中的键写入设置文件。updateSettings() 参考命名每个源接受的键和版本下限。
  • 传递 "localSettings" 以写入项目的本地设置文件，如 await session.updateSettings("localSettings", { outputStyle: "Explanatory" })。写入的键在会话的下一个请求时生效，并为加载 local 设置的后续会话持久化。
  • 传递 "userSettings" 以写入 effortLevel，这是该源接受的唯一键。Claude Code 将其保存为会话当前模型的默认努力级别，运行中的会话的努力不会改变。

下面的示例运行一个两轮会话，在轮次之间更改配置，并打印回答每轮的模型。在 TypeScript 中，提示流保持第二条消息，直到设置器运行，第二轮在新模型上运行。

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

function userMessage(text: string): SDKUserMessage {
return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
yield userMessage("Reply with exactly: ready");
await secondTurnReady;
yield userMessage("Reply with exactly: done");
}

const session = query({
prompt: turnPrompts(),
options: {
model: "claude-sonnet-5",
},
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
if (message.type === "assistant") {
turnModel = message.message.model;
} else if (message.type === "result") {
completedTurns += 1;
if (completedTurns === 1) {
console.log(`First turn model: ${turnModel}`);
await session.setModel("claude-opus-5");
await session.setPermissionMode("acceptEdits");
startSecondTurn();
} else {
console.log(`Second turn model: ${turnModel}`);
break;
}
}
}

import asyncio

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

async def main():
options = ClaudeAgentOptions(model="claude-sonnet-5")

async with ClaudeSDKClient(options=options) as client:
await client.query("Reply with exactly: ready")
first_model = ""
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
first_model = message.model

await client.set_model("claude-opus-5")
await client.set_permission_mode("acceptEdits")

await client.query("Reply with exactly: done")
second_model = ""
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
second_model = message.model

print(f"First turn model: {first_model}")
print(f"Second turn model: {second_model}")

asyncio.run(main())

在 Claude API 上，程序打印 First turn model: claude-sonnet-5，然后在切换后打印 Second turn model: claude-opus-5。

配置特定功能

下表将每个选项映射到它配置的功能。有关本页面未涵盖的选项，请参阅TypeScript 和 Python 参考。如果你知道你的目标但不知道哪个选项服务于它，请从选择正确的功能开始。

后续步骤

要查看配置组合成工作代理：

• 快速入门：端到端构建和运行第一个代理
• 示例：找到完整的、可运行的项目或与你想要构建的内容匹配的指导 Claude Cookbook 配方
• 多租户隔离：使用 settingSources / setting_sources、env 和 cwd 隔离每个租户的设置和内存