Slack

本指南将指导您如何通过 Socket Mode 将 Hermes Agent 部署为 Slack 机器人，实现与 Slack 工作区的实时交互。

📌 前置条件

在开始之前，请确保您已完成以下准备工作：

拥有一个 Slack 工作区。
已创建一个 Slack 应用（建议使用“Bot”类型）。
已启用 Socket Mode（在应用设置中）。
已获取以下凭证：
- SLACK_APP_TOKEN（来自 Socket Mode 设置）
- SLACK_BOT_TOKEN（用于 Bot 用户身份验证）
安装并配置好 Hermes Agent 环境。

🔧 步骤 1：配置 Slack 应用

登录 Slack API Dashboard。
选择您的应用，进入「Features」>「Socket Mode」。
启用 Socket Mode。
复制生成的 App Token（格式为 xapp-...），保存至环境变量或 .env 文件中。

⚠️ 注意：App Token 仅用于建立 WebSocket 连接，不用于执行 API 调用。实际操作需使用 Bot Token。

🛠 步骤 2：配置 Hermes Agent

2.1 创建 `.env` 文件

在 Hermes Agent 项目根目录下创建 .env 文件，填入以下内容：

# Slack 相关配置
SLACK_APP_TOKEN= xapp-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SLACK_BOT_TOKEN= xoxb-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 可选：自定义机器人名称
HERMES_AGENT_NAME=hermes-bot

# 可选：启用调试日志
DEBUG=true

✅ 提示：请勿将 .env 文件提交到 Git，建议添加到 .gitignore。

2.2 修改启动脚本

确保您的启动命令包含 Socket Mode 支持。以 npm 为例：

npm run start -- --mode socket

或在 package.json 中添加脚本：

"scripts": {
  "start:socket": "node dist/index.js --mode socket"
}

然后运行：

npm run start:socket

🔄 步骤 3：部署与连接

启动 Hermes Agent 服务。
在 Slack 工作区中，安装该应用（点击「Add to Slack」）。
机器人将自动连接至 Slack 的 Socket Mode 通道。
您可以在任意频道中 @bot 名称触发指令，例如：
```
@hermes-bot 你好
```
查看控制台输出，确认连接状态和事件处理日志。

📊 功能示例

Hermes Agent 支持以下典型交互：

操作	示例
回复消息	`@hermes-bot 今天天气怎么样？` → 返回天气信息
执行任务	`@hermes-bot 生成一份周报` → 自动生成文档
查询知识库	`@hermes-bot 解释什么是 Socket Mode？`

💡 提示：可结合 OpenAI、OpenRouter 或本地模型（如 Llama 3）增强智能能力。

🛡 安全建议

仅在受信任网络中运行 Socket Mode 服务。
使用 HTTPS 保护 WebSocket 连接（若部署于公网）。
定期轮换 App Token 和 Bot Token。
限制 Bot 权限，仅授予必要作用域（如 chat:write, channels:read）。

📚 参考资料

✅ 成功！现在您已成功将 Hermes Agent 配置为 Slack 机器人，支持实时通信与智能响应。

如需进一步集成，可参考 agentskills.io 上的技能模板或自定义 MCP 插件。"

Slack 设置

通过 Socket Mode 将 Hermes Agent 连接到 Slack 作为机器人。Socket Mode 使用 WebSocket 而非公开的 HTTP 端点，因此您的 Hermes 实例无需对外公开 —— 它可以在防火墙后、您的笔记本电脑上或私有服务器上正常运行。

经典 Slack 应用已弃用

经典 Slack 应用（使用 RTM API）已于 2025 年 3 月完全弃用。Hermes 使用现代 Bolt SDK 和 Socket Mode。如果您拥有旧版经典应用，请按照以下步骤创建新应用。

概览

组件	值
库	`slack-bolt` / `slack_sdk`（Python，Socket Mode）
连接方式	WebSocket —— 不需要公网 URL
所需认证令牌	Bot Token (`xoxb-`) + App-Level Token (`xapp-`)
用户识别方式	Slack 成员 ID（例如 `U01ABC2DEF3`）

第一步：创建 Slack 应用

访问 https://api.slack.com/apps
点击 创建新应用
选择 从头开始
输入应用名称（例如 "Hermes Agent"），并选择您的工作区
点击 创建应用

您将进入应用的 基本信息 页面。

第二步：配置 Bot Token 权限范围

在侧边栏中导航至 功能 → OAuth 与权限。滚动到 权限 → Bot Token 权限范围，添加以下内容：

