マルチエージェントルーティング

目標: 複数の_分離された_エージェント（個別のワークスペース＋agentDir＋セッション）に加え、複数のチャネルアカウント（例: 2つのWhatsApp）を1つのGatewayで運用すること。受信メッセージはバインディングによってエージェントにルーティングされます。

「1つのエージェント」とは

エージェントとは、以下を独自に持つ完全にスコープされた頭脳です:

  • ワークスペース（ファイル、AGENTS.md/SOUL.md/USER.md、ローカルメモ、ペルソナルール）。
  • 状態ディレクトリ（agentDir）--- 認証プロファイル、モデルレジストリ、エージェント別設定。
  • セッションストア（チャット履歴＋ルーティング状態）--- ~/.openclaw/agents/<agentId>/sessions 配下。

認証プロファイルはエージェントごとです。各エージェントは自身の以下のファイルから読み取ります:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

メインエージェントの認証情報は自動的には共有されません。agentDir をエージェント間で使い回さないでください（認証/セッションの衝突が発生します）。認証情報を共有したい場合は、auth-profiles.json を他のエージェントの agentDir にコピーしてください。

スキルはワークスペースの skills/ フォルダによるエージェントごとの設定で、共有スキルは ~/.openclaw/skills から利用可能です。Skills: per-agent vs sharedを参照。

Gatewayは1つのエージェント（デフォルト）または複数のエージェントを並列でホストできます。

ワークスペースに関する注意: 各エージェントのワークスペースはデフォルトのcwdであり、厳密なサンドボックスではありません。相対パスはワークスペース内で解決されますが、サンドボックスが有効でない限り絶対パスでホスト上の他の場所にアクセスできます。Sandboxingを参照。

パス（クイックマップ）

  • 設定: ~/.openclaw/openclaw.json（または OPENCLAW_CONFIG_PATH）
  • 状態ディレクトリ: ~/.openclaw（または OPENCLAW_STATE_DIR）
  • ワークスペース: ~/.openclaw/workspace（または ~/.openclaw/workspace-<agentId>）
  • エージェントディレクトリ: ~/.openclaw/agents/<agentId>/agent（または agents.list[].agentDir）
  • セッション: ~/.openclaw/agents/<agentId>/sessions

シングルエージェントモード（デフォルト）

何も設定しなければ、OpenClawは単一エージェントで動作します:

  • agentId のデフォルトは**main**。
  • セッションは agent:main:<mainKey> としてキーイング。
  • ワークスペースのデフォルトは ~/.openclaw/workspace（OPENCLAW_PROFILE 設定時は ~/.openclaw/workspace-<profile>）。
  • 状態のデフォルトは ~/.openclaw/agents/main/agent。

エージェントヘルパー

エージェントウィザードで新しい分離されたエージェントを追加:

openclaw agents add work

その後、bindings を追加（またはウィザードに任せて）受信メッセージをルーティングします。

確認:

openclaw agents list --bindings

クイックスタート

ステップ1: 各エージェントのワークスペースを作成

ウィザードを使用するか手動でワークスペースを作成:

openclaw agents add coding
openclaw agents add social

各エージェントは SOUL.md、AGENTS.md、オプションの USER.md を含む独自のワークスペースに加え、~/.openclaw/agents/<agentId> 配下に専用の agentDir とセッションストアを持ちます。

ステップ2: チャネルアカウントの作成

好みのチャネルでエージェントごとに1アカウントを作成:

  • Discord: エージェントごとに1ボット、Message Content Intentを有効化、各トークンをコピー。
  • Telegram: BotFatherでエージェントごとに1ボット、各トークンをコピー。
  • WhatsApp: アカウントごとに電話番号をリンク。
openclaw channels login --channel whatsapp --account work

チャネルガイド: Discord、Telegram、WhatsAppを参照。

ステップ3: エージェント、アカウント、バインディングの追加

agents.list にエージェント、channels.<channel>.accounts にチャネルアカウントを追加し、bindings で接続（例は後述）。

ステップ4: 再起動と確認

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

複数エージェント＝複数の人格、複数のパーソナリティ

複数エージェントでは、各 agentId が完全に分離されたペルソナになります:

  • 異なる電話番号/アカウント（チャネルの accountId ごと）。
  • 異なるパーソナリティ（エージェントごとのワークスペースファイル AGENTS.md や SOUL.md）。
  • 別々の認証＋セッション（明示的に有効にしない限りクロストークなし）。

