📘 תיעוד 119

מדריך תאימות של שער לקלוד קוד

שמרו על שער LLM תואם לקלוד קוד: נקודות הקצה שהוא קורא להן, הכותרות ושדות הגוף שיש להעביר הלאה, ומה נשבר כשהם מוסרים.

הדף הזה מתעד את הבקשות שקלוד קוד שולח לשער, כולל נקודות הקצה שהוא קורא להן, הכותרות ושדות הגוף שהשער חייב להעביר הלאה, ואילו יכולות מפסיקות לעבוד כשזה לא קורה. הוא נכתב למפעילים שמגדירים מוצר שער כך שיעבוד עם קלוד קוד.

שער אפליקציות קלוד, השער העצמאי של Anthropic, מגיש הפניה משלו לנקודות קצה בכתובת GET /protocol. ההפניה מכסה את נקודות הקצה של השער הזה להתחברות, להסקה, להגדרות מנוהלות, לגילוי מודלים ולטלמטריה. זה מסמך נפרד מהמדריך הזה.

[!NOTE]

• כדי להפיץ שער קיים או שער של צד שלישי לארגון, ראו הפצת שער LLM
• אם אתם מפתחים יחידים שמאמתים את קלוד קוד מול שער עם אישור שקיבלתם, ראו חיבור קלוד קוד לשער LLM

הדף הזה מכסה:

• פורמטי API ואת נקודות הקצה שיש להגיש לכל אחד
• התנהגות הלקוח לפי שיטת החיבור: איך מזהי מודלים, ערכי anthropic-beta, שדות בקשה וברירות מחדל נבדלים בין הפורמטים לבין התחברות לשער אפליקציות קלוד
• כותרות בקשה: אילו חייבות להגיע אל השרת במעלה הזרם ואילו השער יכול לצרוך
• כותרות תשובה: מה להחזיר כדי שזיהוי תקיעות, ניסיונות חוזרים והצגת מגבלת שימוש יעבדו
• בלוק הייחוס של פרומפט המערכת ואיך הוא מקיים אינטראקציה עם מטמון פרומפטים
• העברת יכולות: מה נשבר כשכותרות או שדות גוף מוסרים
• גילוי מודלים

הדף הזה משתמש בשני מונחים למה שהשער עושה עם כל כותרת ושדה גוף:

• העברה בלי שינוי: העברה אל השרת במעלה הזרם בייט אחר בייט
• צריכה: השער רשאי לקרוא את הערך לצורך ניתוב, ייחוס או מעקב, ואינו חייב להעביר אותו הלאה

כל דבר שלא מסומן כהעברה בלי שינוי הוא שלכם לצרוך או להתעלם ממנו.

#פורמטי API

שער חייב לחשוף לפחות אחד מפורמטי ה-API הבאים ללקוחות קלוד קוד. הלקוח בוחר פורמט ומפנה את קלוד קוד אל השער באמצעות המשתנים בעמודה "נבחר על ידי" בטבלה למטה.

Agent Platform של Google Cloud הוא נקודת הקצה של Google Cloud לקלוד, לשעבר Vertex AI. שמות המשתנים שלו שומרים על האיות VERTEX.

#Foundry ו-Claude Platform on AWS

Microsoft Foundry ו-Claude Platform on AWS מממשים את פורמט Anthropic Messages. קלוד קוד מנתב אליהם דרך המשתנים שלהם, ANTHROPIC_FOUNDRY_BASE_URL ו-ANTHROPIC_AWS_BASE_URL, אבל שער שעומד לפני אחד מהם מממש את שורת Anthropic Messages למעלה. שער שעומד לפני Claude Platform on AWS חייב גם להעביר את הכותרת anthropic-workspace-id, שהפלטפורמה הזו דורשת בכל בקשה.

#נקודות קצה אופציונליות ותעבורת הפעלה

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

ההתאמה היא לפי הנתיב, לא לפי כתובת ה-URL המלאה:

• בקשות הסקה נשלחות ב-POST אל /v1/messages?beta=true
• סיומות השיטה של Agent Platform ב-Google Cloud מצטרפות לנתיב מודל המפרסם, כמו ב-/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

שער רואה גם תעבורת הפעלה במאמץ מיטבי, שאפשר לדחות בלי לשבור דבר. שער בפורמט Anthropic Messages מקבל בדיקת חימום חיבור HEAD /api/hello, שקלוד קוד מדלג עליה כשמוגדרים פרוקסי HTTP או אישור לקוח. שער בפורמט Amazon Bedrock מקבל בקשת GET /inference-profiles?type=SYSTEM_DEFINED, וכשהמודל המוגדר הוא פרופיל הסקה, גם חיפושי GET /inference-profiles/{profile}.

הפעלות שעוברות דרך שער אינן זכאיות להגדרת HIPAA. בדקו איך מפתחים מתחברים ומתחברים מפרט אילו שיטות התחברות וחיבור כן זכאיות. ראו הגדרת HIPAA מאחורי שער.

