📘 תיעוד 117

חיבור Claude Code לשער LLM

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

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

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

[!NOTE]

• כדי לפרוס שער לארגון, ראו פריסת שער LLM
• למה ש-Claude Code שולח לשער, ראו את מדריך התאימות לשער

#בדיקה אם קיימת תצורה

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

1. הפעלת Claude Code

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

2. בדיקת לשונית Status

   אם Claude Code פתח סשן בלי להציג את מסך ההתחברות, הריצו /status, שנפתח בלשונית Status, ובדקו שתי שורות:

   • Anthropic base URL: השורה הזו מופיעה רק כשכתובת שער מוגדרת. אם היא לא שם, Claude Code לא מופנה לשער. הגדירו אותו בעצמכם בהמשך.
   • Auth token או API key: שורה שמציינת ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, או apiKeyHelper מאשרת שאישור שער פעיל. שורת Login method שמציינת חשבון claude.ai פירושה שהאישור לא הופץ. הגדירו אותו בעצמכם.

3. שליחת הודעת בדיקה

   סגרו את תפריט /status ושלחו כל פרומפט ב-Claude Code. תשובה רגילה מ-Claude, בלי שגיאה, מאשרת שחיבור השער עובד.

   אם שתי השורות בתפריט /status נראות תקינות אבל ההודעה ל-Claude נכשלת, ראו את טבלת פתרון הבעיות.

#הגדרת Claude Code בעצמכם

כדי להגדיר את Claude Code לשער בעצמכם, אתם צריכים מצוות השער:

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

הסעיפים הבאים מכסים את ההגדרה לפי הסדר:

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

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

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

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

#הגדרת כתובת הבסיס והאישור

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

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

#הגדרה כמשתני סביבה במעטפת

החליפו את הערכים באלה שצוות השער נתן לכם:

Bash או Zsh

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

PowerShell

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

ייצוא במעטפת חל רק על סשן הטרמינל הזה ועל תוכניות שהופעלו ממנו. עורך שהופעל מה-dock או מתפריט Start לא יראה אותם. כדי שהערכים יישמרו בטרמינלים חדשים, הוסיפו את אותן שורות לפרופיל המעטפת, כמו ~/.zshrc, ~/.bashrc, או $PROFILE של PowerShell.

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

#הגדרה בקובץ הגדרות

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

• ~/.claude/settings.json חל על כל הפרויקטים שלכם. ב-Windows הנתיב הוא %USERPROFILE%\.claude\settings.json
• .claude/settings.local.json חל על פרויקט אחד. Claude Code מוסיף אותו ל-gitignore הגלובלי כשהוא שומר שם הגדרה. אם אתם יוצרים אותו ידנית או אם Claude כותב אותו, הוסיפו אותו ל-gitignore בעצמכם קודם כדי שלא תבצעו בטעות commit לאישור

[!WARNING]

אל תשימו את האישור בקובץ .claude/settings.json של פרויקט. הקובץ הזה נכנס ל-commit ומשותף עם כל מי שמשכפל את המאגר.

בלוק env נראה אותו דבר בשני הקבצים:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

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

#אימות החיבור

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

Bash או Zsh

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

PowerShell

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

אם השער מצפה למפתחות בכותרת x-api-key, החליפו את כותרת Authorization ב-x-api-key: $ANTHROPIC_API_KEY בפקודת Bash, או את רשומת ה-hashtable "Authorization" ב-"x-api-key" = "$env:ANTHROPIC_API_KEY" בפקודת PowerShell.

