Konfigurasi — saluran

Kunci konfigurasi per saluran di bawah channels.*. Mencakup akses DM dan grup, penyiapan multi-akun, pembatasan berdasarkan sebutan, dan kunci per saluran untuk Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, dan Plugin saluran bawaan lainnya.

Untuk agen, alat, runtime Gateway, dan kunci tingkat atas lainnya, lihat Referensi konfigurasi.

# Saluran

Setiap saluran dimulai otomatis ketika bagian konfigurasinya ada (kecuali enabled: false).

# Akses DM dan grup

Semua saluran mendukung kebijakan DM dan kebijakan grup:

# Override model saluran

Gunakan channels.modelByChannel untuk menetapkan ID saluran tertentu ke sebuah model. Nilai menerima provider/model atau alias model yang dikonfigurasi. Pemetaan saluran berlaku ketika sesi belum memiliki override model (misalnya, diatur melalui /model).

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

# Default saluran dan Heartbeat

Gunakan channels.defaults untuk perilaku kebijakan grup dan Heartbeat bersama di seluruh penyedia:

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: kebijakan grup cadangan ketika groupPolicy tingkat penyedia belum diatur.
• channels.defaults.contextVisibility: mode visibilitas konteks tambahan default untuk semua saluran. Nilai: all (default, sertakan semua konteks kutipan/thread/riwayat), allowlist (hanya sertakan konteks dari pengirim yang ada di daftar izin), allowlist_quote (sama seperti allowlist tetapi tetap simpan konteks kutipan/balasan eksplisit). Override per saluran: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: sertakan status saluran yang sehat dalam keluaran Heartbeat.
• channels.defaults.heartbeat.showAlerts: sertakan status terdegradasi/error dalam keluaran Heartbeat.
• channels.defaults.heartbeat.useIndicator: render keluaran Heartbeat bergaya indikator ringkas.

# WhatsApp

