Cài Claude Code với API giá rẻ: hướng dẫn A–Z cho macOS, Windows và Linux

Hướng dẫn cài và cấu hình Claude Code dùng API key Việt Nam: đặt ANTHROPIC_BASE_URL và AUTH_TOKEN, chọn model, kiểm soát chi phí, bảng xử lý lỗi 401/404 và cách cắm thêm Codex, Cursor, Cline, n8n.

Claude Code là trợ lý lập trình chạy thẳng trong terminal: nó đọc được cả kho mã nguồn của bạn, tự sửa nhiều file, chạy test và giải thích lỗi. Điểm vướng duy nhất với người dùng Việt Nam là phần tài khoản và thanh toán. Bài này hướng dẫn cách trỏ Claude Code sang một cổng API trong nước, trả tiền bằng VietQR, chạy được trên cả macOS, Windows và Linux — kèm phần xử lý những lỗi hay gặp nhất.

1. Cơ chế: vì sao đổi endpoint là đủ

Claude Code giao tiếp với máy chủ bằng giao thức Anthropic Messages. Nó không kiểm tra tên miền; nó chỉ đọc hai biến môi trường để biết gửi yêu cầu đi đâu và ký bằng khoá nào:

• ANTHROPIC_BASE_URL — địa chỉ máy chủ.
• ANTHROPIC_AUTH_TOKEN — khoá xác thực.

Vì cổng API của TaiKhoanGiaRe hiện thực đúng endpoint /v1/messages với cùng cấu trúc request và response, kể cả streaming và tool calling, nên Claude Code hoạt động y hệt bản gốc. Không cần vá, không cần bản build riêng, không cần proxy cục bộ.

2. Chuẩn bị

Bạn cần ba thứ:

1. Node.js 18 trở lên. Kiểm tra bằng node -v. Nếu chưa có, cài từ trang chủ Node hoặc qua trình quản lý gói của hệ điều hành.
2. Một tài khoản TaiKhoanGiaRe với API key dạng sk-tk-.... Tài khoản mới được tặng 50 credit, đủ để chạy thử vài chục lượt.
3. Một thư mục dự án để thử. Đừng bắt đầu bằng kho mã quan trọng nhất của bạn; hãy dùng một dự án phụ trong lần đầu.

3. Cài Claude Code

npm install -g @anthropic-ai/claude-code

Kiểm tra:

claude --version

Nếu terminal báo command not found dù npm cài thành công, thư mục global bin của npm chưa nằm trong PATH. Xem đường dẫn bằng npm config get prefix rồi thêm thư mục bin bên trong nó vào PATH.

4. Cấu hình trên macOS và Linux

Mở file khởi động shell — ~/.zshrc nếu bạn dùng zsh (mặc định trên macOS), ~/.bashrc nếu dùng bash — rồi thêm hai dòng:

export ANTHROPIC_BASE_URL="https://taikhoangiare.vn"
export ANTHROPIC_AUTH_TOKEN="sk-tk-..."

Nạp lại cấu hình rồi chạy thử:

source ~/.zshrc
cd duong/dan/den/du-an
claude

Chú ý: ANTHROPIC_BASE_URL không có hậu tố /v1. Claude Code tự thêm phần đó. Đây là lỗi phổ biến nhất và biểu hiện của nó là mọi yêu cầu trả về 404.

5. Cấu hình trên Windows

Trong PowerShell, đặt biến môi trường vĩnh viễn cho người dùng hiện tại:

setx ANTHROPIC_BASE_URL "https://taikhoangiare.vn"
setx ANTHROPIC_AUTH_TOKEN "sk-tk-..."

setx chỉ có tác dụng với các cửa sổ terminal mở sau đó. Hãy đóng PowerShell và mở lại, rồi kiểm tra:

echo $env:ANTHROPIC_BASE_URL
claude

