📘 תיעוד 89

הפניה לטעינת תוספים

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

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

[!NOTE]

המקרים האלה מכוסים בדפים אחרים:

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

התחל בבדיקה לאיזה שלב תוסף הגיע לשלושת השלבים שתוסף מותקן עובר, או עבור לסעיף שמתאים למה שאתה רואה:

• תוסף שכיבית עדיין נטען: מציאת המקום שבו תוסף מופעל
• עדכון לא שינה דבר: גרסאות ועדכונים
• אתה מסתכל על הקבצים תחת ~/.claude/plugins/: מציאת תוספים בדיסק
• תוסף --plugin-dir לא נטען, או שתוסף באותו שם נטען במקומו: התנגשויות שמות
• תוסף תחת ~/.claude/skills/ או .claude/skills/ לא נטען, ואין שגיאה שאומרת למה: תוספי תיקיית skills שנחסמו על ידי הגדרות מנוהלות

#בדיקה לאיזה שלב תוסף הגיע {#check-which-stage-a-plugin-reached}

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

• מוצהר, בהגדרות: enabledPlugins אומר אילו תוספים צריכים להיות פעילים, ו extraKnownMarketplaces אומר אילו מרקטפלייסים צריכים להיות קיימים. כשאתה מריץ claude plugin marketplace add, Claude Code כותב את המרקטפלייס ל extraKnownMarketplaces בהגדרות המשתמש שלך וגם לדיסק
• הובא, בדיסק תחת ~/.claude/plugins/: הרשומות של מה ש Claude Code הביא, והקבצים שהובאו עצמם:
  • known_marketplaces.json רושם כל מרקטפלייס ש Claude Code הביא, עם source, installLocation, lastUpdated, ו autoUpdate. יש known_marketplaces.json אחד לכל משתמש, כך שמרקטפלייס שאתה מוסיף בפרויקט אחד זמין בכל פרויקט
  • installed_plugins.json רושם כל התקנה עם scope, installPath, ו version
  • cache/ מחזיק את קבצי התוסף
• נטען, בסשן שרץ: קבוצת התוספים ש Claude Code טען בהפעלה או ב /reload-plugins האחרון. שינויים בהגדרות או בדיסק לא מגיעים לשכבה הזאת עד שאתה מריץ /reload-plugins או מתחיל סשן חדש. לכן claude plugin update מסתיים ב Restart to apply changes. ועדכוני רקע מציגים לך Run /reload-plugins to apply

#תוספים ומרקטפלייסים שאינם בדיסק בתחילת הסשן

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

• מרקטפלייס שההגדרות מצהירות עליו אבל known_marketplaces.json חסר אותו: Claude Code משכפל אותו, ואז טוען מחדש תוספים ומוריד תוספים מופעלים שעדיין לא במטמון
• מרקטפלייס מוצהר שהמקור שלו השתנה בהגדרות: Claude Code מביא אותו מחדש מהמקור החדש ומציג Plugins changed. Run /reload-plugins to activate.

תוסף מופעל שאף אחד משני הנתיבים האלה לא הביא, ושאין לו תיקיית מטמון שמישה, מציג Plugin "<name>" not cached at <path> בלשונית Errors של /plugin. לתיקון, ראה Plugin "<name>" not cached at <path>.

#מציאת המקור של תוסף {#find-where-a-plugin-came-from}

לכל תוסף יש מזהה בצורה <name>@<origin>, וזה מה שאתה רואה בקובצי הגדרות וב claude plugin list --json. החלק שאחרי @ אומר מאיפה Claude Code מצא את התוסף:

לתוסף ממרקטפלייס, <name> הוא שם הרשומה ב marketplace.json. עבור @inline ו @skills-dir זה ה name במניפסט של התוסף.

שמות המקור בטבלה הזאת שמורים, ולכן אי אפשר לקרוא למרקטפלייס inline, skills-dir, או synced.

#שם הרשומה ושם המניפסט

לתוסף ממרקטפלייס יש שני שמות, והם יכולים להיות שונים:

