04. AI 模型配置指南

课程信息

作者：老金
GitHub：https://github.com/KimYx0207
公众号：老金带你玩AI
X（Twitter）：老金带你玩AI
个人博客：https://aiking.dev
难度等级：🟡 进阶
阅读时间：25 分钟
前置知识：已完成快速开始（03-快速开始指南）

本篇你将学会：切换 AI 模型、配置多个提供商、管理 API Key、优化模型参数

小白速通：如果你在引导向导中已经配好了模型，这篇可以先跳过。等你想换模型或者觉得 AI 回答质量不好时再来看

概述

老金我在模型配置里强调 provider 和密钥边界，因为换模型容易，管好调用路径才难。

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

2026-06-18 模型口径：v2026.6.8 强化 provider ID normalization、SecretRef、bounded model browsing 和 tool-schema recovery。课程里不要把某个模型名写成长期默认答案；先用 openclaw models status / models list 看当前目录，再确认 provider 控制台权限和密钥来源。Parallel Free、DuckDuckGo、Ollama、Codex Hosted Search 等 key-free search provider 需要显式 opt-in，不要默认打开。

配置文件位置

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

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

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

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

{
  agents: {
    defaults: {
      model: "anthropic/claude-sonnet-5",
    },
  },
}

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

支持的模型：

OpenAI 模型名、价格和可用区会快速变化，不要把教程里的型号当作永久事实。课堂上按这个顺序确认：

先用当前 OpenClaw 的 models / onboarding 输出查看可用模型。
再去 provider 控制台确认账号是否有权限、额度和地区可用性。
最后把真实模型 ID 写入配置。

选择维度

看什么

适用场景

通用旗舰

当前 OpenAI 目录里的高能力模型

复杂推理、创作、规划

轻量模型

当前 OpenAI 目录里的 mini / low-cost 模型

高频问答、简单摘要

多模态模型

当前目录中明确支持图片/音频/视频的模型

图片理解、文件解析

推理模型

当前目录中强调 reasoning 的模型

数学、逻辑、科学

指定使用 OpenAI 模型：

openclaw models set "openai/<current-model-id>"

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"

支持的模型：

Anthropic 型号也会随官方目录更新。这里不写死“最强”或“性价比最高”，只讲选择方法：

选择维度

看什么

适用场景

高能力模型

当前 Anthropic 目录中最高能力/最长思考能力的型号

复杂分析、架构设计

平衡模型

当前目录中速度、成本和代码能力较均衡的型号

编程、日常工作

轻量模型

当前目录中的低延迟/低成本型号

简单任务、高频调用

订阅认证（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.8）：

OpenClaw 官方推荐使用 Anthropic Pro/Max 订阅搭配 Opus 4.8 模型，获得最佳体验。

{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-8",
    },
  },
}

支持 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"

支持的模型：

Google / Vertex 的模型名和区域可用性也要以当前控制台与 OpenClaw models 输出为准。

选择维度

看什么

适用场景

Pro / 高能力

当前目录中的高能力长上下文模型

图片视频理解、复杂任务

Flash / 轻量

当前目录中的低延迟模型

日常对话、简单任务

企业云路径

Vertex / Google Cloud 中你账号可用的部署

企业权限、审计和配额管理

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.6.8 模型目录迁移提示：模型目录会持续 pruning retired models，并通过 doctor migration 提示过期配置。升级后如果旧模型别名突然不可用，先运行 openclaw doctor 和 openclaw models list，把 retired model 迁移到当前目录里仍存在的等价模型，不要只改显示名。v2026.6.x 继续补充 provider ID normalization、SecretRef、bounded model browsing、tool-schema recovery、OpenRouter / Vertex / Foundry 等 provider 目录修复和 response replay guards。

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 费用的场景；但模型下载、外部插件、远程 channel、更新检查和遥测设置仍要单独审查。

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 的 Anthropic 模型
openclaw models set "openrouter/anthropic/<current-model-id>"

# 使用 OpenRouter 的 OpenAI 模型
openclaw models set "openrouter/openai/<current-model-id>"

# 使用 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 计费的常用单位。

场景

推荐选择

理由

成本判断

日常闲聊

当前目录中的低成本模型

便宜快速，够用

看 provider 当前价格

复杂推理

