Claude Code

Claude Code là công cụ lập trình trong terminal do Anthropic phát triển. Bạn có thể cấu hình địa chỉ API, API Key và ID mô hình để Claude Code dùng điểm vào tương thích Anthropic Messages của AGTCloud.

Hướng dẫn này chỉ dành cho Claude Code CLI. Mức hỗ trợ gọi công cụ, tư duy mở rộng và tính năng thử nghiệm có thể khác nhau giữa các mô hình; hãy chọn mô hình mà API Key hiện tại nhìn thấy và hỗ trợ Anthropic Messages.

Chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn đã:

Chuẩn bị môi trường terminal và Git;
Đăng ký và đăng nhập AGTCloud;
Tạo token trên trang API Keys;
Tìm ID mô hình giao thức Anthropic mà token hiện tại có thể dùng trong danh mục mô hình.

Cài đặt Claude Code

Chọn phương thức cài đặt cho hệ điều hành của bạn. Script cài đặt gốc tự cập nhật; bản Homebrew và WinGet cần cập nhật thủ công bằng trình quản lý gói tương ứng.

curl -fsSL https://claude.ai/install.sh | bash

Sau khi cài đặt, mở lại terminal và kiểm tra phiên bản:

claude --version
claude doctor

claude doctor kiểm tra trạng thái cài đặt và tệp cấu hình. Nếu terminal không tìm thấy claude, mở lại terminal và xác nhận thư mục cài đặt nằm trong PATH.

Cấu hình AGTCloud

Claude Code gửi yêu cầu đến địa chỉ trong ANTHROPIC_BASE_URL. Chỉ điền AGTCloud API Origin, không thêm /v1 ở cuối vì Claude Code tự gửi yêu cầu đến /v1/messages.

Cấu hình tạm thời

Cấu hình dưới đây chỉ có hiệu lực trong phiên terminal hiện tại. Thay your-api-key và MODEL_ID bằng token và ID mô hình của bạn.

unset ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.agtcloud.cn"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"

Biến môi trường	Vai trò
`ANTHROPIC_BASE_URL`	Hướng yêu cầu Claude Code đến địa chỉ API AGTCloud hiển thị trên trang này
`ANTHROPIC_API_KEY`	Gửi AGTCloud API Key qua Header `X-Api-Key`
`ANTHROPIC_MODEL`	Chỉ định ID mô hình mặc định cho phiên này

Xóa biến xác thực gây xung đột

Nếu ANTHROPIC_AUTH_TOKEN đã được cấu hình trong hệ thống, Claude Code dùng nó làm Bearer Token, có thể ghi đè ANTHROPIC_API_KEY. Xóa biến đó trước khi dùng cấu hình trong hướng dẫn này.

Cấu hình lâu dài

Để tự áp dụng mỗi khi mở terminal, ghi cấu hình tương tự vào tệp cấu hình shell hoặc biến môi trường người dùng Windows. API Key được lưu dạng văn bản thuần trên máy; chỉ dùng cách này trên thiết bị cá nhân đáng tin cậy.

Sửa ~/.zshrc và thêm:

export ANTHROPIC_BASE_URL="https://api.agtcloud.cn"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"

Sau khi lưu, tải cấu hình:

source ~/.zshrc

Chọn mô hình

MODEL_ID chỉ là vị trí cần thay thế, không phải tên mô hình thực tế. Sao chép ID mô hình mà API Key hiện tại có thể dùng và hỗ trợ Anthropic Messages từ danh mục mô hình.

Sau khi vào Claude Code, bạn có thể chạy /model để xem và đổi mô hình của phiên hiện tại. Khả năng tự liệt kê toàn bộ mô hình AGTCloud phụ thuộc vào phiên bản Claude Code và API Key; nếu mô hình đích không xuất hiện, chỉ định ID trực tiếp qua ANTHROPIC_MODEL.

Khởi chạy và kiểm tra kết nối

Vào thư mục dự án

cd /path/to/your/project

Khởi chạy Claude Code

claude

Nếu lần đầu khởi chạy hỏi có dùng API Key từ biến môi trường không, xác nhận theo lời nhắc trong terminal.

Kiểm tra cấu hình hiện tại

Trong Claude Code, chạy:

/status

Xác nhận nguồn xác thực là API Key và Base URL đúng địa chỉ API AGTCloud trên trang này. Base URL không được chứa /v1 lặp.

Thử tác vụ chỉ đọc

Trong dự án thử nghiệm có README.md, nhập:

Hãy đọc README.md và tóm tắt mục đích dự án thành ba ý. Không sửa bất kỳ tệp nào.

Nếu nội dung được trả về bình thường và bảng điều khiển AGTCloud có bản ghi gọi tương ứng, kết nối cơ bản đã được thiết lập.

Sau khi kiểm tra cấu hình, gửi một câu hỏi đơn giản để xác nhận mô hình phản hồi bình thường.

Kiểm tra hội thoại cơ bản trong Claude Code

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

Hiện tượng	Kiểm tra trước	Cách xử lý
Không tìm thấy lệnh `claude`	Kết quả cài đặt và `PATH`	Mở lại terminal, chạy `claude doctor`; nếu cần, chạy lại lệnh cài đặt chính thức
Vẫn yêu cầu đăng nhập sau khi khởi chạy	API Key có hiệu lực trong cùng terminal khởi chạy Claude Code không	Kiểm tra `ANTHROPIC_API_KEY`, mở lại terminal rồi khởi chạy lại
API Key không có hiệu lực	Có đồng thời đặt `ANTHROPIC_AUTH_TOKEN` không	Xóa biến xung đột, kiểm tra nguồn xác thực bằng `/status`
Trả về `401`	API Key, biến môi trường và trạng thái token	Sao chép API Key hợp lệ và xác nhận nguồn xác thực bằng `/status`
Trả về `403`	Quyền token, quyền mô hình và trạng thái tài khoản	Kiểm tra phạm vi dùng token và mô hình trong bảng điều khiển
Trả về `404`	Base URL và ID mô hình	Chỉ điền `https://api.agtcloud.cn`, không thêm `/v1`; sao chép lại ID mô hình
Không tìm thấy hoặc không dùng được mô hình	Mô hình mà API Key nhìn thấy và hỗ trợ giao thức	Chọn mô hình hỗ trợ Anthropic Messages, chỉ định ID đầy đủ qua `ANTHROPIC_MODEL`
Một số công cụ hoặc tính năng nâng cao không khả dụng	Khả năng mô hình và tính tương thích của gateway	Kiểm tra hội thoại cơ bản trước; khả năng nâng cao phụ thuộc mô hình và kết quả thích ứng hiện tại

Nếu chưa xác định được vấn đề, ghi lại thời gian yêu cầu, ID mô hình, trạng thái HTTP và lỗi đã loại thông tin nhạy cảm, rồi xem Lỗi và khắc phục sự cố. Không gửi API Key đầy đủ.

Khuyến nghị bảo mật

Tạo API Key riêng cho Claude Code để dễ quản lý quyền và vô hiệu hóa thông tin xác thực.
Không ghi Key thật vào mã, kho mã, ảnh chụp màn hình, nhật ký hoặc script dùng chung.
Trên thiết bị dùng chung hoặc trong nhóm, ưu tiên quản lý thông tin xác thực của hệ điều hành hoặc cơ chế phân phối khóa tập trung của tổ chức.
Nếu nghi API Key bị lộ, vô hiệu hóa hoặc xóa ngay trong bảng điều khiển rồi tạo Key mới.

Tiếp theo, bạn có thể đọc API Key, Base URL và xác thực và Anthropic Messages.

Trên trang này