Claude Code روی Amazon Bedrock

این یک ترجمهٔ غیررسمی از مستندات Claude Code است که توسط مسیر تهیه شده. نسخهٔ مرجع و معتبر، مستندات رسمی انگلیسی است.

پیش‌نیازها

پیش از پیکربندیِ Claude Code با Bedrock، مطمئن شو که این‌ها را داری:

• یک حسابِ AWS با دسترسیِ فعالِ Bedrock
• دسترسی به مدل‌های موردِنظرِ Claude (برای مثال Claude Sonnet 4.6) در Bedrock
• AWS CLI نصب و پیکربندی‌شده (اختیاری — فقط وقتی لازم است که مکانیزمِ دیگری برای گرفتنِ اعتبارنامه نداشته باشی)
• دسترسی‌های مناسبِ IAM

برای ورود با اعتبارنامه‌های Bedrockِ خودت، ورود با Bedrock در پایین را دنبال کن. برای استقرارِ Claude Code در یک تیم، از مراحلِ راه‌اندازیِ دستی استفاده کن و پیش از عرضه نسخه‌های مدلت را pin کن.

ورود با Bedrock

اگر اعتبارنامه‌های AWS داری و می‌خواهی شروع به استفاده از Claude Code از طریقِ Bedrock کنی، ویزاردِ login تو را از آن عبور می‌دهد. پیش‌نیازهای سمتِ AWS را یک‌بار به‌ازای هر حساب تکمیل می‌کنی؛ ویزارد سمتِ Claude Code را رسیدگی می‌کند.

فعال کردنِ مدل‌های Anthropic در حسابِ AWSَت

در کنسولِ Amazon Bedrock، Model catalog را باز کن، یک مدلِ Anthropic انتخاب کن و فرمِ موردِ استفاده را ثبت کن. دسترسی بلافاصله پس از ثبت اعطا می‌شود. برای AWS Organizations ثبتِ جزئیاتِ موردِ استفاده را ببین و برای دسترسی‌هایی که نقشت لازم دارد پیکربندیِ IAM را.

شروعِ Claude Code و انتخابِ Bedrock

claude را اجرا کن. در پرامپتِ login، 3rd-party platform و سپس Amazon Bedrock را انتخاب کن.

دنبال کردنِ پرامپت‌های ویزارد

انتخاب کن چطور به AWS احراز هویت می‌کنی: یک AWS profile که از دایرکتوریِ ~/.awsَت شناسایی شده، یک Bedrock API key، یک access key و secret، یا اعتبارنامه‌هایی که از قبل در محیطت هستند. ویزارد regionَت را برمی‌دارد، تایید می‌کند که حسابت کدام مدل‌های Claude را می‌تواند فراخواند، و می‌گذارد آن‌ها را pin کنی. نتیجه را در بلاکِ envِ فایلِ تنظیماتِ کاربری‌ات ذخیره می‌کند، پس لازم نیست خودت متغیرهای محیطی را export کنی.

پس از اینکه وارد شدی، هر وقت خواستی /setup-bedrock را اجرا کن تا ویزارد را دوباره باز کنی و اعتبارنامه‌ها، region یا pinهای مدلت را عوض کنی.

راه‌اندازیِ دستی

برای پیکربندیِ Bedrock از طریقِ متغیرهای محیطی به‌جای ویزارد، مثلاً در CI یا یک عرضه‌ی سازمانیِ اسکریپت‌شده، مراحلِ زیر را دنبال کن.

۱. ثبتِ جزئیاتِ موردِ استفاده

کاربرانِ بارِ اولِ مدل‌های Anthropic ملزم‌اند پیش از فراخواندنِ مدل جزئیاتِ موردِ استفاده را ثبت کنند. این یک‌بار به‌ازای هر حسابِ AWS انجام می‌شود.

1. مطمئن شو دسترسی‌های درستِ IAM که در پایین شرح داده شده را داری
2. به کنسولِ Amazon Bedrock برو
3. یک مدلِ Anthropic از Model catalog انتخاب کن
4. فرمِ موردِ استفاده را تکمیل کن. دسترسی بلافاصله پس از ثبت اعطا می‌شود.

