Fix OpenClaw Issues: Run Diagnostics and Repairs

Repair and Migrate with OpenClaw Doctor

The OpenClaw doctor command is the primary tool you will use to maintain the health of your system. It identifies issues with your configuration and provides clear steps to get your system running again.

1. Run the CLI command to check the overall health of your OpenClaw instance.
2. Fix stale JSON configuration files or state data that might be outdated.
3. Use the tool to handle migrations when you update your Gateway version.
4. Follow the actionable repair steps provided directly in your terminal.

Getting started with OpenClaw is straightforward, especially when you use the built-in diagnostic tools to ensure your environment is ready. The OpenClaw doctor command helps you verify your setup and fix common issues in seconds.

Run the OpenClaw doctor quick start

If you ever feel like your setup is acting up, the OpenClaw doctor command is your best friend for diagnosing issues. It scans your environment to make sure everything is running exactly as it should.

1. Run the basic diagnostic command:

openclaw doctor

Automate OpenClaw doctor in headless mode

When you are running scripts or working in a CI environment, you probably don’t want to sit there clicking “yes” to every prompt. You can use specific flags to make the OpenClaw CLI handle everything automatically.

1. Use the --yes flag to accept all default suggestions without being prompted:

openclaw doctor --yes

2. This command accepts defaults for everything, including handling restarts, service fixes, and sandbox repairs whenever they are applicable to your setup.

3. If you want to apply recommended repairs automatically, use the repair flag:

openclaw doctor --repair

4. This will trigger repairs and restarts in cases where the system determines it is safe to do so.

5. For more aggressive fixes that might overwrite your custom supervisor configs, add the force flag:

openclaw doctor --repair --force

6. If you need to run migrations without any human confirmation, use the non-interactive mode:

openclaw doctor --non-interactive

7. This mode runs without prompts and only applies safe migrations, such as JSON config normalization and moving on-disk state. It skips any actions that require a manual check, like service or sandbox restarts. Legacy state migrations will run automatically if the CLI detects them.

Perform a deep scan for OpenClaw Gateway

Sometimes a standard check isn’t enough, especially if you have multiple instances or hidden services running in the background. You can tell OpenClaw to look deeper into your system’s background processes to find every instance.

1. Run a deep scan to find extra Gateway installs across different system services like launchd, systemd, or schtasks:

openclaw doctor --deep

Review your OpenClaw JSON configuration

Before you let the doctor make any permanent changes, it is often a good idea to see what is actually inside your settings. You can peek at the raw configuration file directly from your terminal to verify your current state.

1. Open your configuration file to review the current settings before writing any changes to the disk:

cat ~/.openclaw/openclaw.json

Update OpenClaw Git Installs and UI Protocols

OpenClaw provides a diagnostic suite that automates the maintenance of your environment. This summary covers how the tool handles everything from configuration updates to security audits.

1. Run the optional pre-flight update for git installs during interactive sessions.
2. Check the UI protocol freshness and rebuild the Control UI when the protocol schema is newer.
3. Perform a health check and respond to the restart prompt if needed.

Monitor OpenClaw Skills and Plugin Status

You can see exactly which features are ready to use and which ones might be blocked by missing dependencies. This summary helps you track the health of your plugins and active skills.

1. Review the status summary for skills that are eligible, missing, blocked, or inactive.
2. Check the current status of all installed plugins.

Migrate Legacy OpenClaw Config and Talk Settings

Your configuration needs to stay organized as the platform grows and introduces new features. The tool automatically moves your old settings into the modern JSON structure.

1. Normalize configuration values from legacy formats to ensure consistency.
2. Migrate legacy flat talk.* fields into the new talk.provider and talk.providers.<provider> structure.
3. Run browser migration checks for legacy Chrome extension configs and verify Chrome MCP readiness.

Audit OpenClaw Model Providers and OAuth Security

Security is a top priority when you are connecting to external API services. These checks identify potential conflicts in your provider settings and ensure your OAuth profiles are secure.

