04. AI 模型配置指南
课程信息
⠀
-
作者:老金
-
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 的模型配置存放在:
⠀
# 查看当前模型状态
openclaw models status
# 配置文件默认路径
~/.openclaw/openclaw.json
⠀
配置文件是 JSON5 格式(支持注释和尾逗号),你可以直接编辑,也可以用 openclaw models set 命令修改。两种方式效果一样。
⠀
{
agents: {
defaults: {
model: "anthropic/claude-sonnet-4-6",
},
},
}
⠀
模型 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
查看故障转移列表
云端模型提供商(按推荐度排序)
⠀
OpenAI
⠀
OpenAI 是目前最主流的模型提供商之一,GPT 系列模型在各种任务上表现优秀。
⠀
获取 API Key(访问 AI 服务的密钥,类似于密码):
⠀
-
访问 platform.openai.com
-
注册或登录账号
-
进入 API Keys 页面:Settings > API Keys
-
点击 "Create new secret key"
-
给 Key 起个名字(比如 "openclaw"),复制保存
⠀
注意:API Key 只在创建时显示一次,务必立刻复制保存。丢了只能重新创建。
⠀
配置方法:
⠀
# 方法一:用环境变量(推荐)
export OPENAI_API_KEY="sk-proj-xxxxx"
# 方法二:直接编辑配置文件
# 编辑 ~/.openclaw/openclaw.json
⠀
支持的模型:
⠀
模型名称
模型 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
轻量推理
中等复杂度推理
⠀
指定使用 OpenAI 模型:
⠀
openclaw models set "openai/gpt-5.2"
⠀
OpenAI 特有配置项:
⠀
{
// 在 openclaw.json 中可以配置 OpenAI 相关选项
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
// apiKey 推荐通过环境变量 OPENAI_API_KEY 设置
// 以下是 ModelProviderConfig 支持的可选字段:
// auth: "bearer", // 认证方式
// api: "openai-responses", // API 协议类型
// headers: {}, // 自定义请求头
},
},
},
}
⠀
-
baseUrl:默认不用改,用代理或兼容服务时改成对应地址
-
组织/项目级费用归属请在 OpenAI 控制台设置,而非 OpenClaw 配置文件
Anthropic (Claude)
⠀
Anthropic 的 Claude 系列模型以强大的推理能力和编程能力著称,是很多开发者的首选。
⠀
获取 API Key:
⠀
-
访问 console.anthropic.com
-
注册账号(需要手机号验证)
-
进入 API Keys 页面
-
点击 "Create Key"
-
复制保存 Key(以 sk-ant- 开头)
⠀
配置方法:
⠀
# 环境变量
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
⠀
支持的模型:
⠀
模型名称
模型 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
极速响应,成本低
简单任务、高频调用
⠀
订阅认证(Claude Max 用户):
⠀
如果你有 Claude Max 订阅,可以不用 API Key,直接通过 OAuth 认证:
⠀
# 通过 OAuth 认证(订阅用户)
openclaw models auth login --provider anthropic
⠀
OpenClaw 支持 ANTHROPIC_OAUTH_TOKEN 环境变量来存储 OAuth 令牌。
⠀
这样就能用你的订阅额度,不需要额外付 API 费用。
⠀
推荐配置(Anthropic Pro/Max 100/200 + Opus 4.6):
⠀
OpenClaw 官方推荐使用 Anthropic Pro/Max 订阅搭配 Opus 4.6 模型,获得最佳体验。
⠀
{
agents: {
defaults: {
model: "anthropic/claude-opus-4-6",
},
},
}
⠀
-
支持 OAuth 认证和 API Key 两种方式
-
OAuth 认证通过 ANTHROPIC_OAUTH_TOKEN 环境变量或 openclaw models auth login --provider anthropic 配置
Google Gemini
⠀
Google 的 Gemini 系列模型在多模态能力上表现突出,尤其是图片和视频理解。
⠀
获取 API Key:
⠀
-
访问 aistudio.google.com
-
用 Google 账号登录
-
点击 "Get API Key"
-
创建新 Key 或选择已有项目
-
复制保存 Key(以 AIzaSy 开头)
⠀
配置方法:
⠀
# 环境变量
export GEMINI_API_KEY="AIzaSy-xxxxx"
⠀
支持的模型:
⠀
模型名称
模型 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
快速响应
日常对话、简单任务
⠀
Google 配置项:
⠀
{
agents: {
defaults: {
model: "google/gemini-3.1-pro",
},
},
}
Moonshot / Kimi(中国用户推荐)
⠀
月之暗面出品,中文理解能力非常强,适合中文写作、长文本理解和通用助手场景。v2026.4.20 起默认模型更新为 kimi-k2.6。
⠀
获取 API Key:platform.moonshot.cn
⠀
配置方法:
⠀
# 环境变量:Moonshot 未列入下文「常见内置环境变量」表;请以 OpenClaw 官方文档及当前安装版本为准,或通过 OpenAI 兼容接口 / OpenRouter 接入
⠀
支持的模型:
⠀
模型名称
模型 ID
特点
Kimi-Max
kimi-max
旗舰模型,中文最强
Kimi-Standard
kimi-standard
均衡之选
Kimi-Lite
kimi-lite
轻量快速
通义千问 (Qwen)
⠀
阿里巴巴出品,中文能力优秀,性价比极高。开源版本在 Ollama 上也能跑。
⠀
认证方式变更(v2026.3.28): 旧的 qwen-portal-auth OAuth 认证已废弃。请迁移至 Model Studio API Key 方式:
openclaw onboard --auth-choice modelstudio-api-key
⠀
获取 API Key:dashscope.console.aliyun.com(需要阿里云账号,开通 DashScope 服务)
⠀
配置方法:
⠀
# 环境变量:Qwen 未列入下文「常见内置环境变量」表;请以 OpenClaw 官方文档及当前安装版本为准,或通过 OpenAI 兼容接口 / OpenRouter 接入
⠀
支持的模型:
⠀
模型名称
模型 ID
特点
Qwen-Max
qwen-max
旗舰模型
Qwen-Plus
qwen-plus
均衡之选
Qwen-Turbo
qwen-turbo
快速便宜
Qwen-Long
qwen-long
超长上下文
MistralAI
⠀
法国 AI 公司,模型轻量高效,v2026.2.22 新增集成,支持聊天、记忆和语音功能。
⠀
获取 API Key:console.mistral.ai
⠀
配置方法:
⠀
# 环境变量:Mistral 未列入下文「常见内置环境变量」表;请以 OpenClaw 官方文档及当前安装版本为准,或通过 OpenRouter 接入
⠀
支持的模型:
⠀
模型名称
模型 ID
特点
Mistral Large
mistral-large-latest
旗舰模型
Mistral Medium
mistral-medium-latest
均衡之选
Mistral Small
mistral-small-latest
轻量快速
Codestral
codestral-latest
编程专用
DeepSeek
⠀
国产深度求索,以极低的价格和不错的推理能力出名。v2026.4.24 起新增 V4 Flash 和 V4 Pro,V4 Flash 成为引导向导的默认推荐选项。
⠀
获取 API Key:platform.deepseek.com
⠀
配置方法:
⠀
# 环境变量:DeepSeek 未列入下文「常见内置环境变量」表;请以 OpenClaw 官方文档及当前安装版本为准,或通过 OpenAI 兼容接口 / OpenRouter 接入
⠀
支持的模型:
⠀
模型名称
模型 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
深度推理
xAI (Grok)
⠀
Elon Musk 的 AI 公司,Grok 模型风格独特。v2026.4.22 起新增图像生成(grok-imagine-image)、TTS(6 种语音)和 STT 支持,输出格式支持 MP3/WAV/PCM/G.711。
⠀
v2026.5.22 更新:OpenClaw 已支持 xAI device-code OAuth login,远程服务器或无浏览器环境不必强依赖 localhost callback。Grok web_search 会复用 xAI OAuth auth profile,并把 active-agent auth 线程传入 web search。配置时优先使用当前 openclaw models auth 帮助输出。
⠀
配置方法:
⠀
# 环境变量
export ZAI_API_KEY="xai-xxxxx"
Cohere
⠀
专注企业级 AI,RAG(检索增强生成)能力强。
⠀
配置方法:
⠀
# 环境变量:Cohere 未列入下文「常见内置环境变量」表;请以 OpenClaw 官方文档及当前安装版本为准,或通过 OpenRouter 接入
腾讯云 / Tencent Cloud(v2026.4.22+)
⠀
v2026.4.22 起新增腾讯云捆绑提供商插件,支持 TokenHub 引导配置和 hy3-preview 模型,带分层定价元数据。适合已有腾讯云基础设施的团队。
⠀
配置方法:
⠀
# 通过 TokenHub 引导配置
openclaw onboard
# 在引导向导中选择 Tencent Cloud
⠀
支持的模型:
⠀
模型名称
模型 ID
特点
Hy3 Preview
hy3-preview
腾讯混元旗舰预览版
⠀
具体模型列表可能随版本更新,以 openclaw models list 输出为准。
⠀
v2026.5.27 模型目录迁移提示:模型目录会持续 pruning retired models,并通过 doctor migration 提示过期配置。升级后如果旧模型别名突然不可用,先运行 openclaw doctor 和 openclaw models list,把 retired model 迁移到当前目录里仍存在的等价模型,不要只改显示名。v2026.5.27 还补充了 OpenAI-compatible embedding provider、DeepInfra 全量 credential-aware model catalog、Pixverse 视频生成 / region 选择、VLLM thinking params、Claude CLI OAuth overlays 和 bare direct Anthropic model id 支持。
Fireworks AI(v2026.4.5+)
⠀
v2026.4.5 起新增捆绑提供商。Fireworks AI 专注于高性能模型推理,支持多种开源模型的托管部署,推理速度快。
⠀
获取 API Key:fireworks.ai
⠀
配置方法:
⠀
# 环境变量:请以 OpenClaw 官方文档及当前安装版本为准
⠀
Fireworks AI 支持 Llama、Mixtral 等主流开源模型的托管推理,具体模型列表以 openclaw models list 为准。
StepFun / 阶跃星辰(v2026.4.5+)
⠀
v2026.4.5 起新增捆绑提供商。阶跃星辰是国产 AI 公司,Step 系列模型在中文场景有不错的表现。
⠀
获取 API Key:platform.stepfun.com
⠀
配置方法:
⠀
# 环境变量:请以 OpenClaw 官方文档及当前安装版本为准
⠀
具体模型列表以 openclaw models list 为准。
企业级云平台
⠀
⏭️ 小白可跳过 — 这部分面向高级用户,新手用默认配置就够了
⠀
如果你在企业环境中使用,可能需要通过云平台的托管服务来访问模型,而不是直接用模型提供商的 API。
⠀
Azure OpenAI
⠀
微软 Azure 托管的 OpenAI 模型,适合已有 Azure 订阅的企业用户。数据不出你的 Azure 区域,合规性更好。
⠀
前置条件: 有 Azure 订阅,已创建 Azure OpenAI 资源并部署模型。
⠀
配置方法:
⠀
{
models: {
providers: {
"azure-openai": {
baseUrl: "https://your-resource.openai.azure.com/openai/deployments/gpt-5.2",
// apiKey 推荐通过环境变量设置
// api: "openai-chat", // API 协议类型
},
},
},
}
⠀
注意:baseUrl 中的最后一段是你在 Azure 中部署时起的 deployment 名字,不是 OpenAI 原始的模型名。
AWS Bedrock
⠀
亚马逊 AWS 的托管 AI 服务,支持多家模型提供商。适合已有 AWS 基础设施的团队。
⠀
前置条件: 有 AWS 账号,已在 Bedrock 控制台开通模型访问权限。
⠀
配置方法:
⠀
{
models: {
providers: {
"aws-bedrock": {
baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
// 认证通过 AWS 环境变量或 IAM Role
},
},
},
}
⠀
也可以用 AWS 环境变量(AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_DEFAULT_REGION)。在 EC2 实例上直接用 IAM Role 即可。baseUrl 中的区域按你的实际部署区域修改。Bedrock 支持 Claude、Llama、Mistral 等系列模型。
Google Vertex AI
⠀
Google Cloud 的企业级 AI 平台,适合已有 GCP 基础设施的团队。
⠀
前置条件: 有 Google Cloud 项目,已启用 Vertex AI API。
⠀
配置方法:
⠀
{
models: {
providers: {
"vertex-ai": {
baseUrl: "https://us-central1-aiplatform.googleapis.com/v1/projects/your-project-id",
// 认证通过 gcloud 凭证或环境变量
},
},
},
}
⠀
也可以用 gcloud auth application-default login 认证,OpenClaw 会自动使用你的 gcloud 凭证。
本地模型(隐私优先)
⠀
本地模型的最大优势:数据完全不出你的电脑。适合处理敏感信息、离线使用、或者单纯不想付 API 费用的场景。
⠀
Ollama(强烈推荐)
⠀
Ollama 是目前最简单的本地模型运行方案,一行命令就能跑起来。
⠀
安装 Ollama:
⠀
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
# Windows:从 https://ollama.com/download 下载安装包
⠀
下载模型:
⠀
# 通用对话模型
ollama pull llama3.1 # Meta Llama 3.1,综合能力强
ollama pull llama3.1:70b # 70B 参数版本,更强但需要更多显存
ollama pull qwen2.5 # 通义千问,中文最强开源模型
# 编程专用模型
ollama pull codellama # Meta 编程模型
ollama pull deepseek-coder-v2 # DeepSeek 编程模型
# 轻量模型(低配电脑也能跑)
ollama pull phi3 # 微软 Phi-3,3.8B 参数
ollama pull gemma2:2b # Google Gemma 2,2B 参数
ollama pull mistral # Mistral 7B
⠀
配置 OpenClaw 使用 Ollama:
⠀
openclaw models set "ollama/llama3.1"
⠀
完整配置示例:
⠀
{
agents: {
defaults: {
model: "ollama/llama3.1",
},
},
models: {
providers: {
ollama: {
baseUrl: "http://127.0.0.1:11434",
},
},
},
}
⠀
本地模型推理可能比较慢,如果超时可以在 Ollama 侧调整。Ollama 本身支持 OLLAMA_KEEP_ALIVE 环境变量控制模型在内存中保持多久。
⠀
Ollama 硬件要求参考:
⠀
模型大小
最低内存
推荐显存
示例模型
1-3B
4GB RAM
不需要 GPU
phi3, gemma2:2b
7-8B
8GB RAM
6GB VRAM
llama3.1, mistral
13-14B
16GB RAM
10GB VRAM
llama3.1:13b
32-34B
32GB RAM
24GB VRAM
qwen2.5:32b
70B
64GB RAM
48GB VRAM
llama3.1:70b
⠀
没有独立显卡也能跑,Ollama 会自动用 CPU 推理,只是速度慢一些。
⠀
Ollama 远程访问:
⠀
如果 Ollama 跑在另一台机器上(比如 GPU 服务器),在服务器上设置 OLLAMA_HOST="0.0.0.0:11434",然后在 OpenClaw 配置文件 ~/.openclaw/openclaw.json 中设置远程地址:
⠀
{
models: {
providers: {
ollama: {
baseUrl: "http://192.168.1.100:11434",
},
},
},
}
vLLM
⠀
高性能本地推理引擎,适合有 GPU 的用户,吞吐量比 Ollama 高很多。
⠀
安装和启动:
⠀
# 安装 vLLM
pip install vllm
# 启动 vLLM 服务(以 Llama 3.1 为例)
python -m vllm.entrypoints.openai.api_server \
--model meta-llama/Llama-3.1-8B-Instruct \
--port 8000
⠀
配置 OpenClaw:
⠀
// ~/.openclaw/openclaw.json
{
models: {
providers: {
vllm: {
baseUrl: "http://127.0.0.1:8000",
},
},
},
}
LM Studio
⠀
图形界面的本地模型运行工具,适合不喜欢命令行的用户。
⠀
-
从 lmstudio.ai 下载安装
-
在 LM Studio 中搜索并下载模型
-
启动本地服务器(Local Server 标签页)
-
配置 OpenClaw(编辑 ~/.openclaw/openclaw.json):
⠀
{
models: {
providers: {
lmstudio: {
baseUrl: "http://127.0.0.1:1234/v1",
},
},
},
}
⠀
LM Studio 的 API 兼容 OpenAI 格式,所以也可以用 OpenAI 提供商配置,只需改 baseUrl。
模型路由与聚合
⠀
OpenRouter(一个 Key 用所有模型)
⠀
OpenRouter 是模型路由器,一个 API Key 就能访问 OpenAI、Anthropic、Google、Meta 等所有主流模型。适合想要灵活切换模型、或者不想管理多个 API Key 的用户。
⠀
v2026.5.22 更新:OpenRouter 会尊重 provider-level params.provider 路由策略,模型级和 agent 级参数可以覆盖默认值。团队里如果需要固定地区、价格或供应商偏好,不要只写模型名,还要把 provider routing policy 记录进配置变更说明。
⠀
获取 API Key:
⠀
-
访问 openrouter.ai
-
注册账号
-
在 Keys 页面创建 API Key
⠀
配置方法:
⠀
# 环境变量
export OPENROUTER_API_KEY="sk-or-xxxxx"
⠀
通过 OpenRouter 使用特定模型:
⠀
# 使用 OpenRouter 的 Claude Sonnet
openclaw models set "openrouter/anthropic/claude-sonnet-4-6"
# 使用 OpenRouter 的 GPT-5.2
openclaw models set "openrouter/openai/gpt-5.2"
# 使用 OpenRouter 的 Llama
openclaw models set "openrouter/meta-llama/llama-3.1-70b-instruct"
⠀
OpenRouter 的优势: 一个 Key 访问所有模型、自动选择最便宜的提供商、内置负载均衡和故障转移、统一计费。
媒体理解与外部 CLI 回退
⠀
v2026.5.22 后,媒体理解不再自动探测 Gemini CLI;Antigravity CLI 仅作为低优先级 image / video fallback,优先级低于已配置的 provider API。v2026.5.26 / v2026.5.27 又把图片处理迁到 Rastermill,并补充 HEIC / HEIF 归一化、Pixverse 视频生成和 OpenAI-compatible embedding provider。教程里的建议顺序是:
⠀
-
先配置正式 provider API。
-
再确认图片、视频、TTS、STT 的 provider credentials。
-
最后才考虑 CLI fallback。
⠀
如果媒体任务失败,先查当前 provider 的凭证、超时和模型能力,不要直接让读者安装一堆外部 CLI。
⠀
API Key 安全管理
⠀
API Key 就是钱,泄露了别人就能用你的额度。这里是安全管理的最佳实践。
⠀
绝对不要做的事
⠀
-
把 Key 硬编码在代码里
-
把含有 Key 的配置文件提交到 Git
-
在公开场合(截图、论坛、聊天记录)分享 Key
⠀
推荐的做法
⠀
方法一:用环境变量(最推荐)
⠀
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export OPENAI_API_KEY="sk-proj-xxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
# 然后 source 一下
source ~/.bashrc
⠀
OpenClaw 会自动读取这些环境变量,不需要在配置文件中写 Key。
⠀
以下为 OpenClaw 常见内置环境变量(与多数发行版公开说明一致;若与你本机版本或官方文档不一致,以你安装的版本及官方文档为准):
⠀
环境变量
提供商
OPENAI_API_KEY
OpenAI
ANTHROPIC_API_KEY
Anthropic
ANTHROPIC_OAUTH_TOKEN
Anthropic(OAuth 认证)
GEMINI_API_KEY
Google Gemini
ZAI_API_KEY
xAI (Grok)
OPENROUTER_API_KEY
OpenRouter
AI_GATEWAY_API_KEY
AI Gateway
MINIMAX_API_KEY
MiniMax
ELEVENLABS_API_KEY
ElevenLabs
⠀
方法二:用 .env 文件
⠀
# 在项目根目录创建 .env 文件
OPENAI_API_KEY=sk-proj-xxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxx
# 务必把 .env 加入 .gitignore
echo ".env" >> .gitignore
⠀
方法三:用系统密钥管理器
⠀
macOS 用 Keychain,Linux 用 secret-tool,Windows 用凭据管理器。具体命令参考各系统文档。
⠀
Key 轮换
⠀
定期轮换 API Key 是好习惯。流程:在提供商控制台创建新 Key -> 更新环境变量或配置文件 -> 用 openclaw models status 确认新 Key 工作正常 -> 删除旧 Key。
模型选择策略
⠀
💡 不知道选什么模型? 看这一节就够了,帮你根据预算和需求选最合适的
⠀
不同场景用不同模型,既省钱又高效。
⠀
按场景选模型
⠀
下表中的"token"(AI 处理文本的基本单位,大约 1 个汉字 = 2 个 token)是 AI 计费的常用单位。
⠀
场景
推荐模型
理由
大约成本
日常闲聊
GPT-5.2-mini / Haiku 4.5
便宜快速,够用
~$0.15/百万 token
复杂推理
Claude Opus 4.6 / o3
最强推理能力
~$15/百万 token
编程辅助
Claude Sonnet 4.6 / Codex
编程能力最强
~$3/百万 token
中文场景
Qwen-Max / Kimi-Max / DeepSeek-V4
中文理解优化
按各家定价
隐私优先
Ollama + Llama3.1
数据不出本地
免费(电费除外)
多模态
Gemini 3.1 Pro / GPT-5.2
图片视频理解
~$2.5/百万 token
预算有限
OpenRouter / DeepSeek-V4 Flash
按需选最便宜的
~$0.1-1/百万 token
超长文本
Gemini 2.5 Pro / Qwen-Long
百万级上下文
按各家定价
⠀
按 Agent 角色分配模型
⠀
OpenClaw 支持给不同的 Agent 分配不同的模型:
⠀
{
// 默认模型
agents: {
defaults: {
model: "anthropic/claude-sonnet-4-6",
},
},
// 可通过模型别名为不同场景快速切换
// openclaw models aliases add code-review "anthropic/claude-opus-4-6"
// openclaw models aliases add translator "openai/gpt-5.2"
}
⠀
简单任务用便宜模型省钱,关键任务用强模型保质量,中文任务用中文优化模型效果更好,内部任务用本地模型保隐私。
模型参数调优
⠀
⏭️ 小白可跳过 — 这部分面向高级用户,新手用默认配置就够了
⠀
模型的输出风格可以通过参数来调整。不同的模型提供商支持不同的参数,OpenClaw 会将这些参数透传给模型 API。
⠀
核心参数详解
⠀
常见的模型参数(具体支持情况取决于提供商):
⠀
-
temperature(温度):控制输出随机性,越高越有创意
-
topP(核采样):控制候选词范围
-
maxTokens(最大输出长度):限制单次回复长度
⠀
这些参数通常在调用 API 时传入,而非在 OpenClaw 配置文件中全局设置。OpenClaw 的配置文件主要管理模型选择和提供商连接。
⠀
temperature(温度,控制 AI 回答随机性的参数,越高越有创意,越低越稳定):
⠀
控制输出的随机性,范围 0.0 - 2.0。
⠀
值
效果
适用场景
0.0
完全确定性,每次输出一样
代码生成、数据提取
0.3
低随机性,比较稳定
客服回复、翻译
0.7
中等随机性(默认)
日常对话、写作
1.0
高随机性,更有创意
创意写作、头脑风暴
1.5+
非常随机,可能不连贯
一般不推荐
⠀
topP(核采样):
⠀
控制候选词的范围,范围 0.0 - 1.0。
⠀
-
1.0:考虑所有候选词(默认)
-
0.9:只考虑概率最高的 90% 候选词
-
0.5:只考虑概率最高的 50% 候选词
⠀
一般建议:调 temperature 或 topP 其中一个就行,不要同时调两个。
⠀
maxTokens(最大输出长度):
⠀
限制模型单次回复的最大 token 数。不同模型的最大输出限制不同:
-
GPT-5.2:最大 32,768 tokens
-
Claude Sonnet 4.6:最大 64,000 tokens
-
Gemini 2.5 Pro:最大 65,536 tokens
⠀
frequencyPenalty(频率惩罚):
⠀
减少模型重复已经说过的内容,范围 -2.0 到 2.0。
⠀
-
0.0:不惩罚(默认)
-
0.5:轻微减少重复
-
1.0:明显减少重复
⠀
presencePenalty(存在惩罚):
⠀
鼓励模型谈论新话题,范围 -2.0 到 2.0。
⠀
-
0.0:不惩罚(默认)
-
0.5:轻微鼓励新话题
-
1.0:明显鼓励新话题
⠀
按场景的推荐参数
⠀
场景
temperature
topP
maxTokens
其他
客服机器人
0.3
0.9
2048
创意写作
0.9
0.95
4096
presencePenalty: 0.3
代码生成
0.0
1.0
8192
数据提取
0.0
1.0
1024
多模型切换与 Fallback 策略
⠀
⏭️ 小白可跳过 — 这部分面向高级用户,新手用默认配置就够了
⠀
自动故障转移
⠀
当主模型不可用时(API 挂了、超时、限流),OpenClaw 内置 model-failover 机制,可以自动切换到备用模型。
⠀
查看当前故障转移列表:
⠀
openclaw models fallbacks list
⠀
配置示例:
⠀
{
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 无效)、模型正常返回但内容不符合预期。
⠀
手动切换模型
⠀
# 切换默认模型
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 查看模型状态:
⠀
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 会自动压缩或截断历史消息。
⠀
省钱技巧
⠀
-
简单任务用便宜模型(GPT-5.2-mini、Haiku)
-
设置合理的 maxTokens,避免模型输出过长
-
用 OpenRouter 自动选择最便宜的提供商
-
高频任务考虑用本地模型(Ollama)
-
开启用量追踪,定期检查费用
自定义模型接入
⠀
⏭️ 小白可跳过 — 这部分面向高级用户,新手用默认配置就够了
⠀
如果你有自己部署的模型服务,只要兼容 OpenAI API 格式,就能接入 OpenClaw。
⠀
兼容 OpenAI API 的服务
⠀
很多本地推理框架都兼容 OpenAI API 格式(比如 vLLM、text-generation-webui、LocalAI 等)。配置方法:
⠀
{
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,
},
],
},
},
},
}
⠀
然后就可以用了:
⠀
openclaw models set "custom/my-custom-model"
⠀
多个自定义服务
⠀
可以配置多个自定义提供商,只需用不同的名字:
⠀
{
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 无效
⠀
Error: Invalid API key provided
⠀
确认 Key 没有多余的空格或换行,没有过期或被撤销,用的是正确提供商的 Key。用 openclaw models status 测试。
⠀
问题:连接超时
⠀
Error: Request timed out
⠀
检查网络连接。在中国大陆可能需要代理(export HTTPS_PROXY="http://127.0.0.1:7890")。
⠀
问题:模型不存在
⠀
Error: Model not found
⠀
确认模型 ID 拼写正确,确认你的账号有权限使用该模型(有些模型需要单独申请)。用 openclaw models list 查看可用模型。
⠀
问题:Ollama 连接失败
⠀
Error: Connection refused to http://127.0.0.1:11434
⠀
排查步骤:
⠀
# 1. 确认 Ollama 正在运行
ollama list
# 2. 如果没运行,启动它
ollama serve
# 3. 如果是远程 Ollama,确认防火墙允许 11434 端口
⠀
问题:本地模型太慢
⠀
-
用更小的模型(7B 比 70B 快很多)
-
如果有 NVIDIA GPU,确认 Ollama 在用 GPU(ollama ps 查看)
-
减少 maxTokens 限制输出长度
-
考虑用 vLLM 替代 Ollama(吞吐量更高)
⠀
问题:费用超出预期
⠀
-
开启用量追踪(在 ~/.openclaw/openclaw.json 中配置 usageTracking)
-
设置每日限额
-
检查是否有 Agent 在用昂贵的模型做简单任务
-
把高频任务切换到便宜模型
下一步
⠀
模型配好了!去 05. 消息平台集成 连接你的聊天软件!