OpenClawSkills
GitHub
通道 • 5 分钟阅读

Slack

Slack：Socket 模式或 HTTP（Events API）模式的配置方法

Tutorial.step

Socket Mode（默认）

#

Tutorial.step

新手快速配置

1. 创建一个 Slack App，并启用 <strong>Socket Mode</strong>。

2. 创建 <strong>App Token</strong>（<code>xapp-...</code>）与 <strong>Bot Token</strong>（<code>xoxb-...</code>）。

3. 把 token 配置到 OpenClaw，启动 gateway。

最小配置：

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

#

Tutorial.step

详细设置

1. 在 https://api.slack.com/apps 创建 Slack App（From scratch）。

2. <strong>Socket Mode</strong> → 打开。然后到 <strong>Basic Information</strong> → <strong>App-Level Tokens</strong> → <strong>Generate Token and Scopes</strong>，添加 scope <code>connections:write</code>。复制 <strong>App Token</strong>（<code>xapp-...</code>）。

3. <strong>OAuth & Permissions</strong> → 添加 bot token scopes（建议直接用下方 manifest 确保 scopes 与事件订阅一致）。点击 <strong>Install to Workspace</strong>，复制 <strong>Bot User OAuth Token</strong>（<code>xoxb-...</code>）。

4. 可选：<strong>OAuth & Permissions</strong> → 添加 <strong>User Token Scopes</strong>（下方 read-only 列表）。重新安装 app 并复制 <strong>User OAuth Token</strong>（<code>xoxp-...</code>）。

5. <strong>Event Subscriptions</strong> → 启用 events，并订阅：

- <code>message.*</code>（包含编辑/删除/线程广播）

- <code>app_mention</code>

- <code>reaction_added</code>、<code>reaction_removed</code>

- <code>member_joined_channel</code>、<code>member_left_channel</code>

- <code>channel_rename</code>

- <code>pin_added</code>、<code>pin_removed</code>

6. 把 bot 邀请到你希望它能读取的频道里。

7. Slash Commands：如果你使用 <code>channels.slack.slashCommand</code>，创建 <code>/openclaw</code>。如果你启用 native commands，需要为每个内置命令各建一个 slash command（与 <code>/help</code> 中命令同名）。Slack 默认不会启用 native commands，除非你显式设置 <code>channels.slack.commands.native: true</code>（全局 <code>commands.native</code> 默认 <code>"auto"</code>，会让 Slack 保持关闭）。

8. App Home：启用 <strong>Messages Tab</strong>，让用户可以私信 bot。

建议使用下方 manifest，避免 scopes/events 配漏。

多账号：使用 '<code>'channels.slack.accounts'</code>' 为每个 workspace 配置 token（可选 '<code>'name'</code>'）。共享结构见 '<a href="/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts">'/gateway/configuration'</a>'。

#

Tutorial.step

OpenClaw 配置（最小）

推荐用环境变量（适合服务器）：

- <code>SLACK_APP_TOKEN=xapp-...</code>

- <code>SLACK_BOT_TOKEN=xoxb-...</code>

或配置文件：

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

#

Tutorial.step

User token（可选）

OpenClaw 可以使用 Slack user token（<code>xoxp-...</code>）来进行读操作（历史、pins、reactions、emoji、成员信息等）。默认保持只读：读取优先用 user token（如果存在），写入仍优先用 bot token，除非你显式允许 user token 写入。即便设置 <code>userTokenReadOnly: false</code>，只要 bot token 可用，写操作依旧优先走 bot token。

user token 只能通过配置文件设置（不支持 env）。多账号时设置 '<code>'channels.slack.accounts.'<id>'.userToken'</code>'。

示例（bot + app + user tokens）：

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

允许 user token 写入（慎用）：

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

##

Tutorial.step

Token 使用规则

- 读操作（history、reactions list、pins list、emoji list、member info、search）优先用 user token（如果配置了），否则用 bot token。

- 写操作（发送/编辑/删除消息、加/去 reactions、pin/unpin、文件上传）默认用 bot token；若 <code>userTokenReadOnly: false</code> 且 bot token 不可用，才会回退到 user token。

#

Tutorial.step

历史上下文

- <code>channels.slack.historyLimit</code>（或 <code>channels.slack.accounts.*.historyLimit</code>）控制注入多少最近频道/群消息作为上下文。

- 兜底为 <code>messages.groupChat.historyLimit</code>。设为 <code>0</code> 禁用（默认 50）。

