上周三我把本地的 Aider 从 0.82 升到了 0.89，结果一跑直接报错：
Error: Could not connect to https://api.openai.com/v1/chat/completions
Connection timed out after 30000ms
老问题了。折腾了大半天，把官方直连、环境变量、配置文件三种方式都试了一遍，顺便把 Claude Opus 4.7 和 GPT-5.5 的接入也一并搞定了。这篇把我踩过的坑和最终能跑通的配置全部贴出来，照着抄就行。
Aider 配置 API 的核心思路就一句话：通过 --openai-api-base 参数或环境变量 OPENAI_API_BASE 指定你的 API 地址，再填上对应的 Key，就能接入任何兼容 OpenAI 协议的服务。
先说结论
三种方案我都跑通了，适用场景不太一样：
| 方案 | 配置方式 | 适合谁 | 切换模型方便度 |
|---|---|---|---|
| 命令行参数 | 每次启动时带参数 | 临时测试、偶尔用一下 | 一般，每次都要敲 |
| 环境变量 | 写进 .bashrc / .zshrc | 长期固定用一个服务 | 改一次管一年 |
.aider.conf.yml | 项目根目录放配置文件 | 团队协作、多项目 | 最灵活，按项目切 |
我自己最后选了方案三，因为手头有三四个项目，有的用 Claude Opus 4.7 写后端逻辑，有的用 GPT-5.5 做前端组件生成，一个配置文件搞定。
环境准备
- Python 3.10+（我用的 3.12.4）
- Aider 0.89+（
pip install aider-chat --upgrade） - 一个能用的 API Key
确认 Aider 版本：
aider --version
# aider 0.89.2
方案一：命令行参数直接传
最简单粗暴，适合你就想快速验证能不能通。
aider --openai-api-key sk-your-key-here \
--openai-api-base https://api.ofox.ai/v1 \
--model openai/claude-sonnet-4.6
跑起来之后 Aider 会输出：
Model: openai/claude-sonnet-4.6 with diff edit format
Git repo: .git with 47 files
看到这个就说明连上了。
但这种方式挺烦人的，每次开终端都要敲一长串。Key 直接暴露在命令行历史里，history 一翻就看到了，多人共用机器的话有安全隐患。
方案二：环境变量
写进 shell 配置文件，一劳永逸。
# 编辑 ~/.zshrc 或 ~/.bashrc
export OPENAI_API_KEY="sk-your-key-here"
export OPENAI_API_BASE="https://api.ofox.ai/v1"
保存后 source ~/.zshrc，然后直接：
aider --model openai/claude-opus-4.7
不用再传 base 和 key 了。
这里有个坑我踩了半小时——如果你之前装过 Aider 的旧版本（0.7x 之前），环境变量名可能是 OPENAI_API_BASE_URL（多了个 _URL），新版已经统一成 OPENAI_API_BASE 了。两个都设了的话，新版优先读不带 _URL 的那个。我当时两个都设了还设成了不同的地址，debug 了好一会儿才发现。
方案三：.aider.conf.yml 配置文件（推荐）
这是我最终用的方案。在项目根目录创建 .aider.conf.yml：
# .aider.conf.yml
openai-api-key: sk-your-key-here
openai-api-base: https://api.ofox.ai/v1
model: openai/claude-sonnet-4.6
# 可选配置
auto-commits: true
dark-mode: true
stream: true
然后在这个目录下直接 aider 就行，零参数启动。
多项目的话，每个项目放一份不同的配置。比如我的后端项目用 Opus 4.7：
# backend-service/.aider.conf.yml
openai-api-key: sk-your-key-here
openai-api-base: https://api.ofox.ai/v1
model: openai/claude-opus-4.7
edit-format: diff
前端项目用 GPT-5.5：
# frontend-app/.aider.conf.yml
openai-api-key: sk-your-key-here
openai-api-base: https://api.ofox.ai/v1
model: openai/gpt-5.5
edit-format: whole
切项目就是 cd 一下的事。
整体调用链路
画个图方便理解，Aider 的请求到底走了什么路径：
sequenceDiagram
participant Dev as 你的终端
participant Aider as Aider CLI
participant Gateway as API 聚合网关
participant Model as 目标模型
Dev->>Aider: aider 启动
Aider->>Aider: 读取 .aider.conf.yml
Aider->>Gateway: POST /v1/chat/completions
Note over Aider,Gateway: base_url + API Key
Gateway->>Model: 转发请求到 Claude/GPT
Model-->>Gateway: 流式返回
Gateway-->>Aider: SSE stream
Aider-->>Dev: 实时显示 + 自动编辑文件
踩坑记录
坑 1：model 名称前缀
Aider 0.89 要求模型名带 provider 前缀。直接写 claude-sonnet-4.6 会报：
Error: Unknown model: claude-sonnet-4.6
Did you mean one of these?
openai/claude-sonnet-4.6
anthropic/claude-sonnet-4.6
用兼容 OpenAI 协议的聚合服务（OpenRouter、ofox.ai 这类），前缀统一用 openai/。
坑 2：stream 模式下的 JSON 解析错误
4 月 22 号那天我用 Claude Opus 4.7 生成一个比较长的 Python 文件（大概 400 行），Aider 突然断了：
json.decoder.JSONDecodeError: Expecting ',' delimiter: line 1 column 4096
查了一下是 stream 响应在某个 chunk 边界刚好切到了 JSON 中间。解决办法是在配置里加一行：
stream: false
关掉流式传输就好了。代价是响应不再实时显示，要等模型全部生成完才一次性输出。大部分场景无所谓，反正 Aider 主要是改文件，又不是聊天。
坑 3：.env 文件不生效
有人习惯用 .env 文件管理环境变量。Aider 本身不会自动读 .env，你得配合 direnv 或者在启动前手动 source .env。我一开始以为放了 .env 就行，结果 Key 一直没传进去，报 401：
openai.AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API key'}}
后来老老实实用 .aider.conf.yml，省心。
坑 4：代理和 base_url 冲突
如果你系统设了 HTTP_PROXY 或 HTTPS_PROXY，可能会和 openai-api-base 打架。我之前 HTTPS_PROXY 指向了一个已经过期的地址，请求先走代理再转 base_url，直接 timeout。把代理环境变量清掉或者加 NO_PROXY 排除你的 API 域名就行：
export NO_PROXY="api.ofox.ai"
不同模型的实测效果
既然都配好了，顺手测了一下几个模型在 Aider 里的表现。任务是给一个 FastAPI 项目加一个带分页的用户列表接口：
| 模型 | 首次响应时间 | 生成代码行数 | 一次通过（无需手动修） | 体感评价 |
|---|---|---|---|---|
| Claude Opus 4.7 | 约 3.8s | 127 行 | ✅ | 逻辑最严谨，连异常处理都写了 |
| Claude Sonnet 4.6 | 约 1.9s | 89 行 | ✅ | 速度快，够用，性价比最高 |
| GPT-5.5 | 约 2.4s | 102 行 | ❌ 分页参数校验缺了 | 代码风格好看但细节差一点 |
| DeepSeek V3.2 | 约 2.1s | 95 行 | ✅ | 出乎意料的稳 |
Sonnet 4.6 的速度确实快，日常写代码用它就够了。Opus 4.7 留给复杂重构场景。
小结
配置 Aider 的 API 地址就三步：选一种配置方式（推荐 .aider.conf.yml），填好 openai-api-base 和 Key，模型名记得带 openai/ 前缀。踩坑最多的地方反而是环境变量冲突和 stream 模式的兼容问题，上面的报错信息都贴了，遇到了直接搜就能找到对应的解法。
关于 edit-format 选 diff 还是 whole，我也没完全确定哪个对所有模型都最优。目前的经验是 Claude 系列用 diff 更稳，GPT 系列用 whole 出错少一些，你可以自己试试。
