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

Kilo Code 模型列表拉不到：从哪个端点拉、手填要注意什么

2026-08-07

模型下拉框是空的，绝大多数情况不是”这个模型不能用”，而是 Kilo Code 去拉列表的那一趟没走通。 截至 2026-08-07 的官方文档写得很明确：凭据有效时，Kilo 会从 /v1/models 端点自动拉取模型列表；自动检测失败时可以手动填模型 ID。所以你要先判断的是”拉列表这一趟为什么没成”，而不是先怀疑模型本身。这两件事混在一起，是这类问题最常见的浪费时间的方式。

先把两个概念摆平，后面才不绕。OpenAI 兼容端点指的是：服务商自己实现了一套跟 OpenAI API 长得一样的 HTTP 接口（同样的路径、同样的请求体字段），客户端可以拿对接 OpenAI 的那一套代码直接打过去。它保证的是”接入方式一样”，不保证”模型能力一样”——这是本文反复要区分的两件事。另一个是上下文窗口：模型一次能吞进去的 token 总量上限。按 HTTP API 的一般机制推，请求内容超过这个上限时，服务端要么直接报错、要么按自己的策略处理，具体行为各家不同，以你的服务商文档与实际响应为准。它属于模型能力，不属于接入方式，客户端并不能靠改配置把它变大。

本站已有几篇相邻的文章，分工是这样的：OpenRouter 路由失败排查讲的是聚合路由那一层选错上游、上游不可用的排查，API 返回结构变了怎么办讲的是端点响应体字段变动导致解析崩掉，模型别名的风险讲的是别名指向漂移带来的行为变化；这一篇只管一件更靠前的事——Kilo Code 客户端侧”模型列表从哪来、拉不到怎么办”。

一、模型列表从哪来：先定位那一趟请求

按官方文档，在 Kilo Code 里新建一个 provider，Provider API 这一项选 OpenAI Compatible，走的是 chat completions 端点。这是聊天推理走的路。而模型列表走的是另一条路：凭据有效时，Kilo 会从 /v1/models 端点自动拉取模型列表。

两条路分开，意味着排查也要分开看。下面这几种情况，客户端表现出来可能都是”下拉框空的”，但根因完全不同（这一段属于 HTTP 与 OpenAI 兼容协议层面的通用机制推理，官方文档并没有逐条列出对应的报错文案，实际行为以官方文档与你的服务商响应为准）：

  • 凭据本身不对。文档的措辞是”凭据有效时”自动拉取，那么凭据无效时拉不到是顺理成章的。这一类你在任何客户端里都会撞上，不是 Kilo 独有的。
  • 服务商压根没实现 /v1/models。OpenAI 兼容不是一个有强制认证的标准，很多服务商只实现了推理相关的少数几条路径，模型列表接口可能没有、可能路径不同、可能返回的结构跟客户端的预期对不上。这时候推理是能用的，只是列表拉不出来。
  • Base URL 的形态选得不对，拼出来的地址不是服务商真正的模型列表地址。这一条见下一节。
  • 网络层根本没通（自建网关没起、代理没配、内网证书不被信任）。这跟模型无关。

判断顺序上，一个务实的做法是：先用 curl 之类的工具，拿同一个 Base URL 和同一个 key，手动打一次模型列表接口看返回什么。能拿到就是客户端侧配置问题，拿不到就是服务商侧或者网络侧问题。这一步花不了两分钟，却能把后面所有猜测都省掉。关于兼容端点本身的路径约定，可以顺带看什么是 OpenAI 兼容端点。

二、Base URL 两种形态怎么选，以及手填模型 ID

Kilo Code 的文档明确写了 Base URL 接受两种形态：

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

文档说明第二种是为「端点结构非标准」的服务商与自建网关准备的。也就是说，如果你的网关把推理接口挂在一个不常规的路径上，Kilo 允许你直接把整条推理地址贴进去，不再由客户端替你拼后缀。

这个设计很实用，但它和上一节的自动拉列表之间有一处值得你自己留意：当 Base URL 填成完整端点形态时，模型列表还能不能自动拉、从哪个地址拉，官方文档没有说明。我不替它下结论。实践上的稳妥做法是：如果你填了完整端点形态并且发现列表拉不出来，直接走手填模型 ID 这条路，不要在这上面反复试探；这是文档明确给出的兜底路径——自动检测失败可手动填模型 ID。

手填的时候，有三点边界要守住：

第一，模型 ID 要逐字来自服务商文档，不要按印象拼。带不带前缀、带不带版本后缀、大小写，服务商之间毫无统一。举一个能在官方文档里查到的实例：Groq 的 base URL 是 https://api.groq.com/openai/v1，其文档中出现的示例模型 ID 形如 llama-3.3-70b-versatile、openai/gpt-oss-20b——你可以看到，同一家服务商内部，模型 ID 的形态就可能不一致，有的带斜杠有的不带。凭感觉写一个 ID 上去，界面上未必会立刻拦住你，但请求真发到上游之后，按 HTTP API 的通用机制大概率会换回一个”模型不存在”这一类错误（这一句是机制推断，各家客户端的校验时机与具体报错文案官方文档并未逐条说明，以实际响应为准）。