Tutorial.step

HTTP Mode（Events API）

当你的 Gateway 能通过 HTTPS 被 Slack 访问时（典型服务器部署），使用 HTTP webhook 模式更合适。HTTP 模式使用 Events API + Interactivity + Slash Commands，并共享同一个 Request URL。

#

Tutorial.step

设置

1. 创建 Slack App，并（可选）关闭 Socket Mode（如果你只用 HTTP）。

2. <strong>Basic Information</strong> → 复制 <strong>Signing Secret</strong>。

3. <strong>OAuth & Permissions</strong> → 安装 app 并复制 <strong>Bot User OAuth Token</strong>（<code>xoxb-...</code>）。

4. <strong>Event Subscriptions</strong> → 启用 events，并把 <strong>Request URL</strong> 指向 gateway 的 webhook path（默认 <code>/slack/events</code>）。

5. <strong>Interactivity & Shortcuts</strong> → 启用，并设置同一个 <strong>Request URL</strong>。

6. <strong>Slash Commands</strong> → 对你的命令设置同一个 <strong>Request URL</strong>。

示例公网 URL：

<code>https://gateway-host/slack/events</code>

#

Tutorial.step

OpenClaw 配置（最小）

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

多账号 HTTP 模式：为每个账号设置 '<code>'channels.slack.accounts.'<id>'.mode = "http"'</code>'，并且为每个账号提供唯一的 '<code>'webhookPath'</code>'，让每个 Slack App 指向不同 URL。

#

Tutorial.step

Manifest（可选）

用 manifest 可以快速创建 app（按需改名字/命令）。如果你计划配置 user token，请把 user scopes 一并加入。

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

如果你启用 native commands，需要为每个你想暴露的命令添加一个 <code>slash_commands</code> 条目（与 <code>/help</code> 列表一致），并用 <code>channels.slack.commands.native</code> 覆盖默认行为。

Tutorial.step

Scopes（当前需要 vs 可选）

Slack Conversations API 是按对话类型拆分 scope 的：你只需要你会用到的对话类型 scopes（channels、groups、im、mpim）。概览：https://docs.slack.dev/apis/web-api/using-the-conversations-api/

#

Tutorial.step

Bot token scopes（必需）

- <code>chat:write</code>（发送/更新/删除消息）

https://docs.slack.dev/reference/methods/chat.postMessage

- <code>im:write</code>（打开私信对话，用于 user DMs）

https://docs.slack.dev/reference/methods/conversations.open

- <code>channels:history</code>, <code>groups:history</code>, <code>im:history</code>, <code>mpim:history</code>

https://docs.slack.dev/reference/methods/conversations.history

- <code>channels:read</code>, <code>groups:read</code>, <code>im:read</code>, <code>mpim:read</code>

https://docs.slack.dev/reference/methods/conversations.info

- <code>users:read</code>（用户信息查询）

https://docs.slack.dev/reference/methods/users.info

- <code>reactions:read</code>, <code>reactions:write</code>

https://docs.slack.dev/reference/methods/reactions.get

https://docs.slack.dev/reference/methods/reactions.add

- <code>pins:read</code>, <code>pins:write</code>

https://docs.slack.dev/reference/scopes/pins.read

https://docs.slack.dev/reference/scopes/pins.write

- <code>emoji:read</code>

https://docs.slack.dev/reference/scopes/emoji.read

- <code>files:write</code>（上传）

https://docs.slack.dev/messaging/working-with-files/#upload

#

Tutorial.step

User token scopes（可选，默认只读）

当你配置了 <code>channels.slack.userToken</code> 时，才需要在 <strong>User Token Scopes</strong> 中添加：

- <code>channels:history</code>, <code>groups:history</code>, <code>im:history</code>, <code>mpim:history</code>

- <code>channels:read</code>, <code>groups:read</code>, <code>im:read</code>, <code>mpim:read</code>

- <code>users:read</code>

- <code>reactions:read</code>

- <code>pins:read</code>

- <code>emoji:read</code>

- <code>search:read</code>

Tutorial.step

配置示例

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,
      "reactionLevel": "minimal"
    },
    "commands": {
      "native": false
    }
  }
}

Ack reactions 由全局 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.ackReaction'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.ackReactionScope'</code>' 控制；'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.removeAckAfterReply'</code>' 可在回复后移除 ack reaction。

Tutorial.step

Threading

Slack 支持线程回复。OpenClaw 可以在线程中回复或在顶层回复。