权限范围	用途
`chat:write`	以机器人身份发送消息
`app_mentions:read`	检测是否在频道中被 @ 提及
`channels:history`	读取机器人所在公共频道中的消息
`channels:read`	列出并获取公共频道信息
`groups:history`	读取机器人受邀加入的私有频道中的消息
`im:history`	读取直接消息历史记录
`im:read`	查看基本的 DM 信息
`im:write`	打开和管理 DM
`users:read`	查找用户信息
`files:write`	上传文件（图片、音频、文档）

缺失权限 = 功能缺失

缺少 channels:history 和 groups:history，机器人将 无法接收频道中的消息 —— 仅能在私聊中工作。这是最常见的遗漏项。

可选权限：

权限范围	用途
`groups:read`	列出并获取私有频道信息

第三步：启用 Socket Mode

Socket Mode 允许机器人通过 WebSocket 连接，而无需公网 URL。

在侧边栏中，进入 设置 → Socket Mode
将 启用 Socket Mode 开关设为开启
系统会提示您创建一个 App-Level Token：
- 命名为类似 hermes-socket（名称无关紧要）
- 添加 connections:write 权限范围
- 点击生成
复制该令牌 —— 它以 xapp- 开头。这就是您的 SLACK_APP_TOKEN

tip

您可在 设置 → 基本信息 → App-Level Tokens 下随时查找或重新生成应用级令牌。

第四步：订阅事件

此步骤至关重要 —— 它决定了机器人能看到哪些消息。

在侧边栏中，进入 功能 → 事件订阅
将 启用事件 开关设为开启
展开 订阅机器人事件 并添加：

事件	是否必需	用途
`message.im`	是	机器人接收私聊消息
`message.channels`	是	机器人接收其被加入的公共频道中的消息
`message.groups`	推荐	机器人接收其被邀请加入的私有频道中的消息
`app_mention`	是	防止当机器人被 @ 提及时出现 Bolt SDK 错误

点击页面底部的 保存更改

未订阅事件是设置失败的首要原因

如果机器人在私聊中可以工作，但在 频道中无法响应，几乎可以肯定是忘记了添加 message.channels（用于公共频道）和/或 message.groups（用于私有频道）。没有这些事件，Slack 根本不会将频道消息传递给机器人。

第五步：启用消息标签页

此步骤允许用户直接向机器人发送消息。若不启用，用户尝试私聊时会看到 “向此应用发送消息已被关闭” 的提示。

在侧边栏中，进入 功能 → 应用主页
向下滚动至 显示标签页
将 消息标签页 开关设为开启
勾选 “允许用户通过消息标签页发送 Slash 命令和消息”

若跳过此步骤，私聊将完全被阻止

即使所有权限和事件订阅都正确，Slack 也不会允许用户向机器人发送私聊消息，除非启用了消息标签页。这是 Slack 平台的要求，而非 Hermes 的配置问题。

第六步：将应用安装到工作区

在侧边栏中，进入 设置 → 安装应用
点击 安装到工作区
查看权限并点击允许
授权完成后，您将看到一个以 xoxb- 开头的 Bot 用户 OAuth 令牌
复制该令牌 —— 这就是您的 SLACK_BOT_TOKEN

tip

如果您后续更改了权限范围或事件订阅，必须重新安装应用 才能使更改生效。安装页面会显示提示 banner，提醒您执行此操作。

第七步：获取允许列表中的用户 ID

Hermes 使用 Slack 成员 ID（而非用户名或显示名）进行允许列表配置。

要查找成员 ID：

在 Slack 中点击用户的姓名或头像
点击 查看完整资料
点击 ⋮（更多）按钮
选择 复制成员 ID

成员 ID 格式如 U01ABC2DEF3。至少需要包含您自己的成员 ID。

第八步：配置 Hermes

将以下内容添加到您的 ~/.hermes/.env 文件中：

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Comma-separated Member IDs

# Optional
SLACK_HOME_CHANNEL=C01234567890              # Default channel for cron/scheduled messages
SLACK_HOME_CHANNEL_NAME=general              # Human-readable name for the home channel (optional)

或运行交互式设置：

hermes gateway setup    # Select Slack when prompted

然后启动网关：

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

第九步：将机器人邀请至频道

启动网关后，您需要 手动将机器人邀请至 您希望它响应的每个频道：

/invite @Hermes Agent

机器人 不会自动加入频道。您必须为每个频道单独邀请它。

机器人响应机制

了解 Hermes 在不同场景下的行为：

场景	行为
私聊	机器人对每条消息作出回应 —— 无需 @ 提及
频道	机器人仅在被 @ 提及时才回应（例如 `@Hermes Agent what time is it?`）。在频道中，Hermes 会在该消息的线程中回复。
线程	如果您在已有线程中 @ 提及 Hermes，它将在同一线程中回复。一旦机器人在某个线程中建立会话，后续在该线程中的回复无需再次 @ 提及 —— 机器人会自然延续对话。

