Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

プロバイダー設定

すべてのモデルプロバイダーは [providers.models.<type>.<alias>] に配置されます。<type> は正規のファミリースロットです（各スロットとそのエンドポイントについてはカタログを参照してください）。<alias> はオペレーターが割り当てるインスタンス名で、任意のわかりやすい名前を選択できます（home、work、cn、gpt5 など）。

最小限の動作例

クリーンに読み込まれる最小構成には、4つのセクションヘッダーがあります。プロバイダーエントリ、それを参照するエージェント、そしてエージェントがゲートとして使用するリスクプロファイルです。これらはゲートウェイ、zerocode、または zeroclaw config set を通じて設定します。全フィールドのインデックスについては設定リファレンスを参照してください。

フィールドリファレンス: プロバイダーエントリ

ほぼすべてのファミリーは、ModelProviderConfig からの共有フィールドも取ります:

  • api_key: bearer 認証またはサブスクリプション形式の API キーを使用するプロバイダー向けの認証情報。
  • uri: エンドポイント全体のオーバーライド。未設定のままにすると、ファミリのエンドポイントリゾルバが使用されます。
  • model: プロバイダーに送信されるモデル識別子。
  • temperature: オプションのサンプリング温度。
  • timeout_secs: HTTP リクエストのタイムアウト(秒)。300 を超える値を設定すると、OpenAI Responses および OpenAI 互換プロバイダーにおけるストリーミングのアイドル上限(ストリーム読み取り間の待機時間に対するデフォルトの 300 秒の上限)も引き上げられます。
  • max_tokens: レスポンス長の上限（オプション）。
  • extra_headers: カスタムゲートウェイや認証ブリッジ用の追加HTTPヘッダー。
  • fallback_models: 同じプロバイダーエイリアス上の代替モデルID。
  • fallback: このエイリアスが失敗した後に試す、ドット区切りの他のプロバイダーエイリアスの順序付きリスト。
  • wire_api、native_tools、provider_extra、think、thinking_passthrough、chat_template_kwargs：高度なプロトコルおよびリクエストボディの上書き設定
  • vision: プロバイダーの画像入力（ビジョン）機能を上書きします。未設定の場合は、ファミリーに組み込まれたデフォルトを使用します。llama.cpp 経由で提供される テキスト専用モデルなど、ビジョン対応ファミリーのテキストモデルには false を設定します。これにより、画像メッセージはエラーになるのではなく、設定された [multimodal] vision_model_provider にルーティングされます。true を設定すると強制的に有効になります。ビジョンプロバイダーが設定されていない場合、最新のユーザーメッセージの画像参照のいずれも、存在チェック、データ URI の構造チェック、リモート取得ポリシーのチェックを通過しなければ、非ビジョンのターンは続行され、メディアマーカーはプレースホルダーに置き換えられます。これは、ファイルが存在しない、データ URI が不正である、または multimodal.allow_remote_fetch が無効な状態でリモート URL が指定されている場合に該当します。ローカルパスは、絶対パスであり、エージェントのファイルシステムポリシー（ファイルツールが適用するものと同じチェック）で許可されており、かつファイルとして存在する場合にのみ有効と判定されます。ポリシーで拒否されたパスは、決して存在確認の対象になりません。参照のいずれかが通過した場合、そのターンはビジョン機能エラーで失敗します。解決可能性チェックは、1ターンあたり最大 16 個の絶対ローカルパスマーカーを評価します。これらについては、ポリシーチェックと存在確認をまとめてブロッキングスレッド上で実行し、非同期エグゼキューターから切り離します。それ以上の該当マーカーを含むメッセージでは、残りは検査なしで解決可能とみなされます。これにより、過大なメッセージは黙って劣化するのではなく、ビジョン機能エラーで失敗します。
  • tool_result_image_policy: ネイティブな role = "tool" の結果を互換性のある chat-completions プロバイダーへ送信する際に、tool 結果に添付された画像の扱いを指定します。tool 結果の画像は、tool 結果のキャリア内で結果テキストと並ぶ attachments 配列によって宣言され、結果テキストから復元されることはありません。そのため、ツールの出力に含まれるリテラルのマーカー構文は単なるテキストとして扱われます。デフォルトは "image_url" で（宣言された画像を image_url パートとして送信）、"omit" に設定すると画像を削除し、固定の通知を追加します。このポリシーはネイティブなキャリアの attachments 配列のみを参照します。レガシーな tool 結果（配列キーを持たないもの）は、宣言するものがなく本文がテキストであるため、どちらの設定でもそのまま渡されます。これはユーザーが直接送信した画像や OpenAI Responses プロバイダーには影響しません。
  • cache_passthrough: Anthropic Messages API に変換するチャット補完ゲートウェイで Anthropic のプロンプトキャッシュを有効にします。リクエストごとに最大2つの cache_control ブレークポイントを追加し、ゲートウェイが報告するキャッシュ読み取りをトークン使用量に表示します。デフォルトは false で、リクエストは変更されません。本番環境で使用する前にルートの検証が必要です。詳細は Prompt cache passthrough を参照してください。
  • cache_ttl: Anthropicのプロンプトキャッシュマーカーに要求するキャッシュエントリの有効期間。"5m"（デフォルト）または"1h"。ネイティブのAnthropicプロバイダーに直接適用され、cache_passthrough経由のチャット補完ゲートウェイにも適用されます。passthroughがない場合は効果がありません。独自の方法でキャッシュマーカーを出力するプロバイダー（openrouter）はこの設定を無視します。1時間キャッシュ期間の選び方を参照してください。
  • tls_ca_cert_path: このプロバイダーへの TLS 接続に使用する PEM エンコードされた CA 証明書への絶対パス（プロバイダーごとの信頼のオーバーライドで、ゲートウェイの TLS ca_cert_path とは別のもの）。~ などのシェル展開は行われません。システムの信頼ストアを使用する場合は未設定のままにしてください。

ファミリー固有のエントリは、これらの共有フィールドの上に独自の型付きフィールドを追加します。

Anthropic 思考パススルー

thinking_passthrough = true を OpenAI 互換プロバイダーのエントリーに設定すると、そのエイリアスは Anthropic の 拡張思考パススルー が有効になります。ランタイムの思考予算がゲートウェイへ転送され、ゲートウェイからの思考レスポンスは再生可能な署名付きブロックに正規化され、署名付きブロックは送信する履歴に再生されます。

このフラグを使う前に、ゲートウェイが Anthropic Messages エンドポイントも公開しているかを確認してください。公開している場合は、uri を使って [providers.models.anthropic.<alias>] エントリをそのエンドポイントに向けてください。ネイティブプロバイダーは、変換なしで thinking、署名付きブロックの再送、プロンプトキャッシュを処理します。thinking_passthrough は、Chat Completions のインターフェースしか提供していないゲートウェイ向けです。

