OpenClaw 无需更新即可使用新模型：改为三个模型列表来源

When OpenAI shipped GPT-6.1 Sol, people who use OpenClaw with a ChatGPT sign-in could not select it. OpenClaw bundled Codex 0.158.0 but ChatGPT only offers Sol to Codex 0.159.2 and newer, and the only way to change that number was for us to ship a release.

Launch day is when people most want to try a model, and we were the reason they had to wait. So over about five weeks and roughly 80 pull requests, we rebuilt how OpenClaw finds out which models exist.

This post covers the three places OpenClaw now gets its model list from, one fix we shipped and then reverted, and what still needs a release.

How a model used to reach users

Each provider plugin carried its model list in a manifest file, and that file shipped inside the OpenClaw package. Providers ship as plugins and plugins are bound to a release.

OpenClaw now hydrates your model list from three places.

1. A catalog that updates itself

We host a model catalog at catalog.openclaw.ai. A job rebuilds it every four hours. It takes model data from models.dev, lays our own manifests on top, adds prices, and publishes the result. It holds about 1,000 models today.

A running Gateway checks for a newer catalog in the background and switches to it live.

• Before: the Gateway downloads a new catalog and keeps using the old one until you restart it.
• After: new turns use the new catalog. A turn already in progress finishes on the catalog it started with, so its model list and its prices always match.

The publisher also removes models that have been retired or are no longer served by the provider.

E.g. NVIDIA stopped serving 2 models on their API but the catalog still listed them.

How it broke

On September 21, models.dev split its kimi-for-coding entry into two new ones. Our publisher treated one missing provider as a fatal error, so every run failed. GPT-6 Sol and Luna did not reach existing installs in that time. A missing provider now logs a warning, and only that provider goes without fresh data.

2. If your account lists it, you can pick it

The catalog knows what exists in public. Your account knows what you can use. When you sign in to a provider, OpenClaw asks it for your model list and shows every chat model on it, including models newer than your install or models only your account can access.

• OpenAI API key. Before: Unknown model: openai/gpt-5.2, although the account lists it. After: chat models your account lists appear and run.
• Anthropic API key. Before: a new Claude model stays hidden until an OpenClaw release. After: it appears as soon as Anthropic’s model list returns it.
• Claude Code. Before: a fixed list that we maintained. After: the model menu Claude Code reports for your account.
• GitHub Copilot. Before: kimi-k3 fails its first turn with unsupported_api_for_model. After: we read which endpoint each model accepts and use that one.
• Grok subscription. Before: grok-4.7-build-fast offers two thinking levels, off and ultra. After: it offers low, medium, high and xhigh, as its listing says.
• Ollama. Before: you run ollama pull and the model never shows up. After: it shows up on the next refresh.
• OpenCode Go. Before: four models your account serves are missing. After: every listed model appears.

Half of this work was about what a model can do. OpenClaw used to guess thinking levels and request format from the model’s name, which fails on any new model it has never seen. Providers already publish this in their listings, so we read it from there instead.

3. The Codex version problem

This is the Sol bug from the top of the post. ChatGPT decides which models to offer from the Codex version the client reports. An old version gets a shorter list.

First try: report the newest Codex version

Our first fix was simple. Ask npm for the latest Codex version and report that number when we fetch the list. Sol appeared in the picker.

A mistake we learned from

Unfortunately, the list request said 0.161.0, but turns still ran on the bundled 0.160.0, and that binary reports its own version with every request. A model that needed anything newer would appear in the picker and then fail with HTTP 400. We had moved the failure from the picker to the first message, which is worse. We reverted it.

What ships now

OpenClaw looks for a Codex on your PATH. If it is a stable release, newer than the bundled one and on the same major version, OpenClaw does a real handshake with it. If that passes, the same binary fetches the model list and runs your turns. If anything fails, OpenClaw uses the bundled Codex. It never installs anything for you.

This is the Gateway log line from a test run on a Mac with Codex 0.162.1 installed:

[agent/embedded] Codex app-server: using installed ~/.local/bin/codex 0.162.1 (newer than bundled 0.161.0)

Updating your global Codex is now enough to get a model that needs it.

A list that stops shrinking

Finding models was one problem. Keeping them on screen was another. The list used to lose models for reasons that had nothing to do with the user.

OpenRouter times out once

• Before: 466 → 3 models. They stay gone until someone runs a manual refresh.
• After: it retries on its own. First after 30 seconds, then with longer gaps up to 30 minutes.

The Gateway switches to a new catalog

• Before: 599 → 54 models, for up to four minutes on a production Gateway.
• After: 599 the whole time. The old list stays until the new one is complete.

You change the default model

• Before: 68–142 seconds. The Gateway froze while it reloaded every large plugin.
• After: 0.6–1.4 seconds. It reuses the plugins it already has loaded.

Pickers also open at once now. They show the models OpenClaw already knows and fill in the rest in the background. They used to wait up to five seconds for discovery to finish.

A thousand models is too many

Once every model shows up, the list gets long. OpenRouter alone has 466. So the catalog now carries a short recommended list for each provider, and pickers put it first.

This is the same picker on one of our own Gateways. In the OpenAI group, the current model comes first, then the two recommended models, then the other 33 behind one row.

The recommended list is manually curated and updated daily from our own experience + a variety of benchmarks.

Key takeaways

• The version that lists a model must also run it. Reporting one Codex version and running another only moved the failure from the picker to the first message.
• Read capabilities from the listing, not the name. Provider listings already say which thinking levels and endpoints a model supports. Rules based on the model name break on the first model we have never seen.
• Keep the last good list. A failed refresh or a catalog switch should never leave the picker with fewer models than before.
• One broken source should not block the rest. A renamed provider on models.dev stopped catalog updates for every provider until we made it a warning.

What still needs a release

• If you have no newer Codex installed, the bundled version still decides which ChatGPT models you see.
• A model newer than the catalog has no price yet. OpenClaw shows its cost as unknown, and it runs with cautious default limits until the catalog catches up.

To see what your install can reach right now, run openclaw models list --refresh.

What’s next

We will keep improving the experience over time and support more providers. If your account lists a model that OpenClaw does not show, open an issue and include the output of that command.

Acknowledgements

Written by Ayaan Zaidi. Thanks to @vincentkoc for catalog v2 and per-route pricing, @ly85206559 for the models.dev provider aliases, @mcooks-cmd for the catalog worker memory fix, and @steipete for faster multi-provider catalog refreshes.

Main pull requests: catalog from models.dev, live catalog adoption, account model listing, installed Codex selection, discovery retry, recommended models in pickers.