OpenClaw 自定义模型提供商教程

本教程将手把手教你如何在 OpenClaw 中配置自定义模型提供商，接入各种第三方 AI 模型服务。

📋 前置条件

在开始之前，请确保你已经：

安装并运行了 OpenClaw
拥有至少一个模型提供商的 API 密钥（如 PinCC、阿里云百炼、DeepSeek 等）

🧩 核心概念

OpenClaw 支持通过 models.providers 配置接入任意兼容 OpenAI / Anthropic / Google 协议的 API 端点，包括：

官方 API：Anthropic、OpenAI、Google Gemini
第三方中转：PinCC、硅基流动（SiliconFlow）等
国产大模型：阿里云百炼（Qwen）、DeepSeek、Moonshot（Kimi）、MiniMax
本地推理服务：Ollama、vLLM、LM Studio

支持的 API 协议

协议类型	适用场景
`anthropic-messages`	Anthropic Claude 系列及其兼容 API
`openai-completions`	OpenAI 及大多数兼容 OpenAI 协议的提供商
`openai-responses`	OpenAI Responses API
`google-generative-ai`	Google Gemini 系列

配置模式

models.mode 支持两种模式：

merge（默认）：自定义提供商与内置提供商共存
replace：完全禁用内置提供商，仅使用自定义配置

大多数情况下保持默认 merge 即可。

📁 配置文件位置

OpenClaw 的配置文件位于：

~/.openclaw/openclaw.json

目录结构如下：

~/.openclaw/
├── openclaw.json          # 核心配置文件
├── env                    # 环境变量 / API Key
├── backups/               # 配置备份
└── logs/                  # 日志文件

🔧 配置文件基本结构

一个完整的 openclaw.json 中模型提供商配置的基本结构如下：

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "提供商名称": {
        "baseUrl": "API 基础地址",
        "apiKey": "你的 API 密钥",
        "api": "协议类型",
        "models": [
          {
            "id": "模型ID",
            "name": "模型显示名称",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

Model 字段详解

每个模型对象支持以下字段：

字段	类型	说明
`id`	string	模型 ID（必填），需与提供商的模型标识完全一致
`name`	string	模型显示名称（必填）
`contextWindow`	number	上下文窗口大小（token 数）
`maxTokens`	number	最大输出 token 数
`reasoning`	boolean	是否为推理模型（某些模型需设为 `false`）
`input`	array	输入类型，如 `["text", "image"]`
`cost`	object	费用信息，包含 `input`/`output`/`cacheRead`/`cacheWrite`

📖 配置示例

示例一：PinCC（多模型聚合平台）

PinCC 支持同时接入 Claude、OpenAI 和 Gemini 系列模型，使用同一个 API 密钥。

第一步：获取 PinCC API 密钥

在控制面板中找到 API Keys 页面
点击 创建密钥，复制生成的密钥

第二步：配置 Claude 模型

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "pincc-claude": {
        "baseUrl": "你的PinCC中转地址",
        "apiKey": "你的PinCC令牌",
        "api": "anthropic-messages",
        "authHeader": true,
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "api": "anthropic-messages",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          },
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6",
            "api": "anthropic-messages",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          },
          {
            "id": "claude-haiku-4-5",
            "name": "Claude Haiku 4.5",
            "api": "anthropic-messages",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          }
        ]
      }
    }
  }
}

第三步：配置 OpenAI 模型（可选）

在 providers 下继续添加：

json

{
  "pincc-openai": {
    "baseUrl": "你的PinCC中转地址/v1",
    "apiKey": "你的PinCC令牌",
    "auth": "token",
    "api": "openai-responses",
    "authHeader": true,
    "models": [
      {
        "id": "gpt-5.4",
        "name": "gpt-5.4",
        "api": "openai-responses",
        "reasoning": false,
        "input": ["text"],
        "contextWindow": 128000,
        "maxTokens": 16384,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
      },
      {
        "id": "gpt-5.3-codex",
        "name": "gpt-5.3-codex",
        "api": "openai-responses",
        "reasoning": false,
        "input": ["text"],
        "contextWindow": 128000,
        "maxTokens": 16384,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
      },
      {
        "id": "gpt-5.2",
        "name": "gpt-5.2",
        "api": "openai-responses",
        "reasoning": false,
        "input": ["text"],
        "contextWindow": 128000,
        "maxTokens": 16384,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
      }
    ]
  }
}

第四步：配置 Google Gemini 模型（可选）

json

{
  "pincc-gemini": {
    "baseUrl": "你的PinCC中转地址/v1beta",
    "apiKey": "你的PinCC令牌",
    "auth": "token",
    "api": "google-generative-ai",
    "authHeader": true,
    "models": [
      {
        "id": "gemini-3.1-pro-preview",
        "name": "Gemini 3.1 Pro Preview",
        "api": "google-generative-ai",
        "reasoning": false,
        "input": ["text"],
        "contextWindow": 1000000,
        "maxTokens": 65536,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
      },
      {
        "id": "gemini-3-pro-preview",
        "name": "Gemini 3 Pro Preview",
        "api": "google-generative-ai",
        "reasoning": false,
        "input": ["text"],
        "contextWindow": 1000000,
        "maxTokens": 65536,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
      },
      {
        "id": "gemini-3-flash-preview",
        "name": "Gemini 3 Flash Preview",
        "api": "google-generative-ai",
        "reasoning": false,
        "input": ["text"],
        "contextWindow": 1000000,
        "maxTokens": 65536,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
      }
    ]
  }
}

