novolens-plugin-openclaw

English: NovoLens is an OpenClaw channel plugin that bridges WeChat MiniProgram users to your OpenClaw agent via the official NovoLens bridge (https://platform.novoordoai.cn). After install, scan a QR code to bind a MiniProgram account, then chat with your agent from your phone. Install via openclaw plugins install clawhub:@novoordo-ai/novolens-plugin-openclaw once the GitHub mirror is online; until then see the self-hosted fallback below.

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

安装

方式一：ClawHub（推荐）

状态：已上线（@novoordo-ai/novolens-plugin-openclaw@1.0.1，ClawHub owner @novoordo-ai）。

openclaw plugins install clawhub:@novoordo-ai/novolens-plugin-openclaw --dangerously-force-unsafe-install

⚠️ 为什么必须带 --dangerously-force-unsafe-install：本插件用 child_process 渲染绑定二维码（open-qr-window）并执行安全扫描/自动修复（security-fixer、security-scanner、remediation-executor）。OpenClaw 安装器会把 shell 执行标记为「dangerous code patterns」并默认拦截；此标志表示安装者已审阅并信任本（community）插件后放行。免标志的自动放行只给 OpenClaw 官方插件（源码层硬编码要求 sourceRepo=openclaw/openclaw），社区包拿不到。

若已装过旧版会报 plugin already exists … delete it first：先 openclaw plugins uninstall novolens-plugin-openclaw --force 再装。channel 配置（apiKey 等）存在 openclaw.json，与扩展目录分离，重装不丢。安装后需 openclaw daemon restart 才会加载。

ClawHub 是 OpenClaw 官方插件注册中心（clawhub.ai），自动处理下载、版本管理与配置注入（含插件 npm 依赖的自动安装），不需要走自托管 install.sh。

平台支持：

• macOS / Linux：ClawHub 或自托管 tarball 均可。
• Windows 10 / 11：只支持 ClawHub。自托管 install.sh 依赖 pkill / nohup / mktemp 等 POSIX 工具，在 PowerShell / cmd / Git Bash 下会主动早退（WSL 内的原生 bash 可跑，但仍推荐 ClawHub）。插件运行时（dist/index.js、dist/qr-server.js、安全扫描、自动修复）在 Windows 上原生支持。

方式二：自托管 tarball（内部团队 / 离线场景）

Windows 用户请走 ClawHub，本节不适用。

适用于尚未走 ClawHub、离线环境、或需要 pin 特定 build 的场景。仓库根目录的 install.sh 一次性下载并安装最新 tarball。

发布备案（当前线上版本）

每次 release 必须按本节 uuid 对照替换，保持 git 与线上一致。这是「当前线上版本」的唯一真相来源。

一键安装（内部团队）：

curl -fsSL https://file.9meta.net/file/b97c669b9dfb441ea1d69b68f986b0d5.sh | bash

• 当前线上插件包：8584c51ba77f45e992c708ea9eccf406.gz （sha256 b38d4be8ddfd845c7064f6fda222bc309d14d93e59adf6e3b28a54088a4fa5ab）
• 当前线上安装脚本：b97c669b9dfb441ea1d69b68f986b0d5.sh

前置条件与配置

前置条件（缺任意一项 install.sh 会立刻报错退出）：openclaw、node（≥18）、npm、curl、tar。

可选环境变量覆盖（仅调试或 pin 老版本时需要）：

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

升级与回滚

install.sh 每次安装会把既有插件目录与 openclaw.json 备份到 ~/.openclaw/plugin-backups/（14 天后自动清理），并在结束时打印当次对应的回滚命令。基本回滚形式：

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 \
   --dangerously-force-unsafe-install
# 仅在确实需要回滚配置时执行
cp ~/.openclaw/openclaw.json.bak-<时间戳> ~/.openclaw/openclaw.json
openclaw daemon restart

本地开发

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

安装后不要只停留在 enabled: true。可运行的安装结果还需要完成 channel setup，确保配置里存在：

• plugins.entries.novolens-plugin-openclaw.config.accounts.default.apiKey
• 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

推荐通过 OpenClaw 的 setup 流程写入，而不是手改 ~/.openclaw/openclaw.json。若联调时为排障临时手改了本地配置，必须同步回上述 canonical 结构，否则插件重装后会退回 SETUP not configured。

最小配置示例：

{
  "plugins": {
    "entries": {
      "novolens-plugin-openclaw": {
        "enabled": true,
        "config": {
          "bridgeUrl": "https://platform.novoordoai.cn",
          "accounts": {
            "default": {
              "apiKey": "dev-key",
              "enabled": true
            }
          },
          "defaults": {
            "pollIntervalMs": 5000,
            "sessionKey": "agent:main:main",
            "debug": true,
            "reportIntervalMs": 30000
          }
        }
      }
    },
    "allow": ["novolens-plugin-openclaw"]
  }
}

bridgeUrl 也可通过网关进程环境变量 NOVOLENS_BRIDGE_URL 覆盖。插件状态目录默认使用 OPENCLAW_STATE_DIR，未设置时回退到 ~/.openclaw。

集成测试（需先启动 bridge，测试脚本会模拟必要的本地依赖）：

pnpm test       # 本地优先使用已安装的 vitest 运行集成测试

测试覆盖：轮询启动、消息收发完整链路、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
• 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 的设计背景与数据流
• 开发环境搭建 — 本地联调步骤

项目地图