lingyuzeng/luci-app-openclaw
1
0
Fork 0
mirror of https://github.com/hotwa/luci-app-openclaw.git synced 2026-04-01 05:25:42 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Merge upstream/main into main

Browse Source
This commit is contained in:
mm644706215
2026-03-31 14:26:35 +08:00
parent 156837877d 4d565ee785
commit 12a4b836c0
7 changed files with 192 additions and 663 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.gitignore vendored
View File

@@ -21,3 +21,9 @@ Thumbs.db
*.swp
*.swo
*~
# Claude Code local settings
.claude/
# Internal notes (not for release)
docs/notes/

117
CHANGELOG.md
View File

@@ -4,18 +4,127 @@
格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)。
## [2.0.1] - 2026-03-26
## [2.0.1] - 2026-03-30
### 新增
### 适配 OpenClaw v2026.3.28
#### 版本变更
- **OC_TESTED_VERSION**: 从 2026.3.13 更新到 2026.3.28
- **磁盘空间要求**: 从 1.5GB 提升到 2GB (OpenClaw v2026.3.28 包体积约 200MB)
#### 兼容性分析
- **Node.js 版本**: v2026.3.28 要求 >= 22.14.0 (降低了要求，从 v2026.3.13 的 >= 22.16.0)
- **入口文件**: 无变化，仍为 `openclaw.mjs`
- **配置 Schema**: 向后兼容，无需迁移
- **API**: 向后兼容
#### 包体积变化
- v2026.3.13: ~94MB (4,730 文件)
- v2026.3.28: ~200MB (19,887 文件)
- 文件数量增加 4x+，包体积增加 2x+
#### 新增 Plugin SDK 导出 (20+)
新增 AI 提供商原生支持 SDK:
- `plugin-sdk/xai` — xAI (Grok) API 支持
- `plugin-sdk/vllm` — vLLM 高性能推理引擎支持
- `plugin-sdk/ollama` — Ollama 本地模型原生 SDK
- `plugin-sdk/openai` — OpenAI 原生 SDK
- `plugin-sdk/sglang` — SGLang 推理引擎支持
- `plugin-sdk/chutes` — Chutes AI 平台支持
- `plugin-sdk/google` — Google AI SDK
- `plugin-sdk/nvidia` — NVIDIA NIM API 支持
- `plugin-sdk/venice` — Venice AI 支持
- `plugin-sdk/minimax` — MiniMax API 原生 SDK
- `plugin-sdk/mistral` — Mistral AI 原生 SDK
- `plugin-sdk/qianfan` — 百度千帆大模型 SDK
新增功能模块 SDK:
- `plugin-sdk/zod` — Zod schema 验证支持
- `plugin-sdk/setup` — 安装配置向导 SDK
- `plugin-sdk/routing` — 模型路由配置 SDK
- `plugin-sdk/speech` — 语音处理 SDK
- `plugin-sdk/browser` — 浏览器自动化 SDK
新增顶级导出:
- `extension-api` — 扩展 API 入口 (用于插件开发)
#### 移除的依赖
以下渠道依赖被移除 (功能整合到核心或不再维护):
- `grammy` — Telegram Bot 框架 (改用内置实现)
- `@grammyjs/runner` — Telegram 运行器
- `@grammyjs/transformer-throttler` — Telegram 限流器
- `@whiskeysockets/baileys` — WhatsApp Web API (改用 matrix-js-sdk)
#### 新增依赖
核心依赖:
- `uuid@^13.0.0` — UUID 生成
- `gaxios@7.1.4` — Google API HTTP 客户端
- `matrix-js-sdk@41.2.0` — Matrix 协议支持 (替代 WhatsApp)
- `@anthropic-ai/vertex-sdk@^0.14.4` — Anthropic Vertex AI 支持
#### 依赖版本升级
核心依赖:
- `ws`: 8.19.0 → 8.20.0
- `hono`: 4.12.7 → 4.12.9
- `file-type`: 21.3.2 → 22.0.0
- `undici`: 7.24.1 → 7.24.6
- `sqlite-vec`: 0.1.7-alpha.2 → 0.1.7
AI/ML 依赖:
- `@mariozechner/pi-ai`: 0.58.0 → 0.63.1
- `@mariozechner/pi-tui`: 0.58.0 → 0.63.1
- `@mariozechner/pi-agent-core`: 0.58.0 → 0.63.1
- `@mariozechner/pi-coding-agent`: 0.58.0 → 0.63.1
- `@modelcontextprotocol/sdk`: 1.27.1 → 1.28.0
- `@agentclientprotocol/sdk`: 0.16.1 → 0.17.0
- `@aws-sdk/client-bedrock`: 3.1009.0 → 3.1019.0
#### pnpm 配置变更
新增 `ignoredBuiltDependencies`:
- `@discordjs/opus` — 跳过构建
- `koffi` — 跳过构建
新增 `onlyBuiltDependencies`:
- `@tloncorp/tlon-skill` — 需要构建
#### 中间版本变更 (v2026.3.22 ~ v2026.3.24)
v2026.3.22:
- Node.js 最低版本从 22.16.0 降低到 22.14.0
- 大量 plugin-sdk 模块重构
v2026.3.23:
- 修复版本发布问题
- 稳定性改进
v2026.3.24:
- 依赖安全更新
- 性能优化
#### 升级建议
1. **磁盘空间**: 确保至少 2GB 可用空间
2. **Node.js**: v22.16.0 完全兼容，无需降级
3. **配置迁移**: 现有配置向后兼容，无需手动干预
4. **备份**: 升级前建议执行 `openclaw backup create --only-config`
### hotwa 增强
#### 新增
- **ARM64 musl Node.js 双源下载**: `openclaw-env` 现在默认优先从 GitHub `node-bins` release 下载 Node.js，失败后自动回退到 Gitea 镜像 release
- **Node.js 24 预编译资产**: 新增 `node-v24.14.1-linux-arm64-musl.tar.xz`，供 ARM64 OpenWrt/iStoreOS 设备直接使用
### 变更
#### 变更
- **插件版本升级**: LuCI 插件包版本提升到 `2.0.1`，便于 iStore / opkg 识别升级
- **默认 Node.js 版本升级**: ARM64 musl 默认下载版本从 `23.2.0` 升级到 `24.14.1`
- **构建链路更新**: V2 Node.js musl 资产改为使用 Alpine `edge` 的 `nodejs` LTS 包构建，并校验产物必须精确命中 `24.14.1`
### 适配
#### 兼容补充
- **适配 OpenClaw 3.22-2**: 插件侧安装脚本与默认运行时已按 OpenClaw `2026.3.22` 版本链路完成同步，LuCI 页面中的已验证版本同步更新
- **Gitea 镜像同步**: `node-bins` release 的 GitHub / Gitea 两侧资产与说明已保持一致，确保 ARM64 musl 设备在主源异常时仍可回退下载

