OpenClaw Lumii 插件

在 OpenClaw 中接入 Lumii（Metaio）登录、lumii-file（助手侧绝对路径 → 阿里云 OSS → https://…；用户气泡不上传）、plugin-events WebSocket（与 AINO 协同）、以及 Skills（lumii-file-oss、lumii-oss-website-url、lumii-login-guide）。

不包含：OpenClaw 频道侧的 Lumii 文本/媒体消息收发（sendText / sendMedia 已禁用），与 openclaw.plugin.json 说明一致。需要聊天收发时请使用其它 Lumii 集成或自建 bridge。

环境要求

• OpenClaw（CLI / Gateway）≥ 2026.3.28（peerDependencies / minHostVersion 与此一致）。插件入口使用 openclaw/plugin-sdk/core 的 defineChannelPluginEntry。
• 运行插件：Node.js ≥ 20（engines.node）。在本仓库开发、构建推荐 Node.js ≥ 22（与工具链一致）。

npm 包： @wemotechnology/openclaw-lumii — 常规安装见 第三节 · 方式 A；若 CLI 装依赖超时见 方式 D（手动 npm install + npm run openclaw:register）。维护者发布流程见 第七节。

网站 dist 自动上传 OSS 并生成可发用户的网址

OpenClaw 里的 lumii-file 在 before_prompt_build 中处理「prompt + 非用户角色消息」里的绝对路径（用户入站气泡不上传 OSS），不会在 vite build 结束后自动扫磁盘。若要做到 「构建完成 = 必上传 OSS + 拿到 HTTPS」，请用下面脚本挂在 构建后（与网关侧 LUMII_FILE_OSS_* / ~/.openclaw/openclaw-lumii/dev-config.json 同一套配置）：

# 在插件目录（或复制脚本到你的网站仓库）
node scripts/publish-dist-to-oss.mjs --dir ./dist

在网站项目的 package.json 中示例：

{
  "scripts": {
    "build": "vite build",
    "postbuild": "node /绝对路径/AINO/openclaw-lumii-plugin/scripts/publish-dist-to-oss.mjs --dir dist"
  }
}

成功后终端会打印 LUMII_OSS_SITE_URL=... 与 「发给用户的入口」（需已配置 LUMII_FILE_OSS_PUBLIC_BASE_URL）。未配置公网域名时，脚本会尝试输出短时签名 URL 作预览。

说明：该脚本使用 长期 AK/SK（或 dev-config 中的同名键）；若你只在网关上用 Lumii 侧 STS（经登录 token）、没有落在环境里的 AK，请为构建机单独导出 LUMII_FILE_OSS_*，或使用受限子账号。

插件包内快捷命令（在 openclaw-lumii-plugin 目录下、且已 pnpm install）：

pnpm run oss:publish-dist

一、插件在 OpenClaw 里的位置

OpenClaw 从用户目录下的 extensions 加载插件：

~/.openclaw/extensions/

• openclaw plugins install <路径或 npm 包名>：会把插件装到该目录下（常见子目录名为 openclaw-lumii，与插件 id 一致；若按 npm 包名则可能对应 scope 包目录，以 openclaw plugins list 为准）。
• 手动复制：可将本仓库整个目录复制到 ~/.openclaw/extensions/openclaw-lumii（需本地先 npm install && npm run build，保证存在 dist/index.js）。

二、本仓库结构（AINO 内路径）

插件目录与 AINO-app、AINO-server 同级：AINO/openclaw-lumii-plugin/。

openclaw-lumii-plugin/
├── package.json              # name: @wemotechnology/openclaw-lumii
├── openclaw.plugin.json      # 插件清单、频道 schema、skills
├── index.ts                  # 入口，defineChannelPluginEntry
├── src/                      # 频道、Metaio 登录、plugin-events、lumii-file 钩子等
├── lumii-file/               # lumii-file 子包逻辑
├── skills/                   # lumii-file-oss、lumii-oss-website-url、lumii-login-guide
├── scripts/                  # lumii-metaio-login、configure-token、ensure-channel、install-local、register-openclaw-after-manual-npm 等
├── dev-config.example.json   # 复制到 State 目录后改密钥（见下）
└── README.md

