Multi-Agent Routing の設定ガイド

「エージェント」とは何か？

エージェントとは、それぞれが独立した「脳」のような存在です。以下の要素を個別に持っています。

• Workspace（ファイル、AGENTS.md/SOUL.md/USER.md、ローカルのメモ、ペルソナ設定など）
• State directory（agentDir：認証プロファイル、モデルレジストリ、エージェントごとの設定）
• Session store（チャット履歴とルーティング状態：~/.openclaw/agents/<agentId>/sessions 以下）
• Auth profiles（エージェントごとの認証情報）

Auth profiles はエージェントごとに管理されます。各エージェントは以下のパスから自身の情報を読み込みます。

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

メインエージェントの認証情報は自動的には共有されません。agentDir を複数のエージェントで使い回すのは絶対に避けてください。認証やセッションの衝突が起きてしまいます。もし認証情報を共有したい場合は、auth-profiles.json を別のエージェントの agentDir にコピーしてください。

Skills は、各 Workspace の skills/ フォルダを通じてエージェントごとに設定されます。共有 Skills については ~/.openclaw/skills を参照してください。詳細は Skills: per-agent vs shared を確認してくださいね。

Gateway では、1つのエージェント（デフォルト）を動かすことも、複数のエージェントを並行して動かすことも可能です。

Workspace に関する注意点： 各エージェントの Workspace は**デフォルトの作業ディレクトリ（cwd）**として扱われます。厳密なサンドボックスではありません。相対パスは Workspace 内で解決されますが、サンドボックス機能が有効でない限り、絶対パスを使えばホスト上の他の場所にもアクセスできてしまいます。詳しくは Sandboxing を見てください。

パス（クイックマップ）

• Config: ~/.openclaw/openclaw.json (または OPENCLAW_CONFIG_PATH)
• State dir: ~/.openclaw (または OPENCLAW_STATE_DIR)
• Workspace: ~/.openclaw/workspace (または ~/.openclaw/workspace-<agentId>)
• Agent dir: ~/.openclaw/agents/<agentId>/agent (または agents.list[].agentDir)
• Sessions: ~/.openclaw/agents/<agentId>/sessions

Single-agent mode（デフォルト）

特に設定をしない場合、OpenClaw は単一のエージェントを実行します。

• agentId はデフォルトで main になります。
• Sessions は agent:main:<mainKey> として保存されます。
• Workspace はデフォルトで ~/.openclaw/workspace

複数のエージェント = 複数のユーザー、複数のパーソナリティ

複数のエージェントを使用すると、それぞれの agentId は完全に独立した persona になります。

• チャンネルごとの accountId に応じた、異なる電話番号やアカウント。
• AGENTS.md や SOUL.md といったエージェントごとのワークスペースファイルによる、異なるパーソナリティ。
• 独立した auth とセッションの管理。
• 明示的に有効にしない限り、他のエージェントとデータが混ざることはありません。

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

エージェント間での QMD メモリ検索

あるエージェントが別のエージェントの QMD セッション履歴を検索する必要がある場合は、agents.list[].memorySearch.qmd.extraCollections にコレクションを追加してください。すべてのエージェントに同じ共有履歴コレクションを継承させたい場合にのみ、agents.defaults.memorySearch.qmd.extraCollections を使用します。

{
  agents: {
    defaults: {
      workspace: "~/workspaces/main",
      memorySearch: {
        qmd: {
          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
        },
      },
    },
    list: [
      {
        id: "main",
        workspace: "~/workspaces/main",
        memorySearch: {
          qmd: {
            extraCollections: [{ path: "notes" }], // resolves inside workspace -> collection named "notes-main"
          },
        },
      },
      { id: "family", workspace: "~/workspaces/family" },
    ],
  },
  memory: {
    backend: "qmd",
    qmd: { includeDefaultMemory: false },
  },
}

追加のコレクションパスはエージェント間で共有できますが、パスがエージェントのワークスペース外にある場合、コレクション名は明示的な指定に従います。ワークスペース内のパスはエージェントごとにスコープが限定されるため、各エージェントは独自の履歴検索セットを保持できます。

1つの WhatsApp 番号を複数人で利用する（DM 分割）

1つの WhatsApp アカウントを使いながら、異なる WhatsApp DM を別々のエージェントにルーティングできます。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 アカウントごとにグローバルに適用されます（ペアリングや allowlist）。
• 共有グループの場合は、グループを1つのエージェントに紐付けるか、Broadcast groups を使用してください。

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

Binding は決定論的であり、最も具体的な条件に一致するものが優先されます。

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）

同じ優先順位で複数の Binding がマッチした場合は、設定ファイル内で先に記述されているものが優先されます。1つの Binding に複数のマッチフィールド（例: peer と guildId）を設定した場合、指定されたすべてのフィールドが一致する必要があります（AND 条件）。

アカウントスコープに関する重要な詳細：

