Slack

Socket mode (mặc định)

Cài đặt nhanh (dành cho người mới)

Tạo một Slack app và bật Socket Mode.
Tạo App Token (xapp-...) và Bot Token (xoxb-...).
Đặt token cho OpenClaw và khởi động Gateway.

Cấu hình tối thiểu:

{
  channels: {
    slack: {
      enabled: true,
      appToken: "xapp-...",
      botToken: "xoxb-...",
    },
  },
}

Cài đặt

Tạo một Slack app (From scratch) tại https://api.slack.com/apps.
Socket Mode → bật lên. Sau đó vào Basic Information → App-Level Tokens → Generate Token and Scopes với scope connections:write. Copy App Token (xapp-...).
OAuth & Permissions → thêm bot token scopes (dùng manifest bên dưới). Click Install to Workspace. Copy Bot User OAuth Token (xoxb-...).
Tùy chọn: OAuth & Permissions → thêm User Token Scopes (xem danh sách read-only bên dưới). Cài lại app và copy User OAuth Token (xoxp-...).
Event Subscriptions → bật events và đăng ký:
- message.* (bao gồm edits/deletes/thread broadcasts)
- app_mention
- reaction_added, reaction_removed
- member_joined_channel, member_left_channel
- channel_rename
- pin_added, pin_removed
Mời bot vào các channel mà các bạn muốn nó đọc.
Slash Commands → tạo /openclaw nếu các bạn dùng channels.slack.slashCommand. Nếu bật native commands, thêm một slash command cho mỗi lệnh built-in (tên giống như /help). Native mặc định tắt cho Slack trừ khi các bạn đặt channels.slack.commands.native: true (global commands.native là "auto" sẽ để Slack tắt).
App Home → bật Messages Tab để người dùng có thể DM bot.

Dùng manifest bên dưới để scopes và events luôn đồng bộ.

Hỗ trợ nhiều tài khoản: dùng channels.slack.accounts với token riêng cho từng tài khoản và name tùy chọn. Xem gateway/configuration để biết pattern chung.

Cấu hình OpenClaw (tối thiểu)

Đặt token qua biến môi trường (khuyên dùng):

SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...

Hoặc qua config:

{
  channels: {
    slack: {
      enabled: true,
      appToken: "xapp-...",
      botToken: "xoxb-...",
    },
  },
}

User token (tùy chọn)

OpenClaw có thể dùng Slack user token (xoxp-...) cho các thao tác đọc (history, pins, reactions, emoji, member info). Mặc định nó chỉ đọc: các thao tác đọc ưu tiên user token khi có, còn ghi vẫn dùng bot token trừ khi các bạn bật tường minh. Ngay cả khi userTokenReadOnly: false, bot token vẫn được ưu tiên cho ghi khi có sẵn.

User token được cấu hình trong file config (không hỗ trợ biến môi trường). Với nhiều tài khoản, đặt channels.slack.accounts.<id>.userToken.

Ví dụ với bot + app + user tokens:

{
  channels: {
    slack: {
      enabled: true,
      appToken: "xapp-...",
      botToken: "xoxb-...",
      userToken: "xoxp-...",
    },
  },
}

Ví dụ với userTokenReadOnly được đặt tường minh (cho phép user token ghi):

{
  channels: {
    slack: {
      enabled: true,
      appToken: "xapp-...",
      botToken: "xoxb-...",
      userToken: "xoxp-...",
      userTokenReadOnly: false,
    },
  },
}

Cách dùng token

Thao tác đọc (history, reactions list, pins list, emoji list, member info, search) ưu tiên user token khi được cấu hình, nếu không thì dùng bot token.
Thao tác ghi (send/edit/delete messages, add/remove reactions, pin/unpin, file uploads) dùng bot token mặc định. Nếu userTokenReadOnly: false và không có bot token, OpenClaw sẽ dùng user token.

History context

channels.slack.historyLimit (hoặc channels.slack.accounts.*.historyLimit) kiểm soát số lượng tin nhắn channel/group gần đây được đưa vào prompt.
Fallback về messages.groupChat.historyLimit. Đặt 0 để tắt (mặc định 50).

HTTP mode (Events API)

Dùng HTTP webhook mode khi Gateway của các bạn có thể truy cập được từ Slack qua HTTPS (thường dùng cho triển khai server). HTTP mode dùng Events API + Interactivity + Slash Commands với một request URL chung.

Cài đặt

Tạo một Slack app và tắt Socket Mode (tùy chọn nếu các bạn chỉ dùng HTTP).
Basic Information → copy Signing Secret.
OAuth & Permissions → cài app và copy Bot User OAuth Token (xoxb-...).
Event Subscriptions → bật events và đặt Request URL thành đường dẫn webhook của gateway (mặc định /slack/events).
Interactivity & Shortcuts → bật và đặt cùng Request URL.
Slash Commands → đặt cùng Request URL cho lệnh của các bạn.

