📘 תיעוד 73

Claude apps gateway עבור Amazon Bedrock, Claude Platform ב-AWS, Google Cloud ו-Microsoft Foundry

הרצת Claude Code דרך Amazon Bedrock, Claude Platform ב-AWS, Google Cloud או Microsoft Foundry מאחורי שער באירוח עצמי (self-hosted) עם התחברות SSO, גישה למודלים לפי קבוצה וטלמטריית OTLP.

הערה: ה-Claude apps gateway מיועד לארגונים שחייבים, או מעדיפים, לנתב היקש (inference) דרך ספק הענן שלהם, למשל כדי לעמוד בדרישות שמירת נתונים מקומית (data residency). אם אין לכם דרישה זו, ואתם מעוניינים בגישה לתכונות אחרות כגון הקצאת SCIM או Claude Code ברשת ובמכשירים ניידים, ייתכן ש-Claude Enterprise יתאים יותר. ראו את דף זמינות התכונות להשוואה מלאה של כל שיטות הפריסה.

Claude apps gateway הוא שירות באירוח עצמי שנמצא בין לקוחות ה-Claude Code של המפתחים לבין ספק המודל שלכם. מפתחים מתחברים באמצעות ספק הזהויות הארגוני שלכם (IdP) במקום להחזיק מפתחות API או פרטי גישה לענן. השער מחזיק את פרטי הגישה במעלה הזרם (upstream), אוכף גישה למודלים והגדרות מנוהלות (managed settings) לפי קבוצת IdP, ומעביר טלמטריית שימוש למערך הניטור (observability) שלכם.

הוא כלול בקובץ ההפעלה הבינארי של claude, כך שאותו קובץ הפעלה שמריץ את Claude Code במחשב נייד מריץ את שרת השער באמצעות claude gateway --config gateway.yaml.

דף זה מכסה:

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

דפים נלווים מעמיקים יותר. מדריך התצורה מכסה כל אפשרות בקובץ ה-YAML שנכתב במדריך ההתחלה המהירה, ומדריך הפריסה מכסה הגדרה לפי IdP, פריסה ב-Kubernetes וב-Cloud Run, ותפעול.

#מדוע Claude apps gateway

סקירת השערים מכסה מה שער עושה ומדוע כדאי להפעיל שער כזה. ה-Claude apps gateway הוא שער מבית Anthropic, המובנה בתוך הקובץ הבינארי של claude ונבדק לצד כל מהדורה של Claude Code, כך שהוא מעביר את הכותרות (headers) ושדות הבקשה ש-Claude Code שולח מבלי שמפעילים יצטרכו לתחזק רשימת היתרים נפרדת. לאחר פריסתו הוא מספק:

• פרטי גישה (Credentials): מפתח ה-API או פרטי הגישה לענן במעלה הזרם שמורים אך ורק בתשתית שלכם. מפתחים מזדהים באמצעות SSO ארגוני ומקבלים אסימוני bearer קצרי מועד, כך שתהליך הוצאת משתמש (offboarding) מתבצע ב-IdP שלכם. ביטול הקצאת משתמש (deprovision) גורם לפקיעת הגישה שלו לשער בתוך משך חיי ההפעלה (session lifetime), שעה אחת כברירת מחדל.
• בקרת גישה (Access control): קבוצות ה-IdP שלכם ממופות לרשימות היתרי מודלים ולמדיניות של הגדרות מנוהלות. השער אוכף גישה למודלים בצד השרת, דוחה בקשות למודלים שלא אושרו, ובוחר את מדיניות ההגדרות המנוהלות של כל קבוצה, אותה ה-CLI מחיל בשכבת ההגדרות המנוהלות. צוותים שונים מקבלים מודלים, כלים והרשאות שונים, ומפתח אינו יכול לעקוף את מה שהמדיניות שלו נועלת.
• אספקת הגדרות (Settings delivery): השער מספק הגדרות מנוהלות ללקוחות מחוברים בעצמו, ותופס את מקומן של הגדרות מנוהלות על ידי שרת (server-managed settings) ממסוף הניהול של claude.ai.
• טלמטריה (Telemetry): כל יעד מוגדר מקבל מדדי OpenTelemetry Protocol (OTLP) עם ספירת טוקנים, מודל, זהות משתמש וזמן השהיה כברירת מחדל, כאשר יומנים (logs) ועקבות (traces) ניתנים להפעלה לפי בחירה (opt-in) עבור כל יעד.
• ניתוב במעלה הזרם (Upstream routing): לקוחות מתקשרים עם השער באמצעות ה-Messages API של Anthropic, והשער מתרגם עבור כל ספק במעלה הזרם, בין אם Amazon Bedrock, Claude Platform ב-AWS, Agent Platform של Google Cloud, Microsoft Foundry או ה-API של Anthropic, עם מעבר לגיבוי בעת כשל (failover) ביניהם. ניתן לשנות אזורים, ספקים או סדר גיבוי מבלי שהמפתחים יבחינו בכך או יידרשו להגדרה מחדש.

