适用版本： OpenClaw v2026.3

Node.js 版本要求

检查版本：

node --version
# 输出: v22.12.0 或更高

# 使用 nvm 管理版本
nvm install 22
nvm use 22

API 版本历史

v2026.3 (当前版本)

新增 API：

• agent.start - 支持并行工具调用
• config.patch - 支持热更新
• node.invoke - 节点调用

变更：

• message.send 参数 attachments 支持更多格式
• sessions.patch 支持修改更多属性

废弃：

• gateway.stats → 使用 metrics 端点

v2026.2

新增 API：

• cron.list / cron.add / cron.delete
• plugins.list

变更：

• auth.method 配置结构变更

v2025.x

初始 API：

• sessions.list / sessions.get / sessions.delete
• message.send
• config.get

配置迁移

从 2026.2 升级到 2026.3

# 旧配置 (2026.2)
gateway:
  auth:
    method: token
    token: "secret"

# 新配置 (2026.3)
auth:
  method: token
  tokens:
    - name: "default"
      value: "secret"
      permissions: ["read", "write"]

迁移命令：

# 自动迁移配置
openclaw migrate --from 2026.2 --to 2026.3

# 验证迁移结果
openclaw config validate

从 2025.x 升级到 2026.x

# 旧配置 (2025.x)
providers:
  openai:
    key: "sk-..."

# 新配置 (2026.x)
providers:
  openai:
    apiKey: "${OPENAI_API_KEY}"

数据兼容性

Session 数据

数据迁移：

# 从 JSON 迁移到 SQLite
openclaw migrate-data --from json --to sqlite

# 验证数据完整性
openclaw doctor --check-sessions

Transcript 格式

// 2026.3 格式
interface Transcript {
  messages: Message[];
  tokens: number;
  metadata: {
    model: string;
    provider: string;
  };
}

// 2025.x 格式
interface TranscriptLegacy {
  messages: Message[];
}

插件兼容性

插件 API 版本

// openclaw.plugin.yaml
id: my-plugin
apiVersion: "2026.3"  # 必须匹配 OpenClaw 版本

插件迁移

// 2025.x 插件
export default {
  onMessage: (msg) => { ... }
};

// 2026.x 插件
export default {
  channels: [MyChannel],
  methods: {
    "my.custom": handleCustomMethod,
  },
  hooks: {
    "message:received": myHook,
  },
};

升级指南

升级前检查

# 1. 备份数据
openclaw backup create

# 2. 检查兼容性
openclaw upgrade --check

# 输出示例
# ✅ Node.js version: 22.12.0
# ✅ Config format: compatible
# ⚠️  Legacy config entries: 2 (will be migrated)
# ✅ Session data: 42 sessions (compatible)
# ✅ Plugins: 3 installed (2 need update)

升级步骤

# 1. 停止服务
openclaw gateway stop

# 2. 升级包
npm update -g openclaw

# 3. 迁移配置
openclaw migrate --to 2026.3

# 4. 验证
openclaw config validate
openclaw doctor

# 5. 启动服务
openclaw gateway start

回滚

# 如果升级失败，回滚到旧版本
npm install -g [email protected]

# 恢复备份
openclaw backup restore --latest

依赖版本

系列索引： OpenClaw 源码解析：目录索引