OpenClaw 模型配置完全教程：从零开始到高级玩法（2026）

很多人跑通 openclaw onboard 就以为配置完成了，结果遇到模型切换、fallback、多 Agent 配置时一脸懵。这篇教程从目录结构讲起，逐个拆解模型配置参数，涵盖多模型轮询、自动降级、预算控制等配置。所有示例可直接复制使用。

从 onboard 开始：初始化配置

装好 OpenClaw 之后，第一件事就是运行 onboard 命令：

openclaw onboard

引导过程会依次问你四个问题：

第一步：选择 AI 提供商

? Select your AI provider:
  > OpenAI (官方)
    Anthropic (官方)
    Google (官方)
    Custom (第三方/聚合平台)   ← 如果用 Ofox 等平台选这个

选 Custom 后会要求你输入 base_url。如果你用 Ofox 聚合平台，填：

https://api.ofox.ai/v1

第二步：输入 API Key

? Enter your API Key:
sk-xxxxxxxxxxxxxxxx

用聚合平台的话，一个 Key 就够了。不需要分别去 OpenAI、Anthropic、Google 注册。

第三步：选择默认模型

? Select default model:
  > claude-sonnet-4
    gpt-4o
    gemini-3-pro
    deepseek-v3.2
    (type to search...)

日常使用推荐 claude-sonnet-4 或 gpt-4o，性价比最高。不确定选哪个可以参考《OpenClaw 模型推荐 2026：排行榜与场景选型》。

第四步：配置 Search Provider

? Select search provider:
  > Tavily (推荐，注册送免费额度)
    Google Search
    Bing Search
    Skip

不需要联网搜索就选 Skip，后面随时能改。

onboard 跑完后，OpenClaw 会在 ~/.openclaw/ 目录下生成配置文件。大多数人到这一步就开始用了——但这只是起点。

~/.openclaw/ 目录结构详解

onboard 完成后，你的 ~/.openclaw/ 目录大概长这样：

~/.openclaw/
├── config.yaml          # 全局配置（核心）
├── models.yaml          # 模型定义（所有可用模型）
├── agents/              # Agent 角色配置
│   └── default.yaml     # 默认 Agent
├── memory/              # 记忆存储
│   ├── core.md          # 核心记忆
│   └── conversations/   # 对话历史
├── plugins/             # 插件配置
├── .env                 # 环境变量（可选）
└── logs/                # 运行日志

最重要的是三个文件：config.yaml（全局行为）、models.yaml（模型定义）、agents/default.yaml（Agent 角色）。逐个来看。

config.yaml：全局配置

这是 OpenClaw 的主配置文件，控制整体行为：

# ~/.openclaw/config.yaml

# 默认使用的模型
default_model: claude-sonnet-4

# 模型路由策略
model_routing:
  primary: claude-sonnet-4        # 主力模型
  fallback: gpt-4o                   # 主模型挂了用这个
  economy: deepseek-v3.2             # 简单任务省钱用

# 搜索配置
search:
  provider: tavily
  api_key: tvly-xxxxxxxx

# 预算控制
budget:
  daily_limit: 500000       # 每日 token 上限
  monthly_limit: 10000000   # 每月 token 上限
  warning_threshold: 0.8    # 80% 时提醒

# 日志
logging:
  level: info               # debug / info / warn / error
  file: ~/.openclaw/logs/openclaw.log

# 安全
security:
  allowed_commands:          # 允许执行的系统命令白名单
    - git
    - npm
    - python3
    - curl
  blocked_paths:             # 禁止访问的路径
    - /etc/
    - /var/

models.yaml：模型定义

这个文件定义了所有你可以使用的模型。每个模型是一个独立条目：

# ~/.openclaw/models.yaml

models:
  - name: claude-sonnet-4
    provider: anthropic
    model: anthropic/claude-sonnet-4     # 通过 Ofox（OpenAI 兼容接口）需加 provider 前缀
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}         # 引用环境变量
    max_tokens: 8192
    temperature: 0.7
    timeout: 60

  - name: claude-opus-4
    provider: anthropic
    model: anthropic/claude-opus-4
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 16384
    temperature: 0.3
    timeout: 120

  - name: gpt-4o
    provider: openai
    model: openai/gpt-4o
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 4096
    temperature: 0.7
    timeout: 45

  - name: deepseek-v3.2
    provider: deepseek
    model: deepseek/deepseek-chat
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 30

