מדריך קלוד קוד בעברית
לאתר הראשי כל המדריכים קלאודפלייר קלוד דסקטופ גרוק CLI גרוק בוט MCP קרסור וואטסאפ OpenClaw n8n בענן n8n בהתקנה עצמית

תיעוד 55

ניפוי שגיאות בהגדרות שלך

אבחן מדוע CLAUDE.md, הגדרות, hooks, שרתי MCP או skills אינם נכנסים לתוקף. השתמש ב-/context, ב-/doctor, ב-/hooks וב-/mcp כדי לראות מה נטען בפועל.

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

לבעיות התקנה, אימות וחיבוריות, ראה במקום זאת את פתרון בעיות התקנה והתחברות.

#ראה מה נטען ל-context

הפקודה /context מציגה את כל מה שתופס את חלון ההקשר (context window) בהפעלה הנוכחית, בחלוקה לפי קטגוריות: system prompt, כלי מערכת (system tools), כלי MCP, תת סוכנים מותאמים אישית (custom subagents) יחד עם המקור שממנו כל אחד נטען, קובצי זיכרון (memory files), skills והודעות השיחה. הפעל אותה תחילה כדי לוודא אם קובצי ה-CLAUDE.md, הכללים (rules) או תיאורי ה-skills שלך קיימים בכלל. חלק ה-skills ב-/context כולל גם skills מובנים, שפקודת /skills אינה מציגה ברשימה שלה.

לפרטים נוספים על קטגוריה ספציפית, המשך עם הפקודה הייעודית:

פקודהמה מוצג
/memoryמיקומי קובצי זיכרון בטווחי המשתמש והפרויקט עם אפשרות לפתוח כל אחד מהם בעורך שלך, בתוספת גישה לתיקיית auto memory ומתג ההפעלה של auto memory
/skillsה-skills הזמינים ממקורות פרויקט, משתמש ותוספים (plugins)
/hooksהגדרות hook פעילות
/mcpשרתי MCP מחוברים והסטטוס שלהם
/permissionsכללי allow ו-deny שנפתרו ונמצאים בתוקף כעת
/doctorבדיקת תקינות של ההגדרות: תקינות ההתקנה, קובצי הגדרות לא תקינים, הרחבות שאינן בשימוש, שמות תת סוכנים כפולים באותה ספרייה, ותוכן CLAUDE.md שנשמר ב-git ש-Claude יכול להסיק מתוך בסיס הקוד, יחד עם תיקונים מוצעים
/debug [issue]הפעלת רישום ניפוי שגיאות (debug logging) עבור ההפעלה, והנחיה ל-Claude לאבחן באמצעות פלט היומן ונתיבי ההגדרות
/statusמקורות הגדרות פעילים, כולל האם הגדרות מנוהלות (managed settings) נמצאות בתוקף

אם קובץ זיכרון חסר בפירוט של /context, בדוק את מיקומו מול כיצד קובצי CLAUDE.md נטענים. קובצי CLAUDE.md בתת ספריות נטענים לפי דרישה כאשר Claude קורא קובץ באותה ספרייה באמצעות הכלי Read, ולא בעת תחילת ההפעלה.

אם /context מאשר שהקובץ נטען אך Claude עדיין אינו פועל לפי הוראה מסוימת, הבעיה קשורה ככל הנראה לאופן שבו ההוראה כתובה ולא לשאלה אם היא נטענה. CLAUDE.md עובד היטב עבור סוג ההנחיות שהיית נותן לחבר צוות חדש, כמו מוסכמות פרויקט, פקודות build והיכן שייכים קבצים.

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

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

#בדוק הגדרות שנפתרו

הגדרות מתמזגות בין טווחי managed, משתמש (user), פרויקט (project) ומקומי (local). הגדרות מנוהלות (managed settings) חלות ראשונות כאשר הן קיימות. מבין שאר ההגדרות, הטווח הקרוב יותר דורס את הרחב יותר לפי הסדר: מקומי, לאחר מכן פרויקט, ולאחר מכן משתמש. ניתן לקבוע חלק מההגדרות גם באמצעות דגלים בשורת הפקודה או משתני סביבה, הפועלים כשכבת דריסה נוספת. כאשר הגדרה מסוימת אינה נראית כאילו היא חלה, הערך שהגדרת נדרס בדרך כלל על ידי טווח אחר או על ידי משתנה סביבה.

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

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

