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

Continue 的 config.yaml 怎么写：models 块字段逐项拆解与取舍

2026-08-07

在 Continue 里接一个自定义模型，真正卡住人的不是那个 URL 填哪儿，而是没意识到 name、provider、model 这三个必填字段回答的是三个不同的问题——分别是「我怎么称呼它」「用哪套协议去说话」「对面那台机器上跑的是哪个模型」。 把它们当成同一件事的三种写法，就会出现「配置看着没错、就是不工作」的局面。这篇按字段逐项拆一遍，再说清楚：把接入写进配置文件，相比在图形界面里点表单，你换来了什么、又放弃了什么。

站内已有几篇相邻的文章，分工是这样的：编辑器接入自定义 API 的通用做法讲的是跨工具的共性流程，本地模型接入编辑器讲的是把模型跑在自己机器上时的额外考虑，让 AI 改配置文件讲的是让模型代你动配置时的边界；本篇只钻一件事——Continue 这一个产品的 config.yaml 里，models 块的字段该怎么理解。

一、models 块解决的是「谁来干哪件活」

先说这块配置存在的意义。截至 2026-08-07 的官方文档，Continue 的配置文件是 config.yaml，模型配置放在 models 块下。注意 models 是复数，它天然是一个列表——你可以在里面写多条模型条目，而不是只能配一个「当前模型」。

这个设计和图形界面里「选一个 provider、填一组参数」的心智模型不太一样。以 Cline、Roo Code、Kilo Code 为例，官方文档描述的接入字段是 Base URL、API Key、Model 这样一组表单项，形态上是在描述「这一套凭据对应哪个模型」；而 Continue 的 models 是一个条目列表，形态上描述的是「我这套配置里有哪几条模型条目」。两者各自在界面上如何切换、能不能同时挂多个，官方文档在本篇引用的页面里没有逐条说明，以官方文档为准。理解了这个形态差异，后面 roles 这个字段为什么重要就自然了。

顺带说明一个贯穿全文的概念：OpenAI 兼容端点，指的是一个服务把自己的接口做成和 OpenAI API 相同的请求/响应格式，于是原本只会说 OpenAI 那套话的客户端不用改代码就能连上去。各家工具里那个让你填地址的字段，本质上就是告诉客户端「别去默认地址，去我给的这个地址说话」。这些字段在不同产品里名字完全不同，后面会专门说。

二、三个必填字段：name、provider、model

按官方文档，models 块下每个模型条目的必填字段是三个：

  • name：唯一标识。它是你给这条配置起的名字，用于在配置里区分不同条目。
  • provider：文档举的例子有 openai、ollama、mistral。这一项决定客户端按哪一家的接入方式去发请求。
  • model：具体模型名。也就是对面服务真正认得的那个模型标识。

三者的关系可以这样理解（这是按官方文档给出的字段释义与示例推的读法，不是文档逐条写明的行为说明）：provider 决定「怎么说话」，model 决定「跟谁说」，name 承担的是「这条配置叫什么」。最常见的误解是把 name 当成模型 ID 去填，或者反过来指望 model 里写个好记的别名就行——这两项各管各的，不能互相顶替。

官方文档给出的示例长这样（下面这段是文档里的示例，可以照着理解结构）：

models:
  - name: GPT-4o
    provider: openai
    model: gpt-4o
    roles:
      - chat
      - edit
    defaultCompletionOptions:
      temperature: 0.7
      maxTokens: 1500

看这个例子最该注意的是 name 写的是 GPT-4o（带连字符、大写，一眼是给人看的），而 model 写的是 gpt-4o（服务端认的标识）。它们长得像，但角色完全不同。

三、可选字段逐项说明

必填之外，文档还列出了一批可选字段。下表里的字段名逐字来自官方文档 reference 页；第三列「配错了你会看到什么」是按 OpenAI 兼容协议与配置文件加载的通用机制推出来的判断，官方文档并未逐条说明每个字段配错后的具体表现，实际行为以官方文档与你所用版本为准。

