常见问题 FAQ
基本问题
Q: 这个工具能做什么？
让你用一个微信账号同时连接多个 AI 工具（Claude Code、Recursive、OpenClaw 等），并在微信里随时切换。无需改 AI 工具的代码，只需修改服务器地址。
Q: 我需要懂编程才能用吗？
不一定。有两种使用方式：
- 桌面应用（下载地址）：双击安装，图形界面，不需要终端
- 命令行版本：需要会打开终端、执行基础命令
如果只是想在微信里和 Claude 聊天，推荐先用桌面版。
Q: 使用前需要准备什么？
需要在微信中开启 ClawBot（龙虾插件）。无需申请审核，更新微信到最新版，进入「我 → 设置 → 插件」找到 ClawBot 开启即可。
ClawBot 是微信官方内置功能，2026 年 3 月上线，目前灰度推送中，部分用户可能暂时看不到插件入口。
Q: 支持群聊消息吗？
取决于微信 iLink API 本身的能力。iLink Hub 会透明转发所有消息类型，只要原始 iLink API 支持的，Hub 都会转发。
Q: 有图形界面版本吗？
有。提供 macOS、Windows、Linux 的桌面应用，见桌面应用安装说明。
Q: 开源协议是什么？可以商用吗？
MIT 协议，免费商用。详见 LICENSE。
安装与启动
Q: macOS 提示「无法验证开发者」，无法打开
这是 macOS Gatekeeper 的安全限制。有两种解决方式：
桌面版：右键点击应用 → 「打开」，然后在弹出对话框里点「打开」。
命令行版：在终端运行：
xattr -rd com.apple.quarantine /usr/local/bin/ilink-hubQ: Linux 运行报错「glibc version not found」
当前预编译二进制要求 glibc 2.17+（CentOS 7+、Ubuntu 16.04+）。如果你的系统版本更老：
- 推荐使用 Docker 方式（不依赖宿主 glibc）
- 或从源码编译
Q: 启动后无法访问 8765 端口
- 检查防火墙/安全组是否开放 8765 端口
- 确认监听地址是
0.0.0.0:8765（而不是127.0.0.1:8765）——后者只允许本机访问 - 验证 Hub 是否正常运行：
curl http://localhost:8765/health
登录问题
Q: 二维码扫了没有反应
- 确认用的是已开通 iLink 的微信账号，普通账号无法授权
- 二维码有效期约 2 分钟，超时后重新运行命令
- 扫码后手机上应该会弹出授权确认页，点确认才算完成
Q: 二维码不显示或显示乱码
终端不支持 Unicode 块字符。解决方式：
- macOS 推荐使用 iTerm2 或系统自带的「终端」应用
- Windows 推荐使用 Windows Terminal
- Docker 场景下用
docker compose logs -f查看容器日志
Q: 登录成功但 Hub 启动后提示「upstream connection failed」
可能原因：
- Token 已过期 → 再次运行
ilink-hub serve完成扫码，或执行ilink-hub login - 网络不通 → 确认服务器可以访问
ilinkai.weixin.qq.com - 数据库路径不一致 → 确认
DATABASE_URL指向同一个数据库文件
客户端问题
Q: 客户端显示在线但收不到消息
- 在微信发送
/list确认该客户端是否为当前活跃路由 - 如果不是，发送
/use <客户端名称>切换 - 检查客户端日志是否有连接错误
Q: 多个客户端同时在线，消息为什么只发给一个？
这是设计行为。Hub 同一时间只有一个「活跃客户端」接收消息，用微信命令 /use <名称> 切换。如需同时发给所有客户端，用 /broadcast <消息内容>。如果只想临时给某个后端发一条消息而不切换当前后端，可用 @<名称> <消息>（会在该后端上新建一个临时会话，详见微信命令）。
Q: 消息到了但回复失败（sendmessage 报错）
通常是 context_token 过期（微信的会话令牌有时间限制）。这是正常现象，用户重新发消息后 Hub 会自动生成新的映射。
Q: ilink-hub-bridge 一直在线但微信发文字没反应
- 确认已对该后端执行
/use <注册时用的名称>，且/list里该客户端为在线 - 查看 bridge 终端：是否有报错、或超时日志
- 配置里
require_text: true时，纯图片/语音不会触发 CLI；先发纯文本测试 - Hub 地址和 Token 是否与注册时输出的一致（注意不要多空格）
Q: 注册时提示「name already exists」
客户端名称已存在。要么换一个名称，要么先在 Web UI 或命令行删除旧客户端。
数据库
Q: 数据库文件在哪里？
由 DATABASE_URL 决定。未设置时默认使用 ~/.ilink-hub/ilink-hub.db（SQLite）。Docker 部署示例中常为卷内的 /data/ilink-hub.db。
Q: 可以从 SQLite 迁移到 PostgreSQL 吗？
目前需要重新登录和重新注册客户端（尚未提供数据迁移工具）。建议从一开始就选好数据库类型。
性能与稳定性
Q: Hub 会因为消息队列满而崩溃吗？
不会。每个客户端的消息队列上限为 200 条，超出时最旧的消息会被丢弃（不影响新消息），服务不会崩溃。
Q: Hub 重启后会丢失消息吗？
内存中尚未被客户端取走的消息会丢失，但客户端注册、路由设置、会话映射等状态已持久化到数据库，重启后无需重新配置。
Q: 多个 Hub 实例可以同时运行吗？
目前不支持（多个实例都会抢占同一个真实 iLink 连接）。单实例已足够大多数使用场景。