הערה: מישור הנתונים (data plane) של השער עצמו אינו שולח דבר לתשתית של Anthropic, אלא אם ה-API של Anthropic מוגדר כספק במעלה הזרם. אתם שולטים לאן מגיעים נתוני טלמטריה, יומני ביקורת (audit logs), הגדרות מנוהלות וזהות ה-IdP של המפתחים שלכם, והשער אינו שולח אף אחד מהם ל-Anthropic. לגבי יתר התעבורה שתהליך ה-CLI יכול לשלוח וכיצד לחסום אותה, ראו מצב תאימות (Compliance posture).

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

#מימושי שערים אחרים

אם אתם כבר מפעילים שער LLM או שער API שעונה על הצרכים שלכם, המשיכו להשתמש בו; הדף שערי LLM אחרים מכסה את הגדרת Claude Code מולו.

מדריך תאימות השערים מתעד מה Claude Code מצפה מכל שער: נקודות הקצה (endpoints) שהוא קורא להן, הכותרות (headers) ושדות גוף הבקשה שיש להעביר הלאה, ומה מפסיק לעבוד כאשר הם מוסרים. בנוסף, Claude apps gateway פעיל מגיש מדריך פרוטוקול משלו בנתיב GET /protocol, המתאר את נקודות הקצה שהוא חושף ללקוחות Claude Code: התחברות SSO, היקש (inference), אספקת הגדרות מנוהלות, גילוי מודלים וטלמטריה. ניתן לשלוף אותו באמצעות curl https://claude-gateway.internal.example.com/protocol מכל שער פרוס, כמו זה שנוצר במדריך ההתחלה המהירה להלן.

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

#התחלה מהירה

מדריך התחלה מהירה זה מציג את המסלול המינימלי: רישום לקוח OAuth ב-IdP שלכם, כתיבת gateway.yaml, הרצת השער לצד Postgres באמצעות Docker Compose, ואימות התחברות מקצה לקצה. הוא משתמש ב-Amazon Bedrock כספק במעלה הזרם; Claude Platform ב-AWS, Agent Platform של Google Cloud, Microsoft Foundry וה-API של Anthropic נתמכים באותה מידה על ידי החלפת בלוק ה-upstreams כפי שמוצג במדריך התצורה. בסיום התהליך יהיה ברשותכם שער שמפתח יכול לבצע אליו login/.

הערה: פריסה ברשת הפרטית שלכם. Claude Code מתחבר אך ורק לשער שכתובתו פרטית. זהו מנגנון הגנה אבטחתי, מכיוון ששער מהימן יכול לדחוף הגדרות שמריצות פקודות במחשבי מפתחים. מקמו את השער מאחורי נתב עומסים פנימי (internal load balancer) או VPN והעניקו לו שם מארח (hostname) שנפתר לכתובות IP פרטיות בלבד.

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

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

#שלבים

1. רשמו לקוח OAuth ב-IdP שלכם: החליטו תחילה על שם המארח של השער, מכיוון ש-URI להפניה מחדש (redirect URI) חייב להתאים לו. צרו יישום רשת OIDC חדש והגדירו את ה-redirect URI לכתובת https://claude-gateway.<your-domain>/oauth/callback, כאשר המארח הוא אותו ערך שתגדירו כ-listen.public_url בשלב 3. רשמו לפניכם את ה-client_id ואת ה-client_secret. הוראות עבור כל IdP מופיעות בהגדרת ספק זהויות.

2. הקצו מסד נתונים של PostgreSQL: כל Postgres בגרסה 14 ומעלה מתאים, כולל השכבה המנוהלת הקטנה ביותר. השער מריץ בעצמו מיגרציות סכמה בעת האתחול, ולכן תפקיד מסד הנתונים (database role) זקוק להרשאות ליצירת טבלאות ולשינוי טבלאות; ראו store.

3. כתבו את gateway.yaml: סודות נקראים באמצעות הרחבת משתני סביבה ${ENV_VAR}, כך שהקובץ עצמו יכול להישמר בניהול גרסאות (version control). השתמשו בשם מארח עבור public_url שנפתר ל-IP פרטי ברשת שלכם, מכיוון ש-login/ דוחה כתובות ציבוריות. התצורה המינימלית כוללת חמישה סעיפים, ולכל שאר השדות יש ערכי ברירת מחדל:

listen:
  host: 0.0.0.0
  port: 8080
  
# Required unless host is a loopback address. Used for the IdP
  
# redirect_uri and the discovery document.
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com        
# must serve /.well-known/openid-configuration
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]        
# reject id_tokens outside your org
  userinfo_fallback: true                  
# for IdPs whose id_token omits email/groups; harmless otherwise

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}        
# openssl rand -base64 32
  ttl_hours: 1                             
# also bounds revocation latency on IdP deprovision

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}    
# add ?sslmode=require for managed Postgres

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                               
# empty: AWS default credential chain
                                           
# (IRSA, EC2/ECS task role, env vars, ~/.aws)

