HAPI Hub Docker 部署
一键 Docker 部署 HAPI Hub，在服务器上运行 Hub，本地开发机通过 CLI 连接，手机通过 Web/PWA 远程控制。
支持 Claude Code / Codex / Cursor / Gemini / OpenCode。
服务端部署（在服务器上执行）
1. 准备
mkdir -p /opt/hapi-hub && cd /opt/hapi-hub
2. 创建 docker-compose.yml
services:
hapi-hub:
image: ghcr.io/arkylin/hapi-docker:latest
container_name: hapi-hub
restart: unless-stopped
ports:
- "3006:3006"
volumes:
- ./hapi-data:/root/.hapi
environment:
- CLI_API_TOKEN=这里填一个只有你知道的随机字符串
- HAPI_LISTEN_HOST=0.0.0.0
- HAPI_LISTEN_PORT=3006
3. 启动
docker compose up -d
4. 查看日志（确认启动成功）
docker compose logs -f
启动后浏览器访问 http://服务器IP:3006 即可看到 HAPI Web 界面。
本地开发机配置（在本地电脑上执行）
1. 安装 HAPI CLI
npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org
或用 Homebrew：
brew install tiann/tap/hapi
2. 配置连接 Hub
export HAPI_API_URL="http://服务器IP:3006"
export CLI_API_TOKEN="你在 docker-compose.yml 里填的令牌"
建议将这两行写入
~/.bashrc或~/.zshrc避免重复设置。
3. 启动 AI 会话
# Claude Code
hapi
# Codex
hapi codex
# Cursor Agent
hapi cursor
# Gemini
hapi gemini
# OpenCode
hapi opencode
会话启动后，会在 Hub 注册，Web 端和手机上都能看到。
手机 / 网页端访问
Web
浏览器打开 http://服务器IP:3006，输入 CLI_API_TOKEN 登录。
PWA（添加到桌面）
Android (Chrome): 底部弹出 "Install HAPI" 横幅 → 点击安装。
iOS (Safari): 分享按钮 → "添加到主屏幕"。
Desktop (Chrome/Edge): 地址栏安装图标 (⊕)。
登录后即可在手机上：
- 查看所有活动会话
- 发送消息给 AI
- 审批工具调用请求（文件读写、命令执行等）
- 浏览文件差异
Runner 模式（远程拉起新会话）
在 Hub 容器内启动 Runner，就可以从 Web 端直接创建新会话，无需保持终端打开：
docker exec hapi-hub hapi runner start --foreground
启动后 Web 界面的 "Machines" 列表会出现这台机器，点击即可远程创建新会话。
Seamless Handoff（无缝切换）
- 本地键入 = 终端直接输入
- 手机收到消息 = 自动切换到远程模式，终端显示 "Remote mode"
- 终端按两次空格 = 切回本地模式
同一会话，同一状态，无需重启。
环境变量
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
CLI_API_TOKEN |
是 | - | 认证令牌，CLI 和 Web 登录使用 |
HAPI_PUBLIC_URL |
否 | - | Hub 公网地址（用于 Telegram 等回调） |
CORS_ORIGINS |
否 | * |
允许的 CORS 域名 |
TZ |
否 | Asia/Shanghai |
时区 |
持久化数据
./hapi-data/ 挂载到容器内 /root/.hapi/：
settings.json— 配置文件hapi.db— SQLite 数据库
本地构建（可选）
git clone https://github.com/arkylin/Hapi-Docker.git
cd Hapi-Docker
# 编辑 .env
docker compose up -d