feat: improve gateway compatibility and complete i18n cleanup

2026-05-11 18:10:41 +08:00 · 2026-04-01 15:06:25 +08:00
parent 57b8b25946
commit b427a6b000
59 changed files with 6830 additions and 964 deletions
--- a/docs/index.html
+++ b/docs/index.html
@@ -34,7 +34,7 @@
    "description": "OpenClaw AI Agent 可视化管理面板，基于 Tauri v2 的跨平台桌面应用。内置晴辰助手支持工具调用，晴辰云 AI 接口一键接入。支持仪表盘监控、多模型配置、消息渠道管理、内置 QQ 机器人、实时 AI 聊天、记忆管理、Agent 管理、网关配置、内网穿透等功能。支持 11 种语言。",
    "url": "https://claw.qt.cool/",
    "downloadUrl": "https://github.com/qingchencloud/clawpanel/releases/latest",
-    "softwareVersion": "0.10.0",
+    "softwareVersion": "0.11.0",
    "author": {
      "@type": "Organization",
      "name": "晴辰云 QingchenCloud",
@@ -1155,7 +1155,7 @@
    <div class="orb orb-2" style="top:auto;bottom:-100px"></div>
    <div class="container-sm" style="position:relative;z-index:10">
      <div class="section-header">
-        <div class="reveal download-version"><span class="pulse"></span> <span id="dl-badge" data-i18n="dl.badge">v0.10.0 最新版</span></div>
+        <div class="reveal download-version"><span class="pulse"></span> <span id="dl-badge" data-i18n="dl.badge">v0.11.0 最新版</span></div>
        <h2 class="reveal section-title" data-i18n="dl.title"><span class="gradient-text">下载安装</span></h2>
        <p class="reveal section-desc" data-i18n="dl.desc">选择你的操作系统，一键下载安装</p>
      </div>
@@ -1165,11 +1165,11 @@
          <h3>macOS</h3>
          <p class="dl-desc" data-i18n="dl.mac.d">支持 Apple Silicon 和 Intel 芯片</p>
          <div class="dl-links">
-            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.10.0_aarch64.dmg" target="_blank" rel="noopener">
+            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.11.0_aarch64.dmg" target="_blank" rel="noopener">
              Apple Silicon (M1/M2/M3/M4)
              <span class="dl-format">.dmg</span>
            </a>
-            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.10.0_x64.dmg" target="_blank" rel="noopener">
+            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.11.0_x64.dmg" target="_blank" rel="noopener">
              <span data-i18n="dl.mac.intel">Intel 芯片</span>
              <span class="dl-format">.dmg</span>
            </a>
@@ -1187,11 +1187,11 @@
          <h3>Windows</h3>
          <p class="dl-desc" data-i18n="dl.win.d">支持 Windows 10 及以上版本</p>
          <div class="dl-links">
-            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.10.0_x64-setup.exe" target="_blank" rel="noopener">
+            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.11.0_x64-setup.exe" target="_blank" rel="noopener">
              <span data-i18n="dl.win.exe">安装程序</span>
              <span class="dl-format">.exe</span>
            </a>
-            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.10.0_x64_en-US.msi" target="_blank" rel="noopener">
+            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.11.0_x64_en-US.msi" target="_blank" rel="noopener">
              <span data-i18n="dl.win.msi">MSI 安装包</span>
              <span class="dl-format">.msi</span>
            </a>
@@ -1202,11 +1202,11 @@
          <h3>Linux</h3>
          <p class="dl-desc" data-i18n="dl.linux.d">支持主流 Linux 发行版</p>
          <div class="dl-links">
-            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.10.0_amd64.AppImage" target="_blank" rel="noopener">
+            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.11.0_amd64.AppImage" target="_blank" rel="noopener">
              <span data-i18n="dl.linux.ai">通用版</span>
              <span class="dl-format">.AppImage</span>
            </a>
-            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.10.0_amd64.deb" target="_blank" rel="noopener">
+            <a class="dl-link" href="https://claw.qt.cool/proxy/dl/github.com/qingchencloud/clawpanel/releases/latest/download/ClawPanel_0.11.0_amd64.deb" target="_blank" rel="noopener">
              Debian / Ubuntu
              <span class="dl-format">.deb</span>
            </a>
--- a/docs/openclaw-2026-3-28-compatibility.md
+++ b/docs/openclaw-2026-3-28-compatibility.md
@@ -0,0 +1,463 @@
+# 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 能力。
--- a/docs/openclaw-multi-instance-compatibility.md
+++ b/docs/openclaw-multi-instance-compatibility.md
@@ -0,0 +1,368 @@
+# OpenClaw 多实例兼容性优化方案
+
+更新时间：2026-03-31 01:07:53 +08:00
+
+## 背景
+
+当前 ClawPanel 已经具备“实例切换”的一部分界面与数据结构，但底层仍然以单一 OpenClaw 根目录为默认前提。这会在以下场景中产生明显冲突：
+
+1. 同一台机器存在多个 OpenClaw 安装目录。
+2. 用户手动切换了实例，但某些页面仍然读写旧路径。
+3. Tauri 桌面端与 Web dev-api 对实例的理解不一致。
+4. 多个 OpenClaw 同时运行时，Gateway 名称、Bonjour 广播、端口、配置文件读写可能相互干扰。
+
+这个问题不是单个页面写死路径，而是“实例选择层”和“本地路径解析层”没有完成统一抽象。
+
+## 现状诊断
+
+### 1. 现有能力
+
+当前仓库已经有三类相关能力：
+
+1. 面板设置页支持单个自定义 OpenClaw 路径。
+2. 前端侧边栏支持实例切换 UI。
+3. Web dev-api 具备实例列表、添加、删除、切换能力。
+
+### 2. 当前架构缺口
+
+#### 2.1 单路径配置不等于多实例支持
+
+Tauri 侧当前通过 `clawpanel.json.openclawDir` 决定唯一生效目录，本质上仍然是“全局单路径覆盖”，不是“多实例上下文切换”。
+
+#### 2.2 大量命令直接依赖单一根目录
+
+Rust 侧很多命令直接调用统一的 `openclaw_dir()`，例如：
+
+1. Agent 管理
+2. Memory
+3. Skills
+4. Messaging
+5. Service
+6. Pairing
+7. Config 读写
+
+这意味着只要当前根目录解析不正确，多个页面都会一起读错目录。
+
+#### 2.3 桌面端与 Web 端实例模型不一致
+
+前端 API 里 `instance_*` 被标记为仅 Web 后端实现，说明“实例管理”目前主要停留在 dev-api 层，而桌面端大量本地读写命令仍走 Tauri Rust 本地目录解析。
+
+结果就是：
+
+1. 前端能显示实例切换。
+2. 真实文件读写却未必跟随实例切换。
+3. 用户会感觉“切了实例，但操作的还是另一个 OpenClaw”。
+
+#### 2.4 本地多实例冲突缺少显式选择
+
+当系统中检测到多个 OpenClaw 安装时，当前没有统一的冲突选择弹窗，也没有清晰的“当前操作对象是谁”的确认流程。对于会修改配置、插件、Agent 文件的操作，这个缺口风险很高。
+
+## 根因
+
+根因可以归纳为一句话：
+
+> ClawPanel 目前有“实例列表”，但没有“实例上下文驱动的路径解析内核”。
+
+也就是说，实例是 UI 概念，不是系统级资源定位概念。
+
+## 目标
+
+本次优化的目标不是简单把路径输入框改成下拉框，而是建立完整的一套实例上下文机制。
+
+### 功能目标
+
+1. 支持同时管理多个本地 OpenClaw 安装目录。
+2. 支持远程实例、Docker 实例、本地实例统一出现在实例中心。
+3. 所有本地文件读写类能力都基于“当前激活实例”解析路径。
+4. 检测到多个候选 OpenClaw 时，必须弹窗让用户明确选择。
+5. 用户可以手动新增、重命名、移除、设为默认本地实例。
+6. 高风险操作前能明确显示当前目标实例与路径。
+
+### 体验目标
+
+1. 不允许“静默写错目录”。
+2. 不允许“界面切换了实例，后端仍操作旧实例”。
+3. 当前激活实例必须在侧边栏、详情页、设置页都可见。
+4. 冲突时优先询问用户，不做隐式猜测。
+
+## 设计原则
+
+1. 统一实例抽象，不再区分“本地路径选择”和“实例切换”两套逻辑。
+2. 本地实例必须有稳定 ID，不能只靠路径字符串临时判断。
+3. 路径解析必须收敛到单一入口函数，禁止业务模块自行拼接根目录。
+4. 冲突选择必须是显式交互，不能偷偷回退默认目录。
+5. Web 模式与桌面模式的数据模型必须一致。
+
+## 数据模型改造
+
+建议将“实例”扩展为统一模型：
+
+```json
+{
+  "activeInstanceId": "local-main",
+  "instances": [
+    {
+      "id": "local-main",
+      "name": "本机主实例",
+      "type": "local",
+      "openclawDir": "C:/Users/user/.openclaw",
+      "gatewayPort": 18789,
+      "version": "3.28.0",
+      "detected": true,
+      "isDefault": true,
+      "fingerprint": "sha1:...",
+      "lastSeenAt": 1774890473
+    },
+    {
+      "id": "local-dev",
+      "name": "开发实例",
+      "type": "local",
+      "openclawDir": "D:/OpenClaw/dev",
+      "gatewayPort": 28789,
+      "version": "3.28.0",
+      "detected": false,
+      "isDefault": false,
+      "fingerprint": "sha1:...",
+      "lastSeenAt": 1774890473
+    },
+    {
+      "id": "remote-xxxx",
+      "name": "远程节点",
+      "type": "remote",
+      "endpoint": "http://192.168.1.8:18789"
+    }
+  ]
+}
+```
+
+### 字段说明
+
+1. `id`：稳定实例 ID。
+2. `type`：`local`、`remote`、`docker`。
+3. `openclawDir`：仅本地实例必填。
+4. `fingerprint`：用于识别是否是同一个 OpenClaw 实例，避免路径变更后丢失绑定关系。
+5. `activeInstanceId`：全局激活实例，不再由单独的 `openclawDir` 决定一切。
+
+## 路径解析内核
+
+### 统一入口
+
+新增统一上下文解析函数：
+
+1. Rust：`resolve_active_instance_context()`
+2. Node dev-api：`resolveActiveInstanceContext()`
+
+返回结构建议为：
+
+```json
+{
+  "id": "local-dev",
+  "type": "local",
+  "name": "开发实例",
+  "openclawDir": "D:/OpenClaw/dev",
+  "configPath": "D:/OpenClaw/dev/openclaw.json",
+  "agentsDir": "D:/OpenClaw/dev/agents",
+  "workspaceDir": "D:/OpenClaw/dev/workspace"
+}
+```
+
+### 禁止继续直接使用全局根目录
+
+后续所有本地资源读写都应从实例上下文取值，不再在业务代码中直接调用全局默认目录。需要逐步替换以下模式：
+
+1. `openclaw_dir().join("openclaw.json")`
+2. `openclaw_dir().join("agents")`
+3. `OPENCLAW_DIR + ...`
+4. 基于固定 `~/.openclaw` 的路径常量
+
+## 实例发现与冲突检测
+
+### 自动发现来源
+
+建议本地实例发现至少覆盖以下来源：
+
+1. 默认目录：`~/.openclaw`
+2. 面板历史记录中的自定义目录
+3. 用户手动添加过的目录
+4. 最近成功运行 Gateway 的目录
+
+### 判定一个目录是不是有效 OpenClaw
+
+满足以下条件之一即可视为候选实例：
+
+1. 存在 `openclaw.json`
+2. 存在 `agents`、`logs`、`workspace` 等关键结构
+3. 通过读取配置可得到有效 Gateway 配置或版本信息
+
+### 冲突弹窗触发条件
+
+出现以下任一情况时必须弹窗：
+
+1. 启动时发现 2 个及以上本地有效实例，且尚未指定默认实例。
+2. 当前默认实例路径不存在，但发现其他可用实例。
+3. 用户执行高风险写操作时，当前实例存在歧义。
+4. 发现 Bonjour 名称或 Gateway 端口冲突，需要区分具体实例。
+
+## 交互方案
+
+### 1. 启动冲突选择弹窗
+
+当发现多个本地 OpenClaw 时，弹出实例选择框，展示：
+
+1. 实例名称
+2. 完整路径
+3. OpenClaw 版本
+4. Gateway 端口
+5. 最近使用时间
+6. 配置文件状态
+
+提供按钮：
+
+1. 设为当前实例
+2. 设为默认实例
+3. 查看详情
+4. 手动选择其他目录
+
+### 2. 侧边栏实例切换器增强
+
+当前侧边栏已有实例切换区域，后续应增强为：
+
+1. 本地实例与远程实例分组显示
+2. 当前实例显示路径简写
+3. 高风险页面顶部显示“当前实例路径”
+4. 切换实例后触发全局上下文刷新
+
+### 3. 设置页改造
+
+当前“OpenClaw 安装路径”单输入框应升级为“本地实例管理器”：
+
+1. 列出全部本地实例
+2. 支持新增目录
+3. 支持校验目录有效性
+4. 支持设为默认
+5. 支持删除失效记录
+
+## 实施分期
+
+### Phase 1：先打通实例上下文内核
+
+目标：所有本地读写命令都能跟随当前实例。
+
+改造项：
+
+1. 定义统一实例模型。
+2. 将 `activeInstanceId` 作为全局当前实例标识。
+3. 在 Rust 与 dev-api 中新增统一上下文解析函数。
+4. Agent、Config、Memory、Skills 先切到新解析层。
+
+### Phase 2：补齐实例发现与冲突弹窗
+
+目标：多实例存在时不再隐式写默认目录。
+
+改造项：
+
+1. 启动扫描候选实例。
+2. 新增实例冲突弹窗。
+3. 新增“记住我的选择”。
+4. 启动阶段写入最近使用实例。
+
+### Phase 3：统一桌面端与 Web 端实例能力
+
+目标：两套运行模式具有一致的数据模型与行为。
+
+改造项：
+
+1. 将 `instance_*` 能力从仅 Web 实现，补齐到 Tauri 端或抽象成统一后端层。
+2. 清理前端 `WEB_ONLY_CMDS` 中与实例管理相关的分支差异。
+3. 统一实例切换后的缓存失效与页面刷新策略。
+
+### Phase 4：增加保护性提示与审计
+
+目标：降低误操作风险。
+
+改造项：
+
+1. 高风险写操作展示当前实例标识。
+2. 写配置前生成实例级备份。
+3. 记录最近操作的实例与路径。
+
+## 受影响模块
+
+以下模块需要优先排查和改造：
+
+1. `src-tauri/src/commands/mod.rs`
+2. `src-tauri/src/commands/config.rs`
+3. `src-tauri/src/commands/agent.rs`
+4. `src-tauri/src/commands/memory.rs`
+5. `src-tauri/src/commands/skills.rs`
+6. `src-tauri/src/commands/messaging.rs`
+7. `src-tauri/src/commands/service.rs`
+8. `scripts/dev-api.js`
+9. `src/lib/tauri-api.js`
+10. `src/lib/app-state.js`
+11. `src/components/sidebar.js`
+12. `src/pages/settings.js`
+
+## 迁移建议
+
+### 配置兼容
+
+旧版本仅有：
+
+```json
+{
+  "openclawDir": "D:/OpenClaw/dev"
+}
+```
+
+迁移后建议自动转换为：
+
+```json
+{
+  "activeInstanceId": "local-migrated",
+  "instances": [
+    {
+      "id": "local-migrated",
+      "name": "迁移实例",
+      "type": "local",
+      "openclawDir": "D:/OpenClaw/dev",
+      "isDefault": true
+    }
+  ]
+}
+```
+
+### 兼容策略
+
+1. 首次迁移保留旧字段一段时间，只读不再写。
+2. 新逻辑优先读取实例模型。
+3. 若实例模型缺失，再回退读取旧 `openclawDir`。
+4. 一旦成功迁移，可在后续版本移除旧字段写入。
+
+## 验收标准
+
+满足以下条件，才算多实例兼容完成：
+
+1. 两个本地 OpenClaw 共存时，用户启动面板会看到明确选择。
+2. 切换本地实例后，Agent、Config、Skills、Memory、Channels 页面都读写对应实例目录。
+3. Tauri 与 Web 模式下，实例切换行为一致。
+4. 当前实例信息在 UI 中可见，不存在“我不知道现在在改谁”的状态。
+5. 任意高风险写操作都不会静默落到错误目录。
+
+## 明确不建议的方案
+
+以下做法不建议采用：
+
+1. 继续在更多页面增加单独的路径输入框。
+2. 只在前端记住当前实例，不改底层路径解析。
+3. 发现多个实例时自动猜测“最近修改时间最新的那个”。
+4. 仅修补 Agent 页面，不统一 Config、Memory、Skills 等其他模块。
+
+## 建议的下一步落地顺序
+
+1. 先把实例数据模型统一下来。
+2. 再实现 Rust 和 dev-api 的上下文解析内核。
+3. 然后改 Agent 与 Config 两条主链路做首批验证。
+4. 最后补冲突弹窗和设置页实例管理器。
+
+这样可以避免 UI 先做完，底层路径仍然写错的问题再次出现。
--- a/docs/version-maintenance.md
+++ b/docs/version-maintenance.md
@@ -50,6 +50,8 @@ ClawPanel 现在使用仓库根目录的 `openclaw-version-policy.json` 作为

 ClawPanel 现在以 `package.json` 作为主版本源，并通过脚本同步到其他文件。

+当前 `0.11.0` 起，版本同步脚本也会一并维护 `package-lock.json`，避免 npm 锁文件版本与程序版本漂移。
+
 推荐用法：

 ```bash
@@ -59,6 +61,7 @@ npm run version:set 0.9.1
 这条命令会同步以下文件：

 - `package.json`
+- `package-lock.json`
 - `src-tauri/tauri.conf.json`
 - `src-tauri/Cargo.toml`
 - `docs/index.html`