תשובת JSON שמתחילה ב-{"id":"msg_ וכוללת שדה "content":[...] פירושה שהשער נגיש והאישור עובד. שגיאה שמציינת מודל לא מוכר עדיין מוכיחה שכתובת ה-URL והאישור עובדים, כי השער אימת את הבקשה לפני שדחה את שם המודל. אין צורך למצוא מודל שהשער מגיש עבור הבדיקה הזו. 401 פירושו שהאישור נדחה: אם ניחשתם את המשתנה, עברו למשתנה האחר וייצאו מחדש.

#אישור ב-Claude Code

הפעילו claude מאותה מעטפת כדי שהוא יירש את הייצוא, שלחו הודעה, והריצו /status.

בלשונית Status, שורת Anthropic base URL אמורה להציג את כתובת השער, וזה מאשר שהבקשות מנותבות לשם. אם השורה לא שם, המשתנה לא הגיע לסשן. שורת Auth token או API key שמציינת את המשתנה שהגדרתם מאשרת שאישור השער פעיל ולא התחברות claude.ai שמורה.

אם ההודעה נכשלת, או ש-/status לא מציג את כתובת ה-URL של השער, ראו את טבלת פתרון הבעיות בהמשך.

#איך משתנה האישור ממופה לכותרת

כל משתנה שולח את האישור בכותרת HTTP אחרת: ANTHROPIC_AUTH_TOKEN ב-Authorization: Bearer, ANTHROPIC_API_KEY ב-x-api-key, ו-apiKeyHelper בשתיהן. אישור במשתנה הלא נכון מגיע לשער בכותרת שהוא לא קורא, והבקשה נכשלת עם 401. אם בקשת האימות החזירה 401, עברו למשתנה האחר ונסו שוב.

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

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

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

#הגדרת כל משטח

ה-CLI קורא את משתני הסביבה וקבצי ההגדרות שלמעלה. המשטחים האחרים הם התוסף של VS Code, אפליקציית שולחן העבודה, GitHub Actions, ה-Agent SDK, ומשטחי הענן כמו Slack והווב. הסעיפים שלמטה מכסים אם ההגדרות האלה מגיעות לכל אחד מהם.

#התוסף של VS Code

הגדר את משתני השער עבור התוסף של VS Code ב-claudeCode.environmentVariables, בהגדרות המשתמש של VS Code עצמו שנפתחות עם הפקודה Preferences: Open User Settings (JSON). התוסף בודק אישורים מההגדרה הזו לפני ההפעלה, ולכן זה המקום האמין לאישור השער. ערכים ב-~/.claude/settings.json מגיעים לתהליך שנוצר אבל לא לבדיקת ההתחברות של התוסף עצמו.

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}

#אפליקציית שולחן העבודה

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

• מופץ על ידי מנהל: אם הארגון שלך פרס את ההגדרה, אפליקציית שולחן העבודה מנתבת דרך השער בלי הגדרה מצדך
• מוגדר מקומית: במכשירים בלי הגדרה שהופצה על ידי מנהל, פתח Help → Troubleshooting → Enable Developer Mode, וזה מפעיל מחדש את האפליקציה עם תפריט Developer. אחר כך פתח Developer → Configure Third-Party Inference והזן את כתובת הבסיס של השער. הגדרה שהופצה על ידי מנהל גוברת והופכת את הטופס הזה לקריאה בלבד

כשהגדרת השער פעילה, בורר הסביבות לא מציע סביבות ענן שמתארחות אצל Anthropic, ו-Remote Control לא זמין.

הפעלות SSH נמצאות בבטא עם הגדרת שער ודורשות Claude Desktop v1.40609.0 או חדש יותר. לפני החיבור, בדוק את רשימת המארחים המותרים ואת הכתובת של השער:

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

ראה הפעלות SSH מרוחקות ב-Claude Desktop על 3P. אפשר גם להריץ את ה-CLI על המארח המרוחק כש-ANTHROPIC_BASE_URL ואישור השער מוגדרים שם.

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

#GitHub Actions

Claude Code GitHub Actions קורא את ANTHROPIC_BASE_URL ואת ANTHROPIC_CUSTOM_HEADERS מבלוק env של זרימת העבודה. העבר את האישור כקלט anthropic_api_key של ה-action. ה-action מגדיר אותו כ-ANTHROPIC_API_KEY, ולכן הוא מגיע לשער בכותרת x-api-key.

עבור שער x-api-key, הגדר את כתובת הבסיס ב-env והעבר את מפתח השער כקלט:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

עבור שער bearer-token, העבר את אותו סוד פעמיים: כקלט anthropic_api_key וכ-ANTHROPIC_AUTH_TOKEN בבלוק env של זרימת העבודה. ה-action דורש anthropic_api_key, CLAUDE_CODE_OAUTH_TOKEN, או איחוד זהות של עומס עבודה לפני שהוא מפעיל את Claude Code, והוא לא קורא את ANTHROPIC_AUTH_TOKEN, ולכן הקלט נמצא שם רק כדי לספק את בדיקת ההפעלה הזו. משתנה הסביבה הוא מה שמכניס את המפתח לכותרת Authorization שהשער קורא. העותק ב-x-api-key מתעלמים ממנו:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

לאפשרויות האימות האחרות של ה-action, כולל CLAUDE_CODE_OAUTH_TOKEN ואיחוד זהות של עומס עבודה, ראה Claude Code GitHub Actions ואת ה-README של ה-action.

#Agent SDK

ל-Agent SDK אין אפשרויות ייעודיות לשער. הוא מעביר משתני סביבה לתהליך Claude Code שהוא יוצר. כל SDK מקבל אפשרות env שמגדירה את הסביבה של התהליך שנוצר, וה-SDK של TypeScript ושל Python מטפלים בה אחרת:

• TypeScript: התהליך שנוצר יורש את סביבת האב כברירת מחדל, אבל הגדרת options.env מחליפה את הסביבה לגמרי. פרוס את process.env לתוכה כדי לשמור את משתני השער שלך.
• Python: ClaudeAgentOptions(env=...) מתמזג מעל הסביבה בירושה, ולכן משתני שער שהוגדרו בתהליך האב עוברים בלי פריסה.

const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
      ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
    },
  },
})

options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
        "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
    }
)

#Slack, הפעלות ענן, ו-Remote Control

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

Remote Control והכתבה קולית שניהם נשענים על זהות claude.ai: Remote Control כדי לשייך הפעלה חיה לחשבון שלך, והכתבה קולית כדי להגיע לנקודת הקצה של התמלול ב-claude.ai. הם לא זמינים בזמן ש-ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, או apiKeyHelper פעילים. Remote Control גם מושבת בזמן ש-ANTHROPIC_BASE_URL מצביע על מארח שאינו של Anthropic, ולכן התחברות עם claude.ai לא מספיקה בפני עצמה.

כדי לשחזר כל אחת מהיכולות, התחבר עם claude.ai ובטל את משתני השער שהיכולת בודקת. הסעיף Remote Control של claude doctor מציין מה חוסם כרגע את Remote Control.

• הכתבה קולית: בטל את אישור השער
• Remote Control: בטל את אישור השער ואת ANTHROPIC_BASE_URL

#הגדרות נוספות

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

#שליחת כותרות נוספות

חלק מהשערים מנתבים או מתייגים בקשות באמצעות כותרת מותאמת בנוסף לפרטי ההתחברות, לדוגמה מזהה דייר או מפתח ניתוב. כדי לשלוח כותרת כזאת, הגדר את ANTHROPIC_CUSTOM_HEADERS עם זוג Name: Value אחד בכל שורה. הדוגמה הבאה מוסיפה כותרת ניתוב בשם X-Org-Route:

Bash או Zsh

export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

PowerShell

$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"

אפשר גם להגדיר את ANTHROPIC_CUSTOM_HEADERS בבלוק env של קובץ הגדרות. השתמש ב-\n בין הזוגות שם, כי מחרוזות JSON לא יכולות להימשך על פני כמה שורות:

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: example"
  }
}

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

#הוספת מודלים של השער לבורר המודלים

כשגילוי מודלים מופעל, Claude Code שואל את השער לגבי רשימת המודלים שלו בעת ההפעלה ומוסיף את השמות האלה לבורר /model לצד הרשומות המובנות. אם אתה או מנהל המערכת הגדרתם replaceBuiltInOptions בסידור modelPicker, Claude Code מסתיר גם את השמות שהתגלו. הוא שומר שורה עבור המודל שהסשן כבר משתמש בו.

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

כדי להפעיל, הגדר CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 במעטפת או בבלוק env של ~/.claude/settings.json.

מודלים שהתגלו מופיעים כרשומות /model נוספות. כל רשומה מציגה את התיאור שהשער מספק למודל, או From gateway כשהוא לא מספק תיאור.

כדי לוודא שהגילוי רץ, הפעל claude --debug וחפש את שורות [gatewayDiscovery] ביומן ניפוי השגיאות ב-~/.claude/debug/<session-id>.txt. בפעם הראשונה שהגילוי מצליח, Claude Code רושם כמה מודלים הוא שמר במטמון, והוא רושם שוב רק כשרשימת השער משתנה. גם 404, פסק זמן או הפניה מופיעים שם. למתי הגילוי רץ, מה הוא מסנן, ופורמט התגובה שהשערים מגישים, ראה את הפניה לגילוי מודלים.

#החלפת פרטי התחברות עם apiKeyHelper

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

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

העוזר הוא כל פקודת מעטפת שמדפיסה את פרטי ההתחברות הנוכחיים ל-stdout. Claude Code מריץ אותו דרך מעטפת המערכת, כך שב-Windows הוא יכול להיות קובץ הרצה או הפעלה של PowerShell. דאג שהפקודה תדפיס רק את פרטי ההתחברות. ב-Claude Code גרסה v2.1.227 ואילך, באנר או שורת יומן שמודפסים לצד המפתח גורמים לכשל של העוזר. כתוב את הסקריפט, הפוך אותו לבר הרצה, והפנה אליו מ-apiKeyHelper בקובץ ההגדרות:

Bash או Zsh

לדוגמה, סקריפט שקורא מכספת:

