跳转到主要内容
Aider 是非常实用的终端结对编程工具，适合在 Git 仓库里做小步快跑式改代码、审查 diff、追加上下文文件和逐轮修复。对接 Crazyrouter 时，最稳妥的方式是走 Aider 官方支持的 OpenAI-compatible 配置。

​
概览

通过环境变量或 ~/.aider.conf.yml，Aider 可以把请求发到 Crazyrouter：
  • 推荐协议：OpenAI-compatible API
  • Base URL：https://crazyrouter.com/v1
  • 认证变量：OPENAI_API_KEY
  • 推荐默认模型写法：openai/gpt-5.4
如果你的日常工作流是“读代码 -> 改几处 -> 看 diff -> 再修一轮”，Aider 往往是最轻量、最容易稳定落地的一类终端编码工具。

​
适合谁用

  • 想在终端里做小步提交式代码修改的人
  • 想明确控制上下文文件、diff 和提交节奏的人
  • 想把 Aider 与 Codex、Claude Code 分开计费的人
  • 想先用最直接的 OpenAI 兼容方式接入 Crazyrouter 的人

​
使用协议

推荐协议：OpenAI-compatible API Aider 官方支持以下配置项：
  • OPENAI_API_KEY
  • OPENAI_API_BASE
  • openai-api-key
  • openai-api-base
Crazyrouter 对应写法： 
OPENAI_API_BASE=https://crazyrouter.com/v1
同时要注意：Aider 官方文档里，连接 OpenAI 兼容接口时，模型名建议写成 openai/<model-name>。因此 Crazyrouter 的 gpt-5.4，在 Aider 里建议写成： 
openai/gpt-5.4
这是本轮补强里最重要的修正点之一。Crazyrouter token 白名单里仍然放行原始模型名，例如 gpt-5.4；但在 Aider 命令和 ~/.aider.conf.yml 里，建议写成 openai/gpt-5.4。

​
系统要求与前置条件

项目说明
Crazyrouter 账号先在 crazyrouter.com 注册
Crazyrouter token建议为 Aider 单独创建一个 token
Git建议 git 2.23+
Python如果走 aider-install 路线，建议本机先有 Python 3.8-3.13；如果走官方一键安装脚本，安装器会按需处理 Python 3.12
Aider建议使用当前稳定版本
Git 仓库Aider 在 Git 仓库中体验通常最好
可用模型至少放行一个你要使用的编码模型
建议初始白名单：
  • gpt-5.4
  • claude-sonnet-4-6
  • gemini-3-pro-preview

​
按操作系统的完整安装路径

​
Windows 推荐路径

Aider 在 Windows 上最稳妥的路径是：Git + Python + PowerShell 安装 Aider + PowerShell 写环境变量。 推荐顺序：
  1. 安装 Git
  2. 安装 Python
  3. 用 PowerShell 跑 Aider 官方安装脚本，或先装 aider-install
  4. 用 PowerShell 写临时变量
  5. 用 PowerShell 写用户级持久变量
  6. 新开终端确认 aider 命令和变量都生效
推荐验证命令： 
git --version
python --version
pip --version
aider --version
where.exe git
where.exe python
where.exe aider
如果 aider --version 找不到命令，先关闭并重新打开 PowerShell，再重试。

​
macOS 推荐路径

Aider 在 macOS 上最顺手的路径通常是：Xcode Command Line Tools + Homebrew + Git + Python + Aider 官方安装脚本 + ~/.zshrc 持久化环境变量。 推荐顺序：
  1. 安装 Xcode Command Line Tools
  2. 安装 Homebrew（如果你还没有）
  3. 安装 Git、Python
  4. 运行 Aider 官方安装脚本，或通过 aider-install / uv 安装
  5. 写入 ~/.zshrc
  6. 新开终端确认 aider 命令和变量路径
推荐验证命令： 
git --version
python3 --version
pip3 --version
aider --version
which git
which python3
which aider

