嘎妞连接器 ganiu-remote

让嘎妞 App 直接指挥你电脑上的 AI 编程助手 —— 手机上说一句话，电脑上的 Claude Code / Codex / Hermes 就开干，结果回到手机。

两条通道，装一次都有：

通道	走哪	费用	适用
中继	经嘎妞服务器（wss://）	会员功能	人在外面，手机和电脑不在同一网络
直连	局域网 HTTP + mDNS	免费	手机和电脑连同一个 WiFi

同一个包、同一份代码，Windows / Linux / macOS 都能跑，不需要分平台安装两套。

---

安装

pip install ganiu-remote
ganiu-remote --version    # ganiu-remote 2.0.0

需要 Python 3.10 及以上。

快速开始

1. 中继模式（异地也能用）

在 App 里进入「遥控器 → 连接器」，复制配对 token，然后：

ganiu-remote run --mode relay --token <你的token>

看到这些日志就成功了：

✅ 中继通道已连接
认证成功  user=98  connector=conn-xxxx
能力上报: claude_code/codex/hermes

不想每次带 token，可以写进环境变量：

export GANIU_REMOTE_TOKEN=<你的token>      # Windows: setx GANIU_REMOTE_TOKEN "..."
ganiu-remote run --mode relay

2. 直连模式（同一个 WiFi，免费）

电脑端

ganiu-remote run --mode direct

手机端：App → 遥控器 → 局域网直连 → 申请配对码 → 点「扫描并配对」

配对码 60 秒有效、一次性。配对成功后连接器会换发一个新的直连 token，旧的立刻失效。

如果 App 扫不到设备（常见于公司网络禁 mDNS），可以直接在 App 里手输电脑 IP + 配对码，功能完全一样。

3. 双通道一起跑

ganiu-remote run --mode both

一条通道挂了不影响另一条 —— 中继没配 token 时只会打印警告，直连照常工作。

---

命令行

ganiu-remote discover                 # 探测本机有哪些 agent 可用
ganiu-remote run --mode auto          # 有 token 走中继，没 token 走直连
ganiu-remote direct                   # 只跑直连
ganiu-remote pair --code 1a2b3c4d     # 命令行完成配对（等价于 App 扫码）
ganiu-remote config --hermes-key KEY  # 配置本地 Hermes 网关 key

connect 是 v1 留下的兼容命令，新装不用它。

---

支持的 Agent

Agent	要求
Claude Code	本机装好 claude 并已登录
Codex	本机装好 codex 并已登录
Hermes	本机跑着 Hermes，ganiu-remote config --hermes-key 填过 key
OpenAI 兼容端点	用 --openai-url / --openai-key / --openai-model 配任意第三方 API

用 ganiu-remote discover 可以随时看每个 agent 的 available 和 logged_in。

---

配置文件

位置：~/.ganiu-remote/config.json（Windows：%USERPROFILE%\.ganiu-remote\config.json）

可以用环境变量覆盖：

变量	作用
GANIU_REMOTE_HOME	换配置目录
GANIU_REMOTE_URL	换中继地址
GANIU_REMOTE_TOKEN	配对 token
GANIU_DIRECT_PORT	直连端口（默认 18792）
GANIU_CONNECTOR_ID	连接器 ID（通常不用改）

从 1.x 升级上来会自动迁移，迁移前会把老配置备份成 config.json.bak-v1。

---

常见问题

连不上中继，报 timed out during handshake 检查 ganiu-remote config 里的 relay_url 是不是 wss://ganiu.paihuai.vip/im/gateway。1.x 的默认值是一个明文端口，永远连不上。

手机扫不到设备

1. 确认在同一个 WiFi（不是 5G 蜂窝）
2. Windows 首次运行要允许「专用网络」访问；已经点错了就跑一次：

   netsh advfirewall firewall add rule name="Ganiu Relay Direct" dir=in action=allow protocol=TCP localport=18792 profile=private
   

3. 都不行就手输 IP —— 功能一样

discover 里 agent 都是 unavailable CLI 没在 PATH 里，或者装在 WSL / 容器里而连接器装在 Windows。用 where claude（Windows）或 which claude（Linux）确认。

端口 18792 被占用

ganiu-remote run --mode direct --direct-port 18888

---

安全说明

• 直连 token 只存在本机，配对成功后立即轮换，旧 token 作废
• 配对码 60 秒过期、一次性、连续试错会锁定
• 连接器不会把你的 token / key 上送到任何地方；hermes_key 只从本机 .env 读
• 中继通道的详细威胁模型见 docs/direct-security.md

---

许可

私有软件，随嘎妞 App 一起授权使用。