[providers.models.custom.my-gateway]
uri = "https://your-gateway.example.com"
model = "claude-group/claude-fable-5"
api_key = "..."
wire_api = "chat_completions"
thinking_passthrough = true

何をするものか

  • リクエスト側: ランタイムがネイティブの thinking パラメータを提供する場合、リクエストボディのトップレベルに Anthropic 形式のオブジェクトが追加されます: {"thinking": {"type": "enabled", "budget_tokens": N}}。明示的な provider_extra キーは、注入されたオブジェクトより常に優先されるため、エスケープハッチを通じてカスタム形式を固定できます。temperature と max_tokens の正規化は、実際に送信されるオブジェクトに従います。そのため、明示的な {type = "off"} を指定すると temperature と上限値は維持され、独自の budget_tokens を持つ明示的な enabled オブジェクトを指定すると、max_tokens はその budget を超えるよう引き上げられます。thinking オブジェクトが注入される場合、Anthropic の要件に従ってリクエストの temperature は 1.0 に設定されます。明示的な temperature は thinking が off の場合にのみ適用されます。固定の thinking budget が注入される場合も同様に、Anthropic の要件に従って、設定された上限値が budget 以下であれば max_tokens は budget_tokens + 1 に引き上げられます。
  • キャプチャ: ゲートウェイの思考レスポンスは、ネイティブ Anthropic プロバイダーが reasoning_content に保存するものと同じ、改行区切りの署名付き JSON 形式に正規化されます（ブロックごとに 1 行の {"thinking": ..., "signature": ...}）。署名のみのブロック（テキストは空で署名は有効、TrueFoundry が出力する形式）は保持されます。フラグがオフの場合、ゲートウェイの reasoning_content / thinking_blocks レスポンスは従来どおりに流れるため、DeepSeek/GLM/Qwen の推論動作は変わりません。
  • リプレイ: 署名付きの履歴から、送信されるアシスタントメッセージ上の thinking_blocks 配列を再構築し、文字列フィールドを抑制します。この再構築は全か無かの方式です。以下の制限事項を参照してください。replay_assistant_reasoning = false の上書き設定は引き続き優先されます。推論入力を拒否するプロバイダーには、どのフラグの組み合わせでも何も送信されません。

要件と制限事項

  • translating gateway が必要です。 このフラグは、OpenAI Chat Completions と Anthropic Messages API の間で変換を行う OpenAI 互換エンドポイントでのみ有効です(この変換は LiteLLM でも文書化されており、この形式は実際の TrueFoundry gateway で検証済みです)。変換を行わないアップストリームに向けた場合、注入される thinking オブジェクトは未知のパラメータとなり、リクエストは HTTP 400 で失敗します。これは意図された失敗モードです。最初のリクエストで大きく失敗し、黙って失敗することはありません。
  • 署名のない thinking はリプレイを無効にする。 Anthropic が入力として受け付ける thinking ブロックには、有効な署名が必要です。推論が署名されていない履歴（ストリーミングされたテキスト、または署名を除去するゲートウェイ経由のもの）では、ゲートウェイに拒否される可能性のあるブロックを捏造するのではなく、推論を一切送信しません。解析できない行や署名のない thinking 行が一つでもあれば、そのメッセージ全体のリプレイを無効にします（部分的なシーケンスは送りません）。構造的に無効な redacted_thinking ブロック（data ペイロードがないもの）は個別に省略し、有効な兄弟ブロックはリプレイします。取り込み時に許可されるブロックのホワイトリストは正確に次のとおりです。thinking（text および／または signature が必須）と redacted_thinking（不透明な data が必須。設計上そのまま、署名なしでリプレイされます）。ゲートウェイが出力するその他のブロック種別は取り込み時にスキップされ、リプレイ時には決して転送されません。プロンプトガイド方式のフォールバック経路も同じ検証済みブロックをリプレイするため、二度目のスキーマフォールバックが署名付きの推論の流れを失わせることはありません。
  • ネストされたコンテンツブロックは取得されません。 読み取られるのはトップレベルの reasoning_content、reasoning、thinking_blocks フィールドのみです。content 配列内にネストされた Anthropic 形式のブロックは取得されません。ゲートウェイがそのようなブロックを出力する場合は、ワイヤーサンプルを添えて issue を起票してください。
  • パススルーはリーフでストリーミングを無効化します。 キャプチャの正規化は非ストリーミングのレスポンスに適用され、ゲートウェイの SSE thinking フレームは検証されていない領域であるため、プロバイダーは自身を非ストリーミングとして報告します。このプロバイダーが提供元の場合、ツールループ全体が非ストリーミングのワイヤー上で実行され、そこでは署名付きキャプチャとリプレイが正しく機能します。境界ケースは2つあります。このプロバイダーを解決するルーターは非ストリーミングのパスをディスパッチし、標準のストリームイベントを合成します。また、ストリーミング対応のフォールバックを含む信頼性ドメインは、そのフォールバックでターンを処理することがあります（標準のフォールバック通知が表示されます）。そのため、すべてのターンをオプトインしたプロバイダーで処理する必要がある運用者は、すべてが非ストリーミングのドメインを設定してください。リーフでのターンごとのストリーミングは、ワイヤーファーストのストリーミングサポートが導入された時点で再開されます。
  • 思考形状はネイティブプロバイダーのスタイル解決に従います。 注入されるオブジェクトは、固定予算モデルでは {"type": "enabled", "budget_tokens": N}、adaptive専用モデル（Opus 4.7、Fable 5ファミリー全体）では予算キーのない {"type": "adaptive"} になります。ゲートウェイのモデルIDには claude-group/... のようなルーティング用プレフィックスが付くことがあります。解決は部分文字列で照合されるため、プレフィックス付きのIDも裸の名前と同じ形状に解決されます。ランタイムが表示モードを要求した場合、スネークケースの display キーは両方の形状に付与されます（omitted、updates、summarized）。表示モードが要求されていない場合、display キーは完全に省略されます。
  • エスケープハッチ: この機能がカバーしていない形式については、provider_extra が依然として任意のトップレベル JSON をすべてのリクエストボディにマージします。静的な thinking オブジェクトも含まれ、自己責任で使用してください。レスポンス処理は行われません。

関連項目も参照してください

  • Anthropic プロバイダーでのネイティブ拡張思考: #10542。
  • Request-body のエスケープハッチ: 上記の provider_extra; reference。

フィールド解決順序

ほとんどのファミリーでは、URL は次の順序で解決されます:

  1. 演算子による上書き: エイリアスエントリの uri フィールド（設定されている場合）。
  2. Family endpoint: ファミリーの *Endpoint 列挙型が URL を提供します（例: OpenAIEndpoint::Default -> https://api.openai.com/v1）。マルチリージョンのファミリーでは、エイリアスエントリに endpoint フィールドがあり、バリアントを選択します（例: Moonshot の場合は endpoint = "cn"）。
  3. テンプレート化されたファミリ: Azure は型付き入力（resource、deployment、api_version）を受け取り、それらをファミリの URI テンプレートに代入します。フィールドが欠落している場合は、実行時にエラーになります。

