omp-provider-rerouting-diagnosis
Use when rerouting omp models via a proxy or ANTHROPIC_BASE_URL, proving which definition or URL serves a request, when a models.yml or registerProvider override is ignored, or on 'Connection error.'
SKILL.mdskills/managed/omp-provider-rerouting-diagnosis/SKILL.md
GitHubomp provider rerouting — what works, what doesn't, and how to prove it
Verified against omp v18.1.16 (2026-09-10, D:/NightSmith workstation user); the
ANTHROPIC_BASE_URL, models.yml and debug-log facts against v18.2.9 (2026-09-23); the
source function names and the catalogue location against v18.2.11 (2026-09-24).
Hard constraints (all URL/registry-level proven)
ANTHROPIC_BASE_URLreroutes every built-inanthropic/*model.resolveDirectAnthropicBaseUrl(pi-aiproviders/anthropic-state.ts) returns it whenever the model's own baseUrl is the official endpoint; only Foundry mode or a non-official per-model baseUrl beats it. A value pointing at a dead proxy port fails every Anthropic turn withConnection error.Shells opened before the variable changed keep the old value (a new Windows Terminal tab picks up the new one).pi.registerProvider(name, config)withmodels:replaces the provider's built-in catalog (registry-level) and requiresapiKeyoroauthwhen models are defined.apiKeytakes an environment-variable NAME, resolved exactly like models.yml'sapiKey(resolveConfigValue; seeomp-openai-compatible-provider). UseapiKey: "SOME_ENV_VAR"— never the secret.- With custom models you MUST set
authHeader: trueor noAuthorization: Bearerheader is built (createConfigHeaderResolver: Bearer added only when authHeader truthy + apiKeyConfig present). - Per-model
baseUrlin a registered model def is honored (buildCustomModelOverlay:baseUrl: modelDef.baseUrl ?? providerBaseUrl) — but only for ids the built-in catalog doesn't already have. Same-id overrides lose to the built-in def on the inference path (models.yml same-id models and runtime registerProvider overlays alike). - Copy
compatverbatim from the built-in catalogue:~/.bun/install/global/node_modules/@oh-my-pi/pi-catalog/src/models.json, plain JSON keyed provider → model id whose rows are complete, rules-materialized Models thatpi-catalog/src/models.tsconsumes verbatim (no need to parse the minified bundle). The request layer reads non-schema compat keys directly off the model def (zaiReasoningEffortDialect,clampOutputToModelMax,officialEndpoint,supportsSamplingParams,nativeKimiK3Reasoning, …). Filtering to the models.ymlOpenAICompatFieldsschema silently changes request behavior.registerProviderdoes no compat-key validation (manual checks invalidateProviderConfigurationonly). - Strip only true junk fields:
provider,int,tps,identity,requiresGlyphTokenization,supportsComputerUse. - models.yml:
modelOverridesacceptsheadersbut nobaseUrl(ModelOverrideSchema), so an override can never reroute a model. For the rest of the models.yml shape and its validation trap (one bad field disables every custom provider), seeomp-openai-compatible-provider. --configoverlays are settings-style and silently do nothing for provider blocks. models.yml/config.yml edits need a NEW omp process; a running session keeps its startup snapshot.--no-extensionsdisables extension-discovered extensions (explicit-estill loads). Verify which flag a run needs before believing any test result.
The dead-port discriminator (proves which def serves a request)
omp -p output and --mode json events never reveal the request URL, and proxy dashboards may not count passthrough routes (headroom's /stats never counted its /v4 catch-all), so stats deltas prove nothing. One exception: for Anthropic requests to a plain-http URL, the debug log ~/.omp/logs/omp.<date>.<pid>.log records cowork transport bypassed with the url (reason not-https). The reliable test:
- Register the provider/model with
baseUrl: "http://127.0.0.1:9"(dead port). - Run the real request WITHOUT
--no-extensions. - Reply succeeds → built-in def won (same-id bypass proven). Connection error → extension def served (your rerouting is live).
- Differential variant: register an extension-ONLY id (not in built-in catalog); if it resolves and reaches the dead port, extensions definitely load on the inference path (
-pprint mode DOES load user extensions from~/.omp/agent/extensions/). - On HTTP 400 responses omp dumps the full request (URL, headers, body) to
~/.omp/logs/http-400-requests/<ts>-*.json— URL-level evidence that also works for https targets. Point baseUrl at the real proxy but send a bogus model id to force a 400 and read the URL.
Case study (historical): routing built-in zai/glm-5.3-flash through headroom (2026-09-10)
Headroom was removed from this machine on 2026-09-23 and nothing starts it. This is kept for the rerouting lessons, not as a setup to restore.
- Goal: keep the id
zai/glm-5.3-flashbut change its URL → impossible on v18.1.16 (same-id precedence). Working alternative: a customzai-headroomprovider in models.yml + modelRoles. - Keep only real model fields; keep compat verbatim (above).
- headroom
/stats(requests.by_model,request_logs,recent_requests,persistent_savings) counts only pipeline-processed traffic (gemini/anthropic pipelines), never/v4passthrough — never use it to prove /v4 routing.