Grup

OpenClaw memperlakukan obrolan grup secara konsisten di berbagai surface: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

# Pengantar pemula (2 menit)

OpenClaw "hidup" di akun perpesanan Anda sendiri. Tidak ada pengguna bot WhatsApp terpisah. Jika Anda berada dalam sebuah grup, OpenClaw dapat melihat grup tersebut dan merespons di sana.

Perilaku default:

• Grup dibatasi (groupPolicy: "allowlist").
• Balasan memerlukan mention kecuali Anda secara eksplisit menonaktifkan gerbang mention.
• Balasan final normal di grup/channel bersifat privat secara default. Output ruang yang terlihat menggunakan alat message.

Terjemahan: pengirim yang masuk allowlist dapat memicu OpenClaw dengan menyebutkannya.

Alur cepat (apa yang terjadi pada pesan grup):

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

# Balasan terlihat

Untuk ruang grup/channel, OpenClaw secara default menggunakan messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix menulis default ini ke konfigurasi channel yang telah dikonfigurasi yang belum memilikinya. Artinya agen tetap memproses giliran tersebut dan dapat memperbarui status memori/sesi, tetapi jawaban final normalnya tidak otomatis diposting kembali ke ruang. Untuk berbicara secara terlihat, agen menggunakan message(action=send).

Default ini bergantung pada model/runtime yang andal memanggil alat. Jika log menampilkan teks asisten tetapi didSendViaMessagingTool: false, model menjawab secara privat alih-alih memanggil alat message. Itu bukan kegagalan pengiriman Discord/Slack/Telegram. Gunakan model yang andal dalam pemanggilan alat untuk sesi grup/channel, atau atur messages.groupChat.visibleReplies: "automatic" untuk memulihkan balasan final terlihat gaya lama.

Jika alat message tidak tersedia di bawah kebijakan alat aktif, OpenClaw kembali ke balasan terlihat otomatis alih-alih menekan respons secara diam-diam. openclaw doctor memperingatkan tentang ketidakcocokan ini.

Untuk obrolan langsung dan giliran sumber lainnya, gunakan messages.visibleReplies: "message_tool" untuk menerapkan perilaku balasan terlihat hanya melalui alat yang sama secara global. Harness juga dapat memilih ini sebagai default saat belum diatur; harness Codex melakukan ini untuk obrolan langsung mode Codex. messages.groupChat.visibleReplies tetap menjadi override yang lebih spesifik untuk ruang grup/channel.

Ini menggantikan pola lama yang memaksa model menjawab NO_REPLY untuk sebagian besar giliran mode mengintai. Dalam mode hanya alat, tidak melakukan apa pun yang terlihat berarti tidak memanggil alat message.

Indikator mengetik tetap dikirim saat agen bekerja dalam mode hanya alat. Mode mengetik grup default ditingkatkan dari "message" ke "instant" untuk giliran ini karena mungkin tidak pernah ada teks pesan asisten normal sebelum agen memutuskan apakah akan memanggil alat message. Konfigurasi mode mengetik eksplisit tetap menang.

Untuk memulihkan balasan final otomatis gaya lama untuk ruang grup/channel:

{
  messages: {
    groupChat: {
      visibleReplies: "automatic",
    },
  },
}

Gateway memuat ulang konfigurasi messages secara hot-reload setelah file disimpan. Mulai ulang hanya ketika pemantauan file atau pemuatan ulang konfigurasi dinonaktifkan dalam deployment.

Untuk mewajibkan output terlihat melewati alat message untuk setiap obrolan sumber:

{
  messages: {
    visibleReplies: "message_tool",
  },
}

Perintah slash native (Discord, Telegram, dan surface lain dengan dukungan perintah native) melewati visibleReplies: "message_tool" dan selalu membalas secara terlihat agar UI perintah native channel mendapatkan respons yang diharapkannya. Ini hanya berlaku untuk giliran perintah native yang tervalidasi; perintah /... yang diketik sebagai teks dan giliran obrolan biasa tetap mengikuti default grup yang dikonfigurasi.

# Visibilitas konteks dan allowlist

Dua kontrol berbeda terlibat dalam keamanan grup:

• Otorisasi pemicu: siapa yang dapat memicu agen (groupPolicy, groups, groupAllowFrom, allowlist khusus channel).
• Visibilitas konteks: konteks tambahan apa yang disuntikkan ke model (teks balasan, kutipan, riwayat thread, metadata terusan).

Secara default, OpenClaw memprioritaskan perilaku obrolan normal dan menjaga konteks sebagian besar sebagaimana diterima. Artinya allowlist terutama menentukan siapa yang dapat memicu tindakan, bukan batas redaksi universal untuk setiap cuplikan kutipan atau historis.

Jika Anda ingin...

Untuk allowlist pengirim yang dapat digunakan ulang, lihat Grup akses.

# Kunci sesi

• Sesi grup menggunakan kunci sesi agent:<agentId>:<channel>:group:<id> (ruang/channel menggunakan agent:<agentId>:<channel>:channel:<id>).
• Topik forum Telegram menambahkan :topic:<threadId> ke id grup sehingga setiap topik memiliki sesi sendiri.
• Obrolan langsung menggunakan sesi utama (atau per pengirim jika dikonfigurasi).
• Heartbeat dilewati untuk sesi grup.