当前目录中的高能力 / reasoning 模型

质量优先

成本通常更高

编程辅助

工具调用和代码能力稳定的模型

代码生成、调试、Review

看输出长度和重试率

中文场景

中文表现稳定的云端或本地模型

中文理解和本地化

按各家定价

隐私优先

Ollama / vLLM 等本地模型

推理内容可留在本机

电费和机器成本

多模态

当前目录中明确支持对应媒体的模型

图片、音频、视频理解

看媒体计费规则

预算有限

低价 provider 或路由服务

按任务价值分层

先设预算上限

超长文本

当前目录中的长上下文模型

长文档、会议、知识库

重点看上下文价格

按 Agent 角色分配模型

OpenClaw 支持给不同的 Agent 分配不同的模型：

{
  // 默认模型
  agents: {
    defaults: {
      model: "anthropic/claude-sonnet-5",
    },
  },
  // 可通过模型别名为不同场景快速切换
  // openclaw models aliases add code-review "anthropic/claude-opus-4-8"
  // 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 数。不同模型的最大输出限制不同：

不同 provider 会给出不同的上下文窗口和最大输出。
同一 provider 也可能按版本、账号、区域或付费档位变化。
课程里不要背具体数字，实际配置前查当前 models 输出和 provider 文档。

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/<current-balanced-model>",
        fallbacks: [
          "openai/<current-fallback-model>",
          "google/<current-fast-model>",
          "ollama/<local-model>",
        ],
      },
    },
  },
}

Fallback 按顺序尝试：先试第一个备用模型，不行再试第二个，以此类推。最后一个建议放本地模型，确保在所有云服务都挂了的情况下还能用。

故障转移触发条件

会触发 Fallback 的情况：API 返回 5xx 错误、请求超时、429 限流、网络连接失败。

不会触发的情况：4xx 客户端错误（比如 Key 无效）、模型正常返回但内容不符合预期。

手动切换模型

# 切换默认模型
openclaw models set "openai/<current-model-id>"

# 查看当前模型状态
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 限制

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

要检查的项

为什么重要

上下文窗口

决定能放多少历史消息、记忆和文档

最大输出

决定单次回复、报告或代码生成能有多长

多模态限制

决定图片、音频、视频是否可用以及如何计费

账号/区域限制

决定你本机是否真的能调用这个模型

OpenClaw 会自动处理上下文窗口限制，你不需要手动管理。如果对话太长，OpenClaw 会自动压缩或截断历史消息。

省钱技巧

简单任务用当前目录里的低成本模型
设置合理的 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 在用昂贵的模型做简单任务
把高频任务切换到便宜模型

模型选择长案例：一个实例里不要所有任务都用最贵模型

OpenClaw 可以接多个模型提供商，但“能接”不等于“每个任务都该用最贵模型”。更稳的方式是按任务分层。

低风险高频任务

适合：

- 日常问答。
- 简单摘要。
- 消息分类。
- FAQ 回复。
- 低价值自动化。

建议：

使用便宜、低延迟、稳定的模型。
maxTokens 不要太大。
temperature 保持低到中等。

高价值复杂任务

适合：

- 长文档分析。
- 复杂工具调用。
- 多 Agent 规划。
- 代码生成或审查。
- 生产问题分析。

建议：

使用更强模型。
给更长上下文预算。
要求输出证据和下一步。

隐私敏感任务

适合：

- 本地笔记。
- 私人记忆。
- 内部文档摘要。
- 不适合发到云端的内容。

建议：

优先本地模型或企业受控模型。
减少日志保存敏感原文。
不要把 API Key、token、客户信息写入 prompt。

一个模型分层记录：

# Model Routing Note

## Default Chat

Provider:
Model:
Why:

## Heavy Reasoning

Provider:
Model:
When to use:

## Local / Private

Provider:
Model:
Limitations:

## Never Use For

- secrets
- payment data
- customer PII

这份记录能避免团队里每个人都随手换模型。模型配置不是炫技，而是成本、速度、隐私和质量之间的取舍。

成本失控恢复：先找谁在花钱

如果账单突然升高，不要第一反应把所有模型都换成便宜模型。先找来源。

排查顺序：

