FAQ: 常见问题与解决方案

[HK6666]

OpeniLink Hub 常见问题与解决方案

安装部署

Q: 安装后访问页面白屏

原因： 前端资源未构建。

解决：

1. Docker 部署：确保使用的镜像包含前端资源，或使用 release 二进制
2. 源码构建：先构建前端 cd web && pnpm install && pnpm build，再编译 Go

---

Q: 数据库文件在哪？

平台	路径
Linux	~/.local/share/openilink-hub/openilink.db
macOS	~/Library/Application Support/openilink-hub/openilink.db
root/service	/var/lib/openilink-hub/openilink.db

PostgreSQL 模式下由 DATABASE_URL 环境变量指定。

---

Bot 连接

Q: Bot 显示「会话已过期」

原因： 微信登录 session 过期（通常 24 小时不活动后）。

解决： 在 Bot 详情页点击重新扫码登录。

---

Q: Bot 在线但收不到消息

排查步骤：

1. 确认微信端能正常收发消息
2. 查看 Hub 日志确认消息是否到达：在 Bot 详情页查看消息记录
3. 如果消息到了 Hub 但没转发，检查 App 安装状态和事件订阅配置

---

App 相关

Q: 安装 App 后收不到消息事件

排查：

1. 确认 App 订阅了 message 事件（App 详情页可查看）
2. 确认 App Installation 的 scopes 包含 message:read
3. 确认 Installation 状态为 enabled
4. Hub 版本需 ≥ v0.1.1（修复了 builtin App 事件分发问题）

---

Q: WebSocket 连接正常但收不到事件推送

原因（v0.1.0 及之前）： builtin App（如 OpenClaw）注册为内置应用但无 handler，事件分发被 continue 跳过，WebSocket 投递被绕过。

解决： 升级到 v0.1.1+，此版本修复了 builtin App 无 handler 时 fallthrough 到 WebSocket 投递的问题。

---

Q: 发送消息 API 返回 409

{"error":"暂无法发送：需要先收到用户消息","ok":false}

原因： Bot 还没有与目标用户建立过会话上下文（context_token）。

解决： 用户需要先主动发消息给 Bot，建立会话后才能回复。这是微信平台的限制。

---

Q: 发送消息 API 返回 503

{"error":"bot not connected","ok":false}

原因： Bot 不在线。

解决： 登录 Hub 后台，确认 Bot 状态为在线。如果显示离线，重新扫码登录。

---

多微信号

Q: 同一个 App 能接多个微信号吗？

可以。每个微信号在 Hub 上是一个独立的 Bot，分别安装同一个 App 即可。每个 Installation 有独立的 Token。

客户端（如 OpenClaw）使用多账户配置，每个账户填不同的 Token：

{
  "channels": {
    "openilink": {
      "hub_url": "https://hub.openilink.com",
      "accounts": {
        "bot1": { "app_token": "app_第一个bot的token" },
        "bot2": { "app_token": "app_第二个bot的token" }
      }
    }
  }
}

---

斜杠命令

Q: /s、/gi、/a 等命令怎么用？

这些是 Command Service App 提供的功能：

命令	功能
/s 600519	查股价
/gi 赛博朋克城市	生成图片
/a 帮我写邮件	AI 对话

需要在 Hub 后台单独安装：Bot 详情页 → 应用市场 → Command Service → 安装。

---

Q: @claw 提及命令怎么用？

在微信中发送 @claw 你的问题 即可触发 OpenClaw AI 回复。需要先在 Bot 上安装 OpenClaw App。

@handle 路由支持所有 App，handle 在 Installation 详情页可配置。

---

API

Q: Bot API 认证方式

所有 /bot/v1/* 接口使用 Bearer Token 认证：

curl -X POST https://hub.openilink.com/bot/v1/message/send \
  -H "Authorization: Bearer app_你的token" \
  -H "Content-Type: application/json" \
  -d '{"content":"hello","to":"user_id"}'

Token 在 Hub 后台 App Installation 详情页获取。

---

Q: WebSocket 连接地址

wss://hub.openilink.com/bot/v1/ws?token=app_你的token

连接后会收到 init 消息，包含 bot_id 和 installation_id。需定期发送 {"type":"ping"} 保持连接。

---

升级

Q: 如何升级 Hub？

二进制部署：

# 下载最新 release
# 停止旧服务 → 替换二进制 → 启动
systemctl stop openilink-hub
cp oih /usr/local/bin/oih
systemctl start openilink-hub

Docker 部署：

docker compose pull
docker compose up -d

数据库迁移会自动执行。

---

遇到其他问题？请提交 Issue。

[Sdongmaker]

请教一下，现在腾讯的接口是对文件大小有限制吗？还是对服务端的ip有限制。我部署到加拿大的服务器上的 大一点的图片 视频 就都无法发送了。其次对微信的表情[阴险]支持也不太好。

2026/04/10 07:12:19 INFO 中转开始 bot=[BOT_ID] emoji=🐝 类型=image 目标数=5 msg_id=71
2026/04/10 07:12:19 INFO 中转下载开始 bot=[BOT_ID] 类型=image 有EQP=true 有AES=true 有URL=true 文件大小=0
2026/04/10 07:12:25 INFO 中转下载完成 bot=[BOT_ID] 类型=image 文件=image.jpg 大小=348258 耗时ms=6082
2026/04/10 07:12:25 INFO 中转媒体就绪 bot=[BOT_ID] 文件=image.jpg 大小=348258 MB=0.33 下载耗时ms=6082
2026/04/10 07:12:25 INFO send recipient=[USER_A] has_data=true file=image.jpg text_len=7 context_token="[REDACTED]"
2026/04/10 07:13:27 ERROR send media failed err="ilink: upload media: ilink: cdn upload failed after 3 attempts: ilink: http 500: status 500"
2026/04/10 07:13:27 WARN 中转发送失败 src=[BOT_ID] dst=[DST_ID_1] 尝试次数=1 耗时ms=62316 有媒体=true 文件=image.jpg err="ilink: upload media: ilink: cdn upload failed after 3 attempts: ilink: http 500: status 500"
2026/04/10 07:14:25 WARN 中转发送失败 src=[BOT_ID] dst=[DST_ID_2] 尝试次数=1 耗时ms=120000 有媒体=true 文件=image.jpg err="context deadline exceeded"
2026/04/10 07:14:25 ERROR send media failed err="ilink: upload media: ilink: cdn upload failed after 3 attempts: Post "https://novac2c.cdn.weixin.qq.com/c2c/upload?[SENSITIVE_PARAMS]\": context deadline exceeded"
2026/04/10 07:15:19 ERROR send media failed err="ilink: upload media: ilink: cdn upload failed after 3 attempts: ilink: http 500: status 500"
2026/04/10 07:15:32 WARN 中转发送失败 src=[BOT_ID] dst=[DST_ID_3] 尝试次数=2 耗时ms=120001 有媒体=true 文件=image.jpg err="ilink: upload media: ilink: cdn upload failed after 3 attempts: Post "[SENSITIVE_URL]": context deadline exceeded"

贴上我的日志