8.6 Slack集成

通讯渠道通讯渠道

通过 Slack Bolt SDK 将 OpenClaw 集成到您的工作区，支持 Socket Mode 和 HTTP 模式。

概述

Slack 集成是内置功能，使用官方 Bolt SDK 实现。支持直接消息、频道交互、线程回复、表情反应等丰富功能，并提供灵活的权限控制和工具操作能力。

状态

内置支持，生产环境可用。

连接模式

Socket Mode（推荐用于开发）

无需公网 URL，适合本地开发和测试：

  • ✅ 无需配置 webhook 端点
  • ✅ 无需 HTTPS 证书
  • ✅ 适合防火墙后的环境
  • ⚠️ 需要 App-Level Token

HTTP Mode（推荐用于生产）

使用 Events API webhook 接收事件：

  • ✅ 更高性能和可靠性
  • ✅ 适合生产环境部署
  • ⚠️ 需要公网可访问的 HTTPS 端点

前置要求

  • 一个 Slack 工作区（你需要有安装应用的权限）
  • 创建 Slack App（api.slack.com/apps）

创建 Slack App

1. 创建新应用

访问 Slack API 管理页面，点击 "Create New App"，选择 "From scratch"。

2. 配置 OAuth 权限（Bot Token Scopes）

在 "OAuth & Permissions" 页面添加以下必需的权限范围：

# 必需的 Bot Token Scopes
chat:write              # 发送消息
channels:history        # 读取公开频道历史
channels:read           # 查看频道信息
groups:history          # 读取私有频道历史
groups:read             # 查看私有频道信息
im:history              # 读取直接消息历史
im:read                 # 查看直接消息信息
mpim:history            # 读取群组直接消息历史
mpim:read               # 查看群组直接消息信息
users:read              # 查看用户信息
reactions:read          # 查看表情反应
reactions:write         # 添加表情反应
files:read              # 读取文件
files:write             # 上传文件

3a. Socket Mode 配置

如果使用 Socket Mode：

  1. 在 "Socket Mode" 页面启用 Socket Mode
  2. 生成 App-Level Token（需要 connections:write 权限）
  3. 在 "Event Subscriptions" 启用事件并订阅以下事件：
# Bot Events
message.channels        # 频道消息
message.groups          # 私有频道消息
message.im              # 直接消息
message.mpim            # 群组直接消息
app_mention             # @提及
reaction_added          # 添加表情
reaction_removed        # 移除表情

3b. HTTP Mode 配置

如果使用 HTTP Mode：

  1. 在 "Event Subscriptions" 启用事件
  2. 设置 Request URL：https://your-domain.com/slack/events
  3. 订阅与 Socket Mode 相同的 Bot Events
  4. 记录 "Signing Secret"（在 "Basic Information" 页面）

4. 安装应用到工作区

在 "OAuth & Permissions" 页面点击 "Install to Workspace"，授权后获取：

  • Bot User OAuth Token（xoxb-...）：机器人令牌
  • App-Level Token（xapp-...，Socket Mode）：应用级令牌

OpenClaw 配置

Socket Mode 配置（默认）

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",  // 默认值
      appToken: process.env.SLACK_APP_TOKEN,   // xapp-...
      botToken: process.env.SLACK_BOT_TOKEN    // xoxb-...
    }
  }
}

设置环境变量：

export SLACK_APP_TOKEN="xapp-..."
export SLACK_BOT_TOKEN="xoxb-..."

HTTP Mode 配置

{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: process.env.SLACK_BOT_TOKEN,
      signingSecret: process.env.SLACK_SIGNING_SECRET,
      webhook: {
        path: "/slack/events",  // 默认路径
        port: 3000              // OpenClaw 网关端口
      }
    }
  }
}

设置环境变量：

export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_SIGNING_SECRET="your-signing-secret"

访问控制

直接消息策略

控制谁可以通过 DM 与机器人交互：

{
  channels: {
    slack: {
      enabled: true,
      botToken: process.env.SLACK_BOT_TOKEN,
      dmPolicy: "pairing",  // 默认值
      pairingCodeTTL: 3600  // 配对码有效期（秒），默认1小时
    }
  }
}

dmPolicy 选项：

  • "pairing"（推荐）：用户需要使用配对码激活
  • "allowlist"：仅允许指定用户
  • "open"：接受所有直接消息
  • "disabled"：禁用直接消息

允许列表配置

{
  channels: {
    slack: {
      enabled: true,
      botToken: process.env.SLACK_BOT_TOKEN,
      dmPolicy: "allowlist",
      allowFrom: [
        "U01ABC123",     // 用户 ID
        "@username",     // 用户名
        "user@email.com" // 邮箱
      ]
    }
  }
}

频道和群组策略

{
  channels: {
    slack: {
      enabled: true,
      botToken: process.env.SLACK_BOT_TOKEN,
      groupPolicy: "allowlist",  // 默认为 "open"
      channels: {
        "C01ABC123": { allow: true },      // 频道 ID
        "engineering": { allow: true },    // 频道名
        "random": { allow: false }         // 明确拒绝
      }
    }
  }
}

