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

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"

🔰 首次使用

1. 打开 LuCI → 服务 → OpenClaw，点击「安装运行环境」
2. 安装完成后服务会自动启动，点击「刷新页面」查看状态
3. 进入「Web 控制台」，点击「在新窗口打开控制台」添加 AI 模型和 API Key
4. 进入「配置管理」可使用向导配置消息渠道

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

微信配对推荐流程：

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