Skip to content

04-模型配置指南.md

Latest commit

 

History

History
1021 lines (722 loc) · 26.2 KB

04-模型配置指南.md

File metadata and controls

1021 lines (722 loc) · 26.2 KB

04. AI 模型配置指南

🟡 难度：进阶 | ⏱️ 阅读时间：25 分钟 | 📋 前置知识：已完成快速开始（03-快速开始指南）

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

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

概述

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

配置模型最简单的方式：

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 的模型配置存放在：

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

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

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

{
  agent: {
    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 只在创建时显示一次，务必立刻复制保存。丢了只能重新创建。

配置方法：

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

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

支持的模型：

模型名称 模型 ID 特点 适用场景
GPT-5.3 gpt-5.3 最新旗舰，能力最强 复杂推理、创作
GPT-5.3 Codex gpt-5.3-codex 编程专用优化 代码生成、调试
GPT-5.2 gpt-5.2 多模态，速度快 日常对话、图片理解
GPT-5.2-mini gpt-5.2-mini 便宜快速 简单任务、高频调用
o3 o3 深度推理 数学、逻辑、科学
o3-mini o3-mini 轻量推理 中等复杂度推理

指定使用 OpenAI 模型：

openclaw models set "openai/gpt-5.2"

OpenAI 特有配置项：

{
  // 在 openclaw.json 中可以配置 OpenAI 相关选项
  providers: {
    openai: {
      baseUrl: "https://api.openai.com/v1",
      organization: "org-xxxxx",
      project: "proj-xxxxx",
      timeout: 60000,
      maxRetries: 3,
    },
  },
}
  • organization / project：组织 ID 和项目 ID，用于费用归属
  • baseUrl：默认不用改，用代理或兼容服务时改成对应地址

Anthropic (Claude)

Anthropic 的 Claude 系列模型以强大的推理能力和编程能力著称，是很多开发者的首选。

获取 API Key：

  1. 访问 console.anthropic.com
  2. 注册账号（需要手机号验证）
  3. 进入 API Keys 页面
  4. 点击 "Create Key"
  5. 复制保存 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 auth login anthropic

OpenClaw 支持 ANTHROPIC_OAUTH_TOKEN 环境变量来存储 OAuth 令牌。

这样就能用你的订阅额度，不需要额外付 API 费用。

推荐配置（Anthropic Pro/Max 100/200 + Opus 4.6）：

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

{
  agent: {
    model: "anthropic/claude-opus-4-6",
  },
}
  • 支持 OAuth 认证和 API Key 两种方式
  • OAuth 认证通过 ANTHROPIC_OAUTH_TOKEN 环境变量或 openclaw auth login 配置

Google Gemini

Google 的 Gemini 系列模型在多模态能力上表现突出，尤其是图片和视频理解。

获取 API Key：

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

配置方法：

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

支持的模型：

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

Google 配置项：

{
  agent: {
    model: "google/gemini-2.5-pro",
  },
}

Moonshot / Kimi（中国用户推荐）

月之暗面出品，中文理解能力非常强，v2026.2.23 新增了视觉和视频能力。

获取 API Key：platform.moonshot.cn

配置方法：

# 环境变量（注意：Moonshot 不在 OpenClaw 源码验证的环境变量列表中，
# 可通过 OpenAI 兼容接口或 OpenRouter 接入）

支持的模型：

模型名称 模型 ID 特点
Kimi-Max kimi-max 旗舰模型，中文最强
Kimi-Standard kimi-standard 均衡之选
Kimi-Lite kimi-lite 轻量快速

通义千问 (Qwen)

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

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

国产深度求索，以极低的价格和不错的推理能力出名。

获取 API Key：platform.deepseek.com

配置方法：

# 环境变量（注意：DeepSeek 不在 OpenClaw 源码验证的环境变量列表中，
# 可通过 OpenAI 兼容接口或 OpenRouter 接入）

支持的模型：

模型名称 模型 ID 特点
DeepSeek-V3 deepseek-chat 通用对话
DeepSeek-R1 deepseek-reasoner 深度推理

xAI (Grok)

Elon Musk 的 AI 公司，Grok 模型风格独特。

配置方法：

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

Cohere

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

配置方法：

# 环境变量（注意：Cohere 不在 OpenClaw 源码验证的环境变量列表中，
# 可通过 OpenRouter 接入）

企业级云平台

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

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

Azure OpenAI

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

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

配置方法：

{
  providers: {
    "azure-openai": {
      endpoint: "https://your-resource.openai.azure.com",
      deploymentName: "gpt-5.2",
      apiVersion: "2024-12-01-preview",
    },
  },
}

注意：deploymentName 是你在 Azure 中部署时起的名字，不是 OpenAI 原始的模型名。

AWS Bedrock

亚马逊 AWS 的托管 AI 服务，支持多家模型提供商。适合已有 AWS 基础设施的团队。

前置条件： 有 AWS 账号，已在 Bedrock 控制台开通模型访问权限。

配置方法：

{
  providers: {
    "aws-bedrock": {
      region: "us-east-1",
      // 认证通过 AWS 环境变量或 IAM Role
    },
  },
}

也可以用 AWS 环境变量（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_DEFAULT_REGION）。在 EC2 实例上直接用 IAM Role 即可。Bedrock 支持 Claude、Llama、Mistral 等系列模型。

Google Vertex AI

Google Cloud 的企业级 AI 平台，适合已有 GCP 基础设施的团队。

前置条件： 有 Google Cloud 项目，已启用 Vertex AI API。

配置方法：

{
  providers: {
    "vertex-ai": {
      projectId: "your-project-id",
      location: "us-central1",
      credentials: "/path/to/service-account.json",
    },
  },
}

也可以用 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"

完整配置示例：

{
  agent: {
    model: "ollama/llama3.1",
  },
  providers: {
    ollama: {
      baseUrl: "http://127.0.0.1:11434",
      timeout: 300000,
      keepAlive: "5m",
    },
  },
}
  • timeout：本地模型推理可能比较慢，建议设长一点（300 秒）
  • keepAlive：模型在内存中保持多久，默认 5 分钟。设 "0" 表示用完立刻卸载

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

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

配置方法：

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

API Key 安全管理

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

绝对不要做的事

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

推荐的做法

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

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

# 然后 source 一下
source ~/.bashrc

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

OpenClaw 源码验证的环境变量列表：

环境变量 提供商
OPENAI_API_KEY OpenAI
ANTHROPIC_API_KEY Anthropic
ANTHROPIC_OAUTH_TOKEN Anthropic（OAuth 认证）
GEMINI_API_KEY Google Gemini
ZAI_API_KEY xAI (Grok)
OPENROUTER_API_KEY OpenRouter
AI_GATEWAY_API_KEY AI Gateway
MINIMAX_API_KEY MiniMax
ELEVENLABS_API_KEY ElevenLabs

方法二：用 .env 文件

# 在项目根目录创建 .env 文件
OPENAI_API_KEY=sk-proj-xxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxx

# 务必把 .env 加入 .gitignore
echo ".env" >> .gitignore

方法三：用系统密钥管理器

macOS 用 Keychain，Linux 用 secret-tool，Windows 用凭据管理器。具体命令参考各系统文档。

Key 轮换

定期轮换 API Key 是好习惯。流程：在提供商控制台创建新 Key -> 更新环境变量或配置文件 -> 用 openclaw models status 确认新 Key 工作正常 -> 删除旧 Key。

模型选择策略

💡 不知道选什么模型？ 看这一节就够了，帮你根据预算和需求选最合适的

不同场景用不同模型，既省钱又高效。

按场景选模型

下表中的"token"（AI 处理文本的基本单位，大约 1 个汉字 = 2 个 token）是 AI 计费的常用单位。

场景 推荐模型 理由 大约成本
日常闲聊 GPT-5.2-mini / Haiku 4.5 便宜快速，够用 ~$0.15/百万 token
复杂推理 Claude Opus 4.6 / o3 最强推理能力 ~$15/百万 token
编程辅助 Claude Sonnet 4.6 / Codex 编程能力最强 ~$3/百万 token
中文场景 Qwen-Max / Kimi-Max 中文理解优化 按各家定价
隐私优先 Ollama + Llama3.1 数据不出本地 免费（电费除外）
多模态 Gemini 3.1 / GPT-5.2 图片视频理解 ~$2.5/百万 token
预算有限 OpenRouter / DeepSeek 按需选最便宜的 ~$0.1-1/百万 token
超长文本 Gemini 2.5 Pro / Qwen-Long 百万级上下文 按各家定价

按 Agent 角色分配模型

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

{
  // 默认模型
  agent: {
    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"
}

简单任务用便宜模型省钱，关键任务用强模型保质量，中文任务用中文优化模型效果更好，内部任务用本地模型保隐私。

模型参数调优

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

模型的输出风格可以通过参数来调整。这些参数在配置文件的 modelSettings 中设置。

核心参数详解

{
  agent: {
    model: "anthropic/claude-sonnet-4-6",
    modelSettings: {
      temperature: 0.7,
      topP: 0.9,
      maxTokens: 4096,
      frequencyPenalty: 0.0,
      presencePenalty: 0.0,
      stopSequences: [],
    },
  },
}

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

配置示例：

{
  agent: {
    model: "anthropic/claude-sonnet-4-6",
    modelFallback: [
      "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 费用失控？设置使用限制：

{
  agent: {
    usageTracking: {
      enabled: true,
      dailyLimit: 5.00,
      monthlyLimit: 50.00,
      currency: "USD",
      alertThreshold: 0.8,
    },
  },
}
  • dailyLimit：每日费用上限
  • monthlyLimit：每月费用上限
  • alertThreshold：达到上限的 80% 时发出警告

查看模型状态：

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

Token 限制

除了费用限制，还可以限制单次对话的 Token 用量：

{
  agent: {
    tokenLimits: {
      maxInputTokens: 100000,
      maxOutputTokens: 4096,
      maxTotalTokens: 128000,
    },
  },
}

省钱技巧

  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 等）。配置方法：

{
  providers: {
    custom: {
      type: "openai-compatible",
      baseUrl: "http://your-server:8000/v1",
      apiKey: "your-key-if-needed",
      models: [
        {
          id: "my-custom-model",
          name: "My Custom Model",
          contextWindow: 32768,
          maxOutputTokens: 4096,
        },
      ],
    },
  },
}

然后就可以用了：

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

多个自定义服务

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

{
  providers: {
    "gpu-server-1": {
      type: "openai-compatible",
      baseUrl: "http://192.168.1.100:8000/v1",
    },
    "gpu-server-2": {
      type: "openai-compatible",
      baseUrl: "http://192.168.1.101:8000/v1",
    },
  },
}

常见配置问题排查

问题：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"）。也可以在 ~/.openclaw/openclaw.json 中增加超时时间。

问题：模型不存在

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

问题：本地模型太慢

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