前置条件
- 1已安装 Python 3.9+（推荐 3.10+）或 Homebrew / Docker 环境
- 2已注册至少一家 AI 模型供应商账号（OpenAI / Anthropic / DeepSeek 等）
- 3已安装 Git（Aider 与 Git 仓库深度集成）
Aider 终端 AI 编程助手使用指南
Aider 是由 Paul Gauthier 开发的开源终端 AI 结对编程（pair programming）工具（Apache-2.0 协议），GitHub 已获数万 Star。它和 Git 深度绑定：你说自然语言需求，AI 直接修改本地 git 仓库里的多个文件，每次改动自动产生一个独立 commit，坏了就 /undo 回滚。
Aider 本身就是「终端工具」，用 aider 命令启动；本教程聚焦于如何安装它，并接入合适的 AI 模型供应商（OpenAI / Anthropic / DeepSeek / Ollama / OpenRouter 等皆可）。
前置准备
1. 获取 AI 模型供应商 API Key
Aider 不绑定单一模型，可接入几乎所有主流 LLM：
| 供应商 | 环境变量 | 获取地址 |
|---|---|---|
| Anthropic（推荐 Claude） | ANTHROPIC_API_KEY | console.anthropic.com |
| OpenAI | OPENAI_API_KEY | platform.openai.com/api-keys |
| DeepSeek | DEEPSEEK_API_KEY | platform.deepseek.com |
| OpenRouter（聚合通道） | OPENROUTER_API_KEY | openrouter.ai |
| Ollama（本地模型） | 无需 Key | ollama.com |
警告
⚠️ 务必将 .env 加入 .gitignore，不要把 API Key 提交到公开仓库。
2. 系统要求
| 依赖 | 版本要求 | 检查命令 |
|---|---|---|
| Python | ≥ 3.9（推荐 3.10+） | python --version |
| Git | 任意版本 | git --version |
| LLM API Key | 任选一家供应商 | — |
支持的系统： macOS、Linux、Windows（原生支持，无需 WSL）。
分步安装指南
方式一：pip 安装（推荐，跨平台）
1# 直接安装
2python -m pip install -U --upgrade-strategy only-if-needed aider-chat
3
4# 验证安装
5aider --version方式二：pipx 安装（隔离环境，不污染全局）
1# 安装 pipx（若未装）
2python -m pip install --user pipx
3
4# 用 pipx 隔离安装
5pipx install aider-chat方式三：uv 安装（最快）
1uv tool install aider-chat@latest方式四：Homebrew（macOS）
1brew install aider方式五：Docker 运行
1# 在当前目录启动（挂载当前工作目录到 /app）
2docker run -it --rm \
3 -v $(pwd):/app \
4 -w /app \
5 -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
6 paulgauthier/aider方式六：源码安装（开发者）
1git clone https://github.com/Aider-AI/aider
2cd aider
3pip install -e .配置 API Key 与模型
Aider 提供三种等效的配置方式，可按习惯选一种或组合使用。
方法一：环境变量（推荐）
1# Linux / macOS
2export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"
3export OPENAI_API_KEY="sk-your-openai-key-here"
4
5# 持久化（zsh）
6echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"' >> ~/.zshrc
7source ~/.zshrc1# Windows PowerShell 临时设置
2$env:ANTHROPIC_API_KEY = "sk-ant-api03-your-key-here"
3
4# 永久设置
5[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-key", "User")方法二：.env 文件（持久化）
在 ~/.aider/.env 或项目根目录创建 .env：
1# ~/.aider/.env
2ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
3OPENAI_API_KEY=sk-your-openai-key-here
4DEEPSEEK_API_KEY=sk-your-deepseek-key-here警告
⚠️ 重要：只有 OpenAI 和 Anthropic 的 Key 允许写在 .aider.conf.yml 里；其他所有供应商的 Key 必须 用 .env 文件，否则不会被加载。
方法三：命令行参数
1# 使用 Claude Sonnet
2aider --model claude-sonnet-4-6 --api-key anthropic=sk-ant-api03-your-key
3
4# 使用 GPT-4o
5aider --model gpt-4o --api-key openai=sk-your-openai-key方法四：自定义 OpenAI 兼容端点
Aider 兼容任何 OpenAI 格式端点（如火山方舟 ModelArk、自建代理等）：
1# 设置自定义端点
2export OPENAI_API_BASE="https://ark.cn-beijing.volces.com/api/v3"
3export OPENAI_API_KEY="your-modelark-api-key-here"
4
5# 用模型 ID 启动
6aider --model openai/deepseek-v3.2配置文件：.aider.conf.yml
Aider 的 YAML 配置文件按以下顺序查找，后加载的优先级更高：
- 你的主目录（
~/.aider.conf.yml） - Git 仓库根目录（
.aider.conf.yml） - 当前目录（
.aider.conf.yml） - 或用
--config <filename>指定单一配置
~/.aider.conf.yml 示例：
1# 默认模型
2model: claude-sonnet-4-6
3
4# 自动提交每次改动
5auto-commits: true
6
7# 显示 diff
8show-diffs: true
9
10# 终端深色模式
11dark-mode: true
12
13# 显示 token 成本
14show-cost: true
15
16# 模型别名，便于快速切换
17model-aliases:
18 cheap: openai/glm-4.7
19 balanced: openai/deepseek-v3.2
20 smart: openai/kimi-k2
21 code: openai/seed-code使用别名快速切模型：
1aider --model cheap # 使用 GLM-4.7
2aider --model smart # 使用 Kimi-K2提示
💡 所有命令行开关都有对应的 AIDER_XXX 环境变量与 .aider.conf.yml 选项，三种方式等价。
快速开始
1. 进入 Git 仓库
Aider 必须在 Git 仓库内运行（没有就新建）：
1cd /path/to/your/project
2git init # 若尚未初始化2. 启动 Aider
1# 在当前目录启动，使用默认模型
2aider
3
4# 指定文件加入对话
5aider src/main.rs src/lib.rs
6
7# 指定模型
8aider --model claude-sonnet-4-6
9
10# Architect 模式（先规划再实施）
11aider --architect3. 会话内交互
1$ aider --model claude-sonnet-4-6
2
3Aider v0.77.0
4Main model: claude-sonnet-4-6
5Git repo: .git with 15 files
6
7> /add src/routes/users.js src/models/User.js
8Added src/routes/users.js to the chat
9Added src/models/User.js to the chat
10
11> Add password reset functionality with email verification
12
13# Aider 会：
14# 1. 分析两个文件
15# 2. 生成代码改动
16# 3. 展示 diff
17# 4. 自动应用并 commit
18# 5. 显示本次成本（通常 $0.001 - 0.01）4. 常用斜杠命令
| 命令 | 作用 |
|---|---|
/add <file> | 将文件加入对话上下文 |
/drop <file> | 移除文件 |
/ask <question> | 只提问，不改代码 |
/code <request> | 请求代码改动 |
/architect | 切到 Architect 模式（先规划） |
/diff | 显示待提交的改动 |
/commit | 用 AI 生成的信息提交 |
/undo | 撤销上一次改动 |
/help | 查看所有命令 |
/models | 列出可用模型 |
/list-models openai/ | 按 prefix 过滤模型列表 |
核心功能与使用模式
三种对话模式
| 模式 | 行为 | 适合场景 |
|---|---|---|
| Code（默认） | 边聊边改代码 | 日常开发、bug 修复 |
| Ask | 只问答，不修改任何文件 | 代码理解、概念澄清 |
| Architect | 先用一模型规划，再用另一模型实施 | 复杂任务、大型重构 |
切换方式：会话中输入 /ask、/code、/architect，或启动时加 --architect。
Git 深度集成
- 自动 commit：每次代码改动自动产生有意义的 commit 信息
- 便于回滚：
/undo直接回退上一次 AI 改动 - 尊重 .gitignore：被忽略的文件不会进入上下文
- repo map：自动构建仓库结构图，让 AI 理解文件间依赖
多文件协同编辑
通过 /add 把多个相关文件加入上下文，Aider 会理解它们之间的关系并同步修改。支持 Python / JavaScript / TypeScript / Go / Rust / Java 等 100+ 编程语言。
成本追踪
每次交互后显示：
1Tokens: 1,234 sent, 567 received
2Cost: $0.0004 this message, $0.0023 session total配置文件与项目上下文
项目级配置
在项目根目录放置 .aider.conf.yml，可覆盖全局配置：
1model: openai/deepseek-v3.2
2read:
3 - README.md
4 - CONVENTIONS.md
5context:
6 - "Always validate shell commands before execution"
7 - "Use POSIX-compliant syntax"read 字段指定的文件会自动作为只读上下文加载，适合放项目规范、架构说明等。
可读取文件清单
.aider.conf.yml：选项配置.env：API Key 与环境变量read字段指定的文件：只读上下文
场景应用示例
场景一：多文件功能开发
1你：> /add src/routes/users.js src/models/User.js
2 Add password reset functionality with email verification
3
4Aider 会：
51. 分析两个文件的现有结构
62. 生成路由、模型、邮件模板的协同改动
73. 展示 diff 并自动 commit场景二：Bug 定位与修复
1你：> 这个函数运行时抛出 KeyError，请帮我找出问题并修复
2 [粘贴报错堆栈]
3
4Aider 会：
51. 读取相关文件
62. 定位问题根因
73. 提供修复代码并应用
84. 补充防御性代码避免类似问题场景三：成本敏感的批量重构
1你：> 将所有 .js 文件中的 var 替换为 const
2
3Aider 会（用便宜模型）：
41. 用 repo map 定位所有 .js 文件
52. 用 --model cheap（如 GLM-4.7）执行批量替换
63. 每个文件一个 commit，便于回滚
74. 全程成本极低最佳实践
安全建议
.env加入.gitignore：永远不要把 API Key 提交到仓库- 审查 AI 输出：生产代码上线前务必人工审查 diff
- Architect 模式做复杂任务：先看规划再实施，避免方向跑偏
- 善用
/undo：改坏了就回滚，别怕让 AI 动手
性能与成本优化
- 按需选模型：简单问答用
cheap别名（GLM-4.7），复杂推理用 Claude Sonnet /add精准控制上下文：只加相关文件，减少 Token 消耗- 用 repo map：让 AI 理解全局结构，而不必读所有文件
- 批量任务用便宜模型：如
--model openai/glm-4.7跑简单替换
故障排查
| 问题 | 解决方案 |
|---|---|
| 401 Unauthorized | Key 过期 / 含空格，重新复制并去除首尾空格 |
| 模型不存在 | 用 aider --list-models <provider>/ 查可用模型 |
| 改动未提交 | 确认 auto-commits: true，或手动 /commit |
.aider.conf.yml 中其他供应商 Key 不生效 | 改用 .env 文件，YAML 只支持 OpenAI / Anthropic |
aider 命令找不到 | 检查 Python Scripts 目录是否在 PATH 中 |
| 自定义端点 404 | 确认 OPENAI_API_BASE 是否需要带 /v1 或 /api/v3 |
1# 列出某供应商的所有模型
2aider --list-models openai/
3
4# 验证配置
5aider --model claude-sonnet-4-6 --yes-always "say hello"扩展与进阶
官方资源
- 🌐 官网：aider.chat
- 📖 配置文档：aider.chat/docs/config.html
- 💻 GitHub 仓库：github.com/Aider-AI/aider
- 📋 完整选项示例：sample.aider.conf.yml
- 📦 PyPI 包：
aider-chat
进阶玩法
- Reasoning 模型：用
--reasoning-effort控制 o1/o3 等推理模型的思考深度 - Prompt 缓存：开启
cache-prompts: true，命中后输入成本大幅降低 - 模型别名：在
.aider.conf.yml配置model-aliases，团队统一模型命名 - 弱模型分离：用
--weak-model指定摘要 / commit 信息生成所用的小模型，降低成本 - Editor 模型：用
--editor-model单独指定执行编辑任务的模型
总结
Aider 把「你说需求、AI 直接改代码」的结对编程范式带进终端，并和 Git 深度绑定：每次改动一个独立 commit，坏了就 /undo 回滚，让你敢把真实项目交给 AI 编辑。它模型无关，可接入 OpenAI、Anthropic、DeepSeek、Ollama、OpenRouter 等几乎所有主流 LLM。
无论是多文件协同开发、Bug 定位修复，还是成本敏感的批量重构，Aider 都能成为你终端里的得力 AI 结对编程伙伴。立即安装，体验「住在终端里的 AI pair programmer」吧！
常见问题
QAider 和 GitHub Copilot 有什么区别？
Copilot 是 IDE 内的 Tab 补全，你仍是主要敲键盘的人；Aider 是你说需求、AI 直接修改 git 仓库里的多个文件，每次改动一个独立 commit，可随时 `/undo` 回滚。
QAider 本身包含 AI 模型吗？
不包含。Aider 是工具壳，需接入外部 LLM。支持 OpenAI、Anthropic、DeepSeek、Ollama、OpenRouter 等几乎所有主流供应商，可按需切换。
Q没有 API Key 能用吗？
可以。Aider 内置 OpenRouter 接入能力，首次启动时会引导你使用 OpenRouter 的免费 / 付费通道，无需提前准备任何一家供应商的 Key。
QAPI Key 写在哪里最安全？
推荐用 `.env` 文件（放入 `~/.aider/` 或项目根目录，并加入 `.gitignore`）。注意：`.aider.conf.yml` 只允许写 OpenAI 和 Anthropic 的 Key，其他供应商必须用 `.env`。
Q如何切换不同模型？
用 `aider --model <provider/model>` 切换，如 `aider --model openai/gpt-4o`；也可在 `.aider.conf.yml` 中配置 `model-aliases` 用 `aider --model cheap` 等别名快速切换。
QArchitect 模式和普通模式有什么不同？
Architect 模式先用一个模型做规划（不写代码），再用另一个模型实施修改，适合复杂任务；普通 Code 模式直接边聊边改。