options オブジェクトから設定を読み込みます。このページでは、options オブジェクトを構成する方法と、どの設定ファイルと環境変数が制御するかを示します。
すべてのオプションの型とデフォルトについては、Options(TypeScript)および ClaudeAgentOptions(Python)リファレンスを参照してください。
セッションにオプションを渡す
すべてのquery() 呼び出しは options オブジェクトを受け入れます:TypeScript では Options、Python では ClaudeAgentOptions です。各フィールドはオプションであり、オプションなしで開始されたセッションは SDK のデフォルトで実行されます。以下の例は、プロジェクトのオープン TODO を要約する読み取り専用セッションを設定します。ペアは、スペルが異なる TypeScript / Python として読み取られます:
model:モデルを選択しますallowedTools/allowed_tools:読み取り専用ツールリストを事前承認しますmaxTurns/max_turns:ターン数をキャップしますcwd:作業ディレクトリを設定します
cwd を自分のプロジェクトの 1 つに指定して、例を実行します。そのプロジェクトのオープン TODO の要約は、結果メッセージが到着したときに出力されます。
allowedTools(TypeScript)または allowed_tools(Python)は、リストされたツールを事前承認するため、それらへの呼び出しは承認を待たずに実行されます。リストの外側のツールは利用可能なままです。Claude が未リストのツールを呼び出すと、権限モードが呼び出しを実行するかどうかを決定します。詳細については、許可と拒否ルールを参照してください。
設定ファイルを読み込む
設定ファイルは options オブジェクトを超えた設定を提供します。2 つのオプションが読み込み方法を制御します: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 には、どちらの言語でも options オブジェクトにフィールドがありません。努力レベルまたは 支出キャップを設定するか、これらのパラメータが直接必要な場合は 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 は作業ディレクトリを読み込んで、以下を決定します:
- プロジェクト設定とフック:どのプロジェクトの 設定とフックが読み込まれるか
- スキル:セッションスキルが発見される場所
- セッションストレージ:保存されたセッションが属するプロジェクト
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は予算を開始します
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():権限モードを切り替えます
applyFlagSettings() と updateSettings() もあります:
applyFlagSettings():await session.applyFlagSettings({ effortLevel: "high" })のように実行時に設定を適用します。メソッドは options フィールドではなく設定ファイルキーを取るため、スキーマについてはapplyFlagSettings()リファレンスを確認し、どのキーがセッション中に有効になるかを確認してください。updateSettings():await session.updateSettings("localSettings", { outputStyle: "Explanatory" })のように、許可リストに登録されたキーセットをプロジェクトのローカル設定ファイルに書き込みます。書き込まれたキーはセッションの次のリクエストで有効になり、local設定を読み込む後のセッションに対して永続化されます。メソッドの行は メソッドテーブルで許可リストに登録されたキーとバージョンフロアに名前を付けます。
First turn model: claude-sonnet-5 を出力してから、切り替え後に Second turn model: claude-opus-5 を出力します。
各モデルは独自のプロンプトキャッシュを持つため、セッション中の切り替え後、次のリクエストは新しいモデルのレートでキャッシュされていない完全な会話を再計算します。詳細については、モデルの切り替えを参照してください。