高级 13 分钟Dev

Aider：开发智能体，运行方式为 CLI

直接回答

Aider 是一个命令行编程智能体，可根据您用法语提出的请求编辑文件，并将每次修改提交到 Git。在本地使用时，它通过 ollama_chat/ 前缀连接 Ollama；最关键的设置是上下文窗口，因为 Ollama 默认会将上下文静默截断至 2 000 个 token。要获得较为舒适的使用体验，至少需要 Devstral 这类拥有 240 亿参数的模型。

真正修改您文件的助手必须是可逆的、可预测的，并且能够在不将代码发送给第三方的情况下运行。Aider 符合这些要求，但前提是为本地模型正确配置它。本指南将涵盖安装、连接 Ollama、模型选择、聊天模式、Git 的作用以及您的测试，最后分析实际操作中遇到的问题。

作者： Mohamed Meguedmi·更新于 2026-09-30·已在 Windows、macOS 和 Linux 上测试

#Aider 是什么，以及它在您的代码仓库中做什么

Aider 是一款开源命令行编程助手，它将自身定位为在终端中与 AI 进行结对编程的工具。您在 Git 仓库中运行 aider 命令，用自然语言描述一项变更，它就会提出文件修改方案、应用这些修改，然后将其记录为一次提交。它既能使用托管模型（Claude、GPT、DeepSeek），也能使用由 Ollama 或 LM Studio 提供服务的本地模型，因此是少数无需让项目中的任何一行代码离开本机即可使用的代码智能体之一。其官方仓库在 GitHub 上的星标数已超过 49,000。

它有三个区别于普通聊天的特点。首先，它维护一份代码仓库结构图：每次请求时，都会向模型发送文件列表，其中包括各文件的类、函数和主要签名，让模型知道该去哪里查找，而无需您展示全部内容。其次，它与 Git 集成：每次修改都会成为一个可撤销的提交。最后，它会反复运行您指定的命令，包括代码检查器和测试，并尝试修复失败的部分。它不是一个会自主浏览网络或启动服务器的智能体，而是一个由对话驱动的代码编辑器。

i
本指南及其姊妹指南
本指南涵盖安装、本地配置，以及避免失败的实用做法。《Aider + Ollama：在终端中编程》指南进一步介绍了完整的工作流程；代码模型的对比则见专门的指南。

#安装 Aider

本地副驾驶套件

本指南带你上手模型。工具包则帮你用上能在你的编辑器中编写代码的编程助手。

  • 在线空间，终身可用
  • PDF + 文件
  • 30 天内退款
本地副驾驶工具包 →或 所有套件终身使用权 — 49 € →

官方最简安装方法是使用 aider-install 包，该方法会在独立的 Python 环境中安装 Aider，并在需要时下载兼容的 Python 版本。此方法要求 Python 版本在 3.8 到 3.13 之间。目前已有基于 uv 的单行安装脚本，支持 macOS、Linux 和 Windows。虽然旧版 pipx 安装方式仍有效，但当前文档推荐使用 aider-install。

推荐安装方式
python -m pip install aider-install
aider-install

# Vérifier
aider --version

随后，请进入项目根目录。如果该文件夹不是 Git 仓库，Aider 会建议创建一个，但最好由您自行初始化：下文所述的全部安全机制均依赖于 Git。

#将其连接到 Ollama，避免上下文设置中的陷阱

Aider 针对 Ollama 的官方文档可归纳为四个步骤：设置变量 OLLAMA_API_BASE（通常地址为 http://127.0.0.1:11434），使用 ollama pull 下载模型，启动服务器，然后在模型名称前加上 ollama_chat/ 前缀来运行 aider。文档明确推荐使用 ollama_chat/ 前缀，而不是 ollama/。

使用本地模型启动
export OLLAMA_API_BASE=http://127.0.0.1:11434
ollama pull devstral:24b
OLLAMA_CONTEXT_LENGTH=8192 ollama serve