#!/bin/bash
vault kv get -field=api_key secret/llm-gateway/claude-code

הפנה לנתיב שלו ב-~/.claude/settings.json:

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

PowerShell

לדוגמה, סקריפט שקורא מכספת:

vault kv get -field=api_key secret/llm-gateway/claude-code

הפנה להפעלת PowerShell ב-%USERPROFILE%\.claude\settings.json, עם תווי בריחה ללוכסנים ההפוכים במחרוזת ה-JSON:

{
  "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
}

Claude Code שומר את פלט העוזר במטמון למשך חמש דקות כברירת מחדל ומריץ את העוזר מחדש אחרי שתוקף המטמון חולף. כדי לשנות את משך החיים, הגדר את CLAUDE_CODE_API_KEY_HELPER_TTL_MS באלפיות שנייה, לדוגמה CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000 ל-15 דקות.

ראה apiKeyHelper למקרים הנוספים שבהם Claude Code מריץ מחדש את העוזר.

הערך של העוזר נשלח גם בכותרת Authorization וגם בכותרת x-api-key, כך שהוא עובד לפי הכותרת שהשער שלך קורא.

#כיבוי תעבורה מחוץ לנתיב השער

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

כדי לכבות את התעבורה הזאת, הגדר CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 לצד משתני השער, באותם ייצואי מעטפת או בבלוק env של קובץ ההגדרות:

Bash או Zsh

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

PowerShell

$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"

להגדרת המשתנה יש ההשפעות והמגבלות האלה:

• הוא משבית עדכונים אוטומטיים, אז תכנן נתיב עדכון אחר, כמו מנהל החבילות או הפצה מנוהלת.
• הוא מדכא את בדיקת הזמינות של מצב מהיר. אלא אם בדיקה קודמת כבר הפעילה מצב מהיר במחשב, /fast מדווח שמצב מהיר אינו זמין.
• הוא לא משפיע על גילוי מודלים של השער, ששואל רק את השער שלך. לפני v2.1.257, המשתנה גם עצר את רענון הגילוי, כך שהבורר שמר את הרשימה שנשמרה קודם במטמון.
• בדיקת בטיחות הדומיין של הכלי WebFetch לא מושפעת ועדיין קוראת ל-api.anthropic.com. כבה אותה בנפרד עם skipWebFetchPreflight: true בהגדרות אם הרשת שלך חוסמת את המארח הזה.
• לכל זרם טלמטריה ולמשתנה ששולט בו, ראה שירותי טלמטריה.

#ניתוב לספק ענן דרך שער

ההגדרות האלה מכוונות את Claude Code לשער דרך משתנה כתובת בסיס ייעודי לספק במקום ANTHROPIC_BASE_URL. שערי Amazon Bedrock ו-Google Cloud's Agent Platform מקבלים את פורמטי הבקשה המקוריים של הספקים האלה. שערי Microsoft Foundry ו-Claude Platform on AWS מקבלים את פורמט Anthropic Messages. בנתיבי Amazon Bedrock ו-Google Cloud's Agent Platform, Claude Code גם מגביל את כותרות הבטא ושדות הבקשה שהוא שולח לקבוצה שהספק מקבל. למה שהשער שלך מקבל בכל נתיב, ראה את מדריך התאימות של השער.

השתמש באחד רק אם צוות השער ציין במפורש את Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, או Claude Platform on AWS. אם בקשת האימות שלמעלה החזירה JSON, אפשר לדלג על הסעיף הזה.

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

• Amazon Bedrock, Google Cloud's Agent Platform, או Claude Platform on AWS: הוסף ANTHROPIC_AUTH_TOKEN אחרי הבלוק. Claude Code שולח אותו לשער ככותרת Authorization: Bearer. לפרטי התחברות בסכמה או בכותרת אחרת, השתמש ב-ANTHROPIC_CUSTOM_HEADERS במקום. השאר את משתנה דילוג האימות מוגדר בכל מקרה, כי בלעדיו Claude Code מסיר כל כותרת Authorization ש-ANTHROPIC_AUTH_TOKEN, apiKeyHelper, או ANTHROPIC_CUSTOM_HEADERS היו מוסיפים.
• Microsoft Foundry: השתמש ב-ANTHROPIC_FOUNDRY_API_KEY כפי שהבלוק שלו מראה

#Amazon Bedrock

השאר את AWS_BEARER_TOKEN_BEDROCK לא מוגדר כשהשער מנפיק פרטי התחברות משלו. אם מגדירים אותו, Claude Code שולח את מפתח ה-API של Amazon Bedrock הזה ככותרת Authorization במקום אסימון השער, גם כש-CLAUDE_CODE_SKIP_BEDROCK_AUTH מוגדר.

