Tech

OpenClaw multi-agent routing 設計ガイド - agentId・accountId・binding を分ける

nidoneko · · 15 min read
OpenClawAIエージェントマルチエージェント運用設計
🧩

OpenClaw で複数 agent を増やす前に、routing 境界を決める

OpenClaw を使っていると、すぐに複数 agent を作りたくなります。個人用、仕事用、家族用、通知用、調査用、深い作業用。入口も WhatsApp、Telegram、Discord、Slack のように増えていきます。

ここで雑に増やすと、最初に壊れるのはモデルの品質ではありません。誰の memory で、どの channel から来た依頼を、どの agent が、どの権限で処理しているか が見えなくなります。

この記事では、OpenClaw の multi-agent routing だけを扱います。OpenClaw 全体の使い方は OpenClaw の使い方入門、workspace と memory の置き方は OpenClaw workspace 設計ガイド、安全設定は OpenClaw のセキュリティ設定入門、一般的な分担パターンは マルチエージェントオーケストレーション 4パターン解説 に分けています。

私の結論は、OpenClaw の multi-agent は「人格を増やす機能」ではなく、workspace、auth、session、channel、tool policy を分ける運用境界として設計するべきです。

まず agentId と accountId を混同しない

OpenClaw の routing で最初に分けるべき言葉は、agentId と accountId です。

用語意味例
agentId1つの agent の脳と状態main, work, alerts
accountIdchannel 側のアカウントWhatsApp personal, Telegram alerts
bindinginbound message を agent に送る規則channel + accountId + peer -> agentId
workspaceagent が読む operating files と memory~/.openclaw/workspace-work
agentDirauth profiles や session store を持つ state directory~/.openclaw/agents/work/agent

agentId は「どの agent が考えるか」です。accountId は「どの channel account で受けたか」です。この2つを同じ名前にしても構いませんが、同じ概念ではありません。

たとえば WhatsApp の personal number と business number を同じ Gateway で扱うなら、routing はこう考えます。

{
  agents: {
    list: [
      {
        id: "home",
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      {
        id: "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" } },
  ],
}

これで、personal number への inbound は home agent、business number への inbound は work agent に流れます。

1 agent は workspace だけではない

OpenClaw docs では、1つの agent は workspace、state directory、session store を持つ境界として説明されています。ここが重要です。

agent を分けるなら、最低限この3つを分けます。

  • workspace: AGENTS.md、SOUL.md、USER.md、memory、local notes
  • agentDir: auth profiles、model registry、per-agent config
  • session store: chat history と routing state

workspace だけ分けても、auth や session が混ざると意味が薄いです。特に agentDir の共有は避けるべきです。別 agent が同じ auth profile や session state を見に行くと、どの agent の権限で動いたのか説明できなくなります。

私は、複数 agent を作るときは最初から path を明示します。

{
  agents: {
    list: [
      {
        id: "main",
        workspace: "~/Private/openclaw/main",
        agentDir: "~/.openclaw/agents/main/agent",
      },
      {
        id: "support",
        workspace: "~/Private/openclaw/support",
        agentDir: "~/.openclaw/agents/support/agent",
      },
    ],
  },
}

この形にしておくと、backup、権限棚卸し、事故調査が楽になります。

binding は「最も具体的なルール」を先に置く

OpenClaw の binding は inbound message を agent に送る規則です。ここは route table として扱った方が安全です。

よくある失敗は、channel-wide な fallback を先に置いて、特定 peer の例外が効いているつもりになることです。routing では、peer、group、account、channel のような粒度を意識して、例外を具体的に書きます。

たとえば、普段は WhatsApp を everyday agent に流し、特定の相手だけ deep work agent に流すなら、具体的な peer binding を先に置きます。

{
  agents: {
    list: [
      { id: "chat", workspace: "~/.openclaw/workspace-chat" },
      { id: "deep", workspace: "~/.openclaw/workspace-deep" },
    ],
  },
  bindings: [
    {
      agentId: "deep",
      match: {
        channel: "whatsapp",
        accountId: "*",
        peer: { kind: "direct", id: "+15551234567" },
      },
    },
    {
      agentId: "chat",
      match: { channel: "whatsapp", accountId: "*" },
    },
  ],
}

これを「普段は chat、例外だけ deep」と読めるようにするのが大事です。設定を書いた本人だけが分かる route table は、運用が続くほど危険になります。

direct chat と group では分離の意味が違う

direct chat を複数人で使う場合、true isolation が必要なら 1人1 agent に寄せます。理由は、direct chat が agent の main session key に寄りやすく、同じ agent に複数人を入れると memory と session が混ざるからです。

一方で group では、同じ channel account の中でも peer や group id で agent を分けます。

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        groupChat: {
          mentionPatterns: ["@family", "@familybot"],
        },
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: ["read", "sessions_list", "sessions_history"],
          deny: [
            "exec",
            "write",
            "edit",
            "apply_patch",
            "browser",
            "canvas",
            "cron",
          ],
        },
      },
    ],
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "120363999999999999@g.us" },
      },
    },
  ],
}

group に入れる agent は、direct DM の main agent より権限を絞るべきです。外部の人やノイズの多い会話が混ざるため、write、browser、cron、nodes のような強い tool は最初から外します。

persona を増やす前に、責務を表にする

複数 agent を作るとき、私は先にこの表を書きます。