BedrockはAWSクレデンシャルチェーン（AWS_REGION、AWS_DEFAULT_REGION、またはアクティブなcredential_processやIMDSプロファイルのregion）を通じて解決された署名リージョンからリクエスト時にエンドポイントのホスト名が構築されるという例外があります。uriエイリアスフィールドおよびスキーマレベルのproviders.models.bedrock.<alias>.regionフィールドは、現在の実装では効果がありません。

ファミリースロット

すべてのスロット、そのデフォルトエンドポイント、ローカルで実行されるかどうかは、Catalog に記載されています。ベンダーごとに正規のキーが1つあります。同義語はありません。

認証情報

サポートされている認証情報の入力および保存形式：

  1. エイリアスエントリ内のインライン api_key = "..."（開発用には問題ありませんが、チェックインされた設定ではリスクがあります）。
  2. 1Password 参照: シークレットフィールドに op://vault/item/field を設定します。ZeroClaw は参照を config に保持し、実行時に op read で解決するため、1Password CLI がインストールされサインインされている必要があります。
  3. 設定レベルのシークレットストア: ローカルのキーファイルを使用して ~/.zeroclaw/secrets で暗号化されます。
  4. 汎用的な環境変数オーバーライド: ZEROCLAW_providers__models__<type>__<alias>__api_key=... は起動時に providers.models.<type>.<alias>.api_key を設定します。完全な文法については 環境変数 を参照してください。

スキーマミラーの環境変数オーバーライドは起動時に優先されます。これらはディスク上に保存されたインライン値、暗号化された値、または op:// 値を書き換えることなく、そのプロセスのメモリ内の認証情報を置き換えます。

zeroclaw quickstart はデフォルトで認証情報をシークレットストアに書き込みます。コミットする設定ファイルには、インラインのキーを含めないでください。シェルですでにエクスポートしているエコシステム標準の名前（$ANTHROPIC_API_KEY、$OPENROUTER_API_KEY など）については、env-vars リファレンスに、スキーマミラー名を既存の値に向ける1行の bash 展開が示されています。

OAuth とサブスクリプション認証

いくつかのプロバイダーは、生のAPIキーの代わりにOAuthまたはサブスクリプション形式のトークンを受け付けます。ベンダー独自のダッシュボードまたはCLIフローからトークンを取得し、APIキーと同じ方法でエイリアスエントリに設定してください:

  • Anthropic / Claude: Claude Max 用の claude setup-token で生成された Console API キーとトークンは、[providers.models.anthropic.<alias>] の api_key に設定します。クイックスタートでは api_key または setup_token を選択してください。保存されたプロバイダーエントリは、引き続き正規の anthropic スロットです。
  • OpenAI Codex サブスクリプション: zeroclaw auth login --model-provider openai-codex を実行する（または --import ~/.codex/auth.json で既存の Codex CLI ログインをインポートする）。次に [providers.models.openai.<alias>] で requires_openai_auth = true を設定し、api_key は未設定のままにする。ランタイムは ZeroClaw に保存された openai-codex 認証プロファイルを読み取ります。
  • Gemini CLI: [providers.models.gemini_cli.<alias>] は gemini CLI を呼び出します。CLI 自体の認証フローを使用してください。
  • Grok Build CLI: [providers.models.grok_cli.<alias>] は、文書化された grok agent stdio ACP インターフェース経由で外部コマンドを実行します。組み立てられたプロンプトは stdin 上の JSON-RPC であり、argv やプロンプトファイル経由ではありません。認証にはデフォルトで CLI のログインキャッシュが使用されます。API キー認証では、デーモン環境に XAI_API_KEY をエクスポートし、エイリアスに env_passthrough = ["XAI_API_KEY"] を明示的に追加します。型付きエイリアス api_key は引き続きサポートされません。存在する絶対パスの working_directory が必要で、子プロセスの cwd と ACP セッション境界の両方を定義します。子プロセスの環境は起動前にクリアされ、env_passthrough のデフォルトは空です。他のプロバイダー所有の XAI_* 名とすべての GROK_* 名は拒否されます。ZeroClaw のデフォルトは --sandbox strict、--permission-mode dontAsk、空の組み込みツールセット、およびフェイルクローズの ACP 権限応答です。extra_args は、これらの制御を緩和するための明示的なエイリアスごとのオプトインです。バイパスフラグ --always-approve、--dangerously-skip-permissions、--yolo、および --permission-mode=bypassPermissions により、ヘッドレス ACP クライアントは allow_once を選択します。それ以外の権限モードでは引き続き reject_once が選択されます。ACP のトランスポート、モデル、セッション、cwd に関するフラグに加え、位置引数と短形式の引数は予約されています。値を受け取る未知のロングオプションには --flag=value を使用します。エイリアスの vision = true は、ZeroClaw による ACP 画像ブロックの送信をオプトインするだけです。Grok は 0.2.118 まで promptCapabilities.image = false を引き続き通知し、画像コンテンツを確実には使用しません。本番環境では未設定のままにしてください。ACP ビジョン / 画像入力を参照してください。
  • Qwen / MiniMax: エイリアスエントリに auth_mode = "o_auth" を設定し、関連する oauth_* フィールドも設定します（env-vars → OAuth と CLI パスのフィールド を参照）。

OpenAI Astra セットアップ

OpenAIの公開APIのモデルIDはgpt-6-astraです。モデルガイドでは、ツール呼び出しにはResponses APIが必要であり、temperatureは非対応パラメーターの一覧に含まれていると記載されています。APIキーと明示的なResponses wireを指定して、openaiエイリアスで公開APIのルートを設定してください:

[providers.models.openai.astra_api]
api_key        = "op://platform/openai/api-key"
model          = "gpt-6-astra"
wire_api       = "responses"
vision         = true
context_window = 1050000
max_tokens     = 32000

[runtime]
reasoning_effort = "high"

[runtime_profiles.astra]
agentic             = true
max_tool_iterations = 12
max_history_messages = 80
max_context_tokens  = 200000

[agents.astra]
model_provider  = "openai.astra_api"
runtime_profile = "astra"
risk_profile    = "supervised"

