Slack

使用 Socket Mode 将 Hermes Agent 作为 bot 接入 Slack。Socket Mode 基于 WebSocket，而不是公网 HTTP 端点，因此你的 Hermes 实例无需暴露在公网，也能在防火墙后、笔记本上或私有服务器中工作。

Classic Slack Apps Deprecated

Classic Slack apps（基于 RTM API）已在 2025 年 3 月完全废弃。Hermes 使用现代的 Bolt SDK 和 Socket Mode。如果你有旧的 classic app，需要按本页步骤重新创建一个新应用。

概览

Component	Value
Library	`slack-bolt` / `slack_sdk` for Python（Socket Mode）
Connection	WebSocket，无需公网 URL
Auth tokens needed	Bot Token（`xoxb-`）+ App-Level Token（`xapp-`）
User identification	Slack Member ID（例如 `U01ABC2DEF3`）

第 1 步：创建 Slack App

打开 https://api.slack.com/apps
点击 Create New App
选择 From scratch
输入应用名称（例如 Hermes Agent）并选择目标 workspace
点击 Create App

第 2 步：配置 Bot Token Scopes

进入 Features → OAuth & Permissions，在 Scopes → Bot Token Scopes 下添加：

Scope	Purpose
`chat:write`	以 bot 身份发消息
`app_mentions:read`	检测频道中的 @mention
`channels:history`	读取 bot 所在公共频道的消息
`channels:read`	列出和读取公共频道信息
`groups:history`	读取 bot 被邀请加入的私有频道消息
`im:history`	读取私聊历史
`im:read`	查看私聊基本信息
`im:write`	打开和管理私聊
`users:read`	查询用户信息
`files:read`	读取并下载附件，包括语音/音频
`files:write`	上传图片、音频和文档

Missing scopes = missing features

如果缺少 channels:history 和 groups:history，bot 将无法在频道中收到消息，通常只会在私聊中工作。这是最常见的遗漏。

可选 scope：

Scope	Purpose
`groups:read`	列出和读取私有频道信息

第 3 步：启用 Socket Mode

打开 Settings → Socket Mode
打开 Enable Socket Mode
创建一个带 connections:write scope 的 App-Level Token
复制以 xapp- 开头的 token，作为 SLACK_APP_TOKEN

提示

你随时都可以在 Settings → Basic Information → App-Level Tokens 中重新查看或重新生成 app-level token。

第 4 步：订阅事件

这一步决定 bot 能看到什么消息，非常关键。

打开 Features → Event Subscriptions
打开 Enable Events
在 Subscribe to bot events 下添加：

Event	Required?	Purpose
`message.im`	Yes	接收私聊消息
`message.channels`	Yes	接收 bot 所在公共频道中的消息
`message.groups`	Recommended	接收 bot 被邀请加入的私有频道消息
`app_mention`	Yes	避免 bot 被 @mention 时 Bolt SDK 报错

点击底部 Save Changes

Missing event subscriptions is the #1 setup issue

如果 bot 在私聊中能工作，但在频道里不工作，几乎可以肯定是漏配了 message.channels（公共频道）和 / 或 message.groups（私有频道）。如果没有这些事件，Slack 根本不会把频道消息投递给 bot。

第 5 步：启用 Messages Tab

如果不做这一步，用户私聊 bot 时会看到 "Sending messages to this app has been turned off"。

打开 Features → App Home
在 Show Tabs 中开启 Messages Tab
勾选 Allow users to send Slash commands and messages from the messages tab

Without this step, DMs are completely blocked

即使 scopes 和 event subscriptions 都配置正确，只要没有启用 Messages Tab，Slack 仍然不允许用户私聊你的 bot。这是 Slack 平台本身的要求，不是 Hermes 的问题。

第 6 步：安装到 Workspace

打开 Settings → Install App
点击 Install to Workspace
确认权限并点击 Allow
完成后会看到以 xoxb- 开头的 Bot User OAuth Token
复制它，作为 SLACK_BOT_TOKEN

提示

如果你后续修改了 scope 或 event subscription，必须重新安装应用，否则改动不会生效。

第 7 步：找到 Allowlist 用的 User ID

Hermes 使用 Slack Member ID（不是用户名，也不是显示名）来做 allowlist。

查找方式：

在 Slack 中点击用户名字或头像
点击 View full profile
点击 ⋮（更多）
选择 Copy member ID

Member ID 看起来像 U01ABC2DEF3。至少要把你自己的 Member ID 加进 allowlist。

第 8 步：配置 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

第 9 步：把 Bot 邀请进频道

启动网关后，你还需要把 bot 邀请进希望它响应的频道：

/invite @Hermes Agent

Slack 不会让 bot 自动加入频道。你必须对每个频道分别邀请它。

Bot 的响应方式

Context	Behavior
DMs	对每条消息都回复，无需 @mention
Channels	只有 @mention 时才会回复，且默认在线程中回复
Threads	如果你在已有 thread 中 @mention Hermes，它会继续在该 thread 中回复；一旦 thread 中已有活跃会话，后续 thread 消息通常无需再次 mention

提示

在频道中，通常应通过 @mention 开始和 Hermes 的对话。等 bot 在该 thread 中活跃起来之后，你就可以直接在线程里继续回复，而无需反复 mention。这样可以避免在繁忙频道中制造噪音。

配置选项

除了第 8 步中的必需环境变量，你还可以在 ~/.hermes/config.yaml 中进一步自定义 Slack 行为。

Thread & Reply Behavior

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

Session Isolation

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

