環境変数を設定する

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 は作業ディレクトリを読み込んで、以下を決定します：

• プロジェクト設定とフック：どのプロジェクトの 設定とフックが読み込まれるか
• スキル：セッションスキルが発見される場所
• セッションストレージ：保存されたセッションが属するプロジェクト

ツールが作業ディレクトリの外側のファイルに到達できるようにするには、additionalDirectories（TypeScript）または add_dirs（Python）でパスを追加します。その付与の範囲については、追加ディレクトリはファイルアクセスを付与し、設定ではないを参照してください。

ターンと支出を制限する

maxTurns / max_turns および maxBudgetUsd / max_budget_usd でターンと支出をキャップします。両方のキャップは設定しないままにすると無効です。セッションがキャップに達すると、実行は、サブタイプがキャップに名前を付ける結果メッセージで終了します。error_max_turns または error_max_budget_usd。次に何が起こるかは入力モードによって異なります：

• シングルショット query()：SDK はキャップ結果を生成してから発生するため、ループを try ブロックでラップしてエラーを超えて続行します
• ストリーミング入力：セッションはキャップ結果を超えて生きたままであり、max-turns カウントは各キューに入ったメッセージに対して開始されます。予算合計はメッセージ全体で蓄積され、支出がキャップに達すると、同じ会話の後のメッセージは同じ予算結果で終了します。/clear は予算を開始します

2 つのキャップは 0 を異なる方法で処理します：

• maxTurns / max_turns：0 はセッションをターン制限なしで実行します。オプションを設定しないままにするのと同じです
• maxBudgetUsd / max_budget_usd：CLI はスタートアップで 0 を無効な金額として拒否し、セッションは実行されません

サブエージェント支出を含む両方のキャップの詳細については、ターンと予算を参照してください。

セッション中に設定を変更する

ストリーミング入力でセッションを開始する場合、実行中にモデルと権限モードを切り替えることができます。セッターを呼び出す場所は言語によって異なります：

• TypeScript：query() が返すオブジェクトのメソッド
• Python：ClaudeSDKClientのメソッド。query() は制御メソッドのないプレーンイテレータを返すため

両方の言語には同じセッターがあります：

• setModel() / set_model()：モデルを切り替えます。モデルなしで呼び出して、渡した model ではなく Claude Code のデフォルトモデルに切り替えます。
• setPermissionMode() / set_permission_mode()：権限モードを切り替えます

TypeScript には applyFlagSettings() と updateSettings() もあります：

• applyFlagSettings()：await session.applyFlagSettings({ effortLevel: "high" }) のように実行時に設定を適用します。メソッドは options フィールドではなく設定ファイルキーを取るため、スキーマについては applyFlagSettings() リファレンスを確認し、どのキーがセッション中に有効になるかを確認してください。
• updateSettings()：許可リストに登録されたキーを設定ファイルに書き込みます。updateSettings() リファレンスは各ソースが受け入れるキーとバージョンフロアに名前を付けます。
  • "localSettings" を渡して、プロジェクトのローカル設定ファイルに書き込みます。await session.updateSettings("localSettings", { outputStyle: "Explanatory" }) のように使用します。書き込まれたキーはセッションの次のリクエストで有効になり、local 設定を読み込む後のセッションに対して永続化されます。
  • "userSettings" を渡して、このソースが受け入れる唯一のキーである effortLevel を書き込みます。Claude Code はそれをセッションの現在のモデルのデフォルト努力レベルとして保存し、実行中のセッションの努力は変わりません。

以下の例は 2 ターンセッションを実行し、ターン間で設定を変更し、各ターンに答えたモデルを出力します。TypeScript では、プロンプトストリームは 2 番目のメッセージをセッターが実行されるまで保持し、2 番目のターンは新しいモデルで実行されます。

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 で各テナントの設定とメモリを分離します