奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

Kilo Code 加自定义 provider：两种 Base URL 与自定义请求头怎么填

2026-08-07

Kilo Code 在新建自定义 provider 时把 Base URL 做成接受两种形态——既收 https://api.provider.com/v1 这样的标准前缀，也收 https://api.provider.com/v1/chat/completions 这样的完整端点——这一条决定了你手上那个路径结构不太规矩的自建网关能不能直接接上。 截至 2026-08-07，官方文档对第二种形态的说明是：它是为「端点结构非标准」的服务商与自建网关准备的。官方文档里明确写出「两种形态都收」的，本次核对到的几家客户端中只有 Kilo Code 一家——Cline 与 Roo Code 的文档都只说 Base URL 填服务商给的端点地址，并没有交代客户端拿到它之后怎么往后拼路径。这是文档写没写的差别，不等于别家一定不支持，但对你来说结果是一样的：只有 Kilo Code 这一家，你能从文档上确认「整条端点填进去」是被支持的写法，不必靠试。

一、先分清「接入方式」和「模型能力」是两件事

这篇只讲前一件：怎么让 Kilo Code 把请求发到你指定的地址上去。至于这个地址后面的模型聪不聪明、会不会调用工具、上下文能吃多长，那是模型能力的事，配置界面管不了。

先解释三个后面反复出现的词。OpenAI 兼容端点，指的是一个 HTTP 服务，它的请求体和响应体格式跟 OpenAI 的 chat completions 接口对得上，客户端因此可以拿同一套代码去请求它。chat completions 端点就是这套格式里负责多轮对话的那个具体接口路径。自定义 HTTP 头，是你在每次请求上额外附加的键值对，服务端可以拿它做鉴权、路由或者计费归属，跟消息内容本身无关。

站内这几篇分工不同，可以对照着看：编辑器接自定义 API 的通用做法 讲的是各家编辑器的共性套路和字段名差异，API 聚合与中转平台怎么选 讲的是端点背后那家服务值不值得接，OpenRouter 接入实操 是某一家网关的具体接法，而本篇只盯住 Kilo Code 这一个客户端的 provider 表单，把每个框该填什么讲透。想补一下协议本身长什么样，可以先看 OpenAI 兼容端点是什么。

二、新建一个 provider，表单上有哪几项

截至 2026-08-07 官方文档，Kilo Code 新建 provider 时涉及的字段如下。请以官方文档最新版为准。

配置项它是什么填错时的排查方向出处
Provider ID这个 provider 的唯一标识，文档示例值是 my-provider与已有 provider 重名或留空时，配置无法唯一定位Kilo Code 官方文档
Display name界面上显示的名字只影响你自己认不认得出来Kilo Code 官方文档
Provider API选 OpenAI Compatible，走 chat completions 端点选错协议类型，请求体格式与服务端对不上Kilo Code 官方文档
Base URL接口地址，接受标准前缀与完整端点两种形态路径拼接结果不是服务端真实路径时，返回 404 一类的找不到Kilo Code 官方文档
API key服务商发给你的密钥鉴权不通过时返回 401 / 403 一类的状态码Kilo Code 官方文档
Models模型列表，可手动添加，也可自动检测模型 ID 与服务端对不上时，请求指向一个不存在的模型Kilo Code 官方文档
Headers可选，自定义 HTTP 头，键值对形式缺少服务端要求的头时，请求可能被网关拦下Kilo Code 官方文档

说明一句：表里的字段名逐字来自官方文档，但第三列「填错时的排查方向」不是官方文档的记载，官方文档并未逐条说明每一项填错后客户端会有什么表现。那一列是按 HTTP 与 OpenAI 兼容协议的通用机制推出来的排查方向，实际行为以你所用服务端的返回为准。鉴权类报错的具体分辨方法，见 401 与 403 怎么分辨和排查。

三、两种 Base URL 形态，分别什么时候用

官方文档写明 Base URL 接受两种写法：

  1. 标准形态 https://api.provider.com/v1
  2. 完整端点 https://api.provider.com/v1/chat/completions

