hapi：把 Claude Code 和 Codex 的会话搬到手机上的本地优先方案
Claude Code / Codex / Gemini / OpenCode 的应用程序，随时随地进行氛围编码。 HAPI 在本地运行官方 Claude Code / Codex / Cursor Agent / Grok Build / OpenCode 会话，并通过 Web / PWA / Telegram Mini 应用程序远程控制它们。
秒懂
- 它是什么？
- hapi 是一个本地优先的远程控制层，它包装而不是替换官方 AI 编程代理，让你在手机或浏览器里继续终端里的会话。本文基于 README 和仓库信息，分析它的机制、上手方式与适用边界。
- 适合谁用？
- hapi 适合那些已经重度使用 Claude Code、Codex 或 Cursor Agent，并且经常需要在离开电脑时审批请求或查看进度的开发者。它不适合那些想要一个全托管云端服务、不愿自己处理中继或隧道配置的人。
- 能商用吗？
- 可以，但条件严格。AGPL-3.0 是网络 copyleft 许可证：如果别人通过网络使用你修改过的版本（例如作为托管服务），你必须以同一许可证向他们提供源代码。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是「人不在电脑前」的痛点
AI 编程代理通常跑在本地终端里，会话状态、审批请求、文件读写都绑定在那台机器上。一旦你离开工位，就失去了对会话的控制。hapi 想改变这个局面：它让你在手机上通过 Web 或 Telegram Mini App 继续同一个会话，批准代理的请求，甚至执行命令。它明确把自己定位成 Happy 的本地优先替代品，README 里直接给了对比文档的链接。目标用户很清晰：那些已经用官方代理工作流、不想换工具但需要远程操作能力的人。
包装而非替换：hapi 的核心设计选择
hapi 没有自己实现 AI 代理，而是包装官方的 Claude Code、Codex、Cursor Agent 等程序。这意味着你看到的终端输出、交互方式、上下文管理都来自原版代理，hapi 只负责传输和转发。README 用「Native First」来描述这个设计，强调「Same terminal, same experience」。这个选择降低了迁移成本，但也意味着 hapi 的能力上限受限于每个代理官方 CLI 的功能。如果某个代理不支持远程审批或流式输出，hapi 也无法凭空补上。
数据流：从本地终端到手机屏幕
根据 README，hapi 的运行方式是一个 hub 进程，它启动代理会话，并通过中继把数据加密传输到远程客户端。中继使用 WireGuard 加 TLS 实现端到端加密，数据从你的设备到你的机器全程加密。你启动 hub 后，终端会显示一个 URL 和二维码，手机扫码或打开 URL 即可连接。hapi 还支持通过 `--workspace-root` 开启工作区浏览功能，允许在限定目录树内浏览文件并启动会话。整个架构是本地优先的，中继只负责转发加密数据，不存储会话内容。
上手：两条命令，一个二维码
安装和启动非常简单。README 给出的命令是 `npx @twsxtd/hapi hub --relay` 启动带中继的 hub，然后直接运行 `npx @twsxtd/hapi` 启动 Claude Code。`hapi server` 作为别名仍然支持。如果你不想用官方中继，文档提供了自托管选项，比如 Cloudflare Tunnel 或 Tailscale，细节在 installation 文档里。从源码构建需要 Bun 1.4.0，执行 `bun install` 和 `bun run build:single-exe` 即可。整个流程对熟悉 Node 生态的开发者来说几乎没有门槛。
支持多代理，但每个代理的成熟度可能不同
hapi 声称支持 Claude Code、Codex、Cursor Agent、Grok Build、OpenCode、Kimi、Copilot、Antigravity、Pi、DeepSeek Harness，共十种代理。这是一个很长的列表，但 README 并没有说明每种代理的集成深度。像 Claude Code 和 Codex 这类成熟工具，hapi 的包装可能比较稳定；而 Grok Build、Antigravity 这类较新的工具，官方 CLI 本身还在快速变化，hapi 的适配可能需要频繁更新。在采用前，你应该针对自己常用的代理做一次真实会话测试，而不是假设所有代理都有相同的体验。
局限：本地优先意味着你要自己承担网络和运维
hapi 的本地优先设计带来一个直接代价：你必须自己处理网络可达性。官方中继虽然简化了连接，但它是第三方服务，存在可用性和隐私的考量。自托管方案（Cloudflare Tunnel、Tailscale）需要你有一定的网络配置经验。另一个限制是，远程控制只是把终端搬到了手机上，代理本身仍然运行在你的工作机器上，如果那台机器关机或断网，远程控制就失效。此外，语音控制功能虽然内置，但 README 没有说明它支持哪些语言或命令语法，实际效果需要实测。
替代方案：Happy 与云端 IDE
hapi 的直接替代是它致敬的 Happy，README 特别提供了「Why Not Happy?」的对比文档，说明两者存在关键差异。Happy 可能更偏向云端托管，而 hapi 强调本地优先。另一个广义替代是云端 IDE 或远程开发环境，比如 GitHub Codespaces 或 JetBrains Space，它们把整个开发环境放在云端，你从浏览器或客户端访问。这种方案的优势是环境本身在云端，不依赖你的本地机器；但代价是你需要迁移工作流，可能失去本地文件系统的直接访问。hapi 则保持你现有的本地工作流，只增加一个远程控制层。
维护与许可证：AGPL-3.0 的影响
hapi 使用 AGPL-3.0 许可证，这是一个对修改和分发要求较严格的许可证。如果你只是内部使用，不修改代码，那么影响很小；但如果你修改了 hapi 并对外提供服务或分发，你需要以 AGPL-3.0 许可开源你的修改。这个条款对商业公司尤其重要。从维护角度看，项目最近更新频繁（v0.29.0 于 2026-08-19 发布，v0.28.0 和 v0.27.3 分别在前几天发布），说明开发活跃，但这也意味着 API 和配置可能变化较快，升级时需留意 changelog。原生 iOS 和 Android 客户端还在开发中，目前只能通过 Web 或 PWA 使用，这可能是移动端体验的一个限制。
编辑结论
hapi 适合那些已经重度使用 Claude Code、Codex 或 Cursor Agent，并且经常需要在离开电脑时审批请求或查看进度的开发者。它不适合那些想要一个全托管云端服务、不愿自己处理中继或隧道配置的人。在采用之前，先确认你使用的代理版本与 hapi 的兼容性，特别是 Cursor Agent 和 Grok Build 这类更新、变化更快的工具。另外，AGPL-3.0 许可证意味着如果你修改并分发 hapi，需要开源你的修改，这对内部工具使用者影响不大，但如果你计划基于它构建商业服务，必须仔细评估。最后，实际测试一下中继的延迟和稳定性，因为 WireGuard 加 TLS 的加密链路虽然安全，但网络质量直接影响远程操作的流畅度。
社区笔记