Tham chiếu giao thức LLM Gateway

Trang này mô tả các request Claude Code gửi tới một gateway: endpoint được gọi, header/body field mà gateway phải forward, và tính năng nào ngừng hoạt động nếu không forward. Viết cho người vận hành gateway muốn tích hợp sản phẩm của họ với Claude Code.

Một Claude apps gateway đang chạy phục vụ bản machine-readable của hợp đồng này tại GET /protocol, bao gồm cả các endpoint riêng cho SSO, đưa managed-settings, và telemetry.

Ghi chú

• Để rollout một gateway (có sẵn hoặc bên thứ ba) cho tổ chức, xem Rollout LLM Gateway.
• Nếu bạn là developer cá nhân kết nối Claude Code tới gateway bằng credential được cấp, xem Kết nối Claude Code với LLM Gateway.

Bài viết dùng hai thuật ngữ cho cách gateway xử lý mỗi header/body field:

• Forward unchanged: chuyển tiếp nguyên byte lên upstream.
• Consume: gateway có thể đọc để định tuyến, attribution, hoặc tracing và không cần forward.

Bất cứ gì không đánh dấu “forward unchanged” là của bạn để dùng hoặc bỏ qua.

Định dạng API

Gateway phải phục vụ ít nhất một trong các định dạng API sau. Biến trong cột “Chọn bởi” quyết định Claude Code nói định dạng nào với gateway của bạn.

Định dạng	Chọn bởi	Endpoint	Forward unchanged
Anthropic Messages	ANTHROPIC_BASE_URL	/v1/messages, /v1/messages/count_tokens (tùy chọn)	Header anthropic-beta, anthropic-version
Amazon Bedrock InvokeModel	ANTHROPIC_BEDROCK_BASE_URL với CLAUDE_CODE_USE_BEDROCK=1	/model/{model}/invoke, /model/{model}/invoke-with-response-stream	Body field anthropic_beta, anthropic_version
Google Cloud’s Agent Platform rawPredict	ANTHROPIC_VERTEX_BASE_URL với CLAUDE_CODE_USE_VERTEX=1	:rawPredict, :streamRawPredict, count-tokens:rawPredict (tùy chọn)	Header anthropic-beta, anthropic-version, và body field anthropic_version

Foundry và Claude Platform on AWS

Microsoft Foundry và Claude Platform on AWS triển khai định dạng Anthropic Messages. Claude Code định tuyến tới chúng qua biến riêng (ANTHROPIC_FOUNDRY_BASE_URL, ANTHROPIC_AWS_BASE_URL), nhưng gateway đứng trước phải triển khai theo hàng Anthropic Messages ở trên. Gateway đứng trước Claude Platform on AWS còn phải forward header anthropic-workspace-id mà platform đó yêu cầu trên mọi request.

Endpoint tùy chọn và traffic lúc khởi động

Endpoint đếm token là endpoint tùy chọn duy nhất: khi thiếu, Claude Code tự ước lượng context usage cục bộ. Request inference gửi tới /v1/messages?beta=true, nên match theo path, không phải full URL.

Gateway cũng sẽ thấy traffic khởi động best-effort có thể từ chối mà không ảnh hưởng gì: probe kết nối HEAD /, và với gateway định dạng Bedrock là request GET /inference-profiles?type=SYSTEM_DEFINED.

Kiểm tra khả dụng của fast mode không bao giờ xuất hiện trong log gateway: nó gọi thẳng api.anthropic.com thay vì theo ANTHROPIC_BASE_URL. Kiểm tra an toàn domain của WebFetch cũng gọi thẳng api.anthropic.com.

Streaming

Response inference phải stream. Claude Code tiêu thụ server-sent events khi chúng tới, nên một gateway buffer toàn bộ response trước khi relay sẽ làm client bị treo.

Sai khớp định dạng với upstream

Định dạng client nói quyết định gateway của bạn nhận gì. Lỗi thường gặp là sự sai khớp giữa định dạng client gửi tới gateway và định dạng provider upstream đứng sau chấp nhận:

• Khi client nói định dạng Bedrock hoặc Vertex, Claude Code chỉ gửi tập con năng lực mà các provider đó chấp nhận.
• Khi client nói định dạng Anthropic Messages, Claude Code gửi đầy đủ tập năng lực, kể cả khi gateway của bạn forward tới upstream Bedrock hoặc Vertex.

Việc thu hẹp khoảng cách này là việc của gateway - xem phần Feature pass-through bên dưới.

Request header

Claude Code gửi các header sau trên request API (tên header không phân biệt hoa/thường trên wire). Forward anthropic-version và anthropic-beta nguyên vẹn, cộng anthropic-workspace-id khi upstream là Claude Platform on AWS; phần còn lại gateway có thể dùng cho routing, attribution, tracing và không cần forward.

Header	Mô tả
Authorization, x-api-key	Credential gateway của developer, ở một hoặc cả hai header tùy biến credential họ đặt
anthropic-version	Phiên bản API, hiện là 2023-06-01
anthropic-beta	Danh sách giá trị năng lực cách nhau dấu phẩy cho request. Forward nguyên header, đừng allowlist từng giá trị vì tập này thay đổi theo bản Claude Code
x-claude-code-session-id	ID duy nhất cho session hiện tại. Dùng để gộp mọi request từ một session mà không cần parse body
x-claude-code-agent-id	ID của subagent gửi request, chỉ có trên request từ agent Claude Code spawn trong session
x-claude-code-parent-agent-id	ID của agent đã spawn ra agent đang gửi request, chỉ có ở agent lồng nhau

Nếu developer đặt ANTHROPIC_CUSTOM_HEADERS, các header đó cũng xuất hiện trên request.

Forward như danh sách mở

Coi header và body field là danh sách mở, không đóng. Claude Code có thêm năng lực qua các bản release, dưới dạng giá trị anthropic-beta mới, body field mới, và đôi khi header anthropic-*/x-claude-code-* mới.

Khi forward tới upstream định dạng Anthropic, chuyển tiếp header/body field anthropic-* nguyên vẹn thay vì allowlist những gì thấy hôm nay. Một gateway ghim theo danh sách đã quan sát sẽ strip header/field của năng lực tiếp theo và làm hỏng nó ở bản release giới thiệu năng lực đó.

System prompt attribution block

Claude Code thêm một block attribution ngắn vào đầu system prompt, chứa client version và fingerprint từ conversation. Endpoint api.anthropic.com strip block này trước khi xử lý khi nó tới nguyên vẹn như system block đầu tiên, nên không ảnh hưởng prompt caching first-party. Upstream khác sẽ nhận nó như một phần của prompt.

Việc strip này phụ thuộc vị trí, nên chỉ hoạt động khi gateway forward mảng system nguyên vẹn:

• Forward mảng system đúng như nhận, giữ block ở đầu: thêm system block khác vào trước, sắp xếp lại mảng, hoặc chuyển thành một string đơn sẽ vô hiệu hóa strip.
• Giữ block trong entry mảng riêng: nếu bị gộp vào một block bắt đầu bằng attribution header, endpoint coi toàn bộ là attribution và bỏ mọi thứ gộp vào, kể cả phần system prompt còn lại.
• Nếu gateway phải reshape system content, đặt CLAUDE_CODE_ATTRIBUTION_HEADER=0 để Claude Code bỏ qua block này.

Từ Claude Code v2.1.181, block này ổn định trong suốt vòng đời một conversation khi request đi qua custom base URL, nên gateway-side prompt cache theo full request body hoạt động mà không cần tắt tính năng này.

Feature pass-through

Claude Code coi gateway ANTHROPIC_BASE_URL là endpoint định dạng Anthropic và gửi cùng beta header và body field như gửi api.anthropic.com. Năng lực thêm body field luôn đi kèm beta header tương ứng - một gateway strip header mà giữ body, hoặc forward body định dạng Anthropic tới upstream khác schema, sẽ tạo lỗi 400 cứng.

Tính năng	Cặp header/body	Triệu chứng khi hỏng	Cách khắc phục
Adaptive reasoning	Không có beta header; field thinking: {"type": "adaptive"}	400 nêu tên field thinking khi bản model upstream không chấp nhận	Nâng cấp upstream, hoặc đặt CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 trên Opus/Sonnet 4.6
Context management	Beta header đi kèm body field context_management	400 “Extra inputs are not permitted”	Forward cả hai, hoặc CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Extended context / interleaved thinking	Chỉ beta header, không body field	Âm thầm không khả dụng khi header bị strip	Forward anthropic-beta nguyên vẹn
Tool field beta	Header beta đi kèm field schema tool như strict, defer_loading	400 nêu tên field schema chưa nhận diện	Forward cả hai, hoặc CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Effort / structured outputs	Field output_config đi kèm beta header riêng	400 nêu tên output_config trên Bedrock/Vertex	Forward field và header cùng nhau
Token counting	Không cặp beta; dùng endpoint count_tokens	Claude Code fallback ước lượng context cục bộ	Expose endpoint nếu muốn số đếm chính xác

Retry tự động và forward lỗi

Claude Code tự retry sau một số phản hồi từ chối của upstream và tắt năng lực bị từ chối cho phần còn lại của conversation. Logic retry match theo nội dung lỗi upstream, nên forward error response body nguyên vẹn - một gateway bọc lỗi upstream trong envelope riêng sẽ phá vỡ đường phục hồi này dù giữ nguyên status code.

Tắt năng lực pre-release

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 khiến Claude Code ngừng gửi năng lực pre-release và body field liên quan trên mọi provider.

Model discovery

Khi ANTHROPIC_BASE_URL trỏ tới gateway phục vụ định dạng Anthropic Messages, Claude Code có thể query endpoint /v1/models của gateway lúc khởi động và thêm các model trả về vào bộ chọn /model.

Developer bật bằng CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Tắt mặc định để gateway dùng chung một API key không tự lộ mọi model key đó truy cập được cho mọi user. Yêu cầu Claude Code v2.1.129 trở lên.

Request là GET /v1/models?limit=1000 với timeout 3 giây, và bất kỳ redirect nào cũng bị coi là thất bại (để credential không lộ ra target redirect).

Claude Code đọc id và display_name (tùy chọn) từ mỗi entry trong mảng data, bỏ qua entry có id không bắt đầu bằng claude hoặc anthropic:

{
  "data": [
    { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6" },
    { "id": "claude-opus-4-8" }
  ]
}

Kết quả được cache vào ~/.claude/cache/gateway-models.json (hoặc dưới CLAUDE_CONFIG_DIR nếu đặt), và refresh mỗi lần khởi động.

Chú ý

Chi tiết về beta header, tên field, và ngưỡng phiên bản có thể thay đổi theo các bản Claude Code mới - kiểm tra lại tài liệu gốc khi triển khai gateway thực tế.

Nguồn

Dịch và biên soạn từ Gateway protocol reference.