• שם הרשומה ב marketplace.json: מפתח ההתקנה וההפעלה. זה מה שאתה כותב ב enabledPlugins, על שמו נקראת תיקיית המטמון, וזה מה ש claude plugin list מציג
• ה name במניפסט: השם שתחתיו רכיבי התוסף נמצאים במרחב שמות, ומה שהתנגשויות שמות משוות

#תוספים שמשותפים דרך מאגר

כדי לשתף תוסף דרך מאגר, רשום אותו תחת enabledPlugins ב .claude/settings.json או שים אותו תחת .claude/skills/. Claude Code לא סורק את תיקיית .claude/plugins/ של פרויקט.

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

#בדיקת אמון ומגבלות רכיבים לתוספי מאגר

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

• שרתי MCP שהוא מצהיר עליהם עוברים את אותו אישור לכל שרת כמו .mcp.json של פרויקט
• שרתי MCP שהוא מצהיר עליהם כחבילת MCP, קובץ .mcpb או .dxt, או מקובץ מחוץ לתיקיית התוסף, מדולגים. הצהר עליהם באופן inline, או בקובץ .mcp.json בתוך תיקיית התוסף
• מוניטורים ברקע לא נטענים

בדיקת האמון ומגבלות הרכיבים האלה לא חלות על תוסף תחת ~/.claude/skills/ שלך.

לכתיבת תוספי --plugin-dir ותוספי תיקיית skills, ראה יצירת תוספים.

#בדיקה למה תוסף מאגר לא נטען {#check-why-a-repository-plugin-didnt-load}

אם תוסף ב .claude/skills/ של המאגר שלך לא נטען, בדוק את הסיבות האלה:

• בתיקיית משנה: תוסף בשורש המאגר לא נטען. Claude Code קורא את .claude/skills/ של ספריית העבודה הראשית של הסשן, ובניגוד ל skills ולפקודות רגילים, לא מחפש בתיקיות הורה אחרי תוספים. הפעל משורש המאגר, או העבר את הסשן לשם עם /cd בגרסה v2.1.246 או מאוחר יותר
• מאפליקציית שולחן העבודה, ב worktree: התוסף נטען מ .claude/skills/ של ה checkout הראשי ולא מזה של ה worktree. ראה מה worktrees חולקים עם ה checkout הראשי
• בתיקייה שעדיין לא נתת בה אמון: התוסף נטען רק אחרי שאתה מאשר את תיבת הדו שיח של אמון במרחב העבודה לאותה תיקייה
• בארגון שמנהל את Claude Code: ראה תוספי תיקיית skills שנחסמו על ידי הגדרות מנוהלות

#תוספי תיקיית skills שנחסמו על ידי הגדרות מנוהלות {#skills-directory-plugins-blocked-by-managed-settings}

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

• התאמה אישית נעולה לתוספים: strictPluginOnlyCustomization מוגדר ל true או למערך שמציין סוג אחד או יותר של התאמה אישית לנעילה. כל התוסף מדולג כשסוג אחד כלשהו נעול, למשל mcp, יהיו אשר יהיו הרכיבים שיש לו.
• מקורות מרקטפלייס מוגבלים: רשימת היתר strictKnownMarketplaces בלי רשומת { "source": "skills-dir" }, או רשימת blockedMarketplaces עם רשומה אחת כזאת.

/plugin ו claude plugin list לא מציגים תוסף ולא שגיאה לתיקייה שדולגה. פקודות /<name>:<skill> והסוכנים שלו חסרים, וכך גם ה hooks ושרתי ה MCP שלו.

אלא אם skills הם בין הסוגים הנעולים, קובץ SKILL.md בשורש התיקייה עדיין נטען כ skill רגיל. במקרה הזה /<name> ממשיך לעבוד, ולשונית Installed של /plugin מציגה את ה skill הזה תחת Skills.