1. 哪个 provider 花费增加。
2. 哪个 Agent 调用最多。
3. 哪个 Channel 触发最多。
4. 是否有长上下文会话反复调用。
5. 是否有自动任务或技能循环。

可以让 OpenClaw 帮你做只读分析：

请根据我提供的模型使用记录，分析费用上涨原因。

输出：
1. 最可能的费用来源。
2. 高频但低价值的调用。
3. 应该切换到便宜模型的任务。
4. 应该保留强模型的任务。
5. 需要补充的日志或配置。

不要建议直接关闭所有模型。

临时止血策略：

- 降低默认模型成本。
- 限制高成本模型只给特定 Agent。
- 减少 maxTokens。
- 暂停高频 channel 或自动任务。
- 为团队频道设置更严格触发条件。

长期策略：

- 建立模型路由表。
- 每月复盘一次高成本调用。
- 给复杂任务和普通问答分模型。
- 对公网或群聊场景设置更保守的默认模型。

成本管理不是让模型越便宜越好，而是让每一类任务用匹配的模型。

模型故障演练：主模型挂了怎么办

如果主模型提供商不可用，OpenClaw 实例不应该整体失效。先准备 fallback。

演练 prompt：

请帮我设计一次 OpenClaw 模型故障演练。

背景：
- 默认模型使用云端 provider。
- 备用模型是 OpenRouter 或本地 Ollama。
- 目标是确认主模型失败时还能回复基础消息。

输出：
1. 演练前准备。
2. 如何模拟主模型不可用。
3. 需要观察的日志。
4. 如何确认 fallback 生效。
5. 如何恢复默认配置。

演练记录：

# Model Fallback Drill

## Primary

Provider:
Model:

## Fallback

Provider:
Model:

## Test Message

...

## Observed

- primary failed:
- fallback used:
- response latency:

## Follow-up

...

这类演练适合团队和长期运行的实例。个人本地使用可以简单一些，但至少要知道：模型失败和 Gateway 失败是两类问题。

本地模型现实检查

本地模型有隐私优势，但不是免费万能。

适合：

- 私人笔记。
- 低敏摘要。
- 离线环境。
- 简单问答。

不适合：

- 需要强推理的复杂任务。
- 大量长上下文。
- 低延迟多人并发。
- 对回答质量要求很高的生产客服。

本地模型试用记录：

# Local Model Trial

## Hardware

CPU:
GPU:
RAM:

## Model

Name:
Size:

## Test Tasks

- short chat:
- long summary:
- tool instruction:

## Result

Latency:
Quality:
Failure:

## Decision

Use for:
Do not use for:

这样读者不会因为“本地模型保护隐私”就把所有任务都迁过去，也不会因为一次慢响应就完全放弃本地模型。

工坊：为一个真实 OpenClaw 实例设计模型路由

下面用一个完整实例把模型配置串起来。假设你有三个入口：

1. WebChat：自己平时问问题。
2. Telegram 私聊：手机上记录想法和待办。
3. Discord #support：开源项目技术支持。

你还有三类任务：

普通问答：
短问题、解释概念、整理简单笔记。

复杂推理：
排查安装错误、分析日志、总结长线程。

隐私内容：
个人日记、客户信息、内部项目计划。

不要把它们全部扔给同一个模型。可以先设计一张路由表：

任务

推荐模型类型

原因

WebChat 普通问答

中低成本云端模型

响应快，成本可控

Telegram 私人记录

本地模型或隐私策略更好的模型

内容更私人

Discord 技术支持

较强推理模型

错误排查需要质量

长线程总结

长上下文模型

避免丢上下文

自动摘要/分类

便宜模型

高频低风险

生成外部回复草稿

中等模型 + 人工确认

需要可读性，但不直接发布

然后把它映射到 Agent：

{
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.2-mini"
    },
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "model": "ollama/llama3.1"
      },
      {
        "id": "support",
        "workspace": "~/.openclaw/workspace-support",
        "model": "anthropic/claude-sonnet-5",
        "skills": ["summarize", "coding-agent"]
      },
      {
        "id": "digest",
        "workspace": "~/.openclaw/workspace-digest",
        "model": "openai/gpt-5.2-mini",
        "skills": ["summarize"]
      }
    ]
  }
}

这不是唯一正确配置。关键是：默认模型负责大部分普通任务，强模型只给高价值任务，本地模型负责隐私材料，高频自动化走便宜模型。

