📘 תיעוד 82

תצורת שער יישומי Claude

מדריך עזר לכל אפשרות ב-gateway.yaml: מאזין ו-TLS, OIDC, הפעלה (session), מאגר נתונים של Postgres, שרתי יעד (upstreams) של Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform ו-Microsoft Foundry, ניתוב דגמים, מדיניות מנוהלת וטלמטריה.

פריסה של שער יישומי Claude (Claude apps gateway) מוגדרת על ידי קובץ YAML יחיד, שבדרך כלל נקרא gateway.yaml. הקובץ מגדיר את כל מה שהשער עושה: היכן הוא מאזין, כיצד מפתחים מתחברים, לאן נשלח העיבוד (inference), ואילו מדיניות וטלמטריה חלות. דף זה מהווה מדריך עזר לכל אפשרות בקובץ זה.

כדי לכתוב את הקובץ הראשון שלך, התחל מ-המדריך המהיר, שבונה תצורה עובדת מינימלית ומריץ אותה. לאחר שיש לך תצורה שאתה מרוצה ממנה, מדריך הפריסה מסביר כיצד לארוז אותה במכולה (container) ולארח אותה ב-Kubernetes, ב-Cloud Run או בפלטפורמה משלך.

השער קורא את הקובץ פעם אחת, בעת ההפעלה, באמצעות claude gateway --config /path/to/gateway.yaml. כל אפשרות מאומתת מול סכמה בעת העלייה, כך שתצורה שגויה נכשלת כבר בהתחלה עם שגיאה ברמת השדה, ולא בעת השימוש הראשון.

הדוגמה המלאה בסוף דף זה כוללת את כל החלקים.

#מבנה הקובץ

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

חלקים נדרשים:

• listen: כתובת האזנה, כתובת URL ציבורית, סיום TLS
• oidc: ספק הזהויות שלך (IdP), כולל מנפיק (issuer), לקוח, מיפוי תביעות (claims) ומי רשאי להתחבר
• session: אסימוני ה-bearer שהשער מנפיק, יחד עם מפתח סודי ומשך חיים
• store: בסיס נתונים PostgreSQL, עבור הרשאות מכשיר (device grants) ומוני הגבלת קצב
• upstreams: לאן העיבוד נשלח, בין אם ל-Anthropic, ל-Amazon Bedrock, ל-Claude Platform on AWS, ל-Google Cloud's Agent Platform, או ל-Microsoft Foundry

חלקים אופציונליים:

• admin: אימות עבור Admin API ושמירת נתונים למגבלות הוצאה
• enforcement: התנהגות fail-open או fail-closed באכיפת מגבלות הוצאה
• pricing: תעריפים חוזיים ומכפיל עבור מונה ההוצאות ועבור נתוני העלות שהמפתחים רואים
• models ו-auto_include_builtin_models: רשימת דגמים שנבחרה על ידי מנהל מערכת ומזהים לפי כל upstream
• managed: מדיניות הגדרות מנוהלות לפי קבוצות IdP
• telemetry: העברת OTLP אל מערך הניטור והתצפיתיות (observability) שלך
• access_control, limits, timeouts, rate_limits: רשימות התרה וחסימה של IP, מגבלות גודל בקשה, זמן עד בייט ראשון (time-to-first-byte) מול ה-upstream, ומגבלות התחברות לפי כתובת IP
• load_test_mode: בדיקת עומסים לשער ללא קריאה לספק דגמים

#הרחבת סודות

אל תכתוב סודות כגון client_secret, jwt_secret, או postgres_url ישירות בתוך gateway.yaml. הפנה אליהם באמצעות אחת התבניות שלהלן, והשער יפענח את הערך בעת העלייה מתוך משתנה סביבה או קובץ:

#חלקים נדרשים

#listen

בלוק listen שולט במקום שבו השער משרת: כתובת ההאזנה והיציאה (port), המקור הנראה מבחוץ (origin), וסיום TLS אופציונלי.

#oidc

בלוק oidc מחבר את השער לספק הזהויות שלך וקובע מי יכול להתחבר. הוא מציין את המנפיק (issuer) ולקוח ה-OAuth, ממפה את התביעות (claims) הנושאות דוא"ל וקבוצות, ומגביל את ההתחברות לפי דומיין דוא"ל או קבוצה.

OpenID Connect (OIDC) הוא פרוטוקול ה-SSO שהשער משתמש בו מול ספק הזהויות שלך: ראה הגדרת ספק זהויות לגבי מה לרשום בצד ה-IdP.

#בקשות IdP דרך פרוקסי העברה

שרתי ה-upstream לעיבוד מכבדים את HTTPS_PROXY ואת HTTP_PROXY בכל הגרסאות. הבקשות של השער עצמו ל-IdP, לגילוי, ל-JWKS, לאסימון ול-userinfo, נשלחות ישירות אלא אם כן תגדיר oidc.use_proxy: true, מה שדורש גרסה v2.1.227 ומעלה. כאשר משתנה פרוקסי מוגדר, use_proxy אינו מוגדר, והמנפיק אינו מכוסה על ידי NO_PROXY, השער שומר על בקשות אלו ישירות ורושם הודעה בעת העלייה המבקשת ממך לבחור: use_proxy: false שומר עליהן ישירות ומשתיק את ההודעה.

כאשר מוגדר use_proxy: true, ה-pod מפענח את שם המארח של כל נקודת קצה של ה-IdP בעצמו ומבקש מהפרוקסי לבצע CONNECT לכתובת ה-IP המפוענחת, כך שהפרוקסי חייב לקבל CONNECT לכתובת ה-IP של כל מארח שמסמך הגילוי מציין, ולא רק למנפיק. השתמש בכתובת פרוקסי בתבנית http://. ההגדרות ca_cert_pem ו-מנגנון ההגנה מפני SSRF חלים גם על הנתיב שעובר בפרוקסי.

יציאה דרך פרוקסי בלבד משנה את שניהם: כל עוד היא פעילה, בקשות IdP עוברות דרך הפרוקסי אלא אם תגדיר use_proxy: false, והשער מוסר לפרוקסי כל שם מארח של IdP מבלי לפענח אותו תחילה.

#יציאה דרך פרוקסי בלבד

הגדר CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 בסביבת השער, לצד HTTPS_PROXY, כאשר ה-pod מגיע למארחים אחרים רק דרך פרוקסי העברה זה ואינו יכול לפענח שמות DNS ציבוריים בעצמו, או כאשר הפרוקסי מסרב ל-CONNECT לכתובת IP. דורש גרסה v2.1.277 ומעלה. זהו משתנה סביבה ולא מפתח ב-gateway.yaml כדי ששום דבר בקובץ התצורה לא יוכל להקל בבדיקת הכתובות של השער.

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=
export no_proxy=
export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

השער רושם שורת network: אחת בעת העלייה כאשר יציאה דרך פרוקסי בלבד פעילה.

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

יציאה דרך פרוקסי בלבד נשארת כבויה אלא אם סביבת השער עומדת בכל שלושת התנאים הבאים:

• HTTPS_PROXY או HTTP_PROXY מוגדר.
• NO_PROXY ו-no_proxy ריקים. אם הפלטפורמה שלך מזריקה אחד מהם לתוך pods, הגדר את שניהם לערך ריק במכולת השער. רישום אספן טלמטריה ב-NO_PROXY משאיר את היציאה דרך פרוקסי בלבד כבויה.
• CLAUDE_GATEWAY_ALLOW_LOOPBACK אינו מופעל. לא ניתן לשלב אספן או IdP על ה-loopback של ה-pod עצמו עם יציאה דרך פרוקסי בלבד, מכיוון שכתובת loopback שנמסרת לפרוקסי תהיה הכתובת של מארח הפרוקסי עצמו, לכן תן לשירותים אלה כתובת שהפרוקסי יכול להגיע אליה במקום זאת. מאותה סיבה השער דוחה שמות בתבנית localhost לחלוטין כאשר יציאה דרך פרוקסי בלבד פעילה.

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

ברגע שיציאה דרך פרוקסי בלבד פעילה, אשר כל יעד בפרוקסי, כולל אספן פנימי וכל מארח המוגדר לפי כתובת IP. אתה עדיין יכול לשמור על IdP פנימי כישיר באמצעות oidc.use_proxy: false.

אזהרה: הפעל זאת רק כאשר רשימת ההיתרים (allowlist) של הפרוקסי מחמירה לפחות כמו הבדיקה של השער עצמו. הפרוקסי חייב לסרב לנקודות קצה של מטא-נתונים בענן כגון 169.254.169.254 ו-metadata.google.internal, לכתובות link-local, ול-loopback של מארח הפרוקסי עצמו, ועליו לסרב להן לפי הכתובת שהשם מתפענח אליה, ולא רק לפי השם, מכיוון שהשער אינו תופס עוד שם מארח שמתפענח לאחת מהן. פרוקסי שמתחבר לכל מקום שהוא מתבקש מסיר את מנגנון ההגנה מפני SSRF של השער עבור בקשות אלו.

#session

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

#store

בלוק store מכוון את השער לבסיס הנתונים PostgreSQL שלו, המחזיק הרשאות מכשיר ומוני הגבלת קצב.

לפיתוח מקומי, כוון את postgres_url למכולת Postgres זמנית, לדוגמה docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

#upstreams

השדה upstreams הוא רשימה סדורה. השער מעביר עיבוד ל-upstream הראשון שמפענח את הדגם המבוקש.

במקרים של 5xx, 429, 401, 403, 404, או פסק זמן, השער עובר ל-upstream הבא (failover): שגיאות 4xx אחרות אינן גורמות למעבר, מכיוון ששגיאות אלו מיוחסות לבקשה ולא ל-upstream. שגיאת 401 או 403 פירושה שפרטי ההזדהות של השער עצמו נכשלו מול אותו upstream. שגיאת 404 פירושה שאותו upstream אינו משרת את הדגם המבוקש, כך ש-upstream מאוחר יותר ברשימה עדיין יכול לשרת אותו.

אם תגדיר forward_user_identity: true ב-upstream, שגיאת 429 שהוא מחזיר לבקשה שנשאה את הדוא"ל של המפתח אינה גורמת למעבר ל-upstream הבא. ראה כיצד דחיית מגבלה לפי משתמש מגיעה למפתח.

מעבר על 404 דורש שער בגרסה v2.1.198 ומעלה. מהדורות קודמות החזירו את ה-404 הראשון ללקוח גם כאשר upstream מאוחר יותר ברשימה שירת את הדגם.

מספר upstreams מאותו ספק חייבים להגדיר name: ייחודי.

לקוחות Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, ו-Microsoft Foundry נבנים פעם אחת בעת ההפעלה, וערכות ה-SDK שלהם מרעננות פרטי הזדהות באופן פנימי, כך שהחלפת פרטי הזדהות בענן אינה דורשת הפעלה מחדש. מפתחות ומזהי bearer סטטיים של Anthropic API נקראים בעת ההפעלה: ראה Anthropic API.

#הודעות שגיאה של Upstream

השער מחזיר את תגובת השגיאה של אחד ה-upstreams, או 502 משלו, בהתאם לאופן שבו ה-upstreams ענו:

• upstream החזיר סטטוס שהשער אינו עובר הלאה בגינו: תגובתו של אותו upstream. השער אינו מנסה upstreams נוספים.
• כל upstream שהשער ניסה נכשל באופן שגורם למעבר הלאה: ה-429 האחרון. כאשר אף אחד לא החזיר 429, השער מעדיף, לפי הסדר, את ה-401 או 403 האחרון, ה-404 האחרון, וה-501 האחרון. כאשר אף אחד לא החזיר אף אחד מאלה, השער מחזיר 502 משלו, all upstreams failed (N attempted), כאשר N סופר כל ערך ב-upstreams, כולל ערכים שהשער דילג עליהם מכיוון שאינם משרתים את הדגם המבוקש.

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

שרתי ה-upstream של Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, ו-Microsoft Foundry יכולים לכלול את מזהי החשבון, ה-ARNs של התפקידים ומזהי הפרויקט שלך בטקסט השגיאה שלהם. השער מתעד את הטקסט המלא ב-יומן המבצעי. מה שהמפתח רואה מאותם upstreams תלוי בדחייה:

• 400 או 413 במעטפת השגיאה הסטנדרטית של Anthropic: הודעת ה-upstream עצמה, כגון prompt is too long. Claude Platform on AWS, Agent Platform ו-Microsoft Foundry מחזירים מעטפת זו עבור דחיות של ה-API של הדגם.
• 400 או 413 במבנה של הספק עצמו: אסימון capability_rejected:. כאשר השער אינו יכול לסווג את הדחייה, upstream rejected the request ב-400 או request too large for this upstream ב-413.
• כל סטטוס אחר: נוסח כללי לפי סטטוס, כגון upstream rate limit exceeded ב-429.

לדוגמה, השער מחליף את Input is too long for requested model. של Amazon Bedrock ב-capability_rejected: prompt_too_long. התוכנה Claude Code מבצעת דחיסה אוטומטית על אסימון זה, בדיוק כפי שהיא עושה על prompt is too long.

שמירה על הודעת 400 או 413 של upstream ענן, או החלפתה באסימון capability_rejected:, דורשת שער בגרסה v2.1.233 ומעלה.

#Anthropic API

ה-upstream המינימלי של Anthropic הוא מפתח API מתוך Claude Console:

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    
# OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
    
#   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    
# base_url: https://api.anthropic.com   
# default; override for a forward proxy

שתי תבניות האימות נבדלות בכותרת שהן שולחות:

• api_key: שולח x-api-key. החלף אותו ב-Claude Console ועדכן את משתנה הסביבה.
• oauth_token: שולח Authorization: Bearer. השתמש בתבנית bearer כאשר הארגון שלך מנפיק אסימונים קצרי מועד במקום מפתחות API ארוכי טווח. ה-bearer נקרא פעם אחת בעת ההפעלה, לכן רענון מתבצע על ידי חיבור מחדש של הסוד והפעלה מחדש.

במקום מפתח סטטי או bearer, באפשרותך להשתמש ב-Workload Identity Federation. צור כלל איחוד לפי מדריך Workload Identity Federation, ולאחר מכן חבר את ה-OIDC JWT של עומס העבודה שלך כקובץ, כגון אסימון חשבון שירות מוטל (projected service-account token) ב-Kubernetes או id-token של פלטפורמת CI. השער מחליף את ה-JWT באסימון bearer קצר מועד ומרענן אותו אוטומטית. קובץ האסימון נקרא מחדש בכל החלפה, כך שאסימונים מוטלים שהוחלפו נקלטים ללא הפעלה מחדש.

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      
# workspace_id: wrkspc_...       
# required if the rule covers >1 workspace
      
# service_account_id: svac_...   
# optional expected-target check

#כותרות זהות לפי משתמש עבור פרוקסי שאתה מפעיל

באפשרותך לכוון את ה-base_url של upstream מסוג provider: anthropic לפרוקסי שאתה מפעיל במקום ל-Anthropic API. כדי ליידע את הפרוקסי איזה מפתח שלח כל בקשה, הגדר forward_user_identity: true באותו upstream. הפרוקסי יכול אז לייחס הוצאות לכל מפתח. דורש שער המריץ Claude Code בגרסה v2.1.233 ומעלה.

לדוגמה, עבור פרוקסי בכתובת upstream-gateway.internal.example.com:

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        
# default false

השער מוסיף כותרות אלו לכל בקשה שהוא מעביר לאותו upstream:

כאשר אסימון ה-IdP אינו נושא דוא"ל, השער שולח רק את x-claude-gateway-user-id ומשמיט את שתי כותרות הדוא"ל. אם ה-IdP שלך שם את הדוא"ל בתביעה אחרת, הגדר את oidc.email_claim לתביעה זו.

כאשר הפרוקסי שלך עונה 429 לבקשה שנשאה את הדוא"ל של המפתח, השער מחזיר תגובה זו למפתח כפי שהיא במקום לעבור ל-upstream הבא, כך שתקציב או הגבלת קצב לפי משתמש של הפרוקסי שלך נשמרים. תגובות אחרות של הפרוקסי פועלות לפי כללי המעבר הרגילים. אם אסימון ה-IdP של מפתח אינו נושא דוא"ל, השער מעביר את בקשותיו ללא כותרות הדוא"ל, כך ש-429 לאחת מבקשות אלו נחשב למגבלת קיבולת של upstream ועובר הלאה. לפני גרסה v2.1.267 בשרת השער, כל 429 עבר הלאה.

הגדר forward_user_identity רק ב-upstream שה-base_url שלו הוא פרוקסי שאתה מפעיל. השער שולח כתובות דוא"ל של מפתחים לכל שרת ש-base_url מציין. אם base_url הוא ה-Anthropic API, שזו ברירת המחדל, השער מסרב לפעול.

#Amazon Bedrock

עבור פריסת Amazon Bedrock בצד הלקוח שהשער מחליף או ניצב לפניה, ראה Claude Code ב-Amazon Bedrock. ה-upstream בצד השער:

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           
# preferred: AWS default credential chain
    
# OR explicit credentials:
    
# auth:
    
#   aws_access_key_id: ${AWS_AKID}
    
#   aws_secret_access_key: ${AWS_SK}
    
#   aws_session_token: ${AWS_ST}
    
# OR a Bedrock API bearer token:
    
# auth:
    
#   aws_bearer_token: ${AWS_BEARER_TOKEN}
    
# Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
    
# base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

בלוק auth ריק משתמש בשרשרת פרטי ההזדהות של ברירת המחדל של ה-SDK של AWS: משתני סביבה, ~/.aws/credentials, תפקיד משימה ב-ECS, מטא-נתונים של מופע EC2, או IRSA ב-EKS. בסביבת ייצור, הענק ל-pod של השער תפקיד IAM במקום להטמיע מפתחות סטטיים בתמונת מכולה.

פרטי הזדהות מפורשים חייבים להיות מלאים: השער נכשל בעת העלייה כאשר aws_access_key_id ו-aws_secret_access_key אינם מוגדרים יחד, או כאשר aws_session_token מוגדר בלעדיהם. לפני גרסה v2.1.207, בלוק auth: חלקי עבר אימות.

#Claude Platform on AWS

הפלטפורמה Claude Platform on AWS משרתת את ה-API המקורי של Anthropic על גבי תשתית AWS בכתובת aws-external-anthropic.<region>.api.aws. היא משתמשת במזהי דגמים מקוריים, מכבדת כותרות anthropic-beta כפי שנשלחו, ומשרתת את count_tokens, כך ששום תרגום ייעודי ל-Bedrock אינו חל כאן. ספק ה-anthropicAws דורש Claude Code גרסה v2.1.198 ומעלה: מהדורות שער קודמות דוחות אותו בעת העלייה.

לגבי פריסת צד הלקוח של אותה פלטפורמה, ראה Claude Code ב-Claude Platform on AWS. ה-upstream בצד השער:

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   
# sent as x-api-key
    
# OR SigV4 via the AWS default credential chain:
    
# auth: {}
    
# OR explicit SigV4 credentials:
    
# auth:
    
#   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    
#   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    
# Override the derived endpoint:
    
# base_url: https://aws-external-anthropic.us-east-1.api.aws

הפלטפורמה פועלת בחשבון AWS נפרד מ-Amazon Bedrock וחותמת על בקשות SigV4 עבור שם השירות שלה, aws-external-anthropic, כך שתפקיד IAM המיועד ל-Bedrock אינו מורשה עבורה. מפתח API ב-auth.api_key מקבל עדיפות כאשר מוגדרים גם פרטי הזדהות של SigV4. בלוק auth ריק משתמש בשרשרת פרטי ההזדהות של ברירת המחדל של ה-SDK של AWS, אותה שרשרת שבה משתמש ה-upstream של Amazon Bedrock.

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

#Google Cloud Agent Platform

עבור ההגדרה המקבילה בצד הלקוח, ראה Claude Code ב-Google Cloud. ה-upstream בצד השער:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           
# preferred: Application Default Credentials
    
# OR a service account key file:
    
# auth: { service_account_json: /secrets/sa.json }
    
# Override the aiplatform endpoint for Private Service Connect:
    
# base_url: https://us-east5-aiplatform.p.googleapis.com

בלוק auth ריק משתמש ב-Application Default Credentials (ADC): משתנה GOOGLE_APPLICATION_CREDENTIALS, מטא-נתונים של GCE, או GKE Workload Identity. קובצי מפתח JSON של חשבון שירות נתמכים אך אינם מומלצים: השתמש ב-Workload Identity או צרף חשבון שירות למופע ה-GCE או Cloud Run.

הגדר region: global כדי להשתמש ב-נקודת הקצה הגלובלית עבור Agent Platform של Google Cloud במקום בנקודת קצה אזורית. Google מנתבת אז כל בקשה לאזור זמין, כך שאינך צריך לעקוב אחר זמינות הדגמים לפי אזור. הגדרת אזור ספציפי מקבעת כל בקשה אליו.

#Microsoft Foundry

עבור פריסת Microsoft Foundry בצד הלקוח, ראה Claude Code ב-Microsoft Foundry. ה-upstream בצד השער:

upstreams:
  - provider: foundry
    resource: example-foundry              
# https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        
# preferred: DefaultAzureCredential / Managed Identity
    
# OR an API key:
    
# auth:
    
#   api_key: ${FOUNDRY_API_KEY}

ההגדרה use_azure_ad: true מתפענחת דרך DefaultAzureCredential: זהות מנוהלת (Managed Identity) ב-AKS, ACI או App Service; ה-CLI של Azure; או פרטי הזדהות ממשתני סביבה. מפתחות API עובדים אך הם ברמת הפרויקט ואינם מתחלפים אוטומטית. נקודת הקצה של Microsoft Foundry נגזרת מ-resource:: הגדר את base_url האופציונלי כדי לעקוף אותה עבור עננים ריבוניים כגון Azure Government.

#כותרות סטטיות בבקשות Upstream

כדי להוסיף כותרות קבועות לבקשות שהשער שולח ל-upstream אחד, הגדר headers: באותו upstream. השתמש בזה כאשר פרוקסי שאתה מפעיל מול הספק מנתב או מייחס תעבורה לפי כותרת.

ההגדרה headers: דורשת Claude Code גרסה v2.1.277 ומעלה בשרת השער. שער בגרסה קודמת מסרב להפעיל כאשר הוא מוצא את המפתח. שדרג כל עותק לפני שתוסיף את המפתח, והסר את המפתח לפני שתחזור לגרסה קודמת.

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

דוגמה זו מגיעה ל-upstream מסוג provider: vertex דרך פרוקסי בכתובת upstream-proxy.internal.example.com. היא מגדירה את כותרת ה-x-source שהפרוקסי קורא, ושולחת אסימון ממשתנה הסביבה PROXY_TOKEN בתור x-proxy-token:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

ערכים הם טקסט ASCII להדפסה ללא רווחים באף אחד מהקצוות. שים במירכאות מספר, true, או false כדי ש-YAML יקרא אותו כטקסט.

כדי לשמור סוד מחוץ לקובץ התצורה, השתמש ב-הרחבת סודות כדי לטעון את הערך ממשתנה סביבה באמצעות ${VAR} או מקובץ באמצעות ${file:/path}. ערך ${VAR} שמתפענח לערך ריק עוצר את הפעלת השער.

ההגדרה headers: עובדת בכל ספק, וכל upstream שולח רק את הכותרות שלו.

לא כל בקשה שהשער שולח ל-upstream נושאת אותן:

ב-upstream של Amazon Bedrock או של Claude Platform on AWS שחותם על בקשות באמצעות AWS SigV4, כותרות אלו מהוות חלק מהחתימה, ולכן על הפרוקסי שלך להעביר אותן הלאה ללא שינוי.

אם תשתמש בשם שהשער שומר לעצמו, הוא יסרב לפעול, ושגיאת ההפעלה תציין את שם הכותרת. שמות שמורים כוללים:

• authorization ו-x-api-key
• host, content-type, ו-user-agent
• כל שם שמתחיל ב-anthropic-, ב-x-goog-, ב-x-amz-, או ב-x-amzn-

#ריבוי Upstreams

אותו ספק יכול להופיע יותר מפעם אחת עם name: מובחן. זה מכסה אזורים שונים, חשבונות שונים דרך שרשראות פרטי הזדהות שונות, תפוקה מוקצית (provisioned throughput) לעומת לפי דרישה (on-demand), ונסיגה בין ספקים שונים.

השער מנסה את ה-upstreams לפי הסדר. מצבים של 5xx, 429, 401, 403, 404, פסקי זמן, ונקודת קצה חסרה (501) עוברים ל-upstream הבא: שגיאות 4xx אחרות אינן עוברות.

שגיאת 429 היא ברמת הקיבולת של ה-upstream, ולכן מיצוי תפוקה מוקצית (PT) יעבור לתפוקה לפי דרישה. אם תגדיר forward_user_identity: true ב-upstream, שגיאת 429 לבקשה שנשאה את הדוא"ל של המפתח היא דחייה ברמת המשתמש ולא תעבור ל-upstream הבא.

כל בקשה מתחילה ב-upstream הראשון. בקשה מגיעה ל-upstream מאוחר יותר רק כאשר כל upstream שלפניו נכשל או אינו משרת את הדגם המבוקש.

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

עבור upstream של Anthropic API, ההגדרה timeouts.upstream_ttfb_ms תוחמת את זמן ההמתנה ל-upstream מושבת. הגדרה זו אינה חלה על ספקים אחרים, שבהם השער ממתין עד שעה שלמה לכך ש-upstream יתחיל להגיב.

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

דוגמה זו מנתבת תחילה הקצאת תפוקה מוקצית ב-Amazon Bedrock, גולשת לתפוקה לפי דרישה חוצה אזורים ולחשבון שני, ונסוגה אל ה-Anthropic API הישיר כמוצא אחרון:

upstreams:
  
# Primary: provisioned throughput in your home region.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  
# Overflow: on-demand cross-region.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  
# Different account: a separate Bedrock allotment via assumed-role creds.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  
# Last resort: direct Anthropic API.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# Per-upstream model IDs are keyed on the upstream's `name:`.
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8

מעבר בין ספקי ענן, או אל ה-Anthropic API הישיר, משנה את ההסכם, המיקום הגאוגרפי והתנאים האחרים החלים על הבקשה.

ה-CLI מחיל את אותם תנאי תכונות על שערים ללא קשר לאיזה upstream משרת בקשה נתונה, כך שמעבר ל-upstream אחר אינו שולח שדה בגוף הבקשה ש-upstream עלול לדחות.

#חלקים אופציונליים

#admin

אופציונלי. מפעיל את /v1/organizations/spend_limits, המשקף את ה-Admin API הציבורי של Anthropic, ואכיפת הוצאות לפי מפתח ב-/v1/messages. ראה מגבלות הוצאה לגבי אופן הגדרת המגבלות ואכיפתן: סעיף זה מכסה את המפתחות ב-gateway.yaml שמפעילים את התכונה ומכווננים אותה.

admin:
  
# Named static API keys for the admin endpoints, sent as x-api-key.
  
# The id appears in the audit log as admin-key:<id> so each key is
  
# attributable. Array for rotation: add the new key, roll clients,
  
# remove the old.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  
# IdP groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

#enforcement

בלוק enforcement שולט באופן שבו בדיקות מגבלת הוצאה מתנהגות כאשר מאגר הנתונים אינו זמין.

#pricing

בלוק pricing מורה למונה ההוצאות כמה לחייב במקום מחיר המחירון בדולר ארה"ב (USD), כך שהמגבלות ו-/effective ישקפו את התעריפים החוזיים שלך. הסכומים נשארים בדולר ארה"ב ומהווים הערכה, לא חשבונית. שתי דרישות מוקדמות:

• Claude Code גרסה v2.1.227 ומעלה בשרת השער. גרסאות קודמות דוחות את המפתח הלא מוכר בעת העלייה.
• בלוק admin: או, בגרסה v2.1.268 ומעלה, בלוק managed: עם מדיניות אחת לפחות. השער מסרב להפעיל כאשר pricing מוגדר ללא אף אחד משני הבלוקים הללו, מכיוון ששום דבר לא יקרא אותו.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

כיצד המונה מתאים שורת עקיפה:

• שורה מחליפה את מחיר המחירון עבור בקשות ש-upstream, המוגדר ב-upstreams[].name, משרת עבור model. זה כולל את התעריף הגבוה יותר של מצב מהיר, כך שבקשות רגילות ובקשות מהירות מנוטרות לפי אותם ארבעה תעריפים.
• מזהה מובנה כגון claude-sonnet-4-6, המותאם כמו models[].id, מכסה כל תבנית עם תאריך, תבנית אזורית של Amazon Bedrock, או תבנית של Google Cloud's Agent Platform שהמונה מתמחר כדגם זה. כל מחרוזת אחרת, כגון כינוי או ARN של פרופיל עיבוד, מותאמת למזהה שהלקוח שלח או למחרוזת שנשלחה ל-upstream, ללא תלות ברישיות.
• כאשר יש חפיפה בין שורות, המונה בוחר בשורה הספציפית ביותר ולא בשורה הראשונה: שורה שה-model שלה הוא מחרוזת הדגם המדויקת שנשלחה ל-upstream, לאחר מכן שורה התואמת למזהה המדויק שהלקוח שלח, ולאחר מכן שורה המציינת את הדגם המובנה.
• שם upstream לא מוכר מכשיל את העלייה, וכך גם שתי שורות עבור אותו upstream שמציינות את אותו הדגם, כולל שני איותים שונים של אותו דגם מובנה. השער מזהיר בעת העלייה לגבי שורה שאף דגם שניתן לבקש אינו יכול להשתמש בה.
• בקשות חיפוש באינטרנט נשארות במחיר המחירון של 0.01 דולר: המכפיל עדיין חל עליהן.

עבור תעריפים לפי אזור, תן לכל אזור upstream בעל שם משלו ושורה אחת לכל upstream.

#העלאת מחירים

בגרסה v2.1.271 ומעלה בשרת השער, באפשרותך להגדיר multiplier מעל 1, עד 10, כדי למדוד יותר ממה שהספק גובה, לדוגמה לצורך תעריף חיוב פנימי. דוגמה זו מודדת כל בקשה ב-120% מהמחיר:

pricing:
  multiplier: 1.2

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

המכפיל אינו משנה את מה שספק ה-upstream גובה בפועל עבור הבקשות.

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

שרת שער בגרסה נמוכה מ-v2.1.271 מסרב להפעיל אם תגדיר multiplier מעל 1.

#שליחת התעריפים ללקוחות מחוברים

בגרסה v2.1.268 ומעלה בשרת השער, השער מציב בנוסף את התעריפים מתוך pricing בתוך מדיניות managed שהוא משרת, בתור ההגדרה המנוהלת modelPricing. מפתחים שהותאמו למדיניות רואים אז את תעריפי pricing עבור ה-upstream הראשון שמשרת כל מזהה דגם ב-/usage, בשורת הסטטוס וב-OpenTelemetry. מפתח שאינו מותאם לאף מדיניות אינו מקבל הגדרות מנוהלות, כך שהנתונים שלו נשארים לפי מחיר מחירון. לקוחות מחילים את ההגדרה ב-Claude Code גרסה v2.1.242 ומעלה.

• מה שהשער מוסיף: אלא אם כן בלוק cli של מדיניות כבר מגדיר את modelPricing, השער מוסיף את ה-multiplier ועבור כל מזהה דגם שלקוח יכול לבקש, את שורת העקיפה של ה-upstream הראשון שמשרת מזהה זה. תעריף שרק upstream של מעבר חלופי גובה נשאר בשער.
• החרגת מדיניות אחת: הגדר את modelPricing ל-{} בבלוק cli של אותה מדיניות, והמפתחים שלה יישארו במחיר מחירון.
• שמירה על תעריפים של מדיניות עצמה: מדיניות שבלוק ה-cli שלה מגדיר modelPricing עם multiplier או overrides משלה שומרת על ה-modelPricing במלואו, והשער אינו מוסיף תעריפים משלו לתוכו.

#models

בלוק models הוא רשימת דגמים אופציונלית שנבחרה על ידי מנהל מערכת, המוגשת ב-/v1/models ומשמשת לתרגום מזהי דגמים לכל upstream. הוא נדרש עבור אזורי Amazon Bedrock מחוץ לארה"ב, ARNs של תפוקה מוקצית ב-Amazon Bedrock, ושמות פריסה של Microsoft Foundry.

auto_include_builtin_models: true   
# false: expose only the list below
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    
# description: optional text shown in clients that surface it
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   
# or an inference-profile ARN
      foundry: your-opus-deployment-name

כל מפתח תחת upstream_model חייב להתאים ל-name של upstream מוגדר, אשר כברירת מחדל נקרא כשם הספק. מפתח שאינו תואם לאף upstream מכשיל את העלייה, לכן השמט שורות עבור ספקים שאינך משתמש בהם.

#managed

בלוק managed מגדיר מדיניות בקרת גישה מבוססת תפקידים הממופתחת לפי קבוצות IdP או דומיין דוא"ל. המדיניות מוערכת לפי הסדר: ההתאמה הראשונה נבחרת, ולאחר מכן ממוזגת על גבי בסיס ברירת המחדל הכולל match: {}. המדיניות מוגשת לכל משתמש ב-GET /managed/settings עם שמירה במטמון באמצעות ETag/304.

managed:
  policies:
    
# Specific groups first.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    
# Default catch-all last: matches everyone who authenticated.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

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

• רשימות התרה: availableModels ו-permissions.allow. הרשימה של מדיניות ספציפית מחליפה לחלוטין את זו של הבסיס.
• רשימות חסימה ומערכי hooks: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces, וכל מערך מסוג אירוע ב-hooks. אלה לוקחים את האיחוד של הבסיס והמדיניות, כך שחסימה ברמת הארגון או hook ביקורת לא יימחקו בטעות על ידי עקיפה ברמת התפקיד.
• מפתחות מסוג רשומה: env, modelOverrides, ו-skillOverrides. אלה מתמזגים באופן שטוח, כך שבלוק env לפי תפקיד עוקף מפתחות שהוא מגדיר ויורש את השאר מהבסיס.

ההגדרה availableModels נאכפת גם בצד השרת ב-/v1/messages, כך שדגם חסום מחזיר 400 ללא קשר למה שהלקוח שולח.

השער מאמת את ערך model בעצמו לפני שהוא מעביר בקשה, כך שערך שגוי לעולם אינו מגיע ל-upstream. הוא דוחה את הבקשה עם 400 בשני מקרים:

• כאשר הערך חסר או ריק, השער דוחה את הבקשה עם ההודעה model is required. בדיקה זו דורשת שער המריץ Claude Code בגרסה v2.1.228 ומעלה.
• כאשר הערך קיים אך אינו מחרוזת, השער דוחה את הבקשה עם ההודעה model must be a string. דורש שער המריץ Claude Code בגרסה v2.1.221 ומעלה.

משתמש מאומת שאינו תואם לאף מדיניות מקבל את ברירות המחדל של השער, כלומר כל דגם בקטלוג וללא הגדרות מנוהלות. הוסף match: {} בסוף אם אתה רוצה מדיניות ברירת מחדל מובטחת.

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

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

שני מחזורי הפצה חלים כאן:

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

#ערכי התאמה שעוצרים את השער בעת העלייה

בעת העלייה, השער בודק את בלוק ה-match של כל מדיניות ואת רשימת admin_groups. כל אחד מערכים אלה עוצר את השער עם שגיאה המציינת את השדה:

• רשימת groups ריקה
• רשומה ריקה בתוך groups או בתוך admin_groups
• שדה email_domain ריק
• שדה email_domain המכיל @, רווחים, או פסיק. השער מקצץ רווחים ומסיר @ מוביל אחד לפני בדיקה זו. כתוב דומיין נקי אחד, כגון example.com.

לפני גרסה v2.1.232, השער עלה עם ערכים אלה. לכל ערך הייתה השפעה זו:

• שדה email_domain ריק: השער דילג על בדיקת הדומיין, כך שמדיניות עם email_domain ריק וללא רשימת groups התאימה לכל משתמש מאומת.
• רשימת groups ריקה: המדיניות לא התאימה לאיש.
• שדה email_domain המכיל @, רווחים, או פסיק: המדיניות לא התאימה לאיש.
• רשומה ריקה בתוך groups או בתוך admin_groups: הרשומה התאימה למשתמש רק כאשר תביעת groups של ה-IdP של אותו משתמש הכילה גם היא רשומה ריקה. בתוך admin_groups, התאמה זו העניקה גישת ניהול. אם רשימת admin_groups שלך מעולם לא הכילה רשומה ריקה, איש לא קיבל גישת ניהול בדרך זו.

#מה נכנס ב-cli

כל ערך ב-cli הוא מסמך managed-settings.json מלא של Claude Code, אותה סכמה שהיית פורס דרך MDM או דרך /etc/claude-code/managed-settings.json, המבוטאת כאן כ-YAML. ה-CLI מחיל את המסמך שנמסר ברמת הניהול, מעל הגדרות משתמש והגדרות פרויקט, במקום הגדרות המנוהלות על ידי השרת. לכן הוא מתעלם מההגדרות המוגבלות למקורות מדיניות ברמת מערכת ההפעלה, כגון policyHelper ו-wslInheritsWindowsSettings.

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

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

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

managed:
  policies:
    - match: {}
      cli:
        
# Model access (also enforced server-side at /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

        
# Permission policy
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   
# blocks --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     
# ignore user/project permission rules

        
# Environment pushed into the CLI process. DISABLE_UPDATES blocks
        
# background and manual updates; DISABLE_AUTOUPDATER stops only
        
# background updates.
        env:
          DISABLE_UPDATES: "1"                    
# pin versions via your own distribution

        
# Org-wide hooks. Hook commands run on developer machines, not the
        
# gateway, so the path must exist on every client OS in the policy.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

מכיוון שהגדרות אלו מגיעות דרך הרשת, ה-CLI מציג לכל מפתח תיבת דו-שיח לאישור אבטחה לפני החלת ההגדרות המפורטות להלן:

• hooks
• משתני env הדורשים את אישור המפתח, כגון משתני פרוקסי וכתובת URL בסיסית
• הגדרות הרצת מעטפת כגון apiKeyHelper ו-statusLine
• הגדרות קובצי ההרצה הבינאריים של סביבת הבידוד: sandbox.bwrapPath, sandbox.socatPath, ו-sandbox.ripgrep
• הגדרות ארגז חול המיירטות תעבורה, מזריקות פרטי הזדהות, או מחלישות בידוד, כגון sandbox.network.tlsTerminate והגדרות יציאות הפרוקסי. המסמך תיבות דו-שיח לאישור אבטחה מפרט את כולן.

המסמך זיכרון אישורים מסביר כמה זמן נמשך אישור ומתי תיבת הדו-שיח מופיעה שוב.

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

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

תצורת ה-טלמטריה של השער דוחפת את OTEL_EXPORTER_OTLP_ENDPOINT, ולכן הגדרת telemetry.forward_to מפעילה את תיבת הדו-שיח בכל לקוח אינטראקטיבי. תיבת הדו-שיח מגנה על מחשב המפתח מפני שער שנפרץ או עוין, ולא על הארגון מפני המפתח.

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

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

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

#שרתי MCP במדיניות

כדי לספק שרתי MCP ללקוחות Claude Code שמדיניות מתאימה להם, הגדר את managedMcpServers בבלוק cli של אותה מדיניות. דרושה גרסה v2.1.259 ומעלה של Claude Code בשרת השער ובקרב הלקוחות.

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

אם תכתוב הפניית ${VAR} ב-gateway.yaml, השער מפענח אותה מתוך סביבתו בעת העלייה באמצעות הרחבת סודות לפני שהוא מריץ את בדיקות הרשומות, כך שכל לקוח תואם מקבל את הערך המילולי ויכול לקרוא אותו. הנחיות הכותרות עבור שרתים מסופקים חלות על הערך המורחב.

השער דוחה את איות ה-.mcp.json של mcpServers בתוך בלוק cli, ושגיאת העלייה שלו מציינת את managedMcpServers כמפתח שבו יש להשתמש. לפני גרסה v2.1.259, השער דחה כל הגדרת שרת MCP בתוך בלוק cli.

#שכבת Claude Desktop

אם הארגון שלך פורס גם את Claude Desktop, אותו שער משרת את שני הלקוחות. כוון את bootstrapUrl, בתוך התצורה המנוהלת של Claude Desktop, אל <listen.public_url>/user/bootstrap. התוכנה Claude Desktop גוזרת את מנפיק ה-OAuth מכתובת URL זו, מריצה את אותה התחברות עם קוד מכשיר מול שער זה, ושולפת את התצורה שלה מתוך התגובה.

הערה: דורש Claude Code גרסה v2.1.203 ומעלה בשרת השער, והרשאה מפורשת: הנתיב /user/bootstrap מחזיר 404 אלא אם כן המדיניות המתאימה למשתמש נושאת מפתח desktop. מפתח ריק desktop: {} מצרף מדיניות, ומפתח desktop על גבי שכבת הבסיס match: {} מצרף כל מדיניות שיורשת אותה. יומן הביקורת מתעד כל בקשה כ-desktop_bootstrap.serve או desktop_bootstrap.denied.

השער גוזר חלק גדול מהתגובה מתוך בלוק ה-cli של המדיניות שהותאמה ומתצורת השער ברמה העליונה:

• רשימת הדגמים, מתוך availableModels.

• כלים מושבתים, מתוך רשומות permissions.deny של שמות כלים בלבד. אם תגדיר disabledBuiltinTools בבלוק ה-desktop של המדיניות, השער משרת את האיחוד של הערך שלך ושל הרשימה הנגזרת, כך שתוכל להשבית כלים נוספים בדרך זו אך לא תוכל להפעיל מחדש כלי שהשבתת דרך permissions.deny.

• רשימת התרת היציאה, מתוך sandbox.network.allowedDomains. אם תגדיר coworkEgressAllowedHosts בבלוק ה-desktop של המדיניות, השער משתמש בערך זה במקום ברשימה הנגזרת.

• נקודת קצה של OTLP המצביעה על השער עצמו, ותכונות הזהות של המשתמש המחובר. השער מעביר את הייצואים שהוא מקבל בנקודת קצה זו ליעדי ה-forward_to שלך. הוא כולל את נקודת הקצה והתכונות כאשר מוגדרים גם telemetry.forward_to וגם listen.public_url.

  התוכנה Claude Desktop מייצאת כל אות באמצעות קידוד אחד: http/protobuf, או http/json כאשר אתה מגדיר את OTEL_EXPORTER_OTLP_PROTOCOL או את אחת הווריאציות שלו לפי אות ל-http/json ב-env של המדיניות. לפני גרסה v2.1.261 של Claude Code בשרת השער, התגובה הגדירה http/json בכל מקרה, ולכן אספן שמקבל רק protobuf דחה את הייצואים של Claude Desktop.

כדי להגדיר את disabledBuiltinTools, את coworkEgressAllowedHosts, או את הגדרת managedMcpServers של Claude Desktop עצמה בתוך בלוק desktop של מדיניות, דרושה גרסה v2.1.232 ומעלה של Claude Code בשרת השער. ההגדרה managedMcpServers של Claude Desktop מקבלת ערך מערך ולא אובייקט.

השער משמיט מתוך תגובת ה-bootstrap מפתחות שאין להם מקבילה ב-Claude Desktop, כגון hooks וכללי הרשאות בעלי היקף מוגדר כגון Bash(npm *).

הוסף את בלוק ה-desktop האופציונלי לצד cli כדי להגדיר הגדרות Claude Desktop ישירות. כתוב הגדרות מתוך מדריך התצורה המנוהלת של Claude Desktop כשמות מפתחות שטוחים. השמט מפתחות ש-Claude Desktop קוראת רק מ-MDM או מקבצים מקומיים, כגון bootstrapUrl: השער דוחה אותם בעת העלייה. לפני גרסה v2.1.232, השער קיבל רשימה קבועה של 11 מפתחות של תכונות, כגון chatTabEnabled ו-disableAutoUpdates, ודחה כל מפתח אחר בעת העלייה. לפני גרסה v2.1.227, השער דחה בעת העלייה גם את chatTabEnabled ואת chatAdvancedFileAnalysisEnabled.

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

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

• מפתח לא מוכר
• מפתח מוכר שערכו יידחה או יימחק בשקט על ידי Claude Desktop, כגון ערך ריק או תת-מפתח ששמו שגוי בתוך רשומה מקוננת. לפני גרסה v2.1.260, השער השמיט בשקט שדה ששמו שגוי בתוך אובייקט מקונן של רשומת managedMcpServers או orgPluginSettings במקום להיכשל בעת העלייה.
• מפתח שהשער מחשב בעצמו: חיבור העיבוד, רשימת הדגמים, וממסר ה-OTLP. הגדר אותם דרך upstreams, models, והסעיף forward_to שבתוך telemetry.
• כינוי מדור קודם של מפתח נוכחי. בשגיאת העלייה, השער מציין את המפתח הקנוני שיש לכתוב.

אם תשתמש בערך שהוצא משימוש או במבנה רשומה מיושן, כגון רשומת managedMcpServers ללא transport, השער יעלה וירשום אזהרה המציינת את החלופה.

השער מאמת בלוק desktop מול הסכמה המצורפת לגרסה המותקנת שלו, בדיוק כפי שהוא עושה עבור בלוק ה-cli. כדי למסור הגדרה שהוצגה במהדורה חדשה יותר של Claude Desktop, שדרג תחילה את השער. לדוגמה, userPluginMarketplacesEnabled ו-userPluginUploadsEnabled זקוקים ל-Claude Code גרסה v2.1.260 ומעלה בשרת השער ול-Claude Desktop גרסה 1.37937.0 ומעלה במכונות של החברים.

אם תגדיר orgPluginSettings בבלוק ה-desktop של מדיניות, השער משרת אותו בתבנית מערך ש-Claude Desktop 1.15200.0 ומעלה קוראת. מחשבים שולחניים ישנים יותר מתעלמים מהמערך ואינם אוכפים שום מדיניות כלי תוספים, לכן עדכן את החברים לגרסה 1.15200.0 ומעלה לפני שתסתמך על כך.

השער משלים מפתחות שבלוק ה-desktop של מדיניות אינו מגדיר מתוך בלוק ה-desktop של ברירת המחדל הכוללת match: {}, באותו אופן שבו הוא משלים את בלוק ה-cli של מדיניות מתוך הבסיס. אם תגדיר disabledBuiltinTools או builtinToolPolicy גם בבסיס וגם במדיניות תפקיד, השער שומר על ההגבלה של הבסיס:

• disabledBuiltinTools: השער משתמש באיחוד של רשימת הבסיס ורשימת המדיניות.
• builtinToolPolicy: אם הגדרת כלי לערך שאינו allow בבסיס, השער שומר על ערך זה גם אם הגדרת allow עבור אותו כלי במדיניות תפקיד.

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

אם אינך פורס את Claude Desktop, השמט את desktop מהמדיניות שלך לחלוטין: השער יחזיר אז 404 מ-/user/bootstrap עבור כל משתמש.

#עדיפות מול מקורות ניהול אחרים

אם למכשיר יש גם מדיניות שנמסרה דרך MDM או קובץ managed-settings.json מקומי, הגדרות שנמסרו על ידי השער מקבלות עדיפות ראשונה. המסמך עדיפות בתוך רמת הניהול בדף ההגדרות המנוהלות מפרט מתי מקורות מקומיים חלים, ומכיל את המפתחות ש-Claude Code קוראת מכל מקור ניהול ללא קשר לאיזה מקור נבחר, כגון מפתחות נעילת סביבת הבידוד, forceRemoteSettingsRefresh, ומיזוג env לכל משתנה. רכיב policyHelper המוגדר בפרופיל MDM או בקובץ ההגדרות המנוהלות רץ רק כאשר השער אינו מוסר הגדרות: הרשומה מציינת מה הפלט שלו מחליף.

מארחים מטמיעים כגון Claude Desktop יכולים לספק מדיניות דרך אפשרות ה-SDK של managedSettings. המסמך הגדרות אב ממארחים מטמיעים מציין מתי Claude Code מחילה אותה, והמסמך הגבלת הגדרות אב מפרט אילו הגדרות בכיוון התרה עדיין חלות ללא נעילות ה-allowManaged*Only.

מדיניות השער חלה על כל הפעלה של Claude Code במכונה, כולל ריצות לא אינטראקטיביות של claude -p והפעלות שנוצרו על ידי ה-Agent SDK. אם השער אינו נגיש בעת העלייה, הפעלות מחוברות יוצאות עם שגיאה במקום לרוץ ללא המדיניות שלהן.

#telemetry

ה-CLI שולח מדדים (metrics), יומנים (logs), וכאשר מופעל, עקבות (traces) אל השער, אשר מעביר אותם כלשונם לכל יעד מוגדר. הייצואים משתמשים בפרוטוקול OpenTelemetry Protocol (OTLP) על גבי HTTP. כדי לדלג על הממסר ולגרום להפעלות לייצא ישירות לאספן שלך, ציין את שם האספן במדיניות. ראה ניטור שימוש עבור המדדים והאירועים שה-CLI פולט.

ה-CLI מחתים כל ייצוא בזהות המשתמש המאומת, הנקראת מתוך ה-JWT שהונפק על ידי השער: התכונות user.id, user.email, ו-user.groups. ייחוס עלויות ושימוש לפי מפתח פועל לפיכך ללא כל הגדרה בצד המפתח.

הפעלות Claude Desktop ו-Cowork המחוברות דרך השער מחתימות את הטלמטריה שלהן ב-user.email וב-user.groups לצד enduser.id, כך שתוכל לכסות שימוש במסוף, ב-Desktop וב-Cowork בשאילתה יחידה על user.email או user.groups. התכונה user.groups היא רשימת קבוצות ה-IdP מופרדת בפסיקים.

טלמטריה של Desktop ו-Cowork נושאת בנוסף את enduser.sub, תביעת ה-sub שספק הזהויות שלך מנפיק עבור המשתמש, שנשארת ללא שינוי כאשר כתובת הדוא"ל של המשתמש משתנה. הפעלות מסוף מחתימות את אותו ערך תחת user.id, כך ששאילתה המתאימה בין enduser.sub לבין user.id של המסוף מכסה יחד את השימוש של משתמש יחיד במסוף, ב-Desktop וב-Cowork. בייצואי Desktop ו-Cowork, התכונה user.id היא מזהה אנונימי, ולא הנושא.

כמו כל נתוני ה-OpenTelemetry מ-Claude Code, תכונות אלו נשלחות רק ליעדים שהארגון שלך מגדיר, לעולם לא ל-Anthropic.

אם רשימת הקבוצות של משתמש ארוכה מ-255 תווים לאחר קידוד אחוזים, או ששם קבוצה מכיל פסיק או סימן שווה, השער משמיט את user.groups מהטלמטריה של ה-Desktop וה-Cowork של אותו משתמש במקום לקטוע אותה. הפעלות המסוף של אותו משתמש עדיין נושאות את הרשימה המלאה.

השער משמיט את enduser.sub כאשר הנושא ארוך מ-255 תווים לאחר קידוד אחוזים, או מכיל רווח, תו מחוץ ל-ASCII הניתן להדפסה, או אחד מהתווים , ; = \ " %. הטלמטריה של Desktop ו-Cowork של אותו משתמש שומרת על שאר התכונות שלה.

דרושה גרסה v2.1.265 ומעלה של Claude Code בשרת השער עבור user.email ו-user.groups בטלמטריה של Desktop ו-Cowork, וגרסה 1.24012 ומעלה של Claude Desktop במחשב של כל מפתח עבור user.groups.

דרושה גרסה v2.1.274 ומעלה של Claude Code בשרת השער עבור enduser.sub.

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      
# Per-signal opt-in. Default: metrics only.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

אזהרה: כל יעד בוחר ב-metrics, ב-logs, וב-traces באופן עצמאי, וברירת המחדל היא מדדים בלבד. האותות נבדלים ברמת הרגישות שלהם:

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

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

כל כתובת URL ב-forward_to חייבת להשתמש ב-https://, למעט חריג אחד עבור אספן בממשק ה-loopback של השער עצמו:

• כתובת http://localhost:<port> עוברת את אימות התצורה, אך מנגנון ההגנה מפני SSRF חוסם כל ייצוא עם ECONNREFUSED_SSRF, אלא אם כן תגדיר CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 בסביבת השער.
• כתובת http://127.0.0.1:<port> או http://[::1]:<port> מכשילה את העלייה אלא אם משתנה זה מוגדר.

עבור אספן בתוך האשכול, חשוף אותו ב-HTTPS בכתובת הפנימית שלו, או הרץ אותו כ-sidecar כאשר המשתנה מוגדר.

כאשר מוגדר HTTPS_PROXY, השער שולח ייצואים דרך אותו פרוקסי.

כדי להגיע לאספן פנימי ישירות, הוסף אותו ל-NO_PROXY לפי שם מארח או לפי דומיין עם נקודה מובילה כגון .internal.example.com, מה שדורש Claude Code גרסה v2.1.277 ומעלה בשרת השער. ודא שהשער יכול להגיע לאספן ללא הפרוקסי. רשומה ללא נקודה מובילה תואמת לשם המדויק בלבד, ולא לשמות שתחתיו. טווחי CIDR אינם נתמכים להתאמה.

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

הטלמטריה כבויה ב-CLI כברירת מחדל. כאשר אתה מגדיר גם את telemetry.forward_to וגם את listen.public_url, השער מפעיל אותה עבור לקוחות מחוברים על ידי דחיפת שישה משתני סביבה דרך /managed/settings:

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, ו-OTEL_TRACES_EXPORTER, שכל אחד מהם מוגדר ל-otlp אם לפחות יעד forward_to אחד מפעיל את אותו אות, ול-none אחרת.
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

לפני Claude Code גרסה v2.1.265 בשרת השער, השער דחף את כל שלושת בוררי הייצוא כ-otlp, כולל עבור אותות שאף יעד לא בחר לקבל.

נקודת הקצה שנדחפת נבנית מתוך כתובת ה-URL הציבורית, כך שמדדים ויומנים אינם זקוקים לתצורת OTEL מצד המפתחים או המדיניות.

מפתחים המחוברים דרך /login אינם יכולים לנתב מחדש ייצואים באמצעות תצורת OTEL משלהם:

• משתנים שהוגדרו מקומית: התוכנה Claude Code מחילה את המשתנים שנדחפו ברמת הניהול, כך שכל אחד מהם עוקף את הערך שמפתח הגדיר עבורו מקומית.
• נקודות קצה שהוגדרו מקומית: כאשר ייצוא OTLP/HTTP מופעל, ה-CLI מתעלם מכל נקודת קצה שהוגדרה מקומית, בין אם השער דחף את משתני הטלמטריה ובין אם לא. הייצואים שלו מגיעים לשער, אלא אם כן מדיניות מציינת את האספן שלך כנקודת הקצה.

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

הפעלת עקבות דורשת בנוסף CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 בכל לקוח. הגדר זאת בבלוק env של מדיניות מנוהלת, מכיוון שהשער אינו דוחף זאת בעצמו. מפתחים מאשרים זאת באותה תיבת דו-שיח לאישור אבטחה שנקודת הקצה שנדחפה כבר מפעילה.

הגדר זאת ל-1 רק במדיניות של הקבוצות שאתה רוצה לעקוב אחריהן. מדיניות שאינה מגדירה זאת יורשת את הערך ממדיניות ברירת המחדל הכוללת match: {} אם אותה מדיניות מגדירה ערך כזה, לפי כללי המיזוג. כדי למנוע מלקוחות של קבוצה לשלוח עקבות גם כאשר מפתח מגדיר את המשתנה מקומית, הגדר אותו ל-0 במדיניות של אותה קבוצה.

הן קידודי OTLP ב-protobuf והן ב-JSON מועברים הלאה, וכל מערכת backend התואמת ל-OpenTelemetry מתאימה כיעד.

#ייצוא ישירות לאספן שלך

כדי שהפעלות המחוברות דרך /login ישלחו טלמטריה ישירות לאספן שלך במקום דרך הממסר, הגדר את OTEL_EXPORTER_OTLP_ENDPOINT לכתובת ה-URL הבסיסית ב-https:// של האספן בבלוק ה-env של מדיניות מנוהלת. התוכנה Claude Code מצרפת /v1/metrics, /v1/logs, או /v1/traces לכתובת ה-URL שתגדיר, כגון https://otel-collector.example.com:4318, ומייצאת כל אות לשם על גבי OTLP/HTTP. דורש Claude Code גרסה v2.1.265 ומעלה במחשב של כל מפתח. לקוחות ישנים יותר מייצאים דרך הממסר.

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

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

התוכנה Claude Code בודקת את נקודת הקצה לפני שהיא מייצאת אות ישירות, ומשאירה את האות בממסר כאשר בדיקה נכשלת. הבדיקות כוללות:

• נקודת הקצה מגיעה מהשער עצמו. אם הגדרת את אותו משתנה בפרופיל MDM או בקובץ managed-settings.json מקומי, הייצואים נשארים בממסר.
• כתובת ה-URL משתמשת ב-https://, או ב-http:// לכתובת loopback.
• כתובת ה-URL מתפענחת לנתיב המסתיים ב-/v1/<signal>, ללא שאילתה או מקטע. התוכנה Claude Code בונה נתיב זה בעצמה מתוך המשתנה הכללי. היא משתמשת במשתנה לפי אות כגון OTEL_EXPORTER_OTLP_METRICS_ENDPOINT כפי שנכתב, לכן כלול שם את הנתיב המלא.
• כתובת ה-URL אינה המארח של השער עצמו. נקודת קצה המופנית לשער שומרת על נתיב הממסר ואסימון ההפעלה שלו.
• לא אתה ולא המפתח הגדרתם את otelHeadersHelper באף מקור הגדרות. כאשר רכיב עזר מוגדר, כל אות נשאר בממסר.

נקודת הקצה שאתה מציין משנה רק את היעד שאליו הייצואים נשלחים. אתה עדיין בוחר אילו אותות מיוצאים בכלל באמצעות בוררי ה-OTEL_*_EXPORTER.

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

• אם השער כבר דוחף את משתני הטלמטריה, הם מכסים את ההפעלה, הבוררים והפרוטוקול, ונקודת הקצה המפורשת שלך עוקפת את ערך ה-<public_url> שנדחף. הגדר בורר OTEL_*_EXPORTER ל-otlp בעצמך רק עבור אות שאף יעד ב-forward_to אינו מפעיל.
• אם הוא אינו דוחף אותם, הגדר בנוסף את CLAUDE_CODE_ENABLE_TELEMETRY=1, את בוררי ה-OTEL_*_EXPORTER, ואת OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

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

#כאשר יעד נכשל

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

לאחר חמש מסירות רצופות שנכשלו ליעד מסוים, השער משהה את ההעברה אליו במקטעים של 30 שניות, ומתעד כל השהיה ביומן, עד שמסירה מצליחה. כל תגובת שגיאה, פסק זמן, או שגיאת חיבור נחשבים למסירה שנכשלה, למעט 400, 413, 415, 422, ו-431, שמשמעותם שהאספן סירב למטען הייצוא כבלתי תקין או גדול מדי.

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

#כוונון HTTP

ארבעה בלוקים אופציונליים ברמה העליונה, access_control, limits, timeouts, ו-rate_limits, מכווננים את ממשק ה-HTTP. ברירות המחדל מתאימות לרוב הפריסות.

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

כאשר allow_cidrs ריקה, השער מזהיר בשני מקומות, מבלי לשנות את אופן המענה לבקשה כלשהי:

• בעת העלייה: אזהרה ביומן המבצעי ממליצה להתיר רק את הטווחים הפרטיים 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 127.0.0.0/8, ::1/128, ו-fc00::/7, בנוסף לכל טווח פנימי אחר שממנו המפתחים שלך מתחברים. אם תקשור את השער לכתובת loopback ולא תגדיר trusted_proxies וגם לא public_url, כמו בפיתוח מקומי, האזהרה אינה מופיעה.
• בזמן ריצה: בפעם הראשונה שבקשה מגיעה מכתובת שמחוץ לטווחים פרטיים אלה, השער רושם אזהרה ופולט אירוע ביקורת access.public_client הנושא את ה-IP של הלקוח. שניהם מופעלים פעם אחת לכל תהליך. כתובות link-local, 169.254.0.0/16 ו-fe80::/10, אינן נספרות כציבוריות. השער עונה על /healthz ו-/readyz לפני שבדיקה זו רצה, כך שבדיקות תקינות מטווחים ציבוריים אינן מפעילות אותה.

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

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

#load_test_mode

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

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

הדוגמה להלן מפעילה את המצב עם ערכי ברירת המחדל, תשובה של 750 אסימוני פלט המוזרמת לאורך כ-10 שניות:

load_test_mode:
  enabled: true
  reply_tokens: 750     
# roughly how many tokens of text each canned reply carries
  reply_seconds: 9.5    
# how long a streamed reply takes

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

כל עוד המצב מופעל, בקשה יכולה לשאת כותרת x-load-test-user המכילה מספר שלם של עד שבע ספרות, והשער סופר כל מספר כמפתח נפרד עם הדוא"ל והקבוצות של המפתח שהאסימון שלו הגיע עם הבקשה. הקצה לפריסת בדיקת העומסים בסיס נתונים ריק משלה, מכיוון שהשער מסרב לפעול כאשר המצב מופעל מול בסיס נתונים שבו מפתח כלשהו כבר ביצע הוצאה כלשהי.

אזהרה: לעולם אל תפעיל זאת עבור שער שמפתחים משתמשים בו. כל בקשה מקבלת את התשובה המוכנה מראש ושום דגם אינו נקרא. השער רושם אזהרת load_test_mode is on בעת העלייה ומסמן כל אירוע ביקורת של עיבוד ב-load_test: true כל עוד המצב מופעל.

#דוגמה מלאה

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

# Run with:
#   claude gateway --config gateway.yaml
#
# Operational log verbosity is controlled by the CLAUDE_GATEWAY_LOG_LEVEL
# environment variable (debug | info | warn | error; default info). debug
# also logs the claim names in each id_token, for groups_claim diagnosis.
# It does not affect audit events, which are always emitted.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  
# Omit the tls block when running behind a TLS-terminating ingress.
  
# tls:
  
#   cert: /certs/gateway.crt
  
#   key: /certs/gateway.key
  
# trusted_proxies:
  
#   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  
# Required when the issuer is the Okta org server, whose id_tokens
  
# can omit email and groups; the gateway fills them from /userinfo.
  userinfo_fallback: true
  
# allowed_groups: [claude-code-users]
  
# Okta emits groups only when the `groups` scope is requested and the
  
# app's groups claim filter allows them. The contractors policy below
  
# matches on groups, so the scope is requested here.
  scopes: [openid, profile, email, offline_access, groups]
  
# extra_auth_params: { access_type: offline, prompt: consent }  
# Google
  
# groups_claim: groups          
# Entra app roles: use `roles`
  
# email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   
# openssl rand -base64 32
  
# ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  
# max_connections: 5
  
# connect_timeout_seconds: 5

# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)
# and per-developer spend enforcement on /v1/messages. Omit to disable.
# Caps themselves are set via the admin API, not here.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   
# audit_retention_days: 365
#   
# spend_retention_months: 13
#   
# identity_retention_days: 90
#   
# group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

# Load test this deployment without calling a model provider. Never on a
# gateway that developers use: every request gets a canned reply.
# load_test_mode:
#   enabled: true
#   
# reply_tokens: 750
#   
# reply_seconds: 9.5

# Meter at contracted rates instead of USD list price. Requires admin: or a
# managed: policy. With managed:, the same rates also go to signed-in clients.
# Rates below are placeholders, not real contract prices.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  
# - provider: bedrock
  
#   region: us-east-1
  
#   auth: {}

  
# - provider: anthropicAws
  
#   region: us-east-1
  
#   workspace_id: wrkspc_...
  
#   auth:
  
#     api_key: ${ANTHROPIC_AWS_API_KEY}

  
# - provider: vertex
  
#   region: us-east5
  
#   project_id: example-prod
  
#   auth: {}

  
# - provider: foundry
  
#   resource: example-foundry
  
#   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      
# bedrock: us.anthropic.claude-opus-4-8
      
# anthropicAws: claude-opus-4-8
      
# vertex: claude-opus-4-8
      
# foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        
# Constrain the Default picker option to availableModels instead of
        
# the tier default, so contractors don't get a 400 on the default.
        enforceAvailableModels: true
        
# allow auto-approves these tools; it does not block the rest.
        
# Add deny rules to restrict tools.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

#הגדרות מנוהלות בצד הלקוח

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

עבור ה-CLI, הגדר מפתחות אלו בקובץ managed-settings.json המתאים למערכת ההפעלה. שני מפתחות ההתחברות מנתבים את ה-/login של כל מפתח אל השער שלך:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

הערך "parentSettingsBehavior": "merge" שומר על תקינות מסירת רשימת התרת היציאה מ-Claude Desktop להפעלות Claude Code המוטמעות בתוכה: המסמך מסירת מדיניות להפעלות Claude Desktop מסביר את המנגנון והיכן חייבת להימצא ההרשאה.

פרוס את הקובץ managed-settings.json לכל מכשיר, בדרך כלל דרך פלטפורמת ה-MDM שלך. נתיב הקובץ שונה בכל פלטפורמה. ראה היכן כל מנגנון שומר את המדיניות.

כברירת מחדל, מדיניות registry ב-Windows או קובץ plist של managed-preferences ב-macOS מחליפים את הקובץ managed-settings.json במקום להתמזג איתו, מלבד מפתחות החריגים והבדיקות חוצות המקורות לעיל. כל שלושת המפתחות בקטע קוד זה פועלים לפי כלל המקור בעל העדיפות הגבוהה ביותר, כך שציי מחשבים המוסרים מדיניות דרך Group Policy או פרופילי תצורה חייבים למקם את כל השלושה באותו מנגנון במקום זאת.

עבור Claude Desktop, הגדר את המפתח bootstrapUrl בתוך התצורה המנוהלת של Claude Desktop עצמה ל-<listen.public_url>/user/bootstrap. תהליך ההתחברות והמדיניות לפי קבוצה יתאימו אז לאלה של ה-CLI ברגע שמדיניות מסכימה להצטרף בצד השרת עם מפתח desktop: ללא ההצטרפות, /user/bootstrap מחזיר 404. ראה שכבת Claude Desktop עבור החלק של צד השרת.

התוכנה Claude Code מכבדת את forceLoginGatewayUrl, את gatewayInternalNetworks, ואת הערך "gateway" של forceLoginMethod אך ורק ממקור מנוהל במכשיר: managed-settings.json, קובץ ה-plist ב-macOS או ה-registry של HKLM ב-Windows, או policy helper. מפתח שמגדיר אותם בקובץ ~/.claude/settings.json שלו אינו משפיע, וכך גם להגדרתם במטען הנתונים של השער אין כל השפעה.

#נושאים קשורים

• סקירת שער יישומי Claude: מדריך מהיר וחיבור מפתחים
• מדריך פריסה: הגדרת IdP, תמונת מכולה, Kubernetes ו-Cloud Run, ותפעול
• מגבלות הוצאה: תקרות לכל מפתח וה-Admin API