# Dans un autre terminal, à la racine du projet
aider --model ollama_chat/devstral:24b

代价最大的陷阱是上下文窗口。Ollama 默认使用 2,000 个 token 的上下文，这对编程智能体来说非常小，而且关键的是，它会悄无声息地丢弃超出窗口的内容。因此，您可能在不知情的情况下，与一个只收到您文件开头部分的模型对话。Aider 可以缓解这个问题：默认情况下，它会自行将 Ollama 的上下文窗口设为每次请求的长度，再加上供回复使用的 8,000 个 token。如果您更希望使用固定大小，就需要通过模型设置文件进行配置，而不是使用主配置文件。

文件 .aider.model.settings.yml（固定上下文大小）
- name: ollama_chat/devstral:24b
  extra_params:
    num_ctx: 32768
!
教程中常见的错误
直接在 .aider.conf.yml 中写入 num_ctx 并不能设置 Ollama 的上下文窗口：这个参数属于模型设置（extra_params）。请使用 /tokens 命令核查实际使用的值，该命令会详细列出发送的内容。

上下文会占用内存：KV 缓存随上下文窗口增大而增长，而一个 240 亿参数的模型在 Q4 量化下已经占用约 14 GB，在 16 GB 显卡上留下的余量很少。上下文窗口指南和 KV 缓存量化指南提供了大致的规模参考。

#Aider 该选哪个本地模型

Aider 的表现取决于驱动它的模型，难点有两个：模型既要对代码进行推理，又要遵守严格的编辑格式。不遵守这一格式的模型会生成工具无法应用的修改。Aider 的公开排行榜基于六种编程语言的 225 道 Exercism 练习，衡量的正是这两方面的能力；榜单前列由托管的超大模型占据，能在个人计算机上运行的模型排名则明显靠后。在期待云端级别的结果之前，请先查看这一排行榜。

对于本地工作站，Mistral AI 和 All Hands AI 发布的 Devstral 24B 是一个合理的起点：它专为编程智能体设计，在 Ollama 模型库中的大小为 14 GB，并宣称提供 128,000 个 token 的上下文窗口。如果 GPU 显存为 12 GB 或更少，就需要改用更小的模型，并接受更多格式错误。《最佳本地 LLM 用于编程》指南比较了当前的候选模型；本指南不固定任何排名，因为排名变化太快。

根据自己的机器选择（内存需求参考：Q4 量化后的模型权重，不含上下文占用）
可用内存实际可运行的模型规模可以期待 Aider 做到什么
8至12 GB70至140亿（5至9 GB）小范围的定向修改，一次处理一个文件；格式错误频繁
16 GB140至240亿（9至14 GB）在较短的上下文下修改两三个文件
24GB及以上240至320亿（14至20 GB）日常使用可接受，上下文长度达到16,000个token或以上
托管模型超大规模模型可靠性更高；仅用于非保密代码仓库

#首次变更：从提示词到提交

  1. 01
    添加正确的文件
    启动 aider 时，传入需要修改的文件，例如 aider src/api.py src/models.py。添加的文件就是它可以编辑的文件；仓库的其余内容则通过仓库映射供它了解。
  2. 02
    精确描述该变更
    请写出完整的需求：「添加一个 GET /users/:id 端点，返回用户信息；若该用户不存在，则返回 404 错误。」模糊的需求会产生含糊的代码差异。
  3. 03
    检查 diff
    Aider 会显示修改并应用它们。继续操作前，请用 /diff 查看这些修改：要拒绝修改，就应在此时提出，而不是再追加三次请求之后。
  4. 04
    检查提交版本
    每次编辑都会保存，并附带一条描述性消息。如果结果不佳，/undo 会撤销 Aider 所做的最后一次提交。
  5. 05
    按小步骤依次推进
    接下来，逐步要求添加测试、处理边界情况和记录日志，每次只进行一步。小步推进能保持上下文简短，让代码差异清晰可读。

#重要的聊天命令

Aider 提供数十条以斜杠开头的命令；掌握其中几条就足以开展工作。一般规则是：未添加到聊天中的内容无法修改，但仓库图谱能让模型知道其他文件的存在。

/add et /drop
添加或移除聊天中的文件。移除已无用的文件可释放上下文，这对于本地模型尤其重要。
/read-only
添加一个仅供参考的文件：模型可以读取它，但不能编辑。适用于规范文件或接口契约。
/ask, /code, /architect
切换聊天模式，可仅对一条消息生效，也可通过 /chat-mode 持续生效。
/run et /test
/run lance une commande shell et peut en verser la sortie dans le chat ; /test lance la commande de test et ajoute la sortie au chat si elle échoue, ce qui déclenche une correction.
/diff et /undo
/diff montre les changements depuis votre dernier message ; /undo annule le dernier commit s'il a été fait par Aider.
/tokens
显示当前上下文使用的 token 数量：要理解本地模型为什么会“忘记”，就应养成查看这一数值的习惯。
/map
显示发送给模型的仓库结构映射。

#聊天模式：code、ask、architect

Aider 有四种聊天模式。code 模式是默认模式，会修改您的文件。ask 模式只讨论代码，绝不会修改代码。architect 模式让两个模型协作：先由架构模型提出解决方案，再由编辑模型将方案转化为具体的文件修改。help 模式回答有关 Aider 本身的问题。不存在名为“paired”的中间模式；能力更强的模型与速度更快的模型如何搭配，可通过 --model 和 --editor-model 选项设置。

文档推荐交替使用 /ask 和 /code：先在 ask 模式下讨论方案，再切换到 code 模式，只需输入一句「go ahead」即可执行商定的计划。这相当于使用单个模型的、更流畅的 architect 模式。对于中等规模的本地模型，这通常是最佳折中方案：既避免将两个模型加载到内存中，又能掌控计划。

architect 模式适用于推理能力强但代码编辑能力较差的模型。该模式需要两次请求，而不是一次：只有在 code 模式经常生成无效的 diff 时才启用。

#Git，你的安全网

Aider 借助 Git，让每次错误都可以撤销。每次编辑时，它都会提交更改，并附上描述性的提交消息；消息由弱模型根据 diff 和对话生成，采用 Conventional Commits（约定式提交）的风格。在修改包含尚未提交的更改的文件之前，它会先提交已有的更改：您的工作与 AI 的修改会在历史记录中保持分开。它创建的提交会在作者名中标注“(aider)”，便于查找。

随之而来的是大量小提交。良好的做法是让 Aider 在专用分支上工作，审阅后先将这些提交压缩合并，再合并分支。有两个选项值得了解：--no-auto-commits 禁用自动提交，--git-commit-verify 重新启用 pre-commit 钩子，而该工具默认通过 --no-verify 绕过这些钩子。如果您的团队依赖这些钩子，这个选项就至关重要。

在可丢弃的分支上工作
git switch -c ai/endpoint-users
aider src/api.py
# ... relire, tester, puis :
git rebase -i main

#在循环中运行您的测试

这项设置让 Aider 从代码生成器变成能够自行纠错的工具。启用 --test-cmd 和 --auto-test 后，Aider 会在每次修改后运行您的测试套件；如果命令返回非零退出码，它会读取输出并尝试修复。使用 --lint-cmd 进行 lint 检查也是同样的原理，而且 Aider 默认会对它编辑的文件进行 lint 检查。

自动测试循环
aider --test-cmd "pytest -x -q" --auto-test --lint-cmd "ruff check"

有两点需要注意。测试命令必须执行得快：使用本地模型时，每轮循环仅生成就已经需要几十秒。此外，命令必须显示错误，并以非零退出码退出，否则 Aider 会以为一切正常。

#使用本地模型时哪些环节会失败，以及如何绕过这些问题

