hermes教程-Slack

Slack 设置

使用 Socket 模式将 Hermes Agent 作为机器人连接到 Slack。Socket 模式使用 WebSocket 而非公共 HTTP 端点，因此你的 Hermes 实例无需公开访问——它可以在防火墙后、你的笔记本电脑上或私有服务器上工作。

警告——经典 Slack 应用已弃用

经典 Slack 应用（使用 RTM API）已于 2025 年 3 月完全弃用。Hermes 使用现代 Bolt SDK 和 Socket 模式。如果你有旧的经典应用，必须按照以下步骤创建一个新应用。

概述

步骤 1：创建 Slack 应用

最快的方式是粘贴 Hermes 为你生成的清单。它一次性声明了所有内置斜杠命令 (/btw, /stop, /model, …)、所有必需的 OAuth 作用域、所有事件订阅，并启用了 Socket 模式。

选项 A：使用 Hermes 生成的清单（推荐）

1. 生成清单：
   bashCopy

   hermes slack manifest --write

   这将写入 ~/.hermes/slack-manifest.json 并打印粘贴说明。
2. 前往 https://api.slack.com/apps → 创建新应用 → 从应用清单创建
3. 选择你的工作区，粘贴 JSON 内容，检查，点击 下一步 → 创建
4. 跳转到 步骤 6：将应用安装到工作区。清单已为你处理了作用域、事件和斜杠命令。

选项 B：从头开始（手动）

1. 前往 https://api.slack.com/apps
2. 点击 创建新应用
3. 选择 从头开始
4. 输入应用名称（例如 "Hermes Agent"）并选择你的工作区
5. 点击 创建应用

你将进入应用的 基本信息 页面。继续执行下面的步骤 2–6。

步骤 2：配置机器人令牌作用域

在侧边栏中导航到 功能 → OAuth 与权限。滚动到 作用域 → 机器人令牌作用域 并添加以下内容：

注意——缺少作用域 = 缺少功能

没有 channels:history 和 groups:history，机器人 将无法接收频道中的消息——它只能在 DM 中工作。没有 files:read，Hermes 可以聊天但 无法可靠地读取用户上传的附件。这些是最常被遗漏的作用域。

可选作用域：

步骤 3：启用 Socket 模式

Socket 模式允许机器人通过 WebSocket 连接，无需公共 URL。

1. 在侧边栏中，转到 设置 → Socket 模式
2. 将 启用 Socket 模式 切换为 ON
3. 系统会提示你创建一个 应用级令牌：
   • 将其命名为类似 hermes-socket（名称不重要）
   • 添加 connections:write 作用域
   • 点击 生成
4. 复制令牌——它以 xapp- 开头。这是你的 SLACK_APP_TOKEN

提示

你始终可以在 设置 → 基本信息 → 应用级令牌 下找到或重新生成应用级令牌。

步骤 4：订阅事件

这一步至关重要——它控制机器人能看到哪些消息。

1. 在侧边栏中，转到 功能 → 事件订阅
2. 将 启用事件 切换为 ON
3. 展开 订阅机器人事件 并添加：

4. 点击页面底部的 保存更改

危险——缺少事件订阅是 #1 设置问题

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

步骤 5：启用消息选项卡

此步骤启用与机器人的直接消息。没有它，用户尝试给机器人发 DM 时会看到 "已关闭向此应用发送消息"。

1. 在侧边栏中，转到 功能 → 应用首页
2. 滚动到 显示选项卡
3. 将 消息选项卡 切换为 ON
4. 勾选 "允许用户从消息选项卡发送斜杠命令和消息"

危险——没有此步骤，DM 完全被阻止

即使拥有所有正确的作用域和事件订阅，Slack 也不会允许用户向机器人发送直接消息，除非消息选项卡已启用。这是 Slack 平台的要求，而不是 Hermes 配置问题。

步骤 6：将应用安装到工作区

1. 在侧边栏中，转到 设置 → 安装应用
2. 点击 安装到工作区
3. 查看权限并点击 允许
4. 授权后，你将看到一个以 xoxb- 开头的 机器人用户 OAuth 令牌
5. 复制此令牌——这是你的 SLACK_BOT_TOKEN

提示

