在 Windows 上使用 Aider + 阿里云 Qwen 实现本地 AI 编程助手（避坑指南）

📋 目录

1. 背景介绍
2. 概念澄清
3. 完整安装步骤
4. 常见问题与解决方案
5. 最佳实践

---

背景介绍

在使用阿里云通义千问（Qwen）进行本地 AI 辅助编程时，很多人会遇到各种问题。本文详细记录了从环境配置到实际使用的全过程，帮你避开所有坑。

---

概念澄清

⚠️ 重要：区分两个产品

网页版 Qwen Coder：

• 需要 GitHub 授权
• 只能连接 GitHub 仓库
• 国内访问 GitHub 不稳定
• ❌ 不推荐国内用户使用

本地 Aider + Qwen API：

• 无需 GitHub 授权
• 可操作本地 Git 仓库
• 支持 Gitee 等国内平台
• ✅ 推荐使用此方案

---

完整安装步骤

步骤 1：获取阿里云 API Key

1. 注册/登录阿里云账号（新用户福利）
   (💡 提示：通过此链接注册，新用户可领取免费额度，并享受首购 9 折优惠。如果你已有账号，直接登录即可，系统会自动绑定优惠。)
2. 登录成功后，请直接访问百炼控制台
3. 登录/注册账号（支持支付宝登录）
4. 开通"模型服务灵积"（新用户有大量免费额度）
5. 进入 API-KEY 页面
   6 点击 创建新的 API-KEY
6. 重要：复制并保存 Key（只显示一次！）

创建配置：

• 归属业务空间：默认业务空间
• 描述：本地编程工具调用
• 权限：全部

---

步骤 2：安装 Aider（解决下载慢问题）

问题：Aider 是国外开源项目，直接用 pip 下载非常慢

解决方案：使用清华镜像源

pip install aider-chat -i https://pypi.tuna.tsinghua.edu.cn/simple

验证安装：

aider --version

---

步骤 3：创建启动脚本（bat 文件）

在你的项目根目录（如 D:\PythonProject\AI_workflow\）创建 start_aider.bat：

@echo off
chcp 65001 >nul
title Aider 启动器

echo 正在配置环境变量...
set OPENAI_API_KEY=sk-你的API_KEY_粘贴在这里
set OPENAI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1

echo 激活虚拟环境...
call D:\PythonProject\AI_workflow\.venv\Scripts\activate.bat

echo 正在启动 Aider...
start cmd /k "cd /d D:\PythonProject\AI_workflow && aider --model openai/qwen-plus --no-show-model-warnings"

⚠️** 关键配置点**：

1. OPENAI_API_KEY：替换为你的真实 API Key
2. OPENAI_API_BASE：阿里云兼容模式地址（必须）
3. 虚拟环境路径：替换为你的实际路径
4. 工作目录：建议设为项目根目录
5. 模型名称：必须用 openai/qwen-plus（不是 qwen/qwen-plus）

---

步骤 4：配置 PyCharm 外部工具（可选但推荐）

1. 打开设置：File → Settings
2. 找到外部工具：Tools → External Tools
3. 添加新工具：点击 + 号

配置参数：

• Name：Start Aider
• Group：外部工具
• Program：$ProjectFileDir$\start_aider.bat
• Arguments：（留空）
• Working directory：$ProjectFileDir$

高级选项：

• ✅ 在执行后同步文件
• ✅ 打开工具输出的控制台

---

步骤 5：开始使用

启动方式：

1. 在 PyCharm 中：Tools → External Tools → Start Aider
2. 或在 Terminal 输入：.\start_aider.bat

基本命令：

# 添加单个文件
/add Client_Project/main.py

# 添加多个文件
/add Client_Project/*.py

# 批量添加（递归）
/add Client_Project/**/*.py

# 移除文件
/drop Client_Project/main.py

# 退出
/exit

示例对话：

请分析 Client_Project 目录下的所有 Python 文件，生成一份项目文档

---

常见问题与解决方案

问题 1：pip 下载 Aider 极慢或失败

错误现象：

Collecting aider-chat
（卡住不动）

解决方案：

pip install aider-chat -i https://pypi.tuna.tsinghua.edu.cn/simple

---

问题 2：启动后提示 'aider' is not recognized

错误现象：

'aider' is not recognized as an internal or external command

原因：没有激活虚拟环境

解决方案：在 bat 文件中添加激活命令