上記の数値は、モデルの公称ウィンドウを埋めることを推奨するものではなく、意図的に設定したローカルの予算です。プロバイダーエントリはエンドポイントの機能と出力上限を記録し、ランタイムプロファイルはより小さい推定入力予算を保持して、ツールループを制限します。ワークロードに応じて調整し、出力の余裕を残してください。各フィールドには、それぞれ別の所有者がいます：

  • providers.models.openai.astra_api.context_window は、プロバイダー対応の予算管理で使用されるモデル入力ウィンドウを記録します。
  • providers.models.openai.astra_api.max_tokens は生成される出力を制限するものであり、入力履歴の上限ではありません。
  • runtime_profiles.astra.max_context_tokens は ZeroClaw におけるローカルのトリミング閾値の推定値です。context_window より小さくなる場合があります。
  • runtime_profiles.astra.max_tool_iterations は、エージェントのツールループを制限します。一方、max_history_messages は、ツールのやり取りを含めて保持される完全なユーザーターンの数を別途制限します。チャンネル送信者キャッシュは、行数ベースの独自の上限を引き続き保持します。
  • runtime.reasoning_effort は、プロバイダー向けのグローバルな推論レベルです。ZeroClaw は現在 minimal、low、medium、high、xhigh を受け付けます。Astra の公開 API は low、medium、high、xhigh、max を受け付けるため、max reasoning support が対応されるまでは共通の値を使用してください。

Astraではプロバイダーのtemperatureを設定しないでください。Responsesアダプターは設定された値をそのまま転送し、サポートされていないサンプリングパラメーターを修正することはありません。APIの検証エラーと、アカウント、利用ティア、リージョン、またはバックエンドへのアクセス制限は、区別して扱ってください。

vision = true は、このモデルとエンドポイントが画像入力を受け付けることをオペレーターが保証する設定です。Astra モデル仕様では現在画像入力がサポートされていると記載されていますが、有効にする前に、設定済みのアカウントとエンドポイントを必ず確認してください。ツール結果の画像シリアライズは別のアダプター境界の問題であり、#9599 で追跡されています。

Codex サブスクリプションのルートでは、API キーの代わりに requires_openai_auth = true を使用し、そのバックエンドが提供する正確なモデル ID を指定する必要があります。公開 API で利用可能であっても、Codex バックエンドで利用できるとは限りません。Codex サブスクリプションガイドに従い、本番トラフィックをルーティングする前にアカウントをテストしてください。

公開APIは、このアダプターでZeroClawがまだ公開していない機能をサポートしている場合があります。推論状態の継続性は #10706、非同期の関数ツールは #10704、アクティブ応答のステアリングは #10708、プログラムによるツール呼び出しは #10707 で追跡してください。ZeroClawでの実装とプロバイダーのルートが検証されるまで、これらは提案段階のものです。

コンテナフレンドリーなオーバーライド

ZeroClaw をコンテナ内で実行し、プロバイダーがホスト上にある場合（例: Ollama）は、uri をホストから到達可能なアドレスに設定してください。汎用の環境変数オーバーライド機構（ZEROCLAW_<dotted_path_with_double_underscores>=<value>）を使えば、設定を編集せずに実行時に同じフィールドを設定できます:

sh

ZEROCLAW_providers__models__ollama__home__uri=http://ollama:11434 zeroclaw agent -a assistant

__ はパス区切り文字です。上記の例では providers.models.ollama.home.uri を設定しています。完全な文法については 環境変数 を参照してください。

モデルごとのビジョン機能

vision は、あるプロバイダーファミリーがマルチモーダルモデルとテキスト専用モデルの両方に対応できる場合に使用します。この値はプロバイダーエイリアスに属するため、ルーティングおよびフォールバックのパスでは、そのエイリアスのエンドポイント、認証情報、モデルとともに解決されます。

[providers.models.openai.vision]
model = "gpt-4o"
wire_api = "responses"
vision = true

[providers.models.llamacpp.text]
model = "qwen3-4b"
vision = false

vision を未設定のままにすると、プロバイダーファミリーの組み込みデフォルトが保持されます。OpenAI Responses のエイリアスでは、画像入力を受け付けるモデルに対して vision = true を設定してください。このオプトインにより、テキストのみの Responses モデルが誤って画像ペイロードを受け取ることを防ぎます。

vision = true の設定は、選択したエイリアスが画像入力を受け付けるという、オペレーターによる明示的なアサーションです。これにより画像のルーティングが変わります。ZeroClaw は画像添付をテキスト専用として扱ったり multimodal.vision_model_provider にルーティングしたりせず、そのエイリアスに保持します。テスト済みのプロバイダーとモデルの組み合わせに対してのみ設定してください。grok_cli では、同じフィールドは ZeroClaw が ACP 画像ブロックを 送信するかどうかだけを制御します。Grok の promptCapabilities.image のアドバタイズ内容を書き換えるものではなく（0.2.118 までは引き続き false）、CLI が画像を確実に説明するようになるわけでもありません。ACP ビジョン / 画像入力を参照してください。

[multimodal] vision_model_provider がドット区切りのプロバイダーエイリアスを指定している場合、その model が自動的に使用されます。明示的な [multimodal] vision_model はエイリアスのモデルより優先されます。どちらも設定されていない場合は、後方互換性のためにプライマリターンモデルが使用されます。

ネイティブ思考表示 (Anthropic)

agent.thinking.display は、ネイティブ思考が有効な場合（agent.thinking.native_thinking = true）に Anthropic の拡張思考をどのように配信するかを制御します。指定可能な値:

  • off（デフォルト）: display フィールドは送信されません。リクエストは以前の ZeroClaw バージョンとバイト単位で同一で、推論リクエストでは非ストリーミングのフォールバックが使用されます。
  • omitted: Anthropic はレスポンスから思考テキストを省略します。ブロックは署名のみ（空の thinking、必須の署名）で届き、表示される推論を最小限に抑えながらリプレイを完全な状態に保ちます。
  • updates: リクエストには thinking-display-updates-2026-08-18 ベータが含まれ、ストリーミング応答パスが使用されます。モデルの処理中、読みやすい思考の進行状況がリアルタイムで表示されます。署名付き推論ペイロードは履歴の再生用に別途保持され、表示されることはありません。
  • summarized: 同じストリーミング動作で、思考の要約をリクエストします。
[agent.thinking]
native_thinking = true
display = "updates"

この設定には、thinking-display-updates ベータ版に登録された Anthropic アカウントが必要です。登録されていない場合、API はリクエストを拒否します。以前のワイヤー動作に戻すには、display = “off” を設定するか、フィールドを削除してください。

Prompt cache のパススルー（chat-completions ゲートウェイ向け）

cache_passthrough = true をchat-completionsプロバイダーのエイリアスに設定すると、そのプロバイダーへのリクエストでAnthropicのプロンプトキャッシュが有効になります。Chat CompletionsをAnthropic Messages APIに変換するゲートウェイ（LiteLLM、TrueFoundryなど）で使用してください。ネイティブのAnthropicプロバイダーファミリーはデフォルトでキャッシュを行い、このフィールドは無視されます。

