OpenClaw 大模型配置文件优先级及路径详解

概述

OpenClaw 使用两层配置结构来管理大模型：全局默认配置和 Agent 特定配置。理解这两层配置的优先级和关系对于正确配置和故障排查至关重要。

配置文件结构

1. 全局配置文件

路径：`/root/.openclaw/openclaw.json`

作用：定义所有 Agent 的默认模型行为，包括主模型、备用模型链和模型详情映射。

2. Agent 配置文件

路径：`/root/.openclaw/agents/main/agent/models.json`

作用：提供详细的模型提供者配置，包括 API 端点、密钥、模型规格等。

配置优先级详解

优先级顺序

全局默认配置（`openclaw.json`）
- 定义主模型：`agents.defaults.model.primary`
- 定义备用模型链：`agents.defaults.model.fallbacks`
- 定义模型映射：`agents.defaults.models`
Agent 特定配置（`models.json`）
- 提供模型提供者详细信息
- 包含 API 端点、密钥、模型规格
- 可能覆盖全局配置中的部分设置

配置合并机制

OpenClaw 使用 merge 模式 来合并配置：

"models": {
  "mode": "merge",
  "providers": { ... }
}

这意味着全局配置和 Agent 配置会合并，Agent 配置可以覆盖全局配置中的特定部分。

具体配置项说明

全局配置关键项

1. 主模型配置

"model": {
  "primary": "custom-open-bigmodel-cn/glm-4.7-flash",
  "fallbacks": [
    "custom-integrate-api-nvidia-com/deepseek-ai/deepseek-v3.2",
    "custom-api-inference-modelscope-cn/MiniMax/MiniMax-M2.5"
  ]
}

primary：首选模型，当此模型可用时使用
fallbacks：备用模型列表，按顺序尝试

2. 模型映射

"models": {
  "custom-open-bigmodel-cn/glm-4.7-flash": {},
  "custom-integrate-api-nvidia-com/deepseek-ai/deepseek-v3.2": {},
  "custom-api-inference-modelscope-cn/MiniMax/MiniMax-M2.5": {}
}

这个映射用于存储模型配置的引用，实际配置在 `models.json` 中。

Agent 配置关键项

1. 模型提供者配置

"providers": {
  "custom-open-bigmodel-cn": {
    "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
    "apiKey": "your-api-key-here",
    "api": "openai-completions",
    "models": [
      {
        "id": "glm-4.7-flash",
        "name": "glm-4.7-flash (Custom Provider)",
        "contextWindow": 65535,
        "maxTokens": 4096,
        "reasoning": false
      }
    ]
  },
  "custom-integrate-api-nvidia-com": {
    "baseUrl": "https://integrate.api.nvidia.com/v1",
    "apiKey": "nvapi-your-api-key-here",
    "api": "openai-completions",
    "models": [
      {
        "id": "deepseek-ai/deepseek-v3.2",
        "name": "deepseek-ai/deepseek-v3.2 (Custom Provider)",
        "contextWindow": 65535,
        "maxTokens": 4096,
        "reasoning": false
      }
    ]
  },
  "custom-api-inference-modelscope-cn": {
    "baseUrl": "https://api-inference.modelscope.cn/v1",
    "apiKey": "ms-your-api-key-here",
    "api": "openai-completions",
    "models": [
      {
        "id": "MiniMax/MiniMax-M2.5",
        "name": "MiniMax/MiniMax-M2.5 (Custom Provider)",
        "contextWindow": 65535,
        "maxTokens": 4096,
        "reasoning": false
      }
    ]
  }
}