Cấu hình — kênh

Các khóa cấu hình theo từng kênh dưới channels.*. Bao gồm quyền truy cập DM và nhóm, thiết lập nhiều tài khoản, kiểm soát theo lượt nhắc, và các khóa theo từng kênh cho Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, cùng các Plugin kênh được tích hợp sẵn khác.

Đối với tác tử, công cụ, runtime Gateway và các khóa cấp cao khác, xem Tham chiếu cấu hình.

# Kênh

Mỗi kênh tự động khởi động khi phần cấu hình của kênh đó tồn tại (trừ khi enabled: false).

# Quyền truy cập DM và nhóm

Tất cả kênh đều hỗ trợ chính sách DM và chính sách nhóm:

# Ghi đè mô hình theo kênh

Dùng channels.modelByChannel để ghim các ID kênh cụ thể vào một mô hình. Giá trị chấp nhận provider/model hoặc bí danh mô hình đã cấu hình. Ánh xạ kênh được áp dụng khi một phiên chưa có ghi đè mô hình (ví dụ, được đặt qua /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",
      },
    },
  },
}

# Mặc định kênh và Heartbeat

Dùng channels.defaults cho chính sách nhóm dùng chung và hành vi Heartbeat trên các nhà cung cấp:

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

• channels.defaults.groupPolicy: chính sách nhóm dự phòng khi groupPolicy cấp nhà cung cấp chưa được đặt.
• channels.defaults.contextVisibility: chế độ hiển thị ngữ cảnh bổ sung mặc định cho mọi kênh. Giá trị: all (mặc định, bao gồm toàn bộ ngữ cảnh trích dẫn/luồng/lịch sử), allowlist (chỉ bao gồm ngữ cảnh từ người gửi trong danh sách cho phép), allowlist_quote (giống allowlist nhưng giữ ngữ cảnh trích dẫn/trả lời rõ ràng). Ghi đè theo kênh: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: bao gồm trạng thái kênh khỏe mạnh trong đầu ra Heartbeat.
• channels.defaults.heartbeat.showAlerts: bao gồm trạng thái suy giảm/lỗi trong đầu ra Heartbeat.
• channels.defaults.heartbeat.useIndicator: hiển thị đầu ra Heartbeat theo kiểu chỉ báo gọn.

# WhatsApp

WhatsApp chạy qua kênh web của gateway (Baileys Web). Kênh này tự động khởi động khi có phiên đã liên kết.

