> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tin nhắn nhóm

# Tin nhắn nhóm (kênh WhatsApp web)

Mục tiêu: cho phép Clawd tham gia các nhóm WhatsApp, chỉ thức dậy khi được ping, và giữ luồng đó tách biệt với phiên DM cá nhân.

Lưu ý: `agents.list[].groupChat.mentionPatterns` hiện cũng được dùng cho Telegram/Discord/Slack/iMessage; tài liệu này tập trung vào hành vi riêng của WhatsApp. For multi-agent setups, set `agents.list[].groupChat.mentionPatterns` per agent (or use `messages.groupChat.mentionPatterns` as a global fallback).

## Những gì đã triển khai (2025-12-03)

* Activation modes: `mention` (default) or `always`. `mention` yêu cầu một ping (mention WhatsApp @ thực thông qua `mentionedJids`, các mẫu regex, hoặc số E.164 của bot xuất hiện ở bất kỳ đâu trong văn bản). `always` đánh thức agent với mọi tin nhắn nhưng chỉ nên trả lời khi có thể mang lại giá trị thực; nếu không thì trả về token im lặng `NO_REPLY`. Giá trị mặc định có thể được đặt trong cấu hình (`channels.whatsapp.groups`) và được ghi đè theo từng nhóm thông qua `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
* Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders).
* Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on` or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
* Context injection: **pending-only** group messages (default 50) that *did not* trigger a run are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`. Messages already in the session are not re-injected.
* Hiển thị người gửi: mỗi lô tin nhắn nhóm giờ kết thúc bằng `[from: Sender Name (+E164)]` để Pi biết ai đang nói.
* Tin nhắn tạm thời/xem một lần: chúng tôi mở gói trước khi trích xuất văn bản/nhắc tên, nên các ping bên trong vẫn kích hoạt.
* Discord: allowlist sử dụng `channels.discord.guilds.<id>` Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.\` If metadata isn’t available we still tell the agent it’s a group chat.

## Ví dụ cấu hình (WhatsApp)

Thêm một khối `groupChat` vào `~/.openclaw/openclaw.json` để ping theo tên hiển thị hoạt động ngay cả khi WhatsApp loại bỏ `@` hiển thị trong thân văn bản:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}
```

Ghi chú:

* Các regex không phân biệt hoa thường; chúng bao phủ ping theo tên hiển thị như `@openclaw` và số thô có hoặc không có `+`/khoảng trắng.
* WhatsApp vẫn gửi nhắc tên chuẩn qua `mentionedJids` khi ai đó chạm vào liên hệ, nên phương án dự phòng bằng số hiếm khi cần nhưng là một lưới an toàn hữu ích.

### Lệnh kích hoạt (chỉ chủ sở hữu)

Dùng lệnh trong chat nhóm:

* `/activation mention`
* `/activation always`

Only the owner number (from `channels.whatsapp.allowFrom`, or the bot’s own E.164 when unset) can change this. Send `/status` as a standalone message in the group to see the current activation mode.

## Cách sử dụng

1. Thêm tài khoản WhatsApp của bạn (tài khoản đang chạy OpenClaw) vào nhóm.
2. Say `@openclaw …` (or include the number). Only allowlisted senders can trigger it unless you set `groupPolicy: "open"`.
3. Prompt của tác tử sẽ bao gồm ngữ cảnh nhóm gần đây cùng với dấu `[from: …]` ở cuối để có thể trả lời đúng người.
4. Session-level directives (`/verbose on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent.

## Kiểm thử / xác minh

* Thử nghiệm thủ công:
  * Gửi một ping `@openclaw` trong nhóm và xác nhận có phản hồi tham chiếu đến tên người gửi.
  * Gửi ping thứ hai và xác minh khối lịch sử được bao gồm rồi bị xóa ở lượt tiếp theo.
* Kiểm tra log của gateway (chạy với `--verbose`) để xem các mục `inbound web message` hiển thị `from: <groupJid>` và hậu tố `[from: …]`.

## Các lưu ý đã biết

* Heartbeat được cố ý bỏ qua cho nhóm để tránh phát sóng ồn ào.
* Chống echo sử dụng chuỗi lô kết hợp; nếu bạn gửi cùng một văn bản hai lần mà không có nhắc tên, chỉ lần đầu nhận được phản hồi.
* Các mục lưu trữ phiên sẽ xuất hiện dưới dạng `agent:<agentId>:whatsapp:group:<jid>` trong kho phiên (`~/.openclaw/agents/<agentId>/sessions/sessions.json` theo mặc định); thiếu mục chỉ có nghĩa là nhóm chưa kích hoạt chạy lần nào.
* Chỉ báo đang nhập trong nhóm tuân theo `agents.defaults.typingMode` (mặc định: `message` khi không được nhắc tên).