🤖HermesBlog
Hermes 消息平台接入 · 第4篇2026/8/9· Easy Understand Hermes Agent

Slack 接入——团队办公的 AI 搭档

Hermes 消息平台接入第4篇：Slack。在团队频道里直接指挥 Hermes。

Slack 接入：给 AI 办入职手续

Slack 接入——团队办公的 AI 搭档

把 Hermes Agent 拉进你们的 Slack 工作区，等于给团队配了个随叫随到的 AI 搭档。它能在频道里回答问题、处理私聊请求，甚至还能读你丢进来的文件。而且用的是 Socket Mode（WebSocket 连接），不需要公网 IP，公司防火墙后面、自己笔记本上都能跑，这点对很多团队来说太省心了。

⚠️ 注意：Slack 已经在 2025 年 3 月彻底淘汰了老式的 Classic Apps（RTM API）。如果你手上还有老古董应用，别犹豫，直接按下面的步骤新建一个。

第一步：创建 Slack 应用

推荐用 Hermes 自动生成的 manifest 文件，一条命令搞定所有配置：

hermes slack manifest --agent-view --write

这条命令会生成 ~/.hermes/slack-manifest.json，里面已经帮你声明好了所有内置斜杠命令（/btw、/stop、/model 等）、OAuth 权限范围、事件订阅，连 Socket Mode 都帮你开好了。新应用必须用 Agent view；还在用 Slack 旧版 Assistant view 的老应用，可以暂时不加 --agent-view，等准备好再迁移。

然后去 api.slack.com/apps → Create New App → From an app manifest，粘贴 JSON 内容，一路 Next 就行。

想给应用写个详细描述？加个参数：

hermes slack manifest --agent-view \
  --long-description-file AGENTS.md --write

第二步：配置 Bot Token Scopes

在 OAuth & Permissions 页面添加权限。最容易漏掉的是 channels:history 和 groups:history——没有它们，机器人只在私聊里干活，频道里完全收不到消息。另外 files:read 也很关键，不然用户上传的附件它读不了。

第三步：开启 Socket Mode

在 Settings → Socket Mode 里打开开关，创建一个 App-Level Token（以 xapp- 开头），这就是你的 SLACK_APP_TOKEN。顺便说一句，如果想让机器人处理消息时显示“正在思考…“的状态，记得加上 assistant:write 权限。这个状态显示在回复输入框下方的页脚（”BotName is thinking…“），而不是消息列表里；消息区里那些”Generating response…“ / “Finding answers…” 是 Slack 自己的轮播提示，Hermes 控制不了，两者可能同时出现。

第四步：订阅事件

在 Event Subscriptions 里打开开关，添加这些 bot events：

  • message.im：接收私聊消息
  • message.mpim：接收群聊私信（多人 DM）里的消息
  • message.channels：接收公开频道消息
  • message.groups：接收私密频道消息（推荐）
  • app_mention：被 @ 时正常响应

这一步是新手最容易翻车的地方——如果机器人私聊正常但频道里没反应，十有八九是事件订阅漏了。

最后一步：安装应用到工作区

回到 Basic Information → Install App to Workspace，授权后拿到 Bot Token（xoxb- 开头）。把两个 token 配到 Hermes 的环境变量里，启动，搞定！

你的 Slack 搭档正式上岗了。

补充：让自己的前端发出的消息被当作真人消息（api_human_users）

如果你用自建的前端（内部看板、移动端壳、kiosk 等）以登录用户的身份给 Hermes 发消息，这些消息是通过 Web API 用 user token（xoxp-）发出的——虽然作者是真人，但它们带着发送方的 app_id 且没有 client_msg_id，正好和 Hermes 用来识别应用消息的特征一样，所以默认会被当成机器人流量丢掉。

用 allow_bots: all 可以放行，但那样会把所有机器人消息都放进来，不够安全。更好的做法是在 platforms.slack.extra.api_human_users 里列出这些用户的 Slack ID：