• אימות הסיבה: הרץ /status בסשן של Claude Code. אם שורת Setting sources מציינת Enterprise managed settings, שאל את המנהל אם אחת מההגדרות האלה חלה עליך. אם היא לא חלה, ראה בדיקה למה תוסף מאגר לא נטען לסיבות אחרות.
• טעינת כל התוסף: הוסף אותו למרקטפלייס שהארגון שלך מתיר, והתקן אותו משם. כדי לטעון אותו לסשן אחד במקום זאת, הפעל claude מהמעטפת עם --plugin-dir ונתיב התיקייה. זה עובד, אלא אם המנהל כיבה גם את הדגל הזה.

#תוספים שמסונכרנים מ claude.ai {#synced-plugins}

תוסף שאתה מפעיל לחשבון claude.ai שלך נטען גם ב Claude Code, לצד התוספים שאתה מתקין ממרקטפלייסים. זה כולל תוספים שהארגון שלך מפעיל לחברים שלו. כל אחד מהתוספים האלה נטען כ <name>@synced, בלי מרקטפלייס ובלי רשומת התקנה.

בסשני טרמינל, ה skills, הסוכנים, ה hooks, שרתי ה MCP ושרתי ה LSP של תוסף מסונכרן נטענים כולם, עם אותו אמון כמו תוסף ממרקטפלייס שהתקנת.

לרכיבים ש Cowork טוען, ראה את טבלת התמיכה ברכיבים ב claude.com.

תוספים מסונכרנים נטענים בסשני Cowork ובסשני טרמינל שבהם אתה נכנס עם חשבון claude.ai שלך:

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

#תזמון סנכרון בסשני Cowork בענן

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

#תזמון סנכרון בסשני טרמינל

מכיוון שסנכרון הטרמינל רץ ברקע, הוא יכול להסתיים אחרי שהסשן שלך כבר התחיל. כשהוא מוסיף, מעדכן, או מסיר תוסף מסונכרן בסשן אינטראקטיבי, אתה רואה Plugins changed. Run /reload-plugins to activate. הרץ /reload-plugins כדי לטעון את השינוי באותו סשן, או השאר אותו לפעם הבאה שתפעיל את Claude Code.

אם אתה מפעיל או מכבה תוסף לחשבון claude.ai שלך במהלך סשן טרמינל, Claude Code מוריד או מסיר אותו בפעם הבאה שתפעיל את Claude Code.

#דרישות כניסה לסנכרון בטרמינל

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

Claude Code לא מוריד ולא טוען תוספים מסונכרנים בסשני הטרמינל האלה, גם אחרי כניסה עם /login:

• סשן שבו ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, או סקריפט apiKeyHelper מספק את פרטי ההזדהות במקום הכניסה הזאת
• סשן שלא שולף דגלי יכולת מ Anthropic, למשל סשן שבו הגדרת CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
• סשן במצב bare, או סשן שאתה מתחיל עם --safe-mode
• סשן שאתה מתחיל עם רשימת --setting-sources שמשמיטה את user

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

#שליטה באילו תוספים מסונכרנים נטענים

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

• תוסף אחד: claude plugin disable <name>@synced במעטפת, ולשונית Installed של /plugin בסשן, שומרים שניהם "<name>@synced": false ב enabledPlugins ברמת המשתמש. כדי להשאיר את התוסף מחוץ לפרויקט בכל סביבה, הגדר את אותו מפתח ב .claude/settings.json של הפרויקט שנכלל בקומיט
• כל תוסף מסונכרן במחשב: הגדר syncClaudeAiPlugins ל false בהגדרות המשתמש שלך, או שהארגון שלך מגדיר אותו בהגדרות מנוהלות. Claude Code מפסיק להוריד, ובפעם הבאה שתפעיל אותו הוא מעביר את התוספים שכבר סונכרנו אל ~/.claude/plugins/.trash/ ולא טוען אותם יותר. אם הארגון שלך מכבה את Skills ב claude.ai, גם התוספים מפסיקים להסתנכרן
• תוסף שהארגון שלך דורש: תוסף שהארגון שלך מסמן כנדרש ב claude.ai נטען גם אם השבתת אותו קודם. claude plugin disable מסרב לו עם Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it., ו claude plugin list מסמן אותו required by your org

