aider 配置教程
Aider 配置教程
在 Aider CLI 中通过 OpenAI 兼容方式接入 Crazyrouter，并提供区分 Windows 与 macOS 的完整安装、环境变量、配置文件与验证步骤
更新日期：2026-06-06
概览
~/.aider.conf.yml，Aider 可以把请求发到 Crazyrouter：OpenAI-compatible APIhttps://api.crazyrouter.com/v1OPENAI_API_KEYgpt-5.5Tip: 如果你的日常工作流是“读代码 -> 改几处 -> 看 diff -> 再修一轮”，Aider 往往是最轻量、最容易稳定落地的一类终端编码工具。
适合谁用
使用协议
OpenAI-compatible APIOPENAI_API_KEYOPENAI_API_BASEopenai-api-keyopenai-api-baseOPENAI_API_BASE=https://api.crazyrouter.com/v1gpt-5.5、claude-opus-4-8。在 Aider 里也应直接填写这个模型 ID：gpt-5.5Warning: 不要给 Crazyrouter 模型名额外添加 openai/前缀。openai/gpt-5.5不是本站模型名，会导致model not found或路由无可用渠道。
系统要求与前置条件
| 项目 | 说明 |
|---|---|
| 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.5claude-opus-4-8gemini-3.1-pro按操作系统的完整安装路径
Windows 推荐路径
Git + Python + PowerShell 安装 Aider + PowerShell 写环境变量。1.
2.
3.
aider-install4.
5.
6.
aider 命令和变量都生效git --version
python --version
pip --version
aider --version
where.exe git
where.exe python
where.exe aideraider --version 找不到命令，先关闭并重新打开 PowerShell，再重试。macOS 推荐路径
Xcode Command Line Tools + Homebrew + Git + Python + Aider 官方安装脚本 + ~/.zshrc 持久化环境变量。1.
2.
3.
4.
aider-install / uv 安装5.
~/.zshrc6.
aider 命令和变量路径Linux 说明
~/.bashrc。如果你只是本地开发机或云主机首次接入，优先先用当前 shell 里的临时变量跑通，再决定是否持久写入。从零开始完整安装
第 1 步：安装 Git
Windows PowerShell
winget install --id Git.Git -e --source winget
git --version
where.exe gitmacOS
Ubuntu / Debian
第 2 步：安装 Python 和 pip
Windows PowerShell
winget install Python.Python.3.12
python --version
pip --version
where.exe pythonmacOS
Ubuntu / Debian
第 3 步：安装 Aider
Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"
aider --version
where.exe aidermacOS / Linux
aider-install 路线：Windows PowerShell
python -m pip install aider-install
aider-install
aider --versionmacOS / Linux
uv，也可以按官 方文档这样装：Warning: 不建议一开始就手动 pip install aider-chat到系统环境里。官方更推荐使用安装脚本、aider-install或uv，这样依赖隔离更稳。
第 4 步：在 Crazyrouter 创建 Aider 专用 token
aider 的 token，第一次只建议放行：gpt-5.5claude-opus-4-8gemini-3.1-proNote: 这里白名单里放的是 Crazyrouter 的原始模型名，不需要写 openai/前缀。
第 5 步：先在当前终端设置临时环境变量
macOS / Linux
Windows PowerShell
$env:OPENAI_API_KEY = "sk-xxx"
$env:OPENAI_API_BASE = "https://api.crazyrouter.com/v1"
echo $env:OPENAI_API_KEY
echo $env:OPENAI_API_BASE第 6 步：把环境变量写入持久配置
Linux Bash
macOS / Zsh
Windows PowerShell
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxx", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_API_BASE", "https://api.crazyrouter.com/v1", "User")
$env:OPENAI_API_KEY = "sk-xxx"
$env:OPENAI_API_BASE = "https://api.crazyrouter.com/v1"
echo $env:OPENAI_API_BASEWindows PowerShell
aider --version
echo $env:OPENAI_API_BASEmacOS / Linux
第 7 步：可选写入 ~/.aider.conf.yml
macOS / Linux
Windows PowerShell
@'
model: gpt-5.5
openai-api-base: https://api.crazyrouter.com/v1
'@ | Set-Content -Path "$HOME/.aider.conf.yml"
Get-Content $HOME/.aider.conf.ymlmodel 和 openai-api-base。第 8 步：准备 Git 仓库并做首个快照
第 9 步：启动 Aider 并完成第一次验证
1.
请只总结当前仓库结构，不修改文件2.
请阅读 README，给出最小修改建议，先不要直接改3.
Tip: 如果你临时想验证另一个模型，写法也保持同样模式，例如 aider --model claude-opus-4-8。
推荐模型配置
| 使用场景 | Aider 中建议写法 | 原因 |
|---|---|---|
| 默认主力编码 | gpt-5.5 | 使用 Crazyrouter 原始模型 ID，适合作为 Aider OpenAI 兼容基线 |
| Claude 风格替代 | claude-opus-4-8 | 适合长上下文解释和较稳的多轮协作 |
| Gemini 备用档 | gemini-3.1-pro | 适合作为第二条兼容性验证路径 |
gpt-5.5，跑通后再视场景增加 claude-opus-4-8 或 gemini-3.1-pro。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://api.crazyrouter.com/v1~/.aider.conf.yml 如有使用，模型名写法为 Crazyrouter 原始模型 ID，例如 gpt-5.5aider --model gpt-5.5 可以正常启动常见错误与修复
| 现象 | 常见原因 | 修复方式 |
|---|---|---|
aider: command not found | Aider 没装成功，或安装器没有把可执行文件加入 PATH | 重新运行官方安装器，并开新终端再试 |
| Python 版本混乱 | 系统 Python 与 Aider 运行环境冲突 | 优先使用安装脚本、aider-install 或 uv，不要自己混装多个依赖 |
| 401 unauthorized | API Key 错误、过期或复制不完整 | 重新生成 token 并重新设置 |
| 403 / model not allowed | token 未放行当前模型 | 在 Crazyrouter token 设置中放行模型 |
| 404 | Base URL 填错，或少了 /v1 | 改成 https://api.crazyrouter.com/v1 |
model not found | 模型名写错、使用了不存在的 openai/ 前缀，或该模型当前未在本站开放 | 改回 pricing 页面或模型列表中存在的原始模型 ID，例如 gpt-5.5、claude-opus-4-8 |
| 配置文件和环境变量行为不一致 | 两处配置冲突 | 保留一个主配置来源，重新启动 Aider |
| 成本升高过快 | 长会话累计、上下文文件过多 | 及时清理上下文并限制 token 配额 |
性能与成本建议
gpt-5.5，如需交叉验证再加 claude-opus-4-8FAQ
Aider 应该填哪个 Base URL？
https://api.crazyrouter.com/v1。为什么模型名不要写成 openai/gpt-5.5？
gpt-5.5 这类原始模型 ID。openai/gpt-5.5 会被当作另一个模型名处理，本站没有这个模型。推荐用环境变量还是配置文件？
~/.aider.conf.yml。第一次为什么建议先做 Git 快照？
第一个推荐模型是什么？
gpt-5.5。Aider 一定要在 Git 仓库中使用吗？
Note: 如果你想要一个非常轻量、非常适合日常小步改代码的终端工具，Aider 仍然值得优先保留在 Crazyrouter 的应用指南里。
最后校验/修改：2026-09-28（API Base URL 由 cn.crazyrouter.com 统一改为 https://api.crazyrouter.com，共 13 处；账号/控制台仍为 https://crazyrouter.com）
Modified at 2026-09-28 08:54:42