> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# doctor

# `openclaw doctor`

Health checks + quick fixes for the gateway and channels.

Related:

* Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
* Security audit: [Security](/gateway/security)

## Examples

```bash theme={"dark"}
openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
```

Notes:

* Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
* `--fix` (alias for `--repair`) writes a backup to `~/.openclaw/openclaw.json.bak` and drops unknown config keys, listing each removal.
* Telegram checks warn when `channels.telegram.timeoutSeconds` or `channels.telegram.accounts.<id>.timeoutSeconds` is outside the safe 30-50 second polling window. The warning includes the config path, configured value, applied safe value, and `docs.wednesdayai.dev`.
* `wednesdayai doctor --fix` removes unsafe Telegram timeout overrides when the safe applied value is the default 30 seconds, and rewrites above-maximum overrides to the safe maximum 50 seconds.
* Telegram duplicate-poller checks read the running gateway channel-status snapshot and warn when two pollers share one bot token. The warning includes account id and sanitized token fingerprint, never the raw token, with restart or disable guidance.
* State integrity checks now detect orphan transcript files in the sessions directory and can archive them as `.deleted.<timestamp>` to reclaim space safely.
* Doctor includes a memory-search readiness check and can recommend `openclaw configure --section model` when embedding credentials are missing.
* If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (`install Docker` or `openclaw config set agents.defaults.sandbox.mode off`).

## Telegram polling repair

Use this when Telegram messages stop receiving replies and the gateway logs repeated
`Network request for 'getUpdates' failed!` errors.

```bash theme={"dark"}
wednesdayai doctor
wednesdayai doctor --fix
```

Doctor validates both channel-level and account-level Telegram polling timeouts:

| Config path                                      | Safe range    | `--fix` behavior                                          |
| ------------------------------------------------ | ------------- | --------------------------------------------------------- |
| `channels.telegram.timeoutSeconds`               | 30-50 seconds | Removes values below 30; rewrites values above 50 to `50` |
| `channels.telegram.accounts.<id>.timeoutSeconds` | 30-50 seconds | Removes values below 30; rewrites values above 50 to `50` |

Removing a below-minimum override is intentional: the default safe value is already 30 seconds, so
the smaller custom value should not stay in config. Restart the gateway after repair so the polling
client is recreated from the repaired config.

Doctor also reports duplicate Telegram pollers when the running gateway status shows two accounts
trying to own the same bot token. The output uses a sanitized token fingerprint. Fix the duplicate
account or token fallback, then restart the gateway.

## macOS: `launchctl` env overrides

If you previously ran `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent “unauthorized” errors.

```bash theme={"dark"}
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```