agent入口主な仕事workspacetool policysandbox
mainpersonal DM個人 assistantworkspace-mainbroadoff or ask
workbusiness number仕事の受付・整理workspace-workread / draft 중심all
alertsTelegram bot通知・日次確認workspace-alertsread / message onlyall
deepselected peer長い調査・設計workspace-deepread / browser / draftall

この表が書けないなら、まだ agent を増やす段階ではありません。persona 名だけ増やしても、routing と権限が曖昧なら運用は強くなりません。

per-agent sandbox と tool policy を必ず持たせる

OpenClaw multi-agent の利点は、agent ごとに sandbox と tool restrictions を変えられることです。

たとえば、個人 DM の main agent は広めに使い、group 用の family agent は強く絞る、という設計ができます。

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: ["read"],
          deny: ["exec", "write", "edit", "apply_patch"],
        },
      },
    ],
  },
}

ここで大事なのは、agent の性格ファイルに「危ないことはしない」と書くだけで終わらせないことです。tool policy と sandbox は Gateway 側の制御なので、prompt injection や誤判断があっても最後に止める場所になります。

詳しい安全設定は OpenClaw のセキュリティ設定入門 側で扱っていますが、multi-agent routing では特に次を固定します。

  • public group に入る agent は write tool を持たせない
  • external account に触る agent は dedicated auth を使う
  • browser / canvas / nodes / cron は agent ごとに必要性を説明できる場合だけ許可する
  • elevated tool は global gate と per-agent gate の両方を見る

auth profile は「便利だから共有」しない

multi-agent で一番見落としやすいのは auth です。

たとえば main agent が持つ OAuth credential を、work agent が暗黙に使える状態にすると、agent を分けた意味が薄れます。OpenClaw docs でも、agentDir の再利用や credentials の扱いには注意が必要だと説明されています。

私なら、auth はこの方針にします。

credential扱い
個人用 OAuthmain agent のみ
仕事用 OAuthwork agent で別 sign-in
static API key必要なら portable profile として明示コピー
channel tokenchannel account ごとに分ける
shared secretできるだけ避け、alias だけ memory に残す

「同じ token で動いているけど agent は違う」は、監査しづらい状態です。agent を分けるなら、auth の責務も分けます。

OpenClaw の multi-agent と一般的な multi-agent 設計を分ける

一般的な multi-agent 設計では、Sequential、Concurrent、Hierarchical、Feedback Loop のような分担パターンを考えます。これは マルチエージェントオーケストレーション 4パターン解説 の範囲です。

OpenClaw の multi-agent routing は、それより手前の話です。

  • どの channel account がどの agent に届くか
  • どの workspace と memory を使うか
  • どの auth と session store を持つか
  • どの tool を Gateway 側で許可するか
  • どの sandbox scope で実行するか

つまり、OpenClaw でまず設計するのは「賢い分担」ではなく、混ぜてはいけない状態を混ぜないことです。

運用前チェックリスト

本番っぽく使う前に、私はこのチェックを通します。

チェック見るポイント
agent 一覧openclaw agents list --bindings で route を確認したか
workspaceagent ごとに memory と operating files が分かれているか
agentDirauth / session state を agent ごとに分けているか
bindingpeer 例外が channel-wide fallback より具体的に書かれているか
channel accountpersonal / work / alerts の token が混ざっていないか
sandboxpublic / shared channel に入る agent が sandboxed か
toolswrite / exec / browser / cron を必要最小限にしているか
ownerその agent の設定を誰が review するか決まっているか

この表が埋まっていれば、agent を増やしてもまだ管理できます。埋まらないなら、agent を増やすより先に routing を単純化した方がいいです。

まとめ

OpenClaw の multi-agent routing は、便利な persona 切り替えではありません。agentId、accountId、binding、workspace、agentDir、session store、sandbox、tool policy を使って、どの入口をどの agent の状態へ流すかを決める設計です。

私なら、最初は main と work の2 agent だけで始めます。workspace と agentDir を分け、business channel を work に bind し、work には sandbox と read / draft 中心の tool policy を置く。これで足りなくなってから、alerts や deep work agent を増やします。

複数 agent は、増やすほど賢くなるわけではありません。境界が明確なときだけ、運用が強くなります。

参考情報

WRITTEN BY nidoneko

Full-stack engineer with 8+ years of experience in TypeScript, React, Node.js, and cloud-native development across healthcare, finance, HR, and IoT domains.

View Profile →
// Related articles View All
⚙️
Codex

Codex config profile 設計ガイド - sandbox・approval・MCPを作業別に切り替える

·13 min read

Codex の config.toml と profile を、調査・通常実装・PRレビュー・自動化でどう分けるかを整理します。sandbox、approval、permissions profile、MCP、project config の境界を実務目線で設計します。

Read More →
🔎
Codex

Codex Security plugin 実践ガイド - scan / diff review / triage / fix をどう使い分けるか

·15 min read

Codex Security plugin を、通常scan、PR差分review、deep scan、backlog triage、fix finding に分けて運用する実務ガイドです。Codex の sandbox / approvals や internet access と混ぜず、セキュリティレビューをどこに組み込むかを整理します。

Read More →
🧾
AIエージェント

AIエージェント権限棚卸し設計ガイド - permission reviewで例外とscopeを腐らせない

·16 min read

AIエージェントに許可した権限、MCP scope、secrets、internet access、例外ルールを放置しないために、permission review の棚卸し項目と判断基準を整理します。

Read More →