#בדוק שרתי MCP

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

  • שרתים ברמת הפרויקט ב-.mcp.json דורשים אישור חד פעמי. אם בקשת האישור נסגרה, השרת יישאר מושבת עד שתאשר אותו מתוך /mcp.
  • שרת שנכשל בהפעלה מוצג כנכשל ב-/mcp. נתיבי קבצים יחסיים ב-command או ב-args הם גורם נפוץ לכך, מכיוון שהם נפתרים ביחס לספרייה שממנה הפעלת את Claude Code ולא ביחס למיקום של .mcp.json.
  • שרת שמוצג כמחובר אך מציג אפס כלים הופעל בהצלחה אך אינו מחזיר רשימת כלים. בחר Reconnect מתוך /mcp. אם המספר נשאר אפס, הרץ claude --debug=mcp וקרא את פלט ה-stderr של השרת ביומן ניפוי השגיאות בנתיב ~/.claude/debug/<session-id>.txt.

עבור מיקומי הגדרות וכללי טווח, ראה MCP.

#בדוק hooks

הרץ /hooks כדי לראות רשימה של כל hook שנרשם להפעלה הנוכחית, מקובצים לפי אירוע. אם hook שהגדרת אינו מופיע, הוא אינו נקרא: הגדרות hooks נכנסות תחת המפתח "hooks" בקובץ הגדרות, ולא בקובץ עצמאי.

אם ה-hook מופיע אך אינו מופעל, ה-matcher הוא בדרך כלל הסיבה. בדוק אותו מול הטעויות הבאות:

  • השדה matcher הוא מחרוזת בודדת המשתמשת ב-| כדי להתאים למספר שמות כלים, לדוגמה "Edit|Write". מפריד פסיק , הוא שווה ערך, כך ש-"Edit,Write" מתאים לאותם כלים. לפני גרסה v2.1.191, פסיק נפל להערכת regex וה-matcher לא התאים לעולם, לכן השתמש ב-| אם אינך בגרסה v2.1.191 עדיין.
  • שגיאת כתיב בשם הכלי מייצרת matcher שאינו מתאים לשום דבר, ולכן ה-hook נכשל בשקט.
  • ערך שהוא מערך (array) מהווה שגיאת סכמה (schema error): מערכת Claude Code מציגה הודעת שגיאה בהגדרות ודוחה את כל קובץ ההגדרות של המשתמש, הפרויקט או המקומי, claude doctor מדווח על כישלון האימות, ואף hook מאותו קובץ לא יופיע ב-/hooks. ב-הגדרות מנוהלות, מערכת Claude Code משמיטה את כל מפתח ה-hooks מהקובץ שמכיל את המערך, כך שאף אחד מה-hooks של אותו קובץ אינו חל. שאר ההגדרות של הקובץ עדיין חלות, ו-claude doctor מציג את המפתח שהושמט.

עריכות ב-settings.json נכנסות לתוקף בהפעלה הרצה לאחר השהיה קצרה של יציבות הקובץ (file-stability delay). אין צורך להפעיל מחדש. אם /hooks עדיין מציג את ההגדרה הישנה מספר שניות לאחר השמירה, הרץ שוב את /hooks כדי לרענן את התצוגה.

אם /hooks מציג את ה-hook אך הוא עדיין אינו מופעל, השלב הבא הוא לצפות בהערכת ה-hook בזמן אמת. התחל הפעלה עם claude --debug והפעל את קריאת הכלי. יומן ניפוי השגיאות מתעד כל אירוע, אילו matchers נבדקו, ואת קוד היציאה והפלט של ה-hook. ראה ניפוי שגיאות ב-hooks עבור מבנה היומן, ואת פתרון בעיות ב-hooks עבור דפוסי כשל נפוצים.

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

