项目档案应用项目

tiann/hapi 是什么？用途、安装与使用指南

HAPI 是一个本地优先的 AI 编程助手远程控制应用，支持 Claude Code、Codex、Gemini、OpenCode 等模型。用户可通过 Web、PWA 或 Telegram 从任何设备控制本地运行的 AI 会话，实现无缝切换、手机审批、语音控制和终端访问。本页提供项目介绍、安装指南、使用教程和常见问题解答。

5,093TypeScriptStar 于 2026年3月6日2026年9月19日更新

查看 GitHub 仓库打开项目主页

AI 总结

HAPI 是一个本地优先的 AI 编程助手远程控制平台，支持 Claude Code、Codex、Gemini、OpenCode 等模型，通过 Web/PWA/Telegram 实现跨设备无缝会话管理和终端控制。

中文项目介绍

项目用途：HAPI 允许用户本地运行 AI 编程助手（如 Claude Code、Codex），并通过 Web、PWA 或 Telegram Mini App 从任何设备远程控制它们，实现统一的多模型工作流。解决的问题：传统 AI 助手无法远程操作、会话中断、多模型切换繁琐。HAPI 提供无缝 handoff、会话持久化、手机端审批和语音控制，确保用户离开电脑时 AI 工作不停止。适用场景：开发者可在移动设备上批准 AI 请求、执行终端命令、查看文件更改；支持语音交互进行 hands-free 编程；统一管理不同 AI 后端（Claude、Codex、Cursor、Gemini、OpenCode）。技术特征：本地优先架构，核心组件运行在用户机器；采用 monorepo 设计，使用 Bun 包管理器；实时通信基于 Socket.IO 和 SSE；Hub 提供 REST API 和 SQLite 存储；支持 WireGuard + TLS 端到端加密 relay；可选 Cloudflare Tunnel 或 Tailscale 实现公网访问。

详细信息与使用说明

1. 项目定位与用途

HAPI 是一个本地优先的 AI 代理远程控制应用，旨在让用户通过 Web、PWA 或 Telegram 从任何设备控制本地运行的 AI 编程助手。它支持 Claude Code、Codex、Cursor Agent、Gemini、OpenCode 等多种模型，提供统一的跨设备工作流体验。核心价值在于“本地运行、远程控制”，既保留终端原生体验，又实现移动端便捷操作。用户可在电脑上使用熟悉的 CLI 工具，同时通过手机随时监控、批准请求或执行简单命令，真正实现 vibe coding anytime, anywhere。

2. 解决的问题

HAPI 解决了 AI 编程助手无法远程控制、会话中断、多模型切换繁琐三大痛点。传统方案中，用户必须守在电脑前，切换模型需重启会话，离开即停止。HAPI 通过无缝 handoff 技术实现本地与远程会话的无缝切换，上下文不丢失；支持手机端一键批准 AI 请求，实现 AFK without stopping；并统一不同 AI 后端的接口，简化多模型管理。相比原 Happy 项目，HAPI 强调本地优先，不替换原有代理，而是包装现有 CLI 工具，保持用户肌肉记忆。

3. 适用场景

HAPI 适用于需要灵活控制 AI 编程助手的各类场景：开发者离开座位时，通过手机审批 AI 请求或发送简单指令；在移动设备上执行终端命令直接操作本地开发环境；同时使用多个 AI 模型（如 Claude 写代码、Codex 调试）时，通过统一界面切换；以及通过内置语音助手进行 hands-free 编程，提升效率。此外，团队协作中可通过共享会话链接进行远程协助，或通过 Telegram Mini App 在聊天界面内直接控制 AI，适合远程工作、移动办公和多设备协同场景。

4. 安装方式

HAPI 支持快速启动和自托管两种方式。快速启动：直接运行 `npx @twsxtd/hapi hub --relay` 启动带 E2E 加密的中继服务，再运行 `npx @twsxtd/hapi` 启动 AI 代理，终端会显示 URL 和 QR 码，扫码即可访问。自托管：可通过 Cloudflare Tunnel 或 Tailscale 将 hub 暴露到公网，详细步骤见安装文档。源码构建需 Bun 环境，运行 `bun install` 和 `bun run build:single-exe` 生成单文件可执行程序。注意：需预先安装对应 AI 代理的 CLI 工具（如 claude、codex），仓库中未明确给出具体版本要求。

5. 使用方式

启动 hub 后，扫描终端显示的二维码或打开 URL 用手机浏览器访问 Web 控制台。通过界面可远程监控 AI 会话状态，批准或拒绝请求，查看文件更改，发送消息，甚至访问终端（Linux/macOS）。支持切换不同 AI 后端，无需重启。内置语音助手允许通过语音命令控制 AI。此外，HAPI 提供 Telegram Mini App 集成，可在 Telegram 内直接操作。所有通信均通过加密 relay 保障安全。仓库中未明确给出语音控制的具体命令列表或终端访问的详细权限配置。

6. 补充说明与实现特点

HAPI 采用本地优先架构，核心 AI 代理运行在本地机器，仅将控制面通过 hub 中继到远程设备。通信使用 Socket.IO（CLI-Hub）和 SSE（Web-Hub）确保实时性。Hub 基于 REST API 和 SQLite 存储会话数据。项目为 monorepo，包含 cli、hub、web、shared 等模块，使用 Bun 包管理器。安全方面，relay 采用 WireGuard + TLS 端到端加密。代码开源，遵循 LGPL-3.0 许可，并致敬原 Happy 项目。仓库中未明确给出性能基准、最大并发会话数或企业级部署建议。

思维导图

当前仓库信息不足，或结构不够稳定，暂时没有生成可靠的思维导图。

常见问题

HAPI 是什么？

HAPI 是一个本地优先的 AI 代理远程控制平台，允许你通过 Web、PWA 或 Telegram 从手机或其他设备控制本地运行的 Claude Code、Codex、Gemini 等 AI 编程助手，实现跨设备无缝工作流。

如何安装和启动 HAPI？

确保已安装对应 AI 代理的 CLI 工具（如 claude、codex）。运行 `npx @twsxtd/hapi hub --relay` 启动加密中继服务，再运行 `npx @twsxtd/hapi` 启动 AI 代理。终端会显示 URL 和 QR 码，扫码即可用手机访问。自托管方案（Cloudflare Tunnel、Tailscale）见安装文档。

HAPI 支持哪些 AI 模型？

目前支持 Claude Code、Codex、Cursor Agent、Gemini 和 OpenCode。你可以在 Web 界面中切换不同后端，统一管理多个 AI 编程任务，无需重启会话。

数据通信安全吗？

是的。HAPI 的 relay 服务使用 WireGuard 和 TLS 实现端到端加密，确保数据从你的设备到本地机器全程加密。此外，支持自托管隧道（如 Cloudflare Tunnel、Tailscale）以增强隐私和控制。

是否可以在无图形界面的服务器上使用？

可以。HAPI 的 CLI 组件可在无头环境运行，通过 hub 中继实现远程控制。但需确保服务器能访问互联网或配置隧道服务以暴露 hub 端口，具体网络要求见安装文档。