OpenClawの複数エージェントとモデル：ルーティング、分離、コスト

OpenClaw の複数エージェントと複数モデルは、1つの設定ファイルにおける異なる2つの階層です。複数のエージェントは agents.entries 配下のキー付きエントリであり、それぞれが独自のワークスペース、状態ディレクトリ、セッションストアを所有します。一方、複数のモデルは、それらのエントリ内にあるエージェントごとの model 値です。 これらと並んでさらに2つの階層があります。bindings はどのエージェントが応答するかを決定し、フォールバックチェーンはモデルが失敗したときにそのエージェントがどう動作するかを決定します。誤った階層を編集することが、変更が何も起こさないように見える最も一般的な理由です。

ソフトウェア上、エージェントを増やしても費用はかかりません。OpenClaw の ドキュメント概要 には、「独立した 501(c)(3) である OpenClaw Foundation」によって公開開発されており、「有料プランなし、無効にできるバージョン確認を除き、デフォルトではテレメトリーなし、どのラボにも所有されていない」と記載されています。また、openclaw.ai には「サブスクリプションなし。ホステッドプランなし。トークンなし」とあります。npm パッケージ openclaw は MIT ライセンスで、latest は 2026.9.5、extended-stable チャネルは 2026.7.35、engines.node は >=24.16.0 <25 || >=26.1.0 です（npm レジストリ、2026年9月21日確認）。2つ目のエージェントが請求額に加えるのはトークン費用です。

OpenClaw の複数エージェント設定：4つの階層と、誤った階層を編集した場合の症状

4つすべては、2026年9月21日に OpenClaw 自身のドキュメントから確認しました：エントリとマルチエージェント、エージェントのバインディング、モデルのフェイルオーバー。古いチュートリアルにある2つの形式は現在では古くなっています。agents.list 配列のエージェント一覧は Doctor が移行するレガシー形式であり、エントリ上の default: true マーカーは廃止されています。エントリのページには「default は廃止」と明記され、マルチエージェント操作にはバインディングまたは明示的な対象が必要とされています。OpenClaw は以前2つの別名でも提供されていたため、見つかった Moltbot または Clawdbot 時代の設定は、このスキーマより前のものです。

OpenClaw の複数エージェント設定：最小構成の2エージェント・2モデル設定

この断片は、動作する models.providers ブロックをすでに用意していることを前提とします。OpenClaw に最適な APIには、api: "anthropic-messages" と Anthropic base URL として公開されているベース URL を含む Kunavo 用の記述があります。以下はエージェントとルーティングの階層だけです。

{
  "agents": {
    "defaults": {
      "modelSelectionScope": "session",
      "model": {
        "primary": "kunavo/claude-haiku-4-5",
        "fallbacks": [
          "kunavo/claude-sonnet-5"
        ]
      }
    },
    "entries": {
      "ops": {
        "name": "Ops",
        "workspace": "~/.openclaw/workspace-ops",
        "agentDir": "~/.openclaw/agents/ops/agent",
        "model": "kunavo/claude-haiku-4-5",
        "modelPolicy": {
          "allow": [
            "kunavo/claude-haiku-4-5"
          ]
        }
      },
      "build": {
        "name": "Build",
        "workspace": "~/.openclaw/workspace-build",
        "agentDir": "~/.openclaw/agents/build/agent",
        "model": {
          "primary": "kunavo/claude-opus-5",
          "fallbacks": [
            "kunavo/claude-sonnet-5"
          ]
        },
        "utilityModel": "kunavo/claude-haiku-4-5"
      }
    }
  },
  "bindings": [
    {
      "agentId": "build",
      "match": {
        "channel": "discord",
        "accountId": "build"
      }
    },
    {
      "agentId": "ops",
      "match": {
        "channel": "discord",
        "accountId": "*"
      }
    }
  ]
}