Nếu bạn dùng WSL, hãy đặt biến bên trong WSL theo cách của Linux ở mục 4 — biến của Windows không tự truyền sang.

6. Kiểm tra trước khi đổ lỗi cho công cụ

Trước khi kết luận Claude Code hỏng, hãy xác nhận khoá và đường truyền bằng một lệnh curl trần. Lệnh này không tốn credit:

curl https://taikhoangiare.vn/v1/account \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Nếu trả về JSON có trường credits, phần tài khoản ổn. Tiếp theo thử một lượt chat thật:

curl https://taikhoangiare.vn/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":64,
       "messages":[{"role":"user","content":"chào"}]}'

Hai lệnh này tách bạch ba khả năng: sai khoá, sai endpoint, hoặc lỗi nằm ở phía cấu hình Claude Code.

7. Chọn model cho Claude Code

Claude Code mặc định dùng model mạnh nhất. Với công việc hằng ngày, bạn có thể tiết kiệm đáng kể bằng cách chỉ định model rẻ hơn:

export ANTHROPIC_MODEL="claude-sonnet-5"

Kinh nghiệm thực tế:

Bạn cũng có thể đổi model giữa phiên bằng lệnh /model ngay trong Claude Code, không cần thoát ra.

8. Kiểm soát chi phí

Claude Code tốn tiền nhiều hơn chat thông thường vì nó đọc file, chạy lệnh và lặp nhiều vòng. Vài thói quen giúp giảm hoá đơn rõ rệt:

• Chạy trong thư mục hẹp nhất có thể. Mở Claude Code ở gốc một monorepo nghĩa là nó phải quét rất nhiều thứ không liên quan.
• Dùng /clear giữa các nhiệm vụ khác nhau. Ngữ cảnh cũ được gửi lại mỗi lượt; giữ nó khi đã chuyển sang việc khác là trả tiền cho phần vô dụng.
• Viết file CLAUDE.md ở gốc dự án. Ghi sẵn cách chạy test, quy ước đặt tên, thư mục nào không được sửa. Claude Code đọc file này tự động và không phải dò lại mỗi phiên.
• Nói rõ phạm vi. "Sửa hàm parse_date trong utils/date.py" rẻ hơn nhiều so với "tìm xem tại sao ngày tháng hiển thị sai".
• Mở Bảng điều khiển sau vài phiên đầu. Mỗi lượt gọi hiện rõ model, số token và credit đã trừ, nên bạn biết chính xác thói quen nào đang tốn tiền.

9. Viết file CLAUDE.md cho dự án

Đây là khoản đầu tư mười phút cho lợi ích kéo dài nhiều tháng. Claude Code đọc file CLAUDE.md ở gốc kho mã trong mọi phiên làm việc, nên mọi thứ bạn viết ở đó không cần nhắc lại lần nào nữa. Một file tốt trả lời bốn câu hỏi mà bất kỳ người mới nào cũng sẽ hỏi.

# Dự án X

## Chạy và kiểm thử
- Cài phụ thuộc: `pnpm install`
- Chạy dev: `pnpm dev` (cổng 5173)
- Chạy test: `pnpm test` — luôn chạy trước khi báo hoàn thành
- Kiểm tra kiểu: `pnpm typecheck`

## Quy ước mã nguồn
- TypeScript strict, không dùng `any`
- Component đặt trong `src/components`, một file một component
- Gọi API qua `src/lib/api.ts`, không fetch trực tiếp trong component
- Thông báo cho người dùng viết bằng tiếng Việt, tên biến bằng tiếng Anh

## Không được sửa
- `src/generated/**` sinh tự động từ schema
- File migration đã chạy trên production

## Lưu ý
- Khoá API nằm trong `.env`, không bao giờ in ra log hoặc commit

Ba dòng quan trọng nhất trong file trên là lệnh chạy test, danh sách thư mục cấm sửa và quy tắc về khoá bí mật. Thiếu chúng, bạn sẽ mất thời gian rà soát đúng những thay đổi lẽ ra không nên xảy ra.