اگر از AWS Organizations استفاده می‌کنی، می‌توانی فرم را یک‌بار از حسابِ management با API PutUseCaseForModelAccess ثبت کنی. این فراخوان به دسترسیِ IAMِ bedrock:PutUseCaseForModelAccess نیاز دارد. تاییدیه به‌طور خودکار به حساب‌های فرزند گسترش می‌یابد.

۲. پیکربندیِ اعتبارنامه‌های AWS

Claude Code از زنجیره‌ی پیش‌فرضِ اعتبارنامه‌ی AWS SDK استفاده می‌کند. اعتبارنامه‌هایت را با یکی از این روش‌ها راه‌اندازی کن:

گزینه A: پیکربندیِ AWS CLI

aws configure

گزینه B: متغیرهای محیطی (access key)

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token

گزینه C: متغیرهای محیطی (SSO profile)

aws sso login --profile=<your-profile-name>

export AWS_PROFILE=your-profile-name

گزینه D: اعتبارنامه‌های AWS Management Console

aws login

بیشتر بدان درباره‌ی aws login.

گزینه E: Bedrock API keys

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Bedrock API keyها روشِ احراز هویتِ ساده‌تری بدونِ نیاز به اعتبارنامه‌های کاملِ AWS فراهم می‌کنند. درباره‌ی Bedrock API keyها بیشتر بدان.

پیکربندیِ پیشرفته‌ی اعتبارنامه

Claude Code از تازه‌سازیِ خودکارِ اعتبارنامه برای AWS SSO و ارائه‌دهنده‌های هویتِ سازمانی پشتیبانی می‌کند. این تنظیمات را به فایلِ تنظیماتِ Claude Codeَت اضافه کن (برای مکانِ فایل‌ها تنظیمات را ببین).

این دو تنظیم شرایطِ راه‌انداز متفاوتی دارند:

• awsAuthRefresh: تنها وقتی اجرا می‌شود که Claude Code تشخیص دهد اعتبارنامه‌های AWSَت منقضی شده‌اند، چه محلی بر اساسِ زمان‌سنجشان و چه وقتی Bedrock خطای اعتبارنامه برمی‌گرداند، سپس درخواست را با اعتبارنامه‌های تازه‌شده دوباره تلاش می‌کند.
• awsCredentialExport: در شروعِ نشست و در هر بارگذاریِ دوباره‌ی اعتبارنامه اجرا می‌شود، حتی وقتی اعتبارنامه‌های زنجیره‌ی پیش‌فرضِ ارائه‌دهنده‌ی اعتبارنامه‌ی AWSَت هنوز معتبرند. این را وقتی استفاده کن که حسابِ Bedrockَت به اعتبارنامه‌های بین‌حسابی نیاز دارد که با آن‌هایی که زنجیره‌ی پیش‌فرض حل می‌کند فرق دارند.

مثالِ پیکربندی

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}

توضیحِ تنظیماتِ پیکربندی

awsAuthRefresh: این را برای فرمان‌هایی استفاده کن که دایرکتوریِ .aws را تغییر می‌دهند، مثلِ به‌روزرسانیِ اعتبارنامه‌ها، کشِ SSO یا فایل‌های config. خروجیِ فرمان به کاربر نشان داده می‌شود، اما ورودیِ تعاملی پشتیبانی نمی‌شود. این برای جریان‌های SSOِ مبتنی‌بر‌مرورگر خوب کار می‌کند، جایی که CLI یک URL یا کد نشان می‌دهد و تو احراز هویت را در مرورگر تکمیل می‌کنی.

awsCredentialExport: این را فقط وقتی استفاده کن که نمی‌توانی .aws را تغییر دهی و باید مستقیم اعتبارنامه‌ها را برگردانی. این فرمان هر وقت اعتبارنامه‌ها نیاز به تازه‌سازی دارند اجرا می‌شود، نه فقط وقتی منقضی‌اند. خروجی در سکوت گرفته می‌شود و به کاربر نشان داده نمی‌شود. فرمان باید JSON را در این قالب خروجی دهد:

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value"
  }
}

۳. پیکربندیِ Claude Code

متغیرهای محیطیِ زیر را تنظیم کن تا Bedrock فعال شود:

# Enable Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # optional if your AWS profile already sets a region

# Optional: Override the AWS region for the small/fast model (Bedrock and Mantle).
# On Bedrock, has no effect without ANTHROPIC_DEFAULT_HAIKU_MODEL
# or the deprecated ANTHROPIC_SMALL_FAST_MODEL set.
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