第一种是绝大多数 OpenAI 兼容服务的样子，客户端拿到这个前缀，自己往后接具体接口路径。第二种，官方文档说明是为「端点结构非标准」的服务商与自建网关准备的。

为什么需要留这个口子？因为「OpenAI 兼容」在实践中只保证请求体和响应体兼容，并不保证路径长得一样。举个官方文档里能查到的例子：Groq 的 base URL 是 https://api.groq.com/openai/v1，中间多了一段 openai。这还算规矩的。企业内部那些挂在 API 网关后面的转发服务，路径里塞版本号、租户号、业务线前缀的比比皆是，客户端按标准套路拼出来的地址根本对不上。此时把完整端点整条填进去，就绕过了拼接这一步。

顺带说一句跨产品的常识差异，免得你从别的工具迁过来时想当然。各家管这个东西叫的名字都不一样：Cline、Roo Code、Kilo Code 的界面上叫 Base URL；Continue 的配置文件里叫 apiBase；Zed 的 settings.json 里叫 api_url；goose 用环境变量 OPENAI_HOST（另有 OPENAI_BASE_PATH）把地址拆成两段；Crush 是命令行参数 --base-url。名字不同，接受的形态也不同，不要把某一家的填法直接搬到另一家。

至于要不要带 /v1，也没有统一答案：Cline 文档里的 v0 示例 Base URL 是 https://api.v0.dev/v1，带了；Zed 文档示例是 https://example.com/v1，也带了；Kilo Code 则是两种形态都收。唯一可靠的判断依据是你那家服务商自己的文档。

四、模型列表从哪来，Headers 留给谁用

Models：官方文档说明，凭据有效时 Kilo 会从 /v1/models 端点自动拉取模型列表；自动检测失败可以手动填模型 ID。官方文档说到这里就没有再往下写了，下面这段是按接口机制推的判断，不是文档的记载：既然列表是从 /v1/models 拉的，那自动检测能不能成，就取决于你那个端点有没有实现这个接口。很多自建网关只转发了对话接口，模型列表接口压根没做，自动检测自然拿不到东西，手填就是了。实际表现以你所用服务端的返回和官方文档为准。

对照着看会更清楚各家的取向差异：Kilo Code 从 /v1/models 自动拉取、失败可手填；Zed 要在 available_models 数组里手写；Continue 在 models 块里手写。自动拉取省事，手写则不依赖服务端多实现一个接口。

Headers：官方文档说明这是可选项，填自定义 HTTP 头，键值对形式。为什么要有这一栏，官方文档没有逐条列举使用场景，这里不替它编。能确定的是：既然客户端允许你附加任意头，那些「必须带某个特定头才放行」的自建网关和企业代理就有了接入的可能，而不必去改客户端源码。

顺便提醒一句凭据存放的问题。Kilo Code 的 API key 是表单里的独立字段，与 Headers 分开填。别家在这件事上态度更硬一些：Zed 官方文档的原话是 “Do not put API keys in settings.json.”，并说明「Provider keys saved through Zed are stored in the system keychain, not in settings.json.」——keychain 指的是操作系统自带的凭据保管服务，密钥存在那里而不是明文躺在配置文件里。Gemini CLI 则支持在 settings.json 里用 $VAR_NAME 或 ${VAR_NAME} 做环境变量插值，加载时自动解析，这样配置文件可以进版本库而密钥不进。这些是各家的做法，不要当成 Kilo Code 的行为。

五、边界与代价：这套配置明确不管什么

第一，它不管模型会不会用工具。 「原生工具调用」（function calling）指的是模型按结构化格式返回一个「我要调用哪个工具、参数是什么」的意图，客户端据此真的去执行。这个能力在不在，取决于服务端那个模型，不是你在表单里填几个框能决定的。同类产品里 Roo Code 把这条挑明了，官方文档原话是：“Roo Code uses native tool calling exclusively. This is the only supported tool protocol — there is no XML-based fallback.”，并建议先查服务商文档确认该模型是否支持工具调用。Kilo Code 的文档在这块没有同样的表述，但道理是通的：接得上不等于用得起来。

