Quick Setup

Name: Quick Setup
Rating: 3.5 (1 reviews)
Author: bykim0119

By bykim0119 👁 40 views ▲ 0 votes

plugin for OpenClaw sub settings

GitHub

Install

openclaw plugins install openclaw-quick-setup

README

# openclaw-quick-setup

A `runtime-slash` plugin for [OpenClaw](https://github.com/openclaw/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

```sh
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](LICENSE).

tools