如果你平时大部分时间都泡在终端里写代码最近应该频繁听到“Aider”这个名字。简单说Aider 是一个跑在终端里的 AI 配对编程工具你只要用自然语言把需求说清楚它就能读取当前仓库的文件生成修改建议自动写入代码甚至帮你写好提交信息。它不像网页版 AI 助手那样只能复制粘贴代码而是能真正参与整个提交流程。很多人第一次装好 Aider 之后都是直接连默认模型但实际用下来会发现默认配置不一定适合所有人费用、数据隐私、模型偏好、网络延迟甚至团队统一审计都会成为换 API 的理由。于是“Aider 怎么配置自定义 API”就成了绕不开的问题。这篇文章我就结合自己从零接入的经验整理一份完整教程从原理到命令再到报错排查都有。文章默认你用的是 Linux、macOS 或者 WSL 环境如果是在 Windows 原生终端里操作我会顺便提一下差异。如果你只想快速接上一个能用的模型直接跳到第 3 节照着做如果你希望搞清楚为什么这么配建议从头看一遍概念部分后面排查问题会更有方向。1. 为什么要在终端里给 Aider 配自定义 API1.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 APILM Studio 一键开启本地服务后也是兼容格式甚至很多商业大模型网关也都实现了这个协议。所以配置自定义 API 不需要你去了解 Aider 内部实现只需要知道三个参数API 地址、API 密钥、模型名。Aider 会把它们拼成合法的 HTTP 请求发出去然后把返回结果解析成代码修改展示给你。理解这一点之后你会发现网上那些五花八门的“Aider 接入教程”底层逻辑完全一样。不管是接本地模型、接公司网关、还是接某个商业 API只要对方说“我们支持 OpenAI 兼容格式”你在 Aider 里的配置方法就几乎相同。这就是为什么这份教程可以覆盖绝大多数场景。2.2 三个核心配置项逐个拆解配置自定义 API本质上就是告诉 Aider 三件事请求发到哪里、用什么身份、调用哪个模型。我整理了一个对应关系表配置项常用环境变量命令行参数作用API 地址OPENAI_API_BASE--openai-api-base告诉 Aider 请求发到哪个服务端API 密钥OPENAI_API_KEY--openai-api-key身份认证服务端用这个识别调用者模型名OPENAI_API_MODEL或--model--model指定具体模型同时影响 Aider 的编辑策略逐个说明一下。API 地址通常是一串 URL比如http://localhost:11434/v1。这里最容易犯的错是漏掉/v1路径后面排查部分我会专门讲。API 密钥如果服务端不需要认证可以填EMPTY、ollama或任意非空字符串但最好不要留空因为有些服务端会校验格式。模型名则是三个配置项里最容易踩坑的Aider 不仅会把模型名放进请求体还会根据这个名字判断模型的能力例如是否支持工具调用、上下文多长、输入文本用什么编码等。如果你准备用环境变量在终端里执行export OPENAI_API_BASEhttp://localhost:11434/v1 export OPENAI_API_KEYollama export OPENAI_API_MODELllama3.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 tokenAider 却按 128K 去估算一旦项目文件多了请求超出模型能力就会出现报错或截断。所以正确的做法是能用provider/model这种格式就用这个格式让 Aider 自动加载已知的元数据。比如本地 Ollama 就用ollama/llama3.2OpenAI 兼容接口就用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 接上自定义 API3.1 先把环境和依赖装好Aider 是一个 Python 包安装之前需要确保本机有 Python 3.9 以上版本和 Git。推荐用虚拟环境安装避免和系统依赖冲突python -m pip install -U aider-chat如果你习惯用 pipx也可以这样pipx install aider-chatWindows 用户如果要装我建议直接装 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 listOllama 默认监听 11434 端口并提供/v1的 OpenAI 兼容端点。启动 Aider 时最简单的写法是aider --model ollama/llama3.2Aider 内置了对 Ollama 的特殊支持看到ollama/前缀就知道你用的是本地 OllamaAPI 地址默认会指向http://localhost:11434/v1密钥随便填一个非空字符串就行。如果你想把三个配置项显式写出来方便理解也可以这样export OPENAI_API_BASEhttp://localhost:11434/v1 export OPENAI_API_KEYollama 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-codervLLM 默认监听 8000 端口API 地址就是http://localhost:8000/v1。启动 Aider 时命令如下export OPENAI_API_BASEhttp://localhost:8000/v1 export OPENAI_API_KEYEMPTY 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。保存之后每次进入这个项目目录运行aiderAider 会自动读取配置不需要再带任何参数。配合环境变量还能做到密钥和配置分离配置文件里只写地址和模型名密钥通过export AIDER_OPENAI_API_KEYxxx注入这样即使配置文件不小心被提交到 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 pytestAider 会运行这行命令并把输出结果返回给你。如果测试失败你可以把报错信息直接丢给模型让它继续修改代码然后再跑一次测试。这个“改代码—跑测试—看失败—继续改”的循环非常适合做测试驱动开发。你甚至可以让 Aider 先把失败的测试用例写好再让它去实现功能直到测试全部通过。整个过程不需要你频繁切出终端Aider 就像一个能跑测试的配对搭档。4.4 只读模式和仓库地图有时候你并不是想让 Aider 改代码而是想让它帮助你理解代码或者 review 某个函数。这时可以用/read-only把文件标记为只读Aider 只读取这些文件作为参考不会修改它们。/add和/read-only的区别可以理解为“可编辑上下文”和“参考上下文”。另一个有用的概念是“仓库地图”。Aider 每次请求时会生成一个当前仓库的结构摘要帮助模型快速定位相关文件。文件多了之后这个地图的 token 消耗也会变大。如果你觉得请求太慢或者 token 超了可以调低--map-tokens的值减少地图 token 占用代价是模型对仓库全局结构的把握会弱一些。5. 常见问题与排查技巧实录5.1 常见报错速查表我把实际操作中遇到的高频问题整理成了一张表方便你快速定位现象可能原因解决办法启动提示找不到 API key环境变量没有设置或没生效检查echo $OPENAI_API_KEY确认 export 写法Connection refusedAPI 服务没启动或地址/端口不对先用 curl 验证服务确认监听地址和端口404 Not FoundAPI 地址缺少/v1路径检查 base URL按服务文档补齐路径model not found模型名与实际部署名不一致本地用ollama list远端查服务商控制台请求成功但返回为空本地模型负载过高、上下文太长换小模型、减少/add文件数、调低 token 上限中文乱码终端编码不是 UTF-8设置 localeWindows 建议改 WSL自动提交太频繁你不希望每次改动都生成 commit启动参数加--no-auto-commits模型太弱导致代码错误多本地小模型能力不足换 8B 以上模型或代码专精模型这张表覆盖了绝大多数新手入门时遇到的问题。下面再对几个常见难点深入聊一聊。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 日志看看实际请求 URLaider --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 在你手里才能真正变成一个好用的配对编程搭档。