📘 תיעוד 107

הרצת Claude Code מאחורי משגר ארגוני

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

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

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

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

הערה:

CLAUDE_CODE_PROCESS_WRAPPER דורש Claude Code גרסה v2.1.208 או חדשה יותר. גרסאות קודמות מתעלמות מהמשתנה ומפעילות כל תהליך בלי עטיפה. ההגדרה המקבילה processWrapper דורשת v2.1.210 או חדשה יותר. גרסאות קודמות מתעלמות ממנה כמפתח לא מוכר, לא מפעילות משגר, ולא מדווחות על שגיאה.

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

#מה המשגר מכסה

כש CLAUDE_CODE_PROCESS_WRAPPER מוגדר, Claude Code מפעיל כל אחד מהתהליכים הבאים דרך המשגר שלכם:

• שירות הרקע ש claude agents וסשני רקע מפעילים לפי דרישה.
• מארח הטרמינל וסשן Claude Code בתוך כל שורה בתצוגת סוכן, כולל סשני ההמתנה החמה שהשירות מחזיק מוכנים.
• סשנים שהשירות מפעיל מחדש אחרי עדכון או קריסה.
• ההפעלה מחדש ש Claude Code מבצע לעצמו כדי לסיים התקנת עדכון, כולל פעולת ההפעלה מחדש לעדכון של תצוגת סוכן.
• תהליכי הסשן שRemote Control מפעיל. דורש Claude Code גרסה v2.1.210 או חדשה יותר.
• סשני חבר הצוות בחלונית המפוצלת שצוותי סוכן מפעילים ב tmux או ב iTerm2. חלוניות חבר צוות הן אינטראקטיביות ולא תהליכי רקע, אבל Claude Code מפעיל אותן מהבינארי שלו, ולכן המשגר מכסה אותן. דורש Claude Code גרסה v2.1.210 או חדשה יותר.

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

#תהליכים שמתחילים מחוץ למשגר

התהליכים הבאים לא מתחילים דרך המשגר:

• סשן שאתם מפעילים בעצמכם בטרמינל, שרץ לפי האופן שבו הפעלתם אותו. כדי לכסות את הסשנים האלה, שימו סקריפט בשם claude בתיקייה מוקדמת יותר ב PATH שמריץ את המשגר עם הבינארי האמיתי. אל תחליפו את הקישור הסימבולי המנוהל. שירות הרקע והסשנים שלו מתחילים בלי חיפוש ב PATH, ולכן שני המשגרים לא נערמים שם.
• סשן שנפתח מקישור עומק claude-cli://, שמתחיל בטרמינל חדש בלי המשגר שלכם. כדי למנוע מקישורי עומק לפתוח סשנים למשתמש חדש, הגדירו את disableDeepLinkRegistration ל "disable" לפני שהמשתמש הזה מריץ את Claude Code בפעם הראשונה. אצל משתמש שכבר יש לו מטפל רשום, קישורי עומק ממשיכים לפתוח סשנים, כי ההגדרה לא מסירה את המטפל.
• ההפעלה מחדש ש --worktree בשילוב עם --tmux מבצע: מרבב הטרמינלים מפעיל את החלונית הזו, לא הבינארי של Claude Code.
• מארח ה native-messaging שClaude in Chrome רושם: הדפדפן מפעיל אותו, לא הבינארי של Claude Code.

#שמות תהליכי עזר במנטרי תהליכים

כשמשגר מוגדר, ps ו Activity Monitor כבר לא מציגים את התוויות claude bg-pty-host ו claude bg-spare של Claude Code עבור תהליכי העזר ברקע, כי exec של המשגר בונה מחדש את רשימת הארגומנטים. אובדן התוויות הוא תופעת לוואי, לא הסתרה: התהליכים עצמם לא משתנים מלבד זאת, ו Claude Code מזהה את התהליכים שלו לפי נתיב הבינארי, אף פעם לא לפי שם התצוגה.

#הגדרת המשגר

1. כתיבת סקריפט המשגר

צרו סקריפט בר הרצה בנתיב מוחלט, למשל /opt/corp/launcher. Claude Code מריץ אותו עם פקודת Claude Code המלאה כארגומנטים שלו, והסקריפט חייב להסתיים בקריאה ל exec "$@" כדי שהוא יחליף את עצמו ב Claude Code:

