Slack

Socket 模式(默认)

快速设置(新手)

创建一个 Slack 应用并启用 Socket 模式。
创建 App Token(xapp-...)和 Bot Token(xoxb-...)。
为 OpenClaw 设置令牌并启动网关。

最小配置:

json5

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

设置

在 https://api.slack.com/apps. 中创建 Slack 应用(从头开始)
Socket 模式 → 开启。然后前往 基本信息 → 应用级令牌 → 生成令牌和作用域,使用作用域 connections:write。复制 应用令牌(xapp-...)。
OAuth 与权限 → 添加机器人令牌作用域(使用下面的清单)。点击 安装到工作区。复制 Bot User OAuth Token(xoxb-...)。
可选:OAuth 与权限 → 添加 用户令牌作用域(参见下面的只读列表)。重新安装应用并复制 User OAuth Token(xoxp-...)。
事件订阅 → 启用事件并订阅:
- message.*(包括编辑/删除/线程广播)
- app_mention
- reaction_added、reaction_removed
- member_joined_channel、member_left_channel
- channel_rename
- pin_added、pin_removed
邀请机器人到你希望它读取的频道。
斜杠命令 → 如果使用 channels.slack.slashCommand,创建 /openclaw。如果启用原生命令,为每个内置命令添加一个斜杠命令(与 /help 相同的名称)。除非设置 channels.slack.commands.native: true(全局 commands.native 是 "auto",这会将 Slack 关闭),否则 Slack 的原生默认为关闭。
应用主页 → 启用 消息标签,以便用户可以私信机器人。

使用下面的清单以保持作用域和事件同步。

多账户支持:使用 channels.slack.accounts,为每个账户设置令牌和可选的 name。参见 gateway/configuration 了解共享模式。

OpenClaw 配置(最小)

通过环境变量设置令牌(推荐):

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

或通过配置:

json5

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

用户令牌(可选)

OpenClaw 可以使用 Slack 用户令牌(xoxp-...)进行读取操作(历史记录、置顶、反应、表情符号、成员信息)。默认情况下保持只读:当存在用户令牌时读取优先使用用户令牌,写入仍使用机器人令牌,除非明确选择加入。即使设置了 userTokenReadOnly: false, 当机器人令牌可用时,写入仍优先使用机器人令牌。

用户令牌在配置文件中配置(不支持环境变量)。对于多账户, 设置 channels.slack.accounts.<id>.userToken。

带有 bot + app + user 令牌的示例:

json5

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

显式设置 userTokenReadOnly 的示例(允许用户令牌写入):

json5

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

令牌使用

读取操作(历史记录、反应列表、置顶列表、表情符号列表、成员信息、搜索)在配置时优先使用用户令牌,否则使用机器人令牌。
写入操作(发送/编辑/删除消息、添加/删除反应、置顶/取消置顶、文件上传)默认使用机器人令牌。如果 userTokenReadOnly: false 且没有机器人令牌可用,OpenClaw 将回退到用户令牌。

历史上下文

channels.slack.historyLimit(或 channels.slack.accounts.*.historyLimit)控制将多少最近的频道/群组消息包装到提示中。
回退到 messages.groupChat.historyLimit。设置 0 以禁用(默认 50)。

HTTP 模式(事件 API)

当您的网关可通过 HTTPS 被 Slack 访问时使用 HTTP webhook 模式(典型的服务器部署)。 HTTP 模式使用事件 API + 交互性 + 斜杠命令,共享一个请求 URL。

设置

创建一个 Slack 应用并 禁用 Socket 模式(如果只使用 HTTP 则为可选)。
基本信息 → 复制 签名密钥。
OAuth 与权限 → 安装应用并复制 Bot User OAuth Token(xoxb-...)。
事件订阅 → 启用事件并将 请求 URL 设置为您的网关 webhook 路径(默认 /slack/events)。
交互性与快捷方式 → 启用并设置相同的 请求 URL。
斜杠命令 → 为您的命令设置相同的 请求 URL。

示例请求 URL: https://gateway-host/slack/events

OpenClaw 配置(最小)

json5

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

多账户 HTTP 模式:设置 channels.slack.accounts.<id>.mode = "http" 并为每个账户提供唯一的 webhookPath,以便每个 Slack 应用可以指向自己的 URL。

清单(可选)

使用此 Slack 应用清单快速创建应用(根据需要调整名称/命令)。如果您计划配置用户令牌,请包含用户作用域。

json

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

如果启用原生命令,为您想要公开的每个命令添加一个 slash_commands 条目(与 /help 列表匹配)。使用 channels.slack.commands.native 覆盖。

作用域(当前与可选)

Slack 的对话 API 是类型作用域的:您只需要实际触及的对话类型的作用域 (频道、群组、即时消息、多人即时消息)。参见 https://docs.slack.dev/apis/web-api/using-the-conversations-api/ 了解概述。

机器人令牌作用域(必需)

