Continue 的 roles 七种取值：补全、嵌入、重排该配哪个模型

2026-08-07

Continue 的 roles 默认值是 [chat, edit, apply, summarize]——也就是说你不写这个字段，同一条模型配置会同时被登记成这四种角色；而 autocomplete、embed、rerank 这三种取值，默认没有任何模型认领。这句话是截至 2026-08-07 官方参考文档里写明的默认值，不是推测。很多人接完自定义模型后觉得”补全没反应""检索一直用不上”，第一件该查的事不是端点通不通，而是那条模型配置到底被登记成了哪几个角色。

这篇只讲 Continue 里”哪个模型挂哪个 role”这一层配置边界。补全为什么会漏字、会吞掉后半段，另有代码补全丢内容的排查思路；嵌入模型怎么挑，看嵌入模型选型；重排这一步到底值不值得加，看重排的意义。这三篇讲的是模型能力和检索效果，本篇讲的是配置文件里那几行字段该怎么填、填了之后归谁管。

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

这两件事经常被混在一起谈，但排查路径完全不同。

接入方式说的是：客户端用什么协议、往哪个地址发请求、密钥从哪来。这一层里最常见的概念是”OpenAI 兼容端点”——指某个服务商把自己的接口做成和 OpenAI 的 HTTP 接口同样的请求/响应格式，于是任何按 OpenAI 格式写的客户端，只要把地址换掉就能连上。

模型能力说的是：这个模型本身能不能干某件事。比如能不能做 function calling（也叫原生工具调用，指模型按结构化格式输出”要调用哪个工具、参数是什么”，而不是把调用意图写在自然语言里）；比如它的上下文窗口有多大（上下文窗口就是单次请求里，提示词加上历史加上生成结果能占用的 token 上限，超了就得裁）。

Continue 的接入方式很直白：配置文件是 config.yaml，模型配置写在 models 块下。截至 2026-08-07 的官方参考文档，每条模型配置的必填字段是三个——name（唯一标识）、provider（如 openai、ollama、mistral）、model（具体模型名）。要把请求打到默认端点以外的地方，用可选字段 apiBase 覆盖默认 API 端点。

roles 就是这条模型配置的可选字段之一。它不改变模型能力，只在配置层面标记这条配置参与哪几类工作。

二、七种取值，默认认领四种

官方参考页给出的 roles 取值是七个：chat、autocomplete、embed、rerank、edit、apply、summarize；默认值是 [chat, edit, apply, summarize]。

需要先说清一件事：文档在这一页列的是取值清单和默认值，没有逐条说明客户端内部拿每个 role 做什么调度。下面对每个名字的解释，是按这些词在业界的通用含义给出的，用来帮你判断该把哪类模型往哪个角色上挂；具体到 Continue 内部的行为，以官方文档为准。

按通用含义，这七个词分成三组来看比较顺：

对话与改写这一组（默认已认领）。chat 是对话式问答那类交互；edit 是对选中代码提要求让它改；apply 是把模型给的改动落到文件里；summarize 是把长内容压成短的。这四件事都需要一个理解力够用的通用模型，所以默认值把它们绑在一起是合理的默认——你只配一条模型，这四样立刻能用。

补全这一组（默认没人认领）。autocomplete 对应的是你打字时行内直接冒出来的续写建议。这类请求的特点是频次极高、延迟要求苛刻、每次上下文不大。用做对话的那个大模型去顶补全，通常不是”配不出来”，而是等不起——你敲三个字符它还在想。业界的常规做法是给补全单独挂一个小而快的模型，很多本地部署方案（provider 取值里的 ollama 就是这一类）就是为这个场景准备的。

检索这一组（默认也没人认领）。embed 对应嵌入：把一段文本转成一串数字向量，让语义相近的内容在向量空间里靠得近，检索时才能按意思找而不是按关键词找。rerank 对应重排：先粗排捞出一批候选，再用另一个模型对候选逐条打分重新排序，把最相关的顶上去。这两件事用的都不是对话模型——嵌入模型和重排模型是另一类模型，服务商得单独提供对应的端点。这也是为什么默认值里没有它们：默认值只能假设你配了一个能聊天的模型。

看懂这个分组，“默认只给四种”这件事的含义就清楚了：Continue 不是不支持补全和检索，而是它不替你猜哪个模型该干这个。你不显式声明，这两块就一直空着。

三、拆分时会碰到的字段

下面这张表里的字段名，逐字取自截至 2026-08-07 的官方参考文档。第三列写的是它跟”拆 role”这件事的关系，不是对客户端内部行为的断言。

字段	官方参考文档对它的说明	与拆 role 的关系	出处
`name`	必填，唯一标识	拆开后有多条模型配置，靠它区分，别重名	docs.continue.dev/reference
`provider`	必填，如 openai、ollama、mistral	补全走本地、对话走远端时，两条配置的这一项通常不同	同上
`model`	必填，具体模型名	嵌入/重排要填的是对应那类模型的名字，不是对话模型	同上
`apiBase`	可选，覆盖默认 API 端点	几个角色打到不同服务商时，各自那条配置单独写	同上
`roles`	可选，七种取值，默认 `[chat, edit, apply, summarize]`	本篇主角	同上
`capabilities`	可选，如 `tool_use`、`image_input`	声明这条配置对应的能力项	同上
`defaultCompletionOptions`	可选，temperature、maxTokens、topP 等	每条配置各写各的，补全和对话的取值需求不一样	同上
`autocompleteOptions`	可选	名字对应 autocomplete 这一路的选项	同上
`chatOptions`	可选	名字对应 chat 这一路的选项	同上
`requestOptions`	可选，timeout、headers、proxy 等 HTTP 配置	走代理或自建网关时，按条配置	同上

官方参考页给出的模型配置示例长这样（原样引用，未改字段名）：

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

从这段能看出结构：models 是一个列表，每一项是一条独立的模型配置，roles 写成子项列表。要让补全、嵌入、重排各归各的模型，做法就是在 models 块里再写若干条配置，每条填上自己的 name／provider／model，需要换端点的加 apiBase，并把该条负责的 role 写进它自己的 roles 里。这里不给拼凑出来的完整示例——字段名拼错一个，排查成本比省下的这几行高得多，请以官方参考页的示例为模板。

顺带说一句跨产品的对照，免得你把别家的写法搬过来。同样是”自定义端点”，字段名各家都不一样：Continue 叫 apiBase，Zed 的 settings.json 里叫 api_url，goose 用环境变量 OPENAI_HOST（另有 OPENAI_BASE_PATH），Crush 是命令行参数 --base-url，Cline / Roo Code / Kilo Code 的界面上叫 Base URL。这些不是同一个东西，串台就是白排查。模型清单的来路也不同：Kilo Code 在凭据有效时会从 /v1/models 端点自动拉取模型列表，自动检测失败可手填；Zed 要在 available_models 里手写；Continue 则是在 models 块里手写。以上都是各自官方文档在核对日的写法，读者可自行复核。

四、拆开之后，配套要一起看的几项

工具调用是硬门槛，不是配置项能变出来的。 Continue 的 capabilities 里有 tool_use 这个取值，Zed 的 capabilities 对象里也有 tools、parallel_tool_calls 之类的开关。但这类字段是”声明”，模型端不支持 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 官方文档的说法，不是本文对所有产品的断言）；它还建议先查服务商文档确认该模型是否支持工具调用。这条对你选 chat 角色的模型有直接参考价值：挂在对话角色上的模型如果不支持工具调用，很多”让它自己去读文件、跑命令”的用法会从根上走不通。

每条配置的生成参数要单独看。 defaultCompletionOptions 里的 maxTokens 是按条写的。这里有个属于 OpenAI 兼容协议层的通用机制、而不是某家产品文档的记载：最大输出设得太小，长回答会在中途被截断；上下文相关的上限填得比服务端实际允许的更大，请求可能直接被服务端拒掉。这属于机制推理，实际报错文案和边界以你所用服务商的文档为准。

密钥别跟着配置文件进版本库。 Continue 的密钥字段名以官方文档为准，本文不猜。但可以借两家的做法说清这件事该怎么想：Zed 的文档原话是 “Do not put API keys in settings.json.”，凭据走 provider 设置界面或环境变量（命名规则是 <PROVIDER_NAME>_API_KEY），另一页还写明 “Provider keys saved through Zed are stored in the system keychain, not in settings.json.”——keychain 指操作系统自带的凭据保管服务，由系统加密存放，程序按权限取用，不落在明文文件里。Gemini CLI 走的是另一条路：它的 settings.json 支持环境变量插值，写成 $VAR_NAME 或 ${VAR_NAME}，加载时自动解析——所谓插值就是配置文件里只写一个变量名占位，真正的值运行时从环境变量取，于是配置文件可以进版本库而密钥不进。你按同样的思路对待 Continue 的配置文件即可。

五、边界与代价：拆开之后你放弃了什么

拆 role 不是免费的。

你放弃了”一条配置全包”的简单。 默认那四个角色绑在一起，好处是只有一处要维护。拆成三四条之后，端点、密钥、模型名、超时设置都成了多份。哪天服务商换了地址，你要改的不是一个地方。团队里每人一份本地配置时，这个成本会乘以人数。

它不管服务商那边到底有没有这些能力。 把某条配置的 roles 写上 embed，不代表对面的服务商真提供嵌入端点；rerank 同理。这一层的可用性只能查服务商文档，配置文件不会替你验证。

它不管检索效果。 嵌入和重排配通了，只说明链路能跑，不说明检索结果好。切块策略、元数据过滤、评测方法，都是配置之外的事，跟本篇的关注点不重叠。

它不管成本核算。 Continue 的参考页里没有价格字段这一说（有些图形界面的客户端会让你手填输入/输出单价，那是另一批产品的设计，别按到 Continue 头上）。多挂几个模型之后账单怎么变，你得自己在服务商那边看。

不适用的场景也说清楚：如果你只是偶尔用对话问两句、并不用行内补全、也没接仓库检索，那默认的四个角色就够了，拆开纯属给自己添活。真正值得拆的信号只有两个——补全等不起，或者检索这条链路你确实要用。

六、避坑清单

1. 以为写了 roles 是往默认值上”追加”。 为什么会踩：文档写的是”默认是 [chat, edit, apply, summarize]”，容易读成”这四个永远在，你写的是加上去的”。参考页并没有逐条说明显式写 roles 之后是覆盖还是叠加。怎么避：把这条配置需要承担的角色全部列全，别指望默认值继续兜底；配完实际点一次对话、点一次改写，确认都还在。行为以官方文档和你实测的为准。

2. 把对话模型的名字直接填进嵌入或重排那条配置的 model。 为什么会踩：三条配置长得一样，复制粘贴时只改了 roles 忘了改 model。怎么避：拆分时按”先改 model、再改 roles”的顺序动手；name 起成能一眼看出用途的名字，出问题时日志里认得出是哪条。

3. 把别家的字段名搬到 Continue 上。 为什么会踩：搜索引擎上翻到的教程混着好几个产品，api_url、Base URL、OPENAI_HOST、--base-url 长得都像那么回事。怎么避：Continue 这一侧只认 apiBase。凡是从别处抄来的字段名，先回官方参考页确认它在不在字段清单里。

