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

goose 怎么配模型 provider：向导、环境变量与配置文件

2026-08-07

goose 接模型有两条并行的入口：一条是交互式的 goose configure 向导，另一条是一组以 GOOSE_ 开头的环境变量；按官方文档的说法，配置最终持久化在 config.yaml 里。 你在网上看到的大部分「goose 配置教程」之所以互相打架，就是因为它们各自只讲了其中一条，读者以为自己漏了一步，反复重配。先把这三样东西的关系摆平，后面所有报错的排查方向就清楚了。

本文写的是截至 2026-08-07 官方文档页面上的情况，具体字段随版本会变，以官方文档最新版为准。

一、先分清「接入方式」和「模型能力」

这两件事天天被混在一起说，但排查时完全是两条线。

接入方式，指的是你的客户端用什么协议、往哪个地址、带什么凭据去请求。这一层的关键词是「OpenAI 兼容端点」——意思是某个服务商把自己的 HTTP 接口做成和 OpenAI 那套请求/响应格式一样，于是任何按 OpenAI 格式写的客户端只要改一下地址和密钥就能连上，不必为它单独写适配。goose 文档里给自建与企业内部端点准备的那组变量，解决的就是这一层。

模型能力，指的是你选的那个模型本身会不会干某件事。比如「原生工具调用」（function calling）——模型按结构化格式吐出「我要调用哪个工具、参数是什么」，客户端解析后真的去执行，再把结果喂回去。终端 Agent 的整个循环都建立在这上面。再比如「上下文窗口」，指一次请求里模型能容纳的 token 总量上限，历史对话、文件内容、工具返回全挤在这个额度里。

这两层分开看的价值在于：地址和密钥填对了，请求 200 了，不代表这个模型能驱动 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 官方文档的说法，不是本文的断言）。goose 这边，官方文档自述支持 40+ 个 LLM provider，同时写了 “works best with Claude 4 models”，给出的理由是这些模型的工具调用能力——同样，这是官方文档的说法，本文不替它背书，也不据此给任何模型排座次。

本篇和站内几篇邻近文章的分工：开源终端 Agent 怎么选 解决的是「该不该用这一类工具、几家之间怎么挑」，终端 Agent 横评 是把几家放在一起对比，而 opencode 的模型与 provider 配置 讲的是另一个产品的同类问题；本篇只干一件窄事——把 goose 这一家的配置入口、环境变量和落盘位置说清楚，不做选型建议。

二、goose configure 这个向导在问你什么

命令行这条路，官方文档记录的流程是四步：

  1. 跑 goose configure；
  2. 选 Configure Providers；
  3. 从列表里选一个 provider；
  4. 填 API key 与附加参数，然后选模型。

看着简单，但值得留意的是它的顺序：先定 provider，再定模型。这个顺序不是随便排的——不同 provider 能提供的模型集合不一样，所以第 3 步选完才谈得上第 4 步选什么模型。你如果心里想的是「我要用某个模型」，实际操作上就得先反推它由哪家提供再进向导。需要说明的是，向导会不会帮你按模型名反查 provider，本篇依据的记录里没有写，这只是按「先选 provider 后选模型」这个步骤顺序推出来的判断，实际以官方文档和你跑起来看到的提示为准。

第 4 步里「API key 与附加参数」这个说法要注意：附加参数具体有哪几项、每一项叫什么，取决于你选的是哪个 provider，本篇依据的那一页记录里没有逐个 provider 展开，请以官方文档和你实际跑起来看到的提示为准。这一步的交互界面长什么样、有几行提示、光标停在哪，本文一概不写。

桌面端是另一条路。官方文档写的是在 Settings 的 Models 页配置，并列出了这些入口：Quick Setup with API Key、ChatGPT Subscription（浏览器 OAuth）、Agent Router by Tetrate、OpenRouter、Other Providers（手动配置）。其中 Other Providers 对应的就是手动配置那条路。界面版本更迭较快，以你实际看到的界面为准。

三、两个 GOOSE_ 环境变量，以及自建端点要设的那组

先把「环境变量」这个词说清楚：它是操作系统交给进程的一组键值对，程序启动时能读到。相比写进配置文件，它的好处是可以按 shell 会话、按容器、按 CI 任务分别给不同的值，也不会被误提交进版本库。

goose 这边，官方文档记录的是两个变量：

  • GOOSE_PROVIDER：设默认的 provider；
  • GOOSE_MODEL：设默认的模型。

注意它们的定位是「设默认值」，跟前面向导那一步是同一件事的两种表达方式：一个是问你，一个是你直接给。至于这两者同时存在时谁压过谁，本篇依据的那一页记录里没有写明覆盖顺序，本文不猜，请以官方文档为准。

