Best models for OpenClaw, and how to change the model

Our picks for the best models for OpenClaw on a caft plan, and three ways to change the model: openclaw.json, the openclaw models command, or /model in a chat.

Our pick for OpenClaw on a caft plan is GLM 5.3 as the primary model, with Kimi K3 and then GLM 5.3 Flash behind it as fallbacks. All three run on plan credits. To change the model, run openclaw models set caft/glm-5.3, or type /model caft/glm-5.3 inside a chat to switch just that session.

We put this guide together from OpenClaw's documentation for release 2026.10.9, read on November 2, 2026, plus caft's own plan rules. Where the docs give an exact message or number, you'll find it quoted here with a link back.

The best models for OpenClaw on a caft plan

OpenClaw's advice fits in three lines. Its models page says to set your primary to "the strongest latest-generation model available to you" and to keep fallbacks for cost-sensitive tasks and lower-stakes chat. For agents that use tools or handle untrusted input, it says to "avoid older/weaker model tiers."

That last line is the one people skip. An OpenClaw agent that reads your inbox or browses the web runs tools on untrusted input, which is the case the docs mean. So the primary should be a vendor's top tier, not a Flash model. The caft docs put GLM 5.3 Flash in their setup snippet, and that's fine for a first run. For an agent with real access, move up a tier.

We'd start with GLM 5.3. It's Z.ai's flagship, and in our own OpenCode agent team it runs the orchestrator, the agent that spends its time calling tools and handing work to other agents. Kimi K3.1 Pro, Qwen 3.8 Max and Gemini 3.1 Pro are on the plans too, if you'd rather start with another family.

For the first fallback, switch families. If GLM 5.3 keeps failing, Kimi K3 (the model our team plans with) takes the turn. GLM 5.3 Flash goes last. It's the fast, cheap tier, which is where OpenClaw's docs want low-stakes chat to land. The plans page keeps the live list of covered models and shows how far the credits go on each one.

How do you change the model in OpenClaw?

There are three ways in, and they don't all write to the same place.

Edit openclaw.json

The config lives at ~/.openclaw/openclaw.json. Set OPENCLAW_CONFIG_PATH to use a different file. It's JSON5, so comments and trailing commas are fine. The model sits under agents.defaults.model, with fallbacks tried in order:

JSON

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "caft/glm-5.3",
        "fallbacks": ["caft/kimi-k3", "caft/glm-5.3-flash"]
      }
    }
  }
}

Save it and you're done. The gateway watches the file, and the hot-reload docs say agent model selection and fallbacks apply without a restart. A typo can't take a running gateway down either. An invalid edit leaves the last good config in place, and the log reads config reload skipped (invalid config).

The trouble shows up at the next start. Unknown keys or bad values make the gateway refuse to boot, and openclaw gateway run exits with code 78. openclaw doctor --fix repairs legacy keys.

Use the openclaw models command

openclaw models set writes agents.defaults.model.primary for you, and openclaw models fallbacks manages the list behind it. Run openclaw models with nothing after it to see what OpenClaw resolved: the default, the fallbacks and an overview of auth.

Shell

openclaw models set caft/glm-5.3
openclaw models fallbacks add caft/kimi-k3
openclaw models fallbacks add caft/glm-5.3-flash
openclaw models

Typing caft/glm-5.3-flash gets old fast. openclaw models aliases add flash caft/glm-5.3-flash lets you write flash in models set and the fallback commands. The CLI reference lists the rest of the flags.

Type /model in a chat

Inside a conversation, /model caft/glm-5.3-flash switches the current session and nothing else. Add -a to make it the agent's default as well, or -g to change the shared global default. /model list browses providers, and /model default -s clears the session's choice.

Text

/model caft/glm-5.3-flash
/model caft/glm-5.3 -a
/model default -s

A model you pick this way is strict. If it fails, OpenClaw doesn't fall back for that session. And if a run is still going when you switch, the change waits for the next clean retry point. An idle agent picks it up on the next run.

Why does OpenClaw still use the old model?

