Slack 集成教程

本教程引导你完成 HotPlex Gateway 与 Slack 的集成，实现 AI Agent 在 Slack 中实时响应。

前置条件：HotPlex 已安装（make quickstart）、Slack Workspace 管理权限。

1. 创建 Slack App

访问 api.slack.com/apps，点击 Create New App。

方式 A：一键 Manifest（推荐）

选择 From an app manifest → 粘贴以下 JSON，一次性完成权限、事件、交互、斜杠命令的全部配置：

{
  "_metadata": { "major_version": 2, "minor_version": 1 },
  "display_information": {
    "name": "HotPlex",
    "long_description": "HotPlex is your AI coding partner in Slack. Write code, fix bugs, review PRs, create issues, and manage your entire development workflow directly in conversations.",
    "description": "AI coding partner — write, review, fix, and ship code in Slack",
    "background_color": "#1e293b"
  },
  "features": {
    "assistant_view": {
      "assistant_description": "Your AI coding partner. Supports code writing & review, bug fixes, PR and issue creation, directory switching, and more.",
      "suggested_prompts": [
        { "title": "💡 Creative Sparks", "message": "Use brainstorm mode to analyze current project architecture, identify three areas for improvement, and explain their value and implementation ideas." },
        { "title": "📝 Create Issue", "message": "Create a GitHub Issue using the project's defined template, describing an important bug or feature requirement." },
        { "title": "🔀 Create PR", "message": "Create a pull request based on current code changes using the project's defined PR template." },
        { "title": "🔍 Code Review", "message": "Perform a comprehensive code review of the current branch, covering DRY, SOLID, clean architecture, security vulnerabilities, and performance optimization." }
      ]
    },
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": { "display_name": "HotPlex", "always_online": true },
    "slash_commands": [
      { "command": "/gc", "description": "Sleep session (stop Worker, preserve context)", "should_escape": false },
      { "command": "/park", "description": "Sleep session (same as /gc)", "should_escape": false },
      { "command": "/reset", "description": "Reset context (fresh start)", "should_escape": false },
      { "command": "/new", "description": "Reset context (same as /reset)", "should_escape": false },
      { "command": "/cd", "description": "Switch working directory", "usage_hint": "/cd /path/to/project", "should_escape": false },
      { "command": "/context", "description": "View context window usage", "should_escape": false },
      { "command": "/skills", "description": "List loaded skills", "should_escape": false },
      { "command": "/mcp", "description": "Show MCP server status", "should_escape": false },
      { "command": "/model", "description": "Switch AI model", "usage_hint": "/model claude-sonnet-4-6", "should_escape": false },
      { "command": "/perm", "description": "Set permission mode", "usage_hint": "/perm bypassPermissions", "should_escape": false },
      { "command": "/effort", "description": "Set reasoning effort level", "usage_hint": "/effort high", "should_escape": false },
      { "command": "/compact", "description": "Compact conversation history", "should_escape": false },
      { "command": "/clear", "description": "Clear conversation", "should_escape": false },
      { "command": "/rewind", "description": "Undo last conversation turn", "should_escape": false },
      { "command": "/commit", "description": "Create a Git commit", "should_escape": false }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read", "assistant:write", "bookmarks:read", "bookmarks:write",
        "canvases:read", "canvases:write", "channels:history", "channels:manage",
        "channels:read", "chat:write", "chat:write.customize", "chat:write.public",
        "commands", "dnd:read", "emoji:read", "files:read", "files:write",
        "groups:history", "groups:read", "im:history", "im:read", "im:write",
        "links:read", "links:write", "metadata.message:read", "mpim:history",
        "mpim:read", "mpim:write", "pins:read", "pins:write", "reactions:read",
        "reactions:write", "remote_files:read", "remote_files:write", "team:read",
        "usergroups:read", "users:read", "search:read.files", "search:read.im",
        "search:read.users", "search:read.public"
      ]
    }
  },
  "settings": {
    "event_subscriptions": {
      "bot_events": [
        "app_home_opened", "app_mention", "assistant_thread_context_changed",
        "assistant_thread_started", "message.channels", "message.groups",
        "message.im", "message.mpim"
      ]
    },
    "interactivity": { "is_enabled": true },
    "org_deploy_enabled": true,
    "socket_mode_enabled": true
  }
}

