Aider：终端里的 Git 仓库结对编程 AI 助手｜部署与使用全指南

项目仓库： https://github.com/Aider-AI/aider

开源协议：Apache 2.0 · 语言：Python · 交付形态：终端命令行工具 aider，另有 Docker 镜像 · 模型接入：OpenAI、Anthropic、DeepSeek、OpenRouter、Gemini、Groq、OpenAI 兼容端点、本地 Ollama · 无独立 Web 服务端口 · 官方文档：aider.chat/docs

非官方声明：Aider 是开源社区项目，与 OpenAI、Anthropic、Google、DeepSeek 等模型厂商不存在隶属、授权或合作关系；文章中出现的模型名称仅用于说明兼容目标。模型 API Key、订阅账号与服务条款由对应厂商约束，使用者须自行确认项目代码外发合规边界。

1 项目简介

Aider 是一款运行在终端里的 AI 结对编程助手：在 Git 仓库目录中启动 aider，把需要修改的文件加入聊天，用自然语言描述需求，Aider 直接编辑这些文件，并在每条消息后按 Conventional Commits 规范自动提交到 Git，提交信息附带 (aider) 署名。它内置仓库地图（repo map）感知整个代码库结构，支持 100 多种编程语言，可配合 IDE 的 watch 模式、图片与网页上下文、语音输入、自动 lint 与测试流程使用。

1.1 核心信息一览

1.2 适用场景

• 习惯终端与 Git 工作流的开发者，希望 AI 在真实仓库里边对话边改代码，每步改动都有可回退的 Git 提交。
• 多文件重构、补测试、修 Bug、写文档等需要模型先理解仓库结构再动手的任务。
• 在服务器、SSH 会话、容器等无图形界面环境中完成结对编程。
• 混合使用云端强模型与本地 Ollama 模型：敏感代码走本地，通用任务走云端。
• 通过 IDE watch 模式与现有编辑器配合：在编辑器里写 AI 注释触发 Aider 修改，无需切换应用。

1.3 能力边界（官方口径）

• 官方 README 自述为 “AI pair programming in your terminal”：在聊天中加入文件、让模型修改、按消息自动提交；自动生成仓库地图，支持 100+ 语言；可向聊天添加图片与网页，支持语音输入、lint 与测试。
• 项目本身不提供模型、API Key 与模型权重；模型能力、上下文窗口、工具调用与计费由所选提供者决定。官方推荐模型与完整兼容清单见 llms 文档 与 排行榜。
• 自动提交依赖 Git 仓库；非 Git 目录可通过 --no-git 关闭 Git 集成，但将失去自动提交与历史回退能力。
• Aider 只负责把模型返回的差异落到文件并执行 Git 操作，不保证代码正确；lint、测试与人工评审仍是必要环节。

2 功能特性

2.1 对话式文件编辑与自动提交

• 在聊天中用 /add <file> 把文件加入会话，Aider 只修改已加入聊天的文件；/drop <file> 移出，/clear 清空历史。
• 每条模型消息生成后自动创建 Git 提交：提交信息遵循 Conventional Commits，正文说明改动，提交记录附带 (aider) 署名；仓库初始为脏状态时先做一次 dirty commit 保存现有改动。
• 聊天内命令 /diff 查看当前未提交差异，/undo 撤销最近一次 Aider 提交，/commit 手动提交，/git 执行任意 Git 命令，/tokens 查看 Token 用量。

2.2 仓库地图（Repo Map）

• 自动扫描仓库生成结构化地图，把最相关的文件、类与函数摘要送入模型上下文，帮助模型在大型代码库中定位代码。
• 可用 --map-tokens 调整地图占用 Token 预算，--map-refresh manual 改为手动刷新，--subtree-only 只考虑当前子目录。

2.3 架构师模式（Architect）

• --architect 启用双模型协作：架构师模型负责规划方案，编辑模型负责落地代码；--auto-accept-architect 自动接受架构师方案，--weak-model 指定承担轻量任务的弱模型。

2.4 Lint、测试与 watch 模式

