luci-app-openclaw
OpenClaw AI 网关的 OpenWrt LuCI 管理插件。
在路由器上运行 OpenClaw，通过 LuCI 管理界面完成安装、配置和服务管理。
系统要求
| 项目 | 要求 |
|---|---|
| 架构 | 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 及 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 基本设置里选择，或使用命令行：
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，适用于已安装好的系统。
# 下载最新版本（自动获取版本号）
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 安装
# 下载最新版本（自动获取版本号）
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"
方式三：集成到固件编译
适用于自行编译固件或使用在线编译平台的用户。
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 单独编译：
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"
🔰 首次使用
- 打开 LuCI → 服务 → OpenClaw，点击「安装运行环境」
- 安装完成后服务会自动启动，点击「刷新页面」查看状态
- 进入「Web 控制台」，点击「在新窗口打开控制台」添加 AI 模型和 API Key
- 进入「配置管理」可使用向导配置消息渠道
OpenClaw 官方控制台响应头固定为
X-Frame-Options: DENY，浏览器不允许把它嵌入 LuCI 页面，所以只能在独立窗口中打开。 首次打开若提示需要设备配对，回到 LuCI「Web 控制台」页点击「📱 设备配对」批准，再刷新控制台窗口即可。
自定义安装路径
UCI 字段仍然是 openclaw.main.install_path，语义为基础目录。例如：
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，请预留足够空间）：
# 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. 在路由器上完成初始化：
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
如自动安装失败，可手动安装：
opkg update
opkg install python3-light
微信配对推荐流程：
- 在 LuCI「微信配置」页点击「安装/重新安装插件」。
- 插件安装成功后点击「登录账号」。
- 页面出现链接后，先点击打开链接，再用微信「扫一扫」扫码。
- 等待页面提示登录成功，网关会重新加载微信账号。
- 用微信给网关发一条测试消息，确认能触发 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 |
官方完整配置向导 |
选模型时有三个来源，上游发布新模型后通常不必升级插件：
- 精选模型：内置在目录里，离线可用，并注明核实时依据的 OpenClaw 版本。
- 从 OpenClaw 获取完整列表：调用
openclaw models list，失败时依次回落到--refresh和本地缓存，并显示真实原因。 - 手动输入模型 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！