Session pins. Changing the primary, in the file or with openclaw models set, doesn't touch sessions that already have a model, and that includes the pin a session gets the moment it's created. OpenClaw says so in the status:

Text

This session is pinned to X; config primary Y will apply to new/unpinned sessions.

Run /model default in that session to drop the pin. A pin you set with /model is stubborn: it survives /new, /reset, session rollover and compaction. For a planned switch, OpenClaw's docs suggest a fresh session.

Add caft as a provider in openclaw.json

Put this in ~/.openclaw/openclaw.json, merged with whatever you already have. It's the OpenClaw setup from the caft docs with all three models and the fallbacks filled in.

JSON

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "caft/glm-5.3",
        "fallbacks": ["caft/kimi-k3", "caft/glm-5.3-flash"]
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "caft": {
        "baseUrl": "https://api.caft.dev/v1",
        "apiKey": "${CAFT_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "glm-5.3", "name": "GLM 5.3 (caft)" },
          { "id": "kimi-k3", "name": "Kimi K3 (caft)" },
          { "id": "glm-5.3-flash", "name": "GLM 5.3 Flash (caft)", "contextWindow": 1000000 }
        ]
      }
    }
  }
}

The provider key and the model id make the reference you use everywhere else, so caft plus glm-5.3 becomes caft/glm-5.3.
"api": "openai-completions" is the adapter for Chat Completions endpoints, which is what caft serves. OpenClaw turns off the developer role for custom endpoints like this one, to dodge 400 errors from providers that reject it.
With no contextWindow and nothing discovered from the provider, OpenClaw budgets 200,000 tokens per model. GLM 5.3 Flash takes 1M on caft, so the block says so.
Leave maxTokens out and OpenClaw sends neither max_tokens nor max_completion_tokens, so each model's own default applies. OpenCode does the opposite and asks for 32,000 (see our opencode.json guide).

The custom provider docs cover the optional fields, from reasoning to cost. Any ID on the caft models page works in the models list.

Give the gateway your caft key

OpenClaw's gateway runs in the background, so a key you export in a terminal may never reach it. The environment docs list where it looks, in order: its own process environment, a .env in the working directory, ~/.openclaw/.env, the env block in openclaw.json, and an optional import from your login shell.

The working-directory .env ignores provider credentials, so it's the wrong home for the key. Use ~/.openclaw/.env, the file the docs recommend for provider keys:

Shell

# ~/.openclaw/.env
CAFT_API_KEY=sk-...

Then restart the gateway and check that it came back:

Shell

openclaw gateway restart
openclaw gateway status

The hot-reload docs talk about openclaw.json and say nothing of .env, which is why the restart. A missing variable won't stop OpenClaw. The literal text ${CAFT_API_KEY} stays in the config, OpenClaw logs a warning, and anything that needs the key treats it as unavailable. A request that reaches caft without a valid key gets this back:

Text

Invalid API key. Pass it as `Authorization: Bearer sk-...`, and check the key has not been revoked.

Fallbacks and caft plan limits

Fallbacks rescue you from one model having a bad day. A plan limit isn't that. When a plan window runs out, caft answers with HTTP 429, code plan_limit, and a Retry-After header that counts the seconds to the reset. The example in caft's plans docs reads retry-after: 7800, a little over two hours.

OpenClaw caps a Retry-After wait at 60 seconds by default, per its failover docs, and counts rate limits as a reason to try the next model. Here the next model is another plan model, and every plan model spends the same credits. It gets the same 429. When OpenClaw does switch, the chat shows a line in this shape:

Text

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

To keep the agent working past a limit, turn on Use balance under Billing. Requests past the limit then bill your balance at per-token prices, and OpenClaw never sees an error, as long as the balance has money in it. Without it, the agent waits for the window. The 5-hour one resets five hours after your first request in it.

The other 429 is the requests-a-minute cap: 60, 120 and 240 on the $10, $25 and $50 plans. It clears inside a minute, which suits OpenClaw's own retries. Those back off for up to 60 seconds between tries.

If you run OpenCode next to OpenClaw, our opencode.json guide sets up the same caft models there, down to the errors.