• 改动后可自动运行 lint（--auto-lint，默认开启）与测试（--auto-test，默认关闭）；--lint-cmd "python: flake8 --select=..." 按语言指定命令，--test-cmd 指定测试命令。
• --watch-files 监听文件中的 AI 编码注释，配合任意 IDE / 编辑器触发修改；--lint 与 --test 可在退出前集中修复问题。

2.5 图片、网页与语音

• 聊天中可粘贴图片、拖拽截图，或用 /web <url> 添加网页内容；网页抓取默认使用 httpx，安装 Playwright Chromium 后可渲染 JS 页面。
• /voice 语音输入：Linux 需要 PortAudio（libportaudio2），macOS 用 brew install portaudio，Windows 无需额外安装。

2.6 多模型与本地模型

• 云端：OpenAI（o1、o3-mini、GPT-4o 等）、Anthropic（Claude 3.7 Sonnet、Haiku 等）、DeepSeek（R1、Chat V3）、OpenRouter、Gemini、Groq 等；本地：Ollama、LM Studio 及任意 OpenAI 兼容端点。
• 模型通过 --model 指定，也可用 --alias 给模型起别名；--edit-format 控制差异格式（diff、diff-whole、udiff、edits 等）。

3 官方界面预览

3.1 终端对话与统一差异

下图为官方文档中的终端界面：输入 “change hello to goodbye”，Aider 展示 hello.py 的 ORIGINAL / UPDATED 差异，落地修改后自动提交，并在提交信息中署名 (aider)。

3.2 IDE watch 模式

下图为官方文档中的编辑器配合场景：在代码注释中留下 AI 提示，Aider 监听文件变化后按注释完成修改，实现与现有编辑器的无缝配合。

4 官方跳转链接汇总

5 前置要求与环境配置

5.1 软件前提

• Python：pip 直装路径支持 Python 3.9–3.12；核心包兼容 3.8–3.13，可选附加组件在不同版本上支持情况不同，具体以 install 文档 为准。
• Git：官方建议安装 Git，以获得仓库地图、自动提交与回退能力；安装指引见 git-guides/install-git。
• 模型凭据：OpenAI、Anthropic、DeepSeek、OpenRouter、Gemini 等任一提供者的 API Key；本地模型则需要本机运行 Ollama 等推理服务。
• 可选组件：Playwright Chromium（JS 网页抓取）、PortAudio（语音输入）、git 命令行工具。

5.2 硬件与系统建议

5.3 端口与目录

6 方式一：本地 CLI 安装（推荐日常使用）

Aider 是终端桌面工具，无服务端部署形态；以下按官方安装文档给出本地安装路径。

6.1 推荐安装：aider-install（隔离环境）

python -m pip install aider-install
aider-install

aider-install 会为 Aider 创建独立 Python 环境，避免与项目依赖冲突，是官方在依赖问题排查中推荐的安装方式。

6.2 一键脚本（macOS / Linux）

curl https://aider.chat/install.sh | sh

Windows PowerShell：

irm https://aider.chat/install.ps1 | iex

安全提示：管道执行远程脚本前建议先下载脚本阅读内容；脚本行为与依赖以官方 install 文档 为准。

6.3 uv 安装

uv tool install --force --python python3.12 --with pip aider-chat@latest

6.4 pipx 安装

pipx install aider-chat

6.5 pip 直装（注意依赖隔离）

python -m pip install -U aider-chat

官方提醒：Aider 锁定了部分依赖版本，直接 pip 安装时不要随意升降级 litellm 等核心包；与 Python 项目自身依赖冲突时，优先改用 aider-install、uv 或 pipx 隔离环境。

6.6 首次启动与模型配置

# OpenAI
export OPENAI_API_KEY=your-openai-key
cd your-git-repo
aider

# 指定模型启动
aider --model gpt-4o

# DeepSeek
export DEEPSEEK_API_KEY=your-deepseek-key
aider --model deepseek-chat

# 本地 Ollama 模型
export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen2.5-coder:7b

Ollama 本地模型建议先调大上下文长度再启动服务：

