AZZ API

Hướng dẫn tích hợp trung gian Claude Code: Cấu hình tác nhân terminal và Base URL

Hướng dẫn tích hợp Claude Code - tác nhân lập trình terminal chính thức của Anthropic: Cài đặt, thiết lập ANTHROPIC_BASE_URL và khóa API, chuyển đổi mô hình và khắc phục sự cố.

1. Claude Code là gì?

Claude Code là tác nhân (agent) lập trình trên terminal chính thức từ Anthropic, cho phép đọc/ghi code, chạy lệnh và thực thi các tác vụ trực tiếp ngay trong cửa sổ dòng lệnh. Công cụ này tự động đọc 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 key/hạn mức của mình để vận hành.

2. Cài đặt Claude Code

Bạn cần Node.js (khuyên dùng bản 18 trở lên), sau đó cài đặt trên toàn hệ thống (global) bằng lệnh:

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

Sau khi cài đặt, gõ claude trong terminal để khởi chạy; sử dụng /model hoặc claude --model … để chuyển đổi mô hình.

3. 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-khoa_api_cua_ban"
$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-khoa_api_cua_ban"
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 được sử dụng để ghi đè điểm cuối API mặc định, trỏ tới cổng vào Anthropic của trang này là được.

4. Đối chiếu địa chỉ API

Nhóm mô hìnhCổng vào (Base URL)Giao thức
Claude / Anthropichttps://www.relay-api.comAnthropic Messages
GPT / OpenAIhttps://www.relay-api.com/v1OpenAI Chat Completions
Geminihttps://www.relay-api.com/v1betaGoogle generateContent

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

Hiện tượngCách xử lý
401 / 403Khóa không hợp lệ, chưa được kích hoạt hoặc không đủ số dư; xác nhận mã sk- chính xác và đã nạp tiền.
404 / Mô hình không khả dụngTê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 kỹ ID mô hình.
Unknown modelID mô hình phải chính xác (bao gồm cả chữ hoa/thường), kiểm tra tại bảng mô hình.
Yêu cầu hết thời gian (Timeout)Với các tác vụ dài, có thể điều chỉnh tăng thời gian chờ; thử lại nếu mạng không ổn định.

Lời khuyên bảo mật: Đừng viết khóa API vào các kho lưu trữ công khai, hãy sử dụng .env hoặc biến môi trường; các tác vụ tạo code tiêu tốn nhiều token, hãy chú ý số dư và kiểm tra lịch sử sử dụng tại phần "Nhật ký sử dụng".