三、怎么装到 OpenClaw

插件自带的 Skills（无需单独再装）

OpenClaw 没有「给插件单独执行一条 skills 安装命令」的流程。本仓库在 openclaw.plugin.json 里声明了 skills（如 lumii-file-oss、lumii-oss-website-url、lumii-login-guide），只要：

1. 发布包里带上目录：根目录 package.json → files 已包含 skills/（随 npm pack / openclaw plugins install 进到 ~/.openclaw/extensions/openclaw-lumii/）。
2. 插件已 安装且 openclaw plugins enable openclaw-lumii，Gateway 启动后会从扩展目录解析清单里的相对路径，把 SKILL.md 并入 Agent 可用的技能来源（与 workspace / managed skills 等一起参与解析）。
3. 重启 Gateway 后再跑会话，模型侧才能看到对应 skill。

若始终看不到 lumii-file-oss：确认扩展目录下存在 skills/lumii-file-oss/SKILL.md；用 openclaw plugins inspect openclaw-lumii 看插件是否启用；并检查 Agent 是否配置了 过严的 skills 白名单（需包含该 skill 或放宽为默认策略，以你本机 openclaw.json 与 OpenClaw 文档为准）。

方式 A：npm 最新版（与页首一致）

与 npm 包主页 同步安装当前最新 tag：

openclaw plugins install @wemotechnology/openclaw-lumii@latest
openclaw plugins enable openclaw-lumii

需要把解析结果钉死到某一版本时再使用 openclaw plugins install @wemotechnology/openclaw-lumii --pin（以 CLI 文档为准）。重启 Gateway 后：openclaw plugins list 应含 openclaw-lumii。

本包是 Gateway 插件（openclaw.extensions），不要用 openclaw hooks install … 安装；误用会报 “not a valid hook pack”（例如 openclaw.hooks 缺失或为空）。请始终用 openclaw plugins install。

方式 B：本仓库一键（本地开发推荐）

在克隆下来的 openclaw-lumii-plugin 根目录执行：

npm run install:openclaw
# 等价：bash scripts/install-local-openclaw.sh

脚本会依次：npm install → npm run build → openclaw plugins install -l <本目录>（软链）→ openclaw plugins enable openclaw-lumii → 写入频道存根 → plugins list / plugins doctor →（交互终端下）openclaw channels login --channel openclaw-lumii → 若不存在则从 dev-config.example.json 生成 dev-config（见第四节）。

• 只装插件、暂不登录：LUMII_SKIP_LOGIN=1 npm run install:openclaw
• 保留已有插件扩展与 skills、只跑其余初始化（npm install / build、enable、频道存根、plugins list / doctor、可选 login、首次 dev-config）：已装过扩展且不想重跑 openclaw plugins install -l 时用
  LUMII_SKIP_PLUGINS_INSTALL=1 npm run install:openclaw
  （Skills 随 openclaw.plugin.json 在扩展目录内解析；跳过 install 不会改变你已链到本仓库的 skills/。）
• 非交互环境不会自动跑 login，请之后在终端执行：
  openclaw channels login --channel openclaw-lumii
• 若安装被安全扫描拦截，脚本提示里含 --dangerously-force-unsafe-install（仅信任本仓库时使用）。

完成后请完全退出并重启 OpenClaw Gateway。若列表里仍无 Lumii：openclaw plugins inspect openclaw-lumii。

用 Token 自动配置（免 channels login）

若你已有 Lumii 的 access token（JWT） 以及与 AINO 一致的 OPENCLAW_WEBHOOK_TOKEN（plugin-events secret）：

插件仓库根目录一行：

npm run lumii:configure-token -- --jwt '<JWT>' --user-id '<用户UUID>' --application-id '<applications表UUID>' --secret '<与AINO的OPENCLAW_WEBHOOK_TOKEN一致>'

未 clone 仓库、只装 npm 包时一行（npx 拉最新版并跑 bin）：

npx --yes @wemotechnology/openclaw-lumii@latest openclaw-lumii-configure-token -- --jwt '<JWT>' --user-id '<用户UUID>' --application-id '<APP_UUID>' --secret 'openclaw-aliyunlumii'

