openclaw-quick-setup

A runtime-slash plugin for OpenClaw that detects — and where safe, auto-fixes — silent failures in your gateway configuration.

If your bindings, accounts, or memorySearch are subtly misconfigured, OpenClaw often keeps running but ignores them, fails open, or silently degrades. openclaw doctor and openclaw plugins doctor don't catch most of these. This plugin does.

Install

openclaw plugins install openclaw-quick-setup

Then restart your gateway. The plugin registers a single slash command, /quick-setup, available on every channel that supports slash commands (Discord, Telegram, Slack, Feishu, …).

Usage

/quick-setup            # Run all 5 detect rules, full output with fix hints.
/quick-setup brief      # One line per WARN, no hints. For large multi-agent setups.
/quick-setup help       # Full usage, examples, notes.

/quick-setup apply <rule> <args>   # Auto-fix (writes config; saves a backup first).
/quick-setup rollback              # Undo the most recent apply.

What it detects (5 rules)

| Rule | Catches | |---|---| | binding-missing-account-id | bindings[].match.accountId missing in a multi-account channel → silent fallback to default agent | | binding-unregistered-agent | bindings[].agentId not in agents.list → binding silently no-ops | | ghost-default-account | channels.<ch>.accounts.default coexists with named accounts (residue from top-level policy normalization) | | embedding-provider-credentials | memorySearch.provider has no usable credentials → auto-pick crashes indexing or silently degrades to FTS-only | | plugin-install-path-issue | plugins.installs.<id> path missing or custom → broken on next openclaw upgrade |

Each WARN line includes a copy-pasteable Fix: /quick-setup apply ... syntax.

What it can auto-fix (4 of 5)

| Apply target | Action | |---|---| | apply ghost-default-account <channel> | Deletes channels.<channel>.accounts.default. | | apply binding-missing-account-id <bindingIndex> <accountId> | Sets bindings[i].match.accountId. Use * to match any account on that channel. | | apply binding-unregistered-agent <bindingIndex> <agentId> | Sets bindings[i].agentId to a registered agent. | | apply embedding-provider-credentials <target> <provider> [<modelPath>] | Sets memorySearch provider. <target> = defaults or an agent ID. Validates env credentials for remote providers. Never accepts API keys via slash — set them as env vars on the gateway, then run apply. |

plugin-install-path-issue is intentionally not auto-fixed — it would require shell exec (outside the config-write surface). Run openclaw plugins install <package> manually.

Rollback

/quick-setup rollback restores the previous config from a single-slot backup at ~/.openclaw-quick-setup-backup.json (mode 0600). Each apply overwrites the previous backup, so only the most recent change can be undone.

Why this exists

Two real silent-failure classes that motivated the plugin:

1. Embedding auto-pick crash (gap 1). When memorySearch.provider="auto" (default) and no credentials are detectable, OpenClaw's auto-pick may settle on Bedrock and fail with CredentialsProviderError, or silently degrade memory search to FTS-only. The user never sees a configuration error — just gradually missing memory hits. Tracked upstream as openclaw#71143; the proposed fix (PR openclaw#71245) was rejected by maintainers, so external solutions are needed.

2. Multi-account binding traps (gap 2). In a multi-account channel (e.g., two Discord bots in one guild), omitting match.accountId causes binding to silently route to the default agent. Reported across channels — Discord (#56051), Feishu (#39382), QQBot (#69546) — but no automated detector exists, only docs.

This plugin is a slash-command detector, designed to surface these traps in the place users will actually notice them: in chat. It complements rather than replaces watchdog daemons like openclaw-cli (Sobranier) and clawtool (tunanet), which focus on runtime/uptime monitoring.

Compatibility

• OpenClaw: ≥ 2026.4.21 (the release that introduced the memory module and the plugin-sdk/config-runtime write API used here).
• Node: ≥ 20.
• Channels: any channel with slash-command support. Live-verified on Discord. Other channels (Telegram, Slack, Feishu, …) should work but are unverified.

License

MIT — see LICENSE.