export OLLAMA_CONTEXT_LENGTH=8192
ollama serve

启动后在聊天中加入文件并描述需求：

> /add src/main.py
> 把 main.py 里的错误处理改成抛出带上下文的自定义异常

7 方式二：Docker 运行与源码开发

7.1 Docker 核心镜像

docker pull paulgauthier/aider

# 在 Git 仓库根目录执行；当前目录映射到容器 /app
docker run -it --user $(id -u):$(id -g) \
  --volume $(pwd):/app \
  paulgauthier/aider \
  --openai-api-key $OPENAI_API_KEY

7.2 Docker 全量镜像

paulgauthier/aider-full 预装全部可选附加组件，包括交互式帮助、浏览器 GUI 与 Playwright 网页抓取支持；核心镜像首次访问这些功能时会现场安装，容器重建后需要重装。

docker pull paulgauthier/aider-full

docker run -it --user $(id -u):$(id -g) \
  --volume $(pwd):/app \
  paulgauthier/aider-full \
  --openai-api-key $OPENAI_API_KEY

7.3 容器内 Git 配置

容器不会继承宿主机全局 Git 配置，启动前在仓库内设置提交身份：

git config user.email "you@example.com"
git config user.name "Your Name"

7.4 容器使用限制（官方口径）

• 聊天内 /run 执行的 Shell 命令运行在容器内部，不是宿主机；跑项目测试、调用本机服务时需要把相应环境与依赖一并装入镜像。
• /voice 语音需要容器访问宿主机音频设备；镜像已预装 libportaudio2，挂载音频设备的具体方式以官方 Docker 文档与宿主机系统为准。

7.5 从源码运行（开发者）

git clone https://github.com/Aider-AI/aider.git
cd aider
python -m pip install -e .
python -m aider

开发依赖、测试与构建命令以仓库 CONTRIBUTING 与 requirements/ 目录最新说明为准。

8 配置项说明

8.1 配置来源与优先级

Aider 配置按以下顺序生效：命令行参数 → 环境变量 AIDER_* → .env 文件 → 配置文件 .aider.conf.yml。配置文件可放在主目录或当前 Git 仓库根目录；--env-file 指定 .env 路径，--config 指定配置文件路径。

8.2 .aider.conf.yml 示例

model: gpt-4o
weak-model: gpt-4o-mini
auto-commits: true
dirty-commits: true
auto-lint: true
map-tokens: 1024
dark-mode: true
lint-cmd:
  - "python: ruff check --fix"
  - "javascript: eslint --fix"
test-cmd:
  - "pytest -x"

YAML 键名与命令行参数同名；完整字段以 options 文档 为准。

8.3 API Key 配置方式

# 命令行
aider --openai-api-key sk-...
aider --anthropic-api-key sk-...
aider --api-key gemini=xxx

# 环境变量 / .env 文件
OPENAI_API_KEY=your-key
ANTHROPIC_API_KEY=your-key
GEMINI_API_KEY=foo
OPENROUTER_API_KEY=bar
DEEPSEEK_API_KEY=baz

其他提供者通过 --api-key provider=<key> 设置，等价于写入 PROVIDER_API_KEY 环境变量；密钥不要提交到 Git 仓库。

8.4 常用参数速查

8.5 聊天内常用命令

9 常用运维命令

# ---- 安装与版本 ----
aider --version                 # 查看版本
aider --check-update            # 检查更新
aider --upgrade                 # 升级到最新版本
aider --just-check-update       # 仅检查不更新

# ---- 单轮无头运行 ----
aider --message "Write unit tests for src/utils.py" --exit
aider --message "Fix the failing test" --auto-test --exit

# ---- 历史与配置 ----
# 配置文件：~/.aider.conf.yml 或仓库根 .aider.conf.yml
# 历史文件：--chat-history-file 指定，--restore-chat-history 启动恢复
aider --config ./aider-settings.yml --restore-chat-history

# ---- 仓库巡检 ----
aider --show-repo-map           # 查看仓库地图
aider --show-prompts            # 查看发送给模型的提示词（调试用）
aider --dry-run                 # 空跑，不修改文件

