תיעוד 135

הגדרת כלי Bash בארגז החול

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

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

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

ארגז החול רץ על macOS, Linux ו-WSL2. ב-Windows מקורי, Claude Code מריץ פקודות בלי ארגז חול. כדי להשתמש בארגז החול במחשב Windows, הרץ את Claude Code בתוך הפצת WSL2.

[!NOTE]

העמוד הזה עוסק בארגז החול סביב פקודות מעטפת במחשב שלך. עמודים אחרים עוסקים בשאלות קשורות:

לאופן שבו סשן בענן מבודד, ראה אבטחה ובידוד

להשוואה בין גישות בידוד אחרות כגון dev containers, מכולות מותאמות אישית ומכונות וירטואליות, ראה סביבות ארגז חול

כדי להפחית בקשות הרשאה לכלים שאינם Bash, ראה מצבי הרשאה

#מה ארגז החול מגביל

בזמן שארגז החול פעיל, פקודות המעטפת ש-Claude מריץ מתחילות בתוך הגבול שלו, וכך גם התהליכים שהן מפעילות. ארגז החול כבוי כברירת מחדל. כדי להפעיל אותו, הרץ /sandbox בסשן, כפי שהתחלה מראה, או הגדר את sandbox.enabled ל-true בקובץ הגדרות כגון ~/.claude/settings.json.

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

גישה	ברירת מחדל	שנה באמצעות
כתיבות	תיקיית העבודה, תיקיית temp לכל משתמש, ותיקיות שהוספת. נתיבים מוגנים נשארים חסומים לכתיבה	`filesystem.allowWrite`, `filesystem.denyWrite`
קריאות	רוב המחשב, כולל קובצי אישורים כגון `~/.ssh` ו-`~/.aws/credentials`	`filesystem.denyRead`, `credentials`
רשת	אין מסלול ישיר החוצה. חיבורים עוברים דרך פרוקסי במחשב שלך שבודק כל מארח מול הדומיינים המותרים שלך, שמתחילים ריקים. מצב ההרשאה שלך קובע מה קורה למארחים אחרים	`network.allowedDomains`, `network.deniedDomains`
משתני סביבה	בירושה מ-Claude Code, כולל סודות כלשהם בסביבה שלו	`credentials`, `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`

Claude Code בונה את ארגז החול על חבילת הקוד הפתוח @anthropic-ai/sandbox-runtime.

#מה רץ מחוץ לארגז החול

ארגז החול עוטף פקודות מעטפת. הכלים והתהליכים האלה רצים מחוץ לו:

כלי קבצים ורשת מובנים: כלים כגון Read, Edit, Write, WebFetch ו-WebSearch פועלים לפי כללי הרשאה. רשומת denyRead לא עוצרת את כלי Read, ו-allowedDomains לא מגביל את WebFetch
תהליכים אחרים ש-Claude Code מפעיל: הוקים של פקודות, שרתי MCP מקומיים, מוניטורים של תוספים, שרתי LSP, ופקודות עזר כגון פקודת שורת המצב שלך ו-apiKeyHelper רצים עם הגישה המלאה שלך

חלק מפקודות המעטפת גם רצות מחוץ לארגז החול, בהתאם להגדרות שלך:

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

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

#התחלה

ארגז החול מובנה ב-Claude Code. מה שאתה מתקין תלוי בפלטפורמה שלך:

macOS: ארגז החול משתמש במסגרת Seatbelt המובנית, כך שאפשר לעבור ישר לשלבים
Linux ו-WSL2: ארגז החול נשען על bubblewrap ו-socat, כמפורט בהגדרת Linux ו-WSL2. גם אם עדיין לא התקנת אותם, אפשר להתחיל עם /sandbox, כי הלוח שלו מראה אם משהו חסר

1. הרץ /sandbox

התחל סשן של Claude Code והרץ את הפקודה /sandbox:

/sandbox

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

Mode: בחר איך מאשרים פקודות בתוך ארגז החול, כמפורט בשלב הבא
Overrides: בחר אם פקודות שנכשלות תחת ארגז החול יכולות לחזור להרצה בלי ארגז חול. זו הגדרת allowUnsandboxedCommands
Config: הצג את הגדרות ארגז החול שנפתרו

אם הלוח מציג רק לשונית Dependencies, ארגז החול עדיין לא יכול להתחיל. תקן את מה שהלשונית מדווחת, כמתואר בהגדרת Linux ו-WSL2, הפעל מחדש את Claude Code, והרץ /sandbox שוב.

2. בחר מצב

בלשונית Mode, בחר auto-allow או regular permissions. Auto-allow מריץ פקודות בתוך ארגז החול בלי הנחיה, ו-regular permissions שומר את הנחיות ההרשאה הרגילות גם כשהפקודות בתוך ארגז החול. ראה מצבי ארגז חול לגבי אילו פקודות עדיין מבקשות אישור במצב auto-allow.

3. הרץ פקודת Bash

בקש מ-Claude להריץ פקודה, כגון בנייה או חבילת בדיקות. כברירת מחדל, פקודות בתוך ארגז החול יכולות לכתוב לתיקיית העבודה, לתיקיית temp לכל משתמש, ולכל תיקיות שהוספת באמצעות --add-dir, /add-dir, או permissions.additionalDirectories.

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

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

אם פקודות בתוך ארגז החול נכשלות עם Operation not permitted בתוך מכולה, ראה Bubblewrap נכשל להתחיל בתוך מכולה.

כשאתה בוחר מצב בלוח, Claude Code שומר אותו בהגדרות המקומיות של הפרויקט שלך ב-.claude/settings.local.json, שחלות על הפרויקט הנוכחי. Claude Code מוסיף את הקובץ הזה ל-gitignore הגלובלי שלך כשהוא שומר שם הגדרה. כדי להפעיל את ארגז החול בכל הפרויקטים שלך, הגדר את sandbox.enabled ל-true בהגדרות המשתמש שלך ב-~/.claude/settings.json. כדי לאכוף ארגז חול על כל מפתח בארגון, השתמש בהגדרות מנוהלות.

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

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

[!WARNING]

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

#אימות שפקודות רצות בתוך ארגז החול

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

פקודה	תוצאה בתוך ארגז החול
`touch ~/sandbox-probe`	נכשל עם `Operation not permitted` ב-macOS, או `Read-only file system` ב-Linux וב-WSL2
`curl --noproxy '*' https://example.com`	נכשל עם `Could not resolve host`, כי לפקודה אין מסלול שעוקף את פרוקסי ארגז החול

אם Claude מבקש לנסות שוב פקודה שנכשלה מחוץ לארגז החול, דחה את הניסיון החוזר. אם touch מצליח ותיקיית הבית שלך אינה אחת מהתיקיות שארגז החול מאפשר לפקודות לכתוב אליהן, מחק את ~/sandbox-probe. אחר כך הרץ /sandbox כדי לבדוק שארגז החול פעיל ושהתלויות שלו מותקנות.

#הגדרת Linux ו-WSL2

ב-Linux וב-WSL2, ארגז החול נשען על החבילות האלה:

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

התקן אותם באמצעות מנהל החבילות של ההפצה שלך:

Ubuntu/Debian

sudo apt-get install bubblewrap socat

Fedora

sudo dnf install bubblewrap socat

כשתלות חסרה, לשונית Dependencies ב-/sandbox מפרטת אילו מבין ripgrep, bubblewrap, socat ומסנן seccomp חסרים בפלטפורמה שלך. אם אינך רואה את הלשונית אחרי ההתקנה והפעלה מחדש של Claude Code, כל התלויות קיימות.

Ripgrep ארוז עם הבינארי המקורי של Claude Code. מסנן seccomp אופציונלי ומוסיף חסימת שקעי Unix domain. התקן אותו באמצעות npm install -g @anthropic-ai/sandbox-runtime אם הוא חסר.

Dependencies היא הלשונית היחידה: ארגז החול לא יכול להתחיל. התקן את מה שהלשונית מפרטת כחסר, או אם היא מדווחת על הגבלת AppArmor של Ubuntu, הוסף פרופיל AppArmor עבור bubblewrap
Dependencies מופיעה לצד הלשוניות האחרות: הלשונית מפרטת פריט אופציונלי חסר, כגון מסנן seccomp. ארגז החול יכול להתחיל בלעדיו, אז התקן אותו רק אם אתה רוצה את מה שהוא מוסיף

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

#הערות WSL2

בדוק את גרסת WSL שלך באמצעות wsl -l -v מ-PowerShell. אם אתה רואה Sandboxing requires WSL2, ההפצה שלך רצה על WSL1. שדרג אותה ל-WSL2 או הרץ את Claude Code בלי ארגז חול.

ב-WSL2, WSL מעביר הפעלה של קובץ בינארי של Windows כגון cmd.exe, powershell.exe, או כל דבר תחת /mnt/c/ אל מארח Windows דרך שקע Unix, ולכן האם פקודה בתוך ארגז החול יכולה להפעיל אחד כזה נקבעת לפי הגדרות שקעי Unix של ארגז החול: כדי לחסום את השקע מלכתחילה צריך להתקין את מסנן seccomp האופציונלי. כדי לאפשר את ההפעלות האלה, הגדר את allowAllUnixSockets, שפותח כל שקע Unix לפקודות שבתוך ארגז החול.

#הוספת פרופיל AppArmor עבור bubblewrap

הוסף את הפרופיל אם Claude Code מריץ את /usr/bin/bwrap ואחד מאלה קורה:

Claude Code מדווח על הגבלת AppArmor של Ubuntu על מרחבי שמות משתמש
פקודות בתוך ארגז החול נכשלות עם bwrap: setting up uid map: Permission denied או bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted בזמן שההגבלה הזו פעילה

Claude Code מריץ את bwrap הראשון ב-PATH, אלא אם הגדרות מנוהלות מציינות אחד ב-sandbox.bwrapPath. כדי לראות איזה bwrap ראשון, הרץ which bwrap במעטפת שממנה אתה מפעיל את Claude Code. אם Claude Code מריץ נתיב כלשהו שאינו /usr/bin/bwrap, בטל את ההגבלה באמצעות sysctl.

כדי להוסיף את הפרופיל עבור /usr/bin/bwrap, הרץ את הפקודה הזו:

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

טען מחדש את AppArmor כדי להחיל אותו:

sudo systemctl reload apparmor

אחר כך הפעל מחדש את Claude Code ואשר שארגז החול עובד.

#מצבי ארגז חול

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

#מצב אישור אוטומטי

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

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

גם במצב אישור אוטומטי, אלה עדיין חלים:

פקודה בצורה שכלל דחייה של Bash תואם לה עדיין חסומה
פקודות rm או rmdir שמזוהות כמכוונות לנתיב קריטי עדיין עוברות את זרימת ההרשאות הרגילה
כללי בקשה שמוגבלים לתוכן, כמו Bash(git push *), עדיין כופים בקשה גם לפקודות בתוך ארגז החול
כלל בקשה של Bash בלבד, או הצורה המקבילה Bash(*), מדולג לפקודות שרצות בתוך ארגז החול. הוא עדיין חל על פקודות שרצות מחוץ לארגז החול. במצב תכנון, הכלל לא מדולג: הוא מבקש אישור גם לפקודות בתוך ארגז החול, כולל פקודות לקריאה בלבד
פקודות של כלי Monitor לא מאושרות אוטומטית, אף שהן עדיין רצות בתוך ארגז החול. כדי לדלג על הבקשה, הוסיפו כלל אישור שתואם לפקודה, כמו Bash(npm run *)

חלק מהפקודות בתוך ארגז החול עוברות גם את זרימת ההרשאות הרגילה במקום להיות מאושרות אוטומטית. זה קורה עם פקודות כמו FOO=bar npm test, שבהן משתנה שמוגדר לפני פקודה יכול לשנות איזו תוכנית רצה, ועם make CC=clang או eval "ls". כללי האישור שלכם ומצב ההרשאות מחליטים אז אם תראו בקשה, והפקודה עדיין רצה בתוך ארגז החול.

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

Bash(make *) מאשר את make CC=clang
Bash(FOO=bar npm *) מאשר את FOO=bar npm test. כשהפקודה מתחילה בהשמת משתנה, כללו את ההשמה בכלל
Bash(eval "ls") מאשר את eval "ls". כלל עם תו כללי כמו Bash(eval *) לא עוצר את הבקשה הזו, אז כתבו כלל שתואם לכל הפקודה

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

[!NOTE]

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

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

#מצב הרשאות רגיל

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

#פתח המילוט של ניסיון חוזר בלי ארגז חול

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

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

מצב bypassPermissions: הניסיון החוזר רץ בלי בקשה
מצב Manual ומצב acceptEdits: אתם מקבלים בקשה שכותרתה "Bash command (unsandboxed)"
מצב Auto: מודל מסווג נפרד מעריך את הפקודה הבסיסית
מצב dontAsk: Claude Code דוחה את הניסיון החוזר
מצב Plan: ראו איך Claude Code שולט בפקודות בזמן שאתם מתכננים

הכללים וההגדרות האלה משנים מי מאשר את הניסיון החוזר:

כלל אישור תואם: אם כלל אישור כמו Bash(curl *) תואם לפקודה, הוא מאשר גם את הניסיון החוזר, כך שהפקודה רצה מחוץ לארגז החול בלי בקשה
כלל בקשה לפרמטר: הוסיפו כלל בקשה עבור Bash(dangerouslyDisableSandbox:true) כדי לקבל בקשה בניסיונות חוזרים של Bash. אתם מקבלים את הבקשה גם במצב auto ובמצב bypassPermissions, והכלל גובר על כלל אישור תואם
permissions.blockReadsOutsideWorkingDirectories: פעולות שאף מצב לא מאשר אוטומטית מכסה את הניסיונות החוזרים שמבקשים אישור כשההגדרה פעילה

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

#כיבוי הניסיון החוזר עם מצב ארגז חול קפדני

אפשר להשבית את הניסיון החוזר בלי ארגז חול על ידי הגדרת "allowUnsandboxedCommands": false בהגדרות ארגז החול שלכם. כשהניסיון החוזר מושבת, Claude Code מתעלם מהפרמטר dangerouslyDisableSandbox. בזמן שארגז החול רץ, פקודות ש-Claude מריץ אז נמצאות בתוך ארגז החול אלא אם הן תואמות לרשומת excludedCommands. כדי למנוע מ-Claude Code להריץ פקודות בלי ארגז חול כשארגז החול לא יכול להתחיל, הגדירו גם את failIfUnavailable. הלשונית Overrides של /sandbox מציגה את ההגדרה הזו כ-Strict sandbox mode.

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

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

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

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

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

#ספריות זמניות

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

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

#הגדרת ארגז החול

התאימו את התנהגות ארגז החול דרך קובץ settings.json שלכם. ראו הגדרות לעיון המלא בתצורה.

כברירת מחדל, פקודות בתוך ארגז החול יכולות לכתוב לספריית העבודה הנוכחית, לספריית temp לכל משתמש, ולכל הספריות שהוספתם עם --add-dir, /add-dir, או permissions.additionalDirectories. אם פקודות תהליך בן כמו kubectl, terraform, או npm צריכות לכתוב מחוץ לספריות האלה, השתמשו ב-sandbox.filesystem.allowWrite כדי להעניק גישה לנתיבים מסוימים:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

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

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

אם מדירים מקור עם --setting-sources ב-CLI או עם settingSources ב-Agent SDK, Claude Code מתעלם מרשומות sandbox.filesystem שלו, מכללי הרשאת Edit שלו, ומכללי דחיית Read שלו כשהוא בונה את תצורת ארגז החול. נדרש Claude Code v2.1.246 או חדש יותר.

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

נתיבי מערכת הקבצים של ארגז החול משתמשים במוסכמות רגילות: /tmp/build הוא מוחלט ו-~/.kube הוא יחסי לספריית הבית שלכם. זה שונה מכללי הרשאת Read ו-Edit, שמשתמשים ב-//path למוחלט וב-/path ליחסי לפרויקט. לנתיבים יחסיים, לוכסנים בסוף, ולתווים כלליים, ראו קידומות נתיב של ארגז החול.

אפשר גם לשלול גישת כתיבה או קריאה באמצעות sandbox.filesystem.denyWrite ו-sandbox.filesystem.denyRead, ולאפשר מחדש נתיבים מסוימים בתוך אזור שנשלל באמצעות sandbox.filesystem.allowRead. כשכללי קריאה חופפים, הכלל עם הנתיב הצר יותר חל:

דוגמאות לכללים	תוצאה
`"denyRead": ["~/"]` עם `"allowRead": ["~/projects"]`	`~/projects` קריא ושאר ספריית הבית נשאר חסום. האישור הצר יותר פותח מחדש את החלק הזה של האזור שנשלל
`"allowRead": ["~/"]` עם `"denyRead": ["~/.env"]`	`~/.env` נשאר חסום ושאר ספריית הבית קריא. הדחייה נשמרת בתוך אישור רחב יותר, כך שאישור רחב לא יכול לחשוף מחדש סוד בשקט
`"allowRead": ["~/"]` עם `"denyRead": ["~/**/.env"]`	כל `.env` תחת ספריית הבית נשאר חסום והשאר קריא. דחייה עם תו כללי נשמרת בתוך אישור רחב יותר באותו אופן כמו נתיב מדויק

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

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

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

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

#הרצת פקודות מחוץ לארגז החול עם `excludedCommands`

רשמו תבנית פקודה ב-sandbox.excludedCommands כדי להריץ פקודות תואמות מחוץ לארגז החול, כלומר בלי הגבלות מערכת קבצים ובלי פרוקסי רשת. השתמשו בזה לכלי שלא יכול לעבוד בתוך ארגז החול ושאתם סומכים עליו עם הגישה המלאה שלכם. כלי שצריך ספרייה אחת נוספת או מארח אחד נוסף עשוי לעבוד עם allowWrite או allowedDomains, שמשאירים את הפקודה בתוך ארגז החול.

הדוגמה הזו מוציאה פקודות docker compose מארגז החול. שמרו אותה ב-~/.claude/settings.json כדי להחיל אותה על כל הפרויקטים שלכם:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

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

סיימו את התבנית ב- *: רשומות משתמשות באותו תחביר כמו כלל הרשאה של Bash(...), שבו תבנית בלי תו כללי היא התאמה מדויקת. docker תואם רק ל-docker בלי ארגומנטים. docker * תואם ל-docker עם ארגומנטים או בלי
כל פקודה בקריאה צריכה להתאים: npm ci && docker compose build נשאר בתוך ארגז החול אלא אם רשומה אחרת מכסה את npm ci
Claude Code מתאים את הטקסט של הקריאה: סקריפט או יעד make שקורא ל-docker מבפנים לא תואם, וגם לא /usr/local/bin/docker
חלק מהקריאות נשארות בתוך ארגז החול: הפניה מחדש לקובץ, cd, או החלפת פקודה כמו $(...) משאירים את כל הקריאה בתוך ארגז החול. רשומת העיון מפרטת עוד קריאות שנשארות בתוך ארגז החול
git clone צריך נתיבים יחסיים: הרשומה שלכם לא מכסה שכפול שמציין נתיב מוחלט, נתיב שמתחיל ב-~, או נתיב עם מקטע ... אם השכפול יכול להיכנס לספריית העבודה שלכם, בקשו מ-Claude להשתמש בנתיב יחסי בלי מקטע .., כמו vendor/lib
המקום שבו שומרים את הרשומה יכול להיות חשוב: כשארגז החול נדרש על ידי מנהל, Claude Code מתעלם מרשומות ב-.claude/settings.json וב-.claude/settings.local.json

פקודה שהוצאה עוברת את זרימת ההרשאות הרגילה:

פקודות לקריאה בלבד ופקודות שכללי האישור שלכם מכסים רצות בלי בקשה
במצב auto, המסווג בודק פקודות שהוצאו אחרות
במצב bypassPermissions, פקודה שהוצאה רצה בלי בקשה אלא אם כלל בקשה תואם לה

כדי לאשר שרשומה תואמת, עברו למצב Manual ובקשו מ-Claude להריץ פקודה תואמת שמשנה משהו, כמו docker compose up -d. בקשת ההרשאה כותרתה "Bash command (unsandboxed)".

[!WARNING]

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

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

הגדר את sandbox.filesystem.disabled לערך true כדי לדלג על בידוד מערכת הקבצים תוך שמירה על בידוד הרשת. הדוגמה הבאה מכבה את בידוד מערכת הקבצים תוך שמירה על רשימת דומיינים מותרים ברשת:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

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

ברירת המחדל של sandbox.filesystem.disabled היא false.

[!WARNING]

