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

接完自定义模型别急着干活：一份十项验收清单，逐项跑一遍才算接通

2026-08-07

“填完表单没报错”和”这个模型真能在这个工具里干活”，是两件互不相干的事。 前者只证明配置项被接受了，后者要求端点形态、模型 ID、工具调用协议、上下文窗口数值、角色分工五件事同时对上。多数人卡住的位置不是不会填，而是填完就直接派活，等到第三轮对话崩了才回头怀疑配置——那时候已经分不清是模型不行、网关不行，还是自己少填了一栏。

下面这十项是一份验收动作清单：每一项都告诉你查什么、在哪查、查完能排除掉哪一类怀疑。全部依据各产品官方文档在 2026-08-07 当天的记录，来源 URL 列在文末，请以官方文档最新版为准。

先说清本篇和站内几篇的分工：AI 工具选型流程解决的是”该选哪个工具”，编辑器接入自定义 API解决的是”怎么把配置填进去”，Agent 验收标准解决的是”跑起来之后怎么判断产出合格”；这一篇夹在中间，只管”填完之后、派活之前，你还得亲手确认哪十件事”。

一、第 1-3 项：地址、字段归属、密钥落点

第 1 项：确认端点该不该带 /v1。 OpenAI 兼容端点，指的是一类对外暴露与 OpenAI Chat Completions 相同请求格式的 HTTP 接口，不是”就是 OpenAI”。所以地址栏填的绝不是官方那个地址——Cline 文档就明确提示这里不会是 https://api.openai.com/v1，Roo Code 文档同样提示 Base URL 不会是官方 OpenAI 那个地址。至于要不要带 /v1，各家取向不同：Kilo Code 文档写明它接受两种形态，标准形态 https://api.provider.com/v1，或完整端点 https://api.provider.com/v1/chat/completions，后者是为端点结构非标准的服务商与自建网关准备的；Zed 文档示例是 https://example.com/v1；Cline 文档里那个 v0 Quickstart 示例填的是 https://api.v0.dev/v1，含 /v1；Groq 官方 API 参考给出的 base URL 是 https://api.groq.com/openai/v1。goose 则是把地址拆成两段：OPENAI_HOST 加可选的 OPENAI_BASE_PATH。

验收动作：拿服务商文档上写死的那个地址原样抄，别自己拼；抄完对照你所用工具的文档示例，看它示例里的地址带不带 /v1，形态对齐再往下走。

第 2 项：确认你填的字段属于这一家。 这是最容易翻车的一项，因为”base URL”这个概念在各家的字段名完全不同：Cline、Roo Code、Kilo Code 在配置里叫 Base URL；Continue 的 config.yaml 里叫 apiBase；Zed 的 settings.json 里叫 api_url；goose 用环境变量 OPENAI_HOST；Crush 用命令行参数 --base-url。这些不是同一个东西的别名，是各自产品的配置键。你从别的教程里抄一段配置过来，字段名对不上家，就是无效配置。

验收动作：打开你正在用的那个产品的官方文档页，逐字核对字段拼写，一个字母都不要靠记忆补。

第 3 项：确认密钥没有落在会被提交的文件里。 Zed 文档在这一点上写得很直接，原话是 “Do not put API keys in settings.json.”，并说明凭据走两条路——provider 设置界面，或环境变量，命名规则是 <PROVIDER_NAME>_API_KEY，provider 名为 my-provider 时对应 MY_PROVIDER_API_KEY；其 configuration 页另有一句原话：“Provider keys saved through Zed are stored in the system keychain, not in settings.json.” keychain 指操作系统自带的凭据保管服务，密钥由系统加密保存，程序按需取用，不落在明文配置里。goose 的做法是密钥走各自的环境变量，配置持久化在 config.yaml。Gemini CLI 则支持在 settings.json 里做环境变量插值，写 $VAR_NAME 或 ${VAR_NAME}，加载时自动解析——插值就是配置文件里只写变量名占位、真实值运行时从环境里取，好处是配置文件能进版本库而密钥不进。

验收动作：配完之后在仓库里搜一遍你那串密钥的前几位，搜得到就说明它进了工作区文件，得改走上面任一条路。这一步的展开可参考API 密钥安全管理。

二、第 4-6 项：模型 ID、工具调用、上下文窗口

