lingyuzeng/luci-app-openclaw
1
0
Fork 0
mirror of https://github.com/hotwa/luci-app-openclaw.git synced 2026-03-30 20:25:44 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity
Files
codex/custom-install-root
luci-app-openclaw/docs/UPGRADE_GUIDE_v2026.3.13.md
10000ge10000 1df1a4170b release v2.0.0: 适配 OpenClaw v2026.3.13 
重大变更:
- 配置管理菜单重构，更清晰的导航结构
- 新增高级配置菜单
- 新增全局环境变量 /etc/profile.d/openclaw.sh

修复:
- QQ 机器人插件配置名称不匹配 (#XX)
- 安装运行环境报错缺少 libstdcpp6 (#28)
- 环境变量路径混乱 (#42)

新增:
- 查看日志功能
- 飞书 Bot 配置流程优化

适配:
- Node.js 版本升级到 22.16.0
- OpenClaw 版本升级到 v2026.3.13
- 依赖声明新增 libstdcpp6
2026-03-17 01:51:20 +08:00

16 KiB
Raw Permalink Blame History

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 配置文件格式变化

新增配置项

{
  "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 设置):

# 在会话中切换 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 版本要求提升

- 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

新增内容:

## [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

- 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 入口

建议新增菜单项:

# 在模型配置菜单中新增 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 测试前准备

# 1. 备份当前配置
cp -r /opt/openclaw/data/.openclaw /tmp/openclaw-backup

# 2. 记录当前版本
openclaw --version

# 3. 检查 Node.js 版本
node --version

3.2 升级测试步骤

3.2.1 全新安装测试

# 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 升级安装测试

# 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 配置兼容性测试

# 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 性能测试

# 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 自动回滚脚本

#!/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 手动回滚步骤

# 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. 验证版本号已更新
方式二：通过命令行升级
# SSH 登录后执行
openclaw-env upgrade

# 升级后运行迁移
openclaw doctor --fix

# 验证版本
openclaw --version
方式三：指定版本升级
# 指定升级到 v2026.3.13
export OC_VERSION=2026.3.13
openclaw-env upgrade

升级后验证

# 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 版本是否满足要求：

node --version  # 应显示 v22.16.0 或更高

Q: 升级后配置丢失？

A: 配置文件位于 /opt/openclaw/data/.openclaw/，检查是否正确恢复。

Q: 如何回滚到旧版本？

A: 执行以下命令：

export OC_VERSION=2026.3.8
openclaw-env upgrade

安全改进说明

本次升级包含多项安全修复，建议所有用户尽快升级：

  • WebSocket 跨站劫持漏洞修复
  • 设备配对安全增强
  • 命令审批安全加固
  • 多个渠道 Webhook 安全增强

六、附录

A. 版本发布说明链接

B. 相关 Issue 和 PR

本次升级涉及的主要变更：

  • Node.js 最低版本要求: #45640
  • Fast Mode 支持: 多个 PR
  • 安全修复: 多个 GHSA 编号

C. 联系方式

如有问题，请通过以下方式反馈：

文档版本: 1.0 创建日期: 2026-03-16 最后更新: 2026-03-16

Reference in New Issue View Git Blame Copy Permalink