How to Configure the OpenClaw Model Allowlist

Model configuration is where a lot of OpenClaw operators accidentally break their own sessions. The important distinction is simple: the primary model chooses what OpenClaw uses by default, while agents.defaults.models is the catalog and allowlist for model switching and overrides. Once you define the allowlist, any session-selected model outside it is rejected before a normal reply is generated.

When this is the right move

Configure the allowlist when you want controlled model choices, aliases in the picker, or a safe set of options for operators. Skip it if you are still experimenting and do not need restrictions. If you already see “Model provider/model is not allowed,” the allowlist is the first place to inspect.

The practical workflow

1. Check your current model config and model catalog before changing anything. You want to know whether the allowlist already exists.
2. Add new model entries with --merge. The docs explicitly call out protected map behavior because plain replacement can remove existing models.
3. Keep model references in provider/model format. The model docs say refs are normalized to lowercase and provider aliases can normalize too.
4. Set the primary and fallbacks separately from the catalog. Primary chooses default behavior; fallbacks control recovery order.
5. Use the chat /model picker or status command to verify the model appears and auth candidates are healthy.

Grounded command or config pattern

The documented safe allowlist edit uses --strict-json and --merge. That is the pattern to memorize.

openclaw config get agents.defaults.models
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config get agents.defaults.model
# In chat:
/model list
/model status

The model docs also separate imageModel, pdfModel, imageGenerationModel, musicGenerationModel, and videoGenerationModel. Do not assume changing the chat primary automatically changes every media tool default; configure those surfaces intentionally when you need provider-specific behavior.

Operator notes

A clean policy has three layers: a strong primary model for serious tool-enabled work, fallbacks for resilience or lower-stakes paths, and an allowlist that reflects what you are willing to let operators choose at runtime. For untrusted inputs and tools, the official docs recommend avoiding older or weaker tiers.

Rollout approach

For configure the openclaw model allowlist, I would make the first pass deliberately small: one owner, one machine or channel, one visible test, and one rollback path. OpenClaw features become powerful when they connect to real tools and real messages, so the safest rollout is not a giant configuration day. It is a short rehearsal that proves the docs-grounded path works in your exact workspace before you depend on it while busy.

Common mistake

The common mistake is treating the command as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and a tiny verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A small note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or machine changes.

Safety checks

Never remove working model entries accidentally during a live operations window. Use --merge for additions and reserve --replace for an intentional full replacement. If credentials are SecretRef-managed, remember that provider auth may resolve from profiles, env vars, config, or provider-specific flows; model presence in the catalog does not guarantee auth is healthy.

How to verify it worked

Run /model list in chat to confirm the model appears, /model status to inspect detail, and a small test request after switching. If the session still says the model is not allowed, either the ref differs from your allowlist entry or the active agent/session is using a different config scope.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.