如果你之后更改了作用域或事件订阅，必须重新安装应用 才能使更改生效。安装应用页面会显示一个横幅提示你这样做。

步骤 7：查找允许列表的用户 ID

Hermes 使用 Slack 成员 ID（而非用户名或显示名称）作为允许列表。

要查找成员 ID：

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

成员 ID 看起来像 U01ABC2DEF3。你至少需要你自己的成员 ID。

步骤 8：配置 Hermes

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

## 必需
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # 逗号分隔的成员 ID
## 可选
SLACK_HOME_CHANNEL=C01234567890              # 用于 cron/定时消息的默认频道
SLACK_HOME_CHANNEL_NAME=general              # 主频道的可读名称（可选）

或者运行交互式设置：

hermes gateway setup    # 根据提示选择 Slack

然后启动网关：

hermes gateway              # 前台运行
hermes gateway install      # 安装为用户服务
sudo hermes gateway install --system   # 仅 Linux：作为开机系统服务

步骤 9：将机器人邀请到频道

启动网关后，你需要 邀请机器人 到你希望它响应的任何频道：

机器人 不会 自动加入频道。你必须逐个频道邀请它。

斜杠命令

每个 Hermes 命令（/btw、/stop、/new、/model、/help、...）都是原生的 Slack 斜杠命令——与它们在 Telegram 和 Discord 上的工作方式完全相同。在 Slack 中键入 /，自动完成选择器会列出每个 Hermes 命令及其描述。

在底层：Hermes 附带一个生成的 Slack 应用清单（参见步骤 1，选项 A），该清单在 COMMAND_REGISTRY 中声明每个命令为斜杠命令。在 Socket 模式下，无论清单的 url 字段如何，Slack 都会通过 WebSocket 路由命令事件。

更新后刷新斜杠命令

当 Hermes 添加新命令时（例如在 hermes update 之后），重新生成清单并更新你的 Slack 应用：

hermes slack manifest --write

然后在 Slack 中：

1. 打开 https://api.slack.com/apps → 你的 Hermes 应用
2. 功能 → 应用清单 → 编辑
3. 粘贴 ~/.hermes/slack-manifest.json 的新内容
4. 保存。如果作用域或斜杠命令发生变化，Slack 会提示重新安装应用。

旧版 /hermes <子命令> 仍然有效

为了向后兼容旧清单，你仍然可以键入 /hermes btw run the tests——Hermes 会以与 /btw run the tests 相同的方式路由它。自由形式的问题也有效：/hermes what's the weather? 被视为普通消息。

在线程中使用命令（!cmd 前缀）

Slack 本身阻止在线程回复中使用原生斜杠命令——尝试在线程中键入 /queue，Slack 会回复 "/queue 在线程中不受支持。抱歉！" 没有应用端设置可以重新启用它们；Slack 永远不会将它们传递给 Hermes。

作为变通方法，Hermes 识别前导的 ! 作为替代命令前缀，它可以在线程（以及任何其他地方）中工作。键入 !queue、!stop、!model gpt-5.4 等作为常规线程回复——Hermes 将其视为斜杠形式，并在同一线程中回复。

只有第一个令牌会与已知命令列表进行匹配，因此像 !nice work 这样的随意消息会原封不动地传递给代理。

批准提示（危险命令 / execute_code 批准）通常呈现为交互式按钮。当按钮无法传递且 Hermes 回退到文本提示时，提示会指示你使用 !approve / !deny 回复——这是在线程内有效的形式。

高级：仅输出斜杠命令数组

如果你手动维护 Slack 清单，并且只需要斜杠命令列表：

hermes slack manifest --slashes-only > /tmp/slashes.json

将该数组粘贴到现有清单的 features.slash_commands 键中。

机器人如何响应

了解 Hermes 在不同上下文中的行为：

提示

在频道中，始终 @提及 机器人以开始对话。一旦机器人在线程中活跃，你可以在该线程中回复而无需提及它。在线程之外，没有 @提及 的消息会被忽略，以防止在繁忙频道中产生噪音。

配置选项

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

线程与回复行为

platforms:
  slack:
## 控制多部分响应如何线程化
## "off"   — 从不将回复线程化到原始消息
## "first" — 第一个块线程化到用户消息（默认）
## "all"   — 所有块线程化到用户消息
    reply_to_mode: "first"

    extra:
