21. פתרון תקלות נפוצות

חלק ה׳: עזרהפרק 21 מתוך 23זמן קריאה: כ-9 דקות

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

הצעד הראשון לכל תקלה: claude doctor

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

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

אם אתם לא בטוחים לאן לפנות, /doctor ו-/mcp (לבדיקת חיבורי MCP) הם תמיד מקום טוב להתחיל בו.

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

הריצו claude doctor או /doctor: רוב התקלות מוסברות שם ישירות, כולל הצעת תיקון.
פתחו טרמינל חדש: שינויים ב-PATH ובמשתני סביבה לא נכנסים לתוקף בטרמינל שכבר פתוח.
הריצו claude --safe-mode: אם התקלה נעלמת, הסיבה היא Hook, Plugin, MCP או CLAUDE.md — לא Claude Code עצמו.
בדקו את status.claude.com: חלק גדול משגיאות ה-API (500, 529) הן זמניות וצד-שרת, לא קשורות אליכם.
סגרו והפעילו מחדש: claude --resume באותה תיקייה מחזיר אתכם בדיוק לאותה שיחה, כך שאין מה להפסיד.

בעיות התקנה נפוצות

מה רואים	הסיבה הסבירה	הפתרון
`command not found: claude` / `'claude' is not recognized`	תיקיית ההתקנה לא ב-PATH	ראו "בדיקת PATH" למטה
`syntax error near unexpected token '<'` או שגיאת 403 מה-curl	סקריפט ההתקנה החזיר HTML או שגיאה במקום קוד	נסו שוב בעוד כמה דקות, או התקינו עם Homebrew (Mac) / WinGet (Windows)
`curl: (56) Failure writing output`	ההורדה נקטעה באמצע	בדקו חיבור ל-`downloads.claude.ai` ונסו שוב
`'irm' is not recognized` / `&& is not valid`	הודבקה פקודת ההתקנה של Shell לא נכון (PowerShell מול CMD)	ב-PowerShell: `irm https://claude.ai/install.ps1 \| iex`. ב-CMD: `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`
`running scripts is disabled on this system`	מדיניות הרצה של PowerShell חוסמת סקריפטים שנוצרו על ידי npm	`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`, או השתמשו במתקין הרשמי במקום ב-npm
`Killed` / קוד יציאה 137 בלינוקס	אין מספיק זיכרון פנוי (נדרש כ-512MB להתקנה)	הוסיפו Swap, סגרו תהליכים, או שדרגו למכונה עם יותר RAM
שגיאות TLS/SSL (`unable to get local issuer certificate`)	פרוקסי ארגוני בודק תעודות, או תעודות CA לא מעודכנות	עדכנו תעודות מערכת, או הגדירו `NODE_EXTRA_CA_CERTS` לתעודת הפרוקסי
כמה גרסאות מותקנות, התנהגות לא עקבית	התקנות כפולות (npm global, מתקן מקומי ישן, Homebrew)	`which -a claude` (Mac/Linux) או `where.exe claude` (Windows) כדי לאתר את כולן, ולהסיר את המיותרות

בדיקת PATH

המתקין שם את claude ב-~/.local/bin (Mac/Linux) או ב-%USERPROFILE%.localbin (Windows). אם ההתקנה הצליחה אבל הפקודה לא נמצאת, הסיבה כמעט תמיד היא שהתיקייה הזו לא ב-PATH:

# macOS/Linux: בדיקה
echo $PATH | tr ':' 'n' | grep -Fx "$HOME/.local/bin"

# אם אין פלט, הוספה ל-Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# בדיקה
$env:PATH -split ';' | Select-String '.local\bin'

# הוספה אם חסר
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE.localbin", 'User')

אחרי כל שינוי ב-PATH, פתחו טרמינל חדש ובדקו עם claude --version.

התקנתם רק את תוסף ה-VS Code?

תוסף VS Code כולל עותק פרטי של ה-CLI בתוך התוסף, לשימוש חלונית הצ'אט שלו בלבד, ולא מוסיף אותו ל-PATH. אם אתם רוצים גם claude בטרמינל, צריך להתקין את הגרסה העצמאית בנפרד (ראו פרק 2: התקנה, התחברות ומנויים).

בעיות התחברות (Login)

מה רואים	הפתרון
התחברות נכשלת בלי סיבה ברורה	איפוס נקי: `/logout`, סגירה מלאה, ואז `claude` מחדש להתחברות מהתחלה
`OAuth error: Invalid code`	הקוד פג תוקף או הועתק חלקית. הקישו `Enter` לניסיון חוזר, או `c` להעתקת הכתובת המלאה ופתיחה ידנית בדפדפן
`403 Forbidden` אחרי התחברות	ב-Pro/Max: ודאו שהמנוי פעיל ב-claude.ai/settings. בחשבון Console: ודאו תפקיד "Claude Code" או "Developer"
`This organization has been disabled` למרות מנוי פעיל	משתנה סביבה `ANTHROPIC_API_KEY` ישן דורס את ההתחברות למנוי. הריצו `unset ANTHROPIC_API_KEY` (או `Remove-Item Env:ANTHROPIC_API_KEY` ב-PowerShell) ובדקו קובצי פרופיל של ה-Shell
הדפדפן לא נפתח אוטומטית ב-WSL2/SSH/קונטיינר	הדפדפן מציג קוד במקום להפנות אוטומטית — הדביקו אותו בטרמינל. אם שום דבר לא קורה, נסו `claude auth login` שקורא את הקוד מקלט ישיר
מבקש התחברות מחדש שוב ושוב	בדקו ששעון המערכת מדויק — אימות טוקן תלוי בזמן נכון

כש-CLAUDE.md, Hooks או MCP "לא עובדים"

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

פקודה	מראה
`/context`	כל מה שתופס מקום בהקשר: הנחיות מערכת, כלים, MCP, קובצי זיכרון, Skills, שיחה
`/memory`	מיקומי קובצי CLAUDE.md בכל ההיקפים, עם קישור לעריכה
`/hooks`	כל ה-Hooks הפעילים, מקובצים לפי אירוע
`/mcp`	שרתי MCP מחוברים וסטטוס שלהם
`/permissions`	כללי allow/deny שבתוקף כרגע
`/status`	אילו מקורות הגדרות פעילים, כולל האם יש managed settings

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

תסמין	סיבה	פתרון
Hook לא רץ אף פעם	`matcher` הוא מערך JSON, לא מחרוזת, או כתוב באותיות קטנות	מחרוזת אחת עם `\|`, למשל `"Edit\|Write"`. שמות כלים תמיד עם אות ראשונה גדולה: `Bash`, `Edit`
Hook מוגדר בקובץ נפרד ולא פועל	אין קובץ Hooks עצמאי לפרויקט או למשתמש	Hooks נכנסים תחת המפתח `"hooks"` בתוך `settings.json` עצמו
הגדרות גלובליות מתעלמות מהן	ההגדרה נוספה ל-`~/.claude.json` במקום ל-`~/.claude/settings.json`	`~/.claude.json` הוא מצב UI פנימי. `permissions`, `hooks` ו-`env` שייכים ל-`settings.json`
Skill לא מופיע ב-`/skills`	הקובץ הוא `.claude/skills/name.md` בודד, לא תיקייה	נדרשת תיקייה עם `SKILL.md` בפנים: `.claude/skills/name/SKILL.md`
שרת MCP ב-`.mcp.json` לא נטען	הקובץ נמצא בתוך `.claude/`, או שהשרתים תחת מפתח `servers` במקום `mcpServers`	`.mcp.json` בשורש הפרויקט, עם מפתח `mcpServers`
Subagent מתעלם מ-CLAUDE.md	הסוכנים המובנים Explore ו-Plan לא טוענים CLAUDE.md כלל	כתבו את ההוראה החשובה בפרומפט שמפעיל אותם, במקום להסתמך על CLAUDE.md

בדיקת השוואה נגד תצורה נקייה

אם לא מצאתם את הגורם, הריצו claude --safe-mode. הוא מבטל CLAUDE.md, Skills, Plugins, Hooks, שרתי MCP ופקודות מותאמות לסשן הזה בלבד. אם התקלה נעלמת, אחד מהם הוא הגורם — הפעילו אותם בחזרה אחד-אחד כדי לאתר מי.

בעיות ביצועים

תסמין	מה לעשות
שימוש גבוה ב-CPU או זיכרון	`/compact` באופן קבוע, הוספת תיקיות בנייה גדולות ל-`.gitignore`, סגירה והפעלה מחדש בין משימות גדולות
זיכרון נשאר גבוה גם אחרי זה	`/heapdump` כותב תמונת מצב וקובץ אבחון ל-Desktop. שתפו רק את קובץ ה-diagnostics ב-GitHub Issue — קובץ ה-heapsnapshot מכיל את כל השיחה
`Autocompact is thrashing`	קובץ או פלט גדול ממלא מחדש את ההקשר מיד אחרי סיכום. בקשו לקרוא את הקובץ בחלקים, הריצו `/compact` עם מיקוד, או העבירו את העבודה ל-Subagent
תקיעה או קיפאון מוחלט	`Ctrl`+`C` לניסיון ביטול. אם לא עוזר, סגרו את הטרמינל — `claude --resume` מחזיר לאותה שיחה בלי לאבד כלום
חיפוש קבצים לא מוצא מה שאמור	ה-`ripgrep` המובנה אולי לא רץ במערכת שלכם. התקינו `ripgrep` בעצמכם והגדירו `USE_BUILTIN_RIPGREP=0`
תוצאות חיפוש חלקיות ב-WSL	ביצועי דיסק בין מערכות קבצים. העבירו את הפרויקט ל-`/home/` במקום `/mnt/c/`, או השתמשו ב-Windows רגיל

Safe Mode: בידוד תקלה

claude --safe-mode פותח סשן שמבטל את כל ההתאמות האישיות בו זמנית — CLAUDE.md, Skills, Plugins, Hooks, שרתי MCP, ופקודות וסוכנים מותאמים. אימות, בחירת מודל, הכלים המובנים וההרשאות ממשיכים לעבוד כרגיל, וגם Hooks ומדיניות ארגוניים (managed) עדיין חלים.

זו הדרך המהירה ביותר לענות על השאלה "האם זה קלוד עצמו, או משהו שהתאמתי?" אם התקלה נעלמת ב-Safe Mode, אחד מהמרכיבים שהוא ביטל הוא הגורם. השלב הבא הוא להחזיר אותם בהדרגה, או להשתמש בבדיקות הממוקדות בטבלה למעלה כדי לצמצם את החשד.

מתי ואיך לדווח

פקודה	מתי משתמשים
`/bug [תיאור]`	דיווח על באג או שיתוף שיחה. בוחרים כמה היסטוריה לכלול, ומאשרים במסך הסכמה לפני שנשלח משהו. מכונה גם `/share`
`/feedback [תיאור]`	משוב כללי על המוצר. אותו דיאלוג בדיוק כמו `/bug`

אם אתם מחוברים לחשבון Anthropic ישיר, הדיווח נשלח ל-Anthropic. עם ספק צד שלישי (Bedrock, Vertex, Foundry) או בלי אימות Anthropic, הדוח נשמר מקומית תחת ~/.claude/feedback-bundles/ ואתם מעבירים אותו בעצמכם. אפשר לכבות את הפקודה לגמרי עם משתנה הסביבה DISABLE_FEEDBACK_COMMAND=1.

לבעיה טכנית מתועדת וספציפית (לא רק "זה לא עובד"), פתחו issue ב-GitHub עם מערכת ההפעלה, הפקודה שהרצתם והפלט המלא. לבעיית חשבון, מנוי או חיוב, פנו לתמיכת Anthropic דרך claude.ai → לחיצה על הראשי תיבות בפינה → Get help.

לוג מפורט לאבחון עמוק

claude --debug (או /debug [תיאור הבעיה] בתוך שיחה) מפעיל רישום מפורט ושומר אותו ב-~/.claude/debug/<session-id>.txt. שימושי במיוחד לתקלות Hooks: הלוג מראה כל אירוע, אילו matchers נבדקו, וקוד היציאה של כל handler. לבעיות MCP ספציפית, claude --debug=mcp מציג גם את ה-stderr של כל שרת.

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

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

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

סשן כזה לא טוען שום הגדרות משתמש או פרויקט (managed settings ארגוניים עדיין חלים). אם התקלה נעלמת שם, הסיבה נמצאת ב-~/.claude או ב-.claude של הפרויקט — מחזירים קבצים אחד-אחד כדי לאתר מי.

בדיקת ספריות חסרות בלינוקס

שגיאה כמו Error loading shared library libstdc++.so.6 אחרי התקנה מעידה לרוב על גרסת בינארי לא מתאימה (musl מול glibc). ldd --version מזהה איזה libc יש במערכת, ו-ldd "$(command -v claude)" | grep "not found" מאתר ספריות חסרות ספציפיות.

שגיאות שרת נפוצות מה-API

שגיאות כמו API Error: 500 ו-API Error: Repeated 529 Overloaded errors הן כמעט תמיד זמניות וצד-שרת — לא קשורות להגדרות שלכם. בדקו status.claude.com, המתינו רגע ונסו שוב; 529 אפילו לא נספר במכסת השימוש שלכם. אם מודל מסוים עמוס במיוחד, קלוד Code עשוי להציע להחליף אליו עם /model. שגיאת 429 קשורה למגבלות שימוש — ראו פרק 8: מודלים, רמות מאמץ, עלויות ומגבלות שימוש.

מקלדת ואחסון: macOS Keychain

ב-Mac, פרטי ההתחברות נשמרים ב-Keychain. אם הוא נעול (למשל בסשן SSH) או שהסיסמה לא מסונכרנת, קלוד Code שומר זמנית לקובץ טקסט גלוי ב-~/.claude/.credentials.json. claude doctor מזהה מצב כזה ומציע לפתוח את ה-Keychain; אחרי שהוא כתוב, /logout ואז /login מעבירים את ההתחברות בחזרה להצפנה.

בקצרה

לכל תקלה: קודם claude doctor (מהטרמינל) או /doctor (בתוך שיחה).
בעיות התקנה נפוצות: PATH לא מוגדר, התקנות כפולות, ופקודת ההתקנה הלא נכונה לסביבה (PowerShell מול CMD).
הגדרה "לא עובדת"? /context מראה מה באמת נטען. /hooks, /mcp, /permissions ו-/status מפרטים לפי נושא.
claude --safe-mode מבטל את כל ההתאמות האישיות לסשן אחד — הדרך המהירה לבודד אם התקלה מגיעה מהתאמה שלכם או מ-Claude Code עצמו.
דיווח: /bug או /feedback בתוך שיחה, ו-GitHub Issues לבעיה טכנית מתועדת.

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