第二，手填 ID 只解决”叫什么”，不解决”能不能”。你把 ID 填对了，只代表推理请求能被路由到那个模型上；这个模型支不支持工具调用、支不支持图片输入、上下文窗口有多大，全都是模型本身与服务商的事。不同客户端对这件事的态度差别很大：Roo Code 的官方文档就写了一句硬限制——“Roo Code uses native tool calling exclusively. This is the only supported tool protocol — there is no XML-based fallback.”（这是 Roo Code 官方文档的说法，不是本文的判断），并建议先查服务商文档确认该模型是否支持工具调用。这里的**原生工具调用（function calling）**指的是：模型按接口约定直接输出结构化的函数调用请求，而不是让客户端从自然语言里正则抠。手填 ID 时最容易忽略的就是这一层能力校验。

第三，别把别家的字段名和填法套过来。各家的 base URL 字段名完全不同：Cline、Roo Code、Kilo Code 的界面里都叫 Base URL；Continue 的 config.yaml 里叫 apiBase；Zed 的 settings.json 里叫 api_url；goose 用环境变量 OPENAI_HOST（另有 OPENAI_BASE_PATH）；Crush 是命令行参数 --base-url。名字像、语义不一定像，“Kilo 接受完整端点形态”这条也只对 Kilo 成立，别拿去解释别家的行为。

三、新建 provider 的字段对照表

下面这张表的字段名逐字取自 Kilo Code 官方文档（截至 2026-08-07）。「填错的表现」一列是按 OpenAI 兼容协议与 HTTP 的通用机制推出来的判断，官方文档并没有逐条说明每个字段填错后的报错文案，以实际响应和官方文档最新版为准。

配置项它是什么填错的表现（机制推断，非文档记载）出处
Provider IDprovider 的唯一标识，文档示例 my-provider重名或改名后，原有引用可能对不上Kilo Code 官方文档
Display name界面上显示的名字只影响你自己认不认得出来，不影响请求Kilo Code 官方文档
Provider API选 OpenAI Compatible，走 chat completions 端点选错类型时，请求体与目标接口的约定对不上Kilo Code 官方文档
Base URL服务端点地址，接受 /v1 与 /v1/chat/completions 两种形态路径与服务商实际结构不符，请求打不到正确地址Kilo Code 官方文档
API key访问凭据凭据无效时按文档口径不满足”凭据有效”，自动拉取不成立Kilo Code 官方文档
Models手动添加或自动检测；自动检测走 /v1/models自动检测不成时列表为空，需要手填模型 IDKilo Code 官方文档
Headers可选，自定义 HTTP 头，键值对形式网关要求的头缺失或写错，请求可能在网关侧就被拒Kilo Code 官方文档

Headers 这一项在对接自建网关时特别有用：很多企业网关要求带上团队标识、租户 ID 或者自家的鉴权头，这个入口就是给这类需求准备的。文档只说明了它是可选的自定义 HTTP 头、键值对形式，没有列举具体用法，具体填什么以你的网关文档为准。

顺带说一句路径变动：kilocode.ai/docs/... 在核对日返回 308 永久跳转到 kilo.ai。如果你手里存的是旧书签，看到的可能是跳转后的页面，内容以跳转目的地为准。

四、Azure 那条专门的提醒

官方文档里单独写了一条针对 Azure GPT-5 的提醒，值得单拎出来说：不要用通用的 OpenAI 兼容 provider，要用 Kilo 原生的 azure provider，因为 Azure 会拒绝 max_tokens 参数。

这条提醒的价值在于，它揭示了”OpenAI 兼容”这四个字的边界。兼容说的是路径和字段长得一样，但服务端对参数的接受程度可以不一样。当上游明确拒绝某个通用客户端一定会发的参数时，走通用兼容通道就是必然失败，而且失败点很隐蔽——你会看到一个参数级的报错，很容易被误读成”模型不支持”或者”key 有问题”。

对你的实际意义是：遇到某一家上游反复报参数相关的错，先去查这家有没有独立的原生接入方式，而不是在通用兼容 provider 里反复调 Base URL。 Kilo 这里给的答案就是换成原生 azure provider。文档没有说其它模型或其它 Azure 部署是否也有同样问题，我不做外推，这条提醒在文档里就是明确限定在 Azure GPT-5 这个场景上的。

五、边界与代价：这条路放弃了什么

用通用 OpenAI 兼容 provider 接自定义模型，是一条通用性换确定性的路，代价要提前认下来：

