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

目的：1 つの稼働中の Gateway で、複数の 分離された エージェント（個別のワークスペース + agentDir + セッション）と、複数のチャンネルアカウント（例：2 つの WhatsApp）を同時に扱います。インバウンドは、バインディングによってエージェントへルーティングされます。インバウンドはバインディングを介してエージェントにルーティングされます。

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

エージェントとは、次をそれぞれ専有する、完全にスコープ化された「頭脳」です。

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

認証プロファイルは エージェント単位 です。各エージェントは、次から読み取ります。各エージェントは以下のように読み込みます。

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

メインエージェントの資格情報は 共有されません 。エージェント間で agentDir を再利用しないでください (認証/セッションの衝突を引き起こします)。メインエージェントの認証情報は自動的に共有 されません。エージェント間で agentDir を再利用しないでください（認証／セッションの衝突を引き起こします）。認証情報を共有したい場合は、auth-profiles.json を別のエージェントの agentDir にコピーしてください。

Skills は、各ワークスペースの skills/ フォルダーを通じて エージェント単位 で提供され、共有 Skills は ~/.openclaw/skills から利用できます。詳細は Skills: per-agent vs shared を参照してください。 Skills: per-agent vs sharedを参照してください。

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

ワークスペースに関する注意： 各エージェントのワークスペースは デフォルトの cwd であり、厳密なサンドボックスではありません。相対パスはワークスペース内に解決されますが、サンドボックス化が有効でない限り、絶対パスはホスト上の他の場所へ到達できます。詳細は Sandboxing を参照してください。ワークスペース内では相対パスが解決されますが、サンドボックス化が有効になっていない限り、絶対パスは他のホストロケーションに到達することができます。 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

複数エージェント = 複数人、複数の人格¶

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

異なる電話番号／アカウント（チャンネル accountId 単位）。
異なる人格（AGENTS.md や SOUL.md など、エージェント別ワークスペースファイル）。
分離された認証 + セッション（明示的に有効化しない限り、相互干渉はありません）。

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

1 つの WhatsApp 番号、複数人（DM 分割）¶

1 つの WhatsApp アカウント のまま、異なる WhatsApp DM を異なるエージェントへルーティングできます。送信者の E.164（例：+15551234567）に一致させて peer.kind: "dm" を行います。返信は同じ WhatsApp 番号から送信されます（エージェントごとの送信者 ID はありません）。 peer.kind: "direct" を使用して、送信者の E.164（例: +15551234567）にマッチさせます。返信は依然として同じ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 を使用してください。

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

バインディングは 決定論的 と ほとんどの特定の勝利です:

peer の一致（正確な DM／グループ／チャンネル ID）
guildId（Discord）
teamId（Slack）
チャンネルに対する accountId の一致
チャンネルレベルの一致（accountId: "*"）
デフォルトエージェントへフォールバック（agents.list[].default、それ以外は最初のエントリ、デフォルト：main）

複数アカウント／電話番号¶

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

概念¶

agentId：1 つの「頭脳」（ワークスペース、エージェント別認証、エージェント別セッションストア）。
accountId：1 つのチャンネルアカウントインスタンス（例：WhatsApp アカウント "personal" と "biz"）。
binding：(channel, accountId, peer) および必要に応じてギルド／チーム ID により、インバウンドメッセージを agentId へルーティングします。
ダイレクトチャットは agent:<agentId>:<mainKey>（エージェント別の「メイン」；session.mainKey）に集約されます。

例：2 つの WhatsApp → 2 つのエージェント¶

~/.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",
      },
    ],
  },

  // Deterministic routing: first match wins (most-specific first).
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // Optional per-peer override (example: send a specific group to work agent).
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // Optional override. Default: ~/.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 グループにバインドされたファミリーエージェント¶

メンションゲーティングと、より厳格なツールポリシーを用いて、専用のファミリーエージェントを 1 つの 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",  // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // Always sandboxed
          scope: "agent",  // One container per agent
          docker: {
            // Optional one-time setup after container creation
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Only read tool
          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
        },
      },
    ],
  },
}

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

利点：

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

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

詳細な例は Multi-Agent Sandbox & Tools を参照してください。

Fundamentals

Bootstrapping

Sessions and memory

Multi-agent

Messages and delivery

Multi-Agent Routing

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

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

パス（クイックマップ）¶

単一エージェントモード（デフォルト）¶

エージェントヘルパー¶

複数エージェント = 複数人、複数の人格¶

1 つの WhatsApp 番号、複数人（DM 分割）¶

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

複数アカウント／電話番号¶

概念¶

例：2 つの WhatsApp → 2 つのエージェント¶

例：WhatsApp の日常チャット + Telegram の集中作業¶

例：同一チャンネルで、1 つのピアのみを Opus へ¶

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

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

Fundamentals

Bootstrapping

Sessions and memory

Multi-agent

Messages and delivery

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

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

パス（クイック マップ）¶

単一エージェント モード（デフォルト）¶

エージェント ヘルパー¶

複数エージェント = 複数人、複数の人格¶

1 つの WhatsApp 番号、複数人（DM 分割）¶

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

複数アカウント／電話番号¶

概念¶

例：2 つの WhatsApp → 2 つのエージェント¶

例：WhatsApp の日常チャット + Telegram の集中作業¶

例：同一チャンネルで、1 つのピアのみを Opus へ¶

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

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

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

パス（クイックマップ）¶

単一エージェントモード（デフォルト）¶

エージェントヘルパー¶

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

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