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). Install with the one-line script — curl -fsSL <install.sh> | bash on macOS/Linux or irm <install.ps1> | iex on Windows — or manually with openclaw plugins install clawhub:@novoordo-ai/novolens-plugin-openclaw --dangerously-force-unsafe-install. It then renders a binding QR in your terminal; scan it with the MiniProgram to bind, then chat with your agent from your phone.

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

安装

当前线上版本：@novoordo-ai/novolens-plugin-openclaw@1.0.4（ClawHub owner @novoordo-ai）。安装后会在终端渲染绑定二维码，用 NovoLens 小程序扫码即可绑定。

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

脚本流程：通过 ClawHub 安装插件 → 自动生成/复用绑定凭据（apiKey + bindCode）→ 重启网关 → 在终端打印绑定二维码。两端脚本同构。

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 clawhub:@novoordo-ai/novolens-plugin-openclaw --dangerously-force-unsafe-install
openclaw daemon restart

⚠️ 为什么必须带 --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），社区包拿不到。

openclaw daemon restart 后，插件会自动生成绑定凭据；浏览器打开本地二维码页 http://127.0.0.1:18765/ 即可扫码绑定（手动安装不渲染终端二维码，用本地页面；想要终端二维码请走方式一的一键脚本）。若已装过旧版报 plugin already exists … delete it first，在上面命令末尾加 --force 重装即可；channel 配置（apiKey 等）存在 openclaw.json，与扩展目录分离，重装不丢。

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

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

前置条件与环境变量

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

可选环境变量覆盖：

自愈与在线判定：插件内置 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 天后自动清理），并复用已有 apiKey/bindCode 不轮换凭据。基本回滚形式：

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 的设计背景与数据流
• 开发环境搭建 — 本地联调步骤

项目地图