platforms:
  slack:
    extra:
      api_human_users:
        - U01ABC2DEF3

这样只有这些用户通过 Web API 发出的消息会被当作真人消息处理，其他机器人消息仍然按 allow_bots 的规则过滤。

补充：线程里用 !cmd 触发命令

Slack 自己不允许在线程回复里用原生斜杠命令——你在线程里敲 /queue，Slack 会直接回你“/queue is not supported in threads. Sorry!“，而且没有任何应用侧设置能把它打开。

变通办法是：Hermes 认一个开头的 ! 作为替代命令前缀，在线程里（其他地方也行）照样生效。直接当普通回复发 !queue、!stop、!model gpt-5.4 就行，Hermes 会按斜杠命令一样处理，并在同一个线程里回复。只有第一个词会去匹配命令表，所以像 !nice work 这种闲聊会原样交给 agent。@Hermes !stop 这种带 @ 的写法、以及前面带空格的写法也都认。审批提示（危险命令 / execute_code 审批）在按钮发不出去、退化成文字提示时，也会让你回 !approve / !deny——正是线程里能用的那种形式。

补充：斜杠命令的回复只有你自己看得到

原生斜杠命令（比如 /status、/help）的回复是临时消息——“Only visible to you”——所以命令输出不会刷屏频道。那个“Running /cmd…“的占位会被真实回复替换掉，太长的回复会拆成多条临时消息。Slack 对回复流有 5 条的上限，所以超长输出会明确提示被截断，而不是悄悄丢掉。如果主临时通道失败，Hermes 会走第二条临时 API 路径重试，绝不会把斜杠回复公开贴到频道里。（用普通消息形式敲的命令——线程里的 !cmd、@Hermes /cmd——则按正常可见消息回复。）

补充：clarify 提问的一键按钮

当 agent 需要问你一个选择题（clarify 工具）时，Slack 会渲染成 Block Kit 按钮——每个选项一个按钮，外加一个“✏️ Other…“切到自由输入（你下一条消息就是答案）。点完之后消息会原地更新，显示谁答的、选了什么；同一个提示再点就没反应了。按钮点击和普通消息走同一套用户授权。当提示超时（agent.clarify_timeout）、会话被重置，或者你直接打字回复而不是点按钮时，卡片会原地重写成没有按钮的版本（”⏳ This prompt expired…“ 或 “↩️ Clarification cancelled…”）；如果卡片因为 gateway 重启变成了孤儿，点它也会提示你重新提问，而不是默默吞掉这次点击。开放式 clarify 问题则渲染成一个普通问题。

补充：两个渲染开关

platforms.slack.extra.rich_blocks 设为 true 时，agent 消息会渲染成 Block Kit 块（标题、分割线、真正的嵌套列表、原生表格），Markdown 的 label 链接和 Slack 的 <url|label> 自动链接在列表、引用、表格单元格里都能点，@ 提及保持原样；纯文本兜底始终会发一份，超限的表格退回等宽对齐。这是发送侧改动，不用重装应用。

platforms.slack.extra.native_task_cards 设为 true 时，实时工具调用会渲染成 Slack 原生的计划/任务卡片。卡片和 Slack 内置默认的 tool_progress: off 兼容；但你自己显式写了 tool_progress: off（全局、display.platforms.slack 下，或用 /verbose 切到 off）就会把卡片也关掉，写 new 或 all 则保留。卡片需要线程：卡片通道开着但当前聊天没有可挂靠的线程（比如 reply_in_thread: false 的顶层 DM），Hermes 会干脆不显示工具进度，而不是退成文字气泡——除非你显式设了 new/all，那种情况下会退回可编辑的文字进度。可恢复的原生 API 失败会退回一条持续编辑的文字更新。

📖 官方文档

本文根据 Hermes Agent 官方文档编写，原文见：官方文档 › user-guide/messaging/slack

← 返回全部文章