tip

在频道中，始终需 @ 提及机器人以开启对话。一旦机器人在某线程中活跃，您可在该线程内继续回复而无需提及。在非线程环境中，无 @ 提及的消息将被忽略，以避免在繁忙频道中产生噪音。

配置选项

除了第 8 步所需的环境变量外，您还可以通过 ~/.hermes/config.yaml 自定义 Slack 机器人的行为。

线程与回复行为

platforms:
  slack:
    # Controls how multi-part responses are threaded
    # "off"   — never thread replies to the original message
    # "first" — first chunk threads to user's message (default)
    # "all"   — all chunks thread to user's message
    reply_to_mode: "first"

    extra:
      # Whether to reply in a thread (default: true).
      # When false, channel messages get direct channel replies instead
      # of threads. Messages inside existing threads still reply in-thread.
      reply_in_thread: true

      # Also post thread replies to the main channel
      # (Slack's "Also send to channel" feature).
      # Only the first chunk of the first reply is broadcast.
      reply_broadcast: false

键	默认值	描述
`platforms.slack.reply_to_mode`	`"first"`	多部分消息的线程模式：`"off"`、`"first"` 或 `"all"`
`platforms.slack.extra.reply_in_thread`	`true`	当 `false` 为真时，频道消息将直接回复而非创建线程。已在现有线程内的消息仍会在线程中回复。
`platforms.slack.extra.reply_broadcast`	`false`	当 `true` 为真时，线程回复也会广播到主频道。仅第一个片段会被广播。

会话隔离

# Global setting — applies to Slack and all other platforms
group_sessions_per_user: true

当 true（默认值）时，共享频道中的每位用户都将拥有自己独立的对话会话。两人在 #general 中与 Hermes 对话时，将各自拥有独立的历史记录和上下文。设置为 false 以启用协作模式，此时整个频道共享一个对话会话。请注意，这会导致用户之间共享上下文和 token 成本，且任意用户的 /reset 都将清除所有人的会话。

提及与触发行为

slack:
  # Require @mention in channels (this is the default behavior;
  # the Slack adapter enforces @mention gating in channels regardless,
  # but you can set this explicitly for consistency with other platforms)
  require_mention: true

  # Custom mention patterns that trigger the bot
  # (in addition to the default @mention detection)
  mention_patterns:
    - "hey hermes"
    - "hermes,"

  # Text prepended to every outgoing message
  reply_prefix: ""

info

与 Discord 和 Telegram 不同，Slack 没有对应的 free_response_channels 功能。Slack 适配器要求使用 @mention 来在频道中启动对话。但一旦机器人在某个线程中建立了活跃会话，后续的线程回复则无需再次提及。在私信（DM）中，机器人始终会响应，无需提及。

未授权用户处理

slack:
  # What happens when an unauthorized user (not in SLACK_ALLOWED_USERS) DMs the bot
  # "pair"   — prompt them for a pairing code (default)
  # "ignore" — silently drop the message
  unauthorized_dm_behavior: "pair"

你也可以全局设置适用于所有平台：

unauthorized_dm_behavior: "pair"

平台特定设置（位于 slack: 下）优先于全局设置。

语音转录

# Global setting — enable/disable automatic transcription of incoming voice messages
stt_enabled: true

当 true（默认值）时，系统会自动使用配置的语音转文字（STT）服务对传入的音频消息进行转录，然后再交由代理处理。

完整示例

# Global gateway settings
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Slack-specific settings
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# Platform config
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

主频道（Home Channel）

将 SLACK_HOME_CHANNEL 设置为 Hermes 将发送定时消息、cron 任务结果及其他主动通知的频道 ID。要查找频道 ID：

在 Slack 中右键点击频道名称
选择 查看频道详情
向下滚动 —— 频道 ID 会显示在底部

SLACK_HOME_CHANNEL=C01234567890

确保机器人已被 邀请加入该频道（/invite @Hermes Agent）。

多工作区支持

Hermes 可通过单个网关实例同时连接 多个 Slack 工作区。每个工作区均独立认证，拥有自己的机器人用户 ID。

配置

在 SLACK_BOT_TOKEN 中提供多个机器人令牌，以 逗号分隔 的形式列出：

# Multiple bot tokens — one per workspace
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

# A single app-level token is still used for Socket Mode
SLACK_APP_TOKEN=xapp-your-app-token

或在 ~/.hermes/config.yaml 中配置：

platforms:
  slack:
    token: "xoxb-workspace1-token,xoxb-workspace2-token"

OAuth 令牌文件

除了环境变量或配置文件中的令牌外，Hermes 还会从以下位置加载 OAuth 令牌文件：

