# Aider 集成

> **最后核实**：2026-09-18 · 📄 依据官方文档（Aider 上游仓库；见下表状态说明）

> **上游活跃度**：Aider-AI/aider 仓库最后一次提交为 2026-05-22，其后无新 release（2026-09-18 经 GitHub API 核实）。本页接入方式仍然可用；若需要活跃维护的同类工具，可看 [Cline](/docs/ide/cline) 或 [Kilo Code](/docs/ide/kilo-code)。

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（`anthropic/` 前缀走 Anthropic 端点）· GPT ✅ · 国产 ✅（OpenAI 兼容端点）· Gemini ❌（本页未写 Gemini 接法） |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai/v1` |
| 相关环境变量 | `ANTHROPIC_API_BASE` 与 `OPENAI_API_BASE` 分别指两条腿 |
| 配置位置 | 命令行参数或 `~/.aider.conf.yml` |
| 官方文档 | [aider.chat](https://aider.chat) |

[Aider](https://github.com/paul-gauthier/aider) 是一款热门的开源 AI 编程助手（39K+ GitHub Stars），在终端中运行，支持 100+ 编程语言。它底层用 LiteLLM 路由模型，因此**同时支持 Anthropic 与 OpenAI 两种协议**。

## 🔴 先看这一条：Claude 必须走 Anthropic 端点

QCode 的 OpenAI 兼容端点**不接受 Claude 模型**。把 `OPENAI_API_BASE` 指向 QCode 再用
`openai/claude-…` 这种写法会返回 `model_not_available_on_endpoint`。

| 你想用的模型 | Aider 模型名前缀 | 环境变量 | 值 |
|---|---|---|---|
| Claude | `anthropic/` | `ANTHROPIC_API_BASE` | `https://api.qcode.cc/api` |
| GPT 系 / 国产四家族 | `openai/` | `OPENAI_API_BASE` | `https://api.qcode.cc/openai/v1` |

对照表见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

## 为什么选择 Aider？

- **完全开源免费**：仅需支付 API 费用
- **Architect 模式**：用一个模型做计划、另一个执行，提升代码质量
- **Git 深度集成**：每次 AI 编辑自动生成 git commit
- **Repository Map**：基于 tree-sitter 智能索引整个代码库
- **两种协议都支持**：Claude 走 Anthropic，GPT / 国产走 OpenAI

## 安装

```bash
# 推荐使用 pipx（隔离安装）
pipx install aider-chat

# 或使用 pip
pip install aider-chat
```

## 配置 Claude（Anthropic 端点）

```bash
export ANTHROPIC_API_BASE="https://api.qcode.cc/api"
export ANTHROPIC_API_KEY="cr_你的QCode密钥"

aider --model anthropic/claude-sonnet-5
```

LiteLLM 会在这个 base 后面自动追加 `/v1/messages`，所以**填到 `/api` 为止**，末尾不要带斜杠。

