docs: refactor shared gateway and CA guidance

docs/changelog/2026-07-10.mdx

@@ -17,7 +17,7 @@ NemoClaw v0.0.80 upgrades Hermes to the v0.18 line with richer Slack rendering,
 - NemoClaw can import a host corporate proxy root CA into the sandbox trust bundle so external channel endpoints such as `api.telegram.org` verify TLS behind a corporate MITM proxy.
   Set `NEMOCLAW_CORPORATE_CA_BUNDLE` before onboarding, or rely on detection of the conventional CA variables and host administrator anchor directories.
   NemoClaw appends the validated CA and never replaces the OpenShell root, and you can opt out with `NEMOCLAW_CORPORATE_CA_IMPORT=0`.
-  For more information, refer to [Troubleshooting](/user-guide/openclaw/reference/troubleshooting).
+  For more information, refer to [Configure Corporate CA Trust](/user-guide/openclaw/security/configure-corporate-ca-trust).
 - Sandbox base-image resolution now prefers release-matched image tags before mutable `:latest` for release installs and stale source checkouts, validates explicit base-image overrides exactly, and fails closed when a requested image cannot be pulled or fails compatibility checks.
   Failed cluster-image builds now surface captured, redacted Docker diagnostics instead of an opaque exit code, and the LangChain Deep Agents Code image build preserves the native OpenRouter Nemotron profile registration.
   For more information, refer to [NemoClaw CLI Commands Reference](/user-guide/openclaw/reference/commands) and [Troubleshooting](/user-guide/openclaw/reference/troubleshooting).

docs/changelog/2026-07-14.mdx

@@ -10,7 +10,7 @@ NemoClaw v0.0.83 makes shared inference route changes explicit and safe, restore
 - Shared inference route changes are now explicit and fail-safe.
   When multiple sandboxes share a gateway, onboarding warns immediately before re-pointing the live route and fails closed before replacing a provider-global identity used by another sandbox.
   Status output shows each sandbox's recorded route, the live route, and whether `connect` can safely restore a drifted route.
-  For more information, refer to [View Active Inference Route](/user-guide/openclaw/inference/manage-inference/view-active-inference-route), [Switch Models](/user-guide/openclaw/inference/manage-inference/switch-models), and [Troubleshooting](/user-guide/openclaw/reference/troubleshooting).
+  For more information, refer to [Use Shared Gateway Routes](/user-guide/openclaw/inference/manage-inference/use-shared-gateway-routes) and [View Active Inference Route](/user-guide/openclaw/inference/manage-inference/view-active-inference-route).
 - DGX Station GB300 systems enter the express-install path, and managed vLLM storage preflight blocks only for a verified shortage rather than inconclusive capacity.
   For more information, refer to [Set Up vLLM](/user-guide/openclaw/inference/local-inference/set-up-vllm) and [NemoClaw CLI Commands Reference](/user-guide/openclaw/reference/commands).
 - Onboarding warns when a bring-your-own vLLM server on DGX Spark appears to serve a large unquantized model that may exhaust GPU memory under agent tool-call load.
@@ -20,6 +20,7 @@ NemoClaw v0.0.83 makes shared inference route changes explicit and safe, restore
 - Unreachable custom endpoints during onboarding now route through the transport-recovery path with DNS/VPN guidance and a retry/back/exit prompt instead of silently looping back to provider selection.
 - Rebuild preflight uses the model-aware token field for GPT-5 and o-series models, preventing spurious HTTP 400 failures before rebuild processing begins.
 - Corporate CA trust anchors are available throughout the sandbox image build, so `npm audit signatures` succeeds behind TLS-intercepting corporate proxies without manual workarounds.
+  For more information, refer to [Configure Corporate CA Trust](/user-guide/openclaw/security/configure-corporate-ca-trust).
 - SSH `ControlMaster`-delegated forwards are recognized by the untracked-forward fallback, preventing a healthy sandbox from being deleted after a forward-detection timeout.
 - Hermes light terminal skin writes correctly on macOS via stdin streaming.
 

