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

摘要

OpenClaw 安装容易，配置才是真功夫。很多人跑通了 openclaw onboard 就以为万事大吉，结果遇到模型切换、fallback、多 Agent 配置时一脸懵。这篇教程从 ~/.openclaw/ 目录结构讲起，逐个拆解模型配置参数，手把手教你搞定多模型轮询、自动降级、预算控制等高级玩法。所有配置示例都可以直接复制使用。

目录

• 从 onboard 开始：初始化配置
• ~/.openclaw/ 目录结构详解
• 模型配置参数逐项拆解
• 完整配置示例：从单模型到多模型
• 高级配置：多模型轮询与 Fallback
• 不同场景的最佳配置方案
• 常见配置错误排查
• 常见问题（FAQ）
• 总结
• 参考资料

从 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-6
    gpt-4o
    gemini-3-pro
    deepseek-v3.2
    (type to search...)

日常使用推荐 claude-sonnet-4-6 或 gpt-4o，性价比最高。

第四步：配置 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-6

# 模型路由策略
model_routing:
  primary: claude-sonnet-4-6        # 主力模型
  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-6
    provider: anthropic
    model: claude-sonnet-4-6
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}    # 引用环境变量
    max_tokens: 8192
    temperature: 0.7
    timeout: 60

  - name: claude-opus-4-6
    provider: anthropic
    model: claude-opus-4-6
    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: 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-chat
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 30

注意 api_key 用了 ${OPENCLAW_API_KEY} 语法引用环境变量——这样你不用在配置文件里硬编码密钥，更安全。

模型配置参数逐项拆解

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

参数	类型	必填	说明	示例
name	string	是	模型别名，在 OpenClaw 内部引用	claude-sonnet-4-6
provider	string	是	提供商标识	openai / anthropic / google / deepseek
model	string	是	模型 ID，必须与提供商支持的 ID 完全匹配	claude-sonnet-4-6
base_url	string	是	API 端点地址	https://api.ofox.ai/v1
api_key	string	是	API 密钥，支持环境变量引用	${OPENCLAW_API_KEY}
max_tokens	int	否	单次响应最大 token 数	8192
temperature	float	否	输出随机性，0-2	0.7
top_p	float	否	核采样参数，0-1	0.95
timeout	int	否	请求超时（秒）	60
max_retries	int	否	失败重试次数	3
retry_delay	int	否	重试间隔（秒）	2
context_window	int	否	模型上下文窗口大小	200000
streaming	bool	否	是否启用流式输出	true
headers	map	否	自定义请求头	见下方

几个关键参数的选择建议

temperature

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

场景	推荐值	理由
代码生成 / 数据处理	0.1 - 0.3	需要确定性输出，减少随机错误
日常对话 / 任务执行	0.5 - 0.7	平衡准确性和自然度
创意写作 / 头脑风暴	0.8 - 1.0	更多样化的输出

max_tokens

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

模型	建议 max_tokens	上下文窗口
Claude Sonnet 4.6	8192	200K
Claude Opus 4.6	16384	1M
GPT-4o	4096	128K
GPT-5.4 Thinking	16384	1M
DeepSeek V3.2	8192	128K
Gemini 3.1 Pro	8192	2M

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-6

# ~/.openclaw/models.yaml
models:
  - name: claude-sonnet-4-6
    provider: anthropic
    model: claude-sonnet-4-6
    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-6
model_routing:
  primary: claude-sonnet-4-6
  fallback: gpt-4o

# ~/.openclaw/models.yaml
models:
  - name: claude-sonnet-4-6
    provider: anthropic
    model: claude-sonnet-4-6
    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: 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-6

model_routing:
  primary: claude-sonnet-4-6
  strong: claude-opus-4-6           # 复杂任务自动升级
  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-6
    provider: anthropic
    model: claude-sonnet-4-6
    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-6
    provider: anthropic
    model: claude-opus-4-6
    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: 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-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: 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，不需要分别注册五个账号。

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

Fallback 链的工作原理

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

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

# 详细的 fallback 配置
model_routing:
  primary: claude-sonnet-4-6
  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-6              # 代码任务用最强模型
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-6            # 研究分析用主力模型
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-6          # 只有复杂任务才用
budget:
  daily_limit: 200000
  monthly_limit: 3000000
  on_exceed: pause                   # 超额直接暂停