# Models are translated per upstream automatically. The built-in catalog
# maps claude-opus-4-8 to us.anthropic.claude-opus-4-8 and so on for every
# Bedrock-supported Claude model. Set false and add a `models:` list to
# expose only specific models.
auto_include_builtin_models: true

תצורה זו מספיקה עבור מחזור התחברות תקין עם קטלוג ברירת המחדל של דגמי Amazon Bedrock. לאחר שהשער פועל, הוסיפו RBAC והגדרות מנוהלות לפי קבוצה דרך managed.policies, הפצת טלמטריה דרך telemetry, ומעבר גיבוי בין מספר ספקים, ARNs של provisioned-throughput, או אזורים מחוץ לארצות הברית דרך models.

הערה: הספק Amazon Bedrock במעלה הזרם זקוק לישות AWS (principal) עם ההרשאות bedrock:InvokeModel ו-bedrock:InvokeModelWithResponseStream הן על ה-ARNs של inference-profile/us.anthropic.* והן על ה-ARNs שבבסיסם של foundation-model/anthropic.*, וכן להגשת טופס מקרה השימוש החד-פעמי של Anthropic עבור החשבון מתוך קטלוג הדגמים (Model catalog) במסוף Bedrock. ספקו את פרטי הגישה באמצעות IRSA ב-EKS, תפקיד משימה ב-ECS (task role), או פרופיל מופע ב-EC2 (instance profile) במקום מפתחות סטטיים. מדריך upstreams מכיל את פרטי ה-IAM המלאים, את מטריצת פרטי הגישה בין העננים, ואת בלוקי ה-auth עבור הספקים האחרים.

4. הריצו אותו: בנו תמונת מכולה (container image) סביב הקובץ הבינארי של claude שעומדת בדרישות התמונה, ולאחר מכן הריצו אותה לצד Postgres. קובץ ה-Compose מתייחס לתמונה בשם registry.example.com/claude-gateway:2.1.198; החליפו זאת ב-registry ובתג התמונה שלכם:

services:
  gateway:
    image: registry.example.com/claude-gateway:2.1.198
    ports: ["8080:8080"]
    volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]
    environment:
      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}
      GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway
      
# AWS credentials: in production, omit these and use an instance
      
# role. For local Compose testing, pass through your own:
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
      AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}
    depends_on:
      postgres:
        condition: service_healthy
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gw"]
      interval: 5s
    volumes: ["pgdata:/var/lib/postgresql/data"]
volumes: { pgdata: }

השער הוא קובץ בינארי יחיד של Linux שקורא את התצורה, מתחבר ל-Postgres ומחיל את מיגרציות הסכמה שלו, מריץ גילוי OIDC מול ה-IdP שלכם, בונה לקוחות במעלה הזרם ומתחיל להאזין. האתחול פועל במצב של כישלון חוסם (fail-closed) עבור התצורה, חיבור ה-Postgres עם פסק זמן של 5 שניות, גילוי OIDC ובניית הלקוחות במעלה הזרם. אם אחד מאלה אינו נגיש או שגוי בהגדרתו, השער יוצא עם שגיאה במקום לשרת תעבורה במצב פגום.

אתחול מוצלח אינו מאמת את נתיב ההיקש (inference path), מכיוון שפרטי הגישה של המופע ב-Amazon Bedrock וב-Agent Platform של Google Cloud נפתרים רק בבקשה הראשונה, ולא בעת האתחול.

עקבו אחר stderr עבור רצף האתחול. שורות יומן משתמשות בפורמט [gateway] <timestamp> <level> <message>, אירועי ביקורת (audit events) הם שורת JSON יחידה עם שדה evt, ובאנר הפעלה, שהושמט להלן, מודפס בין שורות המיגרציה ושורות ההאזנה. מסד נתונים חדש מדפיס שורת migration N applied אחת לכל מיגרציית סכמה; מסד נתונים שכבר עבר מיגרציה אינו מדפיס דבר. עליכם לראות, לפי הסדר:

{"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}
[gateway] 2026-06-10T17:03:21.395Z info waiting for migration lock (another replica may be migrating; check pg_locks for key 6775156 if this persists)
[gateway] 2026-06-10T17:03:21.408Z info migration 1 applied
…
[gateway] 2026-06-10T17:03:21.431Z info migration 6 applied
[gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

אם האתחול יוצא לפני השורה claude gateway listening on, השורה האחרונה ב-stderr מציינת את הבעיה:

• מסד נתוני Postgres שאינו נגיש
• תפקיד Postgres ללא הרשאת DDL
• מסמך גילוי OIDC שאינו נגיש או אינו תקין
• הפרת סכמת תצורה עם נתיב השדה הבעייתי

תקנו את הבעיה והפעילו מחדש.

אם כבר יש לכם ingress המסיים TLS, דלגו על Compose והריצו את הקובץ הבינארי ישירות באמצעות claude gateway --config gateway.yaml. הגדירו את public_url למקור של ה-ingress ושייכו (bind) את listen לכתובת loopback או לכתובת פנימית בתוך האשכול.

5. אמתו את משטח האימות: שלוש בדיקות מאשרות שהשער יכול לאמת משתמש אמיתי לפני שאתם מוסרים אותו למפתח.

הדוגמאות משתמשות בכתובת ה-URL הציבורית של השער; עבור הגדרת Compose מקומית ללא ingress, החליפו ב-http://localhost:8080 בשתי הבדיקות הראשונות. הבדיקה השלישית פותחת את verification_uri_complete, שנבנה מתוך public_url, לכן עבור Compose מקומי הגדירו public_url: http://localhost:8080 בקובץ gateway.yaml, והוסיפו את http://localhost:8080/oauth/callback כ-redirect URI שני בלקוח ה-OAuth משלב 1, מכיוון שהשער בונה את ה-redirect_uri של ה-IdP מתוך public_url. קישור האימות ייפתח לאחר מכן בדפדפן המקומי שלכם.

ב-Windows PowerShell, הריצו curl.exe; הפקודה curl לבדה היא כינוי (alias) עבור Invoke-WebRequest ודוחה דגלים אלה.

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

curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

{
  "issuer": "https://claude-gateway.internal.example.com",
  "device_authorization_endpoint": "…/oauth/device_authorization",
  "token_endpoint": "…/oauth/token",
  "grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
}

התגובה כוללת שדות נוספים, כגון response_types_supported ו-scopes_supported.

שנית, בקשו אישור מכשיר (device authorization), המאשר שתהליך ההתחברות של המכשיר עובד וש-Postgres נגיש וניתן לכתיבה:

curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq

{
  "device_code": "…",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://claude-gateway.internal.example.com/device",
  "verification_uri_complete": "https://claude-gateway.internal.example.com/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

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

השתמשו בבדיקה הראשונה שנכשלת כדי לאתר את מקור הבעיה:

• הבדיקה הראשונה נכשלת: האתחול לא הושלם; בדקו את stderr
• הבדיקה השנייה נכשלת: Postgres אינו נגיש מהשער או שלתפקיד אין הרשאת כתיבה; בדקו את מחרוזת החיבור ואת ההרשאות (grants)
• הבדיקה השלישית אינה מגיעה ל-IdP: ודאו שה-redirect URI של ה-IdP תואם במדויק ל-https://<gateway>/oauth/callback
• הבדיקה השלישית מגיעה ל-IdP אך חוזרת עם שגיאה: קראו את יומן הביקורת של השער, המתעד כל דחיית אימות בצירוף הסיבה, כגון email domain not allowed

6. חברו מפתח: שלב אחרון זה מתבצע במחשב של המפתח, לא בשרת. הגדירו את forceLoginMethod ל-"gateway" ואת forceLoginGatewayUrl ל-public_url של השער שלכם בקובץ ההגדרות המנוהלות של אותה מכונה, לאחר מכן הריצו login/, לחצו על Enter במסך Cloud gateway, והשלימו את ההתחברות בדפדפן. הסעיף הגדרת כתובת ה-URL של השער להלן מכסה את הפצת שני המפתחות הללו לכל מחשב מפתח.

#חיבור מפתחים

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

ה-CLI דוגם טביעת אצבע (fingerprint) של תעודת ה-TLS leaf של השער בחיבור הראשון ומצמיד (pins) אותה לפי שם המארח. פרסמו את טביעת האצבע הצפויה מסוג SHA-256 לצד כתובת ה-URL של השער, כדי שלמפתחים יהיה למה להשוות. שורת הפקודה של login/ מציגה את 16 התווים הראשונים של טביעת האצבע כהקסדצימלי באותיות קטנות ללא נקודתיים. כדי להדפיס את טביעת האצבע המלאה בצורה זו מתוך קובץ התעודה, הריצו:

openssl x509 -noout -fingerprint -sha256 -in cert.pem | cut -d= -f2 | tr -d : | tr 'A-F' 'a-f'

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

לאחר ההתחברות, בורר המודלים מציג את המודלים ברשימת ההיתרים availableModels של המפתח, הגדרות מנוהלות מוחלות בעת ההפעלה ומתרעננות מדי שעה, וטלמטריה מנותבת לאספן שלכם. הפעלות (sessions) מתרעננות באופן שקט לפני פקיעת ttl_hours, ורענון שנכשל לאחר ביטול הקצאה ב-IdP דורש התחברות מחדש.

#הגדרת כתובת ה-URL של השער

שלושה מפתחות נכנסים לקובץ ההגדרות המנוהלות לפי מערכת הפעלה שאתם מפיצים באמצעות MDM או ישירות בדיסק. forceLoginMethod ו-forceLoginGatewayUrl פותחים את login/ ישירות במסך Cloud gateway כאשר כתובת ה-URL כבר מוזנת, והערך parentSettingsBehavior: "merge" מאפשר ל-Claude Desktop להעביר את רשימת היתרי היציאה (egress allowlist) של השער אל הפעלות ה-Claude Code שהוא מפעיל, כפי שמוסבר בסעיף העברת מדיניות להפעלות של Claude Desktop:

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

המפתח לוחץ על Enter כדי להתחבר. הודעת טביעת האצבע של ה-TLS בחיבור הראשון עדיין מופיעה.

מפתח אינו יכול להגדיר זאת ידנית. בבורר ההתחברות אין אפשרות של gateway, והמפתח forceLoginGatewayUrl זוכה להתעלמות בקובצי ההגדרות של המפתח עצמו. הגדרת forceLoginMethod לבדו, ללא כתובת URL, משאירה את המפתח עם ההודעה "Contact your IT administrator". מפתחות ההתחברות שייכים לקובץ שאתם דוחפים למחשבים, ולא לבלוק managed.policies[].cli של השער, אשר מגיע רק ללקוחות שכבר מחוברים.

#העברת מדיניות להפעלות של Claude Desktop

Claude Desktop מריץ את הכרטיסיות Cowork ו-Code, בתוספת כרטיסיית Chat כאשר אתם מפעילים אותה, על גבי הפעלות מוטמעות של Claude Code ושולח את בקשות המודל שלהן דרך השער. הוא מעביר מדיניות לכל אחת מאותן הפעלות, שנבנית מתוך התצורה שהשער מגיש לו בנתיב user/bootstrap/: רשימת היתרי המודלים, כלים מושבתים ורשימת היתרי יציאה הנגזרת מבלוק ה-cli של המדיניות התואמת, בתוספת שכבת ה-desktop (desktop overlay).

מפתחות cli אחרים, כגון hooks, משתני סביבה env, וכללי הרשאות מוגדרים כגון Bash(npm *), מגיעים רק ללקוחות שמתחברים דרך login/. Claude Desktop קורא את כתובת ה-URL של השער מתוך התצורה המנוהלת שלו ומתחבר בתהליך משלו, הנפרד מהמפתחות forceLoginMethod ו-forceLoginGatewayUrl שמתוארים בסעיף הגדרת כתובת ה-URL של השער.

הגדרות המועברות על ידי תהליך מפעיל נקראות הגדרות הורה (parent settings). Claude Code מתעלם מהגדרות הורה בכל מחשב שבו מוגדר מקור מנוהל שנפרס על ידי מנהל מערכת, אלא אם כן המקור שמספק את המדיניות מגדיר parentSettingsBehavior: "merge".

#אילו מכונות זקוקות להפעלה מפורשת זו (opt-in)

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

מכונות שבהן מפתחים מתחברים דרך login/ אינן זקוקות לכך; כל הפעלה של Claude Code מושכת את המדיניות שלה מהשער.

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

#הגדרת ה-opt-in

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

1. פרסו את ה-opt-in בקובץ ההגדרות המנוהלות: הקטע לעיל כבר כולל את parentSettingsBehavior: "merge", כך שהקובץ שאתם דוחפים למכונות נושא אותו.
2. שקפו את הקטע בכל מקור בעל עדיפות גבוהה יותר מהקובץ: Claude Code קורא את parentSettingsBehavior אך ורק מתוך המקור שנבחר. הוספת מפתח מדיניות כלשהו למקור מסוים עלולה להפוך מקור זה למקור הנבחר, לכן במקור צד-לקוח, שקפו את כל הקטע ולא רק את parentSettingsBehavior לבדו. הדף הגדרות מנוהלות בצד הלקוח מכסה ציי מחשבים המספקים מדיניות דרך Group Policy או פרופילי תצורה (configuration profiles). קובץ plist של managed-preferences ב-macOS או מדיניות HKLM ב-Windows מקבלים עדיפות על פני הקובץ managed-settings.json, וההגדרות המנוהלות המרוחקות של השער עצמו עולות בעדיפותן על שתיהן, לכן במכונות שמתחברות לשער, הגדירו את parentSettingsBehavior גם בבלוק ה-cli של מדיניות השער.
3. בדקו איזה מקור נבחר: במכונה שמריצה אך ורק את Claude Desktop, קראו לפונקציה resolveSettings() של Agent SDK וקראו את policyOrigin ברשומת managed ברשימת ה-sources שלה. הערך מציין את מקור צד-הלקוח הנבחר, plist, hklm, או file, שהוא המקור שחייב לשאת את הקטע. ההפעלות המוטמעות של Claude Desktop אינן מושכות את מדיניות השער, כך שבלוק ה-cli של השער לעולם אינו נחשב כמקור הנבחר עבורן.

#הגבלת הגדרות הורה

לאחר שפרסתם את parentSettingsBehavior: "merge", כל תהליך מארח שמפעיל את Claude Code יכול לספק הגדרות הורה, לא רק Claude Desktop אלא גם יישום Agent SDK או תוסף ל-IDE.

Claude Code מסנן הגדרות הורה מול רשימת היתרים של מפתחות מגבילים, אך חלק מהמפתחות המותרים יכולים להעניק גישה במקום להגביל אותה. אלא אם כן תגדירו את נעילות allowManaged*Only, כללי היתר (allow rules) של הרשאות ורשימות היתרים של sandbox שסופקו על ידי המארח עדיין יחולו. כללי ה-deny וה-ask של המדיניות שלכם נשארים בתוקף בכל מקרה; הם מוערכים לפני כל כלל היתר.

Claude Code מעביר רשומות sandbox.credentials שסופקו על ידי ההורה בצורה מופשטת:

• רשומות deny: מועברות רק עם ה-path או ה-name שלהן והמצב (mode).
• רשומות קבצים עם mode: mask: מועברות במתכונת sentinel-only בלבד, כמסכת קובץ שלם שבה injectHosts היא רשימה ריקה, כך שהפרוקסי לעולם אינו מחליף את הערך האמיתי עבור רשומה שסופקה על ידי הורה בשום פלטפורמה. כל שדות המיסוך המובנה מושמטים גם כן, כך שתבנית חילוץ שסופקה על ידי הורה אינה יכולה לדחוק מסכה מחמירה יותר שמקור אחר הגדיר עבור אותו נתיב.
• רשומות envVars עם mode: mask: אינן מועברות. deny היא ההגבלה היחידה שערוץ ההורה יכול לבטא באמצעות רשומות envVars.
• awsPairs ו-sigv4: מועברים במתכונת הגבלה בלבד (restriction-only). מתוך sigv4, נשמרים רק ערכי deny, והורה שמגדיר בלוק sigv4 בכלל נועל את כל שלוש צורות הבקשה, streaming, presigned ו-sigv4a, למצב deny. צמד awsPairs לעולם אינו מועבר בצורה שיכולה לחתום מחדש; צמד הנושא את שמו של אחד ממשתני ה-AWS המקובלים מוחלף ברשומה לא פעילה (inert) ששומרת על דיכוי הצימוד האוטומטי של AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY ו-AWS_SESSION_TOKEN.

#פריסת הנעילות

כדי להשאיר את הגדרות ההורה קרובות ככל האפשר למצב של הגבלה בלבד כפי שהמסנן תומך, הוסיפו את כל חמש נעילות allowManaged*Only, ואת רשימות ההיתרים שהן מנהלות, לאותם מקורות שבהם מוגדר ה-opt-in למיזוג:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge",
  "allowManagedPermissionRulesOnly": true,
  "allowManagedMcpServersOnly": true,
  "allowManagedHooksOnly": true,
  "allowedMcpServers": [{ "serverUrl": "https://mcp.internal.example.com/*" }],
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    },
    "filesystem": {
      "allowManagedReadPathsOnly": true,
      "denyRead": ["~/"],
      "allowRead": ["~/projects"]
    }
  }
}

