Slack

连接 Slack。使用应用 Token 与工作区设置。

Socket 模式（默认）

快速设置（入门）

创建 Slack 应用并启用 Socket Mode。
创建 应用 Token（xapp-...）和 机器人 Token（xoxb-...）。
为 Moltbot 配置上述 Token 并启动网关。

最小配置：


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

设置步骤

在 https://api.slack.com/apps 创建 Slack 应用（From scratch）。
Socket Mode → 开启。然后进入 Basic Information → App-Level Tokens → Generate Token and Scopes，勾选 scope connections:write。复制 App Token（xapp-...）。
OAuth & Permissions → 添加机器人 Token 所需 scope（见下方 manifest）。点击 Install to Workspace。复制 Bot User OAuth Token（xoxb-...）。
可选：OAuth & Permissions → 添加 User Token Scopes（见下方只读列表）。重新安装应用并复制 User OAuth Token（xoxp-...）。
Event Subscriptions → 启用事件并订阅：
- message.*（含编辑/删除/线程广播）
- app_mention
- reaction_added、reaction_removed
- member_joined_channel、member_left_channel
- channel_rename
- pin_added、pin_removed
将机器人邀请到需要读取的频道。
Slash Commands → 若使用 channels.slack.slashCommand，创建 /clawd。若启用原生命令，为每个内置命令各添加一个斜杠命令（名称与 /help 列表一致）。Slack 下原生命令默认关闭，除非设置 channels.slack.commands.native: true（全局 commands.native 为 "auto" 时 Slack 保持关闭）。
App Home → 启用 Messages Tab，以便用户可私信机器人。

使用下方 manifest 保持 scope 与事件一致。多账号：使用 channels.slack.accounts，每账号单独 Token 并可设 name。共享模式见配置。

Moltbot 配置（最小）

推荐通过环境变量设置 Token：

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

或通过配置：


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

用户 Token（可选）

Moltbot 可使用 Slack 用户 Token（xoxp-...）进行只读操作（历史、置顶、表态、表情、成员信息）。默认保持只读：有用户 Token 时读操作优先使用它，写操作仍使用机器人 Token，除非你显式放开。即使设置 userTokenReadOnly: false，在有机器人 Token 时写操作仍优先用机器人 Token。用户 Token 在配置文件中设置（无环境变量支持）。多账号时设置 channels.slack.accounts.<id>.userToken。

示例（机器人 + 应用 + 用户 Token）：


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

显式允许用户 Token 参与写操作示例：


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

Token 使用规则

读操作（历史、表态列表、置顶列表、表情列表、成员信息、搜索）在配置了用户 Token 时优先使用用户 Token，否则使用机器人 Token。
写操作（发送/编辑/删除消息、添加/移除表态、置顶/取消置顶、文件上传）默认使用机器人 Token。若 userTokenReadOnly: false 且无机器人 Token，Moltbot 会回退到用户 Token。

历史上下文

channels.slack.historyLimit（或 channels.slack.accounts.*.historyLimit）控制最近多少条频道/群组消息被纳入提示上下文。
回退到 messages.groupChat.historyLimit。设 0 可禁用（默认 50）。

HTTP 模式（Events API）

当网关可通过 HTTPS 被 Slack 访问时（常见于服务器部署），使用 HTTP webhook 模式。HTTP 模式使用 Events API + Interactivity + Slash Commands，共用同一请求 URL。

设置

创建 Slack 应用并关闭 Socket Mode（若仅用 HTTP 可忽略）。
Basic Information → 复制 Signing Secret。
OAuth & Permissions → 安装应用并复制 Bot User OAuth Token（xoxb-...）。
Event Subscriptions → 启用事件，将 Request URL 设为网关 webhook 路径（默认 /slack/events）。
Interactivity & Shortcuts → 启用并设为同一 Request URL。
Slash Commands → 为你的命令设置同一 Request URL。

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

Moltbot 配置（最小）