​
Linux 说明

Linux 基本可以按 macOS 的终端路线理解，只是持久环境变量通常写入 ~/.bashrc。如果你只是本地开发机或云主机首次接入，优先先用当前 shell 里的临时变量跑通，再决定是否持久写入。

​
从零开始完整安装

1

第 1 步：安装 Git

如果机器还没有 Git，请先安装。
winget install --id Git.Git -e --source winget
git --version
where.exe git
建议补齐：
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
2

第 2 步：安装 Python 和 pip

Aider 官方安装器会使用 Python 或自动准备自己的 Python 运行环境。为了排障简单，建议你先确认本机 Python 可用。
winget install Python.Python.3.12
python --version
pip --version
where.exe python
3

第 3 步：安装 Aider

Aider 官方当前推荐的一键安装脚本如下。
powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"
aider --version
where.exe aider
如果你更想先明确看到安装过程，也可以走 Aider 官方的 aider-install 路线：
python -m pip install aider-install
aider-install
aider --version
如果你已经在团队里统一使用 uv，也可以按官方文档这样装：
python -m pip install uv
uv tool install --force --python python3.12 --with pip aider-chat@latest
aider --version
不建议一开始就手动 pip install aider-chat 到系统环境里。官方更推荐使用安装脚本、aider-install 或 uv，这样依赖隔离更稳。
4

第 4 步：在 Crazyrouter 创建 Aider 专用 token

在 Crazyrouter 后台创建一个名为 aider 的 token，第一次只建议放行：
  • gpt-5.4
  • claude-sonnet-4-6
  • gemini-3-pro-preview
这里白名单里放的是 Crazyrouter 的原始模型名，不需要写 openai/ 前缀。
5

第 5 步：先在当前终端设置临时环境变量

先临时配置，跑通后再写入持久配置。
export OPENAI_API_KEY=sk-xxx
export OPENAI_API_BASE=https://crazyrouter.com/v1
echo $OPENAI_API_KEY
echo $OPENAI_API_BASE
6

第 6 步：把环境变量写入持久配置

echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.bashrc
echo 'export OPENAI_API_BASE=https://crazyrouter.com/v1' >> ~/.bashrc
source ~/.bashrc
echo $OPENAI_API_BASE
持久化之后，建议新开一个终端，再执行一次：
aider --version
echo $env:OPENAI_API_BASE
7

第 7 步：可选写入 ~/.aider.conf.yml

如果你不想每次都手动加参数，可以写配置文件。
cat > ~/.aider.conf.yml <<'EOF'
model: openai/gpt-5.4
openai-api-base: https://crazyrouter.com/v1
EOF
cat ~/.aider.conf.yml
如果你更注重安全，也可以把 key 只放在环境变量里，把配置文件里只保留 model 和 openai-api-base。
8

第 8 步：准备 Git 仓库并做首个快照

Aider 在 Git 仓库中体验最好。如果当前目录还不是 Git 仓库：
git init
git add .
git commit -m "chore: initial snapshot before Aider"
如果已经是现有仓库，先看一下：
git status
9

第 9 步：启动 Aider 并完成第一次验证

进入项目目录后执行：
cd /path/to/your/project
aider --model openai/gpt-5.4
第一次验证建议按下面顺序：
  1. 请只总结当前仓库结构，不修改文件
  2. 请阅读 README，给出最小修改建议，先不要直接改
  3. 确认能正常显示 diff 后，再做小范围修改
如果你临时想验证另一个模型，写法也保持同样模式，例如 aider --model openai/claude-sonnet-4-6。

​
推荐模型配置

