OpenClaw 模型配置指南 - OpenClaw 安装与配置指南

这篇文档解决一个核心问题：如何让 OpenClaw 稳定调用你指定的大模型，并在故障时自动回退。

你将看到：

向导里如何快速配置模型
~/.openclaw/openclaw.json 的关键结构
Raw JSON 手工配置模板
/model 指令验证与切换
fallback 回退机制最佳实践

1. 模型配置入口在哪里

OpenClaw 有两个主要配置入口：

Onboarding 向导（首次安装时）
Web 控制台 Config -> Raw JSON

如果你已经在向导里配好模型，可以继续优化。
如果向导中选择了 Skip，也可以在控制台补配。

2. 向导中快速配置模型（推荐起点）

在 openclaw onboard --install-daemon 中：

选择 QuickStart
选择模型提供商（优先 OpenAI / Anthropic）
填写 API Key
选择模型 ID（例如 gpt-5.3-codex）

如果当下不确定模型方案，可先 Skip for now，后续在 Raw JSON 中配置：

3. 核心配置文件：`~/.openclaw/openclaw.json`

OpenClaw 的模型配置最终都落在这个文件：

~/.openclaw/openclaw.json

建议直接用 VS Code 这类编辑器维护，避免在内置表单里做复杂改动。

3.1 你只需要先理解 2 个模块

models：模型提供商与模型清单
agents：默认模型、可选模型、回退模型策略

其余模块（meta、wizard、hooks、gateway 等）可先不动。

4. 最小可用配置模板（OpenAI 兼容）

下面是一个可以直接理解和扩展的最小模板：

{
  "models": {
    "mode": "merge",
    "providers": {
      "openai": {
        "baseUrl": "https://your-openai-compatible-endpoint/v1",
        "apiKey": "YOUR_API_KEY",
        "auth": "api-key",
        "api": "openai-codex-responses",
        "models": [
          {
            "id": "gpt-5.3-codex",
            "label": "GPT-5.3 Codex"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai:gpt-5.3-codex"
      }
    }
  }
}

4.1 字段解释（实用版）

models.mode = "merge"：在默认配置上叠加你的自定义配置
providers.<name>：一个模型提供商定义块，openai 只是示例名
baseUrl：API 根地址
apiKey：访问密钥
api：协议适配类型（OpenAI 兼容接口）
agents.defaults.model.primary：默认主模型

5. 在控制台应用配置

修改完成后，把 JSON 粘贴到控制台 Config -> Raw JSON，点击 Save / Update，系统会重载配置并重启相关服务。

如果短时间不可用，通常属于重载过程，等待几十秒后再测试。

6. 聊天窗口验证模型状态

6.1 查看当前模型

/model status

6.2 切换模型

/model 模型标识

例如：

/model openai:gpt-5.3-codex

7. 回退机制（强烈建议配置）

OpenClaw 在长任务场景会消耗大量 Token。若只配一个模型，一旦超限、余额不足或提供商故障，任务会直接失败。

建议在 agents.defaults.model 中增加 fallbacks：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai:gpt-5.3-codex",
        "fallbacks": [
          "openai:gpt-4.1",
          "bailian:qwen-max"
        ]
      }
    }
  }
}

推荐策略：

主模型：高质量模型（复杂任务）
备模型 1：同厂商中档模型（成本更低）
备模型 2：异厂商模型（降低单点故障）

8. 常见配置错误

8.1 `baseUrl` 写错

症状：认证看似成功但请求 404/401。
处理：检查是否为正确的 OpenAI 兼容根路径（通常到 /v1）。

8.2 `primary` 与 `models` 不一致

症状：/model status 看不到默认模型。
处理：统一模型标识，避免手误或大小写不一致。

8.3 只配置主模型未配置回退

症状：流量高峰时频繁任务失败。
处理：至少配置 1 个 fallback。

9. 推荐落地方案（可直接照做）

先在向导完成基础模型接入（保证能对话）
再到 Raw JSON 规范化 models + agents 配置
加上 fallbacks 提升稳定性
每次改完都执行 /model status 验证

按这条路线，你可以把 OpenClaw 从“能跑”升级到“稳定可用”。

下一步建议阅读：OpenClaw Channels 接入。