Ví dụ request URL: https://gateway-host/slack/events

Cấu hình OpenClaw (tối thiểu)

{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: "xoxb-...",
      signingSecret: "your-signing-secret",
      webhookPath: "/slack/events",
    },
  },
}

HTTP mode nhiều tài khoản: đặt channels.slack.accounts.<id>.mode = "http" và cung cấp webhookPath riêng cho mỗi tài khoản để mỗi Slack app có thể trỏ đến URL riêng.

Manifest (tùy chọn)

Dùng Slack app manifest này để tạo app nhanh (điều chỉnh tên/lệnh nếu muốn). Bao gồm user scopes nếu các bạn định cấu hình user token.

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": {
      "display_name": "OpenClaw",
      "always_online": false
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "channels:history",
        "channels:read",
        "groups:history",
        "groups:read",
        "groups:write",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "users:read",
        "app_mentions:read",
        "reactions:read",
        "reactions:write",
        "pins:read",
        "pins:write",
        "emoji:read",
        "commands",
        "files:read",
        "files:write"
      ],
      "user": [
        "channels:history",
        "channels:read",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "mpim:history",
        "mpim:read",
        "users:read",
        "reactions:read",
        "pins:read",
        "emoji:read",
        "search:read"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "reaction_added",
        "reaction_removed",
        "member_joined_channel",
        "member_left_channel",
        "channel_rename",
        "pin_added",
        "pin_removed"
      ]
    }
  }
}

Nếu các bạn bật native commands, thêm một entry slash_commands cho mỗi lệnh muốn expose (khớp với danh sách /help). Override bằng channels.slack.commands.native.

Scopes (hiện tại vs tùy chọn)

Conversations API của Slack được phân scope theo loại: các bạn chỉ cần scopes cho các loại conversation mà thực sự dùng (channels, groups, im, mpim). Xem https://docs.slack.dev/apis/web-api/using-the-conversations-api/ để biết tổng quan.

Bot token scopes (bắt buộc)

chat:write (send/update/delete messages qua chat.postMessage) https://docs.slack.dev/reference/methods/chat.postMessage
im:write (mở DM qua conversations.open cho user DM) https://docs.slack.dev/reference/methods/conversations.open
channels:history, groups:history, im:history, mpim:history https://docs.slack.dev/reference/methods/conversations.history
channels:read, groups:read, im:read, mpim:read https://docs.slack.dev/reference/methods/conversations.info
users:read (tra cứu user) https://docs.slack.dev/reference/methods/users.info
reactions:read, reactions:write (reactions.get / reactions.add) https://docs.slack.dev/reference/methods/reactions.get https://docs.slack.dev/reference/methods/reactions.add
pins:read, pins:write (pins.list / pins.add / pins.remove) https://docs.slack.dev/reference/scopes/pins.read https://docs.slack.dev/reference/scopes/pins.write
emoji:read (emoji.list) https://docs.slack.dev/reference/scopes/emoji.read
files:write (upload qua files.uploadV2) https://docs.slack.dev/messaging/working-with-files/#upload

User token scopes (tùy chọn, mặc định read-only)

Thêm các scope này vào User Token Scopes nếu các bạn cấu hình channels.slack.userToken.

channels:history, groups:history, im:history, mpim:history
channels:read, groups:read, im:read, mpim:read
users:read
reactions:read
pins:read
emoji:read
search:read

Chưa cần hôm nay (nhưng có thể cần sau)

mpim:write (chỉ khi mình thêm group-DM open/DM start qua conversations.open)
groups:write (chỉ khi mình thêm quản lý private-channel: create/rename/invite/archive)
chat:write.public (chỉ khi mình muốn post vào channel mà bot không ở trong đó) https://docs.slack.dev/reference/scopes/chat.write.public
users:read.email (chỉ khi mình cần trường email từ users.info) https://docs.slack.dev/changelog/2017-04-narrowing-email-access
files:read (chỉ khi mình bắt đầu list/đọc file metadata)

Config

Slack dùng Socket Mode (không có HTTP webhook server). Cung cấp cả hai token:

{
  "slack": {
    "enabled": true,
    "botToken": "xoxb-...",
    "appToken": "xapp-...",
    "groupPolicy": "allowlist",
    "dm": {
      "enabled": true,
      "policy": "pairing",
      "allowFrom": ["U123", "U456", "*"],
      "groupEnabled": false,
      "groupChannels": ["G123"],
      "replyToMode": "all"
    },
    "channels": {
      "C123": { "allow": true, "requireMention": true },
      "#general": {
        "allow": true,
        "requireMention": true,
        "users": ["U123"],
        "skills": ["search", "docs"],
        "systemPrompt": "Keep answers short."
      }
    },
    "reactionNotifications": "own",
    "reactionAllowlist": ["U123"],
    "replyToMode": "off",
    "actions": {
      "reactions": true,
      "messages": true,
      "pins": true,
      "memberInfo": true,
      "emojiList": true
    },
    "slashCommand": {
      "enabled": true,
      "name": "openclaw",
      "sessionPrefix": "slack:slash",
      "ephemeral": true
    },
    "textChunkLimit": 4000,
    "mediaMaxMb": 20
  }
}

Token cũng có thể được cung cấp qua biến môi trường:

SLACK_BOT_TOKEN
SLACK_APP_TOKEN

Ack reactions được kiểm soát toàn cục qua messages.ackReaction + messages.ackReactionScope. Dùng messages.removeAckAfterReply để xóa ack reaction sau khi bot trả lời.

Giới hạn

Text gửi đi được chia thành các chunk theo channels.slack.textChunkLimit (mặc định 4000).
Chunking theo dòng mới tùy chọn: đặt channels.slack.chunkMode="newline" để tách theo dòng trống (ranh giới đoạn văn) trước khi chia theo độ dài.
Upload media bị giới hạn bởi channels.slack.mediaMaxMb (mặc định 20).

Reply threading

Mặc định, OpenClaw trả lời trong channel chính. Dùng channels.slack.replyToMode để kiểm soát threading tự động:

Mode	Hành vi
`off`	Mặc định. Trả lời trong channel chính. Chỉ thread nếu tin nhắn kích hoạt đã ở trong thread.
`first`	Reply đầu tiên vào thread (dưới tin nhắn kích hoạt), các reply sau vào channel chính. Hữu ích để giữ context hiển thị mà tránh thread lộn xộn.
`all`	Tất cả reply vào thread. Giữ cuộc trò chuyện gọn gàng nhưng có thể giảm khả năng hiển thị.

Mode này áp dụng cho cả auto-reply và agent tool calls (slack sendMessage).

Threading theo loại chat

Các bạn có thể cấu hình hành vi threading khác nhau cho từng loại chat bằng cách đặt channels.slack.replyToModeByChatType:

{
  channels: {
    slack: {
      replyToMode: "off", // mặc định cho channels
      replyToModeByChatType: {
        direct: "all", // DM luôn thread
        group: "first", // group DM/MPIM thread reply đầu
      },
    },
  },
}

Các loại chat được hỗ trợ:

direct: DM 1:1 (Slack im)
group: group DM / MPIM (Slack mpim)
channel: channel tiêu chuẩn (public/private)

Thứ tự ưu tiên:

replyToModeByChatType.<chatType>
replyToMode
Provider default (off)

Legacy channels.slack.dm.replyToMode vẫn được chấp nhận làm fallback cho direct khi không có override theo chat-type.

Ví dụ:

Thread chỉ DM:

{
  channels: {
    slack: {
      replyToMode: "off",
      replyToModeByChatType: { direct: "all" },
    },
  },
}

Thread group DM nhưng giữ channel ở root:

{
  channels: {
    slack: {
      replyToMode: "off",
      replyToModeByChatType: { group: "first" },
    },
  },
}

Làm channel thread, giữ DM ở root:

{
  channels: {
    slack: {
      replyToMode: "first",
      replyToModeByChatType: { direct: "off", group: "off" },
    },
  },
}

Tag threading thủ công

Để kiểm soát chi tiết, dùng các tag này trong response của agent:

[[reply_to_current]] — trả lời tin nhắn kích hoạt (bắt đầu/tiếp tục thread).
[[reply_to:<id>]] — trả lời một message id cụ thể.

Session + routing

DM chia sẻ session main (giống WhatsApp/Telegram).
Channel map tới session agent:<agentId>:slack:channel:<channelId>.
Slash commands dùng session agent:<agentId>:slack:slash:<userId> (prefix có thể cấu hình qua channels.slack.slashCommand.sessionPrefix).
Nếu Slack không cung cấp channel_type, OpenClaw suy ra từ prefix channel ID (D, C, G) và mặc định là channel để giữ session key ổn định.
Đăng ký native command dùng commands.native (global mặc định "auto" → Slack tắt) và có thể override cho từng workspace bằng channels.slack.commands.native. Text commands yêu cầu tin nhắn /... độc lập và có thể tắt bằng commands.text: false. Slack slash commands được quản lý trong Slack app và không tự động xóa. Dùng commands.useAccessGroups: false để bỏ qua kiểm tra access-group cho lệnh.
Danh sách lệnh đầy đủ + config: Slash commands