להסרת תוסף ב claude.ai, ראה ניהול תוספים מותקנים.

#מצא היכן תוסף מופעל

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

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

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

אם הגדרת תוסף ל-false ב-~/.claude/settings.json והוא עדיין נטען, ערך true במקור בעל עדיפות גבוהה יותר דורס את זה. השורה של התוסף ב-claude plugin list וב-/plugin מציגה Disabled in ~/.claude/settings.json but still loads , project settings enable it, which overrides your user setting. ההודעה מציינת את המקור שדרס אותך: project, project, gitignored עבור .claude/settings.local.json, cli flag, או managed.

כדי לצאת מתוסף שהפרויקט מפעיל במחשב שלך, הגדר את המזהה ל-false ב-.claude/settings.local.json, שיש לו עדיפות גבוהה יותר מקובץ הפרויקט.

#מופעל בהגדרות הפרויקט אבל לא מותקן

כאשר ה-true היחיד של תוסף נמצא ב-.claude/settings.json של הפרויקט, Claude Code לא מביא אותו למחשב שבו הוא לא מותקן, אלא אם לרשומת ה-marketplace שלו יש מקור בנתיב יחסי או שספריית seed כבר מחזיקה אותו. במקום זאת, לשונית Errors של /plugin מציגה Plugin "<name>" is enabled in project settings but isn't installed here.

תוסף בנתיב יחסי לא צריך רשומת התקנה כי הוא נטען מה-marketplace עצמו.

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

• הגדרות המשתמש שלך
• קובץ .claude/settings.local.json ש-git לא עוקב אחריו
• הדגל --settings
• הגדרות מנוהלות

#מצא תוספים בדיסק

Claude Code שומר קובצי תוספים ורשומות מצב תחת שורש תוספים אחד, שהוא ~/.claude/plugins אלא אם הגדרת CLAUDE_CODE_PLUGIN_CACHE_DIR. כל נתיב בטבלה יחסי לשורש הזה.

מכיוון ש-${CLAUDE_PLUGIN_ROOT} מצביע על ספריית גרסה, נתיב השורש של תוסף משתנה עם כל גרסה. שמור את הקבצים העמידים של תוסף ב-${CLAUDE_PLUGIN_DATA}.

#תוספים שנטענים במקום ותוספים שמועתקים

Claude Code טוען חלק מהתוספים במקום מהמיקום שבו אתה שומר אותם, ומעתיק את השאר למטמון, לפי המקור שלהם:

• תוספי --plugin-dir ותוספי ספריית skills: הספרייה נטענת במקום ולעולם לא מועתקת. ארכיון --plugin-url או קובץ .zip של --plugin-dir מחולץ קודם לספרייה זמנית של ההפעלה
• תוספים בנתיב יחסי ב-marketplace שהוספת מנתיב מקומי: התוסף נטען במקום מהנתיב שלו בתוך תיקיית ה-marketplace. העריכות שלך בספריית המקור נכנסות לתוקף בתחילת ההפעלה הבאה או ב-/reload-plugins, ואין צורך להעלות את הגרסה. תהליכי ה-hook של התוסף ושרתי MCP ו-LSP מקבלים CLAUDE_PLUGIN_ROOT שמצביע על ספריית המקור. לתלויות חבילות Node.js שלו, ראה מתי התקנת התלויות רצה
• תוספים ממקור command במצב link: הספרייה שהפקודה הדפיסה נטענת במקום, דרך קישורים ברשומת המטמון
• כל תוסף marketplace אחר: Claude Code מעתיק את התוסף אל cache/<marketplace>/<plugin>/<version>/ בהתקנה וטוען את העותק הזה. קבצים שמחוץ לספריית התוסף לא מועתקים, ולכן כאשר סקריפט בתוך תוסף שהועתק קורא נתיב שמעל שורש התוסף, כגון ../shared, הוא לא מוצא אותם

