Tools
Lumii
By openclaw-lumii-plugin
Install
npm install
pnpmConfiguration Example
{
"plugins": {
"entries": {
"openclaw-lumii": {
"enabled": true,
"config": {
"lumiiApiBase": "https://你的Lumii后端地址"
}
}
}
}
}README
# @lumii/openclaw-lumii
Standalone Lumii channel plugin for OpenClaw.
## What this plugin targets
- QR account binding flow (WeChat-style UX)
- text and media outbound messaging
- proactive scheduler delivery compatibility (`announce` mode with explicit `channel + accountId + to`)
## Current status
This repository is an initial production-oriented scaffold aligned with mature plugin patterns used by WeChat/Feishu/Telegram ecosystems.
Implemented now:
- plugin packaging contract (`package.json`, `openclaw.plugin.json`)
- OpenClaw plugin entry and channel skeleton
- QR login service abstraction and state machine placeholders
- account state persistence foundation
- outbound text/media path stubs
Still to implement with Lumii backend specifics:
- concrete Lumii endpoint schemas and auth rules
- inbound webhook/event ingestion
- full error mapping and retry strategy
- advanced status telemetry and message-edit based progress updates
## Install
```bash
npm i @lumii/openclaw-lumii
```
or with pnpm:
```bash
pnpm add @lumii/openclaw-lumii
```
## Build
```bash
npm run build
```
## Typecheck
```bash
npm run typecheck
```
## Integration expectations for host apps
Host app should provide:
- channel start/cancel UI bridge for QR login
- plugin installation hook (`ensureLumiiPluginInstalled`)
- runtime event forwarding for:
- `channel:lumii-qr`
- `channel:lumii-success`
- `channel:lumii-error`
# OpenClaw Lumii 绑定插件
在 OpenClaw 里生成 **配对码** 和 **二维码链接**，用户在 Lumii App 中扫码或输入配对码即可完成绑定。
---
## 一、插件应该放在 OpenClaw 的哪个目录
OpenClaw 会从 **用户目录下的扩展文件夹** 加载插件，标准路径是：
```text
~/.openclaw/extensions/
```
- **用命令安装**（推荐）：执行 `openclaw plugins install <路径>` 后，插件会被**自动复制**到
`~/.openclaw/extensions/openclaw-lumii/`（或与 package.json 里 name 同名的子目录）。
**你不需要手动拷文件**，只要在任意目录执行安装命令即可。
- **手动复制**：若不用安装命令，就把本仓库里的 `openclaw-lumii-plugin` 整个文件夹复制到上述目录下，并改名为 `openclaw-lumii`：
```bash
cp -r /你的路径/AINO/openclaw-lumii-plugin ~/.openclaw/extensions/openclaw-lumii
```
`~` 表示当前用户主目录（Windows 一般为 `C:\Users\你的用户名`，macOS/Linux 为 `/Users/你的用户名`）。
即：**放在 OpenClaw 的「扩展目录」`~/.openclaw/extensions/` 里**，子文件夹名为 `openclaw-lumii`。
---
## 二、插件源码在 AINO 仓库的哪里
插件目录在 AINO 仓库里（与 AINO-app、AINO-server 同级）：
```text
AINO/openclaw-lumii-plugin/
├── package.json
├── index.js
└── README.md （本说明）
```
---
## 三、怎么装到 OpenClaw 里
### 方式 1：本地路径安装（推荐）
1. 打开终端，进入 **OpenClaw 的安装目录**（或你放 OpenClaw 的目录）。
2. 执行（把下面的路径改成你本机 AINO 仓库里插件目录的**绝对路径**）：
```bash
openclaw plugins install /绝对路径/AINO/openclaw-lumii-plugin
```
例如 AINO 在 `/Users/devin/AINO` 时：
```bash
openclaw plugins install /Users/devin/AINO/openclaw-lumii-plugin
```
3. 若开发时想改代码即生效，可以用链接方式安装：
```bash
openclaw plugins install -l /Users/devin/AINO/openclaw-lumii-plugin
```
4. 查看是否装上：
```bash
openclaw plugins list
```
列表中应能看到 `openclaw-lumii`（或你 package 里的 name）。
5. **配置 Lumii API 地址**（必做一步）：
在 OpenClaw 的配置里加上 Lumii 服务端地址，例如在 `~/.openclaw/config.json` 或 OpenClaw 使用的配置文件中：
```json
{
"plugins": {
"entries": {
"openclaw-lumii": {
"enabled": true,
"config": {
"lumiiApiBase": "https://你的Lumii后端地址"
}
}
}
}
}
```
或设置环境变量（二选一即可）：
```bash
export LUMII_API_BASE=https://你的Lumii后端地址
```
6. **重启 OpenClaw Gateway**（若在跑）：
```bash
openclaw start
# 或先停再起
```
---
### 方式 2：手动复制到 OpenClaw 的 extensions 目录
1. 打开扩展目录：`~/.openclaw/extensions/`（没有就新建该目录）。
2. 把 AINO 里的 `openclaw-lumii-plugin` 复制进去，并改名为 `openclaw-lumii`：
```bash
mkdir -p ~/.openclaw/extensions
cp -r /Users/devin/AINO/openclaw-lumii-plugin ~/.openclaw/extensions/openclaw-lumii
```
3. 在配置里启用并设置 `lumiiApiBase`（见方式 1 第 5 步）。
4. 重启 OpenClaw。
---
## 四、怎么用
1. 在终端执行：
```bash
openclaw lumii-pair
```
2. 终端会输出：
- **8 位配对码**：在 Lumii App 绑定页「输入配对码」处填写。
- **二维码链接**：用手机浏览器打开这个链接会显示二维码，再用 Lumii App 扫码即可；或把扫码得到的 JSON 粘贴到 Lumii 的输入框。
3. 在 Lumii App 里：
- 打开「绑定 iPolloClaw」；
- 选择「输入 8 位配对码或粘贴扫码结果」；
- 输入终端里显示的 8 位码，或先扫二维码再粘贴结果，点「确认绑定」。
可选参数：
```bash
# 临时配对码（默认，10 分钟有效）
openclaw lumii-pair --gateway-url "http://127.0.0.1:18789" --identity "my-openclaw"
# 固定配对码（永久有效，同 identity 始终返回同一码，机器重启后仍可用）
openclaw lumii-pair --fixed -i "office-pc" -g "http://192.168.1.100:18789"
```
**固定配对码**：`-f/--fixed` + `-i/--identity` 必填。一台 OpenClaw 一个 identity（如 office-pc、home-laptop），首次执行生成配对码，之后始终返回同一码，无过期时间。
---
## 五、把插件打进 OpenClaw 客户端再打包（ClawApp）
你若用 **ClawApp**（如 `ClawApp-main`）打包成 macOS/桌面客户端，插件已经按 ClawApp 规范加在仓库的 **extensions** 里，打包时会一起打进应用。
1. **插件在 ClawApp 里的位置**
- 若你的 ClawApp 在 `~/Downloads/ClawApp-main`，插件目录为：
`ClawApp-main/extensions/openclaw-lumii/`
- 内含：`package.json`、`openclaw.plugin.json`、`index.ts`、`README.md`。
2. **重新打包客户端**（在 ClawApp 仓库根目录执行）：
```bash
cd /path/to/ClawApp-main
pnpm install
pnpm build
pnpm mac:package
```
- `pnpm build`：编译 TypeScript 等，会把 extensions 一起纳入。
- `pnpm mac:package`：打出 macOS 的 `dist/OpenClaw.app`（或你脚本里写的输出路径）。
3. **若插件是后加的**：先 `pnpm install --no-frozen-lockfile` 再执行上面 build 与 mac:package。
4. **配置**：打包后的客户端仍从 `~/.openclaw/openclaw.json`（或应用内配置）读 `lumiiApiBase`，需在应用里或本机配置好 Lumii API 地址。
---
## 六、接口说明（给二次开发用）
- 插件内部会请求：`POST {lumiiApiBase}/api/lumii/openclaw/pairing`
- Body 可选：`{ "gateway_base_url": "...", "openclaw_identity": "..." }`
- 返回：`pairing_code`、`device_code`、`verification_uri`、`expires_in`
- 二维码内容为 JSON：`{"device_code":"...","pairing_code":"...","verification_uri":"..."}`，与 Lumii 侧约定一致。
---
## 七、常见问题
- **“Lumii API 地址未配置”**
在配置里设置 `plugins.entries.openclaw-lumii.config.lumiiApiBase` 或环境变量 `LUMII_API_BASE`，并重启 OpenClaw。
- **`openclaw plugins list` 里没有插件**
确认安装路径正确、目录里有 `package.json` 和 `index.js`，再执行一次 `openclaw plugins install <路径>`。
- **配对码无效或过期**
配对码约 10 分钟有效，超时需重新执行 `openclaw lumii-pair` 再在 Lumii 里绑定。
tools
Comments
Sign in to leave a comment