WhatsApp berjalan melalui saluran web Gateway (Baileys Web). Ini dimulai otomatis ketika sesi yang tertaut ada.

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    whatsapp: {
      keepAliveIntervalMs: 25000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

{
channels: {
  whatsapp: {
    accounts: {
      default: {},
      personal: {},
      biz: {
        // authDir: "~/.openclaw/credentials/whatsapp/biz",
      },
    },
  },
},
}

# Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      apiRoot: "https://api.telegram.org",
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Token bot: channels.telegram.botToken atau channels.telegram.tokenFile (hanya file reguler; symlink ditolak), dengan TELEGRAM_BOT_TOKEN sebagai cadangan untuk akun default.
• apiRoot hanya root Telegram Bot API. Gunakan https://api.telegram.org atau root yang dihosting sendiri/proxy Anda, bukan https://api.telegram.org/bot<TOKEN>; openclaw doctor --fix menghapus akhiran /bot<TOKEN> yang tidak sengaja tertinggal.
• channels.telegram.defaultAccount opsional mengganti pemilihan akun default ketika cocok dengan ID akun yang dikonfigurasi.
• Dalam penyiapan multi-akun (2+ ID akun), atur default eksplisit (channels.telegram.defaultAccount atau channels.telegram.accounts.default) untuk menghindari perutean cadangan; openclaw doctor memperingatkan ketika ini tidak ada atau tidak valid.
• configWrites: false memblokir penulisan konfigurasi yang diprakarsai Telegram (migrasi ID supergrup, /config set|unset).
• Entri bindings[] tingkat atas dengan type: "acp" mengonfigurasi binding ACP persisten untuk topik forum (gunakan chatId:topic:topicId kanonis di match.peer.id). Semantik bidang dibagikan di Agen ACP.
• Pratinjau streaming Telegram menggunakan sendMessage + editMessageText (berfungsi dalam chat langsung dan grup).
• Kebijakan percobaan ulang: lihat Kebijakan percobaan ulang.

# Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: {
        mode: "progress", // off | partial | block | progress (Discord default: progress)
        progress: {
          label: "auto",
          maxLines: 8,
          toolProgress: true,
        },
      },
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, dengan DISCORD_BOT_TOKEN sebagai fallback untuk akun default.
• Panggilan keluar langsung yang menyediakan Discord token eksplisit menggunakan token tersebut untuk panggilan; pengaturan percobaan ulang/kebijakan akun tetap berasal dari akun yang dipilih dalam snapshot runtime aktif.
• channels.discord.defaultAccount opsional menimpa pemilihan akun default jika cocok dengan id akun yang dikonfigurasi.
• Gunakan user:<id> (DM) atau channel:<id> (kanal guild) untuk target pengiriman; ID numerik polos ditolak.
• Slug guild menggunakan huruf kecil dengan spasi diganti -; kunci kanal menggunakan nama yang telah dijadikan slug (tanpa #). Utamakan ID guild.
• Pesan yang ditulis bot diabaikan secara default. allowBots: true mengaktifkannya; gunakan allowBots: "mentions" untuk hanya menerima pesan bot yang menyebut bot (pesan sendiri tetap difilter).
• channels.discord.guilds.<id>.ignoreOtherMentions (dan penimpaan kanal) membuang pesan yang menyebut pengguna atau peran lain tetapi tidak menyebut bot (tidak termasuk @everyone/@here).
• channels.discord.mentionAliases memetakan teks keluar @handle yang stabil ke ID pengguna Discord sebelum pengiriman, sehingga rekan tim yang dikenal dapat disebut secara deterministik bahkan ketika cache direktori sementara kosong. Penimpaan per akun berada di bawah channels.discord.accounts.<accountId>.mentionAliases.
• maxLinesPerMessage (default 17) membagi pesan yang tinggi meskipun kurang dari 2000 karakter.
• channels.discord.threadBindings mengontrol perutean Discord yang terikat thread:
  • enabled: penimpaan Discord untuk fitur sesi terikat thread (/focus, /unfocus, /agents, /session idle, /session max-age, dan pengiriman/perutean terikat)
  • idleHours: penimpaan Discord untuk auto-unfocus karena tidak aktif dalam jam (0 menonaktifkan)
  • maxAgeHours: penimpaan Discord untuk usia maksimum keras dalam jam (0 menonaktifkan)
  • spawnSessions: sakelar untuk sessions_spawn({ thread: true }) dan pembuatan/pengikatan thread otomatis spawn thread ACP (default: true)
  • defaultSpawnContext: konteks subagent native untuk spawn terikat thread ("fork" secara default)
• Entri bindings[] tingkat atas dengan type: "acp" mengonfigurasi binding ACP persisten untuk kanal dan thread (gunakan id kanal/thread di match.peer.id). Semantik bidang dibagikan di Agen ACP.
• channels.discord.ui.components.accentColor mengatur warna aksen untuk kontainer komponen Discord v2.
• channels.discord.voice mengaktifkan percakapan kanal suara Discord dan penimpaan auto-join + LLM + TTS opsional. Konfigurasi Discord teks-saja menonaktifkan suara secara default; setel channels.discord.voice.enabled=true untuk ikut serta.
• channels.discord.voice.model secara opsional menimpa model LLM yang digunakan untuk respons kanal suara Discord.
• channels.discord.voice.daveEncryption dan channels.discord.voice.decryptionFailureTolerance diteruskan ke opsi DAVE @discordjs/voice (true dan 24 secara default).
• channels.discord.voice.connectTimeoutMs mengontrol penantian Ready awal @discordjs/voice untuk percobaan /vc join dan auto-join (30000 secara default).
• channels.discord.voice.reconnectGraceMs mengontrol berapa lama sesi suara yang terputus boleh masuk ke sinyal penyambungan ulang sebelum OpenClaw menghancurkannya (15000 secara default).
• Pemutaran suara Discord tidak diinterupsi oleh peristiwa mulai-berbicara pengguna lain. Untuk menghindari loop umpan balik, OpenClaw mengabaikan penangkapan suara baru saat TTS sedang diputar.
• OpenClaw juga mencoba pemulihan penerimaan suara dengan keluar/bergabung kembali ke sesi suara setelah kegagalan dekripsi berulang.
• channels.discord.streaming adalah kunci mode streaming kanonis. Discord secara default menggunakan streaming.mode: "progress" sehingga progres alat/pekerjaan muncul dalam satu pesan pratinjau yang diedit; setel streaming.mode: "off" untuk menonaktifkannya. Nilai lama streamMode dan boolean streaming tetap menjadi alias runtime; jalankan openclaw doctor --fix untuk menulis ulang konfigurasi yang disimpan.
• channels.discord.autoPresence memetakan ketersediaan runtime ke presence bot (sehat => online, menurun => idle, habis => dnd) dan mengizinkan penimpaan teks status opsional.
• channels.discord.dangerouslyAllowNameMatching mengaktifkan kembali pencocokan nama/tag yang dapat berubah (mode kompatibilitas darurat).
• channels.discord.execApprovals: pengiriman persetujuan exec native Discord dan otorisasi pemberi persetujuan.
  • enabled: true, false, atau "auto" (default). Dalam mode otomatis, persetujuan exec aktif saat pemberi persetujuan dapat diselesaikan dari approvers atau commands.ownerAllowFrom.
  • approvers: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Fallback ke commands.ownerAllowFrom jika dihilangkan.
  • agentFilter: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen.
  • sessionFilter: pola kunci sesi opsional (substring atau regex).
  • target: tempat mengirim prompt persetujuan. "dm" (default) mengirim ke DM pemberi persetujuan, "channel" mengirim ke kanal asal, "both" mengirim ke keduanya. Saat target menyertakan "channel", tombol hanya dapat digunakan oleh pemberi persetujuan yang terselesaikan.
  • cleanupAfterResolve: saat true, menghapus DM persetujuan setelah disetujui, ditolak, atau waktu habis.

Mode notifikasi reaksi: off (tidak ada), own (pesan bot, default), all (semua pesan), allowlist (dari guilds.<id>.users pada semua pesan).

# Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• JSON akun layanan: inline (serviceAccount) atau berbasis file (serviceAccountFile).
• SecretRef akun layanan juga didukung (serviceAccountRef).
• Fallback env: GOOGLE_CHAT_SERVICE_ACCOUNT atau GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Gunakan spaces/<spaceId> atau users/<userId> untuk target pengiriman.
• channels.googlechat.dangerouslyAllowNameMatching mengaktifkan kembali pencocokan principal email yang dapat berubah (mode kompatibilitas darurat).

# Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      socketMode: {
        clientPingTimeout: 15000,
        serverPingTimeout: 30000,
        pingPongLoggingEnabled: false,
      },
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Mode socket memerlukan botToken dan appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN untuk fallback env akun default).
• Mode HTTP memerlukan botToken plus signingSecret (di root atau per akun).
• socketMode meneruskan penyesuaian transport Socket Mode Slack SDK ke API receiver Bolt publik. Gunakan hanya saat menyelidiki timeout ping/pong atau perilaku websocket usang.
• botToken, appToken, signingSecret, dan userToken menerima string plaintext atau objek SecretRef.
• Snapshot akun Slack mengekspos bidang sumber/status per kredensial seperti botTokenSource, botTokenStatus, appTokenStatus, dan, dalam mode HTTP, signingSecretStatus. configured_unavailable berarti akun dikonfigurasi melalui SecretRef tetapi jalur perintah/runtime saat ini tidak dapat menyelesaikan nilai rahasia.
• configWrites: false memblokir penulisan konfigurasi yang dipicu Slack.
• channels.slack.defaultAccount opsional menimpa pemilihan akun default jika cocok dengan id akun yang dikonfigurasi.
• channels.slack.streaming.mode adalah kunci mode streaming Slack kanonis. channels.slack.streaming.nativeTransport mengontrol transport streaming native Slack. Nilai lama streamMode, boolean streaming, dan nativeStreaming tetap menjadi alias runtime; jalankan openclaw doctor --fix untuk menulis ulang konfigurasi yang disimpan.
• Gunakan user:<id> (DM) atau channel:<id> untuk target pengiriman.

