Hapi 远程控制配置指南

简介

Hapi 是一个本地优先的应用，允许用户在本地运行 Claude Code / Codex / Gemini 会话，同时通过 Web、PWA 或 Telegram Mini App 进行远程控制。

核心功能

• 在本地和远程环境间无缝切换
• 从任意设备远程发起会话
• 移动端任务监控和管理
• 远程审批/拒绝工具权限
• 文件浏览和 Git Diff 查看
• 待办事项列表进度跟踪
• 多后端支持（Claude Code、Codex、Gemini）

安装步骤

第一步：安装 Hapi

前提条件： 已安装 Node.js 18+

快速启动：

npx @twsxtd/hapi server

重要

启动后请保存显示的 Token 凭据，连接服务时需要使用。

第二步：启动 AI 会话

启动所需的 AI 服务：

hapi claude    # Claude Code
hapi codex     # Codex
hapi gemini    # Gemini

成功启动后，前端会显示连接状态。本地网络访问地址：http://<server-ip>:3006

Cloudflare Tunnel 配置（公网访问）

前提条件

• 域名
• 免费 Cloudflare 账号

配置步骤

1. 登录 Cloudflare Zero Trust 控制台
2. 创建新的 Tunnel
3. 安装 cloudflared 客户端
4. 配置隧道名称
5. 设置公共主机名
6. 配置服务地址：localhost:3006
7. 完成设置

使用方式

1. 通过浏览器访问：http://localhost:3006（本地）或公共域名
2. 输入 Token 登录
3. 选择 AI 后端
4. 开始远程控制操作

安全建议

• 妥善保管 Token
• 公网访问时启用 Cloudflare 安全功能
• 定期更换 Token
• 仅在受信任的网络上使用

常见问题

连接问题

• 验证服务状态
• 检查防火墙设置
• 确认 Token 准确性

Cloudflare 配置失败

• 确认域名配置正确
• 检查 cloudflared 安装
• 查看日志排查问题

进阶优化

配置 Cloudflare 优选 IP 可显著降低延迟，从数百毫秒降至几十毫秒。详见 Hapi 进阶优化。