Repository navigation
docs: document OmniRoute OpenAI-compatible setup #3283
Description
Activity
Good catch. The /v1 suffix handling (Claw appending /chat/completions) is a common gotcha that trips up new users — surfacing it explicitly in the docs saves debugging cycles. One suggestion: also note that OmniRoute's model listing endpoint (/v1/models) uses OpenAI-compatible response shape, so jq '.data[].id' works out of the box. The proposal is complete and self-contained; +1 on adding this to docs/local-openai-compatible-providers.md.
Thanks for the documentation PR — the OmniRoute setup guide will be helpful for users getting started with OpenAI-compatible endpoints.
Good idea — a copy/paste-safe OmniRoute example fits the existing guide without needing any code changes, since the runtime already handles it: OPENAI_BASE_URL points at the endpoint, the client appends /chat/completions itself, and the local/ prefix is stripped before the model ID is sent. One suggestion: include a short troubleshooting note for the case where users mistakenly paste a full endpoint into OPENAI_BASE_URL (duplicated /chat/completions is a common footgun worth calling out in the example).
Makes sense as an addition to local-openai-compatible-providers.md. Two details that would make the example genuinely copy/paste-safe: (1) state explicitly whether OPENAI_BASE_URL should include the /v1 suffix, since the client appends /chat/completions and getting this wrong is the most common source of 404s; (2) note that the local/ prefix is stripped before the model ID is sent, so for OmniRoute what follows the prefix is exactly what the router sees and has to match a route name it knows. If OmniRoute exposes non-standard model IDs, a troubleshooting row alongside the mlx-lm ones (bare names 404) would save users the same round trip.
Proposal
Add a copy/paste-safe OmniRoute example to the existing
docs/local-openai-compatible-providers.mdguide.Claw already has the required generic runtime behavior:
OPENAI_BASE_URLconfigures the OpenAI-compatible endpoint;/chat/completionswithout duplicating a full endpoint;OPENAI_API_KEYis sent as a Bearer token;local/prefix selects the OpenAI-compatible transport and is removed before the model ID is sent;The proposed documentation would cover:
The
/v1suffix matters because Claw appends/chat/completions. The full proposal also explainsDocker/host reachability, model IDs containing slashes, and that live streaming/tool compatibility
depends on the selected model/provider behind OmniRoute.
Verification completed
cargo test --workspace: 1,415 passed, 0 failed, 1 ignored;cargo fmt --all --check;cargo clippy --workspace(passes with pre-existing warnings);git diff --check.Patch availability
A docs-only patch is prepared locally as one commit (
de857038b2f9ff9b319132e2241549e86215c351),changing only
docs/local-openai-compatible-providers.md(+37 lines).I attempted to create/update a GitHub fork for the normal pull-request flow, but GitHub locked the
fork immediately and rejected both Git push and REST ref creation. If maintainers agree with the
documentation direction, I can open the PR as soon as GitHub permits a writable fork, or provide the
exact patch in the preferred form.