#!/bin/sh
# Your organization's setup: enter the sandbox, apply
# network controls, or inject credentials.
exec "$@"

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

הערה:

אם החלפתם בעבר את הקישור הסימבולי ~/.local/bin/claude במשגר שלכם, שחזרו את הקישור הסימבולי המקורי באותו שינוי. קישור סימבולי שהוחלף גורם לסשן העטוף הראשון להפעיל את שירות הרקע דרך שני המשגרים יחד, ומכניס את ההתקנה למצב מנוהל חיצונית: /doctor מדווח על כך, עדכון אוטומטי משאיר את הקובץ במקום, וניקוי גרסאות ישנות נשאר מושבת עד שהמתקין מנהל שוב את הנתיב הזה.

2. הגדרת CLAUDE_CODE_PROCESS_WRAPPER בהגדרות

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

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

{
  "env": {
    "CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"
  }
}

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

ההגדרה processWrapper נושאת את אותו ערך כמפתח הגדרות בעל שם ברמה העליונה. הגדירו אותה כשהארגון דוחף הגדרות כמפתחות נפרדים ולא כבלוק env. ההגדרה processWrapper דורשת Claude Code גרסה v2.1.210 או חדשה יותר. קובץ ההגדרות הבא מגדיר את אותו משגר דרך המפתח:

{
  "processWrapper": "/opt/corp/launcher"
}

CLAUDE_CODE_PROCESS_WRAPPER מקבל עדיפות כששניהם מוגדרים.

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

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

3. הפעלה מחדש של שירות הרקע ושל הסשנים

שירות רקע שרץ וכל סשני claude פתוחים קוראים את המשתנה פעם אחת בהפעלה, ולכן הם ממשיכים להפעיל תהליכים לא עטופים עד להפעלה מחדש. הריצו claude daemon stop --any כדי לעצור את השירות לפי דרישה. הפקודה הבאה שזקוקה לו, למשל claude agents, מפעילה אחד עטוף. אחר כך הפעילו מחדש את סשני claude הפתוחים.

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

4. אימות

הריצו /status בסשן: הרשומה Self-exec מציגה את פקודת ההפעלה שנפתרה ומזהירה כאשר שירות הרקע שרץ לא תואם לה. claude daemon status מדפיס את אותו מידע מהמעטפת, כולל אחרי ביטול הגדרת המשתנה, כאשר /status כבר לא מציג את הרשומה.

#חוזה המשגר

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

• סיימו ב exec "$@". משגר שמפצל תהליך בן ויוצא משאיר תהליך Claude Code יתום ששירות הרקע לא יכול לעקוב אחריו. תצוגת סוכן מסמנת סשן כזה ככושל עם הודעה שמציינת את המשגר, והשירות אוסף את מה שהמשגר השאיר אחריו.
• אל תשנו סדר, אל תבלעו, ואל תוסיפו לארגומנטים של Claude Code. הסירו את הארגומנטים של המשגר עצמו, שמגיעים ראשונים, והעבירו את השאר ל exec כפי שהגיע.
• העבירו כל משתנה סביבה שעבר בירושה אל exec. הוספת משתנים, למשל אישורים שהוזרקו, תקינה. השמטת משתנים שעברו בירושה לא תקינה.
  • אסימוני האימות של כל סשן, בחירת המודל והספק, ו CLAUDE_CODE_PROCESS_WRAPPER עצמו, כולם עוברים בסביבה שעברה בירושה, ולכן משגר שבונה אותה מחדש מרשימת היתר שובר את הסשנים שהוא מפעיל, ו /status מדווח על אי התאמה של המשגר.
  • אם המשגר חייב להיכנס למרחב שמות או לארגז חול שמאפס את הסביבה, ייצאו מחדש את הסביבה שעברה בירושה בתוכו כלשונה.
