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

base URL 填不填 /v1：几家 AI 编程工具的口径其实不一样

2026-08-07

**base URL 这一栏没有全行业统一的填法：同一个服务商端点，在这家要填到 /v1 结尾，在那家可以直接填到 /v1/chat/completions，在另一家干脆被拆成”主机”和”路径”两个字段分开填。**把它当成一个”到处都一样”的常量去复制粘贴，是接自定义模型时最常见的卡点。本篇只做一件事：把截至 2026-08-07 各家官方文档里能查到的口径摆到一起，让你知道自己面前这一栏该怎么填、填完怎么自己验。

站内已有几篇相邻的文章，分工是这样的：OpenAI 兼容端点到底兼容了什么讲的是协议层——服务商说自己”兼容 OpenAI”时，兼容的是哪些请求路径和字段；豆包 API 接入的坑和SiliconFlow API 接入讲的是具体某一家服务商侧怎么开通、怎么拿密钥。本篇不重复这两层，只盯客户端这一侧：编辑器和终端 Agent 的那一栏输入框（或那一行配置）到底期待你给它什么。

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

很多人配到一半分不清自己卡在哪，是因为把两件事混在一起了。

第一件是接入方式：客户端怎么找到服务端。它由三样东西决定——base URL（请求发到哪个地址）、API Key（凭什么让你发）、模型标识（你要的是哪个模型）。这一层的失败是网络层和 HTTP 层的失败。

第二件是模型能力：这个模型本身能不能干这个活。比如它支不支持 function calling（也叫工具调用，指模型按约定的 JSON 结构输出”我要调用哪个函数、参数是什么”，客户端据此真的去执行读文件、跑命令等操作），比如它的上下文窗口（一次请求里模型能看到的 token 总量上限）有多大。这一层的失败发生在连接已经打通之后。

这两件事的排查方向完全不同。地址填错，你在服务端那侧根本看不到一个像样的请求；模型不支持工具调用，请求是通的、密钥是对的，但 Agent 该动手的地方不动手。Roo Code 官方文档在这一点上写得很硬，原话是：“Roo Code uses native tool calling exclusively. This is the only supported tool protocol — there is no XML-based fallback.”（这是该产品官方文档的说法）文档同时建议，先去查服务商文档确认那个模型是否支持工具调用。也就是说，就算你 base URL 填得完全正确，选了个不支持原生工具调用的模型，在这家也是走不通的。

二、同一件事，六个不同的名字

先把”base URL 这一栏”在各家叫什么摊开。下表里的字段名逐字来自各家官方文档，最后一列的”你能复核的信号”是 OpenAI 兼容协议层的通用机制推理——不是任何一家文档的记载，写在这里是为了给你一个自查方向，实际行为以各产品官方文档和你的服务端日志为准。

配置项出自哪一家文档对它的说明填错时你能复核的信号（机制推理）
Base URLCline / Roo Code / Kilo Code（界面字段）填服务商给的 API 端点客户端把它和端点路径拼接后得到的实际请求路径不存在，服务端按 404 处理
apiBaseContinue（config.yaml）覆盖默认 API 端点同上；另需确认该模型条目的 provider 是否与端点匹配
api_urlZed（settings.json）自定义 base URL同上
OPENAI_HOSTgoose（环境变量）自建 / 企业内部 OpenAI 兼容端点的主机主机与路径分属两个变量，只改一个容易拼出半截地址
OPENAI_BASE_PATHgoose（环境变量，可选）与 OPENAI_HOST 配套的路径段同上
--base-urlCrush（provider add 命令行参数）自定义 provider 的地址参数命令执行时参数值写错，后续所有请求都指向错地址

看这张表你会发现一个规律：图形界面那三家（Cline、Roo Code、Kilo Code）用的是同一个英文标签 Base URL；配置文件那几家各起各的名——Continue 是 apiBase，Zed 是 api_url；到了 goose 这里，设计取向直接变了，它把地址拆成 OPENAI_HOST 与可选的 OPENAI_BASE_PATH 两段。

这就是为什么”照着某篇教程的截图填”经常出问题：那篇教程写的是 A 家的字段，你手上是 B 家的表单，两者对同一个值的期待形态可能根本不一样。

三、/v1 到底带不带：文档里能查到的四个坐标

卡在这一步的人最多。目前能从官方文档里直接查到的坐标有这么几个：

Cline。 文档明确提示，这里不会是 https://api.openai.com/v1（那是官方 OpenAI API 的地址，不是你的第三方服务商地址）。文档里的 v0 Quickstart 示例给的是 Base URL = https://api.v0.dev/v1，Model ID = v0-1.0-md——注意这个示例值是含 /v1 的。

Kilo Code。 这一家讲得最具体：Base URL 接受两种形态，一是标准形态 https://api.provider.com/v1，二是完整端点 https://api.provider.com/v1/chat/completions。文档说明第二种是为”端点结构非标准”的服务商与自建网关准备的。也就是说，如果你手上是公司内部那台自己搭的推理网关，路径不按 OpenAI 那套走，这家给你留了直接填到底的口子。