מדיניות מערכת הפעלה, כגון מדיניות רישום ב-HKLM או plist של managed-preferences, מקבלת עדיפות על פני קובץ זה, לכן ספקו את כל הקטע דרכה במקום דרך הקובץ. ההגדרות המנוהלות המרוחקות של השער מקבלות עדיפות על פני מקורות של מדיניות מערכת הפעלה וקובץ, אך מגיעות רק ללקוחות מחוברים. שקפו את הנעילות, רשימות ההיתרים ואת ה-opt-in למיזוג בתוך בלוק ה-cli של המדיניות והשאירו קובץ זה פרוס, מכיוון שמכונות שלעולם אינן מתחברות, כולל כאלה שמריצות רק את Claude Desktop, מקבלות את המדיניות שלהן מהקובץ בלבד.

#התנהגות נעילות בין מקורות שונים

הגדרת נעילה אחת אינה מגבילה את האחרות; כל מפתח מתועד במדריך ההגדרות. ממקור מנהל מערכת שנמצא מתחת למקור המנצח, שתי נעילות ה-sandbox עדיין חלות, ו-allowManagedPermissionRulesOnly עדיין חוסם כללי היתר ו-additionalDirectories שסופקו על ידי ההורה. נעילות ה-hooks ושרתי ה-MCP, וההשפעה של allowManagedPermissionRulesOnly על הכללים של המפתח עצמו, דורשות את המקור המנצח כברירת מחדל; תחת ה-opt-in למיזוג של managedSourcesBehavior המתואר בכיצד Claude Code משלב מקורות מנוהלים, Claude Code מחיל את הערך המחמיר ביותר שכל מקור מגדיר עבור כל נעילה. בציי מחשבים המשתמשים ב-policyHelper, הנעילות נקראות מפלט ה-helper בלבד.

