04-模型配置指南

04 模型配置指南 04 模型配置指南 Modified June 10 多模型切换与 Fallback 策略 ⠀ ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⠀ 自动故障转移 ⠀ 当主模型不可用时（API 挂了、超时、限流），OpenClaw 内置 model failover 机制，可以自动切换到备用模型。 ⠀ 查看当前故障转移列表： ⠀ Code block Plain Text openclaw models fallbacks list ⠀ 配置示例： ⠀ Code block Plain Text { agents: { defaults: { model: { primary: "anthropic/claude sonnet 4 6", fallbacks: [ "openai/gpt 5.2", "google/gemini 2.5 flash", "ollama/llama3.1", ], }, }, }, } ⠀ Fallback 按顺序尝试：先试第一个备用模型，不行再试第二个，以此类推。最后一个建议放本地模型，确保在所有云服务都挂了的情况下还能用。 ⠀ 故障转移触发条件 ⠀ 会触发 Fallback 的情况：API 返回 5xx 错误、请求超时、429 限流、网络连接失败。 ⠀ 不会触发的情况：4xx 客户端错误（比如 Key 无效）、模型正常返回但内容不符合预期。 ⠀ 手动切换模型 ⠀ Code block Plain Text 切换默认模型 openclaw models set "openai/gpt 5.2" 查看当前模型状态 openclaw models status 列出所有可用模型 openclaw models list Token 限制与成本控制 ⠀ ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⠀ 预算控制 ⠀ 担心 API 费用失控？可以在各模型提供商的控制台设置用量限制： ⠀ • OpenAI：在 platform.openai.com 的 Settings Limits 中设置月度上限 • Anthropic：在 console.anthropic.com 的 Plans & Billing 中查看用量 • Google：在 Google Cloud Console 中设置 API 配额和预算提醒 ⠀ OpenClaw 本身可以通过 CLI 查看模型状态： ⠀ Code block Plain Text openclaw models status 查看当前模型状态 openclaw models list 列出所有可用模型 ⠀ Token 限制 ⠀ 不同模型有不同的上下文窗口和输出限制： ⠀ 模型 上下文窗口 最大输出 GPT 5.2 128K tokens 32,768 tokens Claude Sonnet 4.6 200K tokens 64,000 tokens Gemini 3.1 Pro 1M tokens 65,536 tokens ⠀ OpenClaw 会自动处理上下文窗口限制，你不需要手动管理。如果对话太长，OpenClaw 会自动压缩或截断历史消息。 ⠀ 省钱技巧 ⠀ 1. 简单任务用便宜模型（GPT 5.2 mini、Haiku） 2. 设置合理的 maxTokens，避免模型输出过长 3. 用 OpenRouter 自动选择最便宜的提供商 4. 高频任务考虑用本地模型（Ollama） 5. 开启用量追踪，定期检查费用 自定义模型接入 ⠀ ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⠀ 如果你有自己部署的模型服务，只要兼容 OpenAI API 格式，就能接入 OpenClaw。 ⠀ 兼容 OpenAI API 的服务 ⠀ 很多本地推理框架都兼容 OpenAI API 格式（比如 vLLM、text generation webui、LocalAI 等）。配置方法： ⠀ Code block Plain Text { models: { providers: { custom: { baseUrl: "http://your server:8000/v1", apiKey: "your key if needed", // api: "openai chat", // API 协议类型 models: [ { id: "my custom model", name: "My Custom Model", contextWindow: 32768, maxTokens: 4096, }, ], }, }, }, } ⠀ 然后就可以用了： ⠀ Code block Plain Text openclaw models set "custom/my custom model" ⠀ 多个自定义服务 ⠀ 可以配置多个自定义提供商，只需用不同的名字： ⠀ Code block Plain Text { models: { providers: { "gpu server 1": { baseUrl: "http://192.168.1.100:8000/v1", api: "openai chat", // API 协议类型 }, "gpu server 2": { baseUrl: "http://192.168.1.101:8000/v1", api: "openai chat", }, }, }, } 常见配置问题排查 ⠀ 问题：API Key 无效 ⠀ Code block Plain Text Error: Invalid API key provided ⠀ 确认 Key 没有多余的空格或换行，没有过期或被撤销，用的是正确提供商的 Key。用 openclaw models status 测试。 ⠀ 问题：连接超时 ⠀ Code block Plain Text Error: Request timed out ⠀ 检查网络连接。在中国大陆可能需要代理（export HTTPS PROXY="http://127.0.0.1:7890"）。 ⠀ platform.openai.com console.anthropic.com 多模型切换与 Fallback 策略 ⠀ ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⠀ 自动故障转移 ⠀ 当主模型不可用时（API 挂了、超时、限流），OpenClaw 内置 model failover 机制，可以自动切换到备用模型。 ⠀ 查看当前故障转移列表： ⠀ ⠀ 配置示例： ⠀ ⠀ Fallback 按顺序尝试：先试第一个备用模型，不行再试第二个，以此类推。最后一个建议放本地模型，确保在所有云服务都挂了的情况下还能用。 ⠀ 故障转移触发条件 ⠀ 会触发 Fallback 的情况：API 返回 5xx 错误、请求超时、429 限流、网络连接失败。 ⠀ 不会触发的情况：4xx 客户端错误（比如 Key 无效）、模型正常返回但内容不符合预期。 ⠀ 手动切换模型 ⠀ Token 限制与成本控制 ⠀ ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⠀ 预算控制 ⠀ 担心 API 费用失控？可以在各模型提供商的控制台设置用量限制： ⠀ • OpenAI：在 platform.openai.com 的 Settings Limits 中设置月度上限 platform.openai.com • Anthropic：在 console.anthropic.com 的 Plans & Billing 中查看用量 console.anthropic.com • Google：在 Google Cloud Console 中设置 API 配额和预算提醒 ⠀ OpenClaw 本身可以通过 CLI 查看模型状态： ⠀ ⠀ Token 限制 ⠀ 不同模型有不同的上下文窗口和输出限制： ⠀ 模型 上下文窗口 最大输出 GPT 5.2 128K tokens 32,768 tokens Claude Sonnet 4.6 200K tokens 64,000 tokens Gemini 3.1 Pro 1M tokens 65,536 tokens 模型 模型 上下文窗口 上下文窗口 最大输出 最大输出 GPT 5.2 GPT 5.2 128K tokens 128K tokens 32,768 tokens 32,768 tokens Claude Sonnet 4.6 Claude Sonnet 4.6 200K tokens 200K tokens 64,000 tokens 64,000 tokens Gemini 3.1 Pro Gemini 3.1 Pro 1M tokens 1M tokens 65,536 tokens 65,536 tokens ⠀ OpenClaw 会自动处理上下文窗口限制，你不需要手动管理。如果对话太长，OpenClaw 会自动压缩或截断历史消息。 OpenClaw 会自动处理上下文窗口限制，你不需要手动管理。如果对话太长，OpenClaw 会自动压缩或截断历史消息。 ⠀ 省钱技巧 ⠀ 1. 简单任务用便宜模型（GPT 5.2 mini、Haiku） 2. 设置合理的 maxTokens，避免模型输出过长 3. 用 OpenRouter 自动选择最便宜的提供商 4. 高频任务考虑用本地模型（Ollama） 5. 开启用量追踪，定期检查费用 自定义模型接入 ⠀ ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⠀ 如果你有自己部署的模型服务，只要兼容 OpenAI API 格式，就能接入 OpenClaw。 ⠀ 兼容 OpenAI API 的服务 ⠀ 很多本地推理框架都兼容 OpenAI API 格式（比如 vLLM、text generation webui、LocalAI 等）。配置方法： ⠀ ⠀ 然后就可以用了： ⠀ ⠀ 多个自定义服务 ⠀ 可以配置多个自定义提供商，只需用不同的名字： ⠀ 常见配置问题排查 ⠀ 问题：API Key 无效 ⠀ ⠀ 确认 Key 没有多余的空格或换行，没有过期或被撤销，用的是正确提供商的 Key。用 openclaw models status 测试。 ⠀ 问题：连接超时 ⠀ ⠀ 检查网络连接。在中国大陆可能需要代理（export HTTPS PROXY="http://127.0.0.1:7890"）。 ⠀ 问题：模型不存在 ⠀ ⠀ 确认模型 ID 拼写正确，确认你的账号有权限使用该模型（有些模型需要单独申请）。用 openclaw models list 查看可用模型。 ⠀ 问题：Ollama 连接失败 ⠀ ⠀ 排查步骤： ⠀ ⠀ 问题：本地模型太慢 ⠀ 1. 用更小的模型（7B 比 70B 快很多） 2. 如果有 NVIDIA GPU，确认 Ollama 在用 GPU（ollama ps 查看） 3. 减少 maxTokens 限制输出长度 4. 考虑用 vLLM 替代 Ollama（吞吐量更高） ⠀ 问题：费用超出预期 ⠀ 1. 开启用量追踪（在 /.openclaw/openclaw.json 中配置 usageTracking） 2. 设置每日限额 3. 检查是否有 Agent 在用昂贵的模型做简单任务 4. 把高频任务切换到便宜模型 下一步 ⠀ 模型配好了！去 05. 消息平台集成 连接你的聊天软件！ 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 难度等级：🟡 进阶 • 阅读时间：25 分钟 • 前置知识：已完成快速开始（03 快速开始指南） ⠀ 本篇你将学会： 切换 AI 模型、配置多个提供商、管理 API Key、优化模型参数 ⠀ 小白速通： 如果你在引导向导中已经配好了模型，这篇可以先跳过。等你想换模型或者觉得 AI 回答质量不好时再来看 ⠀ 概述 ⠀ OpenClaw 支持大量 AI 模型提供商（provider，即 AI 模型提供商，比如 OpenAI、Anthropic），从云端大模型到本地开源模型，总有一款适合你。 配置文件位置 ⠀ 在开始之前，先了解配置文件在哪里。OpenClaw 的模型配置存放在： ⠀ ⠀ 配置文件是 JSON5 格式（支持注释和尾逗号），你可以直接编辑，也可以用 openclaw models set 命令修改。两种方式效果一样。 ⠀ ⠀ 模型 CLI 命令速查 ⠀ 命令 说明 openclaw models list 列出所有可用模型 openclaw models status 查看当前模型状态 openclaw models set 设置默认模型 openclaw models set image 设置图像模型 openclaw models aliases list 列出模型别名 openclaw models aliases add <alias <model 添加模型别名 openclaw models aliases remove <alias 删除模型别名 openclaw models fallbacks list 查看故障转移列表 命令 命令 说明 说明 openclaw models list openclaw models list 列出所有可用模型 列出所有可用模型 openclaw models status openclaw models status 查看当前模型状态 查看当前模型状态 openclaw models set openclaw models set 设置默认模型 设置默认模型 openclaw models set image openclaw models set image 设置图像模型 设置图像模型 openclaw models aliases list openclaw models aliases list 列出模型别名 列出模型别名 openclaw models aliases add <alias <model openclaw models aliases add <alias <model 添加模型别名 添加模型别名 openclaw models aliases remove <alias openclaw models aliases remove <alias 删除模型别名 删除模型别名 openclaw models fallbacks list openclaw models fallbacks list 查看故障转移列表 查看故障转移列表 云端模型提供商（按推荐度排序） ⠀ OpenAI ⠀ OpenAI 是目前最主流的模型提供商之一，GPT 系列模型在各种任务上表现优秀。 ⠀ 获取 API Key（访问 AI 服务的密钥，类似于密码）： ⠀ 1. 访问 platform.openai.com platform.openai.com 2. 注册或登录账号 3. 进入 API Keys 页面：Settings API Keys 4. 点击 "Create new secret key" 5. 给 Key 起个名字（比如 "openclaw"），复制保存 ⠀ 注意：API Key 只在创建时显示一次，务必立刻复制保存。丢了只能重新创建。 注意：API Key 只在创建时显示一次，务必立刻复制保存。丢了只能重新创建。 ⠀ 配置方法： ⠀ ⠀ 支持的模型： ⠀ 模型名称 模型 ID 特点 适用场景 GPT 5.4 Pro gpt 5.4 pro 最新旗舰，Codex 定价 复杂推理、创作（v2026.4.14+） GPT 5.4 gpt 5.4 旗舰级，推理能力强 复杂推理、创作 GPT 5.4 mini gpt 5.4 mini 轻量旗舰，带人格切换 日常对话（v2026.4.5+） GPT 5.3 Codex gpt 5.3 codex 编程专用优化 代码生成、调试 GPT 5.2 gpt 5.2 多模态，速度快 日常对话、图片理解 GPT 5.2 mini gpt 5.2 mini 便宜快速 简单任务、高频调用 o3 o3 深度推理 数学、逻辑、科学 o3 mini o3 mini 轻量推理 中等复杂度推理 模型名称 模型名称 模型 ID 模型 ID 特点 特点 适用场景 适用场景 GPT 5.4 Pro GPT 5.4 Pro gpt 5.4 pro gpt 5.4 pro 最新旗舰，Codex 定价 最新旗舰，Codex 定价 复杂推理、创作（v2026.4.14+） 复杂推理、创作（v2026.4.14+） GPT 5.4 GPT 5.4 gpt 5.4 gpt 5.4 旗舰级，推理能力强 旗舰级，推理能力强 复杂推理、创作 复杂推理、创作 GPT 5.4 mini GPT 5.4 mini gpt 5.4 mini gpt 5.4 mini 轻量旗舰，带人格切换 轻量旗舰，带人格切换 日常对话（v2026.4.5+） 日常对话（v2026.4.5+） GPT 5.3 Codex GPT 5.3 Codex gpt 5.3 codex gpt 5.3 codex 编程专用优化 编程专用优化 代码生成、调试 代码生成、调试 GPT 5.2 GPT 5.2 gpt 5.2 gpt 5.2 多模态，速度快 多模态，速度快 日常对话、图片理解 日常对话、图片理解 GPT 5.2 mini GPT 5.2 mini gpt 5.2 mini gpt 5.2 mini 便宜快速 便宜快速 简单任务、高频调用 简单任务、高频调用 o3 o3 o3 o3 深度推理 深度推理 数学、逻辑、科学 数学、逻辑、科学 o3 mini o3 mini o3 mini o3 mini 轻量推理 轻量推理 中等复杂度推理 中等复杂度推理 ⠀ 指定使用 OpenAI 模型： ⠀ ⠀ OpenAI 特有配置项： ⠀ ⠀ • baseUrl：默认不用改，用代理或兼容服务时改成对应地址 • 组织/项目级费用归属请在 OpenAI 控制台设置，而非 OpenClaw 配置文件 Anthropic (Claude) ⠀ Anthropic 的 Claude 系列模型以强大的推理能力和编程能力著称，是很多开发者的首选。 ⠀ 获取 API Key： ⠀ 1. 访问 console.anthropic.com console.anthropic.com 2. 注册账号（需要手机号验证） 3. 进入 API Keys 页面 4. 点击 "Create Key" 5. 复制保存 Key（以 sk ant 开头） ⠀ 配置方法： ⠀ ⠀ 支持的模型： ⠀ 模型名称 模型 ID 特点 适用场景 Claude Opus 4.6 claude opus 4 6 最强推理，深度思考 复杂分析、架构设计 Claude Sonnet 4.6 claude sonnet 4 6 编程最强，性价比高 编程、日常工作 Claude Haiku 4.5 claude haiku 4 5 极速响应，成本低 简单任务、高频调用 模型名称 模型名称 模型 ID 模型 ID 特点 特点 适用场景 适用场景 Claude Opus 4.6 Claude Opus 4.6 claude opus 4 6 claude opus 4 6 最强推理，深度思考 最强推理，深度思考 复杂分析、架构设计 复杂分析、架构设计 Claude Sonnet 4.6 Claude Sonnet 4.6 claude sonnet 4 6 claude sonnet 4 6 编程最强，性价比高 编程最强，性价比高 编程、日常工作 编程、日常工作 Claude Haiku 4.5 Claude Haiku 4.5 claude haiku 4 5 claude haiku 4 5 极速响应，成本低 极速响应，成本低 简单任务、高频调用 简单任务、高频调用 ⠀ 订阅认证（Claude Max 用户）： ⠀ 如果你有 Claude Max 订阅，可以不用 API Key，直接通过 OAuth 认证： ⠀ ⠀ OpenClaw 支持 ANTHROPIC OAUTH TOKEN 环境变量来存储 OAuth 令牌。 ⠀ 这样就能用你的订阅额度，不需要额外付 API 费用。 ⠀ 推荐配置（Anthropic Pro/Max 100/200 + Opus 4.6）： ⠀ OpenClaw 官方推荐使用 Anthropic Pro/Max 订阅搭配 Opus 4.6 模型，获得最佳体验。 ⠀ ⠀ • 支持 OAuth 认证和 API Key 两种方式 • OAuth 认证通过 ANTHROPIC OAUTH TOKEN 环境变量或 openclaw models auth login provider anthropic 配置 Google Gemini ⠀ Google 的 Gemini 系列模型在多模态能力上表现突出，尤其是图片和视频理解。 ⠀ 获取 API Key： ⠀ 1. 访问 aistudio.google.com aistudio.google.com 2. 用 Google 账号登录 3. 点击 "Get API Key" 4. 创建新 Key 或选择已有项目 5. 复制保存 Key（以 AIzaSy 开头） ⠀ 配置方法： ⠀ ⠀ 支持的模型： ⠀ 模型名称 模型 ID 特点 适用场景 Gemini 3.1 Pro gemini 3.1 pro 最新旗舰，多模态最强 图片视频理解、复杂任务 Gemini 2.5 Pro gemini 2.5 pro 深度推理 复杂分析、长文本 Gemini 2.5 Flash gemini 2.5 flash 快速响应 日常对话、简单任务 模型名称 模型名称 模型 ID 模型 ID 特点 特点 适用场景 适用场景 Gemini 3.1 Pro Gemini 3.1 Pro gemini 3.1 pro gemini 3.1 pro 最新旗舰，多模态最强 最新旗舰，多模态最强 图片视频理解、复杂任务 图片视频理解、复杂任务 Gemini 2.5 Pro Gemini 2.5 Pro gemini 2.5 pro gemini 2.5 pro 深度推理 深度推理 复杂分析、长文本 复杂分析、长文本 Gemini 2.5 Flash Gemini 2.5 Flash gemini 2.5 flash gemini 2.5 flash 快速响应 快速响应 日常对话、简单任务 日常对话、简单任务 ⠀ Google 配置项： ⠀ Moonshot / Kimi（中国用户推荐） ⠀ 月之暗面出品，中文理解能力非常强，适合中文写作、长文本理解和通用助手场景。v2026.4.20 起默认模型更新为 kimi k2.6。 ⠀ 获取 API Key：platform.moonshot.cn platform.moonshot.cn ⠀ 配置方法： ⠀ ⠀ 支持的模型： ⠀ 模型名称 模型 ID 特点 Kimi Max kimi max 旗舰模型，中文最强 Kimi Standard kimi standard 均衡之选 Kimi Lite kimi lite 轻量快速 模型名称 模型名称 模型 ID 模型 ID 特点 特点 Kimi Max Kimi Max kimi max kimi max 旗舰模型，中文最强 旗舰模型，中文最强 Kimi Standard Kimi Standard kimi standard kimi standard 均衡之选 均衡之选 Kimi Lite Kimi Lite kimi lite kimi lite 轻量快速 轻量快速 通义千问 (Qwen) ⠀ 阿里巴巴出品，中文能力优秀，性价比极高。开源版本在 Ollama 上也能跑。 ⠀ 认证方式变更（v2026.3.28）： 旧的 qwen portal auth OAuth 认证已废弃。请迁移至 Model Studio API Key 方式： Code block Plain Text openclaw onboard auth choice modelstudio api key 认证方式变更（v2026.3.28）： 旧的 qwen portal auth OAuth 认证已废弃。请迁移至 Model Studio API Key 方式： ⠀ 获取 API Key：dashscope.console.aliyun.com（需要阿里云账号，开通 DashScope 服务） dashscope.console.aliyun.com ⠀ 配置方法： ⠀ ⠀ 支持的模型： ⠀ 模型名称 模型 ID 特点 Qwen Max qwen max 旗舰模型 Qwen Plus qwen plus 均衡之选 Qwen Turbo qwen turbo 快速便宜 Qwen Long qwen long 超长上下文 模型名称 模型名称 模型 ID 模型 ID 特点 特点 Qwen Max Qwen Max qwen max qwen max 旗舰模型 旗舰模型 Qwen Plus Qwen Plus qwen plus qwen plus 均衡之选 均衡之选 Qwen Turbo Qwen Turbo qwen turbo qwen turbo 快速便宜 快速便宜 Qwen Long Qwen Long qwen long qwen long 超长上下文 超长上下文 MistralAI ⠀ 法国 AI 公司，模型轻量高效，v2026.2.22 新增集成，支持聊天、记忆和语音功能。 ⠀ 获取 API Key：console.mistral.ai console.mistral.ai ⠀ 配置方法： ⠀ ⠀ 支持的模型： ⠀ 模型名称 模型 ID 特点 Mistral Large mistral large latest 旗舰模型 Mistral Medium mistral medium latest 均衡之选 Mistral Small mistral small latest 轻量快速 Codestral codestral latest 编程专用 模型名称 模型名称 模型 ID 模型 ID 特点 特点 Mistral Large Mistral Large mistral large latest mistral large latest 旗舰模型 旗舰模型 Mistral Medium Mistral Medium mistral medium latest mistral medium latest 均衡之选 均衡之选 Mistral Small Mistral Small mistral small latest mistral small latest 轻量快速 轻量快速 Codestral Codestral codestral latest codestral latest 编程专用 编程专用 DeepSeek ⠀ 国产深度求索，以极低的价格和不错的推理能力出名。v2026.4.24 起新增 V4 Flash 和 V4 Pro，V4 Flash 成为引导向导的默认推荐选项。 ⠀ 获取 API Key：platform.deepseek.com platform.deepseek.com ⠀ 配置方法： ⠀ ⠀ 支持的模型： ⠀ 模型名称 模型 ID 特点 DeepSeek V4 Flash deepseek v4 flash 快速推理，默认引导选项（v2026.4.24+） DeepSeek V4 Pro deepseek v4 pro 旗舰推理（v2026.4.24+） DeepSeek V3 deepseek chat 通用对话 DeepSeek R1 deepseek reasoner 深度推理 模型名称 模型名称 模型 ID 模型 ID 特点 特点 DeepSeek V4 Flash DeepSeek V4 Flash deepseek v4 flash deepse