ルーティング
ZeroClaw は、2 つの異なる判断にルーティングを使用します：
- エージェントのディスパッチは、どのエージェントがチャネルまたはリクエストを担当するかを選択します。各エージェントには独自のプロバイダープロファイルとランタイムポリシーがあります。
- プロバイダーとモデルのルーティングは、呼び出しに使用する構成済みのプロバイダープロファイルとモデルを選択し、その後、そのプロファイルの再試行およびフォールバックポリシーを適用します。
OpenRouter などの外部ルーティングサービスを使用すれば、1つのプロバイダープロファイルの背後でベンダー選択を引き続き実行できます。これはオプションです。ZeroClaw は、ファーストパーティのヒントルート、同一プロファイル内でのモデルフォールバック、プロバイダープロファイル間のフォールバックにも対応しています。
エージェントごとのディスパッチ
各ルーティングターゲットを個別のエージェントとして定義し、トラフィックを処理すべきエージェントにチャネルを向けてください。
各チャネルは1つのエージェントにバインドされます。チャネルをエージェント間で移動するには、引き継ぐ側のエージェントの channels = [...] を編集します。Config::validate() が参照の解決を確認します。
単一の会話内でのアドホックな複数ステップのルーティングのために、spawn_subagent ツールを使用すると、エージェントは自身のアイデンティティの下で一時的な子プロセスを実行できます。子プロセスは親の権限エンベロープ（[risk_profiles.<alias>].allowed_tools を参照）を継承し、その最終応答を親のツールループに返します。
ヒントベースのモデルルート
より限定的な仕組みとして、[[model_routes]] を使うと、エージェントはヒント文字列が指定されたプロンプトに対して、設定済みの model_provider を上書きできます。1 つのエージェントが、別のエージェントを立ち上げることなく、時折別のモデルを利用すべき場合に便利です。各ルートエントリには、hint（プロンプトがそれを発動させるために宣言する必要がある文字列）、model_provider（切り替え先のドット区切り <type>.<alias> プロファイル、例: deepseek.reasoner）、model（プロバイダーローカルのモデル ID、例: deepseek-reasoner）が含まれます。ルートはゲートウェイ、zerocode、または zeroclaw config set を通じて設定します。フィールドスキーマについては Config reference を参照してください。
ルートは、プロンプトに一致するヒントが明示的に含まれている場合にのみ起動します。デフォルトのリクエストパスでは、エージェントのプライマリ model_provider が使用されます。
未知の hint:<name> は警告をログに記録し、リテラルのヒントを要求されたモデルとして保持したまま、デフォルトの信頼性ドメインにとどまります。ピン留めされたデフォルトエントリは、引き続きアクティブなデフォルトのピンを使用します。ピン留めされていないデフォルトエントリはリテラル値を転送するため、通常のフォールバックまたはエラー処理が続行される前にプロバイダーによって拒否される可能性があります。
model_provider は常に、<type>.<alias> 形式のドット区切りのプロバイダープロファイル参照であり、anthropic.sonnet や openai.default などです。プロファイルには、エンドポイント、認証情報参照、互換性フレーバー、フォールバックチェーン、オプションのデフォルトモデルが含まれます。model フィールドは、そのプロファイルにおけるプロバイダー固有の状態です。
現在の制限: ルートの固定はターゲットプロファイルに依存します。プライマリターゲットは、ルーターの構築に使用されたアクティブ/デフォルトモデルに固定されます。これは、認識されたヒントがアクティブなプライマリプロファイルを指し戻す場合も同様です。そのヒントの
model_routes[].model値はプライマリの固定を上書きしません。構成済みのプロファイルモデルを持つ非プライマリターゲットはそのモデルに固定されるため、そのルートモデルもプロファイルモデルを上書きしません。構成済みモデルを持たない非プライマリターゲットは固定されないままとなり、ルートモデルを受け取ります。そのfallback_modelsは実体化されませんが、参照されているフォールバックプロファイルは引き続き走査されます。ターゲットの固定が存在する場合は、ルートモデルをその固定先と一致させてください。
信頼性のフォールバック
プロバイダープロファイルでは、同じエンドポイント上の代替モデルに対して fallback_models を、その他のドット区切りのプロバイダープロファイルに対して fallback を宣言できます。ZeroClaw は、プロファイルに有効なプライマリモデルがある場合にのみ fallback_models を展開し、それ以外の場合、そのプロファイルはモデル未指定のエントリを1つ提供します。その後、フォールバックプロファイルを深さ優先でたどります。各フォールバックプロファイルは、それ自体のエンドポイント、認証情報、ヘッダー、オプションのモデル、ネストされたフォールバック宣言を保持します。
レート制限後は、実際の実行結果が異なる場合があります。1つのプロファイルのエントリはクールダウンキーを共有するため、プライマリで 429 が発生すると、クールダウン中はそのプロファイルに残っているフォールバックモデルがスキップされる可能性があります。
ZeroCode Config エディター、ダッシュボード、または zeroclaw config set でチェーンを構成します。プロバイダー構成を参照してください。プロバイダーのルーティングライフサイクルには、構築、再試行の分類、ストリーミングの復旧、再送しない境界、帰属の責任範囲について記載されています。
実行時のモデル切り替え
実行時スイッチは、構成ベースのルーティングと同じプロバイダープロファイル契約を使用します。
/models <type>.<alias>は、送信側セッションのアクティブなプロバイダープロファイルを選択します。チャンネルランタイムは、そのプロバイダーファミリーに設定されたエイリアスがちょうど1つだけ存在する場合、<type>のみの省略形も受け付けることができます。/model <model-id>は、アクティブなプロバイダープロファイル内のモデルを選択します。値が[[model_routes]]エントリを介して解決される場合、そのルートでは別のプロバイダープロファイルを選択できます。ピン留めされたターゲットは、必ずしもmodel_routes[].modelではなく、その有効なピンを使用します。設定済みのプロファイルモデルを持たないピン留めされていないターゲットには、ルートモデルが適用されます。model_switchツールは、model_provider = "<type>.<alias>"とmodel = "<provider-local-model-id>"を使用します。
ランタイムスイッチはセッション/ランタイムの状態です。これらは config.toml を編集しません。永続化されたデフォルト値には、明示的な設定の書き込みが必要です。ツール駆動のスイッチでは、openai のような単なるプロバイダーファミリ名はスイッチの対象にはなりません。なぜなら、それらはどの設定済みプロファイル、認証情報、エンドポイント、または互換モードを使用すべきかを識別できないためです。
観測性
エージェントごとのディスパッチ判断はトレースログで確認できます:
INFO channel=telegram.home routed to agent=fast
INFO agent=fast model_provider=anthropic.haiku turn_id=...
INFO model_provider=anthropic.haiku stream complete tokens={input=512, output=128}
本番環境へのデプロイでは、ログ出力を Loki / Grafana に接続してください。Operations → Logs & observability を参照してください。
関連項目も参照してください
- 概要: プロバイダーモデルとエージェントごとのディスパッチ
- 設定:
[providers.*]スキーマの全体 - プロバイダールーティングのライフサイクル：選択、再試行、フォールバック、ストリーミングの復旧、帰属情報の管理責任
- プロバイダーカタログ: すべての正規スロット