docs/index.yml

@@ -117,6 +117,9 @@ navigation:
               - section: "Manage Inference"
                 slug: manage-inference
                 contents:
+                  - page: "Use Shared Gateway Routes"
+                    path: _build/agent-variants/inference/use-shared-gateway-routes.openclaw.generated.mdx
+                    slug: use-shared-gateway-routes
                   - page: "View the Active Inference Route"
                     path: _build/agent-variants/inference/view-active-inference-route.openclaw.generated.mdx
                     slug: view-active-inference-route
@@ -297,6 +300,9 @@ navigation:
               - page: "Security Best Practices"
                 path: _build/agent-variants/security/best-practices.openclaw.generated.mdx
                 slug: best-practices
+              - page: "Configure Corporate CA Trust"
+                path: _build/agent-variants/security/configure-corporate-ca-trust.openclaw.generated.mdx
+                slug: configure-corporate-ca-trust
               - page: "Credential Storage"
                 path: _build/agent-variants/security/credential-storage.openclaw.generated.mdx
                 slug: credential-storage
@@ -470,6 +476,9 @@ navigation:
               - section: "Manage Inference"
                 slug: manage-inference
                 contents:
+                  - page: "Use Shared Gateway Routes"
+                    path: _build/agent-variants/inference/use-shared-gateway-routes.deepagents.generated.mdx
+                    slug: use-shared-gateway-routes
                   - page: "View the Active Inference Route"
                     path: _build/agent-variants/inference/view-active-inference-route.deepagents.generated.mdx
                     slug: view-active-inference-route
@@ -721,6 +730,9 @@ navigation:
               - section: "Manage Inference"
                 slug: manage-inference
                 contents:
+                  - page: "Use Shared Gateway Routes"
+                    path: _build/agent-variants/inference/use-shared-gateway-routes.hermes.generated.mdx
+                    slug: use-shared-gateway-routes
                   - page: "View the Active Inference Route"
                     path: _build/agent-variants/inference/view-active-inference-route.hermes.generated.mdx
                     slug: view-active-inference-route
@@ -873,6 +885,9 @@ navigation:
               - page: "Security Best Practices"
                 path: _build/agent-variants/security/best-practices.hermes.generated.mdx
                 slug: best-practices
+              - page: "Configure Corporate CA Trust"
+                path: _build/agent-variants/security/configure-corporate-ca-trust.hermes.generated.mdx
+                slug: configure-corporate-ca-trust
               - page: "Credential Storage"
                 path: _build/agent-variants/security/credential-storage.hermes.generated.mdx
                 slug: credential-storage

docs/inference/switch-models.mdx

@@ -63,16 +63,8 @@ To validate a new model before replacing the current sandbox, onboard it under a
 
 ## Account for Shared Gateways
 
-OpenShell exposes one inference route per gateway.
-NemoClaw records each sandbox's intended model, but only one recorded route is live at a time.
-Onboarding a sandbox with another valid model warns immediately before it re-points the shared route.
-The warning names each affected sandbox and its recorded provider and model.
-When another registered sandbox uses the same provider name, `connect` verifies the custom endpoint and API family when applicable, plus the credential environment-variable name.
-It then warns and re-points the route to that sandbox's recorded provider and model.
-A different custom endpoint, API family, or credential environment-variable name remains fail-closed because `connect` cannot restore that provider metadata with a provider/model-only route change.
-Remove or re-onboard the conflicting sandbox before applying a different provider-global identity.
-
-`$$nemoclaw <name> status` shows the recorded model and adds an explicit drift warning when another sandbox's route is live.
+One gateway has one live route even when NemoClaw records different intended routes for its sandboxes.
+Review [Use Shared Gateway Routes](use-shared-gateway-routes) before changing a model that another registered sandbox shares.
 Runtime `inference set` remains fail-closed when the requested change conflicts with another registered sandbox or when route metadata is incomplete.
 
 ## Verify the Change
