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

⠀

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. 消息平台集成连接你的聊天软件！

概述

配置文件位置

模型 CLI 命令速查

云端模型提供商（按推荐度排序）

OpenAI

Anthropic (Claude)

Google Gemini

Moonshot / Kimi（中国用户推荐）

通义千问 (Qwen)

MistralAI

DeepSeek

xAI (Grok)

Cohere

腾讯云 / Tencent Cloud（v2026.4.22+）

Fireworks AI（v2026.4.5+）

StepFun / 阶跃星辰（v2026.4.5+）

企业级云平台

Azure OpenAI

AWS Bedrock

Google Vertex AI

本地模型（隐私优先）

Ollama（强烈推荐）

vLLM

LM Studio

模型路由与聚合

OpenRouter（一个 Key 用所有模型）

媒体理解与外部 CLI 回退

API Key 安全管理

绝对不要做的事

推荐的做法

Key 轮换

模型选择策略

按场景选模型

按 Agent 角色分配模型

模型参数调优

核心参数详解

按场景的推荐参数

多模型切换与 Fallback 策略

自动故障转移

故障转移触发条件

手动切换模型

Token 限制与成本控制

预算控制

Token 限制

省钱技巧

自定义模型接入

兼容 OpenAI API 的服务

多个自定义服务

常见配置问题排查

问题：API Key 无效

问题：连接超时

问题：模型不存在

问题：Ollama 连接失败

问题：本地模型太慢

问题：费用超出预期

下一步