Ügynök diagnosztizálása

Ez az útmutató bemutatja, hogyan derítheti ki, miért nem készít futtatásokat egy ügynök.

Haladjon felülről lefelé: először az ügynök saját futtatásai, aztán a háttérrendszere, majd a szerver, végül a gazdagép.

1. Ellenőrizze az ügynök futtatási előzményeit

Beállítások → Munkaterület → Ügynökök → válassza ki az ügynököt → Naplók.

Minden futtatás mutat egy állapotjelvényt, egy időtartamot („Running…”, amíg tart), a kezdési és befejezési időpontját, a PID-jét és a használt adaptert. A Nézet megnyitja az adott futtatás nyers eseményfolyamát. A Leállítás leállít egy futó folyamatot, és a futtatást „Killed by user” jelzéssel látja el; a fejlécben lévő Futó leállítása ugyanezt teszi az ügynök minden futó futtatásával.

Olvassa így:

Egyáltalán nincsenek futtatások — az indítás sosem történt meg. A composer említései @ plusz szókarakterek (betűk, számjegyek, aláhúzás). A feloldás pontos vagy előtag-egyezés az ügynök nevén, így a @code-reviewer code-ként értelmeződik, és így is felébreszthet egy code-reviewer nevű ügynököt. A szóközt tartalmazó nevet nem lehet egyetlen tokenként megemlíteni. Ezután lépjen tovább a 2. lépésre.
Egy azonnal hibával végződött futtatás — nyissa meg a Nézet elemet. A háttérrendszer indításának sikertelensége itt folyamathibaként jelenik meg.
Egy „Running…” állapotban ragadt futtatás — állítsa le, majd ellenőrizze az ügynök Csend időtúllépés (perc) beállítását a Beállítások lapon. A beállítatlan időtúllépés a módonkénti alapértelmezettet használja.
Egy befejezett futtatás hasznos kimenet nélkül — a futtatási napló állapota completed marad egy olyan futtatásnál, amely a deklarált szállítandó nélkül ért véget; az őszinte jelzés az összefoglaló szövege, nem a jelvény.

A Naplók lap nem mutat költséget. A költéseket a Megfigyelhetőség → Betekintések ügynökönkénti táblázatában nézheti meg.

2. Ellenőrizze az ügynök háttérrendszerét

Beállítások → Szerver → Modellszolgáltatók (/settings/server/providers).

A Felismert futtatók lista minden adaptert a próbaeredményével együtt mutat — egy telepített verziót, „Ellenőrzés…”-t vagy „Nem található”-t —, valamint a feloldott útvonalat és egy megtalált CLI képességchipjeit. A próba újbóli lefuttatásához kattintson az oldal fejlécében a Frissítés gombra.

A próba a cc_server-t futtató gépen fut, nem azon a gépen, amelyet éppen néz. Ha a webes kliensen vagy egy párosított eszközön van, a „Nem található” azt jelenti, hogy a CLI hiányzik a szerver gazdagépéről.

Két dolgot érdemes megerősíteni:

Az ügynökhöz egyáltalán van adapter beállítva. Az üres adapterrel rendelkező ügynök a Control Center (beépített) háttérrendszerhez kerül kiosztásra, és a futtatási napló cc-harness-t rögzít, így az átirat megnevezi, mi futott. Modell nélkül az Anthropic-tól kéri az alapértelmezettjét — ami a No credential for provider "anthropic" hibával hiúsul meg, kivéve, ha csatlakoztatott egy Anthropic-fiókot. A kezdetben betöltött szakértők adapter nélkül érkeznek.
A beépített adapterhez tartozik modell. A modellistája élőben az ugyanezen az oldalon lejjebb csatlakoztatott szolgáltatókból származik, így egy tárolt hitelesítő adat nélküli szolgáltató nulla modellt ad hozzá.

Maga az adapterkatalógus rögzített — nincs mód új adapter regisztrálására. Amit adapterenként itt módosíthat, az az indítási argumentumai és a környezeti változói. Ne feledje, hogy az adapterenkénti környezeti felülírás csendben felülírja a csatlakoztatott szolgáltatói fiókot, amikor a hitelesítő adatok feloldódnak.

3. Ellenőrizze a szervert

A Beállítások → Szerver → Kapcsolat és állapot (/settings/server/connection) megmutatja, melyik szerverrel beszél ez a kliens, és mit jelent az.

Headless szerver esetén a GET /healthz ugyanezt az információt adja kliens nélkül. Szándékosan hitelesítés nélküli és CORS-ra nyitott:

curl http://localhost:9030/healthz

Visszaadja a szerver állapotát, a másodpercben mért üzemidőt, az élő kapcsolatok számát, a kötött portot, a buildverziót és a git SHA-t, a munkaterület sémaváltozatát, az RPC-katalógus változatát, a szerver azonosítóját, nevét és identitás-ujjlenyomatát, hogy a kötés nem biztonságos-e, valamint egy codeGraph blokkot a watching / indexing / pending számokkal. Ha egy gyorsítótár forgalmat látott, egy caches blokkot is tartalmaz; egy demószerver hozzáadja a demo: true értéket.

