HotPlex 5 分钟快速上手
June 13, 2026 · View on GitHub
HotPlex 是 AI Coding Agent 统一接入层，让你通过 Slack、飞书或 WebChat 与 Claude Code / OpenCode Server 交互。
读完本文你将：在本地跑起 HotPlex Gateway，通过 WebChat 发出第一条 AI 对话。
AI Agent
AI Agent： 阅读 INSTALL.md 并完成 hotplex 安装和配置。
Core -- 5 分钟跑起来
1. 安装
从 GitHub Releases 下载对应平台的归档文件并解压。
解压后二进制文件名为 hotplex-{os}-{arch}（如 hotplex-darwin-arm64），建议重命名：
macOS (Apple Silicon)
curl -L https://github.com/hrygo/hotplex/releases/latest/download/hotplex-darwin-arm64.tar.gz | tar xz
chmod +x hotplex-darwin-arm64 && mv hotplex-darwin-arm64 hotplex
macOS (Intel)
curl -L https://github.com/hrygo/hotplex/releases/latest/download/hotplex-darwin-amd64.tar.gz | tar xz
chmod +x hotplex-darwin-amd64 && mv hotplex-darwin-amd64 hotplex
Linux (AMD64)
curl -L https://github.com/hrygo/hotplex/releases/latest/download/hotplex-linux-amd64.tar.gz | tar xz
chmod +x hotplex-linux-amd64 && mv hotplex-linux-amd64 hotplex
Linux (ARM64)
curl -L https://github.com/hrygo/hotplex/releases/latest/download/hotplex-linux-arm64.tar.gz | tar xz
chmod +x hotplex-linux-arm64 && mv hotplex-linux-arm64 hotplex
Windows (AMD64)
Invoke-WebRequest -Uri "https://github.com/hrygo/hotplex/releases/latest/download/hotplex-windows-amd64.zip" -OutFile "hotplex.zip"
Expand-Archive -Path hotplex.zip -DestinationPath .
Rename-Item hotplex-windows-amd64.exe hotplex.exe
Windows (ARM64)
Invoke-WebRequest -Uri "https://github.com/hrygo/hotplex/releases/latest/download/hotplex-windows-arm64.zip" -OutFile "hotplex.zip"
Expand-Archive -Path hotplex.zip -DestinationPath .
Rename-Item hotplex-windows-arm64.exe hotplex.exe
或从源码构建：git clone → make build，产物在 bin/ 目录。
验证：hotplex version，应输出版本号（如 v1.28.0 或更高版本）。
2. 环境配置
cp configs/env.example .env
编辑 .env，填入必填项：
# 生成命令: openssl rand -base64 32 | tr -d '/+=' | head -c 43
HOTPLEX_ADMIN_TOKEN_1=<your-admin-token>
3. 前置依赖
AI 功能依赖 Claude Code CLI，确认已安装：claude --version。
如未安装，参考 Claude Code 官方文档。
4. 交互式配置
hotplex onboard # 向导：检测已有配置 → 平台选择 → 工作目录 → 生成 config.yaml
hotplex doctor # 验证：所有检查项应显示 PASS 或可接受的 WARN
5. 启动 Gateway
hotplex gateway start
验证：
curl http://localhost:8888/health # → {"status":"ok"}
open http://localhost:8888 # → WebChat 界面
看到 WebChat 界面即启动成功，在输入框发送消息即可开始 AI 对话。
开发模式下可跳过认证：hotplex dev（等效 gateway start --dev，禁用 API Key 和 Admin Token 校验）。
Platform Integration -- 连接 Slack / 飞书
Slack
# .env 中添加
HOTPLEX_MESSAGING_SLACK_ENABLED=true
HOTPLEX_MESSAGING_SLACK_BOT_TOKEN=xoxb-...
HOTPLEX_MESSAGING_SLACK_APP_TOKEN=xapp-...
可重新运行 hotplex onboard --enable-slack 自动生成配置。详细步骤见 Slack 集成教程。
飞书 (Feishu)
# .env 中添加
HOTPLEX_MESSAGING_FEISHU_ENABLED=true
HOTPLEX_MESSAGING_FEISHU_APP_ID=cli_xxxxxxxxxxxx
HOTPLEX_MESSAGING_FEISHU_APP_SECRET=<your-app-secret>
可重新运行 hotplex onboard --enable-feishu 自动生成配置。详细步骤见 飞书集成教程。
重启生效
修改 .env 或 config.yaml 后：hotplex gateway restart
Advanced Setup
系统服务
hotplex service install # 用户级守护进程（无需 root），开机自启
hotplex service start
hotplex service status
hotplex service logs -f # 实时日志
# 系统级服务: sudo hotplex service install --level system
自更新
hotplex update # 交互式更新
hotplex update --check # 仅检查
hotplex update -y --restart # 跳过确认并重启
定时任务 (Cron)
自然语言描述任务，Gateway 自动调度并将结果回传 Slack / 飞书：
hotplex cron create \
--name "daily-report" --schedule "cron:0 9 * * 1-5" \
-m "生成昨日项目日报" \
--bot-id "$BOT_ID" --owner-id "$USER_ID"
Agent 人格配置
通过 Markdown 文件定制 Agent 行为：
~/.hotplex/agent-configs/
SOUL.md # 人格定义（B 通道）
AGENTS.md # 行为规则（B 通道）
USER.md # 用户信息（C 通道）
MEMORY.md # 长期记忆（C 通道）
修改后对新会话生效，运行中会话需 /reset 重载。
端口说明
| 服务 | 地址 | 用途 |
|---|---|---|
| Gateway | localhost:8888 | WebSocket + WebChat + API |
| Admin API | localhost:9999 | 管理 API（Cron、Session） |