בדיקת הזמינות של מצב מהיר לעולם לא מופיעה ביומני השער: היא קוראת ישירות אל api.anthropic.com ואינה עוקבת אחרי ANTHROPIC_BASE_URL. לכן ברשת שחוסמת יציאה ישירה אל api.anthropic.com, מצב מהיר יכול לדווח על שגיאת קישוריות, בזמן שההסקה דרך השער ממשיכה לעבוד. גם בדיקת הבטיחות של דומיין ב-WebFetch קוראת ישירות אל api.anthropic.com. שימוש במצב מהיר מאחורי פרוקסי ושערי LLM מכסה את המשתנים שמשחזרים אותו.

#הזרמה

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

• אם השער צובר תשובה עד שהיא שלמה, קלוד קוד נתקע.
• קלוד קוד מצפה לרצף האירועים המלא של כל תשובה, לפי הסדר, עד אירועי message_delta ו-message_stop הסופיים. אם הגוף מסתיים בצורה נקייה אחרי שבלוק תוכן התחיל אבל לפני message_delta הסופי הזה, קלוד קוד מתייחס לתשובה כאל חיבור שנפל. ייתכן שהתשובה למעלה אינה שלמה מתאר מה המשתמש רואה אז, וניסיונות חוזרים אוטומטיים אומר מתי קלוד קוד שולח את הבקשה מחדש.
• כשמעקה בטיחות של Amazon Bedrock חוסם תשובה, האירועים ש-Bedrock שולח יכולים להתייחס לבלוק תוכן ש-content_block_stop שלו כבר הגיע, וקלוד קוד מסתמך על קבלתם כפי שנשלחו. מעקות בטיחות של AWS מתאר איך התשובה הזו מסתיימת.
• קלוד קוד מבטל תשובה מוזרמת ברגע שלא מגיעים אליו בתים למשך זמן ארוך מזמן הקצוב להמתנה בהזרמה. במהלך הפסקת חשיבה ארוכה, אירועי SSE מסוג ping של השרת במעלה הזרם יכולים להיות הבתים היחידים על הזרם, ולכן שער שמסיר או צובר אותם יכול להפעיל את הזמן הקצוב הזה באמצע תשובה. לשער שמתרגם משרת במעלה הזרם בלי אירועי ping, כמו זרם האירועים הבינארי של Amazon Bedrock, יש אותו פער, אלא אם הוא פולט אירועי ping משלו.
• בפורמט Amazon Bedrock InvokeModel, קלוד קוד קורא את תשובת /model/{model}/invoke-with-response-stream כגוף הבינארי application/vnd.amazon.eventstream ש-Bedrock מחזיר, ואינו יכול לנתח אותו אחרי ששער ממיר אותו לאירועי שרת נשלחים או משכתב את כותרת Content-Type הזו. שגיאות הזרמה מאחורי שער או פרוקסי מתאר מה המשתמש רואה אז.

#אי התאמה של פורמט מול השרת במעלה הזרם

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

• כשהלקוח מדבר בפורמט Amazon Bedrock או Agent Platform של Google Cloud, קלוד קוד שולח רק את תת הקבוצה מתוך מערך היכולות המלא שאותם ספקים מקבלים
• כשהלקוח מדבר בפורמט Anthropic Messages, קלוד קוד שולח את המערך המלא, גם אם השער מעביר הלאה אל שרת Amazon Bedrock או Agent Platform של Google Cloud במעלה הזרם

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

אם השרת במעלה הזרם הוא Amazon Bedrock או Agent Platform של Google Cloud, אפשר להימנע מהגישור על ידי חשיפת הפורמט של אותו ספק. ניתוב אל ספק ענן דרך שער מציג את הגדרת הלקוח לפורמט הזה.

#איך שיטת החיבור משנה את התנהגות הלקוח

האופן שבו מפתח מתחבר לשער קובע אילו מזהי מודלים, ערכי anthropic-beta ושדות בקשה קלוד קוד שולח, ואילו ברירות מחדל הוא מחיל. השער רואה אחת משלוש התנהגויות לקוח:

• פורמט Amazon Bedrock או Agent Platform: המפתח מגדיר CLAUDE_CODE_USE_BEDROCK=1 עם ANTHROPIC_BEDROCK_BASE_URL, או CLAUDE_CODE_USE_VERTEX=1 עם ANTHROPIC_VERTEX_BASE_URL, כך שהם מצביעים אל השער. קלוד קוד משתמש במזהי המודלים, בשדות הבקשה ובברירות המחדל של אותו ספק.
• פורמט Anthropic Messages: המפתח מגדיר את ANTHROPIC_BASE_URL אל השער. קלוד קוד מתייחס לשער כאל Claude API ואינו יכול לדעת אל איזה שרת במעלה הזרם אתם מעבירים.
• התחברות לשער אפליקציות קלוד: המפתח מתחבר אל שער אפליקציות קלוד. השער הזה מדבר בפורמט Anthropic Messages אבל יכול לנתב אל כל שרת במעלה הזרם, ולכן קלוד קוד שולח רק את ערכי anthropic-beta ואת הנחות יכולות המודל שגם Amazon Bedrock ו-Agent Platform מקבלים.

