# 04. AI 模型配置指南

> **课程信息**
>
> - **作者**：老金
> - **GitHub**：https://github.com/KimYx0207
> - **公众号**：老金带你玩AI
> - **X（Twitter）**：老金带你玩AI
> - **个人博客**：https://aiking.dev
> - **难度等级**：🟡 进阶
> - **阅读时间**：25 分钟
> - **前置知识**：已完成快速开始（[03-快速开始指南](03-快速开始指南.md)）
>
> **本篇你将学会：** 切换 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 的模型配置存放在：

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

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

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

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

1. 访问 [platform.openai.com](https://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
```

**支持的模型：**

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

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

| 选择维度 | 看什么 | 适用场景 |
|----------|--------|----------|
| 通用旗舰 | 当前 OpenAI 目录里的高能力模型 | 复杂推理、创作、规划 |
| 轻量模型 | 当前 OpenAI 目录里的 mini / low-cost 模型 | 高频问答、简单摘要 |
| 多模态模型 | 当前目录中明确支持图片/音频/视频的模型 | 图片理解、文件解析 |
| 推理模型 | 当前目录中强调 reasoning 的模型 | 数学、逻辑、科学 |

**指定使用 OpenAI 模型：**

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

**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](https://console.anthropic.com/)
2. 注册账号（需要手机号验证）
3. 进入 API Keys 页面
4. 点击 "Create Key"
5. 复制保存 Key（以 `sk-ant-` 开头）

**配置方法：**

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

**支持的模型：**

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

| 选择维度 | 看什么 | 适用场景 |
|----------|--------|----------|
| 高能力模型 | 当前 Anthropic 目录中最高能力/最长思考能力的型号 | 复杂分析、架构设计 |
| 平衡模型 | 当前目录中速度、成本和代码能力较均衡的型号 | 编程、日常工作 |
| 轻量模型 | 当前目录中的低延迟/低成本型号 | 简单任务、高频调用 |

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

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

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

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

**配置方法：**

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

**支持的模型：**

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

| 选择维度 | 看什么 | 适用场景 |
|----------|--------|----------|
| Pro / 高能力 | 当前目录中的高能力长上下文模型 | 图片视频理解、复杂任务 |
| Flash / 轻量 | 当前目录中的低延迟模型 | 日常对话、简单任务 |
| 企业云路径 | Vertex / Google Cloud 中你账号可用的部署 | 企业权限、审计和配额管理 |

**Google 配置项：**

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

---

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

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

获取 API Key：[platform.moonshot.cn](https://platform.moonshot.cn/)

**配置方法：**

```bash
# 环境变量：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 方式：
>
> ```bash
> openclaw onboard --auth-choice modelstudio-api-key
> ```

获取 API Key：[dashscope.console.aliyun.com](https://dashscope.console.aliyun.com/)（需要阿里云账号，开通 DashScope 服务）

**配置方法：**

```bash
# 环境变量：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](https://console.mistral.ai/)

**配置方法：**

```bash
# 环境变量：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](https://platform.deepseek.com/)

**配置方法：**

```bash
# 环境变量：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` 帮助输出。

**配置方法：**

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

### 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-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` 中设置远程地址：

```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](https://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 的用户。

> **v2026.5.22 更新**：OpenRouter 会尊重 provider-level `params.provider` 路由策略，模型级和 agent 级参数可以覆盖默认值。团队里如果需要固定地区、价格或供应商偏好，不要只写模型名，还要把 provider routing policy 记录进配置变更说明。

**获取 API Key：**

1. 访问 [openrouter.ai](https://openrouter.ai/)
2. 注册账号
3. 在 Keys 页面创建 API Key

**配置方法：**

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

**通过 OpenRouter 使用特定模型：**

```bash
# 使用 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。教程里的建议顺序是：

1. 先配置正式 provider API。
2. 再确认图片、视频、TTS、STT 的 provider credentials。
3. 最后才考虑 CLI fallback。

如果媒体任务失败，先查当前 provider 的凭证、超时和模型能力，不要直接让读者安装一堆外部 CLI。

## 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_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 文件**

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

| 场景 | 推荐选择 | 理由 | 成本判断 |
|------|----------|------|----------|
| 日常闲聊 | 当前目录中的低成本模型 | 便宜快速，够用 | 看 provider 当前价格 |
| 复杂推理 | 当前目录中的高能力 / reasoning 模型 | 质量优先 | 成本通常更高 |
| 编程辅助 | 工具调用和代码能力稳定的模型 | 代码生成、调试、Review | 看输出长度和重试率 |
| 中文场景 | 中文表现稳定的云端或本地模型 | 中文理解和本地化 | 按各家定价 |
| 隐私优先 | Ollama / vLLM 等本地模型 | 推理内容可留在本机 | 电费和机器成本 |
| 多模态 | 当前目录中明确支持对应媒体的模型 | 图片、音频、视频理解 | 看媒体计费规则 |
| 预算有限 | 低价 provider 或路由服务 | 按任务价值分层 | 先设预算上限 |
| 超长文本 | 当前目录中的长上下文模型 | 长文档、会议、知识库 | 重点看上下文价格 |

### 按 Agent 角色分配模型

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

```json5
{
  // 默认模型
  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 机制，可以自动切换到备用模型。

查看当前故障转移列表：

```bash
openclaw models fallbacks list
```

配置示例：

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

### 手动切换模型

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

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

# 列出所有可用模型
openclaw models list
```

---

## Token 限制与成本控制

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

### 预算控制

担心 API 费用失控？可以在各模型提供商的控制台设置用量限制：

- **OpenAI**：在 [platform.openai.com](https://platform.openai.com/) 的 Settings > Limits 中设置月度上限
- **Anthropic**：在 [console.anthropic.com](https://console.anthropic.com/) 的 Plans & Billing 中查看用量
- **Google**：在 Google Cloud Console 中设置 API 配额和预算提醒

OpenClaw 本身可以通过 CLI 查看模型状态：

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

### Token 限制

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

| 要检查的项 | 为什么重要 |
|------|-----------|
| 上下文窗口 | 决定能放多少历史消息、记忆和文档 |
| 最大输出 | 决定单次回复、报告或代码生成能有多长 |
| 多模态限制 | 决定图片、音频、视频是否可用以及如何计费 |
| 账号/区域限制 | 决定你本机是否真的能调用这个模型 |

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

### 省钱技巧

1. 简单任务用当前目录里的低成本模型
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. 把高频任务切换到便宜模型

---

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

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

### 低风险高频任务

适合：

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

建议：

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

### 高价值复杂任务

适合：

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

建议：

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

### 隐私敏感任务

适合：

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

建议：

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

一个模型分层记录：

```md
# 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
```

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

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

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

排查顺序：

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

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

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

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

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

临时止血策略：

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

长期策略：

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

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

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

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

演练 prompt：

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

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

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

演练记录：

```md
# Model Fallback Drill

## Primary

Provider:
Model:

## Fallback

Provider:
Model:

## Test Message

...

## Observed

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

## Follow-up

...
```

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

## 本地模型现实检查

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

适合：

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

不适合：

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

本地模型试用记录：

```md
# 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 实例设计模型路由

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

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

你还有三类任务：

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

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

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

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

| 任务 | 推荐模型类型 | 原因 |
|---|---|---|
| WebChat 普通问答 | 中低成本云端模型 | 响应快，成本可控 |
| Telegram 私人记录 | 本地模型或隐私策略更好的模型 | 内容更私人 |
| Discord 技术支持 | 较强推理模型 | 错误排查需要质量 |
| 长线程总结 | 长上下文模型 | 避免丢上下文 |
| 自动摘要/分类 | 便宜模型 | 高频低风险 |
| 生成外部回复草稿 | 中等模型 + 人工确认 | 需要可读性，但不直接发布 |

然后把它映射到 Agent：

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

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

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

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

```md
# 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 | 服务没启动、端口不通、模型没拉取 |

排查顺序：

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

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

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

Docker 环境还要进容器看：

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

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

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

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

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

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

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

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

常见选择：

| 优先级 | 配置思路 |
|---|---|
| 质量优先 | 强模型给核心 Agent，降低自动触发频率 |
| 速度优先 | 默认模型用低延迟 provider，复杂任务手动切强模型 |
| 成本优先 | 高频入口用便宜模型，长任务限制 maxTokens |
| 隐私优先 | 本地模型处理私人内容，云端只处理公开材料 |

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

## 长上下文任务的处理方式

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

更稳的流程：

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

例如日志分析：

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

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

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

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

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

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

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

```md
# 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.
```

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

```json5
{
  "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 条固定测试消息。每次换模型都跑一遍。

```md
# Model Eval Set

## 1. 普通问答

请用 100 字解释 OpenClaw 的 Gateway。

## 2. 安装排错

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

## 3. 长文本摘要

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

## 4. 安全边界

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

## 5. 平台接入

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

记录：

```md
# Model Eval Result

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

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

## 隐私分级和模型选择

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

| 内容 | 示例 | 推荐 |
|---|---|---|
| 公开内容 | 文档、公开 issue、开源 FAQ | 云端模型可用 |
| 内部内容 | 团队流程、内部 runbook | 选可信 provider，减少原文外发 |
| 私人内容 | 日记、个人偏好、私聊 | 本地模型或更严格策略 |
| 高敏内容 | token、客户隐私、密钥、财务 | 不发送给模型，先脱敏或拒绝 |

SOUL.md 可以写：

```markdown
## 模型隐私规则

- 遇到 token、私钥、cookie、密码，不发送给外部模型。
- 需要分析日志时，先要求用户脱敏。
- 私人内容优先使用本地模型或让用户确认。
- 公开文档和普通 FAQ 可以使用默认云端模型。
```

模型配置不是只看质量，还要看数据能不能被送出去。

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

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

迁移前记录旧配置：

```bash
openclaw config get agents.defaults.model
openclaw models status
```

写迁移笔记：

```md
# 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

...
```

迁移步骤：

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

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

配置一个测试 Agent：

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

测试：

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

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

## 模型降级策略

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

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

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

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

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

SOUL.md 可以写：

```markdown
## 模型降级行为

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

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

---

## 下一步

模型配好了！去 [05. 消息平台集成](05-消息平台接入指南.md) 连接你的聊天软件！