第 4 项：确认模型 ID 的来源。 各家的取向不一样：Kilo Code 文档说凭据有效时它会从 /v1/models 端点自动拉取模型列表，自动检测失败可手动填模型 ID；Zed 要在 available_models 数组里手写，每项含 name（模型标识）、display_name（界面显示名）、max_tokens；Continue 在 models 块里手写，必填 name、provider、model 三项；Cline 的 Model 一栏是选择或输入具体的模型 ID。

验收动作：如果是手写的，去服务商文档里把模型 ID 原样复制；如果是自动拉取的，确认拉到的列表里确实有你要的那一个，拉不到就说明凭据或端点还没通，别急着怀疑模型。

第 5 项：确认这个模型支持原生工具调用。 原生工具调用（native tool calling，也叫 function calling）指模型按接口协议直接返回结构化的”要调哪个工具、传什么参数”，而不是靠在文本里输出一段标记再由客户端解析。Roo Code 官方文档在这件事上给了一条硬限制，原话是：“Roo Code uses native tool calling exclusively. This is the only supported tool protocol — there is no XML-based fallback.” 也就是说，不支持原生工具调用的模型在这里用不了，文档建议先查服务商文档确认该模型是否支持工具调用。这一条值得单独拎出来，因为它不是”体验差一点”，而是”直接不能用”，而聊天窗里试一句”你好”是试不出来的。

验收动作：派活之前，让它执行一个必须读文件才能回答的任务。工具没被调起来，问题多半在这一层。相关判断可参考Agent 工具调错。

第 6 项：确认上下文窗口这一栏由谁填。 上下文窗口指模型单次能看到的文本总量上限，超出的部分模型看不见。有一类场景需要你手填这个数：Cline 的 Model Configuration 区列出了 Context Window size，Roo Code 列出了 Context Window，Zed 的 available_models 每项含 max_tokens（文档说明是上下文窗口上限），aider 对它不认识的模型用 .aider.model.metadata.json 注册上下文上限与价格，字段包括 max_tokens、max_input_tokens、max_output_tokens。

要说明的是：Cline 与 Roo Code 那几栏，本篇依据的文档页记录里只列了字段名，没有逐条说明客户端内部拿这个数做什么；所以这里只讲”这一项由你填、填的是上下文窗口这个量”，不替产品断言它的内部行为，实际用途请以官方文档为准。至于”填得比服务端实际上限大会怎样”，那属于 OpenAI 兼容协议层的一般机制推理（请求超限通常由服务端拒绝），不是上述任何一家文档的记载。

验收动作：把服务商文档写的窗口数字抄进去，别拍脑袋填一个整数。预算怎么算见Agent 上下文预算。

三、第 7-10 项：能力开关、角色分工、优先级、例外

第 7 项：确认能力开关这一组的填法。 Continue 的可选字段 capabilities 文档举了 tool_use、image_input；Zed 的 capabilities 对象控制能力开关，文档提到 tools、images、parallel_tool_calls 等。Cline 与 Roo Code 的高级项里都列出了 Image Support 与 Computer Use——同样地，本篇依据的那两页记录里只出现了字段名，没有说明客户端拿它们做什么，所以这里不展开用途，只提醒你：这一组是由你声明的，声明得跟模型实际能力不一致，后续行为就不好归因。

第 8 项：确认模型的角色分工。 Continue 的 roles 字段取值有 chat、autocomplete、embed、rerank、edit、apply、summarize，文档写明默认是 [chat, edit, apply, summarize]。这里的 embed 指嵌入，把文本转成向量以便按语义检索；rerank 指重排，对检索回来的候选再做一次相关性排序。这两个角色和聊天不是一回事，一个通用聊天模型不一定担得起。

验收动作：如果你只在 models 块里配了一个模型又没写 roles，那它拿到的就是那四个默认角色；你想让它做补全或检索相关的活，得显式声明。

第 9 项：确认这份配置的作用域和优先级。 aider 的 .aider.model.settings.yml 可放四处，按顺序加载、后加载的优先：home 目录、git 仓库根目录、启动 aider 的当前目录、--model-settings-file <filename> 指定的自定义路径；另有特殊模型名 aider/extra_params 可让设置对所有模型全局生效。Gemini CLI 的 settings.json 有四处位置（系统默认 /etc/gemini-cli/system-defaults.json、用户级 ~/.gemini/settings.json、项目级 .gemini/settings.json、系统覆盖 /etc/gemini-cli/settings.json，后两个 Linux 路径），优先级从低到高是：硬编码默认 → system defaults 文件 → user settings → project settings → system settings → 环境变量 → 命令行参数。Crush 的 crushrc 优先级是项目级 ./.crushrc 高于全局 ~/.config/crush/crushrc。

