clawpanel/docs/openclaw-2026-3-28-compatibility.md

OpenClaw 2026.3.28 兼容性与旧版客户端风险说明

更新时间：2026-03-31 13:02 +08:00

一、文档目的

这份文档用于说明以下三个问题：

1. ClawPanel 当前是否应该将 OpenClaw 2026.3.28 / 2026.3.28-zh.2 设为推荐稳定版。
2. 旧版 ClawPanel 客户端在连接 OpenClaw 2026.3.28 时，兼容边界在哪里。
3. 后续发布策略应该如何兼顾“新版面板适配 3.28”与“旧客户端不要被错误引导升级”。

这份文档不是 OpenClaw 3.28 的功能手册，而是面向 ClawPanel 维护者的兼容性决策说明。

二、结论摘要

1. 当前结论

OpenClaw 2026.3.28 并不是“完全不兼容”。

就当前仓库代码来看：

1. 当前主干代码已经具备基础兼容能力。
2. 推荐稳定版策略文件已经可以指向 2026.3.28 / 2026.3.28-zh.2。
3. 真正需要重点关注的是旧版客户端的写入兼容性，而不是只读兼容性。

2. 不应简单得出的错误结论

以下两种判断都不准确：

1. “所有版本的 ClawPanel 都已经可以安全推荐 3.28。”
2. “旧版客户端完全不能连接 3.28。”

更准确的结论是：

旧版客户端大多可以读取和连接 OpenClaw 3.28，但不一定可以安全地修改其配置。

3. 推荐策略结论

后续发布不建议把 2026.3.28 直接作为所有历史 ClawPanel 版本的推荐稳定版。

更稳妥的策略是：

1. 仅对已经验证过的面板版本推荐 3.28。
2. 对历史旧版客户端保持旧稳定版映射，或至少不给 3.28 做默认推荐。
3. 对旧客户端连接 3.28 的场景，增加明确的风险提示，尤其是配置写入场景。

三、为什么源码改了稳定版，已发布旧桌面客户端可能仍显示旧值

ClawPanel 当前有两套版本策略读取路径：

1. Web / dev-api 模式

Web 模式下，版本策略由 Node 后端在运行时读取：

• 文件：scripts/dev-api.js
• 关键常量：VERSION_POLICY_PATH
• 数据源：仓库根目录 openclaw-version-policy.json

这种模式下，只要修改策略文件并重新启动 Web 后端，新的推荐版就会立即生效。

2. Tauri 桌面端

桌面端不是运行时读 JSON 文件，而是编译时直接把策略文件嵌入到二进制：

• 文件：src-tauri/src/commands/config.rs
• 关键实现：include_str!("../../../openclaw-version-policy.json")

这意味着：

1. 已发布的桌面安装包会继续使用它编译当时内嵌进去的策略。
2. 仓库里后续修改 openclaw-version-policy.json，不会自动影响用户手里的旧桌面安装包。
3. 如果要让桌面端真正把稳定版从 2026.3.13 切到 2026.3.28，必须重新构建并重新发布桌面端。

3. 这件事对旧客户端兼容策略的影响

这实际上天然把“旧客户端兼容”分成了两类：

1. 已发布旧桌面客户端：不会自动切到新推荐版。
2. 未来重新打包的旧版本分支 / Web 旧客户端：会直接吃到当前策略文件。

所以后续讨论“是否推荐 3.28”时，不能只看仓库代码，还要看对应客户端是否已经重新发布。

四、兼容性需要拆成两种：只读兼容 vs 写入兼容

1. 只读兼容

只读兼容指旧版客户端在连接 OpenClaw 3.28 后，是否还能正常：

1. 获取版本信息。
2. 查看服务状态。
3. 打开 Dashboard / About / Services 等页面。
4. 执行基础聊天和基础 RPC 请求。

从当前代码和已知链路看，这部分整体风险相对可控。

原因是：

1. 旧面板很多页面只是读取 getVersionInfo()、getServicesStatus()、readOpenclawConfig() 等接口返回结果。
2. OpenClaw 3.28 的新能力即使旧客户端不认识，通常也只是“页面不展示”，并不必然导致崩溃。
3. 当前版本比较逻辑已经支持去掉 -zh.x 后缀做基础版本判断，因此 2026.3.28-zh.2 不会天然被错误识别成不同主版本。

