תיעוד 66

`Claude Code` ב-Claude Platform ב-AWS

הגדרת Claude Code לשימוש ב-Claude API המופעל על ידי Anthropic עם אימות AWS, בקרת גישה של IAM וחיוב דרך AWS Marketplace.

פורסים את Claude Code ברחבי הארגון שלכם? שוחחו עם מחלקת המכירות על תוכניות לארגונים (enterprise), SSO וחיוב מרוכז: צפייה בתוכניות | פנייה למכירות.

Claude Platform on AWS הוא ה-Claude API המופעל על ידי Anthropic עם אימות AWS, בקרת גישה של IAM וחיוב דרך AWS Marketplace. הבקשות מגיעות ישירות ל-API של Anthropic, כך שאתם מקבלים את אותם הדגמים ואותן תכונות API כמו ב-Claude API באותו לוח זמנים של שחרור גרסאות. אתם מבצעים אימות באמצעות פרטי אימות של AWS או מפתח API של סביבת עבודה (workspace), ומשלמים דרך AWS Marketplace.

תכונות צד לקוח ש-Claude Code מפעיל דרך שירות ה-feature-flag של Anthropic כבויות כברירת מחדל, והכלי advisor אינו זמין. עיינו ב-טבלת זמינות התכונות לרשימה המלאה.

השתמשו במדריך זה כדי להפנות את Claude Code אל סביבת עבודה שכבר הקמתם דרך Claude Platform on AWS. לגבי המנוי ב-AWS והגדרת סביבת העבודה שקודמים לכך, עיינו ב-תיעוד של Claude Platform on AWS.

הערה: הרשמה למנוי דרך AWS Marketplace מקצה ארגון Anthropic חדש המשויך לחשבון ה-AWS שלכם. ארגון זה נפרד מכל ארגון שכבר יש לכם ב-Anthropic, ופרטי אימות אינם עוברים ביניהם. השתמשו ב-workspace ID ובמפתחות ה-API מהארגון המקושר ל-AWS, ולא מחשבון Claude Console קיים.

#דרישות מוקדמות

לפני הגדרת Claude Code, אתם זקוקים ל:

מנוי פעיל ל-Claude Platform on AWS דרך AWS Marketplace
סביבת עבודה בארגון Anthropic המקושר ל-AWS שלכם, יחד עם ה-workspace ID שלה
ישות IAM principal עם הרשאה להפעיל את שירות Anthropic, או מפתח API המוגבל לסביבת העבודה
פרטי אימות של AWS בסביבה שלכם, ב-~/.aws/credentials, או מ-IAM role מצורף אם אתם מעוניינים באימות SigV4. ה-AWS CLI נדרש רק עבור תהליך התחברות ב-SSO.

#הגדרה

#1. הגדרת פרטי אימות של AWS

Claude Code תומך בשתי שיטות אימות עבור Claude Platform on AWS. בחרו בשיטה המתאימה לאופן שבו הצוות שלכם מנהל גישה.

אפשרות א: פרטי אימות של AWS עם SigV4

Claude Code חותם על בקשות באמצעות SigV4 בעזרת שרשרת פרטי האימות הסטנדרטית של AWS: משתני סביבה, פרטי אימות משותפים ב-~/.aws/credentials, תפקידי IAM roles, הפעלות של AWS SSO, וכל מקור אחר שבו ה-AWS SDK תומך.

לשימוש מקומי, התחברו עם ה-AWS CLI לפני הפעלת Claude Code. הדוגמה להלן משתמשת בפרופיל SSO, אך כל שיטה שמייצרת פרטי אימות במיקומים הסטנדרטיים תעבוד.

aws sso login --profile my-profile
export AWS_PROFILE=my-profile

עבור CI ואוטומציה, תנו ל-runner תפקיד IAM role עם הרשאה להפעיל את שירות Anthropic והגדירו את AWS_REGION. שרשרת פרטי האימות מזהה את ה-role באופן אוטומטי.

אם פרטי ה-SSO שלכם פגים באמצע העבודה, הגדירו את awsAuthRefresh כדי ש-Claude Code יריץ מחדש את פקודת ההתחברות שלכם וינסה שוב במקום להיכשל. רענון אוטומטי ב-Claude Platform on AWS דורש את Claude Code בגרסה v2.1.198 ומעלה. גרסאות מוקדמות יותר עוצרות עם הנחיה להריץ /login, שאינה יכולה לרענן פרטי אימות של AWS. הוסיפו את הפקודה לקובץ ההגדרות שלכם, כגון ~/.claude/settings.json:

{
  "awsAuthRefresh": "aws sso login --profile my-profile"
}

Claude Code מריץ פקודה זו גם בעת ההפעלה כאשר אינו מצליח לאמת את פרטי ה-AWS הקיימים שלכם, ומציג את פלט הפקודה בחלונית Authentication עד לסיום ההתחברות.