更新依赖后若出现导入错误，优先重建隔离环境（aider-install / uv tool install / pipx install）。

10 常见故障排查

10.1 aider: command not found

• 安装脚本未把命令目录加入 PATH；可直接用 python -m aider 启动。
• 确认当前终端已重新打开或执行了 shell 配置重载；pipx / uv 安装后检查对应工具的二进制目录是否在 PATH 中。

10.2 ImportError 与依赖版本冲突

• 官方排查口径：Aider 锁定了依赖版本，Homebrew、AUR、ports 等包管理器常装错依赖导致导入错误；改用 aider-install、uv 或 pipx 隔离环境安装。
• 不要随意升降级 litellm，该包更新频繁且可能引入不兼容变更；与项目依赖冲突时在独立环境运行 Aider。

10.3 Token 上限错误

• 上下文超限：用 /drop 移出不需要的文件，只保留需要修改的文件；/clear 清空历史；把大文件拆小；换用上下文窗口更大的模型。/tokens 查看当前用量。
• 输出超限：把大改动拆成多轮小修改；使用支持返回 diff 的强模型；部分模型支持长输出模式，见官方 infinite-output 文档。
• 代理或本地模型服务器不符合规范时也可能误报 Token 错误；去掉 API 代理直连官方云接口或 Ollama 验证问题是否复现。

10.4 模型连接或 SSL 错误

• 核对 --openai-api-base、--openai-api-type、--anthropic-api-base 等端点配置与环境变量；私有部署模型确认 Base URL 路径完整。
• 自签证书环境使用 --verify-ssl（默认校验开启）；内网证书问题需先把根证书导入系统证书库。

10.5 语音与网页功能不可用

• 语音：Linux 安装 libportaudio2（必要时补 libasound2-plugins），macOS brew install portaudio；容器内需额外挂载音频设备。
• 网页：/web 默认用 httpx 抓取；被 JS 渲染或反爬拦截的页面先安装 Playwright Chromium：playwright install --with-deps chromium。

10.6 Docker 内命令与测试跑不通

/run 命令在容器内执行，项目依赖、数据库、环境变量不会自动从宿主机带入；需要在自定义镜像中安装依赖，或把测试命令所需目录与端口挂载进容器。

10.7 Windows PowerShell 执行策略

若安装脚本被执行策略拦截，以管理员身份或当前用户身份调整 PowerShell 执行策略后重新运行 install.ps1；调整范围与安全风险以 Windows 官方文档为准。

11 风险与合规说明

以下条款整理自官方 README、Apache 2.0 许可证与官方文档口径；如与官方原文不一致，以仓库 LICENSE.txt、README 与 aider.chat/docs 为准。

11.1 开源协议

Aider 采用 Apache 2.0 许可证，允许自由使用、修改与再分发，修改文件需保留版权声明与许可证副本；Docker 镜像中预装的可选组件各自遵循其对应许可。

11.2 模型与代码隐私

• 项目不附带模型与 API Key；OpenAI、Anthropic、DeepSeek、OpenRouter、Gemini、Groq 等服务归对应厂商所有，受其条款、隐私政策与计费规则约束。
• 文件内容、仓库地图摘要、终端输出会按所选模型发送到对应服务；商业敏感代码优先使用本地 Ollama 等离线模型，并在团队内明确代码外发规范。

11.3 自动提交与改动风险

• 默认开启自动提交，模型生成的修改会直接进入 Git 历史；重要分支建议先切到特性分支，人工评审 diff 后再合并，必要时用 --no-auto-commits 改为手动提交。
• --dry-run 可在不改文件的前提下验证提示与方案；lint、测试与人工代码评审不应由 Aider 替代。

11.4 商业使用与免责

Apache 2.0 不限制商业场景使用，但集成模型提供者与第三方组件时须同时满足各自许可。项目按现状（AS-IS）提供，不对模型输出正确性、代码安全与服务可用性作担保；使用者自行承担代码质量、数据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue 中提交 API Key、令牌或敏感代码。