Hướng dẫn kết nối Claude Code với API bên thứ ba: cấu hình ANTHROPIC_BASE_URL và xử lý lỗi

Mặc định, Claude Code gửi mọi request đến API chính thức của Anthropic. Khi tuyến chính thức không ổn định từ mạng của bạn, hoặc bạn muốn quản lý key, thanh toán và chuyển đổi mô hình tập trung tại một nơi, việc trỏ Claude Code đến endpoint bên thứ ba tương thích Anthropic là giải pháp trực tiếp nhất. Bài viết này chỉ nói cấu hình thực tế: thay gì, xác thực thế nào, và khi lỗi thì kiểm tra từ đâu.

Hiểu trước: Claude Code là một "client"

Định nghĩa: Claude Code đọc một nhóm nhỏ biến môi trường để quyết định request đi đâu, xác thực bằng key nào, và chạy mô hình nào. Miễn sao endpoint đích implement đúng định dạng request/response của Anthropic Messages API, Claude Code hoạt động với nó y như với API chính thức — tool calling, streaming và phiên nhiều lượt phụ thuộc vào mức tương thích của endpoint.

Việc ghi đè base URL là năng lực được ghi trong tài liệu chính thức, không phải hack. EXAIV cung cấp endpoint tương thích Anthropic; xem trang cấu hình chính thức cho phiên bản ngắn gọn.

Các biến môi trường quan trọng

Cách 1: settings.json (khuyến nghị, bền vững)

Claude Code đọc biến môi trường từ ~/.claude/settings.json, áp dụng cho mọi session và dễ chuẩn hóa cho cả nhóm. Ví dụ với EXAIV:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://exaiv.com/api/ai/v1/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_EXAIV_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "model": "claude-opus-5-5"
}

Khởi động lại claude sau khi lưu. Để giới hạn trong một dự án, đặt cấu trúc tương tự vào .claude/settings.json ở thư mục gốc dự án.

Cách 2: biến môi trường tạm thời (kiểm tra nhanh)

Không cần sửa file — export trong shell hiện tại:

export ANTHROPIC_BASE_URL="https://exaiv.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_EXAIV_API_KEY"

# Kiểm tra tối thiểu
claude --print "say hi"

Có phản hồi nghĩa là endpoint đã hoạt động. Để dùng lâu dài, đưa hai dòng export vào ~/.zshrc hoặc ~/.bashrc — nhưng điều đó ảnh hưởng mọi lệnh claude. Nếu bạn còn subscription chính thức, nên dùng settings.json cấp dự án để tránh tiêu nhầm credit bên thứ ba.

Xem mô hình khả dụng ở đâu

Endpoint quyết định có những mô hình nào. Danh mục đầy đủ của EXAIV (Claude, GPT, Gemini, DeepSeek, Kimi…) ở trang mô hình; chuyển mô hình trong Claude Code qua ANTHROPIC_MODEL hoặc lệnh /model trong phiên.

Xử lý sự cố: kiểm tra theo thứ tự cố định

Ai nên kết nối API bên thứ ba

Không phải ai dùng Claude Code cũng cần cấu hình này. Ba nhóm hưởng lợi rõ nhất:

Người có tuyến chính thức không ổn định. Ở một số khu vực, truy cập endpoint chính thức hay bị timeout — mất kết nối giữa lúc code là giết năng suất thật sự. Đi qua gateway gần hơn giúp đường ngắn lại và phiên code liền mạch hơn rõ rệt.

Người dùng nặng. Claude Code tiêu token nhiều hơn chat thông thường rất nhiều — mỗi lần gọi tool, mỗi lần đọc file đều tính vào context. Nếu bạn dùng hằng ngày, tính theo mức tiêu thụ với đơn giá thấp hơn có thể chênh lệch chi phí tháng đáng kể. Nên ước lượng bằng mức dùng thực của bạn, không phải con số marketing của bất kỳ bên nào.

Nhóm muốn quản lý tập trung. Khi nhóm chạy cả Claude Code, Cursor và script nội bộ, trỏ mọi công cụ về một gateway với một bộ key và một hóa đơn dễ kiểm soát ngân sách hơn nhiều so với mỗi công cụ một tài khoản. EXAIV có cả endpoint tương thích OpenAI và Anthropic, một key phủ hai giao thức.

Chi phí tính thế nào: bắt đầu từ gói trải nghiệm

