​

Nhóm

​

Giới thiệu cho người mới (2 phút)

• Nhóm bị hạn chế (groupPolicy: "allowlist").
• Trả lời yêu cầu phải có đề cập trừ khi bạn chủ động tắt kiểm soát đề cập.

TL;DR

• Quyền truy cập DM được kiểm soát bởi *.allowFrom.
• Quyền truy cập nhóm được kiểm soát bởi *.groupPolicy + danh sách cho phép (*.groups, *.groupAllowFrom).
• Kích hoạt trả lời được kiểm soát bởi kiểm soát đề cập (requireMention, /activation).

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

​

Khóa phiên

• Phiên nhóm dùng khóa phiên agent:<agentId>:<channel>:group:<id> (phòng/kênh dùng agent:<agentId>:<channel>:channel:<id>).
• Chủ đề diễn đàn Telegram thêm :topic:<threadId> vào ID nhóm để mỗi chủ đề có phiên riêng.
• Chat trực tiếp dùng phiên chính (hoặc theo từng người gửi nếu được cấu hình).
• Heartbeat được bỏ qua cho các phiên nhóm.

​

Mẫu: DM cá nhân + nhóm công khai (một tác tử)

• DM: đầy đủ công cụ (host)
• Nhóm: sandbox + công cụ bị hạn chế (Docker)

Nếu bạn cần các workspace/persona thực sự tách biệt (“cá nhân” và “công khai” tuyệt đối không được trộn lẫn), hãy sử dụng agent thứ hai + bindings. Xem Multi-Agent Routing.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // groups/channels are non-main -> sandboxed
        scope: "session", // strongest isolation (one container per group/channel)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // If allow is non-empty, everything else is blocked (deny still wins).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "~/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

• Khóa cấu hình và mặc định: Cấu hình Gateway
• Gỡ lỗi vì sao một công cụ bị chặn: Sandbox vs Tool Policy vs Elevated
• Chi tiết bind mount: Sandboxing

​

Nhãn hiển thị

• Nhãn UI dùng displayName khi có, định dạng là <channel>:<token>.
• #room được dành cho phòng/kênh; chat nhóm dùng g-<slug> (chữ thường, khoảng trắng -> -, giữ #@+._-).

​

Chính sách nhóm

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789", "@username"],
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["[email protected]"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { allow: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}

• groupPolicy tách biệt với kiểm soát đề cập (yêu cầu @đề cập).
• WhatsApp/Telegram/Signal/iMessage/Microsoft Teams: dùng groupAllowFrom (dự phòng: allowFrom tường minh).
• Các giá trị mặc định nằm theo từng subsystem dưới *.groups."*"..channels`.
• Slack: danh sách cho phép dùng channels.slack.channels.
• Matrix: allowlist sử dụng channels.matrix.groups (room ID, alias hoặc tên). Sử dụng channels.matrix.groupAllowFrom để giới hạn người gửi; allowlist users theo từng phòng cũng được hỗ trợ.
• DM nhóm được kiểm soát riêng (channels.discord.dm.*, channels.slack.dm.*).
• Danh sách cho phép Telegram có thể khớp ID người dùng ("123456789", "telegram:123456789", "tg:123456789") hoặc username ("@alice" hoặc "alice"); tiền tố không phân biệt hoa thường.
• Mặc định là groupPolicy: "allowlist"; nếu danh sách cho phép nhóm trống, tin nhắn nhóm sẽ bị chặn.

1. groupPolicy (open/disabled/allowlist)
2. danh sách cho phép nhóm (*.groups, *.groupAllowFrom, danh sách cho phép theo kênh)
3. kiểm soát đề cập (requireMention, /activation)

​

Kiểm soát đề cập (mặc định)

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

• mentionPatterns là các regex không phân biệt hoa thường.
• Các nền tảng có đề cập tường minh vẫn được chấp nhận; pattern chỉ là dự phòng.
• Ghi đè theo tác tử: agents.list[].groupChat.mentionPatterns (hữu ích khi nhiều tác tử chia sẻ một nhóm).
• Kiểm soát đề cập chỉ được áp dụng khi có thể phát hiện đề cập (đề cập native hoặc đã cấu hình mentionPatterns).
• Mặc định Discord nằm trong channels.discord.guilds."*" (có thể ghi đè theo guild/kênh).
• Group history context is wrapped uniformly across channels and is pending-only (messages skipped due to mention gating); use messages.groupChat.historyLimit for the global default and channels.<channel>Sử dụng "" để cho phép tất cả các nhóm đồng thời vẫn thiết lập hành vi mention mặc định..accounts..historyLimit) để ghi đè. Set 0` to disable.

​

Hạn chế công cụ theo nhóm/kênh (tùy chọn)

• tools: cho phép/từ chối công cụ cho toàn bộ nhóm.
• toolsBySender: ghi đè theo từng người gửi trong nhóm (khóa là ID người gửi/tên người dùng/email/số điện thoại tùy theo kênh). Use "*" as a wildcard.

1. khớp toolsBySender theo nhóm/kênh
2. tools theo nhóm/kênh
3. mặc định ("*") khớp toolsBySender
4. mặc định ("*") tools

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

• Hạn chế công cụ theo nhóm/kênh được áp dụng bổ sung vào chính sách công cụ toàn cục/tác tử (từ chối vẫn có hiệu lực).
• Một số kênh dùng cách lồng khác cho phòng/kênh (ví dụ: Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

​

Danh sách cho phép nhóm

1. Tắt toàn bộ trả lời trong nhóm

{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}

2. Chỉ cho phép các nhóm cụ thể (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}

3. Cho phép mọi nhóm nhưng yêu cầu đề cập (tường minh)

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

4. Chỉ chủ sở hữu mới có thể kích hoạt trong nhóm (WhatsApp)

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

​

Kích hoạt (chỉ chủ sở hữu)

• /activation mention
• /activation always

​

Trường ngữ cảnh

• ChatType=group
• GroupSubject (nếu biết)
• GroupMembers (nếu biết)
• WasMentioned (kết quả kiểm soát đề cập)
• Chủ đề diễn đàn Telegram cũng bao gồm MessageThreadId và IsForum.

​

Chi tiết riêng cho iMessage

• Ưu tiên chat_id:<id> khi định tuyến hoặc cho phép.
• Liệt kê chat: imsg chats --limit 20.
• Trả lời nhóm luôn quay lại cùng chat_id.

​

Chi tiết riêng cho WhatsApp