これにより複数の人が1つのGatewayサーバーを共有しながら、AIの「頭脳」とデータを分離して保持できます。

1つのWhatsApp番号で複数人（DMスプリット）

1つのWhatsAppアカウントのまま、異なるWhatsApp DMを異なるエージェントにルーティングできます。送信者のE.164（+15551234567 のような形式）と peer.kind: "direct" でマッチングします。応答は同じWhatsApp番号から送信されます（エージェントごとの送信者IDはありません）。

重要な詳細: ダイレクトチャットはエージェントのメインセッションキーに集約されるため、真の分離には1人1エージェントが必要です。

例:

{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" },
    ],
  },
  bindings: [
    {
      agentId: "alex",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
    },
    {
      agentId: "mia",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
    },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}

注意:

  • DMアクセス制御はエージェントごとではなくWhatsAppアカウントごとのグローバル設定（ペアリング/許可リスト）です。
  • 共有グループの場合、グループを1つのエージェントにバインドするか、Broadcast groupsを使用してください。

ルーティングルール（メッセージがエージェントを選ぶ仕組み）

バインディングは決定的かつ最も具体的なものが優先:

  1. peer マッチ（正確なDM/グループ/チャネルID）
  2. parentPeer マッチ（スレッド継承）
  3. guildId + roles（Discordロールルーティング）
  4. guildId（Discord）
  5. teamId（Slack）
  6. チャネルの accountId マッチ
  7. チャネルレベルマッチ（accountId: "*"）
  8. デフォルトエージェントへのフォールバック（agents.list[].default、なければ最初のリスト要素、デフォルト: main）

同じ階層で複数のバインディングがマッチした場合、設定順序で最初のものが優先されます。 バインディングが複数のマッチフィールドを設定する場合（例: peer + guildId）、指定されたすべてのフィールドが必要です（AND セマンティクス）。

アカウントスコープの重要な詳細:

  • accountId を省略したバインディングはデフォルトアカウントのみにマッチ。
  • 全アカウントにまたがるチャネルワイドフォールバックには accountId: "*" を使用。
  • 同じエージェントに対して明示的なアカウントIDで同じバインディングを後から追加すると、OpenClawは既存のチャネルのみのバインディングを複製せずにアカウントスコープにアップグレードします。

複数アカウント/電話番号

複数アカウントをサポートするチャネル（例: WhatsApp）は accountId で各ログインを識別します。各 accountId を異なるエージェントにルーティングでき、1台のサーバーでセッションを混在させずに複数の電話番号をホストできます。

accountId 省略時のチャネルワイドのデフォルトアカウントが必要な場合は、channels.<channel>.defaultAccount を設定（オプション）。未設定の場合、OpenClawは default が存在すればそれを、そうでなければ最初の設定済みアカウントID（ソート順）にフォールバックします。

このパターンをサポートする一般的なチャネル:

  • whatsapp、telegram、discord、slack、signal、imessage
  • irc、line、googlechat、mattermost、matrix、nextcloud-talk
  • bluebubbles、zalo、zalouser、nostr、feishu

コンセプト

  • agentId: 1つの「頭脳」（ワークスペース、エージェント別認証、エージェント別セッションストア）。
  • accountId: 1つのチャネルアカウントインスタンス（例: WhatsAppアカウント "personal" vs "biz"）。
  • binding: 受信メッセージを (channel, accountId, peer) およびオプションのguild/team IDで agentId にルーティング。
  • ダイレクトチャットは agent:<agentId>:<mainKey> に集約（エージェントごとの「main」、session.mainKey）。

プラットフォーム例

エージェントごとのDiscordボット

各Discordボットアカウントは一意の accountId にマッピングされます。各アカウントをエージェントにバインドし、ボットごとに許可リストを設定します。

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },
  ],
  channels: {
    discord: {
      groupPolicy: "allowlist",
      accounts: {
        default: {
          token: "DISCORD_BOT_TOKEN_MAIN",
          guilds: {
            "123456789012345678": {
              channels: {
                "222222222222222222": { allow: true, requireMention: false },
              },
            },
          },
        },
        coding: {
          token: "DISCORD_BOT_TOKEN_CODING",
          guilds: {
            "123456789012345678": {
              channels: {
                "333333333333333333": { allow: true, requireMention: false },
              },
            },
          },
        },
      },
    },
  },
}

注意:

  • 各ボットをギルドに招待し、Message Content Intentを有効にしてください。
  • トークンは channels.discord.accounts.<id>.token に設定（デフォルトアカウントは DISCORD_BOT_TOKEN を使用可能）。

エージェントごとのTelegramボット

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
  ],
  channels: {
    telegram: {
      accounts: {
        default: {
          botToken: "123456:ABC...",
          dmPolicy: "pairing",
        },
        alerts: {
          botToken: "987654:XYZ...",
          dmPolicy: "allowlist",
          allowFrom: ["tg:123456789"],
        },
      },
    },
  },
}

注意:

  • BotFatherでエージェントごとに1ボットを作成し、各トークンをコピー。
  • トークンは channels.telegram.accounts.<id>.botToken に設定（デフォルトアカウントは TELEGRAM_BOT_TOKEN を使用可能）。

エージェントごとのWhatsApp番号

Gateway起動前に各アカウントをリンク:

openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz

~/.openclaw/openclaw.json（JSON5）:

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent",
      },
    ],
  },

  // 決定的ルーティング: 最初のマッチが優先（最も具体的なものを先に）。
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // オプションのピアごとオーバーライド（例: 特定のグループをworkエージェントに送信）。
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],

  // デフォルトでオフ: エージェント間メッセージングは明示的に有効化＋許可リスト化が必要。
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // オプションのオーバーライド。デフォルト: ~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // オプションのオーバーライド。デフォルト: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

例: WhatsApp日常チャット＋Telegramディープワーク

チャネルで分割: WhatsAppを高速な日常エージェントに、TelegramをOpusエージェントにルーティング。

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

注意:

  • チャネルに複数アカウントがある場合、バインディングに accountId を追加（例: { channel: "whatsapp", accountId: "personal" }）。
  • 残りをチャットに保ちつつ単一のDM/グループをOpusにルーティングするには、そのピアに対する match.peer バインディングを追加。ピアマッチは常にチャネルワイドルールより優先されます。

例: 同じチャネルで1つのピアだけOpusへ

WhatsAppは高速エージェントのまま、1つのDMだけをOpusにルーティング:

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    {
      agentId: "opus",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } },
    },
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}

ピアバインディングは常に優先されるため、チャネルワイドルールより上に配置してください。

WhatsAppグループにバインドされたファミリーエージェント

メンションゲーティングとより厳格なツールポリシーを持つ専用ファミリーエージェントを単一のWhatsAppグループにバインド:

{
  agents: {
    list: [
      {
        id: "family",
        name: "Family",
        workspace: "~/.openclaw/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
        },
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: [
            "exec",
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
        },
      },
    ],
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],
}

注意:

  • ツールのallow/denyリストはツールであり、スキルではありません。スキルがバイナリの実行を必要とする場合、exec が許可されていてサンドボックス内にバイナリが存在することを確認してください。
  • より厳格なゲーティングには agents.list[].groupChat.mentionPatterns を設定し、チャネルのグループ許可リストを有効にしてください。

エージェントごとのサンドボックスとツール設定

v2026.1.6以降、各エージェントは独自のサンドボックスとツール制限を持てます:

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // パーソナルエージェントにはサンドボックスなし
        },
        // ツール制限なし - すべてのツールが利用可能
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // 常にサンドボックス化
          scope: "agent",  // エージェントごとに1コンテナ
          docker: {
            // コンテナ作成後のオプションの1回限りセットアップ
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // readツールのみ
          deny: ["exec", "write", "edit", "apply_patch"],    // その他を拒否
        },
      },
    ],
  },
}

注意: setupCommand は sandbox.docker 配下にあり、コンテナ作成時に1回実行されます。 解決されたスコープが "shared" の場合、エージェントごとの sandbox.docker.* オーバーライドは無視されます。

利点:

  • セキュリティ分離: 信頼されていないエージェントのツールを制限
  • リソース制御: 特定のエージェントをサンドボックス化しつつ他はホスト上で実行
  • 柔軟なポリシー: エージェントごとに異なる権限

注意: tools.elevated はグローバルかつ送信者ベースであり、エージェントごとの設定はできません。エージェントごとの境界が必要な場合は agents.list[].tools で exec を拒否してください。 グループターゲティングには agents.list[].groupChat.mentionPatterns を使用して @メンションが意図したエージェントにきれいにマッピングされるようにしてください。

詳細例はMulti-Agent Sandbox & Toolsを参照。

arrow_back
前へ
Compaction
次へ
Presence
arrow_forward