OpenClaw如何自定义模型供应商（Custom Provider）？图文教程

在使用 OpenClaw 的过程中，除了其内置支持的众多模型供应商（Provider）外，我们常常需要连接一些特殊的服务，例如公司内部的推理接口、本地部署的模型服务（如 Ollama、LM Studio），或是一些新兴的云端模型平台。OpenClaw 提供了强大的自定义模型供应商功能，允许用户灵活地扩展其模型库。

本文将详细介绍两种为 OpenClaw 添加自定义模型供应商的方法：通过命令行向导快速添加，以及通过手动编辑配置文件进行深度定制。

OpenClaw 交流群

如果你也在折腾 OpenClaw，或者对 AI Agent、自动化工具感兴趣，欢迎加入以下交流群。一起交流使用经验、分享自动化玩法、讨论最新进展。

使用向导快速添加

对于初学者或追求效率的场景，使用 OpenClaw 的命令行向导 openclaw onboard 是最直接的方式。该工具会以交互式问答的形式引导你完成配置，无需手动编写 JSON 文件。

交互式设置

打开你的终端，执行以下命令来启动配置向导：

openclaw onboard

在向导的「Model and auth」步骤中，会列出多种模型供应商选项。请选择 Custom provider 选项。

接下来，向导会要求你提供几个关键信息来定义新的模型供应商：

Provider ID（Endpoint ID）: 自定义供应商的唯一标识符，例如 my-local-llm。
Base URL: 模型服务的 API 接入点地址，例如 http://localhost:1234/v1。
Model ID: 你要使用的具体模型的 ID，例如 llama3-8b。
API Key: 用于访问服务的 API 密钥。如果你的服务不需要认证，可以输入任意字符，例如 none。
Compatibility: 指定该服务兼容的 API 格式，通常是 openai 或 anthropic。对于绝大多数模型服务，选择 openai 即可。

完成这些步骤后，向导会自动将配置写入 openclaw.json 文件中，省去了手动编辑的麻烦。

非交互式命令

如果需要在脚本中自动化配置，或者你已经清楚所有配置参数，可以使用非交互式命令一次性完成设置。这对于批量部署或自动化环境搭建非常有用。

例如，要添加一个在本地 8000 端口运行的、兼容 OpenAI API 的模型服务，可以执行以下命令：

openclaw onboard \
  --auth-choice custom-api-key \
  --custom-provider-id my-local-model \
  --custom-base-url http://localhost:8000/v1 \
  --custom-model-id deepseek-coder-v2 \
  --custom-api-key "your-api-key-if-needed" \
  --custom-compatibility openai

这条命令直接指定了所有必要信息，执行后即可完成自定义供应商的添加。

手动编辑配置文件

虽然命令行向导很方便，但它只支持添加基础配置。如果需要更精细的控制，比如为同一个供应商定义多个模型、设置模型的上下文窗口大小、调整参数等，就需要手动编辑 OpenClaw 的核心配置文件。

该配置文件通常位于 ~/.openclaw/openclaw.json。在编辑之前，建议先备份此文件。

理解 `models.providers` 结构

打开 openclaw.json 文件，找到或添加一个名为 models 的顶级字段，并在其中创建 providers 对象。所有的自定义供应商都将在这里定义。

一个基本的供应商配置结构如下：

{
  "models": {
    "providers": {
      "my-provider": {
        "baseUrl": "https://api.example.com/v1",
        "apiKey": "${MY_PROVIDER_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "model-a",
            "name": "Model A"
          }
        ]
      }
    }
  }
}

这里的 "my-provider" 就是你的自定义供应商 ID，后续在引用模型时会用到，格式通常为 my-provider/model-a。

下表解释了供应商配置中的核心字段：

字段 (Field)	说明	示例 (Example)
`baseUrl`	模型服务的 API 基础 URL。如果留空，将使用 OpenClaw 默认的 OpenAI 地址。	`"http://localhost:1234/v1"`
`apiKey`	用于身份验证的 API 密钥。推荐使用 `${ENV_VAR}` 的形式从环境变量中读取，以保证安全。	`"${MY_API_KEY}"`
`api`	指定该供应商使用的 API 规范，决定了 OpenClaw 如何构造请求。常见值为 `openai-completions` 或 `anthropic-messages`。	`"openai-completions"`
`models`	一个数组，用于定义该供应商下的一个或多个具体模型。	`[{ "id": "model-a", ... }]`
`providerAuthEnvVars`	（可选）一个数组，声明该供应商依赖的环境变量。这有助于 OpenClaw 在不加载插件的情况下进行身份验证探测。	`["MY_API_KEY", "MY_SECRET"]`

配置实战：连接本地模型服务

让我们来看一个更完整的例子。假设你正在使用 LM Studio 运行一个本地模型，其服务地址是 http://localhost:1234/v1。我们希望在 OpenClaw 中添加这个服务。

可以在 openclaw.json 中添加如下配置：

{
  "models": {
    "providers": {
      "lmstudio": {
        "baseUrl": "http://localhost:1234/v1",
        "apiKey": "lmstudio-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "minimax-m2.5-gs32",
            "name": "MiniMax M2.5 (Local)",
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "lmstudio/minimax-m2.5-gs32"
      }
    }
  }
}

在这个例子中，我们定义了一个名为 lmstudio 的供应商。

定义模型属性

在 models 数组中，我们可以为每个模型定义详细的属性。这些属性会告诉 OpenClaw 如何与该模型交互。

id: 模型的唯一 ID，在 baseUrl 的 API 范围内必须是有效的。
name: 模型的显示名称，会在 OpenClaw 的界面中展示。
contextWindow: 模型支持的最大上下文长度。
maxTokens: 单次请求能生成的最大 token 数量。
reasoning: 模型是否支持 OpenClaw 的 "reasoning"（思考）过程。本地模型通常设置为 false。
input: 模型支持的输入类型，通常是 ["text"]。
cost: 定义模型的使用成本，对于本地免费模型，可以全部设置为 0。

当这些可选字段被省略时，OpenClaw 会使用一组默认值。为了获得最佳兼容性和性能，建议根据你所使用模型的实际能力，明确地设置这些值。

验证配置

无论你使用哪种方法添加了自定义供应商，最后一步都是验证配置是否生效。

执行以下命令可以列出 OpenClaw 当前识别到的所有模型：

openclaw models list

如果配置正确，你应该能在列表中看到你刚刚添加的供应商和模型。

确认模型可用后，你可以使用 openclaw models set 命令将其设置为默认模型，以便在日常工作中直接使用，例如：

openclaw models set lmstudio/minimax-m2.5-gs32

通过以上步骤，你就可以轻松地将任何兼容 OpenAI 或 Anthropic API 的模型服务接入 OpenClaw，极大地扩展其应用边界。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、API 调试、API 设计、API 测试、API Mock、自动化测试等功能于一体的 API 管理工具，Apifox 可以说是开发者提升效率的必备工具之一。

如果你正在开发项目需要进行接口调试，不妨试试 Apifox。注册过程非常简单，你可以直接在这里注册使用。

立即体验 Apifox

注册成功后可以先看看官方提供的示例项目，这些案例都是经过精心设计的，能帮助你快速了解 Apifox 的主要功能。

使用 Apifox 的一大优势是它完全兼容 Postman 和 Swagger 数据格式，如果你之前使用过这些工具，数据导入会非常方便。而且它的界面设计非常友好，即使是第一次接触的新手也能很快上手，快去试试吧！

免费使用 Apifox

OpenClaw如何自定义模型供应商（Custom Provider）？图文教程