Mode notifikasi reaksi: off, own (default), all, allowlist (dari reactionAllowlist).

Isolasi sesi thread: thread.historyScope bersifat per-thread (default) atau dibagikan di seluruh kanal. thread.inheritParent menyalin transkrip kanal induk ke thread baru.

• Streaming native Slack plus status thread bergaya asisten Slack "is typing..." memerlukan target thread balasan. DM tingkat atas tetap di luar thread secara default, sehingga masih dapat melakukan streaming melalui pratinjau draf Slack kirim-dan-edit alih-alih menampilkan pratinjau stream/status native bergaya thread.
• typingReaction menambahkan reaksi sementara ke pesan Slack masuk saat balasan sedang berjalan, lalu menghapusnya saat selesai. Gunakan shortcode emoji Slack seperti "hourglass_flowing_sand".
• channels.slack.execApprovals: pengiriman persetujuan exec native Slack dan otorisasi pemberi persetujuan. Skema yang sama seperti Discord: enabled (true/false/"auto"), approvers (ID pengguna Slack), agentFilter, sessionFilter, dan target ("dm", "channel", atau "both").

# Mattermost

Mattermost disertakan sebagai Plugin bundel dalam rilis OpenClaw saat ini. Build yang lebih lama atau kustom dapat menginstal paket npm saat ini dengan openclaw plugins install @openclaw/mattermost. Periksa npmjs.com/package/@openclaw/mattermost untuk dist-tag saat ini sebelum mem-pin versi.

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