#בקשות וברירות מחדל לפי שיטת חיבור

הטבלה למטה משווה את שלוש שיטות החיבור, התנהגות אחת בכל שורה. היא משמיטה את Microsoft Foundry ואת Claude Platform on AWS, שגם הם משתמשים בפורמט Anthropic Messages אבל קלוד קוד מגיע אליהם דרך המשתנים שלהם. עבורם, ראו את הדפים Microsoft Foundry ו-Claude Platform on AWS.

לגבי היכולות שכל חיבור תומך בהן והטלמטריה שהוא שולח אל Anthropic כברירת מחדל, ראו זמינות יכולות והתנהגויות ברירת מחדל לפי ספק API.

#הגדרות למזהי מודלים שאינם מזוהים

שתי הגדרות בצד הלקוח משנות את מה שקלוד קוד מניח לגבי מזהה מודל שהוא אינו מזהה, בלי תלות בשיטת החיבור שהמפתח משתמש בה:

• חלון הקשר: קלוד קוד מניח 200K, או 1M כשהמזהה נושא [1m]. כדי להצהיר על החלון האמיתי, ראו תיקון החלון עבור שער או מזהה מודל מותאם
• יכולות: כדי לתת לכינוי של שער את היכולות של המודל שמאחוריו, מפו את מזהה Anthropic של אותו מודל אל הכינוי שלכם באמצעות רשומת modelOverrides בהגדרות שאתם מפיצים. לגבי המקום שבו משתני ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES חלים, ראו העברת יכולות

#כותרות בקשה

Claude Code כולל את הכותרות האלה בבקשות API. שמות הכותרות אינם תלויי רישיות בתעבורה. העבר את anthropic-version ואת anthropic-beta ללא שינוי, ובנוסף את anthropic-workspace-id כאשר השרת במעלה הזרם הוא Claude Platform on AWS. את השאר השער יכול לצרוך לניתוב, לייחוס ולמעקב, ואין חובה להעביר אותן.

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

אם המפתחים שלך מגדירים את ANTHROPIC_CUSTOM_HEADERS, הכותרות האלה מופיעות בבקשות גם כן.

#כותרות רמז של השער

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

האם בקשה נושאת אותן תלוי לאן Claude Code שולח אותה:

• חיבור ישיר ל-API של Anthropic: נשלחות כברירת מחדל
• כתובת בסיס מותאמת: כבויות כברירת מחדל, כי פרוקסי שדוחה כותרות לא מוכרות יגרום לבקשה להיכשל. כדי לקבל אותן, הגדר CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 עבור המפתחים שלך, לדוגמה בבלוק env של הגדרות מנוהלות
• כל קצה אחורי אחר, כולל Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry ו-Claude Platform on AWS: נשלחות רק כאשר CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 מוגדר

הגדרת CLAUDE_CODE_GATEWAY_HINT_HEADERS ל-0 עוצרת את הכותרות בכל חיבור.

הכותרות נושאות רק את מה שהשורות למטה מפרטות: אוצרות מילים קבועים, שמות כלים, משכי זמן ומזהה הנחיה אקראי, ולעולם לא טקסט הנחיה או תוכן קבצים. כל ערך הוא ASCII להדפסה.

לפני ניתוח x-claude-code-prev-tool-durations, בדוק איך Claude Code בונה את הערך ומה הוא משמיט:

• רשומות: אחת לכל קריאת כלי שרצה, לפי הסדר שבו התוצאה שלה נאספה, באלפיות שנייה שלמות
• תקרה: Claude Code שולח לכל היותר 32 רשומות ו-4 KB, ושומר את הרשומות הראשונות
• קידוד: שמות כלים מקודדים באחוזים, ומכסים את %, ;, =, פסיק, רווח, וכל תו מחוץ ל-ASCII להדפסה
• ניתוח: פצל לפי ;, אחר כך לפי =, ופענח כל שם
• היעדר: קריאות דחיסה, בקשות צד והבקשה הראשונה של הנחיה חדשה לעולם לא נושאות אותו. אל תקרא כותרת חסרה כתור שלא הריץ כלים
• זמנים: כל אחד מהם אינו כולל בקשות הרשאה ו-hooks, וקריאות כלים מקבילות מדווחות כל אחת את הזמן שלה, ולכן הרשומות אינן מסתכמות לפער בין הבקשות

#העברה כרשימות פתוחות

התייחס לכותרות ולשדות הגוף כאל רשימות פתוחות, לא סגורות. Claude Code מקבל יכולות לאורך גרסאות, והן מגיעות כערכי anthropic-beta חדשים, שדות גוף בקשה חדשים, ולעיתים כותרות anthropic-* או x-claude-code-* חדשות.