## 是否在线程中回复（默认：true）。
## 当为 false 时，频道消息会直接回复到频道，而不是线程。
## 现有线程内的消息仍会在线程内回复。
      reply_in_thread: true
## 同时将线程回复发布到主频道
## （Slack 的 "同时发送到频道" 功能）。
## 仅广播第一个回复的第一个块。
      reply_broadcast: false

会话隔离

## 全局设置——适用于 Slack 和所有其他平台
group_sessions_per_user: true

当为 true（默认）时，共享频道中的每个用户都有自己的隔离对话会话。两个人在 #general 中与 Hermes 交谈将拥有独立的历史和上下文。

设置为 false 如果你想要协作模式，整个频道共享一个对话会话。请注意，这意味着用户共享上下文增长和令牌成本，并且一个用户的 /reset 会清除所有人的会话。

提及与触发行为

slack:
## 在频道中需要 @提及（这是默认行为；
## Slack 适配器无论如何都会在频道中强制 @提及 门控，
## 但你可以显式设置此选项以与其他平台保持一致）
  require_mention: true
## 防止线程自动参与：仅回复包含显式 @提及 的频道消息。
## 关闭此选项（默认）时，Slack 可以 "自动参与"——记住线程中的过去提及并跟进机器人消息回复，
## 并在没有新提及的情况下恢复活跃会话。
## 开启 strict_mention 时，每条新的频道消息必须 @提及 机器人，Hermes 才会响应。
  strict_mention: false
## 触发机器人的自定义提及模式
## （除了默认的 @提及 检测之外）
  mention_patterns:
    - "hey hermes"
    - "hermes,"
## 附加到每条传出消息前的文本
  reply_prefix: ""

提示——何时使用 strict_mention

在繁忙的工作区中，当 Slack 默认的 "机器人记住此线程" 行为让用户感到意外时，将其设置为 true——例如，一个长的技术支持线程，机器人在开始时提供了帮助，而你希望它保持沉默，除非再次被显式呼叫。DM 和活跃的交互式会话不受影响。

信息

Slack 支持两种模式：默认情况下需要 @mention 才能开始对话，但你可以通过 SLACK_FREE_RESPONSE_CHANNELS（逗号分隔的频道 ID）或 config.yaml 中的 slack.free_response_channels 选择特定频道退出此要求。一旦机器人在线程中有活跃会话，后续的线程回复不需要提及。在 DM 中，机器人始终响应，无需提及。

频道允许列表 (allowed_channels)

将机器人限制在一组固定的 Slack 频道中——当机器人被邀请到许多频道但只应在少数频道中响应时很有用。设置后，来自 不在 此列表中的频道的消息会被 静默忽略，即使机器人被 @提及。

DM 不受此过滤器影响，因此授权用户始终可以通过直接消息联系机器人。

slack:
  allowed_channels:
    - "C0123456789"   # #ops
    - "C0987654321"   # #incident-response

或通过环境变量（逗号分隔）：

SLACK_ALLOWED_CHANNELS="C0123456789,C0987654321"

行为：

• 空/未设置 → 无限制（完全向后兼容）。
• 非空 → 频道 ID 必须在列表中，否则消息会在任何其他门控（提及要求、free_response_channels 等）运行之前被丢弃。
• Slack 频道 ID 以 C（公共）、G（私有）或 D（DM）开头。通过 Slack UI 的 "打开频道详情" → "关于" 面板或通过 API 查找它们。

另请参阅：管理员/用户斜杠命令拆分。

未授权用户处理

slack:
## 当未授权用户（不在 SLACK_ALLOWED_USERS 中）给机器人发 DM 时发生的情况
## "pair"   — 提示他们输入配对码（默认）
## "ignore" — 静默丢弃消息
  unauthorized_dm_behavior: "pair"

你也可以为所有平台全局设置此选项：

unauthorized_dm_behavior: "pair"

slack: 下的平台特定设置优先于全局设置。

语音转录

## 全局设置——启用/禁用传入语音消息的自动转录
stt_enabled: true

当为 true（默认）时，传入的音频消息会在被代理处理之前使用配置的 STT 提供程序自动转录。

完整示例