月均成本：30-80 元。

场景二：全栈开发团队

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

# config.yaml
default_model: claude-sonnet-4-6
model_routing:
  primary: claude-sonnet-4-6
  strong: claude-opus-4-6
  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-6
    - 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 元（取决于请求量）。

三种方案对比

维度	个人开发者	全栈团队	企业客服
主力模型	DeepSeek V3.2	Claude Sonnet 4.6	GPT-4o
模型数量	2	5	5
Fallback 层数	1	2	4
预算控制	严格（超额暂停）	中等（超额降级）	宽松（优先稳定）
月均成本	30-80 元	200-500 元/人	500-2000 元
核心诉求	省钱	质量	稳定

常见配置错误排查

错误 1：invalid model: xxx

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

排查：

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

# 检查你的 models.yaml 中 model 字段拼写
# 常见错误：
#   claude-sonnet → 应为 claude-sonnet-4-6
#   gpt-4 → 应为 gpt-4o
#   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）

OpenClaw 的配置文件在哪里？

所有配置文件在 ~/.openclaw/ 目录下。核心文件是 config.yaml（全局配置）和 models.yaml（模型定义）。首次运行 openclaw onboard 会自动创建这些文件，也可以手动创建和编辑。

onboard 配置过程可以跳过吗？

可以。直接在 ~/.openclaw/ 下手动创建 config.yaml 和 models.yaml，填好模型参数即可。但不建议新手这么做——onboard 引导过程会帮你检查连通性，避免一些低级配置错误。

YAML 和 JSON 配置文件怎么选？

推荐 YAML。YAML 支持注释（# 开头），可读性好得多。OpenClaw 自动识别文件格式——config.yaml 和 config.json 都能用，但不能同时存在两个。

多个模型的 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-6
    api_key: ${OFOX_API_KEY}
    base_url: https://api.ofox.ai/v1

不过用聚合平台的话，一个 Key 就能覆盖所有模型，管理起来更简单。

怎么查看当前用了哪个模型？

# 查看当前活跃模型
openclaw status

# 查看模型使用统计
openclaw usage --detail

# 查看最近 24 小时的模型切换记录
openclaw logs --filter model_switch --since 24h

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

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

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

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

可以。OpenClaw 支持项目级配置——在项目根目录创建 .openclaw/ 目录，放入 config.yaml 和 models.yaml。项目级配置会覆盖全局配置。这对团队协作很有用：把非敏感配置（模型选择、temperature 等）提交到仓库，API Key 通过环境变量注入。

怎么测试配置是否正确？

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

# 测试模型连通性
openclaw models test

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

# 运行一次简单对话确认端到端正常
openclaw chat "你好，请回复一个 OK"

配置太多记不住怎么办？

两个建议：

1. 用 openclaw config show 随时查看当前生效的完整配置
2. 把配置文件加入版本控制（记得 .gitignore 掉含 API Key 的 .env 文件）

OpenClaw 的配置是渐进式的——从最简单的单模型配置开始，用到什么加什么，不需要一次配完所有参数。

总结

OpenClaw 的模型配置体系分三层：

1. 入门：openclaw onboard 引导完成基础配置，一个模型就能跑
2. 进阶：配置 primary + fallback 双模型，保证稳定性
3. 高级：三级模型路由 + 预算控制 + 多 Agent 独立配置，兼顾质量、成本和稳定性

核心原则就一条：不要把所有任务都扔给最贵的模型。80% 的日常任务用 Sonnet/GPT-4o 绰绰有余，只有真正需要深度推理的复杂任务才升级到 Opus 或 GPT-5.4 Thinking。配合经济模型处理简单任务，月均成本能降 60% 以上。

如果你还没有统一的 API 管理方案，推荐试试 Ofox——一个 Key 用所有模型，省去多平台注册和 Key 管理的麻烦。注册有免费额度，跑通配置不花钱。

参考资料

• OpenClaw 官方文档 - 配置指南 - 完整配置参数参考
• OpenClaw 官方文档 - 模型管理 - 模型配置与路由详解
• OpenClaw GitHub 仓库 - 源码和配置示例
• Ofox AI API 文档 - API 接入和模型列表
• Ofox OpenClaw 集成指南 - OpenClaw 专属配置教程
• OpenClaw API 推荐与模型配置指南 - 国内使用完全攻略