Aider自定义API配置完全指南：从Ollama到OpenAI兼容接口

如果你平时大部分时间都泡在终端里写代码，最近应该频繁听到“Aider”这个名字。简单说，Aider 是一个跑在终端里的 AI 配对编程工具，你只要用自然语言把需求说清楚，它就能读取当前仓库的文件，生成修改建议，自动写入代码，甚至帮你写好提交信息。它不像网页版 AI 助手那样只能复制粘贴代码，而是能真正参与整个提交流程。很多人第一次装好 Aider 之后都是直接连默认模型，但实际用下来会发现，默认配置不一定适合所有人：费用、数据隐私、模型偏好、网络延迟甚至团队统一审计，都会成为换 API 的理由。于是“Aider 怎么配置自定义 API”就成了绕不开的问题。这篇文章我就结合自己从零接入的经验，整理一份完整教程，从原理到命令，再到报错排查都有。

文章默认你用的是 Linux、macOS 或者 WSL 环境，如果是在 Windows 原生终端里操作，我会顺便提一下差异。如果你只想快速接上一个能用的模型，直接跳到第 3 节照着做；如果你希望搞清楚为什么这么配，建议从头看一遍概念部分，后面排查问题会更有方向。

1. 为什么要在终端里给 Aider 配自定义 API

1.1 Aider 到底是什么，终端配对编程体验如何

Aider 是一个开源项目，口号叫 AI pair programming in your terminal，翻译过来就是“终端里的 AI 配对编程”。它本质上是一个命令行客户端，本身不内置模型。安装之后，你在一个 Git 仓库目录里运行aider，它会以聊天界面的形式等你下指令。相比网页版 AI 助手，Aider 最大的差异在于它拥有文件读写能力：你先用/add把相关源文件加入上下文，然后说“为这几个函数补上错误处理”，Aider 会基于当前仓库内容生成 diff，直接改到文件里，最后根据改动生成提交信息并要求你确认。

因为全程不用离开终端，它特别适合两类人：一类是经常通过 SSH 登录服务器改代码的开发者，另一类是把终端当作主要工作台、喜欢平铺窗口工作流的人。Aider 之所以敢直接改文件，核心是 Git。它始终运行在 Git 仓库里，每次改动都通过 patch 应用，你可以随时用/undo回滚。这个机制让“AI 改代码”这件事变得安全可控：模型可能犯错，但版本控制兜底，不会把项目搞坏。

我最初不太理解“配对编程”这个词，用了一段时间才有了体感。网站版的对话机器人是“你问一句，它答一句”，代码要自己复制；Aider 更像一个坐在你旁边、手里拿着你仓库代码的同事，你说的不是零散的问答，而是“把这段逻辑重构一下”“在这个模块里加一个接口”，它直接帮你把活干完。这种体验差异，只有真正接到一个能稳定工作的模型之后才能感受到。

1.2 默认模型不够用，自定义 API 解决哪些问题

默认情况下，Aider 会尝试连接官方默认模型的接口。如果只是个人尝尝鲜，这样做没问题，但一旦深入使用就会发现几个很现实的问题。

首先是成本不可控。Aider 每次请求会读取相关文件、生成仓库地图、带上对话历史，token 消耗比单纯聊天快很多。你如果只是改个小脚本，为几个简单任务连续对话，账单可能很快让你肉疼。其次是数据隐私。代码是一个公司最核心的资产，很多团队根本不允许把代码上传到外部服务。把 Aider 接到本地部署的模型上，代码完全不出内网，这是“终端配对编程”落地企业内部的前提条件。

第三是模型选择受限。你可能想用开源模型、某个垂直微调模型，或者团队统一采购的模型服务。如果不支持自定义 API，你就会被绑定在默认那一两家上，这对有模型偏好的人来说非常难受。第四是稳定性和延迟。官方接口的可用性、响应速度在不同时段差异挺大，如果网络路径还复杂，交互式编程时每次请求等十几秒，体验会非常割裂。接到自建推理服务后，内网延迟通常能压到很低，代码修改的反馈节奏会顺畅很多。

