Podagenci

Podagenci to działające w tle uruchomienia agentów tworzone z istniejącego uruchomienia agenta. Działają we własnej sesji (agent:<agentId>:subagent:<uuid>) i po zakończeniu ogłaszają swój wynik z powrotem w kanale czatu żądającego. Każde uruchomienie podagenta jest śledzone jako zadanie w tle.

Główne cele:

• Równoległe wykonywanie pracy typu „badanie / długie zadanie / powolne narzędzie” bez blokowania głównego uruchomienia.
• Domyślna izolacja podagentów (separacja sesji + opcjonalny sandboxing).
• Utrzymanie powierzchni narzędzi trudnej do niewłaściwego użycia: podagenci domyślnie nie otrzymują narzędzi sesji.
• Obsługa konfigurowalnej głębokości zagnieżdżenia dla wzorców orkiestratora.

Polecenie ukośnikowe

Użyj /subagents, aby sprawdzić uruchomienia podagentów dla bieżącej sesji:

/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/subagents info pokazuje metadane uruchomienia (status, znaczniki czasu, id sesji, ścieżkę transkryptu, czyszczenie). Użyj sessions_history, aby uzyskać ograniczony, filtrowany pod kątem bezpieczeństwa widok przywołania; sprawdź ścieżkę transkryptu na dysku, gdy potrzebujesz surowego pełnego transkryptu.

Kontrolki powiązania wątków

Te polecenia działają w kanałach obsługujących trwałe powiązania wątków. Zobacz Kanały obsługujące wątki poniżej.

/focus <subagent-label|session-key|session-id|session-label>/unfocus/agents/session idle <duration|off>/session max-age <duration|off>

Zachowanie tworzenia

Agenci uruchamiają podagentów w tle za pomocą sessions_spawn. Zakończenia podagentów wracają jako wewnętrzne zdarzenia sesji nadrzędnej; agent nadrzędny/żądający decyduje, czy potrzebna jest aktualizacja widoczna dla użytkownika.

Tryby kontekstu

Natywni podagenci zaczynają w izolacji, chyba że wywołujący jawnie poprosi o rozgałęzienie bieżącego transkryptu.

Używaj fork oszczędnie. Służy do delegowania zależnego od kontekstu, a nie jako zamiennik napisania jasnego promptu zadania.

Narzędzie: sessions_spawn

Uruchamia podagenta z deliver: false na globalnym pasie subagent, następnie wykonuje krok ogłoszenia i publikuje odpowiedź ogłoszenia w kanale czatu żądającego.

Dostępność zależy od efektywnej polityki narzędzi wywołującego. Profile coding i full domyślnie udostępniają sessions_spawn. Profil messaging nie udostępnia; dodaj tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] albo użyj tools.profile: "coding" dla agentów, którzy powinni delegować pracę. Polityki allow/deny kanału/grupy, dostawcy, sandboxu i poszczególnych agentów mogą nadal usunąć narzędzie po etapie profilu. Użyj /tools z tej samej sesji, aby potwierdzić efektywną listę narzędzi.

Wartości domyślne:

• Model: natywni podagenci dziedziczą po wywołującym, chyba że ustawisz agents.defaults.subagents.model (lub agents.list[].subagents.model dla poszczególnych agentów). Tworzenia runtime ACP używają tego samego skonfigurowanego modelu podagenta, gdy jest obecny; w przeciwnym razie uprząż ACP zachowuje własną wartość domyślną. Jawne sessions_spawn.model nadal wygrywa.
• Thinking: natywni podagenci dziedziczą po wywołującym, chyba że ustawisz agents.defaults.subagents.thinking (lub agents.list[].subagents.thinking dla poszczególnych agentów). Tworzenia runtime ACP stosują również agents.defaults.models["provider/model"].params.thinking dla wybranego modelu. Jawne sessions_spawn.thinking nadal wygrywa.
• Limit czasu uruchomienia: OpenClaw używa agents.defaults.subagents.runTimeoutSeconds, gdy jest ustawione; w przeciwnym razie przełącza się na 0 (brak limitu czasu). sessions_spawn nie akceptuje nadpisań limitu czasu dla pojedynczego wywołania.
• Dostarczanie zadania: natywni podagenci otrzymują delegowane zadanie w swojej pierwszej widocznej wiadomości [Subagent Task]. Prompt systemowy podagenta przenosi reguły runtime i kontekst routingu, a nie ukryty duplikat zadania.

