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

编辑器与终端 Agent 接自定义模型：四种配置形态怎么挑

2026-08-07

挑工具的时候，你真正该先问的不是”它支持哪些模型”，而是”它把模型配置写在哪里”。 配置落在图形表单里，还是落在一个能进 Git 的文件里，还是落在 shell 的环境变量里，直接决定了这份配置能不能被复制、被评审、被一次性下发给二十个人。模型清单是会变的，配置形态基本不变。

这篇只谈配置形态这一层。同站已有的 编辑器接入自定义 API 的通用做法 讲的是单机把一个端点接通的完整步骤，API 接入方式对比 讲的是直连、网关、中转这些链路层的选择，终端 Agent 横评 比的是各家 Agent 干活的能力差别；本篇不重复这三件事，只把”配置写在哪种载体上、这对团队意味着什么”拆开讲。

下面提到的所有字段名、文件名、环境变量名，都来自各家官方文档在 2026-08-07 当天的记录，来源 URL 集中列在文末。这类东西会随版本变，动手前请以官方文档最新版为准。

一、先把两件事拆开：接入方式和模型能力

很多人配到一半卡住，是因为把两个问题混成了一个。

接入方式说的是：客户端怎么知道该往哪个地址发请求、用什么凭据、请求体里写哪个模型 ID。这一层的关键词是 base URL、API key、模型标识。所谓 OpenAI 兼容端点，指的是服务方按 OpenAI 那套 HTTP 接口约定（路径、请求体字段、返回结构）提供服务，于是任何写死了这套约定的客户端都能直接对接，不必为每家单独写适配。

模型能力说的是：这个模型本身会不会做某件事。最典型的是 原生工具调用（native tool calling，也叫 function calling）——模型按结构化格式输出”我要调用哪个工具、参数是什么”，客户端解析后真的去执行。编辑器类 Agent 要改文件、跑命令、读目录，靠的就是这个。

这两件事的分界线，在 Roo Code 的文档里写得最直接。它的原话是：“Roo Code uses native tool calling exclusively. This is the only supported tool protocol — there is no XML-based fallback.”（这是官方文档的说法，不是本文的判断。）文档同时建议，先去查服务商文档确认目标模型是否支持工具调用。意思很清楚：地址和密钥填对了，只是接入这一层通了；模型不支持原生工具调用，这条路在 Roo Code 上就是走不通的，没有降级方案兜着。

所以配置之前先确认一件事：你要接的模型，服务商有没有说它支持 OpenAI 兼容的 function calling。这一步省了，后面所有排查都是白费。

二、形态一：图形界面表单——Cline、Roo Code、Kilo Code

这三家把接入做成了填表。

Cline 的 API Provider 选 OpenAI Compatible，必填三项：Base URL 填服务商给的 API 端点，文档明确提示这里不会是 https://api.openai.com/v1（那是官方 OpenAI API 的地址）；API Key 填服务商给的密钥，也可以勾选使用 Azure 托管身份认证（Azure managed identity）；Model 选择或输入具体的模型 ID。文档里的 v0 Quickstart 示例是 Base URL = https://api.v0.dev/v1，Model ID = v0-1.0-md，注意这个示例是含 /v1 的。

Cline 的 Model Configuration 区还列出了这些可自定义项：Max Output Tokens、Context Window size、Image Support、Computer Use、Input Price、Output Price。这里要说明白：本篇依据的那一页记录里只列出了这些项的名字，没有逐条说明客户端内部拿它们做什么。所以你可以确定的只有”这几项要由你填、Max Output Tokens 和 Context Window size 填的是 token 数量级的数字、Input Price 和 Output Price 填的是单价”，至于填完之后客户端具体拿它算什么、在什么时机用，以官方文档为准，本文不替它下断言。

