Tài liệu
← Toàn bộ tài liệu

Tài liệu

ANTHROPIC_BASE_URL

Biến môi trường trỏ Claude Code và Anthropic SDK đến endpoint khác api.anthropic.com — tham chiếu đầy đủ các biến, cách thiết lập cho từng client và hai lỗi thường gặp gây ra hầu hết sự cố.

ANTHROPIC_BASE_URL cho Anthropic SDK và Claude Code biết cần gửi yêu cầu API đến máy chủ nào, thay cho mặc định https://api.anthropic.com. Đặt biến này thành một origin không có đường dẫn — client tự nối thêm /v1/messages — và dùng cùng ANTHROPIC_AUTH_TOKEN, biến này sẽ trở thành header Authorization: Bearer.

~/.zshrc
# The origin only — no trailing /v1, no trailing slash.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

Sau đó, hãy mở terminal mới: Claude Code và SDK đọc các biến này khi tiến trình khởi động, nên phiên đang chạy sẽ tiếp tục dùng endpoint cũ.

Không thêm /v1 vào ANTHROPIC_BASE_URL. Các client Anthropic tự nối thêm đường dẫn, vì vậy https://api.kunavo.com/v1 tạo yêu cầu đến /v1/v1/messages và mọi lệnh gọi đều trả về lỗi 404. OpenAI SDK dùng quy ước ngược lại và có yêu cầu /v1 trong base_url — khác biệt này là lỗi cấu hình phổ biến nhất ở đây.

Từng biến và chức năng

Danh sách đầy đủ các biến Claude Code đọc có trong tài liệu tham chiếu biến môi trường của Anthropic. Đây là những biến cần biết khi chuyển hướng endpoint.

BiếnGiá trịChức năng
ANTHROPIC_BASE_URLhttps://api.kunavo.comOrigin mà mọi yêu cầu được gửi đến. Không có đường dẫn, không có dấu gạch chéo ở cuối.
ANTHROPIC_AUTH_TOKENsk-kn-…Thông tin xác thực được gửi qua Authorization: Bearer. Đây là loại gateway cần.
ANTHROPIC_API_KEYsk-ant-…Thông tin xác thực được gửi qua header x-api-key, theo định dạng api.anthropic.com yêu cầu. Chỉ đặt biến này HOẶC token ở trên, không đặt cả hai.
ANTHROPIC_MODELclaude-sonnet-5Mô hình chính Claude Code dùng cho cuộc hội thoại.
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5-5Model đứng sau bí danh opus (/model opus). Mặc định riêng của Claude Code là Opus mới nhất, vì vậy hãy ghim vào một model được endpoint cung cấp. Opus 5.5 yêu cầu Claude Code v2.1.280 trở lên.
ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-5Model đứng sau bí danh sonnet (/model sonnet). Theo mặc định, bí danh này yêu cầu Sonnet 5.5, vì vậy hãy ghim vào một model Sonnet được endpoint cung cấp.
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5Mô hình đứng sau bí danh haiku (/model haiku, các tác tử con được đặt dùng haiku), đồng thời là mô hình Claude Code dùng cho các lệnh gọi chạy nền của chính nó. Từ v2.1.293, bí danh này yêu cầu Haiku 5.5, vì vậy hãy cố định nó vào một mô hình Haiku mà endpoint cung cấp.
Tên mô hình phải là tên mà endpoint thực sự cung cấp. Trỏ đến gateway nhưng để nguyên một model id không có trên đó là lỗi phổ biến thứ hai; lỗi này hiển thị dưới dạng 404 model_not_found, chứ không phải lỗi xác thực. Model id của Kunavo được liệt kê trên trang mô hình và được trả về trực tiếp qua GET /v1/models.

Thiết lập cho từng client

Claude Code

Thêm các lệnh export vào cấu hình shell mà Claude Code khởi chạy cùng, rồi mở terminal mới. Không cần thay đổi cách cài đặt hay quy trình làm việc.

~/.zshrc
# ~/.zshrc (or ~/.bashrc) — applies to every Claude Code session.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models this endpoint serves. Claude Code's default and its opus/sonnet
# aliases follow Anthropic's newest models, which may not be served here —
# unpinned, those calls 404.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Chạy /status bên trong Claude Code để xác nhận endpoint mà phiên hiện tại đang sử dụng. Hướng dẫn từng bước, bao gồm cả nơi tạo khóa: đặt API key trong Claude Code.

Anthropic SDK (Python / TypeScript)

Các SDK đọc cùng những biến môi trường này; bạn cũng có thể truyền cả hai cài đặt vào hàm khởi tạo — hữu ích khi một tiến trình kết nối đến nhiều endpoint.

anthropic_sdk.py
from anthropic import Anthropic

# The Anthropic SDK appends /v1/messages, so pass the origin — not .../v1.
client = Anthropic(
    base_url="https://api.kunavo.com",
    auth_token="sk-kn-...",          # sets the Authorization: Bearer header
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "Say hi"}],
)
print(msg.content[0].text)

OpenAI SDK — quy ước còn lại

Nếu mã của bạn đã dùng giao thức OpenAI, bạn không cần ANTHROPIC_BASE_URL. Trỏ base_url đến đường dẫn tương thích với OpenAI — lần này có /v1 — rồi gọi cùng các mô hình Claude qua /v1/chat/completions.

openai_sdk.py
from openai import OpenAI

# The OpenAI SDK is the other convention: it wants the /v1 in the base_url.
client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Say hi"}],
)
print(r.choices[0].message.content)

Cline, Roo Code, Kilo Code, Cursor