示例二：阿里云百炼（Qwen 系列）

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "你的百炼API密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "Qwen 3.5 Plus",
            "contextWindow": 131072,
            "maxTokens": 8192,
            "reasoning": false
          },
          {
            "id": "qwen3-coder-next",
            "name": "Qwen 3 Coder Next",
            "contextWindow": 131072,
            "maxTokens": 8192,
            "reasoning": false
          }
        ]
      }
    }
  }
}

注意：百炼的模型需要将 reasoning 设为 false，否则可能导致回复内容为空。

示例三：DeepSeek

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "你的DeepSeek API密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "contextWindow": 65536,
            "maxTokens": 8192
          },
          {
            "id": "deepseek-reasoner",
            "name": "DeepSeek Reasoner",
            "contextWindow": 65536,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

示例四：Moonshot（Kimi）

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "apiKey": "你的Moonshot API密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

示例五：本地模型（Ollama）

如果你在本地运行 Ollama，也可以将其接入 OpenClaw：

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3:32b",
            "name": "Qwen3 32B (Local)",
            "contextWindow": 32768,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

⚙️ 设置默认模型

配置好提供商后，你可以设置每次新会话的默认模型。

在 openclaw.json 中添加或修改 agents 配置：

json

{
  "agents": {
    "defaults": {
      "maxConcurrent": 4,
      "model": {
        "primary": "pincc-claude/claude-sonnet-4-6"
      }
    }
  }
}

模型引用格式为 提供商ID/模型ID，例如：

pincc-claude/claude-opus-4-6
bailian/qwen3.5-plus
deepseek/deepseek-chat
ollama/qwen3:32b

模型选择建议

场景	推荐模型	理由
复杂编程任务	Claude Opus 4.6	最强综合能力
日常开发	Claude Sonnet 4.6	性价比最优
简单问答/轻量任务	Claude Haiku 4.6	快速响应、成本低
超长上下文	Gemini 3.1 Pro	百万级上下文窗口

✅ 验证配置

配置完成后，按以下步骤验证：

第一步：重启 OpenClaw Gateway

bash

openclaw gateway restart

第二步：查看已配置的模型

bash

openclaw models list --provider pincc-claude

第三步：发送测试消息

启动 OpenClaw，选择你配置的模型，发送一条测试消息确认能正常响应。

🔍 调试与排错

使用诊断命令

bash

openclaw doctor

该命令会检查配置文件语法、提供商连通性、模型可用性和认证状态。

常见问题

问题	解决方案
API 密钥无效	确认密钥已正确复制（无多余空格），账户余额充足
模型无法使用	检查 JSON 格式是否正确、模型 ID 是否准确
Gateway 无法启动	运行 `openclaw doctor` 检查配置语法
切换提供商后状态异常	删除 `~/.openclaw/agents/main/agent/models.json` 后重启
回复为空	部分模型（如百炼）需设置 `"reasoning": false`

调试技巧

推荐使用最小化配置法进行调试：

先用最小配置（baseUrl、apiKey、api 和一个仅含 id、name 的模型）
运行 openclaw models list --provider 你的提供商 验证连通性
确认基础配置可用后，再逐步添加其他模型和可选字段

⚠️ 注意事项

所有提供商的 apiKey 字段必须替换为你的实际密钥
不要直接修改 ~/.openclaw/agents/main/agent/models.json，它会被 openclaw.json 覆盖
修改 openclaw.json 后请勿全量覆盖，建议做局部修改
OpenClaw 调用模型时会携带较多上下文，Token 消耗可能较高，请关注用量与计费
配置解析器是严格的——多余的逗号、缺少引号或嵌套错误都会导致启动失败

OpenClaw 自定义模型提供商教程 ​

📋 前置条件 ​

🧩 核心概念 ​

支持的 API 协议 ​

配置模式 ​

📁 配置文件位置 ​

🔧 配置文件基本结构 ​

Model 字段详解 ​

📖 配置示例 ​

示例一：PinCC（多模型聚合平台） ​

示例二：阿里云百炼（Qwen 系列） ​

示例三：DeepSeek ​

示例四：Moonshot（Kimi） ​

示例五：本地模型（Ollama） ​

⚙️ 设置默认模型 ​

模型选择建议 ​

✅ 验证配置 ​

🔍 调试与排错 ​

使用诊断命令 ​

常见问题 ​

调试技巧 ​

⚠️ 注意事项 ​

💡 更多帮助 ​

OpenClaw 自定义模型提供商教程

📋 前置条件

🧩 核心概念

支持的 API 协议

配置模式

📁 配置文件位置

🔧 配置文件基本结构

Model 字段详解

📖 配置示例

示例一：PinCC（多模型聚合平台）

示例二：阿里云百炼（Qwen 系列）

示例三：DeepSeek

示例四：Moonshot（Kimi）

示例五：本地模型（Ollama）

⚙️ 设置默认模型

模型选择建议

✅ 验证配置

🔍 调试与排错

使用诊断命令

常见问题

调试技巧

⚠️ 注意事项

💡 更多帮助