שילוב תוסף OpenClaw + QQ ותחקיר ניפוי תקלות ארוך במיוחד (כל התהליך)

AIDO ניפוי באגים
, ,
1

OpenClaw + תוסף QQ: שילוב ותחקיר ניפוי תקלות ארוך במיוחד (כל התהליך)

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

א. רקע ומטרה

המטרה הפעם הייתה לחבר את OpenClaw לערוץ QQ (מבוסס NapCat + התוסף openclaw_qq), ולהשיג:

  • שליחה/קבלה תקינה של הודעות ב-QQ בפרטי/בקבוצה
  • ניתוב שיחות ורישומים נראים ב-WebUI
  • מדיניות מנהלים/רשימה שחורה נשלטת (מניעת ניצול לרעה של Token)
  • תצורה שנשמרת בצורה יציבה ב-Control UI

ב. סביבה וציר זמן (בקירוב)

לפי חותמות הזמן בלוגים של ה-Gateway, הניפוי כיסה כמה שלבים, כאשר ניפוי תקלות רציף ובעצימות גבוהה נמשך בערך כמה שעות (כ~4+ שעות).

ג. תהליך עבודה מרכזי (לפי שלבים)

1) חיבור ערוץ QQ ובדיקות אינטגרציה בסיסיות

תחילה השלמתי פריסה בסיסית של תוסף QQ ושל NapCat:

  • התקנה והפעלה של התוסף openclaw_qq
  • פריסת NapCat באמצעות Docker
  • תיקון מצב החיבור של NapCat ל-Forward WS Server (כאשר OpenClaw מתחבר כלקוח)
  • לאחר יישור OneBot Token והחשבון, סטטוס ערוץ QQ חזר ל-OK

2) תיקון בעיות שיחה וניתוב

במהלך בדיקות האינטגרציה הופיעה תופעה שבה “שיחות QQ מתערבבות עם השיחה הראשית/שיחות TG”, וביצעתי תיקון ניתוב:

  • תיקון ניתוח route עבור QQ group/direct
  • הימנעות מדריסה של מטא-דאטה של השיחה הראשית בעת כתיבה מ-QQ
  • הבטחה ששיחות QQ ו-TG ניתנות להפרדה ולמעקב

תוצאה: הנראות של שיחות QQ ב-WebUI השתפרה משמעותית.

3) התאמות הקשר (Context) ואסטרטגיית הודעות כפולות

לטיפול בבעיה “QQ מצרף בכל פעם היסטוריה ארוכה מאוד ויוצר רעש”:

  • שינוי ברירת המחדל של historyLimit ל-0
  • הבהרה במסמכים: ברירת המחדל מסתמכת על מערכת השיחות של OpenClaw, בלי לכפות חיבור של טקסט מקור מהקבוצה
  • להפעיל חיבור היסטוריה רק כאשר המשתמש מבקש זאת במפורש

בנוסף תוקנה לוגיקה הקשורה להפעלה כפולה ולהודעות כפולות:

  • שינוי סדר בדיקות מגבלת מנהל ל: קודם תנאי טריגר (@/מילות מפתח) ורק אחר כך הרשאה
  • הוספת Debounce/קירור להתראות למשתמשים שאינם מנהלים (ברירת מחדל 10 שניות)
  • תיקון לולאת התראות אפשרית בתרחיש reply-to-bot

4) חיזוק יכולות מנהלים/רשימה שחורה

כדי למנוע ניצול לרעה, הוספתי וחיזקתי יכולות:

  • adminOnlyChat
  • notifyNonAdminBlocked
  • nonAdminBlockedMessage
  • blockedNotifyCooldownMs

לוגיקת הרשימה השחורה הוגדרה סופית כ:

  • משתמשים שפוגעים ב-blockedUsers — ההודעות שלהם מתעלמות ישירות (בלי תגובה ובלי התראה)

5) Control UI ובעיית שמירת תצורה (העיקר)