Mode chat: oncall (merespons pada @-mention, default), onmessage (setiap pesan), onchar (pesan yang dimulai dengan prefiks pemicu).

Ketika perintah native Mattermost diaktifkan:

• commands.callbackPath harus berupa path (misalnya /api/channels/mattermost/command), bukan URL lengkap.
• commands.callbackUrl harus mengarah ke endpoint Gateway OpenClaw dan dapat dijangkau dari server Mattermost.
• Callback slash native diautentikasi dengan token per perintah yang dikembalikan oleh Mattermost selama pendaftaran perintah slash. Jika pendaftaran gagal atau tidak ada perintah yang diaktifkan, OpenClaw menolak callback dengan Unauthorized: invalid command token.
• Untuk host callback privat/tailnet/internal, Mattermost mungkin mengharuskan ServiceSettings.AllowedUntrustedInternalConnections menyertakan host/domain callback. Gunakan nilai host/domain, bukan URL lengkap.
• channels.mattermost.configWrites: izinkan atau tolak penulisan konfigurasi yang dimulai oleh Mattermost.
• channels.mattermost.requireMention: wajibkan @mention sebelum membalas di channel.
• channels.mattermost.groups.<channelId>.requireMention: override mention-gating per channel ("*" untuk default).
• channels.mattermost.defaultAccount opsional mengesampingkan pemilihan akun default ketika cocok dengan id akun yang dikonfigurasi.

# Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

Mode notifikasi reaksi: off, own (default), all, allowlist (dari reactionAllowlist).

• channels.signal.account: sematkan startup channel ke identitas akun Signal tertentu.
• channels.signal.configWrites: izinkan atau tolak penulisan konfigurasi yang dimulai oleh Signal.
• channels.signal.defaultAccount opsional mengesampingkan pemilihan akun default ketika cocok dengan id akun yang dikonfigurasi.

# BlueBubbles

BlueBubbles adalah bridge iMessage lama (didukung Plugin, dikonfigurasi di bawah channels.bluebubbles). Setup yang sudah ada tetap didukung, tetapi deployment iMessage OpenClaw baru sebaiknya memilih channels.imessage ketika imsg dapat berjalan di host Messages.

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• Path kunci inti yang dibahas di sini: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• channels.bluebubbles.defaultAccount opsional mengesampingkan pemilihan akun default ketika cocok dengan id akun yang dikonfigurasi.
• Entri bindings[] tingkat atas dengan type: "acp" dapat mengikat percakapan BlueBubbles ke sesi ACP persisten. Gunakan handle BlueBubbles atau string target (chat_id:*, chat_guid:*, chat_identifier:*) di match.peer.id. Semantik field bersama: Agen ACP.
• Konfigurasi channel BlueBubbles lengkap dan alasan deprekasi didokumentasikan di BlueBubbles.

# iMessage

OpenClaw menjalankan imsg rpc (JSON-RPC melalui stdio). Tidak memerlukan daemon atau port. Ini adalah jalur yang direkomendasikan untuk setup iMessage OpenClaw baru ketika host dapat memberikan izin database Messages dan Automation.

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• channels.imessage.defaultAccount opsional mengesampingkan pemilihan akun default ketika cocok dengan id akun yang dikonfigurasi.

• Memerlukan Full Disk Access ke DB Messages.

• Pilih target chat_id:<id>. Gunakan imsg chats --limit 20 untuk mencantumkan chat.

• cliPath dapat mengarah ke wrapper SSH; atur remoteHost (host atau user@host) untuk pengambilan lampiran melalui SCP.