EXAIV tính theo credits trả theo mức dùng: mua gói một lần, mỗi lần gọi trừ theo đơn giá mô hình, không có phí subscription. Gói thấp nhất là gói nhỏ nhất được liệt kê trên trang giá — đủ cho một vòng xác thực thực tế:

1. Đăng ký và tạo API key trong console
2. Cấu hình Claude Code như bài viết
3. Chạy công việc thường ngày thật 1–2 giờ, quan sát đường tiêu thụ credit trong console
4. Ước tính chi phí tháng, rồi quyết định nâng gói hay không

Mỗi mô hình một đơn giá, giá chính xác nằm ở trang giá theo thời gian thực — vì thế bài này không ghi con số "mỗi lần gọi bao nhiêu" cố định: giá thay đổi theo bên phát hành, trang real-time luôn chính xác nhất.

Dùng trong nhóm: một cấu hình, không lệch pha

Bẫy lớn nhất của nhóm là mỗi người một kiểu cấu hình. Cách làm hiệu quả:

Đưa template settings.json vào repo. Để file mẫu không có key ở thư mục gốc dự án; người mới copy rồi điền key của mình. Năm phút là xong.

Phát key theo cá nhân, không dùng chung. Mỗi người dùng key riêng, mức tiêu thụ hiện rõ trong console. Có vấn đề truy được về người, người rời nhóm chỉ thu hồi một key.

Dùng wrapper script tách bối cảnh. Nếu thành viên vẫn giữ subscription chính thức, viết một script alias trỏ sang cấu hình cấp dự án để hai bên không đốt nhầm quota của nhau.

Nền tảng an toàn

API key là ví tiền. Bốn nguyên tắc:

• Key không bao giờ vào git. File cấu hình có key thật phải nằm ngoài version control; trong repo chỉ có template
• Luân chuyển định kỳ. Tạo key mới trong console theo chu kỳ, thu hồi key cũ; nghi lộ lập tức đổi
• Đặc quyền tối thiểu. Không dán key vào log CI, code frontend hay cuộc chat
• Theo dõi bất thường. Credit tiêu nhanh khác thường thì thu hồi key trước, điều tra sau

Bảng thiết lập nhanh theo hệ điều hành

Mọi thứ còn lại — ánh xạ mô hình, thứ tự xử lý lỗi, nguyên tắc bảo mật — giống nhau trên mọi nền tảng.

Vì sao ánh xạ tier quan trọng hơn bạn nghĩ

Claude Code không chỉ gọi mô hình chính bạn chọn. Ở nền, nó phát nhiều request nhỏ — tóm tắt kết quả tool, viết commit message, tra cứu nhanh — và các request đó được gắn tier Sonnet hoặc Haiku. Nếu endpoint của bạn không có đúng mô hình mặc định cho tier đó, các cuộc gọi sẽ thất bại hoặc fallback khó lường.

Đó là điều ANTHROPIC_DEFAULT_SONNET_MODEL và ANTHROPIC_DEFAULT_HAIKU_MODEL giải quyết: chuyển hướng request có gắn tier sang mô hình mà endpoint thực sự có. Mẫu đơn giản và ổn nhất là đặt cả hai bằng mô hình chính của bạn; gắn tier Haiku vào mô hình rẻ hơn là tối ưu phổ biến khi mọi thứ đã chạy ổn. Cùng logic áp dụng cho gateway: xem trang mô hình để biết có gì, rồi ánh xạ tier sang mô hình bạn chắc chắn tồn tại.

Tinh chỉnh timeout và mạng

Hai biến giải quyết phần lớn phàn nàn về kết nối:

• API_TIMEOUT_MS — các lượt agent phức tạp có thể hợp pháp kéo dài vài phút; timeout client quá ngắn sẽ giết những request lẽ ra thành công. Nếu thấy lượt bị cắt mà không có lỗi, hãy tăng nó lên.
• Proxy chồng lấn — nếu shell cũng đặt HTTP_PROXY/HTTPS_PROXY, request có thể vòng qua proxy cục bộ trước khi tới gateway. Khi base URL đúng mà vẫn không kết nối được, hãy thử với các biến proxy được bỏ trước khi đổi thứ khác.

Không biến nào bắt buộc theo mặc định — đây là hai núm đầu tiên để vặn khi cấu hình đúng mà đường mạng sai.

FAQ

Đọc thêm

• Trang cấu hình Claude Code — bản nhanh trên site
• Anthropic Messages API reference — định dạng request/response
• Bảng giá — giá mô hình theo thời gian thực