このブロックで重要なのは4点です。マルチエージェントページが「エージェント間で agentDir を決して再利用しないでください。認証・セッション状態の衝突を引き起こします」と警告しているため、各エージェントに独自の agentDir があります。ops エージェントは model の 文字列 形式を使用します。エントリのページではこれを「モデルのフォールバックなしの、エージェントごとの厳格なプライマリ」と定義しているため、障害は表面化し、通常の処理が高価な階層へひそかに移行することはありません。build エージェントは明示的な fallbacks リストを持つオブジェクト形式を使用します。これはエージェントをフォールバック対象にする方法です。フェイルオーバーのページには、エージェントが model: { fallbacks: [...] } だけを設定して共有プライマリを継承し続けることもできるとあります。また、1つの照合階層内では「最初に一致した bindings エントリが優先」されるため、狭いバインディングをワイルドカードより上に置きます。

ワークスペースのデフォルトはデフォルトエージェントとそれ以外で異なるため、明示的に設定する価値があります。デフォルトエージェントのワークスペースは <stateDir>/workspace、その他のエージェントのデフォルトは <stateDir>/workspace-<agentId> です。OpenClaw の組み込みエンジンは「エージェントのワークスペースにプレーンな Markdown ファイルを書き込むことで物事を記憶する」ため、メモリはワークスペースに従います。つまり、ワークスペースを分離することがメモリを分離する方法です。セッションの権限モードはさらに別の軸です：read-only、guarded、workspace、full。このうち「full には operator.admin が必要です。他のモードには operator.write が必要です」（権限モード、2026年9月21日）。高価ではないモデルを権限の広いエージェントに割り当てても、そのエージェントの権限が広いことに変わりはありません。

エージェントごとに分離されるものと、分離されないもの

これは料金表では見落とされる境界です。個別のエントリにより、ファイル、メモリ、履歴、ツールポリシー、保存された認証プロファイルが分離されます。しかし、それだけで、環境設定されたカスタムプロバイダーに対する API キーまでエージェントごとに分離されるわけではありません。文書化されたエージェントごとのスキーマには、baseUrl、apiKey、providers のフィールドがまったくありません。ドキュメントにないことは、コードがそれを禁止している証拠ではないため、ここでは 文書化されていないと解釈してください。テナントごとに厳格なキー分離が必要なら、別々の Gateway を実行してください。アイデンティティにも関連する制限があります。OpenClaw の WhatsApp DM 分割例には、「返信は同じ WhatsApp 番号から送信されます。エージェントごとの送信者アイデンティティはありません」、また「ダイレクトチャットはデフォルトでエージェントのメインセッションキーに統合されるため、真の分離には1人につき1エージェントが必要」とあります。この記述は WhatsApp について述べたものです。一般化する前に、利用するチャネルのページを確認してください。

役割を分割する際に、もう1つ能力の境界に注意してください。Kunavo はテキスト読み上げ、音声認識、埋め込みモデルを提供していないため、音声出力やベクトルインデックスを必要とするエージェントは、その処理のために外部プロバイダーを呼び出す必要があります。

OpenClaw の複数モデル：厳格動作、フォールバック、ポリシー、ユーティリティレーン

エージェントごとのモデル選択には、意図的に設定する価値のある4つの制御があります。文字列形式の model は厳格です。{ primary, fallbacks: [...] } により、そのエージェントがフォールバック対象になります。modelPolicy.allow は「そのエージェントのデフォルトポリシーを置き換える」許可リストで、エイリアス、完全一致の参照、末尾ワイルドカードを受け入れます。これにより、通常のエージェントが高価なモデルへ到達するのを防げます。utilityModel は別の、通常はより安価なモデルであり、「生成されるセッション名やスレッド名などの短い内部タスク」に使われ、エージェントごとの上書きも可能です。

