Rollout LLM Gateway cho tổ chức

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Trang này hướng dẫn admin rollout một LLM gateway cho Claude Code. Giả định bạn đã có sản phẩm gateway triển khai sẵn, đáp ứng yêu cầu gateway bên dưới. Việc triển khai hoặc vận hành sản phẩm cụ thể không thuộc phạm vi trang này - làm theo tài liệu của vendor tương ứng.

Yêu cầu trước khi bắt đầu

Gateway đã deploy trên hạ tầng của bạn, phục vụ HTTPS đúng tại địa chỉ bạn sẽ phân phối cho developer (không phải địa chỉ redirect tới nó), và định tuyến tên model Claude tới provider của bạn.
Credential provider để gateway forward: API key từ Claude Console (cho Anthropic API), hoặc cloud credential có quyền truy cập model (cho Bedrock/Vertex/Foundry).
Một cách phân phối settings file tới máy developer, như MDM hoặc configuration management.

Yêu cầu gateway

Dù dùng sản phẩm nào, gateway phải:

Chấp nhận định dạng API được hỗ trợ: một trong các định dạng ở bảng định dạng API. Các bước rollout dưới đây giả định Anthropic Messages API tại POST /v1/messages, định dạng hầu hết gateway phục vụ.
Stream response: chuyển tiếp server-sent events ngay khi tới thay vì buffer toàn bộ response.
Định tuyến tên model Claude: map mỗi tên developer dùng tới model upstream. Claude Code gửi tên model như claude-sonnet-4-6 trong mỗi request.
Forward header và body nguyên vẹn: chuyển tiếp anthropic-beta, anthropic-version, và request body theo cả hai chiều.
Trả lỗi upstream không sửa đổi: cơ chế phục hồi tự động của Claude Code match theo nội dung lỗi, nên bọc lỗi trong envelope riêng của gateway sẽ phá vỡ nó.
Loại trừ path khỏi WAF inspection body: prompt Claude Code mang code nguồn và tag kiểu XML khớp với rule XSS body - một WAF trước gateway sẽ trả 403 trên session thật trong khi request test ngắn thì qua.

Tùy chọn, phục vụ GET /v1/models để Claude Code có thể điền bộ chọn model từ gateway của bạn qua model discovery.

Các bước rollout

Rollout gồm năm bước, mỗi bước có một checkpoint xác nhận:

Xác nhận gateway định tuyến đúng model
Cấp credential cho từng developer
Test Claude Code với gateway
Phân phối base URL và credential
Xác minh từ máy developer

Có ba loại credential khác nhau trong các bước này:

Credential	Ai giữ	Placeholder trong checkpoint
Credential provider	Gateway, forward tới provider upstream	Cấu hình trên gateway; không bao giờ xuất hiện trong lệnh client
Credential quản trị gateway	Bạn, nếu sản phẩm gateway cấp cho giao diện admin/test	`<gateway-key>`
Developer key	Từng developer, cấp bởi gateway	`<developer-key>`

Xác nhận gateway định tuyến đúng model

Gateway của bạn nên đã cấu hình sẵn credential provider, lắng nghe ở base URL, và forward request tới API provider. Test đường đi end-to-end với một request tối thiểu:

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <gateway-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Checkpoint: 200 kèm field content nghĩa là gateway đã tới được provider với tên model đó. 404 nghĩa là tên đó chưa được định tuyến ở gateway; 401 từ provider nghĩa là credential provider của gateway sai. Lặp lại cho từng tên model trong cấu hình định tuyến của gateway.

Cấp credential cho developer

Mỗi developer cần key riêng để xác thực. Tạo credential theo tài liệu quản lý credential của sản phẩm gateway bạn dùng.

Xác nhận key mới cấp hoạt động với cùng request test như trên, thay <gateway-key> bằng <developer-key>.

Checkpoint: 200 kèm content nghĩa là developer key tới được gateway và gateway forward đúng. 401 ở đây (khi bước trước đã thành công) nghĩa là developer key sai hoặc chưa có hiệu lực ở gateway.

Cấp một key riêng cho từng developer thay vì key dùng chung là điều giúp việc theo dõi usage theo từng người và offboarding cá nhân hoạt động được. Biến môi trường chứa key phụ thuộc header gateway đọc: gateway kiểm tra Authorization: Bearer thì developer đặt ANTHROPIC_AUTH_TOKEN; gateway đọc key từ header x-api-key thì đặt ANTHROPIC_API_KEY.

Test Claude Code với gateway

Chạy Claude Code qua gateway trước khi phân phối bất cứ gì, dùng đúng cấu hình sẽ rollout toàn tổ chức. Gõ trực tiếp trong terminal (không dùng file .env hay settings) - chỉ tồn tại trong session terminal này:

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

Sau đó gửi một prompt one-shot:

claude -p "Reply with one word: connected"