Các agent trong trình soạn thảo thường cung cấp hai cài đặt tương tự ngay trong giao diện thay vì qua biến môi trường: trường "base URL" hoặc "custom endpoint" và trường API key. Các quy tắc vẫn vậy — dùng origin không có /v1 cho nhà cung cấp theo kiểu Anthropic, và nhập khóa vào trường API key. Hướng dẫn cho từng client: Cline, Roo Code, Kilo Code.

Xác nhận thiết lập hoạt động

Một lệnh curl xác nhận đồng thời URL cơ sở và thông tin xác thực. Phản hồi 200 kèm nội dung JSON nghĩa là cả hai đều đúng.

# 200 and a JSON body means the base URL and the token are both right.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

# In Claude Code, /status shows the endpoint the session is actually using.

Khi thiết lập không hoạt động

Triệu chứngNguyên nhânCách khắc phục
Mọi yêu cầu đều trả về 404Đã thêm /v1 ở cuối ANTHROPIC_BASE_URLChỉ đặt origin. Client tự nối thêm /v1/messages.
401 / invalid x-api-keyĐặt thông tin xác thực thành ANTHROPIC_API_KEY trong khi endpoint xác thực bằng bearer tokenThay vào đó, hãy dùng ANTHROPIC_AUTH_TOKEN — xem giải thích đầy đủ sự khác biệt
Vẫn đang gửi yêu cầu đến api.anthropic.comXuất biến sau khi phiên bắt đầu hoặc đặt biến trong cấu hình mà shell không đọcMở một terminal mới; xác nhận bằng echo $ANTHROPIC_BASE_URL trong cùng shell khởi chạy client.
404 model_not_foundModel id không được endpoint cung cấpĐặt ANTHROPIC_MODEL thành một id trong GET /v1/models
Claude Code báo số dư tín dụng quá thấpYêu cầu đã đến endpoint và được tính phí vào khóa, không phải gói đăng kýĐúng như dự kiến — nạp thêm tiền hoặc bỏ đặt token để quay lại dùng gói đăng ký. Xem lỗi không đủ tín dụng

Ảnh hưởng đến gói đăng ký Pro hoặc Max

Khi một biến thông tin xác thực được đặt, Claude Code tính phí vào khóa thay vì gói đăng ký đã đăng nhập: các giới hạn của gói không còn áp dụng và chi phí sử dụng được tính cho chủ sở hữu khóa. Bản thân gói đăng ký không bị ảnh hưởng — hãy xóa biến này, mở terminal mới, Claude Code sẽ quay lại dùng gói. Hai hình thức này không bao giờ kết hợp; cách tính chi phí giữa chúng được giải thích trong giá Claude Code.

Tiếp theo

Câu hỏi thường gặp

ANTHROPIC_BASE_URL là gì?

ANTHROPIC_BASE_URL là biến môi trường cho Anthropic SDK và Claude Code biết cần gửi yêu cầu API đến máy chủ nào, thay cho mặc định https://api.anthropic.com. Đặt biến này thành origin không có đường dẫn — client tự nối thêm /v1/messages — và dùng cùng ANTHROPIC_AUTH_TOKEN, biến này sẽ trở thành header Authorization: Bearer. Mọi endpoint tương thích với Anthropic đều dùng được; trên Kunavo, giá trị là https://api.kunavo.com.

ANTHROPIC_BASE_URL có nên bao gồm /v1 không?

Không. ANTHROPIC_BASE_URL chỉ nhận origin — https://api.kunavo.com, không phải https://api.kunavo.com/v1 — vì Anthropic SDK và Claude Code tự nối thêm đường dẫn /v1/messages. Nếu thêm /v1, yêu cầu sẽ được gửi đến /v1/v1/messages và trả về lỗi 404. OpenAI SDK dùng quy ước ngược lại và cần có /v1 trong base_url; vì vậy, cùng một gateway được ghi theo hai cách khác nhau tùy client gọi đến.

ANTHROPIC_AUTH_TOKEN và ANTHROPIC_API_KEY khác nhau thế nào?

ANTHROPIC_AUTH_TOKEN gửi thông tin xác thực qua header Authorization: Bearer, còn ANTHROPIC_API_KEY gửi qua header x-api-key mà api.anthropic.com yêu cầu. Gateway xác thực bằng bearer token cần ANTHROPIC_AUTH_TOKEN; đặt ANTHROPIC_API_KEY thay vào đó là nguyên nhân phổ biến nhất gây lỗi 401 sau khi đổi ANTHROPIC_BASE_URL. Chỉ đặt một trong hai, không đặt cả hai — nếu cùng được khai báo, hành vi sẽ tùy thuộc vào phiên bản client.

Làm cách nào để đặt URL cơ sở tùy chỉnh trong Claude Code?

Xuất ANTHROPIC_BASE_URL và ANTHROPIC_AUTH_TOKEN trong cấu hình shell mà Claude Code khởi chạy cùng (~/.zshrc hoặc ~/.bashrc), sau đó mở terminal mới để các biến được kế thừa. Claude Code đọc chúng khi khởi động, nên phiên đang chạy sẽ tiếp tục dùng endpoint cũ. Chạy /status bên trong Claude Code để xác nhận endpoint mà phiên hiện tại đang sử dụng.

Đặt ANTHROPIC_BASE_URL có vô hiệu hóa gói đăng ký Claude Pro hoặc Max của tôi không?

Khi một biến thông tin xác thực như ANTHROPIC_AUTH_TOKEN được đặt, Claude Code tính phí vào khóa thay vì gói đăng ký đã đăng nhập; do đó, các giới hạn của gói Pro và Max không còn áp dụng và chi phí sử dụng được tính cho chủ sở hữu khóa. Bản thân gói đăng ký không bị ảnh hưởng hay hủy — hãy xóa biến này và mở terminal mới, Claude Code sẽ quay lại dùng gói đăng ký.