הבעיה הכי “זוללת זמן” והכי קריטית הייתה:

  • בעמוד /config גם כשמשנים רק את הרשימה הלבנה/שחורה של QQ, עדיין מתקבלת הודעת invalid config
  • אבל השגיאה מצביעה על models.providers.*.models[0].maxTokens

המסקנה הסופית לאחר איתור מקור הבעיה:

  1. /config שומר חבילה מלאה (full payload), לא רק channels.qq
  2. בזמן ולידציה של כל החבילה, אם שדה כלשהו חריג — כל השמירה נכשלת
  3. maxTokens מעובד בצורה שגויה בחלק מהמסלולים (המרה למחרוזת/פגיעה שגויה עקב “קו אדום”), מה שגורם לכשל ולידציה של כל החבילה
  4. לכן זה נראה כאילו “שינוי מספר QQ גורם לשגיאת מודל”, אבל בפועל זו “ענישה קולקטיבית של ולידציה לכל החבילה”

ד. למה זה נראה ש“שינוי מספר QQ גורר maxTokens”

במשפט אחד: אין קשר עסקי, יש קשר של מנגנון שמירה.

  • מה שמשנים: שדות QQ
  • מה שמופעל: כתיבה מחדש של כל התצורה
  • בתוך התצורה: סטייה טיפוסית בשדות מודל (למשל maxTokens הופך למחרוזת/לא תקין)
  • שלב הוולידציה נכשל, והשגיאה “מבעבעת” אל הפרונטאנד

ה. פעולות סנכרון ריפו ולוקאל

ביצעתי תיקונים מתמשכים בריפו של התוסף ודחפתי (push) כמה פעמים, כולל:

  • תיקון מדיניות מנהלים
  • תיקון ניתוב שיחות
  • התאמת ברירת המחדל של הזרקת היסטוריה
  • שיפור תאימות schema בצד הפרונטאנד
  • חיזוק תיעוד (דוגמאות בסינית)
  • השלמת קבצי פריסה ל-NapCat ב-Docker
  • התעלמות מתיקיות runtime כדי למנוע “זיהום” של הריפו

במקביל, .openclaw/extensions/qq נשמר מסונכרן עם ה-branch הראשי המרוחק.

ו. לגבי “האם שינוי רק בתוסף QQ יכול לפתור לגמרי”

מסקנה:

  • ניתן לפתור את ההתנהגות הפנימית של תוסף QQ ואת רוב בעיות השימושיות
  • אבל אי אפשר לתקן מהשכבה של התוסף את בעיית שמירת החבילה המלאה בליבה של OpenClaw
  • כי הוולידציה של models.* היא של OpenClaw Core, ולא נמצאת בתחום האחריות של תוסף QQ

ז. המלצות ישימות (סופי)

פתרון לטווח קצר (בלי לשנות Core)

  • להשתמש ב-CLI כדי לשנות רשימה לבנה/שחורה של QQ, ולעקוף את מסלול השמירה של חבילה מלאה ב-/config:
openclaw config set channels.qq.admins '\"1838552185\"' --json
openclaw config set channels.qq.blockedUsers '\"342571216\"' --json
openclaw gateway restart

המלצה לטווח בינוני (שורש הבעיה)

  • להמתין/לעקוב אחרי תיקון רשמי של OpenClaw לסוג ה-issue הזה (maxTokens + redaction + config save)
  • או להגיש לרשמי מינימום שחזור (repro) ו-PR עם תיקון

ח. לקחים

  1. בניפוי תקלות בעמוד /config חייבים לחשוב במונחים של “ולידציה של כל החבילה”, ולא להיתקע רק על הפריט ששינית
  2. אם redaction של תצורה משתמש בהתאמה רחבה (כמו /token/i), הוא עלול לפגוע בטעות ב-maxTokens
  3. עבור תוספי צ’אט, סדר ההרשאה (קודם טריגר ואז הרשאה) קריטי מאוד — אחרת זה יוצר רעש בקבוצה
  4. Debounce ומניעת כפילויות חייבים להיות פעילים כברירת מחדל, אחרת בקבוצות הבעיה מתעצמת מהר