文書化されたトリガー一覧は具体的です。OpenClaw は「認証失敗、レート制限、クールダウンの枯渇、過負荷またはプロバイダー使用中エラー、タイムアウト形式のフォールバックエラー、請求による無効化、model_not_found」、および候補が残っている間のその他の未認識エラーで次の候補へ進みます。ただし、コンテキストオーバーフローエラーではコンパクションと再試行の処理内に留まり、「タイムアウトまたはフォールバック形式ではない明示的な中止」でも進みません。グループおよびチャネル以外の会話では、Model Fallback: <fallback> (selected <primary>; <reason>) 形式のステータス通知と対応する解除通知が表示されます。一方、グループおよびチャネル会話では「同じフォールバック状態を保持したまま、表示される通知を抑制」するため、共有ルームで通知が見えることを前提にしないでください。明示的なセッション選択、つまり /model、モデルピッカー、session_status(model=...)、または sessions.patch は厳格です。そのモデルが返信を生成する前に失敗すると、OpenClaw は設定済みのフォールバックから回答せず、失敗を報告します。cron ジョブの --model はこれに該当しません。ドキュメントでは、これは設定済みのフォールバックを引き続き使用するジョブのプライマリであり、ジョブが payload.fallbacks: [] を設定した場合を除くと説明されています。

意図が維持されるかどうかを決める仕組みが、さらに2つあります。リクエストパラメーターは agents.defaults.params から agents.entries.*.params までの4つの階層を通じてマージされ、後の階層がキー単位で上書きします。また、並列性には計算された上限があります。agents.defaults.maxConcurrent はセッション全体で max(8, available CPU parallelism * 4) をデフォルトとし、各セッション内では処理が直列化されます。つまり、1つのエージェントへの2つのメッセージが同時に実行されることはありません。どの役割にどのモデルを割り当てるかについては、能力面を扱った Opus vs Sonnet vs Haiku を参照してください。

エージェント別ではなく、ルート別に費用を割り当てる

エージェント別の支出を報告する文書化されたコマンドがないため、ルート別に割り当てます。以下の計算は 実測請求額ではなく、上限でもない例示です。30日間の月、文書化された 30m のハートビートデフォルト（1,440回の実行）、ハートビートごとの出力トークン300、キャッシュヒットなし、メイン会話レーンの入力トークン8M・出力トークン500Kを前提とします。実行ごとの約100Kおよび約2〜5Kのコンテキスト値は、isolatedSession が何を削減するかについての OpenClaw 独自の例であり、ここで測定したものではありません。3,000は中間値です。料金は、100万トークンあたりの最新の Kunavo カタログ価格です。

最新カタログでは、入力／出力それぞれ100万トークンあたりの料金として、Claude Haiku 4.5 には $0.70 / $3.50 が、Claude Opus 5 には $3.50 / $17.50 が記載されています。重要な点は、これらの前提ではスケジュール実行レーンが支配的になることです。高性能モデルで共有セッションのハートビートを実行すると月額 $511.56 になるのに対し、同じ頻度で isolatedSession: true を設定して安価なモデルを使うと月額 $4.54 になります。OpenClaw 自身も「ハートビートは完全なエージェントターンを実行します。間隔を短くすると、より多くのトークンを消費します」と説明し、isolatedSession、lightContext、より安価な model、target: "none" を調整項目として挙げています。

安価なハートビートには文書化された障害モードがあり、それがモデル変更だけでなく isolatedSession の方が優れた調整手段である理由です。ハートビートは「実行完了後も共有セッションの既存のランタイムモデルを保持」するため、セッションを小さいモデルに切り替えたハートビートが、次のメインセッションターンまでその状態を残すことがあります。そのターンでコンテキストオーバーフローが報告される可能性があり、OpenClaw の復旧メッセージではこれを heartbeat model bleed と呼んでいます。ドキュメントの実例は32kウィンドウのローカルモデルなので、リスクの大きさは、ハートビートモデルのコンテキストウィンドウが共有セッションの必要量よりどれだけ小さいかによって変わります。スケジュールに関する注意点として、文書化されたデフォルト間隔は 30m であり、解決された認証モードが Anthropic OAuth/token の場合にのみ 1h へ延長されます。そのため、通常の API キールートは、heartbeat.every を自分で設定しない限り30分のままです。予算を立てる前に、実際の値を確認してください。