使用场景Aider 中建议写法Crazyrouter 实际模型原因
默认主力编码openai/gpt-5.4gpt-5.42026 年 3 月 23 日已在生产环境实测成功，适合作为 Aider OpenAI 兼容基线
Claude 风格替代openai/claude-sonnet-4-6claude-sonnet-4-6适合长上下文解释和较稳的多轮协作
Gemini 备用档openai/gemini-3-pro-previewgemini-3-pro-preview适合作为第二条兼容性验证路径
建议先用 openai/gpt-5.4，跑通后再视场景增加 openai/claude-sonnet-4-6 或 openai/gemini-3-pro-preview。

​
Token 设置最佳实践

设置建议说明
专用 token必须Aider 不要和其他 IDE / CLI 共用 token
模型白名单强烈建议保持最小模型集合，避免误切高价模型
IP 限制视环境开启固定服务器可以考虑，移动开发机谨慎使用
配额上限强烈建议Aider 长会话和多轮修复容易持续消耗
环境隔离建议本地开发、远程机器、CI 分开 token
泄露处理立即轮换.aider.conf.yml、shell 历史或录屏泄露后要立即换 key

​
验证清单

  • git --version 正常
  • python --version 或 python3 --version 正常
  • aider --version 正常
  • OPENAI_API_KEY 已设置正确
  • OPENAI_API_BASE 已设置为 https://crazyrouter.com/v1
  • ~/.aider.conf.yml 如有使用，模型名写法为 openai/...
  • aider --model openai/... 可以正常启动
  • 第一个只读或小改动任务成功返回
  • Crazyrouter 后台日志能看到对应请求
  • token 配额和模型白名单符合预期

​
常见错误与修复

现象常见原因修复方式
aider: command not foundAider 没装成功，或安装器没有把可执行文件加入 PATH重新运行官方安装器，并开新终端再试
Python 版本混乱系统 Python 与 Aider 运行环境冲突优先使用安装脚本、aider-install 或 uv，不要自己混装多个依赖
401 unauthorizedAPI Key 错误、过期或复制不完整重新生成 token 并重新设置
403 / model not allowedtoken 未放行当前模型在 Crazyrouter token 设置中放行模型
404Base URL 填错，或少了 /v1改成 https://crazyrouter.com/v1
model not found模型名写错，或忘了在 Aider 里加 openai/ 前缀改回 openai/gpt-5.4、openai/claude-sonnet-4-6 等已确认写法
配置文件和环境变量行为不一致两处配置冲突保留一个主配置来源，重新启动 Aider
成本升高过快长会话累计、上下文文件过多及时清理上下文并限制 token 配额

​
性能与成本建议

  • 第一次接入时，先在小仓库里验证
  • 默认用 openai/gpt-5.4，如需交叉验证再加 openai/claude-sonnet-4-6
  • 不同项目类型建议拆开 token，便于统计成本
  • 会话过长时及时清理上下文，避免反复携带无关文件
  • 每次大改后都回看 Aider 生成的 diff 和 Crazyrouter 日志

​
FAQ

​
Aider 应该填哪个 Base URL？

填 https://crazyrouter.com/v1。

​
为什么模型名推荐写成 openai/gpt-5.4？

因为 Aider 官方在 OpenAI-compatible 路线里建议使用 openai/<model-name> 这种写法。Crazyrouter 后台白名单里仍然是原始模型名，但在 Aider 命令和配置文件里建议加上 openai/ 前缀。

​
推荐用环境变量还是配置文件？

两种都可以。先用环境变量更快；长期使用建议再补 ~/.aider.conf.yml。

​
第一次为什么建议先做 Git 快照？

因为 Aider 会改文件、生成 diff、自动提交或建议提交。先做快照，排障和回滚会简单很多。

​
第一个推荐模型是什么？

先用 openai/gpt-5.4。

​
Aider 一定要在 Git 仓库中使用吗？

不是绝对必须，但它在 Git 仓库中的体验通常最好，也更容易审查修改结果。
如果你想要一个非常轻量、非常适合日常小步改代码的终端工具，Aider 仍然值得优先保留在 Crazyrouter 的应用指南里。