Skip to content

slack.md

Latest commit

 

History

History
471 lines (414 loc) · 18.2 KB

slack.md

File metadata and controls

471 lines (414 loc) · 18.2 KB
Raw
summary Slack socket 模式或 HTTP webhook 模式的设置
read_when 设置 Slack 或调试 Slack socket/HTTP 模式

Slack

Socket 模式(默认)

快速设置(初学者)

  1. 创建一个 Slack 应用并启用 Socket Mode。
  2. 创建一个 App Token(xapp-...)和 Bot Token(xoxb-...)。
  3. 为 Moltbot 设置令牌并启动网关。

最小配置:

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

设置

  1. 在 https://api.slack.com/apps 中创建一个 Slack 应用(从零开始)。
  2. Socket Mode → 切换开启。然后转到 Basic Information → App-Level Tokens → Generate Token and Scopes，范围为 connections:write。复制 App Token(xapp-...)。
  3. OAuth & Permissions → 添加 bot 令牌范围(使用下面的清单)。点击 Install to Workspace。复制 Bot User OAuth Token(xoxb-...)。
  4. 可选: OAuth & Permissions → 添加 User Token Scopes(参见下面的只读列表)。重新安装应用并复制 User OAuth Token(xoxp-...)。
  5. Event Subscriptions → 启用事件并订阅:
    • message.*(包括编辑/删除/线程广播)
    • app_mention
    • reaction_added、reaction_removed
    • member_joined_channel、member_left_channel
    • channel_rename
    • pin_added、pin_removed
  6. 邀请 bot 到您希望它阅读的频道。
  7. Slash Commands → 如果您使用 channels.slack.slashCommand，创建 /clawd。如果您启用原生命令，为每个内置命令添加一个斜杠命令(与 /help 同名)。除非您设置 channels.slack.commands.native: true(全局 commands.native 是 "auto"，这意味着 Slack 关闭)，否则 Slack 的原生默认为关闭。
  8. App Home → 启用 Messages Tab，以便用户可以向 bot 发送私信。

使用下面的清单，以便范围和事件保持同步。

多账户支持: 使用 channels.slack.accounts 和每账户令牌以及可选的 name。参见 gateway/configuration获取共享模式。

Moltbot 配置(最小)

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

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

或通过配置:

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

用户令牌(可选)

Moltbot 可以使用 Slack 用户令牌(xoxp-...)进行读操作(历史记录、固定、表情回应、emoji、成员信息)。默认情况下，这保持只读: 当存在用户令牌时，读取优先使用用户令牌，写入仍使用 bot 令牌，除非您明确选择加入。即使使用 userTokenReadOnly: false，当 bot 令牌可用时，写入仍优先使用 bot 令牌。

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

包含 bot + app + user 令牌的示例:

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

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

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

令牌使用

  • 读操作(历史记录、表情回应列表、固定列表、emoji 列表、成员信息、搜索)在配置时优先使用用户令牌，否则使用 bot 令牌。
  • 写操作(发送/编辑/删除消息、添加/删除表情回应、固定/取消固定、文件上传)默认使用 bot 令牌。如果 userTokenReadOnly: false 且没有可用的 bot 令牌，Moltbot 回退到用户令牌。

历史记录上下文

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

设置

  1. 创建一个 Slack 应用并禁用 Socket Mode(如果您只使用 HTTP，则可选)。
  2. Basic Information → 复制 Signing Secret。
  3. OAuth & Permissions → 安装应用并复制 Bot User OAuth Token(xoxb-...)。
  4. Event Subscriptions → 启用事件并将 Request URL 设置为您的网关 webhook 路径(默认 /slack/events)。
  5. Interactivity & Shortcuts → 启用并将相同的 Request URL 设置为。
  6. 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。

清单(可选)

使用此 Slack 应用清单快速创建应用(如果您愿意，可以调整名称/命令)。如果您计划配置用户令牌，请包括用户范围。

