diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md
index f943d1af667..53257172d85 100644
--- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md
+++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md
@@ -6,6 +6,8 @@ license: "Apache-2.0"
# Use a Local Inference Server
+import { AgentOnly } from "../_components/AgentGuide";
+
## Gotchas
- Ollama is convenient for local chat, but some model/template combinations can return tool calls as plain text under realistic agent load.
@@ -15,10 +17,16 @@ license: "Apache-2.0"
- NemoClaw installed. Refer to the Quickstart (use the `nemoclaw-user-get-started` skill) if you have not installed yet.
+
+
+
+
+
- NemoClaw installed. Refer to Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) if you have not installed yet.
-- A local model server running, or a supported Ollama, vLLM, or NIM setup that the NemoClaw onboard wizard can use, start, or install.
-import { AgentOnly } from "../_components/AgentGuide";
+
+
+- A local model server running, or a supported Ollama, vLLM, or NIM setup that the NemoClaw onboard wizard can use, start, or install.
NemoClaw can route inference to a model server running on your machine instead of a cloud API.
This page covers Ollama, compatible-endpoint paths for other servers, and experimental managed options for vLLM and NVIDIA NIM.
diff --git a/skills/nemoclaw-user-configure-inference/SKILL.md b/skills/nemoclaw-user-configure-inference/SKILL.md
index 0a0d57e2aea..53257172d85 100644
--- a/skills/nemoclaw-user-configure-inference/SKILL.md
+++ b/skills/nemoclaw-user-configure-inference/SKILL.md
@@ -1,21 +1,31 @@
---
name: "nemoclaw-user-configure-inference"
-description: "Connects NemoClaw to a local inference server. Use when setting up Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible local model server with NemoClaw. Trigger keywords - nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, switch nemoclaw inference model, change inference runtime, nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, nemoclaw tool calling, ollama tool calls, vllm tool-call-parser, raw json in tui, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing."
+description: "Connects NemoClaw to a local inference server. Use when setting up Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible local model server with NemoClaw. Trigger keywords - nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, switch nemoclaw inference model, change inference runtime, nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing, nemoclaw tool calling, ollama tool calls, vllm tool-call-parser, raw json in tui."
license: "Apache-2.0"
---
-
-
-
# Use a Local Inference Server
+import { AgentOnly } from "../_components/AgentGuide";
+
## Gotchas
- Ollama is convenient for local chat, but some model/template combinations can return tool calls as plain text under realistic agent load.
## Prerequisites
-- NemoClaw installed.
+
+
+- NemoClaw installed. Refer to the Quickstart (use the `nemoclaw-user-get-started` skill) if you have not installed yet.
+
+
+
+
+
+- NemoClaw installed. Refer to Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) if you have not installed yet.
+
+
+
- A local model server running, or a supported Ollama, vLLM, or NIM setup that the NemoClaw onboard wizard can use, start, or install.
NemoClaw can route inference to a model server running on your machine instead of a cloud API.
@@ -28,13 +38,14 @@ OpenShell intercepts inference traffic and forwards it to the local endpoint you
## Ollama
Ollama is the default local inference option.
-The onboard wizard detects Ollama automatically when it is installed or running on the host.
+The onboard wizard detects Ollama automatically when you have installed it or started it on the host.
-If Ollama is installed but not running, NemoClaw starts it for you.
+If you installed Ollama but have not started it, NemoClaw starts it for you.
On macOS and Linux, the wizard can also offer to install Ollama when it is not present.
When the host Ollama is below the minimum version NemoClaw expects for its starter models (currently `0.7.0`), the wizard surfaces an explicit **Upgrade Ollama** entry in the provider menu instead of silently reusing the older daemon, and the express setup path resolves to that entry.
The wizard inspects both the CLI binary (`ollama --version`) and the locally running daemon (`/api/version` on `:11434`) so the upgrade entry still appears when only one side is stale, for example a fresh user-local binary paired with the original system daemon.
-The gate skips Windows-host Ollama reached from WSL via `host.docker.internal`; the separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side.
+The gate skips Windows-host Ollama reached from WSL through `host.docker.internal`.
+The separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side.
On macOS, the wizard runs the platform install or upgrade path with `brew upgrade ollama`.
On Linux, the wizard runs the official `https://ollama.com/install.sh` path.
Upgrades on Linux always take the sudo-driven system path because the sudo-free user-local fallback would leave the existing system daemon on `:11434` serving the stale binary.
@@ -45,7 +56,7 @@ On WSL, the wizard can use, start, restart, or install Ollama on the Windows hos
### Linux Install Modes
-On native Linux, the install path picks between a system install (under `/usr/local`, via the official `https://ollama.com/install.sh`) and a sudo-free user-local install (under `${HOME}/.local`).
+On native Linux, the install path picks between a system install (under `/usr/local`, using the official `https://ollama.com/install.sh`) and a sudo-free user-local install (under `${HOME}/.local`).
NemoClaw selects the mode automatically:
- Running as root or with passwordless sudo (`sudo -n true` returns 0) selects the system install.
@@ -56,21 +67,23 @@ NemoClaw selects the mode automatically:
Override the detection with `NEMOCLAW_OLLAMA_INSTALL_MODE=system` or `NEMOCLAW_OLLAMA_INSTALL_MODE=user`.
The user-local install replicates only the binary extraction step of the official installer.
-It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` once.
-It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so the daemon must be relaunched manually after a reboot.
+It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` one time.
+It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so you must relaunch the daemon manually after a reboot.
NemoClaw also prints a one-line `PATH` hint if `${HOME}/.local/bin` is not already on your `PATH`; you can add `export PATH="${HOME}/.local/bin:$PATH"` to your shell profile to invoke `ollama` directly.
Both modes rely on `zstd` for archive extraction. On Debian and Ubuntu, the system path uses `sudo apt-get` to install `zstd` automatically and explains the prompt before continuing.
-The user-local path cannot bootstrap system packages without elevation, so if `zstd` is missing it prints per-distro install hints and exits — install `zstd` manually, then rerun onboarding.
+The user-local path cannot bootstrap system packages without elevation.
+If `zstd` is missing, it prints per-distro install hints and exits.
+Install `zstd` manually, then rerun onboarding.
Run the onboard wizard.
-```console
-$ nemoclaw onboard
+```bash
+nemoclaw onboard
```
Select **Local Ollama** from the provider list.
-NemoClaw lists installed models or offers starter models if none are installed.
+NemoClaw lists installed models or offers starter models if you have not installed any.
On hosts where the larger starter models fit the currently available GPU memory, the starter list includes `qwen3.6:35b` and selects it by default.
When another GPU workload is using most of the memory at onboard time, NemoClaw downgrades the menu to the largest model that still fits.
It pulls the selected model, loads it into memory, and validates it before continuing.
@@ -78,6 +91,7 @@ When Ollama reports a loaded-model context length, NemoClaw uses that value for
If the selected model declares that it does not support tool calling, onboarding stops with guidance to choose a model whose `ollama show ` capabilities include `tools`.
The validation also requires structured chat-completions tool calls.
If the model leaks tool-call JSON as plain message text, onboarding stops so you can choose a model that returns tool calls in the expected response field.
+If a host-side validation probe times out, NemoClaw retries the Ollama tool-call validation with a larger timeout before failing the setup.
On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL.
### WSL with Windows-Host Ollama
@@ -85,8 +99,8 @@ On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.i
When NemoClaw runs inside WSL, the provider menu can include Windows-host Ollama actions:
- Use Ollama on Windows host when the Windows daemon is already reachable.
-- Restart Ollama on Windows host when the daemon is installed but only bound to Windows loopback.
-- Start Ollama on Windows host when Ollama is installed but not running.
+- Restart Ollama on Windows host when you installed the daemon but bound it only to Windows loopback.
+- Start Ollama on Windows host when you installed Ollama but have not started it.
- Install Ollama on Windows host when Windows does not have Ollama installed.
The install and restart paths set `OLLAMA_HOST=0.0.0.0:11434` on the Windows side so Docker and WSL can reach the daemon through `host.docker.internal`.
@@ -96,6 +110,11 @@ If the HTTP endpoint is not reachable yet, NemoClaw also checks for the Windows
If the daemon does not become reachable, onboarding prints PowerShell commands you can run to inspect the Windows-side process and port state. Use one Ollama instance on port `11434` at a time.
If both WSL and Windows-host Ollama are running, pick the intended menu entry during onboarding so NemoClaw validates and pulls models against the right daemon.
+Windows-host Ollama requires Docker Desktop WSL integration because the sandbox reaches the Windows daemon through Docker Desktop's WSL routing path.
+If NemoClaw detects native Docker Engine inside WSL, the provider menu labels Windows-host Ollama actions as requiring Docker Desktop integration.
+Selecting one of those actions in the unsupported native Docker topology exits early with a remediation message instead of trying to start or install Ollama on Windows.
+
+
**Warning:**
Ollama is convenient for local chat, but some model/template combinations can
@@ -103,13 +122,13 @@ return tool calls as plain text under realistic agent load. If the TUI shows raw
JSON such as `{"name":"memory_search","arguments":{...}}` instead of running a
tool, switch to vLLM with `--enable-auto-tool-choice` and the correct
`--tool-call-parser`. See [Tool-Calling Reliability](references/tool-calling-reliability.md).
+
### Authenticated Reverse Proxy
On non-WSL hosts, NemoClaw keeps Ollama bound to `127.0.0.1:11434` and starts a token-gated reverse proxy on `0.0.0.0:11435`.
The native install/start paths also reset NemoClaw-managed systemd launches to the loopback binding.
-Containers and other hosts on the local network reach Ollama only through the
-proxy, which validates a Bearer token before forwarding requests.
+Containers and other hosts on the local network reach Ollama only through the proxy, which validates a Bearer token before forwarding requests.
On that native path, NemoClaw never exposes Ollama without authentication.
WSL Ollama paths do not use this proxy.
@@ -129,22 +148,19 @@ For non-WSL Ollama setups, the onboard wizard manages the proxy automatically:
On native Linux hosts, a firewall can allow the host proxy health check while still blocking sandbox containers on the OpenShell Docker bridge.
When the sandbox-side proxy probe fails with a TCP error, onboarding exits before it saves the inference route and prints a command like:
-```console
-$ sudo ufw allow from to any port 11435 proto tcp
-$ nemoclaw onboard
+```bash
+sudo ufw allow from to any port 11435 proto tcp
+nemoclaw onboard
```
If the probe cannot run, for example because Docker Desktop or WSL uses a different host routing model, onboarding continues and relies on the regular proxy health check.
-The sandbox provider is configured to use proxy port `11435` with the generated
-token as its `OPENAI_API_KEY` credential.
-OpenShell's L7 proxy injects the token at egress, so the agent inside the
-sandbox never sees the token directly.
+NemoClaw configures the sandbox provider to use proxy port `11435` with the generated token as its `OPENAI_API_KEY` credential.
+OpenShell's L7 proxy injects the token at egress, so the agent inside the sandbox never sees the token directly.
All proxy endpoints require the Bearer token, including `GET /api/tags`.
-Internal health and reachability checks run via the proxy treat any HTTP
-response (including `401`) as proof the proxy is alive — they only fail
-when nothing answers at all.
+Internal health and reachability checks run through the proxy treat any HTTP response, including `401`, as proof the proxy is alive.
+They fail only when nothing answers at all.
If Ollama is already running on a non-loopback address when you start onboard,
the wizard restarts it on `127.0.0.1:11434` so the proxy is the only network
@@ -156,126 +172,90 @@ When you switch away from Ollama, stop host services, or destroy an Ollama-backe
The cleanup sends `keep_alive: 0` for each model reported by Ollama and runs on a best-effort basis, so shutdown continues if Ollama is already stopped.
This does not delete downloaded model files.
-Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup.
+### Non-Interactive Setup
-## OpenAI-Compatible Server
-
-This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others.
-For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default.
-This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions.
-To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard.
-
-Start your model server.
-The examples below use vLLM, but any OpenAI-compatible server works.
-
-```console
-$ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
+```bash
+NEMOCLAW_PROVIDER=ollama \
+ NEMOCLAW_MODEL=qwen3.5:9b \
+ nemoclaw onboard --non-interactive --yes
```
-Run the onboard wizard.
-
-```console
-$ nemoclaw onboard
-```
+If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory.
+If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit.
+Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself.
+In interactive onboarding, registry-known installed tags that do not fit current GPU memory are filtered out of the installed-model menu.
+If none of the installed registry-known tags fit, NemoClaw shows the starter-model choices and warns when even the smallest bootstrap tag may not fit.
+After a selected model fails validation, NemoClaw excludes that tag from the next installed-model menu so pressing Enter cannot select the same failing model repeatedly.
+When Ollama reports a loaded-model context length below `16384` and `NEMOCLAW_CONTEXT_WINDOW` is unset, NemoClaw raises the baked `contextWindow` to `16384` so the agent prompt and tool definitions fit better than the stock daemon default.
+If the initial Ollama validation probe times out during a cold load, NemoClaw retries once with a 300-second probe budget.
+This applies beyond DGX Spark, including tight-VRAM dGPU hosts where warm-up can spill from GPU to CPU.
+
+`--yes` (or `NEMOCLAW_YES=1`) authorizes the Ollama model download without an interactive confirmation prompt.
+Under `--non-interactive`, include `--yes` (or `NEMOCLAW_YES=1`) to authorize the download.
+Onboard exits otherwise because it cannot prompt.
+Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt that shows the model size before downloading.
+
+| Variable | Purpose |
+|---|---|
+| `NEMOCLAW_PROVIDER` | Set to `ollama`. |
+| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. |
+| `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. |
-When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**.
-Enter the base URL of your local server, for example `http://localhost:8000/v1`.
+## Compatible Local Servers
-The wizard prompts for an API key.
-If your server does not require authentication, enter any non-empty string (for example, `dummy`).
+Use **Other OpenAI-compatible endpoint** for vLLM, TensorRT-LLM, llama.cpp, LocalAI, NIM, SGLang, or another server that implements `/v1/chat/completions`.
+For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default because some local backends accept `/v1/responses` but drop system prompts or tool definitions.
+Set `NEMOCLAW_PREFERRED_API=openai-responses` only after you have verified that the backend streams the events OpenClaw requires.
-NemoClaw validates the endpoint by sending a test inference request before continuing.
-The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider.
-If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires.
-If a reasoning model returns only reasoning content before producing a final answer, NemoClaw retries the smoke request with a larger response budget.
-Route, configuration, and authentication failures still fail immediately.
+For the full compatible-endpoint prompt flow, non-interactive variables, API-path controls, managed vLLM profiles, NIM setup, and timeout settings, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers).
-Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup, Selecting the API Path.
+## Managed vLLM and NIM
-## Anthropic-Compatible Server
+NemoClaw can use an already-running vLLM server on `localhost:8000`, start managed vLLM on supported NVIDIA GPU hosts, or manage a local NIM container when `NEMOCLAW_EXPERIMENTAL=1` is set.
+Managed vLLM records the model returned by `/v1/models` and uses runtime metadata such as `max_model_len` when available.
+In interactive managed vLLM setup, the wizard lists validated model choices for your host profile before it pulls weights.
+Press **Enter** to accept the profile default, or choose a numbered model from the list.
+For scripted runs, set `NEMOCLAW_VLLM_MODEL=` to choose a registry model without prompting.
+If the host reboots and the `nemoclaw-vllm` container is stopped, NemoClaw restarts the managed vLLM container during recovery instead of requiring a fresh onboarding run.
+NIM uses the same chat-completions API path restriction as vLLM.
-Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps.
+On Linux Docker-driver GPU sandboxes, NemoClaw keeps local inference on the OpenShell bridge route and verifies `https://inference.local/v1/models` from inside the sandbox runtime after the sandbox reaches ready.
+It treats only a 2xx response as success because that path includes the proxy authentication rewrite the agent uses.
+If the runtime route fails, onboarding reports the endpoint and recovery steps before the first agent prompt.
-## vLLM
+For registry slugs, Hugging Face token requirements, NGC login behavior, and non-interactive examples, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers).
-When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model.
-On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you.
+## Verify the Configuration
-For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list.
+After onboarding completes, confirm the active provider and model.
-```console
-$ nemoclaw onboard
+```bash
+nemoclaw status
```
-If vLLM is already running, NemoClaw detects the running model and validates the endpoint.
-If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default.
-Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears.
-NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, and prints progress markers while the model loads.
-The first run can take 10 to 30 minutes.
-Later runs reuse the cached image and model weights.
-
-Managed vLLM uses these profiles:
+The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model.
+For Local Ollama, status also checks the authenticated proxy when a proxy token is available.
+If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use.
-| Host profile | Default model |
-|---|---|
-| DGX Spark | `Qwen/Qwen3.6-27B-FP8` |
-| DGX Station | `Qwen/Qwen3.6-27B-FP8` |
-| Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` |
-
-**Note:**
-
-NemoClaw forces the `chat/completions` API path for vLLM.
-The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text.
-
-Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup, Override the Managed-vLLM Model.
-
-## NVIDIA NIM (Experimental)
+## Switch Models at Runtime
-NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU.
+You can change the model without re-running onboard.
+Refer to [Switch Inference Models](references/switch-inference-providers.md) for the full procedure.
-Set the experimental flag and run onboard.
+For compatible endpoints, the command is:
-```console
-$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard
+```bash
+nemoclaw inference set --provider compatible-endpoint --model
```
-Select **Local NVIDIA NIM [experimental]** from the provider list.
-NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing.
-On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used.
-
-NIM container images are hosted on `nvcr.io` and require NGC registry authentication before `docker pull` succeeds.
-If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history.
-The prompt masks the key during input and retries once on a bad key before failing.
-In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`.
-If `NGC_API_KEY` or `NVIDIA_API_KEY` is already exported, NemoClaw passes it into the managed NIM container through the process environment instead of command-line arguments.
-If the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines.
-
-**Note:**
-
-NIM uses vLLM internally.
-The same `chat/completions` API path restriction applies.
-
-Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup.
-
-## Timeout Configuration
-
-Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps.
-
-## Verify the Configuration
-
-Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps.
-
-## Switch Models at Runtime
-
-Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps.
+If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`.
## References
- **Load [references/switch-inference-providers.md](references/switch-inference-providers.md)** when switching inference providers, changing the model runtime, or reconfiguring inference routing. Changes the active inference model without restarting the sandbox.
- **Load [references/set-up-sub-agent.md](references/set-up-sub-agent.md)** when users ask how to add a second model, configure a sub-agent model, use Omni for vision tasks, configure agents.list, or use sessions_spawn in NemoClaw. Shows the NemoClaw-specific file paths and update flow for adding an auxiliary OpenClaw sub-agent model.
-- **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when vLLM with a tool-call parser is recommended, and how to repoint NemoClaw to a parser-aware local endpoint.
- **Load [references/inference-options.md](references/inference-options.md)** when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Lists all inference providers offered during NemoClaw onboarding.
-- **Load [references/use-local-inference-details.md](references/use-local-inference-details.md)** when you need detailed steps for Non-Interactive Setup, Selecting the API Path, Anthropic-Compatible Server, and related details.
+- **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when to use vLLM with a tool-call parser, and how to repoint NemoClaw to a parser-aware local endpoint.
## Related Skills
diff --git a/skills/nemoclaw-user-configure-inference/evals/evals.json b/skills/nemoclaw-user-configure-inference/evals/evals.json
index a0bd47ac294..44f8cca76bd 100644
--- a/skills/nemoclaw-user-configure-inference/evals/evals.json
+++ b/skills/nemoclaw-user-configure-inference/evals/evals.json
@@ -3,90 +3,9 @@
"id": "docs-inference-inference-options-001",
"question": "I'm choosing an inference option during onboarding. Help me compare hosted providers, local servers, and compatible endpoints so I can select a model path that fits my privacy, cost, and reliability needs.",
"expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user compare hosted providers, local servers, and compatible endpoints and gives enough concrete guidance, decision criteria, verification steps, or risk framing to select a model path that fits my privacy, cost, and reliability needs."
- },
- {
- "id": "docs-inference-inference-options-002",
- "question": "I'm preparing provider credentials. Help me know which provider capabilities and secrets onboarding requires so I can complete setup without avoidable credential errors.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user know which provider capabilities and secrets onboarding requires and gives enough concrete guidance, decision criteria, verification steps, or risk framing to complete setup without avoidable credential errors."
- },
- {
- "id": "docs-inference-inference-options-003",
- "question": "I'm evaluating routed inference. Help me understand how the sandbox calls models through the gateway so I can trust that model credentials stay outside the sandbox.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user understand how the sandbox calls models through the gateway and gives enough concrete guidance, decision criteria, verification steps, or risk framing to trust that model credentials stay outside the sandbox."
- },
- {
- "id": "docs-inference-use-local-inference-001",
- "question": "I'm connecting a local inference server. Help me route NemoClaw model traffic to Ollama, vLLM, TensorRT-LLM, NIM, or another compatible endpoint so I can meet privacy, latency, or cost goals.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user route NemoClaw model traffic to Ollama, vLLM, TensorRT-LLM, NIM, or another compatible endpoint and gives enough concrete guidance, decision criteria, verification steps, or risk framing to meet privacy, latency, or cost goals."
- },
- {
- "id": "docs-inference-use-local-inference-002",
- "question": "I'm debugging local endpoint reachability. Help me separate NemoClaw routing issues from model-server issues so I can fix the right component first.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user separate NemoClaw routing issues from model-server issues and gives enough concrete guidance, decision criteria, verification steps, or risk framing to fix the right component first."
- },
- {
- "id": "docs-inference-use-local-inference-003",
- "question": "I'm configuring traffic through `inference.local`. Help me understand the required host, port, and model settings so I can make sandboxed inference calls resolve to my local server.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user understand the required host, port, and model settings and gives enough concrete guidance, decision criteria, verification steps, or risk framing to make sandboxed inference calls resolve to my local server."
- },
- {
- "id": "docs-inference-switch-inference-providers-001",
- "question": "I'm switching inference models during a running session. Help me change model behavior without restarting the sandbox so I can adapt to task, cost, or reliability needs quickly.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user change model behavior without restarting the sandbox and gives enough concrete guidance, decision criteria, verification steps, or risk framing to adapt to task, cost, or reliability needs quickly."
- },
- {
- "id": "docs-inference-switch-inference-providers-002",
- "question": "I'm confirming a runtime model change. Help me verify the agent is using the new active model so I can avoid mistaking host configuration changes for live routing changes.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user verify the agent is using the new active model and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid mistaking host configuration changes for live routing changes."
- },
- {
- "id": "docs-inference-switch-inference-providers-003",
- "question": "I'm trying a different model during active work. Help me know how to roll back to the previous model so I can experiment without disrupting the assistant workflow.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user know how to roll back to the previous model and gives enough concrete guidance, decision criteria, verification steps, or risk framing to experiment without disrupting the assistant workflow."
- },
- {
- "id": "docs-inference-set-up-sub-agent-001",
- "question": "I'm configuring a task-specific sub-agent. Help me assign a specialized model to work the default agent should not handle so I can improve task fit without changing the whole assistant.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user assign a specialized model to work the default agent should not handle and gives enough concrete guidance, decision criteria, verification steps, or risk framing to improve task fit without changing the whole assistant."
- },
- {
- "id": "docs-inference-set-up-sub-agent-002",
- "question": "I'm editing sub-agent model configuration. Help me understand where files, credentials, and workspace settings live so I can avoid leaking secrets or changing the wrong agent.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user understand where files, credentials, and workspace settings live and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid leaking secrets or changing the wrong agent."
- },
- {
- "id": "docs-inference-set-up-sub-agent-003",
- "question": "I'm testing a new sub-agent. Help me send a prompt that exercises the intended routing so I can prove it uses the expected provider and model.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user send a prompt that exercises the intended routing and gives enough concrete guidance, decision criteria, verification steps, or risk framing to prove it uses the expected provider and model."
- },
- {
- "id": "docs-inference-tool-calling-reliability-001",
- "question": "I'm seeing tool calls leak as plain text. Help me diagnose whether the model, server, or parser is incompatible so I can restore reliable tool execution.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user diagnose whether the model, server, or parser is incompatible and gives enough concrete guidance, decision criteria, verification steps, or risk framing to restore reliable tool execution."
- },
- {
- "id": "docs-inference-tool-calling-reliability-002",
- "question": "I'm comparing local inference runtimes. Help me understand whether Ollama, vLLM, or parser settings better support tool calls so I can choose a runtime that matches the agent's tool needs.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user understand whether Ollama, vLLM, or parser settings better support tool calls and gives enough concrete guidance, decision criteria, verification steps, or risk framing to choose a runtime that matches the agent's tool needs."
- },
- {
- "id": "docs-inference-tool-calling-reliability-003",
- "question": "I'm letting an always-on assistant use tools unattended. Help me define the reliability bar for local tool calling so I can avoid silent failures or unsafe plain-text tool outputs.",
- "expected_skill": "nemoclaw-user-configure-inference",
- "ground_truth": "A NemoClaw-specific answer that helps the user define the reliability bar for local tool calling and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid silent failures or unsafe plain-text tool outputs."
+ "ground_truth": "A NemoClaw-specific answer that helps the user compare hosted providers, local servers, and compatible endpoints and gives enough concrete guidance, decision criteria, verification steps, or risk framing to select a model path that fits my privacy, cost, and reliability needs.",
+ "expected_behavior": [
+ "Uses the expected_skill and does not make up answers if it cannot find the answer from the skill."
+ ]
}
]
diff --git a/skills/nemoclaw-user-configure-inference/references/inference-options.md b/skills/nemoclaw-user-configure-inference/references/inference-options.md
index 5242cff46c5..513f64a1bf5 100644
--- a/skills/nemoclaw-user-configure-inference/references/inference-options.md
+++ b/skills/nemoclaw-user-configure-inference/references/inference-options.md
@@ -1,10 +1,20 @@
-
-
# NemoClaw Inference Options
+import { AgentOnly } from "../_components/AgentGuide";
+
NemoClaw supports multiple inference providers.
-During onboarding, the `nemoclaw onboard` wizard presents a numbered list of providers to choose from.
-Your selection determines where the agent's inference traffic is routed.
+During onboarding, the NemoClaw onboarding wizard presents a numbered list of providers to choose from.
+Your selection determines where NemoClaw routes the agent's inference traffic.
+
+
+For OpenClaw onboarding, use `nemoclaw onboard`.
+The provider flow is the same, with the NVIDIA Endpoints route available for OpenClaw Agent.
+
+
+
+For Hermes onboarding, use `nemoclaw onboard`.
+The provider flow is the same, with the Hermes Provider route available for Hermes Agent.
+
## How Inference Routing Works
@@ -37,13 +47,13 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l
The onboard wizard presents the following provider options by default.
The first six are always available.
-Ollama appears when it is installed or running on the host.
+Ollama appears when you have installed or started it on the host.
Local vLLM appears when NemoClaw detects a running vLLM server.
The managed install/start vLLM entry appears by default on DGX Spark and DGX Station, and appears on generic Linux NVIDIA GPU hosts after opt-in.
| Option | Description | Curated models |
|--------|-------------|----------------|
-| NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_API_KEY`. | Nemotron 3 Super 120B, GLM-5.1, MiniMax M2.7, GPT-OSS 120B, DeepSeek V4 Pro |
+| NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_API_KEY`. | Nemotron 3 Super 120B, Nemotron 3 Ultra 550B, GLM-5.1, MiniMax M2.7, GPT-OSS 120B, DeepSeek V4 Pro |
| OpenAI | Routes to the OpenAI API. Set `OPENAI_API_KEY`. | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.4-pro-2026-03-05` |
| Other OpenAI-compatible endpoint | Routes to any server that implements `/v1/chat/completions`. NemoClaw uses `/v1/chat/completions` at runtime by default; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` for proxies that implement it, such as some llama.cpp builds. The wizard prompts for a base URL and model name. Works with OpenRouter, LocalAI, llama.cpp, or any compatible proxy. When you enable Telegram messaging, onboarding also runs a bounded sandbox-side smoke check through `https://inference.local/v1/chat/completions`. Set `COMPATIBLE_API_KEY`. | You provide the model name. |
| Anthropic | Routes to the Anthropic Messages API. Set `ANTHROPIC_API_KEY`. | `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6` |
@@ -57,7 +67,7 @@ The managed install/start vLLM entry appears by default on DGX Spark and DGX Sta
NVIDIA Nemotron models expose OpenAI-compatible APIs across every supported deployment surface, so two onboarding options can route to Nemotron.
-| Where Nemotron is hosted | Onboard wizard option | Why |
+| Nemotron Host | Onboard Wizard Option | Why |
|---|---|---|
| `build.nvidia.com` (NVIDIA-hosted) | **Option 1: NVIDIA Endpoints** | NemoClaw sets the base URL to `https://integrate.api.nvidia.com/v1` for you and validates the model against the build catalog. |
| Self-hosted NIM container | **Option 3: Other OpenAI-compatible endpoint** | NIM exposes an OpenAI-compatible `/v1/chat/completions` route. Point the base URL at your NIM service and enter the Nemotron model ID. |
@@ -74,14 +84,53 @@ When you select it, NemoClaw starts the router proxy on the host, waits for its
The sandbox does not call the router port directly.
The router model pool lives in `nemoclaw-blueprint/router/pool-config.yaml`.
+Edit that file to define which models the router can choose from.
The default pool routes between NVIDIA-hosted Nemotron models and uses the `tolerance` value to choose the lowest-cost model whose predicted quality stays within the configured threshold.
+
+```yaml
+routing:
+ method: prefill
+ checkpoint: llm-router/checkpoints/prefill_router_qwen08b.pt
+ tolerance: 0.20
+ encoder: Qwen/Qwen3.5-0.8B
+
+models:
+ - name: nano
+ litellm_model: "openai/nvidia/nvidia/Nemotron-3-Nano-30B-A3B"
+ cost_per_m_input_tokens: 0.05
+ api_base: "https://inference-api.nvidia.com"
+
+ - name: super
+ litellm_model: "openai/nvidia/nvidia/nemotron-3-super-v3"
+ cost_per_m_input_tokens: 0.10
+ api_base: "https://inference-api.nvidia.com"
+```
+
+The `tolerance` parameter controls the accuracy-cost tradeoff.
+
+| Value | Behavior |
+|-------|----------|
+| `0.0` | Always pick the most accurate model. |
+| `0.20` | Allow up to 20 percentage points below the best for a cheaper model (default). |
+| `1.0` | Always pick the cheapest model. |
+
+The router runs on the host, not inside the sandbox.
+
+```text
+Sandbox (agent) ──> OpenShell Gateway (L7 proxy) ──> Model Router (:4000) ──> NVIDIA API
+ └── PrefillRouter selects model
+```
+
+Credentials flow through the OpenShell provider system.
+The sandbox never sees raw API keys.
+
To use the router in scripted setup, set:
-```console
-$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive
+```bash
+NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive
```
-### Host Python requirement
+### Host Python Requirement
The Model Router runs in a host-side virtual environment that NemoClaw creates during onboarding.
NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, and adopts the first interpreter that satisfies both of:
@@ -94,18 +143,19 @@ This surfaces issues like Homebrew `python@3.14` whose `pyexpat` extension fails
To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemoclaw onboard`:
-```console
-$ NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard
+```bash
+NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard
```
The pin is strict.
NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`.
-Relative command names such as `python3.12` are rejected; use `command -v python3.12` to find the absolute path.
+NemoClaw rejects relative command names such as `python3.12`.
+Use `command -v python3.12` to find the absolute path.
If `python -m venv` itself fails for a probe-clean interpreter (for example, a corrupt ensurepip seed), NemoClaw retries with the next healthy candidate when no pin is set; with a pin set, the failure stops onboarding so you can fix or repoint the pinned python.
## Caveated Local Options
-The following local inference options are caveated.
+The following local inference options have caveats.
Local NIM and generic Linux managed vLLM install/start require `NEMOCLAW_EXPERIMENTAL=1`; DGX Spark and DGX Station managed vLLM entries appear by default.
An already-running vLLM server appears directly in the onboarding selection list.
@@ -120,23 +170,268 @@ For setup instructions, refer to [Use a Local Inference Server](../SKILL.md).
NemoClaw validates the selected provider and model before creating the sandbox.
If credential validation fails, the wizard asks whether to re-enter the API key, choose a different provider, retry, or exit.
-Transient upstream validation failures are retried before the wizard reports a provider failure.
+The wizard retries transient upstream validation failures before it reports a provider failure.
The `nvapi-` prefix check applies only to `NVIDIA_API_KEY`.
Other provider credentials, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, and compatible endpoint keys, use provider-aware validation during retry.
| Provider type | Validation method |
|---|---|
| OpenAI | Tries `/responses` first, then `/chat/completions`. |
-| NVIDIA Endpoints | Validates via `/v1/chat/completions` only; the `/v1/responses` probe is skipped because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). |
-| Google Gemini | Validates via Gemini's OpenAI-compatible chat-completions path only; the `/v1/responses` probe is skipped because Gemini does not support the Responses API. |
+| NVIDIA Endpoints | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). |
+| Google Gemini | Validates through Gemini's OpenAI-compatible chat-completions path only; NemoClaw skips the `/v1/responses` probe because Gemini does not support the Responses API. |
| Other OpenAI-compatible endpoint | Tries `/v1/responses` first with a tool-calling probe; falls back to `/v1/chat/completions`. Selected runtime API defaults to `/v1/chat/completions`; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. |
| Anthropic-compatible | Tries `/v1/messages`. |
| NVIDIA Endpoints (manual model entry) | Validates the model name against the catalog API. |
| Compatible endpoints | Sends a real inference request because many proxies do not expose a `/models` endpoint. For OpenAI-compatible endpoints, the probe tries `/v1/responses` first then falls back to `/v1/chat/completions`; the selected runtime API defaults to `/v1/chat/completions`. Set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. |
-| Local NVIDIA NIM | Validates via `/v1/chat/completions` only; the `/v1/responses` probe is skipped (same as NVIDIA Endpoints). |
+| Local NVIDIA NIM | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe (same as NVIDIA Endpoints). |
+
+## Setup Details for Local and Compatible Providers
+
+The sections below collect the detailed setup prompts and environment variables for local and compatible inference providers.
+Use them when the quickstart or local inference guide points you here for exact command shapes.
+
+## OpenAI-Compatible Server
+
+This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others.
+For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default.
+This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions.
+To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard.
+
+Start your model server.
+The examples below use vLLM, but any OpenAI-compatible server works.
+
+```bash
+vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
+```
+
+Run the onboard wizard.
+
+```bash
+nemoclaw onboard
+```
+
+When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**.
+Enter the base URL of your local server, for example `http://localhost:8000/v1`.
+
+The wizard prompts for an API key.
+If your server does not require authentication, enter any non-empty string (for example, `dummy`).
+
+NemoClaw validates the endpoint by sending a test inference request before continuing.
+The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider.
+If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires.
+If a reasoning model returns only reasoning content before producing a final answer, NemoClaw retries the smoke request with a larger response budget.
+Route, configuration, and authentication failures still fail immediately.
+
+### Non-Interactive Setup
+
+Set the following environment variables for scripted or CI/CD deployments.
+
+```bash
+NEMOCLAW_PROVIDER=custom \
+ NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \
+ NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \
+ COMPATIBLE_API_KEY=dummy \
+ nemoclaw onboard --non-interactive
+```
+
+| Variable | Purpose |
+|---|---|
+| `NEMOCLAW_PROVIDER` | Set to `custom` for an OpenAI-compatible endpoint. |
+| `NEMOCLAW_ENDPOINT_URL` | Base URL of the local server. |
+| `NEMOCLAW_MODEL` | Model ID as reported by the server. |
+| `COMPATIBLE_API_KEY` | API key for the endpoint. Use any non-empty value if authentication is not required. |
+
+### Selecting the API Path
+
+For the compatible-endpoint provider, `/v1/chat/completions` is the default.
+NemoClaw tests streaming events during onboarding and uses chat completions
+without probing the Responses API.
+
+To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard:
+
+```bash
+NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard
+```
+
+The wizard then probes `/v1/responses` and only selects it when streaming
+support is complete.
+If the probe fails, the wizard falls back to `/v1/chat/completions`
+automatically.
+You can use this variable in both interactive and non-interactive mode.
+
+| Variable | Values | Default |
+|---|---|---|
+| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints |
+
+If you already onboarded and the sandbox is failing at runtime, re-run `nemoclaw onboard` to re-probe the endpoint and bake the correct API path
+into the image.
+Refer to [Switch Inference Models](switch-inference-providers.md) for more information.
+
+## Anthropic-Compatible Server
+
+If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead.
+
+```bash
+nemoclaw onboard
+```
+
+For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`.
+
+```bash
+NEMOCLAW_PROVIDER=anthropicCompatible \
+ NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \
+ NEMOCLAW_MODEL=my-model \
+ COMPATIBLE_ANTHROPIC_API_KEY=dummy \
+ nemoclaw onboard --non-interactive
+```
+
+## vLLM
+
+When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model.
+On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you.
+
+For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list.
+
+If vLLM is already running, NemoClaw detects the running model and validates the endpoint.
+When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that value for the `contextWindow` baked into `openclaw.json` unless you set `NEMOCLAW_CONTEXT_WINDOW` yourself.
+If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default.
+Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears.
+NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready.
+Managed DGX Spark and DGX Station profiles use the stable NGC `nvcr.io/nvidia/vllm:26.05.post1-py3` container image.
+If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout.
+If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting.
+The first run can take 10 to 30 minutes.
+Later runs reuse the cached image and model weights.
+
+Managed vLLM uses these profiles:
+
+| Host profile | Default model |
+|---|---|
+| DGX Spark | `nvidia/Qwen3.6-35B-A3B-NVFP4` |
+| DGX Station | `Qwen/Qwen3.6-27B-FP8` |
+| Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` |
+
+**Note:**
+
+NemoClaw forces the `chat/completions` API path for vLLM.
+The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text.
+
+### Non-Interactive Setup
+
+Use an already-running vLLM server:
+
+```bash
+NEMOCLAW_PROVIDER=vllm \
+ nemoclaw onboard --non-interactive
+```
+
+Install or start managed vLLM when NemoClaw detects a supported profile.
+On DGX Spark and DGX Station, `NEMOCLAW_PROVIDER=install-vllm` is enough for non-interactive runs; add `NEMOCLAW_EXPERIMENTAL=1` on generic Linux NVIDIA GPU hosts.
+
+```bash
+NEMOCLAW_PROVIDER=install-vllm \
+ nemoclaw onboard --non-interactive
+```
+
+NemoClaw records the model returned by vLLM's `/v1/models` endpoint.
+Start vLLM with the model you want before onboarding if you manage the server yourself.
+
+### Override the Managed-vLLM Model
+
+Managed vLLM serves the profile default unless you select a different registry entry.
+Export `NEMOCLAW_VLLM_MODEL=` before invoking the installer to choose a different model from the registry.
+NemoClaw uses the matching `vllm serve` flags, including the reasoning parser, tool-call parser, and `--max-model-len`.
+Recognized slugs are:
+
+| Slug | Hugging Face model | Notes |
+|---|---|---|
+| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Default on the DGX Station profile |
+| `qwen3.6-35b-a3b-nvfp4` | `nvidia/Qwen3.6-35B-A3B-NVFP4` | Default on the DGX Spark profile |
+| `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile |
+| `deepseek-v4-flash` | `deepseek-ai/DeepSeek-V4-Flash` | Supported override |
+| `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance |
+
+The slug is case-insensitive; the full Hugging Face id is also accepted.
+An unrecognized value fails fast with a list of valid slugs.
+
+Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container:
+
+```bash
+export HF_TOKEN=
+NEMOCLAW_PROVIDER=install-vllm \
+ NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \
+ nemoclaw onboard --non-interactive
+```
+
+NemoClaw accepts `HUGGING_FACE_HUB_TOKEN` as an alternative.
+The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401.
+
+## NVIDIA NIM (Experimental)
+
+NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU.
+
+Set the experimental flag and run onboard.
+
+```bash
+NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard
+```
+
+Select **Local NVIDIA NIM [experimental]** from the provider list.
+NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing.
+On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used.
+On Docker 29.x or containerd image-store hosts, NemoClaw resolves the host-platform manifest digest before pulling multi-architecture NIM images when the registry exposes an index.
+It pulls `repo@digest` and retags the local image so NGC attestation metadata on other architectures does not block the selected platform.
+If the registry does not expose a matching index, NemoClaw falls back to the tag pull.
+
+NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication.
+If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history.
+The prompt masks the key during input and retries one time on a bad key before failing.
+In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`.
+If `NGC_API_KEY` or `NVIDIA_API_KEY` is already exported, NemoClaw passes it into the managed NIM container through the process environment instead of command-line arguments.
+If the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines.
+After NIM becomes healthy, NemoClaw reads `/v1/models` and uses the served model id for validation when it differs from the catalog name.
+Unsafe served ids are rejected instead of being written into the sandbox config.
+
+**Note:**
+
+NIM uses vLLM internally.
+The same `chat/completions` API path restriction applies.
+
+## Timeout Configuration
+
+Local inference requests use a default timeout of 180 seconds.
+Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup.
+
+To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding:
+
+```bash
+export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300
+nemoclaw onboard
+```
+
+The value is in seconds.
+NemoClaw bakes this setting into the sandbox at build time.
+Changing it after onboarding requires re-running `nemoclaw onboard`.
+
+`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe.
+During local Ollama setup, NemoClaw treats host-side curl process timeouts as retryable probe failures and retries with a larger timeout before it reports a validation failure.
+NemoClaw also retries Docker runtime detection with a longer `docker info` timeout before it chooses the local inference route.
+The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds.
+On hosts where the sandbox image takes minutes to build or upload, raise both settings together.
+Examples include large quantized models, DGX Station first runs, and remote VMs over a slow link.
+
+```bash
+export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300
+export NEMOCLAW_SANDBOX_READY_TIMEOUT=600
+nemoclaw onboard
+```
+
+If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill).
## Next Steps
- [Use a Local Inference Server](../SKILL.md) for Ollama, vLLM, NIM, and compatible-endpoint setup details.
+
- [Tool-Calling Reliability](tool-calling-reliability.md) for deciding when Ollama is enough and when vLLM with a parser is safer.
+
- [Switch Inference Models](switch-inference-providers.md) for changing the model at runtime without re-onboarding.
diff --git a/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md b/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md
index 148eaf0e7e2..48cf9b38c41 100644
--- a/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md
+++ b/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md
@@ -1,5 +1,3 @@
-
-
# Set Up Task-Specific Sub-Agents
OpenClaw documents the sub-agent behavior, `sessions_spawn` tool, `agents.list` configuration, tool policy, nesting, and auth model in [Sub-Agents](https://docs.openclaw.ai/tools/subagents).
@@ -37,17 +35,17 @@ It keeps the primary `main` agent on the normal NemoClaw inference route and add
| Sub-agent model | `nvidia-omni/private/nvidia/nemotron-3-nano-omni-reasoning-30b-a3b` |
| Delegation tool | `sessions_spawn` |
-Omni is used as the specialist model for image tasks.
+The sub-agent uses Omni as the specialist model for image tasks.
The primary orchestration model remains responsible for conversation, planning, and deciding when to delegate.
## Update the Sandbox Config
Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary provider and `agents.list` changes, then upload it back.
-```console
-$ export SANDBOX=my-assistant
-$ export DOCKER_CTR=openshell-cluster-nemoclaw
-$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json
+```bash
+export SANDBOX=my-assistant
+export DOCKER_CTR=openshell-cluster-nemoclaw
+docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json
```
Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config.
@@ -56,13 +54,13 @@ For the Omni example, the demo provides `vlm-demo/vlm-subagent/openclaw-patch.py
Upload the patched config and refresh the hash.
In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof; lock the config root-owned and read-only afterward if the sandbox should enforce config integrity at startup.
-```console
-$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/openclaw.json
-$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/.config-hash
-$ cat /tmp/openclaw.updated.json | docker exec -i "$DOCKER_CTR" kubectl exec -i -n openshell "$SANDBOX" -c agent -- sh -c 'cat > /sandbox/.openclaw/openclaw.json'
-$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash"
-$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/openclaw.json
-$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/.config-hash
+```bash
+docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/openclaw.json
+docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/.config-hash
+cat /tmp/openclaw.updated.json | docker exec -i "$DOCKER_CTR" kubectl exec -i -n openshell "$SANDBOX" -c agent -- sh -c 'cat > /sandbox/.openclaw/openclaw.json'
+docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash"
+docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/openclaw.json
+docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/.config-hash
```
Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change.
@@ -77,10 +75,10 @@ For the Omni example:
```
Use the same provider ID that appears in `models.providers`, such as `nvidia-omni`.
-After uploading the auth profile, make sure the sub-agent directory is owned by the sandbox user:
+After uploading the auth profile, make sure the sandbox user owns the sub-agent directory:
-```console
-$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator
+```bash
+docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator
```
## Allow Auxiliary Provider Egress
diff --git a/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md b/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md
index c5a623c42e1..f4bce7ec085 100644
--- a/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md
+++ b/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md
@@ -1,9 +1,9 @@
-
-
# Switch Inference Models at Runtime
+import { AgentOnly } from "../_components/AgentGuide";
+
Change the active inference model while the sandbox is running.
-No restart is required.
+You do not need to restart the sandbox.
## Prerequisites
@@ -12,100 +12,132 @@ No restart is required.
## Switch to a Different Model
+
Use `nemoclaw inference set` with the provider and model that match the upstream you want to use.
The command updates the OpenShell inference route and synchronizes the running agent config.
For OpenClaw, it updates `agents.defaults.model.primary` and the matching provider namespace.
-For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) without rebuilding or restarting Hermes.
+
+
+Use `nemoclaw inference set` with the provider and model that match the upstream you want to use.
+The command updates the OpenShell inference route and synchronizes the running agent config.
+For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes.
+Pass `--sandbox ` when you do not want to use the default registered sandbox.
+Under `nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox.
+
+
Pass `--sandbox ` when you do not want to use the default registered sandbox.
-Under `nemohermes`, pass `--sandbox ` when more than one Hermes sandbox is registered.
+
### NVIDIA Endpoints
-```console
-$ nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b
+```bash
+nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b
```
### OpenAI
-```console
-$ nemoclaw inference set --provider openai-api --model gpt-5.4
+```bash
+nemoclaw inference set --provider openai-api --model gpt-5.4
```
### Anthropic
-```console
-$ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6
+```bash
+nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6
```
### Google Gemini
-```console
-$ nemoclaw inference set --provider gemini-api --model gemini-2.5-flash
+```bash
+nemoclaw inference set --provider gemini-api --model gemini-2.5-flash
```
### Compatible Endpoints
If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint:
-```console
-$ nemoclaw inference set --provider compatible-endpoint --model
+```bash
+nemoclaw inference set --provider compatible-endpoint --model
```
-```console
-$ nemoclaw inference set --provider compatible-anthropic-endpoint --model
+```bash
+nemoclaw inference set --provider compatible-anthropic-endpoint --model
```
+
+
### Hermes Provider
For a NemoClaw-managed Hermes sandbox, use the Hermes alias with the registered Hermes Provider route:
-```console
-$ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini
+```bash
+nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini
```
+
+
+### API Family Sync
+
+Before patching the in-sandbox config, NemoClaw resolves the target route's API family: OpenAI chat completions, Anthropic Messages, or OpenAI Responses.
+For OpenClaw, `inference set` syncs the provider API family and primary model reference into the running config.
+For Hermes, `inference set` writes `model.api_mode: anthropic_messages` for Anthropic Messages routes, `model.api_mode: codex_responses` for OpenAI Responses routes, and removes `api_mode` for OpenAI-style chat-completions routes.
+Hermes also keeps `model.api_key` on the OpenShell proxy placeholder so dashboard and API sessions continue to authenticate through the gateway after a route change.
+
+Amazon Bedrock Runtime routes created through `compatible-anthropic-endpoint` are the exception.
+When you switch within the same Bedrock Runtime compatible provider, NemoClaw keeps the route OpenAI-compatible and does not set Hermes to Anthropic Messages mode.
+
#### Switching from Responses API to Chat Completions
-If onboarding selected `/v1/responses` but the agent fails at runtime (for
-example, because the backend does not emit the streaming events OpenClaw
-requires), re-run onboarding so the wizard re-probes the endpoint and bakes
-the correct API path into the image:
+If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image.
+This can happen when the backend does not emit the streaming events OpenClaw requires.
-```console
-$ nemoclaw onboard
+```bash
+nemoclaw onboard
```
Select the same provider and endpoint again.
-The updated streaming probe will detect incomplete `/v1/responses` support
-and select `/v1/chat/completions` automatically.
+The updated streaming probe detects incomplete `/v1/responses` support and selects `/v1/chat/completions` automatically.
-For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by
-default, so no env var is required to keep the safe path.
-To opt in to `/v1/responses` for a backend you have verified end to end, set
-`NEMOCLAW_PREFERRED_API` before onboarding:
+For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by default, so you do not need an environment variable to keep the safe path.
+To opt in to `/v1/responses` for a backend you have verified end to end, set `NEMOCLAW_PREFERRED_API` before onboarding:
-```console
-$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard
+```bash
+NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard
```
**Note:**
-`NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but
-does not update the Dockerfile ARG baked into the image.
-If you recreate the sandbox without the override env var, the image reverts to
-the original API path.
+`NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but does not update the Dockerfile ARG baked into the image.
+If you recreate the sandbox without the override environment variable, the image reverts to the original API path.
A fresh `nemoclaw onboard` is the reliable fix because it updates both the
session and the baked image.
## Cross-Provider Switching
+
Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`.
The command updates both the gateway route and the OpenClaw provider namespace in the running sandbox config.
+If the in-sandbox config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint.
+Run the rebuild before relying on the running agent if the warning says the image config could not be patched.
-```console
-$ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify
+```bash
+nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify
```
+
+
+Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`.
+The command updates both the gateway route and `/sandbox/.hermes/config.yaml`.
+If the Hermes config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint.
+Run the rebuild before relying on the running agent if the warning says the image config could not be patched.
+
+```bash
+nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify
+```
+
+
+
Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
## Tune Model Metadata
@@ -122,27 +154,42 @@ To change these values, set the corresponding environment variables before runni
| `NEMOCLAW_AGENT_TIMEOUT` | Positive integer (seconds) | `600` |
| `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | Go-style duration (`30m`, `1h`, `0m` to disable) | `unset` (OpenClaw default) |
-Invalid values are ignored, and the default bakes into the image.
+NemoClaw ignores invalid values and bakes the default into the image.
For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset.
+For local vLLM, onboarding uses the runtime `max_model_len` value when the server reports one and `NEMOCLAW_CONTEXT_WINDOW` is unset.
Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider.
-
-```console
-$ export NEMOCLAW_CONTEXT_WINDOW=65536
-$ export NEMOCLAW_MAX_TOKENS=8192
-$ export NEMOCLAW_REASONING=true
-$ export NEMOCLAW_INFERENCE_INPUTS=text,image
-$ export NEMOCLAW_AGENT_TIMEOUT=1800
-$ export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m
-$ nemoclaw onboard
+During interactive onboarding, NemoClaw prompts for **Text only** or **Text + Image** when the discovered model name looks multimodal and `NEMOCLAW_INFERENCE_INPUTS` is not already valid.
+Non-interactive onboarding uses the environment value or the default `text` setting.
+
+```bash
+export NEMOCLAW_CONTEXT_WINDOW=65536
+export NEMOCLAW_MAX_TOKENS=8192
+export NEMOCLAW_REASONING=true
+export NEMOCLAW_INFERENCE_INPUTS=text,image
+export NEMOCLAW_AGENT_TIMEOUT=1800
+export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m
+nemoclaw onboard
```
-`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into
-`agents.defaults.timeoutSeconds`. Increase it for slow local inference (for
-example, CPU-only Ollama or vLLM on modest hardware). NemoClaw writes this
-value into `openclaw.json` during onboarding. The default sandbox may keep that
-file writable for agent state, but direct in-sandbox edits are not the supported
-or durable way to change NemoClaw-managed defaults. Rebuild the sandbox via
-`nemoclaw onboard` to apply a new value.
+
+
+`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into `agents.defaults.timeoutSeconds`.
+Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware.
+NemoClaw writes this value into `openclaw.json` during onboarding.
+The default sandbox can keep that file writable for agent state, but direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults.
+Rebuild the sandbox with `nemoclaw onboard` to apply a new value.
+
+
+
+
+`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into the Hermes sandbox image.
+Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware.
+Direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults.
+Rebuild the sandbox with `nemoclaw onboard` to apply a new value.
+
+
+
+
`NEMOCLAW_AGENT_HEARTBEAT_EVERY` sets `agents.defaults.heartbeat.every`.
This controls OpenClaw's periodic main-session agent turn.
@@ -151,15 +198,22 @@ The OpenClaw default is 30 minutes (1 hour for Anthropic OAuth / Claude CLI reus
Tune the cadence with a duration string like `5m` or `2h`, or set `0m` to disable the periodic turns entirely.
Disabling also drops `HEARTBEAT.md` from normal-run bootstrap context per upstream behavior, so the model no longer sees heartbeat-only instructions.
NemoClaw writes this value into `openclaw.json` during onboarding.
-The in-sandbox `openclaw config set` command is not the supported path for
-NemoClaw-managed build-time defaults, and direct file edits are overwritten by a
-rebuild. Rebuild the sandbox via `nemoclaw onboard --resume` to apply a new value.
+The in-sandbox `openclaw config set` command is not the supported path for NemoClaw-managed build-time defaults, and a rebuild overwrites direct file edits.
+Rebuild the sandbox with `nemoclaw onboard --resume` to apply a new value.
+
+
+
+
+Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism.
+Rebuild the sandbox with `nemoclaw onboard --resume` to apply build-time inference metadata changes.
+
+
These variables are build-time settings.
If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image:
-```console
-$ nemoclaw onboard --resume --recreate-sandbox
+```bash
+nemoclaw onboard --resume --recreate-sandbox
```
## Verify the Active Model
@@ -167,16 +221,26 @@ $ nemoclaw onboard --resume --recreate-sandbox
Use `nemoclaw inference get` to print the provider and model the gateway is currently routing to.
Run it before `nemoclaw inference set` to confirm the starting state, or after a switch to verify the new route.
-```console
-$ nemoclaw inference get
+```bash
+nemoclaw inference get
+```
+
+Expected output:
+
+```text
Provider: nvidia-prod
Model: nvidia/nemotron-3-super-120b-a12b
```
Pass `--json` for machine-readable output.
-```console
-$ nemoclaw inference get --json
+```bash
+nemoclaw inference get --json
+```
+
+Expected output:
+
+```json
{
"provider": "nvidia-prod",
"model": "nvidia/nemotron-3-super-120b-a12b"
@@ -188,20 +252,33 @@ Run `nemoclaw onboard` to configure one.
Run the status command when you also need sandbox, service, and messaging health:
-```console
-$ nemoclaw status
+```bash
+nemoclaw status
```
The status output includes the active provider, model, and endpoint with the rest of the sandbox state.
## Notes
+
+
- The host keeps provider credentials.
- The sandbox continues to use `inference.local`.
- `nemoclaw inference set` patches the selected running OpenClaw or Hermes sandbox config and recomputes its config hash.
- Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents.
- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically.
+
+
+
+- The host keeps provider credentials.
+- The sandbox continues to use `inference.local`.
+- `nemoclaw inference set` patches the selected running Hermes sandbox config and recomputes its config hash.
+- Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents.
+- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically.
+
+
+
## Related Topics
- [Inference Options](inference-options.md) for the full list of providers available during onboarding.
diff --git a/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md b/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md
index 01f2c361152..5c136230910 100644
--- a/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md
+++ b/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md
@@ -1,11 +1,7 @@
-
-
# Tool-Calling Reliability for Local Inference
-Local inference is useful for privacy, cost control, and offline development, but
-tool-calling agents place stricter demands on the model server than simple chat.
-The model server must return structured `tool_calls`, not a JSON-looking string
-inside normal assistant text.
+Local inference is useful for privacy, cost control, and offline development, but tool-calling agents place stricter demands on the model server than simple chat.
+The model server must return structured `tool_calls`, not a JSON-looking string inside normal assistant text.
Use this page when the TUI shows raw JSON such as:
@@ -13,8 +9,7 @@ Use this page when the TUI shows raw JSON such as:
{"arguments":{"query":"robotics"},"name":"memory_search"}
```
-If that appears as text in the assistant reply, OpenClaw cannot dispatch the
-tool because the inference response did not include a structured tool call.
+If that appears as text in the assistant reply, OpenClaw cannot dispatch the tool because the inference response did not include a structured tool call.
## Quick Choice Guide
@@ -28,9 +23,8 @@ tool because the inference response did not include a structured tool call.
| Multi-turn tool dispatch | Risky | Yes |
Ollama can work well for lightweight local chat and some simple tool surfaces.
-For OpenClaw-style agent loops with multiple tools, long instructions, or
-multi-turn dispatch, use a server that exposes OpenAI-compatible
-`/v1/chat/completions` with a tool-call parser. vLLM is the common local choice.
+For OpenClaw-style agent loops with multiple tools, long instructions, or multi-turn dispatch, use a server that exposes OpenAI-compatible `/v1/chat/completions` with a tool-call parser.
+vLLM is the common local choice.
## Symptom
@@ -41,20 +35,23 @@ The common failure mode is:
- The gateway treats the response as normal text.
- No tool runs, and the user sees raw JSON in the TUI.
-This is different from a network or policy block. `nemoclaw status`,
-`nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while
-tool dispatch still fails inside the conversation.
+This is different from a network or policy block.
+`nemoclaw status`, `nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while tool dispatch still fails inside the conversation.
+
+### Nemotron Managed Inference
+
+For the `nvidia/nemotron-3-super-120b-a12b` managed inference route on `inference.local`, NemoClaw disables OpenClaw's native code-based tool search surface.
+That route otherwise tends to generate invalid JavaScript for the `tool_search_code` helper, which creates `[tools] tool_search_code failed` noise even when normal turns succeed.
+The agent still uses the structured tool-calling surface that the model handles correctly.
## Recommended Fix
-For persistent NemoClaw use, start vLLM with auto tool choice and the parser that
-matches your model family, then rerun onboarding and select **Local vLLM
-[experimental]** or **Other OpenAI-compatible endpoint**.
+For persistent NemoClaw use, start vLLM with auto tool choice and the parser that matches your model family, then rerun onboarding and select **Local vLLM [experimental]** or **Other OpenAI-compatible endpoint**.
For Hermes 3 style models, a known-good vLLM command shape is:
-```console
-$ vllm serve /models/Hermes-3-Llama-3.1-8B \
+```bash
+vllm serve /models/Hermes-3-Llama-3.1-8B \
--served-model-name hermes-3-llama-3.1-8b \
--enable-auto-tool-choice \
--tool-call-parser hermes \
@@ -93,22 +90,20 @@ services:
Then onboard against that endpoint:
-```console
-$ NEMOCLAW_PROVIDER=custom \
+```bash
+NEMOCLAW_PROVIDER=custom \
NEMOCLAW_ENDPOINT_URL=http://localhost:8002/v1 \
NEMOCLAW_MODEL=hermes-3-llama-3.1-8b \
COMPATIBLE_API_KEY=$VLLM_API_KEY \
nemoclaw onboard --non-interactive
```
-If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any
-non-empty placeholder, such as `dummy`.
+If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any non-empty placeholder, such as `dummy`.
## Advanced Temporary Repointing
-NemoClaw-managed sandboxes normally block direct `openclaw config set` writes
-inside the sandbox because those edits do not survive rebuilds. Prefer rerunning
-`nemoclaw onboard` for a persistent provider change.
+NemoClaw-managed sandboxes normally block direct `openclaw config set` writes inside the sandbox because those edits do not survive rebuilds.
+Prefer rerunning `nemoclaw onboard` for a persistent provider change.
If you are intentionally testing a mutable OpenClaw config, prepare a batch file
like this:
@@ -134,15 +129,13 @@ like this:
}
```
-Apply it only in environments where OpenClaw config writes are allowed:
+Apply it only in environments where OpenClaw allows config writes:
-```console
-$ openclaw config set --batch-file /sandbox/.openclaw/vllm-tool-calls.json
+```bash
+openclaw config set --batch-file /sandbox/.openclaw/vllm-tool-calls.json
```
-After testing, persist the working provider through `nemoclaw onboard` so the
-sandbox image, OpenShell inference route, and host-managed credentials stay in
-sync.
+After testing, persist the working provider through `nemoclaw onboard` so the sandbox image, OpenShell inference route, and host-managed credentials stay in sync.
## Verify the Fix
@@ -150,12 +143,9 @@ After switching to vLLM, ask for an action that should use a tool. Good signs:
- The TUI does not show JSON blobs as assistant text.
- The gateway log shows tool dispatch and a follow-up answer.
-- `nemoclaw status` reports the local vLLM or compatible endpoint as the
- active provider.
+- `nemoclaw status` reports the local vLLM or compatible endpoint as the active provider.
-If JSON still appears as text, confirm that vLLM was started with both
-`--enable-auto-tool-choice` and the correct `--tool-call-parser` value for your
-model.
+If JSON still appears as text, confirm that you started vLLM with both `--enable-auto-tool-choice` and the correct `--tool-call-parser` value for your model.
## Next Steps
diff --git a/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md b/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md
deleted file mode 100644
index fab5e58f2be..00000000000
--- a/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md
+++ /dev/null
@@ -1,151 +0,0 @@
-
-
-# Use a Local Inference Server: Details
-
-## Non-Interactive Setup
-
-```console
-$ NEMOCLAW_PROVIDER=ollama \
- NEMOCLAW_MODEL=qwen2.5:14b \
- nemoclaw onboard --non-interactive --yes
-```
-
-If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory.
-If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit.
-Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself.
-
-`--yes` (or `NEMOCLAW_YES=1`) authorises the Ollama model download without an interactive confirmation prompt.
-Under `--non-interactive`, `--yes` (or `NEMOCLAW_YES=1`) is required to authorise the download — onboard exits otherwise, since it cannot prompt.
-Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt that shows the model size before downloading.
-
-| Variable | Purpose |
-|---|---|
-| `NEMOCLAW_PROVIDER` | Set to `ollama`. |
-| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. |
-| `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. |
-
-### Selecting the API Path
-
-For the compatible-endpoint provider, `/v1/chat/completions` is the default.
-NemoClaw tests streaming events during onboarding and uses chat completions
-without probing the Responses API.
-
-To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard:
-
-```console
-$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard
-```
-
-The wizard then probes `/v1/responses` and only selects it when streaming
-support is complete.
-If the probe fails, the wizard falls back to `/v1/chat/completions`
-automatically.
-You can use this variable in both interactive and non-interactive mode.
-
-| Variable | Values | Default |
-|---|---|---|
-| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints |
-
-If you already onboarded and the sandbox is failing at runtime, re-run
-`nemoclaw onboard` to re-probe the endpoint and bake the correct API path
-into the image.
-Refer to [Switch Inference Models](switch-inference-providers.md) for details.
-
-## Anthropic-Compatible Server
-
-If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead.
-
-```console
-$ nemoclaw onboard
-```
-
-For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`.
-
-```console
-$ NEMOCLAW_PROVIDER=anthropicCompatible \
- NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \
- NEMOCLAW_MODEL=my-model \
- COMPATIBLE_ANTHROPIC_API_KEY=dummy \
- nemoclaw onboard --non-interactive
-```
-
-### Override the Managed-vLLM Model
-
-Managed vLLM serves the profile default unless you select a different registry entry.
-Export `NEMOCLAW_VLLM_MODEL=` before invoking the installer to choose a different model from the registry.
-NemoClaw uses the matching `vllm serve` flags, including the reasoning parser, tool-call parser, and `--max-model-len`.
-Recognised slugs:
-
-| Slug | Hugging Face model | Notes |
-|---|---|---|
-| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Default on DGX Spark and DGX Station profiles |
-| `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile |
-| `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance |
-
-The slug is case-insensitive; the full Hugging Face id is also accepted.
-An unrecognised value fails fast with a list of valid slugs.
-
-Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container:
-
-```console
-$ export HF_TOKEN=
-$ NEMOCLAW_PROVIDER=install-vllm \
- NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \
- nemoclaw onboard --non-interactive
-```
-
-`HUGGING_FACE_HUB_TOKEN` is accepted as an alternative.
-The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401.
-
-## Timeout Configuration
-
-Local inference requests use a default timeout of 180 seconds.
-Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup.
-
-To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding:
-
-```console
-$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300
-$ nemoclaw onboard
-```
-
-The value is in seconds.
-This setting is baked into the sandbox at build time.
-Changing it after onboarding requires re-running `nemoclaw onboard`.
-
-`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe.
-The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds.
-On hosts where the sandbox image takes minutes to build or upload — large quantised models, DGX Station first runs, or remote VMs over a slow link — raise both together:
-
-```console
-$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300
-$ export NEMOCLAW_SANDBOX_READY_TIMEOUT=600
-$ nemoclaw onboard
-```
-
-If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill).
-
-## Verify the Configuration
-
-After onboarding completes, confirm the active provider and model.
-
-```console
-$ nemoclaw status
-```
-
-The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model.
-For Local Ollama, status also checks the authenticated proxy when a proxy token is available.
-If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use.
-
-## Switch Models at Runtime
-
-You can change the model without re-running onboard.
-Refer to [Switch Inference Models](switch-inference-providers.md) for the full procedure.
-
-For compatible endpoints, the command is:
-
-```console
-$ nemoclaw inference set --provider compatible-endpoint --model
-```
-
-If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`.
diff --git a/skills/nemoclaw-user-configure-inference/skill-card.md b/skills/nemoclaw-user-configure-inference/skill-card.md
index 4a29ef3787c..c3d82db7095 100644
--- a/skills/nemoclaw-user-configure-inference/skill-card.md
+++ b/skills/nemoclaw-user-configure-inference/skill-card.md
@@ -23,7 +23,6 @@ Mitigation: Review and scan skill before deployment.
- [Set Up Sub-Agent](references/set-up-sub-agent.md)
- [Switch Inference Providers](references/switch-inference-providers.md)
- [Tool-Calling Reliability](references/tool-calling-reliability.md)
-- [Use Local Inference Details](references/use-local-inference-details.md)
## Skill Output:
diff --git a/skills/nemoclaw-user-reference/SKILL.md b/skills/nemoclaw-user-reference/SKILL.md
index 25cb810e52c..6d57867d78c 100644
--- a/skills/nemoclaw-user-reference/SKILL.md
+++ b/skills/nemoclaw-user-reference/SKILL.md
@@ -9,7 +9,7 @@ license: "Apache-2.0"
## References
- **Load [references/architecture.md](references/architecture.md)** when looking up architecture, agent integration, plugin structure, or blueprint design. Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes.
-- **[references/cli-selection-guide.md](references/cli-selection-guide.md)** — Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations.
+- **Load [references/cli-selection-guide.md](references/cli-selection-guide.md)** when user asks to decide whether to use `$$nemoclaw` or `openshell`. Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations.
- **Load [references/commands.md](references/commands.md)** when looking up a specific `$$nemoclaw`, `nemohermes`, or `/nemoclaw` subcommand, flag, argument, or exit code. Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands.
- **Load [references/network-policies.md](references/network-policies.md)** when looking up a specific default endpoint, filesystem path, or the runtime approval sequence NemoClaw applies on blocked requests. Covers the baseline network policy, filesystem rules, and operator approval flow.
- **Load [references/troubleshooting.md](references/troubleshooting.md)** when diagnosing a reported NemoClaw error, a failed onboard, or unexpected sandbox behavior. Lists fixes for common installation, onboarding, and runtime issues.
diff --git a/skills/nemoclaw-user-reference/references/architecture.md b/skills/nemoclaw-user-reference/references/architecture.md
index 07bbfc2ba9f..0593eec89ca 100644
--- a/skills/nemoclaw-user-reference/references/architecture.md
+++ b/skills/nemoclaw-user-reference/references/architecture.md
@@ -68,9 +68,14 @@ graph LR
The logical diagram above shows how components relate.
This section shows what actually runs where on the host.
NemoClaw's default Docker-driver topology does not place the sandbox in an embedded k3s cluster.
-On Linux and Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container.
-The gateway normally runs as a host process; Linux hosts that need the gateway compatibility patch may run the same gateway binary inside a small container.
+On Linux, NemoClaw configures and restarts the package-managed OpenShell gateway user service when it is installed, then creates the sandbox as a Docker container.
+NemoClaw treats that service as authoritative only when `systemctl --user show openshell-gateway` reports a package/vendor unit path and an `openshell-gateway` `ExecStart`.
+Per-user units, partial units, and user-manager or bus outages do not take over gateway ownership; NemoClaw falls back to the standalone gateway process used by earlier installs.
+That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage.
+On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container.
In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod.
+The in-container `/tmp/nemoclaw-gateway-local` marker is written only by the entrypoint path that actually launches `openclaw gateway run`;
+NemoClaw does not treat sandbox environment hints such as `OPENSHELL_DRIVERS` as authoritative for dashboard-gateway ownership.
Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology.
```mermaid
@@ -134,8 +139,10 @@ The concrete files differ by agent because each runtime has its own plugin syste
| Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. |
The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox.
-Before an OpenClaw turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary.
+Before an OpenClaw turn starts, the plugin prepends a short system-context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary.
+This guidance stays out of the visible chat transcript.
When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context.
+The context tells the agent to try allowed network and filesystem operations before reporting them unavailable, and to distinguish policy denials from DNS, timeout, TLS, or filesystem errors.
The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path.
The manifest declares Hermes' binary, health probe, config directory, state directories, messaging support, and OpenAI-compatible API endpoint.
@@ -197,7 +204,7 @@ runner still carries a pinned OpenShell Community OpenClaw image for legacy
- Inference calls are routed through OpenShell to the configured provider.
- Network egress is restricted by the baseline policy for the selected agent profile.
- Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only.
-- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can report policy blocks accurately.
+- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can attempt allowed actions and report policy blocks or infrastructure failures accurately.
- The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding.
- The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`.
diff --git a/skills/nemoclaw-user-reference/references/commands.md b/skills/nemoclaw-user-reference/references/commands.md
index 4a632f4f6ab..bf775e1dec8 100644
--- a/skills/nemoclaw-user-reference/references/commands.md
+++ b/skills/nemoclaw-user-reference/references/commands.md
@@ -33,7 +33,7 @@ OpenClaw-specific sections below describe the `/nemoclaw` slash command, the Ope
Use `nemohermes` for the Hermes variant.
It selects Hermes by default during onboarding and for other commands.
Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point.
-Hermes-specific sections below describe the OpenAI-compatible API endpoint, optional Hermes dashboard, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`.
+Hermes-specific sections below describe the built-in Hermes dashboard, the separate OpenAI-compatible API endpoint, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`.
```bash
nemohermes onboard # selects Hermes by default
@@ -173,6 +173,10 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `bal
NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accept-third-party-software
```
+Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default.
+In non-interactive mode, any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight, gateway, or inference side effects with an error listing the valid options.
+Interactive onboarding ignores an invalid environment value and shows the normal tier prompt.
+
`NEMOCLAW_POLICY_MODE` controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox's currently-applied presets.
The default is `suggested`, which is *additive*.
Onboarding applies tier defaults and preserves any presets you previously added with [`nemoclaw policy-add`](#nemoclaw-name-policy-add) across re-onboards.
@@ -181,6 +185,12 @@ Onboarding removes any preset that is not in the list.
`skip` leaves the applied set untouched and does not apply tier defaults.
NemoClaw filters tier suggestions and resume selections by active agent support, so unsupported presets such as Brave Search are not reapplied to agents that do not support them.
+
+
+Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets.
+
+
+
| Value | Behaviour |
|-------|-----------|
| `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. |
@@ -299,9 +309,10 @@ The poll count is clamped to a minimum of `1` so the probe always runs at least
Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image.
The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it.
-Onboarding skips common large directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context.
-It also skips credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`.
-Other build outputs such as `dist/`, `target/`, or `build/` are still included.
+If that directory contains a `.dockerignore`, onboarding applies those rules while calculating the context size and staging files for Docker.
+NemoClaw also applies additional secret-safety exclusions that override `.dockerignore` negation rules: credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key` are still skipped even if `.dockerignore` tries to include them.
+Without a `.dockerignore`, onboarding still skips common large or local-only directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context.
+Other build outputs such as `dist/`, `target/`, or `build/` are included unless your `.dockerignore` excludes them.
If the staged context is larger than 100 MB, onboarding prints a warning before the Docker build starts.
If the directory contains unreadable files (for example, Windows system files visible in WSL), onboarding exits with an error suggesting you move the Dockerfile to a dedicated directory.
@@ -387,6 +398,7 @@ List all registered sandboxes with their model, provider, and policy presets.
Pass `--json` for machine-readable output that includes a `schemaVersion`, the default sandbox, recovery metadata, and the sandbox inventory.
Sandboxes with an active SSH session are marked with a `●` indicator so you can tell at a glance which sandbox you are already connected to in another terminal.
When a sandbox has a recorded dashboard port, the output includes its local dashboard URL.
+The default sandbox in text and JSON output honors the same environment override order as host-level status and tunnel commands: `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default.
```bash
nemoclaw list [--json]
@@ -564,10 +576,15 @@ Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a new
`nemoclaw status` prints the running OpenClaw version on the `Agent` line:
-```console
-$ nemoclaw my-assistant status
+```bash
+nemoclaw my-assistant status
+```
+
+Expected output:
+
+```text
...
- Agent: OpenClaw v2026.5.22
+ Agent: OpenClaw v2026.5.27
...
```
@@ -585,8 +602,13 @@ Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a new
`nemohermes status` prints the running Hermes version on the `Agent` line:
-```console
-$ nemohermes my-assistant status
+```bash
+nemohermes my-assistant status
+```
+
+Expected output:
+
+```text
...
Agent: Hermes v2026.5.16
...
@@ -606,10 +628,35 @@ Warnings do not make the command fail.
Failed checks exit non-zero so scripts can use `doctor` as a readiness gate.
Use `--json` for machine-readable output.
+
+
+For OpenClaw sandboxes, `doctor` also checks the mutable config permission contract.
+If `openclaw doctor --fix` was run inside the sandbox, it can tighten `/sandbox/.openclaw` and `openclaw.json` to a single-user `700/600` layout, which stops the gateway from persisting config changes.
+`doctor` reports this as a `Config permissions` warning; pass `--fix` to restore the group-writable `2770/660` contract without rebuilding.
+Restarting the sandbox repairs the same drift automatically.
+
+```bash
+nemoclaw my-assistant doctor [--json | --fix]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Emit the report as JSON |
+| `--fix` | Restore the mutable OpenClaw config permission contract if it was tightened. Mutually exclusive with `--json` |
+
+
+
+
```bash
nemoclaw my-assistant doctor [--json]
```
+| Flag | Description |
+|------|-------------|
+| `--json` | Emit the report as JSON |
+
+
+
### `nemoclaw logs`
View sandbox logs.
@@ -628,7 +675,9 @@ nemoclaw my-assistant logs [--follow] [--tail |-n ] [--since
-Print the authenticated OpenClaw dashboard URL for a running sandbox.
+Print the browser dashboard URL for a running sandbox.
+For OpenClaw sandboxes this includes the authenticated URL fragment.
+For agent dashboards that manage their own session, such as Hermes Agent, this prints the plain dashboard URL.
Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session.
```bash
@@ -647,14 +696,22 @@ URL=$(nemoclaw my-assistant dashboard-url --quiet)
Treat the authenticated dashboard URL like a password.
Do not log it, share it, or commit it to version control.
+This warning applies when the command prints an OpenClaw tokenized URL.
-`dashboard-url` is not applicable to Hermes sandboxes because Hermes exposes an OpenAI-compatible API endpoint instead of the OpenClaw dashboard URL.
-Use `nemohermes my-assistant status` to find the forwarded API endpoint.
-The Hermes API remains on port `8642` and uses `/v1` for OpenAI-compatible clients.
-If you enabled `NEMOCLAW_HERMES_DASHBOARD=1`, use the optional Hermes dashboard port from the status output instead.
+Print the browser dashboard URL for a running Hermes sandbox.
+Hermes manages dashboard sessions itself, so this command prints a plain URL without an OpenClaw `#token=` fragment.
+The built-in dashboard is forwarded on port `18789` by default.
+
+```bash
+nemohermes my-assistant dashboard-url
+nemohermes my-assistant dashboard-url --quiet
+```
+
+The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for OpenAI-compatible clients.
+Use `nemohermes my-assistant status` to see both the dashboard and API endpoints.
@@ -772,6 +829,8 @@ Custom presets bypass the built-in preset review process and can widen sandbox e
List available policy presets and show which ones are applied to the sandbox.
The command cross-references the local registry against the live gateway state (via `openshell policy get`), so it flags presets that are applied in one place but not the other.
This catches desync caused by external edits to the gateway policy or stale registry entries after a manual rollback.
+Preset summaries come only from the YAML `preset.description` field.
+NemoClaw does not render network-policy rule bodies as prose in `policy-list` output.
```bash
nemoclaw my-assistant policy-list
@@ -802,6 +861,37 @@ If the preset is unknown or not currently applied, the command exits non-zero wi
Unchecking a preset in the onboard TUI checkbox also removes it from the sandbox.
+### `nemoclaw policy-explain`
+
+Print a redacted summary of the active policy context for a sandbox so an agent or operator can reason about what is allowed, what is blocked, and how to request a change.
+The output covers the recorded tier, the applied presets (built-in and custom) with their allowed host categories, the known presets that are not applied, the inspect/add/remove commands that change policy, and the support boundaries between NemoClaw, OpenShell, and the agent.
+Raw policy YAML, rule bodies, and credential metadata are deliberately not included.
+
+```bash
+nemoclaw my-assistant policy-explain
+```
+
+Pass `--json` to emit the same context as a structured object for agent consumption:
+
+```bash
+nemoclaw my-assistant policy-explain --json
+```
+
+NemoClaw refreshes the rendered context inside the sandbox at `/sandbox/.openclaw/workspace/POLICY.md` whenever a preset is added or removed, and once at the end of the onboarding policy step.
+Pass `--write` to refresh that file on demand without changing the policy:
+
+```bash
+nemoclaw my-assistant policy-explain --write
+```
+
+The context also documents how a failed host or integration attempt should be classified.
+The classifications are `blocked-by-policy`, `missing-approval`, `unsupported`, and `unknown`, so the agent can pick a remediation step instead of surfacing a lower-level network error.
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Emit the policy context as a structured JSON object for agent consumption |
+| `--write` | Refresh `/sandbox/.openclaw/workspace/POLICY.md` inside the sandbox in addition to printing |
+
### `nemoclaw hosts-add`
Add a host alias to the sandbox pod template.
@@ -975,6 +1065,9 @@ Skill names must contain only alphanumeric characters, dots, hyphens, and unders
OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see Install OpenClaw Plugins.
+For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into `$HOME/.openclaw/skills/` when the agent home directory differs from the state directory.
+That mirror makes skills listed by `openclaw skills list` available at session startup.
+If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions.
@@ -1268,8 +1361,13 @@ Use this path only when the destination sandbox can be replaced by the selected
Mount the sandbox filesystem on the host machine via SSHFS for bidirectional file sharing.
Files edited on the host appear instantly inside the sandbox, and vice versa.
-```console
-$ nemoclaw my-assistant share mount
+```bash
+nemoclaw my-assistant share mount
+```
+
+Expected output:
+
+```text
✓ Mounted /sandbox → ~/.nemoclaw/mounts/my-assistant
```
@@ -1308,8 +1406,13 @@ nemoclaw my-assistant share unmount
Check whether the sandbox filesystem is currently mounted.
-```console
-$ nemoclaw my-assistant share status
+```bash
+nemoclaw my-assistant share status
+```
+
+Expected output:
+
+```text
● Mounted at ~/.nemoclaw/mounts/my-assistant
```
@@ -1373,6 +1476,16 @@ nemoclaw tunnel stop
`nemoclaw stop` remains as a deprecated alias that prints a warning and delegates to `tunnel stop`.
+### `nemoclaw tunnel status`
+
+Show the current cloudflared public-URL tunnel status for the selected or default sandbox dashboard.
+The output reports whether cloudflared is running, stopped, or stale, and includes the same recovery hint used by `nemoclaw status`.
+Selection honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default.
+
+```bash
+nemoclaw tunnel status
+```
+
### `nemoclaw start`
**Warning:**
@@ -1394,6 +1507,7 @@ This command remains as a compatibility alias to `nemoclaw tunnel stop`.
Show the sandbox list and the status of host auxiliary services (for example cloudflared).
Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and messaging health.
For each listed sandbox, the text output includes the configured inference provider and model plus whether an active SSH session is connected.
+Host-service PID lookup honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default.
```bash
nemoclaw status
@@ -1430,7 +1544,8 @@ For OpenClaw, the patch updates the OpenClaw config provider namespace and selec
-For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) and does not rebuild or restart the gateway.
+For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) and does not rebuild or restart the gateway.
+Keeping the placeholder preserves dashboard and API authentication after provider switches.
Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass `--sandbox ` to target one explicitly.
@@ -1548,7 +1663,7 @@ Earlier releases only stopped `openshell forward` processes, so those orphans ac
For Local Ollama setups, uninstall also stops matching Ollama auth proxy processes before deleting `~/.nemoclaw` state so stale proxy listeners do not block a later reinstall.
-On Linux, uninstall removes `~/.local/state/nemoclaw`, which contains Docker-driver gateway PID files, SQLite data, audit logs, and VM-driver state.
+On Linux, uninstall removes `~/.local/state/nemoclaw`, which contains Docker-driver gateway SQLite data, audit logs, VM-driver state, and standalone-fallback gateway PID files.
| Flag | Effect |
|---|---|
@@ -1690,15 +1805,14 @@ For OpenClaw, `NEMOCLAW_DASHBOARD_PORT` controls the OpenClaw dashboard forward.
-For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the OpenAI-compatible API forward.
-For Hermes sandboxes, `NEMOCLAW_HERMES_DASHBOARD=1` starts the native Hermes dashboard separately from the OpenAI-compatible API.
-The Hermes API remains on port `8642`; the optional browser dashboard uses `NEMOCLAW_HERMES_DASHBOARD_PORT`.
+For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the built-in dashboard forward, which defaults to `18789`.
+The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for API clients.
+Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-browser TUI tab.
| Variable | Default | Service |
|----------|---------|---------|
-| `NEMOCLAW_HERMES_DASHBOARD` | 0 | Optional Hermes native web dashboard (`1`, `true`, `yes`, or `on` enables it) |
-| `NEMOCLAW_HERMES_DASHBOARD_PORT` | 9119 | Optional Hermes native web dashboard forward port |
-| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab when the dashboard is enabled |
+| `NEMOCLAW_DASHBOARD_PORT` | 18789 | Hermes built-in dashboard forward port |
+| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab |
@@ -1722,10 +1836,13 @@ Set them before running `nemoclaw onboard`.
| `NEMOCLAW_OPENCLAW_OTEL_SERVICE_NAME` | service name | Sets the OTEL `service.name` for OpenClaw gateway spans. Defaults to `openclaw-gateway`. |
| `NEMOCLAW_OPENCLAW_OTEL_SAMPLE_RATE` | `0.0` to `1.0` | Sets OpenClaw's root-span sample rate for conversation diagnostics. Defaults to `1.0`. |
| `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). |
-| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. |
+| `NEMOCLAW_SANDBOX_NAME` | sandbox name | Preferred environment override for the default sandbox. Used by onboarding defaults and host-level commands such as `list`, `status`, `tunnel`, `services`, and `debug`. |
+| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. |
+| `SANDBOX_NAME` | sandbox name | Compatibility spelling used after `NEMOCLAW_SANDBOX_NAME` and `NEMOCLAW_SANDBOX`. |
| `NEMOCLAW_INSTALL_REF` | git ref | For internal installer commands: the git ref to install from. Overridden by the `--install-ref` flag. |
| `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. |
-| `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `deepseek-r1-distill-70b`. Unset uses the per-platform profile default. Gated models (e.g. `deepseek-r1-distill-70b`) require `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`. |
+| `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `deepseek-v4-flash`, `deepseek-r1-distill-70b`. Unset uses the per-platform profile default. Gated models (e.g. `deepseek-r1-distill-70b`) require `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`. |
+| `NEMOCLAW_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; see Runtime Controls (use the `nemoclaw-user-manage-sandboxes` skill). |
| `NEMOCLAW_MODEL_ROUTER_PYTHON` | absolute path | Pins the host Python interpreter used to create the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to another python. Relative command names such as `python3.12` are rejected. When unset, NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, retains every interpreter whose version is in `[3.10, 3.14)` and whose `ensurepip`, `pyexpat`, `ssl`, and `venv` stdlib modules import cleanly, and tries `python -m venv` on each in priority order until one succeeds. Set the pin when the auto-discovered interpreter is broken (for example, Homebrew `python@3.14` with a `pyexpat` dlopen mismatch on macOS). |
@@ -1751,6 +1868,38 @@ Hermes-specific provider authentication:
| `NEMOCLAW_HERMES_AUTH_METHOD` | `oauth` | Selects Hermes Provider authentication in non-interactive onboarding. Valid values: `oauth`, `nous-portal-oauth`, `api-key`, `nous-api-key`. |
| `NEMOCLAW_HERMES_AUTH` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Back-compatible alias for Hermes Provider authentication selection. |
| `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. |
+| `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. |
+| `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. |
+| `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` | whitespace- or comma-separated list of upper-snake env keys | Adds operator-supplied OpenShell provider rows so per-profile credentials such as `TELEGRAM_BOT_TOKEN_AGENT_A` flow through the same out-of-process placeholder injection that the canonical channel tokens use, instead of being baked into each Hermes profile `.env` as raw text. See [Extra placeholder keys](#extra-placeholder-keys) for the entry shape and validation rules. |
+
+
+
+
+
+#### Extra placeholder keys
+
+Set `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` before running `nemoclaw onboard` when one container hosts multiple Hermes profiles and each profile needs its own messaging-bridge credential.
+
+```bash
+export NEMOCLAW_EXTRA_PLACEHOLDER_KEYS="TELEGRAM_BOT_TOKEN_AGENT_A TELEGRAM_BOT_TOKEN_AGENT_B"
+export TELEGRAM_BOT_TOKEN_AGENT_A=
+export TELEGRAM_BOT_TOKEN_AGENT_B=
+nemoclaw onboard --agent hermes
+```
+
+For each entry, NemoClaw registers a generic OpenShell provider row that resolves the named env to its operator-supplied value at egress time.
+The Hermes profile `.env` files are operator-owned: write `${TELEGRAM_BOT_TOKEN_AGENT_A}` (or the matching placeholder for each entry) into the per-profile `.env` so the in-sandbox Hermes process inherits the OpenShell placeholder instead of a raw token.
+NemoClaw never reads, writes, or rewrites these `.env` files; verify after onboarding that each profile's `.env` references the placeholder and that no raw bot token value sits on disk.
+
+Entries are split on whitespace and commas and must match `^[A-Z][A-Z0-9_]{0,127}$`.
+Each entry must extend a canonical channel envKey with a non-empty `_` (for example `TELEGRAM_BOT_TOKEN_AGENT_A`); the canonical envKeys are `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, `WECHAT_BOT_TOKEN`, and `BRAVE_API_KEY`.
+Bare canonical envKeys, the control env itself, and arbitrary host secret names (`GITHUB_TOKEN`, `AWS_SECRET_ACCESS_KEY`, `KUBECONFIG`, and similar) are refused so they cannot leak into the sandbox provider gateway.
+Duplicates are dropped silently.
+The list is capped at 32 entries per sandbox.
+Offending tokens emit one warning each and are skipped.
+
+If a referenced env is unset at onboard time, the matching provider row is registered with a null token; the `upsertMessagingProviders` helper then skips the row, so no placeholder is attached to the OpenShell gateway and no Hermes profile can resolve it.
+Export the credential before running `nemoclaw onboard` for that profile.
@@ -1830,9 +1979,9 @@ These flags toggle optional behaviors during onboarding; set them before running
| `NEMOCLAW_SANDBOX_GPU` | `auto`, `1`, or `0` | Controls sandbox GPU passthrough during onboarding. `auto` enables GPU passthrough when an NVIDIA GPU is detected, `1` requires GPU passthrough, and `0` forces CPU-only sandbox creation. |
| `NEMOCLAW_SANDBOX_GPU_DEVICE` | OpenShell GPU device selector | Selects the GPU device passed with `openshell sandbox create --gpu-device`. Requires explicit sandbox GPU enablement with `NEMOCLAW_SANDBOX_GPU=1` (or `--sandbox-gpu` for CLI-driven onboarding); otherwise onboarding rejects the selector instead of treating it as an implicit opt-in. |
| `NEMOCLAW_DOCKER_GPU_PATCH` | `0` to disable, anything else to keep the default | Controls the Linux Docker-driver GPU sandbox compatibility patch. Set to `0` only as an escape hatch when the patch fails and you need onboarding to continue without patching the GPU sandbox container. |
-| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver gateway. Defaults to the binary next to `openshell`, then common install paths. |
-| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary passed to the Linux Docker-driver gateway supervisor. Defaults to the binary next to `openshell`, then common install paths. |
-| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway pid file and SQLite state directory. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. |
+| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths. |
+| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths. |
+| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway SQLite state directory and standalone-fallback PID file. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. |
| `NEMOCLAW_AUTO_FIX_FIREWALL` | `1` to enable | Opts in to automatic UFW remediation when Linux Docker-driver sandbox containers cannot reach the host gateway after a proven TCP failure. NemoClaw runs `sudo -n` only, validates the narrow Docker bridge subnet → gateway IP:port rule before invoking UFW, re-probes after applying it, and otherwise falls back to the printed manual command. |
| `NEMOCLAW_WECHAT_QUIET` | `1` to enable | Silences the `[wechat]` diagnostic lines printed during the host-side WeChat QR login (poll status, IDC redirects, swallowed gateway errors), which are visible by default while the experimental WeChat path stabilizes; set `1` once the flow is reliable in your environment. |
diff --git a/skills/nemoclaw-user-reference/references/network-policies.md b/skills/nemoclaw-user-reference/references/network-policies.md
index de3517a6902..937dd41abe0 100644
--- a/skills/nemoclaw-user-reference/references/network-policies.md
+++ b/skills/nemoclaw-user-reference/references/network-policies.md
@@ -57,13 +57,14 @@ The baseline policy is always applied regardless of the selected tier.
| Tier | Presets included | Description |
|------|------------------|-------------|
| Restricted | None | Base sandbox only. No third-party network access beyond inference and core agent tooling. |
-| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported` | Full dev tooling and web search for agents that support web search. No messaging platform access. |
-| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging and productivity. |
+| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather` | Full dev tooling, read-only weather lookups, and web search for agents that support web search. No messaging platform access. |
+| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather`, `public-reference`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging, productivity, weather, and public-reference APIs. |
After selecting a tier, a combined preset and access-mode screen lets you include or exclude individual presets and toggle each between read (GET only) and read-write (GET + POST/PUT/PATCH) access.
Tier-default presets are pre-selected; additional presets can be added from the full list.
NemoClaw filters tier defaults by the active agent's supported integrations.
For example, Hermes onboarding omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration.
+Hermes managed-tool gateway selections can add Hermes-specific presets, such as Nous-hosted web, image, audio, browser, or code tools, without applying unsupported OpenClaw-only presets.
Claude Code direct egress is not included in any policy tier.
If you install and run the Claude Code CLI inside the sandbox with its own credentials, apply the `claude-code` preset explicitly.
Normal NemoClaw Anthropic inference still routes through the OpenShell gateway.
@@ -76,7 +77,9 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER`:
NEMOCLAW_POLICY_TIER=open nemoclaw onboard --non-interactive --yes-i-accept-third-party-software
```
-If the value does not match a known tier, onboarding exits with an error listing the valid options.
+Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default.
+In non-interactive onboarding, a non-blank value that does not match a known tier exits before preflight, gateway, or inference side effects and lists the valid options.
+Interactive onboarding ignores an invalid environment value and shows the normal tier prompt.
### Inference
diff --git a/skills/nemoclaw-user-reference/references/troubleshooting.md b/skills/nemoclaw-user-reference/references/troubleshooting.md
index cdafbeb91ab..71fd30c635b 100644
--- a/skills/nemoclaw-user-reference/references/troubleshooting.md
+++ b/skills/nemoclaw-user-reference/references/troubleshooting.md
@@ -660,6 +660,8 @@ Region errors usually mean the pasted endpoint region, `AWS_REGION`, `AWS_DEFAUL
For Ollama, vLLM, NIM, and compatible-endpoint inference validation, the default timeout is 180 seconds.
The managed NIM startup health wait uses a separate 15-minute (900-second) default and still exits early if the container stops before it becomes healthy.
+On Docker 29.x or hosts using the containerd image store, managed NIM onboarding resolves and pulls the host-platform image digest when NGC exposes a multi-architecture image index.
+If you still see NGC repository-format or attestation errors, confirm Docker can run `docker manifest inspect` for the selected image and that you are logged in to `nvcr.io`.
If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` before re-running onboard:
```bash
@@ -668,6 +670,7 @@ nemoclaw onboard
```
For local Ollama and vLLM, onboarding retries the container reachability check and can fall back to the host-side health check when the local backend is healthy.
+If Ollama times out during a cold model load, NemoClaw retries once with a 300-second probe budget before failing.
If all attempts fail, the error includes container reachability diagnostics such as HTTP status and host gateway resolution.
`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only covers the inference-server validation probe.
@@ -837,7 +840,37 @@ Do not treat a failed `doctor --fix` run as proof that the Discord gateway path
If `openclaw doctor` reports that it moved Telegram single-account values under `channels.telegram.accounts.default`, rerun onboarding and rebuild the sandbox rather than trying to patch `openclaw.json` in place.
Current NemoClaw rebuilds bake Telegram in the account-based layout and set Telegram group chats to `groupPolicy: open`, which avoids the empty `groupAllowFrom` warning path for default group-chat access.
-### Discord bot logs in, but the channel still does not work
+### `openclaw doctor --fix` tightened config permissions and the gateway can no longer save config
+
+In a mutable NemoClaw sandbox, the gateway UID and the sandbox UID share the `sandbox` group, so `/sandbox/.openclaw` is setgid and group-writable (`2770`) and `openclaw.json` is group-writable (`660`).
+OpenClaw's `openclaw doctor --fix` enforces its own single-user `700/600` layout, so running it inside the sandbox strips group write and breaks gateway-side config writes (for example, control-UI toggles that mutate `openclaw.json`).
+
+Repair the mutable contract without rebuilding:
+
+```bash
+nemoclaw doctor --fix
+```
+
+`nemoclaw doctor` reports the drift as a `Config permissions` warning, and `--fix` restores `2770/660`.
+Restarting the sandbox repairs the same drift automatically, and NemoClaw's own `rebuild` re-applies the contract after its post-upgrade `openclaw doctor --fix` step.
+
+When verifying gateway write access by hand, step down to the gateway UID with the image's installed mechanism so the `sandbox` group membership is initialized:
+
+```bash
+setpriv --reuid=gateway --regid=gateway --init-groups -- sh -c 'echo ok >> /sandbox/.openclaw/openclaw.json'
+# or, where setpriv is unavailable:
+gosu gateway sh -c 'echo ok >> /sandbox/.openclaw/openclaw.json'
+```
+
+Do not probe with `su -s /bin/sh gateway ...`: `su` does not initialize the gateway's supplementary groups the same way, so a group-write probe can spuriously report `EACCES` even when the mutable contract is intact.
+
+A NemoClaw sandbox has two intentional permission states for `/sandbox/.openclaw`; `700/600` is not one of them:
+
+- **Mutable default:** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist.
+- **Host-locked state:** `openclaw.json` is read-only for in-sandbox writers and the config dir is owned by `root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev).
+- **`700/600` (drift):** the layout that upstream `openclaw doctor --fix` imposes inside a mutable sandbox. It is not a supported NemoClaw state; recover with `nemoclaw doctor --fix` or a sandbox restart.
+
+## Discord bot logs in, but the channel still does not work
Separate the problem into two parts:
@@ -980,8 +1013,9 @@ nemoclaw onboard
These are build-time settings baked into the sandbox image.
Changing them after onboarding requires re-running `nemoclaw onboard` to rebuild the image.
-When `HTTP_PROXY` or `HTTPS_PROXY` is set on the host, NemoClaw adds `localhost` and `127.0.0.1` to `NO_PROXY` for managed subprocesses.
-This keeps local Ollama health checks and model pulls from being routed through a corporate or desktop proxy while preserving the proxy for external hosts.
+When `HTTP_PROXY` or `HTTPS_PROXY` is set on the host, NemoClaw adds `localhost`, `127.0.0.1`, `::1`, `0.0.0.0`, the container-host aliases `host.docker.internal` and `host.containers.internal`, and the managed inference hostname `inference.local` to `NO_PROXY` for host-side subprocesses and for the env forwarded into `openshell sandbox create`.
+This keeps local Ollama health checks, model pulls, and managed inference traffic from being chained through a corporate or desktop proxy at the sandbox-create boundary, while preserving the proxy for external hosts.
+Inside the running sandbox, processes continue to use the OpenShell L7 proxy for `inference.local` so OpenShell's internal routing, DNS, and audit boundaries stay intact.
### Agent cannot reach a host-side HTTP service
@@ -996,8 +1030,13 @@ Bypassing the proxy with `--noproxy '*'` also bypasses network policy enforcemen
First, make sure the host-side service listens on a non-loopback address.
For example, a health endpoint on port `50001` should be reachable from the host IP, not only from `127.0.0.1`:
-```console
-$ curl -s http://10.0.0.5:50001/health
+```bash
+curl -s http://10.0.0.5:50001/health
+```
+
+Expected output:
+
+```json
{"status":"ok"}
```
@@ -1030,8 +1069,13 @@ nemoclaw my-assistant policy-add --from-file ./host-memory-api.yaml
After you apply the policy, retry the request from inside the sandbox without disabling the proxy:
-```console
-$ curl -s http://10.0.0.5:50001/health
+```bash
+curl -s http://10.0.0.5:50001/health
+```
+
+Expected output:
+
+```json
{"status":"ok"}
```
@@ -1121,10 +1165,23 @@ OpenShell runs sandboxes inside a k3s network, where `host.docker.internal` is n
Depending on the platform, it may fail DNS resolution or resolve to an internal gateway/bridge address where the host's port `11434` is not forwarded.
The sandbox then sees a DNS failure or `connection refused`:
-```console
-$ getent hosts host.docker.internal
+```bash
+getent hosts host.docker.internal
+```
+
+Expected output:
+
+```text
172.17.0.1 host.docker.internal host.openshell.internal
-$ no_proxy=host.docker.internal curl -v http://host.docker.internal:11434/api/tags
+```
+
+```bash
+no_proxy=host.docker.internal curl -v http://host.docker.internal:11434/api/tags
+```
+
+Expected output:
+
+```text
* connect to 172.17.0.1 port 11434 failed: Connection refused
```
@@ -1251,6 +1308,9 @@ If onboarding reports `OpenShell supervisor did not reconnect to the GPU-enabled
The reconnect wait debounces consecutive Error-phase polls before fast-failing, defaulting to fifteen consecutive polls of about 30 seconds in total.
Increase the debounce window with `NEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_ERROR_DEBOUNCE` if your host needs more time to re-register the patched container, for example slow WSL2 + Docker Desktop setups.
Set it to a higher integer such as `30` (about 60 seconds) and rerun onboarding; the value is clamped to a minimum of `1`.
+If reconnect still fails after the GPU patch, NemoClaw attempts to restore the pre-patch CPU container before exiting.
+When rollback succeeds, the output says the pre-patch sandbox was restored.
+When rollback fails, the error says rollback failed and the pre-patch container was not restored, so inspect Docker state before retrying.
### `pip install` fails with a system-packages error
@@ -1319,6 +1379,8 @@ If the process exists but the endpoint is unreachable, use the restart action wh
Ollama configures context length based on your hardware.
On some GPUs (for example RTX 3500), the default context length is not sufficient for OpenClaw.
+During onboarding, NemoClaw raises loaded-model context lengths below `16384` to `16384` when `NEMOCLAW_CONTEXT_WINDOW` is unset.
+Set the variable manually when you need a different value or when you run Ollama outside the managed onboarding path.
Force a larger context length:
```bash
@@ -1456,8 +1518,13 @@ A browser visit to `http://127.0.0.1:8642/` (or any non-API path) returns nothin
Confirm the agent is healthy with the API health endpoint instead:
-```console
-$ curl -sf http://127.0.0.1:8642/health
+```bash
+curl -sf http://127.0.0.1:8642/health
+```
+
+Expected output:
+
+```json
{"status":"ok","platform":"hermes-agent"}
```
@@ -1478,9 +1545,9 @@ Side-by-side agents are supported, but each sandbox name has one agent type.
Pick a distinct sandbox name (the Hermes default is `hermes`; a common pattern is `my-hermes`) so Hermes and OpenClaw sandboxes can coexist on the same host.
To convert an existing sandbox to Hermes instead, destroy and re-onboard:
-```console
-$ nemoclaw destroy
-$ NEMOCLAW_AGENT=hermes nemohermes onboard
+```bash
+nemoclaw destroy
+NEMOCLAW_AGENT=hermes nemohermes onboard
```
### `nemohermes: command not found` immediately after install
@@ -1490,16 +1557,16 @@ The installer drops the shim in the same directory as `nemoclaw`; if `nemoclaw`
Verify the install:
-```console
-$ command -v nemoclaw
-$ command -v nemohermes
+```bash
+command -v nemoclaw
+command -v nemohermes
```
If only `nemoclaw` resolves, re-run the installer with `NEMOCLAW_AGENT=hermes` set so the shim is published:
-```console
-$ export NEMOCLAW_AGENT=hermes
-$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
+```bash
+export NEMOCLAW_AGENT=hermes
+curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```
Equivalently, every `nemohermes ` invocation is `NEMOCLAW_AGENT=hermes nemoclaw `.
@@ -1511,15 +1578,15 @@ Pick OAuth when you have a Nous Portal account and an interactive terminal; pick
Set the method explicitly so the wizard skips the prompt:
-```console
-$ # OAuth (default; interactive)
-$ export NEMOCLAW_HERMES_AUTH_METHOD=oauth
-$ nemohermes onboard
+```bash
+# OAuth (default; interactive)
+export NEMOCLAW_HERMES_AUTH_METHOD=oauth
+nemohermes onboard
-$ # API key (non-interactive)
-$ export NEMOCLAW_HERMES_AUTH_METHOD=api-key
-$ export NOUS_API_KEY=nous_...
-$ nemohermes onboard --non-interactive
+# API key (non-interactive)
+export NEMOCLAW_HERMES_AUTH_METHOD=api-key
+export NOUS_API_KEY=nous_...
+nemohermes onboard --non-interactive
```
`NEMOCLAW_HERMES_AUTH_METHOD` accepts `oauth`, `nous-portal-oauth`, `api-key`, and `nous-api-key`.
@@ -1528,7 +1595,7 @@ The `NEMOCLAW_HERMES_AUTH` and `NEMOCLAW_NOUS_AUTH_METHOD` variables are back-co
If OAuth is selected and onboarding cannot open the host's default browser (a headless host or SSH session), the device-code prompt still prints the verification URL and user code to the terminal.
Copy them to a browser on any other machine to complete the flow.
-### API client returns `401 Unauthorized` against port 8642
+## API client returns `401 Unauthorized` against port 8642
Hermes uses bearer-token header authentication for client requests, not an OpenClaw-style URL fragment.
A request without an `Authorization: Bearer ` header (or with an OpenClaw `#token=` fragment appended to the URL) is rejected with `401`.
@@ -1536,8 +1603,8 @@ A request without an `Authorization: Bearer ` header (or with an OpenClaw
Configure your OpenAI-compatible client to pass the Hermes API key in the `Authorization` header.
Stored credentials (including `NOUS_API_KEY` and `OPENAI_API_KEY`) are listed by:
-```console
-$ nemohermes credentials list
+```bash
+nemohermes credentials list
```
Reset a specific provider's credentials with `nemohermes credentials reset ` and re-onboard if the stored value is wrong.
@@ -1554,9 +1621,9 @@ Configure Hermes web search from the agent's own configuration inside the sandbo
This is tracked in [#3581](https://github.com/NVIDIA/NemoClaw/issues/3581).
For unattended re-onboards, export the messaging env vars first so the wizard skips the prompts:
-```console
-$ export TELEGRAM_BOT_TOKEN=...
-$ export DISCORD_BOT_TOKEN=...
-$ export SLACK_BOT_TOKEN=...
-$ nemohermes onboard --resume --non-interactive
+```bash
+export TELEGRAM_BOT_TOKEN=...
+export DISCORD_BOT_TOKEN=...
+export SLACK_BOT_TOKEN=...
+nemohermes onboard --resume --non-interactive
```