Zaakceptowane natywne utworzenia podagentów zawierają rozwiązaną metadane modelu dziecka w wyniku narzędzia: resolvedModel zawiera zastosowany ref modelu, a resolvedProvider zawiera prefiks dostawcy, gdy ref go ma.

Tryb promptu delegowania

agents.defaults.subagents.delegationMode kontroluje tylko wskazówki promptu; nie zmienia polityki narzędzi ani nie wymusza delegowania.

• suggest (domyślnie): zachowaj standardową sugestię promptu, aby używać podagentów do większej lub wolniejszej pracy.
• prefer: powiedz głównemu agentowi, aby pozostawał responsywny i delegował wszystko bardziej złożone niż bezpośrednia odpowiedź przez sessions_spawn.

Nadpisania dla poszczególnych agentów używają agents.list[].subagents.delegationMode.

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

Parametry narzędzia

Nazwy zadań i kierowanie

taskName to uchwyt widoczny dla modelu do orkiestracji, a nie klucz sesji. Używaj go dla stabilnych nazw procesów potomnych, takich jak review_subagents, linux_validation lub docs_update, gdy koordynator może potrzebować później sprawdzić ten proces potomny.

Rozpoznawanie celu akceptuje dokładne dopasowania taskName oraz jednoznaczne prefiksy. Dopasowanie jest ograniczone do tego samego aktywnego/ostatniego okna celu używanego przez numerowane cele /subagents, więc nieaktualny ukończony proces potomny nie sprawia, że ponownie użyty uchwyt staje się niejednoznaczny. Jeśli dwa aktywne lub ostatnie procesy potomne współdzielą ten sam taskName, cel jest niejednoznaczny; użyj zamiast tego indeksu listy, klucza sesji lub identyfikatora uruchomienia.

Zarezerwowane cele last i all nie są prawidłowymi wartościami taskName, ponieważ mają już znaczenie sterujące.

Narzędzie: sessions_yield

Kończy bieżący zwrot modelu i czeka, aż zdarzenia środowiska wykonawczego, przede wszystkim zdarzenia ukończenia podagentów, dotrą jako następna wiadomość. Użyj go po uruchomieniu wymaganej pracy potomnej, gdy żądający nie może przygotować ostatecznej odpowiedzi, dopóki te ukończenia nie nadejdą.

sessions_yield jest prymitywem oczekiwania. Nie zastępuj go pętlami odpytywania po subagents, sessions_list, sessions_history, powłokowym sleep ani odpytywaniem procesów tylko po to, aby wykryć ukończenie procesu potomnego.

Używaj sessions_yield tylko wtedy, gdy efektywna lista narzędzi sesji go zawiera. Niektóre minimalne lub niestandardowe profile narzędzi mogą udostępniać sessions_spawn i subagents bez udostępniania sessions_yield; w takim przypadku nie wymyślaj pętli odpytywania tylko po to, aby czekać na ukończenie.

Gdy istnieją aktywne procesy potomne, OpenClaw wstrzykuje kompaktowy, wygenerowany przez środowisko wykonawcze blok promptu Active Subagents do zwykłych zwrotów, aby żądający mógł zobaczyć bieżące sesje potomne, identyfikatory uruchomień, statusy, etykiety, zadania i aliasy taskName bez odpytywania. Pola zadania i etykiety w tym bloku są cytowane jako dane, a nie instrukcje, ponieważ mogą pochodzić z argumentów uruchomienia dostarczonych przez użytkownika/model.

Narzędzie: subagents

Wyświetla uruchomione przebiegi podagentów należące do sesji żądającego. Jest ograniczone do bieżącego żądającego; proces potomny widzi tylko własne kontrolowane procesy potomne.

