Principle:Openclaw Openclaw Diagnostic Repair
Diagnostic Repair
Diagnostic Repair is the principle of running a comprehensive, automated suite of health checks across the entire OpenClaw installation -- configuration, authentication, daemon services, shell integration, and gateway connectivity -- with the option to automatically fix detected issues.
Motivation
A multi-channel AI agent gateway has many moving parts: configuration files, authentication credentials for multiple providers, OS-level service definitions, shell completion scripts, sandbox images, and gateway connectivity. When something breaks, operators need a single command that can diagnose the problem and, ideally, fix it without manual intervention.
The openclaw doctor command fulfills this role. It is inspired by tools like brew doctor and flutter doctor but goes further by offering interactive and non-interactive repair modes.
Core Concepts
Diagnostic Suite
The doctor runs a series of checks in a defined order, each targeting a specific subsystem:
- Update availability -- Checks whether a newer version is available and optionally offers to update before proceeding.
- UI protocol freshness -- Verifies the control UI assets are current.
- Source install issues -- Detects problems with the package root (e.g., missing build output).
- Legacy environment variables -- Warns about deprecated environment variable names.
- Configuration migration -- Loads and validates configuration, offering to migrate from legacy formats.
- Authentication health -- Checks OAuth profiles, API keys, and keychain entries for validity.
- Gateway auth -- Ensures the gateway has a proper authentication token configured.
- Legacy state migrations -- Detects and migrates old session, agent, and WhatsApp auth state.
- State integrity -- Validates the consistency of session stores and workspace data.
- Sandbox images -- Checks Docker sandbox images are available and up to date.
- Service configuration -- Verifies the OS service manager (launchd/systemd) configuration.
- Platform-specific notes -- Checks for macOS LaunchAgent overrides, systemd linger, etc.
- Security warnings -- Scans for insecure configuration patterns.
- Model configuration -- Validates that configured AI models are in the catalog and allowlist.
- Shell completion -- Checks and installs shell tab completion.
- Gateway health -- Runs a full health check against the running gateway.
- Daemon repair -- If the gateway is not healthy, offers to restart or reinstall the daemon.
- Workspace suggestions -- Offers optional workspace improvements (e.g., memory system prompts).
- Configuration write -- Persists any configuration changes made during the doctor run.
Repair Modes
The doctor supports three interaction modes:
- Interactive (default) -- Prompts the user before each repair action via
@clack/prompts. - Auto-repair (
--fixor--yes) -- Automatically applies all safe repairs without prompting. - Non-interactive (
--non-interactive) -- Skips all prompts and only reports findings. Used by automated pipelines and the post-update doctor run.
The DoctorPrompter abstraction encapsulates this logic, providing confirm, confirmRepair, confirmAggressive, and confirmSkipInNonInteractive methods that respect the current mode.
Progressive Disclosure
Not all checks require the same level of user attention. The doctor uses the note() function from @clack/prompts to display informational findings (yellow-boxed notes) and only prompts for action when a fix is available. This keeps the output clean while still surfacing all relevant information.
Design Principles
- Single entry point -- One command (
openclaw doctor) covers the entire diagnostic surface. Operators should never need to manually check individual subsystems. - Safe by default -- The doctor never applies destructive changes without confirmation. Even in auto-repair mode, aggressive fixes (like service reinstallation) require the
--forceflag. - Idempotent -- Running doctor multiple times produces the same result. Fixes that have already been applied are detected and skipped.
- Order matters -- Checks are sequenced so that earlier fixes (e.g., configuration migration) enable later checks (e.g., gateway health) to succeed.
- Configuration preservation -- The doctor writes configuration changes atomically and creates a backup file (
openclaw.json.bak) before modifying the active configuration.
Relationship to Other Concepts
Diagnostic Repair depends on Health Monitoring for the gateway health check step. It is invoked automatically by Version Update after applying updates, and it may trigger Gateway Restart if the daemon is not healthy.