Kết nối Claude Code với LLM gateway

Một LLM gateway là proxy tổ chức bạn chạy giữa Claude Code và model provider. Khi tổ chức bạn dùng gateway, Claude Code xác thực với gateway bằng credential do tổ chức cấp thay vì login claude.ai cá nhân.

Trang này dành cho developer chạy Claude Code qua gateway do tổ chức mình vận hành. Nó bao gồm hai hướng: kiểm tra xem admin đã cấu hình sẵn chưa, và tự cấu hình khi họ chưa làm.

Ghi chú

• Để deploy gateway cho tổ chức, xem Rollout LLM gateway
• Về những gì Claude Code gửi đến gateway, xem tham chiếu protocol gateway

Kiểm tra cấu hình có sẵn

Admin có thể phân phối địa chỉ và credential gateway qua managed settings, device management, hoặc apiKeyHelper, để Claude Code tự nhận chúng khi khởi động mà bạn không cần set gì. Để kiểm tra:

1. Chạy claude. Nếu nó mở màn hình login thay vì vào thẳng session, chưa có gateway credential nào được phân phối - tự cấu hình bên dưới.
2. Kiểm tra tab Status. Nếu Claude Code vào session mà không hiện màn hình login, chạy /status và kiểm tra hai dòng: Anthropic base URL (chỉ xuất hiện khi có set gateway address) và Auth token/API key (tên ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, hoặc apiKeyHelper xác nhận gateway credential đang hoạt động).
3. Gửi thử một tin nhắn. Đóng menu /status và gửi một prompt bất kỳ. Response bình thường, không lỗi, xác nhận kết nối gateway hoạt động.

Tự cấu hình Claude Code

Bạn cần từ team gateway: base URL của gateway, và một credential (key, token string, hoặc lệnh fetch credential).

Set biến credential

Set credential trong	Dùng khi
ANTHROPIC_AUTH_TOKEN	Team gateway nói “bearer token” hoặc “Authorization header”
ANTHROPIC_API_KEY	Team gateway nói “API key” hoặc “x-api-key”
apiKeyHelper	Credential xoay vòng hoặc lấy từ vault

Nếu không được báo dùng loại nào, dùng ANTHROPIC_AUTH_TOKEN trước; request verify bên dưới cho biết có cần đổi không.

Set base URL và credential

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

Shell export chỉ áp dụng cho session terminal đó. Để giữ giá trị qua các terminal mới, thêm cùng dòng vào shell profile (~/.zshrc, ~/.bashrc…). Để cấu hình đến được cả background agent, set trong block env của một settings file thay vì chỉ dựa vào shell:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

Dùng ~/.claude/settings.json (áp dụng mọi project) hoặc .claude/settings.local.json (một project). Đừng đặt credential trong .claude/settings.json của project - file đó được commit và share với mọi người clone repo.

Verify kết nối

Với biến đã export trong shell, gửi một request một-token thẳng đến gateway để xác nhận URL và credential hoạt động trước khi mở Claude Code:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Nếu gateway của bạn đọc key trong header x-api-key, thay Authorization bằng x-api-key: $ANTHROPIC_API_KEY. Response JSON bắt đầu bằng {"id":"msg_ cùng field "content":[...] nghĩa là gateway reachable và credential hoạt động - kể cả một lỗi nêu tên model không tồn tại vẫn chứng minh URL/credential đúng, vì gateway đã xác thực request trước khi từ chối tên model. Một 401 nghĩa là credential bị từ chối - thử đổi sang biến còn lại.

Sau đó chạy claude từ cùng shell, gửi tin nhắn, và chạy /status để xác nhận Anthropic base URL và Auth token/API key hiện đúng.

Biến credential map sang header nào

Mỗi biến gửi credential trong một header HTTP khác nhau: ANTHROPIC_AUTH_TOKEN vào Authorization: Bearer, ANTHROPIC_API_KEY vào x-api-key, apiKeyHelper vào cả hai. Credential đặt sai biến sẽ đến gateway trong một header nó không đọc, và request fail với 401.

Xung đột với login hiện có

Một gateway credential variable ưu tiên hơn login claude.ai đã lưu hoặc Console key. Login claude.ai vẫn được lưu và không dùng trong khi biến đang set; unset biến để quay lại nó. Chạy /status để xác nhận credential source đang hoạt động. Chạy /logout để xóa login đã lưu, chỉ còn lại gateway credential.

Cấu hình từng surface

VS Code extension

Set biến gateway trong claudeCode.environmentVariables, ở user settings JSON của VS Code:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}

Desktop app