このフラグを使う前に、ゲートウェイが Anthropic Messages エンドポイントも公開しているか確認してください。公開している場合は、[providers.models.anthropic.<alias>] エントリをそのエンドポイントに向けて uri を指定し、パススルーは省略してください。ネイティブプロバイダーが独自のブレークポイントを配置します。cache_passthrough は Chat Completions インターフェースしか提供していないゲートウェイ向けです。

フラグが有効な場合、リクエストには最大2つの cache_control ブレークポイントが追加されます。1つ目はシステムプロンプトに設定されます。2つ目は、システム以外のメッセージが1件より多くなった時点で最後のメッセージに設定される移動式（ローリング）ブレークポイントです。これはネイティブの Anthropic プロバイダーが適用する条件と同じです。末尾が画像で終わるメッセージでは、ローリングブレークポイントはそのメッセージの最後のテキストブロックに設定されます。画像は次のターンでカバーされます。

merge_system_into_user を使用すると、system ロールはワイヤー上に送信されません。そのため、統合された最初のユーザーメッセージ（またはシステムテキストを持つ合成ユーザーメッセージ）が、システム相当のブレークポイントを持ちます。シリアライズが変わるのは、ブレークポイントを持つメッセージだけです。

この フラグは、構造化リクエストのパス、つまりエージェントのターン、ツール呼び出し、構造化ストリーミングにも適用されます。テキストのみのヘルパー(chat_with_system、chat_with_history、従来のチャンクストリーム API)は、フラグがオンでも意図的にブレークポイントを出力しません。これらはトークン使用量を一切返さないため、それらが発生させたプレミアムのキャッシュ書き込みが課金情報に表示されないからです。これらのヘルパーでは、フラグは効果がありません。そのため、これらを経由するフォールバックの再入も、マーク付けされていないリクエストを送信することになります。フラグがオフ(デフォルト)の場合、リクエストボディは以前のバージョンとバイト単位で同一です。

[providers.models.custom.claude-via-gateway]
uri = "https://<gateway-host>/v1"
model = "<anthropic-routed model>"
api_key = "op://platform/gateway/api-key"
cache_passthrough = true

要件と注意事項：

  • ゲートウェイのサポートが必要です。 ブレークポイントが Anthropic に届くのは、ゲートウェイがブロック形式の内容と cache_control をネイティブの Messages API に転送する場合のみです。OpenAI API そのものをプロキシするルートではこのフィールドは無視されます。同じゲートウェイ配下の Anthropic 以外にルーティングされるモデルでは、エラーは発生しません。フィールドは受け入れられた上で破棄され、ゲートウェイがそのルートについて独自の使用量計測でキャッシュ書き込みトークンを計上する場合があります。Anthropic にルーティングされるモデルには、混在するエントリでフラグを有効にするのではなく、専用のエイリアスを割り当ててください。
  • サイズとTTL。 Anthropicがキャッシュするのは、少なくとも1024トークン(一部の小規模モデルでは2048トークン)以上のプレフィックスのみで、エントリは約5分後に期限切れになります。ただし読み取りのたびに更新されます。短い会話や頻度の低い会話では効果は得られません。キャッシュの有効期間はプロバイダーごとにcache_ttlで設定できます。詳細は1時間キャッシュ期間の選択を参照してください。
  • 書き込みはプレミアム料金で課金されます。 キャッシュに書き込まれたトークンは入力価格に対してプレミアム料金で課金され、観測されたルートでは5分のデフォルトの書き込みが1.25倍で課金されます。1時間の有効期間内の書き込みは別のレートで課金される場合があります。計画用の数値については1時間キャッシュの有効期間の選択を参照してください。読み取りは大幅に割引された価格で返されます。キャッシュへの書き込みは行うがまったく読み取られないルートは、キャッシュをまったく使用しない場合よりもコストが高くなります。
  • 実際の経路を先に検証する。 ゲートウェイは同じ上流アカウントに対して多数のモデルエイリアスを公開しており、キャッシュ書き込みを受け付けて課金するエイリアスであっても、キャッシュ読み取りは決して提供しない場合があります。本番環境でフラグに依存する前に、フラグ付きリクエストを1回送信し、usageに cache_creation_input_tokens > 0 が含まれることを確認してください。その直後にバイト単位で同一のリクエストを再送信し、cache_read_input_tokens > 0 を確認します。キャッシュ作成だけではキャッシュが機能している証拠にはなりません。モデルエイリアスまたはゲートウェイ経路を変更するたびに、このペアを再実行してください。
  • 使用量レポート。 ゲートウェイがAnthropic形式の使用量カウンターを転送する場合、cache_read_input_tokensはトークン使用量とコストレポートのキャッシュ入力量を埋め、cache_creation_input_tokensはデバッグログにカウントのみ書き込まれます。キャッシュ読み取りがゼロと報告されたレスポンスでは、OpenAI形式のカウンターに置き換えず、キャッシュ量はゼロのままになります。この会計処理は構造化パスのみを対象としており、それが上記で使用量キャプチャのないヘルパーが動作しない（inert）理由です。
  • ツール定義は個別にマークされません。 ネイティブの Anthropic プロバイダーは、さらに最後のツール定義にもマークを付けます。これは、システムプロンプトがない場合にツールスキーマのトークンをカバーします。このフラグはツール定義をマークしません。ツールはあるがシステムプロンプトがないリクエストでは、ローリングのメッセージブレークポイントのみがキャッシュされます。ライブゲートウェイの検証では、システムプロンプトが存在する場合、ツールスキーマのトークンは結局キャッシュされたプレフィックス内に含まれることが示されました。

1時間のキャッシュ有効期間を選ぶ

cache_ttl = "1h" は、このプロバイダーのマーカーが作成するキャッシュエントリの有効期間を、デフォルトの5分ではなく1時間に指定します。会話が前回のリクエストから5分以上経過して再開されることが頻繁にある場合に使用してください。そうしないと、再開されるターンのたびに、より長い有効期間であれば保持されていたはずのプレフィックスについて、全額料金のキャッシュ再書き込みが発生します。

損益分岐の計算です。P はプレフィックスの基本入力価格です。5 分のキャッシュ書き込みは 1.25P、1 時間の書き込みは 2P かかるため、1 時間の有効期間を選ぶと、キャッシュ書き込みごとに 0.75P 多くかかります（ヒットするとエントリの有効期間が更新されるため、割増料金は時間単位ではなく書き込みごとに発生します）。長い有効期間によって回避できる期限切れごとに、1.25P から 0.1P の読み取り料金を差し引いた約 1.15P が節約されます。140k トークンのプレフィックスを入力単価 $10/M で計算すると、P は $1.40 です。1 時間の書き込みごとに約 $1.05 の追加の書き込み割増料金がかかり、回避された期限切れごとに約 $1.61 が節約されます。したがって、最初に回避された一時停止では正味約 $0.56 の節約となり、それ以降の一時停止ではそれぞれ正味 $1.61 の節約となります。節約効果には上限があります。節約が生じるのは、5 分より長く 1 時間より短い間隔を空けてプレフィックスが再利用される場合です。1 時間を超える間隔の後では、節約はなく、2 倍の書き込み料金が再び発生します。書き込み割増料金に加えて、1 時間の有効期間では、追加されるテールごとに小さなコストが加わります。数千トークンに 0.75 を掛けて入力単価を掛けた額で、その単価で数千トークンのテールの場合、ターンごとに 2～3 セントです。（0.1 倍の読み取り単価は一般的な値ですが、モデルによって異なる場合があるため、対象のモデルについては Anthropic のプロンプトキャッシュの料金表を確認してください。）5 分から 1 時間の間で一時停止する会話では "1h" が有利です。アクティブな状態が続く会話、すぐに終わる会話、または 1 時間を超えて一時停止する会話では、デフォルトが有利です。