@@ -88,5 +80,6 @@ Use a sandbox-route verification when you also need to prove that the agent can
 ## Related Topics
 
 - [View the Active Inference Route](view-active-inference-route) to inspect the current provider and model.
+- [Use Shared Gateway Routes](use-shared-gateway-routes) when multiple sandboxes use one gateway.
 - [Switch Providers](switch-providers) to move to another provider family.
 - [Verify the Sandbox Inference Route](../validate-inference/verify-inference-route) to test the agent path.

docs/inference/switch-providers.mdx

@@ -103,22 +103,13 @@ A rebuild reuses the recorded endpoint and cannot change it.
 
 ## Account for Shared Gateways
 
-OpenShell exposes one live inference route per gateway, while NemoClaw records each sandbox's intended provider and model.
-Onboarding a sandbox with a different provider or model warns immediately before it re-points the shared route.
-When another sandbox uses the same provider name, its custom endpoint, API family, and credential environment-variable name must match.
-Onboarding refuses before provider or route mutation when those provider-global fields differ.
-The warning names every affected registered sandbox and its recorded provider and model.
-Those sandboxes use the new live route until a later onboarding run or, when endpoint, API-family, and credential environment-variable identity already match, `$$nemoclaw <name> connect` warns and re-points its provider and model again.
-`connect` refuses a different custom endpoint, API family, or credential environment-variable name because its provider/model-only route change cannot safely reconstruct that metadata.
-
-`$$nemoclaw <name> status` continues to show that sandbox's recorded provider and model and prints an explicit warning when the live shared route differs.
-Incomplete custom-route metadata, provider-global identity conflicts, and invalid gateway bindings remain hard errors because NemoClaw cannot identify or restore those routes safely.
+One gateway has one live route even when NemoClaw records different intended routes for its sandboxes.
+Review [Use Shared Gateway Routes](use-shared-gateway-routes) before changing a provider that another registered sandbox shares.
 Runtime `inference set` also refuses a change that would leave another registered sandbox with a different recorded route.
 
-Do not run `openshell inference set` directly on a shared NemoClaw gateway because that bypasses registry compatibility checks.
-
 ## Related Topics
 
 - [View the Active Inference Route](view-active-inference-route) to inspect the route before and after a switch.
+- [Use Shared Gateway Routes](use-shared-gateway-routes) when multiple sandboxes use one gateway.
 - [Switch Models](switch-models) when the provider does not change.
 - [Set Up an OpenAI-Compatible Endpoint](../custom-endpoints/set-up-openai-compatible-endpoint) to register a custom route through onboarding.

docs/inference/use-shared-gateway-routes.mdx