Roo Code 的三个主参数同样是 Base URL、API Key、Model，文档也提示 Base URL 不会是官方 OpenAI 那个地址。可自定义项包括 Max Output Tokens、Context Window、Image Support、Computer Use 和输入/输出价格。加上前面引用的那条原生工具调用限制，它对模型的要求就多了一条硬门槛：模型不支持原生工具调用，这一家就用不了。

Kilo Code 的表单字段更细，新建一个 provider 要填：Provider ID（唯一标识，文档示例是 my-provider）、Display name（界面显示名）、Provider API（选 OpenAI Compatible，走 chat completions 端点）、Base URL、API key、Models（手动添加或自动检测）、Headers（可选，自定义 HTTP 头，键值对形式）。

Kilo Code 在 Base URL 这一项上给了两种形态：标准形态 https://api.provider.com/v1，或者完整端点 https://api.provider.com/v1/chat/completions。文档说明第二种是为端点结构非标准的服务商和自建网关准备的。凭据有效时，它会从 /v1/models 端点自动拉取模型列表，自动检测失败可以手填模型 ID。文档还专门写了一条 Azure GPT-5 的提醒：不要用通用的 OpenAI 兼容 provider，要用 Kilo 原生的 azure provider，因为 Azure 会拒绝 max_tokens 参数。

这对你意味着什么：表单形态上手最快，一台机器十分钟能接通。代价是这份配置天然是本机的、个人的——它不在你的仓库里，评审不到、diff 不出来、也没法随项目一起分发。一个人干活或小团队各配各的，够用；要统一二十个人的配置，这条路会变成二十次口头指导。另外，Kilo Code 那个自定义 Headers 字段值得留意，自建网关常常要靠额外 HTTP 头做路由或鉴权，有这个口子就不用在网关侧另做兼容。

三、形态二：YAML 配置文件——Continue 与 aider

YAML 形态的核心价值是：配置是一份文本，能进版本库，能被 review。

Continue 的配置文件是 config.yaml，模型配置写在 models 块下。必填字段三个：name（唯一标识）、provider（如 openai、ollama、mistral）、model（具体模型名）。可选字段包括 apiBase（覆盖默认 API 端点）、roles、capabilities（如 tool_use、image_input）、defaultCompletionOptions（temperature、maxTokens、topP 等）、autocompleteOptions、chatOptions、requestOptions（timeout、headers、proxy 等 HTTP 配置）。

文档给的示例可以原样参考：

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

roles 的取值有 chat、autocomplete、embed、rerank、edit、apply、summarize，默认是 [chat, edit, apply, summarize]。这里的 embed 指嵌入模型——把文本转成向量用于相似度检索；rerank 指重排模型——对检索回来的一批候选重新打分排序。这份取值清单本身透露的信息是：配置的粒度不是”选一个模型”，而是按角色分别指派——对话一个、补全一个、检索链路的嵌入和重排各一个。这是按角色名做的理解，客户端在每个角色上具体怎么调度、各角色的行为边界如何，官方文档并未逐条展开，以官方文档为准。

aider 走的是另一种 YAML 思路：模型设置文件 .aider.model.settings.yml 可以放四个位置，按顺序加载、后加载的优先——home 目录、git 仓库根目录、启动 aider 的当前目录、--model-settings-file <filename> 指定的自定义路径。这个层叠顺序很实用：个人默认放 home，项目共识放仓库根并提交进版本库，临时试验用命令行参数顶掉。

对 aider 不认识的模型，用 .aider.model.metadata.json 注册上下文上限与价格，文档示例是：

{
    "provider/model-name": {
        "max_tokens": 4096,
        "max_input_tokens": 32000,
        "max_output_tokens": 4096,
        "input_cost_per_token": 0.00000014,
        "output_cost_per_token": 0.00000028,
        "litellm_provider": "provider",
        "mode": "chat"
    }
}

必须说清楚：这里的数值是官方文档的示例值，不是任何真实模型的报价，别照抄当成价格用。

aider 还有一个 extra_params，可以把任意参数透传给 litellm.completion()，包括 extra_headers，文档示例：

