HAPI常见问题解答：从安装到高级功能的15个关键问题

【免费下载链接】hapiApp for Claude Code / Codex / Gemini / OpenCode, vibe coding anytime, anywhere项目地址: https://gitcode.com/gh_mirrors/hapi6/hapi

HAPI是一款本地优先、自托管的AI编码代理平台，支持Claude Code、Codex、Cursor Agent等多种AI工具，让你随时随地通过手机监控和控制编码会话，打造更自由高效的开发体验。

一、基础认知：什么是HAPI？

1. HAPI核心功能是什么？

HAPI（哈皮）是"Happy"的中文音译，它是一个开源的本地优先平台，允许你在电脑上启动AI编码会话，并通过手机远程监控和控制这些会话。核心优势在于打破终端限制，让AI编码辅助变得更加灵活自由。

HAPI支持多AI代理协作，为开发流程提供全方位智能支持

2. HAPI支持哪些AI编码工具？

目前HAPI已支持多种主流AI编码工具：

• Claude Code（推荐）
• OpenAI Codex
• Cursor Agent
• Grok Build
• OpenCode

这些工具可通过HAPI统一管理，实现跨平台无缝切换与控制。

3. HAPI是免费使用的吗？

是的，HAPI基于AGPL-3.0-only许可证开源，完全免费使用。所有代码和功能都可以在项目仓库中找到，你还可以根据需求进行二次开发。

二、安装配置：快速上手HAPI

4. 如何安装HAPI？

首先需要克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/hapi6/hapi

具体安装步骤可参考官方文档docs/guide/installation.md，里面包含了不同操作系统的详细配置流程。

5. 需要单独部署hub吗？

不需要。HAPI内置了嵌入式hub，只需在终端运行以下命令即可启动：

hapi hub

hapi server命令仍作为别名被支持，两种方式均可启动服务。

6. 如何从手机访问HAPI？

本地网络访问：

http://<你的电脑IP>:3006

注意：若手机无法连接，需确保hub不是仅监听127.0.0.1。可通过修改~/.hapi/settings.json文件设置listenHost为0.0.0.0，或执行以下命令：

export HAPI_LISTEN_HOST=0.0.0.0

然后重启hapi hub即可实现局域网访问。

HAPI移动界面支持终端操作，让你随时随地控制编码会话

互联网访问：

• 若hub有公网IP，可直接访问（建议通过反向代理使用HTTPS）
• 若处于NAT环境，可设置隧道（Cloudflare Tunnel、Tailscale或ngrok）

三、使用技巧：解锁HAPI强大功能

7. 如何远程审批权限请求？

当AI代理请求权限（如编辑文件）时：

1. 你会收到权限请求通知
2. 在手机上打开HAPI应用
3. 导航到活动会话
4. 批准或拒绝待处理权限

8. 如何接收HAPI通知？

HAPI提供两种通知方式：

1. PWA推送通知- 启用后即使应用关闭也能接收通知
2. Telegram机器人- 参考Telegram设置

9. 可以远程启动会话吗？

可以通过运行器模式实现：

1. 在电脑上执行hapi runner start
2. 你的机器会出现在Web应用的"机器"列表中
3. 从任何地方点击即可生成新会话

10. 如何查看文件变更？

在会话视图中，点击"文件"选项卡可以：

• 浏览项目文件
• 查看git状态
• 查看变更文件的差异对比

HAPI代码查看界面支持语法高亮和文件差异对比

11. 可以从手机向AI发送消息吗？

可以。打开任何会话，使用聊天界面直接向AI代理发送消息。HAPI的聊天界面设计直观，支持代码块、命令执行等多种交互方式。

HAPI聊天界面支持与AI代理直接交互，发送指令和接收反馈

12. 如何使用远程终端？

打开Web应用中的会话，点击"终端"选项卡即可使用远程shell：

• Linux和macOS主机使用Bun的POSIX PTY支持
• Windows主机使用Bun的ConPTY支持（需要Bun 1.3.14或更高版本）

HAPI终端界面支持完整的命令行操作，随时随地控制开发环境

13. 如何使用语音控制功能？

设置ELEVENLABS_API_KEY环境变量，在Web应用中打开会话，点击麦克风按钮即可使用语音控制。详细设置方法见语音助手文档。

四、安全与故障排除

14. 我的数据安全吗？

HAPI采用本地优先设计：

• 所有数据保留在你的机器上
• 不会上传到外部服务器
• 数据库存储在本地~/.hapi/目录

访问令牌（CLI_API_TOKEN）是256位加密生成的，确保了访问安全性。建议通过HTTPS隧道进行外部访问，进一步提升安全性。

15. 遇到"连接被拒绝"错误怎么办？

可按以下步骤排查：

• 确保hub正在运行：hapi hub
• 检查防火墙是否允许3006端口
• 验证HAPI_API_URL是否正确

若问题仍然存在，可运行诊断命令获取详细信息：

hapi doctor

该命令会检查hub连接性、令牌有效性、代理可用性等关键组件状态。

五、高级功能探索

HAPI还支持多账户访问、会话持久化、跨机器管理等高级功能。你可以通过命名空间文档了解如何为团队共享hub设置多账户访问，或参考高级使用指南探索更多隐藏功能。

无论是个人开发者还是团队协作，HAPI都能为你的AI编码工作流带来前所未有的灵活性和便捷性。立即开始探索，体验"随时随地，自由编码"的全新可能！

【免费下载链接】hapiApp for Claude Code / Codex / Gemini / OpenCode, vibe coding anytime, anywhere项目地址: https://gitcode.com/gh_mirrors/hapi6/hapi