Hướng dẫn kết nối Claude Code với trung gian: Cấu hình tác nhân terminal và Base URL

I. Claude Code là gì

Claude Code là tác nhân (agent) lập trình trên terminal (CLI) chính thức từ Anthropic, cho phép bạn đọc/ghi mã nguồn, chạy lệnh và thực hiện các tác vụ trực tiếp trong terminal. Nó đọc nguyên bản các biến môi trường như ANTHROPIC_BASE_URL và ANTHROPIC_API_KEY, giúp bạn dễ dàng trỏ tới gateway trung gian và sử dụng khóa (key) cũng như hạn mức của mình để vận hành.

II. Cài đặt Claude Code

Yêu cầu Node.js (khuyến nghị phiên bản 18 trở lên), sau đó cài đặt toàn cục (global):

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

Sau khi cài đặt, hãy nhập claude vào terminal để khởi động; sử dụng /model hoặc claude --model … để chuyển đổi mô hình.

III. Cấu hình biến môi trường

Windows (PowerShell)

$env:ANTHROPIC_BASE_URL="https://www.relay-api.com"
$env:ANTHROPIC_API_KEY="sk-khóa_của_bạn"
$env:ANTHROPIC_MODEL="claude-sonnet-5"
claude

macOS / Linux (bash / zsh)

export ANTHROPIC_BASE_URL="https://www.relay-api.com"
export ANTHROPIC_API_KEY="sk-khóa_của_bạn"
export ANTHROPIC_MODEL="claude-sonnet-5"
claude

Lưu ý: ANTHROPIC_API_KEY sẽ được truyền dưới dạng header yêu cầu, ANTHROPIC_BASE_URL dùng để ghi đè điểm cuối API mặc định, chỉ cần trỏ tới cổng vào Anthropic của trang web này là được.

IV. Bảng tham chiếu địa chỉ giao diện (API)

Nhóm mô hình	Cổng vào (Base URL)	Giao thức
Claude / Anthropic	https://www.relay-api.com	Anthropic Messages
GPT / OpenAI	https://www.relay-api.com/v1	OpenAI Chat Completions
Gemini	https://www.relay-api.com/v1beta	Google generateContent

V. Khắc phục sự cố thường gặp

Hiện tượng	Xử lý
401 / 403	Khóa không hợp lệ, chưa kích hoạt hoặc không đủ số dư; xác nhận sk- chính xác và nạp tiền.
404 / Mô hình không khả dụng	Tên mô hình không khớp với slug của nền tảng, hoặc mô hình chưa được kích hoạt; kiểm tra lại ID mô hình.
Unknown model	ID mô hình phải chính xác (bao gồm chữ hoa/thường), kiểm tra tại mục Model Plaza.
Hết thời gian chờ (Timeout)	Với các tác vụ dài, có thể tăng thời gian chờ; thử lại nếu mạng không ổn định.

Khuyến nghị bảo mật: Không để lộ khóa trong các kho mã nguồn công khai, hãy sử dụng .env hoặc biến môi trường; các tác vụ tạo nội dung tiêu tốn nhiều token, hãy chú ý số dư, bạn có thể kiểm tra mỗi lượt gọi trong "Nhật ký sử dụng".

Giải thích về Base URL: Trang web này chấp nhận cả /v1beta/models/... và /v1beta/v1beta/models/... (cũng như /v1/... và /v1/v1/...), vì vậy việc ứng dụng khách có tự thêm /v1 hoặc /v1beta hay không đều không ảnh hưởng đến quá trình gọi: Bạn có thể điền Base URL là gốc tên miền hoặc địa chỉ có kèm /v1beta. Vui lòng tra cứu và sao chép ID mô hình tại mục "ID mô hình" ở góc trên bên phải trang "Token" trong bảng điều khiển.