Bảo mật DM (pairing)

Mặc định: channels.slack.dm.policy="pairing" — người gửi DM không xác định sẽ nhận mã pairing (hết hạn sau 1 giờ).
Phê duyệt qua: openclaw pairing approve slack <code>.
Để cho phép bất kỳ ai: đặt channels.slack.dm.policy="open" và channels.slack.dm.allowFrom=["*"].
channels.slack.dm.allowFrom chấp nhận user ID, @handle, hoặc email (được resolve khi khởi động nếu token cho phép). Wizard chấp nhận username và resolve thành id trong quá trình setup khi token cho phép.

Group policy

channels.slack.groupPolicy kiểm soát xử lý channel (open|disabled|allowlist).
allowlist yêu cầu channel phải được liệt kê trong channels.slack.channels.
Nếu các bạn chỉ đặt SLACK_BOT_TOKEN/SLACK_APP_TOKEN và không tạo section channels.slack, runtime sẽ mặc định groupPolicy thành open. Thêm channels.slack.groupPolicy, channels.defaults.groupPolicy, hoặc channel allowlist để khóa lại.
Configure wizard chấp nhận tên #channel và resolve thành ID khi có thể (public + private); nếu có nhiều kết quả khớp, nó ưu tiên channel đang hoạt động.
Khi khởi động, OpenClaw resolve tên channel/user trong allowlist thành ID (khi token cho phép) và log mapping; các entry không resolve được sẽ giữ nguyên như đã nhập.
Để không cho phép channel nào, đặt channels.slack.groupPolicy: "disabled" (hoặc giữ allowlist rỗng).

Tùy chọn channel (channels.slack.channels.<id> hoặc channels.slack.channels.<name>):

allow: cho phép/từ chối channel khi groupPolicy="allowlist".
requireMention: mention gating cho channel.
tools: override tool policy tùy chọn cho từng channel (allow/deny/alsoAllow).
toolsBySender: override tool policy tùy chọn cho từng sender trong channel (key là sender id/@handle/email; hỗ trợ wildcard "*").
allowBots: cho phép tin nhắn từ bot trong channel này (mặc định: false).
users: allowlist user tùy chọn cho từng channel.
skills: bộ lọc skill (bỏ qua = tất cả skill, rỗng = không có).
systemPrompt: system prompt bổ sung cho channel (kết hợp với topic/purpose).
enabled: đặt false để tắt channel.

Delivery target

Dùng với cron/CLI send:

user:<id> cho DM
channel:<id> cho channel

Tool actions

Slack tool actions có thể được kiểm soát bằng channels.slack.actions.*:

Action group	Mặc định	Ghi chú
reactions	enabled	React + list reactions
messages	enabled	Read/send/edit/delete
pins	enabled	Pin/unpin/list
memberInfo	enabled	Member info
emojiList	enabled	Custom emoji list

Lưu ý bảo mật

Ghi mặc định dùng bot token nên các hành động thay đổi trạng thái được giới hạn trong quyền và danh tính bot của app.
Đặt userTokenReadOnly: false cho phép user token được dùng cho thao tác ghi khi không có bot token, nghĩa là các hành động chạy với quyền truy cập của user cài đặt. Coi user token là có đặc quyền cao và giữ action gate và allowlist chặt chẽ.
Nếu các bạn bật user-token write, đảm bảo user token bao gồm các write scope mong đợi (chat:write, reactions:write, pins:write, files:write) nếu không các thao tác đó sẽ thất bại.

Ghi chú

Mention gating được kiểm soát qua channels.slack.channels (đặt requireMention thành true); agents.list[].groupChat.mentionPatterns (hoặc messages.groupChat.mentionPatterns) cũng được tính là mention.
Override nhiều agent: đặt pattern riêng cho từng agent trên agents.list[].groupChat.mentionPatterns.
Reaction notification theo channels.slack.reactionNotifications (dùng reactionAllowlist với mode allowlist).
Tin nhắn từ bot bị bỏ qua mặc định; bật qua channels.slack.allowBots hoặc channels.slack.channels.<id>.allowBots.
Cảnh báo: Nếu các bạn cho phép reply tới bot khác (channels.slack.allowBots=true hoặc channels.slack.channels.<id>.allowBots=true), ngăn vòng lặp reply bot-to-bot bằng requireMention, allowlist channels.slack.channels.<id>.users, và/hoặc guardrail rõ ràng trong AGENTS.md và SOUL.md.
Đối với Slack tool, ngữ nghĩa xóa reaction ở /tools/reactions.
Attachment được tải về media store khi được phép và dưới giới hạn kích thước.