hapi是个很好的项目 我开发的 HAPI 开源了：随时随地访问 Claude Code / Codex / Gemini
就是文档比较复杂，刚开始不好看明白,这导致hapi上手配置对很多人来说成为了一个门槛。我把最重要的内容总结一下，方便大家理解和使用。也请作者 @weishu 纠错
一 下载和安装
- GitHub - tiann/hapi: App for Claude Code / Codex / Gemini / OpenCode, vibe coding anytime, anywhere
- 安装 npm install -g @twsxtd/hapi
- 安装你喜欢的编程工具claude code/codex/gemini/opencode
二 中继模式运行
使用作者提供的域名和隧道，建立中继服务器
如果你希望集中管理所有的编程机器和编程客户端会话，需要有一台机器作为中继，这台机器可以配置很低，只做中继而不安装编程工具。在中继机上运行：
hapi hub --relay
第一次运行会生成一个api token，这个token是后续所有客户端连接的密码，必须记下来。这个token也会存到.hapi/setting.json文件的cliApiToken字段，忘记了可以在这里看
默认情况下，hapi的web服务绑定在本机 127.0.0.1的3006端口，除了自己，是无法被其他人连接的。此时他会连接 relay.hapi.run ，使用hapi作者提供的中转服务器，建立隧道(使用 WireGuard + TLS 进行端到端加密)，分配一个https://XXXXX.relay.hapi.run 这样子域名用来后续访问。
HAPI Hub starting…
[Hub] CLI_API_TOKEN: loaded from settings.json
[Hub] HAPI_LISTEN_HOST: 127.0.0.1 (default)
[Hub] HAPI_LISTEN_PORT: 3006 (default)
[Hub] HAPI_PUBLIC_URL: http://localhost:3006 (default)
[Hub] Telegram: disabled (no TELEGRAM_BOT_TOKEN)
[Hub] Tunnel: enabled (–relay), API: relay.hapi.run
[Web] hub listening on 127.0.0.1:3006
[Web] public URL: http://localhost:3006
[Web] Hub listening on :3006
[Web] Local: http://localhost:3006
[Tunnel] Starting tunnel to http://localhost:3006…
[Tunnel] 2026/02/26 08:41:16 tunwg: initiating handshake to server
[Tunnel] 2026/02/26 08:41:17 tunwg: http://localhost:3006 <= https://xxxxx.relay.hapi.run
如果你的这台服务器在境外vps上或者可以连接WireGuard服务的网络上，下面可能会看到：
HAPI Hub is ready!
[Web] Public: https://xxxxxx.relay.hapi.run
Open in browser:
https ://app.hapi.run/?hub=https%3A%2F%2Fxxxxxx.relay.hapi.run&token=XXXXXXXi5fpNIDuvtnN5_J23bAoeA5Z9Mw9IXXXXXXX
然后还会显示一个二维码
看到这些内容，说明隧道成功建立，可以用手机或电脑浏览器去访问这个地址：
https ://app.hapi.run/?hub=https%3A%2F%2Fxxxxxx.relay.hapi.run&token=XXXXXXXi5fpNIDuvtnN5_J23bAoeA5Z9Mw9IXXXXXXX
出现的界面就是中继服务器的控制界面。生成的二维码用手机扫码之后实际也是打开这个地址，主要是避免你自己去输入这么长的url。
如果你直接访问 http://xxxxxx.relay.hapi.run 会提示你输入之前这个服务器生成的api token，输入以后看到的也是上面的界面
但这个时候，访问你的中继服务器界面上是没有任何编程客户端的显示的，也无法添加新的编程会话（你会在新增界面上看到“无可用机器”的提示）。因为现在这个服务器只是以中继模式运行，还没有任何客户端或者主机连接上来。
运行客户端和连接中继服务器
-
在中继服务器上进行编程
如果你在中继服务器另开一个termial会话，运行
hapi或 hapi codex/gemini/opencode
那么你会马上进入hapi封装的对应开发客户端,连接到本机的 hapi hub 服务上。这个时候你去看中继服务器刚才那个链接，你会发现这个会话已经出现了。新增会话的页面上，也会出现这台机器。 -
在其他机器上进行编程
如果你这台服务器只是一台不用来开发的vps,只是用来作为中转站，或者你不想在中继服务器上运行编程客户端。那么你就需要在你的开发用机上做额外配置，让你的开发用机能连上这台中继服务器，再被访问和控制。首先要配置环境变量：
export HAPI_API_URL=“https://xxxxxx.relay.hapi.run” <—这个是前面正常工作做中继服务器的域名。由于目前hapi hub固定绑定在localhost上，因此实际你用https://ip:3006是访问不了的，需要用前面映射的https://xxxxxx.relay.hapi.run 是没问题的。
export CLI_API_TOKEN=“your-token-here” <—这个token,就是是建立中继服务器时生成api token。
设置好以后，启动hapi,那么这个claude的会话就会连接到中继服务器，在中继服务器域名的网页上就可以看到了。
- 如何在web界面上新增会话
如果是在中继服务器之外的主机上，希望实现web界面新增编程会话，需要把这台编程主机注册到中继服务器上。配置好HAPI_API_URL 和 CLI_API_TOKEN环境变量后，用下面的指令
hapi runner start
如果一切正常，你会在web页面上新增会话页面中，看到这台机器。在新增会话上指定了工作目录后，就可以新开一个编程客户端会话并行开发了。
如果你无法连接作者提供的隧道运行中继服务器，或者希望完全自建中继服务器。
最常见的情况是你在国内，或者在被封禁了WireGaurd的网络运行hapi hub --relay，你只会一直看到
HAPI Hub is ready!
[Tunnel] Waiting for trusted TLS certificate…
[Tunnel] Waiting for trusted TLS certificate…
[Tunnel] 2026/02/26 08:43:05 tunwg: initiating handshake to server
[Tunnel] Waiting for trusted TLS certificate…
[Tunnel] Waiting for trusted TLS certificate…
说明连接不上作者提供的relay.hapi.run这个api服务器网络。
简单方式，需要你的中继服务器具有互联网公开ip
配置环境变量
export HAPI_LISTEN_HOST=1.1.1.1 (你这个服务器的公开ip地址）
然后运行 hapi hub
[Hub] CLI_API_TOKEN: loaded from settings.json
[Hub] HAPI_LISTEN_HOST: 1.1.1.1 (environment)
[Hub] HAPI_LISTEN_PORT: 3006 (default)
[Hub] HAPI_PUBLIC_URL: http://localhost:3006 (default)
[Hub] Telegram: disabled (no TELEGRAM_BOT_TOKEN)
[Hub] Tunnel: disabled (default)
[Web] hub listening on 1.1.1.1:3006
[Web] public URL: http://localhost:3006
[Web] Hub listening on :3006
[Web] Local: http://localhost:3006
在你开发机器上设置把这台机器的ip作为环境变量
export HAPI_API_URL=“http://1.1.1.1:3006”
export CLI_API_TOKEN=“your-token-here”
然后运行hapi
好了，现在你这个会话连接到自己的中继服务器上了，当然也可用runner把这个机器也注册到这台中继服务器上。
复杂方式，但是可以适用开发机在内网没有公开ip的情况
用cloudflared来开一条反向隧道。通过loudflared的隧道，映射外部域名和链路到本地的 localhost:3006。从而实现外部能穿透访问到内网主讲上的claude。这种情况无需开–relay，运行hapi hub即可。cloudflared的下载和隧道开启说明都在这里：
等配置好了隧道，你这台中继机器也会有一个自己的域名，后面用这个域名当作HAPI_API_URL，其他用法都是一样的了。
hapi hub和hapi hub --relay的不同
如果用hapi hub启动，那么hapi不会连接作者提供的有隧道中继服务器relay.hapi.run，需要自己修改环境变量对外提供服务，或者开反向隧道才能从远程访问外，否则你只能用本机浏览器去访问3006端口。注意，因为hapi这个项目是c/s模式的，即便是你只有一台机器想用手机远程访问控制，也必须先使用hapi hub或者hapi hub relay。
其他功能
比如团队合作时可以用命名空间来区分验证和会话，使用ElevenLabs api语言输入 hapi/docs/guide/voice-assistant.md at main · tiann/hapi · GitHub ，接入Telegram通知hapi/docs/guide/installation.md at main · tiann/hapi · GitHub
如何让中继服务器和客户端runner成为系统服务自动启动,如何把浏览器页面存为pwa应用 hapi/docs/guide/pwa.md at main · tiann/hapi · GitHub 都是基操，也不赘述。
