Claude Code là công cụ lập trình dòng lệnh do Anthropic phát triển, mặc định kết nối tới giao diện chính thức của Anthropic. Trong thực tế, các đội trong nước thường trỏ công cụ này sang cổng tự xây hoặc bên thứ ba để giải quyết độ ổn định truy cập, hóa đơn thống nhất và quản lý hạn mức. Cái gọi là "tích hợp API tùy chỉnh" về bản chất chỉ đổi ba thứ: yêu cầu gửi đi đâu (Base URL), xác thực bằng gì (khóa) và gọi mô hình nào (tên mô hình).

Bài viết đi theo thứ tự cài đặt, biến môi trường, tệp cấu hình, chọn mô hình, kiểm tra kết nối, triển khai cho đội và bảo mật — một quy trình có thể tái sử dụng. Lệnh chủ yếu dành cho macOS và Linux; Windows sẽ được ghi chú riêng.

Lưu ý: Claude và Anthropic là nhãn hiệu của chủ sở hữu tương ứng. Bài viết chỉ nhằm hướng dẫn kỹ thuật, không có quan hệ trực thuộc với các nhà cung cấp. Claude Code cập nhật khá nhanh; biến môi trường, mục cấu hình và tên menu có thể thay đổi theo phiên bản, vui lòng căn cứ vào claude --help, tài liệu chính thức và hướng dẫn tích hợp trên trang.

1. Xác nhận ba điều trước khi tích hợp

Claude Code dùng giao thức Anthropic Messages, không phải Chat Completions của OpenAI. Vì vậy API tùy chỉnh phải đáp ứng ít nhất hai điểm: cung cấp điểm vào /v1/messages tương thích Anthropic; tên mô hình khớp với tên cổng thực tế cung cấp. Cổng chỉ có điểm vào tương thích OpenAI không thể điền trực tiếp cho Claude Code, trừ khi cổng đồng thời cung cấp tuyến tương thích Anthropic.

Chuẩn bị ba thứ trước khi bắt đầu:

  • Base URL: địa chỉ gốc của cổng, ví dụ https://ai.zhongshangqihang.com. Có kèm /v1 hay không tùy cách cổng triển khai; căn cứ hướng dẫn tích hợp trên trang.
  • API Key: tạo trong bảng điều khiển, đặt hạn mức và thời hạn, đừng dùng khóa dài hạn không giới hạn để kiểm thử.
  • Tên mô hình: sao chép từ bảng điều khiển hoặc trang giá, không viết tay theo trí nhớ; sai một ký tự hoa thường hay dấu nối cũng có thể báo không tìm thấy mô hình.

Nếu chưa có tài khoản, có thể bắt đầu từ trang đăng ký, tạo trước một khóa kiểm thử hạn mức thấp.

2. Cài đặt Claude Code

Claude Code thường được phân phối qua npm và cũng có các cách cài khác. Dưới đây là quy trình phổ biến nhất:

  1. Xác nhận đã cài Node.js. Nên dùng phiên bản LTS còn được bảo trì; phiên bản tối thiểu cụ thể căn cứ tài liệu chính thức.
  2. Chạy npm install -g @anthropic-ai/claude-code để cài toàn cục.
  3. Chạy claude --version, xác nhận lệnh dùng được và ghi lại số phiên bản.
  4. Vào một thư mục dự án kiểm thử, chạy claude, làm theo hướng dẫn để hoàn tất thiết lập lần đầu như giao diện và tin cậy thư mục.
  5. Nếu đội có yêu cầu quản lý phiên bản, hãy khóa phiên bản và ghi vào tài liệu nhập môn; kiểm tra trên dự án thử trước khi nâng cấp.
node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude

Khi dùng API tùy chỉnh, thường không cần đăng nhập tài khoản Anthropic, nhưng việc bỏ qua đăng nhập phụ thuộc phiên bản và cách cấu hình. Nếu sau khi khởi động vẫn bị yêu cầu đăng nhập, trước hết kiểm tra biến môi trường có hiệu lực trong cùng shell khởi chạy Claude Code hay không.

3. Biến môi trường: BASE_URL và AUTH_TOKEN

Claude Code đọc hai biến xác thực phổ biến:

  • ANTHROPIC_BASE_URL: địa chỉ gốc của yêu cầu.
  • ANTHROPIC_AUTH_TOKEN: gửi dưới dạng Authorization: Bearer, thường gặp khi dùng cổng.
  • ANTHROPIC_API_KEY: gửi dưới dạng x-api-key, gần với cách xác thực gốc của Anthropic.

Chỉ cần chọn một trong hai. Nếu cổng xác thực theo Bearer, dùng ANTHROPIC_AUTH_TOKEN; nếu xác thực theo cách gốc, dùng ANTHROPIC_API_KEY. Khi đặt cả hai, thứ tự ưu tiên có thể khác nhau giữa các phiên bản, dễ dẫn đến tình trạng "điền đúng mà vẫn báo 401"; nên chỉ giữ một biến.

