HAPI - 本地优先的 AI 代码助手远程控制服务¶

简介¶

HAPI 是一个本地优先的替代方案，用于远程控制 Claude Code / Codex / Gemini / OpenCode 等 AI 编程助手。与 Happy 不同，HAPI 直接包装你的 AI agent 而不是替换它，保持相同的终端和体验。

快速开始¶

使用加密中继（推荐）¶

npx @twsxtd/hapi hub --relay
npx @twsxtd/hapi

终端会显示 URL 和二维码，用手机扫描或打开 URL 即可访问。

中继使用 WireGuard + TLS 进行端到端加密，数据从设备到机器全程加密。

自建服务¶

Cloudflare Tunnel¶

npx @twsxtd/hapi hub --tunnel

Tailscale¶

npx @twsxtd/hapi hub --tailscale

使用本站自建服务器¶

注意：本站原有的 Happy Coder Server 由于开源社区不活跃，现已迁移至 HAPI 架构。

配置步骤¶

1. 设置环境变量

export HAPI_API_URL="https://happy.iomics.pro/"

1. 登录认证

hapi auth login

输入格式：<API_TOKEN>:<namespace>

例如：abcd1234efgh5678:myproject

1. 访问 Web 界面

访问 https://happy.iomics.pro/，输入相同的 <API_TOKEN>:<namespace> 即可使用。

获取密钥¶

密钥请联系 Haohao 获取。

主要特性¶

• 无缝切换 - 本地工作，需要时切换到远程，随时切换回来，无上下文丢失
• 原生优先 - 包装你的 AI agent 而非替换，相同的终端、相同的体验
• AFK 不停工 - 离开办公桌？通过手机一键批准 AI 请求
• 你的 AI，你选择 - Claude Code、Codex、Cursor Agent、Gemini、OpenCode 统一工作流
• 随处终端 - 从手机或浏览器运行命令，直接连接到工作机器
• 语音控制 - 使用内置语音助手免提与 AI agent 对话

客户端访问¶

Web/PWA¶

访问终端显示的 URL，推荐添加到主屏幕作为 PWA 使用。

Telegram Mini App¶

通过 Telegram 小程序访问（需要配置）。

与 Happy 的区别¶

配置文件¶

HAPI 配置文件通常位于 ~/.hapi/config.json，包含：

• 服务器端口
• 加密密钥
• 中继设置
• Agent 配置

故障排除¶

端口冲突¶

如果默认端口被占用，可以通过环境变量 PORT 指定其他端口。

连接失败¶

• 检查防火墙设置
• 确认 Cloudflare Tunnel 或 Tailscale 配置正确
• 验证中继服务状态

Agent 不工作¶

• 确认本地 AI agent 已正确安装
• 检查 PATH 环境变量
• 查看终端日志获取详细错误信息

参考链接¶

• 官方仓库：https://github.com/tiann/hapi
• 官方文档：https://github.com/tiann/hapi/tree/main/docs/guide
• Why Not Happy：https://github.com/tiann/hapi/blob/main/docs/guide/why-hapi.md