כל נעילה גורמת ל-Claude Code להתעלם מהרשומות של המפתח עצמו עבור אותה הגדרה, לכן כללו את רשימות ההיתרים של הארגון שלכם לצד הנעילות. נעילת דומיינים ברשת עם רשימת דומיינים מנוהלת ריקה חוסמת את כל תעבורת ה-sandbox היוצאת, ונעילת שרתי MCP ללא allowedMcpServers מנוהל או מסופק על ידי הורה טוענת כל שרת ש-deniedMcpServers אינו חוסם. רשומות allowRead רק מאפשרות מחדש נתיבים בתוך אזורי denyRead, לכן הצמידו אותן ל-denyRead מנוהל.

#הגדרות שהנעילות אינן מכסות

ארבע הגדרות המסופקות על ידי הורה עוברות את המסנן גם כאשר כל חמש הנעילות מוגדרות. תחת הגדרת ברירת המחדל שבה המקור הראשון מנצח (first-wins), ערך מנהל המערכת שחוסם את ערך ההורה הוא זה שנמצא במקור מנהל המערכת בעל העדיפות הגבוהה ביותר. תחת ה-opt-in למיזוג של managedSourcesBehavior, הדף כיצד Claude Code משלב מקורות מנוהלים מציין את הערך של איזה מקור חל במקום זאת.