JWT 从管道一行： echo "$JWT" | npm run lumii:configure-token -- --jwt - --user-id "$USER" --application-id "$APP" --secret "$SECRET"

脚本会写入 ~/.openclaw/openclaw-lumii/accounts/<account>.json、dev-config.json（含 LUMII_PLUGIN_WS_URL），并尝试执行 ensure-lumii-channel。本地 AINO 与公网 API 根不一致时可加 --lumii-api-base、--metaio-base、--ws-http-base（node scripts/configure-lumii-from-token.mjs --help）。仅同步 webhook：加 --webhook-only。

方式 C：路径安装（复制或链）

openclaw plugins install /绝对路径/AINO/openclaw-lumii-plugin
# 开发时改代码即生效：
openclaw plugins install -l /绝对路径/AINO/openclaw-lumii-plugin

确认：

openclaw plugins list

应能看到插件 id openclaw-lumii。

方式 D：扩展目录里手动 npm install 后再登记（CLI 装依赖超时 / 国内网络慢）

当 openclaw plugins install @wemotechnology/openclaw-lumii@… 在「Installing plugin dependencies」阶段失败（多为 npm install 超时 或 registry 慢），可先只把包装进扩展目录并本地装依赖，再登记 + 启用：

1. 准备目录 ~/.openclaw/extensions/openclaw-lumii（名称与插件 id 一致），任选其一：

   • registry： npm pack @wemotechnology/openclaw-lumii@<版本>，解压后将 package 移入上述路径；
   • 源码： mkdir -p ~/.openclaw/extensions && cp -r /绝对路径/openclaw-lumii-plugin ~/.openclaw/extensions/openclaw-lumii，并在该目录执行 npm install && npm run build（须存在 dist/index.js）。

2. 只装运行时依赖（与 OpenClaw 内部一致）：

   cd ~/.openclaw/extensions/openclaw-lumii
   npm install --omit=dev --ignore-scripts

3. 登记并启用（发布包内已含脚本，可在扩展目录直接执行，无需单独 clone）：

   npm run openclaw:register
   # 等价：bash scripts/register-openclaw-after-manual-npm.sh

   • 扩展目录不在默认路径：OPENCLAW_LUMII_EXT_DIR=/你的路径/openclaw-lumii npm run openclaw:register
   • 若 install -l 被安全策略拦截：LUMII_UNSAFE=1 npm run openclaw:register（仅信任该目录时）
   • 若扩展与本仓库分离：在仓库根执行 npm run openclaw:register 并设置 OPENCLAW_LUMII_EXT_DIR。

4. 完全重启 OpenClaw Gateway，再按需 openclaw channels login --channel openclaw-lumii。

四、配置说明（摘要）

1. 频道 channels.openclaw-lumii

在 OpenClaw 配置里为该频道设置（与 openclaw.plugin.json / Control UI 一致）：

• Lumii 登录：浏览器内目前为 账号密码（频道字段名仍为 metaioUsername / metaioPassword 等）。终端执行 openclaw channels login --channel openclaw-lumii（或 npm run lumii:login / npm run lumii:login:direct）时：若已配置 METAIO_USERNAME 与 METAIO_PASSWORD（或频道内对应字段），默认优先账号密码登录；若要扫码，请设 METAIO_LOGIN_MODE=qr 或 METAIO_PASSWORD_LOGIN=0（见 .env.example）。
• 智能体 / 自动化：插件不会从聊天读密码；若产品允许「用户在聊天里发账号密码 → 智能体解析 → 在本机执行登录脚本」，见 skills/lumii-login-guide/SKILL.md（lumii-metaio-login.mjs --credentials-json-stdin 等；METAIO_LOGIN_MODE=password 通常可省略）。群聊发密码有风险，见 Skill 安全节。
• lumiiFileEnabled：是否启用 lumii-file（OSS 具体参数见环境变量或 dev-config，见下）。

更多字段说明见仓库根目录 openclaw.plugin.json 的 channelConfigs.openclaw-lumii。