#נתיבים שיוצאים מספריית התוסף

בין שהתוסף נטען במקום ובין שהוא נטען מעותק במטמון, Claude Code לא מאפשר לו להצהיר על רכיבים מחוץ לספרייה שלו. הוא דוחה נתיב רכיב שנפתר מחוץ לשורש התוסף, בין שהנתיב מוצהר ב-plugin.json ובין שברשומת marketplace:

• נתיב שמצביע אל מחוץ לתוסף כפי שהוא כתוב, כגון ../shared-utils
• קישור סמלי שמוביל אל מחוץ לתוסף, מלבד קישורים בין תוספים בתוך marketplace אחד
• ב-macOS וב-Linux, נתיב שמכיל לוכסן הפוך במקום כלשהו בו, גם כאשר הנתיב נשאר בתוך התוסף. לכן רכיבים שהוצהרו עם נתיבי לוכסן הפוך נטענים ב-Windows בלבד, אז כתוב נתיבי רכיבים עם לוכסנים רגילים, כגון ./commands/deploy.md

נתיב שנדחה מופיע כשגיאת path escapes plugin directory, והתוסף נטען בלי הרכיב הזה.

#ניקוי של גרסאות קודמות

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

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

#תלויות חבילות Node.js

כאשר Claude Code מעתיק תוסף למטמון, הוא גם מתקין שם את תלויות חבילות Node.js של התוסף, כדי שה-hooks ושרתי ה-MCP של התוסף יוכלו לטעון אותן.

הסעיף הזה עוסק בחבילות npm ו-Bun שתוסף מצהיר עליהן ב-package.json שלו. לתוספים שתלויים בתוספים אחרים, ראה גרסאות תלות של תוספים.

#מתי התקנת התלויות רצה

Claude Code מתקין את התלויות בספריית הגרסה המועתקת בכל פעם שהוא יוצר ספרייה כזו:

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

לתוסף בנתיב יחסי שנטען במקום מ-marketplace שהוספת מנתיב מקומי, Claude Code לא מתקין את התלויות בספריית המקור. התקן אותן שם בעצמך, או מ-hook אל ${CLAUDE_PLUGIN_DATA}.

ההתקנה רצה רק כאשר ספריית השורש של התוסף מכילה גם package.json וגם קובץ נעילה נתמך.

קובץ הנעילה קובע איזה מנהל חבילות Claude Code מריץ:

אם תוסף מכיל יותר מאחד מקובצי הנעילה האלה, Claude Code משתמש בהתאמה הראשונה, ובודק לפי הסדר: bun.lock, npm-shrinkwrap.json, package-lock.json.

Claude Code מדלג על ההתקנה במקרי קובץ הנעילה האלה:

• bun.lockb: אי אפשר לבדוק את קובץ הנעילה הבינארי של Bun. כלול bun.lock בטקסט או קובץ נעילה של npm
• yarn.lock או pnpm-lock.yaml: החלף אותו בקובץ נעילה של npm
• קובץ נעילה בפורמט ש-Claude Code לא קורא: קובץ נעילה של npm צריך lockfileVersion של 2 או 3, ש-npm 7 ואילך כותב, ו-bun.lock צריך lockfileVersion שלא גבוה מ-2

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

לתוסף שמופץ דרך מקור npm, השתמש ב-npm-shrinkwrap.json, כי npm לא כולל את package-lock.json בחבילות שפורסמו.

#מגבלות על התקנת התלויות

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