Anthropic の名目上の 2 倍のキャッシュ書き込み価格を前提に計画してください。API の前段に置かれたゲートウェイは、1h のキャッシュ書き込みを独自のレートで課金する場合があります。台帳は、設定済みまたはライブの cache_write_per_mtok レートが存在する場合はそのレートでキャッシュ書き込みを計算し、カタログのフォールバックのみが適用される場合（カタログに書き込みレートが含まれていない場合）は通常の入力レートで計算します。cache_ttl は書き込みレートを選択しません。エントリを "1h" に変更するオペレーターは、そのルートが実際に課金する金額に合わせてプロバイダーの書き込みレートを設定してください。

ライブルートの認定試験で得られた2点の注意事項です。5分を超える生存は、6分と49分の2回で実証されました。1時間の完全な有効期間は測定していません。また、この実装が生成するすべてのマーカーには1つのTTLが適用されます。ネイティブのAnthropicプロバイダーのsystem、tool、ローリングメッセージのマーカーと、互換パススルーのブレークポイントは、いずれも設定された有効期間を持ちます。オペレーターが指定したcache_control（provider_extraのボディフィールドまたは生のツールJSON経由）は、この保証の対象外です。1つのリクエスト内で有効期間が混在する場合は、Anthropicの順序規則（1時間のマーカーを5分のマーカーより前に置く）を満たす必要があります。

[providers.models.custom.claude-via-gateway]
uri = "https://<gateway-host>/v1"
model = "<anthropic-routed model>"
api_key = "op://platform/gateway/api-key"
cache_passthrough = true
cache_ttl = "1h"

On ネイティブの Anthropic エントリでは、cache_passthrough なしで同じキーが動作します:

[providers.models.anthropic.direct]
model = "claude-sonnet-4-5"
cache_ttl = "1h"

画像入力の上限

[multimodal] は、チャネルの添付ファイル、ツールが宣言する添付ファイル、Webダッシュボードからのアップロードなど、発生源を問わずリクエストパイプラインに入るすべての画像に上限を設けます。

[multimodal]
max_image_size_mb = 20   # per image, decoded bytes (default: 20, clamped to 1-20)
max_images        = 4    # most images kept per request (default: 4, clamped to 1-16)

max_image_size_mb は base64 エンコード前の値で測定されるため、プロバイダーに届くペイロードはおよそ3分の1大きくなります。20 MiB の上限は、対応するビジョン API 全体で最も低い画像単位またはリクエスト単位の上限であり、画像は丸ごとバッファリングされるため、アップロードごとのゲートウェイのメモリ使用量も抑えます。ターンごとのアップロードコストを抑えるには、この値を下げてください。

プロバイダーは、この設定に加えて独自の上限を適用します。Anthropicは、base64エンコード後で10 MBを超える単一の画像を拒否します。これはデコード後のおよそ7.5 MiBに相当します。同社のクライアントは、max_image_size_mb で許可されている値に関係なく、この制限を適用します。モデルのコンテキストコストはバイト数に比例しません。プロバイダーは画像をラスタライズし、ピクセルの寸法に基づいて課金するため、同じ解像度であればファイルサイズが大きくても小さくても、コストはほぼ同じになります。

max_images は、会話に残っているすべての画像を数えます(新しい画像だけではありません)。そのため長いセッションでは上限に達します。上限を超えると、古い画像が一度にまとめて削除され、上限の半分を切り上げた数(4 なら 2、16 なら 8)まで減ります。その後、次のバッチが処理されるまで画像数は上限まで再び増えていきます。画像を削除すると、それより前のメッセージが変わるため、プロバイダーのプロンプトキャッシュはそのメッセージ以降から再構築されます。バッチ処理により、これは新しい画像1枚ごとではなく max_images / 2 + 1 枚ごとに一度だけ発生します。バッチ直後は、モデルが参照できる古い画像は上限が許す数より少なくなります。スクリーンショットを多用するセッションでは上限を引き上げてください。

ファミリーごとの調整: 実例

Ollama

Ollama はデフォルトでローカルエンドポイントを使用するため、ローカルエイリアスにはモデル名のみが必要です:

[providers.models.ollama.local]
model = "llama3.1"

ZeroClaw が Ollama と同じホスト上で実行されていない場合は uri を設定してください:

[providers.models.ollama.host]
model = "llama3.1"
uri = "http://host.docker.internal:11434"

Ollama 固有のオプションフィールドは num_ctx、num_predict、および temperature_override です。

Hailo-Ollama

Hailo-Ollamaは、ネイティブAPIがOllamaより厳密なリクエスト形式を必要とするため、専用のhailo_ollamaスロットを使用します。ローカルインスタンスのデフォルトはhttp://localhost:8000で、モデルの検出はそのライブな/api/tagsレスポンスを読み取って行います。

[providers.models.hailo_ollama.edge]
model = "qwen3:1.7b"
context_window = 2048
max_tokens = 256
timeout_secs = 90
queue_timeout_secs = 30

設定 uri には、別のホストで実行されている Hailo-Ollama のベース URL を指定します。URL は http または https を使用する必要があり、認証情報、クエリ、フラグメントを含めることはできません。エイリアスの api_key は Bearer Authorization ヘッダーとして送信され、extra_headers はネイティブのチャットリクエストとカタログリクエストの両方に転送されます。api_key と明示的な Authorization の extra header を両方設定しないでください。ZeroClaw は、この曖昧な認証情報の組み合わせを拒否します。複数のエイリアスが同じエンドポイントを対象としている場合でも、正規化されたエンドポイントごとに同時に実行されるリクエストは 1 件に制限され、queue_timeout_secs を超えてキューに入ったリクエストは拒否されます。

ループバック以外のエンドポイントでは、平文の http はプロンプトと応答をトランスポート暗号化も認証もなしに送信します。ネットワークが信頼できる隔離された回線でない場合は https を使用してください。Hailo-Ollama のネイティブエンドポイントには認証の仕様がないため、このプロバイダーは、ローカル環境と明示的に信頼された LAN 環境での平文 HTTP 接続を受け入れます。