{
  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。

Manifest（可选）

使用以下 Slack 应用 manifest 可快速创建应用（可按需调整名称/命令）。若计划配置用户 Token，请包含 user scopes。


{
  "display_information": {
    "name": "Moltbot",
    "description": "Slack connector for Moltbot"
  },
  "features": {
    "bot_user": {
      "display_name": "Moltbot",
      "always_online": false
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "slash_commands": [
      {
        "command": "/clawd",
        "description": "Send a message to Moltbot",
        "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 覆盖。

Scope（当前与可选）

Slack Conversations API 按类型限定 scope：只需为你实际使用的会话类型（channels、groups、im、mpim）申请对应 scope。概览见 https://docs.slack.dev/apis/web-api/using-the-conversations-api/ 。

机器人 Token scope（必需）

chat:write（通过 chat.postMessage 发送/更新/删除消息）https://docs.slack.dev/reference/methods/chat.postMessage
im:write（通过 conversations.open 为用户私信打开 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（用户查询）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

用户 Token scope（可选，默认只读）

若配置 channels.slack.userToken，在 User Token Scopes 下添加：

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 Mode（无 HTTP webhook 服务）。需同时提供两个 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": "clawd",
      "sessionPrefix": "slack:slash",
      "ephemeral": true
    },
    "textChunkLimit": 4000,
    "mediaMaxMb": 20
  }
}

Token 也可通过环境变量提供：SLACK_BOT_TOKEN、SLACK_APP_TOKEN。

确认表态由全局 messages.ackReaction 与 messages.ackReactionScope 控制。使用 messages.removeAckAfterReply 在机器人回复后清除确认表态。

限制

出站文本按 channels.slack.textChunkLimit 分块（默认 4000）。
可选按换行分块：设 channels.slack.chunkMode="newline" 在按长度分块前按空行（段落边界）拆分。
媒体上传受 channels.slack.mediaMaxMb 限制（默认 20）。

回复与线程

默认 Moltbot 在频道主时间线回复。使用 channels.slack.replyToMode 控制自动线程行为：

模式	行为
`off`	默认。在频道主时间线回复。仅当触发消息本身在线程中时才进线程回复。
`first`	首次回复进线程（在触发消息下），后续回复在主时间线。便于保留上下文又避免线程堆积。
`all`	所有回复进线程。对话集中但可能降低可见性。

该模式同时作用于自动回复与 agent 工具调用（slack sendMessage）。

按会话类型的线程

可通过 channels.slack.replyToModeByChatType 为不同会话类型设置不同线程行为：


{
  channels: {
    slack: {
      replyToMode: "off",        // 频道默认
      replyToModeByChatType: {
        direct: "all",           // 私信始终进线程
        group: "first"           // 群组 DM/MPIM 首次回复进线程
      },
    }
  }
}

支持的会话类型：direct（1:1 私信，Slack im）、group（群组 DM/MPIM，Slack mpim）、channel（标准公开/私密频道）。

优先级：1）replyToModeByChatType.<chatType> 2）replyToMode 3）提供方默认（off）。

未设置按类型覆盖时，仍接受旧版 channels.slack.dm.replyToMode 作为 direct 的回退。

示例：仅私信进线程：


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

群组 DM 进线程、频道保持主时间线：


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

频道进线程、私信保持主时间线：


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

手动线程标签

精细控制时，在 agent 回复中使用以下标签：

[[reply_to_current]] — 回复触发消息（开始/继续线程）。
[[reply_to:<id>]] — 回复指定消息 id。

会话与路由

私信共享 main 会话（与 WhatsApp/Telegram 类似）。
频道对应会话 agent:<agentId>:slack:channel:<channelId>。
斜杠命令使用会话 agent:<agentId>:slack:slash:<userId>（前缀可由 channels.slack.slashCommand.sessionPrefix 配置）。
若 Slack 未提供 channel_type，Moltbot 根据频道 ID 前缀（D、C、G）推断，并默认 channel 以保持会话键稳定。
原生命令注册使用 commands.native（全局默认 "auto" → Slack 关闭），可按工作区用 channels.slack.commands.native 覆盖。文本命令需独立成一条 /... 消息，可用 commands.text: false 关闭。Slack 斜杠命令在 Slack 应用中管理，不会自动移除。使用 commands.useAccessGroups: false 可跳过命令的访问组检查。
完整命令列表与配置见斜杠命令。

私信安全（配对）

默认：channels.slack.dm.policy="pairing" — 未知私信发件人会收到配对码（1 小时后过期）。
批准：moltbot pairing approve slack <code>。
允许所有人：设 channels.slack.dm.policy="open" 且 channels.slack.dm.allowFrom=["*"]。
channels.slack.dm.allowFrom 接受用户 ID、@ 句柄或邮箱（在 Token 允许时于启动时解析）。配置向导接受用户名，在 Token 允许时于设置阶段解析为 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；若存在多个匹配，优先当前活跃频道。
启动时，Moltbot 在 Token 允许时将白名单中的频道/用户名解析为 ID 并记录映射；无法解析的条目保持原样。
若要禁止所有频道，设 channels.slack.groupPolicy: "disabled"（或保持空白名单）。

频道选项（channels.slack.channels.<id> 或 channels.slack.channels.<name>）：

allow：在 groupPolicy="allowlist" 时允许/拒绝该频道。
requireMention：该频道的 @ 提及门控。
tools：可选按频道工具策略覆盖（allow/deny/alsoAllow）。
toolsBySender：可选按发件人工具策略覆盖（键为发件人 id/@ 句柄/邮箱；支持 "*" 通配符）。
allowBots：是否允许该频道中机器人发出的消息（默认 false）。
users：可选按频道用户白名单。
skills：技能过滤（省略=全部技能，空=无）。
systemPrompt：该频道额外系统提示（与 topic/purpose 合并）。
enabled：设 false 禁用该频道。

投递目标

与 cron/CLI 发送配合使用：

user:<id> 用于私信
channel:<id> 用于频道

工具动作

Slack 工具动作可通过 channels.slack.actions.* 控制：

动作组	默认	说明
reactions	启用	表态、列表态
messages	启用	读/发/编辑/删除消息
pins	启用	置顶/取消置顶/列表
memberInfo	启用	成员信息
emojiList	启用	自定义表情列表

安全说明

写操作默认使用机器人 Token，使有状态操作限定在应用的机器人权限与身份下。
设置 userTokenReadOnly: false 允许在无机器人 Token 时用用户 Token 执行写操作，即操作以安装用户权限执行。请将用户 Token 视为高权限，并收紧动作门控与白名单。
若启用用户 Token 写操作，请确保用户 Token 包含你期望的写 scope（chat:write、reactions:write、pins:write、files:write），否则相关操作会失败。

说明

@ 提及门控通过 channels.slack.channels 控制（将 requireMention 设为 true）；agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）也计为提及。
多 agent 覆盖：在 agents.list[].groupChat.mentionPatterns 上设每 agent 规则。
表态通知遵循 channels.slack.reactionNotifications（在模式 allowlist 时配合 reactionAllowlist）。
机器人发出的消息默认被忽略；通过 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 工具的表态移除语义见表态。
附件在允许且未超大小限制时会下载到媒体存储。