• חבילות registry בלבד: כל תלות חייבת להיות חבילת registry שנעוצה בקובץ הנעילה לגרסה מדויקת. תוסף עם תלות git, GitHub, folder, workspace, או linked לא מקבל התקנה.
• הורדות https: קישור הורדה בקובץ הנעילה חייב להשתמש ב-https, אלא אם הוא מצביע על מאגר ה-npm ברירת המחדל של המשתמש המתקין.
• תיקיית התקנה נפרדת: מנהל החבילות רץ בתיקייה משלו שמחזיקה רק עותק של רשימת התלויות שנבדקה, כך ש-npm ו-Bun לא קוראים את .npmrc, .env, או bunfig.toml של התוסף. כאשר ההתקנה מצליחה, Claude Code מעביר את node_modules שנוצר אל התוסף.
• פתרון קפוא: ההתקנה משתמשת בדיוק בגרסאות שקובץ הנעילה נועץ, ו-Claude Code מדלג עליה כאשר package.json וקובץ הנעילה לא מפרטים את אותן תלויות
• בלי סקריפטי מחזור חיים: --ignore-scripts מונע הרצה של סקריפטים preinstall, install, ו-postinstall, כך שתלויות שבונות מודולים נייטיביים בסקריפטים האלה מורדות אבל לא מתקמפלות במהלך ההתקנה הזו
• בלי overrides או טלאים: תוסף ש-package.json שלו מגדיר overrides של npm לא מקבל התקנה מקובץ נעילה של npm, ותוסף שמגדיר patchedDependencies של Bun לא מקבל התקנה מ-bun.lock
• פסק זמן של 60 שניות: Claude Code עוצר התקנה שרצה יותר זמן ומתייחס אליה כנכשלת

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

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

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

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

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

/plugin ו-claude plugin list מציגים הערה על תוסף מופעל שהעותק שלו במטמון כולל קובץ נעילה ו-package.json שמפרט תלויות בזמן ריצה, אבל אין ספריית node_modules. ההערה אומרת אם ההתקנה לא הסתיימה או לא יכולה לרוץ עבור התוסף הזה. ראה רשומת פתרון הבעיות לגבי מה לעשות בכל מקרה.

כאשר ההתקנה האוטומטית לא יכולה לספק תלות, התקן אותה מ-hook אל ספריית הנתונים המתמשכים. זה כולל חבילות שצריכות את סקריפטי מחזור החיים שלהן כדי להיבנות, תלויות Python, תוספים שננעלו עם Yarn או pnpm, ותלויות שאינן חבילות registry, כגון תלויות git.

#גרסאות ועדכונים

אם מחבר של תוסף דחף קומיטים חדשים ו-claude plugin update מדפיס <name> is already at the latest version (<version>)., הגרסה ש-Claude Code מחשב לתוסף לא השתנתה, ולכן הקבצים של התוסף בדיסק לא משתנים.

Claude Code מחשב גרסה לכל תוסף שהוא מתקין, והגרסה הזו היא הדרך שבה הוא מזהה עדכון. claude plugin update ועדכון אוטומטי ברקע מחשבים את הגרסה שוב ולא מחליפים את העותק השמור במטמון כשהיא תואמת למה ש-installed_plugins.json רושם. עדכון שאתם מתחילים עדיין יכול לנסות שוב התקנת תלות שלא הושלמה באותו עותק.

הגרסה גם נותנת שם לתיקיית המטמון של התוסף.

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

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

#איך Claude Code מחשב את הגרסה

למרקטפלייס שהוספתם לפי מקור, Claude Code בוחר את הכלל לפי סוג ה-source של רשומת המרקטפלייס של התוסף. הפניית המרקטפלייס מפרטת את סוגי המקור. לכל סוג מקור ברשימה הזו חוץ מ-command:

1. שדה ה-version במניפסט של התוסף בא ראשון
2. אחר כך שדה ה-version ברשומת המרקטפלייס של התוסף
3. כשאף אחד מהם לא מוגדר, הגרסה מגיעה מסוג המקור:

Claude Code לא לוקח את הגרסה ממאגר שעוטף את נתיב ההתקנה, כמו ~/.claude שמנוהל ב-git.

למקור command, Claude Code תמיד גוזר את הגרסה ממה שהפקודה ייצרה: hash של 12 תווים בפני עצמו, או <manifest version>-<hash> כשהמניפסט מגדיר אחד. ה-version של רשומת המרקטפלייס לא נלקח בחשבון למקורות command. למה שה-hash מכסה, ראו מצב העתקה ומצב קישור.

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

