小蓝中转站使用文档

Hapi 远程控制 ​

HAPI 适合“终端工作流已经跑通，但你还想从手机、浏览器或另一台设备继续控制同一个会话”的场景。

它本身不是模型 Provider，也不是单独的聊天客户端。HAPI 的作用是把你已经装好的 Claude Code、Codex、Gemini CLI、OpenCode 这类工具包起来，再把会话同步到远端网页或手机端。

HAPI 远程控制关系图

先理解 HAPI 在链路里的位置 ​

接入 HAPI 时，最容易搞混的一点是：HAPI 不替你配置模型网关，模型仍然由底层 CLI 去调用。

也就是说：

先把其中一个 CLI 本地跑通，再上 HAPI，排障会清楚很多。否则你遇到“远程会话打不开”时，很难判断到底是 HAPI 问题，还是底层模型配置根本没通。

下载与安装 ​

官方入口：

HAPI 官方当前给出的安装方式包括：

  • npm install -g @twsxtd/hapi
  • brew install tiann/tap/hapi
  • npx @twsxtd/hapi
  • GitHub Releases 里的预编译二进制

为什么 HAPI 安装时不建议强行用 npm 镜像 ​

HAPI 官方安装页特别提醒：全局安装时优先使用官方 npm registry，因为镜像站有时不会及时同步它依赖的平台包。

这意味着它和前面多数 CLI 不太一样：

  • 对 Claude Code、Codex、普通 npm CLI，镜像通常更稳
  • 对 HAPI，自身安装阶段优先按官方建议走 registry.npmjs.org 更保险

平时已经把 npm registry 切到镜像时，更省事的做法不是全局来回切换，而是只在这一条安装命令里指定官方源：

bash
npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org
hapi --version

这样做的好处是，HAPI 能按官方建议从 registry.npmjs.org 拉依赖，但你平时给其他工具准备的镜像配置不会被改掉。

更习惯先切全局源再装时，也可以这样做：

bash
npm config set registry https://registry.npmjs.org
npm install -g @twsxtd/hapi
hapi --version
npm config set registry https://registry.npmmirror.com

本来就用 Homebrew 时，也可以直接安装：

bash
brew install tiann/tap/hapi
hapi --version

接入前先准备 ​

按 HAPI 官方安装页，先确认你已经装好了至少一种底层 AI CLI：

bash
claude --version
codex --version
gemini --version
opencode --version

不需要四个都装。你准备远程控制哪个，就先把哪个本地跑通。

最常见的一条接入路径 ​

希望从手机或浏览器继续控制 Claude Code 时，常见顺序是：

  1. 先按 Claude Code 部署 把本地网关配置好
  2. 安装 HAPI
  3. 启动 HAPI Hub
  4. 用 hapi 启动会话
  5. 用浏览器或手机打开 HAPI 给出的地址继续控制

控制的是 Codex、Gemini CLI 或 OpenCode 时，就把第 1 步换成对应页面，然后在第 4 步使用相应命令。

启动 HAPI Hub ​

只想本机浏览器访问时：

bash
hapi hub
# 或
hapi hub --no-relay

这一层默认监听的是：

txt
http://localhost:3006

这也是最适合第一次验证的一层。
因为只要本机能打开 http://localhost:3006，就说明 Hub 本身已经起来了，后面再去看 Relay、手机访问或公网入口时，排障范围会小很多。

只是想让同一 Wi-Fi 下的手机或另一台电脑接入，而不是立刻走公网 Relay 时，可以先把监听地址放开：

bash
export HAPI_LISTEN_HOST=0.0.0.0
hapi hub --no-relay

然后在同局域网设备里访问：

txt
http://你的电脑局域网 IP:3006

这样做的意义，是先把“本地局域网访问”和“公网 Relay 访问”拆开。
同局域网能打开，说明 Hub、端口和浏览器这层基本没问题；后面如果外网不稳定，你就知道该继续看 Relay 或公网入口，而不是回头怀疑模型配置。

想让手机或外部网络也能接进来时：

bash
hapi hub --relay
# 或
hapi server --relay

按 HAPI 官方 Quick Start，首次运行时会：

  • 在终端里打印访问地址
  • 显示二维码
  • 生成访问令牌
  • 把令牌保存到 ~/.hapi/settings.json

hapi server 目前仍然是兼容别名，所以你在一些旧教程里看到 hapi server 不代表那篇教程一定错了。
只是现在官方文档已经更多使用 hapi hub 这个名字。

这一层解决的是“远程访问会话”的问题，不是“模型怎么调用”的问题。只要底层 CLI 已经接好了 小蓝中转站，HAPI 就会把那个已有会话同步出来。

启动不同类型的会话 ​

HAPI 官方工作原理页给出了几种常用入口：

bash
hapi              # 启动 Claude Code 会话
hapi codex        # 启动 Codex 会话
hapi gemini       # 启动 Gemini CLI 会话
hapi opencode     # 启动 OpenCode 会话

你要控制哪个 CLI，就用哪条命令。

准备从手机端直接发起新会话时，可以额外启动后台 Runner：

bash
hapi runner start

