NVIDIA · latenighthackathon · May 28, 2026
diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md
@@ -700,7 +700,12 @@ Channels fall into three login modes:
 After registering the channel, NemoClaw asks whether to rebuild immediately.
 Running `add` for an already-configured channel simply overwrites the stored credentials where applicable — the operation is idempotent.
 Channel names are trimmed and lowercased before NemoClaw stores credentials, names bridge providers, or prints rebuild messages.
-If a matching built-in network policy preset exists, NemoClaw applies it to the sandbox before the rebuild so the bridge has egress to its upstream API; if applying the preset fails, NemoClaw warns and tells you to re-apply manually with `nemoclaw <name> policy-add <channel>`.
+NemoClaw requires the matching built-in network policy preset YAML to be present.
+A missing or malformed preset YAML (no `network_policies:` section) aborts `channels add` before any token prompt, registry write, or rebuild prompt.
+With the preset file in place, NemoClaw applies it to the sandbox before the rebuild so the bridge has egress to its upstream API.
+When the apply step itself fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the `messagingChannels` entry, and any staged environment credentials, then exits without prompting for a rebuild; if any gateway-side step (provider detach or delete) fails the rollback continues and prints a `Rollback could not fully clean <surfaces>` warning so the operator can clean up manually.
+When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers, but flags `gateway-providers` as residual because the in-flight upsert may have left the gateway with the new token; verify the gateway bridge before relying on the channel.
+Restore the preset YAML and re-run `nemoclaw <name> channels add <channel>`.
 For Telegram, Discord, and Slack, a rebuild triggered by `channels add` also verifies that the selected bridge starts and reports credential, startup, or plugin discovery warnings.
 
 ```console
@@ -709,7 +714,7 @@ $ nemoclaw my-assistant channels add telegram
 
 | Flag | Description |
 |------|-------------|
-| `--dry-run` | Validate the channel and token inputs without saving credentials or rebuilding |
+| `--dry-run` | Validate the channel name and matching policy preset without prompting for credentials, contacting the gateway, or rebuilding |
 
 Slack requires both `SLACK_BOT_TOKEN` (bot user OAuth) and `SLACK_APP_TOKEN` (app-level Socket Mode token); the command prompts for each in turn.
 Optional Slack allowlists come from `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` at rebuild time.
@@ -1292,6 +1297,27 @@ NemoClaw reads the following environment variables to configure service ports, o
 Set them before running `nemoclaw onboard` or any command that starts services.
 All ports must be non-privileged integers between 1024 and 65535.
 
+### At a Glance
+
+Every documented `NEMOCLAW_*` environment variable, grouped by category.
+Use this table to find the appropriate variable; see the subsection below for default, format, and effect.
+
+| Category | Variables |
+|----------|-----------|
+| [Service Ports](#service-ports) | `NEMOCLAW_GATEWAY_PORT`, `NEMOCLAW_GATEWAY_BIND_ADDRESS`, `NEMOCLAW_DASHBOARD_PORT`, `NEMOCLAW_DASHBOARD_BIND`, `NEMOCLAW_VLLM_PORT`, `NEMOCLAW_OLLAMA_PORT`, `NEMOCLAW_OLLAMA_PROXY_PORT`, `NEMOCLAW_HERMES_DASHBOARD`, `NEMOCLAW_HERMES_DASHBOARD_PORT`, `NEMOCLAW_HERMES_DASHBOARD_TUI` |
+| [Onboarding Configuration](#onboarding-configuration) | `NEMOCLAW_PROVIDER`, `NEMOCLAW_HERMES_AUTH_METHOD`, `NEMOCLAW_HERMES_AUTH`, `NEMOCLAW_NOUS_AUTH_METHOD`, `NEMOCLAW_ENDPOINT_URL`, `NEMOCLAW_PREFERRED_API`, `NEMOCLAW_INFERENCE_INPUTS`, `NEMOCLAW_AGENT_TIMEOUT`, `NEMOCLAW_CONTEXT_WINDOW`, `NEMOCLAW_MAX_TOKENS`, `NEMOCLAW_REASONING`, `NEMOCLAW_AGENT_HEARTBEAT_EVERY`, `NEMOCLAW_OLLAMA_REQUIRE_TOOLS`, `NEMOCLAW_OLLAMA_INSTALL_MODE`, `NEMOCLAW_PROXY_HOST`, `NEMOCLAW_PROXY_PORT`, `NEMOCLAW_OPENSHELL_BIN`, `NEMOCLAW_SANDBOX`, `NEMOCLAW_INSTALL_REF`, `NEMOCLAW_INSTALL_TAG`, `NEMOCLAW_VLLM_MODEL`, `NEMOCLAW_MODEL_ROUTER_PYTHON`, `NEMOCLAW_HERMES_TOOL_GATEWAYS`, `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS`, `NEMOCLAW_DEFER_OPENSHELL_INSTALL`, `AWS_BEARER_TOKEN_BEDROCK`, `COMPATIBLE_ANTHROPIC_API_KEY` |
+| [Onboarding Behavior Flags](#onboarding-behavior-flags) | `NEMOCLAW_YES`, `NEMOCLAW_NON_INTERACTIVE_SUDO_MODE`, `NEMOCLAW_NO_EXPRESS`, `NEMOCLAW_EXPERIMENTAL`, `NEMOCLAW_IGNORE_RUNTIME_RESOURCES`, `NEMOCLAW_DISABLE_OVERLAY_FIX`, `NEMOCLAW_OVERLAY_SNAPSHOTTER`, `NEMOCLAW_SKIP_TELEGRAM_REACHABILITY`, `NEMOCLAW_CONFIG_ACCEPT_NEW_PATH`, `NEMOCLAW_SANDBOX_GPU`, `NEMOCLAW_SANDBOX_GPU_DEVICE`, `NEMOCLAW_DOCKER_GPU_PATCH`, `NEMOCLAW_OPENSHELL_GATEWAY_BIN`, `NEMOCLAW_OPENSHELL_SANDBOX_BIN`, `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR`, `NEMOCLAW_DISABLE_VM_DNS_MONKEYPATCH`, `NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH`, `NEMOCLAW_DARWIN_VM_COMPAT`, `NEMOCLAW_DOCKER_GPU_PATCH_NETWORK`, `NEMOCLAW_WECHAT_QUIET`, `NEMOCLAW_OLLAMA_NO_AUTOSTART`, `NEMOCLAW_RESOURCE_PROFILE`, `NEMOCLAW_CPU`, `NEMOCLAW_RAM` |
+| [Probe Timeouts](#probe-timeouts) | `NEMOCLAW_SANDBOX_EXEC_TIMEOUT_MS`, `NEMOCLAW_STATUS_PROBE_TIMEOUT_MS` |
+| [Onboard Timeouts](#onboard-timeouts) | `NEMOCLAW_OLLAMA_PULL_TIMEOUT`, `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT`, `NEMOCLAW_SANDBOX_READY_TIMEOUT` |
+| [Gateway Lifecycle Tunables](#gateway-lifecycle-tunables) | `NEMOCLAW_GATEWAY_START_TIMEOUT`, `NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS`, `NEMOCLAW_GATEWAY_RECOVERY_POLL_INTERVAL_SECONDS`, `NEMOCLAW_HEALTH_POLL_COUNT`, `NEMOCLAW_HEALTH_POLL_INTERVAL`, `NEMOCLAW_LOGS_PROBE_TIMEOUT_MS`, `NEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_TIMEOUT` |
+| [Sandbox Runtime](#sandbox-runtime) | `NEMOCLAW_TOOL_CATALOG`, `NEMOCLAW_OPENCLAW_MANAGED_PROXY`, `NEMOCLAW_SANDBOX_BASE_VERSION_TAG`, `NEMOCLAW_HERMES_TOOL_GATEWAY_REFRESH_TOKEN` |
+| [Lifecycle Behavior Flags](#lifecycle-behavior-flags) | `NEMOCLAW_CLEANUP_GATEWAY`, `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR`, `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` |
+| [Onboard Profiling Traces](#onboard-profiling-traces) | `NEMOCLAW_TRACE`, `NEMOCLAW_TRACE_DIR`, `NEMOCLAW_TRACE_FILE` |
+
+### Service Ports
+
+These variables override the TCP ports NemoClaw uses for its core services. Each value must be a non-privileged integer between 1024 and 65535.
+
 | Variable | Default | Service |
 |----------|---------|---------|
 | `NEMOCLAW_GATEWAY_PORT` | 8080 | OpenShell gateway port |
@@ -1346,7 +1372,7 @@ Set them before running `nemoclaw onboard`.
 | `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_ENDPOINT_URL` | URL | Custom OpenAI-compatible endpoint URL. Used together with `NEMOCLAW_PROVIDER=compatible`. |
+| `NEMOCLAW_ENDPOINT_URL` | URL | Custom endpoint URL. Used together with `NEMOCLAW_PROVIDER=custom` for OpenAI-compatible endpoints or `NEMOCLAW_PROVIDER=anthropicCompatible` for Anthropic-compatible endpoints. |
 | `NEMOCLAW_PREFERRED_API` | `completions` (currently the only honored value) | Forces the validation probe to use the `/v1/chat/completions` API path instead of the newer `/v1/responses` API. |
 | `NEMOCLAW_INFERENCE_INPUTS` | comma-separated list of `text` and/or `image` | Declares model input modalities for vision-capable models. Validated strictly; unknown tokens are ignored. |
 | `NEMOCLAW_AGENT_TIMEOUT` | positive integer (seconds) | Overrides `agents.defaults.timeoutSeconds` in the built OpenClaw config. Raise for slow inference. |
@@ -1362,7 +1388,7 @@ Set them before running `nemoclaw onboard`.
 | `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_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`, `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-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_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). |
 
 #### Linux Ollama install mode details
