Slack接入失败主因是Event Subscription未启用或OAuth权限缺失；需依次完成：启用事件订阅并配置回调URL、添加必要Bot Token Scopes并安装应用、配置Signing Secret并验证事件校验、正确设置Slack网关启动参数、启用即时响应模式避免超时。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试将 Hermes Agent 接入 Slack 工作流，但消息无法触发或授权失败，则可能是由于 Event Subscription 未正确启用或 OAuth 鉴权范围缺失。以下是解决此问题的步骤：
一、创建 Slack 应用并启用事件订阅
Slack 要求所有接收实时事件（如消息、反应、成员加入等）的应用必须显式声明所需事件类型，并通过 HTTPS 回调地址接收推送。该配置需在 Slack API 控制台中完成，且回调 URL 必须可被公网访问或使用本地隧道工具暴露。
1、访问 https://api.slack.com/apps，点击 “Create New App”，选择 “From scratch”。
2、输入应用名称（例如 hermes-slack-gateway），选择开发工作区，点击 “Create App”。
3、在左侧菜单中进入 “Event Subscriptions”，将开关切换为 “On”。
4、在 “Request URL” 栏填写 Hermes Agent 的 Slack 网关回调地址，格式为：https://your-domain.com/slack/events（若本地调试，可使用 ngrok 或 localtunnel 生成临时 HTTPS 地址）。
5、点击 “Subscribe to Workspace Events”，添加以下必要事件类型：app_mention、message.im、message.channels、reaction_added。
6、滚动至页面底部，点击 “Enable Events” 保存设置。
二、配置 OAuth 作用域与安装应用
OAuth 作用域决定了 Hermes Agent 在 Slack 中可执行的操作权限。缺少关键 scope 将导致消息发送失败、频道列表获取为空或无法响应提及。必须确保安装时授予全部必需权限，而非仅开发阶段默认 scope。
1、在左侧菜单中进入 “OAuth & Permissions”，在 “Scopes” 区域的 “Bot Token Scopes” 下点击 “Add an OAuth Scope”。
2、逐个添加以下 scope：app_mentions:read、channels:history、channels:join、channels:read、chat:write、groups:history、im:history、im:read、im:write、reactions:read、users:read、users:read.email。
3、返回页面顶部，点击 “Install to Workspace”，确认授权弹窗中的全部权限请求。
4、安装成功后，在 “OAuth Tokens for Your Workspace” 区域复制 Bot User OAuth Token（以 xoxb- 开头）。
5、将该 token 填入 Hermes Agent 的 Slack 网关配置中对应字段：SLACK_BOT_TOKEN。
三、验证 Signing Secret 并启用事件校验
Slack 所有事件推送均附带 X-Slack-Signature 和 X-Slack-Request-Timestamp 头，Hermes Agent 必须使用应用的 Signing Secret 进行 HMAC-SHA256 校验，否则会拒绝处理事件。未启用校验将导致 401 错误或静默丢弃事件。
1、在 “Basic Information” 页面中，展开 “App Credentials” 区域。
2、找到 Signing Secret，点击 “Show” 并复制其值。
3、在 Hermes Agent 的环境变量或 gateway 配置文件中，设置：SLACK_SIGNING_SECRET=your_copied_signing_secret。
4、确保 Hermes Agent 启动时加载该变量，并在 Slack 控制台 “Event Subscriptions” 页面点击 “Verify and Save” 按钮，系统将向回调地址发送测试事件并等待有效响应（HTTP 200 + 正确签名响应体）。
四、配置 Hermes Agent Slack 网关启动参数
Hermes Agent 的 Slack 网关需明确指定监听模式、端口及是否启用交互组件。若使用默认配置，可能遗漏交互事件（如按钮点击、模态框提交）所需的额外路由和事件注册。
1、在终端中运行：hermes gateway setup，选择 Slack 平台。
2、按提示输入：SLACK_BOT_TOKEN、SLACK_SIGNING_SECRET、SLACK_VERIFICATION_TOKEN（已弃用，留空）。
3、设置 SLACK_PORT=3000（或与反向代理一致的端口），并确认 SLACK_ENABLE_INTERACTIVES=true。
4、在 Slack 应用的 “Interactivity & Shortcuts” 页面中，启用 “Interactivity”，填写请求 URL 为：https://your-domain.com/slack/interactive。
5、启动网关：hermes gateway start slack，观察日志中是否出现 Slack event listener initialized 和 Interactive endpoint registered 提示。
五、调试事件接收与响应延迟问题
Slack 对事件响应时间有严格限制：必须在 3 秒内返回 HTTP 200。若 Hermes Agent 处理逻辑过重或依赖未就绪服务（如模型 provider 连接超时），将触发重试机制并造成消息重复或丢失。需分离同步响应与异步任务执行路径。
1、在 Slack “Event Subscriptions” 页面的 “Recent Events” 标签页中，查看每条事件的状态码与响应耗时。
2、若出现大量 4xx 或 5xx 响应，检查 Hermes Agent 日志中是否报出 Failed to validate signature 或 Timeout waiting for model response。
3、确保网关配置中启用快速响应模式：SLACK_IMMEDIATE_ACK=true，该选项使网关在解析事件后立即返回 200，再异步分发至 Hermes 主流程。
4、验证 Slack 应用状态页中 “App Home” 是否显示在线，且 “Bot User OAuth Token” 对应的 bot 已被邀请至目标频道（执行 /invite @hermes-slack-gateway）。
