Aider 配置教程

在 Aider CLI 中通过 OpenAI 兼容方式接入 Crazyrouter，并提供区分 Windows 与 macOS 的完整安装、环境变量、配置文件与验证步骤

更新日期：2026-06-06

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

概览

通过环境变量或 ~/.aider.conf.yml，Aider 可以把请求发到 Crazyrouter：

推荐协议：OpenAI-compatible API

Base URL：https://api.crazyrouter.com/v1

认证变量：OPENAI_API_KEY

推荐默认模型写法：gpt-5.5

Tip: 如果你的日常工作流是“读代码 -> 改几处 -> 看 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://api.crazyrouter.com/v1

同时要注意：Crazyrouter 的模型名就是后台模型列表和 pricing 页面展示的原始模型 ID，例如 gpt-5.5、claude-opus-4-8。在 Aider 里也应直接填写这个模型 ID：

gpt-5.5

Warning: 不要给 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.5

claude-opus-4-8

gemini-3.1-pro

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

Windows 推荐路径

Aider 在 Windows 上最稳妥的路径是：Git + Python + PowerShell 安装 Aider + PowerShell 写环境变量。

推荐顺序：

安装 Git

安装 Python

用 PowerShell 跑 Aider 官方安装脚本，或先装 aider-install

用 PowerShell 写临时变量

用 PowerShell 写用户级持久变量

新开终端确认 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 持久化环境变量。

推荐顺序：

安装 Xcode Command Line Tools

安装 Homebrew（如果你还没有）

安装 Git、Python

运行 Aider 官方安装脚本，或通过 aider-install / uv 安装

写入 ~/.zshrc

新开终端确认 aider 命令和变量路径

推荐验证命令：

Linux 说明

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

从零开始完整安装

第 1 步：安装 Git

如果机器还没有 Git，请先安装。

Windows PowerShell

        winget install --id Git.Git -e --source winget
        git --version
        where.exe git

macOS

或：

Ubuntu / Debian

建议补齐：

第 2 步：安装 Python 和 pip

Aider 官方安装器会使用 Python 或自动准备自己的 Python 运行环境。为了排障简单，建议你先确认本机 Python 可用。

Windows PowerShell

        winget install Python.Python.3.12
        python --version
        pip --version
        where.exe python

macOS

Ubuntu / Debian

第 3 步：安装 Aider

Aider 官方当前推荐的一键安装脚本如下。

Windows PowerShell

        powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"
        aider --version
        where.exe aider

macOS / Linux

如果你更想先明确看到安装过程，也可以走 Aider 官方的 aider-install 路线：

Windows PowerShell

        python -m pip install aider-install
        aider-install
        aider --version

macOS / Linux

如果你已经在团队里统一使用 uv，也可以按官方文档这样装：

Warning: 不建议一开始就手动 pip install aider-chat 到系统环境里。官方更推荐使用安装脚本、aider-install 或 uv，这样依赖隔离更稳。

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

在 Crazyrouter 后台创建一个名为 aider 的 token，第一次只建议放行：

gpt-5.5

claude-opus-4-8

gemini-3.1-pro

Note: 这里白名单里放的是 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_BASE

持久化之后，建议新开一个终端，再执行一次：

Windows PowerShell

        aider --version
        echo $env:OPENAI_API_BASE

macOS / 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.yml

如果你更注重安全，也可以把 key 只放在环境变量里，把配置文件里只保留 model 和 openai-api-base。

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

Aider 在 Git 仓库中体验最好。如果当前目录还不是 Git 仓库：

如果已经是现有仓库，先看一下：

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

进入项目目录后执行：

第一次验证建议按下面顺序：

请只总结当前仓库结构，不修改文件

请阅读 README，给出最小修改建议，先不要直接改

确认能正常显示 diff 后，再做小范围修改

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`	适合作为第二条兼容性验证路径

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.5

aider --model gpt-5.5 可以正常启动

第一个只读或小改动任务成功返回

Crazyrouter 后台日志能看到对应请求

token 配额和模型白名单符合预期

常见错误与修复

现象	常见原因	修复方式
`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-8

不同项目类型建议拆开 token，便于统计成本

会话过长时及时清理上下文，避免反复携带无关文件

每次大改后都回看 Aider 生成的 diff 和 Crazyrouter 日志

FAQ

Aider 应该填哪个 Base URL？

填 https://api.crazyrouter.com/v1。

为什么模型名不要写成 `openai/gpt-5.5`？

因为 Crazyrouter 的模型名不带供应商前缀，本站实际识别的是 gpt-5.5 这类原始模型 ID。openai/gpt-5.5 会被当作另一个模型名处理，本站没有这个模型。

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

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

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

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

第一个推荐模型是什么？

先用 gpt-5.5。

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

不是绝对必须，但它在 Git 仓库中的体验通常最好，也更容易审查修改结果。

Note: 如果你想要一个非常轻量、非常适合日常小步改代码的终端工具，Aider 仍然值得优先保留在 Crazyrouter 的应用指南里。

最后校验/修改：2026-09-28（API Base URL 由 cn.crazyrouter.com 统一改为 https://api.crazyrouter.com，共 13 处；账号/控制台仍为 https://crazyrouter.com）

aider 配置教程

Aider 配置教程#

概览#

适合谁用#

使用协议#

系统要求与前置条件#

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

Windows 推荐路径#

macOS 推荐路径#

Linux 说明#

从零开始完整安装#

第 1 步：安装 Git#

Windows PowerShell#

macOS#

Ubuntu / Debian#

第 2 步：安装 Python 和 pip#

Windows PowerShell#

macOS#

Ubuntu / Debian#

第 3 步：安装 Aider#

Windows PowerShell#

macOS / Linux#

Windows PowerShell#

macOS / Linux#

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

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

macOS / Linux#

Windows PowerShell#

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

Linux Bash#

macOS / Zsh#

Windows PowerShell#

Windows PowerShell#

macOS / Linux#

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

macOS / Linux#

Windows PowerShell#

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

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

推荐模型配置#

Token 设置最佳实践#

验证清单#

常见错误与修复#

性能与成本建议#

FAQ#

Aider 应该填哪个 Base URL？#

为什么模型名不要写成 openai/gpt-5.5？#

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

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

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

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

Aider 配置教程

概览

适合谁用

使用协议

系统要求与前置条件

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

Windows 推荐路径

macOS 推荐路径

Linux 说明

从零开始完整安装

第 1 步：安装 Git

Windows PowerShell

macOS

Ubuntu / Debian

第 2 步：安装 Python 和 pip

Windows PowerShell

macOS

Ubuntu / Debian

第 3 步：安装 Aider

Windows PowerShell

macOS / Linux

Windows PowerShell

macOS / Linux

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

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

macOS / Linux

Windows PowerShell

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

Linux Bash

macOS / Zsh

Windows PowerShell

Windows PowerShell

macOS / Linux

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

macOS / Linux

Windows PowerShell

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

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

推荐模型配置

Token 设置最佳实践

验证清单

常见错误与修复

性能与成本建议

FAQ

Aider 应该填哪个 Base URL？

为什么模型名不要写成 `openai/gpt-5.5`？

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

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

第一个推荐模型是什么？

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