Aider 终端结对编程接入

先说结论:两个环境变量加一个模型前缀

Aider 文档记录在案的 OpenAI 兼容接入路径就是这样:导出 OPENAI_API_BASE 填你的端点,导出 OPENAI_API_KEY 填对应的密钥,模型名前面加上 openai/ 前缀让 Aider 用 chat-completions 协议跟这个 base 对话。前缀后面的字符串原样传给端点,所以端点提供的任何 ID 都能用,Claude 和 DeepSeek 的 ID 也不例外。 这就是全部连接步骤。Mac 和 Linux 上用 export,Windows 上用 setx 并打开一个新 shell,因为 setx 不影响当前会话。同样的值也能写进 Aider 的配置文件或者 .env 文件,如果你更喜欢按项目配置而不是靠 shell 状态。

export OPENAI_API_BASE=https://api.kkaiapi.com/v1
export OPENAI_API_KEY=sk-你的kkaiapi密钥

aider --model openai/claude-sonnet-5

Aider 怎么解析模型和供应商

Aider(GitHub 上的 Aider-AI,约 4.7 万星标)是最早的终端结对编程工具:给你的 git 仓库建索引,在对话里接收改动需求,直接编辑文件,再提交结果。它底层通过 litellm 路由模型调用,这也是为什么 openai/ 前缀这么关键:litellm 靠这个前缀选协议,openai/ 意味着 "用 OPENAI_API_BASE 指定的地址走 chat-completions"。一个不带前缀的模型名会按拼写被自动推断厂商,把一个 Claude ID 推去 Anthropic 的原生接口,要你的 ANTHROPIC_API_KEY,而不是你的网关。 有一个 Aider 特有的行为值得在第一次会话前知道:它自己维护一份模型能力注册表,遇到不认识的模型会触发一句警告 "Unknown context window size and costs, using sane defaults",之后 Aider 会假设上下文窗口无限、成本为零。会话照样能跑,但两个有用的子系统会打折:token 预算没法在你真的超出真实上下文限制之前提醒你,会话内的花费显示会读成零。修法是一个小小的元数据文件,下面会讲,花两分钟很值。 Aider 一次会话也不止跑一个模型。主模型负责写代码;弱模型负责写提交信息和摘要聊天记录;architect 模式下,一个独立的编辑模型负责落地方案。三个都接受同样的 openai/ 前缀,所以都能经一个 Key 走网关。

完整配置:连接加模型元数据

连接就是上面两个变量。真正的打磨在于注册元数据,让 Aider 把网关模型当成已知量对待。在家目录、git 仓库根目录或工作目录创建 .aider.model.metadata.json(或者用 --model-metadata-file 传参),键名是带 openai/ 前缀的完整名字,litellm_provider 字段要和这个前缀一致。注册了 max_input_tokens 之后,Aider 的上下文预算会按模型真实的窗口计算,而不是假设它无限大。 第二个可选文件 .aider.model.settings.yml 按模型调行为:edit_format 控制 Aider 怎么请求代码改动(能处理 diff 的模型用 diff 变体,不能处理的用整文件),use_repo_map 控制是否带上仓库上下文。Aider 没法给一个不认识的模型推断最佳编辑格式,声明它是让一个模型表现平庸还是发挥出真实水平的分界线。

{
  "openai/claude-sonnet-5": {
    "max_input_tokens": 1000000,
    "max_output_tokens": 64000,
    "litellm_provider": "openai",
    "mode": "chat"
  },
  "openai/deepseek-v4-pro": {
    "max_input_tokens": 128000,
    "max_output_tokens": 16000,
    "litellm_provider": "openai",
    "mode": "chat"
  }
}

主模型、弱模型、编辑模型怎么选

Aider 的会话又长又迭代,这让模型比较在这里格外诚实:同一个功能分支,不同天用两个主模型跑一遍,差异会体现在你用 /undo 的频率上。一个端点让每个候选模型都是一次参数改动,按 Key 的用量给每次实验定价。

• 主模型扛下每一次改动。它读仓库地图,在你的文件上推理,产出 diff,claude-sonnet-5 或 gpt-5.5 该放这里;一个把 diff 语法写错的模型,每次改动都会让你多花审查时间
• 弱模型(--weak-model)写提交信息、摘要聊天记录。触发频繁、从不碰代码,所以让它走同一个网关上一个快速、便宜的 ID,而不是让它默认落到别处
• architect 模式把规划和编辑拆开:主模型规划,编辑模型(--editor-model)落地。一个强推理模型规划、一个编码专精的 ID(比如 kimi-k2.7-code)执行,这种搭配是单一厂商 Key 做不到的
• deepseek-v4-pro 和 gpt-5.4 值得在重构密集的日常工作里作为主力模型来跑基准测试,单次会话 token 量大的场景会让价格差异被放大

主力模型价格

价格按 kkaiapi 中文区实时价格计算,单位 ¥/1M tokens(输入/输出)。

Aider 专属的翻车点

相信"合理默认值"。未知模型的回退假设上下文无限、成本为零。实际上这意味着 Aider 会任由一个长会话超出模型真实窗口而不告警,直到网关拒绝请求,或者模型悄悄丢掉早期上下文,而成本追踪器全程显示为零。注册元数据,这两个问题都会消失。 丢掉 openai/ 前缀。没有它,litellm 会按模型名推断供应商,Claude 的 ID 会被路由去 Anthropic 的接口,因为缺 ANTHROPIC_API_KEY 而失败,看起来像 Key 的问题,其实是前缀的问题。 元数据对不上。.aider.model.metadata.json 里的条目按带前缀的完整名字做键,litellm_provider 应该和这个前缀一致。裸 ID 做键或者 provider 字段不匹配会悄无声息地不生效,你会退回默认值,还没有任何报错提示你。 Windows 的 shell 状态。setx 只对之后打开的 shell 生效。在刚跑过 setx 的同一个终端里跑 aider 用的还是旧环境,得到的 401 是 shell 生命周期问题,不是凭证问题。 编辑格式不对。一个没注册的模型会拿到一个默认编辑格式,可能不是它最擅长处理的那种。如果一个强模型持续产出 Aider 拒绝的编辑,在下结论说这个模型不会写代码之前,先在 .aider.model.settings.yml 里显式设置 edit_format。

验证接入与排查首次会话

开始前先列出网关的模型;openai/ 后面的 ID 必须和提供的某个 ID 精确匹配,版本后缀也算。 首次会话的失败排查很快。401 意味着 OPENAI_API_KEY 对启动 aider 的那个 shell 不可见(Windows 上 setx 之后只有新 shell 能看到,在同一个终端里 echo 一下确认)。网关返回模型不存在是 ID 打错了字。提到另一个厂商的 Key 的报错,意味着一个不带前缀的模型名被原生路由走了。启动时的未知模型警告不是错误,但这是提醒你在长会话真正撞到上下文上限之前、而不是之后,补上元数据文件的信号。 会话里,元数据注册之后 Aider 自己的 token 和成本读数会变准确,kkaiapi 控制台从端点侧展示同一批会话:每次请求的模型、token 数、花费。对一个从早用到晚的结对编程工具来说,这个按 Key 的视图是回答一周 Aider 到底花了多少钱的最诚实答案。

curl -s https://api.kkaiapi.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -50

常见问题