📘 תיעוד 79

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

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

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

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

הערה:

• כדי לפרוס שער עבור הארגון שלך, ראה פריסת שער 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 עבור השער, אתה זקוק לקבל מצוות השער שלך:

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

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

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

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

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

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

#הגדרת כתובת ה-URL הבסיסית ופרטי האימות

הגדר את כתובת ה-URL הבסיסית של השער ואת משתנה פרטי האימות שבחרת לעיל כמשתני סביבה. הדוגמאות משתמשות ב-ANTHROPIC_AUTH_TOKEN; החלף אותו ב-ANTHROPIC_API_KEY אם זהו המשתנה שבחרת. תוכל להגדיר אותם במעטפת שלך (shell), דבר שתקף להפעלת מסוף אחת, או בקובץ הגדרות של 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 או מתפריט ההתחלה לא יראה אותם. כדי שהערכים יישמרו על פני מסופים חדשים, הוסף את אותן שורות לקובץ הפרופיל של המעטפת שלך, כגון ~/.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 בטעות לפרטי האימות שלך

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

בלוק ה-env נראה זהה בשני הקבצים:

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

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

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

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

ב-Bash או Zsh:

curl -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, או את ערך ה-"Authorization" בטבלת ה-hashtable ב-"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 כדי לאשר איזה מקור פרטי אימות פעיל. אם בעת ההפעלה מוצגת אזהרת התנגשות אימות המציינת שני מקורות, עיין בשורה הראשונה בטבלת פתרון הבעיות כדי לדעת על איזה מהם לוותר. כדי לנקות התחברות שמורה כך שיישארו רק פרטי האימות של השער, הרץ /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 והזן את כתובת ה-URL הבסיסית של השער שלך. הגדרה שהופצה על ידי מנהל מערכת מקבלת עדיפות והופכת טופס זה לקריאה בלבד

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

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

#GitHub Actions

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

עבור שער המשתמש ב-x-api-key, הגדר את כתובת ה-URL הבסיסית ב-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 של ה-workflow. ה-action דורש anthropic_api_key, CLAUDE_CODE_OAUTH_TOKEN, או איחוד זהויות של עומסי עבודה (workload identity federation) לפני שהוא מפעיל את Claude Code, והוא אינו קורא את ANTHROPIC_AUTH_TOKEN, ולכן הקלט נמצא שם רק כדי לעמוד בבדיקת ההפעלה הזו. משתנה ה-env הוא זה שמציב את המפתח בכותרת 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 שמגדירה את סביבת התהליך שנוצר, וה-SDKs של TypeScript ו-Python מתייחסים אליה באופן שונה:

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

ב-TypeScript:

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

ב-Python:

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

#Slack, רשת, ו-Remote Control

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

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

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

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

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

הגדרות אלו מכסות מקרים שמעבר לכתובת ה-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, או אם מנהל המערכת שלך הורה לך להגדיר אחד כזה. אם פרטי האימות שלך הם מחרוזת קבועה שאתה מגדיר פעם אחת, משתנה פרטי האימות הוא כל מה שאתה צריך ותוכל לדלג על סעיף זה.

המסייע הוא כל פקודת מעטפת שמדפיסה את פרטי האימות הנוכחיים לפלט הסטנדרטי. 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 מצרף פרטי אימות לבקשת טלמטריה או מדדי שימוש רק כאשר הבקשה מיועדת למארח שאליו שייכים פרטי האימות. כל עוד ANTHROPIC_BASE_URL מצביע על השער, Claude Code שולח את אירועי הטלמטריה שלו ל-Anthropic ללא פרטי האימות של השער שלך. כאשר גם משתנה פרטי אימות או apiKeyHelper פעילים, Claude Code אינו מדווח על מדדי שימוש ללוח הבקרה של הניתוחים ב-Console. לפני גרסה v2.1.246,‏ Claude Code יכול היה לצרף את פרטי האימות של השער לבקשות טלמטריה ומדדי שימוש המיועדות למארחי Anthropic; בקשות מודל תמיד עברו לשער עם פרטי האימות שהשער מצפה להם.

כדי לכבות תעבורה זו, הגדר את 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 לשער באמצעות משתנה כתובת URL בסיסית ייעודי לספק, במקום ANTHROPIC_BASE_URL. שערי Amazon Bedrock ו-Agent Platform של Google Cloud מקבלים את פורמט הבקשות המקורי של אותם ספקים; שערי Microsoft Foundry ו-Claude Platform on AWS מקבלים את פורמט Anthropic Messages ונבדלים רק במשתנה כתובת ה-URL הבסיסית שמגיע אליהם.

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

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

#Amazon Bedrock

ב-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"

#Agent Platform של Google Cloud

ב-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"

#Microsoft Foundry

שים את פרטי האימות של השער ב-ANTHROPIC_FOUNDRY_API_KEY; הם נשלחים לשער בכותרת x-api-key. שער שמצפה ל-bearer token יכול לקבל במקום זאת את 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. לפני גרסה v2.1.203, הגדרת CLAUDE_CODE_SKIP_FOUNDRY_AUTH ללא מפתח API הותירה את לקוח Microsoft Foundry ללא יכולת לשלוח בקשות.

ב-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 ID.

ב-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 עבור Agent Platform של Google Cloud; הבלוק של Microsoft Foundry מציג שורת דילוג על אימות רק אם הגדרת את CLAUDE_CODE_SKIP_FOUNDRY_AUTH. אם אתה מנתב בנוסף דרך פרוקסי ארגוני, שורת Proxy מציגה את כתובת ה-URL של הפרוקסי. אם שורת כתובת ה-URL הבסיסית חסרה, המשתנה לא הגיע להפעלה.

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

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

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

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

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