2. dev-config（Lumii 后端 / OSS / 插件 WS 等）

默认路径：

${OPENCLAW_STATE_DIR:-~/.openclaw}/openclaw-lumii/dev-config.json

首次可通过 npm run install:openclaw 从 dev-config.example.json 复制（最小字段：Lumii API 根、plugin-events、webhook token）。lumii-file（OSS）、Lumii 登录账号等见 .env.example 或按需往 dev-config.json 追加同名键，勿把真实密钥提交到 Git。

3. 环境变量（与 dev-config 二选一，env 优先）

详见 .env.example（lumii-file、Metaio 登录、OPENCLAW_WEBHOOK_TOKEN、LUMII_PLUGIN_WS_URL 等）。账户状态里也可存 baseUrl（登录脚本同步），供其它模块解析；本插件不提供频道 HTTP 发消息，无需为「收发聊天」单独配 bridge URL。

五、配对码与 App 绑定（可选）

若发行版提供 openclaw lumii-pair：终端输出配对码 / 二维码链接，供 Lumii App 绑定；参数与行为以当前 OpenClaw CLI 文档为准。与本插件无直接代码依赖。

六、把插件打进 OpenClaw 客户端再打包（ClawApp）

将本插件作为 extensions 之一随 ClawApp 等工程打包时：含 openclaw.plugin.json、构建产物 dist/ 等，按目标仓库文档构建。运行时仍读本机 ~/.openclaw 下配置。

七、维护者：发布 npm 包

在具备 @wemotechnology 组织发布权限 的 npm 账号下操作（首次 npm login；scoped 公共包需 npm publish --access public）。

发布前检查

• [ ] npm run build / npm run typecheck 通过，dist/index.js 存在。
• [ ] 根目录 package.json 的 "version" 与 openclaw.install.npmSpec 一致，形如：
  "npmSpec": "@wemotechnology/openclaw-lumii@<与 version 相同>"
  （若先用 npm version patch，记得再改 npmSpec，或手改版本后统一提交。）
• [ ] 新增脚本若需随包分发，已列入 package.json → files（与仓库 scripts/ 下文件一致，并含 .env.example、dev-config.example.json 等；以 npm pack --dry-run 为准）。
• [ ] 勿将密钥、本机路径写入仓库；bin.openclaw-lumii-configure-token 供 npx 使用。

版本号与发布命令

cd openclaw-lumii-plugin
npm ci
npm run build
npm version patch   # 或 npm version minor / major；会改 package.json 版本并打 git tag（在 git 仓库中时）

将 openclaw.install.npmSpec 改为与 "version" 完全一致后提交（若 npm version 未自动改该项）：

npm publish --access public

prepublishOnly 会执行 npm run build。

发布后校验

npm view @wemotechnology/openclaw-lumii version
npm pack @wemotechnology/openclaw-lumii@latest --dry-run

用户侧安装见 第三节 · 方式 A；若 openclaw plugins install 在装依赖阶段超时，见 第三节 · 方式 D（扩展目录 npm install + npm run openclaw:register）。

私有 registry

若团队使用私有 npm，在发布环境的 ~/.npmrc 中配置 registry 与 token 后再 npm publish。

八、常见问题

• 期望用本插件在 OpenClaw 里「发 Lumii 聊天消息」
  不支持：本仓库频道插件已禁用消息收发，仅提供登录、lumii-file、plugin-events 等（见文首）。聊天类能力请查其它集成或 AINO 文档。

• openclaw plugins list 里没有插件
  确认扩展目录里有 package.json 与构建产物 dist/index.js，并已执行 openclaw plugins install … / enable。