2. 写入兼容

写入兼容才是重点。

这里的风险不在于“旧客户端看不懂新字段”，而在于：

旧客户端一旦保存配置，会不会把 OpenClaw 3.28 新增的字段写没、改坏，或者回写成旧结构。

这是后续是否允许旧客户端“安全管理 3.28”最关键的判断标准。

五、旧客户端连接 3.28 时，当前最主要的风险点

5.1 风险一：整份 openclaw.json 回写

这是当前最需要警惕的风险。

Tauri 当前实现相对安全

在当前仓库版本里，Tauri 的 write_openclaw_config() 已经做了保留未知字段的处理：

• 文件：src-tauri/src/commands/config.rs
• 关键函数：write_openclaw_config()
• 合并逻辑：merge_configs_preserving_fields()

写入流程大致是：

1. 先读取现有配置。
2. 用新配置覆盖旧配置中的同名字段。
3. 保留未被新配置覆盖的已有字段。
4. 最后只清理 ClawPanel 自己的 UI 字段。

这意味着：

1. 如果 OpenClaw 3.28 新增了旧客户端不认识的合法字段，当前 Tauri 主干代码在整份保存时，有机会把这些字段保留下来。
2. 因此当前主干 Tauri 对 3.28 的配置写入兼容性，仍然属于当前仓库里更稳的一侧。

Web dev-api 当前实现已改善，但历史旧客户端仍然有风险

在当前仓库版本里，scripts/dev-api.js 的 write_openclaw_config({ config }) 已不再是“直接写传入对象”，而是：

1. 先读取现有 openclaw.json。
2. 通过 mergeConfigsPreservingFields(existing, config) 合并新旧配置。
3. 再执行 stripUiFields(merged)。
4. 最后写回磁盘。

这意味着：

1. 当前主干 Web dev-api 的整份保存风险，已经明显低于之前的直接覆盖实现。
2. 对于“旧客户端不认识、但本次前端没有主动覆盖”的字段，当前 Web 链路通常也能保留下来。
3. 但这仍然不是零风险：
   • 如果旧客户端在同一路径上用旧结构覆盖新结构，语义仍可能被改坏。
   • 数组类字段、整块对象替换、用户手动删字段等场景，仍然可能破坏 3.28 配置。
   • 已发布的历史旧 Web / 桌面客户端如果还没有这套 merge 逻辑，风险依旧存在。

风险结论

因此在“旧客户端兼容 3.28”这个问题上：

1. Tauri 主干版本的整份配置写入风险较低，但不是零风险。
2. 当前主干 Web dev-api 也已经具备 merge 保留未知字段能力，但整体风险仍略高于只读场景。
3. 任何历史旧版客户端，如果尚未具备 merge 保留未知字段能力，都不应默认推荐用户去管理 3.28 配置。

5.2 风险二：配置编辑器属于高风险入口

文件：src/pages/services.js

当前配置编辑器的流程是：

1. api.readOpenclawConfig() 读取完整配置。
2. 用户在文本框中编辑 JSON。
3. api.writeOpenclawConfig(config) 保存。

这个入口的问题在于：

1. 用户会把它当作“完整配置编辑器”。
2. 但旧客户端不一定理解 OpenClaw 3.28 的所有新字段语义。
3. 一旦旧客户端底层写入链路不保留未知字段，保存行为就可能破坏 3.28 配置。

因此对于旧客户端来说，这个页面属于：

• 高风险写入口。

如果后续要做旧客户端兼容保护，这里应该是首批增加警告或限制的页面。

5.3 风险三：Agent 高级配置字段不一定完全跟上 3.28

OpenClaw 3.28 在 Agent 侧的能力明显增强，例如：

1. 推理模式细分。
2. Fallback 模型链。
3. Heartbeat 轻量会话配置。
4. 更完整的 tools / sessions / subagents / runtime / params 配置。

当前主干代码里，ClawPanel 已经不是“完全没有 Agent 高级能力”，但也还没有完整承接 OpenClaw 3.28 的所有新能力。

