新版openclawai与旧版不兼容，需升级配置为json5、重映射字段路径、迁移api密钥至auth-profiles.json、启用兼容模式或回退至lts分支。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试运行OpenClawAI，但发现其无法识别旧版配置文件、报错字段缺失或服务启动失败，则很可能是新版OpenClawAI与旧版软件在配置格式、目录结构或认证机制上存在不兼容。以下是适配不同版本差异的具体方法：
一、升级配置文件至JSON5格式并修复语法
新版OpenClaw明确支持JSON5格式，允许注释、尾逗号及更宽松的字符串书写方式，而旧版仅接受标准JSON，直接复用将触发解析失败。
1、打开旧版配置文件（如config.json），检查是否存在单行注释//或块注释/* */；若存在，需保留并确认所用编辑器支持JSON5读取。
2、检查所有对象末尾是否含多余逗号（如"sandbox": { ... },），若有，无需删除——新版允许该写法，但旧版会报错；若需双向兼容，可手动移除尾逗号。
3、将文件扩展名由.json改为.json5，并在OpenClaw启动时通过--config config.json5显式指定路径，避免自动加载失败。
二、重映射配置字段路径与目录结构
新版采用多智能体架构，原单智能体字段已迁移至嵌套路径，且本地存储位置发生层级调整，直接沿用旧路径会导致默认值未生效或会话丢失。
1、将原配置中"agent": { "workspace": "...", "sandbox": { ... } }整体替换为"agents": { "defaults": { "workspace": "...", "sandbox": { ... } } }结构。
2、将旧版智能体定义目录~/.openclaw/agent/main/整体迁移至~/.openclaw/agents/main/，确保子目录sessions/同步移入新路径。
3、若使用多个智能体，需在agents.list数组中显式声明每个ID，并设置"default": true标识主智能体，否则系统将忽略defaults以外的配置。
三、迁移API密钥至独立认证配置文件
旧版将API密钥直写于主配置中，存在安全风险且不支持多环境切换；新版强制通过auth-profiles.json统一管理，主配置中仅引用profile名称。
1、在~/.openclaw/下新建文件auth-profiles.json，内容格式为：{ "default": { "provider": "dashscope", "api_key": "sk-xxxxxx" } }。
2、在主配置文件中删除所有api_key、secret等明文字段，改写为"auth_profile": "default"。
3、执行openclaw validate --auth验证认证文件可读性，输出[auth] profile 'default' loaded successfully即表示迁移完成。
四、启用向后兼容运行时模式
针对仍需临时运行旧版插件或技能的场景，新版OpenClaw提供兼容开关，可禁用部分严格校验逻辑，避免因字段缺失导致进程退出。
1、在OpenClaw工作区根目录创建.openclaw/compat.yaml。
2、写入以下内容：compatibility: { strict_schema: false, legacy_agent_fallback: true, allow_missing_fields: ["model.primary"] }。
3、启动时附加参数--compat-config .openclaw/compat.yaml，使运行时跳过对model.primary等新版必填字段的校验。
五、回退至兼容性分支进行渐进式迁移
若上述方法仍无法满足关键业务连续性要求，可临时切换至官方维护的LTS兼容分支，在保留旧版行为的同时获取安全更新。
1、执行git -C $(which openclaw | xargs dirname)/../.. checkout v1.1.x-lts（Linux/macOS）或下载对应Windows ZIP包。
2、运行openclaw migrate --from-legacy-config ~/.openclaw/config.json，该命令将自动生成新版结构的config.yaml及auth-profiles.json。
3、验证迁移结果：openclaw run --dry-run，观察日志中是否出现[migrate] legacy agent config auto-upgraded提示。