Używaj subagents do statusu na żądanie i debugowania. Używaj sessions_yield, aby czekać na zdarzenia ukończenia.

Sesje powiązane z wątkiem

Gdy powiązania wątków są włączone dla kanału, podagent może pozostać powiązany z wątkiem, dzięki czemu kolejne wiadomości użytkownika w tym wątku nadal trafiają do tej samej sesji podagenta.

Kanały obsługujące wątki

Dowolny kanał z adapterem powiązań sesji może obsługiwać trwałe sesje podagentów powiązane z wątkiem (sessions_spawn z thread: true). Dołączone adaptery obecnie obejmują wątki Discord, wątki Matrix, tematy forum Telegram oraz powiązania bieżącej konwersacji dla Feishu. Użyj kluczy konfiguracji threadBindings dla poszczególnych kanałów do włączania, limitów czasu i spawnSessions.

Szybki przepływ

Sterowanie ręczne

Przełączniki konfiguracji

• Domyślna wartość globalna: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Nadpisanie kanału i klucze automatycznego wiązania uruchomień są specyficzne dla adaptera. Zobacz Kanały obsługujące wątki powyżej.

Zobacz Dokumentacja konfiguracji i Polecenia ukośnikowe, aby uzyskać bieżące szczegóły adapterów.

Lista dozwolonych

Jeśli sesja żądającego działa w piaskownicy, sessions_spawn odrzuca cele, które działałyby poza piaskownicą.

Wykrywanie

Użyj agents_list, aby zobaczyć, które identyfikatory agentów są obecnie dozwolone dla sessions_spawn. Odpowiedź zawiera efektywny model każdego wymienionego agenta oraz osadzone metadane środowiska wykonawczego, aby wywołujący mogli odróżnić OpenClaw, serwer aplikacji Codex i inne skonfigurowane natywne środowiska wykonawcze.

Wpisy allowAgents muszą wskazywać skonfigurowane identyfikatory agentów w agents.list[]. ["*"] oznacza dowolnego skonfigurowanego agenta docelowego oraz żądającego. Jeśli konfiguracja agenta zostanie usunięta, ale jego identyfikator pozostanie w allowAgents, sessions_spawn odrzuca ten identyfikator, a agents_list go pomija. Uruchom openclaw doctor --fix, aby wyczyścić nieaktualne wpisy listy dozwolonych, albo dodaj minimalny wpis agents.list[], gdy cel powinien pozostać możliwy do uruchomienia, dziedzicząc wartości domyślne.

Automatyczna archiwizacja

• Sesje podagentów są automatycznie archiwizowane po agents.defaults.subagents.archiveAfterMinutes (domyślnie 60).
• Archiwizacja używa sessions.delete i zmienia nazwę transkrypcji na *.deleted.<timestamp> (ten sam folder).
• cleanup: "delete" archiwizuje natychmiast po ogłoszeniu (nadal zachowuje transkrypcję przez zmianę nazwy).
• Automatyczna archiwizacja działa na zasadzie best-effort; oczekujące timery przepadają, jeśli gateway zostanie ponownie uruchomiony.
• Skonfigurowane limity czasu uruchomienia nie archiwizują automatycznie; tylko zatrzymują uruchomienie. Sesja pozostaje do automatycznej archiwizacji.
• Automatyczna archiwizacja stosuje się jednakowo do sesji głębokości 1 i głębokości 2.
• Czyszczenie przeglądarki jest oddzielne od czyszczenia archiwum: śledzone karty/procesy przeglądarki są zamykane na zasadzie best-effort po zakończeniu uruchomienia, nawet jeśli zapis transkrypcji/sesji zostaje zachowany.

Zagnieżdżone podagenty

Domyślnie podagenty nie mogą uruchamiać własnych podagentów (maxSpawnDepth: 1). Ustaw maxSpawnDepth: 2, aby włączyć jeden poziom zagnieżdżenia — wzorzec orkiestratora: główny → podagent orkiestrator → pod-podagenty robocze.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)        maxConcurrent: 8, // global concurrency lane cap (default: 8)        runTimeoutSeconds: 900, // default timeout for sessions_spawn (0 = no timeout)        announceTimeoutMs: 120000, // per-call gateway announce timeout      },    },  },}

