Định tuyến đa tác tử

Chạy nhiều tác tử cô lập — mỗi tác tử có workspace, thư mục trạng thái (agentDir) và lịch sử phiên riêng — cộng với nhiều tài khoản kênh (ví dụ: hai WhatsApp) trong một Gateway đang chạy. Tin nhắn đến được định tuyến đến đúng tác tử thông qua các liên kết.

Một tác tử ở đây là phạm vi đầy đủ theo từng persona: tệp workspace, hồ sơ xác thực, registry mô hình và kho phiên. agentDir là thư mục trạng thái trên đĩa chứa cấu hình theo từng tác tử này tại ~/.openclaw/agents/<agentId>/. Một liên kết ánh xạ một tài khoản kênh (ví dụ: một workspace Slack hoặc một số WhatsApp) tới một trong các tác tử đó.

"Một tác tử" là gì?

Một tác tử là một bộ não có phạm vi đầy đủ với riêng:

• Workspace (tệp, AGENTS.md/SOUL.md/USER.md, ghi chú cục bộ, quy tắc persona).
• Thư mục trạng thái (agentDir) cho hồ sơ xác thực, registry mô hình và cấu hình theo từng tác tử.
• Kho phiên (lịch sử trò chuyện + trạng thái định tuyến) dưới ~/.openclaw/agents/<agentId>/sessions.

Hồ sơ xác thực là theo từng tác tử. Mỗi tác tử đọc từ tệp riêng của nó:

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

Skills được tải từ workspace của từng tác tử cộng với các gốc dùng chung như ~/.openclaw/skills, rồi được lọc theo allowlist Skills hiệu lực của tác tử khi được cấu hình. Dùng agents.defaults.skills làm baseline dùng chung và agents.list[].skills để thay thế theo từng tác tử. Xem Skills: theo từng tác tử so với dùng chung và Skills: allowlist Skills của tác tử.

Gateway có thể lưu trữ một tác tử (mặc định) hoặc nhiều tác tử song song.

Đường dẫn (bản đồ nhanh)

• Cấu hình: ~/.openclaw/openclaw.json (hoặc OPENCLAW_CONFIG_PATH)
• Thư mục trạng thái: ~/.openclaw (hoặc OPENCLAW_STATE_DIR)
• Workspace: ~/.openclaw/workspace (hoặc ~/.openclaw/workspace-<agentId>)
• Thư mục tác tử: ~/.openclaw/agents/<agentId>/agent (hoặc agents.list[].agentDir)
• Phiên: ~/.openclaw/agents/<agentId>/sessions

Chế độ một tác tử (mặc định)

Nếu bạn không làm gì, OpenClaw chạy một tác tử duy nhất:

• agentId mặc định là main.
• Phiên được khóa theo dạng agent:main:<mainKey>.
• Workspace mặc định là ~/.openclaw/workspace (hoặc ~/.openclaw/workspace-<profile> khi đặt OPENCLAW_PROFILE).
• Trạng thái mặc định là ~/.openclaw/agents/main/agent.

Trình hỗ trợ tác tử

Dùng wizard tác tử để thêm một tác tử cô lập mới:

openclaw agents add work

Sau đó thêm bindings (hoặc để wizard làm việc đó) để định tuyến tin nhắn đến.

Xác minh bằng:

openclaw agents list --bindings

Bắt đầu nhanh

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restartopenclaw agents list --bindingsopenclaw channels status --probe

Nhiều tác tử = nhiều người, nhiều tính cách

Với nhiều tác tử, mỗi agentId trở thành một persona được cô lập hoàn toàn:

• Số điện thoại/tài khoản khác nhau (theo accountId của từng kênh).
• Tính cách khác nhau (các tệp workspace theo từng tác tử như AGENTS.md và SOUL.md).
• Xác thực + phiên riêng biệt (không lẫn chéo trừ khi được bật rõ ràng).

Điều này cho phép nhiều người chia sẻ một máy chủ Gateway trong khi vẫn giữ "bộ não" AI và dữ liệu của họ được cô lập.

Tìm kiếm bộ nhớ QMD xuyên tác tử