Zed。 官方 settings.json 示例里的 api_url 值是 https://example.com/v1，同样带 /v1。完整示例文档给的是这样：

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

Groq（作为真实服务商端点的参照）。 Groq 官方 API 文档给出的 base URL 是 https://api.groq.com/openai/v1，鉴权走 Authorization 头，格式为 "Authorization: Bearer $GROQ_API_KEY"。这个地址值得多看两眼：/v1 前面还有一段 /openai。所以”base URL 就是域名加 /v1”这条经验法则本身就不成立，真实端点长什么样只能去服务商文档里抄。

把这四个坐标合起来看，可以得到一条相对稳的做法：先去服务商文档抄它标注的 base URL 原值，再按客户端的口径决定要不要往后加路径。 反过来——先假设一个形态、再指望客户端替你补齐——是没有依据的。

需要说清的是分寸：上面只有 Kilo Code 一家在文档里写明了”接受两种形态”。其余几家，本篇依据的那几页记录里没有出现关于完整端点形态的说明，这不等于它们不支持，只是本篇没有可引用的依据，你需要以各自官方文档最新版为准。同样，“这一项要怎么填”的具体措辞我也不跨家搬——Kilo Code 的两种形态只对 Kilo Code 成立。

四、填完之后怎么自己验

不用等 Agent 跑一轮任务再判断对错，有几条更快的路。

看客户端会不会自动拉模型列表。 Kilo Code 的文档写明：凭据有效时，它会从 /v1/models 端点自动拉取模型列表；自动检测失败可以手动填模型 ID。具体动作是：把 Base URL 和 API key 填完之后，看 Models 那一项是不是自动出现了可选项——出现了就算通过，没出现就落到”手动填模型 ID”这条路上。这条对你的意义是——拉列表本身就是一次带鉴权的真实请求，所以它顺带把”地址通不通 + 密钥对不对”一起验了。（这一层因果是按 OpenAI 兼容协议的一般机制推的，文档只记载了”从 /v1/models 自动拉取”这件事本身。）

直接手工打一次请求。 拿服务商文档给的地址和鉴权头格式（例如 Groq 文档写的 "Authorization: Bearer $GROQ_API_KEY"），用你惯用的 HTTP 客户端发一次，看返回。这一步能把客户端配置层完全排除掉：如果手工请求通、客户端不通，问题就在填法；如果手工请求也不通，问题在地址、密钥或网络。相关的返回码怎么读，可以看401/403 排查那篇。

注意各家的模型列表来源不同。 Kilo Code 从 /v1/models 自动拉；Zed 要在 available_models 里手写（每项含 name 模型标识、display_name 界面显示名、max_tokens 上下文窗口上限）；Continue 在 models 块里手写。手写的那几家，模型 ID 敲错不会有任何”自动纠正”，你得逐字核对服务商给的 ID——Groq 文档里出现过的示例模型 ID 有 llama-3.3-70b-versatile、llama-3.1-8b-instant、openai/gpt-oss-20b 这类，可以感受一下这种 ID 的写法有多容易手滑。

顺带说密钥该放哪。 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，另有 GOOSE_PROVIDER、GOOSE_MODEL 设默认 provider 与模型，配置流程是跑 goose configure 后选 Configure Providers。Gemini CLI 支持在 settings.json 里用 $VAR_NAME 或 ${VAR_NAME} 做环境变量插值（插值就是配置文件里只写变量名、加载时再从环境里取实际值），好处是配置文件能进版本库而密钥不进。

五、边界与代价：这套对法不管什么

把上面这套流程走完，你解决的是”请求能不能正确送达”。它明确不管这些事：

不管模型能力够不够。 地址对了、密钥对了，模型不支持原生工具调用，在 Roo Code 这样只认 native tool calling、没有 XML 回退的客户端上照样用不了。Continue 那边有 capabilities.tool_use 这类字段，Zed 的 capabilities 对象含 tools、images、parallel_tool_calls 等开关。这些字段名是文档列出的；至于工具拿它们做什么、是否会与服务端实际能力做校验，本篇依据的文档页并没有逐条说明，按字段语义看更像是由你来声明而非由客户端替你探测，但这只是判断，实际行为以官方文档为准。要紧的是：这一栏填了不等于模型真有这个能力。

不管那些要你手填的数值填得对不对。 Cline 的 Model Configuration 区列出 Max Output Tokens、Context Window size、Image Support、Computer Use、Input Price、Output Price；Roo Code 也有 Max Output Tokens、Context Window、Image Support、Computer Use 与输入/输出价格。这些字段名是文档列出的，但本篇依据的那两页记录里没有逐条说明客户端内部拿这些数做什么，所以我不替它们下用途结论——你只需要知道这些量由你填、填的是什么量纲，具体行为以官方文档为准。按 OpenAI 兼容协议的通用机制推断，最大输出设得过小会让长回答被截断、上下文窗口声明值与服务端实际上限对不上会在长会话时暴露问题——但这是协议层的一般道理，不是上述任何一家文档的记载。

