---

手机随时随地写代码：国内云服务器部署 HAPI + Claude Code 踩坑实战

需求

在手机上也能和Claude Code交互，散步和旅行时不用打开电脑就可以干活开发。

选型

HAPI 是一个本地优先的远程 Vibe Coding 工具。它可以“包装”你的 AI 编程代理（如 Claude Code），让你能够在手机网页或小程序上，获得与终端一致的操作体验和历史记录同步。

痛点背景：
官方推荐的快速启动方式是使用 hapi hub --relay 连接海外官方中继服务器。但在国内网络环境下，这往往会导致连接超时，卡在 Waiting for trusted TLS certificate...。

如果你手中有一台国内云服务器，完全可以将其同时作为中继站（Hub）和执行端（Runner）。本文将完整复盘我真实的配置、踩坑与部署流程，帮你避开进程冲突陷阱，实现完美的远程编程自由。

---

核心架构概念速览

在动手前，先简单理解服务器上运行的两个核心组件：

1. HAPI Hub（中继中心）：整个架构的中央协调器。它占用端口监听请求，负责在手机前端和后台代码环境之间同步实时数据。
2. HAPI Runner（后台执行器）：一个后台常驻服务。它向 Hub 注册待命，允许你直接用手机远程唤醒（Spawn）并创建一个全新的 Claude Code 会话。

---

Step 1: 环境准备

首先，确保云服务器上已经安装了 Node.js 和编程助手（如 Claude Code）。接着，安装 HAPI 以及用于进程管理的 pm2。

# 安装 HAPI
npm install -g @twsxtd/hapi --registry=https://registry.npmmirror.com

# 安装 pm2 用于进程守护
npm install -g pm2

---

Step 2: 启动并配置 Hub（中继中心）

为了让外网能够访问你的服务器，需要修改默认的监听地址。

1. 临时设置环境变量并首次启动

在终端中执行以下命令（请将 IP 替换为你的服务器公网 IP）：

# 设置监听所有 IPv4 地址
export HAPI_LISTEN_HOST=0.0.0.0
# 设置外部访问的公网 URL
export HAPI_PUBLIC_URL="http://你的公网IP:3006"

# 启动 Hub
hapi hub

关键点： 首次运行后，控制台会打印出 CLI_API_TOKEN。请务必复制并保存好这个 Token，后续无论是配置执行端还是手机登录都需要用到它。

2. 配置持久化

避坑指南：很多新手担心终端关闭后 export 的环境变量会失效。实际上，HAPI 在首次启动时，会自动将配置保存到 ~/.hapi/settings.json 中。你也可以直接使用 vim ~/.hapi/settings.json 修改配置，这比依赖环境变量更稳妥。

确认配置无误后，按 Ctrl+C 停止当前进程。

---

Step 3: 配置 Runner 并进行身份认证

接下来，我们需要让云服务器作为“执行端”接入刚才配置好的 Hub。

常见疑惑：手机访问的 HAPI_PUBLIC_URL 和执行端指向的 HAPI_API_URL 都使用 3006 端口，会冲突吗？
答案：完全不会。真正占用端口的只有 Hub 程序，这两个 URL 只是告诉组件去哪里通信。

设置执行端目标地址并登录验证：

# 告诉 Runner，Hub 的地址在哪里
export HAPI_API_URL="http://你的公网IP:3006"

# 交互式登录
hapi auth login

根据提示输入你刚刚保存的 CLI_API_TOKEN 完成认证。

---

Step 4: 使用 PM2 部署与排错（重点！）

在官方教程中，通常建议用 pm2 start 管理进程。但如果参数解析不当，极易导致端口占用或进程无限重启。

常见的错误现象：

• Hub 报错 EADDRINUSE：提示 3006 端口被占用。这通常是因为之前手动测试时残留了僵尸进程。
• Runner 报错 errored (too many unstable restarts)：Runner 提示启动成功后瞬间退出。这是因为命令参数没被正确传递，被 PM2 当成普通瞬时命令执行了。

最终正确的部署流程

为了确保环境干净，请严格按照以下步骤执行：

1. 彻底清理环境

# 删除 PM2 中所有旧进程记录
pm2 delete all
# 强制杀掉所有残留的 HAPI 进程，释放 3006 端口
pkill -f hapi

2. 启动 Hub

# 使用拆分参数方式启动 Hub
pm2 start hapi --name hapi-hub -- hub

3. 启动 Runner

确保 --foreground 参数被准确传递，防止进程闪退循环：

# 使用拆分参数方式启动 Runner
pm2 start hapi --name hapi-runner -- runner start --foreground

4. 验证与保存

pm2 status

此时 hapi-hub 和 hapi-runner 的 status 应该都是绿色的 online。最后运行 pm2 save，确保服务器重启后自动拉起服务。

注意：记得在云服务器的安全组/防火墙中放行 3006 端口。

---

Step 5: 手机端远程接管体验

手机登场：

1. 访问：在手机浏览器输入 http://你的公网IP:3006。
2. 登录：填入你的 CLI_API_TOKEN，中继地址填入你的 IP 与 3006 端口。
3. 连接：点击 “Machines”（机器列表），你会看到云服务器在线待命。
4. 开始：点击即可远程 Spawn 新的 Claude Code 会话。你可以直接在手机上写代码、查看 Git diff、或者远程审批文件读写权限。

💡 体验优化小贴士：

• PWA 化：在手机浏览器中选择“添加到主屏幕”，可获得全屏沉浸体验。
• 多端协同：如果你的本地电脑（如 Windows）也想接入，只需在本地机器配置环境变量并指向云端 Hub，即可实现多设备协同控制。

Reference

1. Hapi-使用手机远程你的Claude Code
2. HAPI方案
3. HAPI文档