Skip to content

getting-started.md

Latest commit

 

History

History
201 lines (142 loc) · 5.63 KB

getting-started.md

File metadata and controls

201 lines (142 loc) · 5.63 KB
title HotPlex 5 分钟快速上手
weight 2
description 从零开始安装、配置并运行 HotPlex Worker Gateway

HotPlex 5 分钟快速上手

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）

下一步