OpenClaw 小龙虾从 4.2 升到 4.5,这几步别漏了

OpenClaw 小龙虾从 4.2 升到 4.5，这几步别漏了

升级一时爽，配置火葬场？照着这份指南走，稳稳当当升级到 4.5。

---

先说个真实场景

昨天有个朋友在群里问：「升级完 OpenClaw 4.5，网关死活启动不了，一堆警告怎么办？」

我一看配置，典型的旧版本遗留问题。

4.5 版本确实改动不小，尤其是配置路径的清理和重构。很多人升级后遇到各种奇怪的问题，归根结底就一个原因：没处理好配置迁移。

今天这份指南，就是帮你避开这些坑。从 4.2 或更早版本升级到 4.5，照着做，基本不会翻车。

---

第一步：升级前的准备工作

别急着执行升级命令，先做好这三件事：

1. 备份当前配置

cp ~/.openclaw/config.json ~/.openclaw/config.json.bak

这一步千万别省。万一升级出问题，还能快速回滚。

2. 检查当前版本

openclaw --version

确认你确实需要升级。如果已经是 4.4+，可能不需要大动干戈。

3. 记录关键配置项

打开你的 `config.json`，重点关注下面这些配置（升级后需要迁移）：

配置项	用途
`talk.voiceId` / `talk.apiKey`	语音 TTS 配置
`agents.*.sandbox.perSession`	Agent 沙箱模式
`browser.ssrfPolicy.allowPrivateNetwork`	浏览器 SSRF 策略
`hooks.internal.handlers`	内部钩子处理器
`telegram.enabled` / `discord.enabled`	渠道开关

建议截图或复制一份到备忘录，后面要用。

---

第二步：执行升级

升级命令很简单：

npm install -g openclaw@latest

如果你用的是 yarn 或 pnpm，换成对应的命令就行：

yarn global add openclaw@latest
或
pnpm add -g openclaw@latest

升级完成后，先别急着启动。这是最容易出错的地方。

---

第三步：配置迁移（关键！）

4.5 版本会自动检测并警告废弃的配置路径，但不会自动迁移。你需要手动处理。

方法一：自动修复（推荐）

openclaw doctor --fix

这个命令会帮你：

1. 扫描所有废弃的配置别名

2. 自动迁移到新路径

3. 保留原有的值

4. 输出迁移报告

大部分情况下，这一条命令就够了。

方法二：手动修改（如果自动修复不彻底）

如果 `doctor --fix` 报错或迁移不完整，需要手动编辑 `config.json`。

以下是几个最常见的配置变化：

#### 1. 语音配置

// 旧版本
{
  "talk": {
    "voiceId": "elevenlabs/nova",
    "apiKey": "xxx"
  }
}// 4.5 新版本
{
  "providers": {
    "elevenlabs": {
      "voices": {
        "default": "nova"
      }
    }
  }
}

#### 2. Agent 沙箱配置

// 旧版本
{
  "agents": {
    "myAgent": {
      "sandbox": {
        "perSession": true
      }
    }
  }
}// 4.5 新版本
{
  "agents": {
    "myAgent": {
      "sandbox": {
        "sessionMode": "perSession"
      }
    }
  }
}

#### 3. 浏览器 SSRF 策略

// 旧版本
{
  "browser": {
    "ssrfPolicy": {
      "allowPrivateNetwork": true
    }
  }
}// 4.5 新版本
{
  "browser": {
    "ssrf": {
      "allowPrivateNetwork": true
    }
  }
}

#### 4. 渠道开关配置

// 旧版本
{
  "telegram": {
    "enabled": true
  }
}// 4.5 新版本
{
  "channels": {
    "telegram": {
      "enabled": true
    }
  }
}

---

第四步：重启并验证

配置迁移完成后，重启服务：

openclaw gateway restart

观察启动日志，应该没有关于废弃配置的警告了。如果有，说明还有配置没迁移到位。

验证清单

启动成功后，建议验证以下几个关键功能：

• ✅ 语音功能：测试 TTS 是否正常

• ✅ Agent 沙箱：启动一个 Agent 看看

• ✅ 渠道连接：检查 Telegram/Discord 等渠道是否在线

---

常见问题解决

问题 1：`hooks.internal.handlers` 配置失效

原因：这个配置在 4.5 被完全移除，改为插件机制。

解决方案：如果你之前依赖它，需要改用 hooks 插件实现相同功能。参考官方文档的 hooks 插件部分。

问题 2：`openclaw doctor --fix` 报错

原因：配置文件格式问题或权限问题。

解决方案：

1. 检查 `config.json` 是否是有效的 JSON 格式

2. 确保有文件写入权限

3. 如果还是不行，手动修改配置（参考上面的对照表）

问题 3：启动后部分功能异常

原因：某个配置没迁移到位。

解决方案：

1. 检查日志中的错误信息：`journalctl -u openclaw -f`

2. 对比备份配置和新配置的差异

3. 必要时回退到备份配置，重新迁移

---

升级后值得体验的新功能

折腾完升级，别忘了体验 4.5 带来的新功能：

1. 记忆做梦系统

/dreaming

AI 助手会定期整理记忆，生成「梦境」摘要。看看你的 Agent 最近都在想什么。

2. 音乐视频生成

直接让 AI 生成背景音乐或短视频，无需额外配置。

3. ComfyUI 集成

用自然语言驱动本地 Stable Diffusion 工作流，AI 生图更灵活。

4. 国产模型支持

Qwen、MiniMax、StepFun 等国产模型直接可用，无需复杂配置。

---

最后说两句

升级过程虽然有点繁琐，但 4.5 带来的新功能和新架构确实值得花这点时间。

如果你在升级过程中遇到其他问题，可以到 OpenClaw 社区提问。很多人已经趟过这些坑了，你的问题可能已经有答案。

记住一句话：升级前备份，升级后验证。这两步做好了，基本不会出大问题。

---