#מתי Claude Code מרענן מרקטפלייס לפני התקנה

כשאתם מתקינים תוסף, Claude Code מחפש אותו בעותק המקומי שלו של קטלוג המרקטפלייס. אפשר להריץ /plugin install בסשן או claude plugin install במעטפת, ולנקוב בתוסף עם המרקטפלייס שלו או בלעדיו. הטבלה מראה אילו מהשילובים האלה מרעננים את העותק המקומי.

הרענון לפני התקנת name@marketplace לא תלוי בהגדרת העדכון האוטומטי של המרקטפלייס או ב-DISABLE_AUTOUPDATER.

כשהרענון נכשל, ההתקנה ממשיכה מהקטלוג השמור במטמון ו-claude plugin install מדווח marketplace not refreshed.

Claude Code מדלג על הרענון לפני התקנת name@marketplace כש:

• המרקטפלייס נוסף ממקור file או directory מקומי, או מוגדר בשורה בהגדרות עם מקור settings
• תיקיית seed מספקת את המרקטפלייס
• Claude Code ריענן את המרקטפלייס ב-30 השניות האחרונות
• הגדרתם CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
• הגדרות מנוהלות חוסמות את המרקטפלייס, ובמקרה הזה Claude Code גם מסרב להתקנה

#מתי עדכון אוטומטי רץ

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

הסשן הרץ שומר את הגרסאות שהוא טען, ואתם רואים Plugin updated: <name> · Run /reload-plugins to apply. גם אם תטענו מחדש וגם אם לא, הגרסאות החדשות נטענות בהפעלה הבאה שלכם.

#אילו מרקטפלייסים ותוספים מתעדכנים אוטומטית

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

1. autoUpdate ברשומת extraKnownMarketplaces שלו בקובץ הגדרות
2. autoUpdate ברשומת known_marketplaces.json שלו, שהמתג Enable auto-update תחת /plugin Marketplaces כותב. כשקובץ הגדרות גם מצהיר על המרקטפלייס תחת extraKnownMarketplaces, המתג כותב autoUpdate גם לרשומת ההגדרות הזו
3. ברירת המחדל: דלוק למרקטפלייסים הרשמיים של Anthropic כמו claude-plugins-official, כבוי ל-knowledge-work-plugins ול-first-party-plugins, דלוק למרקטפלייסים שנוספו מ-claude.ai, וכבוי לכל מרקטפלייס אחר

אם הגדרתם DISABLE_UPDATES=1, DISABLE_AUTOUPDATER=1, או CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, כל המעבר כבוי והמתג Enable auto-update מוסתר, אלא אם הגדרתם גם FORCE_AUTOUPDATE_PLUGINS=1. הפניית משתני הסביבה מכסה את ההשפעה הרחבה יותר של כל משתנה.

עדכון אוטומטי גם מדלג על תוסף שרשומת המרקטפלייס שלו מצהירה על headersHelper. התקנות ועדכונים שמסרבים לפקודה במקום לשאול מסביר מתי תוסף כזה מופיע בלשונית Errors של /plugin ואיך מעדכנים אותו משם.

כשתוסף שהועתק מתעדכן באמצע סשן, פקודות hook, מוניטורים, שרתי MCP ושרתי LSP ממשיכים להשתמש בנתיב של הגרסה הקודמת. הריצו /reload-plugins כדי להעביר hooks, שרתי MCP ושרתי LSP לנתיב החדש. מוניטורים דורשים הפעלה מחדש של הסשן.

#מתי מקור command רץ שוב

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

• בכל פעם שאתם מתקינים או מעדכנים את התוסף
• פעם אחת בכל סשן לכל תוסף מופעל שמקורו command, ברקע, זמן קצר אחרי שהסשן מתחיל. הריצה הזו לא תלויה בהגדרת העדכון האוטומטי של המרקטפלייס או ב-DISABLE_AUTOUPDATER
• בהפעלה או ב-/reload-plugins, כשהגרסה המותקנת של תוסף מופעל חסרה ממטמון התוספים

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

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

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