密钥不走这两个变量。官方文档的写法是各家密钥用各自的变量，举的例子是 ANTHROPIC_API_KEY、OPENAI_API_KEY。也就是说变量名跟着 provider 走，你换一家就得换一个变量名，这个映射关系以官方文档为准，别照着某家的名字硬套另一家。

自建或企业内部的 OpenAI 兼容端点是单独一组：官方文档写的是设 OPENAI_HOST，另有可选的 OPENAI_BASE_PATH。这里最值得说的是它的设计取向——host 和 path 被拆成了两段。同一批文档里其他产品多是一个字段吃下整条 base URL：Continue 叫 apiBase，Zed 叫 api_url，Cline / Roo Code / Kilo Code 的界面里叫 Base URL，Crush 是命令行参数 --base-url。goose 这边是拆成两段的设计，所以照搬别家那种「一整条 URL 填一个字段」的习惯多半对不上号——但两段各自该切到哪里、OPENAI_BASE_PATH 不填时按什么处理，本篇依据的记录里都没有写明，上面这句只是按字段名的字面语义作的判断，实际以官方文档为准。

顺带说一句大家最容易卡住的 /v1：这一段到底算 host 还是算 path，各家口径确实不同。Kilo Code 文档明确接受 https://api.provider.com/v1 和 https://api.provider.com/v1/chat/completions 两种形态；Zed 文档示例是 https://example.com/v1；Groq 官方给的 base URL 是 https://api.groq.com/openai/v1。这些是各家文档各自的记载，不能互相搬运，更不能拿来推断 goose 的拆分规则。

四、配置到底落在哪个文件

官方文档的记载很干脆：goose 的配置持久化在 config.yaml。

需要诚实说明的是，本篇依据的那一页记录里只出现了文件名，没有出现它在磁盘上的完整路径——这不等于官方文档没写路径，只是本篇没有据以复述的记录，请到官方文档里确认你所在系统上的实际位置。宁可让你多查一次，也不给你一条可能是拼出来的路径。

知道它落在一个 YAML 文件里，实际有三个用处。一是排查：向导跑完之后到底写进去了什么，看这个文件比反复重跑向导快。二是迁移：换机器时你知道该带走什么。三是风险意识：配置文件是会被误提交进版本库的，而密钥这类东西一旦进了版本历史，删掉当前版本也没用。

顺便对比一下同批产品在密钥落盘这件事上的不同取向，这个差异是能在各家文档里直接查到的：Zed 文档里有一句原话是 “Do not put API keys in settings.json.”，另一页写的是 “Provider keys saved through Zed are stored in the system keychain, not in settings.json.”——keychain 指操作系统提供的凭据保管服务，程序把密钥交给它，读的时候再取回来，不落在明文配置里（以上两句都是 Zed 官方文档的说法）。Gemini CLI 则是另一条思路：它的 settings.json 支持环境变量插值，写法是 $VAR_NAME 或 ${VAR_NAME}，加载时自动解析——所谓插值就是配置文件里只写变量名这个占位符，真正的值运行时从环境变量取，于是配置文件本身可以安心进版本库。goose 这边，官方文档记录的是走环境变量或 config.yaml。

下面这张表把本篇涉及的 goose 配置项按同一口径列一遍。第三列写的是通用机制层面的排查方向，不是官方文档对该字段行为的记载，实际行为以官方文档为准。

配置项（逐字取自官方文档）它是什么出问题时先查什么（机制推理，非文档记载）出处
goose configure命令行的交互式配置入口走完向导仍不生效时，先确认写没写进配置文件，再看是否有环境变量在旁边并存goose 官方文档（URL 见文末）
Configure Providers向导里配置 provider 的那一项选错这一项就进不到填 key 与选模型的分支同上
GOOSE_PROVIDER设默认 provider 的环境变量变量只在当前 shell 会话生效是常见情况，换终端、换 IDE 内置终端都可能读不到同上
GOOSE_MODEL设默认模型的环境变量模型 ID 拼错属于纯字符串问题，逐字对照服务商文档同上
OPENAI_HOST自建 / 企业内部 OpenAI 兼容端点的 host与 OPENAI_BASE_PATH 的切分方式弄反，会让请求打到错的路径上同上
OPENAI_BASE_PATH上一项的可选路径部分同上，两者要一起看，不要单独调同上
ANTHROPIC_API_KEY / OPENAI_API_KEY官方文档举例的各家密钥变量变量名跟着 provider 走，套错家等于没设同上
config.yaml配置持久化的文件配置「莫名其妙变回去了」时，先看这个文件的实际内容同上

五、边界与代价：这套配置方式放弃了什么

把主入口做成交互向导加环境变量，是有取舍的，值得你在选型前想清楚。

第一，可复制性要你自己补。 向导是给人用的，不是给脚本用的。你要在十台机器上铺同一份配置，靠人一台台点向导显然不合适，得自己想办法分发配置文件或预置环境变量。这一步官方文档在本篇依据的那一页里没有给现成方案，不等于没有，请自行查阅。