# Optional: Override the Bedrock endpoint URL for custom endpoints or gateways
# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

هنگامِ فعال کردنِ Bedrock برای Claude Code، این‌ها را در نظر داشته باش:

• {/* min-version: 2.1.172 */}از v2.1.172 به بعد، فقط لازم است AWS_REGION را تنظیم کنی تا regionِ AWS profileَت را override کنی یا وقتی profileَت region ندارد. Claude Code region را به این ترتیب حل می‌کند:

  • AWS_REGION
  • AWS_DEFAULT_REGION
  • regionِ تنظیم‌شده روی AWS profileِ فعالت، که اول از فایلِ مشترکِ اعتبارنامه‌ی AWS و سپس از فایلِ مشترکِ config خوانده می‌شود، مطابقِ تقدمِ AWS SDK
  • us-east-1

  profileِ فعال اگر تنظیم شده باشد AWS_PROFILE است، در غیرِ این صورت default. AWS_SHARED_CREDENTIALS_FILE یا AWS_CONFIG_FILE را تنظیم کن تا به مسیرهای غیرپیش‌فرضِ فایل اشاره کنند. /status را اجرا کن تا regionِ حل‌شده را ببینی. وقتی region از فایل‌های configِ AWSَت یا از fallbackِ پیش‌فرض آمده باشد، /status منبع را هم یادداشت می‌کند. روی v2.1.171 و قدیمی‌تر، Claude Code فایل‌های configِ AWS را نمی‌خواند، پس AWS_REGION را صریح تنظیم کن.

• هنگامِ استفاده از Bedrock، فرمانِ /logout در دسترس نیست چون احراز هویت از طریقِ اعتبارنامه‌های AWS رسیدگی می‌شود.

• ابزارِ WebSearch روی Bedrock در دسترس نیست. رفتارِ ابزارِ WebSearch را ببین.

• می‌توانی از فایل‌های تنظیمات برای متغیرهای محیطی‌ای مثلِ AWS_PROFILE استفاده کنی که نمی‌خواهی به فرایندهای دیگر درز کنند. برای اطلاعاتِ بیشتر تنظیمات را ببین.

۴. pin کردنِ نسخه‌های مدل

احتیاط

هنگامِ استقرار برای چندین کاربر، نسخه‌های مشخصِ مدل را pin کن. بدونِ pin کردن، نام‌های مستعارِ مدل مثلِ sonnet و opus به پیش‌فرضِ داخلیِ Claude Code برای Bedrock حل می‌شوند، که می‌تواند از تازه‌ترین انتشار عقب باشد و ممکن است هنوز در حسابت در دسترس نباشد. Claude Code در شروع، وقتی پیش‌فرض در دسترس نباشد، به نسخه‌ی قبلی برمی‌گردد، اما pin کردن می‌گذارد کنترل کنی کاربرانت کِی به مدلی تازه منتقل شوند.

این متغیرهای محیطی را روی شناسه‌های مشخصِ مدلِ Bedrock تنظیم کن.

بدونِ ANTHROPIC_DEFAULT_OPUS_MODEL، نام مستعارِ opus روی Bedrock به Opus 4.6 حل می‌شود. آن را روی شناسه‌ی Opus 4.8 تنظیم کن تا از تازه‌ترین مدل استفاده کنی:

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'

این متغیرها از شناسه‌های inference profileِ بین‌منطقه‌ای (با پیشوندِ us.) استفاده می‌کنند. اگر از پیشوندِ منطقه‌ی متفاوتی یا از application inference profileها استفاده می‌کنی، متناسب با آن تنظیم کن. در مناطقِ AWS GovCloud، از پیشوندِ us-gov. استفاده کن. برای شناسه‌های مدلِ جاری و قدیمی، مرورِ کلیِ مدل‌ها را ببین. برای فهرستِ کاملِ متغیرهای محیطی پیکربندیِ مدل را ببین.

Claude Code وقتی هیچ متغیرِ pin تنظیم نشده باشد از این مدل‌های پیش‌فرض استفاده می‌کند:

نوعِ مدل	مقدارِ پیش‌فرض
مدلِ اصلی	us.anthropic.claude-sonnet-4-5-20250929-v1:0
مدلِ کوچک/سریع	همان مدلِ اصلی