验收动作：改完一处没生效，先别改第二处，先按上面的顺序确认是不是被更高优先级的那份盖住了。

第 10 项：确认有没有该走专用通道的例外。 Kilo Code 文档明确写了一条提醒：Azure GPT-5 不要用通用的 OpenAI 兼容 provider，要用 Kilo 原生的 azure provider，因为 Azure 会拒绝 max_tokens 参数。这类”看起来兼容、实际不兼容”的情况，通用配置路径是兜不住的。

验收动作：接入前先在该产品文档里搜一下你这家服务商的名字，看有没有单独一节。收尾时再跑一个真实任务——让它读一个真实文件、改一处真实代码、跑一次真实命令，走完一整轮再收工。

四、十项速查表

下表里的配置项名称逐字取自各家官方文档在 2026-08-07 的记录，“你要自查什么”一栏写的是你能亲手执行的动作，不是对产品内部行为的描述。

配置项（逐字）它是什么出自哪家文档你要自查什么
Base URL服务商 API 端点地址Cline / Roo Code / Kilo Code是否原样抄自服务商文档；带不带 /v1 与该产品示例是否一致
apiBase覆盖默认 API 端点的可选字段Continue写在 models 块下、拼写与文档一致
api_url自定义 base URLZed是否嵌在 settings.json 的 language_models → openai_compatible → provider 名这一层结构里
OPENAI_HOST / OPENAI_BASE_PATH自建或企业内部 OpenAI 兼容端点的地址设置goose两段是否都设了、是否与服务商地址切分方式一致
--base-urlprovider add 命令的参数Crush命令是否按 README 示例形态书写
<PROVIDER_NAME>_API_KEY环境变量形式的密钥Zed变量名是否与 provider 名对应（my-provider → MY_PROVIDER_API_KEY）
$VAR_NAME / ${VAR_NAME}settings.json 内的环境变量插值Gemini CLI对应环境变量是否真的存在于进程环境里
Context Window size / Context Window需手填的上下文窗口项Cline / Roo Code数值是否抄自服务商文档
max_tokens上下文窗口上限Zed（available_models 每项）与服务商文档标注是否一致
max_input_tokens / max_output_tokens为 aider 不认识的模型注册的上限aider（.aider.model.metadata.json）是否写进了正确的注册文件
roles模型承担的角色Continue不写时落到默认的 [chat, edit, apply, summarize] 是否符合你的预期
capabilities能力开关Continue（tool_use、image_input）/ Zed（tools、images、parallel_tool_calls）声明与模型实际能力是否一致

五、边界与代价：这份清单不管什么

它不管模型好不好用。 十项全过，只说明这条链路通了、协议对上了、参数没串台。生成质量、指令遵循、长任务稳定性，一项都不在这份清单里。判断产出合格与否是另一套方法，见Agent 验收标准。

它不管钱。 本篇不写任何产品的价格、免费额度、订阅档位、限速数字。需要说明的是，aider 的 .aider.model.metadata.json 文档示例里出现了 input_cost_per_token、output_cost_per_token 这类字段和具体数值，那是官方文档的示例值，不是任何真实模型的报价，抄的时候别当真实单价用。Cline 与 Roo Code 的高级项里也出现了输入/输出价格的字段名，同样不构成报价信息。

它不管界面。 各家的配置入口长什么样、在哪一层菜单、报错怎么提示，本篇一概不写——请以你实际看到的界面为准。文档里明确记下的操作入口只有两类可复述：goose 的 CLI 流程是跑 goose configure，选 Configure Providers，从列表选 provider，填 API key 与附加参数，选模型；Zed 的相关命令是 agent: open settings、zed: open settings、zed: open settings file，另有 disable_ai 设置可关闭全部 AI 功能，写法是 "disable_ai": true。

它不是各家能力的完整清单。 本篇只依据各产品官方文档的特定几页。某一项没在这里出现，只说明本篇依据的那一页记录里没有它，不等于该产品没有这个能力。要下判断，请回到官方文档原页。

