最近好几个同事和群友都在问同一个问题：OpenClaw 里跑着的智能体，怎么才能调上本地 Ollama、LM Studio 里的模型，又能接到企业内部已经封装好的模型网关？OpenClaw 默认配置里通常只给了几个现成的公有云供应商，复制一行 base_url 就能切过去，但换成本地模型或者企业内部接口时，只改地址远远不够，还要处理鉴权、模型名映射、请求路径，甚至响应格式这些细节。这篇文章把这条链路从配置结构到踩坑实录完整捋一遍，适合正在做私有化部署，或者想把模型能力统一收口到公司网关的开发者参考。
1. 自定义模型供应商的整体设计思路
1.1 为什么要自己接供应商，而不是直接用默认配置
默认配置之所以好用，是因为它把很多变量都压死了：请求路径、鉴权方式、模型名规则都已经跟对方的服务对齐。你用的时候只需要选一个模型名，剩下的框架帮你搞定。但实际落地时，你会很快发现默认配置根本不够用。
第一个场景是本地模型。公司内部做知识库问答或者代码辅助，数据不能出内网，模型只能跑在本地机器上。Ollama、LM Studio 这类本地推理工具就是最常见的底座，它们都有自己的 HTTP 接口，但接口路径、模型命名和默认公有云不完全一样。第二个场景是企业内部封装好的模型网关。有些团队会把多个模型统一接进自己的网关，对外只暴露一个地址，由网关做路由、限流、审计。这种情况下，OpenClaw 既要能连上网关，又不能绕过网关的签名和租户隔离逻辑。第三个场景是成本控制。把部分简单任务切到本地小模型，复杂任务才走云端大模型，前提就是同一个 OpenClaw 里能同时挂多个供应商，并且按需求切换。
所以自定义供应商本质上不是“改个地址”的小事，而是要理解 OpenClaw 怎么抽象一次模型调用：配置里描述好“去哪里、用什么身份、传什么参数、怎么解析结果”，剩下的事情交给框架。把这个抽象关系想明白，后面接任何供应商都只是填表。
1.2 OpenClaw 的供应商抽象模型
我在实际配置 OpenClaw 时，发现它把所有模型供应商都抽象成几个核心字段：端点地址、鉴权信息、模型列表、请求模板、响应解析方式。看起来很复杂，但拆开后就一句话：一次大模型调用就是一个 HTTP 请求，供应商配置就是告诉 OpenClaw 怎么构造和发送这个请求，以及怎么读取返回内容。
端点地址通常包括协议、主机、端口和路径前缀。比如本地 Ollama 默认开在 11434 端口，LM Studio 默认开在 1234 端口，企业内部网关则可能是公司域名下的一个特殊路径。鉴权信息常见的三种：不需要鉴权、静态 Token、动态签名 Header。模型列表决定你能在智能体里选择哪些模型名称，OpenClaw 一般会用它做自动补全和校验。
请求模板和响应解析是很多人忽略的部分。本地工具一般兼容行业通用的 Completions 接口格式，但企业内部网关可能对请求字段有额外要求，比如要带租户 ID、要传业务链路 ID，返回体也可能包了一层自己的结构。如果 OpenClaw 提供了自定义请求头和响应解析的入口，你就需要在配置里把这些都写清楚。没有这个入口的版本，就得在网关前面加一层轻量转换服务。
1.3 三种典型接入场景对比
| 场景 | 典型形态 | 接入难度 | 适合人群 |
|---|---|---|---|
| Ollama 本地模型 | 命令行工具，默认 HTTP 服务在 11434 端口 | 低，配置少 | 个人开发者、想跑私有化模型的人 |
| LM Studio 本地模型 | 图形化客户端，内置 Local Server 功能 | 低，但路径和模型名有细节 | 想快速验证模型效果、不熟悉命令行的用户 |
| 企业内部接口 | 公司统一的推理网关或内部服务 | 中高，需要处理鉴权和网络策略 | 生产环境、多团队协作场景 |
从表格能看出来，接入难度主要不取决于工具本身，而取决于你要不要处理鉴权、网络、协议兼容这些问题。本地工具基本不需要鉴权，所以配置最简单。企业内部接口因为要跟现有基础设施打通，反而常常花掉最多时间。我建议先接好 Ollama 或 LM Studio，把整个链路跑通，再去碰企业内部接口，排查问题的时候至少能确定本地服务本身是正常的。
2. 对接 Ollama：最省心的本地模型接入
2.1 Ollama 侧的准备
Ollama 安装好之后，默认会启动一个本地服务，监听 11434 端口。不要急着去 OpenClaw 里配，先把 Ollama 自己的接口验证一遍。
打开终端，执行ollama list看看本地已经拉了哪些模型。如果还没有模型，先用ollama pull拉一个体积适中的模型，比如 7B 或 8B 级别的量化版本。然后执行curl http://127.0.0.1:11434/api/tags，能看到本地模型列表的 JSON 返回。这一步确认服务活着，后边 OpenClaw 连不上时，能快速判断是 Ollama 的问题还是 OpenClaw 配置的问题。
Ollama 默认只监听本机地址，如果你想在局域网内其他机器上通过 OpenClaw 访问，需要额外设置。在 Linux 上通常是修改环境变量OLLAMA_HOST=0.0.0.0，然后重启服务。Windows 和 macOS 可以通过系统环境变量或者启动脚本设置。这里要提醒一下：随意把 Ollama 暴露到局域网，意味着任何能访问到你机器的设备都能调用模型，建议只在可信内网这样操作，并且配合防火墙限制来源 IP。
2.2 在 OpenClaw 中添加 Ollama 供应商
Ollama 自己提供的接口路径是/api/chat和/api/generate，但 OpenClaw 对接时一般推荐使用它兼容行业标准的/v1/chat/completions路径。Ollama 从比较早的版本开始就提供了这个兼容端点，所以配置起来非常像接一个云端服务。
我习惯在 OpenClaw 的配置文件里新建一个供应商条目，大概是这样的结构：
providers: - name: ollama-local type: openai_compatible base_url: http://127.0.0.1:11434/v1 api_key: ollama models: - qwen3:8b - llama3.1:8b timeout: 120 max_retries: 2这里有几个字段值得展开说。base_url最后一定要带/v1，因为 OpenClaw 会根据这个前缀拼接请求路径。api_key理论上随便填，比如ollama或者local，本地服务不会校验，但字段必须要存在，不然框架可能报鉴权参数缺失。models列表里的名称必须跟ollama list显示的完全一致，包括中间的冒号和大小写。
timeout和max_retries是我后来加上去的。本地模型推理速度受显存和模型大小影响很大，一个问题可能几十秒才返回，默认的连接超时常常直接把请求掐断。实测下来，我建议超时至少设置 120 秒，如果跑大模型或者长上下文，可以再往上调。重试次数不要太多，本地服务如果已经过载，重试只会让情况更糟，2 次已经足够。
2.3 Ollama 接入的三个常见错误
第一个错误是请求超时。很多情况下不是配置写错了，而是首轮推理太慢。尤其是刚启动的模型要加载进显存，第一次请求可能等待 20 秒甚至更久。排查时可以先在命令行直接 curl 同一个模型接口，观察原始响应时间，如果 curl 都慢，就说明是 Ollama 自身推理速度问题，跟 OpenClaw 无关。
第二个错误是模型名不匹配。OpenClaw 里配置的模型名必须精确匹配，多一个空格都不行。有些版本里模型名带:latest标签，你在ollama list里看到什么就照着写，不要自己补后缀。报错通常就是模型不存在或者 404，去 Ollama 端执行ollama list对一下就知道。
第三个错误是端口和地址写错。如果 Ollama 装在远程机器上，OpenClaw 和 Ollama 不在同一台机器，127.0.0.1就完全不可用，必须写成 Ollama 所在机器的内网 IP。还要确认远程机器防火墙放行了 11434 端口，Ollama 本身也要监听0.0.0.0而不是默认的127.0.0.1。这个坑非常隐蔽，因为配置看着完全正确，但就是连不上。
3. 对接 LM Studio：零配置背后的三个细节
3.1 启动 Local Server 的正确姿势
LM Studio 本身是个图形化工具，很多人装完就直接在聊天窗口里测试模型，但 OpenClaw 需要通过 HTTP 调用，所以必须把 Local Server 功能打开。界面上的路径一般叫 Developer 或者 Local Server，打开后先选好要加载的模型，点 Start Server。
启动之后，LM Studio 会监听1234端口，并且默认提供一个兼容行业标准的接口路径。你可以在浏览器里访问http://localhost:1234/v1/models来看看模型列表，正常情况下会返回一个 JSON，里面带了当前可用的模型 ID。这里有个细节：很多人在界面里看到的模型名称是类似qwen3-8b这样的可读名字，但 API 返回的model字段可能带路径前缀，比如qwen3-8b或者path/to/model，OpenClaw 里填的必须以 API 返回为准。
还有一个经常被忽略的设置：有些版本需要你在启动服务器前先勾选“在启动时加载模型”之类的选项，否则服务是启动了，但没有加载任何模型，请求会一直排队或者直接报错。建议启动完成后，用 curl 请求带一个具体的模型名称，确认能正常返回，再去 OpenClaw 里配。
3.2 路径和模型名的坑
LM Studio 的 base_url 通常是http://localhost:1234/v1，看起来跟 Ollama 的写法很像，但实际请求行为有一些差别。
首先，模型名不能用简称。LM Studio 的 API 会严格检查模型 ID，如果你填的名字跟加载的模型不匹配，接口可能返回 404 或者 model not found。在 OpenClaw 配置里，我建议先用curl http://localhost:1234/v1/models拿到准确 ID，然后复制到配置里。比如返回的模型 ID 是qwen3-8b-4bit，你就填这个，不要省略成qwen3。
其次，API Key 字段同样可以填写任意值，比如lm-studio，因为本地服务不做鉴权校验。但如果你用 OpenClaw 的默认供应商模板，它可能会把 API Key 作为必填项并校验格式，这时候填一个非空字符串就能通过。
最后是请求路径细节。LM Studio 的/v1前缀一定不能漏掉。有些版本的 UI 会显示服务地址为http://localhost:1234，但 OpenClaw 配置里如果只填到这个地址，就会把请求发到错误的路径上。我踩过一次之后，把所有本地工具都统一成http://127.0.0.1:端口/v1的格式，少了歧义。
3.3 上下文、显存和并发怎么设置
LM Studio 能跑的模型大小受本地显存约束。在 Local Server 页面里，你会看到上下文长度设置，默认值有时只有 2048。如果你的 OpenClaw 智能体任务需要处理长文档，上下文太短会导致后续内容被截断，回答质量很受影响。建议根据模型支持的上下文上限和显存余量，适当调整到 4096 或 8192。
并发请求是另一个隐藏问题。OpenClaw 如果同时发起多个请求，而 LM Studio 服务端对每个模型只维护一个推理队列，超出能力的请求会排队。看起来像是“卡住了”，其实只是前面还有任务在跑。如果并发量高，你需要检查显存是否足够加载多份模型副本，或者拆分模型到多个端口实例。在这些设置里，我通常会把 OpenClaw 对这台供应商的max_concurrent_requests限制在 1 到 2，避免所有任务挤在一个队列里互相拖垮。
GPU 加速方面，LM Studio 默认会自动检测可用 GPU，但如果你用的是核显或者混合显卡机器，需要在设置里手动指定主 GPU。否则可能出现模型加载成功，但推理速度异常慢的情况，因为任务可能跑到了 CPU 上。
3.4 多模型切换的取舍
LM Studio 的 Local Server 同一时间只加载一个模型，如果你在 OpenClaw 里配置了多个模型名，切换模型时实际上需要 LM Studio 先卸载旧模型再加载新模型，速度非常慢。更实际的做法是：每个模型单独跑一个 LM Studio 实例，分配不同端口，然后在 OpenClaw 里注册成多个供应商。这样做可以让多个模型常驻内存，切换开销更小，但显存占用也会成倍增加。
如果你的场景只需要一个本地模型，那完全没必要开多个实例，一个就够了。如果确实需要多模型，我的建议是只在 LM Studio 里保留日常最高频的两个模型，其余模型放到 Ollama 管理，因为 Ollama 能按需加载和释放模型，在模型切换上的灵活性比 LM Studio 更好。
4. 对接企业内部接口：鉴权、网关和协议适配
4.1 企业内部模型接口的常见形态
企业内部接口通常不是给 OpenClaw 单独准备的，而是已经有一套统一的模型网关，供公司内部多个系统调用。这套网关横向看，一般分为三类形态。
第一类是最理想的形态：网关完全兼容行业标准的 Completions 接口格式，只是在外部多了自定义鉴权 Header。这种情况下 OpenClaw 配置很简单，只需要把 base_url 指向网关地址，再配置对应的自定义 Header 即可。
第二类是网关保留标准请求格式，但要求额外的租户 ID、业务来源标识或者签名参数。这种形态也不复杂，因为 OpenClaw 支持自定义请求头模板，你只要知道这些参数是怎么从环境变量或者固定值里取出来的，就能直接填到配置里。
第三类是最麻烦的：网关不是为了大模型调用设计的，而是一个内部 RPC 服务或者消息队列封装，需要你把文本请求转换成它规定的数据结构，再把返回结果解析成 OpenClaw 认识的格式。这种不建议硬凑，更稳妥的方案是在 OpenClaw 和企业网关之间加一个轻量适配服务，把适配逻辑收敛到一个独立模块里。
4.2 用配置完成鉴权和请求重写
OpenClaw 的配置文件里，企业内部接口一般类似下面这样：
providers: - name: internal-gateway type: openai_compatible base_url: https://ml-gateway.internal.local/v1 api_key_env: INTERNAL_GATEWAY_KEY extra_headers: X-Tenant-Id: dev-team X-Business-Line: ai-assistant models: - deepseek-r1-70b - qwen2.5-72b timeout: 180 max_retries: 1重点说下api_key_env。一定不要把密钥明文写在配置文件里，尤其当配置文件会提交到仓库或者分发给多个开发者时。OpenClaw 一般支持从环境变量读取密钥，比如INTERNAL_GATEWAY_KEY。这是我在企业内部接入时最坚持的一条底线。
extra_headers用来补充网关要求的静态 Header。如果网关要求动态签名，比如根据当前时间戳和请求体计算签名，那么静态配置就写不了。我的处理方式是写一个二十行左右的本地代理脚本，在 OpenClaw 和网关之间做签名注入，OpenClaw 只跟这个本地代理通信。这样配置依然干净，签名逻辑也集中在一个地方，后续网关换签名算法，只需要改代理脚本。
企业内部接口通常还有网络层面的限制，比如只允许特定内网 IP 访问。如果你的 OpenClaw 部署在开发机，网关只接受生产网段请求，那么需要在配置里控制代理直连，或者通过本机 HTTP 代理转发。这类网络策略问题排查起来比较麻烦，最好先确认 OpenClaw 所在机器能否直接 curl 通网关地址，再继续怀疑配置问题。
4.3 安全与日志脱敏的实践经验
接企业内部接口，安全比功能更重要。我自己遇到过 OpenClaw 把完整的请求日志打到标准输出，里面带着鉴权 Header 和请求体内容。虽然在测试环境问题不大，但生产环境一旦日志被采集进集中式日志平台，密钥就会暴露在错误的权限范围里。
做法分三层：第一层，配置文件里只写环境变量占位符，不写真实密钥；第二层，给 OpenClaw 设置日志级别，区分普通运行日志和请求日志，请求日志默认关闭，需要排查时再临时打开；第三层，如果框架内置了extra_headers打印，先确认它会不会打印 Header 值。某些版本会把自定义 Header 原样写到调试日志，非常危险。
另外，企业内部接口如果走 HTTPS 并且使用自签名证书，OpenClaw 可能默认校验证书失败。我不建议直接关掉证书校验，更稳妥的方式是把企业网关注册的 CA 证书加入本地信任库。如果只为了快速联调，可以临时设置跳过校验，但上线前必须把证书信任配好，否则相当于在明文传输模型调用数据，风险太大。
4.4 内部接口不兼容标准格式时的适配方案
遇到过最折腾的情况是网关希望调用方用 JSON-RPC 格式交互，而且请求里必须带一个从申请单号生成的签名。OpenClaw 原生配置不支持这种协议，我也不想改 OpenClaw 源码，最后用的是一个 50 行左右的适配服务，部署在 OpenClaw 能访问的 localhost 端口。
适配服务做的事情很简单：接收标准格式请求，转换成企业内部网关要求的格式，加上签名和租户 Header，转发到网关，拿到响应后再转换回标准格式。整个过程中，OpenClaw 只需要把供应商地址指向http://127.0.0.1:9000/v1。这样适配逻辑不污染 OpenClaw 配置，也方便以后网关接口升级时独立维护。
写这个适配服务时，有几个细节别忘了：请求要设置充分超时，因为内部模型可能排队；日志里要脱敏掉签名参数和用户敏感内容；响应转换时要把网关返回的code、message之类的包装字段和真正的模型结果分开。我见过有人直接取整个响应体当成模型输出，结果智能体看到一堆 JSON 绕来绕去，最后只能用正则硬拆，越拆越乱。
5. 常见问题与排查技巧实录
5.1 排查问题的三层思路
接自定义供应商和接默认供应商最大的区别是，默认配置出了问题，你还能依赖官方文档；自定义配置出了问题，只能靠自己的排查链路。我总结了一个三层排查法：先确认服务端，再确认请求，最后确认解析。
第一层确认服务端：用 curl 直接请求供应商地址，看能不能返回预期结果。这一步能一次性排除端口、防火墙、证书、服务未启动等问题。如果 curl 都失败，OpenClaw 配置再正确也没用。第二层确认请求：打开 OpenClaw 的调试日志，看它实际发出的请求 URL、Header、Body 是否正确。这一层能发现路径拼接错误、模型名写错、缺少必要 Header 等问题。第三层确认解析：如果请求能发出去，但返回结果智能体不认，那问题就出在响应格式不一致上，需要检查 OpenClaw 的响应解析逻辑或适配服务。
这三层顺序不要反过来。很多人一遇到问题就去看 OpenClaw 配置，反复改 base_url，却忽略了供应商服务本身已经挂了。先 curl，再查日志，问题范围一下子缩小很多。
5.2 问题速查表
| 现象 | 可能原因 | 解决方式 |
|---|---|---|
| 连接被拒绝 | 服务没启动，或地址端口错误 | 先 curl 验证，检查监听地址和防火墙 |
| 超时 | 模型正在加载，或超出 timeout | 调大 timeout，预热模型后再接 OpenClaw |
| 模型不存在 | 模型名与 API 返回不一致 | 用 /v1/models 接口获取正确模型 ID |
| 401 鉴权失败 | API Key 错误或网关要求额外 Header | 检查环境变量和 extra_headers |
| 响应解析异常 | 返回格式跟标准接口不一致 | 在中间层做响应转换 |
| 首次请求极慢 | 模型冷启动加载进显存 | 预热：先发一次空请求，再正式使用 |
| SSL 证书错误 | 自签名证书不受信任 | 把网关 CA 加入本地信任库 |
这张表基本上覆盖了 80% 的接入问题。剩下 20% 往往是网络策略和权限问题，比如 OpenClaw 运行账户没有权限访问某个环境变量，或者公司安全策略禁止从开发机访问生产网关，这类问题只能通过人和流程去协调，配置层面改不出来。
5.3 日志脱敏和调试技巧
调试自定义供应商时，开调试日志确实很有效，但要注意日志里会暴露多少信息。我自己的做法是把 OpenClaw 的调试日志输出到本地文件，不输出到终端，这样既能完整记录请求和响应，又不会在共享终端里偶尔把某个敏感 Header 刷出来。
如果供应商返回的结果很大，日志文件会被撑爆。建议在调试时只请求一个输出很短的问题，比如“回复OK”，把请求和响应体都控制在小体积。等确认链路通畅后，再把调试日志关掉。我还经常用一个小技巧：在 OpenClaw 和供应商之间跑一个简单的 HTTP 抓包工具，专门记录请求和响应头，不记录响应体。这样既能看到签名 Header 是否正确，又不会把业务内容落盘。
5.4 并发和性能策略怎么调
自定义供应商跑在本地时，最容易出问题的不是功能，而是并发。OpenClaw 是智能体框架，很可能同时触发多个工具调用，每个调用都往同一个供应商发请求。本地模型显存有限，计算能力也有限，处理不了高并发。
经验值是：如果你用的是 Ollama，可以在环境变量里设置OLLAMA_NUM_PARALLEL来指定每个模型的并行度，但并行度越高，单个请求反而越慢。普通 8B 模型在消费级显卡上，并行度设为 1 是最稳定的。LM Studio 则完全取决于显存余量，显存不够时并发会直接导致 OOM，进程崩溃，所以最好在 OpenClaw 侧把并发限制到 1。
企业内部网关通常有更大的吞吐，但也会有租户限流。建议在 OpenClaw 里给供应商配置独立的超时和重试策略，避免因为某个慢请求占用了所有连接，影响其他供应商。如果你的 OpenClaw 支持按任务路由供应商，我建议把简单任务和复杂任务拆分到不同模型，这样能显著提升整体可用性。
6. 实操心得和后续扩展
6.1 先用一个脚本验证全部供应商
接多个供应商时，配置写多了反而容易出低级错误。我每次都会写一个非常短的连通性测试脚本，把所有供应商的地址、模型名、鉴权 Header 放在同一个配置文件里，然后逐个发送一个最小的推理请求，打印状态码和响应前 100 个字符。比如用 curl 循环处理：
for entry in ollama lmstudio internal; do echo "== $entry ==" curl -sS -m 10 \ -H "Content-Type: application/json" \ -X POST "http://$BASE_URL/v1/chat/completions" \ -d '{"model":"test","messages":[{"role":"user","content":"hi"}],"max_tokens":5}' echo done这个脚本不追求功能完备，只负责确认“服务活着、鉴权能过、格式能通”。三个条件都满足，OpenClaw 配置基本上不会有问题。如果脚本某个条目失败，就可以直接进入对应的排查环节，不用反复在 OpenClaw 配置里折腾。
6.2 供应商路由与故障转移
当你把 Ollama、LM Studio、企业内部接口同时挂在 OpenClaw 上之后，下一步值得做的事是设计路由规则。比如团队内部测试用小模型，正式业务走企业内部网关；或者本地服务时不时不响应时，OpenClaw 能不能自动切换备用供应商。
路由规则根据你的任务类型来定比较合适。我习惯把低延迟、高并发的简单任务固定走本地模型，把复杂推理、长上下文、需要更强能力的任务走企业内部网关。这里有个隐藏收益：企业内部接口的额度是有限的，本地模型能分担一部分高频调用，网关的压力会明显下降。如果你发现某个供应商频繁超时，可以先把该供应商的权重调低，让主要流量暂时绕过它，等夜里再排查具体原因。这种“先恢复服务，再查根因”的思路在线上环境非常实用。
6.3 配置管理的最后一条建议
最后分享一个我踩过多次坑之后总结出来的习惯：所有自定义供应商配置里，凡是跟环境相关的值，全部放到环境变量里，不要写死在 YAML 文件里。端口、模型名这种相对稳定的可以留在配置里，但 API Key、租户 ID、网关地址尽量都做成可配置项。
另外，每当你有多个供应商时，选择一个统一的命名规范。我一般用工具名-环境-用途的格式，比如ollama-dev-fast、internal-prod-heavy。这个命名虽然在单个配置里看不出什么价值，但当你几个月后再看 OpenClaw 配置，或者同事接手项目时，能省下大量沟通成本。自定义模型供应商看起来是个技术活，真正拉开项目后期维护效率差距的，往往就是这些不起眼的命名和配置规范。