字段它是什么配错了你会看到什么（机制推断，非文档逐条记载）出处
name这条模型配置的唯一标识两条写成同一个名字，你自己就很难分清哪条是哪条官方 reference 页，必填
provider接入方式，文档举例 openai、ollama、mistral写成对面服务不吃的那一套，请求格式对不上，连不通官方 reference 页，必填
model具体模型名服务端不认这个标识，通常表现为请求被拒官方 reference 页，必填
apiBase覆盖默认 API 端点不填时走该 provider 的默认端点，自建服务就连不上；填错路径层级则请求打不到正确接口官方 reference 页，可选
roles这个模型承担哪些角色不写就落到默认值，某些岗位上你以为配了却没生效官方 reference 页，可选
capabilities能力声明，如 tool_use、image_input声明与模型实际能力不一致时，相关功能行为不符合预期官方 reference 页，可选
defaultCompletionOptions生成参数默认值，含 temperature、maxTokens、topP 等maxTokens 设得过小，长回答会被提前截断（这是采样参数的通用机制）官方 reference 页，可选
autocompleteOptions自动补全相关选项补全体验与预期不符官方 reference 页，可选
chatOptions对话相关选项对话行为与预期不符官方 reference 页，可选
requestOptionsHTTP 层配置，含 timeout、headers、proxy 等内网需要走代理或加自定义头时不配，请求根本发不出去或被网关拒绝官方 reference 页，可选

requestOptions 这一项值得单独提一句：它管的是 HTTP 传输层面的事——超时多久、要不要带额外的请求头、走不走代理。很多「模型接不上」的问题其实和模型无关，是网络层没配对。排查时把它和模型参数分开看，能省不少时间。

四、roles 和 capabilities：把模型钉在具体岗位上

roles 的取值，文档列出的是：chat、autocomplete、embed、rerank、edit、apply、summarize；默认值是 [chat, edit, apply, summarize]。

这里两个词需要先解释：**嵌入（embed）**是把文本转成一串数字向量，好让程序按语义相近去检索，而不是只能按关键词匹配；**重排（rerank）**是在检索出一批候选之后，再用一个模型给它们打分排序，把最相关的顶到前面。这两件事和「和你聊天写代码」是不同的活，通常也用不同的模型。

于是默认值里的信息量就出来了：embed 和 rerank 不在默认角色里。也就是说，你配一个模型进去，它默认会去接对话、编辑、应用改动、总结这四类活，但不会自动承担嵌入和重排。如果你想让某个模型干这两件事，得显式写进 roles。反过来，你想让一个便宜的小模型只做自动补全、不掺和对话，也是靠 roles 把它框住。

capabilities 则是能力声明，文档举的例子是 tool_use 和 image_input。**工具调用（function calling，也叫原生工具调用）**指的是模型按结构化的格式输出「我要调用哪个工具、参数是什么」，客户端据此真的去执行，再把结果喂回去——编辑器里的读文件、跑命令、改代码这类动作大多依赖它。这件事在不同产品里的态度差别很大：Roo Code 的官方文档写得非常硬，原话是 “Roo Code uses native tool calling exclusively. This is the only supported tool protocol — there is no XML-based fallback.”（这是 Roo Code 官方文档的说法），也就是不支持原生工具调用的模型在那边直接用不了，文档建议先查服务商文档确认模型是否支持工具调用。Continue 这边的形态是给你一个 capabilities 里的 tool_use 可以声明。想再往下理解工具调用这套机制本身，可以看MCP 与 function calling 的区别。

还有一个容易被忽略的对比：上下文窗口（模型单次能吃下的最大文本量，超了就得截断或压缩）这一项，在 Cline 里叫 Context Window size、Roo Code 里叫 Context Window、Zed 的模型条目里叫 max_tokens、aider 要在 .aider.model.metadata.json 里写 max_input_tokens / max_output_tokens——都是需要你手填的位置。而 Continue 这边，本篇依据的（截至 2026-08-07 的官方 reference 页）可选字段记录里，没有出现单独的上下文窗口字段。这不等于它不管这件事，也不等于该页此外没有别的相关设置——只是本篇能核到的字段清单里没有这一项，具体以官方文档最新版为准。

五、写进配置文件，相比点图形界面换来了什么

把各家的形态摆在一起看，配置形态大致分四类：图形界面表单（Cline、Roo Code、Kilo Code）、YAML 配置文件（Continue 的 config.yaml、aider 的 .aider.model.settings.yml）、JSON settings（Zed 与 Gemini CLI 的 settings.json）、环境变量与 CLI 子命令（goose 的 GOOSE_PROVIDER 加 goose configure、Crush 的 crushrc 加 provider add）。

配置文件这条路的收益很直接：一是可复制，一份文本发给同事就能复现同样的接入；二是可对比，改了什么用 diff 一眼看得出来；三是结构上就允许写多条，models 既然是列表，一条条模型条目可以各自带自己的 roles。

代价也很实在。表单式界面会用输入框和文案把「哪一项是必填、这里该填什么形态的值」摆在你眼前，纯文本文件没有这层提示，漏写一个必填字段要等到工具加载配置时才暴露出来（这是配置文件加载的通用机制，Continue 具体如何提示与报错，官方文档未逐条说明）。举个跨产品的对比：Cline 的文档会明确提示 Base URL 这里不会是 https://api.openai.com/v1（那是官方 OpenAI API 的地址），Kilo Code 的文档甚至写明它接受两种形态的 Base URL：标准形态 https://api.provider.com/v1，以及完整端点 https://api.provider.com/v1/chat/completions，后者是为端点结构非标准的服务商和自建网关准备的。这类「填法上的分寸」在界面里有文案兜着，在 YAML 文件里只能靠你自己去读文档。

再有就是模型列表从哪儿来。Kilo Code 在凭据有效时会从 /v1/models 端点自动拉取模型列表，拉不到再手填；Zed 要在 available_models 里手写；Continue 则是在 models 块里手写。手写的好处是完全可控，坏处是服务端换了模型标识你不会自动知道。

关于密钥，各家取向差得更远。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}，加载时自动解析；环境变量插值就是配置文件里只写变量名占位、真值由运行环境提供，好处是配置文件能安心进版本库而密钥不进。Continue 这边，本篇不对密钥存放方式作断言，请以官方文档为准。密钥本身怎么管，可以另看API 密钥安全管理。

六、边界与代价：这套写法不管什么

说清楚边界，比多列几个字段更有用。

它不改变模型本身的能力。 按字段名的语义理解，capabilities 里写上 tool_use 是在配置层面声明这个模型具备该能力，而不是给模型装上这个能力——官方文档并未逐条说明客户端读到这个声明后具体做什么，实际行为以官方文档为准。但有一点跟产品无关：模型自己不支持工具调用，配置里怎么写也不会凭空长出来。同理，defaultCompletionOptions 里的参数是在调用时带上去的请求参数，服务端认不认、上限多少，取决于服务端。

它不替你判断端点填得对不对。 地址该不该带 /v1、要不要写到 /chat/completions 这一层，是服务商那边的约定。各家产品对这件事的说法都只覆盖自己：Cline 文档里的 v0 示例 Base URL 是 https://api.v0.dev/v1（含 /v1），Model ID 是 v0-1.0-md；Kilo Code 明确接受两种形态；Zed 的示例是 https://example.com/v1；Groq 官方给的 base URL 是 https://api.groq.com/openai/v1。这些是各家文档里各自的写法，不能互相搬——Continue 的 apiBase、Zed 的 api_url、goose 的 OPENAI_HOST（另有 OPENAI_BASE_PATH）、Crush 命令行的 --base-url、界面里的 Base URL，虽然都跟「地址」有关，但字段名和填法各归各家。