כאשר awsAuthRefresh מוגדר, הריצו /login, בחרו ב-3rd-party platform, ולאחר מכן בחרו ב-Claude Platform on AWS · refresh credentials תחת Using 3rd-party platforms. Claude Code יריץ את הפקודה שהוגדרה ויקרא מחדש את פרטי האימות של AWS ללא צורך בהפעלה מחדש. אפשרות זו דורשת את Claude Code בגרסה v2.1.186 ומעלה.

אפשרות ב: מפתח API של סביבת עבודה

מפתח API של סביבת עבודה הוא סוד ארוך טווח, שימושי כאשר אינכם רוצים לנהל פרטי אימות מאוחדים (federated) של AWS. צרו מפתח כזה ב-AWS Console תחת Claude Platform on AWS → API keys והגדירו אותו כמשתנה ANTHROPIC_AWS_API_KEY:

export ANTHROPIC_AWS_API_KEY=sk-ant-xxxxx

המפתח נשלח בתור x-api-key וקודם ל-SigV4, כך שמתבצעת התעלמות מכל פרטי אימות של AWS שנמצאים בסביבה שלכם. מפתחות API מארגון Claude Console נפרד לא יעבדו כאן.

התייחסו למפתחות API של סביבת עבודה כמו לכל פרט אימות בסביבת ייצור. בלוק ה-env בקובץ הגדרות המשתמש הוא דרך נוחה להגביל את המפתח למחשב שלכם מבלי לייצא אותו באופן גלובלי.

הערה: הפקודות /login ו-/logout אינן מחברות אתכם למנוי Claude.ai עבור Claude Platform on AWS. האימות מתבצע דרך פרטי האימות של AWS או דרך מפתח ה-API של סביבת העבודה.

#2. הגדרת Claude Code

הגדירו את משתני הסביבה שמנתבים את Claude Code דרך Claude Platform on AWS במקום ה-API המוגדר כברירת מחדל של Anthropic.

export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export AWS_REGION=us-east-1

המשתנה ANTHROPIC_AWS_WORKSPACE_ID הוא שדה חובה. Claude Code שולח אותו בכל בקשה ככותרת anthropic-workspace-id. החליפו את ערך הדוגמה wrkspc_01ABCDEFGHIJKLMN במזהה סביבת העבודה שלכם מהגדרות Claude Platform on AWS שלכם.

Claude Code מחשב את כתובת ה-URL הבסיסית בתור https://aws-external-anthropic.{region}.api.aws מתוך אזור ה-AWS, אותו הוא קובע לפי אותו סדר קדימויות כמו Amazon Bedrock. כדי לדרוס את כתובת ה-URL ישירות, הגדירו את ANTHROPIC_AWS_BASE_URL.

השימוש ב-Claude Platform on AWS דורש בחירה מפורשת (opt-in) גם כאשר קיימים פרטי אימות של AWS בסביבה שלכם. ל-Amazon Bedrock ול-Microsoft Foundry יש עדיפות בניתוח ספק השירות, לכן בטלו את ההגדרה של CLAUDE_CODE_USE_BEDROCK ושל CLAUDE_CODE_USE_FOUNDRY אם הם מוגדרים.

#3. קיבוע גרסאות מודלים

Claude Platform on AWS משתמש באותם מזהי מודלים כמו ה-API הישיר של Claude.

כינויי ברירת המחדל fable, opus, sonnet ו-haiku מפנים לברירות המחדל המובנות של Claude Code עבור Claude Platform on AWS, אשר עשויות לפגר אחרי הגרסה החדשה ביותר. ללא ANTHROPIC_DEFAULT_OPUS_MODEL, הכינוי opus מפנה ל-Opus 5. לפני גרסה v2.1.219 הוא הפנה ל-Opus 4.8, ולפני גרסה v2.1.207 ל-Opus 4.7.

אם אתם פורסים את Claude Code לצוות, קבעו את מזהי המודלים באופן מפורש כדי שגרסה חדשה לא תעביר את כולם בבת אחת:

export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

לרשימה המלאה של מזהי מודלים וכינויים, עיינו ב-סקירת מודלים. למשתנים נוספים הקשורים למודלים, עיינו ב-הגדרת מודלים.

שמירת פרומפטים במטמון (Prompt caching) מופעלת באופן אוטומטי. כדי לבקש שמירה במטמון לזמן של שעה אחת (TTL) במקום ברירת המחדל של 5 דקות, הגדירו ENABLE_PROMPT_CACHING_1H=1. ה-API מחייב כתיבות למטמון של שעה אחת בתעריף גבוה יותר. עיינו ב-תמחור שמירת פרומפטים במטמון עבור התעריפים.

כדי להגדיר זמני TTL שונים עבור השיחה הראשית שלכם ועבור הבקשות ש-Claude Code מבצע מחוצה לה, בחרו את ה-TTL בעצמכם.

#4. הפעלה ואימות

הפעילו את Claude Code ואשרו את הניתוב:

claude

באנר הפתיחה מציג Claude Platform on AWS כאשר ספק השירות פעיל. הריצו /status כדי לבדוק את הפרטים: השורה API provider מציגה Claude Platform on AWS, והפלט כולל את ה-Workspace ID שלכם, את ה-AWS region, ואת ה-Claude Platform on AWS base URL אם הגדרתם דריסה.