export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-khoa-cua-ban"
claude

Ghi vào ~/.zshrc hoặc ~/.bashrc để cấu hình có hiệu lực lâu dài; sau khi sửa, chạy source ~/.zshrc. Trên Windows PowerShell dùng $env:ANTHROPIC_BASE_URL="...", chỉ có hiệu lực trong cửa sổ hiện tại; nếu cần lưu lâu dài, dùng giao diện biến môi trường hệ thống hoặc setx, sau đó mở lại terminal.

Đừng viết lệnh export vào script dự án rồi commit. Khi khóa đã vào lịch sử Git, xóa tệp không đồng nghĩa xóa bản ghi.

4. settings.json: cố định cấu hình vào tệp

Biến môi trường phù hợp để chuyển tạm thời; dùng lâu dài nên ghi vào tệp settings của Claude Code. Có ba vị trí phổ biến:

  • Cấp người dùng: ~/.claude/settings.json, áp dụng cho mọi dự án trên máy.
  • Cấp dự án: .claude/settings.json, có thể commit vào kho, phù hợp chia sẻ cấu hình không nhạy cảm trong đội.
  • Cấp dự án cục bộ: .claude/settings.local.json, không commit, phù hợp ghi đè cá nhân.

Ví dụ:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-khoa-cua-ban"
  },
  "model": "claude-sonnet-4-5"
}

Lưu ý: khóa trong settings.json là văn bản thuần. Máy cá nhân có thể chấp nhận, nhưng máy dùng chung, CI và kho mã thì không nên. Tệp cấp dự án chỉ nên chứa Base URL và tên mô hình; khóa giao cho biến môi trường hoặc công cụ quản lý bí mật. Thứ tự ưu tiên cấu hình đại khái là cấu hình quản trị doanh nghiệp, tham số dòng lệnh, dự án cục bộ, dự án, người dùng ghi đè lần lượt; chi tiết căn cứ tài liệu phiên bản hiện tại.

5. Chọn mô hình: phân tầng theo nhiệm vụ

Mô hình Claude thường chia ba tầng, phù hợp với các nhiệm vụ khác nhau:

Tầng Mục đích điển hình Đánh đổi
Opus Tái cấu trúc phức tạp, phân tích nhiều tệp, Agent chuỗi dài Năng lực mạnh hơn, chi phí thường cao hơn, tốc độ có thể chậm hơn
Sonnet Lập trình hằng ngày, sửa lỗi, đánh giá mã Cân bằng năng lực và chi phí, phù hợp làm mặc định
Haiku Hoàn thành đơn giản, định dạng, tác vụ nhỏ hàng loạt Nhanh, chi phí thấp, nhưng dễ đuối với tác vụ phức tạp

Trong Claude Code có thể dùng ANTHROPIC_MODEL để chỉ định mô hình chính, hoặc dùng ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL để ghi đè ánh xạ từng tầng. Các phiên bản khác nhau có thể hỗ trợ biến khác nhau; xem claude --help hoặc tài liệu chính thức trước khi cấu hình.

Tên mô hình phải khớp danh mục mô hình của cổng. Cổng có thể dùng cách đặt tên riêng cho mô hình thượng nguồn; điền tên trong tài liệu chính thức chưa chắc trùng. Mô hình khả dụng và cách tính phí xem tại bảng giá mô hình; giá có thể điều chỉnh theo phiên bản mô hình và chính sách thượng nguồn.

6. Kiểm tra kết nối: curl trước, Claude Code sau

Bỏ qua Claude Code trước, dùng curl kiểm tra bản thân cổng có thông không:

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Chỉ trả lời OK"}]
  }'

Nếu cổng xác thực bằng Bearer, đổi x-api-key thành Authorization: Bearer $ANTHROPIC_AUTH_TOKEN. Trả về 200 và nội dung bình thường nghĩa là Base URL, khóa và mô hình có ít nhất một bộ dùng được.

Sau đó quay lại Claude Code, kiểm tra theo thứ tự:

  1. claude --version xác nhận ứng dụng khách chạy được.
  2. Chạy claude doctor trong thư mục dự án (nếu phiên bản hiện tại có lệnh này) để kiểm tra cài đặt và cấu hình.
  3. Khởi động claude, dùng /status xem mô hình và thông tin tài khoản hiện tại.
  4. Nhập một tác vụ rủi ro thấp, ví dụ "giải thích cấu trúc thư mục này, không sửa tệp".
  5. Quan sát phản hồi có bình thường không, có xuất hiện lỗi 401, 404 hoặc không tìm thấy mô hình không.

Đối chiếu hiện tượng thường gặp:

Hiện tượng Kiểm tra trước Xử lý
401 Khóa, tên biến, tiêu đề yêu cầu Sao chép lại khóa; chỉ giữ một biến xác thực
404 Base URL thừa hoặc thiếu /v1 Theo tài liệu cổng, đổi về địa chỉ gốc hoặc điểm vào tương thích
model not found Tên mô hình không khớp danh mục cổng Sao chép từ bảng điều khiển hoặc trang giá
Yêu cầu quá thời gian Mạng, DNS, proxy Đổi mạng để thử; kiểm tra proxy có sửa tiêu đề yêu cầu không
429 Giới hạn đồng thời hoặc hạn mức Giảm đồng thời; kiểm tra hạn mức của khóa

7. Triển khai cho đội: mỗi người một khóa, đầu mối thống nhất

Không nên dùng chung một khóa cho cả đội. Cách ổn thỏa hơn:

  • Mỗi người một khóa, tên gồm họ tên hoặc mục đích, vô hiệu hóa ngay khi nghỉ việc.
  • Đặt hạn mức theo dự án hoặc môi trường, tách sản xuất và kiểm thử.
  • Dùng cổng thống nhất để xem mức dùng, phân bố mô hình và các lần gọi bất thường.
  • Dùng cấu hình quản trị doanh nghiệp để phân phối Base URL và danh sách mô hình được phép, giảm lỗi cấu hình thủ công của thành viên.
  • Viết quy trình tích hợp thành tài liệu nhập môn, gồm lệnh kiểm tra và lỗi thường gặp.
  • Đánh giá mức dùng hàng tuần hoặc hàng tháng, xử lý kịp thời khóa bất thường.

Nếu công ty có quy trình mua sắm và tuân thủ, hãy xác nhận luồng dữ liệu trước: đoạn mã sẽ được gửi đến cổng và dịch vụ mô hình thượng nguồn. Có lưu giữ không, lưu bao lâu, có dùng để huấn luyện không — cần xem điều khoản dịch vụ, đừng tự giả định.

8. Ranh giới bảo mật: khóa, mã và dữ liệu

Cuối cùng là vài nguyên tắc tối thiểu:

  • Khóa không vào Git, image, mã giao diện, ảnh chụp màn hình hay lịch sử trò chuyện.
  • Thêm .gitignore cho dự án, tối thiểu gồm .env, .env.*, .claude/settings.local.json.
  • Khi nghi ngờ rò rỉ, thu hồi khóa cũ trước rồi kiểm tra mức dùng, đừng chỉ đổi mật khẩu.
  • Đặt thời hạn cho khóa, luân chuyển khi nhân sự thay đổi.
  • Trên máy dùng chung, dùng công cụ quản lý bí mật hoặc apiKeyHelper, không viết văn bản thuần vào settings.json.
  • Chỉ cài Claude Code từ nguồn tin cậy, đọc ghi chú thay đổi trước khi nâng cấp.

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

Claude Code có nhất thiết phải đăng nhập tài khoản Anthropic?

Không nhất thiết. Sau khi cấu hình Base URL và biến xác thực dùng được, ứng dụng khách có thể đi thẳng qua API tùy chỉnh; nhưng lần khởi động đầu vẫn có thể hiện hướng dẫn về giao diện và tin cậy thư mục. Việc có cần đăng nhập hay không tùy phiên bản và cấu hình; khi gặp vấn đề, trước hết kiểm tra biến môi trường có hiệu lực trong shell khởi chạy không.

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

Biến trước thường gửi qua tiêu đề x-api-key, biến sau gửi qua Authorization: Bearer. Chọn biến nào tùy cách xác thực của cổng; nên chỉ đặt một biến để tránh xung đột tiêu đề yêu cầu.

Base URL nên điền địa chỉ gốc hay kèm /v1?

Claude Code thường điền địa chỉ gốc, ứng dụng khách tự ghép /v1/messages; một số cổng yêu cầu điền thẳng điểm vào tương thích. Cách xác định rất đơn giản: dùng curl gọi địa chỉ gốc cộng /v1/messages; nếu thông thì dùng địa chỉ gốc, nếu không thì điều chỉnh theo tài liệu cổng.

Vì sao curl thông mà Claude Code báo lỗi?

Nguyên nhân thường gặp là biến shell không được truyền sang giao diện đồ họa hoặc terminal tích hợp trong IDE, hoặc đặt đồng thời hai biến xác thực gây xung đột. Trước hết chạy echo $ANTHROPIC_BASE_URL trong đúng terminal khởi chạy Claude Code để xác nhận.

Đội có thể dùng chung một khóa không?

Về kỹ thuật là được, nhưng không nên. Khóa dùng chung không phân biệt được mức dùng của từng thành viên, và khi rò rỉ cũng khó truy trách nhiệm. Mỗi người một khóa kèm hạn mức và thời hạn giúp quản lý ít tốn công hơn.

Bước tiếp theo

Nếu chưa có tài khoản cổng dùng được, có thể bắt đầu từ trang đăng ký, tạo trước một khóa kiểm thử hạn mức thấp, rồi kiểm tra theo hai bước curl và Claude Code trong bài. Mô hình và cách tính phí xem tại bảng giá mô hình; giá có thể điều chỉnh, căn cứ thông tin thời gian thực trên trang.

Đọc thêm: