openclaw-weixin-fedx
v2.4.7
Published
Tencent 官方 openclaw-weixin plugin 的内部 fork（v9 2026-08-09），用于支持 OpenClaw Enterprise UI 平台扫码注入账号；上游 @tencent-weixin/[email protected]
Readme
@fedx/openclaw-weixin-fork
Tencent 官方 openclaw-weixin plugin（@tencent-weixin/openclaw-weixin）的内部 fork，用于支持 OpenClaw Enterprise UI 平台扫码注入账号。
本 fork 与 OpenClaw 官方 / Tencent 无关。 由 OpenClaw Enterprise UI 团队自维护，仅供内部使用。
1. 与上游的区别
| 项 | 上游 @tencent-weixin/openclaw-weixin | 本 fork @fedx/openclaw-weixin-fork |
|---|---|---|
| 账号注入方式 | 仅宿主机 terminal openclaw channels login | 额外支持通过内部 RPC 端点 internal/weixin/account/save 接收平台注入 |
| 落盘链路 | 同 | 完全相同：复用上游原 saveWeixinAccount / registerWeixinAccountId / clearStaleAccountsForUserId / triggerWeixinChannelReload，不绕过上任何游函数 |
| 文件格式 / chmod / 索引 | 同 | 同 |
| 同步 SLA | n/a | P0 安全补丁 7 天内合入；功能更新 30 天内；主版本变更走 v9.x 修订 |
| 当前 fork 版本 | 2.4.6（上游） | 2.4.6（本 fork，与上游同号；见 CHANGELOG 说明） |
2. 安装与升级 SOP
2.1 部署前 checklist
[v] corp npm registry 可达（`npm config get registry` 返回 http://121.36.20.147:4873/）
[v] Gateway 版本 >= 2026.7.1（探针确认 internal/* 端点可注册）
[v] 官方版已 uninstall（`openclaw plugins uninstall @tencent-weixin/openclaw-weixin`）
[v] fork 版已 install（`openclaw plugins install @fedx/openclaw-weixin-fork`）
[v] Gateway 已 restart
[v] 平台 CHANNEL_CATALOG.pluginPackage 已更新到 fork 包名（后端 logs `pluginPackage=@fedx/openclaw-weixin-fork`）
[v] 平台 CHANNEL_CATALOG.pluginPackage 已更新到 fork 包名2.2 新装（首次部署 Gateway）
# 1. 确认 corp npm registry 可达
npm config get registry
# 应为 http://121.36.20.147:4873/
# 2. 安装 fork 版
openclaw plugins install "@fedx/openclaw-weixin-fork"
# 3. 验证安装（路径以 `openclaw state path` 输出为准 —— 不要硬编码 ~/.openclaw）
STATE_DIR="$(openclaw state path 2>/dev/null || echo "$OPENCLAW_STATE_DIR")"
ls -la "${STATE_DIR}/npm/projects/"*/node_modules/@fedx/openclaw-weixin-fork/package.json
# ↑ 应存在；version 字段是 2.4.6
# 4. 重启 Gateway（plugin 需 restart 才加载）
openclaw gateway restart
# 5. 验证 fork plugin 已装（关键：平台扫码依赖此 plugin 的 handler）
openclaw plugins list
# ↑ 应看到 @fedx/openclaw-weixin-fork
# 如未显示 → fork 未正确加载 → 排查 plugins install 错误码 + gateway 日志
# 6. 验证 RPC 端点：直接走 UI 联调（扫码 → 后端调 internal/weixin/account/save）
# 成功路径 → SSE 推 event: confirmed，账号落盘文件出现
# 失败路径（fork 未注册）→ SSE 推 event: confirmed_with_terminal_hint + 后端日志 "WEIXIN_RPC_NOT_FOUND"2.3 从官方版切到 fork / fork 版本号升级
# 1. 卸载旧版（保留账号文件不动；plugin 卸载不会清 state dir）
openclaw plugins uninstall "@tencent-weixin/openclaw-weixin"
# 2. 安装新版
openclaw plugins install "@fedx/[email protected]"
# 3. 重启 forkeplugin y装
openclaw ayugess list # 应看到 @fadx/opetclw-fok
# 5. UI 联调验证（见 §3.9.7 SOP）
# 4. 验证 fork plugin 已装
openclaw plugins list # 应看到 @fedx/openclaw-weixin-fork
# 5. UI 联调验证（见 §3.9.7 SOP）2.4 禁止
- 官方版和 fork 版并存：两个包都会向
internal/weixin/account/save注册，端点冲突。
2.5 回滚（fork → 官方版）
openclaw plugins uninstall @fedx/openclaw-weixin-fork
openclaw plugins install @tencent-weixin/openclaw-weixin
openclaw gateway restart账号文件 ~/.openclaw/openclaw-weixin/accounts/*.json 保留（fork 与上游 CLI 共用同一文件格式），无需重新扫码。
3. 故障排查
| 现象 | 原因 | 排查命令 |
|---|---|---|
| 平台扫码点 QR → 后端 SSE 等到 confirmed 但列表无账号 | fork plugin 未加载 / handler 未注册 | openclaw plugins list 看 fork 是否在 + 后端日志是否有 WEIXIN_RPC_NOT_FOUND |
| 平台扫码提示 WEIXIN_RPC_NOT_FOUND | Gateway 版本太老 / fork plugin 版本太老（不含 handler） | openclaw --version + 看 package.json 的 version |
| triggerWeixinChannelReload 后账号没生效 | file watcher 没装 / state dir 路径不对 | openclaw config path 拿到 config.json 路径，jq .channels.openclaw-weixin.channelConfigUpdatedAt 看是否递增；检查 OPENCLAW_STATE_DIR / OPENCLAW_CONFIG 环境变量 |
| fork 与官方版冲突 | 没先 uninstall 官方版 | npm ls -g @tencent-weixin/openclaw-weixin @fedx/openclaw-weixin-fork |
4. 上游同步
见 scripts/sync-upstream.sh + OWNERS.md。
5. 相关链接
- 上游包：
@tencent-weixin/openclaw-weixin（npm scope） - 平台 spec：
docs/specs/012-channel-management/spec.md§3.9 - 平台 acceptance：
docs/specs/012-channel-management/acceptance-tests.mdG31-G36 - corp Verdaccio：
http://121.36.20.147:4873/ - OpenClaw Plugin SDK API 参考：https://docs2.openclaw.ai/plugins/sdk-overview
api.registerGatewayMethod(name, handler)→ Gateway RPC method