כשבידוד מערכת הקבצים כבוי ופקודות מאושרות אוטומטית, פקודה בסנדבוקס יכולה לכתוב קבצים שפקודות מאוחרות יותר מריצות או קוראות, כגון קבצי אתחול של המעטפת, קבצי הרצה ב-$PATH, או ~/.claude/settings.json, ולהשתמש בהם כדי להרחיב את הגישה שלה בהרצה הבאה. הגדר את filesystem.disabled ל-true רק לעומסי עבודה שאתה סומך עליהם שלא יסלימו את הגישה של עצמם. נעילת דומיינים ברשת באמצעות allowManagedDomainsOnly מצמצמת את הסיכון אבל לא מסירה אותו, כי הנעילה חלה רק על פקודות שרצות בתוך הסנדבוקס.

#אילו הגדרות יכולות לכבות אותו

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

הגדרות משתמש, הגדרות מנוהלות ודגל ה-CLI --settings יכולים להגדיר אותו. הגדרות פרויקט ב-.claude/settings.json וב-.claude/settings.local.json לא יכולות, ולכן פרויקט שעבר checkout לא יכול לכבות את בידוד מערכת הקבצים.
כשהגדרות מנוהלות מגדירות את sandbox.filesystem בכלל, או מפרטות רשומה כלשהי ב-sandbox.credentials.files עם "mode": "deny", רק הגדרות מנוהלות יכולות להגדיר את המפתח. כך מפתחים לא יכולים לכבות את בידוד מערכת הקבצים בפריסה כזאת. כדי לכבות אותו לכולם, הגדר "disabled": true בהגדרות המנוהלות.
כש-CLAUDE_CODE_SUBPROCESS_ENV_SCRUB מוגדר, Claude Code מתעלם מ-filesystem.disabled מכל מקור, כולל הגדרות מנוהלות, ומשאיר את בידוד מערכת הקבצים דלוק.

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

#מה משתנה כשבידוד מערכת הקבצים כבוי

הגדרת filesystem.disabled מסירה את ההגנות ששכבת מערכת הקבצים עצמה אוכפת. הגנות ששכבות אחרות אוכפות ממשיכות לחול:

הגנה	כשבידוד מערכת הקבצים כבוי
חסימות קריאה של `filesystem.denyRead` ושל `deny` ב-`credentials.files`	לא נאכפות. שכבת מערכת הקבצים מחילה את שתיהן
רשומות `deny` ו-`mask` של `credentials.envVars`	נאכפות. ניקוי משתני סביבה אינו תלוי בשכבת מערכת הקבצים
רשומות `mask` של `credentials.files` שמוחלות כמיסוך	נאכפות: המיסוך אינו תלוי בשכבת מערכת הקבצים. רשומה שנפלה חזרה ל-`deny` לא נאכפת, כמו כל רשומת `deny`

עוד שני דברים משתנים:

פקודות בסנדבוקס יורשות את $TMPDIR של המעטפת שלך במקום את תיקיית הזמני לכל משתמש, כי כל תיקיית זמני ניתנת לכתיבה ו-Claude Code כבר לא מפנה פקודות לתיקייה לכל משתמש.

בלינוקס המשתנה לעתים קרובות לא מוגדר במעטפת האב. ההנחיה של כלי Bash אומרת ל-Claude ליצור תיקיות זמניות באמצעות mktemp -d במקום להסתמך על $TMPDIR.
autoAllowBashIfSandboxed עדיין ברירת המחדל שלו היא true, ולכן פקודות בסנדבוקס ממשיכות לרוץ בלי הנחיות. הגדר אותו ל-false כדי להציג הנחיה עבור פקודות בסנדבוקס.

#הגנה על אישורים

ההגדרה sandbox.credentials מצהירה על קבצי אישורים ומשתני סביבה שיש להגן עליהם מפני פקודות בסנדבוקס. כל רשומה מציינת נתיב קובץ או משתנה סביבה ו-mode. הבלוק הייעודי credentials שומר את כללי האישורים מקובצים יחד ונפרדים מכללי מערכת הקבצים הכלליים.

עבור רשומות עם "mode": "deny", נתיבי קבצים נחסמים לקריאה בתוך הסנדבוקס, אותה הגבלה ש-filesystem.denyRead מחיל, ומשתני סביבה מבוטלים (unset) לפני שכל פקודה בסנדבוקס רצה. הגנת הקבצים היא חלק משכבת מערכת הקבצים, ולכן היא לא חלה אם אתה מכבה את בידוד מערכת הקבצים. הגנת משתני הסביבה עדיין חלה.

הדוגמה הבאה חוסמת קריאות של קובץ האישורים של AWS ושל תיקיית SSH, ומסירה את GITHUB_TOKEN ואת NPM_TOKEN מסביבת הפקודות בסנדבוקס:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

רשומות של משתני סביבה ורשומות של קבצים מקבלות גם "mode": "mask", כמתואר תחת מיסוך אישורים.

נתיבי קבצים פועלים לפי אותם כללי קידומת כמו הגדרות sandbox.filesystem.*.

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

כשאתה מחריג מקור הגדרות:

הגדרות פרויקט או מקומיות: Claude Code לא מחיל אף אחת מרשומות ה-credentials שלהן. נדרש Claude Code גרסה v2.1.246 או חדשה יותר.
הגדרות משתמש: Claude Code עדיין מחיל את רשומות ה-deny ב-~/.claude/settings.json ושומר את רשומות ה-mask של קבצים כהגבלות שכבר לא מאשרות לפרוקסי להחליף בערך האמיתי, אבל משמיט את רשומות ה-mask של משתני סביבה.

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

sandbox.credentials משפיע רק על פקודות Bash בסנדבוקס. כדי להסיר אישורים מכל תהליכי המשנה בלי קשר לסנדבוקס, הגדר את CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

#מיסוך אישורים

כשאתה ממסך אישור, Claude Code מציג לפקודות בסנדבוקס ממלא מקום לכל סשן שנקרא sentinel, והפרוקסי של הסנדבוקס מחליף בערך האמיתי בבקשות יוצאות למארחים שאתה מתיר. רשומת deny תחת הגנה על אישורים חוסמת את האישור במקום למסך אותו. עבור קבצים ב-macOS, Claude Code חוסם את הקובץ במקום למסך אותו. העיון ב-sandbox.credentials מפרט כל שדה.

מיסוך דורש את הדברים הבאים:

סיום TLS: הפרוקסי מחליף בערך האמיתי בתוך תוכן הבקשות, ולכן הוא צריך לראות אותן. הגדר את network.tlsTerminate כדי שהפרוקסי יסיים את TLS בעצמו. בלעדיו, המיסוך נכשל בלי לחשוף דבר: הפקודה עדיין רואה רק את ה-sentinel, אבל ה-sentinel מגיע לשרת ללא שינוי והאימות נכשל. כדי לבדוק תצורה שגויה זו, הרץ claude doctor בטרמינל וחפש את האזהרה TLS termination is unavailable.
יעד מותר: כל רשומת mask יכולה לפרט injectHosts, המארחים שהערך האמיתי מותר להגיע אליהם. הפרוקסי מזריק רק בחיבורים שרשימת הדומיינים המותרים מתירה, ולכן כל מארח ב-injectHosts חייב להיות נגיש גם דרך network.allowedDomains. עבור רשומת mask בלי injectHosts, הפרוקסי מחליף בערך האמיתי בבקשות לכל מארח ב-network.allowedDomains.
היקף הגדרות מהימן: מיסוך מאשר לפרוקסי לשלוח את האישור האמיתי שלך למקום כלשהו, ולכן Claude Code מכבד רשומות mask, את network.tlsTerminate, את credentials.allowPlaintextInject, את awsPairs ואת sigv4 רק מהגדרות משתמש, הגדרות מנוהלות ודגל --settings. הוא מתעלם מהם ב-.claude/settings.json או ב-.claude/settings.local.json של מאגר. כשהמנהל שלך מעביר רשומות mask, network.tlsTerminate או credentials.allowPlaintextInject דרך הגדרות שמנוהלות בשרת, הן נחשבות להגדרות שדורשות אישור.

#מיסוך משתני סביבה

כדי למסך משתנה סביבה, הגדר "mode": "mask" ברשומת credentials.envVars שלו. הפקודה וכל מה שהיא רושמת בלוג אף פעם לא מחזיקים את האישור האמיתי, אבל הבקשות שלה עדיין עוברות אימות. כשאותו משתנה מופיע עם deny בכל היקף, deny מקבל עדיפות.

הדוגמה הזו ממסכת שני טוקנים. GH_TOKEN מוחלף רק בבקשות אל api.github.com, ואילו ל-NPM_TOKEN אין injectHosts והוא מוחלף בבקשות לכל מארח ב-network.allowedDomains:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

מיסוך מחליף את כל הערך כברירת מחדל. עבור ערך עם מבנה, כגון מחרוזת חיבור DATABASE_URL או JWT, השתמש בשדות extract, decode, maskClaims ו-onExtractNoMatch כדי שכלים שמפענחים את הערך ימשיכו לעבוד.

עבור יעד IPv6, כתוב את הכתובת בצורה שונה בשתי הרשימות:

network.allowedDomains: הצורה עם סוגריים מרובעים, כגון "[::1]"
injectHosts: הכתובת החשופה בצורה הדחוסה הקנונית שלה, כגון "::1"

הפרוקסי מתאים כל רשומת injectHosts לכתובת היעד החשופה של החיבור, ומתעלם מפורטים, ולכן איות עם סוגריים מרובעים, zone-ID, או דחיסה שונה אף פעם לא תואם. claude doctor מסמן רשומות שלעולם לא יכולות להתאים באמצעות האזהרה Sandbox credential injectHosts entries can never match their destination. הבדיקה הזו דורשת Claude Code גרסה v2.1.229 או חדשה יותר.

#חתימה מחדש של בקשות AWS

בקשות AWS נושאות חתימות SigV4 על תוכן הבקשה, ולכן מסך את AWS_ACCESS_KEY_ID ואת AWS_SECRET_ACCESS_KEY יחד. הפרוקסי מזהה בקשת SigV4 לפי ה-sentinel של מפתח הגישה וחותם מחדש את הבקשה עם הערכים האמיתיים, מה שדורש Claude Code גרסה v2.1.221 או חדשה יותר. אם אתה ממסך רק את הסוד, הבקשות נחתמות עם ממלא מקום שהפרוקסי לא יכול לזהות, ולכן הן נכשלות ב-AWS.

Claude Code מקשר את המשתנים המקובלים AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY ו-AWS_SESSION_TOKEN לאישור אחד באופן אוטומטי כשאתה ממסך את הערכים השלמים שלהם. אם אישור ה-AWS שלך נמצא במשתנים עם שמות אחרים, קבץ אותם באמצעות credentials.awsPairs, מה שדורש Claude Code גרסה v2.1.224 או חדשה יותר.