## 全局网关设置
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true
## Slack 特定设置
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"
## 平台配置
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

主频道

设置 SLACK_HOME_CHANNEL 为频道 ID，Hermes 将在此频道中传递定时消息、cron 作业结果和其他主动通知。要查找频道 ID：

1. 右键单击 Slack 中的频道名称
2. 点击 查看频道详情
3. 滚动到底部——频道 ID 显示在那里

SLACK_HOME_CHANNEL=C01234567890

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

多工作区支持

Hermes 可以使用单个网关实例同时连接到 多个 Slack 工作区。每个工作区使用自己的机器人用户 ID 独立认证。

配置

在 SLACK_BOT_TOKEN 中提供多个机器人令牌作为 逗号分隔的列表：

## 多个机器人令牌——每个工作区一个
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token
## 仍然使用单个应用级令牌进行 Socket 模式
SLACK_APP_TOKEN=xapp-your-app-token

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

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

OAuth 令牌文件

除了环境或配置中的令牌，Hermes 还会从 OAuth 令牌文件 加载令牌，路径为：

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

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

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

工作原理

• 列表中的 第一个令牌 是主令牌，用于 Socket 模式连接（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 响应作为音频文件附件发送

每个频道的提示

为特定 Slack 频道分配临时系统提示。提示在每次轮次运行时注入——永远不会持久化到对话历史中——因此更改会立即生效。

slack:
  channel_prompts:
    "C01RESEARCH": |
      你是一名研究助手。专注于学术来源、
      引用和简洁的综合。
    "C02ENGINEERING": |
      代码审查模式。对边缘情况和
      性能影响要精确。

键是 Slack 频道 ID（通过频道详情 → "关于" → 滚动到底部查找）。匹配频道中的所有消息都会获得该提示作为临时系统指令注入。

每个频道的技能绑定

当在特定频道或 DM 中启动新会话时自动加载技能。与每个频道的提示（每次轮次注入）不同，技能绑定会在 会话启动 时将技能内容作为用户消息注入——它成为对话历史的一部分，并且不需要在后续轮次中重新加载。

这对于具有专用目的的 DM 或频道（闪卡、特定领域的问答机器人、支持分类频道等）非常理想，在这些场景中，你不希望模型自己的技能选择器决定是否在每次简短回复时加载。

slack:
  channel_skill_bindings:
## DM 频道——始终以 "german-flashcards" 模式运行
    - id: "D0ATH9TQ0G6"
      skills:
        - german-flashcards
## 研究频道——按顺序预加载多个技能
    - id: "C01RESEARCH"
      skills:
        - arxiv
        - writing-plans
## 简短形式：单个技能作为字符串
    - id: "C02SUPPORT"
      skill: hubspot-on-demand

注意：

• 绑定按频道 ID 匹配。对于绑定频道中的线程消息，线程继承父频道的绑定。
• 技能仅在会话启动时加载（新会话或自动重置后）。如果你更改了绑定，请运行 /new 或等待会话自动重置以使其生效。
• 与 channel_prompts 结合使用，可在技能指令之上添加每个频道的语气/约束。

故障排除

快速检查清单

如果机器人在频道中不工作，请验证 所有 以下内容：

1. ✅ 已订阅 message.channels 事件（对于公共频道）
2. ✅ 已订阅 message.groups 事件（对于私有频道）
3. ✅ 已订阅 app_mention 事件
4. ✅ 已添加 channels:history 作用域（对于公共频道）
5. ✅ 已添加 groups:history 作用域（对于私有频道）
6. ✅ 在添加作用域/事件后 重新安装 了应用
7. ✅ 机器人已被 邀请 到频道（/invite @Hermes Agent）
8. ✅ 你在消息中 @提及 了机器人

安全

警告

始终设置 SLACK_ALLOWED_USERS，包含授权用户的成员 ID。没有此设置，网关将默认 拒绝所有消息 作为安全措施。切勿共享你的机器人令牌——像对待密码一样对待它们。

• 令牌应存储在 ~/.hermes/.env 中（文件权限 600）
• 定期通过 Slack 应用设置轮换令牌
• 审计谁有权访问你的 Hermes 配置目录
• Socket 模式意味着没有公共端点暴露——减少一个攻击面