novolens-plugin-openclaw

English: NovoLens is an OpenClaw channel plugin that bridges Xuexi Qiangguo MiniApp/H5 users to your OpenClaw agent via the official NovoLens bridge (https://platform.novoordoai.cn). Install with the one-line script — curl -fsSL <install.sh> | bash on macOS/Linux or irm <install.ps1> | iex on Windows. The scripts detect the installed OpenClaw CLI and select its supported ClawHub risk-acknowledgement flag. They then render a binding QR in your terminal; scan it with the Xuexi Qiangguo AI Guardian client to bind, then chat with your agent from your phone.

OpenClaw 渠道插件（npm: @novoordo-ai/novolens-plugin-openclaw，manifest id: novolens-plugin-openclaw）。运行在用户本地的 OpenClaw 进程内，把学习强国小程序/H5 消息桥接到 OpenClaw Gateway，并定期把插件本地聚合的监控快照上报到 novolens-bridge。

安装

当前版本：@novoordo-ai/novolens-plugin-openclaw@1.0.9（ClawHub owner @novoordo-ai）。插件会在终端与本地状态页持续展示永久绑定二维码；绑定成功后 bindCode 仍原样保留。同一码后续被其他学习强国账号扫描时，Bridge 会解除前一账号并把智能体转移给后扫码账号。

方式一：一键脚本（推荐）

脚本流程：通过 ClawHub 安装插件 → 生成学习强国绑定凭据（apiKey + 永久 bindCode）→ 自动启动或重启 Gateway → 等待 Bridge 对同一组 apiKey/bindCode 确认 pending 或 bound → 在终端打印永久二维码。未完成服务端登记时脚本会停止且不展示二维码，避免用户扫到服务端不认识的绑定码。两端脚本都执行这项登记校验。

macOS / Linux：

curl -fsSL https://yixu-public-files.oss-cn-beijing.aliyuncs.com/yxsafe/plugin/install.sh | bash

Windows（PowerShell）：

irm https://yixu-public-files.oss-cn-beijing.aliyuncs.com/yxsafe/plugin/install.ps1 | iex

方式二：手动安装（ClawHub）

先运行 openclaw plugins install --help，以下两个安装命令按帮助中可用的参数二选一，不要连续执行：

# 当前 OpenClaw（help 中包含 --acknowledge-clawhub-risk）
openclaw plugins install clawhub:@novoordo-ai/novolens-plugin-openclaw --acknowledge-clawhub-risk

# 旧版 OpenClaw（help 中只有 --dangerously-force-unsafe-install）
openclaw plugins install clawhub:@novoordo-ai/novolens-plugin-openclaw --dangerously-force-unsafe-install

openclaw daemon restart

⚠️ 先审阅再确认：当前 OpenClaw 使用 --acknowledge-clawhub-risk 确认已审阅社区 ClawHub release 的风险提示；旧版使用 --dangerously-force-unsafe-install 处理安装期危险代码扫描。若 plugins install --help 同时列出两者，使用新参数。确认参数不能绕过 malicious、quarantined/revoked、禁止下载或宿主 security.installPolicy 阻断。

openclaw daemon restart 后，插件会自动收口为学习强国新配置并生成绑定凭据；浏览器打开本地页面 http://127.0.0.1:18765/ 即可扫码绑定（手动安装不渲染终端二维码，用本地页面；想要终端二维码请走方式一的一键脚本）。若已装过旧版报 plugin already exists … delete it first，在命令末尾加 --force 重装即可。缺少 qiangguo-v1 标记的配置会被替换为全新凭据，不做旧账号兼容。

手动升级前必须先结束旧版独立 QR Server，否则它可能继续占用 18765 并展示旧页面。一键脚本会自动处理；手动 ClawHub 升级请先执行对应平台命令，再运行上面的 plugins install ... --force：

# macOS / Linux：只匹配 NovoLens 插件目录中的 qr-server
pkill -f 'novolens-plugin-openclaw/.*/qr-server\.js' 2>/dev/null || \
pkill -f 'novolens-plugin-openclaw/qr-server\.ts' 2>/dev/null || true

# Windows：只停止命令行同时包含插件 id 与 qr-server 的 node.exe
Get-CimInstance Win32_Process |
  Where-Object {
    $_.Name -match '^node(\.exe)?$' -and
    $_.CommandLine -like '*novolens-plugin-openclaw*' -and
    $_.CommandLine -like '*qr-server*'
  } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }

新版本地接口 http://127.0.0.1:18765/api/qr 会返回 protocol: "qiangguo-v1" 与插件 version，可用于确认当前监听进程不是旧版本。

ClawHub（clawhub.ai）是 OpenClaw 官方插件注册中心，自动处理下载、版本管理与插件 npm 依赖安装。

平台支持：macOS / Linux / Windows 10·11 均支持（一键脚本两端各一份：install.sh / install.ps1；插件运行时三端原生支持）。

前置条件与环境变量

前置条件（缺任意一项 install.sh 会立刻报错退出）：openclaw、node（≥18）、npm、curl（Windows 用 PowerShell 自带能力，无需 curl）。

可选环境变量覆盖：

自愈与在线判定：插件内置 watchdog——若负责从 Bridge 拉消息的轮询循环卡死（例如下游 长时间无响应），超过 NOVOLENS_WATCHDOG_STALL_MS 会自动进程内软重启该循环，不必再手动 openclaw daemon restart。同时「在线」状态改为基于最近一次成功轮询/活动的时间戳判定 （NOVOLENS_LIVENESS_STALE_MS 窗口），卡死后会如实翻成离线，而非一直假在线。三者夹紧保持 健康间隔 < LIVENESS_STALE_MS < WATCHDOG_STALL_MS，误配会被自动纠正以避免重启风暴。

升级与回滚

重新跑一键脚本（或 openclaw plugins install clawhub:… --force）即升级。脚本每次安装会把既有插件目录与 openclaw.json 备份到 ~/.openclaw/plugin-backups/（14 天后自动清理）。凭据规则只有以下三种：

• 当前 qiangguo-v1 配置（无论待绑定或已绑定）：默认原样复用 apiKey/bindCode；只有 Bridge 明确返回 409，证明该本地身份无法与服务端登记匹配时，才自动生成并登记一组新身份。
• 当前协议配置若已有 apiKey 却缺少 bindCode：安装器会在修改配置前按新到旧扫描 openclaw.json.bak-*，只恢复协议相同、apiKey 完全相同且格式合法的原 bindCode；找不到则失败关闭，绝不生成替代码。
• 无协议标记或其他旧格式：不迁移，生成全新的 apiKey/bindCode。

无论属于哪一种，只有 Bridge 已确认当前身份可绑定，安装器才会输出绑定码和二维码。

基本代码回滚形式：

openclaw plugins uninstall novolens-plugin-openclaw --force
rm -rf ~/.openclaw/extensions/novolens-plugin-openclaw
mv ~/.openclaw/plugin-backups/novolens-plugin-openclaw.bak-<时间戳> \
   ~/.openclaw/extensions/novolens-plugin-openclaw
openclaw plugins install ~/.openclaw/extensions/novolens-plugin-openclaw \
   --force
# 旧版 OpenClaw 若仍被内置危险代码扫描拦截，在上条命令后另加：
#   --dangerously-force-unsafe-install
openclaw daemon restart

本地开发

pnpm install
pnpm build      # 编译 TypeScript
openclaw plugins install /path/to/novolens-plugin-openclaw

安装后重启 daemon，插件会自动生成并维护学习强国身份。不要通过 setup wizard 或手改配置提供 apiKey/bindCode；wizard 只用于调整 Bridge 地址、轮询间隔、 sessionKey 和调试选项。可运行的配置由插件自动确保以下字段存在：

