aider 模型设置文件放哪一层生效：四个加载位置的优先级与全局设置

2026-08-07

你在 aider 里改了半天模型设置没生效，多半不是参数写错了，而是那份文件放错了层——.aider.model.settings.yml 有四个加载位置，官方文档写明这四处是按顺序加载、后加载的优先。也就是说，家目录里那份写得再全，只要仓库根目录或当前目录里还躺着一份同名文件，真正说了算的是后者。先搞清楚这条加载顺序，再谈参数怎么填，顺序反了会白折腾很久。

本篇只讲 aider 的模型设置文件这一层：四个位置、extra_params 透传、全局设置那个特殊模型名，以及给 aider 不认识的模型补元数据的做法。至于团队里多个人各写一份规则文件互相打架该怎么收口，见团队规则文件冲突怎么收口；配置文件被 AI 工具改乱了怎么回滚和约束，见 AI 改配置文件的边界；密钥和端点该走环境变量还是写进配置文件，见配置传环境变量。这三篇讲的是通用做法，本篇讲的是 aider 这一个产品截至 2026-08-07 官方文档里记录的具体机制，两边不重叠。

一、四个加载位置：顺序就是优先级

截至 2026-08-07，aider 官方文档的这一页（URL 见文末来源）写明：.aider.model.settings.yml 可以放四处，按下面这个顺序加载，后加载的优先：

home 目录
git 仓库根目录
启动 aider 的当前目录
--model-settings-file <filename> 指定的自定义路径

这四层的排布方式很好理解，越靠近”这一次具体在干什么”的位置，优先级越高。home 目录是你个人的默认口味，跨所有项目生效；仓库根目录是这个项目的共识，跟着代码走，团队里每个人 clone 下来都一样；当前目录是”我这回就在这个子目录里跑”的临时覆盖；命令行参数指定的那份则是最外层的显式指定，你在命令里点名要哪个文件，它就压过前面所有的。

这里最容易出事的是第二层和第三层的关系。 很多人习惯在仓库的某个子目录里启动 aider，比如只想让它看 backend/ 这一块。这时候”启动 aider 的当前目录”就是 backend/，而不是仓库根。如果 backend/ 下面恰好也有一份历史遗留的同名文件，它会盖掉仓库根那份团队共识的配置，而你在根目录做的任何修改都不会有反应。排查方法很直接：从家目录往下，把四个位置逐个 ls -a 看一遍，确认到底存在几份同名文件，再决定删哪份、留哪份。

顺带说一句，“按层加载、后面覆盖前面”并不是 aider 独有的设计。Gemini CLI 的 settings.json 同样有四处位置（系统默认、用户级、项目级、系统覆盖），并且官方文档把优先级从低到高排成一条完整的链：硬编码默认 → system defaults 文件 → user settings → project settings → system settings → 环境变量 → 命令行参数。两家产品的层数、文件名、具体位置都不一样，别把一家的路径套到另一家上，但”先找到自己现在处在哪一层”这个排查动作是通用的。

二、这些配置项分别是什么

下面这张表里的字段名和文件名，逐字来自 aider 官方文档的这一页。注意最后一行：那一页列出了这些设置项的名字，本篇依据的这份记录里没有它们逐条的语义说明，所以这里只给名字，具体含义请以官方文档为准。

配置项	它在哪里	官方文档这一页记录的说明	出处
`.aider.model.settings.yml`	文件本身	可放四处，按顺序加载，后加载的优先	aider 官方文档该页
`--model-settings-file <filename>`	命令行参数	指定自定义路径，是四个加载位置中的第四个	同上
`extra_params`	设置文件里的模型条目下	可把任意参数透传给 `litellm.completion()`，包括 `extra_headers`	同上
`aider/extra_params`	写在模型名的位置	特殊模型名，可让设置对所有模型全局生效	同上
`.aider.model.metadata.json`	文件本身	对 aider 不认识的模型，用它注册上下文上限与价格	同上
`max_input_tokens`、`max_output_tokens`、`max_tokens`	元数据 JSON 的模型条目下	出现在官方示例的 JSON 结构里	同上
`input_cost_per_token`、`output_cost_per_token`	元数据 JSON 的模型条目下	出现在官方示例的 JSON 结构里	同上
`litellm_provider`、`mode`	元数据 JSON 的模型条目下	出现在官方示例的 JSON 结构里	同上
`edit_format`、`weak_model_name`、`use_repo_map`、`cache_control`、`accepts_settings`	设置文件里	该页列出了这些设置项名	同上

表里出现的”上下文窗口”这个词，指的是模型单次请求能一并看到的文本总量上限，输入的历史对话、贴进去的代码、模型输出的内容都要挤在这个额度里。官方文档在这一页只说了元数据文件用来”注册上下文上限与价格”，并没有逐条说明客户端拿这些数字去做什么；按字段名的字面语义推，一个不认识的模型这些数字无从得知，所以才需要下面这个元数据文件补上——具体用途以官方文档为准。

三、给 aider 不认识的模型补元数据

对 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"
    }
}

这段 JSON 里的数字是官方文档的示例值，不是任何真实模型的报价，也不是任何真实模型的窗口大小。 你照抄结构可以，照抄数字不行——单价必须去你实际用的那家服务商官网查当期数字，窗口上限也一样。这类数字变动频繁，本篇不给具体值。

顶层的键在官方示例里写作 provider/model-name，是模型标识的位置。这类”按名字挂载”的外挂配置有个通用特点：名字对不上，条目就白写——文件语法完全正确，只是它描述的那个模型名压根没被用到。这一条是配置文件的通用常识推的，官方文档这一页并没有逐条说明名字不匹配时的行为，实际以官方文档为准。稳妥做法是让这个键和你实际引用这个模型时的写法保持一致。

input_cost_per_token 和 output_cost_per_token 这两项，按字段名的字面语义读是”每个 token 的单价”（官方文档这一页只给了示例结构，没有逐条解释这两栏怎么被使用，用途以官方文档为准）。真要照这个量纲填，就比服务商官网常见的”每百万 token 多少钱”小六个数量级，换算时多写少写一个零很难用肉眼发现。写完之后建议自己拿计算器反推一遍：把你填的数乘以一百万，看看是不是官网页面上那个数字。

四、extra_params 与 aider/extra_params

extra_params 解决的是另一类问题：官方设置项没覆盖到的参数怎么办。文档写明它可以把任意参数透传给 litellm.completion()，包括 extra_headers。文档给的示例是：

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

看这段结构本身就能读出两件事。第一，设置文件是一个列表，每个条目用 name 指明它管哪个模型，所以同一份文件里可以并排放多个模型各自的设置。第二，extra_params 下面既能放 extra_headers 这种 HTTP 头，也能直接放 max_tokens 这类请求参数——前者是 HTTP 请求头，按 HTTP 这一层的通用用途讲，中转网关和企业内部代理常靠它认路或鉴权（很多自建网关要求带一个特定的头才放行）；后者则是请求参数本身。这两者的区别属于 HTTP 协议常识，不是 aider 官方文档在这一页给出的说明。

然后是那个特殊模型名。文档写明：aider/extra_params 这个模型名可让设置对所有模型全局生效。 官方文档把它归为”特殊模型名”，从这个措辞看，它占的是模型名的位置而不指向某个真实模型；写法上就是把条目的 name 换成它，具体写法与边界以官方文档为准。

这个设计的价值在于消灭重复。假如你的团队所有请求都必须经过一个内部网关，而网关要求每个请求都带同一个自定义头，没有这个特殊名你就得给每个模型条目各抄一遍 extra_headers，以后网关换头名，你得逐条改，漏一条就只有那个模型悄悄失败。用 aider/extra_params 写一次，所有模型都带上。

反过来，它的杀伤半径也正是所有模型。全局条目里放的东西越多，你就越难判断某个模型当前实际生效的是哪一组参数。一个比较稳的用法是：全局条目里只放那些确实与模型无关的东西（认路的头、鉴权的头），凡是和具体模型能力挂钩的数值——比如输出长度上限——就老老实实写在各自的模型条目里。

五、边界与代价：这套机制不管什么

把设置抽到文件里，换来的是可版本化、可分发、可复现，代价也要说清楚。

它不解决”这个模型到底行不行”。 在元数据文件里给一个模型填上很大的 max_input_tokens，只是在告诉工具”你按这个数去算”，服务端能不能真的接住是另一回事。填的数字大于服务端实际上限时，超出的部分会在请求真正发出去之后由服务端拒绝——这是 OpenAI 兼容协议这一层的通用机制（所谓 OpenAI 兼容端点，是指服务商把接口做成和 OpenAI 那套请求/响应格式一致，客户端因此可以不改代码换后端），不是 aider 官方文档记载的产品行为，这里是按协议常识推的，实际报错以你的服务商为准。同理，max_output_tokens 设得太小，长回答会在写到一半时被截断。

它不负责保管密钥。 本篇依据的这一页记录里没有出现密钥存放的规定，这不等于 aider 官方文档没有相关说明，只是不在这一页。但有一条通用判断可以先立住：只要一份配置文件的设计意图是进仓库、跟着代码走（.aider.model.settings.yml 的第二个位置就是 git 仓库根目录），你就该默认它会被别人看到、会被推上远端。作为对照，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 指操作系统自带的凭据保管服务，密钥由系统加密存放，不落在明文文件里。Gemini CLI 走的是另一条路，它的 settings.json 支持环境变量插值，写 $VAR_NAME 或 ${VAR_NAME}，加载时自动替换成环境变量的值，这样配置文件本身能安心进版本库，真正的密钥留在环境里。这两家的做法不能直接搬到 aider 的文件里（字段名和支持的语法完全是两套），但”配置进库、密钥进环境”这个原则值得照搬。

它不管你换了机器还认不认。 四个位置里有三个是路径相关的，home 目录、仓库根、当前目录在 CI 环境、容器里、同事的机器上很可能完全不是一回事。指望”本地跑通了线上就一样”是不成立的，跨环境要么统一用第四个位置显式指定文件，要么在容器里把文件固定烘进去。

它不适用于”我只想这一次不一样”。 为了一次临时试验去改仓库根的文件，改完忘了改回来，是团队协作里最常见的污染源。临时需求应该用当前目录那层，或者干脆用 --model-settings-file 点名一份实验用的文件。

六、避坑清单

同名文件多份共存，你改的那份根本不生效。 会踩是因为四个位置的文件名是一样的，光看文件内容分不出它是哪一层。避法：排查时不要先看内容，先按”home → 仓库根 → 当前目录”的顺序确认存在几份，把不该留的删掉或改名，只保留一份主控文件。要做临时覆盖时，宁可用 --model-settings-file 显式点名，也别再往目录里塞同名文件——命令行里写了什么你自己一眼能看见，目录里躺了什么看不见。

在仓库子目录里启动 aider，导致仓库根的配置被子目录那份盖掉。 会踩是因为”启动 aider 的当前目录”这一层跟着你的 shell 走，而不是跟着项目走，你换个目录敲同一条命令，生效的配置就可能变了。避法：养成固定从仓库根启动的习惯；确实要在子目录跑，就先确认那个子目录下没有同名文件。

元数据里的模型名前缀和实际使用的不一致。 会踩是因为文档示例写的是占位的 provider/model-name，照抄的人容易只改后半段忘了改前半段，或者前缀里多个少个斜杠。避法：把元数据文件里的顶层键和你实际调用时写的模型标识放在一起逐字比对，别凭印象。

把文档示例里的价格数字当成真实报价填进去。 会踩是因为示例值格式完整、看着就像真的，复制粘贴顺手就留下了。避法：动手前先默认示例里所有数值都是假的，只留结构；单价乘以一百万反推一次，和服务商官网当期数字对上再收工。相关的成本核对方法见 API 价格怎么查最新。

全局条目塞太多，后来分不清哪个模型生效了什么。 会踩是因为 aider/extra_params 用起来太顺手，什么都往里丢一时省事。避法：给全局条目定一条自己的规矩——只放与模型无关的东西，和模型能力绑定的参数一律写进各自条目；并在文件里留一行注释写明这条规矩，免得三个月后的自己破戒。

把别家产品的字段名写进 aider 的文件。 会踩是因为这些工具解决的问题高度相似，看多了几家文档很容易记串。要知道，配置形态本身就分好几类：图形界面表单、YAML 配置文件（Continue 的 config.yaml、aider 的 .aider.model.settings.yml）、JSON settings（Zed 的 settings.json、Gemini CLI 的 settings.json）、环境变量与 CLI 子命令。连指代同一件事的字段名都各不相同——自定义端点这一项，Continue 叫 apiBase，Zed 叫 api_url，它们不是同一个东西，互换必错。避法：改配置前先确认自己打开的是哪家文档的哪一页，别拿搜索结果的记忆去填。想横向看各家接自定义模型的差别，见编辑器接入自定义 API。

改完不验证就开始干活。 会踩是因为设置文件的问题大多是静默的：文件加载不到、模型名对不上、条目被更高优先级覆盖，这些都不会把你拦在门口，而是让你带着一组你以为不存在的参数一路跑下去。避法：每次改完先用一个最小的、结果一眼能看出来的任务跑一次，确认行为确实变了，再回到真正的活上。

数据来源与核对日期

本篇引用的产品事实全部来自下列官方文档页面，核对日期均为 2026-08-07。这些页面会更新，读到本文时请以官方文档最新版为准。

aider（本篇主体，四个加载位置、extra_params、aider/extra_params、.aider.model.metadata.json 示例、设置项名清单）：https://aider.chat/docs/config/adv-model-settings.html
Zed（关于密钥不要写进 settings.json、凭据存放在系统 keychain 的两句英文原话，均为该产品官方文档的说法）：https://zed.dev/docs/ai/use-api-access、https://zed.dev/docs/ai/configuration
Gemini CLI（四处 settings.json 位置、从低到高的优先级链、$VAR_NAME 与 ${VAR_NAME} 环境变量插值）：https://google-gemini.github.io/gemini-cli/docs/get-started/configuration.html
Continue（config.yaml 与 apiBase 字段名，仅用于说明各家字段名不同）：https://docs.continue.dev/reference

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

价格、免费额度、订阅档位、限速数字：这类数字变动频繁，本次未做核实，写出来就是给你埋雷。aider 元数据示例里的两个单价是官方文档的示例值，本篇已逐处标明，不作报价使用。
版本号、发布日期、完整模型清单：同样属于易过时信息，请直接查官方文档与服务商控制台。
界面长什么样、菜单在哪一级、报错文案是什么：本篇依据的是配置层的文档记录，不包含界面细节，你实际看到的界面以本机为准。
上面各设置项的逐条语义：edit_format、weak_model_name、use_repo_map、cache_control、accepts_settings 这几项，本篇依据的那一页记录里只出现了名字，因此本篇只列名字不谈用途。这不等于官方文档没有说明，需要时请到官方文档中查它们各自的条目。
各家文档的优劣比较：本篇只做机制上的对照，不对任何产品的文档质量或产品能力排座次。

延伸阅读：同一组里的 aider 不认识你的模型、Zed 接 OpenAI 兼容端点；接完之后照接完自定义模型别急着干活逐项过一遍，才算真接通。