Két dolog, amit érdemes tudni, amikor egy változás „tesztekben működik, de az alkalmazásban nem”:

Az asztali alkalmazás az előre felépített cc_server binárist részesíti előnyben a forrással szemben. Egy új RPC-művelet vagy MCP-eszköz nem jelenik meg, amíg a binárist újra nem építik, és az indítási napló figyelmeztetést ír, amikor a gyermekfolyamat git SHA-ja eltér az alkalmazásétól.
Az asztali alkalmazás leállít egy elindított szervert, amely 20 másodpercen belül nem nyomtatta ki a készjelzőjét, és egy hibaüzenet-képernyőre vált.

4. Ellenőrizze a gazdagépet

A Beállítások → Szerver → Diagnosztika és adatvédelem (/settings/server/diagnostics) a gazdagépszintű oldal. A következőket tartalmazza:

Homokozó — a főkapcsoló, a felismert háttérrendszer és egy telepítési tipp. Csak a felismert háttérrendszer származik a szerverről; lásd az alábbi figyelmeztetést. Nincs visszaállítási vezérlő.
Szemantikus keresés — az eszközön futó beágyazómodell életciklusa: telepítve, letöltés folyamatban százalékos értékkel, nincs telepítve vagy telepítési hiba. Amíg nincs telepítve, a memória- és a kódkeresés csak kulcsszavas marad.
Rendszer viselkedése — tartsa ébren a számítógépet, amíg az ügynökök futnak.
Naplózási szint — emelje meg, mielőtt egy hibát reprodukál.
Adatvédelem — hogy a nyers diff-tartalom továbbítható-e az ügynök modelljének, és hogy elküldésre kerülnek-e a hibajelentések.

Az észlelés és a kikényszerítés mára megegyezik: ahol az észlelő natív háttérrendszert jelent, az adott gazdagépen az ügynökfuttatások valóban abba vannak csomagolva. De ebben a szakaszban az észlelő az egyetlen élő dolog. A főkapcsoló és a háttérrendszer-választó az eszközén tárolt beállítások, és a szerver egyiket sem olvassa — a szerver saját kapcsolója a --sandbox (on az alapértelmezett, off a kikapcsoláshoz).

Tehát az itteni figyelmeztetést érdemes komolyan venni, de általában nem ez az oka annak, hogy egy ügynök meghibásodik. Ha meg akarja erősíteni, milyen állapotban van a szerver, olvassa el az indítási naplóját: kiírja, hogy agent sandbox ON a háttérrendszer-megjegyzéssel, no OS-native agent sandbox on this host egy telepítési tippel, vagy agent sandbox DISABLED by --sandbox off. A GET /healthz nem tartalmaz homokozómezőt.

Ahol nincs háttérrendszer — Windows esetén mindig, Linuxon vagy WSL2-ben bwrap és socat nélkül —, a futtatások nincsenek homokozóba zárva, és amit korlátoz, az a beszélgetés saját munkapéldánya, a csak olvasásra jogosult kódhosting-token és a push-átjáró, a műveleti korlátok, a környezet tisztítása és a mód által engedett eszközfelszín.

Gyakori hibák

A futtatás sosem indul el, és az adapter „Nem található”-t mutat

Telepítse a CLI-t a szerver gazdagépére, majd kattintson a Frissítés gombra a Modellszolgáltatók oldalon. Vagy állítsa át az ügynököt a beépített adapterre, amelyhez nem kell CLI, és csatlakoztasson egy szolgáltatót ugyanezen az oldalon.

Az ügynök nem tud pusholni vagy pull requestet nyitni

Nézze meg, mit írt ki a git vagy az ügynök. A Control Center policy: … azt jelenti, hogy egy műveleti szabály elutasította, vagy egy jóváhagyás megválaszolatlan maradt: ellenőrizze a Küldés távoli tárolóra és a Pull request megnyitása szabályt a Beállítások → Munkaterület → Ügynökjogosultságok alatt. Ha a git azt írja, hogy a Control Centernek nincs pusholásra képes GitHub-hitelesítő adata, telepítse a GitHub Appot az adott repóra, vagy csatlakoztassa a GitHubot.

A szemantikus keresés nem ad hasznos találatot

Ellenőrizze a Beállítások → Szerver → Diagnosztika és adatvédelem → Szemantikus keresés elemet. Amíg a beágyazómodell nincs telepítve, a keresés csak kulcsszavas. A modell telepítése előtt írt sorok soha nem töltődnek fel visszamenőleg, így azután is kulcsszavasak maradnak.

A szerver egyáltalán nem indul el

Natív könyvtárakra van szükség, és nincs csökkentett mód. Egy hiányzó dylib miatt a cc_server megtagadja az indulást, és a hibában megnevezi a hiányzó fájlt. Készítse elő a natívokat a scripts/natives/build_natives.sh szkripttel, és építse újra a szerver binárist.

Egy művelet csendben elutasításra kerül

Egy prompt korlát-döntés csatlakoztatott jóváhagyó nélkül elutasításra kerül, szándékosan. Ellenőrizze a munkaterület szabályait a Beállítások → Munkaterület → Ügynökjogosultságok alatt.