🔧 פרק 13

איתור תקלות ופתרון בעיות נפוצות

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

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

#1. ממשק הניהול בדפדפן אינו נפתח

התסמין: גלישה לכתובת http://127.0.0.1:3100 מחזירה שגיאת "לא ניתן להתחבר לאתר" (Connection Refused).

אבחון ופתרון:

1. ודאו ש-Docker Desktop פועל על המחשב.
2. בקשו מקלוד קוד:

   העתק

   בדוק האם קונטיינר GOWA רץ כרגע. אם הוא כבוי, הפעל אותו מחדש באמצעות docker compose up -d מבלי למחוק את תיקיית data.

3. אם הפורט תפוס על ידי תהליך אחר, בקשו מקלוד לבחור פורט פנוי (לדוגמה 3105) ולעדכן את קובץ ה-docker-compose.yml.

#2. קוד ה-QR מתחלף בלולאה אינסופית ולא מתחבר

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

אבחון ופתרון:

1. פתחו את אפליקציית וואטסאפ בטלפון > מכשירים מקושרים. אם ישנם מכשירים ישנים שאינם פעילים, נתקו אותם כדי לפנות מקום למכשיר החדש.
2. ודאו שקובץ ה-docker-compose.yml מכיל הגדרת volume תקינה:

   העתק

   volumes:
     - ./data:/app/storages

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

#3. GOWA מחובר בדפדפן אך בשיחה אין כלי וואטסאפ

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

אבחון ופתרון:

1. הקלידו בחלון קלוד קוד את הפקודה /mcp.
2. בדקו האם שרת whatsapp מופיע ברשימה. אם הוא מופיע באדום (Failed), קראו את הודעת השגיאה.
3. בצעו רענון מלא: צאו מקלוד קוד (Ctrl + C) והיכנסו שוב מתוך תיקיית הפרויקט (cd ~/gowa-ai && claude).

#4. שגיאת אימות 401 Unauthorized

התסמין: בלוגים של שרת ה-MCP או בתשובות הסוכן מופיעה שגיאת 401 Unauthorized.

אבחון ופתרון: אי התאמה בין סיסמת ה-Basic Auth שהוגדרה עבור קונטיינר ה-GOWA לבין הסיסמה שמועברת על ידי שרת ה-MCP.

בקשו מקלוד:

בדוק את קובץ .env ואת הגדרות ה-Basic Auth בקונטיינר GOWA. ודא שהסיסמה בלקוח ה-MCP תואמת בדיוק לסיסמה של מנוע ה-GOWA, ללא יצירת סיסמה חדשה.

#5. שגיאת שליחה: DEVICE / Not Logged In

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

אבחון ופתרון: קשר התקשורת בין GOWA לשרתי וואטסאפ נותק בטלפון.

1. בדקו באפליקציית הטלפון תחת מכשירים מקושרים האם המכשיר עדיין רשום.
2. אם המכשיר נותק, פתחו שוב את ממשק הדפדפן (http://127.0.0.1:3100) ובצעו סריקת QR חדשה.

#6. תיקיית הנתונים תופסת נפח דיסק גדול

התסמין: ספריית data/ תופסת מספר גיגה-בייט עקב צבירת קובצי מדיה ומסמכים שהורדו.

פתרון: בקשו מקלוד:

בדוק את גודל ספריית data/storages בתיקיית הפרויקט. הצג לי אילו ספריות מדיה זמניות ניתן לנקות בבטחה, מבלי למחוק את קובצי ה-session וה-database של החיבור.

#7. עדכון גרסת GOWA שבר את החיבור

התסמין: לאחר משיכת גרסה חדשה של תמונת ה-Docker, הכלים אינם מגיבים.

פתרון: בגרסאות GOWA v9 שרת ה-MCP שולב ישירות תחת פקודת rest בנתיב /mcp, ובוטלה תת-פקודת ה-mcp הנפרדת שהייתה קיימת בעבר. ודאו שהפקודה ב-Compose מוגדרת כ-rest --port=3000.

#מתי כן נדרשת התקנה מחדש

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

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