10. Làm việc an toàn với trợ lý viết code

Công cụ nào có quyền sửa file và chạy lệnh cũng cần một vài rào chắn. Không phải vì nó hay sai, mà vì hậu quả của một lần sai ở đúng chỗ là rất đắt.

• Nhánh riêng cho mỗi nhiệm vụ. Rà soát diff trên nhánh dễ hơn nhiều so với lục lại lịch sử trên nhánh chính.
• Đọc kỹ ba loại thay đổi: file migration cơ sở dữ liệu, logic thanh toán và mọi thứ liên quan tới xác thực hoặc phân quyền.
• Không đưa dữ liệu thật của khách hàng vào prompt. Nếu cần dữ liệu mẫu để gỡ lỗi, hãy tạo bản ẩn danh.
• Cẩn trọng với lệnh xoá. Khi công cụ đề xuất một lệnh có rm -rf, DROP hoặc --force, hãy đọc kỹ đường dẫn trước khi đồng ý.
• Giữ khoá ngoài mã nguồn. Biến môi trường và .gitignore, luôn luôn. Nếu khoá lỡ lộ, thu hồi trong Bảng điều khiển mất năm giây.

11. Bảng xử lý lỗi thường gặp

12. Codex, Cursor và các công cụ khác

Nguyên tắc y hệt, chỉ khác chỗ khai báo.

Codex CLI và Codex IDE đọc file ~/.codex/config.toml. Khai báo một provider mới rồi đặt nó làm mặc định, với khoá lấy từ biến môi trường.

Cursor: vào Settings → Models, bật OpenAI API Key, đặt Base URL là https://taikhoangiare.vn/v1 và dán khoá. Nhớ bấm Verify trước khi đóng cửa sổ.

Cline và Roo Code: chọn kiểu nhà cung cấp "OpenAI Compatible", điền base URL và khoá, rồi nhập thủ công tên model bạn muốn dùng.

n8n: tạo credential OpenAI tuỳ chỉnh với cùng base URL. Hữu ích khi bạn muốn tự động hoá quy trình mà không viết code.

Trang Kết nối trên website có hướng dẫn chi tiết từng ứng dụng, với lệnh sao chép sẵn theo hệ điều hành.

13. Vài thói quen làm việc đáng học

Claude Code mạnh nhất khi bạn coi nó như một đồng nghiệp mới vào dự án: giỏi, nhưng chưa biết quy ước của bạn.

• Yêu cầu nó đọc trước khi sửa. "Đọc module thanh toán rồi tóm tắt luồng xử lý" trước khi giao việc sửa sẽ cho kết quả tốt hơn hẳn.
• Giao từng việc một. Một yêu cầu gộp năm thay đổi thường cho ra một diff khó rà soát.
• Bắt nó chạy test. Nếu dự án có test, hãy nói rõ lệnh chạy; nó sẽ tự kiểm chứng thay vì đoán.
• Luôn làm việc trên nhánh riêng. Không phải vì công cụ nguy hiểm, mà vì rà soát diff trên nhánh dễ hơn rất nhiều.
• Đọc kỹ những thay đổi liên quan tới bảo mật, migration và thanh toán. Đây là ba chỗ mà một lỗi nhỏ đắt hơn toàn bộ thời gian tiết kiệm được.

14. Tóm lại

Toàn bộ việc cấu hình gói gọn trong hai biến môi trường. Sau đó, thứ quyết định trải nghiệm không còn là hạ tầng mà là cách bạn giao việc: phạm vi rõ ràng, ngữ cảnh sạch, model chọn theo độ khó, và một file CLAUDE.md viết tử tế. Với 50 credit miễn phí khi đăng ký, bạn có thể chạy thử toàn bộ quy trình trên trước khi quyết định nạp tiền.

← Về trang Blog