{
  "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 覆盖。

范围(当前 vs 可选)

Slack 的 Conversations API 是类型范围的: 您只需要实际接触的对话类型的范围(channels、groups、im、mpim)。参见 https://docs.slack.dev/apis/web-api/using-the-conversations-api/ 了解概述。

Bot 令牌范围(必需)

用户令牌范围(可选，默认只读)

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

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

配置

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

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

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

  • SLACK_BOT_TOKEN
  • SLACK_APP_TOKEN

确认表情回应通过 messages.ackReaction + messages.ackReactionScope 全局控制。使用 messages.removeAckAfterReply 在 bot 回复后清除确认表情回应。

限制

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

回复线程

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

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

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

按聊天类型的线程

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

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

支持的聊天类型:

  • direct: 1:1 私信(Slack im)
  • group: 群组私信 / MPIMs(Slack mpim)
  • channel: 标准频道(公共/私人)

优先级:

  1. replyToModeByChatType.<chatType>
  2. replyToMode
  3. 提供程序默认值(off)

旧版 channels.slack.dm.replyToMode 在没有设置聊天类型覆盖时仍被接受为 direct 的回退。

示例:

仅线程私信:

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

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

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

使频道线程，保持私信在根目录:

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

手动线程标签

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

  • [[reply_to_current]] — 回复触发消息(启动/继续线程)。
  • [[reply_to:<id>]] — 回复特定的消息 id。

会话 + 路由

  • 私信共享 main 会话(类似 WhatsApp/Telegram)。
  • 频道映射到 agent:<agentId>:slack:channel:<channelId> 会话。
  • Slash 命令使用 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、@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(公共 + 私人)；如果存在多个匹配，它倾向于活动频道。
  • 启动时，Moltbot 将允许列表中的频道/用户名称解析为 ID(当令牌允许时)并记录映射；未解析的条目保持输入状态。
  • 要允许无频道，设置 channels.slack.groupPolicy: "disabled"(或保持空允许列表)。

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

  • allow: 当 groupPolicy="allowlist" 时允许/拒绝频道。
  • requireMention: 频道的提及限制。
  • tools: 可选的每频道工具策略覆盖(allow/deny/alsoAllow)。
  • toolsBySender: 频道内可选的每发送者工具策略覆盖(键是发送者 id/@handles/emails；支持 "*" 通配符)。
  • allowBots: 在此频道中允许 bot 撰写的消息(默认: false)。
  • users: 可选的每频道用户允许列表。
  • skills: 技能过滤器(省略 = 所有技能，空 = 无)。
  • systemPrompt: 频道的额外系统提示(与主题/目的结合)。
  • enabled: 设置 false 禁用频道。

传递目标

将这些与 cron/CLI 发送一起使用:

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

工具操作

Slack 工具操作可以通过 channels.slack.actions.* 限制:

操作组 默认 注意
reactions 启用 表情回应 + 列出表情回应
messages 启用 读/发送/编辑/删除
pins 启用 固定/取消固定/列出
memberInfo 启用 成员信息
emojiList 启用 自定义 emoji 列表

安全说明

  • 写入默认为 bot 令牌，因此状态更改操作保持在应用的 bot 权限和身份范围内。
  • 设置 userTokenReadOnly: false 允许在 bot 令牌不可用时使用用户令牌进行写操作，这意味着操作使用安装用户的访问权限。将用户令牌视为高度特权，并保持操作门和允许列表紧密。
  • 如果您启用用户令牌写入，请确保用户令牌包含您期望的写入范围(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(对 allowlist 模式使用 reactionAllowlist)。
  • Bot 撰写的消息默认被忽略；通过 channels.slack.allowBots 或 channels.slack.channels.<id>.allowBots 启用。
  • 警告: 如果您允许对其他 bot 的回复(channels.slack.allowBots=true 或 channels.slack.channels.<id>.allowBots=true)，使用 requireMention、channels.slack.channels.<id>.users 允许列表和/或在 AGENTS.md 和 SOUL.md 中设置明确的防护措施来防止 bot 到 bot 的回复循环。
  • 对于 Slack 工具，表情回应删除语义在 /tools/reactions中。
  • 附件在被允许且在大小限制内时下载到媒体存储。