当前已经有基础支持的部分

从当前代码看，以下能力已经有了基础承接：

1. Agent 详情页。
2. Bootstrap 文件读写。
3. model.primary + fallbacks。
4. thinkingDefault。
5. skills。
6. tools。

相关文件包括：

• src/pages/agent-detail.js
• src-tauri/src/commands/agent.rs
• scripts/dev-api.js

当前仍未完整对齐的部分

以下字段和能力，目前仍然更像“部分支持”或“未完整产品化”：

1. reasoningDefault
2. fastModeDefault
3. heartbeat
4. subagents
5. sandbox
6. params
7. runtime
8. 更完整的会话生命周期配置
9. 工具目录、生效工具、工具审批等高级工具系统

这意味着：

1. 新版主干客户端连接 3.28 时，基础 Agent 管理大体可用。
2. 历史旧客户端连接 3.28 时，只要涉及高级 Agent 配置写入，就存在结构丢失或无法表达的风险。

5.4 风险四：旧客户端可能“能看、能连、能聊”，但不代表“能安全写”

这是维护决策里最容易被忽略的一点。

很多时候用户看到旧客户端还能：

1. 显示版本号。
2. 启动 Gateway。
3. 正常聊天。

就会误以为“完全兼容”。

实际上这只能说明：

• 基础运行兼容。

它不能说明：

• 配置写入兼容。
• 高级能力兼容。
• 长期运维兼容。

因此在版本发布策略上，不能把“能连上 3.28”直接等同于“可以安全把 3.28 设成旧客户端的推荐稳定版”。

六、当前主干代码对 3.28 的真实支持情况

6.1 已经具备基础兼容能力的部分

当前主干分支已经有以下基础承接能力：

1. 版本策略统一文件

   • openclaw-version-policy.json

2. 前后端统一版本信息读取

   • Web：scripts/dev-api.js
   • Tauri：src-tauri/src/commands/config.rs

3. Agent 文件管理

   • list_agent_files
   • read_agent_file
   • write_agent_file

4. Agent 高级基础配置

   • primary model
   • fallbacks
   • thinkingDefault
   • tools
   • skills

5. 基础会话能力

   • sessions.list
   • sessions.delete
   • sessions.reset

因此，“ClawPanel 完全不支持 3.28”并不成立。

6.2 当前仍需补齐的部分

要说“ClawPanel 已完整支持 3.28 新能力”，当前也还做不到。

主要缺口包括：

1. Tauri / Web 对 Agent 高级字段的承接还不完全对齐。
2. 会话系统仍然只覆盖部分方法。
3. 工具系统仍然缺少目录与生效状态视图。
4. Heartbeat / lightContext / isolatedSession 等高级能力还没有完整面板入口。
5. 旧客户端缺少针对 3.28 的显式风险提示和保护策略。

七、为什么不建议把 3.28 直接推荐给所有历史客户端

如果把 openclaw-version-policy.json 中所有历史 panels.* 全部统一改成 2026.3.28 / 2026.3.28-zh.2，会有三个风险：

1. 风险一：未来重打旧版本分支时会误导用户

策略文件本身支持按面板版本映射推荐版。

如果后续把所有历史 panel 版本都指向 3.28，那么：

1. 历史旧版本一旦重新构建。
2. 或 Web 模式旧代码直接读取最新策略文件。
3. 用户就会被引导去安装 3.28。

但这些旧客户端并未必具备安全管理 3.28 配置的能力。

2. 风险二：旧客户端缺少写入保护

对于旧客户端来说，真正危险的是：

1. 打开配置编辑器。
2. 修改 Agent 高级配置。
3. 写入 openclaw.json。

如果它们没有“保留未知字段”的能力，就可能把 3.28 的新字段覆盖掉。

3. 风险三：推荐版意味着维护者背书

一旦某版本被标成“推荐稳定版”，用户会自然理解为：

1. 当前面板版本已经验证过。
2. 可以放心安装。
3. 后续出现配置或行为问题，默认认为是面板 bug。

如果实际上只是“能读能连，但不保证安全写”，就不适合把它作为所有历史客户端的推荐稳定版。

