OpenClaw 自定义模型供应商教程|对接 Ollama、LM Studio、企业内部接口

本系列第十一篇：突破官方限制——给“龙虾”装上任意第三方大脑，从本地私有模型到企业内部推理服务

在上一篇文章中，我们系统讲解了阿里云百炼、OpenAI、Kimi K2.5 等主流供应商的接入方法。这些内置供应商已经足够应对大多数日常场景。

但在真实使用中，你一定会遇到官方列表之外的模型服务。比如公司内部的私有推理接口、新出的实验性模型、LM Studio 本地部署的自研模型，或是任何兼容 OpenAI API 协议的自定义服务。

这正是 OpenClaw Custom Provider 功能的用武之地。它让你能够接入任何支持 OpenAI API 兼容协议的模型服务——无论是云端还是本地、官方还是自建、付费还是免费。

本文将系统讲解 自定义模型供应商的完整接入流程，覆盖从命令行向导、手动配置文件编辑，到 Ollama、LM Studio、SGLang 等主流本地推理引擎的实战配置，以及模型降级、故障切换等企业级高阶技巧。

一、什么是 Custom Provider？为什么要用？

OpenClaw 内置支持的模型供应商（如 OpenAI、Anthropic、阿里云百炼、Moonshot 等）覆盖了大部分主流选择。但当你需要接入以下服务时，就需要用到自定义供应商功能：

本地推理引擎：Ollama、LM Studio、llama.cpp、SGLang 等本地运行的模型服务
企业内部 API：公司自建的私有推理服务（兼容 OpenAI 协议）
新兴云平台：官方尚未内置集成的新兴模型平台，如硅基流动 (SiliconFlow)、NVIDIA NIM、DeepSeek API 等
自定义端点：任何兼容 OpenAI API 协议的第三方服务

Custom Provider 的本质是为 OpenClaw 提供一个“万能适配器”——只要目标模型服务提供了 OpenAI 兼容的 API 端点，就可以通过自定义配置接入。

⚠️ 关键约束：自定义模型仅支持 OpenAI 兼容协议的 API 地址。请确认你的目标服务提供了类似 https://api.example.com/v1 格式的端点，并支持 /v1/chat/completions 接口。绝大多数本地推理引擎（Ollama、LM Studio）都满足这一要求。

二、两种接入方式：向导 vs 手动配置

OpenClaw 提供了两种添加自定义供应商的方法，适用于不同使用场景。

2.1 方式一：通过 `openclaw onboard` 向导快速添加（推荐新手）

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

交互式设置步骤：

bash

openclaw onboard

在向导的「Model and auth」步骤中，选择 Custom provider 选项。向导会依次询问以下关键信息：

参数	说明	示例
Provider ID	自定义供应商的唯一标识符	`my-local-llm`
Base URL	模型服务的 API 接入点地址	`http://localhost:1234/v1`
Model ID	你要使用的具体模型的 ID	`llama3-8b`
API Key	访问服务的 API 密钥。无需认证可填任意字符	`none` 或 `local-key`
Compatibility	兼容的 API 格式，通常选择 `openai`	`openai`

完成这些步骤后，向导会自动将配置写入 ~/.openclaw/openclaw.json 文件。

非交互式命令（适合脚本化配置）：

如果需要在脚本中自动化配置，或者已经清楚所有配置参数，可以使用非交互式命令一次性完成设置：

bash

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

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

2.2 方式二：手动编辑配置文件（精细控制）

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

配置文件位置：

Linux/macOS：~/.openclaw/openclaw.json
Windows：C:\Users\用户名\.openclaw\openclaw.json

编辑前建议先备份此文件。

理解 models.providers 结构

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

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

json

