אבחון סוכן
מדריך זה מראה כיצד לגלות מדוע סוכן אינו מפיק הרצות.
עבדו מלמעלה למטה: תחילה ההרצות של הסוכן עצמו, אחר כך הבקאנד שלו, אחר כך השרת, ולבסוף המארח.
1. בדקו את היסטוריית ההרצות של הסוכן
קטע בשם “1. בדקו את היסטוריית ההרצות של הסוכן”הגדרות ← סביבת עבודה ← סוכנים ← בחרו את הסוכן ← יומנים.
כל הרצה מציגה תג סטטוס, משך (“פועל…” בזמן שהיא מתבצעת), את זמני ההתחלה והסיום שלה, את ה-PID שלה ואת המתאם שבו השתמשה. הצגה פותחת את זרם האירועים הגולמי של אותה הרצה. עצור הורג תהליך פעיל ומסמן את ההרצה כ“Killed by user”; עצור הרצות פעילות בראש העמוד עושה את אותו הדבר לכל הרצה פעילה של אותו סוכן.
קראו זאת כך:
- אין הרצות כלל — השליחה מעולם לא התרחשה. אזכורים בתיבת הכתיבה הם
@ואחריו תווי מילה (אותיות, ספרות וקו תחתון). ההתאמה היא התאמה מדויקת או התאמת קידומת של שם הסוכן, ולכן@code-reviewerמפוענח כ-codeועדיין יכול להעיר סוכן בשםcode-reviewer. שם שמכיל רווח אינו יכול להיות מוזכר כאסימון אחד. אחר כך עברו לשלב 2. - הרצה שהסתיימה מיד בשגיאה — פתחו את הצגה. כשל בהפעלת הבקאנד מופיע כאן כשגיאת תהליך.
- הרצה שנתקעה על “פועל…” — עצרו אותה, ואז בדקו את זמן קצוב לשקט של הסוכן בלשונית ההגדרות. זמן קצוב שלא הוגדר משתמש בברירת המחדל של המצב.
- הרצה שהסתיימה בלי פלט שימושי — הסטטוס ביומן ההרצות נשאר
completedעבור הרצה שהסתיימה בלי התוצר המוצהר שלה; הסימן האמין הוא טקסט הסיכום, ולא התג.
לשונית יומנים אינה מציגה עלות. לצורך ההוצאות, השתמשו בטבלה לפי סוכן בניטור ← תובנות.
2. בדקו את הבקאנד של הסוכן
קטע בשם “2. בדקו את הבקאנד של הסוכן”הגדרות ← שרת ← ספקי מודלים (/settings/server/providers).
רשימת מריצים שזוהו מציגה כל מתאם עם תוצאת הבדיקה שלו — גרסה מותקנת, “בודק…” או “לא נמצא” — וכן את הנתיב שנפתר ואת תגי היכולת עבור CLI שנמצא. לחצו על רענן בראש העמוד כדי לבדוק מחדש.
הבדיקה רצה על המכונה שמארחת את cc_server, ולא על המכונה שאתם מסתכלים עליה. אם אתם בלקוח ה-web או במכשיר משויך, “לא נמצא” פירושו שה-CLI חסר במארח השרת.
שני דברים שיש לוודא:
- שלסוכן בכלל מוגדר מתאם. סוכן עם מתאם ריק נשלח אל Control Center (מובנה), ויומן ההרצות רושם
cc-harness, כך שהתמלול מציין מה רץ בפועל. אם גם אין מודל, הוא מבקש מ-Anthropic את מודל ברירת המחדל שלה — בקשה שנכשלת עםNo credential for provider "anthropic"אלא אם חיברתם חשבון Anthropic. המומחים הנזרעים מגיעים בלי מתאם. - שלמתאם המובנה יש מודל. רשימת המודלים שלו נבנית בזמן אמת מהספקים המחוברים בהמשך אותו עמוד, ולכן ספק בלי פרטי גישה שמורים אינו תורם אף מודל.
קטלוג המתאמים עצמו קבוע — אין דרך לרשום מתאם חדש. מה שכן ניתן לשנות כאן לכל מתאם הוא ארגומנטי ההפעלה ומשתני הסביבה שלו. שימו לב שעקיפת משתני סביבה ברמת המתאם מנצחת בשקט חשבון ספק מחובר כשנפתרים פרטי גישה.
3. בדקו את השרת
קטע בשם “3. בדקו את השרת”הגדרות ← שרת ← חיבור וסטטוס (/settings/server/connection) מציג לאיזה שרת הלקוח הזה מדבר ומה הוא מדווח.
עבור שרת ללא ממשק, GET /healthz הוא אותו מידע בלי לקוח. הוא אינו דורש אימות ופתוח ל-CORS במכוון:
curl http://localhost:9030/healthzהוא מחזיר את הסטטוס של השרת, זמן פעילות בשניות, מספר חיבורים פעילים, את הפורט הכרוך, גרסת בנייה ו-git SHA, גרסת סכימה של סביבת העבודה, גרסת קטלוג RPC, מזהה השרת, שמו וטביעת האצבע של זהותו, אם הכריכה אינה מאובטחת, ובלוק codeGraph עם מוני watching / indexing / pending. כשמטמון כבר ראה תעבורה הוא כולל גם בלוק caches; שרת הדגמה מוסיף demo: true.
שני דברים שכדאי לדעת כששינוי “עובד בבדיקות אבל לא באפליקציה”:
- האפליקציה השולחנית מפעילה קובץ הפעלה בנוי מראש של
cc_serverלפני שהיא בוחרת בקוד המקור. פעולת RPC חדשה או כלי MCP חדש לא יופיעו עד שקובץ ההפעלה ייבנה מחדש, ויומן האתחול רושם אזהרה כשגרסת ה-git SHA של תהליך הבן שונה מזו של האפליקציה. - האפליקציה השולחנית הורגת שרת שהופעל ולא הדפיס את הודעת המוכנות שלו בתוך 20 שניות, ועוברת למסך שגיאה.
4. בדקו את המארח
קטע בשם “4. בדקו את המארח”הגדרות ← שרת ← אבחון ופרטיות (/settings/server/diagnostics) הוא העמוד ברמת המארח. הוא כולל:
- ארגז חול — המתג הראשי, הבקאנד שזוהה ורמז התקנה. רק הבקאנד שזוהה מגיע מהשרת; ראו את אזהרת הזהירות שלמטה. אין פקד איפוס.
- חיפוש סמנטי — מחזור החיים של מודל ההטמעה שעל המכשיר: מותקן, בהורדה עם אחוזים, לא מותקן, או שגיאת התקנה. עד שהוא מותקן, החיפוש בזיכרון ובקוד נשאר מבוסס מילות מפתח בלבד.
- התנהגות המערכת — להשאיר את המחשב ער בזמן שסוכנים פועלים.
- רמת יומן — העלו אותה לפני שחזור של כשל.
- פרטיות — אם תוכן diff גולמי עשוי להיות מועבר למודל של הסוכן ואם נשלחים דוחות קריסה.
כשלים נפוצים
קטע בשם “כשלים נפוצים”ההרצה לא מתחילה והמתאם מוצג כ“לא נמצא”
קטע בשם “ההרצה לא מתחילה והמתאם מוצג כ“לא נמצא””התקינו את ה-CLI במארח השרת, ואז לחצו על רענן בעמוד ספקי המודלים. לחלופין, העבירו את הסוכן למתאם המובנה, שאינו זקוק ל-CLI, וחברו ספק באותו עמוד.
הסוכן אינו יכול לדחוף או לפתוח בקשת משיכה
קטע בשם “הסוכן אינו יכול לדחוף או לפתוח בקשת משיכה”בדקו מה git או הסוכן הדפיסו. Control Center policy: … פירושו שכלל פעולה חסם, או שאישור לא נענה: בדקו את דחיפה למאגר מרוחק ואת פתיחת בקשת משיכה בהגדרות → סביבת עבודה → הרשאות סוכנים. אם git אומר של-Control Center אין פרטי גישה של GitHub שיכולים לדחוף, התקינו את GitHub App במאגר הזה, או חברו את GitHub.
החיפוש הסמנטי לא מחזיר דבר שימושי
קטע בשם “החיפוש הסמנטי לא מחזיר דבר שימושי”בדקו את הגדרות ← שרת ← אבחון ופרטיות ← חיפוש סמנטי. עד שמודל ההטמעה מותקן, החיפוש מבוסס מילות מפתח בלבד. רשומות שנכתבו לפני התקנת המודל אינן משלימות רטרואקטיבית, ולכן הן נשארות מבוססות מילות מפתח גם לאחר מכן.
השרת כלל אינו עולה
קטע בשם “השרת כלל אינו עולה”נדרשות ספריות מקוריות ואין מצב מוגבל. ספריית dylib חסרה גורמת ל-cc_server לסרב לעלות ולציין את הקובץ הבעייתי בשגיאה. הכינו את הספריות המקוריות עם scripts/natives/build_natives.sh ובנו מחדש את קובץ ההפעלה של השרת.
פעולה נדחית בשקט
קטע בשם “פעולה נדחית בשקט”החלטת מעקה בטיחות מסוג prompt בלי מאשר מחובר מוכרעת כדחייה, במכוון. בדקו את הכללים של סביבת העבודה תחת הגדרות ← סביבת עבודה ← הרשאות סוכנים.