#התנגשויות שמות

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

1. תוסף שה-id שלו מופיע בהגדרות המנוהלות enabledPlugins, כ-true או false. עותק --plugin-dir ששם המניפסט שלו תואם לחלק השם של ה-id לא נטען, ואתם רואים --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings
2. תוסף --plugin-dir, --plugin-url, או CLAUDE_CODE_PLUGIN_DIRS מופעל. הוא מחליף תוסף מרקטפלייס מותקן או תוסף תיקיית skills באותו שם:
   • תוסף מרקטפלייס מותקן: מוחלף בשקט. claude plugin list עדיין מציג את שורת המרקטפלייס כמופעלת, כי השורה הזו משקפת את ההגדרות שלכם. רק הלוג ש-Claude Code כותב תחת ~/.claude/debug/ כשאתם מתחילים עם --debug רושם Plugin "<name>" from --plugin-dir overrides installed version
   • תוסף תיקיית skills: מוחלף עם שורה בלשונית Errors של /plugin שקוראת Not loaded , the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence
3. תוסף מרקטפלייס מותקן. תוסף תיקיית skills באותו שם מקבל את אותה שורת Not loaded, שמנקבת בתוסף המותקן
4. תוסף תיקיית skills. בין שניים כאלה, העותק תחת ~/.claude/skills/ נטען והעותק .claude/skills/ של הפרויקט נזרק, עם שורה שאומרת איזה נתיב האפיל עליו
5. תוסף שסונכרן מ-claude.ai. כשתוסף מופעל מכל מקור אחר תואם לשם שלו, Claude Code טוען את התוסף הזה ומדווח על העותק המסונכרן כלא נטען. כדי להשתמש בעותק של claude.ai, השביתו את העותק שלכם

מכיוון שהסדר משווה שמות מניפסט, תוסף --plugin-dir בשם hello-plugin מחליף את hello@example-marketplace כשהמניפסט של התוסף הזה גם אומר "name": "hello-plugin".

#Hooks כששני תוספים מופעלים חולקים שם

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

כדי לראות איזה עותק מחזיק את השם, הריצו /plugin בסשן שלכם ופתחו את לשונית Errors. הערה שם לעותק שה-hooks שלו נשארו בחוץ מנקבת בעותק שמחזיק את השם, ופרטי העותק שנשאר בחוץ מציגים את אותה הערה. ל-hooks של hooks/hooks.json ההערה מתחילה ב-Its hooks.json hooks do not run, ולמודול hooks היא מתחילה ב-Its hooks module does not load. ההערה דורשת Claude Code v2.1.296 או מאוחר יותר.

כדי להריץ את ה-hooks של העותק שנשאר בחוץ, השביתו או הסירו את העותק שמחזיק את השם, ואז הריצו /reload-plugins בסשן שלכם. הטעינה מחדש רושמת את ה-hooks של העותק שנשאר ומנקה את ההערה. כשהעותק שמחזיק את השם הוא אחד שההגדרות המנוהלות שלכם מדליקות, אי אפשר להשבית אותו, וה-hooks של העותק האחר נשארים כבויים כל עוד שניהם מותקנים.

#מניעת טעינה של תוסף לסשן בלבד

כדי שתוסף --plugin-dir לא יאפיל על שום דבר, או כדי לכבות אחד כשתהליך אב מעביר את הדגל בשבילכם, הגדירו את ה-id שלו ל-false בכל קובץ הגדרות. לתוסף ששם המניפסט שלו הוא hello-plugin, הרשומה היא "enabledPlugins": {"hello-plugin@inline": false}. תוסף לסשן בלבד שמושבת לא מאפיל, ולכן עותק המרקטפלייס או תיקיית ה-skills נטען.

#הצעדים הבאים

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