• הגיעו ל exec בתוך בערך שלוש שניות בכל פעם שהמשגר רץ. סשן רקע יכול להריץ את המשגר שלוש פעמים ברצף לפני הפלט הראשון שלו. בצעו עבודה איטית, למשל חילופי כניסה יחידה, בעצלנות או ממטמון, ותנו לכל שלב שממתין לרשת מגבלת זמן משלו.
• סבלו הפעלה מתוך עצמכם. Claude Code מפעיל את המשגר על כל הפעלה עצמית מקוננת, ולכן משגר שתופס משאב בלעדי חייב לזהות שהוא כבר מחזיק בו.
• אל תכתבו לטרמינל או לפלט הסטנדרטי לפני ש Claude Code מתחיל. כל מה שמודפס לפני exec מדווח כסיבת הקריסה אם הסשן מת לפני האתחול. טקסט בפלט הסטנדרטי מגיע גם לתוכנית שקוראת את הפלט של Claude Code, למשל סקריפט שמנתח תוצאות של claude -p.
• אל תסתמכו על אופן האיות של ארגומנטים. ערך של דגל יכול להגיע כארגומנט נפרד, --flag value, או מחובר לדגל, --flag=value. הצורה שדגל משתמש בה יכולה להשתנות בין גרסאות.
• הריצו את exec מהתיקייה שבה המשגר התחיל. Claude Code עובד בתיקייה שבה הוא מתחיל, ולכן משגר שמחליף תיקייה יכול להתחיל סשן בפרויקט הלא נכון. אם המשגר חייב להיכנס למרחב שמות או לארגז חול שמאפס את תיקיית העבודה, חזרו לתיקיית ההתחלה בתוכו, לפני ה exec.
• אל תקראו קלט סטנדרטי. פקודה שקוראת אותו לפני ה exec, למשל פקודה שמבקשת סיסמה, יכולה להמתין לקלט שלא מגיע ולהשאיר את הסשן תקוע. היא יכולה גם לקחת קלט שנועד ל Claude Code, ואז הסשן יכול לרוץ בלי הקלט הזה ולא לדווח על שגיאה. הפנו את הקלט של פקודה כזו מ /dev/null.
• קראו לתוכניות אחרות לפי נתיב מוחלט. המשגר יכול להתחיל עם PATH שחסרות בו התיקיות שפרופיל המעטפת שלכם מוסיף.

#פורמט ערך המשגר

CLAUDE_CODE_PROCESS_WRAPPER וההגדרה processWrapper מקבלים את אותו פורמט. אצל רוב המשגרים, הערך הוא הנתיב המוחלט של הסקריפט, כמו /opt/corp/launcher.

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

• רווח לבן מפריד אסימונים, ומירכאות כפולות מקבצות אסימון שמכיל רווחים. מירכה בודדת היא תו רגיל, ולכן 'a b' הוא שני אסימונים.
• ערך שמתחיל ב [ נקרא כמערך מחרוזות JSON, למשל ["/opt/corp/launcher", "--profile", "cc"].
• תחביר מעטפת לא עובד: אין הרחבת משתנים ואין globbing, ואופרטור לא מצוטט כמו ;, |, &, או $( נדחה כשגיאת תצורה ולא מפורש מחדש.

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

בקובץ הגדרות, כתבו את צורת המערך בתוך מחרוזת JSON וצטטו בבריחה את המירכאות שלה: "[\"/opt/corp/launcher\", \"--profile\", \"cc\"]".

#העברת ארגומנטים למשגר

כתבו את הארגומנטים של המשגר עצמו אחרי הנתיב שלו בערך, והסירו אותם בסקריפט לפני הקריאה ל exec. הם מגיעים לסקריפט ראשונים, לפני פקודת Claude Code. הסקריפט הבא, שנכתב עבור הערך /opt/corp/launcher --profile cc, שומר את שם הפרופיל ואז מסיר את שני הארגומנטים עם shift:

#!/bin/sh
if [ "$1" = "--profile" ]; then
  profile="$2"
  shift 2
fi
# Your organization's setup for "$profile".
exec "$@"

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

#הקשר ל CLAUDE_CODE_SHELL_PREFIX

CLAUDE_CODE_PROCESS_WRAPPER עוטף את התהליכים של Claude Code עצמו ומעביר את הפקודה כאסימוני argv נפרדים כדי שהמשגר יבצע exec. CLAUDE_CODE_SHELL_PREFIX עוטף את פקודות המעטפת ש Claude מריץ בשמכם, למשל קריאות לכלי Bash, הוקים, והפקודות שמפעילות שרתי MCP ב stdio, ומעביר כל אחת כמחרוזת מצוטטת למעטפת יחידה ב $1 כדי שהעטיפה תעריך אותה מחדש. משגר שנכתב לאחד לא עובד בתור השני.

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

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