diff --git a/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md index e4377a7f4b..495b1250f9 100644 --- a/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md +++ b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md @@ -181,6 +181,10 @@ If the user invoked this skill for release prep, finish the release-specific doc python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx ``` + Do not include the root `skills/` directory as an output target. That + directory is refreshed by a separate process and must not be updated by this + skill. + ## Step 9: Build and Verify After making changes, build the docs locally: @@ -226,7 +230,7 @@ User says: "Catch up the docs for everything merged since v0.1.0." 4. Read the commit diffs and current doc pages. 5. Draft doc updates reflecting the source code changes in the commits following the style guide. 6. **Release prep only:** Determine the release label from the user-requested release version. -7. **Release prep only:** Run `python3 scripts/docs-to-skills.py docs/ .agents/skills/ skills/ --prefix nemoclaw-user --doc-platform fern-mdx`. +7. **Release prep only:** Run `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx`. Do not update root `skills/`. 8. Present the summary. 9. Build with `npm run docs` to verify. 10. **Release prep only:** Commit changes and open a pull request with the `area: docs`, `area: skills`, and corresponding `vX.Y.Z` release labels. Include a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape: diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index a097a63abc..500792a4cf 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -175,6 +175,12 @@ NEMOCLAW_PROVIDER=ollama \ 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. diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md index 8ca68d7d14..8af6e446af 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -297,6 +297,7 @@ When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that v 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. @@ -307,7 +308,7 @@ Managed vLLM uses these profiles: | Host profile | Default model | |---|---| | DGX Spark | `nvidia/Qwen3.6-35B-A3B-NVFP4` | -| DGX Station | `Qwen/Qwen3.6-27B-FP8` | +| DGX Station | `deepseek-ai/DeepSeek-V4-Flash` | | Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | **Note:** @@ -344,7 +345,8 @@ Recognized slugs are: | Slug | Hugging Face model | Notes | |---|---|---| -| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Default on the DGX Station profile | +| `deepseek-v4-flash` | `deepseek-ai/DeepSeek-V4-Flash` | Default on the DGX Station profile | +| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Supported override | | `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-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance | @@ -377,6 +379,9 @@ 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. @@ -384,6 +389,8 @@ The prompt masks the key during input and retries one time on a bad key before f 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:** diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md b/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md index 92089e996c..0a7a9b6d55 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md @@ -20,7 +20,7 @@ For OpenClaw, it updates `agents.defaults.model.primary` and the matching provid 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`, and `model.provider: custom`) without rebuilding or restarting Hermes. +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. @@ -77,6 +77,16 @@ 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, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image. @@ -148,6 +158,8 @@ 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. +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 diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md b/.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md index d415ce4dda..5c13623091 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md @@ -38,6 +38,12 @@ The common failure mode is: 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**. diff --git a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md index 7893b472e4..d3cfa873a7 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -425,10 +425,10 @@ The auto-pair watcher automatically approves device pairing requests from recogn | Aspect | Detail | |---|---| -| Default | The watcher approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat`. All other clients are rejected and logged. | -| What you can change | This is not a user-facing knob. The allowlist is defined in the entrypoint script. | +| Default | Startup auto-pairing and `connect`-time approval share one policy. NemoClaw approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat` or `cli`, and only for `operator.pairing`, `operator.read`, and `operator.write` scopes. All other clients or scopes are rejected and logged. | +| What you can change | This is not a user-facing knob. The allowlist is defined by NemoClaw's OpenClaw device-approval helper. | | Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. | -| Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | +| Recommendation | No action needed. NemoClaw handles this automatically at startup and during `connect` for late scope upgrades. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | @@ -436,6 +436,8 @@ The auto-pair watcher automatically approves device pairing requests from recogn Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard. Do not publish those endpoints on shared or public networks unless you put them behind your own access controls. NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`. +Generated Hermes runtime files use OpenShell resolver placeholders for managed-tool and messaging credentials. +Hermes startup rejects raw secret-shaped values in sandbox-visible environment or config fields, while allowing empty values, migration sentinels, OpenShell resolver placeholders, and expected Slack placeholder forms. @@ -460,7 +462,7 @@ The scanner intercepts Write, Edit, and similar tool calls targeting memory and | Aspect | Detail | |---|---| | Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. | -| What it covers | Three classifiers, all enforced through `isMemoryPath()`: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | +| What it covers | Three path classifiers, all enforced through `isMemoryPath()`, plus credential-shaped text such as provider API keys, OpenAI project keys with `sk-proj-` prefixes, and Slack app-level `xapp-` tokens. The path classifiers are: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | | What you can change | This is not a user-facing knob. The plugin enforces it automatically. | | Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. | | Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. | diff --git a/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md index cdecf97052..26dc213e61 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md @@ -13,6 +13,9 @@ The sandbox-side OpenClaw gateway token is generated at container startup and is Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. +Those files should contain resolver placeholders, not live provider credentials. +For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into `/sandbox/.hermes/config.yaml`, `/sandbox/.hermes/.env`, and process environment entries visible to the sandbox. +Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces. ## Where Credentials Live diff --git a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md index cb0a62547b..9885238e64 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md @@ -1,6 +1,6 @@ --- name: "nemoclaw-user-deploy-remote" -description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits." +description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw dockerignore, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits." license: "Apache-2.0" --- @@ -145,7 +145,7 @@ nemoclaw deploy ## References -- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox. +- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox, including `.dockerignore` handling for custom build contexts. - **Load [references/brev-web-ui.md](references/brev-web-ui.md)** when a user wants to try NemoClaw without installing the CLI, or asks how to get started on Brev. Guides users through deploying NemoClaw with the Brev web UI. - **Load [references/sandbox-hardening.md](references/sandbox-hardening.md)** when reviewing sandbox image security controls, auditing capability drops, or looking up the runtime resource limits. Includes the sandbox container image hardening reference, covering Docker capabilities and process limits. diff --git a/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md b/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md index 4094f9a924..6f8e721920 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md @@ -13,6 +13,8 @@ The supported NemoClaw path for OpenClaw plugins is to bake the plugin into a cu Put the Dockerfile and everything it needs to `COPY` in one directory. `nemoclaw onboard --from ` uses the Dockerfile's parent directory as the Docker build context. +Add a `.dockerignore` next to the Dockerfile to exclude local caches, generated artifacts, model files, or other paths that are not needed by the image build. +NemoClaw still applies its own secret-safety exclusions for credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` negates them. ```text my-plugin-sandbox/ @@ -67,6 +69,7 @@ These are the most common places where plugin installation gets mixed up with ot - Do not use `nemoclaw skill install` for OpenClaw plugins. That command only installs `SKILL.md` agent skills. - Do not put a Dockerfile in a broad directory such as `/tmp` unless you intend to send that whole directory as the Docker build context. +- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. - Keep plugin dependencies in the build stage or plugin directory; avoid copying unrelated host files into the sandbox image. diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md index 0cc6f4005b..3056b491cd 100644 --- a/.agents/skills/nemoclaw-user-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -70,7 +70,7 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice. Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform. -Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, and local-inference presets. +Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets. On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set. On WSL, express install selects the Windows-host Ollama setup path. Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself. @@ -182,7 +182,7 @@ Review Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) befor After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. Web search and messaging selections happen before this point so the sandbox image and the policy suggestions stay aligned. -The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. +The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, read-only weather lookups, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference. @@ -260,7 +260,7 @@ openclaw tui ## References -- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes API endpoint. +- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes dashboard and API endpoint. - **Load [references/prerequisites.md](references/prerequisites.md)** when verifying prerequisites before installation. Lists the hardware, software, and container runtime requirements for running NemoClaw. - **Load [references/windows-preparation.md](references/windows-preparation.md)** when preparing a Windows machine for NemoClaw, enabling WSL 2, configuring Docker Desktop for Windows, or troubleshooting a Windows-specific install error. Covers Windows-only preparation steps required before the Quickstart. diff --git a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md index d0b15db496..b475cdf1eb 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -20,18 +20,19 @@ export NEMOCLAW_AGENT=hermes curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -If a headless host needs to expose the Hermes API through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding. -Use the externally reachable origin for port `8642`, without the `/v1` path. -NemoClaw derives the forwarded port from this value, binds the forward for remote access when the origin is non-loopback, and prints the final OpenAI-compatible base URL with `/v1` in the ready summary. +If a headless host needs to expose the Hermes dashboard through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding. +Use the externally reachable origin for the dashboard port `18789`. +NemoClaw derives the forwarded dashboard port from this value, binds the forward for remote access when the origin is non-loopback, and prints the final dashboard URL in the ready summary. +The OpenAI-compatible API remains available separately on port `8642`. ```bash export NEMOCLAW_AGENT=hermes -export CHAT_UI_URL="https://hermes.example.com:8642" +export CHAT_UI_URL="https://hermes.example.com:18789" curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -For SSH local port forwarding to `127.0.0.1:8642`, leave `CHAT_UI_URL` unset. -Do not append an OpenClaw `#token=` fragment to the Hermes URL. +For SSH local port forwarding to `127.0.0.1:18789`, leave `CHAT_UI_URL` unset. +Do not append an OpenClaw `#token=` fragment to the Hermes dashboard URL. Hermes API clients authenticate with the bearer token from the generated Hermes environment instead of an OpenClaw dashboard URL token. If NemoClaw is already installed, start Hermes onboarding directly. @@ -58,6 +59,9 @@ Choose the inference provider that matches where you want Hermes model traffic t The provider options and credential environment variables are the same as the standard NemoClaw quickstart. For provider-specific prompts, refer to the Inference Options (use the `nemoclaw-user-configure-inference` skill) page. The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration. +If you authenticate Hermes through Nous Portal OAuth, the wizard can also prompt for managed Nous tool gateways such as web search, image generation, audio, browser automation, or managed code execution. +Those choices add the matching Hermes policy presets to the sandbox. +API-key mode is inference-only and does not enable managed tool gateways. After provider and model selection, review the summary and confirm the build. NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traffic through `inference.local`, and starts the Hermes gateway inside the sandbox. @@ -86,19 +90,13 @@ Use the provider variables from Inference Options (use the `nemoclaw-user-config ## Connect to Hermes -When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, and Hermes API endpoint. -Hermes exposes an OpenAI-compatible API on port `8642`, not a browser dashboard. -To also launch the native Hermes web dashboard, opt in before onboarding: - -```bash -export NEMOCLAW_HERMES_DASHBOARD=1 -nemohermes onboard -``` - -The dashboard uses port `9119` by default. -Set `NEMOCLAW_HERMES_DASHBOARD_PORT` before onboarding to choose a different port. -Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` to enable Hermes' optional in-browser TUI tab. -For upstream dashboard features, refer to the [Hermes web dashboard documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard). +When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, and Hermes dashboard URL. +Hermes exposes its built-in browser dashboard on port `18789`. +NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients. +NemoClaw builds the Hermes dashboard assets into the sandbox image, so the dashboard starts without running `npm` as the sandbox user under `/opt/hermes`. +Dashboard chat uses the prebuilt `/opt/hermes/ui-tui` bundle. +If you need to recover the Hermes dashboard manually, use `hermes dashboard --tui --skip-build` so recovery does not try to rebuild assets under root-owned install paths. +Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab. ```text ────────────────────────────────────────────────── @@ -109,13 +107,9 @@ Model: nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints) Access - Hermes Agent OpenAI-compatible API - Port 8642 must be forwarded before connecting. - http://127.0.0.1:8642/v1 - - Hermes Agent Web dashboard - Port 9119 must be forwarded before opening this URL. - http://127.0.0.1:9119/ + Hermes Agent Dashboard + Port 18789 must be forwarded before opening this URL. + http://127.0.0.1:18789/ Terminal: nemohermes my-hermes connect @@ -144,9 +138,21 @@ To chat with the agent from a terminal, follow these steps: hermes ``` +## Open the Dashboard + +The onboard flow starts the dashboard port forward automatically. +Open the dashboard from the host: + +```console +$ nemohermes my-hermes dashboard-url --quiet +http://127.0.0.1:18789/ +``` + +Hermes handles dashboard sessions itself, so this URL does not include an OpenClaw `#token=` fragment. + ## Check the API Endpoint -The onboard flow starts the port forward automatically. +The onboard flow also starts the API port forward automatically. Check the health endpoint from the host to confirm that the Hermes API is reachable. ```bash @@ -163,17 +169,6 @@ Configure an OpenAI-compatible client with the base URL `http://127.0.0.1:8642/v Hermes uses API header authentication for client requests. Do not append an OpenClaw `#token=` URL fragment to the Hermes endpoint. -## Open the Optional Dashboard - -When you set `NEMOCLAW_HERMES_DASHBOARD=1` during onboarding, NemoClaw starts `hermes dashboard --no-open` inside the sandbox and forwards `http://127.0.0.1:9119/` on the host. -The API endpoint remains separate on `8642`. - -If the dashboard forward is missing after a reboot or terminal restart, start it again: - -```bash -openshell forward start --background 9119 my-hermes -``` - Treat the dashboard as a local management UI. Avoid exposing it on shared or public networks unless you put it behind your own access controls. diff --git a/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md b/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md index 18d77758ba..f28f5dff5f 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md +++ b/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md @@ -48,9 +48,11 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr | OpenClaw model-pricing reference fetch | `openclaw-pricing` | | npm and Yarn packages | `npm` | | Microsoft 365, Outlook, and Graph API | `outlook` | +| Public reference APIs | `public-reference` | | Python Package Index | `pypi` | | Slack messaging | `slack` | | Telegram Bot API | `telegram` | +| Weather and geocoding APIs | `weather` | | WeChat (personal) iLink Bot API (experimental) | `wechat` | | WhatsApp Web messaging (experimental) | `whatsapp` | @@ -231,6 +233,25 @@ nemoclaw my-assistant policy-add brave --yes The Brave Search API key is still configured separately during onboarding or through the web search setup flow. +## Weather and Public Reference Lookups + +Use the `weather` preset when the agent needs read-only weather or geocoding lookups. +The Balanced and Open tiers include it by default. +The preset covers Open-Meteo, geocoding, and National Weather Service endpoints without enabling messaging or productivity APIs. + +```bash +nemoclaw my-assistant policy-add weather --dry-run +nemoclaw my-assistant policy-add weather --yes +``` + +Use the `public-reference` preset when the agent needs read-only public-reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata. +The Open tier includes this preset by default. + +```bash +nemoclaw my-assistant policy-add public-reference --dry-run +nemoclaw my-assistant policy-add public-reference --yes +``` + ## Package and Model Tooling Use these presets when an agent workflow installs packages or downloads model assets: diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md index 7802405ca6..bc81066f59 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md @@ -1,6 +1,6 @@ --- name: "nemoclaw-user-manage-sandboxes" -description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, install hermes plugins, hermes plugins nemoclaw, nemoclaw hermes plugins, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence." +description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, install hermes plugins, hermes plugins nemoclaw, nemoclaw hermes plugins, nemohermes dockerignore, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence." license: "Apache-2.0" --- @@ -113,6 +113,8 @@ When the default API port is already held by another sandbox, `nemoclaw onboard` If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. +Gateway and dashboard cleanup is scoped by sandbox name and port. +A later onboarding run that uses a different `NEMOCLAW_GATEWAY_PORT` or `--control-ui-port` does not tear down the first sandbox's gateway or dashboard forward. ```bash nemoclaw onboard # first sandbox uses 18789 @@ -276,7 +278,7 @@ For a full comparison of the two forms, including what they fetch, what they tru - **[references/runtime-controls.md](references/runtime-controls.md)** — Single page that answers what can change at runtime versus what requires a rebuild for NemoClaw sandboxes. - **Load [references/backup-restore.md](references/backup-restore.md)** when downloading workspace files from a sandbox, uploading restored files into a new sandbox, or preserving sandbox state across rebuilds. Backs up and restores OpenClaw workspace files before destructive operations such as sandbox rebuilds. - **Load [references/messaging-channels.md](references/messaging-channels.md)** when setting up messaging channels, chat interfaces, or integrations without relying on nemoclaw tunnel start for bridges. Explains how Telegram, Discord, Slack, WeChat, and WhatsApp reach sandboxed OpenClaw and Hermes agents through OpenShell-managed processes and NemoClaw channel commands. -- **[references/install-plugins-hermes.md](references/install-plugins-hermes.md)** — Explains how to install Hermes plugins in NemoClaw-managed sandboxes. +- **Load [references/install-plugins-hermes.md](references/install-plugins-hermes.md)** when users ask how to install, build, or configure Hermes plugins under NemoClaw. Explains how to install Hermes plugins in NemoClaw-managed sandboxes, including custom Dockerfile build-directory layout and `.dockerignore` handling. - **Load [references/workspace-files.md](references/workspace-files.md)** when users ask about `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, or other workspace files, or when preparing to back up or restore workspace state. Explains what workspace personality and configuration files are, where they live, and how they persist across sandbox restarts. ## Related Skills diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md index 31f1903af6..4e3deaab2c 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md @@ -24,6 +24,8 @@ It uploads skill instructions and refreshes skill discovery, but it does not ins Put the custom Dockerfile and everything it needs to `COPY` in one directory. `nemohermes onboard --from ` sends the Dockerfile's parent directory as the Docker build context. +Add a `.dockerignore` next to the Dockerfile to keep local caches, generated artifacts, model files, or other unneeded paths out of the staged context. +NemoClaw still excludes credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` tries to include them. ```text my-hermes-plugin-sandbox/ @@ -105,6 +107,7 @@ These are the most common places where Hermes plugin installation gets mixed up - Do not install Hermes plugins into `/sandbox/.openclaw/extensions`; that path is for OpenClaw plugins. - Do not remove `/sandbox/.hermes/plugins/nemoclaw`; NemoClaw depends on that plugin for managed Hermes behavior. - Do not put the Dockerfile in a broad directory unless you intend to send that whole directory as the Docker build context. +- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. - Do not assume OpenShell policy allows Python package downloads during runtime by default. ## Next Steps diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md index 4e13098c3e..e5e026974b 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md @@ -22,6 +22,7 @@ The table below maps each commonly changed item to the layer that owns it and th | Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`openclaw.json` is the source of truth at runtime, see #3453) | `nemoclaw channels stop ` then rebuild | | Dashboard forward port | Runtime. Port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= nemoclaw connect` | | Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw connect` (see #3259) | +| Default OpenClaw workspace template seed (`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`) | Locked at first sandbox boot. Re-onboard required to change the bake-time choice. | Set `NEMOCLAW_MINIMAL_BOOTSTRAP=1` before `nemoclaw onboard` to skip default template seeding for new/pristine workspaces. **Does not delete files already present.** Partial mitigation for #2598 (cuts ~3k tokens of project-context overhead off OpenClaw's per-turn bootstrap injection). | | Web search backend (Brave, Tavily, and so on) | Runtime through `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `nemoclaw config set --key web.backend --value tavily` | | Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | | Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | diff --git a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md index e21062559f..fd7a9108a5 100644 --- a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md +++ b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md @@ -65,6 +65,7 @@ NemoClaw is split into integration pieces on the host and in the sandbox image: - The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. + Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript. @@ -111,6 +112,7 @@ The sandbox starts with a default policy that controls network egress, filesyste | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. +NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether a failure came from policy denial, DNS, timeout, TLS, or filesystem access. ## Next Steps diff --git a/.agents/skills/nemoclaw-user-overview/references/release-notes.md b/.agents/skills/nemoclaw-user-overview/references/release-notes.md index b41cd6022d..77747019bf 100644 --- a/.agents/skills/nemoclaw-user-overview/references/release-notes.md +++ b/.agents/skills/nemoclaw-user-overview/references/release-notes.md @@ -4,6 +4,16 @@ NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track the highlights of the latest release. For more detailed release notes, refer to the [NemoClaw GitHub announcements](https://github.com/NVIDIA/NemoClaw/discussions/categories/announcements?discussions_q=is%3Aopen+category%3AAnnouncements). +## v0.0.60 + +NemoClaw v0.0.60 improves runtime guidance, sandbox lifecycle reliability, local inference setup, messaging enrollment, and maintainer safeguards: + +- OpenClaw runtime guidance stays active without appearing in the visible chat transcript, and sandbox network and filesystem context now tells agents to try allowed in-sandbox actions before reporting them unavailable. OpenClaw device-approval policy also uses the same allowlist and scope behavior during startup and connect. For more information, refer to Architecture (use the `nemoclaw-user-reference` skill). +- Onboarding and sandbox lifecycle paths preserve more host state. NemoClaw uses the package-managed OpenShell gateway user service when available, scopes gateway and dashboard cleanup by sandbox instance, detects Docker-driver sandboxes without writing the local gateway marker, rolls back failed Docker GPU patches, honors `.dockerignore` for custom `--from ` contexts, and can skip default workspace-template seeding with `NEMOCLAW_MINIMAL_BOOTSTRAP=1`. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Local inference setup is more predictable across NVIDIA NIM, Ollama, vLLM, DGX Spark, DGX Station, Anthropic-compatible routes, and Hermes. NemoClaw pulls NIM images by platform digest, uses stable managed-vLLM images and updated DGX model profiles, tightens Ollama fit checks, synchronizes Anthropic route metadata, preserves Hermes proxy API-key placeholders, and serves the prebuilt Hermes dashboard assets from the sandbox image. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill). +- Messaging and day-two CLI operations share more common plumbing. Messaging enrollment uses manifest hooks across Telegram, Discord, Slack, WeChat, and WhatsApp, `nemoclaw tunnel status` reports Cloudflare tunnel state directly, global `status` and `list` honor sandbox environment overrides consistently, and installed OpenClaw skills are mirrored into the agent home directory for session startup. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). +- Policy and secret-handling safeguards cover more edge cases. Non-interactive `NEMOCLAW_POLICY_TIER` validation fails before side effects, interactive onboarding ignores invalid environment values and prompts normally, safe common egress presets are available where supported, persistent-memory scanning catches additional OpenAI and Slack token shapes, and Hermes remote secrets stay out of sandbox-visible surfaces. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill). + ## v0.0.59 NemoClaw v0.0.59 improves OpenClaw runtime compatibility, inference setup, credential reuse, messaging safeguards, and sandbox startup diagnostics: diff --git a/.agents/skills/nemoclaw-user-reference/references/architecture.md b/.agents/skills/nemoclaw-user-reference/references/architecture.md index 07bbfc2ba9..18ecd28a49 100644 --- a/.agents/skills/nemoclaw-user-reference/references/architecture.md +++ b/.agents/skills/nemoclaw-user-reference/references/architecture.md @@ -68,9 +68,13 @@ 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. +When `OPENSHELL_DRIVERS` includes `docker`, NemoClaw treats the gateway as host-owned and does not write the in-container `/tmp/nemoclaw-gateway-local` marker that legacy in-container gateway paths use. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. ```mermaid @@ -134,8 +138,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 +203,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/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index 5beb179d4b..d5db5d01a1 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/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] @@ -606,10 +618,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 +665,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 +686,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 +819,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 @@ -975,6 +1024,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. @@ -1373,6 +1425,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. + +```console +nemoclaw tunnel status +``` + ### `nemoclaw start` **Warning:** @@ -1394,6 +1456,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 +1493,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 +1612,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 +1754,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 +1785,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: `deepseek-v4-flash`, `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_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 +1817,8 @@ 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`. | @@ -1830,9 +1898,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/.agents/skills/nemoclaw-user-reference/references/network-policies.md b/.agents/skills/nemoclaw-user-reference/references/network-policies.md index de3517a690..937dd41abe 100644 --- a/.agents/skills/nemoclaw-user-reference/references/network-policies.md +++ b/.agents/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/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index cdafbeb91a..3d85d5f1be 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/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: @@ -1251,6 +1284,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 +1355,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 diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index 2c52d95b60..ff5303d993 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -74,6 +74,7 @@ NemoClaw is split into integration pieces on the host and in the sandbox image: - The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. + Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript. @@ -120,6 +121,7 @@ The sandbox starts with a default policy that controls network egress, filesyste | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. +NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether a failure came from policy denial, DNS, timeout, TLS, or filesystem access. ## Next Steps diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index 917d7dbfad..dd7a932f39 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -13,6 +13,16 @@ NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track the highlights of the latest release. For more detailed release notes, refer to the [NemoClaw GitHub announcements](https://github.com/NVIDIA/NemoClaw/discussions/categories/announcements?discussions_q=is%3Aopen+category%3AAnnouncements). +## v0.0.60 + +NemoClaw v0.0.60 improves runtime guidance, sandbox lifecycle reliability, local inference setup, messaging enrollment, and maintainer safeguards: + +- OpenClaw runtime guidance stays active without appearing in the visible chat transcript, and sandbox network and filesystem context now tells agents to try allowed in-sandbox actions before reporting them unavailable. OpenClaw device-approval policy also uses the same allowlist and scope behavior during startup and connect. For more information, refer to [Architecture](../reference/architecture). +- Onboarding and sandbox lifecycle paths preserve more host state. NemoClaw uses the package-managed OpenShell gateway user service when available, scopes gateway and dashboard cleanup by sandbox instance, detects Docker-driver sandboxes without writing the local gateway marker, rolls back failed Docker GPU patches, honors `.dockerignore` for custom `--from ` contexts, and can skip default workspace-template seeding with `NEMOCLAW_MINIMAL_BOOTSTRAP=1`. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- Local inference setup is more predictable across NVIDIA NIM, Ollama, vLLM, DGX Spark, DGX Station, Anthropic-compatible routes, and Hermes. NemoClaw pulls NIM images by platform digest, uses stable managed-vLLM images and updated DGX model profiles, tightens Ollama fit checks, synchronizes Anthropic route metadata, preserves Hermes proxy API-key placeholders, and serves the prebuilt Hermes dashboard assets from the sandbox image. For more information, refer to [NemoClaw Inference Options](../inference/inference-options). +- Messaging and day-two CLI operations share more common plumbing. Messaging enrollment uses manifest hooks across Telegram, Discord, Slack, WeChat, and WhatsApp, `$$nemoclaw tunnel status` reports Cloudflare tunnel state directly, global `status` and `list` honor sandbox environment overrides consistently, and installed OpenClaw skills are mirrored into the agent home directory for session startup. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). +- Policy and secret-handling safeguards cover more edge cases. Non-interactive `NEMOCLAW_POLICY_TIER` validation fails before side effects, interactive onboarding ignores invalid environment values and prompts normally, safe common egress presets are available where supported, persistent-memory scanning catches additional OpenAI and Slack token shapes, and Hermes remote secrets stay out of sandbox-visible surfaces. For more information, refer to [Security Best Practices](../security/best-practices). + ## v0.0.59 NemoClaw v0.0.59 improves OpenClaw runtime compatibility, inference setup, credential reuse, messaging safeguards, and sandbox startup diagnostics: diff --git a/docs/get-started/quickstart-hermes.mdx b/docs/get-started/quickstart-hermes.mdx index 1750682646..0fce090fdf 100644 --- a/docs/get-started/quickstart-hermes.mdx +++ b/docs/get-started/quickstart-hermes.mdx @@ -70,6 +70,9 @@ Choose the inference provider that matches where you want Hermes model traffic t The provider options and credential environment variables are the same as the standard NemoClaw quickstart. For provider-specific prompts, refer to the [Inference Options](../inference/inference-options) page. The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration. +If you authenticate Hermes through Nous Portal OAuth, the wizard can also prompt for managed Nous tool gateways such as web search, image generation, audio, browser automation, or managed code execution. +Those choices add the matching Hermes policy presets to the sandbox. +API-key mode is inference-only and does not enable managed tool gateways. After provider and model selection, review the summary and confirm the build. NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traffic through `inference.local`, and starts the Hermes gateway inside the sandbox. @@ -102,6 +105,8 @@ When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle co Hermes exposes its built-in browser dashboard on port `18789`. NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients. NemoClaw builds the Hermes dashboard assets into the sandbox image, so the dashboard starts without running `npm` as the sandbox user under `/opt/hermes`. +Dashboard chat uses the prebuilt `/opt/hermes/ui-tui` bundle. +If you need to recover the Hermes dashboard manually, use `hermes dashboard --tui --skip-build` so recovery does not try to rebuild assets under root-owned install paths. Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab. ```text diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx index 8a023ad354..12a8d5a8bb 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -75,7 +75,7 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice. Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform. -Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, and local-inference presets. +Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets. On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set. On WSL, express install selects the Windows-host Ollama setup path. Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself. @@ -187,7 +187,7 @@ Review [Messaging Channels](../manage-sandboxes/messaging-channels) before enabl After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. Web search and messaging selections happen before this point so the sandbox image and the policy suggestions stay aligned. -The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. +The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, read-only weather lookups, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference. diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index 8285232195..182613a583 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -308,6 +308,7 @@ When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that v 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. @@ -389,6 +390,9 @@ 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. @@ -396,6 +400,8 @@ The prompt masks the key during input and retries one time on a bad key before f 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. NIM uses vLLM internally. diff --git a/docs/inference/switch-inference-providers.mdx b/docs/inference/switch-inference-providers.mdx index 7803512d1f..0313d8a8c8 100644 --- a/docs/inference/switch-inference-providers.mdx +++ b/docs/inference/switch-inference-providers.mdx @@ -31,7 +31,7 @@ For OpenClaw, it updates `agents.defaults.model.primary` and the matching provid 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`, and `model.provider: custom`) without rebuilding or restarting Hermes. +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. @@ -88,6 +88,16 @@ $$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, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image. @@ -159,6 +169,8 @@ 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. +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 diff --git a/docs/inference/tool-calling-reliability.mdx b/docs/inference/tool-calling-reliability.mdx index 653cb92022..9a5a4c2a5a 100644 --- a/docs/inference/tool-calling-reliability.mdx +++ b/docs/inference/tool-calling-reliability.mdx @@ -47,6 +47,12 @@ The common failure mode is: 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**. diff --git a/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index 6dcb3ea6c2..f186516fc8 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -178,6 +178,12 @@ NEMOCLAW_PROVIDER=ollama \ 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. diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 953a150544..7aa34c5d2c 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -118,6 +118,8 @@ When the default API port is already held by another sandbox, `$$nemoclaw onboar If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. +Gateway and dashboard cleanup is scoped by sandbox name and port. +A later onboarding run that uses a different `NEMOCLAW_GATEWAY_PORT` or `--control-ui-port` does not tear down the first sandbox's gateway or dashboard forward. ```bash $$nemoclaw onboard # first sandbox uses 18789 diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index 56b0ffe023..6ef410b6b9 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -59,9 +59,11 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr | OpenClaw model-pricing reference fetch | `openclaw-pricing` | | npm and Yarn packages | `npm` | | Microsoft 365, Outlook, and Graph API | `outlook` | +| Public reference APIs | `public-reference` | | Python Package Index | `pypi` | | Slack messaging | `slack` | | Telegram Bot API | `telegram` | +| Weather and geocoding APIs | `weather` | | WeChat (personal) iLink Bot API (experimental) | `wechat` | | WhatsApp Web messaging (experimental) | `whatsapp` | @@ -242,6 +244,25 @@ $$nemoclaw my-assistant policy-add brave --yes The Brave Search API key is still configured separately during onboarding or through the web search setup flow. +## Weather and Public Reference Lookups + +Use the `weather` preset when the agent needs read-only weather or geocoding lookups. +The Balanced and Open tiers include it by default. +The preset covers Open-Meteo, geocoding, and National Weather Service endpoints without enabling messaging or productivity APIs. + +```bash +$$nemoclaw my-assistant policy-add weather --dry-run +$$nemoclaw my-assistant policy-add weather --yes +``` + +Use the `public-reference` preset when the agent needs read-only public-reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata. +The Open tier includes this preset by default. + +```bash +$$nemoclaw my-assistant policy-add public-reference --dry-run +$$nemoclaw my-assistant policy-add public-reference --yes +``` + ## Package and Model Tooling Use these presets when an agent workflow installs packages or downloads model assets: diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index d372ccbf5a..00350ca183 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -83,6 +83,7 @@ Per-user units, partial units, and user-manager or bus outages do not take over 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. +When `OPENSHELL_DRIVERS` includes `docker`, NemoClaw treats the gateway as host-owned and does not write the in-container `/tmp/nemoclaw-gateway-local` marker that legacy in-container gateway paths use. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. ```mermaid @@ -146,8 +147,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. @@ -209,7 +212,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/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index bd5ca7a102..e465816db4 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -142,7 +142,8 @@ NEMOCLAW_POLICY_TIER=restricted nemohermes onboard --non-interactive --yes-i-acc ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -Any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight with an error listing the valid options. +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*. @@ -152,6 +153,8 @@ 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`. | @@ -343,6 +346,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 nemohermes list [--json] @@ -662,6 +666,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 nemohermes my-assistant policy-list @@ -1229,8 +1235,9 @@ nemohermes tunnel stop ### `nemohermes tunnel status` -Show the current cloudflared public-URL tunnel status for the default sandbox dashboard. +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 `nemohermes status`. +Selection honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. ```console nemohermes tunnel status @@ -1257,6 +1264,7 @@ This command remains as a compatibility alias to `nemohermes 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 nemohermes status @@ -1286,7 +1294,8 @@ nemohermes inference get --json Switch the active inference provider or model for a NemoClaw-managed OpenClaw or Hermes sandbox. The command updates the OpenShell gateway route, patches the selected running agent config so it matches the route, recomputes the config hash, and updates the NemoClaw registry. -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. By default, the command syncs the default registered sandbox. @@ -1560,10 +1569,13 @@ Set them before running `nemohermes 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: `deepseek-v4-flash`, `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_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; see [Runtime Controls](../manage-sandboxes/runtime-controls). | | `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). | Hermes-specific provider authentication: @@ -1573,6 +1585,8 @@ 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`. | #### Linux Ollama install mode details diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index e862f59e64..454819ec9c 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -183,7 +183,8 @@ NEMOCLAW_POLICY_TIER=restricted $$nemoclaw onboard --non-interactive --yes-i-acc ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -Any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight with an error listing the valid options. +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*. @@ -193,6 +194,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`. | @@ -400,6 +407,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] @@ -836,6 +844,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 @@ -1039,6 +1049,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](../manage-sandboxes/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. @@ -1439,8 +1452,9 @@ $$nemoclaw tunnel stop ### `$$nemoclaw tunnel status` -Show the current cloudflared public-URL tunnel status for the default sandbox dashboard. +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. ```console $$nemoclaw tunnel status @@ -1467,6 +1481,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 @@ -1503,7 +1518,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. @@ -1794,10 +1810,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: `deepseek-v4-flash`, `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_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; see [Runtime Controls](../manage-sandboxes/runtime-controls). | | `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). | @@ -1823,6 +1842,8 @@ 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`. | diff --git a/docs/reference/network-policies.mdx b/docs/reference/network-policies.mdx index f373cb7627..957c786c77 100644 --- a/docs/reference/network-policies.mdx +++ b/docs/reference/network-policies.mdx @@ -65,13 +65,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. @@ -85,7 +86,8 @@ NEMOCLAW_POLICY_TIER=open $$nemoclaw onboard --non-interactive --yes-i-accept-th ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -If a non-blank value does not match a known tier, onboarding exits before preflight with an error listing the valid options. +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/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 39e7ed087c..326f13b5f4 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -675,6 +675,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 @@ -683,6 +685,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. @@ -878,8 +881,8 @@ Do not probe with `su -s /bin/sh gateway ...`: `su` does not initialize the gate A NemoClaw sandbox has two intentional permission states for `/sandbox/.openclaw`; `700/600` is not one of them: -- **Mutable default (shields down):** `/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. -- **Shields up (locked from the host with `nemoclaw shields up`):** `openclaw.json` becomes `444 root:root` and the config dir becomes `755 root: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). +- **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 @@ -1295,6 +1298,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 @@ -1362,6 +1368,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 diff --git a/docs/security/best-practices.mdx b/docs/security/best-practices.mdx index 63c530c821..dcf41cb7cd 100644 --- a/docs/security/best-practices.mdx +++ b/docs/security/best-practices.mdx @@ -450,10 +450,10 @@ The auto-pair watcher automatically approves device pairing requests from recogn | Aspect | Detail | |---|---| -| Default | The watcher approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat`. All other clients are rejected and logged. | -| What you can change | This is not a user-facing knob. The allowlist is defined in the entrypoint script. | +| Default | Startup auto-pairing and `connect`-time approval share one policy. NemoClaw approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat` or `cli`, and only for `operator.pairing`, `operator.read`, and `operator.write` scopes. All other clients or scopes are rejected and logged. | +| What you can change | This is not a user-facing knob. The allowlist is defined by NemoClaw's OpenClaw device-approval helper. | | Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. | -| Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | +| Recommendation | No action needed. NemoClaw handles this automatically at startup and during `connect` for late scope upgrades. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | @@ -461,6 +461,8 @@ The auto-pair watcher automatically approves device pairing requests from recogn Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard. Do not publish those endpoints on shared or public networks unless you put them behind your own access controls. NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`. +Generated Hermes runtime files use OpenShell resolver placeholders for managed-tool and messaging credentials. +Hermes startup rejects raw secret-shaped values in sandbox-visible environment or config fields, while allowing empty values, migration sentinels, OpenShell resolver placeholders, and expected Slack placeholder forms. @@ -485,7 +487,7 @@ The scanner intercepts Write, Edit, and similar tool calls targeting memory and | Aspect | Detail | |---|---| | Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. | -| What it covers | Three classifiers, all enforced through `isMemoryPath()`: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | +| What it covers | Three path classifiers, all enforced through `isMemoryPath()`, plus credential-shaped text such as provider API keys, OpenAI project keys with `sk-proj-` prefixes, and Slack app-level `xapp-` tokens. The path classifiers are: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | | What you can change | This is not a user-facing knob. The plugin enforces it automatically. | | Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. | | Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. | diff --git a/docs/security/credential-storage.mdx b/docs/security/credential-storage.mdx index 74043e38ec..7929751214 100644 --- a/docs/security/credential-storage.mdx +++ b/docs/security/credential-storage.mdx @@ -22,6 +22,9 @@ The sandbox-side OpenClaw gateway token is generated at container startup and is Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. +Those files should contain resolver placeholders, not live provider credentials. +For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into `/sandbox/.hermes/config.yaml`, `/sandbox/.hermes/.env`, and process environment entries visible to the sandbox. +Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces. ## Where Credentials Live diff --git a/fern/fern.config.json b/fern/fern.config.json index 5495dca9a7..37536b72aa 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "nvidia", - "version": "5.44.3" + "version": "5.45.0" }