Claude Code trên Amazon Bedrock

Điều kiện tiên quyết

Trước khi cấu hình Claude Code với Amazon Bedrock, cần có:

• Tài khoản AWS đã bật Amazon Bedrock
• Quyền truy cập model Claude mong muốn (ví dụ Claude Sonnet 4.6) trong Amazon Bedrock
• AWS CLI đã cài và cấu hình (tuỳ chọn - chỉ cần nếu không có cơ chế khác để lấy credential)
• Quyền IAM phù hợp

Để đăng nhập với credential Bedrock của riêng bạn, làm theo Đăng nhập bằng Bedrock bên dưới. Để triển khai cho cả team, dùng các bước thiết lập thủ công và ghim phiên bản model trước khi rollout.

Đăng nhập bằng Bedrock

Nếu đã có AWS credential và muốn dùng Claude Code qua Amazon Bedrock, wizard đăng nhập sẽ dẫn bạn qua từng bước. Bạn chỉ cần hoàn tất điều kiện tiên quyết phía AWS một lần mỗi tài khoản.

1. Bật model Anthropic trong tài khoản AWS: mở Amazon Bedrock console, vào Model catalog, chọn model Anthropic, gửi form use case. Quyền truy cập được cấp ngay sau khi gửi.
2. Khởi động Claude Code và chọn Amazon Bedrock: chạy claude, ở prompt login chọn 3rd-party platform rồi Amazon Bedrock. Nếu đã đăng nhập, chạy /setup-bedrock để mở wizard.
3. Làm theo wizard: chọn cách authenticate với AWS (AWS profile, Bedrock API key, access key/secret, hoặc credential có sẵn trong môi trường). Wizard tự nhận diện region, xác minh model nào tài khoản bạn gọi được, và cho ghim model. Kết quả được lưu vào block env của user settings file.

Sau khi đăng nhập, chạy /setup-bedrock bất cứ lúc nào để mở lại wizard và đổi credential, region, hoặc model pin.

Thiết lập thủ công

Để cấu hình Amazon Bedrock qua biến môi trường thay vì wizard (ví dụ trong CI hoặc rollout tổ chức có script), làm theo các bước dưới đây.

1. Gửi thông tin use case

Trước khi gọi model Anthropic lần đầu, cần gửi thông tin use case - chỉ làm một lần mỗi tài khoản AWS. Nếu dùng AWS Organizations, có thể gửi form một lần từ management account qua API PutUseCaseForModelAccess (cần quyền IAM bedrock:PutUseCaseForModelAccess) - quyền truy cập sẽ tự động mở rộng sang các tài khoản con.

2. Cấu hình AWS credential

Claude Code dùng default AWS SDK credential chain. Có thể cấu hình theo nhiều cách: AWS CLI (aws configure), biến môi trường access key, SSO profile (aws sso login --profile=...), AWS Management Console credentials (aws login), hoặc Amazon Bedrock API key (export AWS_BEARER_TOKEN_BEDROCK=...).

Chú ý

Chi tiết về credential caching, resolution timeout, và cấu hình awsAuthRefresh/awsCredentialExport khá kỹ thuật và thay đổi theo phiên bản Claude Code - đối chiếu tài liệu Amazon Bedrock gốc khi cấu hình cho production.

3. Cấu hình Claude Code

# Bật Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # tuỳ chọn nếu AWS profile đã có sẵn region

# Tuỳ chọn: override region cho model nhỏ/nhanh (Bedrock và Mantle)
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

# Tuỳ chọn: override Bedrock endpoint URL cho custom endpoint hoặc gateway
# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

Lưu ý:

• Khi dùng Amazon Bedrock, lệnh /logout không khả dụng vì authentication xử lý qua AWS credential
• WebSearch tool không khả dụng trên Amazon Bedrock
• Có thể dùng settings file cho biến môi trường như AWS_PROFILE mà không muốn leak sang process khác

4. Ghim phiên bản model

Chú ý

Luôn ghim phiên bản model cụ thể khi triển khai cho nhiều user. Không ghim, alias model như sonnet/opus sẽ resolve về mặc định tích hợp của Claude Code cho Amazon Bedrock, có thể chậm hơn bản mới nhất hoặc chưa khả dụng trong tài khoản của bạn.

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

Các biến này dùng cross-region inference profile ID (tiền tố us.). Nếu dùng region prefix khác hoặc application inference profile, điều chỉnh tương ứng. Ở AWS GovCloud, dùng tiền tố us-gov..

Chú ý

Giá trị model mặc định (Opus vs Sonnet), cách chọn model cho background task, và cảnh báo về chênh lệch giá Opus/Sonnet thay đổi khá thường xuyên theo phiên bản Claude Code - kiểm tra lại bảng model mặc định trong tài liệu gốc trước khi rollout, đặc biệt nếu quan tâm đến chi phí.

Với tổ chức cần map nhiều phiên bản của cùng một model family đến các application inference profile ARN riêng, dùng setting modelOverrides trong settings file thay vì biến ANTHROPIC_DEFAULT_*_MODEL.

Kiểm tra model lúc khởi động

Khi Claude Code khởi động với Amazon Bedrock đã cấu hình, nó xác minh model dự định dùng có truy cập được trong tài khoản của bạn không. Nếu đã ghim một phiên bản cũ hơn mặc định hiện tại và tài khoản gọi được bản mới, Claude Code sẽ prompt cập nhật pin. Nếu chưa ghim và mặc định hiện tại không khả dụng, Claude Code fallback cho session hiện tại và hiển thị thông báo.

Cấu hình IAM

Tạo IAM policy với quyền cần thiết (bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, bedrock:ListInferenceProfiles, bedrock:GetInferenceProfile, và quyền marketplace subscription liên quan). Xem ví dụ JSON policy đầy đủ trong tài liệu Amazon Bedrock IAM.

Mẹo

Tạo một tài khoản AWS riêng cho Claude Code để đơn giản hoá cost tracking và access control.

Context window 1M token

Claude Sonnet 5, Opus 4.6 trở lên, và Sonnet 4.6 hỗ trợ context window 1M token trên Amazon Bedrock. Sonnet 5 chạy qua Mantle endpoint và luôn dùng cửa sổ 1M, không có variant [1m] riêng để chọn. Với các model khác, Claude Code tự bật extended context window khi bạn chọn model variant 1M.

Service tier

Amazon Bedrock service tier cho phép đánh đổi chi phí và độ trễ. Đặt ANTHROPIC_BEDROCK_SERVICE_TIER thành default, flex, hoặc priority.

AWS Guardrails

Amazon Bedrock Guardrails cho phép lọc nội dung cho Claude Code - tạo Guardrail trong console, publish version, rồi thêm Guardrail header vào settings file:

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id\nX-Amzn-Bedrock-GuardrailVersion: 1"
  }
}

Dùng Mantle endpoint

Mantle là endpoint Amazon Bedrock phục vụ model Claude qua shape native Anthropic API thay vì Bedrock Invoke API, dùng chung AWS credential và IAM permission. Bật bằng CLAUDE_CODE_USE_MANTLE=1. Model ID trên Mantle có tiền tố anthropic. không kèm hậu tố version (ví dụ anthropic.claude-sonnet-5).

Chú ý

Chi tiết cách chạy Mantle song song với Invoke API, route qua gateway, và bảng biến môi trường Mantle khá kỹ thuật - xem phần Mantle trong tài liệu gốc nếu tổ chức bạn cần dùng endpoint này.

Troubleshooting

• Authentication loop với SSO và corporate proxy: nếu tab trình duyệt liên tục mở khi dùng AWS SSO, xoá setting awsAuthRefresh khỏi settings file - VPN công ty hoặc TLS-inspection proxy có thể làm gián đoạn luồng SSO, khiến Claude Code hiểu nhầm là auth failure và retry vô hạn.
• Vấn đề region: kiểm tra model khả dụng bằng aws bedrock list-inference-profiles --region your-region, hoặc chuyển sang region hỗ trợ (export AWS_REGION=us-east-1). Nếu gặp lỗi “on-demand throughput isn’t supported”, chỉ định model dưới dạng inference profile ID.
• Lỗi streaming sau gateway/proxy: nếu gặp lỗi bắt đầu bằng Bedrock streaming response has content-type, gateway hoặc proxy đang transform response streaming - cấu hình gateway pass-through nguyên vẹn body và header Content-Type.
• Zero token count trong /context: cập nhật lên v2.1.196 trở lên để khắc phục.

Nguồn

Dịch và biên soạn từ Claude Code on Amazon Bedrock.