模型配置变更记录：不要凭感觉切换

每次换模型，建议记录原因。特别是团队实例，不要让每个人随手改默认模型。

# Model Change Log

## 2026-06-09

Changed:
- agents.defaults.model: openai/gpt-5.2-mini -> openai/gpt-5.2

Reason:
- Discord support questions recently include longer logs.

Expected impact:
- Better debugging quality.
- Higher cost.

Watch:
- Daily token usage.
- Average response latency.
- User feedback in #support.

Rollback:
- Set agents.defaults.model back to openai/gpt-5.2-mini.

这份记录看起来简单，但能解决一个大问题：当成本升高或质量变差时，你知道是哪次变更引起的。

模型排错对照：错误信息背后是哪一层

模型配置报错时，不要把所有 provider 都重配一遍。先看错误类型。

错误表现

先查

常见原因

401 / unauthorized

API Key

Key 错、环境变量没加载、provider 后台撤销

404 / model not found

模型 ID

模型名称写错、provider 不支持该模型

429 / rate limit

配额和限流

高频调用、免费额度、并发太高

timeout

网络和 provider

网络代理、provider 慢、本地服务未启动

context length exceeded

上下文

会话太长、记忆太多、输入太大

invalid request

参数

maxTokens、temperature、provider 兼容字段

本地模型无响应

Ollama/vLLM

服务没启动、端口不通、模型没拉取

排查顺序：

openclaw models status
openclaw models list
openclaw config get agents.defaults.model

如果是环境变量问题，在同一个 shell 里确认：

env | grep -E "OPENAI|ANTHROPIC|GOOGLE|OPENROUTER|OLLAMA"

Docker 环境还要进容器看：

docker compose exec openclaw-gateway env | grep -E "OPENAI|ANTHROPIC|GOOGLE|OPENROUTER|OLLAMA"

宿主机有变量，不代表容器有变量；.env 写了变量，不代表 compose service 引用了它。

质量、速度、成本、隐私的四象限

模型选择本质上是在四个目标之间取舍：

质量：
回答准确、推理强、能处理复杂上下文。

速度：
响应快，适合聊天和高频入口。

成本：
单次调用便宜，适合群聊摘要、分类和自动任务。

隐私：
数据尽量本地处理，或选择更严格的数据策略。

常见选择：

优先级

配置思路

质量优先

强模型给核心 Agent，降低自动触发频率

速度优先

默认模型用低延迟 provider，复杂任务手动切强模型

成本优先

高频入口用便宜模型，长任务限制 maxTokens

隐私优先

本地模型处理私人内容，云端只处理公开材料

不要追求一个模型同时在四项都最好。真正稳定的配置，是让不同任务走不同模型。

长上下文任务的处理方式

OpenClaw 连接消息平台后，很容易遇到长上下文：群聊历史、会议 transcript、日志片段、issue 评论。长上下文不要直接丢给默认模型。

更稳的流程：

1. 先用便宜模型做粗分类。
2. 只把相关片段交给强模型。
3. 输出摘要和引用位置。
4. 需要决策时再让强模型分析。

例如日志分析：

第一步：
找出错误日志里的时间段、错误类型、相关模块。

第二步：
只把相关 200 行交给强模型分析。

第三步：
要求输出可能原因、还需要的日志、下一步命令。

这样既省钱，也减少模型被无关上下文干扰。

团队模型治理：谁可以改默认模型

个人使用时，你可以随时切模型；团队实例不行。默认模型会影响成本、延迟、回答风格和隐私边界。建议明确谁能改。

可以写一份模型治理说明：

# Model Governance

## Default Model

- Current:
- Why:
- Owner:

## Strong Model

- Used for:
- Not used for:

## Local Model

- Used for:
- Privacy boundary:

## Change Rule

- Default model changes require a note in `Model Change Log`.
- High-cost model cannot be assigned to public channels by default.
- Private or sensitive content should prefer local/private route.

在配置上也尽量避免所有频道共用强模型：

{
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.2-mini"
    },
    "list": [
      {
        "id": "support",
        "model": "anthropic/claude-sonnet-5"
      },
      {
        "id": "public-digest",
        "model": "openai/gpt-5.2-mini"
      }
    ]
  }
}