Desktop app đọc gateway routing từ third-party inference configuration riêng, không phải từ ANTHROPIC_BASE_URL hay settings.json. Cấu hình đó đến từ tổ chức bạn (nếu đã deploy) hoặc bạn tự nhập qua Developer → Configure Third-Party Inference sau khi bật Developer Mode.

GitHub Actions

Claude Code GitHub Actions đọc ANTHROPIC_BASE_URL và ANTHROPIC_CUSTOM_HEADERS từ block env của workflow. Với gateway x-api-key, set base URL trong env và pass gateway key làm input anthropic_api_key. Với gateway bearer-token, pass cùng secret hai lần: vào input anthropic_api_key và vào ANTHROPIC_AUTH_TOKEN trong block env - action yêu cầu anthropic_api_key trước khi launch nhưng không đọc ANTHROPIC_AUTH_TOKEN như credential thực tế gửi lên gateway.

Agent SDK

Agent SDK không có option riêng cho gateway; nó truyền env variable vào Claude Code process nó spawn. TypeScript: options.env thay thế toàn bộ environment, cần spread process.env vào để giữ biến gateway. Python: ClaudeAgentOptions(env=...) merge lên trên environment kế thừa.

Slack, web, và Remote Control

Claude Code trong Slack và Claude Code trên web là sản phẩm host bởi Anthropic, luôn dùng thẳng Anthropic API - không phải một phần của gateway deployment. Remote Control và voice dictation đều cần danh tính claude.ai, nên không dùng được khi ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, hoặc apiKeyHelper đang active.

Cấu hình bổ sung

Gửi header thêm

Một số gateway route hoặc gắn tag request bằng header tùy chỉnh (tenant ID, routing key…). Set ANTHROPIC_CUSTOM_HEADERS, mỗi cặp Name: Value một dòng:

export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

Thêm model gateway vào model picker

Set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (cần Claude Code v2.1.129+) để Claude Code query danh sách model gateway lúc khởi động và thêm vào picker /model, đánh nhãn From gateway.

Rotate credential bằng apiKeyHelper

Dùng khi credential hết hạn theo lịch, đến từ vault, hoặc admin yêu cầu. apiKeyHelper là một lệnh shell in credential hiện tại ra stdout:

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

Claude Code cache output của helper 5 phút mặc định và chạy lại khi request trả 401. Đổi thời gian cache bằng CLAUDE_CODE_API_KEY_HELPER_TTL_MS (mili giây).

Tắt traffic ngoài đường gateway

Trên mạng chỉ cho phép egress đến gateway, set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 để tắt version check, telemetry, error report, và các luồng nền khác - lưu ý điều này cũng tắt auto-update và gateway model discovery.

Route đến cloud provider qua gateway

Nếu team gateway của bạn nêu rõ Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, hoặc Claude Platform on AWS, dùng biến base URL riêng của provider đó (ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL, ANTHROPIC_FOUNDRY_BASE_URL, ANTHROPIC_AWS_BASE_URL) thay cho ANTHROPIC_BASE_URL, cùng biến CLAUDE_CODE_SKIP_*_AUTH và CLAUDE_CODE_USE_* tương ứng. Nếu request verify ở trên đã trả JSON, bạn không cần phần này.

Xử lý lỗi gateway

Lỗi	Nguyên nhân	Cách khắc phục
Cảnh báo hai credential source khi khởi động	Cả gateway credential và login đã lưu đều active	Unset biến để dùng login đã lưu, hoặc /logout để dùng gateway credential
401 nêu token không hợp lệ	Credential không phải do gateway cấp, hoặc sai header	Đối chiếu biến với loại credential; regenerate key nếu đã bị revoke
Your apiKeyHelper script is failing	Lệnh trong apiKeyHelper fail, timeout, hoặc không in gì	Chạy lệnh trực tiếp để xem lý do
Unable to connect to API	Không có gì trả lời tại base URL	Chạy curl test, xác nhận URL và đường mạng với team gateway
400 nêu context_management hoặc field lạ	Gateway forward request đến upstream từ chối field đó	Set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Model thiếu trong picker /model	Tên model gateway không có trong danh sách built-in	Bật gateway model discovery hoặc thêm tên bằng biến model configuration
/fast báo unavailable dù inference vẫn chạy	Check availability của fast mode gọi thẳng api.anthropic.com, không theo ANTHROPIC_BASE_URL	Allowlist api.anthropic.com hoặc set biến skip

Trang liên quan

• Tổng quan LLM gateway: gateway là gì và tương tác với subscription claude.ai ra sao
• Rollout LLM gateway cho tổ chức: checklist admin
• Tham chiếu protocol gateway: header và field gateway phải forward
• Settings: nơi settings file nằm và cách block env được đọc

Nguồn

Dịch và biên soạn từ Connect Claude Code to an LLM gateway.