第二，环境变量的作用域是你的负担。 变量在哪个 shell、哪个进程、哪个容器里可见，是操作系统的事，不是 goose 的事。它读不到，表现出来就是「我明明设了」。这类问题的排查方法可以看 环境变量丢失怎么查。

第三，它明确不管模型能力。 你把地址、密钥、模型 ID 全填对，goose 也不会替你保证这个模型能撑起 Agent 循环。工具调用支持得好不好、上下文窗口够不够长，是模型和服务商那一侧的事。

第四，本篇的口径不覆盖价格与额度。 官方文档提到过几条免费路径（Groq、Google Gemini 免费档，以及 Ollama / LM Studio / Docker Model Runner 这类本地模型），但具体额度数字本篇没有可复核的记录，一律不写。想省钱的话，判断依据请以各服务商官方页面为准。

什么场景下这套方式不适用：如果你要的是「一份配置文件进版本库、团队每个人拉下来就能跑、密钥各自从环境注入」这种工作流，那么以配置文件为中心的产品可能更顺手（比如 Gemini CLI 的插值写法）。反过来，如果你就是一个人一台机器，向导跑一遍最省事。

六、避坑清单

坑一：以为向导和环境变量是二选一，配完一边又去配另一边。 为什么会踩：两条路都能定 provider 和模型，教程里各讲各的，读者自然以为自己漏了步骤。 怎么避：先决定你走哪条路并写在团队文档里。排查时按这个次序做：第一步，在你实际启动 goose 的那个终端里跑 echo $GOOSE_PROVIDER 和 echo $GOOSE_MODEL（Windows PowerShell 用 $env:GOOSE_PROVIDER），打印为空说明这条路没生效，打印出值说明它在并存；第二步，打开 config.yaml 看里面实际写着哪个 provider 和哪个模型（这个文件在磁盘上的路径本篇没有可复述的记录，原因见第四节，请到官方文档确认）；第三步，把这两处的值抄下来对一眼，不一致就说明你在两条路之间反复横跳。两者谁覆盖谁，本篇不作断言，请查官方文档。

坑二：把别家的 base URL 字段名或填法搬到 goose 上。 为什么会踩：几家产品都在解决同一个问题，名字却全不一样——apiBase、api_url、Base URL、--base-url、OPENAI_HOST，看多了就串了。 怎么避：记住 goose 这边是 OPENAI_HOST 加可选的 OPENAI_BASE_PATH，而且是拆成两段的设计。别人文档里「这一项要怎么填」的说法只对它自己有效。

坑三：把密钥直接写进配置文件然后提交进版本库。 为什么会踩：向导跑完密钥自然就落盘了，你不会主动想起这件事，直到某天 git add . 一把梭。 怎么避：把配置文件加进忽略规则，或者用环境变量注入密钥。密钥一旦进过版本历史，改当前文件没用，得按泄露处理走轮换。相关做法见 API 密钥的安全管理。

坑四：只验证「连上了」，不验证「能干活」。 为什么会踩：接入层通了会给你很强的完成感，于是直接开始跑真实任务，撞墙后又回头怀疑地址填错了。 怎么避：接通之后单独跑一个需要调用工具的小任务，确认整个循环闭得上，再上正式活。这是接入方式和模型能力两条线要分开验的直接原因。

坑五：跟着一篇没标日期的教程逐字照抄。 为什么会踩：这类工具的配置项变动频率不低，文档站的域名本身也会变。 怎么避：看到具体字段名先去官方文档核一遍。本篇的记录截止到 2026-08-07，之后以官方文档最新版为准。

数据来源与核对日期

以下 URL 均为本篇引用事实的官方文档来源，核对日期 2026-08-07。

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

  1. 价格、免费额度、限速数字——这几类数字变动快，本次也没有可复核的一手记录，写出来只会误导你做预算。请以各服务商官方定价页为准。
  2. 完整模型清单——模型上下线的频率远高于文章更新频率，任何一份抄在文章里的清单都会过期。以 provider 官方文档为准。
  3. config.yaml 的磁盘完整路径——本篇依据的那一页记录里只出现了文件名，没有可复述的路径。这不等于官方文档没写，请自行确认。
  4. GOOSE_PROVIDER / GOOSE_MODEL 与配置文件的覆盖优先级——同样没有可复述的记载，不猜。
  5. 界面的具体样子（菜单层级、提示文案、报错文案、什么时候校验）——本篇只写配置层的事实，界面以你实际看到的为准。
  6. 版本号、发布日期、产品之间的公司关系——与配置无关，也不在本篇的核对范围内。

延伸阅读：同一组里的 Zed 为什么不让把密钥写进 settings.json、goose 接自建端点；接完之后照 接完自定义模型别急着干活 逐项过一遍，才算真接通。

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

浏览课程 加入会员