编辑格式错误
模型返回了工具无法应用的修改。请换用更大的模型，或测试 architect 模式。Aider 文档专门用一个故障排查页面介绍这些错误。
上下文丢失
症状：模型忽略了您刚添加的文件。可能原因：上下文窗口过小或上下文已饱和。解决方案：/tokens，/drop 无用文件，然后增大上下文窗口。
文件过长
一个包含数千行的文件会占满本地模型的上下文窗口。请将其拆分，或要求只修改某个具体函数。
模糊请求
“改进这段代码”会产生不可预测的代码改动。请明确指出文件、函数和预期行为。
令牌限制错误
Aider 会在模型超出自身限制时发出提示，并建议采取相应措施：要求更小范围的修改、拆分文件或更换模型。
→
隐私：哪些内容实际会传出本机
使用 Ollama 本地部署时，代码将保留在本地设备上。但请注意检查 Aider 的配置：该工具提供可选的使用统计收集功能，若模型错误配置为托管模式，可能会将代码片段发送至第三方。网站的隐私检查清单详细列出了需要关注的要点。

#Aider 还是编辑器中的智能体

Aider 适合在终端中工作、希望保持 Git 历史整洁的用户。如果您更喜欢在 VS Code 中工作，Cline 提供类似的体验，每一步都需确认；如果您想要更自主的终端智能体，可以考虑 OpenCode。选择的关键不在于模型质量——模型质量是相同的——而在于您希望在哪里审阅代码差异。

Aider 与其他本地编程智能体的对比
标准Aider编辑器中的智能体（Cline）终端智能体（OpenCode）
界面终端VS Code终端
Git历史记录每次编辑后自动提交由用户自行承担由用户自行承担
代码仓库上下文代码仓库结构图，手动添加的文件借助工具探索借助工具探索
理想场景有针对性且经过审查的修改需要视觉验证的多步骤任务在终端中执行耗时较长的任务
FAQ
Aider 真的能配合本地模型运行吗？+
是的，Aider 的文档说明了如何连接 Ollama。质量主要取决于模型：240 亿至 320 亿参数的模型可用于日常工作，低于这个范围时，编辑格式错误会明显增多。对于机密代码，这是常见的折中方案：以略低的可靠性换取数据完全不外传。
通过 Ollama 使用 Aider 时，应选择哪个模型？+
Devstral 24B 是一个合理的起点：它专为代码智能体设计，大小为 14 GB。如果可用内存更少，请选择更小的代码模型，并接受更多错误。Aider 的公开排行榜显示了哪些模型能很好地遵循编辑格式；请参考该排行榜，而不是一份固定不变的排名。
为什么 Aider 似乎忘记了我的文件？+
Ollama 默认使用 2000 个 token 的上下文窗口，并静默丢弃超出窗口的内容。Aider 通常会将该窗口大小设置为请求大小加上 8000 个 token，但上下文仍可能被占满。使用 /tokens 测量占用情况，使用 /drop 释放空间，并在模型设置中设定 num_ctx。
如何撤销Aider的修改？+
输入 /undo：如果最后一次提交是由 Aider 完成的，该命令会撤销这次提交。若要回退到更早的状态，请按常规方式使用 Git，执行 git reset 或 git revert。最稳妥的做法仍是在专用分支上工作，如果结果不合意，可以将该分支整个删除。
是否需要禁用自动提交？+
不一定。自动提交让每次变更都可以撤销，并在历史记录中清晰可查。缺点是会产生大量小提交，可以在合并前通过 rebase 或 squash 处理。使用 --no-auto-commits 会失去这层保障，因此只有在团队强制要求手动提交时才应使用该选项。
Aider 能自动运行我的测试吗？+
是的：使用 --test-cmd 和 --auto-test 选项，每次修改后都会执行命令，并在命令失败时尝试修复。请准备一个快速命令，用于显示错误并返回非零退出码。对于本地模型，每次修复循环会额外增加数十秒的耗时。
这份指南对您有帮助吗？

有反馈、发现了错误，或想补充说明？请告诉我们，让这份指南对每个人都更有帮助。