- name: provider/model-name
  extra_params:
    extra_headers:
      Custom-Header: value
    max_tokens: 8192

另外，特殊模型名 aider/extra_params 可以让设置对所有模型全局生效；文档提到的其他设置项名还有 edit_format、weak_model_name、use_repo_map、cache_control、accepts_settings。

这对你意味着什么：YAML 形态适合”配置本身需要被讨论”的团队。谁把 temperature 调到 1.2、谁给某个模型加了自定义 header，在 PR 里一眼就能看见。aider 的四级层叠还额外解决了一个老问题——个人偏好和项目约定不再互相覆盖，各占一层。

四、形态三：JSON settings——Zed 与 Gemini CLI

Zed 把模型接入放进 settings.json，文档示例结构如下：

{
  "language_models": {
    "openai_compatible": {
      "my-provider": {
        "api_url": "https://example.com/v1",
        "available_models": [
          {
            "name": "my-model",
            "display_name": "My Model",
            "max_tokens": 128000
          }
        ]
      }
    }
  }
}

字段含义文档写得很清楚：api_url 是自定义 base URL；available_models 是模型数组，每项含 name（模型标识）、display_name（界面显示名）、max_tokens（上下文窗口上限）；capabilities 对象控制能力开关，包括 tools、images、parallel_tool_calls 等。这里的上下文窗口指的是一次请求里”提示词加输出”能占用的 token 总量上限，超出这个量的历史就装不下了。

密钥这一项 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 指操作系统自带的凭据保管服务，密钥由系统加密保存，不落在明文文件里。

相关命令有 agent: open settings（配 LLM provider）、zed: open settings、zed: open settings file；想彻底关掉 AI 功能，用 disable_ai 设置，写法是 "disable_ai": true。Zed 文档列出的模型接入路径共五类：Zed 托管模型、自带 API key、复用已有订阅、网关（OpenRouter / Vercel AI / Amazon Bedrock）、本地模型（Ollama / LM Studio / 自托管）。

Gemini CLI 同样是 settings.json，但它把”配置从哪来”这件事摊得更开。文件有四处位置：系统默认 /etc/gemini-cli/system-defaults.json（Linux）、用户级 ~/.gemini/settings.json、项目级的项目根 .gemini/settings.json、系统覆盖 /etc/gemini-cli/settings.json（Linux）。优先级从低到高是：硬编码默认 → system defaults 文件 → user settings → project settings → system settings → 环境变量 → 命令行参数。

它还支持在 settings.json 里做环境变量插值——写 $VAR_NAME 或 ${VAR_NAME}，加载时自动解析成对应环境变量的值。这个机制的意义在于：配置文件里只写变量名不写真值，文件就能安心提交进版本库，密钥留在环境里。.env 的查找顺序是当前工作目录 → 逐级父目录（到项目根或 home 为止）→ 用户 home 的 ~/.env。相关项包括 GEMINI_API_KEY（Gemini API 密钥）、GEMINI_MODEL（默认模型），以及 settings.json 里的 model.name 和 security.auth.selectedType。文档还说明，设置按类别组织成顶层对象（general、ui、tools、model、context 等），每个设置要放进对应的类别里。

这对你意味着什么：JSON settings 形态最适合”配置要下发、密钥不下发”的场景。项目级文件进仓库统一模型和参数，密钥各人放各人的 keychain 或环境变量，两件事彻底分开。Gemini CLI 那条七级优先级链尤其值得记住（硬编码默认、system defaults 文件、user settings、project settings、system settings、环境变量、命令行参数，共七层）——排查”我明明改了却不生效”，顺着这条链从高往低找，通常一次就命中。

五、形态四：环境变量与 CLI 子命令——goose 与 Crush

goose 的 CLI 配置是一条交互流程：跑 goose configure → 选 Configure Providers → 从列表选 provider → 填 API key 与附加参数 → 选模型。桌面端在 Settings 的 Models 页配置，文档列出的入口有 Quick Setup with API Key、ChatGPT Subscription（浏览器 OAuth）、Agent Router by Tetrate、OpenRouter、Other Providers（手动配置）。

