マルチモデルのセットアップ

複数のモデルプロバイダーを使用する際の一般的なパターンを解説します：エージェントごとの振り分け、ヒントによるルーティング、コスト階層化、ローカル優先とホスト型バックアップ、非ストリーミング時のプロバイダーフォールバック、レート制限への対応、ストリーミングの復旧。

プロバイダーシステムのリファレンス資料は以下にあります：

モデルプロバイダー → 概要：プロバイダーとは何か、設定の構成について

モデルプロバイダー → ルーティング: エージェントのディスパッチ、ヒントルート、プロバイダーのフォールバック

モデルプロバイダー → カタログ：各プロバイダーの設定形式

マルチモデル構成を使用するタイミング

マルチモデル設定は以下の場合に役立ちます：

コスト階層化: 安価なモデルが大量のチャネルを処理し、推論モデルが複雑なリクエストを処理します
機能ルーティング: 画像を含むチャネルにはビジョン対応モデル、リサーチワークフローには推論モデル
ローカルファースト開発: 開発にはローカルの Ollama、本番環境にはホスト型エンドポイント
チーム単位の分離: 異なるチームが、それぞれ異なる model_providers と認証情報を持つ異なるエージェントを使用します
非ストリーミングのレート制限処理: 再試行可能な 429 の後、別の設定済みプロバイダープロファイルに切り替える

コアアイデア: エージェントごとのディスパッチ

各 [agents.<alias>] エントリは、1 つの [providers.models.<type>.<alias>] から開始します。そのプロバイダープロファイルでは、fallback_models を使用して代替モデルを、fallback を使用して他のプロバイダープロファイルを宣言できます。完全なパターンについては、Routing を参照してください。

複数のモデルを実行するには、複数のエージェントを起動し、それぞれを1つのモデルプロバイダーにバインドします。各チャンネルは一度に1つのエージェントにバインドされます。チャンネルを別のエージェントに移動するには、そのチャンネルを引き継ぐべきエージェントの channels リストを編集します。Config::validate() が起動時に参照が正しく解決されることを保証します。

プロバイダー間の信頼性

非ストリーミング呼び出しでは、ZeroClaw はプロバイダープロファイル間の順序付きフォールバックグラフを辿ることができます。各フォールバックプロファイルは、独自のエンドポイント、認証情報、モデル、ヘッダー、機能のオーバーライド、ネストされたフォールバック宣言を保持します。ランタイムは、エラー分類とプロファイルのクールダウン状態に応じて、再試行するか次のプロファイルへ進みます。

OpenRouter は引き続き第一級プロバイダーであり、単一のエンドポイント経由でベンダー選択を実行できます。これはオプションの外部ルーティング層であり、ZeroClaw のファーストパーティフォールバックに必須ではありません。

ネットワーク障害、503、タイムアウトなどの一時的なエラーが発生した場合、非ストリーミング呼び出しは上限付き指数バックオフで再試行します。これは reliability でグローバルに設定でき（デフォルトは再試行2回、初期バックオフ500 ms）、エントリでの試行を使い果たすと、信頼性ラッパーはプロファイルの fallback_models とフォールバックプロファイルを順に試します。

ストリーミングリカバリ境界

ストリーミング呼び出しは、必要なストリーム機能をサポートする、適格でクールダウン中でない最初のエントリを選択します。そのストリームの開始後に別のエントリへ進むことはありません。可視出力が不変のコンシューマーに到達する前にストリームが失敗した場合、ランタイムは非ストリーミング経路で呼び出し全体を再試行します。この経路ではフォールバックグラフをたどることがあります。可視出力が存在した後は、ランタイムは部分的なレスポンスを保持し、リクエストを再実行したりプロバイダーを切り替えたりしません。完全な契約については、プロバイダールーティングのライフサイクルを参照してください。

API キーのローテーション制限

認証情報のフェイルオーバーに reliability.api_keys を依存しないでください。再試行可能なレート制限が発生すると、reliable ラッパーは代替キーを選択してログに記録しますが、ModelProvider トレイトでは、すでに構築されたプロバイダーにそのキーを適用できません。再試行でも元の認証情報が使用されます。Issue #9190 でこの制限を追跡しています。

