Slack 接入

Hermes 支持通过 Slack Bot 接入，适合团队在工作区内使用 AI 助手。

---

前置条件

• 已安装并运行 Hermes
• 拥有 Slack 工作区的管理员权限（或有权创建 App）

---

第一步：创建 Slack App

1. 打开 Slack API 控制台，点击 Create New App

2. 选择 From scratch，输入 App 名称（如 Hermes Agent），选择目标工作区

3. 进入 OAuth & Permissions 页面，在 Bot Token Scopes 中添加以下权限：

   权限	用途
   chat:write	发送消息
   im:history	读取私信历史
   im:read	读取私信
   im:write	发送私信
   channels:history	读取公开频道消息
   files:read	读取文件
   files:write	上传文件
   users:read	读取用户信息

4. 点击 Install to Workspace，授权后获取 Bot User OAuth Token（以 xoxb- 开头）

---

第二步：启用事件订阅

1. 进入 Event Subscriptions 页面，打开 Enable Events

2. 在 Request URL 中填入 Hermes 的 Webhook 地址（需要公网可访问）：

   https://your-server.example.com/slack/events

3. 在 Subscribe to bot events 中添加：

   • message.im（私信消息）
   • message.channels（频道消息，可选）
   • app_mention（被提及时）

4. 保存更改

---

第三步：配置环境变量

编辑 ~/.hermes/.env：

# Slack Bot Token（xoxb- 开头）
SLACK_BOT_TOKEN=xoxb-xxxxxxxxxx-xxxxxxxxxx-xxxxxxxxxxxxxxxx

# Slack Signing Secret（用于验证请求来自 Slack）
SLACK_SIGNING_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 允许使用的用户 ID（格式如 U01XXXXXXXX，多个用逗号分隔）
SLACK_ALLOWED_USERS=U01ABC123DE,U01FGH456IJ

获取 Signing Secret

在 Slack App 控制台的 Basic Information 页面可找到 Signing Secret。

获取用户 ID

在 Slack 中点击用户头像，选择 查看完整资料，在个人资料页面点击 更多 -> 复制成员 ID。

---

第四步：运行配置向导并启动

hermes gateway setup
# 选择 Slack

hermes gateway start

---

使用方式

私信

直接向 Bot 发送私信（在左侧栏找到 Bot 名称点击）即可开始对话。

频道中使用

在频道中提及 Bot：

@HermesAgent 帮我分析一下这段代码的性能问题

支持的聊天命令

在对话中发送以下命令：

命令	说明
/new	开始新会话
/reset	重置会话
/model	切换模型
/help	显示帮助

---

企业内网部署注意事项

如果 Slack 工作区在企业内网中使用，Hermes 网关需要可被 Slack 服务器访问（用于事件推送）。可选方案：

• 使用 ngrok 或 Cloudflare Tunnel 将本地服务暴露到公网
• 在有公网 IP 的服务器上部署 Hermes 网关
• 使用 Slack Socket Mode（不需要公网地址，通过 WebSocket 连接）

启用 Socket Mode

1. 在 Slack App 控制台进入 Socket Mode，打开 Enable Socket Mode
2. 生成 App-Level Token（以 xapp- 开头），添加 connections:write 权限
3. 在 .env 中添加：

   SLACK_APP_TOKEN=xapp-xxxxxxxxxx-xxxxxxxxxx-xxxxxxxxxxxxxxxx

Socket Mode 下无需公网地址，适合本地或内网部署场景。

---

常见问题

Bot 收不到消息？

• 确认 Event Subscriptions 中的 Request URL 验证通过（绿色对勾）
• 或确认 Socket Mode 已启用且 App Token 正确

权限不足错误？

• 检查 Bot Token Scopes 是否包含所需权限
• 重新安装 App 到工作区（修改权限后需要重装）

消息发送失败？

• 确认 Bot 已被邀请到对应频道（私信无需此步骤）
• 在频道中输入 /invite @HermesAgent