环境变量方面，GOOSE_PROVIDER 和 GOOSE_MODEL 设默认 provider 与模型，各家密钥用各自的变量（文档举例 ANTHROPIC_API_KEY、OPENAI_API_KEY）。接自建或企业内部的 OpenAI 兼容端点，设 OPENAI_HOST，另有可选的 OPENAI_BASE_PATH。配置持久化在 config.yaml。

goose 文档自述支持 40+ 个 LLM provider，并说 “works best with Claude 4 models”，理由是这些模型的工具调用能力——这是官方文档的说法，本文不替它背书。文档提到的免费路径有 Groq（开源模型 + 快速推理）、Google Gemini 免费档、本地模型（Ollama / LM Studio / Docker Model Runner），具体额度数字本篇不写。

Crush 的配置文件是 crushrc，bash 风格加 Crush 内建命令，不是 JSON。优先级是项目级 ./.crushrc 高于全局的 ~/.config/crush/crushrc（Unix 类系统）。加自定义 provider 用命令，README 的原文示例是：

provider add deepseek --type openai-compat \
  --base-url "https://api.deepseek.com/v1"

自定义 provider 必须是 OpenAI 兼容或 Anthropic 兼容 API；README 列出的 provider 有 Anthropic、OpenAI、Gemini、Ollama 与自定义本地模型。其他相关事实：支持 MCP（HTTP / stdio / SSE 三种传输）、LSP 集成、Agent Skills 标准（SKILL.md 格式）、基于权限的工具执行模型；CRUSH_DISABLE_METRICS=1 关闭用量统计；跨平台覆盖 macOS / Linux / Windows / BSD / Android；许可证是 FSL-1.1-MIT。

这对你意味着什么：这一类形态天然适合放进脚本和容器。GOOSE_PROVIDER、GOOSE_MODEL、OPENAI_HOST 全是环境变量，写进 Dockerfile、CI 的 secrets、devcontainer 定义都是顺手的事；Crush 的 provider add 是一条命令，写进新人入职脚本就行。代价是这份配置对人不可见——它散在 shell 环境和启动脚本里，出问题时得先搞清楚当前进程到底继承了哪些变量。

六、base URL 这一项，五种叫法一张表

跨产品迁移配置时最容易出事的就是这一项。下面表里的字段名全部逐字来自各家官方文档，别互相搬。

产品base URL 这一项叫什么配置载体出处（URL 见文末）
ClineBase URL图形界面表单Cline 官方文档 openai-compatible 页
Roo CodeBase URL图形界面表单Roo Code 官方文档 openai-compatible 页
Kilo CodeBase URL图形界面表单Kilo Code 官方文档 openai-compatible 页
ContinueapiBaseconfig.yamlContinue 官方文档 reference 页
Zedapi_urlsettings.jsonZed 官方文档 use-api-access 页
gooseOPENAI_HOST（另有 OPENAI_BASE_PATH）环境变量goose 官方文档 providers 页
Crush--base-urlprovider add 命令参数Crush 官方 README

/v1 要不要带，各家文档给的线索也不一样：Cline 文档里的 v0 示例是含 /v1 的；Kilo Code 明确接受 /v1 和 /v1/chat/completions 两种；Zed 的示例是 https://example.com/v1；Groq 官方给的 base URL 是 https://api.groq.com/openai/v1，鉴权走 Authorization 头，格式为 "Authorization: Bearer $GROQ_API_KEY"。goose 的设计不同，它把地址拆成 OPENAI_HOST 和 OPENAI_BASE_PATH 两段。所以”带不带 /v1”没有跨产品的统一答案，只能看你正在配的那一家的文档怎么写。

