Doktor
openclaw doctor to narzędzie naprawcze + migracyjne dla OpenClaw. Naprawia
zastaną konfigurację/stan, sprawdza kondycję i dostarcza konkretne kroki naprawcze.
Szybki start
Tryb bezgłowy / automatyzacja
Co robi (podsumowanie)
- Opcjonalna aktualizacja wstępna dla instalacji git (tylko tryb interaktywny).
- Sprawdzenie świeżości protokołu UI (przebudowuje Control UI, gdy schemat protokołu jest nowszy).
- Kontrola zdrowia + monit o restart.
- Podsumowanie stanu Skills (kwalifikujące się/brakujące/zablokowane).
- Normalizacja konfiguracji dla starszych wartości.
- Ostrzeżenia o nadpisaniach dostawcy OpenCode Zen (
models.providers.opencode). - Migracja starszego stanu na dysku (sesje/katalog agenta/uwierzytelnianie WhatsApp).
- Kontrole integralności stanu i uprawnień (sesje, transkrypty, katalog stanu).
- Kontrole uprawnień pliku konfiguracyjnego (chmod 600) przy uruchomieniu lokalnym.
- Kondycja uwierzytelniania modeli: sprawdza wygaśnięcie OAuth, może odświeżać wygasające tokeny oraz raportuje stany cooldown/wyłączone profili uwierzytelniania.
- Wykrywanie dodatkowych katalogów obszaru roboczego (
~/openclaw). - Naprawa obrazu sandbox, gdy sandboxing jest włączony.
- Migracja starszych usług i wykrywanie dodatkowych gateway.
- Kontrole czasu działania Gateway (usługa zainstalowana, ale nieuruchomiona; zbuforowana etykieta launchd).
- Ostrzeżenia o stanie kanałów (sondowane z działającego gateway).
- Audyt konfiguracji supervisora (launchd/systemd/schtasks) z opcjonalną naprawą.
- Kontrole najlepszych praktyk czasu działania Gateway (Node vs Bun, ścieżki menedżerów wersji).
- Diagnostyka kolizji portu Gateway (domyślnie
18789). - Ostrzeżenia bezpieczeństwa dla otwartych polityk DM.
- Ostrzeżenia uwierzytelniania Gateway, gdy nie ustawiono
gateway.auth.token(tryb lokalny; oferuje generowanie tokenu). - Sprawdzenie systemd linger w systemie Linux.
- Kontrole instalacji ze źródeł (niedopasowanie workspace pnpm, brak zasobów UI, brak binarki tsx).
- Zapisuje zaktualizowaną konfigurację + metadane kreatora.
Szczegółowe zachowanie i uzasadnienie
0. Opcjonalna aktualizacja (instalacje git)
Jeśli jest to checkout git i doctor działa interaktywnie, oferuje aktualizację (fetch/rebase/build) przed uruchomieniem doctor.1. Normalizacja konfiguracji
Jeśli konfiguracja zawiera starsze kształty wartości (na przykładmessages.ackReaction
bez nadpisania specyficznego dla kanału), doctor normalizuje je do bieżącego
schematu.
2. Migracje starszych kluczy konfiguracji
Gdy konfiguracja zawiera przestarzałe klucze, inne polecenia odmawiają działania i proszą o uruchomienieopenclaw doctor.
Doctor:
- Wyjaśnia, które starsze klucze zostały znalezione.
- Pokazuje zastosowaną migrację.
- Przepisuje
~/.openclaw/openclaw.jsondo zaktualizowanego schematu.
routing.allowFrom→channels.whatsapp.allowFromrouting.groupChat.requireMention→channels.whatsapp/telegram/imessage.groups."*".requireMentionrouting.groupChat.historyLimit→messages.groupChat.historyLimitrouting.groupChat.mentionPatterns→messages.groupChat.mentionPatternsrouting.queue→messages.queuerouting.bindings→ najwyższy poziombindingsrouting.agents/routing.defaultAgentId→agents.list+agents.list[].defaultrouting.agentToAgent→tools.agentToAgentrouting.transcribeAudio→tools.media.audio.modelsbindings[].match.accountID→bindings[].match.accountIdidentity→agents.list[].identityagent.*→agents.defaults+tools.*(tools/elevated/exec/sandbox/subagents)agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks→agents.defaults.models+agents.defaults.model.primary/fallbacks+agents.defaults.imageModel.primary/fallbacks
2b) Nadpisania dostawcy OpenCode Zen
Jeśli ręcznie dodanomodels.providers.opencode (lub opencode-zen), nadpisuje to
wbudowany katalog OpenCode Zen z @mariozechner/pi-ai. Może to
wymusić użycie jednego API dla wszystkich modeli lub wyzerować koszty. Doctor ostrzega,
aby można było usunąć nadpisanie i przywrócić per‑modelowe trasowanie API + koszty.
3. Migracje starszego stanu (układ na dysku)
Doctor może migrować starsze układy na dysku do bieżącej struktury:- Magazyn sesji + transkrypty:
- z
~/.openclaw/sessions/do~/.openclaw/agents/<agentId>/sessions/
- z
- Katalog agenta:
- z
~/.openclaw/agent/do~/.openclaw/agents/<agentId>/agent/
- z
- Stan uwierzytelniania WhatsApp (Baileys):
- ze starszego
~/.openclaw/credentials/*.json(z wyjątkiemoauth.json) - do
~/.openclaw/credentials/whatsapp/<accountId>/...(domyślny identyfikator konta:default)
- ze starszego
openclaw doctor.
4. Kontrole integralności stanu (trwałość sesji, routowanie i bezpieczeństwo)
Katalog stanu to operacyjny „pień mózgu”. Jeśli zniknie, tracisz sesje, poświadczenia, logi i konfigurację (chyba że masz kopie zapasowe gdzie indziej). Doctor sprawdza:- Brak katalogu stanu: ostrzega o katastrofalnej utracie stanu, proponuje odtworzenie katalogu i przypomina, że nie może odzyskać brakujących danych.
- Uprawnienia katalogu stanu: weryfikuje możliwość zapisu; oferuje naprawę uprawnień
(i emituje podpowiedź
chown, gdy wykryto niezgodność właściciela/grupy). - Brak katalogów sesji:
sessions/i katalog magazynu sesji są wymagane do utrwalania historii i unikania awariiENOENT. - Niezgodność transkryptów: ostrzega, gdy ostatnie wpisy sesji nie mają plików transkryptów.
- Główna sesja „JSONL z 1 linią”: sygnalizuje, gdy główny transkrypt ma tylko jedną linię (historia się nie kumuluje).
- Wiele katalogów stanu: ostrzega, gdy istnieje wiele folderów
~/.openclaww różnych katalogach domowych lub gdyOPENCLAW_STATE_DIRwskazuje gdzie indziej (historia może dzielić się między instalacje). - Przypomnienie trybu zdalnego: jeśli
gateway.mode=remote, doctor przypomina, aby uruchomić go na hoście zdalnym (tam znajduje się stan). - Uprawnienia pliku konfiguracyjnego: ostrzega, jeśli
~/.openclaw/openclaw.jsonjest czytelny dla grupy/świata i oferuje zaostrzenie do600.
5. Kondycja uwierzytelniania modeli (wygaśnięcie OAuth)
Doctor sprawdza profile OAuth w magazynie uwierzytelniania, ostrzega o wygasających/wygasłych tokenach i może je odświeżyć, gdy jest to bezpieczne. Jeśli profil Anthropic Claude Code jest nieaktualny, sugeruje uruchomienieclaude setup-token
(lub wklejenie setup-token).
Monity odświeżania pojawiają się tylko w trybie
interaktywnym (TTY); --non-interactive pomija próby odświeżania.
Doctor raportuje również profile uwierzytelniania, które są tymczasowo niedostępne z powodu:
- krótkich okresów cooldown (limity szybkości/timeouty/błędy uwierzytelniania)
- dłuższych wyłączeń (problemy z rozliczeniami/kredytem)
6. Walidacja modelu Hooks
Jeśli ustawionohooks.gmail.model, doctor weryfikuje referencję modelu względem
katalogu i listy dozwolonych oraz ostrzega, gdy nie da się jej rozwiązać lub jest niedozwolona.
7. Naprawa obrazu sandbox
Gdy sandboxing jest włączony, doctor sprawdza obrazy Dockera i oferuje budowę lub przełączenie na starsze nazwy, jeśli bieżący obraz jest brakujący.8. Migracje usług Gateway i wskazówki sprzątania
Doctor wykrywa starsze usługi gateway (launchd/systemd/schtasks) i oferuje ich usunięcie oraz instalację usługi OpenClaw z użyciem bieżącego portu gateway. Może też skanować w poszukiwaniu dodatkowych usług podobnych do gateway i wypisywać wskazówki sprzątania. Usługi gateway OpenClaw nazwane profilem są traktowane jako pierwszorzędne i nie są oznaczane jako „dodatkowe”.9. Ostrzeżenia bezpieczeństwa
Doctor emituje ostrzeżenia, gdy dostawca jest otwarty na DM‑y bez listy dozwolonych lub gdy polityka jest skonfigurowana w niebezpieczny sposób.10. systemd linger (Linux)
Jeśli działa jako usługa użytkownika systemd, doctor upewnia się, że włączono lingering, aby gateway pozostawał aktywny po wylogowaniu.11. Status Skills
Doctor drukuje krótkie podsumowanie kwalifikujących się/brakujących/zablokowanych Skills dla bieżącego obszaru roboczego.12. Kontrole uwierzytelniania Gateway (token lokalny)
Doctor ostrzega, gdy na lokalnym gateway brakujegateway.auth, i oferuje
wygenerowanie tokenu. Użyj openclaw doctor --generate-gateway-token, aby wymusić
tworzenie tokenu w automatyzacji.
13. Kontrola zdrowia Gateway + restart
Doctor uruchamia kontrolę zdrowia i oferuje restart gateway, gdy wygląda na niezdrowy.14. Ostrzeżenia o stanie kanałów
Jeśli gateway jest zdrowy, doctor uruchamia sondę stanu kanałów i raportuje ostrzeżenia wraz z sugerowanymi poprawkami.15. Audyt konfiguracji supervisora + naprawa
Doctor sprawdza zainstalowaną konfigurację supervisora (launchd/systemd/schtasks) pod kątem brakujących lub nieaktualnych domyślnych ustawień (np. zależności network‑online systemd i opóźnienia restartu). Gdy znajdzie niezgodność, rekomenduje aktualizację i może przepisać plik usługi/zadanie do bieżących domyślnych ustawień. Uwagi:openclaw doctorpyta przed przepisaniem konfiguracji supervisora.openclaw doctor --yesakceptuje domyślne monity napraw.openclaw doctor --repairstosuje zalecane poprawki bez monitów.openclaw doctor --repair --forcenadpisuje niestandardowe konfiguracje supervisora.- Zawsze możesz wymusić pełne przepisanie przez
openclaw gateway install --force.
16. Diagnostyka czasu działania Gateway + portów
Doctor sprawdza czas działania usługi (PID, ostatni status zakończenia) i ostrzega, gdy usługa jest zainstalowana, ale faktycznie nie działa. Sprawdza też kolizje portów na porcie gateway (domyślnie18789) i raportuje prawdopodobne przyczyny (gateway już
uruchomiony, tunel SSH).
17. Najlepsze praktyki czasu działania Gateway
Doctor ostrzega, gdy usługa gateway działa na Bun lub na ścieżce Node zarządzanej przez menedżer wersji (nvm, fnm, volta, asdf itd.). Kanały WhatsApp + Telegram wymagają Node,
a ścieżki menedżerów wersji mogą się psuć po aktualizacjach, ponieważ usługa nie
ładuje inicjalizacji powłoki. Doctor oferuje migrację do systemowej instalacji Node,
gdy jest dostępna (Homebrew/apt/choco).