创建后跳到 步骤 1.3 生成 Token。

方式 B：手动配置

选择 From scratch，按以下步骤逐项配置。

1.1 启用 Socket Mode

Settings → Socket Mode → 打开 Enable Socket Mode。

Socket Mode 让 Gateway 通过 WebSocket 与 Slack 通信，无需公网地址。

1.2 配置 Bot Token Scopes

OAuth & Permissions → Bot Token Scopes，添加以下权限：

1.3 生成 Token

需要两个 Token：

• Bot Token (xoxb-...)：OAuth & Permissions → Bot User OAuth Token
• App-Level Token (xapp-...)：Basic Information → App-Level Tokens → Generate，Scope 勾选 connections:write

记录这两个 Token，下一步需要用到。

1.4 订阅事件

Event Subscriptions → 打开 Enable → Subscribe to bot events：

• message.channels
• message.groups
• message.im
• app_mention

1.5 启用交互

Interactivity & Shortcuts → 打开 Enable Interactivity。

权限请求和问答按钮需要此功能。

1.6 安装到 Workspace

OAuth & Permissions → Install to Workspace → 授权。

验证：Settings → Install App 页面显示 Bot Token，Slack 侧栏 Apps 中出现你的 Bot。

2. 配置 HotPlex

在项目根目录编辑 .env（首次使用：cp configs/env.example .env）：

# 启用 Slack
HOTPLEX_MESSAGING_SLACK_ENABLED=true

# 填入步骤 1.3 获取的 Token
HOTPLEX_MESSAGING_SLACK_BOT_TOKEN=xoxb-your-bot-token
HOTPLEX_MESSAGING_SLACK_APP_TOKEN=xapp-your-app-token

也可以运行 hotplex onboard 向导交互式配置。

验证：确认 .env 中三个变量均已取消注释且值非空。

3. 启动 Gateway

hotplex gateway start -d

-d 表示后台运行。查看状态：

hotplex status

输出中应包含 health endpoint 返回 200 的状态，表示 Socket Mode 已连接。

验证：hotplex status 显示 Slack 连接正常。

4. 测试

4.1 基本对话

1. 在 Slack 中找到你的 Bot（侧栏 Apps → 点击进入私聊）
2. 发送 你好
3. 等待流式回复完成

验证：Bot 回复消息，内容为 AI 生成的响应。

4.2 权限请求

1. 发送一条需要执行命令的请求，例如 帮我看一下当前目录的文件
2. Slack 中应出现权限确认按钮

验证：出现 Allow / Deny 按钮，点击后 Bot 执行相应操作。

5. 进阶配置

# 私聊策略：open（所有人）| allowlist（白名单）| disabled（禁止）
HOTPLEX_MESSAGING_SLACK_ALLOW_DM_FROM=U12345678,U87654321

# 群组策略：同上
HOTPLEX_MESSAGING_SLACK_ALLOW_GROUP_FROM=U12345678

messaging:
  slack:
    dm_policy: allowlist      # open | allowlist | disabled
    group_policy: allowlist
    allow_from: ["U12345678"]
    allow_dm_from: []
    allow_group_from: []

# 群组需要 @提及（默认 true）
HOTPLEX_MESSAGING_SLACK_REQUIRE_MENTION=true

# 文字转语音（Edge TTS，免费）
HOTPLEX_MESSAGING_TTS_ENABLED=true
HOTPLEX_MESSAGING_TTS_PROVIDER=edge
HOTPLEX_MESSAGING_TTS_VOICE=zh-CN-XiaoxiaoNeural

# 语音转文字
HOTPLEX_MESSAGING_STT_PROVIDER=local

下一步：配置 Agent 人格 或探索 飞书集成。