Hailo-Ollamaは、対応できないトランスポートオプションを黙って無視するのではなく、拒否します。特に、tls_ca_cert_path、think=true、vision=true、呼び出しレベルのネイティブthinking、provider_extra、api_path、wire_api、chat_template_kwargsはサポートされていません。native_tools = falseを設定してください(または未設定のままにしてください)。

受理されたリクエストがHTTPタイムアウトに達した場合、または接続確立後のその他のトランスポート障害で終了した場合、ZeroClawはHailoがクライアント切断後もまだ生成を続けている可能性があるため、そのエンドポイントをプロセスの残りの期間隔離します。バックエンドがアイドル状態であることを確認し(必要に応じて再起動します)、その後ZeroClawを再起動して隔離を解除してください。接続確立の失敗では、エンドポイントは隔離されません。

ネイティブバックエンドとの互換性のため、ZeroClawはサポートされていないthinkおよびnum_ctxのワイヤフィールドを省略し、それらを制御しているかのように見せかけることはしません。ネイティブサービスは、デコード済みの各メッセージを構造化プロンプトのJSONとして再度パースします。そのため、ZeroClawはAPI値内のリテラルのバックスラッシュとCR/LF/タブの制御文字の両方をエスケープし、そのパースを経ても元の意味が保たれるようにします。context_windowは、ZeroClawのベストエフォートなローカル履歴の予算管理を制御します。プロバイダー全体のコンテキストに関する前提を避けるために省略してください。正の値を設定すると、ローカルでの予算管理が有効になります。明示的なゼロは、共有のconfiguration doctorによって拒否されます。この値はHailo-Ollamaには意図的に送信されません。呼び出しレベルのネイティブthinkingリクエストは、バックエンドへのリクエストが行われる前に拒否されます。レスポンスは完了した非ストリーミングのレスポンス（done=true）である必要があり、空の完了レスポンスはエラーとして扱われます。context_windowが小さい場合、設定されたベストエフォートの合計予算を用いて、ユーザー発話を起点とする完全な古いターンを削除します。システム指示は、そのチェックの前に、保持される最初のユーザーメッセージに統合されます。ゼロ以外のcontext_windowが設定されている場合、最新の完全なターンだけで設定された予算を超えるときは、そのターンを削除したり合成プロンプトに置き換えたりせず、転送前にローカルでリクエストを失敗させます。context_windowを省略した場合、プロバイダー全体のローカル予算は適用されません。プロバイダー全体の文字数やメッセージ数の上限はありません。実際にサポートされるコンテキスト容量については、ネイティブのHEF/ランタイムが引き続き決定権を持ちます。

ネイティブレスポンスに表示可能なコンテンツがなく、空でない内部推論（reasoning）フィールドが含まれている場合、プロバイダーは、その出力を唯一の出力先とするモデルとの互換性のため、最終手段として通常テキストのフォールバックとしてそのフィールドを使用します。プロバイダーは推論専用の独立したチャネルを公開しておらず、呼び出し元はこのフォールバックを拡張思考（extended thinking）のサポートの証拠として扱うべきではありません。

ネイティブのツール呼び出し、ストリーミング、ビジョンは提供されていません。Hailo-Ollama 0.5.1 のチャット DTO には画像フィールドがないため、vision=true はテキスト専用の機能を上書きせず拒否されます。代わりに、ビジョン対応の別プロバイダーを設定してください。プロンプトベースのツール呼び出しと結果は、注入されるツールプロトコル全体が有界な最初のメッセージに収まる場合、プレーンテキストの履歴として引き続き利用できます。プロトコルが大きすぎる場合、ZeroClaw は切り詰められたツール指示を送信せず、拒否します。

Azure OpenAI

Azure OpenAI は、入力された Azure フィールドからエンドポイントを計算します:

[providers.models.azure.work]
api_key = "op://platform/azure-openai/api-key"
model = "gpt-4o"
resource = "example-resource"
deployment = "gpt-4o-prod"
api_version = "2024-10-21"

resource、deployment、api_version の各値はこの型付き設定に格納されており、Azure 固有の環境変数からは読み込まれません。計算されたエンドポイントを完全に上書きする必要がある場合にのみ uri を使用してください。

Amazon Bedrock

Bedrock ではモデルを指定したエイリアスが必要です。エンドポイントのリージョンは現在、Bedrock の認証環境/プロファイルパスから取得されます。

[providers.models.bedrock.work]
model = "anthropic.claude-sonnet-4-6"

Bedrock プロバイダーは、crates/zeroclaw-providers/src/bedrock.rs に実装されている認証情報パスを使用します。

  1. Bedrock エイリアスの api_key または BEDROCK_API_KEY は、Bedrock のベアラートークン認証を使用し、SigV4 の認証情報より優先されます。
  2. AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY を使用すると SigV4 が利用されます。AWS_SESSION_TOKEN はオプションです。AWS_REGION または AWS_DEFAULT_REGION で署名リージョンを選択し、指定がない場合は us-east-1 にフォールバックします。
  3. ~/.aws/config のアクティブプロファイル、または AWS_CONFIG_FILE に設定された credential_process は SigV4 を使用します。AWS_PROFILE はプロファイルを選択し、デフォルトは default です。
  4. EC2 IMDSv2 インスタンス認証情報は、最後の SigV4 フォールバックです。

設定スキーマには providers.models.bedrock.<alias>.region フィールドも定義されていますが、現在の実装ではこのフィールドは読み込まれません。エンドポイントのリージョンは、上記のとおり常に AWS 認証情報チェーン（環境変数、credential_process、または IMDS）から解決されます。

現在の Bedrock 実装では、~/.aws/credentials にある通常の静的プロファイルは読み込まれません。~/.zeroclaw/secrets には、エイリアス api_key などの ZeroClaw 設定シークレットのみが保存され、プロバイダー向けに AWS_* 変数をエクスポートすることはありません。

実装済みのプロファイルパス経由で AWS CLI プロファイルを再利用するには、~/.aws/config に credential_process を記述します:

[profile zeroclaw-bedrock]
credential_process = /usr/bin/aws configure export-credentials --profile my-existing-profile
region = us-east-1

/usr/bin/aws は Debian と Ubuntu でのデフォルトパスです。他のシステムでは、command -v aws で得られる絶対パスを使用してください。

次に、AWS_PROFILE=zeroclaw-bedrock を指定して ZeroClaw を実行します。systemd ユーザーサービスについては、サービス管理 を参照してください。

マルチリージョン (Moonshot / Qwen / GLM / MiniMax / …)

ファミリーごとに1つの型を指定します。エイリアスエントリの型付き endpoint フィールドを使用してリージョンを選択してください。

カスタム OpenAI 互換エンドポイント

