如何在 Slack 上部署 Hermes Agent（Socket Mode）

为什么要在 Slack 中运行 Hermes Agent

如果你的团队日常都在 Slack 中工作，那么 AI 智能体也应该在那里。独立的浏览器标签页和控制台缺乏上下文——而频道、线程和私信本身就免费提供了这些信息：谁在提问、他们刚才在聊什么、答案应该出现在哪里。

Hermes Agent 通过 Socket Mode 提供一流的 Slack 支持，因此运行时可以部署在你的笔记本电脑上、一台 $5 的 VPS 上，甚至企业防火墙之后，依然能实时传递消息。无需暴露公网 webhook，无需维护反向代理，也无需开放入站端口。智能体主动连接 Slack，保持一个 WebSocket 长连接，所有消息和响应都通过这条单一通道传输。

本指南将完整介绍整个配置流程：通过内置清单创建 Slack 应用、生成 bot 令牌和应用级令牌、配置主频道和用户白名单、启动网关，以及初次部署时最容易踩到的坑。

开始之前你需要准备什么

一次干净的 Slack 部署需要具备以下五个条件：

一个你有权限安装应用的工作区。大多数工作区默认需要管理员审批安装——如果你不是管理员，请在 Settings & administration → Workspace settings → Permissions 中确认。
一个正在运行的 Hermes Agent 实例。Hermes Agent Docker 指南介绍了最简洁的部署方式；如果你在 Windows 上，WSL2 配置指南是对应的参考。
一个模型服务商的 API 密钥。Anthropic、OpenAI、OpenRouter 以及任何兼容 OpenAI 的接口均可使用。运行时通过它来实际回答消息。
你的 Slack 数字用户 ID，用于白名单配置（详见下文）。
大约 15 分钟完成首次安装。后续重新部署不到一分钟。

第一步 - 生成 Slack 应用清单

Slack 应用由一个 YAML 清单定义，一次性声明权限范围、事件订阅、斜线命令和 Socket Mode。Hermes 提供了一个专为其内置 Slack 处理器定制的清单，无需手动拼凑权限列表：

hermes slack manifest --write ./hermes-slack-manifest.yaml

打开 https://api.slack.com/apps，点击 Create New App，选择 From an app manifest，选定你的工作区，然后粘贴 hermes-slack-manifest.yaml 的内容。Slack 会预览将要创建的内容，确认即可。

该清单启用了 Socket Mode，声明了 Hermes 订阅的所有事件（app_mention、message.im、message.channels、message.groups、message.mpim），注册了内置斜线命令，并申请了运行时实际使用的 bot 权限范围：

app_mentions:read - 监听频道中有人 @ 提及机器人的事件。
chat:write - 发送回复和创建线程。
im:history、im:read、im:write - 私信会话。
channels:history、groups:history、mpim:history - 读取机器人被邀请加入的公共频道、私有频道和群组私信的上下文。
users:read - 将用户 ID 解析为显示名称，用于白名单界面和审计日志。
commands - 注册 /hermes 斜线命令入口。

安装后编辑清单没有问题。安装后新增权限范围是导致最多静默故障的操作——详见下方的故障排查部分。

第二步 - 生成 Bot 令牌和应用级令牌

Slack 为 Socket Mode 应用颁发两种不同的令牌，Hermes 两者都需要：

Bot 令牌（xoxb-…）

在应用设置中，进入 OAuth & Permissions → Install to Workspace。批准清单中的权限范围，Slack 会颁发一个 xoxb-… 令牌，复制它。

应用级令牌（xapp-…）

进入 Basic Information → App-Level Tokens → Generate Token and Scopes。为其命名（例如 hermes-socket），添加 connections:write 权限范围，然后点击 Generate。Slack 会颁发一个 xapp-… 令牌，复制它。

这两个令牌的职责不同。Bot 令牌用于认证 Slack API 调用（发送消息、读取频道历史）。应用令牌用于认证 Socket Mode WebSocket 连接本身——没有它，运行时虽然启动，但永远不会连接到 Slack，机器人将始终保持沉默。

第三步 - 找到你的 Slack 数字用户 ID

Hermes Agent 只会响应出现在 SLACK_ALLOWED_USERS 中的用户 ID。这是整个配置中最重要的安全控制，它需要数字 ID，而不是 @用户名 或显示名称。

在 Slack 中，点击你的头像 → Profile → 三点菜单（⋮）→ Copy member ID。ID 格式类似 U01ABCD2EFG。对每个需要授权的团队成员重复此操作。

跳过白名单配置，等同于将你的服务商 API 密钥公开给工作区中的所有人。如果一个 Hermes 实例可以从公开的 Slack 工作区访问，且白名单为空，那么机器人被邀请加入的每个频道中的每条消息都会消耗你的额度。

第四步 - 配置 Hermes 运行时

打开 ~/.hermes/.env（或你的容器所读取的 .env 文件），添加以下内容：

SLACK_BOT_TOKEN=xoxb-...your-bot-token...
SLACK_APP_TOKEN=xapp-...your-app-token...
SLACK_ALLOWED_USERS=U01ABCD2EFG,U02HIJK3LMN
SLACK_HOME_CHANNEL=C04XYZ123AB

各配置项说明：