認証情報単位のフェイルオーバーが必要な場合は、それぞれ固有の認証情報を持つ個別のプロバイダープロファイル、または外部ルーティングサービスを使用してください。

ホスティング型の代替手段を用いたローカル開発

ローカルの Ollama エージェントとホスト型プロバイダーのエージェントを並行して実行し、各チャネルを使用したいエージェントへルーティングします。

dev エージェントは CLI から実行されます（チャネルのバインドは不要で、zeroclaw agent -a dev で十分です）。Ollama がダウンしている場合、dev エージェントは即座に失敗し、エラーを表面化します。prod チャネルには影響しません。

ローカルスモールテキストフォールバックなしプロファイル

小規模なローカルモデルには通常、プロバイダー固有のモードではなくランタイムプロファイルが必要です。Ollama プロバイダーは接続の詳細に専念させ、[runtime_profiles.<alias>] を使ってプロンプト/ツールループの挙動を厳密に制御しましょう。ZeroClaw は、ランタイムプリセットを直接インストールするコードパス向けに、組み込みの local_small ランタイムプリセットを提供しています。設定を手動で編集する場合は、次の同等のブロックを使用してください:

[providers.models.ollama.local]
uri   = "http://localhost:11434"
model = "qwen2.5-coder:7b"

[agents.local]
model_provider  = "ollama.local"
risk_profile    = "supervised"
runtime_profile = "local_small"

[risk_profiles.supervised]
level                            = "supervised"
workspace_only                   = true
require_approval_for_medium_risk = true
block_high_risk_commands         = true

[runtime_profiles.local_small]
agentic                 = true
compact_context          = true
strict_tool_parsing      = true
max_tool_iterations      = 4
max_actions_per_hour     = 10
max_cost_per_day_cents   = 100
shell_timeout_secs       = 30
max_delegation_depth     = 1
delegation_timeout_secs  = 60
agentic_timeout_secs     = 120
max_history_messages     = 20
max_context_tokens       = 8000
parallel_tools           = false
max_system_prompt_chars  = 4000
max_tool_result_chars    = 4000
keep_tool_context_turns  = 1
memory_recall_limit      = 3

このプロファイルは既存のプリミティブを組み合わせています:

compact_context は起動時のコンテキストを小さく保ちます。
strict_tool_parsing は、プロバイダーがネイティブのツール呼び出しを返さない限り、XML/JSON のように見えるフォールバックテキストをアシスタントのテキストとして扱います。
max_tool_iterations、max_context_tokens、max_system_prompt_chars、および max_tool_result_chars は、暴走ループや過大なプロンプト/ツールコンテキストを制限します。
max_actions_per_hour、max_cost_per_day_cents、およびタイムアウト/委譲フィールドにより、ローカル実行を組み込みプリセットと同じ予算形式に保ちます。
parallel_tools = false と keep_tool_context_turns = 1 により、ローカル実行が順次処理となり、保持されるツールコンテキストが制限されます。

Ollama では、これはテキストフォールバックなしのプロファイルです。許可されたツールは risk_profile に設定されたままですが、モデルからのテキスト形式のツールマークアップは実行されません。チャット優先のローカルエージェントや、ネイティブ/構造化されたツール呼び出しを返すプロバイダーに使用してください。ローカルモデルが ZeroClaw のテキストフォールバックツール構文を使用する必要がある場合は、strict_tool_parsing = false を設定し、その他の小規模モデルの制限はそのままにしてください。

コスト階層化: 必要なときはヘビーモデル、それ以外は高速モデル

2つのエージェントを実行し、チャネルを適切なティアにルーティングします。delegate ツールにより、1つのエージェントが会話の途中で別のエージェントへ処理を引き継げます。Delegation はゲートされています。呼び出し元のリスクプロファイルで delegation_policy mode = "allow" を設定する必要があり、かつターゲットが呼び出し元から到達可能でなければなりません（同一プロファイルのピア、または呼び出し元の delegates リストにある明示的なエントリ）。以下のフロントラインエージェントとヘビーエージェントは 同一の trusted リスクプロファイルで実行されるため、同一プロファイルのピアとして互いに到達できます。両者はモデルとランタイムプロファイル（イテレーション予算）が異なるだけで、信頼サーフェスは異なりません。