自定义 API 本质上就是把 Aider 里的三个接口参数替换成你想用的地址、密钥和模型名。这相当于给终端里的 AI 助理换了一个大脑，整体使用方式不变，但背后的模型和链路完全由你掌控。

1.3 什么人适合看这份教程

这份教程主要适合四类人：一是已经在用 Aider，但想切换到 Ollama、LM Studio、vLLM 等本地模型的人；二是团队里已经有了 OpenAI 兼容的模型网关，想给每个开发者统一配置 Aider 的人；三是不想为简单任务付出默认模型 token 成本，希望接一个免费或低价模型的人；四是对数据安全有要求，需要在隔离环境里完成 AI 辅助编程的人。

如果你完全没接触过终端，我建议先花半小时熟悉cd、ls、export这几个基础命令，再回来看这篇教程。Aider 的使用门槛并不高，但终端操作基础是绕不开的。

2. 配置前先搞懂这几个关键概念

2.1 Aider 与自定义 API 的“语言约定”

Aider 本质上是一个 AI API 客户端，它通过 HTTP 调用后端模型服务的接口。为了兼容性，Aider 主要走的是 OpenAI Chat Completions 格式：请求体里面是model、messages等字段，响应里返回choices。只要你的自定义 API 服务能理解这个格式，Aider 就能用它，而不需要关心背后的模型是什么、训练数据是什么、部署在哪个机房。

这个设计对使用者非常友好。因为现在几乎所有主流推理框架都提供了 OpenAI 兼容接口：Ollama 从很早就支持/v1端点，vLLM 直接支持 OpenAI API，LM Studio 一键开启本地服务后也是兼容格式，甚至很多商业大模型网关也都实现了这个协议。所以配置自定义 API 不需要你去了解 Aider 内部实现，只需要知道三个参数：API 地址、API 密钥、模型名。Aider 会把它们拼成合法的 HTTP 请求发出去，然后把返回结果解析成代码修改展示给你。

理解这一点之后，你会发现网上那些五花八门的“Aider 接入教程”，底层逻辑完全一样。不管是接本地模型、接公司网关、还是接某个商业 API，只要对方说“我们支持 OpenAI 兼容格式”，你在 Aider 里的配置方法就几乎相同。这就是为什么这份教程可以覆盖绝大多数场景。

2.2 三个核心配置项逐个拆解

配置自定义 API，本质上就是告诉 Aider 三件事：请求发到哪里、用什么身份、调用哪个模型。我整理了一个对应关系表：

逐个说明一下。API 地址通常是一串 URL，比如http://localhost:11434/v1。这里最容易犯的错是漏掉/v1路径，后面排查部分我会专门讲。API 密钥如果服务端不需要认证，可以填EMPTY、ollama或任意非空字符串，但最好不要留空，因为有些服务端会校验格式。模型名则是三个配置项里最容易踩坑的：Aider 不仅会把模型名放进请求体，还会根据这个名字判断模型的能力，例如是否支持工具调用、上下文多长、输入文本用什么编码等。

如果你准备用环境变量，在终端里执行：

export OPENAI_API_BASE=http://localhost:11434/v1 export OPENAI_API_KEY=ollama export OPENAI_API_MODEL=llama3.2

如果你更喜欢命令行参数，等价写法是：

aider --openai-api-base http://localhost:11434/v1 --openai-api-key ollama --model llama3.2

我个人的习惯是：排查问题时用命令行参数临时指定，稳定下来之后用配置文件固定，后面会讲到。

2.3 为什么模型名不能随便填

模型名是 Aider 配置里最特殊的部分，因为它不只是请求里的一个字符串。Aider 内置了一张模型元数据表，记录了各种模型的最大输入 token、最大输出 token、是否支持工具调用、推荐使用哪种编辑格式等信息。比如 GPT-4 系列支持 function call，所以 Aider 会用更高效的增量修改方式；而某些本地小模型不支持工具调用，Aider 就会改成直接把完整文件重写，效率差很多。

如果模型名填错了，Aider 可能把“重写整个文件”误判为“可以精准定位修改”，导致生成结果非常差。更常见的问题是上下文窗口识别错误：模型实际只能处理 8K token，Aider 却按 128K 去估算，一旦项目文件多了，请求超出模型能力，就会出现报错或截断。

所以正确的做法是：能用provider/model这种格式就用这个格式，让 Aider 自动加载已知的元数据。比如本地 Ollama 就用ollama/llama3.2，OpenAI 兼容接口就用openai/模型名。确实遇到很冷门、Aider 不认识的模型时，再用--model-metadata-file手动补充，第 5 节我会详细说。

2.4 动手前先 curl 验证 API 通不通

很多人在 Aider 里折腾半天，最后发现其实是 API 服务本身有问题。所以我强烈建议，在接入 Aider 之前，先用 curl 手动打一次接口，确认服务是否正常。以本地 Ollama 为例：

curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"llama3.2","messages":[{"role":"user","content":"hi"}]}'

如果返回一段包含choices字段的 JSON，说明服务通了。如果返回 404，先检查路径是不是少了/v1；如果返回 401 或 403，检查密钥；如果返回模型不存在，检查模型名。对于任意 OpenAI 兼容 API，道理一样，只是需要加一个认证头：

curl http://your-api-host:port/v1/chat/completions \ -H "Authorization: Bearer your-key" \ -H "Content-Type: application/json" \ -d '{"model":"your-model","messages":[{"role":"user","content":"hi"}]}'

这一步做好了，后面 Aider 的报错能少一半。我的经验是：Aider 本身很稳定，绝大多数接入失败都是 API 地址写错、模型名不对、或者服务没起来这三种原因。

3. 实操：两种主流方式把 Aider 接上自定义 API

3.1 先把环境和依赖装好

Aider 是一个 Python 包，安装之前需要确保本机有 Python 3.9 以上版本和 Git。推荐用虚拟环境安装，避免和系统依赖冲突：

python -m pip install -U aider-chat

如果你习惯用 pipx，也可以这样：

pipx install aider-chat

Windows 用户如果要装，我建议直接装 WSL，在 WSL 的 Linux 环境里跑 Aider。原因很实际：Aider 的交互界面依赖终端控制序列，原生 Windows 终端有时会出现颜色显示异常、光标移动错位、快捷键不灵等问题，换成 WSL 基本都能规避。装完之后还要记得进入 Git 仓库。Aider 强制要求工作在 Git 仓库里，这是它的设计底线：只有代码被版本控制，AI 的自动修改才可回滚。如果你只是想测试，可以建一个临时目录：

mkdir test-aider && cd test-aider && git init

装完可以运行一下aider --version，看到版本号就说明环境没问题。

3.2 方式一：接本地 Ollama，零成本跑通

Ollama 是目前最简单的本地模型运行工具，安装之后拉一个模型就能用。先拉取模型，以 llama3.2 为例：

ollama pull llama3.2

如果你喜欢代码能力更强的模型，可以考虑qwen2.5-coder:7b、codegemma这类专门为代码优化的模型。查看本地已经下载了哪些模型：

ollama list

Ollama 默认监听 11434 端口，并提供/v1的 OpenAI 兼容端点。启动 Aider 时，最简单的写法是：

aider --model ollama/llama3.2

Aider 内置了对 Ollama 的特殊支持，看到ollama/前缀就知道你用的是本地 Ollama，API 地址默认会指向http://localhost:11434/v1，密钥随便填一个非空字符串就行。如果你想把三个配置项显式写出来，方便理解，也可以这样：

export OPENAI_API_BASE=http://localhost:11434/v1 export OPENAI_API_KEY=ollama aider --model llama3.2

这里有个细节需要注意：使用环境变量方式时，模型名到底要不要带ollama/前缀，取决于 Aider 版本。为了避免踩坑，我推荐直接用aider --model ollama/llama3.2这种写法，让 Aider 自己处理 provider 逻辑，最省心。

本地小模型的速度和效果会受硬件影响。我自己实测下来，7B 到 8B 左右的模型在代码修改任务上勉强能用，但遇到复杂重构会明显吃力；有条件的话上 70B 或者更大参数量的模型，体验会有质变。如果你只是想先跑通流程，用一个小模型练手完全没问题。

3.3 方式二：接任意 OpenAI 兼容 API，不限于本地

除了 Ollama，你还会遇到大量其他推理服务。最典型的是 vLLM，它经常被用来部署企业内部的模型服务。比如启动一个本地模型：

vllm serve deepseek-ai/deepseek-coder-6.7b-instruct --served-model-name deepseek-coder

vLLM 默认监听 8000 端口，API 地址就是http://localhost:8000/v1。启动 Aider 时，命令如下：

export OPENAI_API_BASE=http://localhost:8000/v1 export OPENAI_API_KEY=EMPTY aider --model openai/deepseek-coder

注意这里的模型名带了openai/前缀。Aider 看到openai/前缀，就会把请求发送到OPENAI_API_BASE指向的地址，而这个地址可以是任何兼容 OpenAI 格式的服务。vLLM 的--served-model-name参数决定了你请求时要使用的模型名，上面例子中我把它设置成了deepseek-coder，所以--model里也写deepseek-coder。

如果接的是 LM Studio，默认地址是http://localhost:1234/v1，模型名就是你在 LM Studio 里加载的模型名称，启动命令：

aider --model openai/模型名 --openai-api-base http://localhost:1234/v1 --openai-api-key EMPTY

如果接的是公司内部统一网关，操作完全一样，把地址换成网关地址，模型名换成网关发布的模型名，密钥换成你的个人 token。这种方式对团队特别友好：管理员在网关后面接入各种商业模型或开源模型，开发者只需要拿到一个 base 地址和 key，就能在 Aider 里自由使用。

3.4 用配置文件固定配置，避免每次敲一堆参数

配置项一多，每次启动时敲一堆参数就很烦。Aider 支持配置文件.aider.conf.yml，可以放在项目根目录，也可以放在用户主目录。根目录配置优先于主目录配置，每个项目可以有自己的模型设置。

如果只接 Ollama，配置文件可以非常简单：

model: ollama/llama3.2

如果接的是一个 OpenAI 兼容的自定义 API，配置文件大概长这样：

model: openai/deepseek-coder openai-api-base: http://localhost:8000/v1 openai-api-key: EMPTY

注意 YAML 的缩进，不要用 Tab。保存之后，每次进入这个项目目录运行aider，Aider 会自动读取配置，不需要再带任何参数。配合环境变量还能做到密钥和配置分离：配置文件里只写地址和模型名，密钥通过export AIDER_OPENAI_API_KEY=xxx注入，这样即使配置文件不小心被提交到 Git，密钥也不会泄露。

还有一个实用技巧：在项目根目录的.gitignore里加一行.aider.conf.yml，避免把本地配置误提交。毕竟每个开发者可能用不同的模型，配置文件属于个人工作区。

3.5 如何验证配置是否真的生效

配置完成后，怎么确认 Aider 确实在用你指定的 API？第一步，启动 Aider 时注意看界面上方的模型信息，它会显示当前使用的模型名称和 API 地址。第二步，在会话中输入/model，它会列出当前模型以及可切换的模型，这是最直接的验证方式。第三步，随便发一句简单需求，比如“用 Python 写一个计算斐波那契数列的函数”，观察模型是否正常响应。如果 API 地址不对，启动时一般会立刻报连接错误；如果模型名不对，往往在发送第一条消息时才报错。

我自己的习惯是先跑一条最简单的请求，确认链路通顺后再开始正式任务。这样能避免在复杂任务的中途突然发现配置问题，省掉很多不必要的排查时间。

4. 配置好之后，用 Aider 完成一次真实编程任务

4.1 初始化 Git 仓库和添加上下文

配置完 API，接下来需要实际用起来。第一步是准备一个 Git 仓库，然后启动 Aider。假设你有一个空项目：

mkdir ai-blog && cd ai-blog && git init

创建一个简单的 Python 文件：

echo "" > cli.py

启动 Aider，这里以接 Ollama 为例：

aider --model ollama/llama3.2

进入交互界面后，把文件加入上下文：

/add cli.py

然后就可以提需求了。比如：“给 cli.py 增加一个命令行参数 --verbose，默认为 False，当它为 True 时打印详细日志”。Aider 会读取文件当前内容，生成修改方案，展示 diff，询问你是否应用。确认应用之后，文件被修改，紧接着 Aider 会生成一条提交信息并执行 commit。你可以退出后用git log --oneline查看，会看到一条由 AI 生成的提交记录。

这个流程就是 Aider 的核心工作方式：需求、改码、应用、提交。整套都在终端里完成，没有离开过工作环境。

4.2 多文件修改与补测试

Aider 一次可以添加多个文件，这让它特别适合跨文件改造。比如你的项目里有app.py、utils.py、tests/test_app.py，可以这样：

/add app.py utils.py tests/test_app.py

然后说：“根据 utils.py 里新增的 helper 函数，为 app.py 补上调用逻辑，并在 test_app.py 里增加两个对应的测试用例。”Aider 会同时理解这几个文件的关联，生成跨文件的修改 patch。这就是终端配对编程和网页问答最本质的区别：它不只是告诉你“应该改哪里”，而是直接把多个文件一起改了。

但如果改动了关键模块，我建议在提出大需求之前先手动/commit一次，给自己留一个稳定基线。Aider 的自动提交虽然方便，但粒度不一定符合你的预期。

4.3 用 /run 直接执行命令

Aider 不是只能聊天改代码，它还能执行终端命令。在会话里输入/run pytest，Aider 会运行这行命令并把输出结果返回给你。如果测试失败，你可以把报错信息直接丢给模型，让它继续修改代码，然后再跑一次测试。

这个“改代码—跑测试—看失败—继续改”的循环，非常适合做测试驱动开发。你甚至可以让 Aider 先把失败的测试用例写好，再让它去实现功能，直到测试全部通过。整个过程不需要你频繁切出终端，Aider 就像一个能跑测试的配对搭档。

4.4 只读模式和仓库地图

有时候你并不是想让 Aider 改代码，而是想让它帮助你理解代码或者 review 某个函数。这时可以用/read-only把文件标记为只读，Aider 只读取这些文件作为参考，不会修改它们。/add和/read-only的区别，可以理解为“可编辑上下文”和“参考上下文”。

另一个有用的概念是“仓库地图”。Aider 每次请求时会生成一个当前仓库的结构摘要，帮助模型快速定位相关文件。文件多了之后，这个地图的 token 消耗也会变大。如果你觉得请求太慢或者 token 超了，可以调低--map-tokens的值，减少地图 token 占用，代价是模型对仓库全局结构的把握会弱一些。

5. 常见问题与排查技巧实录

5.1 常见报错速查表

我把实际操作中遇到的高频问题整理成了一张表，方便你快速定位：

这张表覆盖了绝大多数新手入门时遇到的问题。下面再对几个常见难点深入聊一聊。

5.2 API 地址最容易犯的“/v1 重复”问题

API 地址是配置里最“细思极恐”的部分。很多服务商给出的 base URL 是https://api.example.com/v1，这个/v1一般表示 API 版本。如果你漏掉了，Aider 请求会发到https://api.example.com/chat/completions，很容易 404。但如果你接的是某些老版本配置，Aider 本身又在地址后面自动追加过/v1，就可能出现https://api.example.com/v1/v1这种奇怪路径，同样 404。

遇到 404 时，不要瞎猜，先开 Aider 的 verbose 日志看看实际请求 URL：

aider --model openai/deepseek-coder --openai-api-base http://localhost:8000/v1 --verbose

日志里会打出请求的完整路径，一看就知道问题出在哪。这个习惯我一直保留着，排查网络类问题非常高效。

5.3 模型元数据不识别怎么办

当你用最新的开源模型时，Aider 可能不认识这个模型，启动时会提示 unknown model。解决办法是用--model-metadata-file参数指定一个 JSON 文件，手动告诉 Aider 这个模型的能力参数。文件大致长这样：

{ "model_name": "my-local-model", "max_input_tokens": 32768, "max_output_tokens": 4096, "use_tools": false }

启动时这样用：

aider --model openai/my-local-model --model-metadata-file ./my-model.json

核心思路是让 Aider 知道这个模型能承担多大的任务、支不支持工具调用，从而匹配编辑方式。需要提醒的是，文件里具体还支持哪些字段，最好以 Aider 官方文档为准，不同版本略有差异。这个技巧属于进阶玩法，只有用到冷门模型时才需要，大多数情况下用内置的 provider 前缀就够了。

5.4 交互卡顿与响应慢的排查思路

如果你配置完成后发现 Aider 响应很慢，先别急着怀疑网络。如果模型跑在本地，用/run htop或/run nvidia-smi看看 CPU、GPU 和内存占用情况。本地小模型推理本来就是计算密集型任务，如果模型参数量超过显卡显存，速度会非常感人。如果模型跑在远端，重点看网络延迟和服务端负载。

还有一个容易被忽略的因素：Aider 每次请求会携带仓库地图，文件越多、目录越复杂，地图 token 消耗越大，响应自然变慢。你可以减少--map-tokens的值，或者只/add真正相关的文件，不要一次性把整个仓库塞进去。交互式编程讲究快速反馈，上下文精简对体验提升非常明显。

5.5 安全习惯和合规提醒

接入自定义 API 之后，安全习惯比配置本身更重要。API key 尽量放到环境变量里，或者使用系统密钥管理工具，不要直接写进配置文件并提交到 Git。对接外部 API 时，先确认服务商的条款允许你用它来做自动代码修改，避免超出使用范围。对接本地模型时，代码不出本机，隐私保护最好，这也是很多企业选择本地部署的原因。

另外，不要把项目里所有文件都加入上下文。Aider 只会读取你通过/add或/read-only加入的文件，加入越少，token 越省，模型也越不容易被无关代码干扰判断。

6. 最后分享一点我的经验和体会

从最初直接启动 Aider 连默认模型，到后来切换到团队网关、再到本地 Ollama 和 vLLM，这个折腾过程我走了不少弯路。现在我最顺手的配置是：日常简单任务用本地 8B 左右的模型，省心省钱；遇到复杂重构、跨模块改动时，切到能力更强的商业 API，通过/model在同一个终端会话里随时切换。两个模型共存，既不心疼 token，也不耽误效率。

要让我给新用户一个建议，我会说三件事：第一，配置文件一定要整理好，放项目根目录，密钥走环境变量，换机器之后五分钟就能恢复工作环境。第二，Git 仓库一定初始化，Aider 的所有自动修改都依赖版本控制，没有 Git 就没有后悔药。第三，遇到连不上、报错，先用 curl 自己打一次 API 接口，确认服务端正常，再回头看 Aider 配置。这个排查顺序能解决绝大多数接入问题。

这套配置流程我前后教过不少同事，覆盖的坑基本就是上面这些。如果你是在终端里第一次体验 AI 配对编程，从 Ollama 接本地小模型开始是最低成本的路，先跑通，再根据自己的场景慢慢换成真正需要的 API。配置本质上就是地址、密钥、模型名三件事，弄懂了这三个参数，Aider 在你手里才能真正变成一个好用的配对编程搭档。