העלאות בזרימה, כתובות URL חתומות מראש ובקשות SigV4A נושאות חתימות שהפרוקסי לא יכול לחשב מחדש. כשאחת מהבקשות האלה חתומה עם ממלא המקום של זוג ממוסך, הפרוקסי נכשל בה במקום להעביר חתימה שבורה. בקשות שנחתמו עם אישורים לא ממוסכים לא מושפעות. השתמש ב-credentials.sigv4, מה שדורש Claude Code גרסה v2.1.224 או חדשה יותר, כדי להעביר אחת מצורות הבקשה האלה במקום זאת. AWS עדיין דוחה את הבקשה, ולכן הכלי הקורא מקבל את תגובת הדחייה של AWS עצמה במקום שגיאת פרוקסי.

#מיסוך קבצי אישורים

כדי למסך קובץ אישורים, הגדר "mode": "mask" ברשומת credentials.files שלו. מיסוך קבצים דורש Claude Code גרסה v2.1.221 או חדשה יותר. מה שפקודה בסנדבוקס רואה תלוי בפלטפורמה:

Linux ו-WSL2: פקודות בסנדבוקס קוראות עותק sentinel של הקובץ, והפרוקסי מחליף בערך האמיתי בבקשות יוצאות.
macOS: פקודות בסנדבוקס לא יכולות לקרוא את הקובץ בכלל. Claude Code לא בונה עותק sentinel, ולכן כלים שמאמתים באמצעות הקובץ לא עובדים בתוך הסנדבוקס, אותה השפעה כמו deny. חסימת הקריאה נשמרת גם כשאתה מכבה את בידוד מערכת הקבצים.

הדוגמה הזו ממסכת טוקן GitHub שמאוחסן ב-~/.config/gh/hosts.yml. תבנית ה-extract מסמנת איזה חלק מהקובץ הוא הסוד, ולכן ב-Linux וב-WSL2 gh עדיין מפענח את שאר התצורה שלו:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

כדי לוודא שהמיסוך פעיל, בקש מ-Claude להריץ cat ~/.config/gh/hosts.yml בפקודה בסנדבוקס. ב-Linux וב-WSL2 הפלט מציג sentinel במקום הטוקן, וב-macOS הקריאה נכשלת.

בלי extract או decode, Claude Code מחליף את כל הקובץ ב-sentinel אחד, מה שמתאים לקובץ שמחזיק סוד חשוף יחיד. השתמש בשדות extract, decode, maskClaims, onExtractNoMatch ו-maskDuplicates כדי לשלוט במיסוך חלקי ובמה שקורה כשהתבנית לא תואמת כלום.

[!WARNING]

כשההתאמה לא מוצאת דבר למסך, ערך ברירת המחדל של onExtractNoMatch, warn, מדלג על הרשומה, ולכן פקודות בסנדבוקס יכולות לקרוא את הקובץ האמיתי ללא מיסוך. ב-macOS, Claude Code מחיל רשומות mask כ-deny לפני שהתבנית רצה בכל פעם שבידוד מערכת הקבצים דלוק, ולכן תוצאות אי-ההתאמה נכנסות לתוקף שם רק כשבידוד מערכת הקבצים כבוי. ברירת המחדל מתאימה לאישורים שעשויים להיעדר באופן לגיטימי. אם הסוד עשוי להיות קיים אבל התבנית עשויה לפספס אותו, השתמש ב-deny.

mask חל על קובץ יחיד, ולכן פרט כל קובץ אישורים בנפרד. Claude Code נופל חזרה ל-deny עבור רשומת mask שהוא לא יכול למסך בבטחה: נתיב תיקייה, תבנית glob, קובץ גדול מ-8 MiB, או קובץ שאינו טקסט UTF-8.

#איך ארגז החול עובד

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

כלי ה-Bash שבארגז החול מגביל את הגישה למערכת הקבצים לתיקיות מסוימות:

התנהגות כתיבה ברירת מחדל: גישת קריאה וכתיבה לתיקיית העבודה הנוכחית ולתת התיקיות שלה, לכל תיקייה שהוספת עם --add-dir, /add-dir, או permissions.additionalDirectories, וגם לתיקיית הזמני של המשתמש שאליה $TMPDIR מצביע
התנהגות קריאה ברירת מחדל: גישת קריאה לכל המחשב, חוץ מתיקיות חסומות מסוימות. ברירת המחדל הזו עדיין מאפשרת קריאה של קבצי אישורים, ולכן הגן על אישורים שאינך רוצה שפקודות יקראו.
חסימת קריאה: כש-permissions.blockReadsOutsideWorkingDirectories מופעל, פקודות בארגז החול מאבדות גם גישת קריאה לתיקיית הבית שלך ולתיקיות האחרות שמחזיקות קבצי משתמש, מלבד הנתיבים ש-פקודות בארגז החול תחת החסימה מפרטת. הסעיף הזה גם אומר מתי החלק הזה של החסימה לא חל.
עצי עבודה של Git: כשתיקיית העבודה היא עץ עבודה מקושר של git, ארגז החול מאפשר גם כתיבה לתיקיית .git המשותפת של המאגר הראשי, כדי שפקודות כמו git commit יוכלו לעדכן refs ואת האינדקס. כתיבה ל-hooks/ ול-config בתוך התיקייה הזו נשארת חסומה.

כדי לדלג לגמרי על בידוד מערכת הקבצים ועדיין לשמור על בידוד הרשת, הגדר sandbox.filesystem.disabled.

#נתיבים מוגנים

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

בתיקיית העבודה שלך ובתיקיות שמעליה: קבצי ההגדרות .claude, התיקיות .claude/skills, .claude/agents, .claude/commands ו-.claude/hooks, .mcp.json, והקבצים ש-Claude Code מריץ בעצמו, כמו .claude/workflows ו-.claude/scheduled_tasks.json
בתיקיית העבודה שלך בלבד: קבצי הפעלה של המעטפת כמו .bashrc ו-.zshrc, .gitconfig, התיקיות .vscode ו-.idea, וגם hooks ו-config בתוך .git
קבצים שיהפכו את תיקיית העבודה שלך למאגר git חשוף: HEAD, objects ו-refs ברמה העליונה, וגם רשומות config ו-hooks קיימות שם כשקובץ או קישור סמלי HEAD יושב לצדם. קובץ בשם config חסום גם בלי HEAD. אפשר למחוק HEAD, objects או refs שמופיעים מאוחר יותר. ב-Linux וב-WSL2, פקודה בארגז החול יכולה ליצור אחד במקום שבו אין כזה.
ב-~/.claude, או בתיקייה שאליה CLAUDE_CONFIG_DIR מצביע: רוב התוכן שלה, וגם ~/.claude.json ומאגר האישורים .credentials.json

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

אם תוסיף רשומת allowWrite או כלל הרשאה Edit שמכסה אחד מהנתיבים האלה, ההגנה עדיין חלה. כדי לכבות את ההגנה, הגדר filesystem.disabled, וזה גם מכבה את שאר בידוד מערכת הקבצים.

[!WARNING]

אם תגדיר allowNestedUserNamespaces ל-true ב-Linux או ב-WSL2, אל תסתמך על נתיבים מוגנים: קוד מפקודה בארגז החול יכול בסוף לרוץ מחוץ לארגז החול.

כדי לראות את רוב הנתיבים האלה כפי שהם נפתרים במחשב שלך, הרץ /sandbox ופתח את הלשונית Config, שמפרטת אותם תחת Denied within allowed, מעורבבים עם רשומות denyWrite שלך.

אם git merge או git checkout נכשלים עם unable to unlink old על אחד מהנתיבים האלה, ראה פקודת git נכשלת עם unable to unlink old.

#מתי ארגז החול מוחק את `HEAD`, `objects` או `refs`

אחרי שפקודה בארגז החול מסתיימת, רשומת HEAD, objects או refs חדשה יותר ברמה העליונה של תיקיית העבודה שלך נמחקת, אלא אם היא תיקייה עם תוכן. חדשה יותר פירושו שהרשומה לא הייתה שם כשארגז החול בנה לאחרונה את ההגדרות שלו: בתחילת הסשן, או אחרי שינוי כמו /cd.

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

#נתיבים חסומים שעוברים דרך קישור סמלי

ב-macOS, כשנתיב חסום עובר דרך קישור סמלי, כמו ~/.claude שהוא קישור למאגר dotfiles, ארגז החול חוסם גם את המיקום האמיתי של הנתיב. זה מכסה את החסימות של ארגז החול עצמו ואת רשומות denyWrite ו-denyRead המילוליות שלך.