フロントラインエージェントは、すべての受信メッセージをHaiku上で処理します。より深い推論が必要になると、delegateツールをagent = "heavy"で呼び出します。両方のエージェントがtrustedリスクプロファイルを共有しており、そのプロファイルが委任を許可しているため、より重量級のエージェントがOpus上でサブタスクを引き継ぎます。

非ストリーミングエラー処理

非ストリーミング呼び出しでは、再試行可能な失敗には次が含まれます：

タイムアウト: プロバイダーが設定されたタイムアウト内に応答しませんでした
接続エラー: ネットワークまたは DNS の障害
レート制限 (429): プロバイダープロファイルを一時的なインメモリのクールダウン状態に設定し、別のエントリが存在する場合は次のエントリに進みます
サービス利用不可 (503): 一時的なサービスの問題

再試行がトリガーされない条件:

無効なリクエスト (400): 入力が不正です。再試行しても解決しません
永続的な認証エラー: API キーの形式が無効です
モデル出力エラー: モデルは応答しましたが、エラーペイロードを返しました

すべてのマテリアライズ済みエントリが使い果たされるかクールダウン中になると、収集された試行失敗とともに失敗が呼び出し元のチャネルに通知されます。

デバッグ

永続化ログ（"rolling" がデフォルト）は、再試行、クールダウン、フォールバックの動作を記録します。次にトレースをクエリします:

sh

zeroclaw doctor traces --contains リトライ
zeroclaw doctor traces --contains "429"
zeroclaw doctor traces --contains "model_provider"

ベストプラクティス

ルーティングの意図ごとに 1 つのエージェントを用意します。 2 つのチャネルで異なるモデルの動作が必要な場合は、2 つのエージェントに名前を付けます。
フォールバックプロファイルの所有権を明示します。 各エンドポイント、認証情報、モデル、機能のオーバーライドは、それを提供するプロファイルに保持します。
OpenRouter をオプションのルーティングレイヤーとして扱います。 サーバー側でベンダー選択を行うと便利な場合はこれを使用し、ランタイムで順序を管理する必要がある場合は ZeroClaw のフォールバックプロファイルを使用します。
reliability.api_keys に依存しないでください。 issue #9190 が修正されるまで、個別に構築したプロファイルを使用してください。
各エージェントを単独でスモークテストします。 zeroclaw agent -a <alias> は、チャネルの配管に邪魔されずにエージェントを実行します。
エージェントの意図をドキュメント化する。 各エージェントがどのチャネルを処理するのか、またその理由を説明する # comment 行を追加してください。
シークレットはインラインではなく env 経由で注入してください。 ZEROCLAW_providers__models__<type>__<alias>__api_key=... は起動時に api_key を設定します。環境変数を参照してください。
開発エージェントと本番エージェントを分離する。 各環境は、それぞれのチャンネルにバインドされた独自の [agents.<alias>] エントリを持ちます。

認証情報の解決

各プロバイダーエントリは、次の順序で認証情報を解決します:

プロバイダーエントリのインライン api_key。
~/.zeroclaw/secrets にある Secrets store。
汎用の環境変数オーバーライド: 起動時の ZEROCLAW_providers__models__<type>__<alias>__api_key=...。シェルがすでに ANTHROPIC_API_KEY、OPENROUTER_API_KEY、または類似のベンダーデフォルト名をエクスポートしている場合は、プロバイダーファミリーがネイティブのランタイム環境変数ブリッジを明示的にドキュメント化していない限り、起動前にこのスキーマミラー変数へブリッジしてください。完全な文法とブリッジの例については環境変数を参照してください。

認証情報はプロバイダープロファイル間で共有されないため、プロファイルごとに設定してください。ルートレベルの model_routes[].api_key は、ルーティング先のターゲットを構築する際に、より優先度の高い上書き値となります。ルートターゲットは model_provider に基づいて重複排除されるため、最初に一致したルートの認証情報で、複数のヒントが共有するプロバイダーを構築できます。ルートがターゲットを共有する場合は、プロファイル所有の認証情報を優先してください。

ZeroClaw Docs