fix(inference): contain shared gateway route conflicts (#6338)

<!-- markdownlint-disable MD041 -->
## Summary

Contain the current one-route-per-OpenShell-gateway behavior so
onboarding, runtime inference switches, and connect-time repair cannot
silently change the route used by another registered sandbox. This is a
compatibility guard for the current OpenShell contract; true
simultaneous per-sandbox routing remains upstream work.

## Related Issue

Addresses #6315

## Changes

- Compare the requested provider/model and custom endpoint/API family
with every durable registry row on the target gateway, including stopped
sandboxes.
- Allow identical routes and different gateways; fail closed for
same-gateway conflicts, missing durable provider/model identity,
incomplete legacy custom-route identity, and invalid gateway bindings.
- Run the guard before onboarding setup, resumed setup, runtime
`inference set`, connect-time route writes, endpoint probes, or repair
mutations.
- Serialize route-sensitive onboarding, runtime switches, connect
repair, snapshot restore, and registry recovery per gateway; different
gateways remain independent.
- Persist a full pending route reservation before verification/smoke
checks, and revalidate the target reservation under the gateway lock
before creating or reusing a sandbox.
- Resolve `inference set -g` from the target sandbox's recorded gateway
instead of hardcoding the default gateway.
- Keep missing-flag guidance inside NemoClaw so users do not bypass the
shared-route protection with raw OpenShell commands.
- Document the one-route-per-gateway contract and recovery options:
align routes, remove the conflicting sandbox, or use another
`NEMOCLAW_GATEWAY_PORT`.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [x] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Quality Gates

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] Docs updated for user-facing behavior changes
- [ ] Docs not applicable — justification:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [x] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification: exact head `7df7274c`
passed an independent nine-category security review with no findings;
the maintainer disposition, exact-head E2E evidence, and manual
validation procedure are recorded
[here](#6338 (comment)).
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Verification

- [x] PR description includes the DCO sign-off declaration and every
commit appears as `Verified` in GitHub — all 45 PR commits are
GitHub-verified and signed off at
`7df7274c138efe4080993378863a21b4567db842`.
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run check:diff` passed when hooks were skipped or unavailable —
normal pre-commit, commit-msg, and pre-push hooks passed for the
merge-resolution and documentation commits at exact head `7df7274c`.
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — 93 conflict-focused assertions and CLI
typecheck passed locally after the merge; an independent exact-head
security pass reran 108 focused assertions across route locking, DNS
finalization, late peers, incomplete recovered rows, aliases, SSRF
no-bypass behavior, connect/onboard containment, and local-provider
probes.
- [x] Applicable broad gate passed — refreshed exact-head CI [run
28893800691](https://github.com/NVIDIA/NemoClaw/actions/runs/28893800691)
passed all five CLI shards, aggregate tests/checks, build/typecheck,
installer, plugin, security, docs, macOS/WSL, self-hosted, and
growth-guard jobs; all five required contexts pass.
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only) — 0
errors; Fern reports two pre-existing hidden warnings.
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

Additional validation: CLI typecheck, formatting, source/test budgets,
the Fern docs build, and normal git hooks passed for the final merge and
docs changes at `7df7274c`. The top-level `src/lib/onboard.ts` is
net-neutral against the PR base (`+139/-139`). This branch includes
`main` through `376ebe2ed18f71555aca0d139337e7f6a9a76e90`. The DCode
default-model conflict in `setup-nim-flow.ts` was resolved additively:
DCode retains its Ultra default and logger, while same-gateway discovery
constraints, pre-probe checks, exact route checks, and API coercion
remain intact; the combined interaction is now regression-tested. The
later rebuild loader-seam merge was conflict-free. The race coverage
includes same-gateway serialization, independent gateways,
DNS-normalized endpoint changes between preliminary and finalized
checks, gateway-binding changes while queued, pending-reservation loss,
snapshot pre-delete rejection, recovered rows with incomplete durable
route identity, and zero-mutation conflict exits. The earlier isolated
OpenShell 0.0.72 proof `2026-07-06T23-01-11-471Z-pid-7719` remains
applicable to the unchanged live containment path: identical
same-gateway onboarding succeeded; a conflicting same-gateway onboard
named both peers, made zero conflicting endpoint probes, and left the
first route, providers, sandboxes, forwards, configs, containers,
images, volumes, registry, credentials, gateway PID, and data plane
unchanged; the same conflicting route succeeded on a separate gateway
without changing gateway A; all cleanup checks passed. Final exact-head
E2E passed every refreshed advisor requirement: [run
28893935439](https://github.com/NVIDIA/NemoClaw/actions/runs/28893935439)
covered resume/repair, cloud onboarding, inference routing, both
OpenClaw variants, both Hermes variants, double-onboard, and concurrent
gateway ports; [run
28893939992](https://github.com/NVIDIA/NemoClaw/actions/runs/28893939992)
passed the canonical OpenClaw cloud target; and [run
28894237287](https://github.com/NVIDIA/NemoClaw/actions/runs/28894237287)
passed sandbox operations and snapshot commands. Exact-head GPT-5.5
attempt 2 reports zero required findings and one runtime-test warning.
The explicit maintainer acceptance of that residual checked-in-target
gap, its rationale, exact-head live evidence, and reproducible manual
validation procedure are recorded
[here](#6338 (comment)).
Nemotron's only required item applies an unenforced 20-line growth
heuristic even though the repository's 1,500-line test budget passes. An
independent exact-head audit found no remaining product or security
defect.

<details>
<summary>Advisor scope rationale</summary>

- The two-phase custom-route check is intentional: the synchronous
preliminary guard rejects known registry conflicts before endpoint work,
then asynchronous DNS validation feeds a fresh-registry final guard
before any OpenShell, config, or registry mutation. The removal
condition is concrete: collapse the phases only when preparation can
consume fully DNS-validated metadata without an earlier endpoint probe
or mutation.
- Registry recovery never invents missing route identity, probes an
endpoint, or changes the live gateway route. Complete recovered
identities are compatibility-checked; a durable recovered row with
missing provider/model is preserved for inventory but makes every later
same-gateway route mutation fail closed until the row is removed and
re-onboarded. DNS pinning remains at the later endpoint-use/mutation
boundary.
- Snapshot restore compares the recorded route through the shared
compatibility guard under the gateway mutation lock. It does not
introduce or probe a new custom endpoint, so adding a second DNS-pinning
path there would duplicate the endpoint-use boundary without closing a
mutation gap.
- Both the ambient `OPENSHELL_GATEWAY_ENDPOINT` environment path and the
explicit endpoint flag are rejected or validated at their entry
boundaries; neither bypasses the compatibility guard.
- Further splits of `connect.ts`, provider onboarding, and the focused
containment test files would be structural refactors without changing
this issue's behavior. All affected files remain within the repository's
enforced source/test budgets, so those splits are deferred to avoid
widening the containment PR and its regression surface.
- The OpenShell 0.0.72 proof above covers the same-gateway conflict
contract and separate-gateway success path; the refreshed exact-head E2E
run covers onboarding, repair, switching, sandbox operations,
multi-gateway behavior, and stale rebuild.
- Overlapping PR merge order requires maintainer coordination: this
branch contains `main` through `376ebe2e`; overlapping route-changing
work should rebase after this containment change lands. No change inside
this PR can safely rewrite those independent branches.
- Validation failures are intentionally converted to credential-safe
`InferenceSetError` messages. Preserving raw URL/DNS error causes would
risk exposing untrusted endpoint detail and is not required for the
fail-closed behavior.

</details>

---
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>

---------

Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Signed-off-by: Carlos Villela <cvillela@nvidia.com>
Co-authored-by: Carlos Villela <cvillela@nvidia.com>

Author: ericksoa

bin/lib/nim-images.json

@@ -7,6 +7,7 @@
     },
     {
       "name": "nvidia/nemotron-3-nano-30b-a3b",
+      "servedModel": "nvidia/nemotron-3-nano",
       "image": "nvcr.io/nim/nvidia/nemotron-3-nano:latest",
       "minGpuMemoryMB": 8192
     },

ci/test-file-size-budget.json

@@ -10,7 +10,7 @@
     "test/nemoclaw-start.test.ts": 4827,
     "test/onboard-messaging.test.ts": 2062,
     "test/onboard-selection.test.ts": 4834,
-    "test/onboard.test.ts": 4057,
+    "test/onboard.test.ts": 4043,
     "test/policies.test.ts": 2279
   }
 }

docs/about/release-notes.mdx

@@ -48,6 +48,23 @@ NemoClaw v0.0.74 upgrades the OpenShell policy boundary, adds managed MCP and pr
   The selected mode persists through resume and transactional rebuilds, and model-specific compatibility safeguards can keep an incompatible model on direct disclosure.
   Sandbox-first `inference get` and `inference set` commands now provide the same route controls as their global forms.
   For more information, refer to [Tool Calling Reliability](../inference/tool-calling-reliability), [Model Capability Audit](../inference/model-capability-audit), and [NemoClaw CLI Commands Reference](../reference/commands).
+- Shared OpenShell gateways now enforce a single compatible inference route across every registered sandbox, including stopped sandboxes.
+  Onboarding, connect-time repair, and `inference set` reject provider/model conflicts; custom routes must also match the normalized endpoint and API family.
+  As a migration requirement, custom switches must provide `--endpoint-url` and an unambiguous API family, and incomplete legacy custom-route metadata fails closed until the sandbox is removed and re-onboarded with complete metadata.
+  After backing up an affected workspace, an OpenAI-compatible route can be re-onboarded with complete metadata as follows (replace the example endpoint, model, and sandbox name):
+
+  ```bash
+  $$nemoclaw legacy-sandbox destroy
+  NEMOCLAW_PROVIDER=custom \
+    NEMOCLAW_ENDPOINT_URL=https://endpoint.example/v1 \
+    NEMOCLAW_MODEL=your-model-id \
+    NEMOCLAW_PREFERRED_API=openai-completions \
+    $$nemoclaw onboard --name legacy-sandbox
+  ```
+
+  Hermes deterministically selects `openai-completions` for `compatible-anthropic-endpoint`, so that one route may omit `--inference-api`; explicit incompatible values are rejected.
+  Use a different `NEMOCLAW_GATEWAY_PORT` when sandboxes need independent routes.
+  For more information, refer to [Switch Inference Providers](../inference/switch-inference-providers), [NemoClaw CLI Commands Reference](../reference/commands), and [Troubleshooting](../reference/troubleshooting).
 - LangChain Deep Agents Code now provides managed `status`, `whoami`, and `identity` commands without launching the interactive UI, validates the installed agent version during onboarding, and keeps credential-shaped or tracing configuration out of persisted runtime metadata.
   Its rebuild path validates recreation before destructive handoff and preserves the managed proxy, tool-disclosure, and MCP boundaries.
   For more information, refer to [Quickstart with LangChain Deep Agents Code](../../openclaw/get-started/quickstart-langchain-deepagents-code), [NemoClaw CLI Commands Reference](../reference/commands), and [Security Best Practices](../security/best-practices).

docs/inference/switch-inference-providers.mdx

@@ -27,6 +27,17 @@ If you run `$$nemoclaw inference set` before NemoClaw has a selected sandbox, th
 Run `$$nemoclaw onboard` first, then retry the switch.
 </Note>
 
+<Warning>
+OpenShell currently exposes one inference route per gateway, not one route per sandbox.
+All registered sandboxes on the same gateway must use the same provider and model.
+Custom compatible routes must also use the same endpoint and API family.
+An OpenClaw native-Anthropic route and a Hermes OpenAI-frontend route therefore cannot share a gateway, even when their custom endpoint and model are otherwise identical.
+NemoClaw checks stopped sandboxes because they depend on that route when restarted.
+If a registered same-gateway sandbox lacks durable provider or model metadata, or a custom route lacks durable endpoint or API-family metadata, NemoClaw fails closed until you remove and re-onboard that sandbox with complete route metadata.
+When a route conflicts, onboarding, runtime switching, and connect-time repair exit non-zero before changing the gateway and name the affected sandboxes.
+Align the routes, remove the conflicting sandbox, or onboard it with another `NEMOCLAW_GATEWAY_PORT`.
+</Warning>
+
 ## Find the Provider Name
 
 The `--provider` value must match a provider already configured on the sandbox.
@@ -104,7 +115,11 @@ $$nemoclaw inference set --provider compatible-endpoint --model <model-name>
 $$nemoclaw inference set --provider compatible-anthropic-endpoint --model <model-name>
 ```
 
-To change only the model on a sandbox that is already on this provider, omit `--endpoint-url` — `inference set` reuses the endpoint that onboarding established and does not repoint the gateway route. Any `--endpoint-url` you do pass is always validated by the host-side SSRF guard, so a URL that resolves to a private or internal address is rejected even if it is the same one onboarding recorded; omit the flag to keep the established endpoint. To point the sandbox at a genuinely different endpoint, re-run `$$nemoclaw onboard` with the new endpoint (rebuild reuses the recorded endpoint and cannot change it).
+To change only the model on a sandbox that is already on this provider, omit `--endpoint-url` when its durable registry entry contains both endpoint and API-family metadata.
+`inference set` reuses that recorded route and does not repoint the gateway.
+If the durable metadata is incomplete, NemoClaw fails closed and tells you to re-run onboarding.
+Any `--endpoint-url` you pass is always validated by the host-side SSRF guard, so a URL that resolves to a private or internal address is rejected even if it matches the recorded endpoint.
+To point the sandbox at a different endpoint, re-run `$$nemoclaw onboard` with the new endpoint because rebuild reuses the recorded endpoint and cannot change it.
 
 <AgentOnly variant="hermes">
 
@@ -145,6 +160,7 @@ $$nemoclaw <sandbox-name> rebuild
 
 Resuming onboarding also detects and repairs a stale route.
 `inference set` can select this provider after it has been registered on the verified OpenAI surface, but it fails before mutation for a legacy Anthropic registration because that command cannot change a gateway provider's protocol type.
+When supplying new custom metadata, Hermes may omit `--inference-api` for this provider because NemoClaw deterministically selects `openai-completions`; an explicit non-OpenAI value is rejected.
 </AgentOnly>
 
 #### Switching from Responses API to Chat Completions
@@ -203,6 +219,7 @@ The error includes a redacted OpenShell detail, lists the registered providers w
 Run `$$nemoclaw onboard` to register the provider, then retry `$$nemoclaw inference set`.
 
 Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
+`--no-verify` does not bypass the one-route-per-gateway compatibility check.
 
 ## Tune Model Metadata
 

docs/reference/commands-nemohermes.mdx

@@ -541,8 +541,10 @@ If another terminal is already connected to the sandbox, `connect` prints a note
 An unknown model slug, malformed extra-args JSON, or a gated model (for example `deepseek-r1-distill-70b`) with no `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exits non-zero with the same error the installer would emit, before any sandbox readiness probe or SSH attach.
 Unset the managed-vLLM variable, or fix the value, before retrying.
 
-When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` prints an explicit warning and realigns the shared gateway to the recorded route.
-Use `nemohermes inference set --provider <provider> --model <model>` to make an intentional route change.
+When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` checks every registered sandbox on that gateway before attempting a repair.
+It realigns the route only when those registry entries are compatible with the requested provider and model.
+If another sandbox records a conflicting route, `connect` exits non-zero without changing the gateway and names the affected sandboxes.
+Use `nemohermes inference set --provider <provider> --model <model>` to make an intentional compatible route change.
 If the sandbox is registered locally but missing from a healthy gateway, `connect` preserves the registry entry and points you to `rebuild --yes`, `onboard`, or `destroy` instead of deleting the metadata needed for recovery.
 
 After a host reboot, the OpenShell gateway rotates its SSH host keys.
@@ -1921,6 +1923,12 @@ By default, the command syncs the default registered sandbox.
 The command refuses before changing the OpenShell route when the selected sandbox has shields up.
 Run `nemohermes <name> shields down`, apply the inference change, then run `nemohermes <name> shields up` again.
 
+Each OpenShell gateway exposes one inference route to every sandbox registered on that gateway.
+Before changing the route, NemoClaw compares the requested provider and model with every same-gateway registry entry, including stopped sandboxes.
+Custom compatible routes must also have matching normalized endpoint URLs and API families.
+If a route conflicts or a legacy custom route lacks enough endpoint or API-family metadata to prove compatibility, the command exits non-zero before changing the OpenShell route, agent config, or host registry and names the conflicting sandboxes.
+Align those sandboxes to the same route, remove the conflicting sandbox, or onboard it with another `NEMOCLAW_GATEWAY_PORT`.
+
 ```bash
 nemohermes inference set --provider <provider> --model <model> [--sandbox <name>] [--no-verify] [--endpoint-url <url>] [--credential-env <ENV>] [--inference-api <api>]
 ```
@@ -1933,19 +1941,21 @@ nemohermes my-assistant inference set --provider nvidia-prod --model nvidia/nemo
 ```
 
 Pass both `--provider` and `--model` when you want NemoClaw to update the OpenShell inference route and sync the selected sandbox's agent config.
-If you only want the lower-level OpenShell route operation, run `openshell inference set -g nemoclaw --model <model> --provider <provider>` directly.
-When either flag is missing, `nemohermes inference set` prints that OpenShell command instead of an oclif flag-validation error.
+NemoClaw resolves the OpenShell gateway from the target sandbox's recorded gateway binding, including non-default `NEMOCLAW_GATEWAY_PORT` deployments.
+Do not run `openshell inference set` directly on a shared NemoClaw gateway because that bypasses registry compatibility checks and can break other sandboxes.
+When either flag is missing, `nemohermes inference set` reports both required flags without suggesting a raw OpenShell command.
 The command updates the host registry immediately after the gateway route changes.
 If the in-sandbox config sync fails, NemoClaw keeps the gateway and registry aligned, warns that the running image may still need a rebuild, and points you to `nemohermes <name> rebuild`.
 
 Supported provider names are `nvidia-prod`, `nvidia-nim`, `nvidia-router`, `openai-api`, `anthropic-prod`, `compatible-anthropic-endpoint`, `gemini-api`, `compatible-endpoint`, `hermes-provider`, `ollama-local`, and `vllm-local`.
 Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
-When switching to `compatible-endpoint` or `compatible-anthropic-endpoint` from a different provider family, pass `--endpoint-url` with the trusted custom provider URL so NemoClaw can persist durable rebuild metadata.
+When switching to `compatible-endpoint` or `compatible-anthropic-endpoint` from a different provider family, pass `--endpoint-url` with the trusted custom provider URL and, except for the Hermes case below, `--inference-api` with its API family so NemoClaw can persist a complete route identity for rebuild and shared-gateway checks.
+For a Hermes `compatible-anthropic-endpoint` target, `--inference-api` may be omitted because NemoClaw deterministically selects `openai-completions`; an explicit different API family is rejected.
 NemoClaw rejects loopback, link-local, private, and internal endpoint addresses, including public hostnames that resolve to a private address.
 For public HTTP URLs, NemoClaw stores the validated IP address to prevent DNS rebinding.
 DNS-backed HTTPS URLs are rejected because NemoClaw cannot pin the downstream peer address while preserving TLS SNI and host validation across the OpenShell runtime boundary; HTTPS IP-literal URLs remain supported.
 NemoClaw accepts `http://host.openshell.internal:<port>` only with an explicit port from `1024` through `65535`; this narrow exception supports NemoClaw's sandbox-to-host inference routes and is not a general private-endpoint bypass.
-`--credential-env` and `--inference-api` may also be supplied for the compatible provider metadata; supported API values are `openai-completions`, `anthropic-messages`, and `openai-responses`.
+`--credential-env` may also be supplied for compatible provider metadata; supported `--inference-api` values are `openai-completions`, `anthropic-messages`, and `openai-responses`.
 
 ### `nemohermes setup`
 

docs/reference/commands.mdx

@@ -645,8 +645,10 @@ If another terminal is already connected to the sandbox, `connect` prints a note
 An unknown model slug, malformed extra-args JSON, or a gated model (for example `deepseek-r1-distill-70b`) with no `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exits non-zero with the same error the installer would emit, before any sandbox readiness probe or SSH attach.
 Unset the managed-vLLM variable, or fix the value, before retrying.
 
-When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` prints an explicit warning and realigns the shared gateway to the recorded route.
-Use `$$nemoclaw inference set --provider <provider> --model <model>` to make an intentional route change.
+When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` checks every registered sandbox on that gateway before attempting a repair.
+It realigns the route only when those registry entries are compatible with the requested provider and model.
+If another sandbox records a conflicting route, `connect` exits non-zero without changing the gateway and names the affected sandboxes.
+Use `$$nemoclaw inference set --provider <provider> --model <model>` to make an intentional compatible route change.
 If the sandbox is registered locally but missing from a healthy gateway, `connect` preserves the registry entry and points you to `rebuild --yes`, `onboard`, or `destroy` instead of deleting the metadata needed for recovery.
 
 After a host reboot, the OpenShell gateway rotates its SSH host keys.
@@ -2380,6 +2382,12 @@ By default, the command syncs the default registered sandbox.
 The command refuses before changing the OpenShell route when the selected sandbox has shields up.
 Run `$$nemoclaw <name> shields down`, apply the inference change, then run `$$nemoclaw <name> shields up` again.
 
+Each OpenShell gateway exposes one inference route to every sandbox registered on that gateway.
+Before changing the route, NemoClaw compares the requested provider and model with every same-gateway registry entry, including stopped sandboxes.
+Custom compatible routes must also have matching normalized endpoint URLs and API families.
+If a route conflicts or a legacy custom route lacks enough endpoint or API-family metadata to prove compatibility, the command exits non-zero before changing the OpenShell route, agent config, or host registry and names the conflicting sandboxes.
+Align those sandboxes to the same route, remove the conflicting sandbox, or onboard it with another `NEMOCLAW_GATEWAY_PORT`.
+
 ```bash
 $$nemoclaw inference set --provider <provider> --model <model> [--sandbox <name>] [--no-verify] [--endpoint-url <url>] [--credential-env <ENV>] [--inference-api <api>]
 ```
@@ -2392,19 +2400,21 @@ $$nemoclaw my-assistant inference set --provider nvidia-prod --model nvidia/nemo
 ```
 
 Pass both `--provider` and `--model` when you want NemoClaw to update the OpenShell inference route and sync the selected sandbox's agent config.
-If you only want the lower-level OpenShell route operation, run `openshell inference set -g nemoclaw --model <model> --provider <provider>` directly.
-When either flag is missing, `$$nemoclaw inference set` prints that OpenShell command instead of an oclif flag-validation error.
+NemoClaw resolves the OpenShell gateway from the target sandbox's recorded gateway binding, including non-default `NEMOCLAW_GATEWAY_PORT` deployments.
+Do not run `openshell inference set` directly on a shared NemoClaw gateway because that bypasses registry compatibility checks and can break other sandboxes.
+When either flag is missing, `$$nemoclaw inference set` reports both required flags without suggesting a raw OpenShell command.
 The command updates the host registry immediately after the gateway route changes.
 If the in-sandbox config sync fails, NemoClaw keeps the gateway and registry aligned, warns that the running image may still need a rebuild, and points you to `$$nemoclaw <name> rebuild`.
 
 Supported provider names are `nvidia-prod`, `nvidia-nim`, `nvidia-router`, `openai-api`, `anthropic-prod`, `compatible-anthropic-endpoint`, `gemini-api`, `compatible-endpoint`, `hermes-provider`, `ollama-local`, and `vllm-local`.
 Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
-When switching to `compatible-endpoint` or `compatible-anthropic-endpoint` from a different provider family, pass `--endpoint-url` with the trusted custom provider URL so NemoClaw can persist durable rebuild metadata.
+When switching to `compatible-endpoint` or `compatible-anthropic-endpoint` from a different provider family, pass `--endpoint-url` with the trusted custom provider URL and, except for the Hermes case below, `--inference-api` with its API family so NemoClaw can persist a complete route identity for rebuild and shared-gateway checks.
+For a Hermes `compatible-anthropic-endpoint` target, `--inference-api` may be omitted because NemoClaw deterministically selects `openai-completions`; an explicit different API family is rejected.
 NemoClaw rejects loopback, link-local, private, and internal endpoint addresses, including public hostnames that resolve to a private address.
 For public HTTP URLs, NemoClaw stores the validated IP address to prevent DNS rebinding.
 DNS-backed HTTPS URLs are rejected because NemoClaw cannot pin the downstream peer address while preserving TLS SNI and host validation across the OpenShell runtime boundary; HTTPS IP-literal URLs remain supported.
 NemoClaw accepts `http://host.openshell.internal:<port>` only with an explicit port from `1024` through `65535`; this narrow exception supports NemoClaw's sandbox-to-host inference routes and is not a general private-endpoint bypass.
-`--credential-env` and `--inference-api` may also be supplied for the compatible provider metadata; supported API values are `openai-completions`, `anthropic-messages`, and `openai-responses`.
+`--credential-env` may also be supplied for compatible provider metadata; supported `--inference-api` values are `openai-completions`, `anthropic-messages`, and `openai-responses`.
 
 ### `$$nemoclaw setup`