注意两点：1）api_key 用 ${OPENCLAW_API_KEY} 引用环境变量，避免硬编码密钥；2）通过 Ofox 等 OpenAI 兼容接口调用非 OpenAI 模型时，model 字段需要加 provider/ 前缀。

模型配置参数逐项拆解

models.yaml 中每个模型条目支持以下参数：

几个关键参数的选择建议

temperature

这个参数对输出质量影响很大，不同场景差别明显：

max_tokens

别设太小，不然模型回复到一半就被截断。不同模型的推荐值：

timeout

根据模型响应速度设：

• 轻量模型（GPT-4o-mini、Gemini Flash）：30 秒
• 主力模型（Sonnet、GPT-4o）：60 秒
• 旗舰模型（Opus、GPT-5.4 Thinking）：120 秒
• 长文本生成场景：300 秒

完整配置示例：从单模型到多模型

最简配置：只用一个模型

刚上手的话，最简单的配置是这样：

# ~/.openclaw/config.yaml
default_model: claude-sonnet-4

# ~/.openclaw/models.yaml
models:
  - name: claude-sonnet-4
    provider: anthropic
    model: anthropic/claude-sonnet-4
    base_url: https://api.ofox.ai/v1
    api_key: sk-your-ofox-key-here
    temperature: 0.7

两个文件加起来不到 10 行就能跑起来。

进阶配置：主力 + 备用

实际使用中建议至少配两个模型——主力模型偶尔会抽风（限流、超时），有个备用不至于卡住：

# ~/.openclaw/config.yaml
default_model: claude-sonnet-4
model_routing:
  primary: claude-sonnet-4
  fallback: gpt-4o

# ~/.openclaw/models.yaml
models:
  - name: claude-sonnet-4
    provider: anthropic
    model: anthropic/claude-sonnet-4
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 60
    max_retries: 2

  - name: gpt-4o
    provider: openai
    model: openai/gpt-4o
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 4096
    temperature: 0.7
    timeout: 45
    max_retries: 2

完整配置：三级模型 + 预算控制

# ~/.openclaw/config.yaml
default_model: claude-sonnet-4

model_routing:
  primary: claude-sonnet-4
  strong: claude-opus-4           # 复杂任务自动升级
  economy: deepseek-v3.2            # 简单任务自动降级
  fallback:
    - gpt-4o                        # 第一备选
    - gemini-3-flash                # 第二备选

auto_routing:
  enabled: true
  complexity_threshold:
    strong: 0.8                     # 复杂度 > 0.8 用 strong 模型
    economy: 0.3                    # 复杂度 < 0.3 用 economy 模型

budget:
  daily_limit: 500000
  monthly_limit: 10000000
  warning_threshold: 0.8
  on_exceed: downgrade              # 超额后降级到经济模型

search:
  provider: tavily
  api_key: ${TAVILY_API_KEY}

logging:
  level: info
  file: ~/.openclaw/logs/openclaw.log

# ~/.openclaw/models.yaml
models:
  - name: claude-sonnet-4
    provider: anthropic
    model: anthropic/claude-sonnet-4
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 60
    max_retries: 2
    streaming: true

  - name: claude-opus-4
    provider: anthropic
    model: anthropic/claude-opus-4
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 16384
    temperature: 0.3
    timeout: 120
    max_retries: 1
    streaming: true

  - name: gpt-4o
    provider: openai
    model: openai/gpt-4o
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 4096
    temperature: 0.7
    timeout: 45
    max_retries: 2
    streaming: true

  - name: deepseek-v3.2
    provider: deepseek
    model: deepseek/deepseek-chat
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 30
    max_retries: 3
    streaming: true

  - name: gemini-3-flash
    provider: google
    model: google/gemini-3.0-flash
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 4096
    temperature: 0.7
    timeout: 20
    max_retries: 2
    streaming: true

大部分请求走 Sonnet（性价比最高），复杂推理自动升级到 Opus，简单任务降级到 DeepSeek，任何模型出问题自动切到 GPT-4o 或 Gemini Flash 兜底。通过 Ofox 聚合平台，五个模型共用一个 API Key。

如果中文任务多或者想进一步压缩成本，可以考虑把 economy 换成 Kimi K2.5（输入 $0.60/百万 token，比 DeepSeek 还便宜），具体配置参考《Kimi K2.5 OpenClaw 配置教程》。

高级配置：多模型轮询与 Fallback

Fallback 链的工作原理

当主模型请求失败时，OpenClaw 按以下顺序处理：

1. 检查错误类型（超时？限流？模型不可用？）
2. 如果设置了 max_retries，先重试当前模型
3. 所有重试失败后，按 fallback 列表顺序尝试下一个模型
4. 所有 fallback 都失败，返回错误并提示用户手动 /model 切换

# 详细的 fallback 配置
model_routing:
  primary: claude-sonnet-4
  fallback:
    - model: gpt-4o
      on_errors: [timeout, rate_limit, server_error]
    - model: deepseek-v3.2
      on_errors: [timeout, rate_limit, server_error, model_unavailable]
    - model: gemini-3-flash
      on_errors: [all]       # 最后兜底，任何错误都接

限流处理

遇到 429 (Rate Limit) 时的处理策略：

rate_limit:
  strategy: exponential_backoff    # 指数退避
  initial_delay: 2                 # 首次等待 2 秒
  max_delay: 30                    # 最多等 30 秒
  auto_fallback: true              # 退避超限后自动切模型

多 Agent 独立模型配置

不同 Agent 可以用不同的模型。在 ~/.openclaw/agents/ 下创建各自的配置文件：

# ~/.openclaw/agents/coder.yaml
name: Coder
description: 专职代码助手
model: claude-opus-4              # 代码任务用最强模型
temperature: 0.2                     # 代码生成低随机性
max_tokens: 16384
system_prompt: |
  你是一个高级软件工程师，擅长代码审查、Bug 修复和架构设计。
  输出代码时注重可读性和最佳实践。

# ~/.openclaw/agents/assistant.yaml
name: Assistant
description: 日常办公助手
model: deepseek-v3.2               # 日常任务用经济模型
temperature: 0.7
max_tokens: 4096
system_prompt: |
  你是一个高效的办公助手，擅长日程管理、邮件处理和信息检索。
  回答简洁准确，必要时主动提供后续建议。

# ~/.openclaw/agents/researcher.yaml
name: Researcher
description: 深度研究分析
model: claude-sonnet-4            # 研究分析用主力模型
temperature: 0.5
max_tokens: 8192
system_prompt: |
  你是一个专业的研究分析师，擅长深度调研和报告撰写。
  输出结构化，论点有数据支撑，区分事实和推测。

这样做的好处是：代码 Agent 用最强模型保证质量，日常 Agent 用经济模型控制成本，各司其职。

不同场景的最佳配置方案

场景一：个人开发者（预算敏感）

目标：花最少的钱，日常够用。

# config.yaml
default_model: deepseek-v3.2
model_routing:
  primary: deepseek-v3.2
  strong: claude-sonnet-4          # 只有复杂任务才用
budget:
  daily_limit: 200000
  monthly_limit: 3000000
  on_exceed: pause                   # 超额直接暂停

月均成本：30-80 元。

场景二：全栈开发团队

目标：代码质量优先，成本其次。

# config.yaml
default_model: claude-sonnet-4
model_routing:
  primary: claude-sonnet-4
  strong: claude-opus-4
  economy: deepseek-v3.2
  fallback:
    - gpt-4o
    - gemini-3-flash
auto_routing:
  enabled: true
budget:
  daily_limit: 1000000
  monthly_limit: 20000000
  on_exceed: downgrade

月均成本：200-500 元/人。

场景三：企业客服 / 7x24 自动化

目标：稳定性第一，不能断。

# config.yaml
default_model: gpt-4o
model_routing:
  primary: gpt-4o
  fallback:
    - claude-sonnet-4
    - deepseek-v3.2
    - gemini-3-flash
    - gpt-4o-mini                    # 最后兜底

rate_limit:
  strategy: exponential_backoff
  auto_fallback: true

health_check:
  enabled: true
  interval: 300                      # 每 5 分钟检查模型可用性
  auto_switch: true                  # 不可用时自动切换

月均成本：500-2000 元（取决于请求量）。

三种方案对比

常见配置错误排查

错误 1：invalid model: xxx

原因：模型 ID 不被 API 提供商识别。

排查：

# 查看当前提供商支持的模型列表
openclaw models list

# 检查你的 models.yaml 中 model 字段拼写
# 常见错误：
#   claude-sonnet → 应为 anthropic/claude-sonnet-4
#   gpt-4 → 应为 gpt-4o
#   deepseek → 应为 deepseek/deepseek-chat

错误 2：authentication failed / invalid api key

原因：API Key 无效或未正确加载。

排查：

# 检查环境变量是否设置
echo $OPENCLAW_API_KEY

# 如果用 .env 文件，确认格式正确（等号两边不能有空格）
cat ~/.openclaw/.env
# 正确：OPENCLAW_API_KEY=sk-xxxxx
# 错误：OPENCLAW_API_KEY = sk-xxxxx

# 直接测试 API Key 是否有效
curl -s https://api.ofox.ai/v1/models \
  -H "Authorization: Bearer sk-your-key" | head -20

错误 3：timeout 请求超时

原因：timeout 设置过小，或网络到 API 端点延迟高。

排查：

# 测试到 API 端点的延迟
curl -o /dev/null -s -w "time_total: %{time_total}s\n" \
  https://api.ofox.ai/v1/models \
  -H "Authorization: Bearer sk-your-key"

# 如果延迟 > 2 秒，考虑：
# 1. 增大 timeout 值
# 2. 切换有国内加速节点的提供商

错误 4：YAML 语法错误

这是最隐蔽的问题。OpenClaw 不一定给出明确的 YAML 解析错误提示，可能表现为配置不生效。

# 验证配置文件语法
openclaw config validate

# 常见 YAML 坑：
# 1. 缩进用了 Tab（必须用空格）
# 2. 冒号后面没有空格（name:value → name: value）
# 3. 字符串含特殊字符没加引号（api_key: sk-xxx#123 → api_key: "sk-xxx#123"）

错误 5：配置修改后不生效

原因：部分配置需要重启才能生效。

# models.yaml 修改后需要重启
openclaw restart

# config.yaml 中以下参数支持热加载（不需要重启）：
#   - budget
#   - logging.level
#   - security.allowed_commands

# 确认加载的是哪个配置文件
openclaw config show --source

错误 6：环境变量没有覆盖配置文件

环境变量的优先级：命令行参数 > 环境变量 > .env 文件 > config.yaml 默认值。

# 检查所有生效的配置来源
openclaw config show --verbose

# 如果 .env 文件不生效，确认文件位置：
# ~/.openclaw/.env      ← 全局
# ./.env                ← 项目级（当前目录）

常见问题（FAQ）

多个模型的 API Key 可以不一样吗？

可以。每个模型条目都有独立的 api_key 字段。比如国产模型用 DeepSeek 官方 Key，海外模型用 Ofox 的 Key：

models:
  - name: deepseek-v3.2
    api_key: ${DEEPSEEK_API_KEY}
    base_url: https://api.deepseek.com/v1
  - name: claude-sonnet-4
    api_key: ${OFOX_API_KEY}
    base_url: https://api.ofox.ai/v1

用聚合平台的话，一个 Key 就能覆盖所有模型。

Agent 级别的模型配置和全局配置冲突了怎么办？

Agent 配置优先级高于全局配置。如果 agents/coder.yaml 里设了 model: claude-opus-4，即使全局 default_model 是 Sonnet，Coder Agent 仍然会用 Opus。

优先级从高到低：命令行参数 > Agent 配置 > 全局配置 > 默认值。

怎么测试配置是否正确？

# 验证配置文件语法
openclaw config validate

# 测试模型连通性
openclaw models test

# 测试特定模型
openclaw models test --model claude-sonnet-4

配置文件可以放在项目目录里吗？

可以。在项目根目录创建 .openclaw/ 目录，放入 config.yaml 和 models.yaml。项目级配置会覆盖全局配置，适合团队协作：把非敏感配置提交到仓库，API Key 通过环境变量注入。

通过 OpenAI 兼容接口调用非 OpenAI 模型需要注意什么？

model 字段需要加 provider 前缀。例如通过 Ofox 调用 Claude，model 应填 anthropic/claude-sonnet-4 而不是 claude-sonnet-4。OpenAI 自家模型（如 gpt-4o）不需要前缀。

总结

OpenClaw 的模型配置分三层：入门用 openclaw onboard 一个模型跑起来；进阶配 primary + fallback 双模型保证稳定性；高级用三级路由 + 预算控制 + 多 Agent 独立配置。

核心原则：按任务复杂度分配模型。80% 的日常任务用 Sonnet/GPT-4o 足够，只有复杂推理才升级到 Opus。配合经济模型处理简单任务，月均成本能降 60% 以上。