Fixing Your OpenClaw Setup with the Doctor Command

I have been there before: you change a configuration file, restart your service, and suddenly nothing works. You spend way too much time staring at logs or wondering if a hidden environment variable is causing a conflict. It is frustrating when you just want your gateway to run, but you are stuck hunting for a typo or a permission error.

To help with this, I use the doctor command. It is a built-in tool designed to find what is wrong with your gateway and channels so you can get back to work.

What You’ll Need

• OpenClaw installed on your system
• Terminal access to run CLI commands

Quick Start

The fastest way to check your system health is to run the base command. It scans your setup and reports any issues it finds.

openclaw doctor

If you want the tool to attempt to fix the problems it finds, use the --repair flag (or its alias --fix). When you run this, the tool creates a backup of your configuration at ~/.openclaw/openclaw.json.bak. It will also remove any unknown configuration keys and list exactly what it deleted.

openclaw doctor --repair

For a more thorough scan, you can use the deep check:

openclaw doctor --deep

Troubleshooting

Prompts are being skipped

If you are running the doctor in a headless environment—like a cron job, a Telegram bot, or any setup without a terminal—you might notice it skips interactive fixes. Prompts for things like OAuth or keychain fixes only run when stdin is a TTY. If you have --non-interactive set, these prompts will also stay hidden.

Persistent “unauthorized” errors on macOS

I have seen cases where macOS users face “unauthorized” errors that won’t go away, even after updating the config file. This usually happens because of launchctl environment overrides. If you previously set a token or password via launchctl, those values take priority over your config file.

You can check if these overrides exist with these commands:

launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

If they return a value, you should clear them to let your config file take over:

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

If you still run into issues, you can chat with the AI Setup Assistant for more help.

What’s Next

• Troubleshooting Guide
• Security Audit Docs