- <code>channels.slack.replyToMode</code>: <code>off | all | first | last</code>

- <code>off</code>：在顶层回复（无线程）。

- <code>all</code>：所有消息都在线程中回复。

- <code>first</code>：仅第一条消息在线程中回复。

- <code>last</code>：仅最后一条消息在线程中回复。

- 默认：<code>off</code>。

- 按频道覆盖：'<code>'channels.slack.channels.'<id>'.replyToMode'</code>'。

- 按频道用户：'<code>'channels.slack.channels.'<id>'.users'</code>'。

- 按频道技能：'<code>'channels.slack.channels.'<id>'.skills'</code>'。

- 按频道系统提示：'<code>'channels.slack.channels.'<id>'.systemPrompt'</code>'。

Tutorial.step

私信的 Threading

私信也可以使用线程。通过 <code>channels.slack.dm.replyToMode</code> 配置。

- <code>off</code>：在顶层回复。

- <code>all</code>：所有消息都在线程中回复。

- <code>first</code>：仅第一条消息在线程中回复。

- <code>last</code>：仅最后一条消息在线程中回复。

- 默认：<code>off</code>。

Tutorial.step

按聊天类型分别配置 threading

用 <code>channels.slack.replyToModeByChatType</code>：

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

支持的聊天类型：

- <code>direct</code>：一对一私信（Slack <code>im</code>）

- <code>group</code>：群私信/MPIM（Slack <code>mpim</code>）

- <code>channel</code>：普通频道（公有/私有）

优先级：

1. 1. '<code>'replyToModeByChatType.'<chatType>''</code>'

2. 2. <code>replyToMode</code>

3. 3. 默认值（<code>off</code>）

旧配置 <code>channels.slack.dm.replyToMode</code> 仍接受，作为 <code>direct</code> 的兜底。

#

Tutorial.step

手动 threading tags

需要更细粒度控制时，在 agent 回复里使用：

- <code>[[reply_to_current]]</code>

- '<code>'[[reply_to:'<id>']]'</code>'

Tutorial.step

会话与路由

- 私信使用 <code>main</code> 会话（与 WhatsApp/Telegram 类似）。

- 频道会话键：'<code>'agent:'<agentId>':slack:channel:'<channelId>''</code>'。

- Slash commands 会话键：'<code>'agent:'<agentId>':slack:slash:'<userId>''</code>'（前缀可通过 '<code>'channels.slack.slashCommand.sessionPrefix'</code>' 配置）。

- 如果 Slack 没提供 <code>channel_type</code>，OpenClaw 会按 channel id 前缀（<code>D</code>/<code>C</code>/<code>G</code>）推断，默认 <code>channel</code>，以保证会话键稳定。

- 原生命令注册：全局 <code>commands.native</code> 默认 <code>"auto"</code>（Slack 默认关闭），可用 <code>channels.slack.commands.native</code> 覆盖。文本命令需要单独 <code>/...</code> 消息，可用 <code>commands.text: false</code> 关闭。Slack slash commands 由 Slack App 管理，不会被自动移除。<code>commands.useAccessGroups: false</code> 可绕过 access-group 检查。

- 命令列表与配置：'<a href="/tools/slash-commands">'/tools/slash-commands'</a>'

Tutorial.step

私信安全（pairing）

- 默认：<code>channels.slack.dm.policy="pairing"</code>（未知发送者会收到配对码，1 小时过期）。

- 批准：'<code>'openclaw pairing approve slack '<code>''</code>'。

- 若允许任何人私信：<code>channels.slack.dm.policy="open"</code> 且 <code>channels.slack.dm.allowFrom=["*"]</code>。

- <code>channels.slack.dm.allowFrom</code> 支持 user id、@handle 或 email（在 tokens 允许时启动时解析）。向导会在可能时把 username 解析为 id。

Tutorial.step

群策略（Group policy）

- <code>channels.slack.groupPolicy</code> 控制频道处理：<code>open|disabled|allowlist</code>。

- <code>allowlist</code> 要求在 <code>channels.slack.channels</code> 里列出允许的频道。

- 如果你只设置了 <code>SLACK_BOT_TOKEN</code>/<code>SLACK_APP_TOKEN</code>，却从未创建 <code>channels.slack</code> 配置段，运行时默认 <code>groupPolicy</code> 为 <code>open</code>。一旦你显式配置 <code>channels.slack.groupPolicy</code>/<code>channels.defaults.groupPolicy</code> 或频道 allowlist，就会被收紧。