📘 תיעוד 69

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

הגדר את Claude Code עבור סביבות ארגוניות עם שרתי פרוקסי, רשויות אישורים מותאמות אישית (CA), ואימות Transport Layer Security הדדי (mTLS).

Claude Code תומך במגוון הגדרות רשת ואבטחה ארגוניות באמצעות משתני סביבה. זה כולל ניתוב תעבורה דרך שרתי פרוקסי ארגוניים, מתן אמון ברשויות אישורים מותאמות אישית (Certificate Authorities, או CA), ואימות באמצעות תעודות Transport Layer Security הדדי (mTLS) לשיפור האבטחה.

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

הערה: כל משתני הסביבה המוצגים בדף זה ניתנים להגדרה גם ב-settings.json.

#הגדרת פרוקסי

#משתני סביבה

Claude Code מכבד משתני סביבה סטנדרטיים של פרוקסי. בהפעלות של Claude Desktop שבהן היישום מנהל את החיבור לספק, Claude Code קורא אותם רק מתוך הגדרות מנוהלות ומתוך ~/.claude/settings.json: ראה אימות mTLS עבור כללי הטווח.

# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP proxy (if HTTPS not available)
export HTTP_PROXY=http://proxy.example.com:8080

# Bypass proxy for specific requests - space-separated format
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# Bypass proxy for specific requests - comma-separated format
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# Bypass proxy for all requests
export NO_PROXY="*"

גרסאות באותיות קטנות פועלות גם כן, ו-Claude Code משתמש במשתנה הראשון שמוגדר לפי הסדר: https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY.

Claude Code לעולם אינו שולח את חיבורי ה-WebSocket שלו אל localhost, ::1, או 127.0.0.0/8 דרך הפרוקסי, כך שאין צורך ברשומת loopback ב-NO_PROXY עבורם.

הערה: Claude Code אינו תומך בפרוקסי מסוג SOCKS.

#אימות בסיסי

אם הפרוקסי שלך דורש אימות בסיסי (basic authentication), כלול את פרטי הגישה בכתובת ה-URL של הפרוקסי:

export HTTPS_PROXY=http://username:[email protected]:8080

אזהרה: הימנע מהטמעת סיסמאות קבועות בקוד (hardcoding) בסקריפטים. השתמש במשתני סביבה או באחסון פרטי גישה מאובטח במקום זאת.