#שימוש ב-Agent SDK

ה-Agent SDK קורא את אותם משתני סביבה כמו ה-CLI, כך שכל תוכנית שמפעילה את תהליך המשנה (subprocess) של Claude Code יכולה לפנות אל Claude Platform on AWS על ידי ייצוא של CLAUDE_CODE_USE_ANTHROPIC_AWS, ANTHROPIC_AWS_WORKSPACE_ID, וכן ANTHROPIC_AWS_API_KEY או פרטי אימות של AWS לפני הקריאה.

import { query } from "@anthropic-ai/claude-agent-sdk";

process.env.CLAUDE_CODE_USE_ANTHROPIC_AWS = "1";
process.env.ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN";
process.env.AWS_REGION = "us-east-1";

for await (const msg of query({ prompt: "What's in this repo?" })) {
  console.log(msg);
}

דוגמה זו מסתמכת על שרשרת פרטי האימות הסביבתית של AWS עבור SigV4. כדי לבצע אימות באמצעות מפתח API של סביבת עבודה במקום זאת, הגדירו את ANTHROPIC_AWS_API_KEY באותו אופן. לסקירה רחבה יותר של יכולות ה-Agent SDK, עיינו ב-סקירת Agent SDK.

#ניתוב דרך שרת פרוקסי ארגוני

כדי לנתב תעבורה דרך פרוקסי או שער LLM gateway, הגדירו את ANTHROPIC_AWS_BASE_URL לכתובת הפרוקסי. Claude Code שולח בקשות לכתובת URL זו עם אותן כותרות של סביבת עבודה ואימות, כך שכל שער שמעביר אותן ללא שינוי יעבוד.

export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export ANTHROPIC_AWS_BASE_URL=https://anthropic-proxy.example.com

אם השער שלכם חותם על בקשות בעצמו, הגדירו CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1 כדי ש-Claude Code ישלח בקשות לא חתומות ויאפשר לשער להוסיף כותרות SigV4 לפני העברתן ל-AWS. אם השער דורש טוקן משלו, הגדירו אותו ב-ANTHROPIC_AUTH_TOKEN.

export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export ANTHROPIC_AWS_BASE_URL=https://anthropic-proxy.example.com

#פתרון בעיות

הריצו /status כדי לראות את ספק השירות שנבחר וכן כל workspace ID, אזור (region), עקיפת כתובת URL בסיסית והגדרת דילוג על אימות (auth-skip) שהוגדרו במפורש. זוהי הדרך המהירה ביותר לאמת ש-Claude Code אכן פונה אל Claude Platform on AWS.

#שגיאות 403 Forbidden או AccessDenied בכל בקשה

סביר להניח שלישות ה-IAM principal ש-Claude Code זיהה חסרה הרשאה להפעיל את שירות Anthropic בסביבת העבודה שלכם. בדקו את ה-role המצורף לפרופיל ה-AWS שלכם או ל-runner שהפעיל את Claude Code, וודאו שיש לו את פעולות aws-external-anthropic המתועדות ב-מדריך פעולות IAM.

אם הגדרתם את ANTHROPIC_AWS_API_KEY, המפתח מקבל עדיפות על פני SigV4, ומפתח לא עדכני גורם לאותה שגיאה. צרו מחדש את המפתח ב-AWS Console תחת Claude Platform on AWS → API keys או בטלו את הגדרת המשתנה כדי לחזור לשימוש בפרטי האימות של AWS.

#בקשות נכשלות עם שגיאת missing-workspace

סביר להניח ש-ANTHROPIC_AWS_WORKSPACE_ID אינו מוגדר או ריק. כל בקשה אל Claude Platform on AWS חייבת לכלול את ה-workspace ID. הוא אינו נגזר מפרטי האימות של AWS שלכם. מצאו את המזהה בהגדרות Claude Platform on AWS שלכם וייצאו אותו (באמצעות export) לפני הפעלת Claude Code.

#בקשות עדיין נשלחות אל api.anthropic.com

סביר להניח ש-CLAUDE_CODE_USE_ANTHROPIC_AWS אינו מוגדר או מוגדר לערך שאינו נחשב כערך אמת (truthy). הגדירו אותו ל-1 והריצו /status כדי לאמת את ספק השירות שנבחר. אם CLAUDE_CODE_USE_BEDROCK או CLAUDE_CODE_USE_FOUNDRY מוגדרים גם הם, יש להם עדיפות על פני Claude Platform on AWS.

#משאבים נוספים

המנוי ל-Claude Platform on AWS, סביבת העבודה והגדרות ה-IAM שקודמים להגדרת Claude Code מכוסים בתיעוד הפלטפורמה:

סקירת Claude Platform on AWS: מנוי, הגדרת סביבת עבודה וסקירת מוצר
מדריך פעולות IAM: הרשאות ומדיניות מנוהלת (managed policies)

Claude Code ב-Claude Platform ב-AWS