ドル表示について2点注意があります。Kunavo のカタログ金額は上限ではなく請求下限です。上流プロバイダーが請求額を報告する場合、請求額はカタログ費用と、適用されるマークアップを掛けた上流費用の大きい方になります。また、モデルごとの cost オブジェクトなしで宣言されたカスタムプロバイダーでは、OpenClaw 自身の表示は役に立ちません。cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } がデフォルトとなり、サプライヤーが通常どおり請求していても $0 と表示されます。追加する各モデルに cost、contextWindow、maxTokens を宣言し、プロバイダーの台帳と照合してください。Kunavo の最低チャージ額は前払いクレジット $10 です。これは資金投入の最低額であり、タスク料金でもサブスクリプション料金でもありません。請求の詳細 と AI のコスト最適化 を参照してください。

複数エージェント Gateway に適した購入ルート

方言について1点補足します。キャッシュが費用を左右するためです。関連ガイドの Kunavo ブロックでは api: "anthropic-messages" を宣言しており、OpenClaw はこれを直接の Anthropic エンドポイントではないものとして扱います。文書化された結果は2つあります。そのようなエンドポイントでは暗黙の Anthropic ベータヘッダーが抑制されるため、インターリーブ思考などの機能は自動ではなく、明示的な headers["anthropic-beta"] によってオプトインします。また、キャッシュは明示的に要求する必要があります。OpenClaw は直接の anthropic および anthropic-vertex プロバイダーに対してのみ cacheRetention: "short" を初期化します。一方、「カスタム anthropic-messages 互換エンドポイント」は「cacheRetention が明示的に設定されている場合」にサポートされるため、デフォルトを想定せず、自分で params.cacheRetention を設定してください（プロンプトキャッシュ、2026年9月21日）。別の方言については、非ネイティブエンドポイントへの openai-completions ルートは「プロンプトキャッシュのヒントを送信しない」という別ルールがあります。繰り返し使うコンテキストがキャッシュにヒットすると見込んで予算を立てる前に、自分のルートで報告されるキャッシュ使用量を確認してください。料金面については プロンプトキャッシュ を参照してください。

意図した場所に反映されたことを確認する

openclaw config validate
openclaw gateway restart
openclaw agents list --bindings
openclaw models status --agent ops --json --check
openclaw models list --agent build

Config validation は形式を確認し、gateway restart は設定を再読み込みします。しかし、どちらも請求対象のリクエストが成功したことを証明するものではありません。openclaw agents list --bindings は実際に読み込まれたルーティングを表示します。概念ページには登場しますが、CLI command table にはない --tree より、こちらを優先してください。openclaw models status --agent <id> はそのエージェントに設定されたデフォルトを説明し、models list --agent <id> はそのインベントリを表示します。未知のプロバイダーで models set が非ゼロ終了する場合、それはモデル階層の問題です。プロバイダーはインストール済みプラグインであるか、models.providers 配下で宣言されている必要があります。メッセージがどのエージェントにも到達しない場合は、ルーティング階層の問題です。複数のエージェントがチャネルを共有した際に重複実行が現れる場合、OpenClaw では bot loop protection キーを防御策として文書化しています。ドキュメントが説明しているのは防止策であり、根本原因ではないため、決めつける前に診断してください。

次に、エージェントごとに1つの上限付きタスクを実行し、そのタスクについてプロバイダーアカウントに記録された請求額を確認してください。Kunavo は OpenClaw をシングルエージェントでもマルチエージェントでも実行時テストしていません。ここまでの内容はすべて OpenClaw が公開しているドキュメントから読み取ったものであり、公開設定は互換性テストではありません。試す間も、動作するルートを利用可能な状態に保ってください。プロバイダー設定 から開始し、OpenClaw の料金 で運用全体の請求額を比較し、キーへの資金投入の準備ができたら Kunavo アカウントを作成してください。

よくある質問

OpenClaw のドキュメント、CLI リファレンス、npm レジストリエントリを、パッケージバージョン 2026.9.5 の状態で2026年9月21日に確認しました。ここでは Gateway、エージェント、バインディング、または有料リクエストを実行していません。Kunavo のトークン料金は最新カタログから取得しており、このページのすべてのドル表示は、実測請求額ではなく、例示的なトークン計算です。