کارهای پس‌زمینه مثلِ تولیدِ عنوانِ نشست از مدلِ کوچک/سریع استفاده می‌کنند، که معمولاً یک مدلِ کلاسِ Haiku است. روی Bedrock، Claude Code این را به مدلِ اصلی پیش‌فرض می‌کند چون ممکن است Haiku در هر حساب یا منطقه‌ای فعال نباشد. برای استفاده از Haiku برای کارهای پس‌زمینه، ANTHROPIC_DEFAULT_HAIKU_MODEL را روی شناسه‌ی مدلی که در حسابت در دسترس است تنظیم کن.

برای سفارشی‌سازیِ بیشترِ مدل‌ها، از یکی از این روش‌ها استفاده کن:

# Using inference profile ID
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# Using application inference profile ARN
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# Optional: Disable prompt caching if needed
export DISABLE_PROMPT_CACHING=1

# Optional: Request 1-hour prompt cache TTL instead of the 5-minute default
export ENABLE_PROMPT_CACHING_1H=1

TTLِ کشِ ۱‌ساعته با نرخی بالاتر از پیش‌فرضِ ۵‌دقیقه‌ای صورت‌حساب می‌شود. طولِ عمرِ کش را ببین.

یادداشت

prompt caching ممکن است در همه‌ی مناطقِ Bedrock در دسترس نباشد. اگر شمارِ توکن‌های کش روی صفر می‌ماند، در مستنداتِ Bedrock مدل‌ها، مناطق و محدودیت‌های پشتیبانی‌شده را چک کن.

نگاشتِ هر نسخه‌ی مدل به یک inference profile

متغیرهای محیطیِ ANTHROPIC_DEFAULT_*_MODEL به‌ازای هر خانواده‌ی مدل یک inference profile پیکربندی می‌کنند. اگر سازمانت نیاز دارد چند نسخه از همان خانواده را در انتخابگرِ /model عرضه کند، که هرکدام به ARNِ application inference profileِ خودش مسیریابی شود، به‌جایش از تنظیمِ modelOverrides در فایلِ تنظیماتت استفاده کن.

این مثال چهار نسخه‌ی Opus را به ARNهای متمایز نگاشت می‌کند تا کاربران بتوانند بدونِ دور زدنِ inference profileهای سازمانت بینشان جابه‌جا شوند:

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-47-prod",
    "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",
    "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",
    "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"
  }
}

وقتی کاربری یکی از این نسخه‌ها را در /model انتخاب می‌کند، Claude Code با ARNِ نگاشت‌شده Bedrock را فراخوانی می‌کند. نسخه‌هایی بدونِ override به شناسه‌ی مدلِ داخلیِ Bedrock یا هر inference profileِ هم‌خوانی که در شروع کشف شده برمی‌گردند. برای جزئیاتِ اینکه overrideها چطور با availableModels و دیگر تنظیماتِ مدل تعامل می‌کنند، override کردنِ شناسه‌های مدل به‌ازای هر نسخه را ببین.

چک‌های مدل در شروع

وقتی Claude Code با Bedrockِ پیکربندی‌شده شروع می‌شود، تایید می‌کند که مدل‌هایی که قصدِ استفاده‌شان را دارد در حسابت در دسترس‌اند. این چک به Claude Code نسخه‌ی v2.1.94 یا بالاتر نیاز دارد.

اگر نسخه‌ای از مدل را pin کرده‌ای که از پیش‌فرضِ جاریِ Claude Code قدیمی‌تر است، و حسابت می‌تواند نسخه‌ی تازه‌تر را فراخواند، Claude Code از تو می‌خواهد pin را به‌روز کنی. پذیرفتن، شناسه‌ی مدلِ تازه را در فایلِ تنظیماتِ کاربری‌ات می‌نویسد و Claude Code را راه‌اندازیِ دوباره می‌کند. ردّ کردن تا تغییرِ نسخه‌ی پیش‌فرضِ بعدی به‌خاطر سپرده می‌شود. pinهایی که به یک ARNِ application inference profile اشاره می‌کنند رد می‌شوند، چون آن‌ها توسطِ مدیرت مدیریت می‌شوند.

اگر مدلی pin نکرده‌ای و پیش‌فرضِ جاری در حسابت در دسترس نیست، Claude Code برای نشستِ جاری به نسخه‌ی قبلی برمی‌گردد و اعلانی نشان می‌دهد. این fallback ماندگار نمی‌شود. مدلِ تازه‌تر را در حسابِ Bedrockَت فعال کن یا نسخه‌ای را pin کن تا انتخاب دائمی شود.