{  "models": {    "providers": {      "my-provider": {        "baseUrl": "https://api.example.com/v1",        "apiKey": "{MY_API_KEY}

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

核心字段说明：

字段	说明	示例
`baseUrl`	模型服务的 API 基础 URL	`http://localhost:1234/v1`
`apiKey`	API 密钥。建议使用环境变量引用	`${MY_API_KEY}`
`api`	API 协议类型	`"openai-completions"` 或 `"openai-responses"`
`models`	模型列表数组	见下方
`models[].id`	模型唯一标识，必须与服务返回一致	`"llama3-8b"`
`models[].name`	UI 中显示的模型名称	`"Llama 3 8B"`
`models[].contextWindow`	上下文窗口大小（Token 数）	`8192`
`models[].maxTokens`	单次最大输出 Token 数	`8192`

三、场景一：Ollama 本地模型集成

Ollama 是当前最受欢迎的本地 LLM 运行时，OpenClaw 与其原生 API 深度集成，支持流式输出和工具调用，并且可以自动发现支持工具调用的模型。

3.1 准备工作：安装 Ollama 并拉取模型

bash

# 安装 Ollama（macOS 使用 Homebrew）brew install ollama# 或访问 https://ollama.com/download 下载其他平台安装包# 拉取推荐模型（支持工具调用）ollama pull gpt-oss:20b      # 高质量开源模型，工具调用支持完善ollama pull llama3.3         # Meta 最新开源模型ollama pull qwen2.5-coder:32b  # 专为编码优化的模型ollama pull deepseek-r1:32b  # 推理模型# 查看已下载的模型列表ollama list

关于本地模型的硬件要求：OpenClaw 推荐使用尽可能大的完整尺寸模型，避免使用过度量化的“small”变体，量化程度过高会削弱安全防护能力。建议至少配备能够运行 20B 以上模型的硬件环境。

3.2 方式一：自动发现（最推荐，零配置）

OpenClaw 能够自动检测并加载本地 Ollama 实例中的所有支持工具调用的模型，无需手动配置模型列表。

启用自动发现只需设置一个环境变量。Ollama 的本地服务不需要真实的 API 密钥，任意字符串均可：

bash

export OLLAMA_API_KEY="ollama-local"

如果 Ollama 运行在其他主机或端口上，可以通过环境变量指定：

bash

export OLLAMA_HOST="http://192.168.1.100:11434"export OLLAMA_API_KEY="ollama-local"

设置完成后，OpenClaw 会自动：

连接到本地 Ollama 实例（默认 http://127.0.0.1:11434）

调用 /api/tags 和 /api/show 获取模型信息

仅保留报告支持 tools 功能的模型

从 model_info 读取上下文窗口大小

将 maxTokens 设置为上下文窗口的 10 倍

所有费用设为 0（本地运行免费）

验证自动发现是否生效：

bash

openclaw models list

    你应该能看到所有本地 Ollama 模型出现在列表中。新拉取的模型也会自动被 OpenClaw 发现。

3.3 方式二：显式配置（适合远程 Ollama 或精细化控制）

以下场景需要使用显式配置：

Ollama 运行在其他主机/端口上

需要强制指定特定的上下文窗口或模型列表

需要包含不支持工具调用的模型

需要禁用自动发现功能

显式配置示例：

json

{  "models": {    "providers": {      "ollama": {        "baseUrl": "http://127.0.0.1:11434/v1",        "apiKey": "ollama-local",        "api": "openai-completions",        "models": [          {            "id": "llama3.3",            "name": "Llama 3.3",            "reasoning": false,            "input": ["text"],            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },            "contextWindow": 8192,            "maxTokens": 81920          }        ]      }    }  }}

⚠️ 重要提醒：如果你显式设置了 models.providers.ollama，自动发现功能会被跳过，你必须手动定义所有希望使用的模型。

3.4 使用 Ollama 模型

配置完成后，将默认模型设置为 Ollama 模型：

json

{  "agents": {    "defaults": {      "model": {        "primary": "ollama/llama3.3"      }    }  }}

添加新模型只需通过 Ollama 拉取，OpenClaw 会自动发现（前提是未显式配置 providers）：

bash

ollama pull mistralopenclaw models list | grep mistral   # 自动发现并可用

四、场景二：LM Studio 本地模型集成

LM Studio 是另一种流行的本地模型推理工具，提供图形化界面和 OpenAI 兼容的 API 服务器。OpenClaw 官方文档将其列为推荐的本地部署方案。

4.1 准备工作：安装 LM Studio 并加载模型

从 lmstudio.ai 下载并安装 LM Studio
在 LM Studio 中下载一个本地模型（建议使用你能运行的最大模型构建，避免“small”或重度量化变体）
点击 "Start Server" 启动本地服务器（默认端口：1234）
确认模型已成功加载：curl http://127.0.0.1:1234/v1/models
让模型保持在已加载状态——冷加载会增加启动延迟

4.2 完整配置步骤

LM Studio 的集成涉及配置文件中的两处关键配置——模型参数定义和 UI 下拉注册，两者缺一不可。

步骤一：查询 LM Studio 当前加载的模型

LM Studio 启动后，通过标准 OpenAI 接口查询已加载模型列表：

bash

curl http://127.0.0.1:1234/v1/models

返回示例：

json

{  "data": [    { "id": "openai/gpt-oss-20b", "object": "model" },    { "id": "google/gemma-3-27b", "object": "model" },    { "id": "meta-llama-3.1-8b-instruct-128k", "object": "model" }  ]}

把所有 id 记录下来，后续配置要用到。id 字段必须与 LM Studio 返回的完全一致，包括大小写和斜杠。

步骤二：配置 models.providers（定义模型参数）

打开 ~/.openclaw/openclaw.json，找到 models.providers 部分，为每个模型添加配置。官方推荐使用 openai-responses API 类型，这样可以保持推理过程与最终文本分离：

json

{  "models": {    "mode": "merge",    "providers": {      "lmstudio": {        "baseUrl": "http://127.0.0.1:1234/v1",        "apiKey": "lmstudio",        "api": "openai-responses",        "models": [          {            "id": "openai/gpt-oss-20b",            "name": "GPT-OSS 20B",            "reasoning": false,            "input": ["text"],            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },            "contextWindow": 32000,            "maxTokens": 8192          },          {            "id": "google/gemma-3-27b",            "name": "Gemma 3 27B",            "reasoning": false,            "input": ["text"],            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },            "contextWindow": 8192,            "maxTokens": 8192          }        ]      }    }  }}

步骤三：配置 agents.defaults.models（让模型出现在 UI 下拉中）

OpenClaw 的模型注册机制需要同时维护两处配置——只配第一处，模型能被调用但不出现在 UI；只配第二处，模型会出现但缺少参数定义：

json

{  "agents": {    "defaults": {      "model": {        "primary": "lmstudio/openai/gpt-oss-20b"      },      "models": {        "lmstudio/openai/gpt-oss-20b": { "alias": "GPT-OSS" },        "lmstudio/google/gemma-3-27b": { "alias": "Gemma" }      }    }  }}

4.3 验证配置是否完整

使用以下命令验证模型是否正确注册：

bash

pnpm openclaw models list

当 Tags 列出现 configured 时，说明两处配置都已正确设置，模型可以正常使用。

五、场景三：SGLang 提供商配置

SGLang 是一个用于服务开源模型的运行时，可以通过兼容 OpenAI 的 HTTP API 来托管模型。

5.1 快速开始

启动 SGLang 并开启兼容 OpenAI 的服务端，确保基础 URL 暴露 /v1 端点（如 /v1/models、/v1/chat/completions）。SGLang 通常运行在 http://127.0.0.1:30000/v1。

5.2 自动发现（推荐）

bash

# 设置 API Key（服务器未配置鉴权时任意值均可）export SGLANG_API_KEY="sglang-local"

当 SGLANG_API_KEY 已设置且未定义 models.providers.sglang 时，OpenClaw 会自动调用 GET http://127.0.0.1:30000/v1/models，将返回的模型 ID 转换为模型条目。

5.3 显式配置（手动模型）

以下场景需要使用显式配置：

SGLang 运行在其他主机/端口上

需要固定 contextWindow/maxTokens 的值

服务器需要真实的 API 密钥

json

{  "models": {    "providers": {      "sglang": {        "baseUrl": "http://127.0.0.1:30000/v1",        "apiKey": "${SGLANG_API_KEY}",        "api": "openai-completions",        "models": [          {            "id": "your-model-id",            "name": "Local SGLang Model",            "reasoning": false,            "input": ["text"],            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },            "contextWindow": 128000,            "maxTokens": 8192          }        ]      }    }  }}

5.4 故障排查

bash

# 检查服务器是否可访问curl http://127.0.0.1:30000/v1/models

如果请求因鉴权错误失败，请设置与服务器配置匹配的真实 SGLANG_API_KEY。

六、高级配置：模型混合部署与故障切换

OpenClaw 支持同时配置多个模型，并设置了智能的故障切换机制。当主模型超限或不可用时，系统会自动切换到备用模型。

6.1 配置主模型和降级模型

json

{  "agents": {    "defaults": {      "model": {        "primary": "ollama/llama3.3",        "fallbacks": ["bailian/qwen-plus", "openai/gpt-4o-mini"]      }    }  },  "models": {    "mode": "merge"  }}

配置逻辑解析：primary 定义主用模型，OpenClaw 优先调用；fallbacks 定义降级模型列表，当主模型遇到限流、配额超限等错误时自动按顺序尝试列表中的下一个模型。

6.2 混合配置：云端主模型 + 本地降级

json

{  "agents": {    "defaults": {      "model": {        "primary": "anthropic/claude-sonnet-4-5",        "fallbacks": ["lmstudio/my-local-model", "anthropic/claude-opus-4-5"]      }    }  },  "models": {    "mode": "merge",    "providers": {      "lmstudio": {        "baseUrl": "http://127.0.0.1:1234/v1",        "apiKey": "lmstudio",        "api": "openai-responses",        "models": [          {            "id": "my-local-model",            "name": "Local Model",            "reasoning": false,            "input": ["text"],            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },            "contextWindow": 196608,            "maxTokens": 8192          }        ]      }    }  }}

models.mode: "merge" 让备用方案保持可用，确保云端模型不可用时，本地模型可以无缝接管。

6.3 本地优先 + 云端兜底

如果你以本地模型为主要选择，云端作为安全网，只需调换主模型和降级模型的顺序，保持相同的 providers 配置和 models.mode: "merge" 即可。

七、完整配置示例汇总

示例一：Ollama 自动发现（最简单，推荐新手）

bash

# 终端中设置环境变量export OLLAMA_API_KEY="ollama-local"

在 ~/.openclaw/openclaw.json 中设置默认模型

{  "agents": {    "defaults": {      "model": {        "primary": "ollama/llama3.3"      }    }  }}

示例二：LM Studio 完整配置（支持多模型热切换）

json

{  "models": {    "mode": "merge",    "providers": {      "lmstudio": {        "baseUrl": "http://127.0.0.1:1234/v1",        "apiKey": "lmstudio",        "api": "openai-responses",        "models": [          {            "id": "openai/gpt-oss-20b",            "name": "GPT-OSS 20B",            "reasoning": false,            "input": ["text"],            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },            "contextWindow": 32000,            "maxTokens": 8192          }        ]      }    }  },  "agents": {    "defaults": {      "model": {        "primary": "lmstudio/openai/gpt-oss-20b",        "fallbacks": ["bailian/qwen-plus"]      },      "models": {        "lmstudio/openai/gpt-oss-20b": { "alias": "GPT-OSS" }      }    }  }}

示例三：企业自定义 API 接入（硅基流动）

硅基流动提供了兼容 OpenAI 协议的服务，可以通过自定义供应商配置接入：

json

{  "models": {    "providers": {      "siliconflow": {        "baseUrl": "https://api.siliconflow.cn/v1",        "apiKey": "${SILICONFLOW_API_KEY}",        "api": "openai-completions",        "models": [          {            "id": "deepseek-ai/DeepSeek-V3.2",            "name": "DeepSeek V3.2"          }        ]      }    }  },  "agents": {    "defaults": {      "model": {        "primary": "siliconflow/deepseek-ai/DeepSeek-V3.2"      }    }  }}

八、常见问题与排查

问题	可能原因	解决方案
配置后 `/model` 命令看不到模型	只配置了 `models.providers` 未配置 `agents.defaults.models`	在 `agents.defaults.models` 中添加模型引用
`openclaw models list` 中模型没有 `configured` 标签	模型参数定义或注册不完整	检查配置文件，确保 `models.providers.models` 中的 `id` 与引用格式一致
Ollama 自动发现不生效	未设置 `OLLAMA_API_KEY` 或显式定义了 `models.providers.ollama`	设置环境变量，并删除或注释掉显式配置
Ollama 工具调用失败	使用了 OpenAI 兼容 URL（含 `/v1`）	使用原生 API URL `http://host:11434`（不加 `/v1`）
LM Studio 模型不被 OpenClaw 识别	`id` 与 `/v1/models` 返回的 `id` 不一致	用 `curl http://127.0.0.1:1234/v1/models` 获取准确 `id` 后复制到配置中
Gateway 启动失败，配置相关错误	配置文件不符合 JSON5 格式	检查是否有遗漏的逗号或引号，使用 `openclaw doctor --repair` 自动修复
模型上下文不够用	`contextWindow` 设置过小	Agent 任务建议至少 32k-64k，根据模型实际能力调大
模型响应异常缓慢	本地模型硬件资源不足或冷加载	保持模型处于已加载状态，避免冷启动延迟

九、最佳实践建议

自动发现优先：Ollama 和 SGLang 等本地引擎优先使用自动发现，避免手动维护模型列表的麻烦
模型参数精细化：手动配置时正确设置 contextWindow 和 maxTokens，Agent 任务需要较大上下文窗口
混合部署降级：配置云端模型作为本地模型的降级选项，确保 AI 服务不中断
安全存储 API Key：使用环境变量引用 API Key，不要硬编码在配置文件中
配置验证：修改配置后执行 openclaw doctor 自动检查健康状态
备份配置文件：修改 openclaw.json 前先备份，出现问题可快速回滚

十、下一步做什么？

恭喜！你的 OpenClaw 已经可以接入任何兼容 OpenAI 协议的第三方模型服务。接下来可以根据需要继续探索：

第 12 篇：OpenClaw 配置文件深度解析——搞懂 7 个核心文件，让 AI 从“傻白甜”变“智能助手”
第 14-18 篇：技能开发——从零创建自己的 Skills 和 Plugins
第 19-22 篇：多平台集成——微信、飞书、Telegram 等渠道接入
第 27 篇：安全配置指南——沙箱隔离、执行审批与权限最小化最佳实践

💡 最终提醒：自定义模型供应商是 OpenClaw 最强大的扩展能力之一。它让 OpenClaw 不仅是一个“开箱即用”的工具，更是一个“海纳百川”的 AI 执行平台。从本地私有模型到企业自建服务，只要兼容 OpenAI 协议，OpenClaw 就能接入使用。善用这一能力，你的“龙虾”将拥有真正无限的可能性。

一、什么是 Custom Provider？为什么要用？

二、两种接入方式：向导 vs 手动配置

2.1 方式一：通过 openclaw onboard 向导快速添加（推荐新手）

2.2 方式二：手动编辑配置文件（精细控制）

三、场景一：Ollama 本地模型集成

三、场景一：Ollama 本地模型集成

3.1 准备工作：安装 Ollama 并拉取模型

3.2 方式一：自动发现（最推荐，零配置）

3.3 方式二：显式配置（适合远程 Ollama 或精细化控制）

3.4 使用 Ollama 模型

四、场景二：LM Studio 本地模型集成

4.1 准备工作：安装 LM Studio 并加载模型

4.2 完整配置步骤

4.3 验证配置是否完整

五、场景三：SGLang 提供商配置

5.1 快速开始

5.2 自动发现（推荐）

5.3 显式配置（手动模型）

5.4 故障排查

六、高级配置：模型混合部署与故障切换

6.1 配置主模型和降级模型

6.2 混合配置：云端主模型 + 本地降级

6.3 本地优先 + 云端兜底

七、完整配置示例汇总

示例一：Ollama 自动发现（最简单，推荐新手）

示例二：LM Studio 完整配置（支持多模型热切换）

示例三：企业自定义 API 接入（硅基流动）

八、常见问题与排查

九、最佳实践建议

十、下一步做什么？

2.1 方式一：通过 `openclaw onboard` 向导快速添加（推荐新手）