Files
op-packages/luci-app-openclaw/README.md
T

305 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# luci-app-openclaw
[![Bilibili](https://img.shields.io/badge/B%E7%AB%99-59438380-00a1d6?logo=bilibili)](https://space.bilibili.com/59438380)
[![Blog](https://img.shields.io/badge/Blog-910501.xyz-orange)](https://blog.910501.xyz/)
[![Build & Release](https://github.com/10000ge10000/luci-app-openclaw/actions/workflows/build.yml/badge.svg)](https://github.com/10000ge10000/luci-app-openclaw/actions/workflows/build.yml)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)
[OpenClaw](https://github.com/openclaw/openclaw) AI 网关的 OpenWrt LuCI 管理插件。
在路由器上运行 OpenClaw,通过 LuCI 管理界面完成安装、配置和服务管理。
<div align="center">
<img src="docs/images/2.png" alt="OpenClaw LuCI 管理界面" width="800" style="border-radius:8px;" />
</div>
**系统要求**
| 项目 | 要求 |
|------|------|
| 架构 | x86_64 或 aarch64 (ARM64) |
| C 库 | musl(自动检测;离线包仅支持 musl) |
| 依赖 | luci-compat, luci-base, curl, openssl-util, tar, script-utils |
| 存储 | **2GB 以上可用空间** |
| 内存 | 推荐 1GB 及以上 |
**当前适配版本**
| 组件 | 默认版本 | 说明 |
|------|----------|------|
| OpenClaw | `2026.9.36` | 默认通道 `extended-stable`(官方长期维护)。也可选 `latest` 通道(当前已验证 `2026.10.9`)或锁定具体版本,见下方「发布通道与版本」 |
| Node.js | `24.22.2` | 满足上述版本要求的 `>=24.22.1 <25 \|\| >=26.12.1`,也兼容旧版 `2026.9.1`。升级 OpenClaw 时先升级 Node.js;x86_64 与 aarch64 优先从官方、unofficial-builds 及镜像源获取,自托管资产作为兜底;严格校验 `engines.node`,失败即中止 |
| 微信插件 | `@tencent-weixin/openclaw-weixin@2.4.10` | CLI 使用 `@tencent-weixin/openclaw-weixin-cli@2.1.4` |
### 运行时与架构说明
- **x86_64 / aarch64 (musl)**:Node.js v24.22.2 优先通过上游 [unofficial-builds](https://unofficial-builds.nodejs.org/) 及 npmmirror 镜像源获取,安装时自动下载并强校验 `SHASUMS256.txt`。依赖只有系统 musl 和 `libgcc`。Release 中的 `node-bins` 资产是同一文件的兜底镜像,由 `.github/workflows/build-node-musl.yml` 校验哈希后原样转发。
### 发布通道与版本
插件把「上游已发布」和「本插件已验证」分开记录。上游版本通过 npm dist-tags 实时查询;已验证版本写在 `openclaw-compat.json`,包含 `engines`、生命周期脚本和 tarball `integrity`,安装时逐项比对。
| 选项 | 安装什么 |
|------|----------|
| `extended-stable`(默认) | 该通道的已验证版本,只接收修复,适合路由器长期运行 |
| `latest` | 该通道的已验证版本,功能更新快 |
| 锁定版本 | 指定版本,配置项 `openclaw.main.pin_version` |
| 允许安装未验证版本 | 上游最新版或矩阵外的锁定版本。生命周期脚本必须与已验证版本一致,否则仍会拒绝。兼容性由你自行承担 |
上游有更新但插件还没验证时,「检测升级」只提示,不会自动安装。在 LuCI 基本设置里选择,或使用命令行:
```bash
OC_CHANNEL=latest openclaw-env upgrade
OC_VERSION=2026.9.36 openclaw-env upgrade
OC_CHANNEL=latest OC_ALLOW_UNVERIFIED=1 openclaw-env upgrade
```
版本的验证范围记录在 `openclaw-compat.json` 的 `verification` 字段里,`device` 为 `null` 表示还没有真机验证记录。
## 📦 安装
### 方式一:.run 自解压包(推荐)
无需 SDK,适用于已安装好的系统。
```bash
# 下载最新版本(自动获取版本号)
VER=$(curl -sI "https://github.com/10000ge10000/luci-app-openclaw/releases/latest" 2>/dev/null | grep -i "location:" | sed 's/.*tag\/v\{0,1\}//' | tr -d '\r\n')
wget "https://github.com/10000ge10000/luci-app-openclaw/releases/download/v${VER}/luci-app-openclaw_${VER}.run"
sh "luci-app-openclaw_${VER}.run"
```
### 方式二:.ipk 安装
```bash
# 下载最新版本(自动获取版本号)
VER=$(curl -sI "https://github.com/10000ge10000/luci-app-openclaw/releases/latest" 2>/dev/null | grep -i "location:" | sed 's/.*tag\/v\{0,1\}//' | tr -d '\r\n')
wget "https://github.com/10000ge10000/luci-app-openclaw/releases/download/v${VER}/luci-app-openclaw_${VER}-1_all.ipk"
opkg install "luci-app-openclaw_${VER}-1_all.ipk"
```
### 方式三:集成到固件编译
适用于自行编译固件或使用在线编译平台的用户。
```bash
cd /path/to/openwrt
# 添加 feeds
echo "src-git openclaw https://github.com/10000ge10000/luci-app-openclaw.git" >> feeds.conf.default
# 更新安装
./scripts/feeds update -a
./scripts/feeds install -a
# 选择插件
make menuconfig
# LuCI → Applications → luci-app-openclaw
# 编译
make package/luci-app-openclaw/compile V=s
```
使用 OpenWrt SDK 单独编译:
```bash
git clone https://github.com/10000ge10000/luci-app-openclaw.git package/luci-app-openclaw
make defconfig
make package/luci-app-openclaw/compile V=s
find bin/ -name "luci-app-openclaw*.ipk"
```
## 🔰 首次使用
1. 打开 LuCI → 服务 → OpenClaw,点击「安装运行环境」
2. 安装完成后服务会自动启动,点击「刷新页面」查看状态
3. 进入「Web 控制台」,点击「在新窗口打开控制台」添加 AI 模型和 API Key
4. 进入「配置管理」可使用向导配置消息渠道
> OpenClaw 官方控制台响应头固定为 `X-Frame-Options: DENY`,浏览器不允许把它嵌入 LuCI 页面,所以只能在独立窗口中打开。
> 首次打开若提示需要设备配对,回到 LuCI「Web 控制台」页点击「📱 设备配对」批准,再刷新控制台窗口即可。
## 自定义安装路径
UCI 字段仍然是 `openclaw.main.install_path`,语义为基础目录。例如:
```bash
uci set openclaw.main.install_path='/mnt/data'
uci commit openclaw
openclaw-env setup
```
实际运行目录会固定展开为 `/mnt/data/openclaw`。如果误填 `/mnt/data/openclaw`,插件会自动规范化为 `/mnt/data`,不会再拼成 `/mnt/data/openclaw/openclaw`。
安装前会执行写入探针;如果 overlay 已满、只读或外置盘未正确挂载,安装会在下载前失败并给出明确日志。
## 预放置安装(安装时整机重启的设备)
部分采用厂商闭源内核的固件(例如 #113 中 IPQ60xx + Kwrt 的京东云亚瑟)在短时间内大量写盘时会被硬件看门狗复位。在线安装需要下载、解压 Node.js 并安装约 3 万个依赖文件,正好会触发这个问题,表现为安装一半路由器重启。这是内核层面的问题,插件无法从根本上修复。对这类设备,可以在电脑上准备好文件,限速拷贝到路由器,再让插件只做初始化。
**1. 选择存储位置**:优先选独立的 ext4 分区(如 eMMC 上的 `/opt`)。不要选 tmpfs 或 overlay。#113 的实测中,USB 盘上的 ext4 因日志和元数据写放大,反而比 eMMC 更容易触发复位。
**2. 在电脑上准备文件**(以 arm64 musl 设备为例,版本与插件默认版本保持一致。`2026.9.36` 解压后约 390MB,请预留足够空间):
```bash
# Node.js 运行时:musl 设备使用 unofficial-builds 的 musl 构建
curl -LO https://unofficial-builds.nodejs.org/download/release/v24.22.2/node-v24.22.2-linux-arm64-musl.tar.xz
tar xJf node-v24.22.2-linux-arm64-musl.tar.xz && mv node-v24.22.2-linux-arm64-musl node
# OpenClaw 及其依赖:按目标平台解析依赖树
npm install -g openclaw@2026.9.36 --prefix ./global \
--os=linux --cpu=arm64 --libc=musl --ignore-scripts --omit=optional
```
**3. 限速拷贝到路由器**:目录结构必须是 `<安装目录>/openclaw/node/bin/node` 和 `<安装目录>/openclaw/global/lib/node_modules/openclaw/openclaw.mjs`(插件按这两个路径识别已安装的运行环境)。拷贝时请限速,例如 `scp -l 16000 -r`(约 2MB/s);路由器的 SSH 不支持 SFTP 时加 `-O`。不要先拷贝压缩包再到路由器上解压,解压本身就会触发复位。
**4. 在路由器上完成初始化**:
```bash
uci set openclaw.main.install_path='/opt'
uci commit openclaw
openclaw-env setup
```
`setup` 识别到程序文件已就位、但还没有 `openclaw.json` 时,只会创建 `openclaw` 系统用户、校验 Node.js 版本、执行初始化,不下载、不解压任何文件。完成后在 LuCI → 服务 → OpenClaw 中启用服务,首次启动时会生成 `openclaw.json`。
> 限制说明:在线安装会在受控环境中执行经过校验的 OpenClaw `preinstall` / `postinstall` 脚本,预放置时用的是 `--ignore-scripts`,这两步不会执行。#113 的实测组合是 Node.js 22 + OpenClaw 2026.9.1,这个组合 `setup` 仍然接受;上面的新版本组合还没有在这类设备上验证过,请自行确认。`openclaw-env setup-offline <目录>` 是给 `.run` 离线安装器用的,它仍会在路由器上解压压缩包,不适合这类设备。
## 微信插件依赖
官方插件只声明了核心版本下限,旧插件在新核心上能装上但渠道会反复崩溃,所以每个已验证核心要求的最低插件版本记录在 `openclaw-compat.json` 里。`2026.9.x` 要求 `2.4.9` 及以上,`2026.10.9` 要求 `2.4.10` 及以上。升级核心时会自动收敛,结果见升级报告的 `WECHAT:` 一行。
微信渠道安装前会检查:
- `openclaw` 系统用户是否存在,不存在时自动创建
- `python3` 是否已安装;缺失时会自动执行 `opkg update && opkg install python3-light`
- npm cache、tmp、OpenClaw 数据目录是否可由 `openclaw` 用户写入
- 路由器到 `https://ilinkai.weixin.qq.com` 的 TLS/超时状态
- npm 插件是否已写入 `plugins.installs.openclaw-weixin`、`plugins.allow` 和 `channels.openclaw-weixin.enabled`
- 旧渠道名 `weixin` 会迁移为 `openclaw-weixin`
如自动安装失败,可手动安装:
```bash
opkg update
opkg install python3-light
```
微信配对推荐流程:
1. 在 LuCI「微信配置」页点击「安装/重新安装插件」。
2. 插件安装成功后点击「登录账号」。
3. 页面出现链接后,先点击打开链接,再用微信「扫一扫」扫码。
4. 等待页面提示登录成功,网关会重新加载微信账号。
5. 用微信给网关发一条测试消息,确认能触发 AI 回复。
常见失败原因:
- 二维码过期:重新点击「登录账号」生成新链接。
- 微信账号触发安全风控:更换常用设备/常用网络后再扫码,或换账号测试。
- 路由器网络异常:检查日志中的 `微信接口连通性检查`,重点看 TLS、timeout、DNS。
- 插件注册缺失:重新安装插件,启动时也会自动补齐 `openclaw-weixin` 配置。
- 目录权限错误:按页面日志提示修复 OpenClaw 数据目录权限。
## AI 模型配置
LuCI →「配置管理」里的交互式菜单和无 TTY 时的传统 Shell 菜单功能相同,共用同一个后端(`oc-providers.js`)和同一份目录(`provider-catalog.json`)。
| 按键 | 功能 |
|------|------|
| `q` | 常用 Provider 快速配置 |
| `1` | 官方 API(按量付费):OpenAI、Claude、Gemini、DeepSeek、千问、智谱等 |
| `2` | 订阅套餐、Coding Plan、账号登录:百炼、GLM、Kimi Code、Copilot 等 |
| `3` | 聚合平台与自定义 API:OpenRouter、硅基流动、OpenAI / Anthropic 兼容接口 |
| `4` | 本地与局域网模型:Ollama、vLLM、LM Studio |
| `5` | 查看模型与认证状态(已脱敏) |
| `6` / `7` | 切换默认模型 / 管理备用模型(fallback) |
| `8` | 连通性测试 |
| `9` | 删除凭据或 Provider |
| `w` | 官方完整配置向导 |
选模型时有三个来源,上游发布新模型后通常不必升级插件:
1. **精选模型**:内置在目录里,离线可用,并注明核实时依据的 OpenClaw 版本。
2. **从 OpenClaw 获取完整列表**:调用 `openclaw models list`,失败时依次回落到 `--refresh` 和本地缓存,并显示真实原因。
3. **手动输入模型 ID**:始终保留。
使用时注意:
- **能查到模型不等于账号有权调用。** 列表只代表上游登记过这个模型,要确认账号能否调用请用连通性测试。它会发出真实请求,可能消耗少量 token。Gateway 运行时走 `models.probe`,不会中断服务。
- **凭据不写入 `auth-profiles.json`。** 该文件已被上游退役,Key 由官方 CLI 存入 `state/openclaw.sqlite`。Key 通过环境变量或标准输入传递,不进命令行参数,也不显示在菜单输出里。自定义 Provider 的 Key 按上游设计以明文保存在 `openclaw.json` 的 `models.providers` 下,备份文件里也有,请妥善保管。
- **不会覆盖已有配置。** 新增 Provider 默认保留当前默认模型,已有凭据原地更新。同一 ID 的自定义 Provider 只追加模型,Base URL 不同时拒绝。配置文件损坏时直接中止,原文件不变。
- **部分 Provider 需要官方插件。** 菜单会先询问,同意后才安装 `@openclaw/*-provider`。
- **OAuth 和设备码登录**(Copilot、Codex、MiniMax)只透传官方流程,维护者没有用真实账号验证过,菜单里有标注。
## 备份与恢复
LuCI → 服务 → OpenClaw →「💾 备份/恢复」:
- **创建**:「仅配置文件」只包含 `openclaw.json`(模型、渠道、插件设置);「配置 + 状态数据」还包含会话等状态数据。
- **下载**:列表中每份备份都可以下载到电脑保存。备份里有 API Key,请妥善保管。
- **上传与恢复**:重装或配置损坏后,上传之前下载的 `*-openclaw-backup.tar.gz`(上限 20MB),再在列表中点「恢复」即可。恢复前,当前配置会另存为 `openclaw.json.pre-restore`。
恢复只会写入 OpenClaw 状态目录(如 `/opt/openclaw/data/.openclaw`)。上传的备份不能包含状态目录之外的文件或链接,否则会被拒绝。
## 已知说明
- OpenClaw 的 diagnostic heartbeat 可能在日志中出现类似周期性探测记录。它不是一次真实用户对话请求;如需降低噪音,优先在 OpenClaw 配置或日志采集侧降低诊断日志级别,不建议直接修改模型调用逻辑。
- 配置管理界面依赖 `oc-config-interactive.js`;若该文件缺失(例如自行裁剪打包清单),
界面会静默回落到功能较少的传统数字菜单。`tests/test_packaging_parity.sh` 会校验
三条打包路径的文件清单一致性。
- 当前仓库提供源码、OpenWrt feeds 集成方式、本地 `.run` / `.ipk` 构建脚本入口;推送 `v*` 标签后 CI 会自动构建并发布 Release 产物。
## 📂 目录结构
```
luci-app-openclaw/
├── Makefile # OpenWrt 包定义
├── luasrc/
│ ├── controller/openclaw.lua # LuCI 路由和 API
│ ├── openclaw/paths.lua # 路径规范化与安全校验
│ ├── model/cbi/openclaw/basic.lua # 主页面
│ └── view/openclaw/
│ ├── status.htm # 状态面板
│ ├── advanced.htm # 配置管理(终端)
│ ├── console.htm # Web 控制台
│ └── wechat.htm # 微信渠道向导
├── root/
│ ├── etc/
│ │ ├── config/openclaw # UCI 配置
│ │ ├── init.d/openclaw # 服务脚本
│ │ └── uci-defaults/99-openclaw # 初始化脚本
│ └── usr/
│ ├── libexec/ # 共享 shell helper
│ ├── bin/openclaw-env # 环境管理工具
│ └── share/openclaw/
│ ├── oc-config.sh # 配置管理入口(无 TTY 时的回退菜单)
│ ├── oc-config-interactive.js # 交互式配置菜单(默认路径)
│ ├── oc-menu-engine.js # 方向键菜单引擎
│ ├── oc-providers.js # 模型与凭据配置后端(两套菜单共用)
│ ├── oc-config-fixups.js # 启动和升级前迁移旧版配置字段
│ ├── provider-catalog.json # Provider 目录与精选模型(唯一数据源)
│ ├── openclaw-compat.json # 发布通道与已验证版本矩阵
│ ├── openclaw-package-contract.js # 安装包与运行时契约校验
│ ├── web-pty.js # Web PTY 服务
│ └── ui/ # 配置终端前端资源
├── scripts/
│ ├── build_ipk.sh # 本地 IPK 构建
│ ├── build_run.sh # .run 安装包构建
│ ├── gen-release-body.sh # Release 说明生成
│ └── build-node-musl.sh # 转发并校验 Node.js arm64 musl 兜底资产
├── tests/ # 契约测试(sh tests/run_all.sh)
└── .github/workflows/
├── build.yml # 在线构建 + 发布
└── build-node-musl.yml # Node.js musl 构建
```
## 🤝 贡献
欢迎提交 Issue 和 Pull Request!
## 📄 License
[GPL-3.0](LICENSE)