OpenRouter "is not a valid model ID": causes and the right ID
OpenRouter's 400 "<id> is not a valid model ID" means the model string matches nothing it serves. Read the ID in the message, find the real one, write it right.
OpenRouter answers HTTP 400 with “<id> is not a valid model ID” when the model string it received matches nothing it serves. The string in the message is exactly what your agent sent, so read it first: an extra prefix such as openrouter/, an alias or display name instead of an ID, a misspelling, spaces, or a model that has been retired. The key is not what it is refusing; a bad key gets a 401. Get the real ID from the model’s page or from https://openrouter.ai/api/v1/models (it looks like qwen/qwen3.6-27b), then give it to your agent in the form that agent expects, which for OpenClaw and OpenCode means openrouter/ in front of it.
What the error looks like
The body is OpenRouter’s usual error shape, with the status repeated in code. This one is from a LiteLLM report of March 2026, as the library printed it:
OpenrouterException - {"error":{"message":"openrouter/google/gemini-2.5-flash is not a valid model ID","code":400}}CopiedAgents show it in their own wrapping: “run error: 400 …” in OpenClaw, “HTTP 400: …” in Hermes. OpenRouter’s documentation does not list this message; it falls under 400, “invalid or missing params”. Two things follow from where it comes. Retrying sends the same string and gets the same answer. And the key is not the problem: Claude Code’s gateway docs treat an error naming an unknown model as proof that the URL and credential work. A missing or wrong key gets a 401 instead (the 401 guide decodes those).
Read the ID in the message
Compare the string OpenRouter quotes with the ID on the model’s page. The cases reported on the agents’ trackers fall into these:
- The agent’s own prefix went out with it.
openrouter/google/gemini-2.5-flashis LiteLLM’s name for the model, not OpenRouter’s; in that report, LiteLLM v1.82.3 sent the whole thing, and a user found a later release worked. If the quoted ID starts withopenrouter/and the model is not one of OpenRouter’s own (below), the tool failed to strip its prefix: update it, or check that the model is set where that tool expects an OpenRouter model. - A prefix that belongs was stripped. OpenRouter’s own routers live under
openrouter/themselves (openrouter/auto,openrouter/fusion), so an agent that adds its ownopenrouter/has to keep theirs: OpenClaw writes Fusion asopenrouter/openrouter/fusionin its OpenRouter docs (its default, automatic routing, is writtenopenrouter/auto). OpenClaw once stripped the inner prefix and got this 400 foropenrouter/aurora-alpha; the fix was merged in February 2026. - An alias or a display name. In a Hermes report from November 2026 (v0.23.1), an alias set as the default model on gateway sessions went to OpenRouter as the literal word: “HTTP 400: myalias is not a valid model ID”. The fix was still an open pull request on November 22; until it ships, put the real ID in
model.default. A name like “Qwen3.6 27B” is a label, never an ID. - A near miss. OpenCode 1.14.41 sent
qwen/qwen-3.6-27bfor a model whose ID isqwen/qwen3.6-27b(the report never found where the extra dash came from). One character is enough. Check dots against dashes, version numbers, and the vendor before the slash. - Spaces. OpenClaw 2026.4.8’s cron tool saved model IDs with spaces after each slash, and the job failed with “400 minimax/minimax-m2.5-free is not a valid model ID (format)”. It was fixed by 2026.4.23, and
openclaw doctor --fixnormalises jobs saved before that. A model that works in chat and fails only in a scheduled job points to the job’s saved copy. - A
-latestalias without its tilde. OpenRouter’s latest aliases are written~author/family-latest, and the tilde is part of the ID: DataLLM Lab, an LLM gateway company, reports thatz-ai/glm-flash-latestgot this 400 where~z-ai/glm-flash-latestworked. - A model, or a
:freeversion, that is gone. Free versions in particular are withdrawn on a date shown on their page and then drop out of the models list, astencent/hy3:freedid on July 21, 2026. OpenRouter does not document what a retired ID returns, and users report both this 400 and a 404. If the ID was right last month and is missing from the list now, it is retired: pick another model.
Suffixes after the colon
OpenRouter’s variants page sorts suffixes into two kinds, and they behave differently:
:free,:batchare versions of particular models, and “Only the models that list them support them.” A:freeon a model that has no free version “does not fall back to the base model”; the request fails.:thinkingand:extendedare deprecated (the reasoning parameter replaces the first, and no model offers the second).:nitro,:floor,:exactochange how providers are chosen and “are accepted on any model ID”, so they are never the reason an ID is rejected. They do not appear in the models list.:onlineis one of these too, deprecated in favour of theopenrouter:web_searchserver tool.
An ID takes at most one of the first kind, and OpenRouter adds that “Only the suffixes listed on this page are variants.” When a :free version is gone, its advice is to treat it as an unavailable model, “not as a signal to retry with the base slug”: the paid ID is a different model to choose deliberately, since it bills your credits.
Finding the right ID
On the web, the model’s page address is its ID: openrouter.ai/qwen/qwen3.6-27b is qwen/qwen3.6-27b. From a terminal, the models API lists every ID, and the list needs no key:
curl -s https://openrouter.ai/api/v1/models | jq -r '.data[].id' | grep -i qwen3.6CopiedThe list holds text-output models by default (add ?output_modalities= to ask for others). To check one ID before handing it to an agent:
curl -s https://openrouter.ai/api/v1/model/qwen/qwen3.6-27b \
| jq '.data | {id, canonical_slug, expiration_date}'CopiedOn November 22, 2026 that gave qwen/qwen3.6-27b with no expiry date, and the misspelt qwen/qwen-3.6-27b gave a 404. Three fields are worth knowing. id is what goes in the request. canonical_slug is a dated name that “never changes”, useful for recognising the model later. expiration_date is set when the model is due to be withdrawn, which is your warning before this error starts. This lookup is a little more forgiving than a request: it resolves old aliases, so anthropic/claude-3-5-sonnet comes back as anthropic/claude-3.5-sonnet. Copy the id it returns rather than the one you typed.
For a model that follows a family, the ~ aliases such as ~anthropic/claude-sonnet-latest move to each new release by themselves; OpenRouter’s advice when you need the same model every time is to call the concrete ID instead.
How each agent wants the ID written
Some agents put their own provider name in front of OpenRouter’s ID and take it off before sending; others pass the ID through as written. Getting this wrong in either direction produces the error. As their docs state it in November 2026:
| Agent | Where the model goes | How it is written |
|---|---|---|
OpenClaw | openclaw models set, /model, agents.defaults.model.primary | openrouter/qwen/qwen3.6-27b; Fusion: openrouter/openrouter/fusion |
OpenCode | opencode.json model, /models | openrouter/qwen/qwen3.6-27b |
Hermes | model.default with provider: openrouter | qwen/qwen3.6-27b |
Codex | model in ~/.codex/config.toml, or -m | qwen/qwen3.6-27b |
Claude Code | ANTHROPIC_DEFAULT_*_MODEL, --model | ~anthropic/claude-sonnet-latest or a pinned Anthropic ID |
In OpenClaw, the part after the first openrouter/ must be the whole OpenRouter ID, and openclaw models list --provider openrouter shows the strings it knows. In Hermes, hermes config get model --json shows the active model, and hermes model picks one from the provider’s list and writes it to the config. In Claude Code, a [1m] on the end is allowed: OpenRouter strips it before routing. Claude Code is the one agent here where non-Claude models are unsupported by both Anthropic and OpenRouter. The full setup for the last three, key and all, is in using OpenRouter with Codex, OpenCode and Claude Code.
If the ID is right and it still fails
Once OpenRouter accepts the ID, the next refusals are different messages with different fixes. “No endpoints found that support tool use” or “No allowed providers are available” mean the model exists but no provider of it can take this request (the no-endpoints guide). “Provider returned error” is the company running the model refusing, with its reason inside (the provider-error guide). And in Claude Code, OpenRouter’s own page says a model-not-found error for an OpenRouter-only model such as openrouter/auto is “Usually caused by a credential conflict”, an old Anthropic sign-in still active, which /logout clears.