Nếu một tác tử cần tìm kiếm transcript phiên QMD của tác tử khác, hãy thêm các collection bổ sung dưới agents.list[].memorySearch.qmd.extraCollections. Chỉ dùng agents.defaults.memorySearch.qmd.extraCollections khi mọi tác tử đều nên kế thừa cùng các collection transcript dùng chung.

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

Đường dẫn collection bổ sung có thể được dùng chung giữa các tác tử, nhưng tên collection vẫn là tường minh khi đường dẫn nằm ngoài workspace của tác tử. Đường dẫn bên trong workspace vẫn được giới hạn theo tác tử để mỗi tác tử giữ bộ tìm kiếm transcript riêng.

Một số WhatsApp, nhiều người (tách DM)

Bạn có thể định tuyến các DM WhatsApp khác nhau tới các tác tử khác nhau trong khi vẫn dùng một tài khoản WhatsApp. Khớp theo người gửi E.164 (như +15551234567) với peer.kind: "direct". Phản hồi vẫn đến từ cùng số WhatsApp (không có danh tính người gửi theo từng tác tử).

Ví dụ:

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

Ghi chú:

• Kiểm soát truy cập DM là toàn cục theo tài khoản WhatsApp (ghép nối/allowlist), không phải theo tác tử.
• Với nhóm dùng chung, liên kết nhóm với một tác tử hoặc dùng nhóm phát sóng.

Quy tắc định tuyến (cách tin nhắn chọn tác tử)

Liên kết là xác định và cụ thể nhất thắng:

Nhiều tài khoản / số điện thoại

Các kênh hỗ trợ nhiều tài khoản (ví dụ: WhatsApp) dùng accountId để nhận diện từng lần đăng nhập. Mỗi accountId có thể được định tuyến tới một tác tử khác nhau, vì vậy một máy chủ có thể lưu trữ nhiều số điện thoại mà không trộn lẫn phiên.

Nếu bạn muốn một tài khoản mặc định toàn kênh khi bỏ qua accountId, hãy đặt channels.<channel>.defaultAccount (tùy chọn). Khi không đặt, OpenClaw fallback về default nếu có, nếu không thì ID tài khoản được cấu hình đầu tiên (đã sắp xếp).

Các kênh phổ biến hỗ trợ mẫu này gồm:

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

Khái niệm

• agentId: một "bộ não" (workspace, xác thực theo từng tác tử, kho phiên theo từng tác tử).
• accountId: một thực thể tài khoản kênh (ví dụ tài khoản WhatsApp "personal" so với "biz").
• binding: định tuyến tin nhắn đến tới một agentId theo (channel, accountId, peer) và tùy chọn ID guild/team.
• Trò chuyện trực tiếp gộp về agent:<agentId>:<mainKey> ("main" theo từng tác tử; session.mainKey).

Ví dụ nền tảng

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

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

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

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

Mẫu phổ biến

{  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", accountId: "*" } },    { agentId: "opus", match: { channel: "telegram", accountId: "*" } },  ],}

{  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", accountId: "*", peer: { kind: "direct", id: "+15551234567" } },    },    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },  ],}

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

Cấu hình sandbox và công cụ cho từng tác nhân

Mỗi tác nhân có thể có sandbox và hạn chế công cụ riêng:

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

Lợi ích:

• Cách ly bảo mật: hạn chế công cụ cho các tác nhân không đáng tin cậy.
• Kiểm soát tài nguyên: đặt sandbox cho các tác nhân cụ thể trong khi giữ những tác nhân khác trên máy chủ.
• Chính sách linh hoạt: quyền khác nhau cho từng tác nhân.

Xem Sandbox và công cụ đa tác nhân để biết ví dụ chi tiết.

Liên quan

• Tác nhân ACP — chạy các harness lập trình bên ngoài
• Định tuyến kênh — cách tin nhắn định tuyến đến tác nhân
• Hiện diện — trạng thái hiện diện và khả dụng của tác nhân
• Phiên — cách ly và định tuyến phiên
• Tác nhân con — sinh các lượt chạy tác nhân nền