Bash או Zsh

export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

PowerShell

$env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
$env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
$env:CLAUDE_CODE_USE_BEDROCK = "1"

#Google Cloud's Agent Platform

החלף את מזהה הפרויקט והאזור בערכים שלך. Claude Code כולל את שניהם בנתיב של כל בקשה שהוא שולח לשער:

Bash או Zsh

export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

PowerShell

$env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
$env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
$env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
$env:CLAUDE_CODE_USE_VERTEX = "1"
$env:CLOUD_ML_REGION = "us-east5"

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

• אזורים לפי מודל: אם השער מגיש חלק מהמודלים מאזור שאינו CLOUD_ML_REGION, הגדר את משתנה VERTEX_REGION_CLAUDE_* המתאים לכל אחד, לדוגמה VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1. הפניה למשתני הסביבה מפרטת את השמות המדויקים.
• גרסאות מודל: נעץ את ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ו-ANTHROPIC_DEFAULT_HAIKU_MODEL כמו בנעיצת גרסאות מודל. הגדרת ANTHROPIC_DEFAULT_HAIKU_MODEL גם מעבירה משימות רקע כמו כותרות סשן למודל הזה, והסעיף הזה מסביר איזה מודל מריץ אותן אחרת.
• יכולות מודל: אם נועצים מזהה מודל שגרסת Claude Code שלך לא מזהה, תכונות כמו רמות מאמץ או חשיבה מורחבת יכולות להישאר מושבתות עליו. הצהר מה המודל תומך בו עם ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES והמקבילים של Sonnet ו-Haiku.

#Microsoft Foundry

שים את פרטי ההתחברות של השער ב-ANTHROPIC_FOUNDRY_API_KEY. הם נשלחים לשער ככותרת x-api-key. שער שמצפה לאסימון bearer יכול לקבל במקום זאת את ANTHROPIC_FOUNDRY_AUTH_TOKEN. Claude Code שולח את הערך הזה ככותרת Authorization: Bearer, והוא מקבל עדיפות על פני ANTHROPIC_FOUNDRY_API_KEY כששניהם מוגדרים. נדרש Claude Code v2.1.203 ואילך.

לשער שמזריק כותרת Authorization משלו, הגדר CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1 והשאר את שני משתני פרטי ההתחברות לא מוגדרים. Claude Code אז שולח בקשות בלי פרטי התחברות של Azure ושומר את כותרת Authorization שאתה מספק, לדוגמה דרך ANTHROPIC_CUSTOM_HEADERS.

Bash או Zsh

export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
export CLAUDE_CODE_USE_FOUNDRY=1

PowerShell

$env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
$env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
$env:CLAUDE_CODE_USE_FOUNDRY = "1"

#Claude Platform on AWS

ראה Claude Platform on AWS למזהה ה-workspace.

Bash או Zsh

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

PowerShell

$env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
$env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
$env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
$env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"

#אישור נתיב הספק

הפעל claude מהמעטפת שבה הגדרת את הבלוק והרץ /status. עם בלוק Amazon Bedrock, הכרטיסייה Status מציגה שורות כאלה:

API provider: Amazon Bedrock
Bedrock base URL: https://llm-gateway.example.com/bedrock
AWS auth skipped

הבלוקים האחרים מייצרים את אותן שורות תחת שמות הספק שלהם, לדוגמה Vertex base URL ו-GCP auth skipped עבור Google Cloud's Agent Platform. בלוק Microsoft Foundry מציג שורת דילוג אימות רק אם הגדרת CLAUDE_CODE_SKIP_FOUNDRY_AUTH. אם מנתבים גם דרך פרוקסי ארגוני, שורת Proxy מציגה את כתובת הפרוקסי. אם שורת כתובת הבסיס חסרה, המשתנה לא הגיע לסשן.

#פתרון שגיאות של שער

אלה השגיאות הנפוצות ביותר בהרצת Claude Code דרך שער, עם הסיבה בצד השער והתיקון:

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

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

• סקירת שערי LLM: מהו שער ואיך הוא פועל מול מנויים של claude.ai
• פריסת שער LLM לארגון: רשימת הבדיקה למנהלים לפריסה ולהפצה של הגדרת השער
• מדריך תאימות שער: מה Claude Code שולח לשער, כולל הכותרות והשדות שהשער חייב להעביר
• הגדרות: איפה נמצאים קובצי ההגדרות ואיך נקרא בלוק env
• אימות: איך משתני אישורים, apiKeyHelper והתחברות OAuth פועלים יחד