• forceLoginOrgUUID: Claude Code מכבד ערך שסופק על ידי הורה כאשר מקור מנהל המערכת בעל העדיפות הגבוהה ביותר אינו מגדיר מזהה ארגון (org UUID). התחברות לשער אינה בודקת מפתח זה, ולכן הוא משמעותי רק עבור ציי מחשבים המשתמשים גם בהתחברויות ישירות מול Anthropic. מזהה ארגון במקור מנהל המערכת בעל העדיפות הגבוהה ביותר חוסם את הערך של ההורה והוא זה ש-Claude Code אוכף, לכן הגדירו את forceLoginOrgUUID שם.
• allowedMcpServers: Claude Code מכבד רשימת היתרים שסופקה על ידי הורה כאשר מקור מנהל המערכת בעל העדיפות הגבוהה ביותר אינו מגדיר כזו, והנעילה allowManagedMcpServersOnly אינה חוסמת אותה, מכיוון שהנעילה אוכפת את הרשימה שמנצחת כערך המנוהל, כולל רשימה שסופקה על ידי הורה כאשר מקור מנהל המערכת בעל העדיפות הגבוהה ביותר אינו מגדיר כזו. רשימה במקור מנהל המערכת בעל העדיפות הגבוהה ביותר חוסמת את זו של ההורה והיא הרשימה ש-Claude Code אוכף, לכן הגדירו את allowedMcpServers שם, לצד הנעילה. לפני גרסה v2.1.223, ערך עבור אחד משני המפתחות בכל מקור מנהל מערכת חסם את זה של ההורה.
• availableModels: Claude Code מכבד רשימת מודלים שסופקה על ידי הורה כאשר המקור המנוהל המנצח אינו מגדיר כזו. אם צי המחשבים שלכם מגביל מודלים, הגדירו את availableModels במקור המנצח.
• strictPluginOnlyCustomization: מפתח זה עובר את המסנן ללא קשר לנעילה כלשהי, והוא גורם ל-Claude Code להתעלם מהתאמות אישיות של המפתח עצמו, כולל hooks מגנים. שום נעילה אינה חוסמת אותו.

#חיבור Claude Desktop

Claude Desktop מתחבר לאותו שער דרך מפתח MDM שונה: הגדירו את bootstrapUrl בתצורה המנוהלת של Claude Desktop לערך <listen.public_url>/user/bootstrap, ואשרו את מדיניות המשתמש (opt-in) באמצעות מפתח desktop. הדף שכבת Claude Desktop (Claude Desktop overlay) מכסה את שני החלקים. דורש Claude Code בגרסה v2.1.203 ומעלה בשרת השער.

Claude Desktop מחבר את המפתח דרך ספק הזהויות של השער באותו שלב SSO בדפדפן, ולאחר מכן מושך את התצורה שלו מהשער במקום מ-Anthropic. הגישה למודלים והמדיניות פועלות לפי אותם כללים לפי קבוצה כמו ב-CLI. מפתח המשתמש הן ב-CLI והן ב-Claude Desktop מתחבר לכל אחד מהם בנפרד; הפעלת השער (gateway session) אינה משותפת ביניהם.

לאחר החיבור, Claude Desktop שולח בקשות מודל מכל כרטיסייה פעילה דרך השער. הוא מציג את הכרטיסיות Cowork ו-Code כברירת מחדל. כדי להפעיל גם את כרטיסיית Chat, הגדירו את chatTabEnabled ל-true בתצורה המנוהלת של Claude Desktop, או בבלוק ה-desktop של המדיניות בשער המריץ Claude Code בגרסה v2.1.227 ומעלה.

#תהליכי CI ומכונות מרוחקות

אין תהליך של אסימון שירות (service token) עבור צינורות אוטומטיים ללא השגחה. התחברות לשער מריצה תמיד את תהליך המכשיר בדפדפן (browser device flow), כך שמשימת CI ללא מפתח שיאשר את ההתחברות אינה יכולה להזדהות; הגדירו משימות אלו ישירות מול הספק שלכם.

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

