Hướng dẫn cấu hình Aider với Beeknoee

Aider là gì?

Aider là công cụ AI pair programming chạy trong terminal — tương tự Claude Code nhưng hỗ trợ nhiều model providers. Aider nổi bật với khả năng chỉnh sửa nhiều file, tích hợp Git (tự động commit), và architect mode để thiết kế trước khi code.

💡 Aider sử dụng OpenAI-compatible API — chỉ cần set OPENAI_API_BASE và OPENAI_API_KEY của Beeknoee là dùng được ngay.

Yêu cầu

• Python 3.9+ (kiểm tra: python --version)
• Git (Aider tích hợp sâu với Git)
• API Key từ Beeknoee Platform

📌 Bước 1: Tạo API Key

1. Truy cập https://platform.beeknoee.com/api-keys
2. Đăng nhập bằng tài khoản Google
3. Nhấn "Tạo API Key"
4. Copy API Key (dạng sk-bee-xxxx...)

⚠️ API key chỉ hiển thị 24 giờ đầu — copy và lưu ngay!

📌 Bước 2: Cài đặt Aider

Aider khuyến nghị cài bằng aider-install — nó tự tạo môi trường riêng và tự lo phiên bản Python, tránh xung đột với các gói khác trên máy:

python -m pip install aider-install
aider-install

# Dùng uv (nhanh, khuyến nghị nếu bạn đã có uv)
uv tool install --force --python python3.12 --with pip aider-chat@latest

# Dùng pipx
pipx install aider-chat

Kiểm tra cài đặt thành công:

aider --version

⚠️ Cách cũ pip install aider-chat vẫn chạy được nhưng không còn là cách khuyến nghị — cài thẳng vào Python hệ thống dễ gây xung đột thư viện. Nếu đang dùng cách này, bạn không bắt buộc phải đổi.

📌 Bước 3: Cấu hình Beeknoee API

Aider cung cấp 3 cách cấu hình — chọn cách phù hợp nhất với bạn:

Cách 1: Biến môi trường (Khuyên dùng)

export OPENAI_API_BASE=https://platform.beeknoee.com/v1
export OPENAI_API_KEY=sk-bee-YOUR_API_KEY

echo 'export OPENAI_API_BASE=https://platform.beeknoee.com/v1' >> ~/.bashrc
echo 'export OPENAI_API_KEY=sk-bee-YOUR_API_KEY' >> ~/.bashrc
source ~/.bashrc

$env:OPENAI_API_BASE = "https://platform.beeknoee.com/v1"
$env:OPENAI_API_KEY = "sk-bee-YOUR_API_KEY"

[System.Environment]::SetEnvironmentVariable("OPENAI_API_BASE", "https://platform.beeknoee.com/v1", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-bee-YOUR_API_KEY", "User")

Cách 2: File .env trong thư mục dự án

Tạo file .env ở thư mục root project:

OPENAI_API_BASE=https://platform.beeknoee.com/v1
OPENAI_API_KEY=sk-bee-YOUR_API_KEY

💡 Nhớ thêm .env vào .gitignore để không commit API key!

Cách 3: File cấu hình .aider.conf.yml

Tạo file .aider.conf.yml ở thư mục home (~) hoặc thư mục project:

openai-api-base: https://platform.beeknoee.com/v1
openai-api-key: sk-bee-YOUR_API_KEY
model: openai/claude-sonnet-4-6

📌 Bước 4: Chạy Aider

Mở terminal mới (để env vars có hiệu lực), rồi:

cd /path/to/your/project
aider --model openai/claude-sonnet-4-6

⚠️ Khi dùng Beeknoee, cần thêm prefix openai/ trước model ID: openai/claude-sonnet-4-6, openai/deepseek/deepseek-v3.2, v.v.

📌 Bước 5: Sử dụng

Lệnh phổ biến trong Aider

Ví dụ phiên làm việc

# Thêm files vào context
> /add src/api.py src/models.py

# Yêu cầu AI thay đổi code
> Add a new endpoint POST /users that creates a user with email and password validation

# Aider sẽ đề xuất thay đổi → chọn y (accept) hoặc n (reject)

# Commit thay đổi
> /commit

📌 Các chế độ nâng cao

Auto-commits

aider --model openai/claude-sonnet-4-6 --auto-commits

AI tự động commit sau mỗi thay đổi thành công.

Architect Mode

aider --model openai/claude-sonnet-4-6 --architect

AI tập trung vào thiết kế cấu trúc trước, sau đó mới viết code.

Watch Mode

aider --model openai/claude-sonnet-4-6 --watch

Aider tự động reload khi file thay đổi.

Models khuyên dùng với Aider

💡 Lấy Model ID chính xác tại trang Models trên Dashboard rồi ghép sau openai/. Mẹo: dùng Claude Sonnet cho refactoring lớn, DeepSeek cho sửa lỗi nhỏ để tối ưu chi phí.

🆓 Models miễn phí qua BeeSynapse

Khi đã kết nối email tại trang BeeSynapse Integrations, hệ thống tự động ưu tiên free quota:

Danh sách model free thay đổi theo quota nhà cung cấp — xem chính xác tại trang BeeSynapse Integrations. Bạn không cần thay đổi gì — Beeknoee tự route qua free quota trước, hết quota mới trừ VND.

Xử lý lỗi

"Connection refused" hoặc "Network error"

• Kiểm tra OPENAI_API_BASE đúng: https://platform.beeknoee.com/v1
• Đảm bảo URL kết thúc bằng /v1

"Unauthorized" hoặc "Invalid API key"

• Kiểm tra OPENAI_API_KEY đã set đúng:

  echo $OPENAI_API_KEY
  

• Kiểm tra key bắt đầu bằng sk-bee-
• Kiểm tra key chưa bị thu hồi tại API Keys

"Model not found"

• Đảm bảo dùng prefix openai/ trước model ID: openai/claude-sonnet-4-6 ✅, claude-sonnet-4-6 ❌
• Kiểm tra Model ID tại Text Models

Aider không tìm thấy file

• Chạy aider từ thư mục root của project (nơi có .git)
• Dùng /add để thêm file trước khi yêu cầu AI thay đổi

So sánh Aider vs Claude Code

HOÀN TẤT! 🎉

Cần hỗ trợ thêm? Sử dụng Support Chat (góc dưới phải trên platform) hoặc liên hệ qua email.