线程回复控制

控制机器人如何在线程中回复：

{
  channels: {
    slack: {
      enabled: true,
      botToken: process.env.SLACK_BOT_TOKEN,
      replyToMode: "first",  // "off" | "first" | "all"
      replyToModeByChatType: {
        direct: "off",     // DM 不使用线程
        group: "first",    // 群组：仅回复第一条
        channel: "all"     // 频道：所有消息都使用线程
      }
    }
  }
}

replyToMode 选项：

  • "off"：不使用线程，始终在主频道回复
  • "first"：如果消息在线程中，回复到该线程
  • "all"：始终在线程中回复

工具操作权限

细粒度控制机器人可以执行的操作：

{
  channels: {
    slack: {
      enabled: true,
      botToken: process.env.SLACK_BOT_TOKEN,
      toolActions: {
        reactions: true,      // 允许添加表情反应
        messages: true,       // 允许读取消息
        pins: false,          // 禁止置顶消息
        files: true,          // 允许文件操作
        channelsByName: {
          "sensitive-channel": {
            reactions: false,  // 特定频道禁用反应
            messages: false
          }
        }
      }
    }
  }
}

用户令牌（高级功能）

某些操作需要用户令牌（xoxp-...）：

{
  channels: {
    slack: {
      enabled: true,
      botToken: process.env.SLACK_BOT_TOKEN,
      userToken: process.env.SLACK_USER_TOKEN,     // xoxp-...
      userTokenReadOnly: false  // 允许写操作，默认为 true
    }
  }
}
注意
用户令牌具有很高的权限，默认设置为只读模式。仅在必要时启用写操作，并妥善保管令牌。

多账号配置

同时连接多个 Slack 工作区：

{
  channels: {
    slack: {
      accounts: {
        company: {
          enabled: true,
          botToken: process.env.SLACK_BOT_TOKEN_COMPANY,
          appToken: process.env.SLACK_APP_TOKEN_COMPANY
        },
        community: {
          enabled: true,
          botToken: process.env.SLACK_BOT_TOKEN_COMMUNITY,
          appToken: process.env.SLACK_APP_TOKEN_COMMUNITY,
          dmPolicy: "open"  // 不同工作区可以有不同配置
        }
      }
    }
  }
}

App Manifest（快速设置）

使用 App Manifest 快速创建配置好的应用：

display_information:
  name: OpenClaw Bot
  description: AI assistant powered by OpenClaw
  background_color: "#2c2d30"

features:
  bot_user:
    display_name: OpenClaw
    always_online: true

oauth_config:
  scopes:
    bot:
      - chat:write
      - channels:history
      - channels:read
      - groups:history
      - groups:read
      - im:history
      - im:read
      - mpim:history
      - mpim:read
      - users:read
      - reactions:read
      - reactions:write
      - files:read
      - files:write
      - app_mentions:read

settings:
  event_subscriptions:
    bot_events:
      - message.channels
      - message.groups
      - message.im
      - message.mpim
      - app_mention
      - reaction_added
      - reaction_removed
  socket_mode_enabled: true

配对工作流

当用户首次发送 DM 时（dmPolicy: "pairing"）：

# 1. 用户向机器人发送消息
# 2. 机器人回复配对码（1小时有效）

# 3. 管理员审批配对
openclaw pairing approve slack:U01ABC123

# 或使用配对码
openclaw pairing approve --code ABC123

# 查看待审批列表
openclaw pairing list

# 撤销配对
openclaw pairing revoke slack:U01ABC123

获取用户和频道 ID

用户 ID

  • 右键点击用户头像 → "Copy member ID"
  • 或使用 Slack API：https://api.slack.com/methods/users.list/test

频道 ID

  • 右键点击频道 → "Copy link"，URL 中的 C01ABC123 就是频道 ID
  • 或使用：https://api.slack.com/methods/conversations.list/test

故障排查

Socket Mode 连接失败

  • 确认 App-Level Token 包含 connections:write 权限
  • 检查 Socket Mode 是否已启用
  • 验证令牌格式正确（xapp-...）

HTTP Mode 验证失败

  • 确认 Signing Secret 正确
  • 检查 webhook URL 可公网访问且使用 HTTPS
  • 查看 OpenClaw 日志：openclaw logs --follow

机器人不响应

  • 确认已订阅相应的 Bot Events
  • 检查机器人已被邀请到频道（/invite @bot-name）
  • 验证 Bot Token Scopes 包含所需权限
  • 查看频道策略是否允许该频道

权限不足

  • 重新安装应用以获取新增的权限范围
  • 确认工作区管理员已批准应用
安全最佳实践
  • 生产环境使用 pairing 或 allowlist DM 策略
  • 对敏感频道使用 groupPolicy: "allowlist"
  • 限制工具操作权限到必需范围
  • 定期审查配对用户列表
  • 使用环境变量存储所有令牌，不要硬编码
提示
更多详细信息和高级配置，请访问 官方文档。