OpenClaw 升级后避坑指南（实干版）

问题 1：配置文件变复杂，新版安全机制太麻烦

解决：继续用旧写法 -- provider + apiKey 写在一起，不用 .env
解释：新版强制分离密钥是为了安全，但旧写法 100% 能用，省事。

问题 2：自定义模型平台（聚合/自建）不回复

解决：baseUrl 末尾必须加 /v1
解释：新版要求显式指定 API 版本后缀，不加就找不到端点。

问题 3：直接升级后各种报错、缺包、崩溃

解决：彻底卸载 → 清理 → 重装
解释：旧版残留文件和全局模块冲突，只有完全删干净才稳定。

一、彻底重装（唯一不报错的方法）

bash

复制代码

# 1. 卸载全局
npm uninstall -g openclaw

# 2. 删除用户配置（重要）
rmdir /s /q %USERPROFILE%\.openclaw

# 3. 删除全局损坏文件
rmdir /s /q %APPDATA%\npm\node_modules\openclaw

# 4. 全新安装
npm install -g openclaw

# 5. 初始化
openclaw daemon start

向导中：删除旧网关 → 新建一个 → 一路默认。

二、缺包报错怎么办？

bash

复制代码

cd %APPDATA%\npm\node_modules\openclaw
npm install @buape/carbon@latest

解释：新版经常缺特定库，进安装目录手动装 latest 即可，缺什么装什么。

三、配置文件万能模板（直接复制）

json

复制代码

{
  "auth": {
    "profiles": {
      "bailian:default": {
        "provider": "bailian",
        "mode": "token"
      }
    }
  },
  "plugins": {
    "entries": {
      "openai": { "enabled": true },
      "anthropic": { "enabled": true }
    }
  },
  "providers": {
    "bailian": {
      "baseUrl": "https://你的平台.com/v1",
      "apiKey": "你的KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "glm-4.7",
          "name": "glm-4.7",
          "api": "openai-completions"
        }
      ]
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/glm-4.7"
      },
      "models": {
        "bailian/glm-4.7": {}
      }
    }
  }
}

规则：

baseUrl 末尾必须 /v1
api 固定写 openai-completions
自定义平台不需要新版安全机制

四、加新模型平台（例：火山引擎）

在 providers 里加一段：

json

复制代码

"huoshan": {
  "baseUrl": "https://火山平台.com/v1",
  "apiKey": "火山的KEY",
  "api": "openai-completions",
  "models": [
    { "id": "doubao", "name": "doubao", "api": "openai-completions" }
  ]
}

在 agents.defaults.models 里加：

json

复制代码

"huoshan/doubao": {}

五、最终 5 句口诀（背下来）

升级必卸载干净，不然报错。
自定义平台网址末尾 + /v1。
api 永远写 openai-completions。
缺包就进目录 npm install xxx@latest。
配置坚持旧写法（provider+key写一起）。