# 附录F：版本映射与升级指南

本附录不再把某一代旧字段硬写成“当前配置”，而是给出一套更安全的升级方法：先识别当前 schema 家族，再用 `doctor`、`config validate` 和 `config get/set/unset` 做增量迁移。

> \[!WARNING] OpenClaw 使用日历版本号（CalVer），字段层级与命名可能随版本演进而变化。本附录仅提供迁移思路与当前 live 审计实例（2026.5.3）的可观察结构，不能替代官方文档与本地 `config schema`。

## F.1 版本号方案

OpenClaw 采用**日历版本号（CalVer）**，格式为 `YYYY.M.D`：

* `YYYY`：发布年份
* `M`：发布月份
* `D`：发布日期

示例：

```
2025.11.15  →  2026.1.9  →  2026.2.14  →  2026.3.30  →  2026.5.3
```

CalVer 的最大价值是“版本号天然携带时间语义”。做迁移判断时，先确认你当前运行的具体版本，再去看对应文档与 schema 输出。

## F.2 当前 schema 家族速览

在本次 live 审计实例中，最稳定、最值得优先识别的是下面这些 schema 家族。

| 家族      | 当前常见结构                                                            | 说明                                                            |
| ------- | ----------------------------------------------------------------- | ------------------------------------------------------------- |
| 认证      | `auth.profiles`                                                   | 认证档案与 provider 绑定，不再把所有密钥都直接写进单层字段                            |
| Agent   | `agents.defaults` + `agents.list[]`                               | “全局默认 + 按 agent 覆盖”是当前更常见的组织方式                                |
| 模型      | `agents.defaults.model`（字符串或 `{ primary, fallbacks }`）            | 当前 schema 以 `agents.defaults.model` 为主入口；对象形态可显式表达主模型与回退链     |
| 渠道      | `channels.<channel>.dmPolicy` / `groupPolicy`                     | 私聊与群聊分开治理是当前入口控制的核心                                           |
| Gateway | `gateway.port` / `gateway.auth.mode` / `controlUi.allowedOrigins` | 控制面鉴权与来源校验已经是显式结构                                             |
| Hook    | `hooks.internal.entries.*`                                        | 当前 live 实例首先暴露的是内建 hooks，而不是默认目录式 Hook                        |
| 插件      | `plugins.entries.*`                                               | 用户配置面仍以 `plugins.entries` 为核心；兼容 bundle 只是分发/发现层，不应混同为另一套配置语法 |

把这些家族先识别出来，迁移就不会被某个旧字段名牵着走。

## F.3 从旧结构到当前结构的迁移思路

下面不是“一一精确映射表”，而是当前更安全的迁移方向。

| 历史写法                  | 当前更应迁移到                                                             | 迁移原则                                 |
| --------------------- | ------------------------------------------------------------------- | ------------------------------------ |
| 单体 agent 配置           | `agents.defaults` + `agents.list[]`                                 | 先抽公共默认，再做特定 agent 覆盖                 |
| `agents.*.model` 单字符串 | `agents.defaults.model.primary` + `agents.defaults.model.fallbacks` | 把模型选择与回退链显式化；如仅需单模型，也可继续使用字符串形态      |
| 渠道单层门控开关              | `dmPolicy` / `groupPolicy` / `groups.*`                             | 先分清私聊与群聊，再处理提及门控和白名单                 |
| 顶层零散安全字段              | `gateway.auth`、`controlUi.allowedOrigins`、`tools` 策略                | 把控制面鉴权、来源校验、执行策略分层                   |
| 目录式 Hook 假设           | `hooks.internal.entries.*`                                          | 先看当前版本是否已有内建 Hook 体系，再决定是否需要自定义 Hook |
| 明文 key/file key       | `auth.profiles` + `${ENV}` / SecretRef                              | 优先迁向当前 secrets/环境变量体系                |

## F.4 常见“已过时思路”提示