התחל עם claude --safe-mode, שמפעיל הפעלה כאשר כל ההתאמות האישיות מושבתות, כולל CLAUDE.md, skills, תוספים (plugins), hooks, שרתי MCP, ופקודות וסוכנים מותאמים אישית. אימות, בחירת מודל, כלים מובנים והרשאות פועלים כרגיל. אם הבעיה נעלמת ב-safe mode, אחד מהרכיבים הללו הוא הגורם; השתמש בבדיקות הממוקדות שלמעלה כדי לגלות איזה מהם. מצב בטוח (safe mode) עדיין מחיל hooks מנוהלים ומדיניות הגדרות מהארגון שלך. תוספים, skills, קובצי CLAUDE.md ושרתי MCP מנוהלים מושבתים.

אם הבעיה נמשכת במצב בטוח, או שההגדרות שלך עצמן חשודות, השווה מול הפעלה שאינה טוענת דבר מההתקנה הרגילה שלך. כוון את CLAUDE_CONFIG_DIR לספרייה ריקה כדי לעקוף את כל מה שנמצא תחת ~/.claude, והפעל מספרייה שאין בה תיקיית .claude, קובץ .mcp.json או CLAUDE.md כך שגם תצורת הפרויקט תידלג.

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

ההפעלה הנקייה אינה כוללת הגדרות משתמש או פרויקט, hooks, שרתי MCP, תוספים או זיכרון. בהפעלה הראשונה, צפה למסכי ההגדרה של הפעלה ראשונה, החל מבחירת ערכת נושא (theme). אם אתה רואה אותם, ספריית התצורה הנקייה נמצאת בתוקף. הפעלות מאוחרות יותר עם אותה ספרייה מדלגות על מסכים אלה מכיוון ש-Claude Code שומר שם את מצב ההגדרה הראשונית (onboarding).

  • הגדרות מנוהלות עדיין חלות אם הארגון שלך פורס אותן. Claude Code קורא פרופילי MDM, מדיניות registry ואת managed-settings.json ממיקומים מחוץ לספריית התצורה, ומושך מחדש הגדרות המנוהלות על ידי שרת עבור ההפעלה הנקייה ברגע שיש לו פרטי התחברות
  • תתבקש להתחבר שוב

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

#בדיקת סיבות נפוצות

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

