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

目標: 1つの実行中のゲートウェイ内で、複数の分離されたエージェント（個別のワークスペース + agentDir + セッション）、および複数のチャネルアカウント（例: 2つの WhatsApp アカウント）を運用すること。受信メッセージはバインディングを介して適切なエージェントにルーティングされます。

「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 から共有スキルを利用することも可能です。詳細はスキル: エージェントごと vs 共有を参照してください。ゲートウェイは、1つのエージェント（デフォルト）または複数のエージェントを並行してホストできます。 ワークスペースに関する注意: 各エージェントのワークスペースはデフォルトの作業ディレクトリ (cwd) であり、厳密なサンドボックスではありません。相対パスはワークスペース内で解決されますが、サンドボックスが有効でない限り、絶対パスを使用してホスト上の他の場所にアクセスできてしまいます。詳細はサンドボックスを参照してください。

パス (クイックマップ)

構成ファイル: ~/.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

クイックスタート

各エージェントのワークスペースを作成する

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

openclaw agents add coding
openclaw agents add social

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

チャネルアカウントを作成する

利用したいチャネルで、エージェントごとにアカウントを作成します。

Discord: エージェントごとに 1 つのボットを作成し、「Message Content Intent」を有効にして、それぞれのトークンをコピーします。
Telegram: BotFather を使用してエージェントごとに 1 つのボットを作成し、それぞれのトークンをコピーします。
WhatsApp: アカウントごとに電話番号をリンクします。

openclaw channels login --channel whatsapp --account work

詳細はチャネルガイドを参照してください: Discord、Telegram、WhatsApp。

エージェント、アカウント、バインディングを追加する

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

再起動して確認する

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

複数のエージェント = 複数の人格、複数のキャラクター

複数のエージェントを運用する場合、各 agentId は完全に独立したペルソナとして機能します。

異なる電話番号/アカウント (チャネルごとの accountId)。
異なるキャラクター (AGENTS.md や SOUL.md などのエージェントごとのワークスペースファイルによる設定)。
個別の認証とセッション (明示的に有効にしない限り、データが混ざることはありません)。

これにより、複数のユーザーが 1 つのゲートウェイサーバーを共有しながら、それぞれの AI の「頭脳」とデータを分離して保持できます。

1 つの WhatsApp 番号で、複数人を相手にする (DM 分割)

1 つの 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 アカウント単位でグローバルに適用されます（ペアリング/許可リスト）。
共有グループの場合は、グループを特定のエージェントにバインドするか、ブロードキャストグループを使用してください。

ルーティングルール (メッセージがどのエージェントに送られるか)

バインディングは確定的であり、最も条件が限定されているもの（具体的なもの）が優先されます。

peer の一致 (特定の DM/グループ/チャネル ID)
parentPeer の一致 (スレッドの継承)
guildId + roles (Discord のロールによるルーティング)
guildId (Discord)
teamId (Slack)
accountId によるチャネルの一致
チャネルレベルの一致 (accountId: "*")
デフォルトエージェントへのフォールバック (agents.list[].default、設定がない場合はリストの最初のエントリ、デフォルトは main)

複数のバインディングが同じ優先度で一致した場合は、設定ファイル内で先に記述されているものが優先されます。1つのバインディングに複数の条件（例: 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" と "biz")。
binding: 受信メッセージを (channel, accountId, peer) およびオプションでギルド/チーム ID に基づいて特定の agentId にルーティングします。
ダイレクトチャットは agent:<agentId>:<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 を使用してエージェントごとにボットを作成し、トークンをコピーしてください。
トークンは channels.telegram.accounts.<id>.botToken に設定します（デフォルトアカウントでは TELEGRAM_BOT_TOKEN 環境変数も使用可能です）。

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

ゲートウェイを起動する前に、各アカウントをリンクしておきます。

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" } },

    // 特定の相手（グループなど）を別のエージェントに送る例
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // デフォルトではオフ: エージェント間のメッセージ送信は明示的な有効化と許可が必要です。
  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 を追加してください。
特定の DM/グループだけを Opus に送り、残りを通常チャットに維持したい場合は、その相手に対して match.peer バインディングを追加してください。ピア一致は常にチャネル全体のルールよりも優先されます。

例: 同一チャネルで、特定の相手だけ 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: "120363999999999999@g.us" },
      },
    },
  ],
}

注:

ツールの許可/拒否リストはツールの設定であり、スキルの設定ではありません。スキルがバイナリを実行する必要がある場合は、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: {
            // コンテナ作成時のオプション設定
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // 読み取りツールのみ許可
          deny: ["exec", "write", "edit", "apply_patch"],    // その他を拒否
        },
      },
    ],
  },
}

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

セキュリティの分離: 信頼できないエージェントのツールを制限できます。
リソース管理: 特定のエージェントだけをサンドボックス化し、他はホスト上で実行できます。
柔軟なポリシー: エージェントごとに異なる権限を設定できます。

注: tools.elevated はグローバルかつ送信者ベースの設定であり、エージェントごとに構成することはできません。エージェントごとの境界を設けたい場合は、agents.list[].tools を使用して exec を拒否してください。グループ内でのターゲット指定には、agents.list[].groupChat.mentionPatterns を使用し、@メンションが目的のエージェントに正しくマッピングされるようにします。詳細はマルチエージェントサンドボックス & ツールを参照してください。

基礎

ブートストラップ

セッションとメモリ