call D:\你的路径\.venv\Scripts\activate.bat

---

问题 3：模型名称错误

错误现象：

litellm.BadRequestError: LLM Provider NOT provided
You passed model=qwen/qwen-plus

原因：模型名称格式不对

解决方案：使用 openai/qwen-plus 而不是 qwen/qwen-plus

aider --model openai/qwen-plus

---

问题 4：环境变量失效

错误现象：每次重启都要重新配置

原因：使用 $env: 设置的是临时环境变量

解决方案：

• 临时方案：每次在 bat 文件中设置
• 永久方案：在 Windows 系统环境变量中设置
  1. Win + S 搜索"环境变量"
  2. 新建用户变量：
     • OPENAI_API_KEY = sk-xxx
     • OPENAI_API_BASE = https://dashscope.aliyuncs.com/compatible-mode/v1
  3. 重启 PyCharm

---

问题 5：Aider 无法读取项目文件

错误现象：

我目前没有收到 Client_Project 目录下的任何 Python 文件内容

原因：Aider 不会自动扫描所有文件

解决方案：

1. 方法一：使用 /add 命令手动添加

/add Client_Project/*.py

2. 方法二：直接描述需求

请读取 Client_Project 目录下的所有 Python 文件并分析

3. 方法三：创建 .aider.conf.yml 配置文件

---

问题 6：Can’t initialize prompt toolkit

错误现象：

Can't initialize prompt toolkit: No Windows console found

原因：PyCharm 外部工具不是标准 CMD 控制台

解决方案：

• 方案一：忽略警告（不影响功能）
• 方案二：修改 bat 文件，用独立窗口启动

start cmd /k "cd /d 项目路径 && aider --model openai/qwen-plus"

---

问题 7：多层目录结构如何管理

错误现象：项目有多个子目录，不知道如何配置

解决方案：

1. 从根目录启动：在 AI_workflow 目录启动
2. 按需添加文件：

/add Client_Project/main.py
/add Admin_Project/config.py

3. 不需要每个目录都配置启动项

---

最佳实践

1. 项目结构建议

D:\PythonProject\AI_workflow\
├── .venv/                    # 虚拟环境
├── Client_Project/           # 子项目1
│   ├── main.py
│   └── config.py
├── Admin_Project/            # 子项目2
│   └── admin.py
├── start_aider.bat          # 启动脚本（根目录）
└── .aider.conf.yml          # Aider 配置文件（可选）

2. 启动脚本最佳配置

@echo off
chcp 65001 >nul
title Aider - AI 编程助手

echo ========================================
echo   Aider + Qwen AI 编程助手
echo ========================================
echo.

echo [1/3] 配置环境变量...
set OPENAI_API_KEY=sk-你的API_KEY
set OPENAI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1

echo [2/3] 激活虚拟环境...
call %~dp0.venv\Scripts\activate.bat

echo [3/3] 启动 Aider...
echo.
start cmd /k "cd /d %~dp0 && aider --model openai/qwen-plus --no-show-model-warnings"

echo Aider 已在独立窗口启动，请查看新窗口！
pause

3. 常用命令速查

命令	说明
/add 文件	添加文件到上下文
/drop 文件	从上下文移除
/git	执行 git 命令
/undo	撤销上次修改
/clear	清空对话历史
/exit	退出 Aider

4. 费用控制建议

1. 使用免费额度：阿里云新用户有大量免费额度
2. 选择合适模型：
   • qwen-plus：性价比高，适合日常开发
   • qwen-max：能力强，适合复杂任务
3. 避免重复请求：Aider 会缓存上下文
4. 监控用量：在阿里云控制台查看使用情况

---

总结

✅ 优势

• 无需 GitHub，支持本地 Git 和 Gitee
• 国内访问稳定，速度快
• 免费额度充足
• 完全本地化操作

⚠️ 注意事项

1. API Key 要保密，不要泄露
2. 模型名称必须用 openai/qwen-plus
3. 需要手动添加文件到上下文
4. 虚拟环境路径要正确

🚀 快速开始

1. 获取 API Key
2. pip install aider-chat -i https://pypi.tuna.tsinghua.edu.cn/simple
3. 创建 bat 启动脚本
4. 开始 coding！

---

希望这份文档能帮助你顺利使用 Aider + Qwen 进行 AI 辅助编程！

如有问题，欢迎在评论区留言讨论。