@@ -0,0 +1,71 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Use Shared Gateway Routes"
+sidebar-title: "Use Shared Gateway Routes"
+description: "Understand how multiple NemoClaw sandboxes safely share one live OpenShell inference route."
+description-agent: "Explains shared gateway inference routes, recorded route drift, safe route changes, and provider-global compatibility. Use when multiple sandboxes use one OpenShell gateway."
+keywords: ["nemoclaw shared gateway", "shared inference route", "route drift"]
+content:
+  type: "how_to"
+---
+
+OpenShell exposes one live inference route per gateway.
+NemoClaw records each sandbox's intended provider and model so compatible sandboxes can take turns using that route.
+
+## Change the Live Route During Onboarding
+
+Onboarding a sandbox with another valid provider or model warns immediately before it re-points the shared route.
+The warning names every affected registered sandbox and its recorded provider and model.
+Those sandboxes use the new live route until another onboarding run or connection re-points it again.
+
+When multiple sandboxes use the same provider name, their provider-global identity must match.
+For a custom provider, NemoClaw compares the normalized endpoint and API family.
+It also compares the credential environment-variable name for every provider.
+Onboarding exits before provider or route mutation when those fields differ.
+
+Do not run `openshell inference set` directly on a shared NemoClaw gateway because that bypasses the registry compatibility checks.
+
+## Restore a Sandbox Route When You Connect
+
+Connect to a sandbox when you want its recorded provider and model to become live again.
+
+```bash
+$$nemoclaw <name> connect
+```
+
+Before changing the route, `connect` verifies the same provider-global identity used during onboarding.
+When the identity is compatible, `connect` warns and re-points the route to the sandbox's recorded provider and model.
+When the identity differs or required metadata is incomplete, `connect` stops because a provider-and-model-only route change cannot safely reconstruct that configuration.
+
+## Inspect Recorded and Live Routes
+
+Run sandbox status to compare the sandbox's recorded route with the gateway's live route.
+
+```bash
+$$nemoclaw <name> status
+$$nemoclaw <name> status --json
+```
+
+Text output shows the provider and model recorded for the sandbox and adds a warning when the live route differs.
+JSON output exposes the two sources as `recordedRoute` and `liveRoute` and adds `routeDrift` when they differ.
+The schema-version `1` `provider` and `model` fields remain live-first when the gateway route is readable and fall back to the recorded route otherwise.
+When `routeDrift.canConnect` is `false`, `connect` cannot safely restore the recorded route because provider-global identity differs or required route or gateway metadata is incomplete.
+
+## Handle a Hard Route Conflict
+
+NemoClaw fails closed when it cannot prove that a route change preserves the provider and sandbox contracts.
+
+- For a provider-global identity conflict, align the endpoint, API family, and credential environment-variable name, or remove a sandbox you no longer need.
+- For incomplete legacy custom-route metadata, back up and remove the affected sandbox, then re-onboard it with an explicit endpoint and API family.
+- For an invalid gateway binding, restore known-good `gatewayName` and `gatewayPort` metadata from a trusted backup, or back up and remove the sandbox before re-onboarding it.
+- For a runtime `inference set` conflict, align the registered sandbox routes or remove the conflicting sandbox before retrying.
+
+Refer to [Troubleshooting a Shared Inference Route Conflict](../../reference/troubleshooting#a-shared-inference-route-conflicts-with-another-sandbox) for the recovery commands.
+
+## Related Topics
+
+- [View the Active Inference Route](view-active-inference-route) to read the gateway's live provider and model.
+- [Switch Models](switch-models) to change a model through NemoClaw.
+- [Switch Providers](switch-providers) to move to another provider family.
+- [Verify the Sandbox Inference Route](../validate-inference/verify-inference-route) to test the agent traffic path.

docs/inference/view-active-inference-route.mdx

@@ -66,14 +66,13 @@ $$nemoclaw <name> status
 ```
 
 The status output shows the provider and model recorded for that sandbox.
-When the gateway's live shared route differs, status also prints an explicit warning with both the live and recorded routes.
-The JSON report exposes them separately as `recordedRoute` and `liveRoute` and repeats both under `routeDrift` when they differ.
-The existing schema-version `1` `provider` and `model` fields remain live-first when the gateway route is readable and fall back to the recorded route otherwise.
-When `routeDrift.canConnect` is `false`, incomplete route metadata, an invalid gateway binding, or a provider-global identity conflict prevents `connect` from restoring the recorded route safely.
+When the gateway's live shared route differs, status prints both routes and reports whether `connect` can safely restore the recorded route.
+Refer to [Use Shared Gateway Routes](use-shared-gateway-routes) for the text and JSON drift fields and their compatibility rules.
 Use the route verification workflow when you need to prove that an inference request succeeds through the sandbox path.
 
 ## Related Topics
 
 - [Verify the Sandbox Inference Route](../validate-inference/verify-inference-route) for an end-to-end route check.
+- [Use Shared Gateway Routes](use-shared-gateway-routes) when multiple sandboxes use one gateway.
 - [Switch Models](switch-models) to select another model.
 - [Switch Providers](switch-providers) to move to another provider family.