پیکربندیِ IAM

یک خط‌مشیِ IAM با دسترسی‌های لازم برای Claude Code بساز:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles",
        "bedrock:GetInferenceProfile"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*:*:application-inference-profile/*",
        "arn:aws:bedrock:*:*:foundation-model/*"
      ]
    },
    {
      "Sid": "AllowMarketplaceSubscription",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:ViewSubscriptions",
        "aws-marketplace:Subscribe"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:CalledViaLast": "bedrock.amazonaws.com"
        }
      }
    }
  ]
}

برای دسترسی‌های محدودتر، می‌توانی Resource را به ARNهای مشخصِ inference profile محدود کنی.

bedrock:GetInferenceProfile به Claude Code اجازه می‌دهد یک ARNِ application inference profile را به foundation modelِ پشتیبانش حل کند، که برای انتخابِ شکلِ درستِ درخواست برای آن مدل استفاده می‌شود.

اگر توکن این دسترسی را نداشته باشد، Claude Code به‌طور خودکار با یک‌بار تلاشِ دوباره با شکلِ جایگزین بهبود می‌یابد، پس درخواست‌ها همچنان موفق می‌شوند ولی هر مدلِ تازه یک رفت‌وبرگشتِ اضافی اضافه می‌کند. اعطای دسترسی از این تلاشِ دوباره جلوگیری می‌کند. این بیشترِ مواقع به استقرارهای AWS_BEARER_TOKEN_BEDROCK مربوط است، جایی که خط‌مشیِ توکن معمولاً باریک‌تر از یک نقشِ کاملِ IAM است.

برای جزئیات، مستنداتِ IAMِ Bedrock را ببین.

یادداشت

یک حسابِ AWSِ اختصاصی برای Claude Code بساز تا ردیابیِ هزینه و کنترلِ دسترسی ساده شود.

پنجره‌ی کانتکستِ ۱M توکنی

Claude Opus 4.6 و بالاتر، و Sonnet 4.6، از پنجره‌ی کانتکستِ ۱M توکنی روی Amazon Bedrock پشتیبانی می‌کنند. Claude Code وقتی یک نوعِ ۱M از مدل را انتخاب می‌کنی به‌طور خودکار پنجره‌ی کانتکستِ گسترده را فعال می‌کند.

ویزاردِ راه‌اندازی هنگامِ pin کردنِ مدل‌ها یک گزینه‌ی کانتکستِ ۱M عرضه می‌کند. برای فعال کردنش روی مدلی که به‌صورتِ دستی pin شده، [1m] را به شناسه‌ی مدل بچسبان. برای جزئیات pin کردنِ مدل‌ها برای استقرارهای شخصِ ثالث را ببین.

ردیف‌های سرویس

ردیف‌های سرویسِ Amazon Bedrock می‌گذارند هزینه را در برابرِ تأخیر معاوضه کنی. ANTHROPIC_BEDROCK_SERVICE_TIER را روی default، flex یا priority تنظیم کن:

export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

Claude Code این را به‌عنوانِ هدرِ X-Amzn-Bedrock-Service-Tier روی هر درخواست می‌فرستد. در دسترس بودنِ ردیف بر اساسِ مدل و منطقه فرق می‌کند. ظرفیتِ رزروشده به‌جای این تنظیم از یک ARNِ provisioned throughput به‌عنوانِ شناسه‌ی مدل استفاده می‌کند.

AWS Guardrails

Amazon Bedrock Guardrails می‌گذارند فیلترِ محتوا برای Claude Code پیاده‌سازی کنی. در کنسولِ Amazon Bedrock یک Guardrail بساز، نسخه‌ای منتشر کن، سپس هدرهای Guardrail را به فایلِ تنظیماتت اضافه کن. اگر از inference profileهای بین‌منطقه‌ای استفاده می‌کنی Cross-Region inference را روی Guardrailَت فعال کن.

مثالِ پیکربندی:

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

استفاده از endpointِ Mantle

Mantle یک endpointِ Amazon Bedrock است که مدل‌های Claude را از طریقِ شکلِ بومیِ Anthropic API به‌جای Bedrock Invoke API سرو می‌کند. از همان اعتبارنامه‌های AWS، دسترسی‌های IAM و پیکربندیِ awsAuthRefresh که پیش‌تر در این صفحه شرح داده شد استفاده می‌کند.

یادداشت

Mantle به Claude Code نسخه‌ی v2.1.94 یا بالاتر نیاز دارد. برای چک کردن claude --version را اجرا کن.

فعال کردنِ Mantle

با اعتبارنامه‌های AWS که از قبل پیکربندی شده‌اند، CLAUDE_CODE_USE_MANTLE را تنظیم کن تا درخواست‌ها به endpointِ Mantle مسیریابی شوند:

export CLAUDE_CODE_USE_MANTLE=1
export AWS_REGION=us-east-1

Claude Code آدرسِ endpoint را از منطقه‌ی AWS می‌سازد. {/* min-version: 2.1.172 */}از v2.1.172 به بعد، region با همان تقدمِ Bedrock در بالا حل می‌شود؛ نسخه‌های قدیمی‌تر فقط از AWS_REGION استفاده می‌کنند. برای override کردنِ URL برای یک endpoint یا gatewayِ سفارشی، ANTHROPIC_BEDROCK_MANTLE_BASE_URL را تنظیم کن.