• plugins.entries.novolens-plugin-openclaw.config.accounts.default.apiKey
• plugins.entries.novolens-plugin-openclaw.config.accounts.default.bindCode
• plugins.entries.novolens-plugin-openclaw.config.bridgeUrl
• plugins.entries.novolens-plugin-openclaw.config.defaults.pollIntervalMs
• plugins.entries.novolens-plugin-openclaw.config.defaults.sessionKey
• plugins.entries.novolens-plugin-openclaw.config.defaults.debug
• plugins.entries.novolens-plugin-openclaw.config.defaults.reportIntervalMs

accounts.default.apiKey 与 bindCode 都是插件管理字段：首次初始化后永久保存。 Bridge 返回身份或绑定码冲突时，插件会明确停止轮询并保留本地原值，绝不会静默 删除、轮换或重新生成凭据。外部输入不会被当作身份凭据写入。

bridgeUrl 也可通过网关进程环境变量 NOVOLENS_BRIDGE_URL 覆盖。插件状态目录默认使用 OPENCLAW_STATE_DIR，未设置时回退到 ~/.openclaw。每次 getUpdates 固定发送 protocol=qiangguo-v1，并始终通过 x-novolens-bind-code 请求头传输永久 bindCode；绑定码不会进入 URL、代理访问日志或历史记录。Bridge 返回 426 时插件停止该账号并明确提示升级。Bridge 返回 binding.status = "bound" 只更新展示状态，不会修改凭据。

1.0.9 继续严格使用学习强国 qiangguo-v1 专用协议，不接受旧令牌、顶层单账户字段、嵌套配置、绑定密钥或 apiKey 直绑签名等旧入口。

集成测试（需先以开发模式启动 bridge，测试会通过 provider=qiangguo 登录、扫码绑定并走完整消息链路）：

# novolens-bridge
ALLOW_INSECURE_DEV_LOGIN=true JWT_SECRET=dev_secret npm run dev

# novolens-plugin-openclaw
npm run test:integration

纯单元测试可直接运行 npm run test:unit。集成测试覆盖强国身份登录、绑定、轮询启动、消息收发完整链路和 monitor-reporter 上报。

设计约束

这些约束是当前联调链路的一部分；后续若改安装或配置流程，必须继续保持这套 canonical 配置和本地采集架构。

• 插件不再在运行时调用 mission-control，也不依赖其 API、SQLite 表或 security/task/memory 数据模型。
• 插件自行从消息轮询、reply 发送、会话归属、OpenClaw runtime 与本地 store 中采集遥测数据。
• monitor-reporter 只把插件本地聚合后的快照上报给 novolens-bridge。
• SBTI 评估输入来自插件本地 telemetry 摘要，而不是远程抓取 mission-control。
• telemetry 持久化路径复用 OpenClaw session store；当 resolveStorePath(...) 返回 *.json 文件路径时，插件会自动回退到其父目录下的 .novolens/telemetry.json，避免把 sessions.json 当目录使用。

联调检查清单

• openclaw plugins inspect novolens-plugin-openclaw 应显示 Status: loaded
• openclaw status 中 NovoLens 应为 ON / OK / configured
• accounts.default.bindCode 在绑定前后始终存在且保持不变，本地页面始终显示同一个永久二维码
• bridge 若以 node dist/index.js 运行，则每次改 novolens-bridge/src/* 后都要重新 build 再重启
• 联调时手改 ~/.openclaw/openclaw.json，记得把有效配置同步回 canonical 结构，不要留下只在本机生效的临时字段
• 用 /api/messages → /monitor/dashboard → /monitor/agents/:id 作为最短联调闭环
• 重装后 channel 又变成 SETUP not configured 时，先查的不是代码，而是 accounts.default.apiKey 是否被 OpenClaw 清空

文档

完整文档见 novolens-spec。本仓相关：

• 插件通信协议 — 消息格式、长轮询机制、媒体处理
• 监控数据上报架构 — monitor-reporter 的设计背景与数据流
• 开发环境搭建 — 本地联调步骤

项目地图