תסמיןסיבהתיקון
Hook לא מופעל לעולםmatcher הוא מערך JSON במקום מחרוזתהשתמש במחרוזת בודדת עם | כדי להתאים למספר כלים, לדוגמה "Edit|Write". ראה דפוסי matcher.
Hook לא מופעל לעולםmatcher משתמש ב-, כמפריד בגרסה שקדמה ל-v2.1.191Claude Code בגרסה v2.1.191 ומעלה מתייחס ל-, כמפריד רשימה בדומה ל-|. גרסאות קודמות מעריכות פסיק כתו מילולי, ולכן "Edit,Write" אינו תואם לשום דבר. השתמש ב-| במקום זאת, או שדרג את Claude Code.
Hook לא מופעל לעולםערך ה-matcher כתוב באותיות קטנות (lowercase), לדוגמה "bash"ההתאמה תלוית רישיות (case-sensitive). שמות הכלים מתחילים באות גדולה: Bash, Edit, Write, Read.
Hook לא מופעל לעולםה-hooks מוגדרים בקובץ עצמאי במקום ב-settings.jsonאין קובץ hooks עצמאי עבור תצורת פרויקט או משתמש. הגדר hooks תחת המפתח "hooks" ב-settings.json. רק תוספים (plugins) טוענים קובץ נפרד hooks/hooks.json. ראה הגדרת hooks.
הרשאות, hooks או משתני סביבה (env) שהוגדרו גלובלית זוכים להתעלמותהתצורה נוספה לקובץ ~/.claude.jsonהקובץ ~/.claude.json מחזיק את מצב היישום ומתגי ממשק המשתמש. permissions, hooks ו-env שייכים לקובץ ~/.claude/settings.json. אלו שני קבצים שונים.
ערך ב-settings.json נראה כאילו מתעלמים ממנואותו מפתח מוגדר ב-settings.local.jsonהקובץ settings.local.json דורס את settings.json, ושניהם דורסים את ~/.claude/settings.json. ראה קדימות הגדרות.
ה-skill אינו מופיע ב-/skillsקובץ ה-skill נמצא ב-.claude/skills/name.md במקום בתוך תיקייההשתמש בתיקייה שמכילה בתוכה קובץ SKILL.md: .claude/skills/name/SKILL.md.
ה-skill מופיע ב-/skills אך Claude לעולם אינו מפעיל אותול-skill מוגדר disable-model-invocation: true ב-frontmatter שלו, או שהתיאור שלו אינו תואם לאופן שבו אתה מנסח את הבקשהבדוק את התגית ב-/skills: תווית "user-only" מציינת ש-Claude לא יפעיל אותו בעצמו. ראה הפעלת skills.
נראה שיש התעלמות מהוראות CLAUDE.md בתת ספרייהקבצים בתת ספריות נטענים לפי דרישה, ולא בעת תחילת ההפעלההם נטענים כאשר Claude קורא קובץ באותה ספרייה באמצעות הכלי Read, ולא בעת ההפעלה ולא בעת כתיבה או יצירה של קבצים שם. ראה כיצד קובצי CLAUDE.md נטענים.
תת סוכן (subagent) מתעלם מהוראות CLAUDE.mdהסוכנים המובנים Explore ו-Plan מדלגים על CLAUDE.md. תת סוכנים מותאמים אישית טוענים אותו באותו אופן כמו השיחה הראשיתעבור Explore או Plan, נסח מחדש את ההוראה בבקשת ההאצלה שלך (delegating prompt). עבור תת סוכן מותאם אישית, שים הוראות קריטיות בגוף קובץ הסוכן, שהופך ל-system prompt של הסוכן. ראה מה נטען בעת ההפעלה.
לוגיקת ניקוי אינה רצה לעולם בסיום ההפעלהלא הוגדר hook מסוג SessionEndהוסף hook מסוג SessionEnd ב-settings.json. ראה את רשימת אירועי hook.
שרתי MCP ב-.mcp.json אינם נטענים לעולםהקובץ נמצא תחת .claude/, או שהשרתים שלו יושבים תחת מפתח עליון servers, כמו ב-mcp.json של VS Code, במקום mcpServersתצורת MCP של הפרויקט צריכה להיות בשורש המאגר בשם .mcp.json, ולא בתוך .claude/, כאשר השרתים מוגדרים תחת המפתח mcpServers. ראה הגדרת MCP.
שרתי MCP שנוספו תחת mcpServers ב-settings.json אינם מופיעים לעולםהקובץ settings.json אינו קורא מפתח בשם mcpServersהגדר שרתי פרויקט ב-.mcp.json בשורש המאגר, או הרץ claude mcp add --scope user עבור שרתים ברמת המשתמש. ראה הגדרת MCP.
שרת MCP של פרויקט נוסף אך אינו מופיעחלונית בקשת האישור החד פעמית נסגרהשרתים ברמת הפרויקט דורשים אישור. הרץ /mcp כדי לראות את הסטטוס ולאשר.
שרת MCP נכשל בהפעלה מספריות מסוימותcommand או args משתמשים בנתיב קובץ יחסיהשתמש בנתיבים מוחלטים עבור סקריפטים מקומיים. קובצי הפעלה שנמצאים ב-PATH שלך כמו npx או uvx עובדים כמו שהם.
שרת MCP מופעל ללא משתני הסביבה הצפוייםרשומת התצורה של השרת אינה מגדירה אותם, והם אינם בסביבה ש-Claude Code מעביר לשרתי stdio: הסביבה שלו עצמו, פחות המשתנים שהוא מסיר מתהליכי משנההגדר env ברמת השרת בתוך הרשומה שלו ב-.mcp.json, שאינה תלויה בסביבת ההפעלה או ב-workspace trust.
כלל deny מסוג Bash(rm *) אינו חוסם את /bin/rm או find -deleteכללי קידומת (prefix rules) מתאימים למחרוזת הפקודה המילולית, ולא לקובץ ההפעלה הבסיסיהוסף תבניות מפורשות עבור כל גרסה, או השתמש ב-PreToolUse hook או ב-sandbox לקבלת הבטחה קשיחה.

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

למידע מלא על כל תחום תצורה, ראה את הדף הייעודי: