在使用 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 的地址，比如本地服务的
https://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 https://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。
各字段含义如下表：
| 字段 | 说明 | 示例 |
|---|---|---|
baseUrl | API 基础 URL。留空则使用 OpenClaw 默认的 OpenAI 地址。 | "https://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 运行一个本地模型，服务地址为 https://localhost:1234/v1。在 openclaw.json 中添加如下配置：
{
"models": {
"providers": {
"lmstudio": {
"baseUrl": "https://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，玩法的可能性一下子开阔了许多。