Poziomy głębokości

Łańcuch ogłoszeń

Wyniki przepływają z powrotem w górę łańcucha:

1. Worker głębokości 2 kończy pracę → ogłasza to swojemu rodzicowi (orkiestratorowi głębokości 1).
2. Orkiestrator głębokości 1 odbiera ogłoszenie, syntetyzuje wyniki, kończy pracę → ogłasza to do głównego agenta.
3. Główny agent odbiera ogłoszenie i dostarcza je użytkownikowi.

Każdy poziom widzi tylko ogłoszenia od swoich bezpośrednich dzieci.

Polityka narzędzi według głębokości

• Rola i zakres sterowania są zapisywane w metadanych sesji w momencie spawnowania. Dzięki temu płaskie lub przywrócone klucze sesji nie odzyskują przypadkowo uprawnień orkiestratora.
• Głębokość 1 (orkiestrator, gdy maxSpawnDepth >= 2): otrzymuje sessions_spawn, subagents, sessions_list, sessions_history, aby mógł spawnować dzieci i sprawdzać ich status. Inne narzędzia sesji/systemowe pozostają zabronione.
• Głębokość 1 (liść, gdy maxSpawnDepth == 1): brak narzędzi sesji (obecne zachowanie domyślne).
• Głębokość 2 (worker liściowy): brak narzędzi sesji — sessions_spawn jest zawsze zabronione na głębokości 2. Nie może spawnować dalszych dzieci.

Limit spawnowania na agenta

Każda sesja agenta (na dowolnej głębokości) może mieć jednocześnie najwyżej maxChildrenPerAgent (domyślnie 5) aktywnych dzieci. Zapobiega to niekontrolowanemu rozgałęzianiu z pojedynczego orkiestratora.

Kaskadowe zatrzymanie

Zatrzymanie orkiestratora głębokości 1 automatycznie zatrzymuje wszystkie jego dzieci głębokości 2:

• /stop na głównym czacie zatrzymuje wszystkich agentów głębokości 1 i kaskadowo zatrzymuje ich dzieci głębokości 2.

Uwierzytelnianie

Uwierzytelnianie subagenta jest rozwiązywane według identyfikatora agenta, a nie według typu sesji:

• Klucz sesji subagenta to agent:<agentId>:subagent:<uuid>.
• Magazyn uwierzytelniania jest ładowany z agentDir tego agenta.
• Profile uwierzytelniania głównego agenta są scalane jako fallback; profile agenta zastępują profile główne w przypadku konfliktów.

Scalanie jest addytywne, więc profile główne są zawsze dostępne jako fallbacki. W pełni izolowane uwierzytelnianie na agenta nie jest jeszcze obsługiwane.

Ogłaszanie

Subagenci raportują z powrotem przez krok ogłaszania:

• Krok ogłaszania działa wewnątrz sesji subagenta (nie w sesji żądającej).
• Jeśli subagent odpowie dokładnie ANNOUNCE_SKIP, nic nie zostanie opublikowane.
• Jeśli najnowszy tekst asystenta jest dokładnym cichym tokenem NO_REPLY / no_reply, wyjście ogłoszenia jest tłumione nawet wtedy, gdy wcześniej istniał widoczny postęp.

Dostarczenie zależy od głębokości żądającego:

• Sesje żądające najwyższego poziomu używają kolejnego wywołania agent z dostarczeniem zewnętrznym (deliver=true).
• Zagnieżdżone sesje subagentów żądających otrzymują wewnętrzne wstrzyknięcie dalszego wywołania (deliver=false), aby orkiestrator mógł syntetyzować wyniki dzieci w sesji.
• Jeśli zagnieżdżona sesja subagenta żądającego zniknęła, OpenClaw wraca do żądającego tej sesji, gdy jest dostępny.