默认情况下，共享频道中的每个用户都有自己的独立会话。若设为 false，整个频道就会共享同一段会话。

Mention & Trigger Behavior

slack:
  require_mention: true
  mention_patterns:
    - "hey hermes"
    - "hermes,"
  reply_prefix: ""

信息

Slack 默认要求通过 @mention 开始对话，但你可以通过 SLACK_FREE_RESPONSE_CHANNELS 或 slack.free_response_channels 把特定频道设为免 mention。只要 bot 已在 thread 中有活跃会话，后续 thread 回复就不再需要 mention。在 DM 中，bot 始终直接响应。

Unauthorized User Handling

slack:
  unauthorized_dm_behavior: "pair"

你也可以全局设置：

unauthorized_dm_behavior: "pair"

Voice Transcription

stt_enabled: true

为 true 时，入站音频会在进入 agent 前自动交给 STT 大模型提供商（provider）转写。

Full Example

# 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 结果和其他通知的频道。获取 channel ID 的方式：

在 Slack 中右键频道名
点击 View channel details
拉到最底部查看 Channel ID

SLACK_HOME_CHANNEL=C01234567890

确保 bot 已经被邀请进该频道（/invite @Hermes Agent）。

Multi-Workspace Support

Hermes 支持使用单个网关实例同时连接多个 Slack workspace。每个 workspace 都用自己的 bot token 独立鉴权。

Configuration

把多个 bot token 以逗号分隔形式写入 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 Token File

除了环境变量和配置文件中的 token 外，Hermes 也会从以下 OAuth token file 中加载 token：

~/.hermes/slack_tokens.json

文件格式如下：

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

这个文件中的 token 会与 SLACK_BOT_TOKEN 中的 token 合并，重复值会自动去重。

How it works

列表中的第一个 token 会作为主 token，用于建立 Socket Mode 连接
每个 token 在启动时都会通过 auth.test 校验，网关会为每个 team_id 建立自己的 WebClient 和 bot_user_id
当消息到来时，Hermes 会使用对应 workspace 的 client 回复
第一个 token 对应的 bot_user_id 会作为默认 bot 身份，兼容仍然只支持单 bot 身份的旧逻辑

Voice Messages

Hermes 支持 Slack 语音：

入站：语音 / 音频消息会自动由配置好的 STT 大模型提供商（provider）转写
出站：TTS 回复会作为音频附件发送

Per-Channel Prompts

你可以为特定 Slack 频道配置临时系统提示。该提示会在每轮运行时注入，但不会写入 transcript 历史，因此修改会立刻生效。

slack:
  channel_prompts:
    "C01RESEARCH": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "C02ENGINEERING": |
      Code review mode. Be precise about edge cases and
      performance implications.

key 是 Slack channel ID。匹配频道中的所有消息都会应用相应的临时系统提示。

Troubleshooting

Problem	Solution
私聊不响应	确认已订阅 `message.im`，并且在修改后重新安装了应用
私聊正常但频道不响应	最常见原因：缺少 `message.channels` / `message.groups`，应用未重新安装，或 bot 没被 `/invite` 进频道
频道中 @mention 后仍不响应	检查 `message.channels`、`channels:history`、bot 是否在该频道里，以及修改后是否重新安装应用
私有频道中不响应	需要同时配置 `message.groups` 和 `groups:history`，并重新安装，再用 `/invite` 邀请 bot
私聊里出现 “Sending messages to this app has been turned off”	在 App Home 中启用 Messages Tab
`not_authed` / `invalid_auth`	重新生成 Bot Token 与 App Token，并更新 `.env`
bot 能回复但无法往某个频道发消息	用 `/invite @Hermes Agent` 把它邀请进频道
`missing_scope`	在 OAuth & Permissions 中补 scope，然后重新安装应用
Socket 频繁断开	检查网络；Bolt 会自动重连，但网络不稳定会导致明显延迟
修改了 scopes / events 但没生效	必须重新安装应用

Quick Checklist

如果 bot 在频道里不工作，请核对以下项是否全部满足：

✅ 已订阅 message.channels（公共频道）
✅ 已订阅 message.groups（私有频道）
✅ 已订阅 app_mention
✅ 已添加 channels:history scope
✅ 已添加 groups:history scope
✅ 修改后已重新安装应用
✅ 已用 /invite @Hermes Agent 把 bot 邀请进频道
✅ 你发消息时确实 @mention 了 bot

Security

注意

务必设置 SLACK_ALLOWED_USERS。否则，出于安全考虑，网关默认会拒绝所有消息。请像对待密码一样保管 Slack token。

token 应保存在 ~/.hermes/.env（建议文件权限为 600）
可在 Slack app 设置中定期轮换 token
定期审计谁能访问你的 Hermes 配置目录
Socket Mode 不暴露公网端点，天然少一个攻击面

概览​

第 1 步：创建 Slack App​

第 2 步：配置 Bot Token Scopes​

第 3 步：启用 Socket Mode​

第 4 步：订阅事件​

第 5 步：启用 Messages Tab​

第 6 步：安装到 Workspace​

第 7 步：找到 Allowlist 用的 User ID​

第 8 步：配置 Hermes​

第 9 步：把 Bot 邀请进频道​

Bot 的响应方式​

配置选项​

Thread & Reply Behavior​

Session Isolation​

Mention & Trigger Behavior​

Unauthorized User Handling​

Voice Transcription​

Full Example​

Home Channel​

Multi-Workspace Support​

Configuration​

OAuth Token File​

How it works​

Voice Messages​

Per-Channel Prompts​

Troubleshooting​

Quick Checklist​

Security​

概览