設定環境變數

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 隔離每個租戶的設定和記憶