# Pola: DM pribadi + grup publik (satu agen)

Ya — ini bekerja dengan baik jika lalu lintas "pribadi" Anda adalah DM dan lalu lintas "publik" Anda adalah grup.

Alasannya: dalam mode satu agen, DM biasanya masuk ke kunci sesi utama (agent:main:main), sedangkan grup selalu menggunakan kunci sesi non-utama (agent:main:<channel>:group:<id>). Jika Anda mengaktifkan sandboxing dengan mode: "non-main", sesi grup tersebut berjalan di backend sandbox yang dikonfigurasi sementara sesi DM utama Anda tetap di host. Docker adalah backend default jika Anda tidak memilih salah satu.

Ini memberi Anda satu "otak" agen (workspace + memori bersama), tetapi dua postur eksekusi:

• DM: alat penuh (host)
• Grup: sandbox + alat terbatas

{
  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
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

Terkait:

• Kunci konfigurasi dan default: Konfigurasi Gateway
• Men-debug mengapa alat diblokir: Sandbox vs Kebijakan Alat vs Elevated
• Detail bind mount: Sandboxing

# Label tampilan

• Label UI menggunakan displayName jika tersedia, diformat sebagai <channel>:<token>.
• #room dicadangkan untuk ruang/channel; obrolan grup menggunakan g-<slug> (huruf kecil, spasi -> -, pertahankan #@+._-).

# Kebijakan grup

Kontrol bagaimana pesan grup/ruang ditangani per channel:

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @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": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

Model mental cepat (urutan evaluasi untuk pesan grup):

# Pembatasan mention (default)

Pesan grup memerlukan mention kecuali ditimpa per grup. Default berada per subsistem di bawah *.groups."*".

Membalas pesan bot dihitung sebagai mention implisit ketika saluran mendukung metadata balasan. Mengutip pesan bot juga dapat dihitung sebagai mention implisit pada saluran yang mengekspos metadata kutipan. Kasus bawaan saat ini mencakup Telegram, WhatsApp, Slack, Discord, Microsoft Teams, dan ZaloUser.

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

# Pembatasan tool grup/saluran (opsional)

Beberapa konfigurasi saluran mendukung pembatasan tool mana yang tersedia di dalam grup/ruangan/saluran tertentu.

• tools: izinkan/tolak tool untuk seluruh grup.
• toolsBySender: penimpaan per pengirim dalam grup. Gunakan prefiks kunci eksplisit: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, dan wildcard "*". Kunci lama tanpa prefiks masih diterima dan dicocokkan hanya sebagai id:.

Urutan resolusi (yang paling spesifik menang):

Contoh (Telegram):

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

# Daftar izin grup

Ketika channels.whatsapp.groups, channels.telegram.groups, atau channels.imessage.groups dikonfigurasi, kuncinya berfungsi sebagai daftar izin grup. Gunakan "*" untuk mengizinkan semua grup sambil tetap menetapkan perilaku mention default.

Maksud umum (salin/tempel):

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

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

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

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

# Aktivasi (khusus pemilik)

Pemilik grup dapat mengaktifkan/menonaktifkan aktivasi per grup:

• /activation mention
• /activation always

Pemilik ditentukan oleh channels.whatsapp.allowFrom (atau E.164 mandiri bot saat tidak diatur). Kirim perintah sebagai pesan mandiri. Permukaan lain saat ini mengabaikan /activation.

# Kolom konteks

Payload masuk grup mengatur:

• ChatType=group
• GroupSubject (jika diketahui)
• GroupMembers (jika diketahui)
• WasMentioned (hasil pembatasan mention)
• Topik forum Telegram juga menyertakan MessageThreadId dan IsForum.

Catatan khusus saluran:

• BlueBubbles secara opsional dapat memperkaya peserta grup macOS tanpa nama dari database Contacts lokal sebelum mengisi GroupMembers. Ini nonaktif secara default dan hanya berjalan setelah pembatasan grup normal lolos.

Prompt sistem agen menyertakan intro grup pada giliran pertama sesi grup baru. Ini mengingatkan model untuk merespons seperti manusia, menghindari tabel Markdown, meminimalkan baris kosong dan mengikuti spasi obrolan normal, serta menghindari mengetik urutan literal \n. Nama grup dan label peserta yang bersumber dari saluran dirender sebagai metadata tidak tepercaya berpagar, bukan instruksi sistem inline.

# Kekhususan iMessage

• Utamakan chat_id:<id> saat merutekan atau memasukkan ke daftar izin.
• Daftar obrolan: imsg chats --limit 20.
• Balasan grup selalu kembali ke chat_id yang sama.

# Prompt sistem WhatsApp

Lihat WhatsApp untuk aturan prompt sistem WhatsApp kanonis, termasuk resolusi prompt grup dan langsung, perilaku wildcard, dan semantik penimpaan akun.

# Kekhususan WhatsApp

Lihat Pesan grup untuk perilaku khusus WhatsApp (injeksi riwayat, detail penanganan mention).

# Terkait

• Grup broadcast
• Perutean saluran
• Pesan grup
• Pemasangan