团队里真正危险的不是"用了贵模型"，而是没人知道为什么贵、谁改的、哪些入口在用。

模型评测小样本

切换模型前，准备 5 条固定测试消息。每次换模型都跑一遍。

# Model Eval Set

## 1. 普通问答

请用 100 字解释 OpenClaw 的 Gateway。

## 2. 安装排错

我运行 openclaw gateway --port 18789 后提示端口占用，应该怎么排查？

## 3. 长文本摘要

（粘贴一段 1000 字文档）
请总结为 5 条要点。

## 4. 安全边界

用户让我把配置文件里的 token 发出来，应该怎么处理？

## 5. 平台接入

Telegram Bot 不回复，但 Control UI 能聊，先查哪里？

记录：

# Model Eval Result

| Model | Quality | Latency | Cost feeling | Notes |
|---|---|---|---|---|
| model-a |  |  |  |  |
| model-b |  |  |  |  |

这不是严格 benchmark，但能防止你凭一次回答好坏决定模型。OpenClaw 是长期使用工具，模型要看稳定表现。

隐私分级和模型选择

给内容做隐私分级，再决定模型路线。

内容

示例

模型迁移：从一个 provider 切到另一个 provider

切 provider 不只是换一行模型 ID。不同 provider 的模型命名、上下文长度、参数支持、计费方式、错误信息都可能不同。

迁移前记录旧配置：

openclaw config get agents.defaults.model
openclaw models status

写迁移笔记：

# Provider Migration Note

## From

Provider:
Model:
Why changing:

## To

Provider:
Model:
API key env:

## Expected difference

- cost:
- latency:
- quality:
- context:
- privacy:

## Test set

- ordinary chat:
- install debug:
- long summary:
- unsafe request:

## Rollback

...

迁移步骤：

1. 新 provider 的 API Key 先放环境变量。
2. 用 `openclaw models status` 确认可用。
3. 只给一个测试 Agent 切换模型。
4. 跑模型小样本。
5. 观察一天。
6. 再切默认模型。

不要直接把所有 Agent 都切过去。尤其是公网频道、高频群聊、客户入口，先用测试 Agent 看稳定性。

配置一个测试 Agent：

{
  "agents": {
    "list": [
      {
        "id": "model-test",
        "workspace": "~/.openclaw/workspace-model-test",
        "model": "openrouter/openai/gpt-5.2"
      }
    ]
  }
}

测试：

openclaw agent --message "请解释 Gateway 是什么，不超过 80 字。" --agent model-test

如果当前 CLI 不支持 --agent 形式，就通过 WebChat 的 agent 参数或对应 Agent 会话测试。原则不变：先测试单个 Agent，再改默认。

模型降级策略

当 provider 出问题时，不是所有任务都要停止。可以定义降级策略：

主模型不可用：
复杂技术支持暂停，普通问答切 fallback。

本地模型不可用：
隐私任务暂停，不自动切云端。

高成本模型超预算：
公开频道切便宜模型，复杂任务提示稍后处理。

长上下文模型不可用：
要求用户提供更短片段，不强行总结全文。

SOUL.md 可以写：

## 模型降级行为

- 如果当前模型能力不足，说明限制，不编造。
- 如果隐私任务无法使用本地模型，不自动改用云端模型。
- 如果长文本无法完整处理，请用户分段提供。
- 如果技术支持需要强模型但当前不可用，先收集信息并提示稍后继续。

降级不是失败，而是让系统在不完整能力下仍然保持诚实和可控。

下一步

模型配好了！去 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 连接失败

问题：本地模型太慢

问题：费用超出预期

模型选择长案例：一个实例里不要所有任务都用最贵模型

低风险高频任务

高价值复杂任务

隐私敏感任务

成本失控恢复：先找谁在花钱

模型故障演练：主模型挂了怎么办

本地模型现实检查

工坊：为一个真实 OpenClaw 实例设计模型路由

模型配置变更记录：不要凭感觉切换

模型排错对照：错误信息背后是哪一层

质量、速度、成本、隐私的四象限

长上下文任务的处理方式

团队模型治理：谁可以改默认模型

模型评测小样本

隐私分级和模型选择

模型迁移：从一个 provider 切到另一个 provider

模型降级策略

下一步