כאשר מעבירים לשרת במעלה הזרם בפורמט Anthropic, העבר כותרות בקשה anthropic-* ושדות גוף בקשה ללא שינוי, במקום להגדיר רשימת היתר לאלה שאתה רואה היום. שער שמוצמד לרשימה שנצפתה מסיר את הכותרת או השדה של היכולת הבאה ושובר אותה בגרסה שמציגה אותה.

החריג הוא שרת במעלה הזרם שאינו Anthropic, כגון Amazon Bedrock או Google Cloud's Agent Platform, שם גישור הפרש הסכמה הוא תפקיד השער. ראה העברת יכולות.

#כותרות תשובה

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

#בלוק ייחוס בהנחיית המערכת

Claude Code מוסיף בהתחלה בלוק ייחוס קצר להנחיית המערכת, שמכיל את גרסת הלקוח וטביעת אצבע שנגזרת מהשיחה. נקודת הקצה api.anthropic.com מסירה את הבלוק לפני העיבוד כאשר הוא מגיע ללא שינוי כבלוק המערכת הראשון, ולכן הוא אינו משפיע על שמירת הנחיות במטמון של הצד הראשון. כל שרת אחר במעלה הזרם מקבל אותו כחלק מההנחיה.

ההסרה היא לפי מיקום, ולכן היא פועלת רק כאשר השער מעביר את מערך system ללא שינוי. כדי להשאיר את הבלוק מחוץ להנחיה בלי לאבד תוכן מערכת אחר:

• העבר את מערך system בדיוק כפי שהתקבל, והשאר את הבלוק ראשון: הוספת בלוק מערכת אחר בהתחלה, סידור מחדש של המערך, או המרה למחרוזת אחת מבטלים את ההסרה, ואז הבלוק מגיע למודל ולמפתח מטמון ההנחיה.
• השאר את הבלוק ברשומת מערך משלו: נקודת הקצה מתייחסת לבלוק ממוזג שמתחיל בכותרת הייחוס כייחוס במלואו, ומשליכה את כל מה שמוזג לתוכו, כולל שאר הנחיית המערכת.
• אם השער שלך חייב לעצב מחדש תוכן מערכת, הגדר CLAUDE_CODE_ATTRIBUTION_HEADER=0 כדי ש-Claude Code ישמיט את הבלוק. Anthropic ונקודות הקצה של Claude אצל ספקי הענן קוראות את הבלוק לייחוס, ולכן השמט אותו בלקוח במקום להסיר אותו או להזיז אותו בשער.

המשתנה קיים לתאימות מטמון של שער ושל צד שלישי, לא כבקרת פרטיות: בחיבור ישיר הבקשה המלאה כבר הולכת ל-API של Anthropic בכל מקרה. כאשר שני אלה מתקיימים, Claude Code שומר את הבלוק בבקשות המסווג של מצב אוטומטי גם כאשר מגדירים את המשתנה ל-0:

• הבקשות הולכות אל api.anthropic.com, כאשר ANTHROPIC_BASE_URL לא מוגדר או מציין את המארח הזה, ולא נבחר ספק צד שלישי.
• האישור הפעיל אינו פרופיל Anthropic או אישור פדרציה.

בקשות מסווג מדלגות על שאר הנחיית המערכת של Claude Code, ולכן בבקשות האלה הבלוק הוא הסמן היחיד בגוף הבקשה שמזהה אותן כתעבורת Claude Code. כאשר אחד התנאים נכשל, דרך שער LLM, אצל ספק צד שלישי, או כאשר פרופיל או אישור פדרציה פעיל, הגדרת 0 מסירה את הבלוק גם מבקשות המסווג. לפני גרסה 2.1.229 החריג הזה לא היה קיים: הגדרת 0 הסירה את הבלוק מבקשות המסווג האלה, וכאשר ה-API דחה את הבקשות הלא מזוהות, המצב האוטומטי נכשל בכל פעולה ששלח למסווג.

החל מ-Claude Code גרסה 2.1.181, הבלוק יציב למשך חיי השיחה כאשר בקשות מנותבות דרך כתובת בסיס מותאמת, ולכן מטמון הנחיות בצד השער שמפתחו הוא גוף הבקשה המלא פועל בלי להשבית אותו, וכל ספק שהשער שלך מעביר אליו מקבל קידומת הנחיה יציבה. לפני גרסה 2.1.181 הבלוק כלל אסימון לכל בקשה ששינה את תחילת הנחיית המערכת בכל בקשה. בגרסאות האלה, הגדר CLAUDE_CODE_ATTRIBUTION_HEADER=0 כאשר השער שלך עושה אחד מאלה:

• מממש מטמון הנחיות שמפתחו הוא גוף הבקשה.
• מעביר בקשות לספק צד שלישי כגון Amazon Bedrock, Microsoft Foundry או Google Cloud's Agent Platform, בפורמט Anthropic Messages או בפורמט של הספק עצמו, שם הקידומת המשתנה מפחיתה שימוש חוזר במטמון ההנחיות אצל הספק הזה.

#העברת יכולות

Claude Code מתייחס לשער ANTHROPIC_BASE_URL כאל נקודת קצה בפורמט Anthropic, ושולח אליו את כותרות הבטא ואת שדות גוף הבקשה שהוא שולח אל api.anthropic.com, מלבד קבוצה קטנה של אבחונים וברירות מחדל השמורים לחיבורים ישירים, כגון ברירת המחדל של הזרמת כלים ברזולוציה עדינה שמכוסה למטה. הקבוצה הזו משתנה לפי גרסה, ולכן אל תסתמך על התוכן שלה.

הזרמת כלים ברזולוציה עדינה היא אחת מברירות המחדל של חיבור ישיר: היא כבויה כברירת מחדל בכל פעם שבקשות מנותבות דרך כתובת בסיס מותאמת, והשער מקבל אותה כאשר מפתחים מגדירים CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1.

#זוגות של כותרת בטא ושדה בגוף

יכולות שמוסיפות שדות לגוף מצמידות אותם לכותרת בטא, והזוג נע יחד. שער שמסיר את הכותרת ומעביר את הגוף, או מעביר גוף בפורמט Anthropic לזרם במעלה עם סכמה שונה, מייצר שגיאות 400. כששני החצאים נעדרים יחד, היכולת נכבית בשקט.

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

המשתנים ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES מצהירים על יכולות מודל רק בתצורות הספק: CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, ו-CLAUDE_CODE_USE_MANTLE. אין להם השפעה מאחורי שער ANTHROPIC_BASE_URL.

#ניסיון חוזר אוטומטי והעברת שגיאות

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

• כש-400 אומר שהערך enabled או adaptive של thinking.type לא נתמך, Claude Code מנסה פעם אחת עם הסוג האחר ושומר את השדה thinking. בקשות מאוחרות יותר לאותו מודל שומרות את הסוג שהוחלף עד ש-Claude Code יוצא. לפני v2.1.121, Claude Code לא ניסה שוב, כך ש-thinking.type.enabled is not supported הגיע למפתח
• כשהזרם במעלה דוחה רשומת role: "system" בתוך messages, Claude Code מנסה פעם אחת בלי הודעות המערכת האלה מאמצע השיחה ונושא את הטקסט שלהן בהודעות משתמש. בקשות מאוחרות יותר בשיחה שומרות את הצורה הזו עד שהמפתח מריץ /clear או עד שהשיחה נדחסת
• כשהזרם במעלה דוחה רק את סמן cache_control על הודעת מערכת באמצע השיחה, Claude Code שומר את הודעות המערכת ומנסה פעם אחת כשהסמן הועבר. הסמן עובר לרשומה האחרונה ב-messages שאינה הודעת מערכת, בניסיון הזה ובבקשות מאוחרות יותר עד ש-Claude Code יוצא
• כשהזרם במעלה דוחה חתימת חשיבה, כולל עם 400 שההודעה שלו אומרת שהבלוק הוא bound to a different conversation, Claude Code מסיר בלוקי חשיבה קודמים מהבקשה, מנסה שוב, ומשאיר אותם מחוץ לכל בקשה מאוחרת יותר. תשובות חדשות עדיין כוללות חשיבה
• כשהשער או הזרם במעלה שלו דוחה את רשומת כלי היועץ ב-tools כסוג כלי לא מוכר, Claude Code מנסה פעם אחת בלי הרשומה הזו ובלי ערך anthropic-beta שלה. בקשות מאוחרות יותר משמיטות אותם. Claude Code מזהה את הדחייה הזו לפי תשובת 400 או 422 שההודעה שלה מציינת את סוג הכלי אחרי Input tag, כגון Input tag 'advisor_20260301'. לפני v2.1.280, Claude Code לא ניסה שוב את הדחייה הזו
• כשהזרם במעלה דוחה את output_config.effort או את ערך anthropic-beta שלו, השער רואה את הבקשה פעם נוספת בלעדיהם. בקשות מאוחרות יותר משמיטות אותם. השער שלכם לא צריך שינוי אם הוא מעביר את ה-400 של הזרם במעלה בלי שינוי וההודעה:
  • מציינת את output_config.effort לצד Extra inputs are not permitted
  • אומרת שהמודל לא תומך בפרמטר המאמץ
  • מתחילה ב-Unexpected value(s) ומפרטת את effort-2025-11-24 עבור כותרת anthropic-beta. דורש v2.1.310 או מאוחר יותר. מפתחים ש-ANTHROPIC_BETAS שלהם מפרט את הערך ממשיכים לשלוח אותו ולקבל את ה-400, ולכן בקשו מהם להסיר את הרשומה הזו
• כשהזרם במעלה דוחה את השדה context_management או את ערך anthropic-beta שלו, השער רואה את הבקשה פעם נוספת בלעדיהם. בקשות מאוחרות יותר משמיטות אותם. Claude Code מזהה את הדחייה הזו לפי ההודעה שלה, למשל הודעה שמכילה context_management: Extra inputs are not permitted. לפני v2.1.304, Claude Code לא ניסה שוב את הדחייה הזו
• כש-400 דוחה לפי שם ערך anthropic-beta אחר, השער רואה את הבקשה פעם נוספת בלעדיו אם הניסיון החוזר מכסה את הערך הזה
• כשהזרם במעלה דוחה שדה כלי בבטא שאינו defer_loading, כגון strict, ה-400 מגיע למפתח. לפני שהוא מגיע, השער יכול לראות את הבקשה שוב בלי שדות חיפוש הכלים. כדי להפסיק לשלוח שדות כאלה, בקשו מהמפתחים להגדיר CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

דחיית bound to a different conversation מגיעה מבדיקת החשיבה השמורה של ה-API, שנכשלת כשתוכן system, tools, או messages קודמים שונה מהבקשה שיצרה את החשיבה. שער שכותב מחדש חלק מהתוכן הזה יכול לגרום לדחייה בעצמו. ספריות, פרוקסי ושערים מכסים מה להעביר בלי שינוי.

רוב לוגיקת הניסיון החוזר הזו מתאימה לניסוח השגיאה של הזרם במעלה, ולכן העבירו גופי תשובות שגיאה בלי שינוי. שער שעוטף שגיאות של הזרם במעלה במעטפת משלו שובר את נתיב ההתאוששות, גם כשהוא שומר את קוד המצב, אלא אם הודעת המעטפת נושאת אסימון capability_rejected: יציב. Claude apps gateway מחליף את הניסוח של שגיאות ספקי הענן באסימונים האלה, למשל capability_rejected: prompt_too_long.

#ניסיון חוזר בלי ערך בטא שנדחה

כש-400 דוחה לפי שם ערך anthropic-beta שהניסיון החוזר הזה מכסה, השער רואה את הבקשה פעם נוספת בלעדיו. בקשות מאוחרות יותר משמיטות את הערך. רוב הערכים שהוא מכסה דורשים v2.1.314 או מאוחר יותר.

השער שלכם לא צריך שינוי אם ההודעה של ה-400 שהוא מחזיר נושאת את הערך באחת מהצורות האלה:

• המשפט של ה-API: משפט Unexpected value(s) שמפרט את הערך עבור כותרת anthropic-beta
• אסימון beta_header:: capability_rejected: beta_header: ואחריו הערך, אסימון capability_rejected:

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

• ערך עם ניסיון חוזר משלו, כגון יועץ או חיפוש כלים: השער רואה את הניסיון החוזר של היכולת הזו
• ערך ש-Claude Code לא מזהה: ערך שמפתח הגדיר דרך ANTHROPIC_BETAS נשאר בכל בקשה, ולכן בקשות המפתח ממשיכות להיכשל עם ה-400. בקשו מהמפתח להסיר את הרשומה
• דגל invalid beta flag חשוף: Claude Code מנחש איזה ערך הזרם במעלה דחה. אם הבקשה נשאה ערך שהוא מנחש, השער רואה את הבקשה שוב בלי הערך הזה. אם ה-400 עדיין מגיע למפתח, בקשו מהשער לציין את הערך שנדחה באחת מהצורות האלה

#כמה זמן ערך בטא שנדחה נשאר בחוץ

#ניסיון חוזר בלי חיפוש כלים

ב-v2.1.305 או מאוחר יותר, Claude Code שולח מחדש בקשה בלי שדות defer_loading ובלוקי tool_reference אחרי 400 או 422 שמציינת חיפוש כלים או שהגורם שלה לא מזוהה. אחרי ניסיון חוזר מוצלח, בקשות מאוחרות יותר באותה שיחה משמיטות אותם גם כן.

בקשות המפתח ממשיכות לעבוד בלי שום שינוי בשער, כשכלי ה-MCP שלהם נטענים מראש. כש-Claude Code מנסה שוב חיפוש כלים, השער יכול לראות בקשה נוספת שנדחתה ואחריה את הניסיון החוזר שלה. עבור חיפוש הכלים עצמו, Claude Code מצפה שהשער יעביר את שדות defer_loading ואת בלוקי tool_reference עם ערך anthropic-beta שלהם.

#השבתת יכולות לפני שחרור

כשהשער שלכם או הזרם במעלה שלו דוחה ערכי anthropic-beta שלפני שחרור או את שדות הגוף שמצמידים אותם, ואתם לא יכולים להעביר את שני החצאים, בקשו מהמפתחים להגדיר CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1. כשהמשתנה מוגדר, Claude Code מפסיק לשלוח יכולות לפני שחרור ואת ערכי anthropic-beta שמצמידים אותן, כולל:

• ניהול הקשר ושדה הגוף context_management שלו
• שדות סכמת הכלים בבטא, כגון strict ו-defer_loading. שדות הכלי הרגילים name, description, input_schema ו-cache_control נשארים
• שדה הפלט המובנה output_config.format. דורש Claude Code v2.1.287 או מאוחר יותר
• השדה output_config.task_budget
• חיפוש כלי MCP, כך שכל כלי MCP נטען מראש, אלא אם הארגון שלכם משאיר אותו פעיל דרך הגדרות מנוהלות

המשתנה לא מסיר כל ערך anthropic-beta. מה שנשאר כולל:

• ערכי anthropic-beta עבור הקשר מורחב, חשיבה משולבת ומאמץ, שגם ספקי ענן מקבלים
• שדה output_config.effort ברמה העליונה. ניסיון חוזר אוטומטי והעברת שגיאות מכסה זרם במעלה שדוחה אותו
• שדה החשיבה המסתגלת thinking, שאין לו כותרת בטא
• רשומות role: "system" שנושאות הודעות מערכת באמצע שיחה
• ערך anthropic-beta של OAuth שאימות המנוי דורש
• ערכי כותרת ושדות גוף שמפתחים מוסיפים בעצמם דרך ANTHROPIC_BETAS או CLAUDE_CODE_EXTRA_BODY

כשפלטפורמת מארח שמשבצת את Claude Code מגדירה CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS לא עוצר סשנים של מצב אוטומטי ב-Amazon Bedrock, ב-Agent Platform של Google Cloud, ב-Microsoft Foundry, או ב-Claude apps gateway מלבקש מהשרת סקירת מסווג. הסקירה הזו מוסיפה ערך anthropic-beta ושדה בקשה safeguards. הגדירו CLAUDE_CODE_AUTO_MODE_SERVER=0 כדי לעצור את זה שם.

ב-Claude Code v2.1.227 או מאוחר יותר, הארגון שלכם יכול להשאיר את חיפוש כלי MCP פעיל תחת המשתנה הזה דרך הגדרות מנוהלות. מה ש-Claude Code שולח כשהדריסה הזו פעילה תלוי באופן החיבור:

• בחיבור ישיר בלי תצורת HIPAA, או דרך שער שמוגדר עם ANTHROPIC_BASE_URL, Claude Code ממשיך לשלוח את כותרת הבטא של חיפוש הכלים, שדות כלי defer_loading, ובלוקי tool_reference
• אצל ספק ענן, או בחיבור דרך Claude apps gateway, לדריסה אין השפעה
• בסשן שמקבל את תצורת HIPAA, לדריסה אין השפעה וחיפוש הכלים נשאר כבוי

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

#גילוי מודלים

כאשר ANTHROPIC_BASE_URL מצביע על שער שחושף את פורמט Anthropic Messages, Claude Code יכול לשלוח שאילתה לנקודת הקצה /v1/models של השער בעת ההפעלה ולהוסיף את המודלים שהוחזרו לבורר /model. אם אתה או המנהל שלך מגדירים את replaceBuiltInOptions במערך modelPicker, Claude Code מסתיר את המודלים שהתגלו מהבורר.

מפתחים מפעילים את זה על ידי הגדרת CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, בסביבה שלהם או דרך הגדרות מנוהלות. הגילוי כבוי כברירת מחדל כדי ששערים שמגובים במפתח API משותף לא יציגו לכל משתמש כל מודל שהמפתח יכול לגשת אליו.

#מתי הגילוי רץ

הגילוי חל רק על פורמט Anthropic Messages. הוא לא רץ כאשר:

• כל משתנה ספק CLAUDE_CODE_USE_* מוגדר, גם אם ANTHROPIC_BASE_URL מוגדר גם כן
• ANTHROPIC_BASE_URL לא מוגדר או מצביע על api.anthropic.com

הגילוי עדיין רץ כאשר תעבורה לא חיונית כבויה, כי הבקשה הולכת רק לשער שלך. לפני גרסה v2.1.257, הגילוי לא רץ בזמן שתעבורה לא חיונית הייתה כבויה.

#בקשה ותגובה

הבקשה היא GET /v1/models?limit=1000 עם זמן קצוב של 3 שניות כברירת מחדל, וכל הפניה מטופלת ככישלון כדי שהאישור לא ידלוף ליעד ההפניה. שער שמגיב לאט יותר מהזמן הקצוב, או שער שמפנה את /v1/models, גם מ-http ל-https, נכשל בגילוי בשקט. הגש את נקודת הקצה ישירות בכתובת הבסיס המוגדרת.

כדי לתת לשער איטי זמן ארוך יותר, הגדר את CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS. המשתנה דורש את Claude Code בגרסה v2.1.269 או מאוחרת יותר.

Claude Code שולח את בקשת הגילוי עם שתי כותרות האישור שלמטה, ומשמיט כותרת שהערך שלה לא נפתר. שליחת שתי הכותרות דורשת את Claude Code בגרסה v2.1.248 או מאוחרת יותר. גרסאות מוקדמות יותר שולחות רק Authorization כאשר ANTHROPIC_AUTH_TOKEN מוגדר, ורק x-api-key אחרת.

• Authorization: ANTHROPIC_AUTH_TOKEN כאסימון bearer, אחרת הערך של apiKeyHelper כאסימון bearer.
• x-api-key: מפתח ה-API ש-Claude Code פתר, למשל ANTHROPIC_API_KEY. כאשר ערך של helper הוא האישור היחיד, הכותרת הזו נושאת אותו גם כן, כך שהערך מגיע בשתי הכותרות.

Claude Code שולח גם כל כותרת מ-ANTHROPIC_CUSTOM_HEADERS. כאשר לכותרת מותאמת יש ערך לא ריק, Claude Code שולח אותה במקום כותרת מובנית באותו שם, עם התאמת שמות בלי רגישות לאותיות גדולות וקטנות.

כאשר הערך של אף אחת מכותרות האישור לא נפתר, Claude Code מדלג על הגילוי וכותב שורה [gatewayDiscovery] skipped ליומן הניפוי של סשן claude --debug. אם אתה מספק אישור רק דרך ANTHROPIC_CUSTOM_HEADERS, Claude Code עדיין מדלג על הגילוי.

Claude Code קורא את id, את display_name האופציונלי, ואת description האופציונלי מכל רשומה במערך data של התגובה:

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

Claude Code שומר רשומה כאשר ה-id שלה מכיל claude או anthropic בכל מקום במחרוזת, בהתאמה בלי רגישות לאותיות גדולות וקטנות, ומתעלם מהשאר. מזהים עם קידומת ספק כמו vertex_ai/claude-sonnet-4-6 או bedrock/anthropic.claude-sonnet-4-5 עוברים את המסנן. מזהה שלא מכיל אף אחת משתי מחרוזות המשנה לא עובר. לפני גרסה v2.1.223, Claude Code שמר רשומה רק כאשר ה-id שלה התחיל ב-claude או ב-anthropic, מה שהסתיר מזהים עם קידומת ספק.

#רשומות בבורר ומטמון

הבורר הוא רשימת המודלים האינטראקטיבית שנפתחת כאשר מפתח מריץ /model ב-Claude Code. כל רשומה שהתגלתה משתמשת ב-display_name כשמה כאשר השער שולח שם ששונה מה-id. אחרת הרשומה מציגה את שם המודל כאשר Claude Code מזהה את ה-id, ואת ה-id כאשר הוא לא מזהה. לדוגמה, רשומה עם ה-id my-gateway-claude-sonnet-4-6 ובלי display_name מופיעה כ-Sonnet 4.6.

הגילוי מוסיף רק מודלים שההגדרה המנוהלת availableModels מתירה.

כל רשומה מציגה גם את ה-description של המודל, מכווץ לשורה אחת. רשומה בלי description מציגה במקום זאת את הטקסט "From gateway". לפני גרסה v2.1.257, כל רשומה שהתגלתה הציגה את הטקסט "From gateway".

מזהה שהתגלה לא מקבל שורה משלו כאשר הוא תואם לשורה שכבר נמצאת בבורר:

• אותו מזהה: המזהה שהתגלה תואם בדיוק למזהה של שורה קיימת, או ששני המזהים הם איותים של אותה גרסת Fable.
• אותו מודל כמו כינוי מובנה: כאשר מזהה מפורש שהתגלה מציין את המודל שכינוי מובנה נפתר אליו כרגע, הבורר מציג רק את שורת הכינוי. לדוגמה, בזמן ש-sonnet נפתר ל-claude-sonnet-5-5, claude-sonnet-5-5 שהתגלה מתקפל לתוך שורת sonnet, ו-claude-sonnet-5 שהתגלה עדיין מקבל שורה משלו.

התוצאות נשמרות במטמון ב-~/.claude/cache/gateway-models.json, או ב-%USERPROFILE%\.claude\cache\gateway-models.json ב-Windows, ומתרעננות בכל הפעלה. אם אתה מגדיר את CLAUDE_CONFIG_DIR, המטמון נמצא תחת הספרייה הזו במקום. אם הבקשה נכשלת או שהשער לא מממש את /v1/models, הבורר חוזר לרשימה שבמטמון מההפעלה הקודמת או לרשימת המודלים המובנית. אם השער שלך מגיש מודלי Claude תחת כינויים שלא תואמים למסנן הגילוי, מפתחים יכולים להוסיף את הכינויים האלה ידנית עם משתני הגדרת המודל.

#משאבים קשורים

לשאר סט התיעוד של השער ולהפניות ה-API הבסיסיות:

• סקירת שער: מהו שער ואיך לבחור בין שער של יישומי Claude לבין מוצר אחר
• שערי LLM אחרים: איך לפרוס שער שהארגון שלך מפעיל ואיך הוא פועל מול מנויי claude.ai
• פריסת שער LLM לארגון שלך: רשימת הבדיקה למנהל שמשתמשת במדריך הזה
• חיבור Claude Code לשער LLM: הגדרה לכל מפתח וטבלת פתרון הבעיות
• הפניה לכותרות בטא: הקבוצה הנוכחית של ערכי anthropic-beta
• Messages API: פורמט ה-API ששער בפורמט Anthropic מממש