目录
-
- 热门文章推荐
- 摘要
- 一、引言:为什么需要多模型支持
-
- [1.1 AI 模型生态的多元化现状](#1.1 AI 模型生态的多元化现状)
- [1.2 多模型支持的核心价值](#1.2 多模型支持的核心价值)
- 二、支持的模型提供商
-
- [2.1 OpenAI](#2.1 OpenAI)
- [2.2 Anthropic(Claude)](#2.2 Anthropic(Claude))
- [2.3 Qwen(通义千问)](#2.3 Qwen(通义千问))
- [2.4 Ollama(本地模型)](#2.4 Ollama(本地模型))
- 三、模型配置详解
-
- [3.1 基本配置结构](#3.1 基本配置结构)
- [3.2 模型选择配置](#3.2 模型选择配置)
- [3.3 自定义提供商配置](#3.3 自定义提供商配置)
- [3.4 模型参数配置](#3.4 模型参数配置)
- 四、模型切换机制
-
- [4.1 Default 默认模型](#4.1 Default 默认模型)
- [4.2 Reasoning 推理模型](#4.2 Reasoning 推理模型)
- [4.3 Per-Session 会话级切换](#4.3 Per-Session 会话级切换)
- [4.4 模型回退机制](#4.4 模型回退机制)
- 五、模型路由策略
-
- [5.1 任务类型分类](#5.1 任务类型分类)
- [5.2 路由策略配置](#5.2 路由策略配置)
- [5.3 CLI 路由管理](#5.3 CLI 路由管理)
- [5.4 智能路由示例](#5.4 智能路由示例)
- 六、成本优化实践
-
- [6.1 模型成本对比](#6.1 模型成本对比)
- [6.2 提示缓存优化](#6.2 提示缓存优化)
- [6.3 分层模型策略](#6.3 分层模型策略)
- [6.4 成本监控与分析](#6.4 成本监控与分析)
- 七、总结
- 参考资料
热门文章推荐
摘要
在现代 AI 应用开发中,单一模型已无法满足多样化的业务需求。OpenClaw 作为一款强大的 AI 智能体框架,提供了灵活的多模型配置与切换机制,支持 OpenAI、Anthropic、Qwen、Ollama 等主流模型提供商。本文将深入探讨 OpenClaw 的多模型架构设计,详细解析 openclaw.yaml 配置文件中的模型配置格式,介绍 default、reasoning、per-session 等多种模型切换机制,并分享基于任务类型的模型路由策略与成本优化实践。通过本文,读者将掌握如何在 OpenClaw 中高效管理多个 AI 模型,实现性能与成本的最佳平衡。🔧
一、引言:为什么需要多模型支持
1.1 AI 模型生态的多元化现状
随着大语言模型技术的飞速发展,AI 模型生态呈现出前所未有的多元化格局。OpenAI 的 GPT 系列、Anthropic 的 Claude 系列、阿里巴巴的通义千问(Qwen)、以及开源社区的各种模型,各有其独特的优势和应用场景。这种多元化为开发者提供了丰富的选择,同时也带来了新的挑战:如何在同一个应用中灵活地使用不同的模型?🤔
不同的模型在以下方面存在显著差异:
| 维度 | OpenAI GPT | Anthropic Claude | Qwen | Ollama 本地模型 |
|---|---|---|---|---|
| 推理能力 | 强 | 极强 | 强 | 取决于模型 |
| 代码生成 | 优秀 | 优秀 | 优秀 | 取决于模型 |
| 中文理解 | 良好 | 良好 | 优秀 | 取决于模型 |
| 成本 | 较高 | 较高 | 免费/低成本 | 免费 |
| 隐私保护 | 云端处理 | 云端处理 | 云端处理 | 本地处理 |
| 响应速度 | 快 | 快 | 快 | 取决于硬件 |
1.2 多模型支持的核心价值
OpenClaw 的多模型支持架构为开发者带来了以下核心价值:
🎯 灵活选择:根据任务特点选择最合适的模型,例如使用 Claude 进行深度推理,使用 GPT 进行创意写作,使用 Qwen 处理中文任务。
💰 成本优化:通过合理配置模型路由,在保证质量的前提下降低 API 调用成本。简单任务使用低成本模型,复杂任务才使用高端模型。
🔒 隐私保护:敏感数据处理可路由至本地 Ollama 模型,确保数据不出本地环境。
⚡ 高可用性:配置模型回退机制,当主模型不可用时自动切换到备用模型,保证服务稳定性。
多模型支持的核心价值
灵活选择
任务匹配最优模型
成本优化
按需分配资源
隐私保护
敏感数据本地处理
高可用性
自动故障转移
提升整体效率
二、支持的模型提供商
OpenClaw 支持多种主流模型提供商,每种提供商都有其独特的认证方式和配置方法。下面将详细介绍各个提供商的特点和配置方式。
2.1 OpenAI
OpenAI 是 AI 领域的先驱者,其 GPT 系列模型在业界广受认可。OpenClaw 支持两种 OpenAI 认证方式:
方式 A:API 密钥认证
这是最常用的认证方式,适用于直接 API 访问和按量计费场景。开发者可以从 OpenAI 控制台获取 API 密钥。
bash
# 交互式设置
openclaw onboard --auth-choice openai-api-key
# 非交互式设置
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
方式 B:Codex 订阅认证
适用于使用 ChatGPT/Codex 订阅访问而非 API 密钥的场景。这种方式通过 OAuth 流程完成认证。
bash
# 运行 Codex OAuth
openclaw onboard --auth-choice openai-codex
# 或直接运行 OAuth
openclaw models auth login --provider openai-codex
2.2 Anthropic(Claude)
Anthropic 的 Claude 系列模型以其出色的推理能力和安全性著称。OpenClaw 同样支持两种认证方式:
选项 A:Anthropic API 密钥
标准 API 访问方式,在 Anthropic Console 中创建 API 密钥。
json5
{
env: { ANTHROPIC_API_KEY: "sk-ant-..." },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
}
选项 B:Claude setup-token
使用 Claude 订阅进行认证,setup-token 由 Claude Code CLI 创建:
bash
claude setup-token
然后在 OpenClaw 中粘贴该令牌即可完成认证。
2.3 Qwen(通义千问)
Qwen 是阿里巴巴推出的大语言模型系列,在中文理解和代码生成方面表现出色。Qwen 提供免费层 OAuth 访问,每天支持 2000 次请求。
bash
# 启用插件
openclaw plugins enable qwen-portal-auth
# 认证登录
openclaw models auth login --provider qwen-portal --set-default
Qwen 的模型 ID 包括:
qwen-portal/coder-model:代码生成专用qwen-portal/vision-model:视觉理解专用
2.4 Ollama(本地模型)
Ollama 是一个本地 LLM 运行时,可以轻松在本地机器上运行开源模型。OpenClaw 通过 Ollama 的 OpenAI 兼容 API 进行集成,并支持自动发现支持工具调用的模型。
bash
# 安装 Ollama
# 访问 https://ollama.ai
# 拉取模型
ollama pull llama3.3
ollama pull qwen2.5-coder:32b
ollama pull deepseek-r1:32b
# 启用 Ollama
export OLLAMA_API_KEY="ollama-local"
Ollama 的优势在于:
- 完全免费:所有模型费用为 $0
- 隐私保护:数据不出本地
- 灵活配置:支持各种开源模型
模型提供商认证方式
OpenAI
API Key
OAuth/Codex
Anthropic
API Key
setup-token
Qwen
OAuth 免费层
Ollama
本地无需认证
三、模型配置详解
OpenClaw 的模型配置主要通过 openclaw.yaml 或 openclaw.json5 文件完成。本节将详细解析配置文件的结构和各个配置项的含义。
3.1 基本配置结构
OpenClaw 的模型配置遵循清晰的层次结构,主要包括以下几个部分:
json5
{
// 环境变量配置
env: {
OPENAI_API_KEY: "sk-...",
ANTHROPIC_API_KEY: "sk-ant-...",
},
// 智能体默认配置
agents: {
defaults: {
// 主模型配置
model: {
primary: "anthropic/claude-opus-4-5",
fallbacks: ["openai/gpt-5.2", "qwen-portal/coder-model"]
},
// 图像模型配置
imageModel: {
primary: "openai/gpt-4-vision"
},
// 模型白名单和别名
models: {
"anthropic/claude-opus-4-5": { alias: "Opus" },
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
"openai/gpt-5.2": { alias: "GPT-5" }
}
}
},
// 自定义提供商配置
models: {
mode: "merge",
providers: {
// 提供商详细配置
}
}
}
3.2 模型选择配置
agents.defaults.model 是模型选择的核心配置项,支持以下属性:
| 属性 | 类型 | 说明 | 示例 |
|---|---|---|---|
primary |
string | 主要使用的模型 | "anthropic/claude-opus-4-5" |
fallbacks |
array | 回退模型列表 | ["openai/gpt-5.2"] |
reasoning |
string | 推理任务专用模型 | "anthropic/claude-opus-4-5" |
模型引用格式统一为 provider/model,例如:
openai/gpt-5.2anthropic/claude-opus-4-5qwen-portal/coder-modelollama/llama3.3
3.3 自定义提供商配置
对于需要自定义端点的提供商,可以通过 models.providers 进行详细配置:
json5
{
models: {
mode: "merge", // merge 或 replace
providers: {
moonshot: {
baseUrl: "https://api.moonshot.ai/v1",
apiKey: "${MOONSHOT_API_KEY}",
api: "openai-completions",
models: [
{
id: "kimi-k2.5",
name: "Kimi K2.5",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 8192
}
]
},
lmstudio: {
baseUrl: "http://localhost:1234/v1",
apiKey: "LMSTUDIO_KEY",
api: "openai-completions",
models: [
{
id: "minimax-m2.1-gs32",
name: "MiniMax M2.1",
contextWindow: 200000,
maxTokens: 8192
}
]
}
}
}
}
上述配置展示了如何添加 Moonshot AI 和 LM Studio 作为自定义提供商。每个提供商配置包含以下关键字段:
- baseUrl:API 端点地址
- apiKey:认证密钥(支持环境变量引用)
- api :API 协议类型(
openai-completions或anthropic-messages) - models:该提供商支持的模型列表
3.4 模型参数配置
OpenClaw 支持为特定模型配置参数,例如 Anthropic 的提示缓存功能:
json5
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-5": {
params: { cacheRetention: "long" }
}
}
}
}
}
提示缓存配置选项:
| 值 | 缓存时长 | 描述 |
|---|---|---|
none |
无缓存 | 禁用提示缓存 |
short |
5 分钟 | API 密钥认证的默认值 |
long |
1 小时 | 扩展缓存(需要 beta 标志) |
配置文件结构
openclaw.yaml
env 环境变量
agents 智能体配置
models 提供商配置
defaults.model 主模型
defaults.imageModel 图像模型
defaults.models 模型白名单
providers 自定义提供商
mode 合并模式
baseUrl 端点
apiKey 密钥
models 模型列表
四、模型切换机制
OpenClaw 提供了灵活的模型切换机制,支持多种切换方式以满足不同场景的需求。
4.1 Default 默认模型
默认模型是 OpenClaw 启动时自动加载的主模型,通过 agents.defaults.model.primary 配置:
json5
{
agents: {
defaults: {
model: { primary: "anthropic/claude-opus-4-5" }
}
}
}
默认模型的选择应考虑以下因素:
- 通用性:能够处理大多数常见任务
- 稳定性:API 可用性高,响应稳定
- 成本效益:在性能和成本之间取得平衡
4.2 Reasoning 推理模型
对于需要深度推理的任务,OpenClaw 支持配置专用的推理模型:
json5
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-5",
reasoning: "anthropic/claude-opus-4-5"
}
}
}
}
推理模型通常具有更强的逻辑分析能力,适用于:
- 复杂问题求解
- 代码架构设计
- 数据分析与洞察
- 多步骤推理任务
4.3 Per-Session 会话级切换
OpenClaw 支持在运行时动态切换模型,无需重启服务。通过 /model 命令实现:
bash
# 查看可用模型
/model
/model list
# 通过编号选择
/model 3
# 通过完整引用选择
/model openai/gpt-5.2
# 查看当前模型状态
/model status
会话级切换的特点:
- 即时生效:切换后立即使用新模型
- 无需重启:不影响其他会话
- 灵活便捷:根据任务需求快速调整
4.4 模型回退机制
当主模型不可用时,OpenClaw 会自动尝试回退模型列表中的模型:
json5
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4-5",
fallbacks: [
"openai/gpt-5.2",
"qwen-portal/coder-model",
"ollama/llama3.3"
]
}
}
}
}
回退机制的触发条件:
- API 调用失败(网络错误、服务不可用)
- 认证过期或无效
- 速率限制触发
- 模型响应超时
回退模型2 回退模型1 主模型 OpenClaw 网关 用户 回退模型2 回退模型1 主模型 OpenClaw 网关 用户 alt [回退模型1成功] [回退模型1失败] alt [主模型成功] [主模型失败] 发送请求 调用主模型 返回结果 返回响应 错误响应 调用回退模型1 返回结果 返回响应 错误响应 调用回退模型2 返回结果 返回响应
五、模型路由策略
合理的模型路由策略能够在保证服务质量的同时优化成本。本节将介绍基于任务类型的模型路由最佳实践。
5.1 任务类型分类
根据任务的复杂度和特点,可以将任务分为以下几类:
| 任务类型 | 特点 | 推荐模型 | 成本等级 |
|---|---|---|---|
| 简单问答 | 单轮对话,信息检索 | GPT-4o-mini, Qwen | 低 |
| 代码生成 | 需要编程能力 | Claude Sonnet, GPT-4 | 中 |
| 深度推理 | 复杂逻辑分析 | Claude Opus | 高 |
| 创意写作 | 内容创作 | GPT-4, Claude | 中 |
| 数据处理 | 结构化数据处理 | Claude Sonnet | 中 |
| 隐私敏感 | 需要本地处理 | Ollama 本地模型 | 免费 |
5.2 路由策略配置
以下是一个基于任务类型的模型路由配置示例:
json5
{
agents: {
defaults: {
model: {
// 默认使用性价比高的模型
primary: "anthropic/claude-sonnet-4-5",
// 推理任务使用更强的模型
reasoning: "anthropic/claude-opus-4-5",
// 回退链
fallbacks: [
"openai/gpt-5.2",
"qwen-portal/coder-model",
"ollama/llama3.3"
]
},
// 图像处理模型
imageModel: {
primary: "openai/gpt-4-vision",
fallbacks: ["qwen-portal/vision-model"]
},
// 模型别名,便于切换
models: {
"anthropic/claude-opus-4-5": { alias: "Opus" },
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
"openai/gpt-5.2": { alias: "GPT-5" },
"qwen-portal/coder-model": { alias: "Qwen" },
"ollama/llama3.3": { alias: "Local" }
}
}
}
}
5.3 CLI 路由管理
OpenClaw 提供了丰富的 CLI 命令来管理模型路由:
bash
# 查看模型列表
openclaw models list
openclaw models list --all # 完整目录
openclaw models list --local # 仅本地提供商
openclaw models list --provider anthropic # 按提供商筛选
# 查看模型状态
openclaw models status
openclaw models status --check # 自动化检查
# 设置主模型
openclaw models set anthropic/claude-opus-4-5
# 管理回退模型
openclaw models fallbacks list
openclaw models fallbacks add openai/gpt-5.2
openclaw models fallbacks remove openai/gpt-5.2
openclaw models fallbacks clear
# 管理模型别名
openclaw models aliases list
openclaw models aliases add Opus anthropic/claude-opus-4-5
openclaw models aliases remove Opus
5.4 智能路由示例
以下代码展示了如何根据任务特征自动选择合适的模型:
python
# 这是一个概念示例,展示模型路由的逻辑
# 实际实现可能因 OpenClaw 版本而异
def select_model_for_task(task_type, privacy_required=False):
"""
根据任务类型选择合适的模型
Args:
task_type: 任务类型 (simple, coding, reasoning, creative, data)
privacy_required: 是否需要隐私保护
Returns:
推荐的模型引用
"""
# 隐私敏感任务使用本地模型
if privacy_required:
return "ollama/llama3.3"
# 根据任务类型路由
model_mapping = {
"simple": "anthropic/claude-sonnet-4-5", # 性价比高
"coding": "anthropic/claude-sonnet-4-5", # 代码能力强
"reasoning": "anthropic/claude-opus-4-5", # 推理能力最强
"creative": "openai/gpt-5.2", # 创意表现好
"data": "anthropic/claude-sonnet-4-5" # 数据处理稳定
}
return model_mapping.get(task_type, "anthropic/claude-sonnet-4-5")
def estimate_cost(model, input_tokens, output_tokens):
"""
估算 API 调用成本
Args:
model: 模型引用
input_tokens: 输入 token 数
output_tokens: 输出 token 数
Returns:
预估成本(美元)
"""
# 模型定价(示例,实际价格请参考官方)
pricing = {
"anthropic/claude-opus-4-5": {"input": 0.015, "output": 0.075},
"anthropic/claude-sonnet-4-5": {"input": 0.003, "output": 0.015},
"openai/gpt-5.2": {"input": 0.01, "output": 0.03},
"qwen-portal/coder-model": {"input": 0, "output": 0}, # 免费
"ollama/llama3.3": {"input": 0, "output": 0} # 本地免费
}
if model not in pricing:
return 0
rates = pricing[model]
cost = (input_tokens * rates["input"] + output_tokens * rates["output"]) / 1000
return cost
上述代码展示了模型路由的核心逻辑:首先检查隐私需求,然后根据任务类型选择最合适的模型。成本估算函数帮助开发者在选择模型时做出经济决策。
是
否
简单问答
代码生成
深度推理
创意写作
数据处理
是
否
接收任务
隐私敏感?
路由到 Ollama 本地模型
任务类型?
Claude Sonnet
Claude Sonnet / GPT-4
Claude Opus
GPT-4 / Claude
Claude Sonnet
执行任务
执行成功?
返回结果
尝试回退模型
六、成本优化实践
在多模型环境中,成本优化是一个重要课题。本节将分享一些实用的成本优化策略。
6.1 模型成本对比
不同模型的定价差异显著,合理选择可以大幅降低成本:
| 模型 | 输入价格 ($/1K tokens) | 输出价格 ($/1K tokens) | 适用场景 |
|---|---|---|---|
| Claude Opus 4.5 | $0.015 | $0.075 | 复杂推理、关键任务 |
| Claude Sonnet 4.5 | $0.003 | $0.015 | 日常任务、代码生成 |
| GPT-5.2 | $0.010 | $0.030 | 通用任务、创意写作 |
| GPT-4o-mini | $0.00015 | $0.0006 | 简单任务、批量处理 |
| Qwen Portal | 免费 | 免费 | 中文任务、代码生成 |
| Ollama | 免费 | 免费 | 隐私敏感、离线场景 |
6.2 提示缓存优化
Anthropic 提供的提示缓存功能可以显著降低重复内容的处理成本:
json5
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-5": {
params: { cacheRetention: "long" } // 1小时缓存
},
"anthropic/claude-sonnet-4-5": {
params: { cacheRetention: "short" } // 5分钟缓存
}
}
}
}
}
缓存优化的效果:
- 系统提示:缓存后无需重复计费
- 长上下文:文档分析场景节省 80%+ 成本
- 多轮对话:历史消息缓存减少重复处理
6.3 分层模型策略
采用分层策略,根据任务重要性选择不同级别的模型:
json5
{
agents: {
// 主智能体:处理重要任务
defaults: {
model: { primary: "anthropic/claude-opus-4-5" }
},
// 子智能体列表:处理不同优先级任务
list: [
{
id: "quick-helper",
model: { primary: "anthropic/claude-sonnet-4-5" },
description: "快速响应日常问题"
},
{
id: "code-assistant",
model: { primary: "qwen-portal/coder-model" },
description: "代码生成与审查"
},
{
id: "private-processor",
model: { primary: "ollama/llama3.3" },
description: "处理隐私敏感数据"
}
]
}
}
6.4 成本监控与分析
OpenClaw 提供了模型状态监控功能,帮助追踪使用情况:
bash
# 查看模型状态和认证信息
openclaw models status
# JSON 格式输出,便于分析
openclaw models status --json
# 自动化检查(缺失/过期时退出码非0)
openclaw models status --check
建议的成本监控实践:
- 定期审查:每周检查模型使用分布
- 设置预算:为不同项目设置 API 调用预算
- 优化提示:精简提示词,减少不必要的 token 消耗
- 使用缓存:充分利用提示缓存功能
- 选择合适模型:简单任务使用轻量模型
40% 20% 15% 15% 10% 模型成本分配建议 Claude Sonnet (日常任务) Claude Opus (关键推理) GPT-4o-mini (批量处理) Qwen (中文任务) Ollama (隐私敏感)
七、总结
OpenClaw 的多模型配置与切换机制为现代 AI 应用开发提供了强大而灵活的解决方案。通过本文的详细介绍,我们深入了解了以下核心内容:
🎯 多模型支持的价值:在 AI 模型生态日益多元化的今天,单一模型已无法满足所有需求。OpenClaw 的多模型架构让开发者能够根据任务特点灵活选择最合适的模型,在性能、成本和隐私之间取得最佳平衡。
🔧 丰富的提供商支持:OpenClaw 支持主流模型提供商,包括 OpenAI(API 和 Codex 订阅)、Anthropic(API 和 setup-token)、Qwen(免费 OAuth)以及 Ollama(本地模型)。每种提供商都有其独特的认证方式和配置方法,满足不同场景的需求。
⚙️ 灵活的配置体系 :通过 openclaw.yaml 配置文件,开发者可以精细控制模型选择、回退机制、参数设置等各个方面。配置结构清晰,支持环境变量引用、模型别名、自定义提供商等高级功能。
🔄 多样的切换机制:Default 默认模型、Reasoning 推理模型、Per-Session 会话级切换,以及自动回退机制,构成了完整的模型切换体系。无论是静态配置还是动态调整,OpenClaw 都能优雅应对。
📊 智能路由策略:基于任务类型的模型路由策略,结合成本优化实践,帮助开发者在保证服务质量的同时有效控制成本。提示缓存、分层模型策略、成本监控等手段,进一步提升了资源利用效率。
展望未来,随着 AI 模型技术的持续发展,OpenClaw 的多模型架构将继续演进,支持更多新兴模型提供商,提供更智能的路由算法,助力开发者构建更强大的 AI 应用。无论是个人开发者还是企业团队,都能从 OpenClaw 的多模型支持中受益,专注于业务创新,而非基础设施的复杂性。🚀
参考资料
- OpenClaw 官方文档 - 模型提供商:https://docs.openclaw.ai/providers/
- OpenClaw 官方文档 - 模型配置:https://docs.openclaw.ai/providers/models/
- OpenClaw 官方文档 - OpenAI 配置:https://docs.openclaw.ai/providers/openai/
- OpenClaw 官方文档 - Anthropic 配置:https://docs.openclaw.ai/providers/anthropic/
- OpenClaw 官方文档 - Qwen 配置:https://docs.openclaw.ai/providers/qwen/
- OpenClaw 官方文档 - Ollama 配置:https://docs.openclaw.ai/providers/ollama/
- OpenClaw 官方文档 - 模型提供商概念:https://docs.openclaw.ai/concepts/model-providers/
- OpenClaw 官方文档 - 模型 CLI:https://docs.openclaw.ai/concepts/models/
- Ollama 官方网站:https://ollama.ai
- Anthropic 官方文档:https://docs.anthropic.com