• Installing plugin dependencies / npm install failed: + Also not a valid hook pack: … openclaw.hooks
  真实原因几乎总是：在扩展目录里执行依赖安装时，npm install 失败（网络、registry、权限、磁盘、npm 版本等）。OpenClaw 在「插件 npm 安装」失败后会再试把同一包当成 hook 包安装；本仓库是 Gateway 插件，没有 openclaw.hooks，所以第二行会报 missing openclaw.hooks 或 openclaw.hooks is empty——这是 误导性的附加提示，请按 npm install 失败来排查。
  排查： 在机器上进入 ~/.openclaw/extensions/openclaw-lumii（若安装中断可先手动从 npm 拉包解压到同名目录），执行：
  npm install --omit=dev --ignore-scripts（不要加 --silent**，以便看到完整报错）。确认 **Node.js** 满足 **engines.node（≥ 20）**、npm config get registry可达、磁盘与权限正常。说明：OpenClaw 在扩展目录里跑npm install时会**暂时移走包内.npmrc**，不能依赖随包 .npmrc；第二行 **openclaw.hooks** 仅为失败回退提示，**不要**为此去伪造钩子包。 **绕过：** 见 **第三节 · 方式 D**（扩展目录 **npm install** + **npm run openclaw:register**）；或 clone 后 npm install && npm run build 再 **openclaw plugins install -l <仓库绝对路径>`**。

• 安装插件时提示 dangerous code patterns（Shell / credential harvesting）
  本仓库的 scripts/ 已改为只读写本机 JSON，不再使用 child_process。若仍对 dist/ 内「环境变量 + 网络」告警，多为频道插件读取 dev-config / 连 Lumii 后端的静态规则误报；仅在信任本包时使用：
  openclaw plugins install @wemotechnology/openclaw-lumii@latest --dangerously-force-unsafe-install（见 CLI 说明）。

• Lumii 登录或 lumii-file 未生效
  检查 dev-config.json 路径、.env.example 中变量是否与进程一致；频道 lumiiFileEnabled 是否打开（若使用 lumii-file）。

• 配对码过期
  临时配对码约 10 分钟 有效，超时需重新执行 openclaw lumii-pair（若你的发行版提供该命令）。

• Gateway 报 plugin WS error: Unexpected server response: 426
  AINO 对 /api/lumii/openclaw/plugin-events 的普通 HTTP GET 会返回 426（提示该路径只接受 WebSocket）。插件若收到 426，说明 WebSocket 升级没走到 Node 的 upgrade 处理，请求被当成普通 GET。请检查：反代是否转发 Upgrade、Connection；LUMII_PLUGIN_WS_URL / 自动拼接的 URL 是否完整包含路径 /api/lumii/openclaw/plugin-events；公网 HTTPS 入口是否用 wss:// 且代理已开启 WebSocket。本地联调可直连 ws://127.0.0.1:<AINO端口>/api/lumii/openclaw/plugin-events?... 排除代理问题。
  Nginx 反代写法见下一节。

• 排查插件健康
  openclaw plugins doctor、openclaw plugins inspect openclaw-lumii。

九、Nginx 反向代理 AINO（含 plugin-events WebSocket）

AINO 监听例如 127.0.0.1:3007（以你 .env 的 PORT 为准）。对公网域名 https://api.example.com 做反代时，需让 WebSocket 握手原样到达 Node（Upgrade / Connection），否则插件会得到 426。

在 http { ... } 里增加 map（官方常用写法：无 Upgrade 时用 close，避免普通 HTTP 也强行带 upgrade）：

map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server 示例（TLS 证书路径请自拟；仅 HTTP 时把 listen 443 ssl 改为 listen 80 并去掉 ssl_certificate 两行）：

upstream aino_node {
  server 127.0.0.1:3007;
  keepalive 32;
}

server {
  listen 443 ssl http2;
  server_name api.example.com;

  # ssl_certificate     /path/to/fullchain.pem;
  # ssl_certificate_key /path/to/privkey.pem;

  client_max_body_size 100m;

  location / {
    proxy_pass http://aino_node;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # WebSocket（plugin-events 与其它可能走 upgrade 的路径）
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    # 长连接、流式响应可适当加大
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;
  }
}

插件侧 LUMII_PLUGIN_WS_URL（或自动拼接的 baseUrl）应指向 对外域名，例如：

wss://api.example.com/api/lumii/openclaw/plugin-events?applicationId=…&userId=…&secret=…

注意： 若你还用路径前缀（如 /lumii）再转发到后端，则插件里的 URL 必须带同一前缀，且 Nginx location 与 proxy_pass 不要少写、多写斜杠导致路径被截断。