HAPI 远程控制台
在本机运行各类编码 Agent，再用手机、网页或 Telegram 随时接手，无需重启会话。
- 源仓库
- tiann/hapi
- Star 数
- ★ 5.3k
- 最近更新
- 1 天前
- License
- AGPL-3.0
- 主语言
- TypeScript
- FA 评分
- 62/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude CodeChatGPT（部分支持）
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 下班离开工位后，需要远程批准 Claude Code 权限请求的开发者
- 不适合
- 只想用浏览器、完全不碰终端的用户
- 需要完全离线或禁止中继转发的团队
- 不愿部署 hub 或配置自托管隧道的个人
- 源码审查
- 62/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
HAPI 是一个本地优先的远程控制层，包裹官方 Claude Code、Codex、Cursor Agent、Grok Build、OpenCode、Kimi、Copilot、Antigravity、Pi 与 DeepSeek Harness 等 Agent 会话，让你在终端和移动端之间来回切换而不丢失上下文。它由 hub 服务、Web/PWA 前端、SwiftUI/UIKit 与 Kotlin Compose 原生客户端以及 Telegram Mini App 组成。安全性上，hub 可配合基于 WireGuard + TLS 的中继实现设备到本机的端到端加密；也可改用 Cloudflare Tunnel、Tailscale 等自托管方式暴露服务。部署边界在你的本机或自管服务器：通过 npx 启动 hub，再用二维码配对手机或打开网页 URL。除了聊天，它还提供一次性批准请求、在手机浏览器里执行终端命令、语音听写与网页语音助手，以及通过 hapi runner start --workspace-root 开启的工作区文件浏览。
npx @twsxtd/hapi hub --relay 在本机启动 hub（hapi server 为别名），输出一个网页 URL 与两个二维码；npx @twsxtd/hapi 让你选择 Agent 并开新会话，hapi claude、hapi codex 等则直接启动指定 Agent。hub 包裹原 Agent 进程，把会话内容通过中继推送到 iOS/Android 原生客户端、Web/PWA 或 Telegram Mini App，并把手机端的输入、批准与命令回送终端。用户在手机上可一键批准 AI 请求、创建会话、浏览文件、对输入做听写或用网页语音助手口述指令，还能在手机浏览器起 shell 命令。使用 hapi runner start --workspace-root <path> 可选择开放受限的目录树，在允许的子目录里新建会话。Codex 0.154.0+ 支持终端与手机同时共享同一会话。
- 下班离开工位后，需要远程批准 Claude Code 权限请求的开发者
- 想用手机查看并继续 Codex 会话，又不愿在终端里重启上下文的工程师
- 需要在服务器或家用主机上跑 Agent、只用浏览器或 iPhone 操作的自托管用户
- 习惯用语音输入下指令、不愿长时间打字的移动端用户
- 希望把多个编码 Agent（Claude Code、OpenCode、Kimi 等）统一到一套远程操作界面的团队
- 在受限目录中开子项目会话、需要先划定工作区可见范围的运维或平台工程师
如何安装或部署这个 Agent？
需要 Node.js 环境以运行 npx；从源码构建则要求 Bun 1.4.0。
用 npx 直接启动 hub（带端到端加密中继）：
npx @twsxtd/hapi hub --relay从源码构建单文件可执行程序：
bun install
bun run build:single-exe原生 App 的构建与配对步骤见 ios/README.md 与 android/README.md；自托管部署（Cloudflare Tunnel、Tailscale）见 docs/guide/installation.md。
如何使用这个 Agent？
启动 hub 后，终端会显示一个网页 URL 和两个二维码：浏览器打开 URL，或用配套二维码在原生 App 中配对。
直接启动指定 Agent：
hapi claude
hapi codex不带参数时由界面选择 Agent；脚本中必须显式写出 Agent。查看命令与支持的 Agent 列表：
hapi --help开启受限工作区浏览并新建会话：
hapi runner start --workspace-root /path/to/project这个 Agent 有哪些优点和局限？
- 会话包裹原始 Agent，保持同一终端与操作习惯，切换到远端不需要重启上下文。
- 中继采用 WireGuard + TLS 做端到端加密，也支持 Cloudflare Tunnel、Tailscale 等自托管方式。
- 原生 iOS/Android 客户端与 Web/PWA、Telegram Mini App 并存，覆盖批准、建会话、文件浏览、听写与推送通知。
- Codex 0.154.0+ 支持终端与手机共享同一会话，两端可并行操作。
- 一个界面统一接入 Claude Code、Codex、Cursor Agent、OpenCode、Kimi、Pi 等多种 Agent。
- 需要自行启动并维护 hub，长期使用还涉及中继或自建隧道，不是开箱即用的托管服务。
- 从源码构建单文件可执行程序要求 Bun 1.4.0，属于额外的运行时约束。
- 共享 Codex 会话依赖 Codex 0.154.0+，旧版本无法使用该能力。
- AGPL-3.0 许可对再分发和衍生作品的合规义务需要评估。
- 中继默认把会话流量经由第三方转发（虽为端到端加密），对数据出境有要求的组织需改自托管方案。
这个 Agent 与同类方案有什么区别？
README 明确把 HAPI 定位为 Happy 的本地优先替代方案（文档 docs/guide/why-hapi.md 说明差异），并说明 HAPI 是“哈皮”的音译、源自 Happy 项目。这是仓库唯一具名对比对象；Cursor Agent、Claude Code、Codex 等属于被包裹的目标 Agent，而非替代品。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| HAPI 远程控制台 当前 | 62 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 5.3k | 1 天前 | TypeScript | Codex · Claude Code |
| Vicoa | 52 · 缺口较多 | 桌面应用免费 + 模型费 | ★ 516 | 10 天前 | Python | Codex · Claude Code |
| OtoDock | 77 · 表现良好 | 自托管服务免费版 + 付费版 | ★ 191 | 6 天前 | Python | Codex · Claude Code |
| Tessera | 74 · 存在缺口 | 桌面应用免费 + 模型费 | ★ 315 | 今天 | TypeScript | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
隐私政策对数据流向（hub、推送中继、FCM/APNs、转写与模型提供商）披露详尽，属数据流透明度的强项；但最小权限方面，runner 默认无 --workspace-root 时可在 OS 账户可达的任意路径浏览与启动会话，且提供远程终端 PTY，权限面很大，仅靠可选参数收紧，故 least_privilege 仅 1。用户确认方面有远程权限审批流程（手机一键批准/拒绝），但未见对破坏性操作或外部副作用的强制确认，给 2。敏感数据处理：令牌 256 位、Android 强制 HTTPS、凭据存平台保护存储、测试环境显式白名单隔离密钥，做得不错；但推送中继仍记录可关联的令牌哈希与源 IP，且私有构建的 FCM 载荷未加密，扣分至 2。依赖安全：仅见 package.json 与 Bun 版本锁定，无依赖审计、锁文件审查或漏洞处置证据，给 1。外部副作用：远程终端、会话生成、附件上传与推送均产生真实外部效果，文档有说明但缺少统一的副作用确认/审计机制，给 1。回滚：有 runner 停止、会话停止、版本交接与 doctor clean，但无会话/数据层面的回滚或撤销机制，给 1。来源归属：README 明确致谢 Happy 原项目并说明 HAPI 为其衍生，LICENSE 为 AGPL-3.0，归属清晰；但发布者身份未经验证，故 2。
自一致性：README、安装、FAQ 对命令（hapi hub、hapi server 别名、runner、doctor）与端口/配置描述基本一致，给 2。依赖可用性：依赖 Bun 1.4.0、外部 agent CLI、tunwg 下载、npm 平台包与 Homebrew tap，任一缺失即不可用，且文档自承镜像可能不同步，给 1。失败信息：FAQ 与 doctor 覆盖连接拒绝、无效令牌、runner 无法启动、agent 未找到等常见故障并给出排查步骤，测试代码也强调扫描失败必须报错而非静默通过，给 2。
受众与场景：面向多 agent（Claude Code、Codex、Cursor、Grok、OpenCode、Kimi 等）与多客户端（iOS/Android/Web/PWA/Telegram），场景覆盖本地、远程、AFK 审批，给 3。能力边界：文档说明远程模式不改变执行位置、笔记本休眠会中断、Windows 需 Bun 1.3.14+ 等边界，但部分能力（共享 Codex 会话、语音）边界描述较简，给 2。触发精度：作为 CLI/服务而非提示词型 Agent，缺少明确的触发条件与作用域定义，给 1。环境适配：覆盖 macOS/Linux/Windows、自托管与中继、Tailscale/Cloudflare 等，但 Windows 与部分平台存在限制，给 2。
信息架构：README 与 docs/guide 下安装、FAQ、隐私、原生应用、部署等分册清晰，给 3。安装说明：npm、npx、Homebrew、预编译二进制、源码构建与 hub/runner 配置齐全，给 3。命名稳定性：存在 hapi server 与 hapi hub 别名并存、包名 @twsxtd/hapi 与仓库名不一致，命名有历史包袱，给 2。示例与 FAQ：FAQ 详尽且含对比表与故障排查，给 3。已知限制：FAQ 提到休眠、LAN 绑定、Windows PTY 等限制，但缺少集中的限制清单，给 2。许可证：LICENSE 为完整 AGPL-3.0 文本，FAQ 声明 AGPL-3.0-only，给 3。版本与变更日志：仅见发布工作流与版本号输入，未见 CHANGELOG，给 1。维护责任：SECURITY.md 仅一行指向安全公告，无维护者、支持范围或 SLA 说明，发布者身份亦未验证，给 1。
输出可用性：提供终端、Web、原生应用与审批流，输出形态实用，但本次静态审查未验证实际运行效果，给 2。边际价值：相对直接使用 agent CLI 增加了远程控制、会话持久与多机能力，价值明确但依赖额外部署成本，给 2。成本效益：需自建 hub、runner、HTTPS/中继、多端构建与多机升级同步，运维成本较高，给 1。
主张可追溯：隐私政策与安装文档中的多数主张可对应到仓库文件与配置项，给 2。交叉印证：README、FAQ、安装与隐私文档在命令、端口、推送模式上相互印证，给 2。事实与推断分离：文档区分了自托管数据与外部服务数据，隐私政策明确标注哪些是元数据、哪些加密，给 2；但缺少对安全主张的独立验证材料。
- runner 未配置 --workspace-root 时可在 OS 账户可达的任意路径浏览与启动会话，并暴露远程终端，部署前应显式限制工作区根目录。
- 默认使用官方推送中继 push.hapi.run，会处理设备令牌、加密信封与源 IP 等元数据；私有 FCM 构建的通知载荷未加密，需评估合规影响。
- 依赖 Bun 1.4.0、外部 agent CLI、tunwg 下载与 npm 平台包，安装链路较长，镜像不同步或版本不匹配会导致失败。
- 发布者身份未经验证，且 SECURITY.md 仅一行，缺少维护者、支持范围与漏洞响应承诺。
- 缺少 CHANGELOG 与依赖安全审计证据，升级与漏洞处置路径不透明。
常见问题
HAPI 自己会调用大模型吗，费用怎么算？
必须使用官方中继吗？
--relay 只是快速起步方式；文档给出 Cloudflare Tunnel、Tailscale 等自托管部署路径，可完全绕开该中继。手机上能做什么，不能做什么？
hapi runner start --workspace-root 显式开放目录。支持哪些 Agent？
hapi --help 可查看当前实际支持的列表。