chat:write(通过 chat.postMessage 发送/更新/删除消息) https://docs.slack.dev/reference/methods/chat.postMessage
im:write(通过 conversations.open 打开 DM 用于用户 DM) https://docs.slack.dev/reference/methods/conversations.open
channels:history、groups:history、im:history、mpim:historyhttps://docs.slack.dev/reference/methods/conversations.history
channels:read、groups:read、im:read、mpim:readhttps://docs.slack.dev/reference/methods/conversations.info
users:read(用户查找) 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(通过 files.uploadV2 上传) https://docs.slack.dev/messaging/working-with-files/#upload

用户令牌作用域(可选,默认只读)

如果配置 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

今天不需要(但可能在未来)

mpim:write(仅当我们通过 conversations.open 添加群组 DM 打开/DM 启动时)
groups:write(仅当我们添加私有频道管理:创建/重命名/邀请/归档时)
chat:write.public(仅当我们想要发布到机器人不在的频道时) https://docs.slack.dev/reference/scopes/chat.write.public
users:read.email(仅当我们需要从 users.info 获取电子邮件字段时) https://docs.slack.dev/changelog/2017-04-narrowing-email-access
files:read(仅当我们开始列出/读取文件元数据时)

配置

Slack 仅使用 Socket 模式(无 HTTP webhook 服务器)。提供两个令牌:

json

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

令牌也可以通过环境变量提供:

SLACK_BOT_TOKEN
SLACK_APP_TOKEN

确认反应通过 messages.ackReaction + messages.ackReactionScope 全局控制。使用 messages.removeAckAfterReply 在机器人回复后清除确认反应。

限制

出站文本被分块为 channels.slack.textChunkLimit(默认 4000)。
可选换行分块:设置 channels.slack.chunkMode="newline" 以在长度分块之前在空行(段落边界)处拆分。
媒体上传受 channels.slack.mediaMaxMb 限制(默认 20)。

回复线程

默认情况下,OpenClaw 在主频道中回复。使用 channels.slack.replyToMode 控制自动线程:

模式	行为
`off`	默认。在主频道回复。仅当触发消息已在线程中时才在线程中回复。
`first`	第一个回复进入线程(在触发消息下),后续回复进入主频道。用于保持上下文可见同时避免线程混乱。
`all`	所有回复进入线程。保持对话包含但可能降低可见性。

该模式适用于自动回复和代理工具调用(slack sendMessage)。

按聊天类型的线程

您可以通过设置 channels.slack.replyToModeByChatType 为每种聊天类型配置不同的线程行为:

json5

{
  channels: {
    slack: {
      replyToMode: "off", // default for channels
      replyToModeByChatType: {
        direct: "all", // DMs always thread
        group: "first", // group DMs/MPIM thread first reply
      },
    },
  },
}

支持的聊天类型:

direct:1:1 DM(Slack im)
group:群组 DM / MPIM(Slack mpim)
channel:标准频道(公开/私有)

优先级:

replyToModeByChatType.<chatType>
replyToMode
提供商默认(off)

遗留的 channels.slack.dm.replyToMode 仍被接受作为 direct 的后备,当没有设置聊天类型覆盖时。

示例:

仅线程 DM:

json5

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

线程群组 DM 但保持频道在根目录:

json5

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

使频道成为线程,保持 DM 在根目录:

json5

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

手动线程标签

对于细粒度控制,在代理响应中使用这些标签:

[[reply_to_current]] — 回复触发消息(开始/继续线程)。
[[reply_to:<id>]] — 回复特定消息 ID。

会话 + 路由

DM 共享 main 会话(如 WhatsApp/Telegram)。
频道映射到 agent:<agentId>:slack:channel:<channelId> 会话。
斜杠命令使用 agent:<agentId>:slack:slash:<userId> 会话(前缀可通过 channels.slack.slashCommand.sessionPrefix 配置)。
如果 Slack 不提供 channel_type,OpenClaw 从频道 ID 前缀推断(D、C、G)并默认为 channel 以保持会话键稳定。
原生命令注册使用 commands.native(全局默认 "auto" → Slack 关闭),可以通过 channels.slack.commands.native 按工作区覆盖。文本命令需要独立的 /... 消息,可以通过 commands.text: false 禁用。Slack 斜杠命令在 Slack 应用中管理,不会自动删除。使用 commands.useAccessGroups: false 绕过命令的访问组检查。
完整命令列表 + 配置:斜杠命令

DM 安全(配对)

默认:channels.slack.dm.policy="pairing" — 未知 DM 发送者获得配对代码(1 小时后过期)。
通过以下方式批准:openclaw pairing approve slack <code>。
允许任何人:设置 channels.slack.dm.policy="open" 和 channels.slack.dm.allowFrom=["*"]。
channels.slack.dm.allowFrom 接受用户 ID、@handles 或电子邮件(在令牌允许时在启动时解析)。向导接受用户名并在令牌允许时在设置期间将其解析为 ID。