4. apiBase 结尾要不要带 /v1 靠猜。 为什么会踩：各家惯例不统一——Kilo Code 的文档明确说它接受 https://api.provider.com/v1 和 https://api.provider.com/v1/chat/completions 两种形态，后者是为端点结构非标准的服务商和自建网关准备的；Cline 文档里的 v0 Quickstart 示例填的是含 /v1 的地址。这几条是那两家文档的说法，Continue 的参考页没有就此给出规则。怎么避：以你所用服务商文档给出的端点为准，一次只改一处，改完立刻发一次请求验证，别同时动地址和模型名。

5. 给补全角色挂了一个上下文窗口很大、但延迟很高的模型。 为什么会踩：选模型时习惯性挑”更强的那个”，忘了补全这类请求的评判标准是响应速度。怎么避：补全和对话分开选型；补全那条配置的生成参数按”短输出”来设，autocompleteOptions 这条路的选项以官方文档为准。

6. 密钥写进配置文件，然后跟着仓库一起提交。 为什么会踩：为了让队友”拿来即用”，直接把完整配置提交了。怎么避：参考前一节两家的做法——凭据交给系统凭据存储或环境变量，配置文件里只留引用；提交前先看一眼 diff 里有没有长串字符。

7. 觉得 capabilities 写上 tool_use 就等于模型支持工具调用。 为什么会踩：把”声明能力”当成”启用能力”。怎么避：先查服务商文档确认该模型支持 OpenAI 兼容的 function calling，再回来写声明。Roo Code 的文档在这件事上给出的建议同样适用：先确认模型支不支持工具调用，再谈配置。

如果你是从”接入自定义端点”这一步开始摸的，配置文件之外的整体路径可以先看编辑器接入自定义 API 的通用做法；补全打算走本地模型的，参考本地模型接入编辑器。

数据来源与核对日期

本篇涉及的产品事实，全部来自下列官方文档页面，核对日期均为 2026-08-07。文档随时可能更新，实际以官方文档最新版为准。

Continue 配置参考（config.yaml、models 块、roles 取值与默认值、其余字段与 YAML 示例）：https://docs.continue.dev/reference
Roo Code OpenAI 兼容 provider（native tool calling 那句原话、建议先查服务商是否支持工具调用）：https://roocodeinc.github.io/Roo-Code/providers/openai-compatible
Kilo Code OpenAI 兼容 provider（Base URL 两种形态、/v1/models 自动拉取模型列表）：https://kilo.ai/docs/providers/openai-compatible
Cline OpenAI 兼容 provider（Base URL 字段、v0 Quickstart 示例含 /v1）：https://docs.cline.bot/provider-config/openai-compatible
Zed（api_url、available_models、capabilities、不要把 API key 放进 settings.json、keychain 那句原话）：https://zed.dev/docs/ai/use-api-access、https://zed.dev/docs/ai/configuration
goose（OPENAI_HOST、OPENAI_BASE_PATH）：https://goose-docs.ai/docs/getting-started/providers/
Crush（provider add 的 --base-url 参数）：https://raw.githubusercontent.com/charmbracelet/crush/main/README.md
Gemini CLI（settings.json 的 $VAR_NAME / ${VAR_NAME} 环境变量插值）：https://google-gemini.github.io/gemini-cli/docs/get-started/configuration.html

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

不写价格、免费额度、订阅档位、限速数字。这类信息变动频繁，本次也未核实，写下来只会误导。请直接查你所用服务商的定价页。
不写任何产品的完整模型清单和版本号。模型上下线的节奏比文章更新快；文中出现的模型名只是官方示例里原样出现过的字符串，不构成推荐。
不写各 role 在客户端内部的调度细节。官方参考页列出了取值和默认值，没有逐条说明内部行为；文中对每个角色的解释按通用含义给出，已在正文标明，实际行为以官方文档为准。
不写 UI 菜单的逐级路径。界面改版后这类描述最先失效。
文中涉及”最大输出设太小会截断""上限填过大可能被服务端拒绝”的部分，属于 OpenAI 兼容协议层的通用机制推理，不是上述任何一家文档的原文记载，已在正文中标明。

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