它不适用于哪些场景。 如果你走的是产品托管的模型、复用已有订阅或官方网关，这份清单里关于端点和模型 ID 的几项就用不上了。Zed 文档列出的模型接入路径共五类：Zed 托管模型、自带 API key、复用已有订阅、网关（OpenRouter / Vercel AI / Amazon Bedrock）、本地模型（Ollama / LM Studio / 自托管）——只有”自带 API key”和”自托管/网关”这几条路才需要逐项验收。

还有一个明确的空白：Windsurf。核对日当天 https://docs.windsurf.com/windsurf/models 返回 307 跳转到 https://docs.devin.ai/desktop/models，该页自述为 Devin Desktop 的文档，未提及是否支持自带 API key、也未给出配置位置。所以本篇不写它的接入做法，请以官方文档为准。

六、避坑清单

坑一：从别家教程抄配置片段。 为什么会踩——各家字段名长得像、语义也像，apiBase、api_url、Base URL、OPENAI_HOST、--base-url 在人脑里都是”那个地址”。怎么避——只从你正在用的那个产品的官方文档页复制，抄完逐字比对拼写，不靠记忆补字母。

坑二：地址的 /v1 凭感觉加减。 为什么会踩——不同产品与服务商对”端点从哪一段开始”的切分不同，Kilo Code 文档就明说它接受两种形态，goose 干脆把 host 和 path 拆成两个变量。怎么避——服务商文档给的地址原样抄，需要调整时以你所用产品文档的示例形态为准，两边都看一眼再落笔。

坑三：只用聊天验收。 为什么会踩——聊天不触发工具调用，模型不支持原生工具调用这件事在闲聊里完全暴露不出来，等到派真活时才崩。怎么避——第一个验收任务就设计成必须读文件或必须执行命令的，一次跑通再往下。

坑四：上下文窗口随手填个整数。 为什么会踩——这一栏在几家产品里都由你填，填什么都能存下来，看上去像”配好了”。怎么避——去服务商文档抄真实数值，抄不到就不要臆造。

坑五：密钥写进配置文件然后提交。 为什么会踩——图省事，写进去当场就能跑通，风险要到推上去才显形。怎么避——按第 3 项那三条路走，配完在仓库里搜一遍密钥前缀确认没留痕。

坑六：改错了地方的配置文件。 为什么会踩——aider、Gemini CLI、Crush 都是多处配置且有优先级，你改的那份可能被更高优先级的盖住，表现就是”改了没反应”，很容易误判成产品有 bug。怎么避——记住各自的优先级顺序（第 9 项列了），排查时从最高优先级那一层往下找。

坑七：把特殊 provider 当通用兼容端点接。 为什么会踩——名字里带 OpenAI 就默认它兼容。怎么避——接入前在产品文档里搜一遍服务商名，看有没有专门的一节，比如 Kilo Code 就单独提醒了 Azure GPT-5 要走原生 azure provider。

数据来源与核对日期

以下 URL 为本篇依据的官方文档页，核对日期均为 2026-08-07。文档随时可能更新，正文提到的所有字段名与行为均以官方文档最新版为准。

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

  1. 价格、免费额度、订阅档位、限速数字——这类信息变动频繁，且本次核对未采集，写出来只会误导。aider 文档示例中出现的单价数字是文档示例值，不是真实报价。
  2. 完整模型清单——各家支持的模型随时增删，本篇只在引用官方示例时提到过个别模型 ID，不构成清单。
  3. 版本号、发布日期与产品之间的关系——未核实，一律不写；Windsurf 那一条只陈述核对日当天的跳转事实，不据此推断任何产品归属。
  4. 界面细节与菜单层级——本次核对的是配置层事实，界面请以你实际看到的为准。
  5. 各产品字段的内部用途——凡官方文档页只列了字段名而未说明用途的（如上下文窗口以外的几个高级项），本篇不替产品断言其行为。

需要什么就去查对应那一页，别拿这篇当权威。它的作用是提醒你查哪几件事，不是替代文档。

这个系列的其余文章

这一组文章讲的是同一件事的不同侧面：把自己的模型接进编辑器与终端 Agent。上面的验收清单是收口，下面按四个方向列出其余各篇。

按产品接入

跨产品横向对比

接上之后的排查

成本、团队与配置管理

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

浏览课程 加入会员