> **变量名可能因版本而异**：LiteLLM 历史上在 `ANTHROPIC_API_BASE` 与 `ANTHROPIC_BASE_URL`
> 之间有过分歧。如果一个不生效，试另一个，或用命令行参数 `--anthropic-api-key`。
> 以 [Aider 官方文档](https://aider.chat/) 为准。

永久设置（追加到 `~/.zshrc` 或 `~/.bashrc`）：

```bash
echo 'export ANTHROPIC_API_BASE="https://api.qcode.cc/api"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="cr_你的QCode密钥"' >> ~/.zshrc
source ~/.zshrc
```

## 配置 GPT 与国产模型（OpenAI 兼容端点）

```bash
export OPENAI_API_BASE="https://api.qcode.cc/openai/v1"
export OPENAI_API_KEY="cr_你的QCode密钥"

aider --model openai/gpt-5.5
```

国产四家族（`glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.7-max` 等）两条腿都能走，
id 见 [国产模型接入](/docs/usage/cn-models)。

## 使用

```bash
cd /path/to/your/project

# 日常主力
aider --model anthropic/claude-sonnet-5

# 更强的旗舰
aider --model anthropic/claude-opus-5
```

### Architect 模式（推荐）

Architect 模式让一个模型负责规划，另一个负责执行代码修改：

```bash
# Opus 规划 + Sonnet 执行（推荐）
aider --architect --model anthropic/claude-opus-5 --editor-model anthropic/claude-sonnet-5

# Sonnet 规划 + Haiku 执行（省费用）
aider --architect --model anthropic/claude-sonnet-5 --editor-model anthropic/claude-haiku-4-5
```

> 两个模型必须用**同一条协议腿**。混用（例如 `anthropic/` 规划 + `openai/claude-…` 执行）
> 会在执行侧被拒。

### 常用命令

在 Aider 会话中：

| 命令 | 说明 |
|------|------|
| `/add file.py` | 将文件添加到聊天上下文 |
| `/drop file.py` | 移除文件 |
| `/run pytest` | 执行命令并将输出发给 AI |
| `/diff` | 显示所有变更 |
| `/undo` | 撤销上一次 AI 编辑 |
| `/commit` | 提交当前变更 |
| `/help` | 显示帮助 |

## 备用节点

四个接入域业务能力相同，只是网络路由不同，同一把 Key 通用：

| 节点 | Anthropic（Claude） | OpenAI（GPT / 国产） |
|------|---------------------|----------------------|
| 全球 | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| 亚洲（大陆首选） | `https://asia.qcode.cc/api` | `https://asia.qcode.cc/openai/v1` |
| 美国 | `https://us.qcode.cc/api` | `https://us.qcode.cc/openai/v1` |
| 欧洲 | `https://eu.qcode.cc/api` | `https://eu.qcode.cc/openai/v1` |

## 可用模型

| 模型 | Aider 中的名称 | 说明 |
|------|---------------|------|
| Claude Sonnet 5 | `anthropic/claude-sonnet-5` | 推荐，性价比高 |
| Claude Opus 5 | `anthropic/claude-opus-5` | 最强模型 |
| Claude Haiku 4.5 | `anthropic/claude-haiku-4-5` | 低成本快速 |
| GPT 5.5 | `openai/gpt-5.5` | OpenAI 旗舰 |
| GLM 5.2 | `openai/glm-5.2` | 国产，单价低 |

> `claude-sonnet-4-6`、`claude-opus-4-8` 等 4.x 仍在售（前缀同样是 `anthropic/`）。
> 实时清单以 [qcode.cc/models](https://qcode.cc/models) 为准。

## 与 Claude Code CLI 的对比

| 维度 | Aider | Claude Code CLI |
|------|-------|-----------------|
| 开源 | 完全开源 | 不开源 |
| Git 集成 | 每次编辑自动 commit | 手动 /commit |
| Architect 模式 | 双模型规划+执行 | 单模型 |
| 工具能力 | 文件编辑 + Shell | 更丰富（LSP、搜索、浏览器） |
| 上下文管理 | Repository Map 智能索引 | 20 万-100 万 token 窗口 |
| 配额 | 共享 QCode.cc 套餐配额 | 共享 QCode.cc 套餐配额 |

**推荐组合**：Aider 用于快速代码修改和 Architect 模式规划，Claude Code CLI 用于复杂项目分析和自动化任务。

## 常见问题

### 报错 `model_not_available_on_endpoint`

你把 Claude 模型送到了 OpenAI 腿上。检查两件事：模型名前缀应是 `anthropic/` 而不是 `openai/`；
base 应是 `ANTHROPIC_API_BASE=https://api.qcode.cc/api`。

### 报错 "Model not found"

Aider 需要前缀来判断走哪个 provider：

```bash
# 正确
aider --model anthropic/claude-sonnet-5

# 错误（缺少前缀）
aider --model claude-sonnet-5
```

### API 调用超时

尝试切换备用节点，或增加超时时间：

```bash
aider --model anthropic/claude-sonnet-5 --timeout 120
```

## 下一步

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族真源表
- [Cline 集成](/docs/ide/cline) — VS Code 中的图形化替代方案
- [命令行技巧](/docs/usage/cli-tips) — Claude Code 的高级用法
- [Aider 官方文档](https://aider.chat/)