Διάγνωση πράκτορα

Αυτός ο οδηγός δείχνει πώς να ανακαλύψετε γιατί ένας πράκτορας δεν παράγει εκτελέσεις.

Δουλέψτε από πάνω προς τα κάτω: πρώτα τις εκτελέσεις του ίδιου του πράκτορα, μετά το backend του, έπειτα τον διακομιστή και στο τέλος τον κεντρικό υπολογιστή.

1. Ελέγξτε το ιστορικό εκτελέσεων του πράκτορα

Ρυθμίσεις → Χώρος εργασίας → Πράκτορες → επιλέξτε τον πράκτορα → Αρχεία καταγραφής.

Κάθε εκτέλεση εμφανίζει μια ένδειξη κατάστασης, μια διάρκεια («Running…» όσο βρίσκεται σε εξέλιξη), τις ώρες έναρξης και ολοκλήρωσης, το PID της και τον προσαρμογέα που χρησιμοποίησε. Η Προβολή ανοίγει την ακατέργαστη ροή συμβάντων αυτής της εκτέλεσης. Η Διακοπή τερματίζει μια διεργασία που εκτελείται και επισημαίνει την εκτέλεση ως «Killed by user»· ο Τερματισμός εκτέλεσης στην κεφαλίδα κάνει το ίδιο για κάθε εκτέλεση αυτού του πράκτορα που βρίσκεται σε εξέλιξη.

Διαβάστε το ως εξής:

Καμία εκτέλεση καθόλου — η αποστολή δεν έγινε ποτέ. Οι αναφορές στον συνθέτη μηνυμάτων είναι @ συν χαρακτήρες λέξης (γράμματα, ψηφία, κάτω παύλα). Η αντιστοίχιση γίνεται ακριβώς ή κατά πρόθεμα με το όνομα του πράκτορα, οπότε το @code-reviewer αναλύεται ως code και μπορεί ακόμη να ξυπνήσει έναν πράκτορα με το όνομα code-reviewer. Ένα όνομα με κενό δεν μπορεί να αναφερθεί ως ένα διακριτικό. Στη συνέχεια πηγαίνετε στο βήμα 2.
Μια εκτέλεση που τελείωσε αμέσως με σφάλμα — ανοίξτε την Προβολή. Μια αποτυχία εκκίνησης του backend εμφανίζεται εδώ ως σφάλμα διεργασίας.
Μια εκτέλεση κολλημένη στο «Running…» — σταματήστε την και μετά ελέγξτε το Χρονικό όριο σιωπής του πράκτορα στην καρτέλα Ρυθμίσεις. Ένα μη ορισμένο όριο χρησιμοποιεί την προεπιλογή ανά λειτουργία.
Μια ολοκληρωμένη εκτέλεση χωρίς χρήσιμη έξοδο — η κατάσταση στην καταγραφή εκτέλεσης παραμένει completed για μια εκτέλεση που τελείωσε χωρίς το δηλωμένο παραδοτέο της· το ειλικρινές σήμα είναι το κείμενο της σύνοψης, όχι η ένδειξη.

Η καρτέλα Αρχεία καταγραφής δεν εμφανίζει κόστος. Για τη δαπάνη, χρησιμοποιήστε τον πίνακα ανά πράκτορα στην Παρατηρησιμότητα → Στοιχεία.

2. Ελέγξτε το backend του πράκτορα

Ρυθμίσεις → Διακομιστής → Πάροχοι μοντέλων (/settings/server/providers).

Η λίστα Ανιχνευμένοι εκτελεστές δείχνει κάθε προσαρμογέα με το αποτέλεσμα του ελέγχου του — μια εγκατεστημένη έκδοση, «Έλεγχος…» ή «Δεν βρέθηκε» — καθώς και τη διαδρομή που εντοπίστηκε και τα πλακίδια δυνατοτήτων για ένα CLI που βρέθηκε. Πατήστε Ανανέωση στην κεφαλίδα της σελίδας για επανάληψη του ελέγχου.

Ο έλεγχος εκτελείται στο μηχάνημα που φιλοξενεί το cc_server, όχι στο μηχάνημα που κοιτάτε. Αν βρίσκεστε στον web client ή σε μια συζευγμένη συσκευή, το «Δεν βρέθηκε» σημαίνει ότι το CLI λείπει από τον κεντρικό υπολογιστή του διακομιστή.

Δύο πράγματα που πρέπει να επιβεβαιώσετε:

Ο πράκτορας έχει ορίσει καθόλου προσαρμογέα. Ένας πράκτορας με κενό προσαρμογέα αποστέλλεται στο Control Center (ενσωματωμένο) και η καταγραφή εκτέλεσης καταχωρεί cc-harness, ώστε να φαίνεται τι έτρεξε. Χωρίς μοντέλο επίσης, ζητά από την Anthropic το προεπιλεγμένο της — κάτι που αποτυγχάνει με No credential for provider "anthropic" αν δεν έχετε συνδέσει λογαριασμό Anthropic. Οι ειδικοί του αρχικού εφοδιασμού έρχονται χωρίς προσαρμογέα.
Ο ενσωματωμένος προσαρμογέας έχει μοντέλο. Η λίστα μοντέλων του προέρχεται ζωντανά από τους παρόχους που είναι συνδεδεμένοι πιο κάτω στην ίδια σελίδα, οπότε ένας πάροχος χωρίς αποθηκευμένο διαπιστευτήριο συνεισφέρει μηδέν μοντέλα.

Ο κατάλογος των προσαρμογέων είναι σταθερός — δεν υπάρχει τρόπος να καταχωρίσετε νέο προσαρμογέα. Αυτό που μπορείτε να αλλάξετε ανά προσαρμογέα εδώ είναι τα ορίσματα εκκίνησης και οι μεταβλητές περιβάλλοντος. Σημειώστε ότι μια παράκαμψη περιβάλλοντος ανά προσαρμογέα υπερισχύει σιωπηλά ενός συνδεδεμένου λογαριασμού παρόχου όταν επιλύονται τα διαπιστευτήρια.

3. Ελέγξτε τον διακομιστή

Ρυθμίσεις → Διακομιστής → Σύνδεση και κατάσταση (/settings/server/connection) δείχνει σε ποιον διακομιστή μιλάει αυτός ο πελάτης και τι αναφέρει.

Για έναν headless διακομιστή, το GET /healthz δίνει τις ίδιες πληροφορίες χωρίς πελάτη. Είναι χωρίς έλεγχο ταυτότητας και ανοιχτό σε CORS εκ σχεδιασμού:

curl http://localhost:9030/healthz

Επιστρέφει την κατάσταση του διακομιστή, τον χρόνο λειτουργίας σε δευτερόλεπτα, τον αριθμό των ζωντανών συνδέσεων, τη δεσμευμένη θύρα, την έκδοση build και το git SHA, την έκδοση του σχήματος του χώρου εργασίας, την έκδοση του καταλόγου RPC, το αναγνωριστικό, το όνομα και το αποτύπωμα ταυτότητας του διακομιστή, αν η δέσμευση είναι μη ασφαλής, και ένα μπλοκ codeGraph με μετρητές watching / indexing / pending. Όταν μια προσωρινή μνήμη έχει δεχθεί κίνηση, περιλαμβάνει επίσης ένα μπλοκ caches· ένας διακομιστής επίδειξης προσθέτει demo: true.

Δύο πράγματα που αξίζει να γνωρίζετε όταν μια αλλαγή «δουλεύει στα τεστ αλλά όχι στην εφαρμογή»:

Η εφαρμογή desktop εκκινεί κατά προτίμηση ένα προκατασκευασμένο δυαδικό cc_server αντί για τον πηγαίο κώδικα. Μια νέα λειτουργία RPC ή ένα νέο εργαλείο MCP δεν εμφανίζεται μέχρι να ξαναχτιστεί το δυαδικό, και η εκκίνηση καταγράφει προειδοποίηση όταν το git SHA του θυγατρικού διαφέρει από αυτό της εφαρμογής.
Η εφαρμογή desktop τερματίζει έναν διακομιστή που εκκίνησε και δεν έχει εκτυπώσει το πανό ετοιμότητάς του εντός 20 δευτερολέπτων, πέφτοντας σε οθόνη σφάλματος.

4. Ελέγξτε τον κεντρικό υπολογιστή

Ρυθμίσεις → Διακομιστής → Διαγνωστικά και απόρρητο (/settings/server/diagnostics) είναι η σελίδα επιπέδου κεντρικού υπολογιστή. Περιλαμβάνει:

Sandboxing — τον γενικό διακόπτη, το ανιχνευμένο backend και μια υπόδειξη εγκατάστασης. Μόνο το ανιχνευμένο backend προέρχεται από τον διακομιστή· δείτε την προσοχή παρακάτω. Δεν υπάρχει στοιχείο επαναφοράς.
Σημασιολογική αναζήτηση — τον κύκλο ζωής του μοντέλου ενσωμάτωσης στη συσκευή: εγκατεστημένο, σε λήψη με ποσοστό, μη εγκατεστημένο ή σφάλμα εγκατάστασης. Μέχρι να εγκατασταθεί, η αναζήτηση μνήμης και κώδικα παραμένει μόνο με λέξεις-κλειδιά.
Συμπεριφορά συστήματος — να μένει ο υπολογιστής σε εγρήγορση όσο εκτελούνται πράκτορες.
Επίπεδο καταγραφής — ανεβάστε το πριν αναπαραγάγετε μια αποτυχία.
Απόρρητο — αν το ακατέργαστο περιεχόμενο diff μπορεί να προωθηθεί στο μοντέλο του πράκτορα και αν αποστέλλονται αναφορές κατάρρευσης.

Η ανίχνευση και η επιβολή συμφωνούν πλέον: όπου ο ανιχνευτής αναφέρει εγγενές backend, οι εκτελέσεις πρακτόρων σε αυτόν τον κεντρικό υπολογιστή είναι πραγματικά περιτυλιγμένες σε αυτό. Όμως ο ανιχνευτής είναι το μόνο ζωντανό στοιχείο αυτής της ενότητας. Ο γενικός διακόπτης και ο επιλογέας backend είναι προτιμήσεις αποθηκευμένες στη συσκευή σας και ο διακομιστής δεν διαβάζει καμία από αυτές — ο δικός του διακόπτης είναι το --sandbox (on από προεπιλογή, off για εξαίρεση).

Έτσι, μια προειδοποίηση εδώ αξίζει να την αντιμετωπίσετε, αλλά συνήθως δεν είναι ο λόγος που αποτυγχάνει ένας πράκτορας. Για να επιβεβαιώσετε σε ποια κατάσταση βρίσκεται ο διακομιστής, διαβάστε το αρχείο καταγραφής εκκίνησής του: εκτυπώνει agent sandbox ON με τη σημείωση του backend, no OS-native agent sandbox on this host με υπόδειξη εγκατάστασης ή agent sandbox DISABLED by --sandbox off. Το GET /healthz δεν περιέχει πεδίο sandbox.

Όπου δεν υπάρχει backend — πάντα στα Windows, σε Linux ή WSL2 χωρίς bwrap και socat — οι εκτελέσεις δεν είναι σε sandbox και αυτό που τις περιορίζει είναι το ίδιο το checkout της συνομιλίας, το token φιλοξενίας κώδικα μόνο για ανάγνωση και η πύλη push, οι περιορισμοί ενεργειών, η απολύμανση του περιβάλλοντος και η επιφάνεια εργαλείων που επιτρέπει η λειτουργία του.

Συνήθεις αποτυχίες

Η εκτέλεση δεν ξεκινά ποτέ και ο προσαρμογέας εμφανίζει «Δεν βρέθηκε»

Εγκαταστήστε το CLI στον κεντρικό υπολογιστή του διακομιστή και μετά πατήστε Ανανέωση στη σελίδα Πάροχοι μοντέλων. Ή αλλάξτε τον πράκτορα στον ενσωματωμένο προσαρμογέα, που δεν χρειάζεται CLI, και συνδέστε έναν πάροχο στην ίδια σελίδα.

Ο πράκτορας δεν μπορεί να κάνει push ή να ανοίξει pull request

Διαβάστε τι εμφάνισε το git ή ο πράκτορας. Το Control Center policy: … σημαίνει ότι ένας κανόνας ενέργειας το απέρριψε ή ότι μια έγκριση έμεινε αναπάντητη: ελέγξτε τα Push σε απομακρυσμένο και Άνοιγμα pull request στις Ρυθμίσεις → Χώρος εργασίας → Δικαιώματα πρακτόρων. Αν το git λέει ότι το Control Center δεν έχει διαπιστευτήριο GitHub που μπορεί να κάνει push, εγκαταστήστε τη GitHub App σε αυτό το αποθετήριο ή συνδέστε το GitHub.

Η σημασιολογική αναζήτηση δεν επιστρέφει τίποτα χρήσιμο

Ελέγξτε Ρυθμίσεις → Διακομιστής → Διαγνωστικά και απόρρητο → Σημασιολογική αναζήτηση. Μέχρι να εγκατασταθεί το μοντέλο ενσωμάτωσης, η αναζήτηση γίνεται μόνο με λέξεις-κλειδιά. Οι εγγραφές που γράφτηκαν πριν από την εγκατάσταση του μοντέλου δεν συμπληρώνονται αναδρομικά, οπότε παραμένουν μόνο με λέξεις-κλειδιά ακόμη και μετά.

Ο διακομιστής δεν ξεκινά καθόλου

Απαιτούνται εγγενείς βιβλιοθήκες και δεν υπάρχει υποβαθμισμένη λειτουργία. Μια dylib που λείπει κάνει το cc_server να αρνείται να ξεκινήσει και να ονομάζει τον ένοχο στο σφάλμα. Τοποθετήστε τα εγγενή αρχεία με το scripts/natives/build_natives.sh και ξαναχτίστε το δυαδικό του διακομιστή.

Μια ενέργεια απορρίπτεται σιωπηλά

Μια απόφαση περιορισμού prompt χωρίς συνδεδεμένο εγκριτή απορρίπτεται, εκ σχεδιασμού. Ελέγξτε τους κανόνες του χώρου εργασίας στις Ρυθμίσεις → Χώρος εργασίας → Δικαιώματα πρακτόρων.