【部署】升级现有的 OpenClaw 到最新版（v2026.8.2）

文章目录

- 一、安装流程总览
- 二、说明
- - [1. 环境准备（ $1/4$ Preparing environment）](#1. 环境准备（[1/4] Preparing environment）)
  - [2. 安装 OpenClaw（ $2/4$ Installing OpenClaw）](#2. 安装 OpenClaw（[2/4] Installing OpenClaw）)
  - [3. 最终化设置与 Doctor 自动修复（ $3/4$ Finalizing setup）](#3. 最终化设置与 Doctor 自动修复（[3/4] Finalizing setup）)
  - - [3.1 修复配置键迁移（Config warnings -> Doctor changes）](#3.1 修复配置键迁移（Config warnings -> Doctor changes）)
    - [3.2 状态迁移（state-migrations，17:34:56）](#3.2 状态迁移（state-migrations，17:34:56）)
    - [3.3 第二次配置键迁移（automatic config repair）](#3.3 第二次配置键迁移（automatic config repair）)
    - [3.4 插件能力确认（Plugin capabilities）](#3.4 插件能力确认（Plugin capabilities）)
    - [3.5 技能工坊提案迁移（Skill Workshop proposal）](#3.5 技能工坊提案迁移（Skill Workshop proposal）)
    - [3.6 Doctor 警告（非错误，仅提示）](#3.6 Doctor 警告（非错误，仅提示）)
    - [3.7 遗留状态迁移（Legacy state detected）](#3.7 遗留状态迁移（Legacy state detected）)
    - [3.8 清理旧的执行审批（Exec approvals）](#3.8 清理旧的执行审批（Exec approvals）)
    - [3.9 会话 SQLite 处理（Session SQLite）](#3.9 会话 SQLite 处理（Session SQLite）)
    - [3.10 插件注册表刷新](#3.10 插件注册表刷新)
    - [3.11 其他检查项（简略翻译）](#3.11 其他检查项（简略翻译）)
    - [3.12 最终修复动作（Doctor changes 继续）](#3.12 最终修复动作（Doctor changes 继续）)
    - [3.13 网关重启与验证](#3.13 网关重启与验证)
  - [4. 插件更新（Updating plugins）](#4. 插件更新（Updating plugins）)
  - [5. 安装验证（ $4/4$ Verifying installation）](#5. 安装验证（[4/4] Verifying installation）)
- 三、总结

一、安装流程总览

命令： curl -fsSL https://openclaw.ai/install.sh | bash

目的： 自动检测系统环境，升级现有的 OpenClaw 到最新版（v2026.8.2）。

二、说明

1. 环境准备（ $1/4$ Preparing environment）

操作	说明	具体操作与补充
✓ Detected: linux	检测到操作系统：Linux	自动识别为 Linux 发行版。
Install method: npm	安装方式：npm	选择通过 npm（Node.js 包管理器）进行升级。
Requested version: latest	请求版本：最新版	未指定版本，默认拉取最新稳定版。
· Existing OpenClaw installation detected, upgrading	检测到已有 OpenClaw 安装，执行升级	不是全新安装，而是对现有版本进行更新。
✓ Node.js v24.18.0 found	找到 Node.js v24.18.0	系统已安装 Node.js，版本满足要求。
· Active Node.js: v24.18.0 (/usr/bin/node)	当前使用的 Node.js 位于 /usr/bin/node	明确运行时路径。
· Active npm: 11.14.1 (/home/tht/.npm-global/bin/npm)	当前 npm 版本 11.14.1，位于用户全局目录	npm 工具已就绪。

2. 安装 OpenClaw（ $2/4$ Installing OpenClaw）

操作	说明	具体操作与补充
✓ Git already installed	Git 已安装	安装过程依赖 Git，已存在则跳过。
· Installing OpenClaw v2026.8.2	正在安装 OpenClaw v2026.8.2	开始下载并安装指定版本。
· Installing OpenClaw package	安装 OpenClaw npm 包	通过 npm 全局安装或更新 `openclaw` 包。
✓ OpenClaw npm package installed	OpenClaw npm 包安装完成	包已成功安装。
· Published openclaw bin link at /home/tht/.npm-global/bin/openclaw	在用户全局 bin 目录创建了 `openclaw` 命令软链接	确保 `openclaw` 命令可在终端直接调用。
✓ OpenClaw installed	OpenClaw 安装成功	软件主体安装阶段结束。

3. 最终化设置与 Doctor 自动修复（ $3/4$ Finalizing setup）

这是日志中最长、最关键的部分，Doctor 会扫描并自动修复配置和数据的不一致。

操作	说明	具体操作与补充
Warning: timed out during installer finalization probe: openclaw daemon status --json	警告：在检查守护进程状态时超时	安装器尝试查询服务状态未响应，但不影响后续修复（可能服务未启动）。
· Running openclaw doctor	执行 `openclaw doctor` 诊断修复	启动内置的配置和数据迁移工具。

3.1 修复配置键迁移（Config warnings -> Doctor changes）

操作	说明	补充说明
agents.entries: Moved agents.list to keyed agents.entries.	将旧版 `agents.list` 迁移到带键的 `agents.entries` 结构	原 `agents.list` 是一个数组，新版本要求使用对象键值对（以 agent 名称作为键），便于按名称索引。
Imported legacy exec approvals into shared SQLite state.	将旧版执行审批记录导入共享 SQLite 状态	原先 `exec approvals`（命令执行需要人工确认的规则）可能存在 JSON 文件中，现统一存入 SQLite。
Removed retired exec approvals JSON after recording its migration decision.	迁移完成后删除旧版执行审批 JSON 文件	确认 SQLite 导入无误后清理原始文件。

3.2 状态迁移（state-migrations，17:34:56）

此处重复了之前日志的内容，但这次是升级过程中的一部分。具体说明同前次翻译，不再赘述，概括为：

保留 lastTouchedAt 字段
迁移 1 个设备认证令牌、主设备身份到 SQLite
迁移 Memory Core 主机事件（152 行）至 SQLite
归档原 events.jsonl 为 .migrated
删除已验证的旧 JSON 文件

3.3 第二次配置键迁移（automatic config repair）

操作	说明	补充说明
Migrated legacy config keys in the active openclaw.json	迁移 `openclaw.json` 中的旧版配置键	对活动配置文件进行现代化改造。
Moved legacy memorySearch defaults → memory.search.	`memorySearch` 默认设置移至 `memory.search`	原顶层键被重命名并移到 `memory` 子对象下。
Removed retired gateway.tailscale.resetOnExit config.	删除废弃的 `gateway.tailscale.resetOnExit`	该配置在新版中不再支持，直接移除，使用内置行为。
Moved mcp.servers.zhihu_search.connectTimeout → connectionTimeoutMs (15000 ms)	知乎搜索 MCP 服务器的连接超时重命名为 `connectionTimeoutMs`，值为 15000ms	统一命名规范。
Moved mcp.servers.zhihu_search.timeout → requestTimeoutMs (30000 ms)	请求超时重命名为 `requestTimeoutMs`，值 30000ms	同上。
Copied the legacy default model map to agents.defaults.modelPolicy.allow.	将旧版默认模型映射复制到 `agents.defaults.modelPolicy.allow`	原先允许的模型列表被整合到策略字段中，方便后续控制。
Moved plugins.entries.codex-supervisor to plugins.entries.codex.config.supervision.	将插件条目 `codex-supervisor` 移至 `codex` 插件的 `config.supervision` 下	插件配置结构扁平化调整。
Applied tier-eval tranche retirements; canonical settings and built-in defaults now apply.	应用分层评估批次废弃；标准设置和内置默认值现已生效	补充：清理了实验性功能开关，所有未显式指定的参数回退到官方默认值，避免旧参数干扰。
Moved gateway.nodes.denyCommands → gateway.nodes.commands.deny.	`denyCommands` 迁移至 `commands.deny`	命令黑名单移至 `commands` 子对象，结构更清晰。
Removed retired runtime tuning knobs; built-in defaults now apply.	删除废弃的运行时调优参数；现在使用内置默认值	补充：移除一些早期用于性能调优的实验性参数（如并发数、缓存大小），系统自动采用优化后的默认值。

3.4 插件能力确认（Plugin capabilities）

检测到 codex 插件（@openclaw/codex）未安装，但 Doctor 自动执行了安装（见后文）。
用户被提示接受插件能力（工具、合约等），选择 Yes。
随后 Doctor 安装缺失的 codex 插件。

3.5 技能工坊提案迁移（Skill Workshop proposal）

操作	说明	补充
Migrated 1 Skill Workshop proposal into shared SQLite.	将 1 条技能工坊提案迁移到共享 SQLite	技能工坊（Skill Workshop）是用于定义自定义技能的机制，其提案数据从文件迁移到数据库。

3.6 Doctor 警告（非错误，仅提示）

contextEngine 缺失 ：lossless-claw 上下文引擎未注册，暂不影响使用。
Agent 模型无 fallback ：agents.entries.main.model 被设为单个模型字符串，未配置 fallback 列表，导致该模型不可用时无备选。提示添加 fallbacks 数组。
明文模型凭证：检测到 8 个明文 API Key 存储在配置文件中，Doctor 复制并验证了其中 6 个到 SQLite，但明文原值仍存在，后续需要迁移到 SecretRefs（安全引用）。
网关绑定仅本地 ：gateway.bind 为 loopback，建议改为 lan 或启用 Tailscale，以便外部访问。
未配置命令所有者 ：commands.ownerAllowFrom 未设置，提示应指定一个管理员用户 ID（如 Telegram ID），否则某些特权命令无法执行。
未配置备份 ：提示执行 openclaw backup create 启用备份。

3.7 遗留状态迁移（Legacy state detected）

操作	说明	补充
TUI last-session pointers: legacy JSON file → shared SQLite state	TUI 最后会话指针从 JSON 迁移到 SQLite	TUI（终端界面）记录的上次会话信息现存入数据库。
config audit log: legacy JSONL file → shared SQLite state	配置审计日志从 JSONL 迁移到 SQLite（新增 48 行）	审计日志（谁何时改了配置）被导入，原文件归档为 `.migrated` 和 `.raw`。
Workspace setup and attestations: legacy files → shared SQLite state	工作区设置和证明文件迁移到 SQLite	工作区的初始化状态和凭证信息从独立文件迁入数据库。
Removed retired workspace state after verified SQLite import.	验证后删除旧版工作区状态文件	清理原文件。

3.8 清理旧的执行审批（Exec approvals）

操作	说明	补充
removed 20 older generated approvals that were not tied to a working directory	移除了 20 条未绑定工作目录的旧版自动审批记录	这些审批可能是临时生成的，已失效，清理后可减少冗余。手动添加的规则不受影响。

3.9 会话 SQLite 处理（Session SQLite）

操作	说明	补充
Legacy entries: 1; SQLite entries: 1.	旧版条目数 1，SQLite 条目数 1	会话条目一致，无需额外迁移。
Transcript events: imported=6; validated=0.	会话记录事件：导入 6 条，验证 0 条	导入了 6 条对话事件，但可能因格式问题未做深度校验。
Archived 3 legacy transcript artifact(s).	归档了 3 个旧版会话记录文件	将旧的转录文件（artifact）归档。
Archived 55 unreferenced JSONL artifact(s).	归档了 55 个未被引用的 JSONL 文件	这些文件可能来自之前的实验或临时数据，不再被系统使用，被归档保存。

3.10 插件注册表刷新

操作	说明
Plugin registry refreshed: 44/64 enabled plugins indexed.	插件注册表已刷新：64 个已启用插件中索引了 44 个（其余可能未启用或未安装）。

3.11 其他检查项（简略翻译）

OAuth 目录：未创建（因为没有 WhatsApp/配对通道处于活跃状态）。
备份：无记录，建议创建。
使用成本缓存：删除 1 个可重建的旧缓存文件，SQLite 会按需重建。
桌面功能 ：默认禁用，可启用 desktop.host.enabled=true。
安全性：再次提醒明文 secret，需迁移至 SecretRefs。
GitHub 项目 ：建议设置 gateway.controlUi.github.token。
浏览器中继认证：建议升级到 v2 并关闭遗留认证。
插件能力许可 ：多个插件（lossless-claw, memory-lancedb, openclaw-honcho, searxng）需要用户显式接受能力，Doctor 会后续提示安装。

3.12 最终修复动作（Doctor changes 继续）

操作	说明	补充
Create heartbeat monitor for agent "main" at 30m.	为主 agent "main" 创建心跳监控，间隔 30 分钟	用于检测 agent 是否存活，若异常可重启。
Migrated ~/.openclaw/workspace/HEARTBEAT.md into cron scratch for Heartbeat (main).	将 `HEARTBEAT.md` 文件迁移到 cron 暂存区	原有心跳文件被整合进调度系统。
Removed untouched ~/.openclaw/workspace/TOOLS.md after archiving it.	移除未修改的 `TOOLS.md` 文件（已归档）	该文件可能已被新机制取代，归档后删除。
Gateway health will be checked after Doctor repair.	修复完成后将检查网关健康状态。	---
Device pairing legacy stores not imported yet; restart gateway to import.	旧设备配对存储（`paired.json`, `pending.json`）尚未导入 SQLite，需要重启网关来导入。	---

3.13 网关重启与验证

重启 systemd 服务 openclaw-gateway.service，确认运行正常。

4. 插件更新（Updating plugins）

Doctor 之后，安装器自动更新/安装多个插件：

lossless-claw：从 0.15.3 → 1.0.0
memory-lancedb ：从 2026.7.1 → 2026.8.2（需用户接受能力，选择 y）
openclaw-honcho：1.5.3 → 1.5.5
searxng：2026.7.1 → 2026.8.2（注意插件 manifest id 与包名不同，但配置键使用 manifest id）
codex 已是最新（2026.8.2）

安装完成后再次重启网关，确保新插件生效。

5. 安装验证（ $4/4$ Verifying installation）

检查版本号
检查网关服务状态
全部通过，升级完成！

最后显示 Dashboard URL（http://127.0.0.1:18789/），并尝试打开浏览器。

三、总结

软件升级：从旧版升级到 OpenClaw v2026.8.2，使用 npm 全局更新。
数据迁移 ：
- 将所有旧版 JSON/JSONL 格式的状态（设备认证、身份、会话、审批、工作区、审计日志、TUI 指针等）全部迁移到统一的 SQLite 存储，提高一致性和查询效率。
- 清理并归档原始文件（加 .migrated 后缀或移至备份目录）。
配置标准化 ：
- 对 openclaw.json 中多个过时或命名不规范的键进行迁移（如 memorySearch → memory.search，connectTimeout → connectionTimeoutMs 等）。
- 删除废弃配置项（如 resetOnExit、调优旋钮），使配置符合新版结构。
插件管理与修复 ：
- 自动安装缺失的 codex 插件，并更新其他四个插件到最新版。
- 提醒用户接受新插件的能力许可（已交互式完成）。
- 创建 heartbeat 监控，确保 agent 稳定运行。

最终网关服务正常启动，可以通过本地 Dashboard 进行管理。