~/.hermes/slack_tokens.json

该文件是一个 JSON 对象，将团队 ID 映射到令牌条目：

{
  "T01ABC2DEF3": {
    "token": "xoxb-workspace-token-here",
    "team_name": "My Workspace"
  }
}

此文件中的令牌将与通过 SLACK_BOT_TOKEN 指定的令牌合并，重复项会自动去重。

工作原理

列表中的 第一个令牌 为主令牌，用于 Socket Mode 连接（AsyncApp）。
启动时，每个令牌通过 auth.test 进行认证。网关将每个 team_id 映射到其独立的 WebClient 和 bot_user_id。
当消息到达时，Hermes 使用对应工作区的客户端进行响应。
主 bot_user_id（来自首个令牌）用于向后兼容那些期望单一机器人身份的功能。

语音消息

Hermes 支持 Slack 上的语音功能：

接收端：语音/音频消息会自动通过配置的 STT 服务转录：本地 faster-whisper、Groq Whisper（GROQ_API_KEY）或 OpenAI Whisper（VOICE_TOOLS_OPENAI_KEY）
发送端：TTS 响应将以音频文件附件形式发送

故障排除

问题	解决方案
机器人在私信中不响应	确保 `message.im` 已添加至事件订阅，并重新安装应用
机器人在私信中正常，但在频道中无效	最常见的问题。添加 `message.channels` 和 `message.groups` 到事件订阅，重新安装应用，并用 `/invite @Hermes Agent` 将机器人邀请至频道
机器人不响应频道中的 @提及	1) 检查是否订阅了 `message.channels` 事件；2) 机器人必须被邀请至频道；3) 确保已添加 `channels:history` 权限范围；4) 在更改权限或事件后重新安装应用
机器人忽略私有频道中的消息	添加 `message.groups` 事件订阅和 `groups:history` 权限范围，然后重新安装应用并 `/invite` 机器人
私信中提示“向此应用发送消息已被关闭”	在应用主页设置中启用消息标签页（参见第 5 步）
出现 “not_authed” 或 “invalid_auth” 错误	重新生成 Bot Token 和 App Token，更新 `.env`
机器人能响应但无法在频道中发消息	使用 `/invite @Hermes Agent` 将机器人邀请至频道
出现 “missing_scope” 错误	在 OAuth & 权限中添加所需权限范围，然后重新安装应用
Socket 频繁断开	检查网络状况；Bolt 会自动重连，但不稳定连接会导致延迟
更改权限或事件后无变化	必须在更改权限或事件订阅后重新安装应用

快速检查清单

若机器人在频道中无法工作，请确认全部以下事项均已满足：

✅ 已订阅 message.channels 事件（公共频道）
✅ 已订阅 message.groups 事件（私有频道）
✅ 已订阅 app_mention 事件
✅ 已添加 channels:history 权限范围（公共频道）
✅ 已添加 groups:history 权限范围（私有频道）
✅ 在添加权限/事件后已重新安装应用
✅ 机器人已加入频道（/invite @Hermes Agent）
✅ 你的消息中已正确 @提及机器人

安全性

warning

始终设置 SLACK_ALLOWED_USERS，并填入授权用户的身份 ID。若未设置此选项，网关将默认 拒绝所有消息，作为安全措施。切勿共享你的机器人令牌——请将其视为密码对待。

令牌应存储在 ~/.hermes/.env（文件权限设为 600）
定期通过 Slack 应用设置轮换令牌
审计谁有权访问你的 Hermes 配置目录
使用 Socket Mode 时不会暴露公网端点 —— 减少一个攻击面

📌 前置条件​

🔧 步骤 1：配置 Slack 应用​

🛠 步骤 2：配置 Hermes Agent​

2.1 创建 .env 文件​

2.2 修改启动脚本​

🔄 步骤 3：部署与连接​

📊 功能示例​

🛡 安全建议​

📚 参考资料​

如需进一步集成，可参考 agentskills.io 上的技能模板或自定义 MCP 插件。"​

Slack 设置

概览​

第一步：创建 Slack 应用​

第二步：配置 Bot Token 权限范围​

第三步：启用 Socket Mode​

第四步：订阅事件​

第五步：启用消息标签页​

第六步：将应用安装到工作区​

第七步：获取允许列表中的用户 ID​

第八步：配置 Hermes​

第九步：将机器人邀请至频道​

机器人响应机制​

配置选项​

线程与回复行为​

会话隔离​

提及与触发行为​

未授权用户处理​

语音转录​

完整示例​

主频道（Home Channel）​

多工作区支持​

配置​

OAuth 令牌文件​

工作原理​

语音消息​

故障排除​

快速检查清单​

安全性​