八、建议采用的版本推荐策略

8.1 分层推荐，而不是一刀切推荐

推荐策略应分为三层：

A. 已验证的新面板版本

这类版本已经完成对 3.28 的验证，可以推荐：

• official: 2026.3.28
• chinese: 2026.3.28-zh.2

B. 历史旧面板版本

这类版本不建议默认推荐 3.28。

可以继续保持旧稳定版，例如：

• official: 继续使用旧验证版
• chinese: 继续使用旧验证版

C. 未知来源 / 手动升级用户

允许用户自己切换到 3.28，但必须承担自测兼容性的责任。

适合继续保留以下原则：

1. 关于页允许手动切换版本。
2. 服务页只默认推荐“已验证稳定版”。
3. 高于推荐版时显示风险提示。

8.2 对旧客户端，应至少明确支持两档兼容声明

后续在说明和 UI 提示中，建议把兼容性拆成两档：

只读兼容

表示：

1. 可以连接 3.28。
2. 可以查看状态。
3. 可以做基础聊天。
4. 不代表所有配置编辑都安全。

完整管理兼容

表示：

1. 已验证当前客户端对 3.28 的配置读写安全。
2. 已验证关键高级字段不会被误删。
3. 可以作为推荐稳定版公开引导用户升级。

九、如果后续要做旧客户端保护，优先级建议

P0：先调整推荐策略

最先应该做的不是补全所有 3.28 UI，而是先控制策略风险：

1. 不再给所有历史面板版本一刀切推荐 3.28。
2. 只对当前验证通过的面板版本设置 3.28 推荐。
3. 历史版本保留旧推荐版映射。

P1：补旧客户端风险提示

优先在这些高风险入口增加提示：

1. 关于页版本管理。
2. 服务页配置编辑器。
3. Agent 高级配置页面。

提示目标不是阻止用户使用 3.28，而是明确说明：

• 当前客户端可能仅保证只读兼容或基础运行兼容。
• 高级配置写入需谨慎。

P2：补 Web 写入链路的未知字段保留能力

当前 scripts/dev-api.js 的 write_openclaw_config() 风险高于 Tauri。

如果要提高 3.28 在 Web 模式下的兼容性，建议优先把这条链路改成和 Tauri 一样的“先读现有配置、再 merge 保留未知字段”的模式。

P3：逐步补齐 3.28 高级能力

后续再考虑：

1. reasoning / fast mode
2. heartbeat 高级配置
3. sessions 全量方法
4. tools.catalog / tools.effective
5. requireApproval / 审批策略
6. subagents / sandbox / runtime / params

十、维护建议

后续在维护 OpenClaw 推荐版时，建议遵循以下原则：

1. 推荐稳定版不等于上游最新版。
2. 是否推荐，取决于当前面板版本是否已经验证过读写兼容。
3. 旧客户端兼容性优先看写入风险，而不是页面能不能打开。
4. Tauri 已发布旧包与仓库当前代码要分开判断。
5. Web 模式与桌面模式的写入安全性不能混为一谈。

十一、最终结论

最终建议如下：

1. 可以让当前主干 ClawPanel 以 OpenClaw 2026.3.28 / 2026.3.28-zh.2 为推荐稳定版。
2. 不要把 3.28 直接作为所有历史 ClawPanel 版本的推荐稳定版。
3. 对旧客户端，应将兼容性定义为“基础运行兼容优先、配置写入兼容待验证”。
4. 后续若要正式公开推广 3.28，应优先补策略分层和写入保护。

换句话说：

3.28 可以成为新面板的推荐稳定版，但不应成为所有旧客户端的默认推荐版。

十二、建议后续动作清单

建议按以下顺序推进：

1. 重新审视 openclaw-version-policy.json 的历史版本映射。
2. 为当前已验证的面板版本单独设置 3.28 推荐。
3. 保留历史旧面板版本的旧推荐版映射。
4. 在旧客户端的高风险写入口增加 3.28 风险提示。
5. 优先修复 Web write_openclaw_config() 的未知字段丢失风险。
6. 再逐步补齐 3.28 的高级 Agent / Session / Tools 能力。