Dla sesji żądających najwyższego poziomu bezpośrednie dostarczenie w trybie ukończenia najpierw rozwiązuje dowolną powiązaną trasę rozmowy/wątku i nadpisanie hooka, a następnie uzupełnia brakujące pola kanału-docelu z zapisanej trasy sesji żądającej. Dzięki temu ukończenia pozostają na właściwym czacie/temacie nawet wtedy, gdy źródło ukończenia identyfikuje tylko kanał.

Agregacja ukończeń dzieci jest ograniczona do bieżącego uruchomienia żądającego podczas budowania zagnieżdżonych ustaleń ukończenia, co zapobiega przeciekaniu wyjść dzieci z poprzednich uruchomień do bieżącego ogłoszenia. Odpowiedzi ogłoszeń zachowują trasowanie wątku/tematu, gdy jest dostępne w adapterach kanałów.

Kontekst ogłaszania

Kontekst ogłaszania jest normalizowany do stabilnego wewnętrznego bloku zdarzenia:

Zakończone niepowodzeniem uruchomienia terminalne raportują status niepowodzenia bez odtwarzania przechwyconego tekstu odpowiedzi. Wyjście tool/toolResult nie jest promowane do tekstu wyniku dziecka.

Wiersz statystyk

Ładunki ogłoszeń zawierają na końcu wiersz statystyk (nawet gdy są zawijane):

• Czas runtime (np. runtime 5m12s).
• Zużycie tokenów (wejście/wyjście/łącznie).
• Szacowany koszt, gdy skonfigurowano ceny modelu (models.providers.*.models[].cost).
• sessionKey, sessionId i ścieżka transkryptu, aby główny agent mógł pobrać historię przez sessions_history lub sprawdzić plik na dysku.

Metadane wewnętrzne są przeznaczone tylko do orkiestracji; odpowiedzi skierowane do użytkownika należy przepisać normalnym głosem asystenta.

Dlaczego preferować sessions_history

sessions_history jest bezpieczniejszą ścieżką orkiestracji:

• Przywoływanie asystenta jest najpierw normalizowane: tagi myślenia usunięte; szkielety <relevant-memories> / <relevant_memories> usunięte; bloki ładunków XML wywołań narzędzi w tekście jawnym (<tool_call>, <function_call>, <tool_calls>, <function_calls>) usunięte, w tym obcięte ładunki, które nigdy nie zamykają się czysto; zdegradowane szkielety wywołań/wyników narzędzi i markery kontekstu historycznego usunięte; ujawnione tokeny sterujące modelu (<|assistant|>, inne ASCII <|...|>, pełnej szerokości <｜...｜>) usunięte; zniekształcony XML wywołań narzędzi MiniMax usunięty.
• Tekst przypominający poświadczenia/tokeny jest redagowany.
• Długie bloki mogą być obcinane.
• Bardzo duże historie mogą usuwać starsze wiersze lub zastępować zbyt duży wiersz tekstem [sessions_history omitted: message too large].
• Użyj nextOffset, gdy jest obecny, aby stronicować wstecz przez starsze okna transkryptu.
• Surowa inspekcja transkryptu na dysku jest fallbackiem, gdy potrzebujesz pełnego transkryptu bajt w bajt.

Polityka narzędzi

Subagenci najpierw używają tego samego profilu i potoku polityki narzędzi co agent nadrzędny lub docelowy. Następnie OpenClaw stosuje warstwę ograniczeń subagenta.

Bez restrykcyjnego tools.profile subagenci otrzymują wszystkie narzędzia oprócz narzędzia wiadomości, narzędzi sesji i narzędzi systemowych:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

sessions_history pozostaje także tutaj ograniczonym, oczyszczonym widokiem przywołania — nie jest surowym zrzutem transkryptu.

Gdy maxSpawnDepth >= 2, subagenci orkiestratorzy głębokości 1 dodatkowo otrzymują sessions_spawn, subagents, sessions_list i sessions_history, aby mogli zarządzać swoimi dziećmi.