custom スロットには uri が必要です。Custom providers を参照してください。

エージェントが使用するプロバイダーの選択

エージェントはドット区切りのエイリアスでプロバイダーを参照します。プロバイダーのエントリーは、それ単体では何も行いません。

risk_profile と runtime_profile は独立したエイリアスマップを参照するため、両者の名前は一致する必要はありません（runtime_profile もオプションです）。Config::validate() は、model_provider が設定済みの [providers.models.<type>.<alias>] エントリに解決されない場合、または risk_profile が設定済みの [risk_profiles.<alias>] エントリに解決されない場合、起動時に明示的にエラーを発生させます。

複数のエージェントを異なるプロバイダーに向ける場合は、Routing を参照してください。

単一ツールラウンドのサポート

エージェントランタイムプロファイルのsingle_tool_rounds設定はデフォルトでオフです。設定、集計、ロールバックの動作についてはSingle-tool roundsを参照してください。実際のモデルルートと到達可能なすべてのフォールバックがネイティブ制御を尊重する場合にのみ、応答ごとに1回の呼び出しを要求します。

|Configured provider path 設定済みのプロバイダーパス| |-|ネイティブ制御サポート
openai、APIキー認証、公式のOpenAIエンドポイント、chat-completions または Responses のワイヤープロトコルparallel_tool_calls: falseサポート対象
anthropic、公式Anthropicエンドポイントtool_choice.disable_parallel_tool_use: trueサポート対象
Custom または互換エンドポイント、OVH、Codex サブスクリプション認証、その他のアダプター検証済みの制御がありません制限事項の通知を表示するバッチ処理

Responses と Anthropic は、ストリーミングと非ストリーミングの両方のリクエストで制御を送信します。OpenAI chat-completions は、ルーターがそのレスポンスをストリームイベントとして投影する場合も含め、既存の非ストリーミング実装を使用します。ツールを含まないリクエストは、既存のワイヤー形式を維持します。サポートされているプロバイダーとアダプターを共有していても、別のエンドポイントのサポートが確立されるわけではありません。プライマリプロバイダーが制御をサポートしていても、混合フォールバックチェーンはバッチのままです。

失敗時のフォールバック

プロバイダーへのリクエストがリトライを使い果たした後に失敗した場合（プロバイダーのダウン、キーのレート制限、モデルの利用不可）、エイリアスはエイリアスエントリーで宣言した代替先にフェイルオーバーできます。2つの独立した順序付き軸：

  • fallback_models: _この_プロバイダーで試行される代替モデルID。同じエンドポイント、キー、ヘッダーを使用します。変更されるのはモデル識別子のみです。プロバイダーを完全に離れる前に試すべきバックアップモデル（より小型または古いバリアント）をプロバイダーが提供している場合に使用します。
  • fallback: 他の プロバイダーエイリアスの順序付きリスト（[providers.models] への <type>.<alias> 形式のドット区切り参照）。各フォールバックエイリアスはそれ自身の認証情報、エンドポイント、モデルで解決され、フォールバックが失敗したエイリアスのキーを継承することはありません。

試行順序

このウォークは深さ優先です。エイリアスのモデルリスト全体を使い切ってからそのエイリアスを離れ、その後各 fallback エイリアスを順番に降りていき、そのエイリアス自身の fallback_models と fallback を再帰的に適用します。anthropic.prod が claude-sonnet-4-5 を提供し、その fallback_models に claude-haiku-4-5 を列挙し、その fallback に openai.backup（gpt-4.1 を提供）を指定しているとします。この場合の試行順序は次のとおりです。

anthropic.prod/claude-sonnet-4-5
  -> anthropic.prod/claude-haiku-4-5
  -> openai.backup/gpt-4.1
  -> (request fails)

フォールバックエイリアス自体もfallbackを宣言できるため、チェーンは設定次第で長くなり、最大で3エイリアスの深さまで到達します。自分自身にループバックするチェーン（a -> b -> a）は検出され、循環するエッジは切り取られます。また、制限を超える深さの非循環チェーンは、残りのリンクが切り取られます。いずれの場合も、ループ、ハング、スタックオーバーフローが発生することはありません。

設定の誤り

設定されていないエイリアスを指定する fallback エントリ、循環を形成するもの、または最大深度を超える連鎖は 致命的ではありません。Config::validate() は引き続き成功し、問題のあるエッジは実行時にスキップされ、その問題は CLI とダッシュボード上で検証警告（dangling_fallback_ref / fallback_cycle / max_fallback_depth_exceeded）として表示されます。空欄であるか、エイリアスのプライマリ model と重複する fallback_models エントリも同様に実行時にスキップされ、表示されます（empty_fallback_model / fallback_model_duplicates_primary）。不正なフォールバックリンクは適切に劣化し、エージェントの実行を妨げることは決してありません。

Anthropicの拒否とフォールバック

Anthropicのネイティブリクエストは_refusal_として返されることがあります。これはHTTP 200で、stop_reasonが"refusal"になっており、通常の完了ではなくFableの安全性分類器によって出力されたものです。ZeroClawはrefusalを型付きエラーとして扱い、フォールバックによって次の2つの方法で回復できるようにします。

  • クライアント側（上記のfallback_models）：拒否はエラーとして表面化し、ZeroClaw は他のプロバイダーの失敗時と同様に次のモデルまたはエイリアスへ進むため、応答は別のモデルから返されます。
  • サーバー側（[providers.models.anthropic.<alias>] の server_fallback_models）：Anthropic は、拒否されたリクエストを、サーバー側でリストに含まれるモデルに対して単一の非ストリーミング呼び出しで再試行します。エントリには、許可されたフォールバック先のモデル名を指定する必要があります。例えば、claude-fable-5 を claude-opus-4-8 にマッピングする場合などです。

いずれの場合も、返信の末尾には要求されたモデルと提供されたモデルの名前を示す短いフッターが付き、モデルの切り替えがユーザーに見えるようになっています。Webダッシュボードのチャットでは、同じ切り替えが回答の直前にインライン通知として表示され、要求されたモデル名と提供されたモデル名のみが示されます。通常のプロバイダー障害によって、Anthropic 側でモデルが切り替わる前にクライアント側のフォールバックへリクエストが移された場合、返信には通常のフォールバック通知も残ります。これにより、元々要求されたモデルが表示されたままになり、2 つの原因が混同されることはありません。

Streaming には制限があります。ストリーミング出力が開始された後に届いた拒否は、既存の応答中断時の動作をそのまま維持します。フォールバックが適用されるのは、出力開始前に検出された拒否のみです。

OpenAI互換およびResponsesのワイヤーでは、Anthropic固有のrefusal/fallbackメタデータを伝送できません。このような動作を得るには、Anthropicモデルを[providers.models.anthropic.<alias>]経由でルーティングしてください。

関連項目も参照してください