@@ -1404,6 +1430,10 @@ These flags toggle optional behaviors during onboarding; set them before running
 | `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_DISABLE_VM_DNS_MONKEYPATCH` | `1` to enable | Skips the macOS VM-driver DNS monkeypatch that rewrites in-sandbox `host.docker.internal` lookups to the host bridge. Use only when troubleshooting DNS interactions on macOS. |
+| `NEMOCLAW_FORCE_VM_DNS_MONKEYPATCH` | `1` to enable | Forces the macOS VM-driver DNS monkeypatch on non-Darwin platforms. Linux defaults already route through the Docker bridge; use this override only to reproduce the macOS DNS path on a non-Darwin host. |
+| `NEMOCLAW_DARWIN_VM_COMPAT` | `0` or `1` (build-time `ARG`) | macOS VM-driver compatibility flag baked into the sandbox Dockerfile by `nemoclaw onboard` based on platform detection. Override only when rebuilding a sandbox image with a custom Dockerfile. |
+| `NEMOCLAW_DOCKER_GPU_PATCH_NETWORK` | `host` or `preserve` (default) | Selects the Docker network mode used by the Linux Docker-driver GPU sandbox patch. `host` clones the gateway's host-networking endpoint for the patched container; `preserve` (default) keeps the original network mode. Set `host` only when the GPU patch needs the gateway endpoint exposed on the loopback path. |
 | `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. |
 
 ### Onboard Profiling Traces
@@ -1452,6 +1482,38 @@ If a timeout fires, onboarding emits the elapsed budget plus a hint to raise the
 The Ollama pull preserves its partial download for the next attempt.
 The readiness wait deletes the orphaned sandbox first so the next `nemoclaw onboard` starts clean.
 
+### Gateway Lifecycle Tunables
+
+These variables tune the polling and timeout budgets used by gateway-recovery and health-check paths.
+The default values target typical local development; raise them on slow links, large image pulls, or remote-deployed hosts where round-trip latency to the gateway is high.
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `NEMOCLAW_GATEWAY_START_TIMEOUT` | `600` (seconds) | Wall-clock timeout for OpenShell gateway start during onboarding. Multiplied by 1000 internally to drive the underlying spawn timeout. Raise when the gateway start path spans large image pulls or slow first-time setup. |
+| `NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS` | `30` | Total wait budget for `nemoclaw <name> connect` recovery to confirm the gateway is back up after a respawn. Raise when the gateway's first-paint latency is bounded by network or disk rather than CPU. |
+| `NEMOCLAW_GATEWAY_RECOVERY_POLL_INTERVAL_SECONDS` | `3` | Sleep interval between recovery readiness probes. The probe runs `ceil(NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS / NEMOCLAW_GATEWAY_RECOVERY_POLL_INTERVAL_SECONDS)` times. |
+| `NEMOCLAW_HEALTH_POLL_COUNT` | `12` (`30` on arm64; lower per-call-site overrides exist) | Number of health-poll attempts the gateway and sandbox readiness probes perform before giving up. Defaults are tuned per call site; this var overrides the standard path used by `nemoclaw onboard` and `nemoclaw <name> connect`. |
+| `NEMOCLAW_HEALTH_POLL_INTERVAL` | `5` (`10` on arm64; `2` for some lifecycle probes) | Sleep interval between health-poll attempts (seconds). Pairs with `NEMOCLAW_HEALTH_POLL_COUNT` to bound total wait. |
+| `NEMOCLAW_LOGS_PROBE_TIMEOUT_MS` | `5000` | Milliseconds the `nemoclaw <name> logs` probe waits for the sandbox to start emitting log lines before reporting an empty stream. Non-positive or non-numeric values fall back to the default. |
+| `NEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_TIMEOUT` | `900` (seconds) | Maximum wait for the Linux Docker-driver GPU supervisor to reconnect after the GPU sandbox is patched. The value is clamped to a minimum of `1` second; the default is sized for cold GPU device attach on first onboard. |
+
+```console
+$ NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS=60 nemoclaw <name> connect
+$ NEMOCLAW_HEALTH_POLL_COUNT=60 NEMOCLAW_HEALTH_POLL_INTERVAL=5 nemoclaw onboard
+```
+
+### Sandbox Runtime
+
+These variables tune sandbox runtime surfaces.
+None are required for a default install; set them only when you need to override the default behavior.
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `NEMOCLAW_TOOL_CATALOG` | unset (compact catalog enabled) | Set to `0` to disable the build-time OpenClaw tool-catalog compaction added in #3808. The default OpenClaw plugin install monkey-patches the selection runtime to expose three meta-tools (`tool_search`, `tool_describe`, `tool_call`) for Nemotron and other large-tool-set models; setting `NEMOCLAW_TOOL_CATALOG=0` skips the patch and falls back to the full tool list. |
+| `NEMOCLAW_OPENCLAW_MANAGED_PROXY` | `1` (true) | Controls whether the OpenClaw managed-proxy block is emitted into `~/.openclaw/openclaw.json` during sandbox config generation. Falsy values (`0`, `false`, `no`, `off`) defer the proxy block; the build path passes `0` while running `openclaw doctor` and `openclaw plugins install` so those commands do not try to reach a not-yet-running gateway. |
+| `NEMOCLAW_SANDBOX_BASE_VERSION_TAG` | unset (auto-detect from `NEMOCLAW_INSTALL_REF`, `git describe`, or `.version`) | Pin the sandbox base image to a specific version tag. When set, `getVersionedBaseImageTags` tries the pinned tag first before falling back to source-sha or `:latest`. Use this when a base-image re-publish must not change the resolved digest during reproducible rebuilds. |
+| `NEMOCLAW_HERMES_TOOL_GATEWAY_REFRESH_TOKEN` | unset | Nous OAuth refresh token for the host-side Hermes managed-tool gateway broker (port 11436). Stays on the host only; the sandbox sees an opaque `nc_broker_<base64url>` token instead. Set this once during onboard to enable the `nous-*` policy presets without re-prompting. |
+
 ### Lifecycle Behavior Flags
 
 These flags change defaults for commands that manage existing sandboxes.