Aider

安装 Aider，并使用 OpenAI 兼容环境变量将 Aider 连接到 TokenHub。

Aider 是终端里的结对编程 Agent。它可以通过 OpenAI 兼容 Base URL 使用 TokenHub 模型，并且天然适合在 Git 工作区里追踪每次代码修改。

适合场景

Aider 适合小步修改、测试驱动修复、跨文件重构和解释代码。它会把文件加入上下文后再改动，因此建议先在一个干净的 Git 分支里使用。

安装 Aider

先参考 Aider 官方安装文档。常见安装方式如下：

# 推荐：使用 uv
uv tool install aider-chat

# 或使用 pipx
pipx install aider-chat

# 已有 Python 环境时也可以使用 pip
python -m pip install -U aider-chat

确认命令可用：

aider --version

准备 TokenHub 凭证

export TOKENHUB_API_KEY="sk-..."

建议先进入 Git 工作区：

cd /path/to/your/repo
git status --short

如果当前工作区已有未提交改动，先确认这些改动不是别人的工作，再启动 Aider。

推荐方式：固化 Aider 配置

如果你经常使用 TokenHub，优先把模型和 Base URL 写进用户级 ~/.aider.conf.yml 或项目内 .aider.conf.yml：

model: openai/gpt-4.1
openai-api-base: __API_BASE_URL__/v1

项目内 .aider.conf.yml 适合提交非密钥默认值，例如模型和 openai-api-base。API Key 不建议写入 YAML，仍放在本机环境变量、系统钥匙串或团队密钥管理中：

在启动 Aider 的终端中设置：

export OPENAI_API_KEY="$TOKENHUB_API_KEY"

然后在项目目录启动：

aider --model openai/gpt-4.1

临时命令行验证

如果只是快速排查，也可以不写配置文件，直接显式传入 Base URL：

export OPENAI_API_KEY="$TOKENHUB_API_KEY"
export OPENAI_API_BASE="__API_BASE_URL__/v1"

aider --model openai/gpt-4.1 --openai-api-base "__API_BASE_URL__/v1"

这种方式只适合验证当前 Aider 版本是否能连到 TokenHub。团队教程或长期使用场景，建议回到 .aider.conf.yml 固化模型和地址。

验证

启动后先执行只读问题：

/ask 请总结这个仓库的目录结构，不要修改文件。

确认回答正常后，再把需要修改的文件加入上下文，并让 Aider 执行小范围改动。

常见问题

现象	处理方式
401	确认 `OPENAI_API_KEY` 等于 `TOKENHUB_API_KEY`。
404	确认 `OPENAI_API_BASE` 包含 `/v1`。
模型名解析失败	使用 `openai/<TokenHub Model ID>` 的形式。
改动范围太大	用 `/ask` 先讨论方案，再显式添加文件，避免一次性加载整个项目。
Git 状态混乱	使用 `git diff` 审阅，必要时手动回退 Aider 生成的单个文件改动。