ルーティング

ZeroClaw は、2 つの異なる判断にルーティングを使用します：

1. エージェントのディスパッチは、どのエージェントがチャネルまたはリクエストを担当するかを選択します。各エージェントには独自のプロバイダープロファイルとランタイムポリシーがあります。
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 を参照してください。

Routeは通常、プロンプトに対応するヒントが明示的に含まれている場合に発動します。オプトインされたeffort-routingのランタイムプロファイルでは、プロバイダーによる実行前に、名前付きの2つのRouteを自動的に選択することもできます。

未知の hint:<name> は警告をログに記録し、リテラルのヒントを要求されたモデルとして保持したまま、デフォルトの信頼性ドメインにとどまります。ピン留めされたデフォルトエントリは、引き続きアクティブなデフォルトのピンを使用します。ピン留めされていないデフォルトエントリはリテラル値を転送するため、通常のフォールバックまたはエラー処理が続行される前にプロバイダーによって拒否される可能性があります。

model_provider は常に、<type>.<alias> 形式のドット区切りのプロバイダープロファイル参照であり、anthropic.sonnet や openai.default などです。プロファイルには、エンドポイント、認証情報参照、互換性フレーバー、フォールバックチェーン、オプションのデフォルトモデルが含まれます。model フィールドは、そのプロファイルにおけるプロバイダー固有の状態です。

現在の制限: ルートの固定はターゲットプロファイルに依存します。プライマリターゲットは、ルーターの構築に使用されたアクティブ/デフォルトモデルに固定されます。これは、認識されたヒントがアクティブなプライマリプロファイルを指し戻す場合も同様です。そのヒントの model_routes[].model 値はプライマリの固定を上書きしません。構成済みのプロファイルモデルを持つ非プライマリターゲットはそのモデルに固定されるため、そのルートモデルもプロファイルモデルを上書きしません。構成済みモデルを持たない非プライマリターゲットは固定されないままとなり、ルートモデルを受け取ります。その fallback_models は実体化されませんが、参照されているフォールバックプロファイルは引き続き走査されます。ターゲットの固定が存在する場合は、ルートモデルをその固定先と一致させてください。

Effort ベースのローカル/クラウド ルーティング

effort_routingブロックをランタイムプロファイル上に設定すると、単純なターンと曖昧なターンにはローカルルートを、複雑なターンにはクラウドルートを選択できます。このブロックが存在しない限り、この機能は無効のままです。この機能は、完全一致かつ大文字小文字を区別する[[model_routes]].hintの値を再利用するため、プロバイダーの認証情報とモデルIDは既存のルートおよびプロバイダープロファイルの設定で引き続き管理されます。

[[model_routes]]
hint = "local"
model_provider = "ollama.local"
model = "qwen3:8b"

[[model_routes]]
hint = "cloud"
model_provider = "anthropic.sonnet"
model = "claude-sonnet-4-5"

[runtime_profiles.local_first.effort_routing]
local_hint = "local"
cloud_hint = "cloud"
cloud_escalation = "auto"

最初の実装では、ZeroClaw の決定論的な複雑度推定器を使用します。プロンプトを分類のために別のモデルへ送信することはありません。推定器は UTF-8 のバイト数を数えます。50 バイト未満で推論キーワードを含まないテキストは単純とみなされます。200 バイトを超える場合、コードフェンスを含む場合、または英語の推論キーワードを 2 つ以上含む場合は複雑とみなされます。それ以外は標準です。単純および標準のターンでは local_hint が選択されます。複雑なターンでは、cloud_escalation = "auto" の場合にのみ cloud_hint が選択されます。デフォルトの "never" では、自動判定はすべてローカルに留まります。

チャネルのターンでは、添付マーカーを取り除いた、エンリッチメント前のユーザーのテキストを分類します。そのため、取得したリンクの要約やエンコードされたメディアのバイト列がクラウドへのエスカレーションを引き起こすことはありません。

ルーティングの決定はターンごとに行われます。ログには、選択されたターゲット、複雑度ティア、エスカレーションポリシー、メッセージの長さが含まれますが、メッセージ本文は含まれません。ローカルの決定では、プロバイダーへの試行は設定されたローカルプロバイダーに限定され、ストリームから非ストリームへのリカバリーも含まれます。そのため、可用性フォールバックによって当該ターンがクラウドに黙って開示されることはありません。クラウドの決定では、設定されたローカルプロバイダーとクラウドプロバイダーのプロバイダー参照の両方が許可されます。

オペレーターの選択は、自動 effort ルーティングより優先されます。CLI の --provider または --model による上書きは、これをバイパスします。チャネルでの /model <model-or-hint> の選択は、次の分類可能なターンで置き換えられることなく、選択された状態のまま維持されます。/model auto を使用すると、送信者セッションの選択がクリアされ、設定された自動ルーティングが復元されます。スコープ指定の /model --user auto および /model --agent auto は、それらのスコープ指定された選択をクリアします。構造化されたセッションのプロバイダーまたはモデルの上書きは、そのセッションに対して明示的なまま維持されます。モデルが発行した model_switch は、引き続き有効な effort ポリシーの対象となり、そのターンで許可されたプロバイダープロファイルのみを選択できます。

effort_routing は、そのエージェントに対して auto_classify およびチャネルの query_classification を置き換えます。設定の検証では、effort_routing と auto_classify の両方を設定したランタイムプロファイルを拒否します。effort_routing を持つエージェントでは、チャネルコマンドは自動ルーティングを復元するために auto を予約します。effort_routing を持たないエージェントは、auto という名前のモデルやルートのヒントを含め、既存のモデルおよびルート選択の動作を維持します。

この実装スライスには、クラウド実行前に確認を求めるモード、エスカレーション頻度の上限、個別のコスト上限は含まれていません。effort ルーティングによるモデルプロバイダーへの試行をローカルに留めるには cloud_escalation = "never" を使用してください。コスト管理にはプロバイダーの予算設定と通常のオブザーバビリティを利用してください。この設定は、無関係なツールやメディア前処理によって行われる個別のネットワーク呼び出しやプロバイダー呼び出しには適用されません。

選択されたプロバイダーがビジョンに対応しておらず、画像を含むターンで設定済みの vision_model_provider が必要な場合、そのプロバイダーは、そのターンで許可されているローカルまたはクラウドのプロバイダー参照のいずれかに解決されなければなりません。専用のビジョンプロバイダーがその集合の外にある場合、ターンはフェイルクローズ(安全側で停止)します。

Effort routing は、隣接する作業とは意図的に限定された関係にあります:

• Issue #5287 は、ローカルモデルや小規模モデルの選択後の動作を管理します。
• Issue #7539 は、ローカルのモデルルーターとディスカバリー機能に関するもので、effort ルーティングがモデルを検出する代わりに、設定済みのエイリアスを使用する問題です。
• Issue #7431 は、ローカルとクラウドのモデル選択ではなく、配信とツールルーティングの意図に関するものです。

信頼性のフォールバック

プロバイダープロファイルでは、同じエンドポイント上の代替モデルに対して 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.*] スキーマの全体
• プロバイダールーティングのライフサイクル：選択、再試行、フォールバック、ストリーミングの復旧、帰属情報の管理責任
• プロバイダーカタログ: すべての正規スロット