群组策略

channels.slack.groupPolicy 控制频道处理(open|disabled|allowlist)。
allowlist 要求频道列在 channels.slack.channels 中。
如果您只设置 SLACK_BOT_TOKEN/SLACK_APP_TOKEN 而从不创建 channels.slack 部分, 运行时默认 groupPolicy 为 open。添加 channels.slack.groupPolicy、 channels.defaults.groupPolicy 或频道允许列表以锁定它。
配置向导接受 #channel 名称并在可能时将其解析为 ID (公开 + 私有);如果存在多个匹配,它优先选择活动频道。
启动时,OpenClaw 将允许列表中的频道/用户名称解析为 ID(当令牌允许时) 并记录映射;未解析的条目保持原样。
要允许 没有频道,设置 channels.slack.groupPolicy: "disabled"(或保持空允许列表)。

频道选项(channels.slack.channels.<id> 或 channels.slack.channels.<name>):

allow:当 groupPolicy="allowlist" 时允许/拒绝频道。
requireMention:频道的提及门控。
tools:可选的每频道工具策略覆盖(allow/deny/alsoAllow)。
toolsBySender:频道内可选的每发送者工具策略覆盖(键为发送者 ID/@handles/电子邮件;支持 "*" 通配符)。
allowBots:允许此频道中机器人编写的消息(默认:false)。
users:可选的每频道用户允许列表。
skills:技能过滤器(省略 = 所有技能,空 = 无)。
systemPrompt:频道的额外系统提示(与主题/目的组合)。
enabled:设置 false 以禁用频道。

投递目标

与 cron/CLI 发送一起使用:

user:<id> 用于 DM
channel:<id> 用于频道

工具操作

Slack 工具操作可以通过 channels.slack.actions.* 门控:

操作组	默认	注释
reactions	启用	反应 + 列出反应
messages	启用	读取/发送/编辑/删除
pins	启用	置顶/取消置顶/列表
memberInfo	启用	成员信息
emojiList	启用	自定义表情符号列表

安全说明

写入默认使用机器人令牌,因此状态更改操作保持在应用的机器人权限和身份范围内。
设置 userTokenReadOnly: false 允许在机器人令牌不可用时使用用户令牌进行写入操作,这意味着操作以安装用户的访问权限运行。将用户令牌视为高度特权, 并保持操作门控和允许列表严格。
如果启用用户令牌写入,请确保用户令牌包含您期望的写入作用域(chat:write、reactions:write、pins:write、 files:write),否则这些操作将失败。

注释

提及门控通过 channels.slack.channels 控制(将 requireMention 设置为 true);agents.list[].groupChat.mentionPatterns(或 messages.groupChat.mentionPatterns)也算作提及。
多代理覆盖:在 agents.list[].groupChat.mentionPatterns 上设置每个代理的模式。
反应通知遵循 channels.slack.reactionNotifications(使用 reactionAllowlist 与模式 allowlist)。
默认情况下忽略机器人编写的消息;通过 channels.slack.allowBots 或 channels.slack.channels.<id>.allowBots 启用。
警告:如果允许回复其他机器人(channels.slack.allowBots=true 或 channels.slack.channels.<id>.allowBots=true),请使用 requireMention、channels.slack.channels.<id>.users 允许列表和/或 AGENTS.md 和 SOUL.md 中的明确防护措施防止机器人对机器人的回复循环。
对于 Slack 工具,反应删除语义在 /tools/reactions 中。
当允许并在大小限制内时,附件被下载到媒体存储。

Slack ​

Socket 模式(默认) ​

快速设置(新手) ​

设置 ​

OpenClaw 配置(最小) ​

用户令牌(可选) ​

令牌使用 ​

历史上下文 ​

HTTP 模式(事件 API) ​

设置 ​

OpenClaw 配置(最小) ​

清单(可选) ​

作用域(当前与可选) ​

机器人令牌作用域(必需) ​

用户令牌作用域(可选,默认只读) ​

今天不需要(但可能在未来) ​

配置 ​

限制 ​

回复线程 ​

按聊天类型的线程 ​

手动线程标签 ​

会话 + 路由 ​

DM 安全(配对) ​

群组策略 ​

投递目标 ​

工具操作 ​

安全说明 ​

注释 ​

Slack

Socket 模式(默认)

快速设置(新手)

设置

OpenClaw 配置(最小)

用户令牌(可选)

令牌使用

历史上下文

HTTP 模式(事件 API)

设置

OpenClaw 配置(最小)

清单(可选)

作用域(当前与可选)

机器人令牌作用域(必需)

用户令牌作用域(可选,默认只读)

今天不需要(但可能在未来)

配置

限制

回复线程

按聊天类型的线程

手动线程标签

会话 + 路由

DM 安全(配对)

群组策略

投递目标

工具操作

安全说明

注释