System Vault

Appearance

04. AI 模型配置指南 ​

概述 ​

OpenClaw 支持大量 AI 模型提供商（provider，即 AI 模型提供商，比如 OpenAI、Anthropic），从云端大模型到本地开源模型，总有一款适合你。

2026-04 差量更新（v2026.3.28 → v2026.4.24）

  • 提供商列表变化较快，最可靠的当前视图请以 openclaw models list 和官方 CLI 文档为准
  • 这一章保留”怎么选、怎么配、怎么做 fallback”的结构，不再把提供商数量写成长期固定数字
  • v2026.3.28：Qwen OAuth（qwen-portal-auth）已废弃，需迁移至 openclaw onboard --auth-choice modelstudio-api-key
  • v2026.4.5：新增 Fireworks AI、StepFun 捆绑提供商
  • v2026.4.14：GPT-5.4 Pro 前向兼容
  • v2026.4.22：xAI 新增图像生成、TTS、STT 支持；新增腾讯云（Tencent Cloud）提供商及 hy3-preview 模型
  • v2026.4.24：DeepSeek V4 Flash / V4 Pro 入目录，V4 Flash 成为默认引导选项

教程版本基线

稳定版参考 v2026.4.24；另有预发布线见 Releases。约定全文见 00-阅读指南。

配置模型最简单的方式：

bash
openclaw onboard

引导向导会帮你配置。但如果你想手动配置、切换模型、或者做更精细的调优，这篇指南就是为你准备的。

本章内容比较多，先给你一个目录：

  • 云端模型提供商完整配置（OpenAI、Anthropic、Google、国产模型等）
  • 企业级云平台（Azure OpenAI、AWS Bedrock、Google Vertex AI）
  • 本地模型部署（Ollama、vLLM、LM Studio）
  • 模型路由与聚合（OpenRouter）
  • API Key 安全管理
  • 模型选择策略（不同场景用什么模型）
  • 模型参数调优（temperature、top_p 等）
  • 多模型切换与 Fallback 策略
  • Token 限制与成本控制
  • 自定义模型接入（兼容 OpenAI API 的任意服务）
  • 常见配置问题排查

配置文件位置 ​

在开始之前，先了解配置文件在哪里。OpenClaw 的模型配置存放在：

bash
# 查看当前模型状态
openclaw models status

# 配置文件默认路径
~/.openclaw/openclaw.json

配置文件是 JSON5 格式（支持注释和尾逗号），你可以直接编辑，也可以用 openclaw models set 命令修改。两种方式效果一样。