Nadpisanie przez konfigurację

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // deny wins        deny: ["gateway", "cron"],        // if allow is set, it becomes allow-only (deny still wins)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow jest końcowym filtrem tylko-dopuszczającym. Może zawęzić już rozwiązany zestaw narzędzi, ale nie może dodać z powrotem narzędzia usuniętego przez tools.profile. Na przykład tools.profile: "coding" obejmuje web_search/web_fetch, ale nie narzędzie browser. Aby pozwolić subagentom z profilem coding używać automatyzacji przeglądarki, dodaj browser na etapie profilu:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Użyj agents.list[].tools.alsoAllow: ["browser"] dla każdego agenta, gdy tylko jeden agent powinien otrzymać automatyzację przeglądarki.

Współbieżność

Subagenci używają dedykowanej kolejki wewnątrz procesu:

• Nazwa toru: subagent
• Współbieżność: agents.defaults.subagents.maxConcurrent (domyślnie 8)

Żywotność i odzyskiwanie

OpenClaw nie traktuje braku endedAt jako trwałego dowodu, że subagent nadal działa. Niezakończone uruchomienia starsze niż okno przestarzałego uruchomienia przestają liczyć się jako aktywne/oczekujące w /subagents list, podsumowaniach statusu, bramkowaniu ukończeń potomków i kontrolach współbieżności na sesję.

Po ponownym uruchomieniu gatewaya przestarzałe, niezakończone przywrócone uruchomienia są przycinane, chyba że ich sesja dziecka jest oznaczona abortedLastRun: true. Te przerwane przez restart sesje dzieci pozostają odzyskiwalne przez przepływ odzyskiwania osieroconego subagenta, który wysyła syntetyczną wiadomość wznowienia przed wyczyszczeniem znacznika przerwania.

Automatyczne odzyskiwanie po restarcie jest ograniczone na sesję dziecka. Jeśli to samo dziecko subagenta jest wielokrotnie akceptowane do odzyskiwania osierocenia wewnątrz okna szybkiego ponownego zakleszczenia, OpenClaw utrwala nagrobek odzyskiwania w tej sesji i przestaje automatycznie wznawiać ją przy późniejszych restartach. Uruchom openclaw tasks maintenance --apply, aby uzgodnić rekord zadania, lub openclaw doctor --fix, aby wyczyścić przestarzałe flagi przerwanego odzyskiwania w sesjach z nagrobkiem.

Zatrzymywanie

• Wysłanie /stop na czacie żądającego przerywa sesję żądającego i zatrzymuje wszystkie aktywne uruchomienia subagentów z niej spawnowane, kaskadowo przechodząc na zagnieżdżone dzieci.

Ograniczenia

• Ogłaszanie subagenta jest best-effort. Jeśli gateway zostanie ponownie uruchomiony, oczekująca praca „ogłoś z powrotem” zostanie utracona.
• Subagenci nadal współdzielą te same zasoby procesu gatewaya; traktuj maxConcurrent jako zawór bezpieczeństwa.
• sessions_spawn jest zawsze nieblokujące: natychmiast zwraca { status: "accepted", runId, childSessionKey }.
• Kontekst subagenta wstrzykuje tylko AGENTS.md i TOOLS.md (bez SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md ani BOOTSTRAP.md). Subagenci natywni dla Codex przestrzegają tej samej granicy: TOOLS.md pozostaje w odziedziczonych instrukcjach wątku Codex, podczas gdy pliki persony, tożsamości i użytkownika przeznaczone tylko dla rodzica są wstrzykiwane jako instrukcje współpracy ograniczone do tury, aby dzieci ich nie klonowały.
• Maksymalna głębokość zagnieżdżenia wynosi 5 (zakres maxSpawnDepth: 1–5). Głębokość 2 jest zalecana dla większości przypadków użycia.
• maxChildrenPerAgent ogranicza aktywne dzieci na sesję (domyślnie 5, zakres 1–20).

Powiązane

• Agenci ACP
• Wysyłanie do agenta
• Zadania w tle
• Narzędzia sandboxa wieloagentowego