Checkpoint: prompt trả về response, và request xuất hiện trong log gateway dưới dạng POST /v1/messages với status 200. Hai thông báo lỗi thường gặp trỏ tới hai nguyên nhân khác nhau:

Not logged in: kiểm tra log gateway - nếu trống, không có credential nào tới được session; nếu thấy request bị từ chối với x-api-key trong body 401, gateway đang chờ key ở header đó - chuyển sang ANTHROPIC_API_KEY.
Failed to authenticate. API Error: 401: một credential đã gửi và bị từ chối - log gateway sẽ cho biết ở đâu.

Base URL sai hoặc không tới được sẽ khiến Claude Code tự retry với backoff và có thể im lặng vài phút trước khi báo lỗi - kiểm tra log gateway thay vì chờ.

Phân phối cấu hình

Mỗi máy developer cần địa chỉ gateway và một credential. Bạn có thể phân phối tập trung qua managed settings, hoặc đưa developer tự đặt.

Nội dung cần phân phối

Biến/setting	Chức năng	Bao gồm khi
`ANTHROPIC_BASE_URL`	Gửi request API của Claude Code tới gateway thay vì `api.anthropic.com`	Luôn luôn
`apiKeyHelper`, hoặc credential trong `ANTHROPIC_AUTH_TOKEN`/`ANTHROPIC_API_KEY`	Xác thực mỗi request tới gateway	Luôn luôn; chọn một trong ba
`ANTHROPIC_CUSTOM_HEADERS`	Thêm header HTTP khác vào mọi request	Gateway của bạn yêu cầu header tenant/routing trên mọi request
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	Query `/v1/models` của gateway lúc khởi động	Gateway phục vụ `/v1/models` và bạn muốn bộ chọn model tự điền
`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`	Ngừng gửi header/body field năng lực pre-release	Gateway forward tới upstream Bedrock/Vertex từ chối các field beta
`ANTHROPIC_MODEL` hoặc biến default model	Đặt tên model Claude Code yêu cầu cho session chính và traffic nền	Gateway định tuyến tên model khác default của Claude Code
`ANTHROPIC_BEDROCK_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL`, `ANTHROPIC_FOUNDRY_BASE_URL`, hoặc `ANTHROPIC_AWS_BASE_URL`	Trỏ Claude Code tới gateway qua base URL riêng provider	Gateway đứng trước Bedrock, Vertex, Foundry, hoặc Claude Platform on AWS

Phân phối qua managed settings

Đưa các biến qua block env của một managed settings file, đẩy bằng MDM, registry policy, hoặc configuration management:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

Một ANTHROPIC_BASE_URL managed được enforce và không thể bị ghi đè bởi shell export của developer, vì Claude Code áp nó lên trên process environment và settings có độ ưu tiên thấp hơn.

Một số môi trường cần phân phối riêng: desktop app đọc cấu hình gateway routing từ file cấu hình third-party inference riêng, không từ managed settings; CI runner cần ANTHROPIC_BASE_URL và credential đặt trong môi trường runner; WSL trên máy Windows managed chỉ đọc managed settings Windows khi wslInheritsWindowsSettings là true.

Checkpoint: trên máy developer, claude khởi động session không hiện màn hình đăng nhập. Chạy /status, mở tab Status: dòng Anthropic base URL hiển thị địa chỉ gateway.

Xác minh rollout

Xác nhận mọi thứ hoạt động từ máy developer, không phải host gateway, để test đi qua đúng đường mạng developer dùng. Gửi một request streaming để kiểm tra endpoint, streaming pass-through, và định tuyến model cùng lúc:

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

Các dòng data: phải tới dần dần - nếu toàn bộ response tới cùng lúc sau một khoảng dừng, gateway đang buffer, làm treo Claude Code. Sau đó khởi động claude và gửi một message, kiểm tra log gateway theo x-claude-code-session-id để nhóm request theo session.

Duy trì gateway

Thay đổi	Triệu chứng khi gateway chưa theo kịp	Hành động
Bản Claude Code mới thêm giá trị `anthropic-beta` và body field	Developer báo lỗi `400` nêu field mới sau khi update Claude Code	Forward header/body `anthropic-*` nguyên vẹn thay vì allowlist; test bản Claude Code mới trước khi phát hành
Model Claude mới ra mắt	Developer chọn model mới bị `404`; bộ chọn `/model` không liệt kê nó	Thêm tên model vào cấu hình định tuyến gateway, re-test
Credential hết hạn hoặc cần xoay vòng	Toàn bộ request developer lỗi `401`	Xoay credential provider của gateway theo lịch riêng; developer key xoay ở gateway

Khi định cỡ rate limit theo key, tính cả việc client tự retry lỗi tạm thời (kể cả 429) tới 10 lần với backoff, tuân theo Retry-After.

Phuc Tran

Software Engineer | Learning Claude