תהליך המכשיר מפריד בין ה-CLI הבודק לבין הדפדפן המאשר, כך שמכונת פיתוח מרוחקת ללא תצוגה עדיין עובדת: המפתח מריץ login/ דרך SSH במכונה המרוחקת ופותח את קישור האימות בדפדפן במחשב הנייד שלו.

#מה נאכף על מפתחים

ערבויות אלו חלות על כל הפעלה שמחוברת דרך login/. ההפעלות המוטמעות ש-Claude Desktop מפעיל מקבלות את המדיניות שלהן כפי שמתואר בסעיף העברת מדיניות להפעלות של Claude Desktop, והסעיף של הטלמטריה מציין לאן הייצוא שלהן נשלח.

• גישה למודלים: בקשות למודלים שהמדיניות אינה מאשרת מחזירות שגיאת 400, ובורר model/ מסונן לרשימת ההיתרים availableModels של המדיניות. הגדירו enforceAvailableModels: true במדיניות כך שאפשרות Default תיפתר למודל בתוך availableModels במקום לברירת המחדל המובנית של Claude Code; בלעדיה, Default נשאר זמין לבחירה ונדחה בעת ביצוע הבקשה אם מודל זה אינו מאושר.
• יעד טלמטריה: בהפעלות המחוברות דרך login/, ה-CLI שולח את ייצויי ה-OTLP/HTTP שלו לשער ללא קשר לכל OTEL_EXPORTER_OTLP_ENDPOINT שמוגדר מקומית, והשער מעביר אותם ליעדים המוגדרים ב-telemetry.forward_to. בהפעלות המוטמעות ש-Claude Desktop מפעיל, ה-CLI שולח את הייצוא שלו ל-OTEL_EXPORTER_OTLP_ENDPOINT המוגדר. ה-CLI מצרף את אסימון הפעלת השער לייצוא זה רק כאשר נקודת קצה זו מצביעה על השער עצמו. אם לא מוגדר יעד עבור אות מסוים, השער מקבל אותו ומשליך אותו, כך שאם אתם כבר אוספים טלמטריה של Claude Code ישירות, הוסיפו את האספן שלכם כיעד ב-forward_to.
• פרטי גישה: אסימון השער הוא פרט הגישה היחיד של ההפעלה. ישנה התעלמות מ-ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, פרופילי Anthropic, ומכל התחברות קודמת ל-claude.ai בזמן שהמשתמש מחובר, כך שמפתחים אינם צריכים להתנתק מ-claude.ai תחילה.
• הגדרות מנוהלות: לא ניתן לעקוף מפתחות נעולים באופן מקומי. ה-CLI מחיל את המדיניות בעת ההפעלה ומחיל שינויים בכל בדיקה שעתית, למעט שינויים החלים רק בהפעלה הבאה.
• אתחול: הפעלות מחוברות יוצאות בעת ההפעלה עם שגיאה לאחר כ-10 שניות כאשר השער אינו נגיש, במקום להתחיל ללא ההגדרות שלהן.
• ביטול הקצאה: הפעלה שמשתמשה הושבת ב-IdP פוקעת בתוך ttl_hours כאשר הרענון הבא נכשל.

#מה הארגון יכול לראות

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

#זמינות ומגבלות

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

השער מעביר את ערכי anthropic-beta שה-CLI שולח לכל ספק במעלה הזרם, כך שמפעילים אינם צריכים לתחזק רשימת היתרים לגרסאות בטא. עבור Amazon Bedrock, שמתעלם מכותרת זו, השער מעביר את הערכים אל השדה anthropic_beta בגוף הבקשה; שאר הספקים במעלה הזרם מקבלים את הכותרת כפי שנשלחה.

#הצעדים הבאים

מדריך ההתחלה המהירה משאיר אתכם עם תצורה מינימלית הפועלת תחת Docker Compose. להמשך:

• הרחיבו את gateway.yaml מעבר לתצורה המינימלית, למשל כדי להוסיף RBAC לפי קבוצה, מעבר לגיבוי בין מספר ספקים, או יעדי טלמטריה. מדריך התצורה מכסה כל אפשרות.
• עברו מ-Compose לפריסת ייצור ב-Kubernetes או ב-Cloud Run, הגדירו את ה-IdP שלכם כראוי, ובחנו את מודל האבטחה. מדריך הפריסה והתפעול מכסה הגדרה לפי IdP, דרישות תמונת מכולה, בדיקות תקינות (health probes) ופתרון בעיות.
• הגדירו תקרות הוצאה למפתחים בודדים או לקבוצות כדי שעומס עבודה שיוצא משליטה לא יכלה את כל ההתחייבות שלכם. הדף מגבלות הוצאה מכסה את ה-API למנהלים וכיצד האכיפה עובדת.
• לדוגמה מעשית מלאה ב-AWS, עם ECS Fargate או EKS, Amazon RDS ו-Secrets Manager, ראו פריסה ב-AWS.
• לדוגמה מעשית מלאה ב-Google Cloud, עם Cloud Run, Cloud SQL ו-Secret Manager, ראו פריסה ב-Google Cloud.