From 49ccc73f44239e2bcf2c3760445c27ed1d4e90a2 Mon Sep 17 00:00:00 2001 From: Dvir Arad Date: Sat, 25 Jul 2026 08:51:22 +0300 Subject: [PATCH] docs(claude-code): document unprefixed model IDs and the Ambiguous model error (#8410) Claude Code always sends bare (unprefixed) model IDs such as claude-opus-4-8. When both the Claude Code (cc) and Claude (claude) providers are connected, that bare id resolves to two routes and the gateway returns a 400 'Ambiguous model' error, which the guide never mentioned. Add a Troubleshooting entry covering both fixes: pinning a prefixed ANTHROPIC_MODEL, or enabling the 'Prefer Claude Code for unprefixed Claude models' setting (dashboard toggle / OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS), linking to the environment reference where the flag is documented. Closes #8311 --- docs/guides/CLAUDE-CODE-CONFIGURATION.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/guides/CLAUDE-CODE-CONFIGURATION.md b/docs/guides/CLAUDE-CODE-CONFIGURATION.md index a34ee464fd..e8c916d12f 100644 --- a/docs/guides/CLAUDE-CODE-CONFIGURATION.md +++ b/docs/guides/CLAUDE-CODE-CONFIGURATION.md @@ -1,7 +1,7 @@ --- title: "Claude Code CLI — Configuration with OmniRoute" version: 3.8.40 -lastUpdated: 2026-06-28 +lastUpdated: 2026-07-24 --- # Claude Code CLI — Configuration with OmniRoute @@ -144,6 +144,16 @@ v2.1.129+ and `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`. Only `claude*` / `anthropic*` model IDs appear in the picker; force any other model with `ANTHROPIC_MODEL=` (this is what profiles do). +**`400 Ambiguous model 'claude-…'`** — Claude Code always sends **unprefixed** +model IDs (e.g. `claude-opus-4-8`), so when both the Claude Code (`cc/…`) and +Claude (`claude/…`) providers are connected the bare id matches two routes and +OmniRoute refuses to guess. Fix it either way: pin a prefixed id with +`ANTHROPIC_MODEL=cc/claude-opus-4-8`, or enable **Prefer Claude Code for +unprefixed Claude models** — the toggle on the Claude provider page, or +`OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true` (default off; +see [Environment](../reference/ENVIRONMENT.md)) — which routes bare `claude-*` +IDs to Claude Code instead. Explicit provider prefixes always win. + **Auth errors** — the profile holds no token. Use `omniroute launch --profile` (injects it) or export `ANTHROPIC_AUTH_TOKEN`.