/status را داخلِ Claude Code اجرا کن تا تایید کنی. خطِ ارائه‌دهنده وقتی Mantle فعال است Amazon Bedrock (Mantle) را نشان می‌دهد.

انتخابِ یک مدلِ Mantle

Mantle از شناسه‌های مدلِ پیشوندخورده با anthropic. و بدونِ پسوندِ نسخه استفاده می‌کند، برای مثال anthropic.claude-haiku-4-5. مدل‌های در دسترسِ حسابت به آنچه سازمانت اعطا شده بستگی دارد؛ شناسه‌های مدلِ بیشتر در موادِ onboardingَت از AWS فهرست شده‌اند. برای درخواستِ دسترسی به مدل‌های allowlist‌شده با تیمِ حسابِ AWSَت تماس بگیر.

مدل را با پرچمِ --model یا با /model داخلِ Claude Code تنظیم کن:

claude --model anthropic.claude-haiku-4-5

اجرای Mantle در کنارِ Invoke API

مدل‌های در دسترسِ تو روی Mantle ممکن است هر مدلی که امروز استفاده می‌کنی را شامل نشوند. تنظیمِ هردوی CLAUDE_CODE_USE_BEDROCK و CLAUDE_CODE_USE_MANTLE می‌گذارد Claude Code هر دو endpoint را از همان نشست فراخوانی کند. شناسه‌های مدلی که با قالبِ Mantle هم‌خوانی دارند به Mantle مسیریابی می‌شوند، و همه‌ی شناسه‌های مدلِ دیگر به Bedrock Invoke API می‌روند.

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

برای نمایشِ یک مدلِ Mantle در انتخابگرِ /model، شناسه‌اش را در availableModels در فایلِ تنظیماتت فهرست کن. این تنظیم انتخابگر را هم به ورودی‌های فهرست‌شده محدود می‌کند، پس هر نام مستعاری که می‌خواهی در دسترس بماند را شامل کن:

{
  "availableModels": ["opus", "sonnet", "haiku", "anthropic.claude-haiku-4-5"]
}

ورودی‌هایی با پیشوندِ anthropic. به‌عنوانِ گزینه‌های سفارشیِ انتخابگر اضافه و به Mantle مسیریابی می‌شوند. anthropic.claude-haiku-4-5 را با شناسه‌ی مدلی که به حسابت اعطا شده جایگزین کن. برای اینکه ببینی availableModels چطور با دیگر تنظیماتِ مدل تعامل می‌کند، محدود کردنِ انتخابِ مدل را ببین.

وقتی هر دو ارائه‌دهنده فعال‌اند، /status Amazon Bedrock + Amazon Bedrock (Mantle) را نشان می‌دهد.

مسیریابیِ Mantle از طریقِ یک gateway

اگر سازمانت ترافیکِ مدل را از طریقِ یک LLM gatewayِ متمرکز مسیریابی می‌کند که اعتبارنامه‌های AWS را سمتِ سرور تزریق می‌کند، احراز هویتِ سمتِ کلاینت را غیرفعال کن تا Claude Code درخواست‌ها را بدونِ امضای SigV4 یا هدرهای x-api-key بفرستد:

export CLAUDE_CODE_USE_MANTLE=1
export CLAUDE_CODE_SKIP_MANTLE_AUTH=1
export ANTHROPIC_BEDROCK_MANTLE_BASE_URL=https://your-gateway.example.com

متغیرهای محیطیِ Mantle

این متغیرها مختصِ endpointِ Mantle‌اند. برای فهرستِ کامل متغیرهای محیطی را ببین.

متغیر	هدف
CLAUDE_CODE_USE_MANTLE	فعال کردنِ endpointِ Mantle. روی 1 یا true تنظیم کن.
ANTHROPIC_BEDROCK_MANTLE_BASE_URL	override کردنِ آدرسِ پیش‌فرضِ endpointِ Mantle
CLAUDE_CODE_SKIP_MANTLE_AUTH	رد کردنِ احراز هویتِ سمتِ کلاینت برای راه‌اندازی‌های proxy
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION	override کردنِ منطقه‌ی AWS برای مدلِ کلاسِ Haiku (مشترک با Bedrock)

عیب‌یابی

حلقه‌ی احراز هویت با SSO و proxyهای سازمانی

اگر هنگامِ استفاده از AWS SSO تب‌های مرورگر مدام spawn می‌شوند، تنظیمِ awsAuthRefresh را از فایلِ تنظیماتت بردار. این می‌تواند وقتی رخ دهد که VPNهای سازمانی یا proxyهای بازرسیِ TLS جریانِ مرورگرِ SSO را قطع کنند. Claude Code اتصالِ قطع‌شده را به‌منزله‌ی شکستِ احراز هویت می‌گیرد، awsAuthRefresh را دوباره اجرا می‌کند و بی‌نهایت حلقه می‌زند.

اگر محیطِ شبکه‌ات با جریان‌های خودکارِ SSOِ مبتنی‌بر‌مرورگر تداخل دارد، به‌جای تکیه بر awsAuthRefresh پیش از شروعِ Claude Code aws sso login را به‌صورتِ دستی استفاده کن.

مشکلاتِ منطقه

اگر با مشکلاتِ منطقه برخوردی:

• در دسترس بودنِ مدل را چک کن: aws bedrock list-inference-profiles --region your-region
• به منطقه‌ای پشتیبانی‌شده سوییچ کن: export AWS_REGION=us-east-1
• استفاده از inference profileها برای دسترسیِ بین‌منطقه‌ای را در نظر بگیر

اگر خطای “on-demand throughput isn’t supported” گرفتی:

• مدل را به‌عنوانِ شناسه‌ی inference profile مشخص کن

Claude Code از Bedrock Invoke API استفاده می‌کند و از Converse API پشتیبانی نمی‌کند.

خطاهای endpointِ Mantle

اگر /status پس از تنظیمِ CLAUDE_CODE_USE_MANTLE Amazon Bedrock (Mantle) را نشان نداد، متغیر به فرایند نمی‌رسد. تایید کن که در shellی که claude را از آن راه انداختی export شده، یا آن را در بلاکِ envِ فایلِ تنظیماتت تنظیم کن.

یک 403 از endpointِ Mantle با اعتبارنامه‌های معتبر یعنی به حسابِ AWSَت دسترسی به مدلی که درخواست کرده‌ای اعطا نشده. برای درخواستِ دسترسی با تیمِ حسابِ AWSَت تماس بگیر.

یک 400 که شناسه‌ی مدل را نام می‌برد یعنی آن مدل روی Mantle سرو نمی‌شود. Mantle ردیفِ مدلِ خودش را جدا از کاتالوگِ استانداردِ Bedrock دارد، پس شناسه‌های inference profile مثلِ us.anthropic.claude-sonnet-4-6 کار نمی‌کنند. از یک شناسه‌ی قالبِ-Mantle استفاده کن، یا هر دو endpoint را فعال کن تا Claude Code هر درخواست را به endpointی مسیریابی کند که مدل در آن در دسترس است.

منابعِ اضافی

• مستنداتِ Bedrock
• هزینه‌ی Bedrock
• inference profileهای Bedrock
• مصرفِ توکن و سهمیه‌های Bedrock
• Claude Code روی Amazon Bedrock: راهنمای راه‌اندازیِ سریع
• پیاده‌سازیِ پایشِ Claude Code (Bedrock)