# hapi
**Repository Path**: Mr_zoupeng/hapi
## Basic Information
- **Project Name**: hapi
- **Description**: HAPI 是一个本地优先的工具，用于运行 AI 编程代理并通过 Web / PWA / Telegram Mini App 远程控制它们。它包装你的代理而不是替代它 —— 同样的终端、同样的体验、同样的操作习惯。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-02-02
- **Last Updated**: 2026-03-31
## Categories & Tags
**Categories**: ai
**Tags**: None
## README
HAPI
在本地运行 Claude Code / Codex / Gemini / OpenCode，随时随地远程控制。
English |
中文 |
日本語 |
한국어
---
HAPI 是一个本地优先的工具，用于运行 AI 编程代理并通过 Web / PWA / Telegram Mini App 远程控制它们。它包装你的代理而不是替代它 —— 同样的终端、同样的体验、同样的操作习惯。
> **为什么选择 HAPI？** HAPI 是 [Happy](https://github.com/slopus/happy) 的本地优先替代方案，你的数据始终留在自己的机器上。详见 [Why HAPI?](docs/guide/why-hapi.md)。
## 特性
- **无缝切换** — 本地工作，需要时切到远程，随时切回。不丢上下文，不重启会话。
- **原生优先** — HAPI 包装你的 AI 代理而非替代它。同样的终端、同样的体验、同样的肌肉记忆。
- **离开也不停** — 离开工位？在手机上一键审批 AI 请求。
- **自由选择 AI** — Claude Code、Codex、Gemini、OpenCode —— 不同模型，统一工作流。
- **随处终端** — 从手机或浏览器运行命令，直连你的工作机器。
- **语音控制** — 通过内置语音助手免提与 AI 代理对话。
## 演示
https://github.com/user-attachments/assets/38230353-94c6-4dbe-9c29-b2a2cc457546
## 架构
```
┌─────────────────────────────────────────────────────┐
│ 你的机器 │
│ │
│ ┌─────────┐ Socket.IO ┌─────────────┐ │
│ │ CLI │◄───────────────►│ Hub │ │
│ │+ Agent │ │ + SQLite │ │
│ └─────────┘ └──────┬──────┘ │
│ ▲ │ SSE │
│ │ spawn ▼ │
│ ┌────┴────┐ ┌─────────────┐ │
│ │ Runner │◄────RPC────────►│ Web App │ │
│ └─────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────┘
│
[隧道 / 中继]
│
┌─────▼─────┐
│ 手机/浏览器 │
└───────────┘
```
| 组件 | 职责 | 是否必需 |
|------|------|----------|
| **CLI** | 包装 AI 代理（Claude/Codex/Gemini/OpenCode），运行会话 | 是 |
| **Hub** | 中央协调器：持久化、实时同步、远程访问 | 是 |
| **Runner** | 后台服务，用于远程创建会话 | 可选 |
更多细节请参阅 [How it Works](docs/guide/how-it-works.md)。
## 快速开始
### 前置要求
需要安装以下任一 AI 编程代理：
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — `claude --version`
- [OpenAI Codex CLI](https://github.com/openai/codex) — `codex --version`
- [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) — `gemini --version`
- [OpenCode CLI](https://github.com/opencode-ai/opencode) — `opencode --version`
### 安装
**npm（推荐）：**
```bash
npm install -g @zzp123/hapi
```
**Homebrew：**
```bash
brew install tiann/tap/hapi
```
**npx（免安装）：**
```bash
npx @zzp123/hapi
```
预编译二进制
从 [GitHub Releases](https://github.com/tiann/hapi/releases) 下载最新版本。
```bash
chmod +x ./hapi
sudo mv ./hapi /usr/local/bin/
```
从源码构建
```bash
git clone https://github.com/tiann/hapi.git
cd hapi
bun install
bun run build:single-exe
```
### 启动
```bash
hapi hub --relay # 启动 Hub 并开启端到端加密中继
hapi # 运行 Claude Code（默认）
```
终端会显示一个 URL 和二维码。用手机扫描或在浏览器中打开即可访问。
> 中继使用 WireGuard + TLS 进行端到端加密。数据从你的设备到你的机器全程加密。
`hapi server` 仍然支持作为别名使用。
## 配置
配置优先级：**环境变量 > settings.json > 默认值**
```
~/.hapi/
├── settings.json # 主配置文件
├── hapi.db # SQLite 数据库（Hub）
├── runner.state.json # Runner 进程状态
└── logs/ # 日志文件
```
### 环境变量
| 变量 | 默认值 | settings.json | 说明 |
|------|--------|---------------|------|
| `CLI_API_TOKEN` | 自动生成 | `cliApiToken` | 认证共享密钥 |
| `HAPI_API_URL` | `http://localhost:3006` | `apiUrl` | CLI 连接的 Hub URL |
| `HAPI_LISTEN_HOST` | `127.0.0.1` | `listenHost` | Hub HTTP 绑定地址 |
| `HAPI_LISTEN_PORT` | `3006` | `listenPort` | Hub HTTP 端口 |
| `HAPI_PUBLIC_URL` | - | `publicUrl` | 外部访问的公网 URL |
| `CORS_ORIGINS` | - | `corsOrigins` | 允许的 CORS 来源（逗号分隔） |
| `TELEGRAM_BOT_TOKEN` | - | `telegramBotToken` | Telegram Bot API 令牌 |
| `TELEGRAM_NOTIFICATION` | `true` | `telegramNotification` | 启用 Telegram 通知 |
| `HAPI_RELAY_FORCE_TCP` | `false` | - | 强制中继使用 TCP 模式 |
| `VAPID_SUBJECT` | `mailto:admin@hapi.run` | - | Web Push 联系信息 |
| `HAPI_HOME` | `~/.hapi` | - | 配置目录路径 |
| `DB_PATH` | `~/.hapi/hapi.db` | - | 数据库文件路径 |
| `ELEVENLABS_API_KEY` | - | - | ElevenLabs 语音 API 密钥 |
| `ELEVENLABS_AGENT_ID` | 自动创建 | - | 自定义 ElevenLabs 代理 ID |
settings.json 示例
```json
{
"$schema": "https://hapi.run/docs/schemas/settings.schema.json",
"listenHost": "0.0.0.0",
"listenPort": 3006,
"publicUrl": "https://your-domain.com"
}
```
## 使用方式
### 支持的代理
```bash
hapi # Claude Code（默认）
hapi codex # OpenAI Codex CLI
hapi gemini # Google Gemini CLI
hapi opencode # OpenCode CLI
```
### 核心命令
```bash
hapi hub # 启动 Hub（仅本地）
hapi hub --relay # 启动 Hub 并开启公共中继
hapi runner start # 启动后台 Runner，支持远程创建会话
hapi runner status # 查看 Runner 状态
hapi runner stop # 停止 Runner
hapi auth login # 交互式登录远程 Hub
hapi auth status # 查看认证状态
hapi doctor # 诊断问题
```
### 远程访问方式
| 方式 | 配置方法 | 适用场景 |
|------|----------|----------|
| **公共中继**（默认） | `hapi hub --relay` | 零配置，穿透 NAT |
| **Cloudflare Tunnel** | 需创建命名隧道 | 低延迟，自主管理 |
| **Tailscale** | 安装 + `tailscale up` | 私有 Mesh VPN |
| **公网 IP** | 直连或反向代理 | 完全控制 |
详细配置说明请参阅 [Installation](docs/guide/installation.md)。
## 文档
- [安装指南](docs/guide/installation.md) — 完整安装和配置说明
- [工作原理](docs/guide/how-it-works.md) — 架构深度解析
- [为什么选择 HAPI？](docs/guide/why-hapi.md) — 与 Happy 的对比
- [PWA / App](docs/guide/pwa.md) — 渐进式 Web 应用指南
- [语音助手](docs/guide/voice-assistant.md) — 语音控制配置
- [多机器部署](DEPLOY.md) — 多机器部署指南
- [常见问题](docs/guide/faq.md) — 常见问题解答
## HAPI vs Happy
| 方面 | Happy | HAPI |
|------|-------|------|
| **架构** | 中心化云服务器 | 去中心化（每个用户运行自己的 Hub） |
| **数据** | 加密存储在服务器 | 留在你自己的机器上 |
| **部署** | PostgreSQL + Redis + 应用服务器 | 单一二进制文件 |
| **加密** | 应用层端到端加密 | WireGuard + TLS（中继）或 HTTPS（自托管） |
| **配置** | Docker + 配置文件 | 一条命令 |
**选择 HAPI**：如果你追求数据主权、自托管和极简部署。
**选择 Happy**：如果你需要托管云服务和多用户协作。
完整对比请查看 [为什么选择 HAPI？](docs/guide/why-hapi.md)。
## 参与贡献
欢迎贡献！以下是参与方式：
1. **Fork** 本仓库
2. **创建**功能分支：`git checkout -b feat/my-feature`
3. 使用 [约定式提交](https://www.conventionalcommits.org/) **提交**你的更改：
- `feat:` 新功能
- `fix:` 修复 Bug
- `docs:` 文档变更
- `refactor:` 代码重构
4. **推送**到你的分支：`git push origin feat/my-feature`
5. **提交** Pull Request
### 开发环境
```bash
git clone https://github.com/tiann/hapi.git
cd hapi
bun install
# 启动开发服务器（Hub + Web）
bun run dev
# 运行测试
bun run test
# 类型检查
bun run typecheck
```
### 项目结构
```
hapi/
├── cli/ # AI 代理的 CLI 包装器
├── hub/ # 中央 Hub 服务器（HTTP API + Socket.IO + SQLite）
├── web/ # 基于 React 的 PWA 前端
├── shared/ # 共享类型和协议
├── website/ # 项目网站
└── docs/ # VitePress 文档
```
## 开源协议
[AGPL-3.0](LICENSE)
## 致谢
HAPI 的名字来源于"哈皮"，是 [Happy](https://github.com/slopus/happy) 的中文音译。感谢原项目的杰出贡献。