它不保证模型能力。 接进来只代表请求能发出去。工具调用、图片输入、上下文窗口这些属于模型和服务商，客户端配置改不动。这里要留意一个容易混的点：截至 2026-08-07 的官方文档里，Kilo Code 新建 provider 的字段就是上面表格那七项，并没有让你手填上下文窗口；把上下文窗口列成可自定义项的是另外几家——Cline 的 Context Window size、Roo Code 的 Context Window、Zed 的 max_tokens、aider 的 .aider.model.metadata.json 里的 max_input_tokens / max_output_tokens。这些字段的名字来自各家官方文档，但客户端具体拿它做什么，文档并没有逐条说明；按字段语义推，它更像是让客户端知道这个模型的量纲，而不是能给模型扩容——实际行为以各家官方文档最新版为准。

它不保证参数被全量接受。 Azure 那条提醒就是活证据。通用通道发的是一套通用参数，上游有权拒绝其中任何一个。

它不替你管密钥安全。 Kilo 这边的字段就是 API key 一项。别家在这件事上的设计取向可以做参照：Zed 的官方文档直接写了 “Do not put API keys in settings.json.”，并说明 “Provider keys saved through Zed are stored in the system keychain, not in settings.json.”（这两句都是 Zed 官方文档的说法）——keychain 指的是操作系统提供的凭据保管服务，密钥交给它，就不会以明文躺在配置文件里。Gemini CLI 则支持在 settings.json 里用 $VAR_NAME 或 ${VAR_NAME} 做环境变量插值（加载时自动把变量名替换成变量值），好处是配置文件可以进版本库而密钥不进。这些是各家自己的设计，不能挪到 Kilo 上当作它的行为来讲。

自动拉列表这件事本身也不是万能的。 好处是省手工、模型上下线能跟上；代价是你多依赖了一个接口，这个接口不归你控制。相比之下，Zed 要在 available_models 里手写模型数组，Continue 要在 models 块里手写——手写更啰嗦，但少一个运行时依赖。两种取向没有优劣，只有你更怕哪一种麻烦。

什么场景下这条路不适用：上游明确拒绝通用参数（有原生 provider 就走原生）；模型不支持你要用的能力（换模型，不是换配置）；企业网关有复杂的鉴权流程而不只是一个静态头。

六、避坑清单

坑一：看到空列表就换服务商。 为什么会踩——空列表这个现象太笼统，凭据、路径、上游没实现、网络不通，四种根因表现一样。怎么避——先用命令行手打一次模型列表接口，把”客户端问题”和”服务端问题”切开再动手。

坑二：把 Base URL 的两种形态混着填。 为什么会踩——文档写明两种形态都接受，光看界面分不出你填的这一种适不适合你的服务商，问题往往要到真正发请求时才暴露（这一句是机制推断，不是文档记载）。怎么避——照服务商文档给的地址填；服务商给的是标准形态就用标准形态，只有端点结构确实非标准或走自建网关时才用完整端点形态，并且这时候要预期自动拉列表可能不生效。

坑三：模型 ID 凭印象拼。 为什么会踩——模型 ID 在各家的命名毫无统一，前缀、斜杠、版本后缀都可能有也可能没有。怎么避——逐字从服务商文档复制，一个字符都别改。别名类 ID 还有指向漂移的问题，那部分见模型别名的风险。

坑四：把手填 ID 当成能力开通。 为什么会踩——填完 ID 界面就正常了，容易误以为万事俱备，直到 Agent 开始调工具才发现模型压根不支持。怎么避——填 ID 之前先查一次服务商文档里该模型的工具调用支持情况；Roo Code 的文档就是这么建议的。

坑五：撞到参数报错就狂改 Base URL。 为什么会踩——参数级错误和地址错误在客户端里的呈现常常一样笼统。怎么避——先看报错里有没有出现具体参数名（比如 max_tokens 这类），出现了就说明地址是通的，问题在参数与上游的匹配上，该找原生 provider 就找原生 provider。

坑六：把别家的字段名和填法搬过来。 为什么会踩——apiBase、api_url、OPENAI_HOST、--base-url 看着都在说同一件事。怎么避——认准你现在用的这一家的字段名；关于各家接入方式的整体差异，可以看编辑器接自定义 API。

坑七：拿旧域名的文档当准。 为什么会踩——文档站会搬家，旧链接跳转后你未必留意到域名变了。怎么避——以跳转后的地址为准，收藏夹里的旧链接及时更新。

数据来源与核对日期

以下为本文用到的官方文档来源，核对日期均为 2026-08-07。文档会更新，请以官方最新版为准。

本文没有写什么，以及为什么：没有写任何产品的价格、免费额度、订阅档位、限速数字、版本号与完整模型清单——这类信息变动快，本次也未逐项核实，写进来只会误导；没有写 Kilo Code 界面菜单的逐级层级，因为官方文档中未逐级写明；没有写 Azure 除 GPT-5 之外场景的行为，文档只限定了这一个场景，向外推就是编造；表格中「填错的表现」一列已注明是按协议通用机制推出来的判断，不是官方文档的记载。所有细节请以各产品官方文档最新版为准。

延伸阅读：同一组里的 Kilo Code 加自定义 provider、Continue 的 config.yaml 怎么写；接完之后照 接完自定义模型别急着干活 逐项过一遍，才算真接通。

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

浏览课程 加入会员