Runner 的作用是让网页或手机端在你不盯着终端的时候，也能拉起新的会话。

准备长期开着 HAPI 时，也可以顺手看一下 Runner 当前状态和日志目录：

bash
hapi runner status
ls ~/.hapi/logs

这一层看的是“远端能不能发起和接住会话”，不是“模型有没有选对”。
Runner 和日志都正常时，后面的排障就可以更放心地回到底层 CLI。

第一次验证怎么做 ​

第一次建议先从本机验证开始，不要一上来就把问题和公网混在一起：

  1. 底层 CLI 本地单独跑一次，确认能正常走 小蓝中转站
  2. 执行 hapi hub
  3. 在本机浏览器打开 http://localhost:3006
  4. 再执行你对应的会话命令，比如 hapi codex
  5. 在页面里发送一句短消息，例如“请告诉我当前会话是否在线”

本机这一步通了以后，再切到：

bash
hapi hub --relay

然后再让手机或外部浏览器接进来。

只要这一步成功，说明三层都已经打通：

  • CLI 本身能调用模型
  • HAPI Hub 能接住会话
  • 远端页面能把消息送回本机

如果这里失败，也尽量按层看，不要几层一起重装：

  • 本机 CLI 都不能回消息：先回对应 CLI 页面
  • http://localhost:3006 都打不开：先看 HAPI Hub 有没有启动
  • 页面能打开但没有会话：再看你是不是还没执行 hapi、hapi codex 这类会话命令
  • 页面和会话都有，但手机端新建失败：再回到 Runner

使用建议 ​

远程控制和模型网关分开看 ​

当你发现 HAPI 页面能打开，但模型回复失败时，不要第一反应去改 HAPI。

优先拆成两段看：

  1. 底层 CLI 单独运行时，能不能直接走 小蓝中转站
  2. HAPI 只负责把这个已经存在的会话同步出去

这样排障速度会快很多。

给远程场景单独建 Key ​

计划在远端主机、长期运行的开发机或共享机器上用 HAPI 时，建议给底层 CLI 对应的远程环境单独建 Key，例如：

txt
Remote-Claude
Remote-Codex
Remote-OpenCode

这样一旦需要停用远端环境，只需要处理那一把 Key，不会影响你本地桌面或其他设备。

会话稳定后再考虑公网 ​

HAPI 很适合远程操作，但这也意味着你的开发会话可能被放到公网入口后面。正式长期使用前，先确认：

  • 访问令牌保存妥当
  • 不把 ~/.hapi/settings.json 随手同步出去
  • 共享设备上的浏览器会话及时退出

常见问题 ​

页面能打开，但发送消息后没有模型回复 ​

这通常不是 HAPI Hub 地址写错，而是底层 CLI 没有先跑通。

例如你正在用 hapi codex，那就先退出 HAPI，单独回到终端执行 Codex 的最小测试。只有 Codex 本地能正常走 小蓝中转站，HAPI 才有东西可同步。

hapi 能跑，手机端看不到会话 ​

优先检查：

  • Hub 是否已经先启动
  • 你当前是 hapi hub 还是 hapi hub --relay
  • 会话启动命令是否和你要控制的 CLI 对应

如果只是本地模式启动 hapi hub，外部网络设备一般不会直接拿到可访问入口。

准备把 CLI 跑在另一台机器上，而 Hub 不在本机时，还要继续确认这台 CLI 机器有没有正确登录 Hub。
HAPI 官方提供的常用检查命令是：

bash
hapi auth status
hapi auth login

这一层没连上时，看起来也会像“手机看不到会话”，但问题其实不是 Relay，而是 CLI 根本没连到目标 Hub。

是在同一 Wi-Fi 下测试时，别忘了再检查两件事：

  • HAPI_LISTEN_HOST 是否仍然是默认的 127.0.0.1
  • 系统防火墙有没有拦住 3006 端口

这两层没放开时，Hub 在本机可以访问，手机同网段却还是会像“完全找不到页面”。

HAPI 装不上，或者装完命令异常 ​

先看是不是 npm 镜像导致的平台包没有同步齐。HAPI 官方对这一点有明确提醒。

最简单的处理方式通常是：

  1. 临时切回 https://registry.npmjs.org
  2. 重新安装 HAPI
  3. 装完后再把 registry 切回镜像

想用手机直接创建新会话 ​

这不是普通 hapi hub 的职责，通常还需要：

bash
hapi runner start

Runner 没启动时，手机端更适合“接管已有会话”，而不是“凭空创建一条新会话”。

Windows 上为什么只能部分使用 HAPI ​

HAPI 官方 FAQ 当前明确说明，远程终端能力主要面向 macOS 和 Linux。
在 Windows 上使用时，最适合把它理解成“远程接管已经存在的 AI 会话”，而不是完整替代一台 Unix 开发机。

也就是说，Windows 上看到某些远程终端相关能力不完整，并不一定是你配置错了，很多时候是平台支持范围本来就不同。

进阶 ​

已经能稳定远程接入，但还想继续优化入口、网络路径或远端主机部署时，再看 Hapi 进阶：优选 IP 配置。

小蓝中转站使用文档

© 2026 小蓝中转站