为 Aider 配置 Router One：base URL、Key 与 openai/ 模型名

安装 Aider 0.86.2，并创建专用 Key

Aider 的安装文档推荐用 aider-install 辅助工具，它会把 Aider 装进独立的 Python 环境：先运行 python -m pip install aider-install，再运行 aider-install。PyPI 上的当前版本 aider-chat 0.86.2（2026 年 2 月 12 日发布）要求 Python 3.10、3.11 或 3.12，并锁定 LiteLLM 1.81.10——真正发出请求的就是这个库。aider --version 应输出 aider 0.86.2。接着为 Aider 单独创建一把 Router One Key 并设置 maxSpend 消费上限。Aider 会发出你没有手动输入的请求，比如每次改动后的提交信息、对话历史变长后的摘要，所以这个上限就是硬性止损；单独一把 Key 还能在控制台 → 日志按 API Key 筛选时，把 Aider 的花费和其他工具分开。

python -m pip install aider-install
aider-install
aider --version        # aider 0.86.2

把 Aider 配置到 Router One base URL

在启动 Aider 的 Shell 里导出这两个变量（Windows 上对每个变量运行一次 setx，然后打开新的终端），再在项目目录中启动 Aider。OPENAI_API_BASE 填带 /v1 的 base URL，因为 LiteLLM 会自己拼上 /chat/completions，填完整端点地址会让路径重复。模型名是 openai/ 加完整的目录模型 ID，LiteLLM 只在第一个斜杠处拆分：openai 选中它的 OpenAI 兼容客户端，剩下的部分（这里是 anthropic/claude-sonnet-5）原样作为 model 字段发出。因此，自带厂商前缀的目录 ID 看起来像是前缀重复了，这是正确写法：openai/openai/gpt-5.5 发出的是 openai/gpt-5.5。没有厂商前缀的 ID（如 deepseek-v4-flash、grok-4.7）只需一个 openai/。如果漏掉内层前缀，发出去的就是 gpt-5.5 这样的裸名；网关接受大多数官方裸名作为别名，但不是全部，不认识的模型名会返回 404，所以请始终写完整的目录 ID。也可以用参数代替环境变量：--openai-api-base 与 --openai-api-key，或 AIDER_OPENAI_API_BASE 与 AIDER_OPENAI_API_KEY 变量，都会在启动时写入 OPENAI_API_BASE 与 OPENAI_API_KEY；--api-key openai=sk-… 同样会设置 Key：

# macOS / Linux
export OPENAI_API_BASE=https://api.router.one/v1
export OPENAI_API_KEY=sk-your-router-one-key
cd /path/to/your-project
aider --model openai/anthropic/claude-sonnet-5

# openai/ + the exact catalog ID; IDs keep their own vendor prefix:
#   aider --model openai/openai/gpt-5.5
#   aider --model openai/deepseek-v4-flash

# Windows (then open a new terminal):
#   setx OPENAI_API_BASE https://api.router.one/v1
#   setx OPENAI_API_KEY sk-your-router-one-key

发一次计费测试，到日志里核对

aider --model openai/anthropic/claude-sonnet-5 --message "Reply with OK" --no-auto-commits 只发送一条提示然后退出；--message（或 -m）会跳过交互式对话。对于没有元数据的模型，Aider 会先打印 "Warning for openai/anthropic/claude-sonnet-5: Unknown context window size and costs, using sane defaults."，这是预期行为，后面两节会处理它。这条提示以一次 stream 为 true 的 POST /v1/chat/completions 发出，因为 Aider 默认流式接收回复（--no-stream 可关闭）。在控制台 → 日志中，对应的请求会显示模型、输入与输出 tokens、费用、状态、总耗时，以及产生过输出的流式请求的首字延迟（TTFT）。输入 tokens 会比提示本身多：每次请求都带着 Aider 的编辑格式说明，在 git 仓库里还会带上仓库地图的摘录。如果 Aider 报 404，且错误信息以 "no route matched POST /chat/completions" 开头，说明 OPENAI_API_BASE 缺了 /v1；"no route matched POST /v1/v1/chat/completions" 则说明 /v1 写了两遍。

aider --model openai/anthropic/claude-sonnet-5 --message "Reply with OK" --no-auto-commits

告诉 Aider 如何对待 Router One 的模型 ID

Aider 为它认识的模型名内置了预设，Router One 的目录 ID 一个也匹配不上，于是它退回通用默认值：whole 编辑格式，模型要把改过的每个文件完整返回；弱模型（weak model）直接用主模型；temperature 为 0；对话历史预算 1,024 tokens，超过后较早的轮次会被摘要。仓库地图保持开启，预算 1,024 tokens。.aider.model.settings.yml 可以按模型改掉这些默认值。Aider 依次从主目录、git 根目录和当前目录读取它，后读取的文件优先；--model-settings-file 还可以再指定一个。name 必须与 --model 的字符串完全一致。edit_format: diff 改用搜索替换块，模型只返回改动的那几行。weak_model_name 把提交信息和历史摘要交给更便宜的聊天模型。use_temperature: false 让 Aider 不再发送 temperature 0，Aider 自己对 GPT-5 模型的预设就是这样做的；对 GPT 系列 ID 请把它当作预防措施，而不是已知的必需项。accepts_settings: ["reasoning_effort"] 让 --reasoning-effort 生效：对没有设置的模型，Aider 会忽略这个参数并打印警告。对 Claude 系列 ID，Router One 不会把 reasoning_effort 转换为 thinking 设置；Claude Opus 5.5 例外，会映射到 output_config.effort（none 与 minimal 记为 low）。其他模型可能忽略它，或以 400 拒绝请求。

- name: openai/anthropic/claude-sonnet-5
  edit_format: diff
  weak_model_name: openai/anthropic/claude-haiku-4.5
- name: openai/openai/gpt-5.5
  edit_format: diff
  weak_model_name: openai/deepseek-v4-flash
  use_temperature: false
  accepts_settings: ["reasoning_effort"]

在 .aider.model.metadata.json 里登记上下文窗口

元数据文件能消除上面的警告，并给 Aider 一个用来估算用量的上下文窗口。它从同样三个位置读取，另可用 --model-metadata-file 指定。每个键都是完整的 --model 字符串，litellm_provider 填 openai，mode 填 chat。max_input_tokens 取自 /models 上该模型的详情页；详情页显示的是取整后的缩写（1.05M、200K），请换算成整数并往小取：anthropic/claude-sonnet-5、openai/gpt-5.5 与 deepseek-v4-flash 填 1000000，anthropic/claude-haiku-4.5 填 200000。弱模型也要登记，Aider 会用同样的方式检查它们。不要填输出上限和价格。Aider 文档说明它从不强制执行 token 上限，只会转报 API 返回的错误；不填价格时，Aider 自带的费用显示没有数据可算，计费以 Router One 的日志为准。登记窗口后有三处变化：Aider 会在估算的对话长度超过窗口时，发送前先给出警告；对话历史预算提高到窗口的十六分之一，上限 8,192 tokens，摘要触发得更少；仓库地图扩大到窗口的八分之一，介于 1,024 与 4,096 tokens 之间，每次请求可能多出约 3,000 个输入 tokens。--map-tokens 可以固定地图大小，--map-tokens 0 则关闭地图。不想建文件时，在命令行用 --edit-format diff --weak-model openai/anthropic/claude-haiku-4.5 --max-chat-history-tokens 8192 也能达到大致相同的效果。

{
  "openai/anthropic/claude-sonnet-5": { "max_input_tokens": 1000000, "litellm_provider": "openai", "mode": "chat" },
  "openai/anthropic/claude-haiku-4.5": { "max_input_tokens": 200000, "litellm_provider": "openai", "mode": "chat" },
  "openai/openai/gpt-5.5": { "max_input_tokens": 1000000, "litellm_provider": "openai", "mode": "chat" },
  "openai/deepseek-v4-flash": { "max_input_tokens": 1000000, "litellm_provider": "openai", "mode": "chat" }
}

把地址写进配置文件，并留意项目里的 .env

Aider 会依次加载主目录、git 根目录和当前目录下的 .env 文件，最后加载 --env-file 指定的文件，而且每个文件都会覆盖已经存在的值，包括你在 Shell 里导出的变量。这是「换到某个项目就失灵」最常见的原因：项目的 .env 为你自己的应用设置了 OPENAI_API_KEY 或 OPENAI_API_BASE，会悄悄替换掉 Router One 的值，请求随之返回 401，或者发到了别的端点，在控制台 → 日志里根本看不到。解决办法：把 Router One 的值放进 ~/.env，项目 .env 里不要写这两个变量；或者用 --env-file 指向一个专用文件；或者直接传 --openai-api-base 与 --openai-api-key，它们在所有 .env 之后生效。Key 以外的配置可以写进 .aider.conf.yml，键名就是 Aider 的长参数名（model、openai-api-base、edit-format、weak-model、auto-commits），同样从主目录、git 根目录和当前目录读取，后读取的文件优先。不要把 Key 写进任何会提交的文件。

model: openai/anthropic/claude-sonnet-5
openai-api-base: https://api.router.one/v1
edit-format: diff
weak-model: openai/anthropic/claude-haiku-4.5
# Key 写在 ~/.env 里（OPENAI_API_KEY=sk-your-router-one-key），不要写进这个文件

日志里多出来的请求从哪来

一次会话计费的请求数会多于你输入的提示数。自动提交默认开启：Aider 每应用一次改动，就让弱模型写一行提交信息并提交，--no-auto-commits 可以关闭。对话历史超过预算后，弱模型还会摘要较早的轮次。没有配置弱模型时，这两项工作都落在主模型上，而主模型往往是会话里最贵的那个 ID。架构师模式（启动时加 --architect，或在对话里输入 /architect）会把每次改动拆成两次调用：主模型规划改动，编辑模型（用 --editor-model openai/<目录 ID> 指定）负责写出编辑。Aider 默认最多等待 600 秒响应，可用 --timeout 调整。Aider 常规的编辑格式都是纯文本，所以选用的聊天模型不需要支持工具调用；只有旧式的函数调用编辑格式才会发送工具定义。Aider 从不调用 /v1/responses 或 /v1/messages：包括提交信息和摘要在内，每个请求都是 Chat Completions 调用。

Aider 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Aider 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。

Aider 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在请求日志里核对 Aider 的调用

先在 Aider 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，要么请求没到达网关（客户端配置或网络问题），要么网关在调用模型之前就拒绝了它——Key 问题的 401、余额不足或 Key 达到 maxSpend 上限的 402、Key 或账户自身限额触发的 429，或模型 ID、端点不对的 400 / 404；在输出任何内容之前就失败的流式请求也可能没有日志。看客户端收到的状态码和错误消息就能区分是哪一种；先确认这一点，再判断是不是网关或上游故障。

常见问题