openclaw doctor
Kontrole kondycji + szybkie poprawki dla Gateway i kanałów.
Powiązane:
- Rozwiązywanie problemów: Rozwiązywanie problemów
- Audyt bezpieczeństwa: Bezpieczeństwo
Dlaczego warto go używać
openclaw doctor to powierzchnia kontroli kondycji OpenClaw. Użyj jej, gdy Gateway,
kanały, pluginy, Skills, routing modeli, stan lokalny lub migracje konfiguracji
nie działają zgodnie z oczekiwaniami i potrzebujesz jednego polecenia, które wyjaśni,
co jest nie tak.
Doctor ma trzy tryby działania:
| Tryb | Polecenie | Zachowanie |
|---|---|---|
| Inspekcja | openclaw doctor | Kontrole zorientowane na człowieka i prowadzone monity. |
| Naprawa | openclaw doctor --fix | Stosuje obsługiwane naprawy, używając monitów, chyba że bezpieczna jest naprawa nieinteraktywna. |
| Lint | openclaw doctor --lint | Tylko do odczytu, ustrukturyzowane wyniki dla CI, preflight i bramek przeglądu. |
--lint, gdy automatyzacja potrzebuje stabilnego wyniku. Preferuj --fix, gdy
operator świadomie chce, aby doctor edytował konfigurację lub stan.
Przykłady
doctor:
Opcje
--no-workspace-suggestions: wyłącz sugestie pamięci/wyszukiwania obszaru roboczego--yes: zaakceptuj wartości domyślne bez monitowania--repair: zastosuj zalecane naprawy niezwiązane z usługami bez monitowania; instalacje i przepisywanie usługi Gateway nadal wymagają interaktywnego potwierdzenia lub jawnych poleceń Gateway--fix: alias dla--repair--force: zastosuj agresywne naprawy, w tym nadpisanie niestandardowej konfiguracji usługi, gdy jest to potrzebne--non-interactive: uruchom bez monitów; tylko bezpieczne migracje i naprawy niezwiązane z usługami--generate-gateway-token: wygeneruj i skonfiguruj token Gateway--allow-exec: zezwól doctor na wykonywanie skonfigurowanych exec SecretRefs podczas weryfikowania sekretów--deep: skanuj usługi systemowe pod kątem dodatkowych instalacji Gateway i zgłaszaj ostatnie przekazania restartów nadzorcy Gateway--lint: uruchom zmodernizowane kontrole kondycji w trybie tylko do odczytu i emituj wyniki diagnostyczne--post-upgrade: uruchom sondy zgodności pluginów po aktualizacji; emituje wyniki do stdout; kończy z kodem 1, jeśli obecne są jakiekolwiek wyniki na poziomie błędu--json: z--lintemituj wyniki JSON zamiast wyjścia czytelnego dla człowieka; z--post-upgradeemituj czytelną maszynowo kopertę JSON ({ probesRun, findings })--severity-min <level>: z--lintodrzuć wyniki poniżejinfo,warningluberror--all: z--linturuchom wszystkie zarejestrowane kontrole, w tym kontrole opt-in wykluczone z domyślnego zestawu automatyzacji--skip <id>: z--lintpomiń id kontroli; powtórz, aby pominąć więcej niż jedną--only <id>: z--linturuchom tylko id kontroli; powtórz, aby uruchomić mały wybrany zestaw
Tryb Lint
openclaw doctor --lint to postawa automatyzacji tylko do odczytu dla kontroli doctor.
Używa ustrukturyzowanej ścieżki kontroli kondycji, nie monituje oraz nie naprawia
ani nie przepisuje konfiguracji/stanu. Używaj jej w CI, skryptach preflight i przepływach
przeglądu, gdy zamiast prowadzonych monitów naprawy potrzebujesz wyników czytelnych maszynowo.
Opcje wyjścia lint, takie jak --json, --severity-min, --all, --only i --skip,
są akceptowane tylko z --lint.
0: brak wyników na wybranym progu ważności lub powyżej niego1: co najmniej jeden wynik spełnia wybrany próg2: awaria polecenia/środowiska uruchomieniowego przed wygenerowaniem wyników lint
--severity-min kontroluje zarówno widoczne wyniki, jak i próg wyjścia. Na
przykład openclaw doctor --lint --severity-min error może nie wypisać żadnych wyników i
zakończyć się kodem 0, nawet gdy istnieją wyniki o niższej ważności info lub warning.
--all kontroluje, które kontrole są wybierane przed filtrowaniem ważności. Domyślne
uruchomienie lint jest stabilną bramką automatyzacji i wyklucza kontrole, które są
celowo opt-in, ponieważ są głębokie, historyczne lub z większym prawdopodobieństwem
ujawniają naprawialne pozostałości legacy. Użyj --all, gdy potrzebujesz pełnej
inwentaryzacji lint bez wymieniania każdego id kontroli. --only <id> pozostaje najbardziej precyzyjnym
selektorem i może uruchomić dowolną zarejestrowaną kontrolę według id.
Ustrukturyzowane kontrole kondycji
Nowoczesne kontrole doctor używają małego ustrukturyzowanego kontraktu:detect() zasila doctor --lint. repair() jest opcjonalne i jest brane pod uwagę tylko
przez doctor --fix / doctor --repair. Kontrole, które nie zostały zmigrowane do tego
kształtu, nadal używają legacy przepływu kontrybucji doctor.
Ten podział jest celowy: detect() odpowiada za diagnozę, podczas gdy repair() odpowiada za
raportowanie tego, co zmieniło lub zmieniłoby. Konteksty naprawy mogą przenosić
żądania dryRun/diff, a wyniki naprawy mogą zwracać ustrukturyzowane diffs dla
edycji konfiguracji/plików oraz effects dla efektów ubocznych dotyczących usług, procesów, pakietów, stanu lub innych
efektów ubocznych. Dzięki temu skonwertowane kontrole mogą ewoluować w stronę doctor --fix --dry-run
i raportowania diff bez przenoszenia planowania mutacji do detect().
repair() zgłasza, czy podjęło próbę żądanej naprawy, używając status: "repaired" | "skipped" | "failed". Pominięty status oznacza repaired, więc proste
kontrole naprawy muszą zwracać tylko zmiany. Gdy naprawa zwraca skipped lub
failed, doctor zgłasza powód i nie uruchamia walidacji dla tej kontroli.
Po udanej ustrukturyzowanej naprawie doctor ponownie uruchamia detect() z
naprawionymi wynikami jako zakresem. Kontrole mogą używać wybranych wyników, ścieżek lub wartości ocPath
do ukierunkowanej walidacji. Jeśli wynik nadal jest obecny, doctor zgłasza
ostrzeżenie naprawy zamiast traktować zmianę jako cicho ukończoną.
Wynik zawiera:
| Pole | Cel |
|---|---|
checkId | Stabilne id dla filtrów skip/only i allowlist CI. |
severity | info, warning lub error. |
message | Czytelny dla człowieka opis problemu. |
path | Konfiguracja, plik lub ścieżka logiczna, gdy dostępna. |
line / column | Lokalizacja w źródle, gdy dostępna. |
ocPath | Precyzyjny adres oc://, gdy kontrola może go wskazać. |
fixHint | Sugerowane działanie operatora lub podsumowanie naprawy. |
doctor / doctor --fix. Wspólny ustrukturyzowany
rejestr kondycji jest punktem rozszerzeń: kontrole pakietowe i wspierane przez pluginy uruchamiają się
po podstawowych kontrolach doctor, gdy ich pakiet właścicielski zarejestruje je w aktywnej
ścieżce polecenia. Podścieżka openclaw/plugin-sdk/health udostępnia ten sam
kontrakt tym konsumentom rozszerzeń.
Wybór kontroli
Użyj--only i --skip, gdy przepływ pracy potrzebuje ukierunkowanej bramki:
--only i --skip akceptują pełne id kontroli i mogą być powtarzane. Jeśli id --only
nie jest zarejestrowane, dla tego id nie zostanie uruchomiona żadna kontrola; użyj pól checksRun
i checksSkipped polecenia, aby zweryfikować, że ukierunkowana bramka wybiera kontrole, których
oczekujesz.
Tryb po aktualizacji
openclaw doctor --post-upgrade uruchamia sondy zgodności pluginów przeznaczone do
łańcuchowego uruchamiania po kompilacji lub aktualizacji. Wyniki są emitowane do stdout; polecenie
kończy się kodem 1, jeśli jakikolwiek wynik ma level: "error". Dodaj --json, aby otrzymać
czytelną maszynowo kopertę ({ probesRun, findings }) odpowiednią dla CI,
społecznościowej umiejętności fork-upgrade i innych narzędzi smoke po aktualizacji. Jeśli
indeks zainstalowanych pluginów jest brakujący lub zniekształcony, tryb JSON nadal emituje tę
kopertę z wynikiem błędu plugin.index_unavailable.
Uwagi:
- W trybie Nix (
OPENCLAW_NIX_MODE=1) kontrole doctor tylko do odczytu nadal działają, aledoctor --fix,doctor --repair,doctor --yesidoctor --generate-gateway-tokensą wyłączone, ponieważopenclaw.jsonjest niemutowalny. Zamiast tego edytuj źródło Nix dla tej instalacji; w przypadku nix-openclaw użyj podejścia agent-first z Szybkiego startu. - Interaktywne monity (takie jak naprawy keychain/OAuth) są uruchamiane tylko wtedy, gdy stdin jest TTY, a
--non-interactivenie jest ustawione. Uruchomienia bez interfejsu (cron, Telegram, brak terminala) pominą monity. - Wydajność: nieinteraktywne uruchomienia
doctorpomijają gorliwe ładowanie Plugin, dzięki czemu bezterminalowe kontrole kondycji pozostają szybkie. Interaktywne sesje doctor nadal ładują powierzchnie Plugin potrzebne przez starszy przepływ kondycji i naprawy. --lintjest bardziej rygorystyczne niż--non-interactive: zawsze działa tylko do odczytu, nigdy nie wyświetla monitów i nigdy nie stosuje bezpiecznych migracji. Uruchomdoctor --fixlubdoctor --repair, gdy chcesz, aby doctor wprowadził zmiany.- Domyślnie doctor nie wykonuje SecretRefs typu
execpodczas sprawdzania sekretów. Używajopenclaw doctor --allow-execlubopenclaw doctor --lint --allow-exectylko wtedy, gdy celowo chcesz, aby doctor uruchomił te skonfigurowane resolvery sekretów. --fix(alias dla--repair) zapisuje kopię zapasową w~/.openclaw/openclaw.json.baki usuwa nieznane klucze konfiguracji, wypisując każde usunięcie.- Zmodernizowane kontrole kondycji mogą udostępniać ścieżkę
repair()dladoctor --fix; kontrole, które jej nie udostępniają, nadal przechodzą przez istniejący przepływ naprawy doctor. doctor --fix --non-interactivezgłasza brakujące lub nieaktualne definicje usługi Gateway, ale nie instaluje ich ani nie przepisuje poza trybem naprawy aktualizacji. Uruchomopenclaw gateway installdla brakującej usługi alboopenclaw gateway install --force, gdy celowo chcesz zastąpić launcher.- Kontrole integralności stanu wykrywają teraz osierocone pliki transkryptów w katalogu sesji. Zarchiwizowanie ich jako
.deleted.<timestamp>wymaga interaktywnego potwierdzenia;--fix,--yesi uruchomienia bezterminalowe pozostawiają je na miejscu. - Doctor skanuje także
~/.openclaw/cron/jobs.json(lubcron.store) pod kątem starszych kształtów zadań cron i przepisuje je przed zaimportowaniem kanonicznych wierszy do SQLite. - Doctor zgłasza zadania cron z jawnymi nadpisaniami
payload.model, w tym liczbę przestrzeni nazw providerów i niezgodności względemagents.defaults.model, dzięki czemu zaplanowane zadania, które nie dziedziczą domyślnego modelu, są widoczne podczas dochodzeń dotyczących uwierzytelniania lub rozliczeń. - W systemie Linux doctor ostrzega, gdy crontab użytkownika nadal uruchamia starszy
~/.openclaw/bin/ensure-whatsapp.sh; ten skrypt nie jest już utrzymywany i może logować fałszywe awarie WhatsApp Gateway, gdy cron nie ma środowiska user-bus systemd. - Gdy WhatsApp jest włączony, doctor sprawdza zdegradowaną pętlę zdarzeń Gateway przy nadal działających lokalnych klientach
openclaw-tui.doctor --fixzatrzymuje tylko zweryfikowanych lokalnych klientów TUI, aby odpowiedzi WhatsApp nie były kolejkowane za nieaktualnymi pętlami odświeżania TUI. - Doctor przepisuje starsze referencje modeli
openai-codex/*na kanoniczne referencjeopenai/*w modelach głównych, fallbackach, modelach generowania obrazów/wideo, nadpisaniach heartbeat/subagent/compaction, hookach, nadpisaniach modeli kanałów i nieaktualnych przypięciach tras sesji.--fixmigruje także starsze profile uwierzytelnianiaopenai-codex:*i wpisyauth.order.openai-codexdoopenai:*, przenosi intencję Codex do wpisówagentRuntime.id: "codex"ograniczonych do providera/modelu, usuwa nieaktualne przypięcia runtime całego agenta/sesji i utrzymuje naprawione referencje agentów OpenAI na routingu uwierzytelniania Codex zamiast bezpośredniego uwierzytelniania kluczem API OpenAI. - Doctor czyści starszy stan stagingu zależności Plugin utworzony przez starsze wersje OpenClaw i ponownie linkuje pakiet hosta
openclawdla zarządzanych Plugin npm, które deklarują go jako zależność peer. Naprawia także brakujące pobieralne Plugin, do których odwołuje się konfiguracja, takie jakplugins.entries, skonfigurowane kanały, skonfigurowane ustawienia providerów/wyszukiwania lub skonfigurowane runtime agentów. Podczas aktualizacji pakietów doctor pomija naprawę Plugin przez menedżera pakietów, dopóki podmiana pakietu się nie zakończy; uruchom potem ponownieopenclaw doctor --fix, jeśli skonfigurowany Plugin nadal wymaga odzyskania. Jeśli pobieranie się nie powiedzie, doctor zgłasza błąd instalacji i zachowuje skonfigurowany wpis Plugin na kolejną próbę naprawy. - Doctor naprawia nieaktualną konfigurację Plugin, usuwając brakujące identyfikatory Plugin z
plugins.allow/plugins.deny/plugins.entries, a także pasującą osieroconą konfigurację kanałów, cele heartbeat i nadpisania modeli kanałów, gdy wykrywanie Plugin działa poprawnie. - Doctor poddaje kwarantannie nieprawidłową konfigurację Plugin, wyłączając dotknięty wpis
plugins.entries.<id>i usuwając jego nieprawidłowy payloadconfig. Uruchamianie Gateway już pomija tylko ten wadliwy Plugin, więc inne Plugin i kanały mogą nadal działać. - Ustaw
OPENCLAW_SERVICE_REPAIR_POLICY=external, gdy inny supervisor zarządza cyklem życia Gateway. Doctor nadal zgłasza kondycję Gateway/usługi i stosuje naprawy niezwiązane z usługą, ale pomija instalację/uruchamianie/restart/bootstrap usługi oraz czyszczenie starszych usług. - W systemie Linux doctor ignoruje nieaktywne dodatkowe jednostki systemd podobne do Gateway i podczas naprawy nie przepisuje metadanych polecenia/entrypointu dla działającej usługi Gateway systemd. Najpierw zatrzymaj usługę albo użyj
openclaw gateway install --force, gdy celowo chcesz zastąpić aktywny launcher. - Doctor automatycznie migruje starszą płaską konfigurację Talk (
talk.voiceId,talk.modelIdi powiązane) dotalk.provider+talk.providers.<provider>. - Powtarzane uruchomienia
doctor --fixnie zgłaszają już ani nie stosują normalizacji Talk, gdy jedyną różnicą jest kolejność kluczy obiektu. - Doctor zawiera kontrolę gotowości wyszukiwania w pamięci i może zalecić
openclaw configure --section model, gdy brakuje poświadczeń embeddingów. - Doctor ostrzega, gdy nie skonfigurowano właściciela poleceń. Właściciel poleceń to konto operatora-człowieka uprawnione do uruchamiania poleceń tylko dla właściciela i zatwierdzania niebezpiecznych działań. Parowanie DM pozwala jedynie rozmawiać z botem; jeśli zatwierdzono nadawcę, zanim istniał bootstrap pierwszego właściciela, ustaw jawnie
commands.ownerAllowFrom. - Doctor zgłasza notatkę informacyjną, gdy skonfigurowano agentów w trybie Codex, a osobiste zasoby Codex CLI istnieją w katalogu domowym Codex operatora. Lokalne uruchomienia app-server Codex używają izolowanych katalogów domowych per agent, więc w razie potrzeby najpierw zainstaluj Plugin Codex, a następnie użyj
openclaw migrate plan codex, aby zinwentaryzować zasoby, które należy celowo wypromować. - Doctor usuwa wycofane
plugins.entries.codex.config.codexDynamicToolsProfile; app-server Codex zawsze utrzymuje natywne narzędzia workspace Codex jako natywne. - Doctor ostrzega, gdy Skills dozwolone dla domyślnego agenta są niedostępne w bieżącym środowisku runtime, ponieważ brakuje binariów, zmiennych env, konfiguracji lub wymagań systemu operacyjnego.
doctor --fixmoże wyłączyć te niedostępne Skills za pomocąskills.entries.<skill>.enabled=false; zamiast tego zainstaluj/skonfiguruj brakujące wymaganie, gdy chcesz zachować aktywny Skill. - Jeśli tryb sandbox jest włączony, ale Docker jest niedostępny, doctor zgłasza ostrzeżenie o wysokim sygnale wraz z naprawą (
install Dockeralboopenclaw config set agents.defaults.sandbox.mode off). - Jeśli istnieją starsze pliki rejestru sandbox lub katalogi shardów (
~/.openclaw/sandbox/containers.json,~/.openclaw/sandbox/browsers.json,~/.openclaw/sandbox/containers/lub~/.openclaw/sandbox/browsers/), doctor je zgłasza;openclaw doctor --fixmigruje prawidłowe wpisy do SQLite i poddaje kwarantannie nieprawidłowe starsze pliki. - Jeśli
gateway.auth.token/gateway.auth.passwordsą zarządzane przez SecretRef i niedostępne w bieżącej ścieżce polecenia, doctor zgłasza ostrzeżenie tylko do odczytu i nie zapisuje poświadczeń fallback w postaci zwykłego tekstu. W przypadku SecretRefs opartych na exec doctor pomija wykonanie, chyba że obecne jest--allow-exec. - Jeśli inspekcja SecretRef kanału nie powiedzie się w ścieżce naprawy, doctor kontynuuje i zgłasza ostrzeżenie zamiast kończyć działanie przedwcześnie.
- Po migracjach katalogu stanu doctor ostrzega, gdy włączone domyślne konta Telegram lub Discord zależą od fallbacku env, a
TELEGRAM_BOT_TOKENlubDISCORD_BOT_TOKENjest niedostępny dla procesu doctor. - Automatyczne rozpoznawanie nazw użytkowników Telegram
allowFrom(doctor --fix) wymaga rozwiązywalnego tokena Telegram w bieżącej ścieżce polecenia. Jeśli inspekcja tokena jest niedostępna, doctor zgłasza ostrzeżenie i pomija automatyczne rozpoznawanie w tym przebiegu.
macOS: nadpisania env launchctl
Jeśli wcześniej uruchomiono launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (lub ...PASSWORD), ta wartość nadpisuje plik konfiguracji i może powodować trwałe błędy „unauthorized”.