json5
{
  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 服务的密钥，类似于密码）：

  1. 访问 platform.openai.com
  2. 注册或登录账号
  3. 进入 API Keys 页面：Settings > API Keys
  4. 点击 "Create new secret key"
  5. 给 Key 起个名字（比如 "openclaw"），复制保存

注意：API Key 只在创建时显示一次，务必立刻复制保存。丢了只能重新创建。

配置方法：

bash
# 方法一：用环境变量（推荐）
export OPENAI_API_KEY="sk-proj-xxxxx"

# 方法二：直接编辑配置文件
# 编辑 ~/.openclaw/openclaw.json

支持的模型：

模型名称模型 ID特点适用场景
GPT-5.4 Progpt-5.4-pro最新旗舰，Codex 定价复杂推理、创作（v2026.4.14+）
GPT-5.4gpt-5.4旗舰级，推理能力强复杂推理、创作
GPT-5.4-minigpt-5.4-mini轻量旗舰，带人格切换日常对话（v2026.4.5+）
GPT-5.3 Codexgpt-5.3-codex编程专用优化代码生成、调试
GPT-5.2gpt-5.2多模态，速度快日常对话、图片理解
GPT-5.2-minigpt-5.2-mini便宜快速简单任务、高频调用
o3o3深度推理数学、逻辑、科学
o3-minio3-mini轻量推理中等复杂度推理

指定使用 OpenAI 模型：

bash
openclaw models set "openai/gpt-5.2"

OpenAI 特有配置项：

json5
{
  // 在 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：

  1. 访问 console.anthropic.com
  2. 注册账号（需要手机号验证）
  3. 进入 API Keys 页面
  4. 点击 "Create Key"
  5. 复制保存 Key（以 sk-ant- 开头）

配置方法：

bash
# 环境变量
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

支持的模型：

模型名称模型 ID特点适用场景
Claude Opus 4.6claude-opus-4-6最强推理，深度思考复杂分析、架构设计
Claude Sonnet 4.6claude-sonnet-4-6编程最强，性价比高编程、日常工作
Claude Haiku 4.5claude-haiku-4-5极速响应，成本低简单任务、高频调用

订阅认证（Claude Max 用户）：

如果你有 Claude Max 订阅，可以不用 API Key，直接通过 OAuth 认证：

bash
# 通过 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 模型，获得最佳体验。

json5
{
  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：

  1. 访问 aistudio.google.com
  2. 用 Google 账号登录
  3. 点击 "Get API Key"
  4. 创建新 Key 或选择已有项目
  5. 复制保存 Key（以 AIzaSy 开头）

配置方法：

bash
# 环境变量
export GEMINI_API_KEY="AIzaSy-xxxxx"

支持的模型：

模型名称模型 ID特点适用场景
Gemini 3.1 Progemini-3.1-pro最新旗舰，多模态最强图片视频理解、复杂任务
Gemini 2.5 Progemini-2.5-pro深度推理复杂分析、长文本
Gemini 2.5 Flashgemini-2.5-flash快速响应日常对话、简单任务

Google 配置项：

json5
{
  agents: {
    defaults: {
      model: "google/gemini-3.1-pro",
    },
  },
}

Moonshot / Kimi（中国用户推荐） ​

月之暗面出品，中文理解能力非常强，适合中文写作、长文本理解和通用助手场景。v2026.4.20 起默认模型更新为 kimi-k2.6。

获取 API Key：platform.moonshot.cn

配置方法：

bash
# 环境变量：Moonshot 未列入下文「常见内置环境变量」表；请以 OpenClaw 官方文档及当前安装版本为准，或通过 OpenAI 兼容接口 / OpenRouter 接入

支持的模型：

模型名称模型 ID特点
Kimi-Maxkimi-max旗舰模型，中文最强
Kimi-Standardkimi-standard均衡之选
Kimi-Litekimi-lite轻量快速

通义千问 (Qwen) ​

阿里巴巴出品，中文能力优秀，性价比极高。开源版本在 Ollama 上也能跑。

认证方式变更（v2026.3.28）： 旧的 qwen-portal-auth OAuth 认证已废弃。请迁移至 Model Studio API Key 方式：

bash
openclaw onboard --auth-choice modelstudio-api-key

获取 API Key：dashscope.console.aliyun.com（需要阿里云账号，开通 DashScope 服务）

配置方法：

bash
# 环境变量：Qwen 未列入下文「常见内置环境变量」表；请以 OpenClaw 官方文档及当前安装版本为准，或通过 OpenAI 兼容接口 / OpenRouter 接入

支持的模型：

模型名称模型 ID特点
Qwen-Maxqwen-max旗舰模型
Qwen-Plusqwen-plus均衡之选
Qwen-Turboqwen-turbo快速便宜
Qwen-Longqwen-long超长上下文

MistralAI ​

法国 AI 公司，模型轻量高效，v2026.2.22 新增集成，支持聊天、记忆和语音功能。

获取 API Key：console.mistral.ai

配置方法：

bash
# 环境变量：Mistral 未列入下文「常见内置环境变量」表；请以 OpenClaw 官方文档及当前安装版本为准，或通过 OpenRouter 接入

支持的模型：

模型名称模型 ID特点
Mistral Largemistral-large-latest旗舰模型
Mistral Mediummistral-medium-latest均衡之选
Mistral Smallmistral-small-latest轻量快速
Codestralcodestral-latest编程专用

DeepSeek ​

国产深度求索，以极低的价格和不错的推理能力出名。v2026.4.24 起新增 V4 Flash 和 V4 Pro，V4 Flash 成为引导向导的默认推荐选项。

获取 API Key：platform.deepseek.com

配置方法：

bash
# 环境变量：DeepSeek 未列入下文「常见内置环境变量」表；请以 OpenClaw 官方文档及当前安装版本为准，或通过 OpenAI 兼容接口 / OpenRouter 接入

支持的模型：

模型名称模型 ID特点
DeepSeek-V4 Flashdeepseek-v4-flash快速推理，默认引导选项（v2026.4.24+）
DeepSeek-V4 Prodeepseek-v4-pro旗舰推理（v2026.4.24+）
DeepSeek-V3deepseek-chat通用对话
DeepSeek-R1deepseek-reasoner深度推理

xAI (Grok) ​

Elon Musk 的 AI 公司，Grok 模型风格独特。v2026.4.22 起新增图像生成（grok-imagine-image）、TTS（6 种语音）和 STT 支持，输出格式支持 MP3/WAV/PCM/G.711。

配置方法：

bash
# 环境变量
export ZAI_API_KEY="xai-xxxxx"

Cohere ​

专注企业级 AI，RAG（检索增强生成）能力强。

配置方法：

bash
# 环境变量：Cohere 未列入下文「常见内置环境变量」表；请以 OpenClaw 官方文档及当前安装版本为准，或通过 OpenRouter 接入

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

v2026.4.22 起新增腾讯云捆绑提供商插件，支持 TokenHub 引导配置和 hy3-preview 模型，带分层定价元数据。适合已有腾讯云基础设施的团队。

配置方法：

bash
# 通过 TokenHub 引导配置
openclaw onboard
# 在引导向导中选择 Tencent Cloud

支持的模型：

模型名称模型 ID特点
Hy3 Previewhy3-preview腾讯混元旗舰预览版

具体模型列表可能随版本更新，以 openclaw models list 输出为准。

Fireworks AI（v2026.4.5+） ​

v2026.4.5 起新增捆绑提供商。Fireworks AI 专注于高性能模型推理，支持多种开源模型的托管部署，推理速度快。

获取 API Key：fireworks.ai

配置方法：

bash
# 环境变量：请以 OpenClaw 官方文档及当前安装版本为准

Fireworks AI 支持 Llama、Mixtral 等主流开源模型的托管推理，具体模型列表以 openclaw models list 为准。

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

v2026.4.5 起新增捆绑提供商。阶跃星辰是国产 AI 公司，Step 系列模型在中文场景有不错的表现。

获取 API Key：platform.stepfun.com

配置方法：

bash
# 环境变量：请以 OpenClaw 官方文档及当前安装版本为准

具体模型列表以 openclaw models list 为准。

企业级云平台 ​

⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了

如果你在企业环境中使用，可能需要通过云平台的托管服务来访问模型，而不是直接用模型提供商的 API。

Azure OpenAI ​

微软 Azure 托管的 OpenAI 模型，适合已有 Azure 订阅的企业用户。数据不出你的 Azure 区域，合规性更好。

前置条件： 有 Azure 订阅，已创建 Azure OpenAI 资源并部署模型。

配置方法：

json5
{
  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 控制台开通模型访问权限。

配置方法：

json5
{
  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。

配置方法：

json5
{
  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：

bash
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows：从 https://ollama.com/download 下载安装包

下载模型：

bash
# 通用对话模型
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：

bash
openclaw models set "ollama/llama3.1"

完整配置示例：

json5
{
  agents: {
    defaults: {
      model: "ollama/llama3.1",
    },
  },
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
      },
    },
  },
}

本地模型推理可能比较慢，如果超时可以在 Ollama 侧调整。Ollama 本身支持 OLLAMA_KEEP_ALIVE 环境变量控制模型在内存中保持多久。

Ollama 硬件要求参考：

模型大小最低内存推荐显存示例模型
1-3B4GB RAM不需要 GPUphi3, gemma2:2b
7-8B8GB RAM6GB VRAMllama3.1, mistral
13-14B16GB RAM10GB VRAMllama3.1:13b
32-34B32GB RAM24GB VRAMqwen2.5:32b
70B64GB RAM48GB VRAMllama3.1:70b

没有独立显卡也能跑，Ollama 会自动用 CPU 推理，只是速度慢一些。

Ollama 远程访问：

如果 Ollama 跑在另一台机器上（比如 GPU 服务器），在服务器上设置 OLLAMA_HOST="0.0.0.0:11434"，然后在 OpenClaw 配置文件 ~/.openclaw/openclaw.json 中设置远程地址：

json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://192.168.1.100:11434",
      },
    },
  },
}

vLLM ​

高性能本地推理引擎，适合有 GPU 的用户，吞吐量比 Ollama 高很多。

安装和启动：

bash
# 安装 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：

json5
// ~/.openclaw/openclaw.json
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000",
      },
    },
  },
}

LM Studio ​

图形界面的本地模型运行工具，适合不喜欢命令行的用户。

  1. 从 lmstudio.ai 下载安装
  2. 在 LM Studio 中搜索并下载模型
  3. 启动本地服务器（Local Server 标签页）
  4. 配置 OpenClaw（编辑 ~/.openclaw/openclaw.json）：
json5
{
  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 的用户。

获取 API Key：

  1. 访问 openrouter.ai
  2. 注册账号
  3. 在 Keys 页面创建 API Key

配置方法：

bash
# 环境变量
export OPENROUTER_API_KEY="sk-or-xxxxx"

通过 OpenRouter 使用特定模型：

bash
# 使用 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 访问所有模型、自动选择最便宜的提供商、内置负载均衡和故障转移、统一计费。

API Key 安全管理 ​

API Key 就是钱，泄露了别人就能用你的额度。这里是安全管理的最佳实践。

绝对不要做的事 ​

  • 把 Key 硬编码在代码里
  • 把含有 Key 的配置文件提交到 Git
  • 在公开场合（截图、论坛、聊天记录）分享 Key

推荐的做法 ​

方法一：用环境变量（最推荐）

bash
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export OPENAI_API_KEY="sk-proj-xxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 然后 source 一下
source ~/.bashrc

OpenClaw 会自动读取这些环境变量，不需要在配置文件中写 Key。

以下为 OpenClaw 常见内置环境变量（与多数发行版公开说明一致；若与你本机版本或官方文档不一致，以你安装的版本及官方文档为准）：

环境变量提供商
OPENAI_API_KEYOpenAI
ANTHROPIC_API_KEYAnthropic
ANTHROPIC_OAUTH_TOKENAnthropic（OAuth 认证）
GEMINI_API_KEYGoogle Gemini
ZAI_API_KEYxAI (Grok)
OPENROUTER_API_KEYOpenRouter
AI_GATEWAY_API_KEYAI Gateway
MINIMAX_API_KEYMiniMax
ELEVENLABS_API_KEYElevenLabs

方法二：用 .env 文件

bash
# 在项目根目录创建 .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 分配不同的模型：

json5
{
  // 默认模型
  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：明显鼓励新话题

按场景的推荐参数 ​

场景temperaturetopPmaxTokens其他
客服机器人0.30.92048-
创意写作0.90.954096presencePenalty: 0.3
代码生成0.01.08192-
数据提取0.01.01024-

多模型切换与 Fallback 策略 ​

⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了

自动故障转移 ​

当主模型不可用时（API 挂了、超时、限流），OpenClaw 内置 model-failover 机制，可以自动切换到备用模型。

查看当前故障转移列表：

bash
openclaw models fallbacks list

配置示例：

json5
{
  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 无效）、模型正常返回但内容不符合预期。

手动切换模型 ​

bash
# 切换默认模型
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 查看模型状态：

bash
openclaw models status           # 查看当前模型状态
openclaw models list             # 列出所有可用模型

Token 限制 ​

不同模型有不同的上下文窗口和输出限制：

模型上下文窗口最大输出
GPT-5.2128K tokens32,768 tokens
Claude Sonnet 4.6200K tokens64,000 tokens
Gemini 3.1 Pro1M tokens65,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 等）。配置方法：

json5
{
  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,
          },
        ],
      },
    },
  },
}

然后就可以用了：

bash
openclaw models set "custom/my-custom-model"

多个自定义服务 ​

可以配置多个自定义提供商，只需用不同的名字：

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

排查步骤：

bash
# 1. 确认 Ollama 正在运行
ollama list

# 2. 如果没运行，启动它
ollama serve

# 3. 如果是远程 Ollama，确认防火墙允许 11434 端口

问题：本地模型太慢 ​

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

Released under the MIT License.

Copyright © 2024-present DANTE FUNG