升级时，最容易踩坑的不是字段拼错，而是**沿用了一整套过时的配置思路**。下面这些情况要特别警惕：

* 把 `agents.default`、`agents.*.models`、`gateway.listeners` 之类写成“当前默认写法”。
* 把 `channels.*.requireMention`、`channels.*.routing[].conditions.requireMention` 这类旧门控路径写成唯一正确答案。
* 把 `auth.type`、`auth.useKeyFile` 之类单层认证字段写成主路径，而忽略 `auth.profiles`。
* 把旧案例里的“可直接粘贴运行”配置直接当成当前版本模板。

更稳妥的做法是：**先用 schema 看家族，再用示例做映射**，而不是反过来。

## F.5 当前可用的迁移命令

当前官方 CLI 中，最实用的是下面几组命令。

### `openclaw doctor`

`doctor` 负责诊断配置和运行时健康状态，同时会处理当前官方支持的 legacy migration。

```bash
openclaw doctor
openclaw doctor --deep
openclaw doctor --repair
```

> 当前官方 CLI 文档将 `--fix` 视为 `--repair` 的别名；同时，运行时提示和不少诊断输出仍常直接打印 `openclaw doctor --fix`。两者语义等价，实际以本地 `openclaw doctor --help` 为准。

### `openclaw config`

`config` 用于读取、校验和精确修改配置项。

```bash
openclaw config file
openclaw config validate
openclaw config get gateway.auth.mode
openclaw config set gateway.auth.mode token
openclaw config unset legacy.oldField
```

### `openclaw secrets`

如果迁移涉及凭据存储，而不是普通字段层级调整，更稳妥的入口是当前官方提供的 `secrets audit / configure / apply / reload` 流程，而不是假定存在某个单独的 `migrate` 子命令：

```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets reload
```

## F.6 推荐升级流程

配置升级更适合遵循 **备份 → doctor → validate → 手动补差 → 深度诊断 → 回归测试** 的流程。

### 快速步骤

```bash
# 1. 备份当前配置目录
cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d_%H%M%S)

# 2. 先运行 doctor，处理当前官方已知迁移
openclaw doctor

# 3. 校验配置结构
openclaw config validate

# 4. 精确读取关键配置
openclaw config get gateway.auth.mode
openclaw config get agents.defaults.model.primary

# 5. 按当前 schema 手动补差
openclaw config set gateway.auth.mode token

# 6. 深度诊断
openclaw doctor --deep
```

### 回滚步骤

```bash
rm -rf ~/.openclaw
mv ~/.openclaw.backup.YYYYMMDD_HHMMSS ~/.openclaw
openclaw gateway restart
```

## F.7 升级时最值得优先复验的项

升级后不要只看“配置校验通过”，还应至少复验以下内容：

1. Control UI 是否仍能正常连接。
2. `gateway.auth.mode` 与 `controlUi.allowedOrigins` 是否符合当前部署方式。
3. 默认 agent 的 `agents.defaults.model.primary` / `agents.defaults.model.fallbacks` 是否仍指向可用模型。
4. `dmPolicy` / `groupPolicy` 是否符合当前入口治理策略。
5. Hook、插件、工具策略是否仍按预期生效。

## F.8 本章小结

版本迁移的关键不是背一张“旧字段 → 新字段”的表，而是先抓住当前 schema 家族：

* 认证看 `auth.profiles`
* Agent 看 `agents.defaults` 与 `agents.list[]`
* 模型看 `agents.defaults.model`
* 渠道看 `dmPolicy / groupPolicy`
* Gateway 看 `auth + controlUi.allowedOrigins`
* Hook 看 `hooks.internal`
* 插件看 `plugins.entries`

先跑 `doctor`，再用 `config validate` 和 `config get/set/unset` 做精确补差，是当前更可靠的升级路径。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/openclaw_guide/fu-lu/appendix/version_mapping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.