1. Identify OpenCode provider override warnings for models.providers.opencode and models.providers.opencode-go.
2. Detect Codex OAuth shadowing warnings within models.providers.openai-codex.
3. Verify OAuth TLS prerequisites for OpenAI Codex OAuth profiles.
4. Check model auth health to refresh expiring tokens and report disabled auth-profile states.

Manage OpenClaw State and File Permissions

Keeping your data safe requires the right file permissions and a clean state directory. The tool migrates your session history and applies strict security rules to your local files.

1. Migrate legacy on-disk state for sessions, agent directories, WhatsApp auth, and local logs.
2. Update legacy plugin manifest keys like speechProviders, realtimeTranscriptionProviders, imageGenerationProviders, and videoGenerationProviders to the new contracts key.
3. Check for legacy plugin manifest keys like realtimeVoiceProviders, mediaUnderstandingProviders, webFetchProviders, and webSearchProviders.
4. Move legacy cron store data including jobId, schedule.cron, top-level delivery, and payload fields.
5. Inspect session lock files and perform a stale lock cleanup.
6. Verify state integrity and permissions for sessions, transcripts, state directories, and cache files.
7. Apply chmod 600 to configuration files when you are running the tool locally.

Diagnose OpenClaw Gateway and Runtime Services

The Gateway must run smoothly to handle your requests without any port conflicts. These diagnostics look at your runtime environment and help repair common service issues.

1. Detect extra workspace directories like ~/openclaw that might cause confusion.
2. Repair Docker sandbox images when you have sandboxing enabled.
3. Migrate legacy services and detect any extra Gateway instances.
4. Perform Gateway runtime checks for services that are installed but not currently running.
5. Diagnose Gateway port collisions on the default port 18789.
6. Audit supervisor configurations for launchd, systemd, schtasks, and other managers with optional repair.
7. Check for systemd linger on Linux and verify Gateway runtime best practices for Node.js or Bun.
8. Check channel status warnings probed from the running Gateway.
9. Review security warnings for open DM policies.
10. Migrate Matrix channel legacy state when running in —fix or —repair mode.

Configure OpenClaw Device Pairing and Workspace

Setting up your workspace and pairing your devices should be a quick process. The tool checks for pairing drift and ensures your shell is ready for CLI commands.

1. Generate local tokens for Gateway auth when no token source exists.
2. Detect device pairing trouble like pending first-time requests, role upgrades, scope upgrades, and stale token cache drift.
3. Check workspace bootstrap file sizes to avoid truncation or near-limit warnings for context files.
4. Install or upgrade shell completion status automatically.
5. Verify memory search embedding provider readiness for local models, remote API keys, QMD binaries, or external services.
6. Check source installations for pnpm workspace mismatches, missing UI assets, missing tsx binaries, and environment errors.
7. Write the updated config and wizard metadata to your disk.

Manage Dreams UI backfill and reset actions

The OpenClaw Control UI Dreams scene provides a set of tools including Backfill, Reset, and Clear Grounded to help you handle your grounded dreaming workflow. While these actions use Gateway doctor-style RPC methods, you should note that they operate independently from the standard openclaw doctor CLI repair and migration tasks.

1. Backfill scans your historical memory/YYYY-MM-DD.md files in the active workspace to run the grounded REM diary pass.
2. It then writes reversible backfill entries directly into your DREAMS.md file.
3. Reset allows you to remove only those specific marked backfill diary entries from DREAMS.md without affecting other data.
4. Clear Grounded removes staged grounded-only short-term entries that originated from historical replay but haven’t gained live recall or daily support.

Use the CLI for advanced memory promotion

It is important to understand what these UI actions do not handle on their own to avoid confusion during your workflow. If your goal is to have historical replays influence the normal deep promotion lane, you will need to use the OpenClaw CLI flow instead of the UI buttons.

1. These actions do not edit your MEMORY.md file directly.
2. They do not execute full doctor migrations across your workspace.
3. They do not automatically stage grounded candidates into the live short-term promotion store.
4. To stage grounded durable candidates into the short-term dreaming store while using DREAMS.md for review, run the openclaw memory rem-backfill —path ./memory —stage-short-term command:

openclaw memory rem-backfill --path ./memory --stage-short-term

Update your OpenClaw git installation

When you run the OpenClaw doctor command, it performs a series of deep diagnostics to ensure your environment is perfectly tuned. If you are working from a git checkout, the tool helps you stay up to date with the latest improvements.

1. The tool detects if you are running in an interactive terminal.
2. It offers to fetch, rebase, and build the project before starting the diagnostic checks.

Normalize your OpenClaw configuration schema

Your configuration might occasionally contain older data structures that need to be aligned with the latest version. The doctor tool handles this normalization automatically to prevent any runtime issues.

1. It looks for legacy value shapes, such as messages.ackReaction without channel-specific overrides, and converts them to the current schema.
2. It rewrites legacy Talk fields, moving flat fields like talk.voiceId or talk.apiKey into the structured talk.provider and talk.providers.<provider> map.

Migrate legacy configuration keys automatically

When your JSON config contains deprecated keys, other commands might refuse to run until you perform a migration. This ensures that your setup remains compatible with the latest OpenClaw features.

1. The doctor explains exactly which legacy keys it found in your configuration.
2. It shows you the specific migration it plans to apply.
3. It rewrites your ~/.openclaw/openclaw.json file with the updated schema.
4. The Gateway also runs these migrations on startup if it detects an old format, so your config is repaired without you having to do anything manually.
5. You can handle cron job store migrations specifically by running the following command:

openclaw doctor --fix

The current migrations include:

• routing.allowFrom → channels.whatsapp.allowFrom
• routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
• routing.groupChat.historyLimit → messages.groupChat.historyLimit
• routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
• routing.queue → messages.queue
• routing.bindings → top-level bindings
• routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
• legacy talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + talk.providers.<provider>
• routing.agentToAgent → tools.agentToAgent
• routing.transcribeAudio → tools.media.audio.models
• messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
• channels.discord.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.<provider>
• channels.discord.accounts.<id>.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.accounts.<id>.voice.tts.providers.<provider>
• plugins.entries.voice-call.config.tts.<provider> (openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.<provider>
• plugins.entries.voice-call.config.provider: "log" → "mock"
• plugins.entries.voice-call.config.twilio.from → plugins.entries.voice-call.config.fromNumber
• plugins.entries.voice-call.config.streaming.sttProvider → plugins.entries.voice-call.config.streaming.provider
• plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold → plugins.entries.voice-call.config.streaming.providers.openai.*
• bindings[].match.accountID → bindings[].match.accountId
• For channels with named accounts but lingering single-account top-level channel values, move those account-scoped values into the promoted account chosen for that channel (accounts.default for most channels; Matrix can preserve an existing matching named/default target)
• identity → agents.list[].identity
• agent.* → 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
• browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
• browser.profiles.*.driver: "extension" → "existing-session"
• remove browser.relayBindHost (legacy extension relay setting)

The tool also provides guidance for multi-account channels:

1. If you have multiple accounts without a defaultAccount set, the doctor warns that routing might pick an unexpected account.
2. If your defaultAccount points to an unknown ID, it lists the valid account IDs for you.

Resolve OpenCode provider overrides

Manually adding certain providers can sometimes interfere with the built-in catalog logic. This can lead to models being routed to the wrong API or incorrect cost tracking.

1. If you have manually added models.providers.opencode, opencode-zen, or opencode-go, it overrides the official OpenCode catalog.
2. The doctor warns you so you can remove the override and restore the correct per-model routing and costs.

Prepare for Chrome MCP and browser migrations

The way OpenClaw handles browser interactions has shifted from an extension-based model to a host-local attach model. This change requires some updates to your browser configuration.

1. The doctor updates browser.profiles.*.driver from "extension" to "existing-session" and removes the old browser.relayBindHost setting.
2. It checks if Google Chrome is installed on your host for auto-connect profiles.
3. It verifies your Chrome version and warns if it is below version 144.
4. It reminds you to enable remote debugging in your browser settings (e.g., chrome://inspect/#remote-debugging).
5. You must have a Chromium-based browser 144+ running locally with remote debugging enabled to use this feature.
6. Note that these checks do not apply to Docker, sandboxes, or remote-browser flows, which continue to use raw CDP.

Verify OAuth TLS prerequisites for OpenAI Codex

When using OpenAI Codex with OAuth, your local environment needs to be able to validate secure certificate chains. The doctor tool probes the connection to ensure everything is configured correctly.

1. The tool probes the OpenAI authorization endpoint to check your local Node.js and OpenSSL TLS stack.
2. If it finds a certificate error like UNABLE_TO_GET_ISSUER_CERT_LOCALLY, it provides platform-specific fix guidance.
3. On macOS with Homebrew, the fix is typically running brew postinstall ca-certificates.
4. You can use the --deep flag to run this probe even if your Gateway appears healthy.

Clean up Codex OAuth provider overrides

Legacy transport settings can sometimes shadow the newer, automated OAuth paths used by recent releases. This can prevent you from getting the best routing and fallback behavior.

1. The doctor warns you if it sees old transport settings under models.providers.openai-codex alongside Codex OAuth.
2. You should remove or rewrite these stale overrides to use the built-in behavior.
3. Custom proxies and header-only overrides are still supported and will not trigger this warning.

Migrate legacy state and disk layouts

As the project grows, the way data is stored on your disk has been reorganized for better management. The doctor tool helps move your sessions and credentials into this new structure.

1. It moves session stores and transcripts from ~/.openclaw/sessions/ to ~/.openclaw/agents/<agentId>/sessions/.
2. It relocates the agent directory to ~/.openclaw/agents/<agentId>/agent/.
3. WhatsApp authentication state is moved to ~/.openclaw/credentials/whatsapp/<accountId>/.
4. While the Gateway and CLI auto-migrate some paths on startup, WhatsApp auth is only migrated when you run the doctor.
5. The tool uses structural equality to compare configurations, so simple changes in key order won’t trigger unnecessary updates.

Update legacy plugin manifests

Plugins have a new way of declaring their capabilities, and the doctor helps you update your installed plugins to match. This ensures that all your tools remain functional and efficient.

1. The tool scans your plugin manifests for deprecated keys like speechProviders or imageGenerationProviders.
2. It offers to move these into the contracts object and update the manifest file.
3. This migration is idempotent, meaning it won’t duplicate data if the contracts key already exists with the same values.

Clean up legacy cron job stores

Your scheduled tasks might be using an older format that needs to be cleaned up for better compatibility. The doctor tool audits your cron store to ensure every job is correctly defined.

1. It checks ~/.openclaw/cron/jobs.json for old job shapes.
2. It renames fields like jobId to id and schedule.cron to schedule.expr.
3. It moves top-level payload and delivery fields into their proper nested objects.
4. It converts legacy notify: true webhooks into explicit delivery.mode="webhook" settings.
5. If a job has a mix of old and new settings that might change its behavior, the doctor will warn you to review it manually.

Remove stale session lock files

If a session exits unexpectedly, it might leave behind a lock file that prevents it from being accessed again. The doctor tool identifies and cleans up these stale files.

1. It scans your agent session directories for write-lock files.
2. It reports the PID and age of the lock, and whether the process is still alive.
3. In --fix or --repair mode, it automatically removes locks that are older than 30 minutes or belong to dead processes.

Check state integrity and safety

Your state directory is the most critical part of your installation, containing all your history and credentials. The doctor tool performs several checks to make sure this data is safe and accessible.

1. It warns you if the state directory is missing and prompts you to recreate it.
2. It verifies that the directory is writable and offers to fix permissions or ownership issues.
3. On macOS, it warns if your state is in a cloud-synced folder like iCloud, which can cause I/O races.
4. On Linux, it flags if you are running on an SD card or eMMC, which can be slow and wear out quickly.
5. It checks for missing transcript files or “1-line JSONL” files where history isn’t accumulating.
6. It warns if you have multiple ~/.openclaw folders across different home directories.
7. If you are in remote mode, it reminds you to run the doctor on the remote host where the state lives.
8. It also checks that your config file permissions are set to 600 to protect your secrets.

Monitor model auth health and OAuth expiry

Keeping your authentication tokens fresh is essential for uninterrupted service. The doctor tool inspects your auth store and helps you refresh tokens before they expire.

1. It warns you when OAuth tokens are expiring or have already expired.
2. In interactive mode, it can refresh these tokens for you.
3. If a refresh fails, it provides the exact command to log in again:

openclaw models auth login --provider ...

4. It also reports if any auth profiles are temporarily unusable due to rate limits or billing failures.

Validate hooks model configuration

If you use hooks like Gmail, the AI model you select must be valid and available in your catalog. The doctor tool ensures your hook settings won’t lead to errors.

1. It validates your hooks.gmail.model against the catalog and your allowlist.
2. It warns you if the model reference won’t resolve or is disallowed.

Repair sandbox Docker images

When you use sandboxing for security, you need the correct images available in your environment. The doctor tool checks your local setup to ensure everything is ready.

1. It checks for the required Docker images when sandboxing is enabled.
2. It offers to build missing images or switch to legacy names if necessary.

Manage bundled plugin runtime dependencies

Some plugins require specific packages to be installed in your environment to function correctly. The doctor tool can identify and install these missing dependencies for you.

1. It verifies runtime dependencies for bundled plugins that are active in your config.
2. If packages are missing, you can install them by running:

openclaw doctor --fix

3. Note that for external plugins, you should continue to use the standard plugin installation commands.

Migrate and clean up Gateway services

Running the Gateway as a system service is the best way to ensure it stays active. The doctor tool helps you migrate from legacy service managers to the current recommended setup.

1. It detects legacy services like launchd, systemd, or schtasks.
2. It offers to remove them and install the current OpenClaw service on your gateway port.
3. It also scans for extra services that might conflict and provides hints for cleaning them up.

Handle Matrix channel migrations

If you use Matrix, there are specific state migrations required to keep your encrypted chats working correctly. The doctor tool handles these complex steps safely.

1. In --fix mode, it creates a pre-migration snapshot of your state.
2. It runs migrations for legacy Matrix state and encrypted-state preparation.
3. These steps are non-fatal, so the Gateway will still attempt to start even if an error occurs.

Audit device pairing and auth drift

Managing paired devices and their permissions is a key part of keeping your setup secure. The doctor tool now provides a detailed view of your device pairing state.

1. It reports pending pairing requests and role or scope upgrades for existing devices.
2. It catches public-key mismatches and stale tokens that have drifted from the approved baseline.
3. It provides specific commands for you to take action:

• Use openclaw devices list to see pending requests.
• Use openclaw devices approve <requestId> to approve a request.
• Use openclaw devices rotate --device <deviceId> --role <role> to refresh a token.
• Use openclaw devices remove <deviceId> to clear a stale record.

Review security warnings and policies

The doctor tool helps you identify potential security risks in your configuration. This ensures that your agents and channels are not exposed to unauthorized access.

1. It warns you if a provider is open to DMs without an allowlist.
2. It flags any policies that are configured in a way that could be dangerous.

Enable systemd linger on Linux

On Linux systems, user services can sometimes be stopped when you log out. The doctor tool ensures that your Gateway stays alive in the background.

1. If you are running as a systemd user service, the tool checks if “lingering” is enabled.
2. It ensures that the Gateway continues to run even after your session ends.

Check workspace status for skills and plugins

Your workspace is where your agent’s skills and plugins live, and keeping it organized is vital. The doctor tool provides a summary of your workspace health.

1. It counts your eligible, missing, and blocked skills.
2. It warns you if legacy workspace directories exist alongside your current one.
3. It reports on the status of your plugins, including any load-time errors or compatibility issues.

Monitor bootstrap file size and character budget

Injecting too much context into your agent can lead to important information being cut off. The doctor tool monitors your bootstrap files to ensure they fit within your character budget.

1. It checks files like AGENTS.md or CLAUDE.md against your configured limits.
2. It reports the raw vs. injected character counts and the percentage of any truncation.
3. If files are being cut off, it gives you tips on how to adjust agents.defaults.bootstrapMaxChars.

Install and optimize shell completion

Tab completion makes using the CLI much faster and more intuitive. The doctor tool ensures that completion is correctly installed and optimized for your shell.

1. It checks for completion support in zsh, bash, fish, and PowerShell.
2. it upgrades slow flexible patterns to a faster cached file variant.
3. It automatically regenerates the cache if it is missing.
4. In interactive mode, it will prompt you to install completion if it’s not already set up.

Verify Gateway auth and local tokens

Securing your Gateway with tokens is a best practice for protecting your data. The doctor tool checks your local token setup to ensure you can authenticate correctly.

1. If you need a token but don’t have one, the tool offers to generate it.
2. It respects SecretRef-managed tokens and won’t overwrite them with plaintext.
3. You can force the generation of a new token with:

openclaw doctor --generate-gateway-token

Perform read-only SecretRef-aware repairs

Fixing your configuration shouldn’t mean exposing your sensitive credentials. The doctor tool uses a secure model to inspect your settings without risking your secrets.

1. The --fix command uses a read-only summary model for targeted repairs.
2. For example, it can use bot credentials for Telegram repairs without crashing if the token is stored in a SecretRef.
3. If a credential is required but unavailable, the tool reports it instead of misreporting it as missing.

Run Gateway health checks and restarts

A quick health check can often identify why your setup isn’t responding as expected. The doctor tool probes the Gateway and helps you get it back on track.

1. It runs a health check and offers to restart the Gateway if it looks unhealthy.

Verify memory search and embedding readiness

If your agent uses memory, the embedding provider must be ready to handle search requests. The doctor tool verifies that your chosen backend and provider are functional.

1. For the QMD backend, it checks if the qmd binary is available and working.
2. For local providers, it looks for the model file or a valid download URL.
3. For remote providers like OpenAI or Voyage, it ensures an API key is present in your environment.
4. You can also verify this at runtime by running:

openclaw memory status --deep

Check channel status and suggested fixes

The doctor tool can probe your active channels to ensure they are online and ready to receive messages. This helps you catch connection issues before they affect your workflow.

1. If the Gateway is healthy, it runs a status probe for all configured channels.
2. It reports any warnings and provides suggested fixes for each issue.

Audit and repair supervisor configurations

Your system service configuration needs to be correct for the Gateway to start reliably. The doctor tool audits your supervisor settings and offers to update them to the latest defaults.

1. It checks launchd, systemd, or schtasks configs for missing or outdated settings.
2. It can rewrite your service files to include better restart delays and network dependencies.
3. You can apply these fixes automatically with:

openclaw doctor --repair

4. Use the --force flag if you need to overwrite custom supervisor configurations.

Diagnose Gateway runtime and port collisions

If the Gateway is installed but not running, there might be a conflict or a crash that needs attention. The doctor tool investigates the runtime state to find the cause.

1. It inspects the service PID and last exit status.
2. It checks for port collisions on the default port 18789 and identifies potential causes like SSH tunnels.

Follow Gateway runtime best practices

Running the Gateway in a stable environment is key to its long-term reliability. The doctor tool warns you about runtime setups that might cause issues during system updates.

1. It flags if you are running on Bun or a version-managed Node.js path like nvm or asdf.
2. Since some channels require a stable Node.js path, it offers to migrate you to a system-wide installation.

Save configuration and wizard metadata

After performing diagnostics and repairs, the doctor tool ensures that all your changes are saved correctly. This keeps your environment in sync with the fixes you’ve applied.

1. It persists any changes made to your configuration file.
2. It records the doctor run in your metadata so the setup wizard knows your environment has been checked.

Get workspace tips for backups and memory

The doctor tool also provides helpful advice on how to improve your overall setup. These tips help you get the most out of your OpenClaw experience.

1. It suggests setting up a workspace memory system if one is missing.
2. It recommends putting your workspace under git (such as a private GitHub repository) for easy backups.