1. 先搞清楚Aider为什么要折腾自定义API1.1 自定义API解决什么问题Aider这个工具本质上是把大模型的能力塞进终端里让你在写代码的时候不用频繁切换窗口直接在命令行里让AI帮你改文件、写测试、重构代码。它默认对接的是OpenAI官方接口开箱即用填个Key就能跑。但实际用下来很多人会碰到几个绕不开的点。第一官方接口按token计费高频使用时账单涨得飞快尤其是让AI反复改一个大型代码库的时候。第二有些项目对数据有要求代码不能出内网需要把模型部署在本地或私有环境里。第三很多人手里已经有现成的模型服务比如本地跑着Ollama、LM Studio或者公司内部用vLLM搭了一套统一推理平台这时候再去单独开一个OpenAI账号就重复建设了。Aider好就好在它对API地址做了抽象支持通过环境变量和启动参数把请求指向任何兼容OpenAI协议的端点。所以配置自定义API解决的不只是省钱问题更关键的是把Aider接进你自己的模型服务生态里让终端AI配对编程真正落地到你现有的基础设施上。1.2 一套通用的接入思路不管你的服务端是哪个平台接入思路其实可以统一成三步确认服务端地址、确认模型对外名称、告诉Aider这两个信息再加一个有效的Key。这里稍微解释一下原理。Aider在请求模型时走的是OpenAI的Chat Completions协议也就是向{base_url}/chat/completions这个路径发POST请求。你配置自定义API时本质上就是做三件事把base_url指向你自己的服务把模型名改成服务端实际注册的名字再填一个服务端认账的密钥。理解了这个套路之后你会发现配置本身不复杂真正的坑往往出在细节上——比如Ollama的地址端口、vLLM的served-model-name、不同服务对模型前缀的要求这些后面会逐一展开。2. 动手前的三项准备2.1 安装Aider本体先确认你的终端里有没有Aider。安装方式很简单Python环境干净的话直接pip install aider-chat装完验证一下aider --version如果之前装过但版本太老建议顺手升级pip install --upgrade aider-chat在macOS上也可以用Homebrewbrew install aider不过我个人还是推荐pip方式版本更新更及时踩坑时查文档也对得上号。Windows用户只要装好了Python并勾选了PATH在PowerShell或Windows Terminal里同样用pip安装后续配置方式完全一致。安装时有个小经验尽量用虚拟环境避免和其它Python项目的依赖冲突。我自己就吃过亏全局环境里装了一堆包aider启动时莫名其妙的报错排了半天才发现是某个依赖版本不兼容。2.2 理解API地址、密钥、模型名这三样东西任何OpenAI兼容的自定义API你都要拿到三个信息缺一不可。API地址Base URL是服务的入口比如本地Ollama默认监听http://localhost:11434/v1LM Studio的本地服务默认是http://localhost:1234/v1vLLM启动后会告诉你一个地址通常是http://localhost:8000/v1。记住最后要有/v1前缀Aider会在它后面拼上/chat/completions发请求。密钥API Key用于身份认证。有些本地服务不校验Key随便填一个字符串就能过比如Ollama官方文档里也是这么建议的。但生产环境的服务通常会校验你得用服务端分配的真实密钥。理解这点很关键否则你会看到Aider那边报了401却想不通本地服务明明不需要密码。模型名Model Name是最容易出问题的一个。它不是你在Aider里随便指定的显示名而是服务端真正注册好的那个标识。比如Ollama里ollama list看到的名字是qwen2.5-coder:14b你就得用这个名字去请求。vLLM启动时如果不加--served-model-name参数默认会用模型路径里的名字但很多部署者会手动指定一个对外名称你得去服务端确认。2.3 确认你的服务端是OpenAI兼容的这一点值得单独拎出来说。现在很多模型服务框架都自称兼容OpenAI但兼容程度参差不齐。Aider依赖的是/chat/completions这套接口如果你的服务端只支持/completions老式文本补全接口或者走了自定义协议那Aider直接连是连不上的必须靠中间层做转换。一个快速的验证方法是在终端里用curl直接调一下接口确认服务真的活着、地址和模型名都对得上。比如Ollama的验证命令curl http://localhost:11434/v1/models如果返回一串JSON里面包含你拉取的模型列表说明服务正常。这一步能帮你把服务问题和Aider配置问题隔离开。很多人一上来就配Aider报错了不知道是Aider的问题还是后端服务的问题其实就是少了这个前置验证。3. 最省事的接法本地Ollama一键接入3.1 启动本地模型服务如果你的目标只是想在Aider里跑本地模型Ollama是目前最省心的选择。它把模型下载、服务启动、OpenAI兼容接口全打包好了几乎零门槛。先确保Ollama已经安装并启动。Linux和macOS用户在终端执行ollama serveWindows用户一般装的是桌面版装好后服务会自动在后台跑。确认服务状态同样用curl测一下curl http://localhost:11434/v1/models然后拉取你要用的模型。编程场景下我建议优先选代码类模型效果和通用模型差距很大。比如ollama pull qwen2.5-coder:14b这个模型对代码理解、生成、重构的表现都算本地模型里的第一梯队14B的体量在中高端个人电脑上也能跑得动。显存不够可以选7B版本显存充裕直接上32B效果会更好。3.2 用命令行参数接入Ollama服务起来之后Aider接入只需要三个参数。aider \ --openai-api-base http://localhost:11434/v1 \ --openai-api-key ollama \ --model ollama_chat/qwen2.5-coder:14b这里逐项说明一下。--openai-api-base指向Ollama的OpenAI兼容地址--openai-api-key随意填一个非空字符串Ollama本身不校验但Aider要求这个字段必须存在--model这里有个关键细节我填的是ollama_chat/qwen2.5-coder:14b其中ollama_chat/前缀告诉Aider这是一个走Ollama Chat格式的模型后面跟的是Ollama里真实的模型名。为什么要加这个前缀因为Ollama同时支持原生接口和OpenAI兼容接口Aider为了把两者区分开约定了一个命名规则。如果你不加前缀直接写qwen2.5-coder:14bAider会把它当成OpenAI原生模型去请求可能导致上下文窗口识别不对或请求格式异常。这是很多新手第一次接入时踩得最多的一类坑。3.3 用配置文件接入命令行参数适合临时验证但每次启动都敲一长串参数太啰嗦。更推荐把这些配置固化到Aider的配置文件里。Aider的配置文件名是.aider.conf.yml放在当前项目目录下或~/.aider.conf.yml作为全局配置。内容长这样model: ollama_chat/qwen2.5-coder:14b openai-api-base: http://localhost:11434/v1 openai-api-key: ollama保存后直接在项目目录运行aider它会自动读取配置不用再带任何参数。这个文件更适合放到项目里、跟着仓库走这样团队成员克隆下代码后只要装好Aider和Ollama执行aider就能用上同样的模型配置省去了一人一份参数说明的沟通成本。配置文件的优先级需要注意命令行参数高于配置文件配置文件高于环境变量。如果你在命令行显式传了参数它就会覆盖配置文件里同名的键。排查问题时先搞清当前生效的是哪一层配置能少走不少弯路。我实际用下来配置文件里还会加两个选项大家可以按需抄作业model: ollama_chat/qwen2.5-coder:14b openai-api-base: http://localhost:11434/v1 openai-api-key: ollama auto-commits: false pretty: trueauto-commits关闭后AI不会自作主张帮你提交Git生成代码给你过目后再手动提交避免了AI改坏代码产生一堆垃圾提交记录pretty开启后输出更好看终端里看代码差异体验明显提升。4. 换一个服务商怎么办LM Studio与vLLM端点配置4.1 LM Studio的本地开发服务器Ollama不是唯一选项。如果你喜欢图形界面或者需要在不同模型之间快速切换试用LM Studio更顺手。它在本地启动OpenAI兼容服务的方式很直观界面上找到一个类似Local Server的区域点一下Start按钮服务就起来了。LM Studio的默认端口是1234地址为http://localhost:1234/v1。对应Aider的配置是aider \ --openai-api-base http://localhost:1234/v1 \ --openai-api-key lm-studio \ --model openai/qwen2.5-coder-14b-instruct这里模型名需要留意。LM Studio加载模型后界面上会显示一个类似qwen2.5-coder-14b-instruct的标识你在Aider里填的模型名必须和它一致否则服务端报model not found。我见过不少人在这一步卡住实际去LM Studio的模型下拉列表里复制完整名称就不会错。另外一点LM Studio的模型名前面加openai/前缀还是ollama_chat/前缀取决于你加载的模型文件格式。大部分在LM Studio里跑的GGUF模型走的是OpenAI兼容Chat接口所以用openai/前缀比较稳。如果加了前缀后Aider提示模型不识别换成不带前缀的完整模型名再试。4.2 vLLM这类生产级端点怎么配vLLM是生产环境里非常常用的推理服务框架它启动时暴露的也是OpenAI兼容接口。和本地工具不同vLLM通常部署在服务器上所以你的Aider可能跑在另一台机器此时--openai-api-base要填的是服务器的访问地址比如http://192.168.1.100:8000/v1。vLLM接入Aider的典型参数aider \ --openai-api-base http://192.168.1.100:8000/v1 \ --openai-api-key token-abc123 \ --model openai/deepseek-coder-6.7b-instruct需要注意vLLM的一个特性模型对外名称默认取自模型路径但实际部署时常被参数覆盖。启动命令里如果带了--served-model-name那么对外名称就以此为准。比如下面这个启动命令python -m vllm.entrypoints.openai.api_server \ --model /models/deepseek-coder-6.7b \ --served-model-name code-helper \ --port 8000这个服务对外暴露的模型名就是code-helperAider里就必须填openai/code-helper。如果填了文件路径里的名字服务端会返回404。遇到这情况直接去vLLM日志里搜served-model-name或者问部署的人比在Aider端反复试快得多。4.3 不同端点的参数对照把几种常见服务端梳理成一张表方便对照配置服务端默认地址是否校验Key模型名获取方式Aider模型前缀Ollamahttp://localhost:11434/v1不校验ollama listollama_chat/LM Studiohttp://localhost:1234/v1不校验界面模型列表openai/或不用前缀vLLMhttp://服务器IP:8000/v1按部署配置启动参数served-model-nameopenai/商业兼容API服务商提供校验服务商文档按服务商要求还要提醒一种情况如果你用的是第三方商业API服务它虽然兼容OpenAI格式但模型名可能不是标准的GPT系列而是服务商自定义的名称。这种服务通常还要求你在请求里带上一个特殊的模型ID此时Aider里--model参数就要跟着服务商文档走前缀按它推荐的写法来不要照抄Ollama的习惯。5. 配置过程中的高频坑与排查实录5.1 认证失败401/403Aider报401或403第一反应别急着怀疑Key写错先分清你的服务端到底校不校验Key。Ollama和LM Studio本地模式下任何非空Key都能通过所以这两个服务如果报401大概率是--openai-api-key没传或者传了空值Aider认为你根本没提供密钥。vLLM生产环境则要看启动时有没有开鉴权开了就需要真实Key。排查方法很简单先用curl直接带Key请求一次curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer ollama \ -d {model:qwen2.5-coder:14b,messages:[{role:user,content:hi}]}如果curl也返回401说明问题在服务端和Aider无关如果curl通了Aider不通那你得检查Aider进程实际读取的配置确认没有旧的环境变量覆盖了你的新设置。5.2 模型名不匹配导致404Aider报404的时候绝大多数是模型名和服务端不匹配。很多人以为--model后面随便填一个听起来像的名字就行这是最大的误区。排查时按顺序做三件事。第一用服务端的命令或界面确认真实模型名Ollama用ollama listvLLM查日志或启动参数LM Studio看模型文件列表。第二确认Aider里加了正确的前缀Ollama场景要用ollama_chat/其它多数场景用openai/。第三直接把模型名和地址拿去curl验证这一步能立刻确认问题是不是出在名字上。5.3 上下文窗口不够用本地模型常见的报错之一是上下文长度超限提示类似context length exceeded。这个问题的根源是Aider对每个模型设了一套默认的上下文上限如果你的模型实际支持的上下文比Aider默认值小或者你的请求内容确实超过了模型上限就会触发。本地小模型尤其容易出现因为它们的上下文窗口往往就4K、8K而Aider在分析代码库时会往上下文里塞入大量代码内容很容易超出。解决办法有两个方向。一个是换大上下文模型。比如Qwen2.5系列很多模型原生支持128K上下文Ollama里可以指定num_ctx参数Aider侧也可以尝试将该模型的上下文上限调大model: ollama_chat/qwen2.5-coder:14b openai-api-base: http://localhost:11434/v1 openai-api-key: ollama另一个方向是让Aider少读点内容。Aider提供了--files参数你可以显式指定当前这次对话只关注哪些文件避免它把整个仓库都扫进上下文。这个习惯非常好既省token本地模型省显存又能让AI回答更聚焦实测对代码修改质量有明显提升。5.4 端口被占用或服务没起来Aider显示Connection refused说明它压根没连上你的服务端。这时候别急着看Aider配置先用浏览器或curl访问一下服务地址看服务有没有真的在监听端口。Ollama的默认端口是11434如果你之前装过老版本或手动改过配置端口可能不是默认值。查看Ollama实际占用端口Linux和macOS可以用lsof -iTCP -sTCP:LISTEN -P | grep -E ollama|11434服务起了但连不上还有一种常见场景Aider跑在远程服务器或容器里服务端跑在本机而你的--openai-api-base填了localhost从远程自然访问不到。这时候要么改成服务端的局域网IP要么通过端口转发把服务暴露过去。这个坑在远程开发场景里几乎每天都会遇到写代码前就想清楚Aider和模型服务各自跑在哪台机器上能省掉一大半连接故障的排查时间。5.5 意外收获的调试技巧最后分享几个调Aider时的实用技巧。Aider支持--verbose参数启动后会在终端打印完整的请求日志包括实际请求的URL、模型名、响应状态码。所有配置相关的问题只要开着--verbose跑一遍基本能定位到是地址不对、Key不对还是模型名不对。这个参数是排查Aider问题最值得依赖的工具没有之一。再一个是环境变量的问题。有时候你明明在命令行传了正确的参数但Aider仍然走了错误的配置十有八九是环境变量里残留了旧的OPENAI_API_BASE或OPENAI_MODEL。它们和命令行参数、配置文件混在一起优先级让人迷糊。建议从头到尾只用一种配置方式要么全部靠配置文件要么全部靠命令行参数混用的后果就是出问题时分不清哪层配置在起作用。还有一个小细节Aider对模型名的解析规则在不同版本之间有过调整。你搜到的很多教程可能是几个月前写的里面的前缀或配置格式可能已经变了。遇到配置解析相关的问题第一件事看官方文档里的Models说明比在网上翻旧帖子效率高得多。最后再分享一个我自己实际使用的体会Aider配置自定义API真正要花心思的不是把请求发出去而是把这个链路稳定地跑在你自己熟悉的环境里。我个人的习惯是先在本机用Ollama把整套流程跑通确认代码修改、Git提交这些核心功能都正常再考虑切换到更强大的服务端或生产级的vLLM端点。这样出了问题排查范围会被压缩得很小不会一会儿怀疑网络、一会儿怀疑模型、一会儿怀疑Aider配置。另外想提醒的一点是终端里的AI编程工具用得好不好配置只是第一步。Aider的价值在于它和Git深度绑定你能直观看到AI对代码的每一步改动可以随时回退、随时对比。这种可审查、可回滚的协作方式才是它区别于网页版AI助手的核心优势。配置好API之后多花点时间适应这种工作流你会感受到终端AI配对编程的真正效率提升。