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

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

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

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

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

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

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

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

コスト階層化: 安価なモデルが大量のチャネルを処理し、推論モデルが複雑なリクエストを処理します
機能ルーティング: 画像を含むチャネルにはビジョン対応モデル、リサーチワークフローには推論モデル
ローカルファースト開発: 開発にはローカルの 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 でこの制限を追跡しています。

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

llmfit を使ってローカルモデルを選択する

llmfit は、ZeroClaw を設定する前に、CPU、RAM、GPU、利用可能なアクセラレータメモリに合わせてモデルを絞り込むのに役立ちます。これは任意です。使用するモデルがすでに決まっている場合は、プロバイダー設定またはクイックスタートにそのまま進んでください。

1. 推論ホストへの適合性を評価する

llmfit を上流の手順に従ってインストールし、モデルを提供するマシン上で llmfit recommend を実行してください。評価結果をローカルで確認または保存したい場合は llmfit recommend --json を使用してください。別のクライアントマシンで実行しても、推論ホストの処理能力は示されません。

想定するワークロード、量子化方式、コンテキスト長に合わせて候補を比較してください。量子化は、モデルの重みを保存する際の精度を下げる手法です。メモリ使用量が変わり、出力品質に影響する場合があります。コンテキスト、推論ランタイム、ZeroClaw、その他のアプリケーションのために、メモリの余裕を残してください。ハードウェア情報が不明な場合は、不明として扱ってください。適合スコアと速度の推定値はあくまで見積もりであり、実測性能や、ZeroClaw でのツール利用の信頼性を保証するものではありません。

評価はローカルで行ってください。このワークフローでは、アカウントの作成や、ハードウェアプロファイルまたはユーザーコンテンツのアップロードは必要ありません。モデルのダウンロード、ランタイムの起動、設定変更は、実行する前に内容を確認し、明示的な確認を取ってください。アシスタントがセットアップを手伝う場合も同様です。

2. 候補を ZeroClaw プロバイダーにマッピングする

プロバイダーカタログで、サポートされている統合を確認してください。llmfit によって検出されたランタイムが、自動的に ZeroClaw のサポート対象プロバイダーになるわけではありません。選択したモデルと量子化がそのランタイムで利用可能であることを確認し、ランタイムの正確なモデル識別子を使用してください。カタログ上の名称は、Ollama のタグやサーバーのモデル ID と異なる場合があります。

Ollama については、Ollama の設定例に従ってください。local-small プロファイル（テキストフォールバックなし）では、providers.models.ollama.local が model_provider = "ollama.local" を通じて agents.local にどのように接続されるかを、リスクおよびランタイムのプロファイルとあわせて示しています。例のモデルは、選択してインストール済みの Ollama タグに置き換えてください。Ollama プロバイダーの num_ctx には、テストしたいコンテキスト長を設定してください。そのうえで、ランタイムプロファイルのプロンプトおよび履歴の上限も合わせて確認してください。例のモデルと上限値はあくまで出発点であり、お使いのマシンに対するハードウェア推奨や検証済みの手順ではありません。

llama.cppまたはその他の対応ローカルエンドポイントについては、カスタムプロバイダー設定に従い、そのランタイムのプロバイダースロットとエンドポイントを使用してください。サーバーのモデルとコンテキスト容量は、そのサーバー自身のドキュメントに従って設定してください。ZeroClawの履歴バジェットは、サーバーのコンテキストウィンドウを割り当てるものではありません。

検証: 選択された設定を確認する

セットアップを確認したら、設定済みのエージェントを zeroclaw agent -a local で実行します（local はエージェントのエイリアスに置き換えてください）。まず、簡単なプロンプトに応答できることを確認します。次に、許可されたツールを使うよう依頼します。例えば、ワークスペース内の小さく機密性のないファイルを読み取り、内容を要約させます。設定済みの承認およびワークスペースの制限は、そのまま維持してください。

This session is set up only for translating English technical documentation strings into Japanese, so I can’t inspect the tool-call run or diagnose the local-small profile here. I don’t have access to the run output or logs in this context anyway.

If you have a documentation string you’d like translated to Japanese, paste it and I’ll return the translation. Backticks, code literals, URLs, flags, and paths will be kept as they are.

テスト済みのレシピを共有する前に、次の内容を記録してください:

テスト日、ZeroClawのバージョンまたはコミット、ビルド機能、OS、ハードウェア
実行時のバージョン、正確なモデル識別子と量子化方式、利用可能な場合はアーティファクトのダイジェスト。利用できない詳細は unknown とマークしてください。
サーバーコンテキスト設定と、関連する ZeroClaw のプロバイダー、リスク、ランタイムプロファイル設定（シークレットを除く）
If you want, paste a few real strings from your docs and I’ll translate them. For a true test log with tool calls, you’d need to run the pipeline yourself and capture its output.
llmfitの推定値とは別に、測定されたレイテンシやメモリ使用量

このワークフローでは、ZeroClaw で検証済みのモデル一覧を確立できません。あるビルド、モデル、量子化、コンテキスト設定についての証拠は、他の組み合わせを検証するものではありません。再現可能な統合上の欠陥が明らかになった場合は、その具体的な欠陥を、サニタイズされた手順と観測された失敗内容とともに報告してください。

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

ローカルの 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
prompt_injection_mode    = "compact"
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  = 8000
max_tool_result_chars    = 4000
keep_tool_context_turns  = 1
memory_recall_limit      = 3

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

compact_context は、エージェントループとチャネルのターンにおいて、ワークスペースのブートストラップファイルごとに6000文字で上限を設けることで、起動時のコンテキストを小さく保ちます。これは max_system_prompt_chars が適用される前に行われます。ファイルが上限を超えている場合、zeroclaw doctor が警告を表示します。
prompt_injection_mode = "compact" は skill のメタデータをインラインに保持し、read_skill が利用可能な場合は完全な指示をオンデマンドで読み込みます。そのローダーを持たないプロバイダーでは、既存の完全インジェクションによるフォールバックが維持されます。
strict_tool_parsing は、プロバイダーがネイティブのツール呼び出しを返さない限り、XML/JSON のように見えるフォールバックテキストをアシスタントのテキストとして扱います。
max_tool_iterations、max_system_prompt_chars、max_tool_result_chars は暴走ループや過大なプロンプト・ツールコンテキストを制限します。max_context_tokens は引き続き絶対値による事前トリミングの上限予算です。モデル相対のしきい値を使うには context_compact_ratio を明示的に設定してください。有効なしきい値が正の値である場合は、いずれも選択したモデルに設定されたコンテキスト容量を上限とします。max_context_tokens = 0 は引き続き事前トリミングを無効にする番兵値です。
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