第二，官方文档明确点名了一个不适用场景。 Kilo Code 文档写明：接 Azure 上的 GPT-5 时，不要用通用的 OpenAI 兼容 provider，要用 Kilo 原生的 azure provider，因为 Azure 会拒绝 max_tokens 参数。这是一个很典型的信号——「OpenAI 兼容」是个宽泛的说法，参数层面的差异足以让通用通道直接失效。遇到这类服务，找专用 provider 比硬调通用通道省事得多。

第三，它不管你花了多少钱。 官方文档为 Kilo Code 新建 provider 列出的字段里没有计费相关的项（顺带一提，Cline 与 Roo Code 的文档里倒是列了输入价、输出价这样的自定义项，不过文档只给了字段名，没说客户端拿这两个数去做什么，这里不替它推断）。用量和账单要去服务商那边看。本篇也不写任何价格、免费额度、限速数字。

第四，接完之后的稳定性不归它管。 自建网关的转发延迟、上游服务的限流、长响应被中途截断，这些都是运行期的问题，跟表单填得对不对是两回事。

六、避坑清单

坑一：把别家的 Base URL 直接粘过来。 为什么会踩——各家客户端对 Base URL 的拼接规则不同，同一个服务商在 A 工具里填 /v1、在 B 工具里要填完整端点，都可能是对的。怎么避——以服务商文档给出的地址为准，先按标准前缀试；试不通再改成完整端点形态，Kilo Code 两种都收，成本很低。

坑二：自动检测拉不到模型就以为配错了。 为什么会踩——/v1/models 是个独立接口，自建网关经常没实现，此时对话接口其实是通的。怎么避——自动检测失败先别推翻整套配置，改成手动填一个你确定存在的模型 ID 试一次，通了就说明只是模型列表接口缺失。

坑三：Azure 上的 GPT-5 硬走通用兼容通道。 为什么会踩——名字里带 OpenAI，很容易默认它就是标准 OpenAI 兼容。怎么避——按官方文档的提示改用 Kilo 原生的 azure provider，参数层面的差异不是你在客户端能绕过去的。

坑四：选了个不支持工具调用的模型，然后怀疑客户端坏了。 为什么会踩——聊天能出字，一让它读文件改代码就没反应，表象很像客户端 bug。怎么避——接入前先去服务商文档确认这个模型支持不支持 function calling，别拿聊天通不通当验收标准。

坑五：把密钥当成普通请求头随手填进 Headers。 为什么会踩——反正都是发出去的头，看着没区别。怎么避——API key 有独立字段就用独立字段，Headers 留给服务端要求的业务头。把凭据混在自定义配置里，将来分享或备份配置时最容易出事。

坑六：一次改多项然后猜是哪项错了。 为什么会踩——Base URL、模型 ID、Headers 三处都可能导致请求失败，一起改就没法定位。怎么避——先只填 Base URL、API key 和一个手写的模型 ID 跑通最小路径，再往上加 Headers 和其他项。

数据来源与核对日期

本篇涉及的产品事实来自以下官方文档页面，核对日期均为 2026-08-07：

本篇没有写的内容以及原因：

  • 任何产品的价格、免费额度、订阅档位、限速数字——这类信息变动频繁，本次未做核实，写出来只会误导，请以各产品与各服务商官方文档为准。
  • 完整的模型清单与模型能力对照——同上，清单变动快，且各服务商实际开放的模型与文档示例未必一致。
  • Kilo Code 界面菜单的逐级层级——官方文档未逐级写明，本篇只按字段名描述，实际入口以你手上版本的界面为准。
  • 各产品的版本号、发布日期与彼此之间的归属关系——不在核实范围内，本篇不做推断。

文中出现的所有字段名、配置项、URL 与英文原句，均为上述页面在 2026-08-07 当天的内容。这类文档更新频繁，动手配置前请以官方文档最新版为准。

延伸阅读：同一组里的 Roo Code 只认原生工具调用、Kilo Code 模型列表拉不到；接完之后照 接完自定义模型别急着干活 逐项过一遍，才算真接通。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员