OpenClaw自定义模型供应商Custom Provider图文教程

在使用 OpenClaw 的过程中，除了它内置支持的模型供应商外，我们经常需要接入一些特殊的服务——比如公司内部的推理接口、本地运行的 Ollama 或 LM Studio，甚至是尚未进入官方列表的新兴云端平台。好在 OpenClaw 预留了自定义模型供应商的入口，能够非常灵活地将这些外部模型纳入其管理范围。

下面系统拆解一下，如何通过两种方式为 OpenClaw 添加自定义供应商：一种是适合快速上手的命令行向导，另一种则是深度玩家偏爱的手动配置文件编辑。

使用向导快速添加

如果你是刚接触 OpenClaw，或者单纯图个省事，直接使用 openclaw onboard 这个命令是最快的。它会像一位耐心的向导，一步步向你提问，你只需回答，剩下的工作它自动完成。

交互式设置

打开终端，输入：

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：如果服务不需要认证，随便填个占位符即可，比如 none。
• Compatibility：API 格式兼容性，绝大多数情况选择 openai 就对了。

完成后，向导会自动把这些配置写入 openclaw.json 文件，无需手动操作 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.json 进行手动编辑。动手之前，建议先备份原文件，防止误操作。

理解 models.providers 结构

打开 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。

各字段含义如下表：

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

假设你正在用 LM Studio 运行一个本地模型，服务地址为 http://localhost:1234/v1。在 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 的“思考”过程，本地模型通常设为 false。
• input：输入类型，一般为 ["text"]。
• cost：成本定义，本地免费模型全部设为 0 即可。

如果省略这些字段，OpenClaw 会使用默认值。为了获得最佳兼容性，建议根据模型的实际能力，把能够设置的参数都配置上。

验证配置

无论你使用的是哪种方法，最后一步都是确认配置是否正确生效。执行：

openclaw models list

如果一切正常，列表中就会出现你刚刚添加的供应商和模型。确认模型可用后，可以使用 openclaw models set 将其设为默认模型，例如：

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

这样一来，任何兼容 OpenAI 或 Anthropic API 的模型服务都可以接入 OpenClaw，玩法的可能性一下子开阔了许多。