还有一件事跨产品有共性：上下文窗口经常要你手填。Cline 有 Context Window size，Roo Code 有 Context Window，Zed 在 available_models 里写 max_tokens，aider 用 .aider.model.metadata.json 里的 max_input_tokens / max_output_tokens。至于模型清单从哪来，三种做法都有：Kilo Code 从 /v1/models 自动拉取（失败可手填），Zed 要在 available_models 里手写，Continue 在 models 块里手写。

七、边界与代价：这套分类不管什么

按配置形态分类，是为了帮你选载体，不是帮你选模型。它明确不管这几件事。

不管模型好不好用。 表单填得再顺，模型不支持原生工具调用，在 Roo Code 上照样跑不起来。选型的第一道门槛是模型能力，不是配置便利性。

不管钱。 本篇不写任何产品的价格、免费额度、订阅档位、限速数字。Cline 表单里的 Input Price / Output Price、aider metadata 里的单价字段，本篇只说它们要由你填、填的是单价量纲，不说客户端拿它做什么，也不说该填多少。

不管完整清单。 每家的字段本篇只覆盖官方文档相应页面在核对日的记录，绝不是完整清单。看不到某一项，只能说明本篇依据的那一页记录里没有出现它，不等于该产品没有这项能力。

四种形态各有放弃的东西。 图形表单放弃了版本管理和批量下发；YAML / JSON 要求你先知道字段名，而字段名不跨产品通用，抄错就是配了个不存在的键；环境变量与子命令形态放弃了可见性，配置散在进程环境里，新人接手时看不到全貌。没有哪一类通吃，只有匹配不匹配。

Windsurf 本篇不写。 2026-08-07 当天，https://docs.windsurf.com/windsurf/models 返回 307 跳转到 https://docs.devin.ai/desktop/models，该页自述为 Devin Desktop 的文档，页面列出了模型与成本数据结构，但未提及是否支持自带 API key、也未给出配置位置。所以本篇不写它接自定义模型的做法，也不据此推断任何产品关系——这一条只是当天可复现的观察，请以官方文档为准。

八、避坑清单：为什么会踩、怎么避

把 A 家的字段名抄到 B 家。 为什么会踩：这几家做的事情高度相似，人脑会默认字段名也相似，于是把 Continue 的 apiBase 写进 Zed 的 settings.json，或者把 Zed 的 api_url 写进 Continue 的 config.yaml。怎么避：配之前先打开你正在配的那一家的文档，把字段名逐字对一遍；跨产品迁移时别复制配置块，只复制值。

以为地址通了就等于能用。 为什么会踩：接入和能力是两层，测试时往往只发一句”你好”，聊天能返回就以为配好了，等 Agent 要改文件时才发现工具调用不通。怎么避：接完先跑一个必须调用工具的任务（比如让它读一个文件），而不是只做对话测试；配 Roo Code 之前，先按它文档的建议去服务商那边确认模型是否支持工具调用。

把密钥写进配置文件然后提交进仓库。 为什么会踩：文件形态的配置天然想进版本库，密钥又刚好挨着别的字段。怎么避：Zed 的做法是文档直接禁止（原话 “Do not put API keys in settings.json.”），走 provider 设置界面或 <PROVIDER_NAME>_API_KEY 环境变量，密钥由系统 keychain 保管；Gemini CLI 的做法是在 settings.json 里用 $VAR_NAME 插值，文件进库、真值留在环境。选一种照做，别自创第三种。

改了配置不生效，还在原地反复改。 为什么会踩：多数产品的配置来源不止一处。Gemini CLI 是七层链路（硬编码默认 → system defaults → user settings → project settings → system settings → 环境变量 → 命令行参数），aider 的 .aider.model.settings.yml 是四处按顺序加载、后加载的优先，Crush 是 ./.crushrc 盖过 ~/.config/crush/crushrc。怎么避：认准这条优先级链，从最高的一端往下查，先确认是不是被更高优先级的来源盖掉了，再动手改文件。