• accountId を省略した Binding は、デフォルトのアカウントにのみマッチします。
• すべてのアカウントにわたるチャンネル全体のフォールバックには、accountId: "*" を使用してください。
• 後から同じエージェントに対して明示的なアカウント ID を持つ同じ Binding を追加した場合、OpenClaw は既存のチャンネル限定 Binding を複製するのではなく、アカウントスコープにアップグレードします。

AI Setup Assistant

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

WhatsAppなどの複数のアカウントをサポートするChannelでは、各ログインを識別するために accountId を使用します。それぞれの accountId は異なるAgentにルーティングできるため、1つのサーバーでセッションを混同することなく、複数の電話番号をホストできます。

accountId が省略された場合にChannel全体で適用されるデフォルトアカウントを設定したいときは、 channels.<channel>.defaultAccount （任意）を指定してください。設定されていない場合、OpenClawは default があればそれを使い、なければ設定されている最初の accountId （ソート順）をフォールバックとして使用します。

このパターンをサポートしている主なChannelは以下の通りです：

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

コンセプト

• agentId: 1つの「脳」（ワークスペース、Agentごとの認証、Agentごとのセッションストレージ）。
• accountId: 1つのChannelアカウントのインスタンス（例：WhatsAppアカウントの "personal" と "biz"）。
• binding: (channel, accountId, peer) や、オプションのguild/team IDに基づいて、受信メッセージを agentId にルーティングします。
• Direct chats: agent:<agentId>:<mainKey> に集約されます（Agentごとの「メイン」、 session.mainKey ）。

プラットフォームの構成例

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

各 Discord ボットアカウントは、一意の accountId にマッピングされます。各アカウントをエージェントにバインドし、ボットごとに allowlist を保持します。

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

注意点：

• 各ボットをサーバー（guild）に招待し、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 番号

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

  // 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-6",
      },
      {
        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" } },
  ],
}

注意点：

• 1つのチャンネルに複数のアカウントがある場合は、binding に accountId を追加してください（例：{ channel: "whatsapp", accountId: "personal" }）。
• 特定の DM やグループだけを Opus にルーティングし、残りを chat に残したい場合は、その peer 用の match.peer binding を追加します。peer の一致は、チャンネル全体のルールよりも常に優先されます。

同じチャンネル内で、特定の相手だけ Opus に割り当てる例

通常の WhatsApp はレスポンスの速い Agent に任せつつ、特定の相手とのダイレクトメッセージ（DM）だけを Opus にルーティングする設定です。

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      {
        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" } },
  ],
}

Peer（相手）ごとの設定は常に優先されるため、チャンネル全体の設定よりも上に記述するようにしてください。

WhatsApp グループ専用のファミリー Agent

特定の WhatsApp グループに専用のファミリー Agent を割り当てます。メンションによるフィルタリングや、より厳格なツールポリシーを適用した例です。

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

注意点：

• ツールの許可・拒否リスト（allow/deny）は、あくまで tools の設定であり、スキルそのものではありません。もしスキルがバイナリを実行する必要がある場合は、exec が許可されており、かつそのバイナリが sandbox 内に存在することを確認してください。
• より厳密に制限したい場合は、agents.list[].groupChat.mentionPatterns を設定し、チャンネル側でグループの allowlist を有効にしたままにしてください。

エージェントごとの Sandbox とツールの設定

各エージェントには、それぞれ独自の Sandbox やツールの制限を設定できます。

{
  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 の配下に記述し、コンテナ作成時に一度だけ実行されます。また、解決されたスコープが "shared" の場合、エージェントごとの sandbox.docker.* による上書きは無視されます。

メリット:

• セキュリティの隔離: 信頼できないエージェントに対してツールの使用を制限できます。
• リソースの制御: 特定のエージェントのみを Sandbox 化し、他のエージェントはホスト上で動作させることが可能です。
• 柔軟なポリシー設定: エージェントごとに異なる権限を割り当てられます。
• 環境の最適化: 各エージェントの役割に応じたセットアップを個別に行えます。

注意：tools.elevated はグローバルな設定であり、送信者に基づきます。エージェントごとに設定することはできません。エージェントごとの境界が必要な場合は、agents.list[].tools を使用して exec を拒否してください。グループチャットでターゲットを指定する場合は、agents.list[].groupChat.mentionPatterns を使用することで、@メンションを目的のエージェントに正確に紐付けることができます。

詳細は Multi-Agent Sandbox & Tools の例を確認してください。

関連情報

• Channel Routing — メッセージがどのようにエージェントへルーティングされるか
• Sub-Agents — バックグラウンドでのエージェント実行の開始
• ACP Agents — 外部のコーディング用ハーネスの実行
• Presence — エージェントのプレゼンスと利用可能性
• Session — セッションの隔離とルーティング

openclaw agents add work

openclaw agents list --bindings

openclaw agents add coding
openclaw agents add social

openclaw channels login --channel whatsapp --account work

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