Skip to main content
Agent SDK セッションは、設定ファイル、環境変数、およびセッション開始時に渡す 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 リクエストパラメータ temperaturetop_p、および max_tokens には、どちらの言語でも options オブジェクトにフィールドがありません。努力レベルまたは 支出キャップを設定するか、これらのパラメータが直接必要な場合は Messages API を呼び出します。

環境変数を設定する

env オプションは、セッションを実行する Claude Code プロセスの環境変数を設定します。値が継承された環境を置き換えるか、それにマージするかは言語によって異なります:
  • TypeScriptenv はサブプロセス環境を置き換えます
  • Python:SDK は値を継承された環境にマージし、値は継承されたものをオーバーライドします
TypeScript では、process.envenv に展開して、PATHHOMEANTHROPIC_API_KEY などの継承された変数を保持します。env を設定しないままにすると、サブプロセスは両方の言語で環境を継承します。 例は、ANTHROPIC_BASE_URL を設定してゲートウェイを通じて API トラフィックをルーティングします。
渡す変数は 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_turns0 はセッションをターン制限なしで実行します。オプションを設定しないままにするのと同じです
  • maxBudgetUsd / max_budget_usd:CLI はスタートアップで 0 を無効な金額として拒否し、セッションは実行されません
サブエージェント支出を含む両方のキャップの詳細については、ターンと予算を参照してください。

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

ストリーミング入力でセッションを開始する場合、実行中にモデルと権限モードを切り替えることができます。セッターを呼び出す場所は言語によって異なります:
  • TypeScriptquery() が返すオブジェクトのメソッド
  • PythonClaudeSDKClientのメソッド。query() は制御メソッドのないプレーンイテレータを返すため
両方の言語には同じセッターがあります:
  • setModel() / set_model():モデルを切り替えます。モデルなしで呼び出して、渡した model ではなく Claude Code のデフォルトモデルに切り替えます。
  • setPermissionMode() / set_permission_mode():権限モードを切り替えます
TypeScript には applyFlagSettings()updateSettings() もあります:
  • applyFlagSettings()await session.applyFlagSettings({ effortLevel: "high" }) のように実行時に設定を適用します。メソッドは options フィールドではなく設定ファイルキーを取るため、スキーマについては applyFlagSettings() リファレンスを確認し、どのキーがセッション中に有効になるかを確認してください。
  • updateSettings()await session.updateSettings("localSettings", { outputStyle: "Explanatory" }) のように、許可リストに登録されたキーセットをプロジェクトのローカル設定ファイルに書き込みます。書き込まれたキーはセッションの次のリクエストで有効になり、local 設定を読み込む後のセッションに対して永続化されます。メソッドの行は メソッドテーブルで許可リストに登録されたキーとバージョンフロアに名前を付けます。
以下の例は 2 ターンセッションを実行し、ターン間で設定を変更し、各ターンに答えたモデルを出力します。TypeScript では、プロンプトストリームは 2 番目のメッセージをセッターが実行されるまで保持し、2 番目のターンは新しいモデルで実行されます。
Claude API では、プログラムは First turn model: claude-sonnet-5 を出力してから、切り替え後に Second turn model: claude-opus-5 を出力します。
各モデルは独自のプロンプトキャッシュを持つため、セッション中の切り替え後、次のリクエストは新しいモデルのレートでキャッシュされていない完全な会話を再計算します。詳細については、モデルの切り替えを参照してください。

特定の機能を設定する

以下の表は、各オプションをそれが設定する機能にマップします。このページでカバーされていないオプションについては、TypeScript および Python リファレンスを参照してください。目標は知っているが、どのオプションがそれを提供するかわからない場合は、正しい機能を選択するから始めてください。

次のステップ

設定を構成した作業中のエージェントを確認するには:
  • クイックスタート:最初のエージェントをエンドツーエンドで構築して実行します
  • :構築したいものと一致する完全で実行可能なプロジェクトまたはガイド付き Claude Cookbook レシピを見つけます
  • マルチテナント分離settingSources / setting_sourcesenv、および cwd で各テナントの設定とメモリを分離します