上下文窗口和最大输出这两个数拍脑袋填。 为什么会踩：好几家都要求你手填这两个量（Cline 的 Context Window size、Roo Code 的 Context Window、Zed 的 max_tokens、aider 的 max_input_tokens / max_output_tokens），文档不会替你查目标模型的真实上限。怎么避：去服务商文档查这个模型的真实上限，按真实值填。补一句机制层面的常识（这是 OpenAI 兼容协议的通用行为，不是上述任何一家文档的记载）：最大输出设得过小，长回答会在中途被截断；窗口值填得超过服务端的实际上限，超限请求通常会被服务端拒绝——具体表现以你所用服务商的返回为准。

遇到特殊后端还按通用兼容 provider 硬配。 为什么会踩：OpenAI 兼容不等于处处一致，某些后端对特定参数有额外要求。怎么避：看文档有没有针对性提醒。比如 Kilo Code 文档明确写了 Azure GPT-5 不要用通用的 OpenAI 兼容 provider，要用它原生的 azure provider，因为 Azure 会拒绝 max_tokens 参数。这类提醒往往就藏在同一页里。

端点结构非标准的自建网关直接填标准形态。 为什么会踩：默认以为客户端会自动拼上 /chat/completions。怎么避：Kilo Code 在文档里给了完整端点形态 https://api.provider.com/v1/chat/completions 这条路，就是为端点结构非标准的服务商和自建网关准备的；goose 则把地址拆成 OPENAI_HOST 和 OPENAI_BASE_PATH 两段。用哪家就按哪家的写法来，别混着填。

九、怎么按团队规模挑

一个人或两三个人：图形表单最省事，Cline、Roo Code、Kilo Code 都能十分钟接通，不必为了”规范”提前上文件形态。

需要把配置写进代码评审的团队：优先 YAML 或 JSON 形态。Continue 的 config.yaml、aider 的仓库根 .aider.model.settings.yml、Gemini CLI 的项目级 .gemini/settings.json 都能随项目走，谁改了什么在 diff 里看得见。密钥单独走 keychain 或环境变量插值，跟配置分开管。

要在 CI、容器、远程机器上跑 Agent 的团队：环境变量与子命令形态最顺手。GOOSE_PROVIDER / GOOSE_MODEL / OPENAI_HOST 是环境变量，Crush 的 provider add 是一条命令，两者都能直接写进镜像构建和启动脚本。想进一步理清链路层的选择，可以再读 API 接入方式对比 和 OpenAI 兼容端点是什么。

已经开始给不同任务派不同模型的团队：留意 Continue 的 roles，它把 chat、autocomplete、embed、rerank、edit、apply、summarize 拆成了独立角色，默认是 [chat, edit, apply, summarize]。要做分层调度，这种把角色显式化的设计比”全局选一个模型”好落地得多。

数据来源与核对日期

以下 URL 均为本篇引用事实的官方文档出处，核对日期统一为 2026-08-07。各家文档随版本更新，动手前请以官方文档最新版为准。

本篇没有写什么，以及为什么。 任何产品的价格、免费额度、订阅档位、限速数字、版本号与发布日期，一律不写——这些要么会过时，要么本次没有核实，写进来只会误导你做预算。各家的完整模型清单也不写，只在必要处引用文档里出现过的示例模型 ID（如 Cline 文档 v0 示例的 v0-1.0-md、Groq 文档中出现的 llama-3.3-70b-versatile 等），这些是文档举例，不代表当前可用清单。aider metadata 示例里的单价数字是官方文档的示例值，不是任何真实模型的报价。各产品的界面长什么样、菜单怎么走、报错文案是什么，本篇一概不描述，以你实际看到的界面为准。以上任何一项要拿来做决策，请直接查各产品官方文档的最新版本。

延伸阅读：同一组里的 自定义 provider 的 ID、显示名、模型名撞在一起、base URL 填不填 /v1；接完之后照 接完自定义模型别急着干活 逐项过一遍，才算真接通。

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

浏览课程 加入会员