טיפ: עבור שרתי פרוקסי הדורשים אימות מתקדם (NTLM, Kerberos וכו'), שקול להשתמש בשירות LLM Gateway שתומך בשיטת האימות שלך.

#מאגר אישורי CA

כברירת מחדל, Claude Code נותן אמון הן באישורי ה-Mozilla CA המצורפים שלו והן במאגר האישורים של מערכת ההפעלה שלך. קריאת מאגר מערכת ההפעלה דורשת סביבת ריצה הכוללת את tls.getCACertificates: למתקין המקורי (native installer) תמיד יש תכונה זו, והתקנות דרך npm דורשות את Node 22.15 ומעלה. בגרסאות Node ישנות יותר, רק הערכה המצורפת ו-NODE_EXTRA_CA_CERTS חלים. שרתי פרוקסי ארגוניים לבדיקת TLS פועלים ללא הגדרה נוספת כאשר אישור השורש שלהם מותקן במאגר האמון של מערכת ההפעלה וסביבת הריצה מסוגלת לקרוא אותו.

CLAUDE_CODE_CERT_STORE מקבל רשימת מקורות מופרדת בפסיקים. הערכים המוכרים הם bundled עבור ערכת אישורי ה-Mozilla CA המסופקת עם Claude Code, ו-system עבור מאגר האמון של מערכת ההפעלה. ברירת המחדל היא bundled,system.

כדי לתת אמון רק בערכת ה-Mozilla CA המצורפת:

export CLAUDE_CODE_CERT_STORE=bundled

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

export CLAUDE_CODE_CERT_STORE=system

הערה: ל-CLAUDE_CODE_CERT_STORE אין מפתח סכמה ייעודי ב-settings.json. הגדר אותו דרך בלוק ה-env ב-~/.claude/settings.json או ישירות בסביבת התהליך.

#אישורי CA מותאמים אישית

אם הסביבה הארגונית שלך משתמשת ב-CA מותאם אישית, הגדר את Claude Code לתת בו אמון ישירות:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

#אימות mTLS

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

# Client certificate for authentication
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

# Client private key
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

# Optional: Passphrase for encrypted private key
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

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

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

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

• עיתוי: Claude Code אינו עושה דבר ברגע שבו אתה מחליף את הקבצים. הוא מציג את הצמד החדש בניסיון החוזר לאחר כשל שעומד בתנאים, או בבקשה הבאה לאחר שהוא מחיל הגדרות, המוקדם מביניהם.
• דחיות שער (Gateway rejections): Claude Code קורא מחדש כאשר השער שלך מאפס את החיבור או דוחה את לחיצת היד של TLS לאחר שהפסיק לקבל את הצמד הישן. הוא אינו קורא מחדש כאשר השער משלים את לחיצת היד ומשיב עם שגיאת HTTP. במקרה זה, Claude Code טוען את הצמד החדש כאשר הוא מחיל הגדרות בפעם הבאה או כאשר אתה מפעיל אותו מחדש.
• סבבי החלפה שנכתבו חלקית: כאשר Claude Code קורא מחדש בזמן שסבב ההחלפה נמצא באמצע הכתיבה, כגון קריאת תעודה ומפתח שאינם תואמים זה לזה, הוא שומר על הצמד הקודם וקורא מחדש בכשל הבא.
• מייצאי טלמטריה של OTLP: Claude Code שומר על התעודה שנטענה על ידי ה-מייצאים בשימוש הראשון, לכן הפעל מחדש את Claude Code כדי שתעודה שהוחלפה תגיע לאוסף הטלמטריה שלך.
• כיבוי הטעינה מחדש: הגדר את CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1 כדי לכבות את הקריאה מחדש בעת שגיאת חיבור. במקרה זה Claude Code יקלוט קבצים שהוחלפו רק כאשר יחיל הגדרות בפעם הבאה או בהפעלה הבאה.

כדי לוודא ש-Claude Code קלט סבב החלפה, הפעל את ההפעלה עם יומן ניפוי שגיאות וחפש ביומן את השורה: Stale connection: reloaded rotated mTLS client material. Claude Code אינו רושם שורה זו ביומן כאשר הוא קולט את ההחלפה בעת החלת הגדרות, ולכן היעדר השורה לבדו אינו מעיד על כך שסבב ההחלפה נכשל.

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

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

• CLAUDE_CODE_CLIENT_CERT
• CLAUDE_CODE_CLIENT_KEY
• CLAUDE_CODE_CLIENT_KEY_PASSPHRASE
• NODE_EXTRA_CA_CERTS
• NODE_TLS_REJECT_UNAUTHORIZED
• CLAUDE_CODE_OAUTH_SCOPES

Claude Code מציין כל מפתח שזכה להתעלמות ביומן הניפוי של ההפעלה.

בהפעלות של Claude Desktop שבהן היישום מנהל את החיבור לספק, כגון כרטיסיית Code עם ספק צד שלישי והפעלות Cowork, Claude Code קורא משתנים אלה ואת משתני הפרוקסי HTTP_PROXY, HTTPS_PROXY ו-NO_PROXY רק מתוך הגדרות מנוהלות ומתוך ~/.claude/settings.json: הוא מתעלם מהם בקובצי הגדרות של המאגר עצמו, כך שמאגר שנמשך לא יכול לנתב מחדש את נתיב ה-TLS או הפרוקסי של הפעלה שפרטי הגישה שלה מגיעים מהיישום. בהפעלת כרטיסיית Code מקומית, ב-SSH או ב-WSL המחוברת דרך claude.ai, היישום אינו מנהל את החיבור, ו-Claude Code קורא משתנים אלה מכל טווח הגדרות, כמו בכל הפעלת מסוף; הפעלות ענן פועלות לפי כללי הפעלות הענן שלעיל בכל מקום שבו אתה מפעיל אותן. לפני גרסה v2.1.217, Claude Code התעלם ממשתנים אלה בכל קובץ הגדרות כאשר היישום ניהל את החיבור.

#אימות ההגדרות שלך

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

כדי לוודא שההגדרות שלך נטענו לפני שאתה שולח בקשה, הפעל את Claude Code עם יומן ניפוי שגיאות (debug logging):

claude --debug

פלט הניפוי נשלח אל ~/.claude/debug/<session-id>.txt במקום למסוף, או לנתיב שקבעת באמצעות --debug-file <path>. ביומן, חפש את השורות המאשרות שכל קובץ נטען:

CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (/etc/ssl/certs/corp-ca.pem)
mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

אם Claude Code אינו יכול לקרוא את אחד הקבצים הללו, היומן מציג שורת Failed to read או Failed to load עם הסיבה במקום זאת.

תוכל גם להריץ /status בהפעלה אינטראקטיבית ולבדוק שורות אלה:

• Proxy: מציג את כתובת ה-URL הפעילה של הפרוקסי, ומסמן ערך שאינו יכול לנתח כלא תקין ושזכה להתעלמות.
• mTLS client cert ו-mTLS client key: מופיעים רק כאשר הקבצים נטענו, לכן שורה חסרה פירושה שהטעינה נכשלה וביומן הניפוי מופיעה הסיבה.
• Additional CA cert(s): מציג את נתיב NODE_EXTRA_CA_CERTS מבלי לבדוק שהקובץ נטען, לכן אמת זאת ביומן הניפוי.

#החלת הגדרות רשת על סוכני רקע

סוכני רקע אינם רצים בתוך המסוף ששיגר אותם. תהליך מפקח (supervisor) ייעודי לכל משתמש מופעל לפי דרישה, ממשיך להתקיים לאחר סגירת המעטפת שלך, ומארח כל הפעלה של claude agents, --bg ו-/background. ראה כיצד מתארחות הפעלות רקע. הדבר משנה את האופן שבו ההגדרות בדף זה מגיעות להפעלות הללו.

#הגדרת משתני רשת בהגדרות, לא במעטפת

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

הגדר את אותם משתנים בבלוק ה-env של ~/.claude/settings.json או ב-הגדרות מנוהלות במקום זאת. כל משתנה בדף זה ניתן להגדרה שם, והגדרות הן התצורה היחידה שמגיעה לכל הפעלת רקע בכל מכונה.

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

ארגונים מסוימים דורשים שכל תהליך של Claude Code יופעל דרך משגר ארגוני (corporate launcher) שמחיל בידוד (sandboxing), בקרות רשת או הזרקת פרטי גישה. המפקח ותהליכי העבודה (workers) שלו מפעילים את Claude Code מנתיב קבוע ולא על ידי חיפוש של claude ב-PATH, כך שכל סוכן רקע עוקף מעטפת (wrapper) שהוצבה מוקדם יותר ב-PATH.

הגדר את ההגדרה processWrapper כדי להוסיף כקידומת את המשגר שלך למפקח, לתהליכי העבודה שלו ולשאר תהליכי הרקע המפורטים תחת מה שהמשגר מכסה. משתנה הסביבה המקביל CLAUDE_CODE_PROCESS_WRAPPER מקבל עדיפות כאשר שניהם מוגדרים, והוא כפוף לאותו כלל: העבר אותו דרך הגדרות מנוהלות או ~/.claude/settings.json, ולא דרך ייצוא במעטפת. הפעלת Claude Code מאחורי משגר ארגוני מכסה את החוזה שהמשגר חייב לעמוד בו, למה הוא מגיע ולמה לא, וכיצד לפרוס אותו.

הערה: מפקח שכבר פועל שומר על תצורת ההפעלה שאיתה התחיל. לאחר פריסת הגדרת המשגר, הרץ את claude daemon stop --any כדי שהפקודה הבאה של claude agents או --bg תפעיל מפקח שמכבד אותה. שירות מותקן מקבל claude daemon stop ללא --any.

#מנגנוני מעקב (watchdogs) אחר חוסר פעילות בהזרמה

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

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

• CLAUDE_ENABLE_STREAM_WATCHDOG ו-CLAUDE_ENABLE_BYTE_WATCHDOG כופים הפעלה של המעקב המתאים עם 1 או כיבוי עם 0, במסגרת החיבורים המפורטים בטבלה; אף משתנה אינו מרחיב מעקב לסוג חיבור שאינו מכוסה על ידו. CLAUDE_ENABLE_BYTE_WATCHDOG המוגדר ל-0 מכבה גם את המועד האחרון לבייט ראשון.
• CLAUDE_STREAM_IDLE_TIMEOUT_MS מגדיר את הזמן הקצוב של שני מנגנוני המעקב. Claude Code מעלה ערכים הנמוכים מ-5 דקות ל-5 דקות, ומגביל את הערך ל-30 דקות לכל היותר עבור המעקב ברמת הבייטים.
• CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS מגדיר את הזמן הקצוב של המעקב ברמת הבייטים מבלי לשנות את זה של המעקב ברמת האירועים, מוגבל לטווח שבין 10 שניות ל-30 דקות, וקודם ל-CLAUDE_STREAM_IDLE_TIMEOUT_MS עבור מעקב זה.
• CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS מגדיר ישירות את המועד האחרון לבייט ראשון. השארתו ללא הגדרה גורמת ל-Claude Code להשתמש בזמן הקצוב של המעקב ברמת הבייטים, כך ש-CLAUDE_STREAM_IDLE_TIMEOUT_MS ו-CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS משנים גם הם מועד אחרון זה. לגבי הגבלות הטווח, תוספת הזמן להעלאה, תקרת API_TIMEOUT_MS, ומשך ההמתנה של הניסיון החוזר לאחר ביטול עקב חוסר תגובה, ראה אין תגובה מה-API.
• הגדרת API_FORCE_IDLE_TIMEOUT ל-0 מכבה את הזמן הקצוב לחוסר פעילות של גוף התגובה, והגדרתו ל-1 מפעילה אותו עבור כל ספק. מנגנוני המעקב פועלים באופן בלתי תלוי בו, ולכן כדי לאפשר להזרמה להשתהות זמן רב יותר מהספים שלהם, יש להעלות גם אותם או להשבית אותם.

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

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

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

#דרישות גישה לרשת

Claude Code דורש גישה לכתובות ה-URL הבאות. הוסף אותן לרשימת ההיתרים (allowlist) בהגדרות הפרוקסי ובכללי חומת האש שלך, במיוחד בסביבות רשת מוגבלות או מבוססות מכולות (containers). בדיקת הקישוריות בהפעלה הראשונה מפנה לכאן כאשר אינה מצליחה לגשת אל api.anthropic.com או אל platform.claude.com; ראה לא ניתן להתחבר לשירותי Anthropic עבור הודעות הבדיקה וצעדי ההתאוששות.