SLACK_BOT_TOKEN - 第二步中获取的 xoxb-… 令牌。
SLACK_APP_TOKEN - xapp-… 令牌。忘记填写这项是最常见的故障原因，且不会产生任何错误信息——网关就是不会建立 WebSocket 连接。
SLACK_ALLOWED_USERS - 以逗号分隔的数字 ID 列表。机器人会忽略所有其他人，包括管理员和机器人账号。
SLACK_HOME_CHANNEL（可选）- 用于主动消息、定时摘要和技能触发通知的频道 ID。在 Slack 中右键点击频道 → View channel details → 复制底部的频道 ID。若未设置，主动输出将发送至第一个白名单用户与机器人的私信。

保存后执行 chmod 600 ~/.hermes/.env。两个令牌都授予了对工作区的写入权限，请像对待 SSH 密钥一样妥善保管。

终端界面显示 Hermes .env 文件，其中 SLACK_BOT_TOKEN、SLACK_APP_TOKEN、SLACK_ALLOWED_USERS 和 SLACK_HOME_CHANNEL 均已填写，文件权限已收紧至 600

第五步 - 启动网关

重启网关以加载新的环境配置：

hermes gateway restart

或者，使用 Docker Compose：

docker compose restart gateway

追踪日志，等待 Slack 握手完成：

hermes gateway logs --follow

按顺序查找以下两行输出：

slack: connecting to Socket Mode
slack: connected as @your-bot-name (workspace: your-workspace)

如果只看到第一行而没有后续输出，说明 xapp-… 令牌有误、缺失，或缺少 connections:write 权限范围。如果两行都没有，说明网关没有读取到新的 .env——请确认运行时所读取的文件路径。

第六步 - 邀请机器人并发送第一条消息

在任意希望机器人参与的频道中执行：

/invite @your-bot-name

机器人只能看到它被邀请加入的频道中的消息。这是 Slack 侧的限制，与 Hermes 无关——即使已授予 channels:history 权限，在执行 /invite 之前，机器人读取不到任何历史记录。

向机器人发送私信，或在频道中 @ 提及它。Hermes 会在同一会话中回复，持久化记忆和技能上下文完整保留。从这里开始，Hermes 的所有功能——持久化记忆、定时任务、自定义技能——与在 Telegram 平台上的表现完全一致。

Slack 频道中用户与 Hermes 机器人的对话线程，机器人给出了有上下文的回复，机器人名称旁有绿色在线标识

最常见的故障模式

五种错误几乎占了所有"Slack 配置出问题"支持案例的绝大多数：

忘记填写 xapp-… 令牌。 没有它，Socket Mode 根本不会建立连接，而 Slack 的应用控制台不会给出任何警告。解决方法是在 .env 中加一行并重启。

安装后新增权限范围但未重新安装。 新的权限范围会出现在 OAuth 页面，但在你点击 Reinstall to Workspace 之前，实际上并未授予机器人。机器人会静默保留旧的权限集。如果运行时日志出现 missing_scope 错误，原因就在于此。

机器人未被邀请到频道。 即使拥有 channels:history 权限，机器人在被邀请之前仍然读取不到任何历史记录。机器人会立即响应私信，但在频道中始终保持沉默，直到执行 /invite @your-bot-name。

SLACK_ALLOWED_USERS 为空。 默认行为是忽略所有人。这是一个经过深思熟虑的安全默认值，但会让忘记添加自己 ID 的初次使用者误以为机器人坏了。

两个网关进程共享同一数据卷。 如果你针对同一个 /data 目录同时启动 Slack 模式网关和 Telegram 模式网关，消息顺序和记忆写入会在几分钟内相互损坏。如果你希望同时使用两个平台，请运行单个网关并在 .env 中同时设置 SLACK_* 和 TELEGRAM_* 配置块——运行时原生支持多路复用。

如果问题看起来与 Slack 相关但症状更像通用问题，Telegram 故障排查指南深入介绍了底层网关和服务商问题——大多数问题与平台无关。

Slack 与 Telegram 对比

关注点	Slack	Telegram
配置时间	15 分钟（清单 + 2 个令牌）	5 分钟（一个 BotFather 令牌）
可达性	防火墙内（Socket Mode WebSocket）	防火墙内（长轮询）
白名单字段	`SLACK_ALLOWED_USERS`（数字 ID）	`TELEGRAM_ALLOWED_USERS`（数字 ID）
适合场景	团队协作、频道上下文、线程	个人使用、移动优先、语音模式
线程支持	原生支持	仅引用回复
文件处理	内置上传 + 预览	内置上传 + 预览

两个平台并不互斥。同一个 Hermes 运行时可以同时向两者推送消息——当同一个智能体需要同时服务个人 Telegram 聊天和团队 Slack 频道，并共享同一记忆存储时，这非常实用。

跳过 Slack 的基础配置

Slack 的配置步骤本身并不复杂，但你仍然需要自己负责主机运维：备份、控制台的 TLS、日志轮转和升级节奏。对于个人规模的部署，这没什么问题。而对于希望在几分钟内让机器人上线、此后无需任何运维开销的团队，Hermify 提供托管的 Hermes 运行时，对你的 Slack 令牌进行静态加密，通过可视化界面而非 .env 管理白名单，并在持久化服务器上维护 Socket Mode 的稳定连接。

你只需提供 Slack 工作区和模型服务商的 API 密钥，平台负责其余一切。如果你正在权衡这个取舍，自托管与托管服务对比详细分析了成本和维护数据。