198 lines
5.5 KiB
Markdown
198 lines
5.5 KiB
Markdown
# Hapi 远程控制配置指南
|
||
|
||
**随时随地远程控制你的 AI 编程助手**
|
||
|
||
> **作者** ：[weishu](<https://github.com/tiann>)**官方文档** ：<https://hapi.run/>
|
||
|
||
📋 简介
|
||
|
||
Hapi 是一个本地优先的应用程序，可以让你在本地运行 Claude Code / Codex / Gemini 会话，并通过 Web / PWA / Telegram Mini App 进行远程控制。这意味着你可以在手机或浏览器上监控和管理你的 AI 编程任务。
|
||
|
||
## 🔗 相关链接
|
||
|
||
资源| 地址
|
||
---|---
|
||
Hapi 官网| <https://hapi.run/>
|
||
Hapi 仓库| <https://github.com/tiann/hapi>
|
||
快速开始| [官方快速开始文档](<https://hapi.run/docs/guide/quick-start>)
|
||
Cloudflare Tunnel 文档| [创建远程隧道](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>)
|
||
|
||
## ✨ 核心功能
|
||
|
||
Hapi 提供以下强大功能：
|
||
|
||
* ✅ **无缝切换** ：在本地原生环境和远程控制之间无缝切换
|
||
* ✅ **远程会话** ：从任何设备发起远程会话
|
||
* ✅ **移动监控** ：通过手机或浏览器监控和管理任务
|
||
* ✅ **权限控制** ：远程批准/拒绝工具权限
|
||
* ✅ **文件浏览** ：浏览文件和查看 git diff
|
||
* ✅ **进度跟踪** ：通过待办事项列表跟踪进度
|
||
* ✅ **多后端支持** ：支持 Claude Code、Codex、Gemini
|
||
|
||
## 🛠️ 安装步骤
|
||
|
||
### 第一步：安装 Hapi
|
||
|
||
💡 前置要求
|
||
|
||
请确保已安装 Node.js 18+ 环境。如需安装，请参考 [Node.js 环境安装](</node/windows>)。
|
||
|
||
访问 [Hapi 官方快速开始文档](<https://hapi.run/docs/guide/quick-start>) 了解详细的安装方法。
|
||
|
||
推荐使用 npx 快速启动 Hapi 服务器：
|
||
|
||
bash
|
||
|
||
|
||
npx @twsxtd/hapi server
|
||
|
||
1
|
||
|
||
启动后会显示 Token 凭证和访问地址。
|
||
|
||
⚠️ 重要提示
|
||
|
||
**请务必保存好 Token 凭证！** 这是你连接和控制 Hapi 服务的唯一凭证。
|
||
|
||
|
||
|
||
### 第二步：启动 AI 会话
|
||
|
||
在项目目录下执行以下命令启动对应的 AI 服务：
|
||
|
||
**启动 Claude Code** ：
|
||
|
||
bash
|
||
|
||
|
||
hapi claude
|
||
|
||
1
|
||
|
||
**启动 Codex** ：
|
||
|
||
bash
|
||
|
||
|
||
hapi codex
|
||
|
||
1
|
||
|
||
**启动 Gemini** ：
|
||
|
||
bash
|
||
|
||
|
||
hapi gemini
|
||
|
||
1
|
||
|
||
|
||
|
||
启动成功后，前端界面会显示连接状态：
|
||
|
||
|
||
|
||
🎉 局域网访问
|
||
|
||
此时你已经可以在本地局域网内通过 `http://<server-ip>:3006` 访问和控制你的 AI 编程助手了！
|
||
|
||
## 🌐 配置 Cloudflare 内网穿透
|
||
|
||
如果你想在任何地方（包括外网）访问你的 Hapi 服务，可以通过 Cloudflare Tunnel 实现内网穿透。
|
||
|
||
### 前置要求
|
||
|
||
* 一个域名（任意域名均可）
|
||
* Cloudflare 账号（免费账号即可）
|
||
|
||
### 配置流程
|
||
|
||
按照 [Cloudflare Tunnel 官方文档](<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/>) 进行配置：
|
||
|
||
**1\. 登录 Cloudflare Zero Trust 控制台**
|
||
|
||
|
||
|
||
**2\. 创建新的 Tunnel**
|
||
|
||
|
||
|
||
**3\. 安装 cloudflared 客户端**
|
||
|
||
|
||
|
||
**4\. 配置隧道名称**
|
||
|
||
|
||
|
||
**5\. 配置公共主机名**
|
||
|
||
|
||
|
||
**6\. 设置服务地址**
|
||
|
||
将服务地址设置为 `localhost:3006`（Hapi 默认端口）
|
||
|
||
|
||
|
||
**7\. 完成配置**
|
||
|
||
|
||
|
||
## ✅ 使用 Hapi
|
||
|
||
配置完成后，你可以：
|
||
|
||
1. **本地访问** ：`http://localhost:3006`
|
||
2. **局域网访问** ：`http://<server-ip>:3006`
|
||
3. **公网访问** ：`https://your-domain.com`（如果配置了 Cloudflare Tunnel）
|
||
|
||
使用步骤：
|
||
|
||
1. 打开浏览器访问 Hapi 地址
|
||
2. 输入 Token 登录
|
||
3. 选择要启动的 AI 后端（Claude / Codex / Gemini）
|
||
4. 开始远程控制你的 AI 编程助手
|
||
|
||
💡 使用技巧
|
||
|
||
* 在手机浏览器中访问可以随时随地监控任务进度
|
||
* 可以安装为 PWA 应用，获得类似原生应用的体验
|
||
* 支持多设备同时连接和控制
|
||
|
||
## 🔒 安全建议
|
||
|
||
* 不要将 Token 泄露给他人
|
||
* 如果使用公网访问，建议启用 Cloudflare 的安全功能（如 Access 策略）
|
||
* 定期更换 Token
|
||
* 仅在可信网络环境下使用
|
||
|
||
## 常见问题
|
||
|
||
### 提示无法连接到服务器？
|
||
|
||
* 检查 Hapi 服务是否正常运行
|
||
* 确认防火墙未阻止 3006 端口
|
||
* 检查 Token 是否正确
|
||
|
||
### Cloudflare Tunnel 配置失败？
|
||
|
||
* 确认域名已正确添加到 Cloudflare
|
||
* 检查 cloudflared 客户端是否正确安装
|
||
* 查看 cloudflared 日志排查问题
|
||
|
||
### 更多问题
|
||
|
||
请查看 [FAQ](</support/faq>) 或访问 [Hapi GitHub Issues](<https://github.com/tiann/hapi/issues>)。
|
||
|
||
## 🚀 进阶优化
|
||
|
||
如果你想进一步提升 Hapi 的访问速度（特别是在国内网络环境下），可以配置 Cloudflare 优选 IP：
|
||
|
||
💡 速度优化
|
||
|
||
通过配置 Cloudflare 优选 IP，可以将访问延迟从几百毫秒降低到几十毫秒，实现接近直连的体验。
|
||
|
||
👉 查看详细教程：[Hapi 进阶：Cloudflare 优选 IP 高速穿透](</apps/hapi-advanced>)
|