652
docs/UPGRADE_GUIDE_v2026.3.13.md
View File

@@ -1,652 +0,0 @@
# OpenClaw 版本升级推进流程文档
## 概述
本文档详细记录了从 OpenClaw v2026.3.8 升级到 v2026.3.13 的完整分析和推进流程。
| 项目 | 当前版本 | 目标版本 |
|------|----------|----------|
| OpenClaw | v2026.3.8 | v2026.3.13 |
| 发布日期 | 2026-03-09 | 2026-03-14 |
| Node.js 要求 | >= 22.x | >= 22.16.0 |
---
## 一、版本差异分析报告
### 1.1 版本发布时间线
| 版本 | 发布日期 | 类型 |
|------|----------|------|
| v2026.3.8 | 2026-03-09 | 稳定版 (当前) |
| v2026.3.11 | 2026-03-12 | 稳定版 |
| v2026.3.12 | 2026-03-13 | 稳定版 |
| v2026.3.13 | 2026-03-14 | 稳定版 (目标) |
### 1.2 关键变更摘要
#### 🔴 重大变更 (Breaking Changes)
1. **Node.js 最低版本要求提升**
- 旧版本: Node.js >= 22.x
- 新版本: Node.js >= 22.16.0
- **影响**: 当前项目 `NODE_VERSION="22.15.1"` 不满足要求，必须升级
2. **Cron/主动投递收紧 (v2026.3.11)**
- 孤立的直接 cron 发送不再通过临时 agent 发送或主会话摘要通知
- 需要运行 `openclaw doctor --fix` 迁移旧版 cron 存储
3. **插件安全策略变更 (v2026.3.12)**
- 禁用隐式工作区插件自动加载
- 克隆的仓库不能执行工作区插件代码，需要显式信任决策
#### 🟡 安全修复
| 编号 | 描述 | 影响范围 |
|------|------|----------|
| GHSA-5wcw-8jjv-m286 | WebSocket 跨站劫持漏洞修复 | Gateway 模式 |
| GHSA-99qw-6mr3-36qr | 设备配对安全：切换到短期引导令牌 | 配对流程 |
| GHSA-pcqg-f7rg-xfvv | 执行审批：Unicode 不可见字符转义 | 命令审批 |
| GHSA-9r3v-37xh-2cf6 | 执行检测：Unicode 规范化 | 命令检测 |
| GHSA-f8r2-vg7x-gh8m | 执行白名单：POSIX 大小写敏感 | 命令白名单 |
| GHSA-r7vr-gr74-94p8 | 命令权限：/config 和 /debug 需所有者权限 | 权限控制 |
| GHSA-rqpp-rjj8-7wv8 | Gateway 认证：清除未绑定客户端声明范围 | 认证安全 |
| GHSA-vmhq-cqm9-6p7q | 浏览器请求：阻止持久化配置文件变更 | 浏览器控制 |
| GHSA-2rqg-gjgv-84jm | Agent 安全：拒绝公共生成运行血统字段 | Agent 安全 |
| GHSA-wcxr-59v9-rxr8 | 会话状态：沙箱会话树可见性强制执行 | 会话隔离 |
| GHSA-2pwv-x786-56f8 | 设备配对：限制令牌范围 | 令牌安全 |
| GHSA-jv4g-m82p-2j93 | WebSocket 预认证：缩短握手保留时间 | 连接安全 |
| GHSA-6rph-mmhp-h7h9 | 代理附件：恢复媒体存储大小限制 | 文件上传 |
| GHSA-jf5v-pqgw-gm5m | 主机环境：阻止继承 GIT_EXEC_PATH | 环境隔离 |
| GHSA-g353-mgv3-8pcj | 飞书 Webhook：要求加密密钥 | 飞书渠道 |
| GHSA-m69h-jm2f-2pv8 | 飞书反应：群组授权和提及门控 | 飞书渠道 |
| GHSA-mhxh-9pjm-w7q5 | LINE Webhook：空事件也需要签名 | LINE 渠道 |
| GHSA-5m9r-p9g7-679c | Zalo Webhook：限制无效密钥猜测速率 | Zalo 渠道 |
#### 🟢 新增功能
1. **Control UI/Dashboard-v2 重构** (v2026.3.12)
- 模块化概览、聊天、配置、agent 和会话视图
- 命令面板、移动端底部标签
- 斜杠命令、搜索、导出、固定消息等聊天工具
2. **OpenAI/GPT-5.4 Fast Mode** (v2026.3.12)
- 可配置的会话级快速切换
- 跨 `/fast`、TUI、Control UI 和 ACP 支持
- 每模型配置默认值和 OpenAI/Codex 请求整形
3. **Anthropic/Claude Fast Mode** (v2026.3.12)
- 映射共享 `/fast` 切换到 Anthropic API `service_tier` 请求
- Anthropic 和 OpenAI fast-mode 层级的实时验证
4. **提供商插件架构** (v2026.3.12)
- Ollama、vLLM、SGLang 迁移到提供商插件架构
- 提供商拥有的引导、发现、模型选择器设置
5. **Kubernetes 部署支持** (v2026.3.12)
- 原始清单、Kind 设置、部署文档
6. **Ollama 本地模式向导** (v2026.3.11)
- 本地或云端+本地模式的首选 Ollama 设置
- 基于浏览器的云端登录
- 精选模型建议
7. **Docker 时区支持** (v2026.3.13)
- 新增 `OPENCLAW_TZ` 环境变量
8. **iOS/macOS UI 改进**
- iOS: 欢迎屏幕、停靠工具栏、聊天模型选择器
- macOS: 聊天模型选择器、思考级别选择持久化
#### 🔵 Bug 修复 (精选)
| 类别 | 修复内容 |
|------|----------|
| 模型支持 | Kimi Coding 工具调用格式修复、OpenRouter 模型 ID 规范化 |
| Telegram | HTML 消息分块、最终预览投递、IPv4 回退重试 |
| Discord | 回复分块、自动线程归档时长配置 |
| 飞书 | 本地图片自动转换、非 ASCII 文件名保留 |
| Mattermost | 块流重复消息修复、Markdown 格式保留 |
| 会话管理 | 重置模型重新计算、会话发现、ACP 会话别名 |
| 性能 | 构建内存回归修复 (~2x)、插件 SDK 块去重 |
### 1.3 配置文件格式变化
#### 新增配置项
```json
{
"agents": {
"defaults": {
"compaction": {
"postIndexSync": true
},
"memorySearch": {
"sync": {
"sessions": {
"postCompactionForce": false
}
}
}
}
},
"channels": {
"discord": {
"autoArchiveDuration": 60 // 60, 1440, 4320, 10080 分钟
}
}
}
```
#### Fast Mode 使用说明
Fast Mode 是 OpenClaw v2026.3.12 新增的功能，用于启用 OpenAI/Anthropic 的快速响应模式。
**注意**: Fast Mode 不是通过配置文件直接设置的，而是通过以下方式启用：
1. **TUI 界面**: 使用 `/fast` 命令切换
2. **Control UI**: 在聊天界面中切换 Fast Mode 开关
3. **API 调用**: 在请求参数中设置 `fastMode: true`
**配置示例** (通过 CLI 设置):
```bash
# 在会话中切换 Fast Mode
openclaw tui
# 然后输入 /fast 命令
# 或通过 Control UI (http://<设备IP>:18789) 在聊天设置中启用
```
**支持的模型**:
- OpenAI: GPT-4/5 系列 (需要 API 支持 fast tier)
- Anthropic: Claude 系列 (需要 API 支持 service_tier)
#### 废弃/变更配置项
- `channels.zalouser.dangerouslyAllowNameMatching` - 新增危险选项
- `channels.slack.dangerouslyAllowNameMatching` - 新增危险选项
- `channels.teams.dangerouslyAllowNameMatching` - 新增危险选项
### 1.4 API 接口变动
| 接口 | 变化类型 | 描述 |
|------|----------|------|
| `/pair` | 安全增强 | 使用短期引导令牌替代共享凭证 |
| `sessions_spawn` | 新增 | 支持 `resumeSessionId` 参数 |
| `sessions.patch` | 新增字段 | 支持 `spawnedBy`、`spawnDepth` 血统字段 |
| `node.pending.*` | 新增 | 内存中待处理工作队列原语 |
### 1.5 依赖项变更
#### Node.js 版本要求
```
旧版本: "engines": { "node": ">=22.x" }
新版本: "engines": { "node": ">=22.16.0" }
```
#### 包管理器
```
pnpm@10.23.0 (无变化)
```
#### 核心依赖更新 (精选)
| 包名 | 变化 |
|------|------|
| `@agentclientprotocol/sdk` | 升级到 0.16.1 |
| `playwright-core` | 升级到 1.58.2 |
| `sharp` | 升级到 ^0.34.5 |
| `hono` | 升级到 4.12.7 |
| `zod` | 升级到 ^4.3.6 |
### 1.6 二进制文件大小变化
| 指标 | v2026.3.8 | v2026.3.13 | 变化 |
|------|-----------|------------|------|
| npm 包解压大小 | ~90MB | ~95MB | +5MB |
| 文件数量 | ~4500 | ~4730 | +230 |
---
## 二、需要修改的文件清单及具体修改内容
### 2.1 必须修改的文件
#### 2.1.1 `root/usr/bin/openclaw-env`
**修改原因**: Node.js 版本要求提升
```diff
- NODE_VERSION="${NODE_VERSION:-22.15.1}"
+ NODE_VERSION="${NODE_VERSION:-22.16.0}"
- # 经过验证的 OpenClaw 稳定版本 (更新此值需同步测试)
- OC_TESTED_VERSION="2026.3.8"
+ # 经过验证的 OpenClaw 稳定版本 (更新此值需同步测试)
+ OC_TESTED_VERSION="2026.3.13"
```
#### 2.1.2 `CHANGELOG.md`
**新增内容**:
```markdown
## [2.1.0] - 2026-03-XX
### 适配 OpenClaw v2026.3.13
#### 升级说明
- **Node.js 版本升级**: 从 22.15.1 升级到 22.16.0 (OpenClaw 最低要求)
- **OpenClaw 版本升级**: 从 v2026.3.8 升级到 v2026.3.13
#### 重要变更
- 安全修复: WebSocket 跨站劫持漏洞、设备配对安全增强
- 新功能: Control UI 重构、Fast Mode 支持、Ollama 本地向导
- 插件安全: 禁用隐式工作区插件自动加载
#### 配置迁移
- 升级后建议运行 `openclaw doctor --fix` 迁移旧版 cron 存储
```
#### 2.1.3 `VERSION`
```diff
- 2.0.0
+ 2.1.0
```
### 2.2 建议修改的文件
#### 2.2.1 `root/usr/share/openclaw/oc-config.sh`
**检查点**:
1. 确认 `openclaw doctor --fix` 命令在升级后可用
2. 检查是否有新增的配置项需要在菜单中展示
3. 确认 Fast Mode 配置是否需要 UI 入口
**建议新增菜单项**:
```bash
# 在模型配置菜单中新增 Fast Mode 开关
configure_fast_mode() {
local current
current=$(get_config ".params.fastMode // false")
if [ "$current" = "true" ]; then
status="已启用"
else
status="已禁用"
fi
echo ""
echo "=== Fast Mode 配置 ==="
echo "当前状态: $status"
echo ""
echo "Fast Mode 可启用 OpenAI/Anthropic 的快速响应模式"
echo "需要 API 密钥支持相应的服务层级"
echo ""
echo "1) 启用"
echo "2) 禁用"
echo "0) 返回"
echo ""
read -p "请选择: " choice
case $choice in
1) set_config ".params.fastMode = true" ;;
2) set_config ".params.fastMode = false" ;;
0) return ;;
esac
}
```
#### 2.2.2 `luasrc/model/cbi/openclaw/basic.lua`
**检查点**:
1. 确认配置项与新版 OpenClaw 兼容
2. 考虑新增 Fast Mode 配置 UI
#### 2.2.3 `README.md`
**更新内容**:
- 更新版本号引用
- 添加升级注意事项
- 更新 Node.js 版本要求说明
### 2.3 需要验证的文件
| 文件 | 验证内容 |
|------|----------|
| `root/etc/init.d/openclaw` | 启动脚本兼容性 |
| `scripts/build_run.sh` | 构建脚本 Node.js 版本 |
| `scripts/build_ipk.sh` | IPK 构建脚本 |
---
## 三、升级测试方案
### 3.1 测试环境准备
#### 3.1.1 测试矩阵
| 环境 | 架构 | libc | 固件 |
|------|------|------|------|
| x86_64-glibc | x86_64 | glibc | Debian/Ubuntu |
| x86_64-musl | x86_64 | musl | OpenWrt/iStoreOS |
| aarch64-musl | aarch64 | musl | OpenWrt/iStoreOS |
#### 3.1.2 测试前准备
```bash
# 1. 备份当前配置
cp -r /opt/openclaw/data/.openclaw /tmp/openclaw-backup
# 2. 记录当前版本
openclaw --version
# 3. 检查 Node.js 版本
node --version
```
### 3.2 升级测试步骤
#### 3.2.1 全新安装测试
```bash
# 1. 清理旧环境
rm -rf /opt/openclaw
# 2. 安装新版本
openclaw-env setup
# 3. 验证版本
openclaw --version # 应显示 2026.3.13
node --version # 应显示 v22.16.0 或更高
# 4. 运行引导
openclaw onboard
# 5. 基础功能测试
openclaw doctor
```
#### 3.2.2 升级安装测试
```bash
# 1. 从 v2026.3.8 升级
export OC_VERSION=2026.3.13
openclaw-env upgrade
# 2. 验证版本
openclaw --version
# 3. 运行迁移
openclaw doctor --fix
# 4. 验证配置
openclaw config list
```
#### 3.2.3 配置兼容性测试
```bash
# 1. 恢复旧配置
cp -r /tmp/openclaw-backup/* /opt/openclaw/data/.openclaw/
# 2. 重启服务
/etc/init.d/openclaw restart
# 3. 检查日志
logread -f | grep -i openclaw
# 4. 验证渠道
openclaw channels list
```
### 3.3 功能回归测试清单
| 测试项 | 测试内容 | 预期结果 | 状态 |
|--------|----------|----------|------|
| 基础启动 | Gateway 启动 | 正常启动 | [ ] |
| 模型配置 | 设置活动模型 | 配置保存成功 | [ ] |
| Telegram | 消息收发 | 双向通信正常 | [ ] |
| QQ Bot | 消息收发 | 双向通信正常 | [ ] |
| 飞书 | 消息收发 | 双向通信正常 | [ ] |
| Discord | 消息收发 | 双向通信正常 | [ ] |
| Doctor | 健康检查 | 无错误报告 | [ ] |
| Doctor --fix | 迁移修复 | 成功执行 | [ ] |
| Fast Mode | 开关切换 | 配置生效 | [ ] |
| LuCI 界面 | 页面加载 | 正常显示 | [ ] |
| 日志查看 | 日志输出 | 正常显示 | [ ] |
| 备份恢复 | 配置备份/恢复 | 功能正常 | [ ] |
### 3.4 性能测试
```bash
# 1. 内存占用
ps aux | grep node
# 2. 启动时间
time /etc/init.d/openclaw start
# 3. 响应延迟
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3000/health
```
### 3.5 回滚策略
#### 3.5.1 自动回滚脚本
```bash
#!/bin/sh
# rollback.sh - OpenClaw 版本回滚脚本
echo "=== OpenClaw 版本回滚 ==="
# 1. 停止服务
/etc/init.d/openclaw stop
# 2. 备份当前状态
cp -r /opt/openclaw/data/.openclaw /tmp/openclaw-failed-upgrade
# 3. 恢复旧版本
export OC_VERSION=2026.3.8
openclaw-env upgrade
# 4. 恢复配置
cp -r /tmp/openclaw-backup/* /opt/openclaw/data/.openclaw/
# 5. 重启服务
/etc/init.d/openclaw start
# 6. 验证
openclaw --version
echo "回滚完成"
```
#### 3.5.2 手动回滚步骤
```bash
# 1. 停止服务
/etc/init.d/openclaw stop
# 2. 卸载新版本
npm uninstall -g openclaw --prefix /opt/openclaw/global
# 3. 安装旧版本
npm install -g openclaw@2026.3.8 --prefix /opt/openclaw/global
# 4. 恢复 Node.js (如需要)
# 重新运行 openclaw-env node 安装 22.15.1
# 5. 恢复配置
cp -r /tmp/openclaw-backup/* /opt/openclaw/data/.openclaw/
# 6. 重启服务
/etc/init.d/openclaw start
```
---
## 四、发布前检查清单
### 4.1 代码检查
- [ ] 所有文件修改已提交
- [ ] CHANGELOG.md 已更新
- [ ] VERSION 文件已更新
- [ ] README.md 已更新
### 4.2 测试检查
- [ ] x86_64-glibc 环境测试通过
- [ ] x86_64-musl 环境测试通过
- [ ] aarch64-musl 环境测试通过
- [ ] 全新安装测试通过
- [ ] 升级安装测试通过
- [ ] 配置兼容性测试通过
- [ ] 功能回归测试通过
- [ ] 性能测试无退化
### 4.3 文档检查
- [ ] 升级指南已更新
- [ ] 用户文档已更新
- [ ] API 文档已更新 (如有变化)
### 4.4 构建检查
- [ ] IPK 构建成功
- [ ] 离线安装包构建成功
- [ ] 文件大小合理
### 4.5 安全检查
- [ ] 无已知安全漏洞
- [ ] 敏感信息已清理
- [ ] 权限设置正确
---
## 五、用户升级指南草稿
### OpenClaw v2026.3.13 升级指南
#### 升级前须知
1. **Node.js 版本要求**: 本次升级要求 Node.js >= 22.16.0
2. **配置兼容性**: 现有配置文件兼容，无需手动迁移
3. **建议备份**: 升级前建议备份当前配置
#### 升级方式
##### 方式一：通过 LuCI 界面升级
1. 登录 LuCI 管理界面
2. 进入「服务」→「OpenClaw」
3. 点击「系统管理」→「升级 OpenClaw」
4. 等待升级完成
5. 验证版本号已更新
##### 方式二：通过命令行升级
```bash
# SSH 登录后执行
openclaw-env upgrade
# 升级后运行迁移
openclaw doctor --fix
# 验证版本
openclaw --version
```
##### 方式三：指定版本升级
```bash
# 指定升级到 v2026.3.13
export OC_VERSION=2026.3.13
openclaw-env upgrade
```
#### 升级后验证
```bash
# 1. 检查服务状态
/etc/init.d/openclaw status
# 2. 检查版本
openclaw --version
# 3. 运行健康检查
openclaw doctor
# 4. 检查日志
logread | grep -i openclaw | tail -20
```
#### 新功能体验
1. **Fast Mode**: 在模型配置中启用快速响应模式
2. **Control UI**: 访问 `http://<设备IP>:3000` 体验新版控制面板
3. **Ollama 本地向导**: 运行 `openclaw onboard` 配置本地模型
#### 常见问题
**Q: 升级后服务无法启动？**
A: 检查 Node.js 版本是否满足要求：
```bash
node --version # 应显示 v22.16.0 或更高
```
**Q: 升级后配置丢失？**
A: 配置文件位于 `/opt/openclaw/data/.openclaw/`，检查是否正确恢复。
**Q: 如何回滚到旧版本？**
A: 执行以下命令：
```bash
export OC_VERSION=2026.3.8
openclaw-env upgrade
```
#### 安全改进说明
本次升级包含多项安全修复，建议所有用户尽快升级：
- WebSocket 跨站劫持漏洞修复
- 设备配对安全增强
- 命令审批安全加固
- 多个渠道 Webhook 安全增强
---
## 六、附录
### A. 版本发布说明链接
- [v2026.3.13 Release Notes](https://github.com/openclaw/openclaw/releases/tag/v2026.3.13-1)
- [v2026.3.12 Release Notes](https://github.com/openclaw/openclaw/releases/tag/v2026.3.12)
- [v2026.3.11 Release Notes](https://github.com/openclaw/openclaw/releases/tag/v2026.3.11)
### B. 相关 Issue 和 PR
本次升级涉及的主要变更：
- Node.js 最低版本要求: #45640
- Fast Mode 支持: 多个 PR
- 安全修复: 多个 GHSA 编号
### C. 联系方式
如有问题，请通过以下方式反馈：
- GitHub Issues: https://github.com/10000ge10000/luci-app-openclaw/issues
- OpenClaw 官方: https://github.com/openclaw/openclaw/issues
---
**文档版本**: 1.0
**创建日期**: 2026-03-16
**最后更新**: 2026-03-16

6
luasrc/controller/openclaw.lua
View File

@@ -924,16 +924,16 @@ end
-- ═══════════════════════════════════════════
-- 系统配置检测 API (安装前检测)
-- 检测内存和磁盘空间是否满足最低要求
-- 要求: 内存 > 1GB, 磁盘可用空间 > 1.5GB
-- 要求: 内存 > 1GB, 磁盘可用空间 > 2GB (OpenClaw v2026.3.28+ 包体积约 200MB)
-- ═══════════════════════════════════════════
function action_check_system()
local http = require "luci.http"
local sys = require "luci.sys"
local valid_root, install_root, root_error = normalize_requested_install_root(http.formvalue("install_root"))
-- 最低要求配置
-- 最低要求配置 (v2026.3.28: 包体积 ~200MB, 建议 2GB 可用空间)
local MIN_MEMORY_MB = 1024 -- 1GB
local MIN_DISK_MB = 1536 -- 1.5GB
local MIN_DISK_MB = 2048 -- 2GB
local paths = get_runtime_paths(install_root)
local result = {

2
luasrc/model/cbi/openclaw/basic.lua
View File

@@ -138,7 +138,7 @@ act.cfgvalue = function(self, section)
html[#html+1] = 'logEl.textContent+="检测目录: "+(r.install_root||installRoot)+"\\n";'
html[#html+1] = 'logEl.textContent+="实际安装: "+(r.oc_root||_ocLastInstallPath)+"\\n";'
html[#html+1] = 'logEl.textContent+="内存: "+r.memory_mb+" MB (需要 ≥ 1024 MB) — "+(r.memory_ok?"✅ 通过":"❌ 不达标")+"\\n";'
html[#html+1] = 'logEl.textContent+="磁盘: "+r.disk_mb+" MB 可用"+(r.disk_path?" [检测路径 "+r.disk_path+"]":"")+" (需要 ≥ 1536 MB) — "+(r.disk_ok?"✅ 通过":"❌ 不达标")+"\\n";'
html[#html+1] = 'logEl.textContent+="磁盘: "+r.disk_mb+" MB 可用"+(r.disk_path?" [检测路径 "+r.disk_path+"]":"")+" (需要 ≥ 2048 MB) — "+(r.disk_ok?"✅ 通过":"❌ 不达标")+"\\n";'
html[#html+1] = 'logEl.textContent+="\\n";'
html[#html+1] = 'if(!r.pass){'
html[#html+1] = 'ocCloseSetupDialog();'

4
root/usr/bin/openclaw-env
View File

@@ -15,14 +15,14 @@ set -e
. /usr/libexec/openclaw-node.sh
# ── Node.js 版本策略 ──
# V2: 当前推荐版本，用于 OpenClaw v2026.3.11+ (默认下载 24.14.1，满足 >= 22.16.0)
# V2: 当前推荐版本，用于 OpenClaw v2026.3.22+ (默认下载 24.14.1，满足 >= 22.14.0)
# V1: 保留给显式指定旧版环境时使用，不再作为 V2 的自动回退
NODE_VERSION_V2="24.14.1"
NODE_VERSION_V1="22.15.1"
# 默认使用 V2 版本 (可通过 NODE_VERSION 环境变量覆盖)
NODE_VERSION="${NODE_VERSION:-${NODE_VERSION_V2}}"
# 经过验证的 OpenClaw 稳定版本 (更新此值需同步测试)
OC_TESTED_VERSION="2026.3.22"
OC_TESTED_VERSION="2026.3.28"
# 用户可通过 OC_VERSION 环境变量覆盖安装版本
OC_VERSION="${OC_VERSION:-}"
oc_load_paths "$OPENCLAW_INSTALL_ROOT"

68
root/usr/share/openclaw/oc-config.sh
View File

@@ -646,7 +646,9 @@ configure_model() {
echo -e " ${CYAN}11)${NC} 硅基流动 SiliconFlow"
echo -e " ${CYAN}12)${NC} Ollama (本地模型，无需 API Key)"
echo -e " ${CYAN}13)${NC} 腾讯云 Coding Plan (HY T1/TurboS/GLM-5/Kimi)"
echo -e " ${CYAN}14)${NC} 自定义 OpenAI 兼容 API"
echo -e " ${CYAN}14)${NC} Mistral AI (Mistral Large, Codestral)"
echo -e " ${CYAN}15)${NC} 百度千帆 (ERNIE-4.0, ERNIE-3.5)"
echo -e " ${CYAN}16)${NC} 自定义 OpenAI 兼容 API"
echo -e " ${CYAN}0)${NC} 返回"
echo ""
prompt_with_default "请选择" "1" choice
@@ -1263,6 +1265,70 @@ configure_model() {
fi
;;
14)
echo ""
echo -e " ${BOLD}Mistral AI 配置${NC}"
echo -e " ${YELLOW}获取 API Key: https://console.mistral.ai/api-keys/${NC}"
echo ""
prompt_with_default "请输入 Mistral API Key" "" api_key
if [ -n "$api_key" ]; then
auth_set_apikey mistral "$api_key"
echo ""
echo -e " ${CYAN}可用模型:${NC}"
echo -e " ${CYAN}a)${NC} mistral-large-latest — 旗舰模型，最强性能 (推荐)"
echo -e " ${CYAN}b)${NC} mistral-medium-latest — 均衡模型"
echo -e " ${CYAN}c)${NC} codestral-latest — 代码专用，极速补全"
echo -e " ${CYAN}d)${NC} mistral-small-latest — 轻量快速"
echo -e " ${CYAN}e)${NC} 手动输入模型名"
echo ""
prompt_with_default "请选择模型" "a" model_choice
case "$model_choice" in
a) model_name="mistral-large-latest" ;;
b) model_name="mistral-medium-latest" ;;
c) model_name="codestral-latest" ;;
d) model_name="mistral-small-latest" ;;
e) prompt_with_default "请输入模型名称" "mistral-large-latest" model_name ;;
*) model_name="mistral-large-latest" ;;
esac
register_custom_provider mistral "https://api.mistral.ai/v1" "$api_key" "$model_name" "$model_name"
register_and_set_model "mistral/${model_name}"
echo -e " ${GREEN}✅ Mistral AI 已配置，活跃模型: mistral/${model_name}${NC}"
fi
;;
15)
echo ""
echo -e " ${BOLD}百度千帆大模型配置${NC}"
echo -e " ${YELLOW}获取 API Key: https://console.bce.baidu.com/qianfan/ais/console/onlineService${NC}"
echo ""
echo -e " ${DIM}提示: 需要 API Key (Access Token) 和可选的 Secret Key${NC}"
echo ""
prompt_with_default "请输入百度千帆 API Key (Access Token)" "" api_key
if [ -n "$api_key" ]; then
auth_set_apikey qianfan "$api_key"
echo ""
echo -e " ${CYAN}可用模型:${NC}"
echo -e " ${CYAN}a)${NC} ernie-4.0-8k — 文心一言 4.0 (推荐)"
echo -e " ${CYAN}b)${NC} ernie-3.5-8k — 文心一言 3.5"
echo -e " ${CYAN}c)${NC} ernie-4.0-turbo-8k — 文心一言 4.0 Turbo"
echo -e " ${CYAN}d)${NC} ernie-speed-8k — 文心一言 Speed 极速"
echo -e " ${CYAN}e)${NC} 手动输入模型名"
echo ""
prompt_with_default "请选择模型" "a" model_choice
case "$model_choice" in
a) model_name="ernie-4.0-8k" ;;
b) model_name="ernie-3.5-8k" ;;
c) model_name="ernie-4.0-turbo-8k" ;;
d) model_name="ernie-speed-8k" ;;
e) prompt_with_default "请输入模型名称" "ernie-4.0-8k" model_name ;;
*) model_name="ernie-4.0-8k" ;;
esac
# 百度千帆使用 OpenAI 兼容接口
# 注: OpenClaw v2026.3.28+ 支持 qianfan 原生 provider
register_custom_provider qianfan "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop" "$api_key" "$model_name" "$model_name"
register_and_set_model "qianfan/${model_name}"
echo -e " ${GREEN}✅ 百度千帆已配置，活跃模型: qianfan/${model_name}${NC}"
fi
;;
16)
echo ""
echo -e " ${BOLD}自定义 OpenAI 兼容 API${NC}"
echo -e " ${YELLOW}支持任何兼容 OpenAI API 格式的服务商${NC}"