Aider 命令速查表 - 开源终端 AI 结对编程全参数
Aider 是开源 Apache 2.0 终端 AI 结对编程工具，面向想在本机编辑代码、让 AI 实际修改文件并自动 git 提交的开发者，支持 100+ 模型且不锁定供应商。它的特点是每次改动自动提交 git，配合 --test-cmd/--lint-cmd 形成"AI 改一行、坏了 /undo 回退"的安全循环；本表帮你掌握文件上下文管理、聊天模式切换与架构模式等核心命令。
典型使用场景
面向希望在本地仓库里做可控改动的开发者，尤其是重视「随时能回退」的团队。Aider 的核心差异点是 git 集成：每次改动自动提交，配合 --test-cmd 和 --lint-cmd 形成「改—测—提交」的闭环，一行改坏用 /undo 就能回来。本表覆盖几条主线：模型与推理配置（--architect 双模型分工、--weak-model 用于廉价子任务、--map-tokens 控制仓库地图开销）；文件与上下文管理（/add、/drop、/read-only 控制哪些文件可编辑）；四种聊天模式（/code、/ask、/architect、/chat-mode）；以及把一次会话存成可复现脚本的 /save 与 /load。
安装与启动 5
pip install aider-chataideraider src/main.py tests/test_main.pyaider --model claude-sonnet-4-6export ANTHROPIC_API_KEY="sk-ant-..."模型与推理 7
aider --model ollama/codellamaaider --architect --model claude-opus --editor-model claude-sonnetaider --weak-model gpt-4o-miniaider --reasoning-effort highaider /think-tokens 4096/model/models文件与上下文 9
/add src/auth/*.py/drop tests/auth/test_login.py/read-only docs/api-spec.md/ls/reset/clearaider --map-tokens 2048aider --show-repo-map/map-refresh聊天模式 5
/code/ask/architect/chat-mode/contextGit 与运行 10
/git status/commit "实现 JWT 认证"/undo/diff/run pytest tests//test/lintaider --auto-commitsaider --lint-cmd "ruff check"aider --test-cmd "pytest"会话与工具 11
/voice/web https://docs.site/paste/copy/copy-context/save /path/script.md/load /path/script.md/settings/report/help/exit高级用法 6
aider --message "/ask 这个 bug 在哪"aider --edit-format wholeaider --cache-prompts/multiline-mode/vim/editor参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
--model <m> | 指定主模型 | aider --model claude-sonnet-4-6 |
--editor-model <m> | 指定编辑模型，与 --architect 搭配 | aider --architect --model claude-opus --editor-model claude-sonnet |
--weak-model <m> | 指定廉价弱模型，用于子任务 | aider --weak-model gpt-4o-mini |
--architect | 架构模式：规划模型出方案、编辑模型出 diff | aider --architect |
--reasoning-effort <lvl> | 设置推理强度（模型支持时） | aider --reasoning-effort high |
/think-tokens <n> | 设置每轮思考 token 预算 | /think-tokens 4096 |
--map-tokens <n> | 设置仓库地图 token 预算 | aider --map-tokens 2048 |
--show-repo-map | 打印当前仓库地图后退出 | aider --show-repo-map |
--auto-commits | 每次改动自动 git 提交 | aider --auto-commits |
--test-cmd <cmd> | 改动后自动运行测试命令 | aider --test-cmd "pytest" |
--lint-cmd <cmd> | 改动后自动运行 lint | aider --lint-cmd "ruff check" |
--edit-format whole | 整文件编辑，适合小文件 | aider --edit-format whole |
--message / -m <s> | 非交互发送单条消息 | aider --message "/ask 这个 bug 在哪" |
--cache-prompts | 启用提示缓存降本提速 | aider --cache-prompts |
/add / /drop | 把文件加入会话 / 移出以省上下文 | /add src/auth/*.py |
/read-only <f> | 只读参考，禁止编辑 | /read-only docs/api-spec.md |
/ask / /code / /architect | 问答 / 改代码 / 双模型模式 | /ask 这个 bug 在哪 |
/run <cmd> 与 /test / /lint | 运行 shell 命令并把输出喂回会话 | /run pytest tests/ |
/commit / /undo / /diff | 提交脏改动 / 撤销上次提交 / 查看最近 diff | /undo |
/save / /load <file> | 会话存为可复现脚本 / 从脚本加载运行 | /save /path/script.md |
易错点与避坑指南
现象会话越聊越慢、变贵，而且模型开始改到不相关的文件
原因会话里堆积了过多文件，仓库地图与文件内容一起挤占了上下文预算。
处置每任务只保留 3-5 个相关文件，用完就 /drop；必要时用 --map-tokens 压缩仓库地图预算。
现象Aider 改了不该动的文件，或者把只读文档也重写了
原因文件被 /add 进了可编辑集合；只读文件应当用 /read-only 而不是 /add。
处置把参考资料从 /add 换成 /read-only，用 /ls 核对当前会话里到底哪些文件可编辑。
现象复杂重构质量不稳定，方案做到一半就跑偏
原因单模型同时负责设计和编辑，容易在细节里丢失整体意图。
处置用 /architect 切双模型：规划模型出方案，编辑模型只负责落地 diff。
现象改完之后测试挂了，却不知道是哪一次改动引入的
原因没有把测试接入闭环，改动与验证分离。
处置启动时带 --test-cmd "pytest" --lint-cmd "ruff check"，让每次提交前都自动跑一遍。
现象一次大改动后想整体回退，undo 不掉
原因/undo 只撤销 Aider 自己最近的那次 git 提交，更早的改动需要手动处理。
处置重要任务先开独立分支或保持 --auto-commits 开启，用 git log 定位提交后按需回退。
现象中文提问得到的是泛泛的英文回答，或答案与项目实际结构不符
原因仓库地图 token 预算太小，模型没拿到足够的结构信息。
处置先用 aider --show-repo-map 看看地图内容是否覆盖了相关目录，再调大 --map-tokens。
现象报告问题时说不清配置，把 key 一起贴了出去
原因/report 会预填诊断信息，直接把内容发出去有泄露风险。
处置提交前用 /settings 打印生效配置自查，必要时手工删掉 /copy-context 输出中的密钥行再外发。
排障路径
1确认会话里到底纳入了哪些文件
/ls输出应只包含当前任务需要的文件；发现多余文件用 /drop 移出。
2检查仓库地图是否覆盖到目标目录
aider --show-repo-map打印后退出，用于确认 token 预算是否够用；不够就调大 --map-tokens。
3在动手前先只问不动
/ask 这个 bug 在哪问答模式不改文件，适合先定位问题再决定改法。
4查看最近一次改动的完整 diff
/diff确认改动范围是否符合预期，异常立即 /undo 回到上一个提交。
5让测试输出回到会话作为依据
/run pytest tests/命令输出会喂给模型，比人肉复制报错更快也更完整。
6打印当前生效配置并核对模型设置
/settings重点核对主模型、编辑模型、test/lint 命令与自动提交开关是否符合预期。
命令示例
先只读问答定位问题，再决定要不要让它改
/read-only docs/api-spec.md
/add src/main.py
/ask 这个接口 500 的可能原因是什么/ask 模式只讨论不落盘。把规格文档设为只读、代码加入会话，让它在不碰文件的前提下给出判断，是最安全的排查起点——确认方向对了再切 /code。
改动之后立刻验证，失败就整批撤销
/code
/run pytest tests/
/diff
/undoAider 的每次改动都会落成 git 提交，/undo 回退的是它自己刚做的提交。测试失败时先看 /diff 确认改了哪些文件，再用 /undo 整体回退，比手工逐个撤销干净。
用架构模式先规划，落地交给编辑模型
/architect
把限流拆成中间件和配置两层，先给方案不要改代码
/code大改动直接让主模型写代码容易跑偏。/architect 让规划模型先输出结构，你审完再 /code 落地，方案阶段的错误成本最低。
会话太长时 drop 测试文件，保留生产代码
/add src/auth/*.py
/drop tests/auth/test_login.py
/ls上下文有限，测试文件常常占了相当大的比例却对生成补丁帮助有限。/drop 只是移出会话（文件不变），/ls 用来确认当前到底装了什么，避免模型「以为」看过某个文件。
一次性提问，不进入交互界面
aider --message "/ask 这个 bug 在哪"适合在脚本或 CI 里跑一次「让 AI 解释这段代码」。配合 /add 先把文件喂进去，-m 会在处理完这条消息后退出，不会挂在终端上等输入。
常见坑与注意事项
- 工作区不干净时启动 Aider，模型生成的提交会把你的半成品改动一起卷进去；启动前先 /git status 或在干净分支上跑。
- --auto-commits 会在每次改动后自动提交，CI 环境里如果分支受保护会在中途失败，留下半截提交难以追溯；首次使用建议先不开。
- export ANTHROPIC_API_KEY="sk-..." 写进 shell 历史长期留在磁盘上；用 read -s 或 .env + 环境变量管理，别把密钥留在历史记录里。
- 把 .env、密钥或含 token 的配置文件 /add 进会话，这些内容会进入模型上下文并发往远端 API；只读参考用 /read-only 也仍然会发送内容。
- /undo 只能撤销 Aider 自己创建的提交：你在会话之外手工 git commit 的改动它不动，用错时机反而丢自己的代码。
- 会话没 /exit 就直接关终端，未提交的编辑不会自动收尾：下次打开会看到残留改动，先 /diff 确认再决定提交还是回退。
- /web 抓取的网页文本进入上下文后可能被模型当作指令执行（提示注入）；对不可信的 URL 不要用 /web 抓进需要改代码的会话。
提示
- 每次改动自动 git 提交是 Aider 的杀手锏：配合
--test-cmd和--lint-cmd，改坏了一行/undo就能回退。 - 复杂重构用
/architect双模型：规划模型出方案、编辑模型出 diff，质量比单模型全程更高且通常更省钱。 - 只加相关文件（每任务 3-5 个），用完
/drop；小会话更快、更便宜、编辑更精准。 - 先用
/ask让 Aider 规划再编辑，复杂任务先想清楚能少走弯路。
常见问题
/code 和 /ask 模式该怎么选？
/ask 只讨论不修改文件，适合先让 AI 解释代码、评估方案；/code 则会直接改文件，是默认模式。接手陌生代码库时先用 /ask 问清楚再切 /code 动手，能避免它在你还没确认方向时就开始大范围改动。改错了可以用 /undo 撤销 Aider 上一次做的 git 提交。
为什么改之前要先把文件 /add 进会话？
Aider 只编辑你显式加入会话的文件，/add src/auth/*.py 把它加进来成为可编辑对象；/read-only docs/api-spec.md 则只作为参考资料引入，禁止修改。这是刻意的设计，防止它顺手改到你没打算动的文件。会话太大时用 /drop 把暂时不用的文件移出，节省上下文。
架构模式（--architect）解决什么问题？
它用两个模型分工：规划模型先产出方案，编辑模型再按方案改代码。相比单模型直接改，好处是大改动前会先有一份可审阅的设计，能显著减少「改了很多但方向错了」的返工。代价是成本和耗时翻倍，适合跨模块重构，日常小改用默认模式即可。
怎样在不污染主分支的前提下让 Aider 提交代码？
Aider 本身就是围绕 git 设计的，每次改动会自动提交，随时可以 /undo 回退。若要跑测试验证，用 /run pytest tests/ 让它执行命令并把输出喂回会话，比你手动粘贴报错更快。想先看改了什么再决定，用 /diff 显示最近一次改动的 diff。
怎么让 Aider 用本地模型？
模型名带 ollama/ 前缀即可，例如 aider --model ollama/codellama 会通过 Ollama 调用本地模型，配合提前启动 ollama serve 使用。本地模型同样支持架构模式：--architect 指定规划模型，--editor-model 指定编辑模型，两者可以都是本地模型，只是复杂任务的规划质量会下降。
由 巧匠 维护
公开更新于 2026年8月5日，内容持续校对官方文档。