第 5 章 · 模型配置与切换
模型是 Agent 的"大脑"。选错模型，Agent 就像个博士在读小学题——浪费且笨拙；选对了，你的 AI 助手才能在速度、成本和智能之间找到最佳平衡点。
本章你将学到：
- 掌握主流模型提供商（Anthropic、OpenAI、Google、DeepSeek 等）的完整配置方法
- 理解多模型混合策略——什么时候用贵模型，什么时候用便宜模型
- 学会本地模型接入和成本控制，把每一分钱花在刀刃上
5.1 模型体系全景：理解 OpenClaw 的模型架构
在动手配置之前，你需要理解 OpenClaw 是怎么"看待"模型的。这不是一个简单的"填 API Key"的过程——OpenClaw 的模型体系比大多数人想象的要灵活得多。
5.1.1 模型引用格式：provider/model
OpenClaw 用 provider/model 格式引用模型，比如：
anthropic/claude-opus-4-6
openai/gpt-5.4
google/gemini-3.1-pro-preview
ollama/llama3.3
这个格式贯穿整个配置体系。provider 告诉 OpenClaw 去哪里调用（用什么 API、怎么认证），model 告诉它具体用哪个模型。当你看到类似 openrouter/anthropic/claude-sonnet-4-6 的三段式引用时，中间那段是原始提供商——OpenRouter 是个"中间商"，它转发请求给 Anthropic。
5.1.2 三层模型选择机制
OpenClaw 选择模型的优先级是这样的：
┌─────────────────────────────────────────┐
│ 1. Primary Model（主力模型） │
│ agents.defaults.model.primary │
│ ↑ 每次对话首先尝试这个 │
├─────────────────────────────────────────┤
│ 2. Fallbacks（备用模型链） │
│ agents.defaults.model.fallbacks │
│ ↑ 主力挂了按顺序往下试 │
├─────────────────────────────────────────┤
│ 3. Auth Profile Rotation（密钥轮转） │
│ 同一提供商的多个 API Key │
│ ↑ 在跳到下一个模型前先换 Key 重试 │
└─────────────────────────────────────────┘
这意味着你可以设计出非常精细的策略：比如主力用 Claude Opus（最强但最贵），第一个备用是 Claude Sonnet（稍弱但便宜一半），第二个备用是 GPT-5.4（不同提供商，分散风险）。
5.1.3 内置提供商 vs 自定义提供商
OpenClaw 内置了 30+ 个提供商的配置——Anthropic、OpenAI、Google、DeepSeek、Ollama、OpenRouter 等等。这些"开箱即用"的提供商你只需要设置认证信息就能用。
如果内置提供商不满足需求（比如你想用自己的代理服务器、私有部署的模型），OpenClaw 提供了 models.providers 配置项，允许你定义任意 OpenAI 兼容或 Anthropic 兼容的自定义提供商。
5.1.4 两个"容易混淆"的配置项
新手最常搞混的是这两个概念：
agents.defaults.model：当前 Agent 使用哪个模型（主力 + 备用）agents.defaults.models：模型白名单——定义了 Agent 可以使用哪些模型
如果你设置了 agents.defaults.models，它就变成了白名单。用户通过 /model 切换到不在白名单里的模型时，会收到 "Model is not allowed" 的提示——然后 Agent 就"沉默"了，因为它连正常回复都没生成。
⚠️ 踩坑记录
问题：设置了模型白名单后，Agent 突然不回复消息了。
原因：用户尝试切换到白名单外的模型，OpenClaw 拦截了请求，但拦截发生在正常回复之前，所以看起来像是 Agent "死了"。
解决：把需要的模型加到
agents.defaults.models里，或者直接删掉这个配置项（删除白名单，所有已认证的模型都可用）。
5.2 Anthropic Claude：三种接入方式
Anthropic 的 Claude 是目前最强的大模型之一，OpenClaw 提供了三种接入方式，适合不同的使用场景。
5.2.1 方式 A：Anthropic API Key（推荐）
这是最标准的接入方式。你在 Anthropic Console 创建 API Key，按用量付费。
步骤 1：获取 API Key
- 访问 console.anthropic.com
- 创建 API Key
- 复制保存（只显示一次）
步骤 2：配置 OpenClaw
# 交互式配置（推荐）
openclaw onboard
# 选择：Anthropic API key
# 或者非交互式配置
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
步骤 3：设置默认模型
// openclaw.json
{
env: { ANTHROPIC_API_KEY: "sk-ant-..." },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
Claude 4.6 系列目前有这些可选模型：
| 模型引用 | 模型名称 | 特点 |
|---|---|---|
anthropic/claude-opus-4-6 |
Claude Opus 4.6 | 最强，适合复杂推理和长文生成 |
anthropic/claude-sonnet-4-6 |
Claude Sonnet 4.6 | 性价比最高，日常对话首选 |
5.2.2 方式 B：Claude Setup-Token（用订阅额度）
如果你已经订阅了 Claude Pro/Max，可以用 Setup-Token 复用订阅额度，不额外付 API 费用。
⚠️ 注意：Anthropic 过去曾阻止订阅凭证在 Claude Code 之外使用。使用前请确认 Anthropic 当前的使用条款。API Key 方式是最安全、最推荐的路径。
获取 Setup-Token：
# 在任意机器上运行（不需要是 Gateway 所在机器）
claude setup-token
在 Gateway 上配置：
# 如果 token 是在 Gateway 机器上生成的
openclaw models auth setup-token --provider anthropic
# 如果 token 是在别的机器上生成的，需要手动粘贴
openclaw models auth paste-token --provider anthropic
5.2.3 方式 C：Claude CLI 后端（复用本地 CLI）
这个方式让 OpenClaw 直接调用本地安装的 Claude CLI 来做推理，而不是通过 Anthropic API。
适合场景：Gateway 和 Claude CLI 在同一台机器上的个人用户。
{
agents: {
defaults: {
model: {
primary: "claude-cli/claude-sonnet-4-6",
},
sandbox: { mode: "off" },
},
},
}
如果 claude 命令不在默认 PATH 里：
{
agents: {
defaults: {
cliBackends: {
"claude-cli": {
command: "/opt/homebrew/bin/claude",
},
},
},
},
}
⚠️ 注意：CLI 后端模式下，OpenClaw 侧的工具调用是禁用的。这是"文本进、文本出"的模式——适合简单的对话场景，不适合需要 Agent 调用工具的复杂任务。
5.2.4 Claude 的高级配置
Prompt Caching（提示词缓存）
Anthropic 支持提示词缓存——如果连续请求中有一部分内容相同，缓存命中后可以跳过重复处理，降低延迟和成本。
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": {
params: { cacheRetention: "long" }, // 1 小时缓存
},
},
},
},
}
cacheRetention 值 |
缓存时长 | 说明 |
|---|---|---|
none |
不缓存 | 完全禁用 |
short |
5 分钟 | API Key 认证时的默认值 |
long |
1 小时 | 需要启用 beta flag |
1M 上下文窗口
Claude 支持最大 1M token 的上下文窗口，但需要显式启用：
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": {
params: { context1m: true },
},
},
},
},
}
前提是你的 Anthropic 账户支持长上下文（通常是 API Key 付费账户，或开启了 Extra Usage 的订阅账户）。否则会收到 429 错误。
Fast Mode（快速模式）
{
agents: {
defaults: {
models: {
"anthropic/claude-sonnet-4-6": {
params: { fastMode: true },
},
},
},
},
}
Fast Mode 映射到 Anthropic 的 service_tier 参数。不过要注意：这只对 API Key 认证有效，setup-token 和 OAuth 认证不支持。
Thinking 模式（思考模式）
Claude 4.6 默认使用 adaptive 思考模式——模型自己决定要不要"深思"。你可以通过 /think 命令在聊天中切换：
/think low # 浅思考，响应更快
/think medium # 中等思考
/think high # 深度思考，适合复杂推理
/think off # 关闭思考
也可以在配置中为特定模型设置默认值：
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": {
params: { thinking: "high" },
},
},
},
},
}
5.3 OpenAI GPT：API Key 与 Codex 订阅
OpenAI 提供了两种接入路径：标准的 API Key 付费，以及通过 ChatGPT/Codex 订阅的 OAuth 认证。
5.3.1 方式 A：OpenAI API Key
openclaw onboard --auth-choice openai-api-key
# 或者
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
{
env: { OPENAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}
OpenClaw 当前支持的 OpenAI 模型：
| 模型引用 | 模型名称 | 说明 |
|---|---|---|
openai/gpt-5.4 |
GPT-5.4 | 当前主力模型 |
openai/gpt-5.4-pro |
GPT-5.4 Pro | 更强的推理能力 |
5.3.2 方式 B：OpenAI Codex 订阅（OAuth）
如果你有 ChatGPT Plus/Pro 订阅，可以通过 OAuth 直接使用 Codex：
openclaw onboard --auth-choice openai-codex
# 或直接触发 OAuth
openclaw models auth login --provider openai-codex
{
agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}
OpenAI 明确支持订阅 OAuth 在外部工具中使用——这和 Anthropic 的 setup-token 不同，Codex OAuth 是官方认可的使用方式。
5.3.3 传输协议：WebSocket vs SSE
OpenClaw 对 OpenAI 的默认传输协议是 "auto"——先尝试 WebSocket（更快），失败后回退到 SSE。
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
transport: "websocket", // "sse" | "websocket" | "auto"
},
},
},
},
},
}
WebSocket Warm-up（预热）
OpenClaw 默认为 OpenAI 启用 WebSocket 预热——在第一条消息到来之前就建立连接，减少首次响应延迟。
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: { openaiWsWarmup: false }, // 关闭预热
},
},
},
},
}
5.3.4 OpenAI 专属特性
Priority Processing（优先处理）
OpenAI 的 API 支持 service_tier=priority 参数，可以让你的请求排在前面：
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: { serviceTier: "priority" },
},
},
},
},
}
可选值：auto、default、flex、priority。
Fast Mode（快速模式）
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: { fastMode: true },
},
},
},
},
}
Fast Mode 开启后，OpenClaw 会自动设置低延迟配置：
reasoning.effort = "low"（降低推理深度）text.verbosity = "low"（降低输出冗长度）service_tier = "priority"（优先处理）
在聊天中也可以用 /fast on 和 /fast off 实时切换。
Server-Side Compaction（服务端压缩）
对于 openai/* 的 Responses 模型，OpenClaw 默认启用 OpenAI 的服务端上下文压缩：
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
responsesServerCompaction: true,
responsesCompactThreshold: 120000, // 自定义压缩阈值
},
},
},
},
},
}
当上下文占用达到 compact_threshold（默认为模型上下文窗口的 70%）时，OpenAI 服务端会自动压缩历史消息。这和 OpenClaw 自己的压缩机制是互补的——两道防线。
5.4 Google Gemini：多模态的瑞士军刀
Google Gemini 的独特之处在于它的多模态能力——不仅支持文本，还内置了图像生成、音视频理解和网页搜索。
5.4.1 API Key 接入
openclaw onboard --auth-choice google-api-key
{
agents: {
defaults: {
model: { primary: "google/gemini-3.1-pro-preview" },
},
},
}
获取 API Key：访问 aistudio.google.com，创建 API Key。
5.4.2 Gemini 的能力矩阵
| 能力 | 支持 | 说明 |
|---|---|---|
| 文本对话 | 是 | 基础对话能力 |
| 图像生成 | 是 | 直接生成图片，无需额外配置 |
| 图像理解 | 是 | 发送图片让模型分析 |
| 音频转录 | 是 | 语音转文字 |
| 视频理解 | 是 | 发送视频让模型分析 |
| 网页搜索（Grounding） | 是 | 模型可以联网搜索 |
| 思考/推理 | 是 | Gemini 3.1+ 支持 |
这个能力矩阵意味着：如果你需要"全能型" Agent——既能聊天，又能看图、听音频、搜网页——Gemini 可能是最省事的选择。
5.4.3 OAuth 接入（Gemini CLI）
Google 还提供了基于 OAuth 的接入方式（google-gemini-cli provider），通过 PKCE OAuth 流程认证。
⚠️ 注意：这是非官方集成。有用户报告使用第三方客户端后 Google 账户被限制。如果决定使用，建议用非核心账户，并仔细阅读 Google 的使用条款。
# 启用 Google 插件
openclaw plugins enable google
# OAuth 登录
openclaw models auth login --provider google-gemini-cli --set-default
5.5 DeepSeek：性价比之王
DeepSeek 提供了 OpenAI 兼容的 API，以极高的性价比著称。
5.5.1 快速配置
openclaw onboard --auth-choice deepseek-api-key
{
env: { DEEPSEEK_API_KEY: "sk-..." },
agents: {
defaults: {
model: { primary: "deepseek/deepseek-chat" },
},
},
}
获取 API Key：访问 platform.deepseek.com/api_keys。
5.5.2 可用模型
| 模型 ID | 名称 | 类型 | 上下文 |
|---|---|---|---|
deepseek-chat |
DeepSeek Chat (V3.2) | 通用对话 | 128K |
deepseek-reasoner |
DeepSeek Reasoner (V3.2) | 推理链 | 128K |
deepseek-chat 是日常对话的好选择，响应快、价格低。deepseek-reasoner 会在回复前展示"思考过程"（Chain-of-Thought），适合数学、编程等需要深度推理的场景。
5.6 Amazon Bedrock：企业级模型网关
如果你的组织已经在用 AWS，Bedrock 可能是最自然的接入方式——它提供了统一的 API 来调用 Claude、Llama、Mistral 等多种模型，计费走 AWS 账单。
5.6.1 配置 AWS 凭证
Bedrock 使用 AWS SDK 的默认凭证链，不需要单独的 API Key：
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# 可选
export AWS_SESSION_TOKEN="..."
export AWS_PROFILE="your-profile"
5.6.2 配置 Bedrock 模型
{
models: {
providers: {
"amazon-bedrock": {
baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
api: "bedrock-converse-stream",
auth: "aws-sdk",
models: [
{
id: "us.anthropic.claude-opus-4-6-v1:0",
name: "Claude Opus 4.6 (Bedrock)",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 200000,
maxTokens: 8192,
},
],
},
},
},
agents: {
defaults: {
model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
},
},
}
5.6.3 自动模型发现
Bedrock 支持自动发现可用模型——前提是你的 AWS 凭证有 bedrock:ListFoundationModels 权限：
{
models: {
bedrockDiscovery: {
enabled: true,
region: "us-east-1",
providerFilter: ["anthropic", "amazon"],
refreshInterval: 3600, // 缓存 1 小时
defaultContextWindow: 32000,
defaultMaxTokens: 4096,
},
},
}
5.6.4 EC2 实例角色
如果 OpenClaw 运行在 EC2 上，可以使用 IAM 实例角色自动认证。但 OpenClaw 的凭证检测目前只检查环境变量，不检查 IMDS。需要设置一个"信号"：
export AWS_PROFILE=default
export AWS_REGION=us-east-1
实际认证仍然通过 IMDS 使用实例角色，AWS_PROFILE=default 只是告诉 OpenClaw "我有 AWS 凭证"。
5.7 OpenRouter：一把钥匙开所有门
OpenRouter 是一个模型聚合平台——一个 API Key 就能访问几十个提供商的模型。对于想快速尝试不同模型的用户来说，这是最方便的选择。
5.7.1 快速配置
openclaw onboard --auth-choice apiKey \
--token-provider openrouter \
--token "$OPENROUTER_API_KEY"
{
env: { OPENROUTER_API_KEY: "sk-or-..." },
agents: {
defaults: {
model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
},
},
}
模型引用格式是 openrouter/<原始提供商>/<模型名>。
5.7.2 扫描免费模型
OpenRouter 有一些免费模型。OpenClaw 提供了 models scan 命令来自动发现和测试它们：
# 扫描 OpenRouter 的免费模型目录
openclaw models scan
# 只看元数据，不做实时探测
openclaw models scan --no-probe
# 过滤条件
openclaw models scan --min-params 7 # 至少 70 亿参数
openclaw models scan --max-age-days 180 # 180 天内的模型
# 直接设置为默认模型
openclaw models scan --set-default --set-image --yes
扫描结果按以下标准排序：
- 图像支持
- 工具调用延迟
- 上下文窗口大小
- 参数量
5.8 Ollama：把大模型跑在自己电脑上
前面所有的提供商都是"云端调用"——你的消息要发到远程服务器，模型在别人的机器上运行。Ollama 让你把模型下载到本地，在自己的电脑上跑。这意味着：
- 零网络延迟：不需要等网络往返
- 完全隐私：数据不出你的机器
- 零 API 成本：不需要付费（但需要硬件）
5.8.1 安装 Ollama
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
# Windows
# 从 https://ollama.com/download 下载安装包
5.8.2 下载模型
# 推荐的轻量级模型（4-8GB 显存即可）
ollama pull glm-4.7-flash
# 编程专用
ollama pull qwen2.5-coder:32b
# 推理模型
ollama pull deepseek-r1:32b
# 通用模型
ollama pull llama3.3
# 查看已下载的模型
ollama list
5.8.3 连接 OpenClaw
方式一：通过 Onboarding（推荐）
openclaw onboard
# 选择 Ollama
# 选择 Local（只用本地模型）或 Cloud + Local（同时用云端模型）
方式二：手动配置
# 启用 Ollama（任意值即可，Ollama 不需要真 Key）
export OLLAMA_API_KEY="ollama-local"
{
agents: {
defaults: {
model: { primary: "ollama/glm-4.7-flash" },
},
},
}
配置完成后，OpenClaw 会自动发现本地 Ollama 中已下载的所有模型。你不需要手动在配置里列出每个模型——拉了新模型就能直接用。
# 验证模型列表
openclaw models list
# 切换模型
openclaw models set ollama/llama3.3
5.8.4 远程 Ollama 实例
如果 Ollama 跑在另一台机器上（比如一台装了大显卡的服务器）：
{
models: {
providers: {
ollama: {
baseUrl: "http://192.168.1.100:11434", // 远程地址
apiKey: "ollama-local",
api: "ollama", // 必须设为 ollama，不要用 openai-completions
models: [
{
id: "qwen2.5-coder:32b",
name: "Qwen 2.5 Coder 32B",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 32768,
maxTokens: 8192,
},
],
},
},
},
}
⚠️ 踩坑记录
问题：配置远程 Ollama 后，Agent 有时会把工具调用的 JSON 原样输出为文本，而不是执行工具。
原因：URL 中包含了
/v1（比如http://host:11434/v1），这会让 Ollama 进入 OpenAI 兼容模式，而 OpenAI 兼容模式的工具调用不可靠。解决：去掉 URL 中的
/v1，并显式设置api: "ollama"使用原生 API。
5.8.5 云端模型（Ollama Cloud）
Ollama 也提供云端模型（如 kimi-k2.5:cloud、minimax-m2.5:cloud、glm-5:cloud），不需要本地下载就能用。在 Onboarding 中选择 "Cloud + Local" 模式即可。
{
agents: {
defaults: {
model: {
primary: "ollama/kimi-k2.5:cloud",
fallbacks: ["ollama/glm-4.7-flash"], // 云端挂了用本地兜底
},
},
},
}
5.9 自定义提供商：接入任何 OpenAI 兼容服务
如果你的模型服务暴露了 OpenAI 兼容的 API（LM Studio、vLLM、LiteLLM、自建代理等），你可以用 models.providers 接入。
5.9.1 接入 LM Studio
LM Studio 是一个流行的本地模型运行工具，自带 OpenAI 兼容 API：
{
agents: {
defaults: {
model: { primary: "lmstudio/minimax-m2.5-gs32" },
models: {
"lmstudio/minimax-m2.5-gs32": { alias: "Minimax" },
},
},
},
models: {
providers: {
lmstudio: {
baseUrl: "http://localhost:1234/v1",
apiKey: "LMSTUDIO_KEY", // LM Studio 通常不验证 Key
api: "openai-completions",
models: [
{
id: "minimax-m2.5-gs32",
name: "MiniMax M2.5",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 200000,
maxTokens: 8192,
},
],
},
},
},
}
5.9.2 接入 vLLM
vLLM 是高性能的模型推理服务器，支持多种开源模型：
# 启用 vLLM 自动发现
export VLLM_API_KEY="vllm-local"
{
agents: {
defaults: {
model: { primary: "vllm/your-model-id" },
},
},
}
5.9.3 自定义提供商的关键参数
当你定义自定义提供商时，每个模型可以设置以下参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
reasoning |
false |
是否支持推理/思考模式 |
input |
["text"] |
支持的输入类型（"text", "image"） |
cost |
全 0 | 每千 token 的成本（input/output/cacheRead/cacheWrite） |
contextWindow |
200000 |
上下文窗口大小 |
maxTokens |
8192 |
单次回复最大 token 数 |
💡 提示：虽然这些参数都有默认值，但建议你根据实际模型能力显式设置。错误的
contextWindow会导致 OpenClaw 的上下文管理做出错误判断——比如在一个只有 8K 上下文的模型上尝试发送 100K 的对话历史。
5.10 API Key 轮转：多 Key 负载均衡
如果你有多个 API Key（比如多个团队成员各有一个），OpenClaw 支持在同一提供商内自动轮转 Key，实现负载均衡和更高的请求限额。
5.10.1 配置多 Key
有三种方式配置多个 Key：
# 方式 1：逗号分隔的列表
export ANTHROPIC_API_KEYS="sk-ant-key1,sk-ant-key2,sk-ant-key3"
# 方式 2：编号 Key
export ANTHROPIC_API_KEY_1="sk-ant-key1"
export ANTHROPIC_API_KEY_2="sk-ant-key2"
export ANTHROPIC_API_KEY_3="sk-ant-key3"
# 方式 3：运行时覆盖（最高优先级）
export OPENCLAW_LIVE_ANTHROPIC_KEY="sk-ant-hot-swap"
优先级顺序：
OPENCLAW_LIVE_<PROVIDER>_KEY（运行时热切换，最高优先级）<PROVIDER>_API_KEYS（逗号分隔列表）<PROVIDER>_API_KEY（主 Key）<PROVIDER>_API_KEY_*（编号 Key）
5.10.2 轮转规则
OpenClaw 不是"每次请求换一个 Key"——这样会破坏缓存效率。它的轮转策略更聪明：
- 会话固定：同一个会话内使用同一个 Key，保持提供商缓存热度
- 仅限触发轮转：只有当遇到 429（速率限制）、
rate_limit、quota、resource exhausted等错误时才换 Key - 非速率限制错误不轮转：如果返回的是 400（参数错误）或 500（服务器错误），直接报错，不换 Key
当所有 Key 都失败后，OpenClaw 返回最后一个 Key 的错误信息。
5.11 模型 Fallback：构建弹性模型链
Fallback 是 OpenClaw 模型体系中最实用的功能之一。它让你能设计出"主力 + 备用"的弹性架构。
5.11.1 配置 Fallback 链
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4-6", // 最强但最贵
fallbacks: [
"anthropic/claude-sonnet-4-6", // 同提供商，稍弱但便宜
"openai/gpt-5.4", // 不同提供商，分散风险
"deepseek/deepseek-chat", // 最便宜的兜底
],
},
},
},
}
5.11.2 Fallback 的触发条件
Fallback 只在以下情况触发：
- 认证失败（API Key 无效、OAuth 过期）
- 速率限制（429）
- 超时（看起来像速率限制的超时）
其他错误（如 400 参数错误、模型不存在等）不会触发 Fallback——因为这些错误换模型也解决不了。
5.11.3 Auth Profile 冷却机制
当一个 Key 因为速率限制失败后，OpenClaw 会把它标记为"冷却中"，使用指数退避策略：
第 1 次失败 → 冷却 1 分钟
第 2 次失败 → 冷却 5 分钟
第 3 次失败 → 冷却 25 分钟
第 4 次+ → 冷却 1 小时（上限）
对于"余额不足"这类计费错误，冷却时间更长：
第 1 次失败 → 禁用 5 小时
第 2 次失败 → 禁用 10 小时
...
上限 → 禁用 24 小时
冷却状态保存在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 中，Gateway 重启后仍然有效。
5.11.4 用 CLI 管理 Fallback
# 查看当前 Fallback 配置
openclaw models fallbacks list
# 添加备用模型
openclaw models fallbacks add openai/gpt-5.4
openclaw models fallbacks add deepseek/deepseek-chat
# 移除备用模型
openclaw models fallbacks remove deepseek/deepseek-chat
# 清空所有备用
openclaw models fallbacks clear
5.12 聊天中切换模型
不需要重启 Gateway 就能切换模型——OpenClaw 提供了 /model 命令。
5.12.1 交互式切换
/model # 打开模型选择器
/model list # 列出可用模型（带编号）
/model 3 # 选择编号 3 的模型
/model openai/gpt-5.4 # 直接指定模型
/model status # 查看当前模型和认证状态
在 Discord 中，/model 会打开一个带下拉菜单的交互式选择器。
5.12.2 图像模型分离
有些模型不支持图像输入（比如某些本地模型）。OpenClaw 允许你单独配置一个"图像模型"——当主模型不能处理图片时，自动切换到图像模型：
{
agents: {
defaults: {
model: { primary: "deepseek/deepseek-chat" }, // 主力模型，不支持图像
imageModel: { primary: "google/gemini-3.1-pro-preview" }, // 图像走 Gemini
},
},
}
# 用 CLI 设置图像模型
openclaw models set-image google/gemini-3.1-pro-preview
5.12.3 模型别名
给模型起个简短的名字，方便在 /model 中快速选择：
{
agent: {
model: { primary: "anthropic/claude-sonnet-4-6" },
models: {
"anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
"anthropic/claude-opus-4-6": { alias: "Opus" },
"openai/gpt-5.4": { alias: "GPT" },
"deepseek/deepseek-chat": { alias: "DeepSeek" },
},
},
}
5.13 成本控制实战
模型 API 的费用很容易失控——尤其是启用了 200K 上下文窗口后。这里提供几个实战层面的成本控制策略。
5.13.1 策略一：分级模型架构
不要所有任务都用最贵的模型。设计一个"按任务分模型"的架构：
┌─────────────────────────────────────────────┐
│ 高价值任务 → Claude Opus │
│ 复杂推理、长文写作、代码架构设计 │
├─────────────────────────────────────────────┤
│ 日常对话 → Claude Sonnet │
│ 一般问答、简单代码、翻译 │
├─────────────────────────────────────────────┤
│ 低价值任务 → DeepSeek / 本地模型 │
│ 天气查询、闲聊、格式转换 │
└─────────────────────────────────────────────┘
在 OpenClaw 中实现这个策略：
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-6", // 日常用 Sonnet
fallbacks: ["deepseek/deepseek-chat"], // 挂了用 DeepSeek
},
},
list: [
{
id: "coder",
model: { primary: "anthropic/claude-opus-4-6" }, // 编程 Agent 用 Opus
},
{
id: "casual",
model: { primary: "deepseek/deepseek-chat" }, // 闲聊 Agent 用 DeepSeek
},
],
},
}
5.13.2 策略二：利用 Prompt Caching
如果你用 Anthropic 模型，务必启用 Prompt Caching。在长对话中，系统提示词和工具定义是不变的——缓存命中后，这些"重复内容"就不需要重新处理了。
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": {
params: { cacheRetention: "long" }, // 1 小时缓存
},
"anthropic/claude-sonnet-4-6": {
params: { cacheRetention: "short" }, // 5 分钟缓存
},
},
},
},
}
对于不同 Agent 可以设置不同的缓存策略——高复用的 Agent 用长缓存，低复用的用短缓存或不缓存。
5.13.3 策略三：本地模型兜底
在 Fallback 链的最后放一个本地模型，确保即使所有云端服务都挂了，Agent 仍然能提供基本服务：
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-6",
fallbacks: [
"openai/gpt-5.4",
"ollama/glm-4.7-flash", // 本地兜底，永不宕机
],
},
},
},
}
5.13.4 策略四：用 /fast 控制实时成本
在聊天中，你可以随时用 /fast on 切换到低成本模式——降低推理深度、减少输出冗余。遇到重要问题时再 /fast off 切回高质量模式。
5.14 模型配置诊断
当模型配置出问题时，以下 CLI 命令是排查的第一道防线：
# 查看当前模型配置和认证状态
openclaw models status
# 详细认证状态（包括 OAuth 过期警告）
openclaw models status --json
# 自动化检查（缺失认证返回 1，即将过期返回 2）
openclaw models status --check
# 列出所有可用模型
openclaw models list
# 列出所有模型（包括未配置的）
openclaw models list --all
# 只看本地模型
openclaw models list --local
# 按提供商过滤
openclaw models list --provider anthropic
# 查看模型别名
openclaw models aliases list
⚠️ 踩坑记录
问题：
openclaw models status显示认证正常，但发消息时收到 "No credentials found for profile"。原因：认证是按 Agent 隔离的。新建的 Agent 不会继承主 Agent 的 API Key。
解决：为新 Agent 重新运行 onboarding，或者确认
openclaw models status是在正确的 Agent 上下文中执行的。
本章小结
- OpenClaw 用
provider/model格式引用模型，支持 30+ 内置提供商和任意自定义提供商 - Anthropic 提供 API Key、Setup-Token、CLI 后端三种接入方式，API Key 最推荐
- OpenAI 支持 API Key 和 Codex OAuth 两种方式，WebSocket 传输默认启用
- Gemini 的多模态能力（图像生成、音视频理解、网页搜索）在同价位模型中独一无二
- Ollama 让你把模型跑在本地——零成本、零延迟、完全隐私
- Fallback 链 + Auth Profile 轮转 + 冷却机制构成了完整的弹性架构
- 成本控制的核心思路：按任务分级、利用缓存、本地兜底
下一步
现在你的 Agent 有了"大脑"（模型）和"嘴巴"（通道）。下一章，我们要深入 Agent 的"灵魂"——工作空间。你将学到如何通过 SOUL.md、USER.md、AGENTS.md 等文件塑造 Agent 的性格、行为和知识体系，让它从一个"聪明的机器人"变成一个"有个性的助手"。