{
  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 hoặc channels.telegram.tokenFile (chỉ tệp thông thường; từ chối symlink), với TELEGRAM_BOT_TOKEN làm dự phòng cho tài khoản mặc định.
• apiRoot chỉ là gốc Telegram Bot API. Dùng https://api.telegram.org hoặc gốc tự lưu trữ/proxy của bạn, không dùng https://api.telegram.org/bot<TOKEN>; openclaw doctor --fix xóa hậu tố /bot<TOKEN> vô tình ở cuối.
• channels.telegram.defaultAccount tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình.
• Trong thiết lập nhiều tài khoản (2+ id tài khoản), hãy đặt mặc định rõ ràng (channels.telegram.defaultAccount hoặc channels.telegram.accounts.default) để tránh định tuyến dự phòng; openclaw doctor cảnh báo khi phần này bị thiếu hoặc không hợp lệ.
• configWrites: false chặn các lượt ghi cấu hình do Telegram khởi tạo (di chuyển ID supergroup, /config set|unset).
• Các mục bindings[] cấp cao với type: "acp" cấu hình liên kết ACP bền vững cho chủ đề diễn đàn (dùng chatId:topic:topicId chuẩn trong match.peer.id). Ngữ nghĩa trường được chia sẻ trong Tác tử ACP.
• Bản xem trước luồng Telegram dùng sendMessage + editMessageText (hoạt động trong trò chuyện trực tiếp và nhóm).
• Chính sách thử lại: xem Chính sách thử lại.

# 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, với DISCORD_BOT_TOKEN làm dự phòng cho tài khoản mặc định.
• Các lệnh gọi đi trực tiếp cung cấp Discord token rõ ràng sẽ dùng token đó cho lệnh gọi; thiết lập thử lại/chính sách của tài khoản vẫn đến từ tài khoản đã chọn trong ảnh chụp nhanh runtime đang hoạt động.
• channels.discord.defaultAccount tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình.
• Dùng user:<id> (DM) hoặc channel:<id> (kênh guild) cho mục tiêu gửi; ID số trần bị từ chối.
• Slug guild viết thường và thay khoảng trắng bằng -; khóa kênh dùng tên đã slug hóa (không có #). Ưu tiên ID guild.
• Tin nhắn do bot soạn mặc định bị bỏ qua. allowBots: true bật chúng; dùng allowBots: "mentions" để chỉ chấp nhận tin nhắn bot có nhắc đến bot (tin nhắn của chính bot vẫn bị lọc).
• channels.discord.guilds.<id>.ignoreOtherMentions (và các ghi đè kênh) loại bỏ tin nhắn nhắc đến người dùng hoặc vai trò khác nhưng không nhắc đến bot (loại trừ @everyone/@here).
• channels.discord.mentionAliases ánh xạ văn bản @handle gửi đi ổn định sang ID người dùng Discord trước khi gửi, để có thể nhắc đến đồng đội đã biết một cách xác định ngay cả khi bộ nhớ đệm thư mục tạm thời trống. Ghi đè theo tài khoản nằm trong channels.discord.accounts.<accountId>.mentionAliases.
• maxLinesPerMessage (mặc định 17) chia các tin nhắn cao ngay cả khi dưới 2000 ký tự.
• channels.discord.threadBindings điều khiển định tuyến ràng buộc theo luồng Discord:
  • enabled: ghi đè Discord cho các tính năng phiên ràng buộc theo luồng (/focus, /unfocus, /agents, /session idle, /session max-age, và gửi/định tuyến đã ràng buộc)
  • idleHours: ghi đè Discord cho tự động bỏ tập trung khi không hoạt động, tính bằng giờ (0 để tắt)
  • maxAgeHours: ghi đè Discord cho tuổi tối đa cứng, tính bằng giờ (0 để tắt)
  • spawnSessions: công tắc cho sessions_spawn({ thread: true }) và tự động tạo/ràng buộc luồng khi ACP sinh luồng (mặc định: true)
  • defaultSpawnContext: ngữ cảnh tác tử con gốc cho các lần sinh ràng buộc theo luồng (mặc định là "fork")
• Các mục bindings[] cấp cao nhất với type: "acp" cấu hình các ràng buộc ACP bền vững cho kênh và luồng (dùng id kênh/luồng trong match.peer.id). Ngữ nghĩa trường được dùng chung trong Tác tử ACP.
• channels.discord.ui.components.accentColor đặt màu nhấn cho container thành phần Discord v2.
• channels.discord.voice bật các cuộc trò chuyện kênh thoại Discord và các ghi đè tự động tham gia + LLM + TTS tùy chọn. Cấu hình Discord chỉ văn bản mặc định để tắt thoại; đặt channels.discord.voice.enabled=true để bật.
• channels.discord.voice.model tùy chọn ghi đè mô hình LLM dùng cho phản hồi kênh thoại Discord.
• channels.discord.voice.daveEncryption và channels.discord.voice.decryptionFailureTolerance truyền tiếp đến các tùy chọn DAVE của @discordjs/voice (mặc định là true và 24).
• channels.discord.voice.connectTimeoutMs điều khiển thời gian chờ Ready ban đầu của @discordjs/voice cho /vc join và các lần thử tự động tham gia (mặc định là 30000).
• channels.discord.voice.reconnectGraceMs điều khiển khoảng thời gian một phiên thoại đã ngắt kết nối có thể dùng để đi vào tín hiệu kết nối lại trước khi OpenClaw hủy phiên đó (mặc định là 15000).
• Phát lại giọng nói Discord không bị gián đoạn bởi sự kiện bắt đầu nói của người dùng khác. Để tránh vòng lặp phản hồi, OpenClaw bỏ qua việc thu giọng nói mới trong khi TTS đang phát.
• OpenClaw cũng cố gắng khôi phục nhận thoại bằng cách rời/tham gia lại một phiên thoại sau các lỗi giải mã lặp lại.
• channels.discord.streaming là khóa chế độ stream chính tắc. Discord mặc định là streaming.mode: "progress" để tiến trình công cụ/công việc xuất hiện trong một tin nhắn xem trước được chỉnh sửa; đặt streaming.mode: "off" để tắt. Các giá trị cũ streamMode và streaming dạng boolean vẫn là alias runtime; chạy openclaw doctor --fix để viết lại cấu hình đã lưu.
• channels.discord.autoPresence ánh xạ mức sẵn sàng runtime sang trạng thái hiện diện của bot (healthy => online, degraded => idle, exhausted => dnd) và cho phép ghi đè văn bản trạng thái tùy chọn.
• channels.discord.dangerouslyAllowNameMatching bật lại việc khớp tên/thẻ có thể thay đổi (chế độ tương thích phá kính).
• channels.discord.execApprovals: gửi phê duyệt exec gốc Discord và ủy quyền người phê duyệt.
  • enabled: true, false, hoặc "auto" (mặc định). Ở chế độ tự động, phê duyệt exec kích hoạt khi có thể phân giải người phê duyệt từ approvers hoặc commands.ownerAllowFrom.
  • approvers: ID người dùng Discord được phép phê duyệt yêu cầu exec. Dự phòng về commands.ownerAllowFrom khi bị bỏ qua.
  • agentFilter: danh sách cho phép ID tác tử tùy chọn. Bỏ qua để chuyển tiếp phê duyệt cho mọi tác tử.
  • sessionFilter: mẫu khóa phiên tùy chọn (chuỗi con hoặc regex).
  • target: nơi gửi lời nhắc phê duyệt. "dm" (mặc định) gửi đến DM của người phê duyệt, "channel" gửi đến kênh khởi nguồn, "both" gửi đến cả hai. Khi target bao gồm "channel", chỉ những người phê duyệt đã phân giải mới dùng được nút.
  • cleanupAfterResolve: khi true, xóa DM phê duyệt sau khi phê duyệt, từ chối hoặc hết thời gian chờ.

Chế độ thông báo phản ứng: off (không có), own (tin nhắn của bot, mặc định), all (mọi tin nhắn), allowlist (từ guilds.<id>.users trên mọi tin nhắn).

# 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 tài khoản dịch vụ: nội tuyến (serviceAccount) hoặc dựa trên tệp (serviceAccountFile).
• SecretRef tài khoản dịch vụ cũng được hỗ trợ (serviceAccountRef).
• Dự phòng env: GOOGLE_CHAT_SERVICE_ACCOUNT hoặc GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Dùng spaces/<spaceId> hoặc users/<userId> cho mục tiêu gửi.
• channels.googlechat.dangerouslyAllowNameMatching bật lại việc khớp principal email có thể thay đổi (chế độ tương thích phá kính).

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

• Chế độ socket yêu cầu cả botToken và appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN cho dự phòng env của tài khoản mặc định).
• Chế độ HTTP yêu cầu botToken cộng với signingSecret (ở gốc hoặc theo tài khoản).
• socketMode truyền tiếp tinh chỉnh truyền tải Socket Mode của SDK Slack đến API receiver Bolt công khai. Chỉ dùng khi điều tra thời gian chờ ping/pong hoặc hành vi websocket cũ.
• botToken, appToken, signingSecret, và userToken chấp nhận chuỗi văn bản thuần hoặc đối tượng SecretRef.
• Ảnh chụp nhanh tài khoản Slack hiển thị các trường nguồn/trạng thái theo từng thông tin xác thực như botTokenSource, botTokenStatus, appTokenStatus, và, trong chế độ HTTP, signingSecretStatus. configured_unavailable nghĩa là tài khoản được cấu hình thông qua SecretRef nhưng đường dẫn lệnh/runtime hiện tại không thể phân giải giá trị bí mật.
• configWrites: false chặn việc ghi cấu hình do Slack khởi tạo.
• channels.slack.defaultAccount tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình.
• channels.slack.streaming.mode là khóa chế độ stream Slack chính tắc. channels.slack.streaming.nativeTransport điều khiển truyền tải stream gốc của Slack. Các giá trị cũ streamMode, streaming dạng boolean, và nativeStreaming vẫn là alias runtime; chạy openclaw doctor --fix để viết lại cấu hình đã lưu.
• Dùng user:<id> (DM) hoặc channel:<id> cho mục tiêu gửi.

Chế độ thông báo phản ứng: off, own (mặc định), all, allowlist (từ reactionAllowlist).

Cô lập phiên luồng: thread.historyScope là theo luồng (mặc định) hoặc dùng chung trên kênh. thread.inheritParent sao chép transcript kênh cha sang các luồng mới.

• Stream gốc Slack cùng trạng thái luồng kiểu trợ lý Slack "is typing..." yêu cầu mục tiêu luồng trả lời. DM cấp cao nhất mặc định vẫn nằm ngoài luồng, nên chúng vẫn có thể stream qua bản xem trước bài nháp đăng-và-sửa của Slack thay vì hiển thị bản xem trước stream/trạng thái gốc kiểu luồng.
• typingReaction thêm phản ứng tạm thời vào tin nhắn Slack đến trong khi phản hồi đang chạy, rồi xóa nó khi hoàn tất. Dùng mã ngắn emoji Slack như "hourglass_flowing_sand".
• channels.slack.execApprovals: gửi phê duyệt exec gốc Slack và ủy quyền người phê duyệt. Cùng schema với Discord: enabled (true/false/"auto"), approvers (ID người dùng Slack), agentFilter, sessionFilter, và target ("dm", "channel", hoặc "both").

# Mattermost

Mattermost được phát hành dưới dạng Plugin đóng gói sẵn trong các bản phát hành OpenClaw hiện tại. Các bản dựng cũ hơn hoặc tùy chỉnh có thể cài đặt gói npm hiện tại bằng openclaw plugins install @openclaw/mattermost. Kiểm tra npmjs.com/package/@openclaw/mattermost để biết dist-tag hiện tại trước khi ghim phiên bản.

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

Chế độ trò chuyện: oncall (phản hồi khi được @-mention, mặc định), onmessage (mọi tin nhắn), onchar (tin nhắn bắt đầu bằng tiền tố kích hoạt).

Khi lệnh gốc của Mattermost được bật:

• commands.callbackPath phải là một đường dẫn (ví dụ /api/channels/mattermost/command), không phải URL đầy đủ.
• commands.callbackUrl phải phân giải tới endpoint Gateway của OpenClaw và truy cập được từ máy chủ Mattermost.
• Callback slash gốc được xác thực bằng token theo từng lệnh do Mattermost trả về trong quá trình đăng ký slash command. Nếu đăng ký thất bại hoặc không có lệnh nào được kích hoạt, OpenClaw sẽ từ chối callback với Unauthorized: invalid command token.
• Với các máy chủ callback riêng tư/tailnet/nội bộ, Mattermost có thể yêu cầu ServiceSettings.AllowedUntrustedInternalConnections bao gồm máy chủ/tên miền callback. Dùng giá trị máy chủ/tên miền, không dùng URL đầy đủ.
• channels.mattermost.configWrites: cho phép hoặc từ chối các lượt ghi cấu hình do Mattermost khởi tạo.
• channels.mattermost.requireMention: yêu cầu @mention trước khi trả lời trong kênh.
• channels.mattermost.groups.<channelId>.requireMention: ghi đè kiểm soát yêu cầu nhắc tên theo từng kênh ("*" cho mặc định).
• channels.mattermost.defaultAccount tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình.

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

Chế độ thông báo phản ứng: off, own (mặc định), all, allowlist (từ reactionAllowlist).

• channels.signal.account: ghim khởi động kênh vào một danh tính tài khoản Signal cụ thể.
• channels.signal.configWrites: cho phép hoặc từ chối các lượt ghi cấu hình do Signal khởi tạo.
• channels.signal.defaultAccount tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình.

# BlueBubbles

BlueBubbles là cầu nối iMessage cũ (được Plugin hỗ trợ, cấu hình trong channels.bluebubbles). Các thiết lập hiện có vẫn được hỗ trợ, nhưng các triển khai iMessage OpenClaw mới nên ưu tiên channels.imessage khi imsg có thể chạy trên máy chủ Messages.

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

• Các đường dẫn khóa lõi được đề cập ở đây: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• channels.bluebubbles.defaultAccount tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình.
• Các mục bindings[] cấp cao nhất với type: "acp" có thể liên kết cuộc trò chuyện BlueBubbles với các phiên ACP bền vững. Dùng handle BlueBubbles hoặc chuỗi đích (chat_id:*, chat_guid:*, chat_identifier:*) trong match.peer.id. Ngữ nghĩa trường dùng chung: Tác nhân ACP.
• Cấu hình đầy đủ của kênh BlueBubbles và lý do ngừng khuyến nghị được ghi lại trong BlueBubbles.

# iMessage

OpenClaw khởi chạy imsg rpc (JSON-RPC qua stdio). Không cần daemon hoặc cổng. Đây là đường dẫn được ưu tiên cho các thiết lập iMessage OpenClaw mới khi máy chủ có thể cấp quyền cơ sở dữ liệu Messages và quyền 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 tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình.

• Yêu cầu Full Disk Access tới DB của Messages.

• Ưu tiên đích chat_id:<id>. Dùng imsg chats --limit 20 để liệt kê cuộc trò chuyện.

• cliPath có thể trỏ tới một wrapper SSH; đặt remoteHost (host hoặc user@host) để lấy tệp đính kèm qua SCP.

• attachmentRoots và remoteAttachmentRoots giới hạn đường dẫn tệp đính kèm đầu vào (mặc định: /Users/*/Library/Messages/Attachments).

• SCP dùng kiểm tra host-key nghiêm ngặt, vì vậy hãy bảo đảm khóa máy chủ chuyển tiếp đã tồn tại trong ~/.ssh/known_hosts.

• channels.imessage.configWrites: cho phép hoặc từ chối các lượt ghi cấu hình do iMessage khởi tạo.

• Các mục bindings[] cấp cao nhất với type: "acp" có thể liên kết cuộc trò chuyện iMessage với các phiên ACP bền vững. Dùng handle đã chuẩn hóa hoặc đích cuộc trò chuyện rõ ràng (chat_id:*, chat_guid:*, chat_identifier:*) trong match.peer.id. Ngữ nghĩa trường dùng chung: Tác nhân ACP.

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

# Matrix

Matrix được Plugin hỗ trợ và được cấu hình trong 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",
        },
      },
    },
  },
}

• Xác thực bằng token dùng accessToken; xác thực bằng mật khẩu dùng userId + password.
• channels.matrix.proxy định tuyến lưu lượng HTTP của Matrix qua một proxy HTTP(S) rõ ràng. Các tài khoản có tên có thể ghi đè bằng channels.matrix.accounts.<id>.proxy.
• channels.matrix.network.dangerouslyAllowPrivateNetwork cho phép homeserver riêng tư/nội bộ. proxy và lựa chọn tham gia mạng này là các điều khiển độc lập.
• channels.matrix.defaultAccount chọn tài khoản ưu tiên trong thiết lập nhiều tài khoản.
• channels.matrix.autoJoin mặc định là off, nên các phòng được mời và lời mời kiểu DM mới sẽ bị bỏ qua cho tới khi bạn đặt autoJoin: "allowlist" với autoJoinAllowlist hoặc autoJoin: "always".
• channels.matrix.execApprovals: phân phối phê duyệt exec gốc Matrix và ủy quyền người phê duyệt.
  • enabled: true, false, hoặc "auto" (mặc định). Ở chế độ tự động, phê duyệt exec được kích hoạt khi có thể phân giải người phê duyệt từ approvers hoặc commands.ownerAllowFrom.
  • approvers: id người dùng Matrix (ví dụ @owner:example.org) được phép phê duyệt yêu cầu exec.
  • agentFilter: danh sách cho phép id tác nhân tùy chọn. Bỏ qua để chuyển tiếp phê duyệt cho mọi tác nhân.
  • sessionFilter: mẫu khóa phiên tùy chọn (chuỗi con hoặc regex).
  • target: nơi gửi lời nhắc phê duyệt. "dm" (mặc định), "channel" (phòng gốc), hoặc "both".
  • Ghi đè theo từng tài khoản: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope kiểm soát cách DM Matrix được nhóm vào phiên: per-user (mặc định) chia sẻ theo peer được định tuyến, còn per-room cô lập từng phòng DM.
• Các probe trạng thái Matrix và tra cứu thư mục trực tiếp dùng cùng chính sách proxy như lưu lượng runtime.
• Cấu hình Matrix đầy đủ, quy tắc nhắm mục tiêu, và ví dụ thiết lập được ghi lại trong Matrix.

# Microsoft Teams

Microsoft Teams được Plugin hỗ trợ và được cấu hình trong channels.msteams.

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

• Các đường dẫn khóa lõi được đề cập ở đây: channels.msteams, channels.msteams.configWrites.
• Cấu hình Teams đầy đủ (thông tin xác thực, Webhook, chính sách DM/nhóm, ghi đè theo từng nhóm/từng kênh) được ghi lại trong Microsoft Teams.

# IRC

IRC được Plugin hỗ trợ và được cấu hình trong channels.irc.

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

• Các đường dẫn khóa lõi được đề cập ở đây: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• channels.irc.defaultAccount tùy chọn ghi đè lựa chọn tài khoản mặc định khi khớp với một id tài khoản đã cấu hình.
• Cấu hình kênh IRC đầy đủ (máy chủ/cổng/TLS/kênh/danh sách cho phép/kiểm soát yêu cầu nhắc tên) được ghi lại trong IRC.

# Nhiều tài khoản (mọi kênh)

Chạy nhiều tài khoản trên mỗi kênh (mỗi tài khoản có accountId riêng):

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

• default được dùng khi accountId bị bỏ qua (CLI + định tuyến).
• Token env chỉ áp dụng cho tài khoản mặc định.
• Thiết lập kênh cơ sở áp dụng cho mọi tài khoản trừ khi được ghi đè theo từng tài khoản.
• Dùng bindings[].match.accountId để định tuyến từng tài khoản tới một tác nhân khác.
• Nếu bạn thêm tài khoản không mặc định qua openclaw channels add (hoặc onboarding kênh) khi vẫn đang dùng cấu hình kênh cấp cao nhất một tài khoản, OpenClaw trước tiên sẽ nâng cấp các giá trị một tài khoản cấp cao nhất có phạm vi tài khoản vào bản đồ tài khoản của kênh để tài khoản ban đầu tiếp tục hoạt động. Hầu hết các kênh chuyển chúng vào channels.<channel>.accounts.default; Matrix có thể giữ lại một đích có tên/mặc định khớp hiện có thay vào đó.
• Các binding chỉ theo kênh hiện có (không có accountId) tiếp tục khớp với tài khoản mặc định; binding có phạm vi tài khoản vẫn là tùy chọn.
• openclaw doctor --fix cũng sửa các dạng trộn lẫn bằng cách di chuyển các giá trị một tài khoản cấp cao nhất có phạm vi tài khoản vào tài khoản được nâng cấp đã chọn cho kênh đó. Hầu hết các kênh dùng accounts.default; Matrix có thể giữ lại một đích có tên/mặc định khớp hiện có thay vào đó.

# Các kênh Plugin khác

Nhiều kênh Plugin được cấu hình dưới dạng channels.<id> và được ghi lại trong các trang kênh chuyên dụng của chúng (ví dụ Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, và Twitch). Xem chỉ mục kênh đầy đủ: Kênh.

# Kiểm soát yêu cầu nhắc tên trong trò chuyện nhóm

Tin nhắn nhóm mặc định yêu cầu nhắc tên (nhắc tên metadata hoặc mẫu regex an toàn). Áp dụng cho trò chuyện nhóm WhatsApp, Telegram, Discord, Google Chat, và iMessage.

Các phản hồi hiển thị được kiểm soát riêng. Phòng nhóm/kênh mặc định là messages.groupChat.visibleReplies: "message_tool": OpenClaw vẫn xử lý lượt này, nhưng phản hồi cuối thông thường vẫn riêng tư và đầu ra phòng hiển thị yêu cầu message(action=send). Chỉ đặt "automatic" khi bạn muốn hành vi cũ, trong đó phản hồi thông thường được đăng lại vào phòng. Để áp dụng cùng hành vi phản hồi hiển thị chỉ qua công cụ cho cả trò chuyện trực tiếp, hãy đặt messages.visibleReplies: "message_tool"; Codex harness cũng dùng hành vi chỉ qua công cụ đó làm mặc định trò chuyện trực tiếp khi chưa đặt.

Phản hồi hiển thị chỉ qua công cụ yêu cầu model/runtime gọi công cụ một cách đáng tin cậy. Nếu nhật ký phiên hiển thị văn bản của assistant với didSendViaMessagingTool: false, thì model đã tạo câu trả lời cuối riêng tư thay vì gọi công cụ nhắn tin. Chuyển sang model gọi công cụ mạnh hơn cho kênh đó, hoặc đặt messages.groupChat.visibleReplies: "automatic" để khôi phục phản hồi cuối hiển thị theo hành vi cũ.

Nếu công cụ nhắn tin không khả dụng theo chính sách công cụ đang hoạt động, OpenClaw sẽ chuyển dự phòng sang phản hồi hiển thị tự động thay vì âm thầm chặn phản hồi. openclaw doctor cảnh báo về điểm không khớp này.

Gateway tải nóng cấu hình messages sau khi tệp được lưu. Chỉ khởi động lại khi tính năng theo dõi tệp hoặc tải lại cấu hình bị tắt trong triển khai.

Loại nhắc đến:

• Nhắc đến bằng metadata: @-mention gốc của nền tảng. Bị bỏ qua trong chế độ tự trò chuyện WhatsApp.
• Mẫu văn bản: Mẫu regex an toàn trong agents.list[].groupChat.mentionPatterns. Mẫu không hợp lệ và lặp lồng nhau không an toàn sẽ bị bỏ qua.
• Việc chặn theo nhắc đến chỉ được thực thi khi có thể phát hiện (nhắc đến gốc hoặc ít nhất một mẫu).

{
  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 đặt mặc định toàn cục. Các kênh có thể ghi đè bằng channels.<channel>.historyLimit (hoặc theo từng tài khoản). Đặt 0 để tắt.

messages.visibleReplies là mặc định toàn cục cho lượt nguồn; messages.groupChat.visibleReplies ghi đè giá trị đó cho các lượt nguồn nhóm/kênh. Khi messages.visibleReplies chưa được đặt, harness có thể cung cấp mặc định trực tiếp/nguồn của riêng nó; Codex harness mặc định là message_tool. Danh sách cho phép của kênh và chặn theo nhắc đến vẫn quyết định liệu một lượt có được xử lý hay không.

# Giới hạn lịch sử DM

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

Cách phân giải: ghi đè theo DM → mặc định của nhà cung cấp → không giới hạn (giữ lại tất cả).

Được hỗ trợ: telegram, whatsapp, discord, slack, signal, imessage, msteams.

# Chế độ tự trò chuyện

Bao gồm số của chính bạn trong allowFrom để bật chế độ tự trò chuyện (bỏ qua @-mention gốc, chỉ phản hồi các mẫu văn bản):

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

# Lệnh (xử lý lệnh trò chuyện)

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

# Liên quan

• Tham chiếu cấu hình — khóa cấp cao nhất
• Cấu hình — agents
• Tổng quan kênh