如何实现模型热切换？修改 /app/openclaw.json 实操解析

在本地运行 OpenClaw 时，最让人上瘾的功能之一就是模型热切换——无需重启服务、无需重新加载容器，只需几秒钟就能从 Qwen3-4B 换到 Claude-Opus-4.5，或从本地 vLLM 模型切到 OpenRouter 远程模型。这种“即改即用”的体验，正是 OpenClaw 能迅速火起来的核心原因之一。

本文聚焦最实操的部分：通过直接修改容器内的核心配置文件 /app/openclaw.json，实现真正意义上的模型热切换。我们将从原理到步骤、从常见坑到进阶玩法，一步步带你吃透这个配置文件的每一行。

文章导航

一、什么是模型热切换？为什么值得掌握手动修改配置文件

OpenClaw 的模型切换有三种方式：

聊天框输入 /model ：最快，但受白名单限制
Web 界面点击切换：方便，但部分模型需先配置
直接修改 /app/openclaw.json + 重载；最灵活，能突破所有限制

前两种方式本质上都是对同一份配置文件的操作进行封装。当你遇到“model not allowed”或想批量添加多个自定义模型时，手动修改 /app/openclaw.json 是唯一彻底的解决方案。

掌握它有三个最大好处：

完全掌控：不受 onboard 向导和白名单机制限制，想加什么模型加什么模型
批量操作：一次配置多个 provider，适合多模型并行测试
生产级稳定：云服务器、虚拟机、旧电脑三种场景通用，配置一次到处迁移

二、准备工作：进入容器并定位配置文件

大多数用户通过 Docker 部署 OpenClaw，配置文件实际路径是容器内的 /app/.openclaw/openclaw.json，宿主机映射目录通常是 ~/.openclaw/openclaw.json。

进入容器的方法：

# 找到容器名（通常是 openclaw）
docker ps

# 进入容器
docker exec -it openclaw /bin/bash

# 查看配置文件（容器内路径）
cat /app/.openclaw/openclaw.json

如果你在宿主机操作（推荐），直接编辑映射文件即可：

nano ~/.openclaw/openclaw.json

修改后无需重启容器，只需执行热重载命令：

# 在容器内执行
openclaw models reload

# 或在宿主机执行（如果 openclaw CLI 已全局安装）
openclaw models reload

三、核心原理：openclaw.json 的结构解析

一个典型的 openclaw.json 包含以下关键字段：

{
  "models": {
    "mode": "merge",
    "providers": { ... },
    "agents": {
      "defaults": {
        "model": { "primary": "xxx" },
        "models": [ ... ]   // 白名单数组
      }
    }
  }
}

关键字段解释：

字段路径	作用	修改影响
models.mode	merge（推荐）或 override	merge 会合并 onboard 配置，安全
models.providers	所有模型源（vllm、openrouter、custom 等）	添加新模型必改此处
agents.defaults.model.primary	当前默认模型	切换默认启动模型
agents.defaults.models	白名单数组，决定 /model 命令能切哪些模型	若存在则限制切换，建议删除或扩充

白名单机制是最大坑点：如果 agents.defaults.models 数组存在，你只能在数组内切换模型；若数组为空或删除，则可自由切换所有已注册的模型。

四、实操案例一：快速切换到 Claude-Opus-4.5（OpenRouter）

假设你已通过 onboard 配置了 OpenRouter，当前默认是 minimax-m2.1，想热切换到最强 Opus。

步骤：

编辑配置文件，确认 providers 中有 openrouter
删除或清空 agents.defaults.models 数组（突破白名单）
设置 primary 为 opus

修改后示例片段：

{
  "models": {
    "mode": "merge",
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "sk-or-xxx",
        "api": "openai-completions",
        "models": []
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-opus-4.5"
      }
      // "models": []  // 直接删除这整行或留空数组
    }
  }
}

保存 → openclaw models reload → 新建对话 → 直接使用 Opus。

五、实操案例二：添加自定义模型（以 Kimi K2.5 为例）

Kimi 最新 K2.5 在 OpenRouter 列表中可能尚未上线，我们通过 custom provider 添加。

完整添加配置：

{
  "models": {
    "mode": "merge",
    "providers": {
      "custom": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "${your_openrouter_api_key}",
        "api": "openai-completions",
        "models": [
          {
            "id": "moonshot/kimi-k2.5",
            "name": "Kimi K2.5 (Custom)"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "custom/moonshot/kimi-k2.5"
      },
      "models": [
        "openrouter/minimax/minimax-m2.1",
        "custom/moonshot/kimi-k2.5",
        "openrouter/anthropic/claude-opus-4.5"
      ]
    }
  }
}

注意点：
– provider 名称为 custom
– id 必须与 OpenRouter 实际模型 ID 一致
– 使用 custom/ 前缀调用
– 同时将新模型加入白名单数组，避免“model not allowed”

热重载后，在聊天框输入：

/model custom/moonshot/kimi-k2.5

即可立即切换。

六、实操案例三：本地 vLLM 模型热替换（无需重启容器）

假设你已下载 Qwen2.5-14B 到 ~/openclaw/models/Qwen2.5-14B-Instruct。

添加本地模型配置：

{
  "models": {
    "providers": {
      "vllm": {
        "baseUrl": "http://localhost:8000/v1",
        "apiKey": "sk-local",
        "api": "openai-responses",
        "models": [
          {
            "id": "Qwen2.5-14B-Instruct",
            "name": "Qwen2.5-14B 本地",
            "path": "/app/models/Qwen2.5-14B-Instruct"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "vllm/Qwen2.5-14B-Instruct"
      },
      "models": [
        "vllm/Qwen3-4B-Instruct-2507",
        "vllm/Qwen2.5-14B-Instruct"
      ]
    }
  }
}

保存 → openclaw models reload → Web 界面模型列表立即出现新模型。

七、常见问题与避坑指南

1、修改后不生效？

确认执行了 clawdbot models reload
检查 JSON 语法：推荐用 vscode 格式化
删除 agents.defaults.models 整行：最常见原因

2、“model not allowed” 错误

白名单数组未包含目标模型，或数组存在但目标模型未加入

3、想恢复 onboard 默认配置

删除 ~/.clawdbot/clawdbot.json
重新执行 clawdbot onboard

4、多模型并行测试技巧

在 agents.defaults.models 中列出所有常用模型
使用 /model + 模型 ID 快速切换
每个对话可独立绑定不同模型（Web 界面右上角齿轮 → Model）

八、进阶玩法：批量管理与自动化

熟练后，你可以：
– 编写脚本一键替换 primary 模型
– 使用不同 profile 文件（如 openclaw-coding.json、openclaw-writing.json）快速切换配置场景
– 结合 openclaw dashboard 命令，在远程服务器上通过 SSH 隧道安全访问 Web 界面

九、不同模型实测对比（2026 年 2 月数据）

模型	提供商	速度（token/s）	智能度	费用（每百万 token）	推荐场景
minimax-m2.1	OpenRouter	85	★★★★☆	~$0.5	日常对话、代码辅助
claude-opus-4.5	OpenRouter	62	★★★★★	~$15	复杂推理、长文写作
moonshot/kimi-k2.5	Custom	92	★★★★☆	~$1.2	中文理解、快速响应
Qwen2.5-14B-Instruct	本地 vLLM	48	★★★★☆	0	隐私敏感、离线使用
Qwen3-32B	本地 vLLM	35	★★★★★	0	高质量长上下文任务