• attachmentRoots dan remoteAttachmentRoots membatasi path lampiran masuk (default: /Users/*/Library/Messages/Attachments).

• SCP menggunakan pemeriksaan host-key yang ketat, jadi pastikan kunci host relay sudah ada di ~/.ssh/known_hosts.

• channels.imessage.configWrites: izinkan atau tolak penulisan konfigurasi yang dimulai oleh iMessage.

• Entri bindings[] tingkat atas dengan type: "acp" dapat mengikat percakapan iMessage ke sesi ACP persisten. Gunakan handle yang dinormalisasi atau target chat eksplisit (chat_id:*, chat_guid:*, chat_identifier:*) di match.peer.id. Semantik field bersama: Agen ACP.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

# Matrix

Matrix didukung Plugin dan dikonfigurasi di bawah channels.matrix.

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• Autentikasi token menggunakan accessToken; autentikasi sandi menggunakan userId + password.
• channels.matrix.proxy merutekan traffic HTTP Matrix melalui proxy HTTP(S) eksplisit. Akun bernama dapat mengesampingkannya dengan channels.matrix.accounts.<id>.proxy.
• channels.matrix.network.dangerouslyAllowPrivateNetwork mengizinkan homeserver privat/internal. proxy dan opt-in jaringan ini adalah kontrol yang independen.
• channels.matrix.defaultAccount memilih akun yang diprioritaskan dalam setup multi-akun.
• channels.matrix.autoJoin default ke off, jadi room undangan dan undangan baru bergaya DM diabaikan sampai Anda mengatur autoJoin: "allowlist" dengan autoJoinAllowlist atau autoJoin: "always".
• channels.matrix.execApprovals: pengiriman persetujuan exec native Matrix dan otorisasi pemberi persetujuan.
  • enabled: true, false, atau "auto" (default). Dalam mode auto, persetujuan exec aktif ketika pemberi persetujuan dapat di-resolve dari approvers atau commands.ownerAllowFrom.
  • approvers: ID pengguna Matrix (mis. @owner:example.org) yang diizinkan menyetujui permintaan exec.
  • agentFilter: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen.
  • sessionFilter: pola kunci sesi opsional (substring atau regex).
  • target: tempat mengirim prompt persetujuan. "dm" (default), "channel" (room asal), atau "both".
  • Override per akun: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope mengontrol bagaimana DM Matrix dikelompokkan ke dalam sesi: per-user (default) berbagi berdasarkan peer yang dirutekan, sementara per-room mengisolasi setiap room DM.
• Probe status Matrix dan pencarian direktori live menggunakan kebijakan proxy yang sama dengan traffic runtime.
• Konfigurasi Matrix lengkap, aturan penargetan, dan contoh setup didokumentasikan di Matrix.

# Microsoft Teams

Microsoft Teams didukung Plugin dan dikonfigurasi di bawah channels.msteams.

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• Path kunci inti yang dibahas di sini: channels.msteams, channels.msteams.configWrites.
• Konfigurasi Teams lengkap (kredensial, Webhook, kebijakan DM/grup, override per tim/per channel) didokumentasikan di Microsoft Teams.

# IRC

IRC didukung Plugin dan dikonfigurasi di bawah channels.irc.

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "[email protected]",
      },
    },
  },
}

• Path kunci inti yang dibahas di sini: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• channels.irc.defaultAccount opsional mengesampingkan pemilihan akun default ketika cocok dengan id akun yang dikonfigurasi.
• Konfigurasi channel IRC lengkap (host/port/TLS/channel/allowlist/mention gating) didokumentasikan di IRC.

# Multi-akun (semua channel)

Jalankan beberapa akun per channel (masing-masing dengan accountId sendiri):

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default digunakan ketika accountId dihilangkan (CLI + routing).
• Token env hanya berlaku untuk akun default.
• Pengaturan channel dasar berlaku untuk semua akun kecuali di-override per akun.
• Gunakan bindings[].match.accountId untuk merutekan setiap akun ke agen yang berbeda.
• Jika Anda menambahkan akun non-default melalui openclaw channels add (atau onboarding channel) saat masih berada pada konfigurasi channel tingkat atas akun tunggal, OpenClaw terlebih dahulu mempromosikan nilai akun tunggal tingkat atas yang tercakup akun ke dalam map akun channel agar akun asli tetap berfungsi. Sebagian besar channel memindahkannya ke channels.<channel>.accounts.default; Matrix dapat mempertahankan target bernama/default yang cocok jika sudah ada.
• Binding khusus channel yang sudah ada (tanpa accountId) tetap mencocokkan akun default; binding tercakup akun tetap opsional.
• openclaw doctor --fix juga memperbaiki bentuk campuran dengan memindahkan nilai akun tunggal tingkat atas yang tercakup akun ke akun yang dipromosikan yang dipilih untuk channel tersebut. Sebagian besar channel menggunakan accounts.default; Matrix dapat mempertahankan target bernama/default yang cocok jika sudah ada.

# Channel Plugin lainnya

Banyak channel Plugin dikonfigurasi sebagai channels.<id> dan didokumentasikan di halaman channel khususnya (misalnya Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, dan Twitch). Lihat indeks channel lengkap: Channel.

# Mention gating chat grup

Pesan grup secara default memerlukan mention (mention metadata atau pola regex aman). Berlaku untuk chat grup WhatsApp, Telegram, Discord, Google Chat, dan iMessage.

Balasan terlihat dikontrol secara terpisah. Ruang grup/kanal secara default menggunakan messages.groupChat.visibleReplies: "message_tool": OpenClaw tetap memproses giliran, tetapi balasan akhir normal tetap privat dan keluaran ruang yang terlihat memerlukan message(action=send). Atur "automatic" hanya ketika Anda menginginkan perilaku lama di mana balasan normal diposting kembali ke ruang. Untuk menerapkan perilaku balasan terlihat khusus alat yang sama ke chat langsung juga, atur messages.visibleReplies: "message_tool"; harness Codex juga menggunakan perilaku khusus alat tersebut sebagai default chat langsung yang belum diatur.

Balasan terlihat khusus alat memerlukan model/runtime yang secara andal memanggil alat. Jika log sesi menampilkan teks assistant dengan didSendViaMessagingTool: false, maka model menghasilkan jawaban akhir privat alih-alih memanggil alat pesan. Beralihlah ke model pemanggilan alat yang lebih kuat untuk kanal tersebut, atau atur messages.groupChat.visibleReplies: "automatic" untuk memulihkan balasan akhir terlihat gaya lama.

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

Gateway memuat ulang panas konfigurasi messages setelah file disimpan. Mulai ulang hanya ketika pengawasan file atau pemuatan ulang konfigurasi dinonaktifkan dalam deployment.

Jenis mention:

• Mention metadata: @-mention platform native. Diabaikan dalam mode self-chat WhatsApp.
• Pola teks: Pola regex aman di agents.list[].groupChat.mentionPatterns. Pola tidak valid dan pengulangan bersarang yang tidak aman diabaikan.
• Pembatasan mention diberlakukan hanya ketika deteksi memungkinkan (mention native atau setidaknya satu pola).

{
  messages: {
    visibleReplies: "automatic", // global default for direct/source chats; Codex harness defaults unset direct chats to message_tool
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // default; use "automatic" for legacy final replies
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit menetapkan default global. Kanal dapat menimpa dengan channels.<channel>.historyLimit (atau per akun). Atur 0 untuk menonaktifkan.

messages.visibleReplies adalah default giliran sumber global; messages.groupChat.visibleReplies menimpanya untuk giliran sumber grup/kanal. Ketika messages.visibleReplies belum diatur, harness dapat menyediakan default langsung/sumber miliknya sendiri; harness Codex default ke message_tool. Allowlist kanal dan pembatasan mention tetap menentukan apakah suatu giliran diproses.

# Batas riwayat DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

Resolusi: penimpaan per-DM → default penyedia → tanpa batas (semua dipertahankan).

Didukung: telegram, whatsapp, discord, slack, signal, imessage, msteams.

# Mode self-chat

Sertakan nomor Anda sendiri di allowFrom untuk mengaktifkan mode self-chat (mengabaikan @-mention native, hanya merespons pola teks):

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

# Perintah (penanganan perintah chat)

{
  commands: {
    native: "auto", // register native commands when supported
    nativeSkills: "auto", // register native skill commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    mcp: false, // allow /mcp
    plugins: false, // allow /plugins
    debug: false, // allow /debug
    restart: true, // allow /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

# Terkait

• Referensi konfigurasi — kunci tingkat atas
• Konfigurasi — agent
• Ikhtisar kanal