它不解决跨工具统一。 你在 Continue 里配好的这套，换到别的编辑器里一行都用不了，字段名和文件位置全不一样。想在多个工具间统一接入口径，得在网关层做，而不是在编辑器配置层做，参见OpenAI 兼容端点是怎么回事。

它不适用于「今天临时试一个模型」的场景。 改文件、存盘、让工具重新读取，这条链路比在界面上点两下慢。真正划算的场景是：这套接入要长期用、要发给别人、要进版本库。

七、避坑清单

把 name 当模型 ID 填。 为什么会踩：三个字段挨在一起，name 又排第一，很容易顺手写成模型标识。怎么避：写的时候心里念一遍——name 是给人看的标签，model 是给服务端看的标识，两栏分开确认。

忘了 roles 有默认值。 为什么会踩：默认是 [chat, edit, apply, summarize]，四个角色已经覆盖了日常大半场景，所以不写也「像是能用」，直到你发现嵌入或重排一直没走你以为的那个模型。怎么避：凡是想让模型承担 embed 或 rerank，必须显式写进 roles，因为这两个不在默认值里。

只写一次 roles 就当全局生效。 为什么会踩：models 是列表，每条各有各的 roles。怎么避：多模型分工时，逐条检查每一条的角色，别指望某一条的设置影响其他条目。

把别家的字段名搬过来。 为什么会踩：这几家的界面和文档看多了，api_url、OPENAI_HOST、Base URL、--base-url 会在脑子里糊成一团。怎么避：以你正在配的这个产品的文档为准，逐字核对字段名的大小写与拼写，别凭印象写。

忽略 requestOptions。 为什么会踩：内网环境、需要走代理或加自定义请求头时，模型参数配得再对也发不出请求，而报错往往看起来像模型问题。怎么避：先把编辑器排除在外，在同一台机器上用命令行直接请求你填在 apiBase 里的那个地址（带上同一个密钥、同一个模型标识），看返回的是正常响应体、还是超时、还是网关返回的 4xx/5xx。命令行能通而编辑器不通，问题多半在 requestOptions 这一层（代理、超时、自定义头）；命令行也不通，就别再改模型参数了，先解决网络与鉴权。

maxTokens 一刀切设小。 为什么会踩：为省 token 把上限压很低，长回答被截断，看起来像模型「说一半就停」。这是采样参数的通用机制，不是某个产品的特殊行为。怎么避：把最大输出和你实际的任务长度对齐，别用一个数字管所有角色。

照抄别人的完整配置。 为什么会踩：别人的 apiBase 指向他的服务、model 是他那边认的标识，抄过来只有结构可用。怎么避：把示例当结构参考，三个必填字段逐项按自己的服务重填一遍。

数据来源与核对日期

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

本篇没有写什么，以及为什么：

  • 不写价格、免费额度、订阅档位、限速数字。这类信息变动频繁，本次也未逐项核实，写出来只会误导你做预算判断，请以各产品与各服务商官方页面为准。
  • 不写完整模型清单与版本号。模型标识和可用范围随时在变，文中出现的模型 ID 只是各家官方文档里的示例值，不构成推荐，也不代表当前仍然可用。
  • 不写各家产品界面的逐级菜单路径，除非官方文档写明。界面改版比文档快，写死路径会让你在找不到入口时更困惑。
  • 不对字段配错后的具体报错文案作断言。上文表格第三列是按协议与加载机制推出的判断，官方文档没有逐条说明，实际表现以你的版本和服务商为准。
  • 文中所有字段名、配置键与示例，都是截至 2026-08-07 官方文档页面上的内容；动手前请再核一遍官方文档最新版。

延伸阅读：同一组里的 Kilo Code 模型列表拉不到、Continue 的 roles 七种取值；接完之后照 接完自定义模型别急着干活 逐项过一遍，才算真接通。

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

浏览课程 加入会员