不管非标准端点的适配。 自建网关如果路径结构和 OpenAI 那套差得远，只有明确接受完整端点形态的客户端（如 Kilo Code 文档所写）能靠一个字段兜住；其余情况你可能得在网关侧做一层路径改写，这属于你自己的基础设施工作。

不管厂商特例。 Kilo Code 文档明确提醒：Azure GPT-5 不要用通用的 OpenAI 兼容 provider，要用它原生的 azure provider，因为 Azure 会拒绝 max_tokens 参数。这类”看起来兼容、实际有出入”的情况，通用配置这条路兜不住。

不管角色分工。 Continue 的 roles 取值有 chat、autocomplete、embed、rerank、edit、apply、summarize，默认是 [chat, edit, apply, summarize]。其中 embed（嵌入）指把文本转成向量用于检索，rerank（重排）指对检索出的候选结果重新打分排序——这两个角色跟聊天不是一回事，一个能聊天的端点不必然能干这两件事。要用就得单独配、单独验。

六、避坑清单

把别家的字段名抄到这家。 为什么会踩：网上教程混着写，apiBase、api_url、Base URL、OPENAI_HOST、--base-url 长得都像”那个填地址的地方”。怎么避：认准你手上这个产品的官方文档页（URL 见文末），字段名一个字母都别改。

默认”域名 + /v1”就是答案。 为什么会踩：多数示例长这样，形成了肌肉记忆。怎么避：看 Groq 官方给的 https://api.groq.com/openai/v1——/v1 前面还有一段。永远以服务商文档标注的原值为准。

在只接受一种形态的地方填了完整端点。 为什么会踩：见过 Kilo Code 那条”两种都行”，就以为通用。怎么避：那条只对 Kilo Code 成立，别处照抄之前先查那一家自己的文档。

把 OPENAI_HOST 当成完整地址填。 为什么会踩：goose 把地址拆成主机与可选路径两段，跟别家一个字段搞定的设计不一样。怎么避：配 goose 的自建 / 企业内部端点时，把 OPENAI_HOST 和 OPENAI_BASE_PATH 一起想清楚再填。

密钥写进配置文件然后提交上去。 为什么会踩：地址和密钥经常挨着填，顺手就一起存了。怎么避：Zed 明确要求不要把 API key 放进 settings.json（走设置界面或 <PROVIDER_NAME>_API_KEY 环境变量）；Gemini CLI 允许用 $VAR_NAME 插值。拿不准就把密钥放环境变量，配置文件里只留引用。

只验地址不验模型能力。 为什么会踩：连通了就以为配完了。怎么避：分两步验——先确认请求能通（手工发一次或看客户端能否拉到模型列表），再确认这个模型支持你要用的能力（工具调用尤其关键）。

拿一份配置去套所有工具。 为什么会踩：同一个服务商、同一个模型，感觉配一次就够。怎么避：配置形态本身就分四类——图形界面表单、YAML 配置文件、JSON settings、环境变量与 CLI 子命令。换一类工具就重新读一次它的文档，别指望迁移。想系统过一遍，可以看编辑器接自定义 API那篇。

最后补一句关于选型口径的诚实说法：goose 官方文档自述支持 40+ 个 LLM provider，并写着 “works best with Claude 4 models”，理由是这些模型的工具调用能力——这是该产品官方文档的说法，不是本文的判断，也不构成对任何模型的背书。各家在设计取向上的差异（表单填、文件写、还是环境变量拆两段）只是取向差异，本文不排座次。

数据来源与核对日期

以下 URL 全部来自各产品官方文档站，核对日期均为 2026-08-07。文中提到的字段名、示例值与英文原句，都是截至该日期这些页面上的内容，请以官方文档最新版为准。

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

  • 价格、免费额度、订阅档位、限速数字——这类内容变动快，本次没有逐一核实，写进来只会误导，请以各产品与各服务商官方页面为准。
  • 完整模型清单——文中出现的模型 ID 只是官方文档里的示例值（如 Groq 文档中的 llama-3.3-70b-versatile），不代表可用模型的全集。
  • 版本号、发布日期与产品之间的公司关系——不在本篇核实范围内，一律不写。
  • 界面长什么样——本篇依据的是各家配置层文档，不涉及面板位置、菜单层级、提示文案与校验时机，这些以你实际看到的界面为准。
  • 各家文档的优劣比较——不做这类排序。上文列出的差异都是可以自己打开对应 URL 复核的记载，不是评价。

延伸阅读：同一组里的 编辑器与终端 Agent 接自定义模型、你的 API key 躺在哪；接完之后照 接完自定义模型别急着干活 逐项过一遍，才算真接通。

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

浏览课程 加入会员