רשומת denyWrite שמכילה *, ? או [ מכוסה גם כשתיקייה לפני הראשון מהתווים האלה היא קישור סמלי. לדוגמה, ~/.claude/*.json חסום גם תחת המיקום האמיתי של ~/.claude.

#בידוד רשת

לפקודה בארגז החול אין מסלול ישיר לרשת:

Linux ו-WSL2: הפקודה רצה במרחב שמות רשת נפרד שאין לו חיבור לרשת שלך
macOS: מסגרת ארגז החול Seatbelt חוסמת כברירת מחדל חיבורים חוץ מהחיבור ל-proxy של ארגז החול

Claude Code מריץ את ה-proxy של ארגז החול במחשב שלך, מחוץ לארגז החול, ומפנה פקודות אליו עם HTTP_PROXY, HTTPS_PROXY, ALL_PROXY ומשתני סביבה קשורים. ה-proxy בודק את שם המארח של כל חיבור מול הדומיינים המותרים והחסומים שלך.

מה שכלי יכול להגיע אליו תלוי אם הוא משתמש ב-proxy:

כלים שקוראים את משתני ה-proxy: curl, npm, git מעל HTTPS, וכלים דומים מתחברים ברגע שהמארח שלהם מותר. רשומת allowedDomains בלי פורט מתירה כל פורט באותו מארח
כלים שמתעלמים ממשתני ה-proxy: ssh רגיל, רוב מנהלי ההתקן של מסדי נתונים, וכלים דומים לא יכולים להתחבר, גם למארח מותר. ראה לקוח מסד נתונים או כלי שאינו HTTP נכשל בהגעה למארח מותר
כל מה שאינו TCP: UDP, HTTP/3 מעל QUIC, וכלי ICMP כמו ping לא יכולים לצאת מארגז החול

ההגדרות וההתנהגויות הבאות קובעות אילו מארחים ה-proxy מתיר:

הגבלות דומיין: הדומיינים המותרים שלך מתחילים ריקים. מארחים מחוץ לדומיינים המותרים שלך מכסה מה קורה בפעם הראשונה שפקודה צריכה דומיין חדש.
בחירות אישור: אם תבחר Yes כשמוצגת בקשה, Claude Code מתיר את המארח לשאר הסשן הנוכחי. אם תבחר "Yes, and don't ask again", Claude Code שומר כלל הרשאה WebFetch(domain:...) ב-הגדרות המקומיות שלך, כך שהמארח נשאר מותר בסשנים עתידיים. כשארגז החול הוא נדרש על ידי מנהל, Claude Code שומר את הכלל בהגדרות המשתמש שלך, שם הוא חל בכל פרויקט.
דומיינים מותרים מראש: התר דומיינים מראש עם allowedDomains כדי להימנע מהבקשה לגמרי. Claude Code גם מתיר מראש דומיינים מכללי הרשאה WebFetch(domain:...), כפי שמתואר ב-כללי הרשאה.
רשימת היתר מחמירה: אם תגדיר strictAllowlist ל-true בהגדרות משתמש, מנוהלות, או --settings של ה-CLI, Claude Code חוסם פקודות בארגז החול מגישה לכל מארח מחוץ לרשימת ההיתר במקום להציג בקשה. רשימת ההיתר היא allowedDomains ועוד דומיינים מכללי הרשאה WebFetch(domain:...), או רק הרשומות מההגדרות המנוהלות כש-allowManagedDomainsOnly מוגדר. נעילות שחלות בלי ארגז חול שנדרש על ידי מנהל מכסה את הרשומות של מאגר. Claude Code אוכף את זה רק לפקודות בארגז החול. כלים בתוך התהליך כמו WebFetch עדיין פועלים לפי כללי ההרשאה שלהם. הגדרה בקובץ .claude/settings.json או .claude/settings.local.json של מאגר לא משפיעה. נדרש Claude Code v2.1.219 או מאוחר יותר.
נעילה מנוהלת: אם allowManagedDomainsOnly מוגדר בהגדרות מנוהלות, דומיינים לא מותרים נחסמים אוטומטית במקום בקשה, ורק allowedDomains וכללי הרשאה WebFetch(domain:...) מההגדרות המנוהלות מכובדים.
פרוקסי ארגוני: כשהרשת שלך דורשת שתעבורה יוצאת תעבור דרך פרוקסי ארגוני, הגדר HTTPS_PROXY, HTTP_PROXY ו-NO_PROXY כפי ש-הגדרת פרוקסי מתארת, בבלוק env של ההגדרות שלך כדי שגם סוכני רקע יקבלו אותם, או בסביבה שממנה אתה מפעיל את Claude Code. Claude Code אוכף את רשימת ההיתר של הדומיינים ואז מעביר חיבורים מותרים במנהרה דרך הפרוקסי במעלה הזרם. כתובות פרוקסי http:// ו-https:// עובדות, עם אימות בסיסי בכתובת אם אתה צריך אותו.

בכלל WebFetch(domain:...), ארגז החול מכבד שתי צורות של תו כללי: *. מוביל, כמו *.example.com, ו-* בודד. הצורה * הבודדת דורשת Claude Code v2.1.186 או מאוחר יותר. תו כללי בכל מיקום אחר, כמו WebFetch(domain:example.*), עדיין מתאים לשליפות אבל אין לו השפעה על פקודות בארגז החול.

[!NOTE]

הפרוקסי המובנה אוכף את רשימת ההיתר לפי שם המארח המבוקש, וכברירת מחדל אינו מסיים או בודק תעבורת TLS. ההגדרה הניסיונית network.tlsTerminate גורמת לפרוקסי המובנה לסיים TLS בעצמו, מה ש-רשומות אישורים mask דורשות. ראה מגבלות אבטחה להשלכות של ברירת המחדל, ו-הגדרת פרוקסי מותאמת אם מודל האיום שלך דורש בדיקת TLS.

#מארחים מחוץ לדומיינים המותרים שלך

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

מצב הרשאה	מה קורה לחיבור
מצב `bypassPermissions`, ומצב plan עם הרשאות עקיפה זמינות	מותר בלי בקשה
מצב ידני, מצב `acceptEdits`, ומצב plan אחרת	מקבלים בקשה
מצב Auto	נדחה אלא אם הפקודה ציינה את המארח והמסווג אישר את הרשימה
מצב `dontAsk`	נדחה

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

#שמות מארח שנפתרים לכתובות מקומיות

אחרי ששם מארח עובר את רשימת ההיתר, פרוקסי ארגז החול פותר אותו ומסרב לחיבור כשהשם נפתר רק לכתובות מקומיות. כתובות מקומיות כוללות כתובות loopback כמו 127.0.0.1, כתובות link-local כמו נקודת הקצה של מטא דאטה בענן 169.254.169.254, וכתובות שמוקצות למחשב שלך. השמות localhost ו-*.localhost מורשים להיפתר ל-loopback.

שם מארח אינטראנט מותר שנפתר לטווח פרטי כמו 10.0.0.0/8 מתחבר. כדי לאפשר לשם להיפתר לכתובת שנדחתה, הוסף את כתובת ה-IP הזו ל-allowedDomains, כמו "127.0.0.1:8080".

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

#דומיינים מותרים לפי פקודה במצב auto

ב-מצב auto עם ארגז חול מופעל, Claude מציין את המארחים שפקודה צריכה על הפקודה עצמה במקום להפעיל אישור רשת לכל חיבור. כל פקודת Bash, PowerShell, או Monitor שרצה בארגז החול יכולה לשאת רשימת מארחים מעבר לרשימת ההיתר של ארגז החול: דומיין כמו registry.npmjs.org, תו כללי כמו *.pythonhosted.org, או כתובת IP, כל אחד עם :port אופציונלי. המסווג בודק את המארחים יחד עם הפקודה. נדרש Claude Code v2.1.271 או מאוחר יותר.

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

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

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

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

#כתובות IPv6 ברשימות דומיין

כדי להתאים כתובת IPv6 ב-allowedDomains, ב-deniedDomains, או בכלל WebFetch(domain:...), כתוב את הכתובת בסוגריים מרובעים: "[::1]" מתאים לכתובת הזו בכל פורט, ו-"[::1]:443" מתאים לה בפורט 443 בלבד. הצורה עם הסוגריים דורשת Claude Code v2.1.229 או מאוחר יותר.

רשומה בלי סוגריים כמו ::1:443 היא דו משמעית בין כתובת לכתובת עם פורט:

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

כדי למצוא רשומות דו משמעיות, הרץ claude doctor במסוף וחפש את האזהרה Sandbox network domain entries have unreliable spellings. שכתב כל רשומה דו משמעית בצורה עם הסוגריים.

#אכיפה ברמת מערכת ההפעלה

כלי ה-Bash שבארגז החול משתמש ברכיבי אבטחה של מערכת ההפעלה:

macOS: משתמש ב-Seatbelt לאכיפת ארגז החול
Linux: משתמש ב-bubblewrap לבידוד
WSL2: משתמש ב-bubblewrap, כמו Linux

אפשר גם להריץ את החבילה @anthropic-ai/sandbox-runtime בפני עצמה כדי לעטוף את תהליך Claude Code. ראה סביבת הריצה של ארגז החול.

#איך ארגז החול קשור להרשאות ולמצבי הרשאה

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

#כללי הרשאה

כללי הרשאה וארגז החול שולטים בדברים שונים:

כללי הרשאה שולטים באילו כלים Claude Code יכול להשתמש, והם נבדקים לפני שכל כלי רץ. הם חלים על כל כלי: Bash, Read, Edit, WebFetch, MCP ואחרים, למעט שכלל deny או ask לא יכול לחסום את EndConversation כל עוד כלי אחר נשאר.
ארגז החול מספק אכיפה ברמת מערכת ההפעלה שמגבילה למה פקודות מעטפת יכולות לגשת ברמת מערכת הקבצים והרשת. הוא חל על פקודות הכלים Bash, PowerShell ו-Monitor ועל תהליכי הילד שלהן.

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

הגבלות מערכת קבצים ורשת מוגדרות גם דרך הגדרות ארגז החול וגם דרך כללי הרשאה:

הגדרה או כלל	מה זה עושה
`sandbox.filesystem.allowWrite`	מעניק לתהליך משנה גישת כתיבה לנתיבים מחוץ לתיקיית העבודה
`sandbox.filesystem.denyWrite` ו-`sandbox.filesystem.denyRead`	חוסמים גישת תהליך משנה לנתיבים מסוימים
`sandbox.filesystem.allowRead`	מאפשר מחדש קריאה של נתיבים מסוימים בתוך אזור `denyRead`
`sandbox.filesystem.disabled`	מכבה לגמרי את שכבת מערכת הקבצים, תוך שמירה על בידוד רשת
כללי allow של `Edit`	מעניקים גישת כתיבה לנתיבים מסוימים, באותו אופן שבו `sandbox.filesystem.allowWrite` עושה זאת
כללי deny של `Read` ושל `Edit`	חוסמים גישה לקבצים או לתיקיות מסוימים
כללי allow ו-deny של `WebFetch(domain:...)`	שולטים בגישה לדומיינים
`allowedDomains` של ארגז החול	שולט לאילו דומיינים פקודות Bash יכולות להגיע
`deniedDomains` של ארגז החול	חוסם דומיינים מסוימים גם כשתו כללי רחב יותר של `allowedDomains` היה מתיר אותם אחרת

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

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

#מצבי הרשאה

/sandbox אינו מצב הרשאה. מצבי הרשאה מחליטים אם קריאת כלי רצה ואם מוצגת לכם בקשה קודם, בעוד שארגז החול מגביל למה פקודת Bash יכולה לגשת אחרי שהיא רצה. הם נבדלים במה שהם שולטים ובמה שמחליף את הבקשה לכל פעולה:

	מה זה שולט	מה מחליף את הבקשה
`/sandbox`	למה פקודת Bash יכולה לגשת אחרי שהיא רצה	גבול ארגז החול עצמו, במצב auto-allow
מצב Auto	אם כל קריאת כלי רצה	מסווג שסוקר פעולות
`--dangerously-skip-permissions`	אם כל קריאת כלי רצה	כלום. גם בדיקות נתיב מוגן מדולגות. הפעולות שאף מצב לא מאשר אוטומטית עדיין חלות

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

#הגדרת ארגז החול עבור הארגון

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

#אכיפת ארגז חול עם הגדרות מנוהלות

כדי לחייב את ארגז החול לכל מפתח, מסרו את מפתחות sandbox דרך הגדרות מנוהלות, כקובץ שמנוהל על ידי ה-MDM שלכם או דרך הגדרות מנוהלות בשרת ב-claude.ai.

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

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

שני המפתחות מעבר ל-enabled שולטים במה שקורה כשארגז החול לא יכול להריץ פקודה:

failIfUnavailable: כשהפלטפורמה לא תומכת בארגז החול, או שבדיקת התלות בהפעלה נכשלת, Claude Code מסרב להתחיל במקום לחזור להרצה בלי ארגז חול
allowUnsandboxedCommands: false: Claude Code מתעלם מפתח המילוט dangerouslyDisableSandbox, כך שכשפקודה נכשלת תחת ארגז החול, Claude לא יכול לנסות אותה שוב בלי ארגז חול

שקלו את התוספות האלה לצדן:

הוסיפו excludedCommands לכלים שאושרו על ידי הארגון וחייבים לרוץ בלי בידוד, כי התצורה הזו מונעת מהגדרות של מאגר להוציא פקודות מארגז החול
הוסיפו רשומות sandbox.credentials לתיקיות אישורים כמו ~/.aws ו-~/.ssh ולמשתני סביבה סודיים, כי מדיניות הקריאה כברירת מחדל עדיין מתירה אותם

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

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

למסור את התצורה לפי מערכת הפעלה: לפרוס אותה דרך ה-MDM שלכם או כקובץ הגדרות מנוהלות רק במכונות macOS ו-Linux. הגדרות מנוהלות בשרת חלות על כל המשתמשים בארגון
להעביר משתמשי Windows לסביבה נתמכת: שיריצו את Claude Code בתוך WSL2 או בתוך קונטיינר

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

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

אלא אם הגדרות מנוהלות מגדירות אותם, הגדרות המשתמש של מפתח או --settings יכולים להפעיל את המפתחות הבאים. גם .claude/settings.json של מאגר יכול, אלא אם ארגז החול הוא נדרש על ידי מנהל. כל אחד מהם מחליש את ארגז החול, אז הגדירו אותו ל-false בהגדרות מנוהלות אם אינכם רוצים שייעשה בו שימוש:

enableWeakerNestedSandbox
enableWeakerNetworkIsolation
network.allowAllUnixSockets
network.allowLocalBinding
allowAppleEvents, שמאגר לא יכול להפעיל
allowNestedUserNamespaces, שמאגר לא יכול להפעיל

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

כשהגדרות מנוהלות מגדירות את sandbox.filesystem, או מפרטות רשומת sandbox.credentials.files כלשהי עם "mode": "deny", רק הגדרות מנוהלות יכולות להגדיר את filesystem.disabled, כך שמפתחים לא יכולים לכבות בידוד מערכת קבצים עם המפתח הזה. רשומת mask תקינה לא נועלת את המפתח. ראו אילו הגדרות יכולות לכבות אותו.

#הגדרות מאגר תחת ארגז חול שנדרש על ידי מנהל

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

allowUnsandboxedCommands מוגדר ל-false בהגדרות מנוהלות, או עם הדגל --settings, אלא אם הגדרות מנוהלות מגדירות אותו ל-true
allowManagedDomainsOnly מוגדר ל-true בהגדרות מנוהלות

ההגדרות האלה לא מפעילות את ארגז החול, אז הגדירו גם את enabled.

כל עוד ארגז החול נדרש על ידי מנהל, Claude Code לוקח את ההגדרות שמרפות אותו רק מהגדרות מנוהלות, מהדגל --settings ומ-~/.claude/settings.json של כל מפתח. הוא מתעלם מההגדרות האלה ב-.claude/settings.json וב-.claude/settings.local.json של מאגר:

הגדרת מאגר	ממה Claude Code מתעלם
`excludedCommands`, `ignoreViolations`, `network.allowedDomains`, `network.allowUnixSockets`, `network.allowMachLookup`, `network.httpProxyPort`, `network.socksProxyPort`	כל רשומה
`filesystem.allowWrite`, כללי allow של `Edit(...)`, `permissions.additionalDirectories`	גישת הכתיבה שכל רשומה נותנת לפקודות בארגז חול. כלי הקבצים של Claude עדיין עוקבים אחרי כללי `Edit(...)` ותיקיות נוספות
כללי allow של `WebFetch(domain:...)`	המארח שכל כלל מוסיף לרשימת ההיתר של ארגז החול. כלי WebFetch עדיין עוקב אחרי הכלל
`enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `network.allowAllUnixSockets`, `network.allowLocalBinding`	`true`. ערך `false` עדיין חל
`enabled`, `failIfUnavailable`	`false`, כש-`~/.claude/settings.json` של המפתח מגדיר `true`
`filesystem.allowRead`	רשומה בנתיב או מתחת לנתיב שהגדרות מנוהלות, `--settings` או הגדרות משתמש אוסרות לקרוא, או glob שיכול להתאים לאחד כזה

ההגדרות האלה עדיין חלות כל עוד ארגז החול נדרש על ידי מנהל:

בקבצי מאגר: רשומות deny והערך autoAllowBashIfSandboxed. הגדירו את המפתח בהגדרות מנוהלות כדי למנוע ממאגר לשנות אותו
בהגדרות של המפתח עצמו: ההגדרות בטבלה עדיין חלות מ-~/.claude/settings.json או מ---settings, אלא אם נעילה למנוהלות בלבד כמו allowManagedDomainsOnly מכסה אותן. לרוב, כמו excludedCommands ו-filesystem.allowWrite, אין נעילה למנוהלות בלבד

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

נדרש Claude Code מגרסה v2.1.285 ואילך. מ-v2.1.282 עד v2.1.284, אותן הגדרות גרמו ל-Claude Code להתעלם מרשומות excludedCommands של מאגר.

#נעילות שחלות בלי ארגז חול שנדרש על ידי מנהל

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

הגדרה	איפה מגדירים אותה	ממה Claude Code מתעלם בהגדרות של מאגר
`network.deniedDomains` או כלל deny של `WebFetch(domain:...)`	הגדרות מנוהלות, `--settings`	`httpProxyPort` ו-`socksProxyPort`
`network.strictAllowlist`	הגדרות מנוהלות, `--settings`, הגדרות משתמש	פורטי הפרוקסי, `allowedDomains` וכללי allow של `WebFetch(domain:...)`
`filesystem.denyRead`, כלל deny של `Read(...)`, או רשומת `credentials.files`	הגדרות מנוהלות, `--settings`	רשומת `allowRead`, `allowWrite`, allow של `Edit(...)` או `additionalDirectories` בנתיב או מתחת לנתיב שהגדרות מנוהלות, `--settings` או הגדרות משתמש אוסרות לקרוא, או glob שיכול להתאים לאחד כזה

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

#תצורת פרוקסי מותאמת

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

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

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

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

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

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

allowManagedDomainsOnly פועל: רק הגדרות מנוהלות
ארגז החול נדרש על ידי מנהל, או שחלה נעילת רשת צרה יותר: הגדרות מנוהלות, --settings והגדרות משתמש
אחרת: כל קובץ הגדרות

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

[!WARNING]

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

#פתרון בעיות

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

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

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

#פקודות נכשלות עם שגיאת host-not-allowed

כלי CLI רבים צריכים להגיע למארחים מסוימים. אשרו את המארח כשמוצגת בקשה, או הוסיפו אותו ל-allowedDomains. אם הארגון נועל את רשימת ההיתר עם allowManagedDomainsOnly, אין בקשה, אז בקשו ממנהל המערכת להוסיף את המארח.

#`jest` נתקע או נכשל

watchman אינו תואם לארגז החול. הריצו במקום זאת את jest --no-watchman.

#כלי שורת פקודה מבוססי Go נכשלים באימות TLS ב-macOS

כלים כגון gh, gcloud ו-terraform עלולים להיכשל באימות TLS תחת Seatbelt. כדי להריץ את הכלים האלה מחוץ לארגז החול, הוסיפו תבנית לכל כלי, כגון gh *, אל excludedCommands. הכלי רץ אז עם הגישה המלאה שלכם ועם האישורים השמורים שלו. אם אתם משתמשים ב-httpProxyPort עם פרוקסי MITM ו-CA מותאם, הגדירו את enableWeakerNetworkIsolation ל-true במקום זאת.

#`open`, `osascript` או תהליכי אימות מבוססי דפדפן נכשלים עם שגיאה `-600` ב-macOS

ארגז החול חוסם Apple Events כברירת מחדל. הגדירו את allowAppleEvents ל-true בהגדרות המשתמש, המנוהלות או ה-CLI כדי לאפשר אותם. Claude Code מתעלם מהמפתח הזה בהגדרות הפרויקט.

הפעלת allowAppleEvents מסירה את הבידוד של הרצת קוד, משום שפקודות בארגז החול יכולות אז להפעיל יישומים אחרים מחוץ לארגז החול בלי בקשת משתמש, ויכולות לשלוח פקודות AppleScript ליישומים שרצים, בכפוף לבקשת ההסכמה לאוטומציה של macOS (TCC). לחלופין, הוסיפו תבנית כגון open * אל excludedCommands. כל קריאה ל-open עוברת אז דרך תהליך ההרשאות, ו-open יכול להפעיל כל קובץ או אפליקציה, כולל אחד ש-Claude כתב.

#פקודות `docker` נכשלות

docker אינו תואם לארגז החול. הוציאו את פקודות ה-docker שאתם צריכים מארגז החול עם תבנית excludedCommands כגון docker compose *. הרצת פקודות מחוץ לארגז החול עם excludedCommands מסבירה למה פקודת docker מוחרגת יכולה להגיע. תבנית צרה יותר מוציאה פחות פקודות מארגז החול.

#Chromium או Podman ללא root נכשלים בתוך ארגז החול ב-Linux

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

Chromium יוצא עם No usable sandbox!
unshare -U true מדפיס unshare: unshare failed: Operation not permitted. כש-allowAllUnixSockets מופעל, הוא יכול להדפיס No space left on device במקום זאת
Podman ללא root מדפיס cannot clone: Operation not permitted, או נעצר מוקדם יותר עם read-only file system על אחת מהתיקיות שלו

בסשן שבו CLAUDE_CODE_SUBPROCESS_ENV_SCRUB מוגדר ל-1, הפעילו את Chromium או Electron עם --no-sandbox, והריצו כל כלי אחר בעצמכם מחוץ ל-Claude Code. בסשן הזה, כל פקודה רצה בארגז החול, ולהגדרות ששאר התיקונים למטה מציינים אין השפעה.

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

עבור Chromium או Electron, הפעילו את הדפדפן עם --no-sandbox. ארגז החול של Claude Code נשאר כפי שהוא, אבל הדפדפן מריץ תוכן אינטרנט בלי ארגז החול שלו.
עבור Podman ללא root, Buildah, או סקריפט או פקודת בדיקה שמריצה דפדפן או unshare, הוסיפו תבנית אל sandbox.excludedCommands, כגון podman *. פקודות שתואמות רצות מחוץ לארגז החול עם הגישה המלאה שלכם, ו-Claude יכול לערוך סקריפט בתיקיית העבודה שלכם לפני שהוא מריץ אותו. התבנית חייבת להתאים לפקודה ש-Claude מריץ, ולכן עבור דפדפן, התאימו את פקודת הבדיקה ולא את הדפדפן.
כדי לשמור על ארגז החול של Chromium או Electron עצמם, או כדי להריץ bubblewrap מקונן או unshare, הגדירו את sandbox.allowNestedUserNamespaces ל-true ב-~/.claude/settings.json, לא ב-.claude/settings.json של הפרויקט. נדרש Claude Code גרסה v2.1.305 או חדשה יותר. פקודה שמתחילה ב-unshare נשארת בארגז החול בכל תבנית excludedCommands שתרשמו, משום ש-unshare יכול להפעיל כל תוכנית אחרת. ההגדרה הזו לבדה אינה מספיקה עבור Podman ללא root או Buildah, שארגז החול עוצר גם בדרכים אחרות.

[!WARNING]

אם תגדירו את allowNestedUserNamespaces ל-true, אתם מכבים גבול אבטחה: קוד מפקודה בארגז החול עלול בסוף לרוץ מחוץ לארגז החול.

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

#`pbcopy`, `xclip` או `wl-copy` לא מעדכנים את הלוח

כלי הלוח pbcopy, xclip ו-wl-copy עלולים להיכשל בהגעה ללוח המערכת מתוך ארגז החול, ובמקרה כזה הטקסט שמועבר אליהם בצינור לא מגיע.

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

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

#פקודת git נכשלת עם `unable to unlink old`

git merge, git checkout ופקודות דומות נכשלות עם unable to unlink old כשהן צריכות להחליף קובץ שארגז החול אוסר כתיבה אליו. ב-Linux וב-WSL2 השגיאה מסתיימת ב-Read-only file system. הקובץ יכול להיות באחד מהמקומות האלה:

תחת נתיב מוגן כגון .claude/skills
תחת אחת מרשומות ה-denyWrite שלכם
מחוץ לתיקיות שארגז החול מאפשר לפקודות לכתוב אליהן בכלל

אחרי הכישלון, Claude עשוי להציע להריץ מחדש את הפקודה מחוץ לארגז החול. אשרו את הניסיון החוזר, או הריצו את פקודת ה-git בעצמכם במסוף אחר. אם הגדרתם את allowUnsandboxedCommands ל-false, Claude לא יכול להציע את הניסיון החוזר, אז הריצו את הפקודה בעצמכם.

#תיקייה בשם `objects` או `refs` נעלמת אחרי פקודה

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

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

#Bubblewrap נכשל בהתחלה בתוך קונטיינר

בקונטיינר לא פריבילגי, bubblewrap לא יכול לעגן מערכת קבצים /proc חדשה, ולכן פקודות בארגז החול נכשלות עם שגיאת bwrap כגון Can't mount proc on /newroot/proc: Operation not permitted. הגדירו את enableWeakerNestedSandbox ל-true כדי שארגז החול יבצע bind-mount ל-/proc הקיים של הקונטיינר. השתמשו בהגדרה הזו רק כשהקונטיינר החיצוני כבר מספק את גבול הבידוד שאתם צריכים, משום שההגדרה חושפת מידע על תהליכים לפקודות בארגז החול שמעגן /proc חדש היה מסתיר.

#הגבלת AppArmor של Ubuntu עוצרת את bubblewrap

ב-Linux וב-WSL2, ההודעה Ubuntu's AppArmor restriction on user namespaces stops bubblewrap here אומרת שהגבלת AppArmor של Ubuntu מונעת מארגז החול להתחיל.

כדי שארגז החול יתחיל, הסירו את ההגבלה באחת משתי הדרכים האלה:

הוסיפו פרופיל AppArmor עבור bubblewrap אם Claude Code מריץ את /usr/bin/bwrap
במעטפת שלכם, הריצו sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0, שמסיר את ההגבלה עבור כל תוכנית במכונה ונמשך עד שתאתחלו

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

עד שתסירו את ההגבלה, פקודות רצות בלי ארגז החול תחת תהליך ההרשאות הרגיל, או ש-Claude Code מסרב להתחיל אם sandbox.failIfUnavailable הוא true.

#פקודות בארגז החול נכשלות עם `bwrap: setting up uid map: Permission denied`

ב-Linux וב-WSL2, השגיאה הזו או bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted יכולות לומר שהגבלת AppArmor של Ubuntu על מרחבי שמות משתמש עוצרת את bubblewrap. כדי לבדוק, הריצו sysctl kernel.apparmor_restrict_unprivileged_userns במעטפת שלכם:

kernel.apparmor_restrict_unprivileged_userns = 1: ההגבלה פעילה. הוסיפו פרופיל AppArmor אם Claude Code מריץ את /usr/bin/bwrap, או הריצו sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0, שמסיר אותה עבור כל תוכנית עד שתאתחלו. אחר כך הפעילו מחדש את Claude Code ואשרו שארגז החול עובד
כל פלט אחר: ההגבלה אינה הסיבה. כדי לדווח על הכישלון, הריצו /feedback בשורת Claude Code

לפני v2.1.310, Claude Code לא בדק את ההגבלה הזו בהפעלה, ולכן /sandbox לא דיווח עליה.

#קבצים לקריאה בלבד בגודל 0 בתים מופיעים בנתיבי ההגדרות של `.claude`, ו-"Yes, and don't ask again" לא נשמר

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

מציין מקום נשאר מאחור במקרים כגון אלה:

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

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

הריצו claude doctor במסוף שלכם כדי לרשום את קבצי מצייני המקום שנשארו. האזהרה Sandbox mask files left behind at write-deny paths מציינת חלק מהם וסופרת את השאר. מחקו כל קובץ עם rm בזמן שאין סשן Claude Code אחר שרץ בפרויקט הזה. לפני v2.1.257, Claude Code השאיר את אותם מצייני מקום כשסשן נהרג, בלי לסמן אותם.

#`git` דרך SSH נכשל כשארגז החול פועל

ב-macOS, git fetch, git pull ו-git push מול remote של SSH נכשלים בתוך ארגז החול גם כשהמארח מותר. ב-Linux וב-WSL2, הם עובדים ברגע שהמארח מותר. Claude Code מעביר במנהרה את חיבור ה-SSH של git דרך פרוקסי ארגז החול, ומנהרת macOS לא יכולה להזדהות מול הפרוקסי הזה.

ב-Linux וב-WSL2, בדקו את אלה אם החיבור עדיין נכשל:

המארח מותר בפורט 22: רשומת allowedDomains בלי פורט, כגון "git.example.com", מכסה אותו
הפרוקסי הארגוני שלכם מתיר פורט 22: אם הרשת שלכם דורשת פרוקסי במעלה הזרם, המנהרה עוברת גם דרכו
המפתח קריא כקובץ: ארגז החול יכול לחסום את שקע ssh-agent, ורשומת denyRead או credentials עבור ~/.ssh מסתירה את קבצי המפתח שלכם

ב-macOS, החליפו את ה-remote ל-HTTPS, שדורש אישורי HTTPS כגון אסימון גישה אישי:

git remote set-url origin https://git.example.com/example-org/example-repo.git

אם אתם חייבים לשמור את ה-remote של SSH, הוציאו את פקודות הרשת של git מארגז החול עם excludedCommands:

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

הרשומות האלה תואמות ל-git push origin main. קריאה שמוסיפה cd, משתמשת ב-git -C, או מכילה החלפת פקודה נשארת בארגז החול. פקודות ה-git המוחרגות יכולות להגיע לכל מארח, לא רק לאלה שב-allowedDomains.

ssh, scp ו-rsync רגילים דרך SSH נכשלים מהסיבה שרשומת לקוח מסד הנתונים נותנת.

#לקוח מסד נתונים או כלי אחר שאינו HTTP נכשל בהגעה למארח מותר

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

הכישלון נראה כמו שגיאת רשת או פתרון שמות:

macOS: Operation not permitted, או שגיאת פתרון שמות כגון Could not resolve host
Linux ו-WSL2: Network is unreachable, או שגיאת פתרון שמות כגון Temporary failure in name resolution

כלי שמשתמש בפרוקסי נכשל אחרת כשהמארח שלו לא מותר. אתם מקבלים בקשת רשת, או שהכלי מקבל תשובת 403 מהפרוקסי.

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

{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

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

#פקודה נכשלת בהגעה לשרת ב-localhost

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

macOS: הגדירו את network.allowLocalBinding ל-true. פקודות בארגז החול יכולות אז להאזין על פורטי רשת ולהתחבר לכל פורט ב-localhost, שכולל כל שירות אחר שמאזין שם. שירות localhost שלא דורש אימות, כגון מנפה שגיאות, יכול אז לפעול עבור הפקודה מחוץ לארגז החול, ופקודה שמאזינה על כתובת שאינה loopback מקבלת חיבורים ממכונות אחרות
Linux ו-WSL2: ה-localhost של פקודה בארגז החול פרטי לפקודה הזו. הפקודה יכולה להאזין על פורט ולהגיע לשרתים שהיא עצמה הפעילה. חיבור ישיר ל-localhost או ל-127.0.0.1 לא מגיע לשרתים על המארח, ול-allowLocalBinding אין השפעה. הריצו את הפקודה שצריכה את השרת של המארח מחוץ לארגז החול עם excludedCommands, שם אין לה מגבלות מערכת קבצים או רשת. עבור חיבורים שעוברים דרך פרוקסי ארגז החול, ראו שמות מארח שנפתרים לכתובות מקומיות

הדוגמה הזו מפעילה את ההגדרה עבור macOS:

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

רשומת allowedDomains עבור localhost חלה על חיבורים שעוברים דרך הפרוקסי, ולכן היא לא משנה חיבור ישיר. Claude Code מגדיר NO_PROXY עבור פקודות בארגז החול כדי שהן יתחברו ל-localhost ישירות ולא דרך הפרוקסי. הרשומה גם חושפת כל פורט ב-localhost של המכונה שלכם לפקודה שכן משתמשת בפרוקסי. עבור שם מארח לפיתוח שמצביע על 127.0.0.1, ראו שם מארח מותר נדחה עם resolved to a loopback address.

#שם מארח מותר נדחה עם `resolved to a loopback address`

פרוקסי ארגז החול מסרב לשם מארח מותר שנפתר לכתובת מקומית, מה שמשפיע על שמות פיתוח כגון myapp.test שמצביעים על 127.0.0.1. הפקודה רואה תשובת 403 שגוף שלה מציין את סוג הכתובת, כגון Connection to myapp.test blocked: resolved to a loopback address.

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

{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

רשומת כתובת IP בלי פורט מאפשרת לפקודות בארגז החול להגיע לכל שירות שמאזין על הכתובת הזו.

לפני v2.1.284, הפרוקסי התחבר לכל כתובת ששם מארח מותר נפתר אליה.

#פקודות נדחות עם `Sandbox is required`

אם אתם דורשים את ארגז החול באמצעות sandbox.failIfUnavailable והוא נכשל באחת מהדרכים האלה אחרי ש Claude Code מתחיל, כל פקודה בארגז החול ש Claude מריץ נדחית עם ההודעה המוצגת. ההפעלה ממשיכה לרוץ, והפקודה שנדחתה לא רצה מחוץ לארגז החול:

Sandbox is required but failed to initialize: <reason>: Claude Code התחיל, אבל ארגז החול נכשל אחר כך באתחול. בצעו את הצעד שההודעה נותנת: Restart to retry. או Fix the sandbox settings to retry.
Sandbox is required (sandbox.failIfUnavailable) and stopped being available in this session: <reason>: ב Linux או ב WSL2, ארגז החול התחיל ו Claude Code מצא אחר כך תלות חסרה. תקנו את מה שהסיבה מציינת, למשל התקנת תלות חסרה, ואז הפעילו מחדש את Claude Code.

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

פקודות מוחרגות: פקודות שתואמות רשומת excludedCommands ממשיכות לרוץ מחוץ לארגז החול. כשאחת כותבת לנתיב filesystem.allowWrite מחוץ לתיקיית העבודה שלכם, הכתיבה עוברת דרך זרימת ההרשאות הרגילה. תחת ארגז חול שדורש מנהל, Claude Code מתעלם מרשומות מהגדרות המאגר
פקודות שאתם מקלידים בשורת ! shell-mode: ממשיכות לרוץ מחוץ לארגז החול. בהפעלת רקע, גם הן נדחות
ניסיונות חוזרים מחוץ לארגז החול: Claude Code מתעלם מהפרמטר dangerouslyDisableSandbox של ניסיון חוזר מחוץ לארגז החול

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

#`/sandbox` נכשל עם `Sandbox settings are overridden by a higher-priority configuration`

/sandbox מדפיס Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally. במקום לפתוח את הלוח שלו, כשרמת הגדרות גבוהה יותר מגדירה את sandbox.enabled, את sandbox.autoAllowBashIfSandboxed או את sandbox.allowUnsandboxedCommands. הלוח שומר את הבחירות שלכם ב .claude/settings.local.json, וערך שנשמר שם לא יכול לדרוס את הרמות האלה.

הגדרות מנוהלות ו --settings מדורגות מעל הגדרות מקומיות. כדי לראות איזו מהן ההפעלה הזו טענה, הריצו /status וקראו את שורת Setting sources:

Command line arguments: אם התחלתם את Claude Code עם --settings, בדקו אם הקובץ או ה JSON שהעברתם מגדירים אחד מהמפתחות האלה. אם כן, שנו את הערך שם, או התחילו את Claude Code שוב בלי המפתחות האלה.
Enterprise managed settings: הגדרות מנוהלות של הארגון שלכם נטענו. אם הן מגדירות אחד מהמפתחות האלה, אי אפשר לשנות את המפתח הזה מ /sandbox או מקובץ הגדרות שאתם שולטים בו, אז בקשו ממנהל המערכת.

#`/sandbox` מדפיס `Sandbox settings not changed`

השורה הזו אומרת ש /sandbox לא הצליח לשמור את הבחירה שעשיתם בלוח שלו אל .claude/settings.local.json של הפרויקט שלכם:

✗ Sandbox settings not changed: /home/you/project/.claude/settings.local.json couldn't be updated (EACCES). Start Claude Code in a project folder you can write to.

אם הסיבה בסוגריים היא EACCES, EPERM או EROFS, התחילו את Claude Code בתיקיית פרויקט שאפשר לכתוב אליה, ואז הריצו /sandbox שוב באותה הפעלה. אם הסיבה מתחילה ב Invalid JSON syntax in settings file, תקנו את ה JSON ב .claude/settings.local.json של הפרויקט שלכם, ואז הריצו /sandbox שוב.

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

{
  "sandbox": {
    "enabled": true
  }
}

זה מפעיל את מצב auto-allow. למצב הרשאות רגיל, הגדירו גם את sandbox.autoAllowBashIfSandboxed ל false. השינוי נכנס לתוקף בהפעלה הרצה שלכם בפקודת המעטפת הבאה ש Claude מריץ, ולשונית Mode של /sandbox מסמנת אז את המצב שבתוקף.

#מגבלות

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

#מגבלות אבטחה

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

[!WARNING]

התרת דומיינים רחבים כמו github.com יכולה ליצור נתיבים להוצאת נתונים. מכיוון שהפרוקסי מקבל את החלטת ההתרה לפי שם המארח שהלקוח סיפק, בלי לבדוק TLS, קוד שרץ בתוך ארגז החול יכול להשתמש בdomain fronting או בטכניקות דומות כדי להגיע למארחים מחוץ לרשימת ההיתר. אם מודל האיום שלכם דורש ערבויות חזקות יותר, הגדירו פרוקסי מותאם שמסיים TLS ובודק תעבורה, והתקינו את אישור ה CA שלו בתוך ארגז החול. בידוד רשת חזק יותר שמודע ל TLS הוא תחום פיתוח פעיל.

הסלמת הרשאות דרך שקעי Unix: הגדרת allowUnixSockets יכולה בלי כוונה להעניק גישה לשירותי מערכת שעלולים להוביל לעקיפת ארגז החול. לדוגמה, התרת גישה ל /var/run/docker.sock מעניקה למעשה גישה למערכת המארחת דרך שקע Docker. שקלו בזהירות כל שקעי Unix שאתם מתירים דרך ארגז החול.
הסלמת הרשאות במערכת הקבצים: הרשאות כתיבה רחבות מדי במערכת הקבצים יכולות לאפשר מתקפות הסלמת הרשאות. התרת כתיבה לתיקיות שמכילות קבצי הפעלה ב $PATH, לתיקיות הגדרות מערכת, או לקובצי הגדרות מעטפת של המשתמש כמו .bashrc או .zshrc יכולה להוביל להרצת קוד בהקשרי אבטחה שונים, כשמשתמשים אחרים או תהליכי מערכת ניגשים לקבצים האלה.
חוזק ארגז החול ב Linux: המימוש ב Linux מספק בידוד חזק של מערכת הקבצים והרשת, אבל כולל מצב enableWeakerNestedSandbox שמאפשר לו לעבוד בתוך סביבות Docker בלי מרחבי שמות מורשים. האפשרות הזו מחלישה את האבטחה במידה ניכרת, ויש להשתמש בה רק כשבידוד נוסף נאכף בדרך אחרת.
Apple Events ב macOS: ארגז החול של macOS חוסם Apple Events כברירת מחדל. ההגדרה allowAppleEvents מסירה את ההגבלה הזו כדי שכלים כמו open ו osascript יעבדו, אבל היא מסירה את בידוד הרצת הקוד: פקודות בארגז החול יכולות להפעיל יישומים אחרים מחוץ לארגז החול בלי בקשה מהמשתמש, ויכולות לשלוח פקודות AppleScript ליישומים שרצים, בכפוף לבקשת הסכמת האוטומציה של macOS לכל יישום (TCC). היא מכובדת רק מהגדרות משתמש, מהגדרות מנוהלות או מהגדרות CLI. הגדרות פרויקט לא יכולות להפעיל אותה.
שירותי Mach ו XPC ב macOS: פקודות בארגז החול יכולות להגיע אל מחוץ לארגז החול לכל שירות שאתם רושמים ב network.allowMachLookup, וארגז החול לא מגביל את מה שהשירותים האלה עושים עבור הפקודות האלה.
מרחבי שמות משתמש ב Linux וב WSL2: כברירת מחדל, פקודות בארגז החול לא יכולות ליצור מרחבי שמות משתמש. אם מגדירים את allowNestedUserNamespaces ל true, מכבים גבול אבטחה: קוד מפקודה בארגז החול יכול בסוף לרוץ מחוץ לארגז החול. לפני שמפעילים את ההגדרה הזו, קראו את האזהרה בChromium או Podman ללא root נכשלים בתוך ארגז החול ב Linux.

#היקף

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

שימוש במחשב: כש Claude פותח יישומים ושולט במסך שלכם, הוא רץ על שולחן העבודה האמיתי שלכם ולא בסביבה מבודדת. בקשות הרשאה לכל יישום משמשות שער לכל יישום. ראו שימוש במחשב ב CLI או שימוש במחשב ב Desktop.
תת סוכנים: תת סוכנים רצים באותו תהליך כמו הפעלת האב ומשתמשים באותה הגדרת ארגז חול. פקודות Bash בתוך תת סוכן רצות בארגז החול כשארגז החול מופעל בהפעלת האב.
הפעלות רקע: הפעלת רקע רצה בתהליך משלה, ופקודות Bash שלה רצות בארגז החול כשההגדרות שלה מפעילות ארגז חול.
גבול סביב כל התהליך: כדי לשים גם את התהליכים במה רץ מחוץ לארגז החול מאחורי גבול, הריצו את Claude Code (מצב מקומי) בתוך סביבת הריצה של ארגז החול עם רשימת היתר רשת שמוגבלת למארחים שאתם מאשרים, או בdev container עם סקריפט חומת האש שלו. עבור שירות הרקע וההפעלות שהוא מארח, ראו הרצת Claude Code מאחורי מפעיל ארגוני.
Mods: mod הוא תוסף שמריץ קוד משלו בתוך Claude Code, ותהליך ש mod מתחיל רץ מחוץ לארגז החול. ראו מה mod יכול להגיע אליו.

[!WARNING]

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

#ראו גם

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