diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index f437ede713..3f639ad3ff 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -1,451 +1,129 @@ --- name: "nemoclaw-user-configure-inference" -description: "Lists all inference providers offered during NemoClaw onboarding. Use when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Trigger keywords - nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing, switch nemoclaw inference model, change inference runtime, nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint." +description: "Shows the NemoClaw-specific file paths and update flow for adding an auxiliary OpenClaw sub-agent model. Use when users ask how to add a second model, configure a sub-agent model, use Omni for vision tasks, configure agents.list, or use sessions_spawn in NemoClaw. Trigger keywords - nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, switch nemoclaw inference model, change inference runtime, nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing." --- -# NemoClaw Inference Options +# Set up a Task-Specific Sub-Agent -## Prerequisites +OpenClaw documents the sub-agent behavior, `sessions_spawn` tool, `agents.list` configuration, tool policy, nesting, and auth model in [Sub-Agents](https://docs.openclaw.ai/tools/subagents). +Use that page as the source of truth for how OpenClaw sub-agents work. -- A running NemoClaw sandbox. -- The OpenShell CLI on your `PATH`. -- NemoClaw installed. -- A local model server running, or Ollama installed. The NemoClaw onboard wizard can also start Ollama for you. +This NemoClaw page covers the sandbox-specific pieces: where the OpenClaw config lives, where to put per-agent credentials, which writable workspace path agents should use, and how the Omni VLM demo maps onto those paths. -Change the active inference model while the sandbox is running. -No restart is required. +## Step 1: NemoClaw Sandbox Paths -## Step 1: Switch to a Different Model +NemoClaw runs OpenClaw inside an OpenShell sandbox. +When adapting an OpenClaw sub-agent setup, use these paths inside the sandbox: -Switching happens through the OpenShell inference route. -Use the provider and model that match the upstream you want to use. - -### NVIDIA Endpoints - -```console -$ openshell inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b -``` - -### OpenAI - -```console -$ openshell inference set --provider openai-api --model gpt-5.4 -``` - -### Anthropic - -```console -$ openshell inference set --provider anthropic-prod --model claude-sonnet-4-6 -``` - -### Google Gemini - -```console -$ openshell inference set --provider gemini-api --model gemini-2.5-flash -``` - -### Compatible Endpoints - -If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint: - -```console -$ openshell inference set --provider compatible-endpoint --model -``` - -```console -$ openshell inference set --provider compatible-anthropic-endpoint --model -``` - -If the provider itself needs to change, rerun `nemoclaw onboard`. - -#### Switching from Responses API to Chat Completions - -If onboarding selected `/v1/responses` but the agent fails at runtime (for -example, because the backend does not emit the streaming events OpenClaw -requires), re-run onboarding so the wizard re-probes the endpoint and bakes -the correct API path into the image: - -```console -$ nemoclaw onboard -``` - -Select the same provider and endpoint again. -The updated streaming probe will detect incomplete `/v1/responses` support -and select `/v1/chat/completions` automatically. - -For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by -default, so no env var is required to keep the safe path. -To opt in to `/v1/responses` for a backend you have verified end to end, set -`NEMOCLAW_PREFERRED_API` before onboarding: - -```console -$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard -``` - -> **Note:** `NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but -> does not update the Dockerfile ARG baked into the image. -> If you recreate the sandbox without the override env var, the image reverts to -> the original API path. -> A fresh `nemoclaw onboard` is the reliable fix because it updates both the -> session and the baked image. - -## Step 2: Cross-Provider Switching - -Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) requires updating both the gateway route and the sandbox config. - -Set the gateway route on the host: - -```console -$ openshell inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify -``` - -Then set the override env vars and recreate the sandbox so they take effect at startup: - -```console -$ export NEMOCLAW_MODEL_OVERRIDE="anthropic/claude-sonnet-4-6" -$ export NEMOCLAW_INFERENCE_API_OVERRIDE="anthropic-messages" -$ nemoclaw onboard --resume --recreate-sandbox -``` - -The entrypoint patches `openclaw.json` at container startup with the override values. -You do not need to rebuild the image. -Remove the env vars and recreate the sandbox to revert to the original model. - -`NEMOCLAW_INFERENCE_API_OVERRIDE` accepts `openai-completions` (for NVIDIA, OpenAI, Gemini, compatible endpoints) or `anthropic-messages` (for Anthropic and Anthropic-compatible endpoints). -This variable is only needed when switching between provider families. - -## Step 3: Tune Model Metadata - -The sandbox image bakes model metadata (context window, max output tokens, reasoning mode, and accepted input modalities) into `openclaw.json` at build time. -To change these values, set the corresponding environment variables before running `nemoclaw onboard` so they patch into the Dockerfile before the image builds. - -| Variable | Values | Default | -|---|---|---| -| `NEMOCLAW_CONTEXT_WINDOW` | Positive integer (tokens) | `131072` | -| `NEMOCLAW_MAX_TOKENS` | Positive integer (tokens) | `4096` | -| `NEMOCLAW_REASONING` | `true` or `false` | `false` | -| `NEMOCLAW_INFERENCE_INPUTS` | `text` or `text,image` | `text` | -| `NEMOCLAW_AGENT_TIMEOUT` | Positive integer (seconds) | `600` | - -Invalid values are ignored, and the default bakes into the image. -Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. - -```console -$ export NEMOCLAW_CONTEXT_WINDOW=65536 -$ export NEMOCLAW_MAX_TOKENS=8192 -$ export NEMOCLAW_REASONING=true -$ export NEMOCLAW_INFERENCE_INPUTS=text,image -$ export NEMOCLAW_AGENT_TIMEOUT=1800 -$ nemoclaw onboard -``` - -`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into -`agents.defaults.timeoutSeconds`. Increase it for slow local inference (for -example, CPU-only Ollama or vLLM on modest hardware). `openclaw.json` is -immutable at runtime, so this value can only be changed by rebuilding the -sandbox via `nemoclaw onboard`. - -These variables are build-time settings. -If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image: - -```console -$ nemoclaw onboard --resume --recreate-sandbox -``` - -## Step 4: Verify the Active Model - -Run the status command to confirm the change: - -```console -$ nemoclaw status -``` - -Add the `--json` flag for machine-readable output: - -```console -$ nemoclaw status --json -``` - -The output includes the active provider, model, and endpoint. - -## Step 5: Notes - -- The host keeps provider credentials. -- The sandbox continues to use `inference.local`. -- Same-provider model switches take effect immediately via the gateway route alone. -- Cross-provider switches also require `NEMOCLAW_MODEL_OVERRIDE` (and `NEMOCLAW_INFERENCE_API_OVERRIDE`) plus a sandbox recreate so the entrypoint patches the config at startup. -- Overrides are applied at container startup. Changing or removing env vars requires a sandbox recreate to take effect. - ---- - -NemoClaw can route inference to a model server running on your machine instead of a cloud API. -This page covers Ollama, compatible-endpoint paths for other servers, and two experimental options for vLLM and NVIDIA NIM. - -All approaches use the same `inference.local` routing model. -The agent inside the sandbox never connects to your model server directly. -OpenShell intercepts inference traffic and forwards it to the local endpoint you configure. - -## Step 6: Ollama - -Ollama is the default local inference option. -The onboard wizard detects Ollama automatically when it is installed or running on the host. - -If Ollama is not running, NemoClaw starts it for you. -On macOS, the wizard also offers to install Ollama through Homebrew if it is not present. - -Run the onboard wizard. - -```console -$ nemoclaw onboard -``` - -Select **Local Ollama** from the provider list. -NemoClaw lists installed models or offers starter models if none are installed. -It pulls the selected model, loads it into memory, and validates it before continuing. - -### Authenticated Reverse Proxy - -NemoClaw keeps Ollama bound to `127.0.0.1:11434` and starts a token-gated -reverse proxy on `0.0.0.0:11435`. -Containers and other hosts on the local network reach Ollama only through the -proxy, which validates a Bearer token before forwarding requests. -Ollama itself is never exposed without authentication. - -The onboard wizard manages the proxy automatically: - -- Generates a random 24-byte token on first run and stores it in - `~/.nemoclaw/ollama-proxy-token` with `0600` permissions. -- Starts the proxy after Ollama and verifies it before continuing. -- Cleans up stale proxy processes from previous runs. -- Reuses the persisted token after a host reboot so you do not need to re-run - onboard. - -The sandbox provider is configured to use proxy port `11435` with the generated -token as its `OPENAI_API_KEY` credential. -OpenShell's L7 proxy injects the token at egress, so the agent inside the -sandbox never sees the token directly. - -`GET /api/tags` is exempt from authentication so container health checks -continue to work. -All other endpoints (including `POST /api/tags`) require the Bearer token. - -If Ollama is already running on a non-loopback address when you start onboard, -the wizard restarts it on `127.0.0.1:11434` so the proxy is the only network -path to the model server. - -### Non-Interactive Setup - -```console -$ NEMOCLAW_PROVIDER=ollama \ - NEMOCLAW_MODEL=qwen2.5:14b \ - nemoclaw onboard --non-interactive -``` - -If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. - -| Variable | Purpose | +| Path | Purpose | |---|---| -| `NEMOCLAW_PROVIDER` | Set to `ollama`. | -| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. | - -## Step 7: OpenAI-Compatible Server - -This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others. -For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default. -This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions. -To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard. - -Start your model server. -The examples below use vLLM, but any OpenAI-compatible server works. - -```console -$ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 -``` - -Run the onboard wizard. +| `/sandbox/.openclaw/openclaw.json` | OpenClaw config, including `models.providers`, `agents.defaults`, and `agents.list`. | +| `/sandbox/.openclaw/.config-hash` | Hash for `openclaw.json`. Keep it in sync after manual config edits; it becomes a startup-enforced trust anchor only after `shields up` locks it root-owned and read-only. | +| `/sandbox/.openclaw/agents//agent/auth-profiles.json` | Per-agent provider credentials. Use this when a sub-agent calls an auxiliary provider directly. | +| `/sandbox/.openclaw/workspace/` | Writable shared workspace path for files the primary agent passes to the sub-agent. | +| `/tmp/gateway.log` | OpenClaw gateway log. Use it to confirm config reloads and diagnose sub-agent failures. | -```console -$ nemoclaw onboard -``` +For file-based tasks, instruct agents to use `/sandbox/.openclaw/workspace/`. +Avoid relying on legacy `.openclaw-data` paths or read-only OpenClaw paths in delegation instructions. -When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. -Enter the base URL of your local server, for example `http://localhost:8000/v1`. +## Step 2: Omni Vision Sub-Agent Example -The wizard prompts for an API key. -If your server does not require authentication, enter any non-empty string (for example, `dummy`). +The [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-demo) applies the OpenClaw sub-agent pattern to a vision task. +It keeps the primary `main` agent on the normal NemoClaw inference route and adds a `vision-operator` sub-agent backed by an Omni vision model. -NemoClaw validates the endpoint by sending a test inference request before continuing. -The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider. -If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires. - -### Non-Interactive Setup - -Set the following environment variables for scripted or CI/CD deployments. - -```console -$ NEMOCLAW_PROVIDER=custom \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ - NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ - COMPATIBLE_API_KEY=dummy \ - nemoclaw onboard --non-interactive -``` - -| Variable | Purpose | +| OpenClaw field | Omni example value | |---|---| -| `NEMOCLAW_PROVIDER` | Set to `custom` for an OpenAI-compatible endpoint. | -| `NEMOCLAW_ENDPOINT_URL` | Base URL of the local server. | -| `NEMOCLAW_MODEL` | Model ID as reported by the server. | -| `COMPATIBLE_API_KEY` | API key for the endpoint. Use any non-empty value if authentication is not required. | - -### Selecting the API Path - -For the compatible-endpoint provider, `/v1/chat/completions` is the default. -NemoClaw tests streaming events during onboarding and uses chat completions -without probing the Responses API. - -To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: - -```console -$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard -``` - -The wizard then probes `/v1/responses` and only selects it when streaming -support is complete. -If the probe fails, the wizard falls back to `/v1/chat/completions` -automatically. -You can use this variable in both interactive and non-interactive mode. - -| Variable | Values | Default | -|---|---|---| -| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints | - -If you already onboarded and the sandbox is failing at runtime, re-run -`nemoclaw onboard` to re-probe the endpoint and bake the correct API path -into the image. -Refer to Switch Inference Models (use the `nemoclaw-user-configure-inference` skill) for details. - -## Step 8: Anthropic-Compatible Server - -If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. - -```console -$ nemoclaw onboard -``` - -For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. - -```console -$ NEMOCLAW_PROVIDER=anthropicCompatible \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ - NEMOCLAW_MODEL=my-model \ - COMPATIBLE_ANTHROPIC_API_KEY=dummy \ - nemoclaw onboard --non-interactive -``` +| Primary agent | `main` | +| Primary model | `inference/nvidia/nemotron-3-super-120b-a12b` | +| Auxiliary provider | `nvidia-omni` | +| Sub-agent | `vision-operator` | +| Sub-agent model | `nvidia-omni/private/nvidia/nemotron-3-nano-omni-reasoning-30b-a3b` | +| Delegation tool | `sessions_spawn` | -## Step 9: vLLM Auto-Detection (Experimental) +Omni is used as the specialist model for image tasks. +The primary orchestration model remains responsible for conversation, planning, and deciding when to delegate. -When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. +## Step 3: Update the Sandbox Config -Set the experimental flag and run onboard. +Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary provider and `agents.list` changes, then upload it back. ```console -$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +$ export SANDBOX=my-assistant +$ export DOCKER_CTR=openshell-cluster-nemoclaw +$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json ``` -Select **Local vLLM [experimental]** from the provider list. -NemoClaw detects the running model and validates the endpoint. - -> **Note:** NemoClaw forces the `chat/completions` API path for vLLM. -> The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text. +Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config. +For the Omni example, the demo provides `vlm-demo/vlm-subagent/openclaw-patch.py`. -### Non-Interactive Setup +Upload the patched config and refresh the hash. +In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof; run `nemoclaw shields up` afterward if the sandbox should enforce config integrity at startup. ```console -$ NEMOCLAW_EXPERIMENTAL=1 \ - NEMOCLAW_PROVIDER=vllm \ - nemoclaw onboard --non-interactive +$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/openclaw.json +$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/.config-hash +$ cat /tmp/openclaw.updated.json | docker exec -i "$DOCKER_CTR" kubectl exec -i -n openshell "$SANDBOX" -c agent -- sh -c 'cat > /sandbox/.openclaw/openclaw.json' +$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash" +$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/openclaw.json +$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/.config-hash ``` -NemoClaw auto-detects the model from the running vLLM instance. -To override the model, set `NEMOCLAW_MODEL`. +Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change. -## Step 10: NVIDIA NIM (Experimental) +## Step 4: Add Sub-Agent Credentials -NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU. +If the auxiliary model uses a provider key outside the normal NemoClaw inference route, put that key in the sub-agent auth profile. +For the Omni example: -Set the experimental flag and run onboard. - -```console -$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +```text +/sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json ``` -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. - -NIM container images are hosted on `nvcr.io` and require NGC registry authentication before `docker pull` succeeds. -If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history. -The prompt masks the key during input and retries once on a bad key before failing. -In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`. - -> **Note:** NIM uses vLLM internally. -> The same `chat/completions` API path restriction applies. - -### Non-Interactive Setup +Use the same provider ID that appears in `models.providers`, such as `nvidia-omni`. +After uploading the auth profile, make sure the sub-agent directory is owned by the sandbox user: ```console -$ NEMOCLAW_EXPERIMENTAL=1 \ - NEMOCLAW_PROVIDER=nim \ - nemoclaw onboard --non-interactive +$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator ``` -To select a specific model, set `NEMOCLAW_MODEL`. - -## Step 11: Timeout Configuration +## Step 5: Allow Auxiliary Provider Egress -Local inference requests use a default timeout of 180 seconds. -Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for local providers (Ollama, vLLM, NIM). +If the sub-agent calls a provider directly, update the OpenShell network policy for the binary that makes the request. +In the Omni demo, the OpenClaw gateway runs as `/usr/local/bin/node`, so the NVIDIA endpoint policy must allow that binary. -To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: +Refer to Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for policy update workflows. -```console -$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -$ nemoclaw onboard -``` - -The value is in seconds. -This setting is baked into the sandbox at build time. -Changing it after onboarding requires re-running `nemoclaw onboard`. +## Step 6: Add Delegation Instructions -## Step 12: Verify the Configuration +OpenClaw handles `sessions_spawn`, but the primary agent still needs task instructions. +Place those instructions in the writable workspace, for example: -After onboarding completes, confirm the active provider and model. - -```console -$ nemoclaw status +```text +/sandbox/.openclaw/workspace/TOOLS.md ``` -The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. +The Omni demo includes `vlm-demo/vlm-subagent/TOOLS.md`, which tells `main` to delegate image tasks to `vision-operator` and tells the sub-agent to read the image path it receives. +Adapt that file for other task-specific models. -## Step 13: Switch Models at Runtime +## Step 7: Demo Assets -You can change the model without re-running onboard. -Refer to Switch Inference Models (use the `nemoclaw-user-configure-inference` skill) for the full procedure. - -For compatible endpoints, the command is: - -```console -$ openshell inference set --provider compatible-endpoint --model -``` +Use the [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-demo) repository for runnable Omni example assets: -If the provider itself needs to change (for example, switching from vLLM to a cloud API), rerun `nemoclaw onboard`. +- `vlm-subagent-guide.md` for a command-by-command walkthrough. +- `vlm-subagent/openclaw-patch.py` for patching `openclaw.json`. +- `vlm-subagent/auth-profiles.template.json` for the sub-agent auth profile. +- `vlm-subagent/TOOLS.md` for delegation instructions. ## References +- **Load [references/switch-inference-providers.md](references/switch-inference-providers.md)** when switching inference providers, changing the model runtime, or reconfiguring inference routing. Changes the active inference model without restarting the sandbox. +- **Load [references/use-local-inference.md](references/use-local-inference.md)** when setting up Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible local model server with NemoClaw. Connects NemoClaw to a local inference server. - **Load [references/inference-options.md](references/inference-options.md)** when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Lists all inference providers offered during NemoClaw onboarding. ## Related Skills -- `nemoclaw-user-get-started` — Quickstart (use the `nemoclaw-user-get-started` skill) for first-time installation +- Refer to [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for `sessions_spawn`, `agents.list`, nesting, tool policy, and auth behavior. +- `nemoclaw-user-workspace` — Refer to Workspace Files (use the `nemoclaw-user-workspace` skill) to understand per-agent workspace directories 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 d7cf24868c..1df1a69feb 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -14,6 +14,8 @@ OpenShell intercepts inference traffic on the host and forwards it to the provid Provider credentials stay on the host. The sandbox does not receive your API key. +Local Ollama and local vLLM do not require your host `OPENAI_API_KEY`. +NemoClaw uses provider-specific local tokens for those routes, and rebuilds of legacy local-inference sandboxes migrate away from stale OpenAI credential requirements. ## Provider Status @@ -39,7 +41,7 @@ Ollama appears when it is installed or running on the host. | Option | Description | Curated models | |--------|-------------|----------------| -| NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_API_KEY`. | Nemotron 3 Super 120B, Kimi K2.5, GLM-5.1, MiniMax M2.5, GPT-OSS 120B | +| NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_API_KEY`. | Nemotron 3 Super 120B, GLM-5.1, MiniMax M2.5, GPT-OSS 120B | | OpenAI | Routes to the OpenAI API. Set `OPENAI_API_KEY`. | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.4-pro-2026-03-05` | | Other OpenAI-compatible endpoint | Routes to any server that implements `/v1/chat/completions`. If the endpoint also supports `/responses` with OpenClaw-style tool calling, NemoClaw can use that path; otherwise it falls back to `/chat/completions`. The wizard prompts for a base URL and model name. Works with OpenRouter, LocalAI, llama.cpp, or any compatible proxy. Set `COMPATIBLE_API_KEY`. | You provide the model name. | | Anthropic | Routes to the Anthropic Messages API. Set `ANTHROPIC_API_KEY`. | `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6` | @@ -88,6 +90,7 @@ Other provider credentials, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMI | Anthropic-compatible | Tries `/v1/messages`. | | NVIDIA Endpoints (manual model entry) | Validates the model name against the catalog API. | | Compatible endpoints | Sends a real inference request because many proxies do not expose a `/models` endpoint. For OpenAI-compatible endpoints, the probe includes tool calling before NemoClaw favors `/responses`. | +| Local NVIDIA NIM | Uses the same validation behavior as NVIDIA Endpoints and skips the `/v1/responses` probe for endpoints that do not expose it. | ## Next Steps 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 new file mode 100644 index 0000000000..0c6ab3b27a --- /dev/null +++ b/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md @@ -0,0 +1,177 @@ + + +# Switch Inference Models at Runtime + +Change the active inference model while the sandbox is running. +No restart is required. + +## Prerequisites + +- A running NemoClaw sandbox. +- The OpenShell CLI on your `PATH`. + +## Switch to a Different Model + +Switching happens through the OpenShell inference route. +Use the provider and model that match the upstream you want to use. + +### NVIDIA Endpoints + +```console +$ openshell inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b +``` + +### OpenAI + +```console +$ openshell inference set --provider openai-api --model gpt-5.4 +``` + +### Anthropic + +```console +$ openshell inference set --provider anthropic-prod --model claude-sonnet-4-6 +``` + +### Google Gemini + +```console +$ openshell inference set --provider gemini-api --model gemini-2.5-flash +``` + +### Compatible Endpoints + +If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint: + +```console +$ openshell inference set --provider compatible-endpoint --model +``` + +```console +$ openshell inference set --provider compatible-anthropic-endpoint --model +``` + +If the provider itself needs to change, rerun `nemoclaw onboard`. + +#### Switching from Responses API to Chat Completions + +If onboarding selected `/v1/responses` but the agent fails at runtime (for +example, because the backend does not emit the streaming events OpenClaw +requires), re-run onboarding so the wizard re-probes the endpoint and bakes +the correct API path into the image: + +```console +$ nemoclaw onboard +``` + +Select the same provider and endpoint again. +The updated streaming probe will detect incomplete `/v1/responses` support +and select `/v1/chat/completions` automatically. + +For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by +default, so no env var is required to keep the safe path. +To opt in to `/v1/responses` for a backend you have verified end to end, set +`NEMOCLAW_PREFERRED_API` before onboarding: + +```console +$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard +``` + +> **Note:** `NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but +> does not update the Dockerfile ARG baked into the image. +> If you recreate the sandbox without the override env var, the image reverts to +> the original API path. +> A fresh `nemoclaw onboard` is the reliable fix because it updates both the +> session and the baked image. + +## Cross-Provider Switching + +Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) requires updating both the gateway route and the sandbox config. + +Set the gateway route on the host: + +```console +$ openshell inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify +``` + +Then set the override env vars and recreate the sandbox so they take effect at startup: + +```console +$ export NEMOCLAW_MODEL_OVERRIDE="anthropic/claude-sonnet-4-6" +$ export NEMOCLAW_INFERENCE_API_OVERRIDE="anthropic-messages" +$ nemoclaw onboard --resume --recreate-sandbox +``` + +The entrypoint patches `openclaw.json` at container startup with the override values. +You do not need to rebuild the image. +Remove the env vars and recreate the sandbox to revert to the original model. + +`NEMOCLAW_INFERENCE_API_OVERRIDE` accepts `openai-completions` (for NVIDIA, OpenAI, Gemini, compatible endpoints) or `anthropic-messages` (for Anthropic and Anthropic-compatible endpoints). +This variable is only needed when switching between provider families. + +## Tune Model Metadata + +The sandbox image bakes model metadata (context window, max output tokens, reasoning mode, and accepted input modalities) into `openclaw.json` at build time. +To change these values, set the corresponding environment variables before running `nemoclaw onboard` so they patch into the Dockerfile before the image builds. + +| Variable | Values | Default | +|---|---|---| +| `NEMOCLAW_CONTEXT_WINDOW` | Positive integer (tokens) | `131072` | +| `NEMOCLAW_MAX_TOKENS` | Positive integer (tokens) | `4096` | +| `NEMOCLAW_REASONING` | `true` or `false` | `false` | +| `NEMOCLAW_INFERENCE_INPUTS` | `text` or `text,image` | `text` | +| `NEMOCLAW_AGENT_TIMEOUT` | Positive integer (seconds) | `600` | + +Invalid values are ignored, and the default bakes into the image. +Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. + +```console +$ export NEMOCLAW_CONTEXT_WINDOW=65536 +$ export NEMOCLAW_MAX_TOKENS=8192 +$ export NEMOCLAW_REASONING=true +$ export NEMOCLAW_INFERENCE_INPUTS=text,image +$ export NEMOCLAW_AGENT_TIMEOUT=1800 +$ nemoclaw onboard +``` + +`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into +`agents.defaults.timeoutSeconds`. Increase it for slow local inference (for +example, CPU-only Ollama or vLLM on modest hardware). `openclaw.json` is +immutable at runtime, so this value can only be changed by rebuilding the +sandbox via `nemoclaw onboard`. + +These variables are build-time settings. +If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image: + +```console +$ nemoclaw onboard --resume --recreate-sandbox +``` + +## Verify the Active Model + +Run the status command to confirm the change: + +```console +$ nemoclaw status +``` + +Add the `--json` flag for machine-readable output: + +```console +$ nemoclaw status --json +``` + +The output includes the active provider, model, and endpoint. + +## Notes + +- The host keeps provider credentials. +- The sandbox continues to use `inference.local`. +- Same-provider model switches take effect immediately via the gateway route alone. +- Cross-provider switches also require `NEMOCLAW_MODEL_OVERRIDE` (and `NEMOCLAW_INFERENCE_API_OVERRIDE`) plus a sandbox recreate so the entrypoint patches the config at startup. +- Overrides are applied at container startup. Changing or removing env vars requires a sandbox recreate to take effect. +- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. + +## Related Topics + +- Inference Options (use the `nemoclaw-user-configure-inference` skill) for the full list of providers available during onboarding. diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/use-local-inference.md b/.agents/skills/nemoclaw-user-configure-inference/references/use-local-inference.md new file mode 100644 index 0000000000..b4d426b9c0 --- /dev/null +++ b/.agents/skills/nemoclaw-user-configure-inference/references/use-local-inference.md @@ -0,0 +1,277 @@ + + +# Use a Local Inference Server + +NemoClaw can route inference to a model server running on your machine instead of a cloud API. +This page covers Ollama, compatible-endpoint paths for other servers, and two experimental options for vLLM and NVIDIA NIM. + +All approaches use the same `inference.local` routing model. +The agent inside the sandbox never connects to your model server directly. +OpenShell intercepts inference traffic and forwards it to the local endpoint you configure. + +## Prerequisites + +- NemoClaw installed. + Refer to the Quickstart (use the `nemoclaw-user-get-started` skill) if you have not installed yet. +- A local model server running, or Ollama installed. The NemoClaw onboard wizard can also start Ollama for you. + +## Ollama + +Ollama is the default local inference option. +The onboard wizard detects Ollama automatically when it is installed or running on the host. + +If Ollama is not running, NemoClaw starts it for you. +On macOS, the wizard also offers to install Ollama through Homebrew if it is not present. + +Run the onboard wizard. + +```console +$ nemoclaw onboard +``` + +Select **Local Ollama** from the provider list. +NemoClaw lists installed models or offers starter models if none are installed. +It pulls the selected model, loads it into memory, and validates it before continuing. + +### Authenticated Reverse Proxy + +NemoClaw keeps Ollama bound to `127.0.0.1:11434` and starts a token-gated +reverse proxy on `0.0.0.0:11435`. +Containers and other hosts on the local network reach Ollama only through the +proxy, which validates a Bearer token before forwarding requests. +Ollama itself is never exposed without authentication. + +The onboard wizard manages the proxy automatically: + +- Generates a random 24-byte token on first run and stores it in + `~/.nemoclaw/ollama-proxy-token` with `0600` permissions. +- Starts the proxy after Ollama and verifies it before continuing. +- Cleans up stale proxy processes from previous runs. +- Retries the sandbox container reachability check and can continue when the host-side proxy is healthy even if the container probe fails. +- Reuses the persisted token after a host reboot so you do not need to re-run + onboard. + +The sandbox provider is configured to use proxy port `11435` with the generated +token as its `OPENAI_API_KEY` credential. +OpenShell's L7 proxy injects the token at egress, so the agent inside the +sandbox never sees the token directly. + +`GET /api/tags` is exempt from authentication so container health checks +continue to work. +All other endpoints (including `POST /api/tags`) require the Bearer token. + +If Ollama is already running on a non-loopback address when you start onboard, +the wizard restarts it on `127.0.0.1:11434` so the proxy is the only network +path to the model server. + +### Non-Interactive Setup + +```console +$ NEMOCLAW_PROVIDER=ollama \ + NEMOCLAW_MODEL=qwen2.5:14b \ + nemoclaw onboard --non-interactive +``` + +If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. + +| Variable | Purpose | +|---|---| +| `NEMOCLAW_PROVIDER` | Set to `ollama`. | +| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. | + +## OpenAI-Compatible Server + +This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others. +For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default. +This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions. +To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard. + +Start your model server. +The examples below use vLLM, but any OpenAI-compatible server works. + +```console +$ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 +``` + +Run the onboard wizard. + +```console +$ nemoclaw onboard +``` + +When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. +Enter the base URL of your local server, for example `http://localhost:8000/v1`. + +The wizard prompts for an API key. +If your server does not require authentication, enter any non-empty string (for example, `dummy`). + +NemoClaw validates the endpoint by sending a test inference request before continuing. +The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider. +If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires. + +### Non-Interactive Setup + +Set the following environment variables for scripted or CI/CD deployments. + +```console +$ NEMOCLAW_PROVIDER=custom \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ + NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ + COMPATIBLE_API_KEY=dummy \ + nemoclaw onboard --non-interactive +``` + +| Variable | Purpose | +|---|---| +| `NEMOCLAW_PROVIDER` | Set to `custom` for an OpenAI-compatible endpoint. | +| `NEMOCLAW_ENDPOINT_URL` | Base URL of the local server. | +| `NEMOCLAW_MODEL` | Model ID as reported by the server. | +| `COMPATIBLE_API_KEY` | API key for the endpoint. Use any non-empty value if authentication is not required. | + +### Selecting the API Path + +For the compatible-endpoint provider, `/v1/chat/completions` is the default. +NemoClaw tests streaming events during onboarding and uses chat completions +without probing the Responses API. + +To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: + +```console +$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard +``` + +The wizard then probes `/v1/responses` and only selects it when streaming +support is complete. +If the probe fails, the wizard falls back to `/v1/chat/completions` +automatically. +You can use this variable in both interactive and non-interactive mode. + +| Variable | Values | Default | +|---|---|---| +| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints | + +If you already onboarded and the sandbox is failing at runtime, re-run +`nemoclaw onboard` to re-probe the endpoint and bake the correct API path +into the image. +Refer to Switch Inference Models (use the `nemoclaw-user-configure-inference` skill) for details. + +## Anthropic-Compatible Server + +If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. + +```console +$ nemoclaw onboard +``` + +For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. + +```console +$ NEMOCLAW_PROVIDER=anthropicCompatible \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ + NEMOCLAW_MODEL=my-model \ + COMPATIBLE_ANTHROPIC_API_KEY=dummy \ + nemoclaw onboard --non-interactive +``` + +## vLLM Auto-Detection (Experimental) + +When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. + +Set the experimental flag and run onboard. + +```console +$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +``` + +Select **Local vLLM [experimental]** from the provider list. +NemoClaw detects the running model and validates the endpoint. + +> **Note:** NemoClaw forces the `chat/completions` API path for vLLM. +> The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text. + +### Non-Interactive Setup + +```console +$ NEMOCLAW_EXPERIMENTAL=1 \ + NEMOCLAW_PROVIDER=vllm \ + nemoclaw onboard --non-interactive +``` + +NemoClaw auto-detects the model from the running vLLM instance. +To override the model, set `NEMOCLAW_MODEL`. + +## NVIDIA NIM (Experimental) + +NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU. + +Set the experimental flag and run onboard. + +```console +$ 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. + +NIM container images are hosted on `nvcr.io` and require NGC registry authentication before `docker pull` succeeds. +If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history. +The prompt masks the key during input and retries once on a bad key before failing. +In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`. + +> **Note:** NIM uses vLLM internally. +> The same `chat/completions` API path restriction applies. + +### Non-Interactive Setup + +```console +$ NEMOCLAW_EXPERIMENTAL=1 \ + NEMOCLAW_PROVIDER=nim \ + nemoclaw onboard --non-interactive +``` + +To select a specific model, set `NEMOCLAW_MODEL`. + +## Timeout Configuration + +Local inference requests use a default timeout of 180 seconds. +Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup. + +To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ nemoclaw onboard +``` + +The value is in seconds. +This setting is baked into the sandbox at build time. +Changing it after onboarding requires re-running `nemoclaw onboard`. + +## Verify the Configuration + +After onboarding completes, confirm the active provider and model. + +```console +$ nemoclaw status +``` + +The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. + +## Switch Models at Runtime + +You can change the model without re-running onboard. +Refer to Switch Inference Models (use the `nemoclaw-user-configure-inference` skill) for the full procedure. + +For compatible endpoints, the command is: + +```console +$ openshell inference set --provider compatible-endpoint --model +``` + +If the provider itself needs to change (for example, switching from vLLM to a cloud API), rerun `nemoclaw onboard`. + +## Next Steps + +- Inference Options (use the `nemoclaw-user-configure-inference` skill) for the full list of providers available during onboarding. +- Switch Inference Models (use the `nemoclaw-user-configure-inference` skill) for runtime model switching. +- Quickstart (use the `nemoclaw-user-get-started` skill) for first-time installation. 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 6b31e0a541..b58f669ab4 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -210,29 +210,22 @@ The container mounts system directories read-only to prevent the agent from modi ### Agent Config Directory The `/sandbox/.openclaw` directory contains the OpenClaw gateway configuration (model routing, CORS settings, channel config). -The gateway auth token is **not** stored in this directory — it is generated at container startup and passed via the `OPENCLAW_GATEWAY_TOKEN` environment variable only to the gateway process (which runs as the `gateway` user). - -The token file location depends on the startup mode: - -- **Root mode** (production): `/run/nemoclaw/gateway-token` (`gateway:gateway 0400`). - The sandbox user cannot read this file (different uid), cannot read the gateway process env (`/proc/pid/environ` is uid-gated), and `no-new-privileges` prevents escalation. -- **Non-root mode** (dev/fallback): `/tmp/.runtime/nemoclaw/gateway-token` (`sandbox:sandbox 0400`). - Without uid separation the sandbox user owns the file, matching the pre-externalization security posture. - The token is not exported to the shell env or written to rc files. +The current entrypoint reads the gateway auth token from OpenClaw config when present, exports it as `OPENCLAW_GATEWAY_TOKEN`, and writes it to `/tmp/nemoclaw-proxy-env.sh` so interactive sandbox sessions can reach the gateway through the static `/sandbox/.bashrc` and `/sandbox/.profile` source shims. +In root mode, the gateway process still runs as the separate `gateway` user, but the token is intentionally available to sandbox shells for local gateway access. Writable agent state such as plugins, skills, hooks, and workspace metadata lives directly under `/sandbox/.openclaw`. By default, this directory starts writable so the agent can manage its own config, install skills, and write to standard home-directory paths natively. Operators can opt into immutability by running `nemoclaw shields up`, which locks the config and writable state entry points until `shields down` restores the default writable state. -- **DAC permissions (default).** The sandbox user owns the directory and `openclaw.json` with `chmod 600`, so the agent can read and write config directly. +- **DAC permissions (default).** The sandbox user owns `/sandbox/.openclaw` with mode `700` and `openclaw.json` with mode `600`, so the agent can read and write config directly. - **Config integrity hash.** The image includes a SHA256 hash of `openclaw.json`. In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. After `nemoclaw shields up` locks the hash root-owned and read-only, startup enforces it and refuses to start if the hash does not match. -- **Externalized gateway token.** The gateway auth token never appears in `openclaw.json`. It is generated at container startup, written to a mode-dependent token file, and passed to the gateway process via an environment variable. In root mode, the token file is owned by the `gateway` user and unreadable by the sandbox agent. +- **Gateway token environment.** The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or with Shields UP. - **Shields UP (opt-in).** `nemoclaw shields up` applies root-owned read-only permissions and best-effort immutable bits to sensitive config files, and locks writable state directories such as workspace, memory, skills, hooks, cron, agents, and extensions. | Aspect | Detail | |---|---| -| Default | `/sandbox/.openclaw` is writable (`700 sandbox:sandbox`; `openclaw.json` is `600 sandbox:sandbox`). The agent can read and write config, install skills, and manage state directly. The gateway auth token is stored separately: `/run/nemoclaw/gateway-token` in root mode (`gateway:gateway 0400`) or `/tmp/.runtime/nemoclaw/gateway-token` in non-root mode (`sandbox:sandbox 0400`). | +| Default | The sandbox keeps `/sandbox/.openclaw` writable (`700 sandbox:sandbox`), sets `openclaw.json` to `600 sandbox:sandbox`, lets the agent manage state directly, and has the gateway place `OPENCLAW_GATEWAY_TOKEN` in `/tmp/nemoclaw-proxy-env.sh` for interactive shells. | | What you can change | Run `nemoclaw shields up` to lock config and state directories with DAC permissions and the immutable flag where available. Run `shields down` to return to the writable default. | | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. | | Recommendation | For always-on assistants handling sensitive workloads, use `shields up` to lock config after initial setup. For development workflows, the writable default is appropriate. | @@ -434,7 +427,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 | `.openclaw/memory/`, `workspace/`, `agents/`, `skills/`, `hooks/`, and `MEMORY.md`. | +| What it covers | Examples include `.openclaw/memory/`, `.openclaw/workspace/`, `.openclaw/agents/`, `.openclaw/skills/`, `.openclaw/hooks/`, `.openclaw/credentials/`, `.openclaw/openclaw.json`, `.nemoclaw/`, and `MEMORY.md`; the exact coverage is defined by `MEMORY_PATH_SEGMENTS` and enforced through `isMemoryPath()`. | | 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. | @@ -523,7 +516,7 @@ The following patterns weaken security without providing meaningful benefit. | Omitting `protocol: rest` on REST API endpoints | Endpoints without a `protocol` field use L4-only enforcement. The proxy allows the TCP stream through after checking host, port, and binary, but cannot see or filter individual HTTP requests. | Add `protocol: rest` with explicit `rules` to enable per-request method and path control on REST APIs. | | Adding endpoints to the baseline policy for one-off requests | Adding an endpoint to the baseline policy makes it permanently reachable across all sandbox instances. | Use operator approval. Approved endpoints persist within the sandbox instance but reset when you destroy and recreate the sandbox. | | Relying solely on the entrypoint for capability drops | The entrypoint drops dangerous capabilities using `capsh`, but this is best-effort. If `capsh` is unavailable or `CAP_SETPCAP` is not in the bounding set, the container runs with the default capability set. | Pass `--cap-drop=ALL` at the container runtime level as defense-in-depth. | -| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent modify auth tokens, disable CORS, or redirect inference routing. | Run `nemoclaw shields up` to lock config for always-on assistants handling sensitive data. | +| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Run `nemoclaw shields up` to lock config for always-on assistants handling sensitive data. | | Adding inference provider hosts to the network policy | Direct network access to an inference host bypasses credential isolation and usage tracking. | Use OpenShell inference routing instead of adding hosts like `api.openai.com` or `api.anthropic.com` to the network policy. | | Disabling device auth for remote deployments | Without device auth, any device on the network can connect to the gateway without pairing. Combined with a cloudflared tunnel, this makes the dashboard publicly accessible and unauthenticated. | Keep `NEMOCLAW_DISABLE_DEVICE_AUTH` at its default (`0`). Only set it to `1` for local headless or development environments. | diff --git a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md index ba81724b8f..b38da40332 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 sandbox hardening, container security, docker capabilities, process limits, nemoclaw telegram, telegram bot openclaw agent, openshell channel messaging." +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 telegram, telegram bot openclaw agent, openshell channel messaging, nemoclaw sandbox hardening, container security, docker capabilities, process limits." --- @@ -18,8 +18,6 @@ description: "Explains how to run NemoClaw on a remote GPU instance, including t - The [Brev CLI](https://brev.nvidia.com) installed and authenticated. - A provider credential for the inference backend you want to use during onboarding. - NemoClaw installed locally if you plan to use the deprecated `nemoclaw deploy` wrapper. Otherwise, install NemoClaw directly on the remote host after provisioning it. -- A machine where you can run `nemoclaw onboard` (local or remote host that runs the gateway and sandbox). -- A Telegram bot token from [BotFather](https://t.me/BotFather). Run NemoClaw on a remote GPU instance through [Brev](https://brev.nvidia.com). The preferred path is to provision the VM, run the standard NemoClaw installer on that host, and then run `nemoclaw onboard`. @@ -121,6 +119,7 @@ $ nemoclaw onboard ``` These values are baked into the sandbox image at build time. +They are also forwarded into the runtime container during sandbox creation, so `/tmp/nemoclaw-proxy-env.sh` uses the same host and port that the image build used. Only alphanumeric characters, dots, hyphens, and colons are accepted for the host. The port must be numeric (0-65535). Changing the proxy after onboarding requires re-running `nemoclaw onboard`. @@ -136,163 +135,10 @@ $ export NEMOCLAW_GPU="a2-highgpu-1g:nvidia-tesla-a100:2" $ nemoclaw deploy ``` ---- - -OpenClaw plugins extend the OpenClaw runtime with hooks, services, tools, or -provider integrations. They are different from NemoClaw-managed agent skills: - -- **Plugins** are code packages loaded by OpenClaw. -- **Skills** are `SKILL.md` directories that teach an agent how to perform a task. -- **Policy presets** are network-egress rules that control what sandboxed code can reach. - -Today, the supported NemoClaw path for OpenClaw plugins is to bake the plugin -into a custom sandbox image and onboard from that Dockerfile. - -## Step 9: Prepare a Build Directory - -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. - -```text -my-plugin-sandbox/ -├── Dockerfile -└── my-plugin/ - ├── package.json - └── src/ -``` - -## Step 10: Example Dockerfile - -Use the custom image to copy the plugin into the OpenClaw extensions directory -and let OpenClaw refresh its config before NemoClaw starts the sandbox. - -```dockerfile -ARG SANDBOX_BASE=ghcr.io/nvidia/nemoclaw/sandbox-base:latest -FROM ${SANDBOX_BASE} - -COPY my-plugin/ /opt/my-plugin/ -WORKDIR /opt/my-plugin -RUN npm ci --no-audit --no-fund && npm run build - -RUN mkdir -p /sandbox/.openclaw/extensions \ - && cp -a /opt/my-plugin /sandbox/.openclaw/extensions/my-plugin \ - && openclaw doctor --fix - -WORKDIR /opt/nemoclaw -``` - -If the plugin needs configuration in `openclaw.json`, apply it after -`openclaw doctor --fix` so the base config exists first. - -## Step 11: Create the Sandbox - -Point `nemoclaw onboard --from` at the Dockerfile in the build directory. - -```console -$ nemoclaw onboard --from ./my-plugin-sandbox/Dockerfile -``` - -If you need a second sandbox alongside an existing one, use a dedicated build -directory and rerun onboarding with the sandbox name and ports you intend to -use. - -## Step 12: Network Access - -Plugins still run inside the sandbox policy boundary. If a plugin needs network -egress, add or update a policy preset for the required hostnames and binaries -before rebuilding the sandbox. - -For example, see Network Policies (use the `nemoclaw-user-reference` skill) for -policy concepts and Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) -for custom preset workflows. - -## Step 13: Common Mistakes - -These are the most common places where plugin installation gets mixed up with -other NemoClaw extension paths. - -- 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. -- Keep plugin dependencies in the build stage or plugin directory; avoid copying - unrelated host files into the sandbox image. - ---- - -Telegram, Discord, and Slack reach your agent through OpenShell-managed processes and gateway constructs. -NemoClaw configures those channels during `nemoclaw onboard`. Tokens are registered with OpenShell providers, channel configuration is baked into the sandbox image, and runtime delivery stays under OpenShell control. - -`nemoclaw tunnel start` does not start Telegram (or other chat bridges). It only starts optional host services such as the cloudflared tunnel when that binary is present. (`nemoclaw start` is kept as a deprecated alias.) -For details, refer to Commands (use the `nemoclaw-user-reference` skill). - -## Step 14: Create a Telegram Bot - -Open Telegram and send `/newbot` to [@BotFather](https://t.me/BotFather). -Follow the prompts to create a bot and copy the bot token. - -## Step 15: Provide the Bot Token and Optional Allowlist - -Onboarding reads Telegram credentials from either host environment variables or the NemoClaw credential store (`getCredential` / `saveCredential` in the onboard flow). You do not have to export variables if you enter the token when the wizard asks. - -### Option A: Environment variables (CI, scripts, or before you start the wizard) - -```console -$ export TELEGRAM_BOT_TOKEN= -``` - -Optional comma-separated allowlist (maps to the wizard field “Telegram User ID (for DM access)”): - -```console -$ export TELEGRAM_ALLOWED_IDS="123456789,987654321" -``` - -### Option B: Interactive `nemoclaw onboard` - -When the wizard reaches **Messaging channels**, it lists Telegram, Discord, and Slack. -Press **1** to toggle Telegram on or off, then **Enter** when done. -If the token is not already in the environment or credential store, the wizard prompts for it and saves it to the store. -If `TELEGRAM_ALLOWED_IDS` is not set, the wizard can prompt for allowed sender IDs for Telegram DMs (you can leave this blank and rely on OpenClaw pairing instead). -NemoClaw applies that allowlist to Telegram DMs only. -Group chats stay open by default so rebuilt sandboxes do not silently drop Telegram group messages because of an empty group allowlist. - -## Step 16: Run `nemoclaw onboard` - -Complete the rest of the wizard so the blueprint can create OpenShell providers (for example `-telegram-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. - -Channel entries in `/sandbox/.openclaw/openclaw.json` are baked into the container image at build time. Changes made inside the running sandbox do not persist across rebuilds. - -If you add or change `TELEGRAM_BOT_TOKEN` (or toggle channels) after a sandbox already exists, you typically need to run `nemoclaw onboard` again so the image and provider attachments are rebuilt with the new settings. - -NemoClaw stores a SHA-256 hash of each messaging token in the sandbox registry at creation time. -When you re-run `nemoclaw onboard --non-interactive` with a new token, NemoClaw detects the change, backs up workspace state, deletes the sandbox, recreates it with the new credential, and restores the backup. -This makes credential rotation safe to script. - -Telegram, Discord, and Slack each allow only one active consumer per bot token. -If you enable a messaging channel and another sandbox already uses the same token, onboard prompts you to confirm before continuing in interactive mode and exits non-zero in non-interactive mode. -`nemoclaw status` also reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping. - -For a full first-time flow, refer to Quickstart (use the `nemoclaw-user-get-started` skill). - -## Step 17: Confirm Delivery - -After the sandbox is running, send a message to your bot in Telegram. -If something fails, use `openshell term` on the host, check gateway logs, and verify network policy allows the Telegram API (see Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) and the `telegram` preset). - -## Step 18: `nemoclaw tunnel start` (cloudflared Only) - -`nemoclaw tunnel start` starts cloudflared when it is installed, which can expose the dashboard with a public URL. -It does not affect Telegram connectivity. The older `nemoclaw start` still works as a deprecated alias. - -```console -$ nemoclaw tunnel start -``` - -To pause the Telegram bridge without removing its credentials or destroying the sandbox, use `nemoclaw channels stop telegram`. Re-enable it later with `nemoclaw channels start telegram`. - ## 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/set-up-telegram-bridge.md](references/set-up-telegram-bridge.md)** when setting up Telegram, a chat interface, or messaging integration without relying on nemoclaw tunnel start for bridges. Explains how Telegram reaches the sandboxed OpenClaw agent through OpenShell-managed processes and onboarding-time channel configuration. - **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. ## Related Skills 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 new file mode 100644 index 0000000000..cc4edd05ac --- /dev/null +++ b/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md @@ -0,0 +1,93 @@ + + +# Install OpenClaw Plugins + +OpenClaw plugins extend the OpenClaw runtime with hooks, services, tools, or +provider integrations. They are different from NemoClaw-managed agent skills: + +- **Plugins** are code packages loaded by OpenClaw. +- **Skills** are `SKILL.md` directories that teach an agent how to perform a task. +- **Policy presets** are network-egress rules that control what sandboxed code can reach. + +Today, the supported NemoClaw path for OpenClaw plugins is to bake the plugin +into a custom sandbox image and onboard from that Dockerfile. + +## Prepare a Build Directory + +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. + +```text +my-plugin-sandbox/ +├── Dockerfile +└── my-plugin/ + ├── package.json + └── src/ +``` + +## Example Dockerfile + +Use the custom image to copy the plugin into the OpenClaw extensions directory +and let OpenClaw refresh its config before NemoClaw starts the sandbox. + +```dockerfile +ARG SANDBOX_BASE=ghcr.io/nvidia/nemoclaw/sandbox-base:latest +FROM ${SANDBOX_BASE} + +COPY my-plugin/ /opt/my-plugin/ +WORKDIR /opt/my-plugin +RUN npm ci --no-audit --no-fund && npm run build + +RUN mkdir -p /sandbox/.openclaw/extensions \ + && cp -a /opt/my-plugin /sandbox/.openclaw/extensions/my-plugin \ + && openclaw doctor --fix + +WORKDIR /opt/nemoclaw +``` + +If the plugin needs configuration in `openclaw.json`, apply it after +`openclaw doctor --fix` so the base config exists first. + +## Create the Sandbox + +Point `nemoclaw onboard --from` at the Dockerfile in the build directory. + +```console +$ nemoclaw onboard --from ./my-plugin-sandbox/Dockerfile +``` + +If you need a second sandbox alongside an existing one, use a dedicated build +directory and rerun onboarding with the sandbox name and ports you intend to +use. + +## Network Access + +Plugins still run inside the sandbox policy boundary. If a plugin needs network +egress, add or update a policy preset for the required hostnames and binaries +before rebuilding the sandbox. + +For example, see Network Policies (use the `nemoclaw-user-reference` skill) for +policy concepts and Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) +for custom preset workflows. + +## Common Mistakes + +These are the most common places where plugin installation gets mixed up with +other NemoClaw extension paths. + +- 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. +- Keep plugin dependencies in the build stage or plugin directory; avoid copying + unrelated host files into the sandbox image. + +## Next Steps + +- Review Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill) before adding plugin code to a + shared or long-lived sandbox. +- Review Network Policies (use the `nemoclaw-user-reference` skill) to plan plugin + egress rules. +- Follow Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) + if the plugin needs a custom preset. diff --git a/.agents/skills/nemoclaw-user-deploy-remote/references/set-up-telegram-bridge.md b/.agents/skills/nemoclaw-user-deploy-remote/references/set-up-telegram-bridge.md new file mode 100644 index 0000000000..58fdd7a304 --- /dev/null +++ b/.agents/skills/nemoclaw-user-deploy-remote/references/set-up-telegram-bridge.md @@ -0,0 +1,84 @@ + + +# Set Up Telegram + +Telegram, Discord, and Slack reach your agent through OpenShell-managed processes and gateway constructs. +NemoClaw configures those channels during `nemoclaw onboard`. Tokens are registered with OpenShell providers, channel configuration is baked into the sandbox image, and runtime delivery stays under OpenShell control. + +`nemoclaw tunnel start` does not start Telegram (or other chat bridges). It only starts optional host services such as the cloudflared tunnel when that binary is present. (`nemoclaw start` is kept as a deprecated alias.) +For details, refer to Commands (use the `nemoclaw-user-reference` skill). + +## Prerequisites + +- A machine where you can run `nemoclaw onboard` (local or remote host that runs the gateway and sandbox). +- A Telegram bot token from [BotFather](https://t.me/BotFather). + +## Create a Telegram Bot + +Open Telegram and send `/newbot` to [@BotFather](https://t.me/BotFather). +Follow the prompts to create a bot and copy the bot token. + +## Provide the Bot Token and Optional Allowlist + +Onboarding reads Telegram credentials from either host environment variables or the NemoClaw credential store (`getCredential` / `saveCredential` in the onboard flow). You do not have to export variables if you enter the token when the wizard asks. + +### Option A: Environment variables (CI, scripts, or before you start the wizard) + +```console +$ export TELEGRAM_BOT_TOKEN= +``` + +Optional comma-separated allowlist (maps to the wizard field “Telegram User ID (for DM access)”): + +```console +$ export TELEGRAM_ALLOWED_IDS="123456789,987654321" +``` + +### Option B: Interactive `nemoclaw onboard` + +When the wizard reaches **Messaging channels**, it lists Telegram, Discord, and Slack. +Press **1** to toggle Telegram on or off, then **Enter** when done. +If the token is not already in the environment or credential store, the wizard prompts for it and saves it to the store. +If `TELEGRAM_ALLOWED_IDS` is not set, the wizard can prompt for allowed sender IDs for Telegram DMs (you can leave this blank and rely on OpenClaw pairing instead). +NemoClaw applies that allowlist to Telegram DMs only. +Group chats stay open by default so rebuilt sandboxes do not silently drop Telegram group messages because of an empty group allowlist. + +## Run `nemoclaw onboard` + +Complete the rest of the wizard so the blueprint can create OpenShell providers (for example `-telegram-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. + +Channel entries in `/sandbox/.openclaw/openclaw.json` are baked into the container image at build time. Changes made inside the running sandbox do not persist across rebuilds. + +If you add or change `TELEGRAM_BOT_TOKEN` (or toggle channels) after a sandbox already exists, you typically need to run `nemoclaw onboard` again so the image and provider attachments are rebuilt with the new settings. + +NemoClaw stores a SHA-256 hash of each messaging token in the sandbox registry at creation time. +When you re-run `nemoclaw onboard --non-interactive` with a new token, NemoClaw detects the change, backs up workspace state, deletes the sandbox, recreates it with the new credential, and restores the backup. +This makes credential rotation safe to script. + +Telegram, Discord, and Slack each allow only one active consumer per bot token. +If you enable a messaging channel and another sandbox already uses the same token, onboard prompts you to confirm before continuing in interactive mode and exits non-zero in non-interactive mode. +`nemoclaw status` also reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping. + +For a full first-time flow, refer to Quickstart (use the `nemoclaw-user-get-started` skill). + +## Confirm Delivery + +After the sandbox is running, send a message to your bot in Telegram. +If something fails, use `openshell term` on the host, check gateway logs, and verify network policy allows the Telegram API (see Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) and the `telegram` preset). + +## `nemoclaw tunnel start` (cloudflared Only) + +`nemoclaw tunnel start` starts cloudflared when it is installed, which can expose the dashboard with a public URL. +It does not affect Telegram connectivity. The older `nemoclaw start` still works as a deprecated alias. + +```console +$ nemoclaw tunnel start +``` + +To pause the Telegram bridge without removing its credentials or destroying the sandbox, use `nemoclaw channels stop telegram`. Re-enable it later with `nemoclaw channels start telegram`. + +## Related Topics + +- Deploy NemoClaw to a Remote GPU Instance (use the `nemoclaw-user-deploy-remote` skill) for remote deployment with messaging. +- Architecture (use the `nemoclaw-user-reference` skill) for how providers, the gateway, and the sandbox fit together. +- Commands (use the `nemoclaw-user-reference` skill) for `tunnel start`, `tunnel stop`, `channels start`, `channels stop`, and `status`. diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md index 334504c0c8..340d4d8436 100644 --- a/.agents/skills/nemoclaw-user-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -1,12 +1,12 @@ --- name: "nemoclaw-user-get-started" -description: "Lists the hardware, software, and container runtime requirements for running NemoClaw. Use when verifying prerequisites before installation. Trigger keywords - nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw quickstart, install nemoclaw openclaw sandbox, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop." +description: "Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop." --- -# NemoClaw Prerequisites +# NemoClaw Quickstart: Install, Launch, and Run Your First Agent ## Gotchas @@ -70,7 +70,7 @@ Respond to the wizard as follows. 1. At the `Choose [1]:` prompt, press Enter (or type `1`) to select **NVIDIA Endpoints**. 2. At the `NVIDIA_API_KEY:` prompt, paste your key if it is not already exported. -3. At the `Choose model [1]:` prompt, pick a curated model from the list (for example, **Nemotron 3 Super 120B**, **Kimi K2.5**, **GLM-5.1**, **MiniMax M2.5**, or **GPT-OSS 120B**), or pick **Other...** to enter any model ID from the [NVIDIA Endpoints catalog](https://build.nvidia.com). +3. At the `Choose model [1]:` prompt, pick a curated model from the list (for example, **Nemotron 3 Super 120B**, **GLM-5.1**, **MiniMax M2.5**, or **GPT-OSS 120B**), or pick **Other...** to enter any model ID from the [NVIDIA Endpoints catalog](https://build.nvidia.com). NemoClaw validates the model against the catalog API before creating the sandbox. @@ -252,16 +252,24 @@ openshell forward list ### Run Multiple Sandboxes -Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using. Override the port with `CHAT_UI_URL` at onboard time — the dashboard port is derived automatically. +Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using. +When the default port is already held by another sandbox, `nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port. ```console $ nemoclaw onboard # first sandbox uses 18789 -$ CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard # second sandbox uses 19000 +$ nemoclaw onboard # second sandbox uses the next free port ``` -You can also use `NEMOCLAW_DASHBOARD_PORT` directly if you prefer: +To choose a specific port, pass `--control-ui-port`: ```console +$ nemoclaw onboard --control-ui-port 19000 +``` + +You can also set `CHAT_UI_URL` or `NEMOCLAW_DASHBOARD_PORT` before onboarding: + +```console +$ CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard $ NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard ``` diff --git a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md index cc4e169559..a5cb986cd7 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md @@ -8,15 +8,10 @@ description: "Reviews and approves blocked agent network requests in the TUI. Us # Approve or Deny NemoClaw Agent Network Requests -## Gotchas - -- Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations. - ## Prerequisites - A running NemoClaw sandbox. - The OpenShell CLI on your `PATH`. -- A running NemoClaw sandbox for dynamic changes, or the NemoClaw source repository for static changes. Review and act on network requests that the agent makes to endpoints not listed in the sandbox policy. OpenShell intercepts these requests and presents them in the TUI for operator approval. @@ -67,271 +62,11 @@ $ ./scripts/walkthrough.sh This script opens a split tmux session with the TUI on the left and the agent on the right. The walkthrough requires tmux and the `NVIDIA_API_KEY` environment variable. ---- - -Add, remove, or modify the endpoints that the sandbox is allowed to reach. - -The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). -NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI. - -> **Note:** If the sandbox needs to reach an HTTP service running on the host, expose the service on a host IP that the OpenShell gateway can reach. -> Apply a custom NemoClaw preset with `nemoclaw policy-add --from-file`. -> Do not rely on `host.docker.internal` as a general host-service path because it bypasses the OpenShell policy path and may not be reachable in every sandbox runtime. -> See Agent cannot reach a host-side HTTP service (use the `nemoclaw-user-reference` skill). - -## Step 5: Static Changes - -Static changes modify the baseline policy file and take effect after the next sandbox creation. - -### Edit the Policy File - -Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries. - -If you only need one of the built-in presets, use `nemoclaw policy-add` instead of editing YAML by hand: - -```console -$ nemoclaw my-assistant policy-add -``` - -To remove a previously applied preset, use `nemoclaw policy-remove`: - -```console -$ nemoclaw my-assistant policy-remove -``` - -Use a manual YAML edit when you need to allow custom hosts that are not covered by a preset, such as an internal API or a weather service. - -Each entry in the `network` section defines an endpoint group with the following fields: - -`endpoints` -: Host and port pairs that the sandbox can reach. - -`binaries` -: Executables allowed to use this endpoint. - -`rules` -: HTTP methods and paths that are permitted. - -### Re-Run Onboard - -Apply the updated policy by re-running the onboard wizard: - -```console -$ nemoclaw onboard -``` - -The wizard picks up the modified policy file and applies it to the sandbox. - -### Verify the Policy - -Check that the sandbox is running with the updated policy: - -```console -$ nemoclaw status -``` - -## Step 6: Dynamic Changes - -Dynamic changes apply a policy update to a running sandbox without restarting it. - -> [!WARNING] -> `openshell policy set` **replaces** the sandbox's live policy with the contents of the file you provide; it does not merge. -> A running sandbox's live policy is the baseline from `openclaw-sandbox.yaml` plus every preset that was layered on during onboarding. -> Applying a file that contains only the baseline (or only a single preset) silently drops every other preset that was in effect. - -### Option 1: Drop a Preset File and Use `policy-add` (Recommended) - -This is the non-destructive path and the only flow NemoClaw supports out of the box for merging new entries into a running policy. - -1. Create a preset-format YAML file under `nemoclaw-blueprint/policies/presets/`, for example `nemoclaw-blueprint/policies/presets/influxdb.yaml`: - - ```yaml - preset: - name: influxdb - description: "InfluxDB time-series database" - network_policies: - influxdb: - name: influxdb - endpoints: - - host: influxdb.internal.example.com - port: 8086 - protocol: rest - enforcement: enforce - tls: terminate - rules: - - allow: { method: GET, path: "/**" } - - allow: { method: POST, path: "/api/v2/write" } - binaries: - - { path: /usr/bin/curl } - ``` - -2. Apply it to the running sandbox: - - ```console - $ nemoclaw my-assistant policy-add - ``` - - NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. - Existing presets and the baseline remain in place. - The preset file under `presets/` also persists across sandbox recreations. - -### Option 2: Snapshot, Edit, and Set via OpenShell - -Use this path only when you cannot add a file under the NemoClaw source tree. -You must start from the **live** policy, not from `openclaw-sandbox.yaml`, so the presets layered on at onboarding are preserved in the file you apply. - -```console -$ openshell policy get --full my-assistant > live-policy.yaml -``` - -Edit `live-policy.yaml` to add your entries under `network_policies:`, keeping the existing `version` field intact, then apply: - -```console -$ openshell policy set --policy live-policy.yaml my-assistant -``` - -### Scope of Dynamic Changes - -Dynamic changes apply only to the current session. -When the sandbox stops, the running policy resets to the baseline composed from `openclaw-sandbox.yaml` plus the presets recorded for the sandbox. -To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above — the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. - -### Approve Requests Interactively - -For one-off access, you can approve blocked requests in the OpenShell TUI instead of editing the baseline policy: - -```console -$ openshell term -``` - -This is useful when you want to test a destination before deciding whether it belongs in a permanent preset or custom policy file. - -## Step 7: Policy Presets - -NemoClaw ships preset policy files for common integrations in `nemoclaw-blueprint/policies/presets/`. -Apply a preset as-is or use it as a starting template for a custom policy. - -During onboarding, the policy tier (use the `nemoclaw-user-reference` skill) you select determines which presets are enabled by default. -You can add or remove individual presets in the interactive preset screen that follows tier selection. - -Available presets: - -| Preset | Endpoints | -|--------|-----------| -| `brave` | Brave Search API | -| `brew` | Homebrew (Linuxbrew) package manager | -| `discord` | Discord webhook API | -| `github` | GitHub and GitHub REST API | -| `huggingface` | Hugging Face Hub (download-only) and inference router | -| `jira` | Atlassian Jira API | -| `npm` | npm and Yarn registries | -| `outlook` | Microsoft 365 and Outlook | -| `pypi` | Python Package Index | -| `slack` | Slack API and webhooks | -| `telegram` | Telegram Bot API | - -To apply a preset to a running sandbox: - -```console -$ nemoclaw policy-add -``` - -> **Note:** Preset selection is interactive. -> Positional preset arguments are ignored. - -For example, to interactively add PyPI access to a running sandbox: - -```console -$ nemoclaw my-assistant policy-add -``` - -To list which presets are applied to a sandbox: - -```console -$ nemoclaw policy-list -``` - -To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. - -> **Note:** The `openshell policy set --policy ` command operates on raw policy files and does not -> accept the `preset:` metadata block used in preset YAML files. Use `nemoclaw policy-add` for -> presets. - -For scripted workflows, `policy-add` and `policy-remove` accept the preset name as a positional argument: - -```console -$ nemoclaw my-assistant policy-add pypi --yes -$ nemoclaw my-assistant policy-remove pypi --yes -``` - -Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to drive the same flow from an environment variable. -See Commands (use the `nemoclaw-user-reference` skill) for the full flag reference. - -`nemoclaw rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. - -## Step 8: Custom Preset Files - -Apply a user-authored preset YAML to a running sandbox without editing the baseline or dropping to `openshell policy set`. - -### Authoring - -A custom preset follows the same shape as the built-in ones under `nemoclaw-blueprint/policies/presets/`: - -```yaml -preset: - name: my-internal-api - description: "Internal service" -network_policies: - my-internal-api: - name: my-internal-api - endpoints: - - host: api.example.internal - port: 443 - protocol: rest - enforcement: enforce - rules: - - allow: { method: GET, path: "/**" } - binaries: - - { path: /usr/local/bin/node } -``` - -The top-level `preset.name` must be a lowercase RFC 1123 label (letters, digits, hyphens) and must not collide with a built-in preset name such as `slack` or `pypi`. -Rename `preset.name` if NemoClaw refuses to apply the file because of a collision. - -### Apply a Single File - -```console -$ nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml -``` - -Preview the endpoints without applying with `--dry-run`, and skip the confirmation prompt with `--yes` or by exporting `NEMOCLAW_NON_INTERACTIVE=1`. - -### Apply Every File in a Directory - -```console -$ nemoclaw my-assistant policy-add --from-dir ./presets/ --yes -``` - -Files are processed in lexicographic order. -Processing stops at the first failure; presets already applied are not rolled back. -Fix the failing file and re-run the command to continue. - -> **Warning:** Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations. -> Review every host in a custom preset before applying it, especially when the file originates outside your team. - -### Remove a Custom Preset - -Custom presets applied with `--from-file` or `--from-dir` are recorded in the NemoClaw sandbox registry alongside their full YAML content, so they can be removed by name — the original file does not need to be kept on disk: - -```console -$ nemoclaw my-assistant policy-remove my-internal-api --yes -``` +## References -`policy-remove` accepts both built-in and custom preset names. Run `nemoclaw policy-list` to see every preset currently applied to the sandbox. +- **Load [references/customize-network-policy.md](references/customize-network-policy.md)** when customizing network policy, changing egress rules, or configuring sandbox endpoint access. Adds, removes, or modifies allowed endpoints in the sandbox policy. ## Related Skills - `nemoclaw-user-reference` — Network Policies (use the `nemoclaw-user-reference` skill) for the full baseline policy reference - `nemoclaw-user-monitor-sandbox` — Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) for general sandbox monitoring -- OpenShell [Policy Schema](https://docs.nvidia.com/openshell/latest/reference/policy-schema.html) for the full YAML policy schema reference. -- OpenShell [Sandbox Policies](https://docs.nvidia.com/openshell/latest/sandboxes/policies.html) for applying, iterating, and debugging policies at the OpenShell layer. diff --git a/.agents/skills/nemoclaw-user-manage-policy/references/customize-network-policy.md b/.agents/skills/nemoclaw-user-manage-policy/references/customize-network-policy.md new file mode 100644 index 0000000000..f7af2e330c --- /dev/null +++ b/.agents/skills/nemoclaw-user-manage-policy/references/customize-network-policy.md @@ -0,0 +1,280 @@ + + +# Customize the Sandbox Network Policy + +Add, remove, or modify the endpoints that the sandbox is allowed to reach. + +The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). +NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI. + +> **Note:** If the sandbox needs to reach an HTTP service running on the host, expose the service on a host IP that the OpenShell gateway can reach. +> Apply a custom NemoClaw preset with `nemoclaw policy-add --from-file`. +> Do not rely on `host.docker.internal` as a general host-service path because it bypasses the OpenShell policy path and may not be reachable in every sandbox runtime. +> See Agent cannot reach a host-side HTTP service (use the `nemoclaw-user-reference` skill). + +## Prerequisites + +- A running NemoClaw sandbox for dynamic changes, or the NemoClaw source repository for static changes. +- The OpenShell CLI on your `PATH`. + +> [!IMPORTANT] +> Make static policy edits on the host, not inside the sandbox. +> The sandbox image is intentionally minimal and may not include editors or package-management tools. +> Changes made only inside the sandbox are also ephemeral and are lost when the sandbox is recreated. + +## Static Changes + +Static changes modify the baseline policy file and take effect after the next sandbox creation. + +### Edit the Policy File + +Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries. + +If you only need one of the built-in presets, use `nemoclaw policy-add` instead of editing YAML by hand: + +```console +$ nemoclaw my-assistant policy-add +``` + +To remove a previously applied preset, use `nemoclaw policy-remove`: + +```console +$ nemoclaw my-assistant policy-remove +``` + +Use a manual YAML edit when you need to allow custom hosts that are not covered by a preset, such as an internal API or a weather service. + +Each entry in the `network` section defines an endpoint group with the following fields: + +`endpoints` +: Host and port pairs that the sandbox can reach. + +`binaries` +: Executables allowed to use this endpoint. + +`rules` +: HTTP methods and paths that are permitted. + +### Re-Run Onboard + +Apply the updated policy by re-running the onboard wizard: + +```console +$ nemoclaw onboard +``` + +The wizard picks up the modified policy file and applies it to the sandbox. + +### Verify the Policy + +Check that the sandbox is running with the updated policy: + +```console +$ nemoclaw status +``` + +## Dynamic Changes + +Dynamic changes apply a policy update to a running sandbox without restarting it. + +> [!WARNING] +> `openshell policy set` **replaces** the sandbox's live policy with the contents of the file you provide; it does not merge. +> A running sandbox's live policy is the baseline from `openclaw-sandbox.yaml` plus every preset that was layered on during onboarding. +> Applying a file that contains only the baseline (or only a single preset) silently drops every other preset that was in effect. + +### Option 1: Drop a Preset File and Use `policy-add` (Recommended) + +This is the non-destructive path and the only flow NemoClaw supports out of the box for merging new entries into a running policy. + +1. Create a preset-format YAML file under `nemoclaw-blueprint/policies/presets/`, for example `nemoclaw-blueprint/policies/presets/influxdb.yaml`: + + ```yaml + preset: + name: influxdb + description: "InfluxDB time-series database" + network_policies: + influxdb: + name: influxdb + endpoints: + - host: influxdb.internal.example.com + port: 8086 + protocol: rest + enforcement: enforce + tls: terminate + rules: + - allow: { method: GET, path: "/**" } + - allow: { method: POST, path: "/api/v2/write" } + binaries: + - { path: /usr/bin/curl } + ``` + +2. Apply it to the running sandbox: + + ```console + $ nemoclaw my-assistant policy-add + ``` + + NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. + Existing presets and the baseline remain in place. + The preset file under `presets/` also persists across sandbox recreations. + +### Option 2: Snapshot, Edit, and Set via OpenShell + +Use this path only when you cannot add a file under the NemoClaw source tree. +You must start from the **live** policy, not from `openclaw-sandbox.yaml`, so the presets layered on at onboarding are preserved in the file you apply. + +```console +$ openshell policy get --full my-assistant > live-policy.yaml +``` + +Edit `live-policy.yaml` to add your entries under `network_policies:`, keeping the existing `version` field intact, then apply: + +```console +$ openshell policy set --policy live-policy.yaml my-assistant +``` + +### Scope of Dynamic Changes + +Dynamic changes apply only to the current session. +When the sandbox stops, the running policy resets to the baseline composed from `openclaw-sandbox.yaml` plus the presets recorded for the sandbox. +To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above — the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. + +### Approve Requests Interactively + +For one-off access, you can approve blocked requests in the OpenShell TUI instead of editing the baseline policy: + +```console +$ openshell term +``` + +This is useful when you want to test a destination before deciding whether it belongs in a permanent preset or custom policy file. + +## Policy Presets + +NemoClaw ships preset policy files for common integrations in `nemoclaw-blueprint/policies/presets/`. +Apply a preset as-is or use it as a starting template for a custom policy. + +During onboarding, the policy tier (use the `nemoclaw-user-reference` skill) you select determines which presets are enabled by default. +You can add or remove individual presets in the interactive preset screen that follows tier selection. + +Available presets: + +| Preset | Endpoints | +|--------|-----------| +| `brave` | Brave Search API | +| `brew` | Homebrew (Linuxbrew) package manager | +| `discord` | Discord webhook API | +| `github` | GitHub and GitHub REST API | +| `huggingface` | Hugging Face Hub (download-only) and inference router | +| `jira` | Atlassian Jira API | +| `npm` | npm and Yarn registries | +| `outlook` | Microsoft 365 and Outlook | +| `pypi` | Python Package Index | +| `slack` | Slack API and webhooks | +| `telegram` | Telegram Bot API | + +To apply a preset to a running sandbox: + +```console +$ nemoclaw policy-add +``` + +> **Note:** Preset selection is interactive. +> Positional preset arguments are ignored. + +For example, to interactively add PyPI access to a running sandbox: + +```console +$ nemoclaw my-assistant policy-add +``` + +To list which presets are applied to a sandbox: + +```console +$ nemoclaw policy-list +``` + +To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. + +> **Note:** The `openshell policy set --policy ` command operates on raw policy files and does not +> accept the `preset:` metadata block used in preset YAML files. Use `nemoclaw policy-add` for +> presets. + +For scripted workflows, `policy-add` and `policy-remove` accept the preset name as a positional argument: + +```console +$ nemoclaw my-assistant policy-add pypi --yes +$ nemoclaw my-assistant policy-remove pypi --yes +``` + +Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to drive the same flow from an environment variable. +See Commands (use the `nemoclaw-user-reference` skill) for the full flag reference. + +`nemoclaw rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. + +## Custom Preset Files + +Apply a user-authored preset YAML to a running sandbox without editing the baseline or dropping to `openshell policy set`. + +### Authoring + +A custom preset follows the same shape as the built-in ones under `nemoclaw-blueprint/policies/presets/`: + +```yaml +preset: + name: my-internal-api + description: "Internal service" +network_policies: + my-internal-api: + name: my-internal-api + endpoints: + - host: api.example.internal + port: 443 + protocol: rest + enforcement: enforce + rules: + - allow: { method: GET, path: "/**" } + binaries: + - { path: /usr/local/bin/node } +``` + +The top-level `preset.name` must be a lowercase RFC 1123 label (letters, digits, hyphens) and must not collide with a built-in preset name such as `slack` or `pypi`. +Rename `preset.name` if NemoClaw refuses to apply the file because of a collision. + +### Apply a Single File + +```console +$ nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml +``` + +Preview the endpoints without applying with `--dry-run`, and skip the confirmation prompt with `--yes` or by exporting `NEMOCLAW_NON_INTERACTIVE=1`. + +### Apply Every File in a Directory + +```console +$ nemoclaw my-assistant policy-add --from-dir ./presets/ --yes +``` + +Files are processed in lexicographic order. +Processing stops at the first failure; presets already applied are not rolled back. +Fix the failing file and re-run the command to continue. + +> **Warning:** Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations. +> Review every host in a custom preset before applying it, especially when the file originates outside your team. + +### Remove a Custom Preset + +Custom presets applied with `--from-file` or `--from-dir` are recorded in the NemoClaw sandbox registry alongside their full YAML content, so they can be removed by name — the original file does not need to be kept on disk: + +```console +$ nemoclaw my-assistant policy-remove my-internal-api --yes +``` + +`policy-remove` accepts both built-in and custom preset names. Run `nemoclaw policy-list` to see every preset currently applied to the sandbox. + +## Related Topics + +- Approve or Deny Agent Network Requests (use the `nemoclaw-user-manage-policy` skill) for real-time operator approval. +- Network Policies (use the `nemoclaw-user-reference` skill) for the full baseline policy reference. +- OpenShell [Policy Schema](https://docs.nvidia.com/openshell/latest/reference/policy-schema.html) for the full YAML policy schema reference. +- OpenShell [Sandbox Policies](https://docs.nvidia.com/openshell/latest/sandboxes/policies.html) for applying, iterating, and debugging policies at the OpenShell layer. diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index 17626944eb..02a345e63b 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -105,6 +105,8 @@ $ BRAVE_API_KEY=... \ ``` `BRAVE_API_KEY` enables Brave Search in non-interactive mode and also enables `web_fetch`. +If Brave Search key validation fails in non-interactive mode, onboarding prints a warning, skips web search setup, and continues with the rest of the sandbox setup. +After fixing the key, re-enable web search with `nemoclaw config web-search`. The wizard prompts for a sandbox name. Names must follow RFC 1123 subdomain rules: lowercase alphanumeric characters and hyphens only, and must start and end with an alphanumeric character. @@ -139,23 +141,52 @@ If the installed OpenShell version falls outside this range, onboarding exits wi 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 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. ```console $ nemoclaw onboard --from path/to/Dockerfile ``` +The Dockerfile path must exist. +Missing paths fail during command parsing before preflight, gateway setup, inference setup, or sandbox creation starts. + The file can have any name; if it is not already named `Dockerfile`, onboard copies it to `Dockerfile` inside the staged build context automatically. +To create an isolated build context, create a dedicated directory that contains only the Dockerfile and the files it needs: + +```text +build-dir/ +├── Dockerfile +└── files-used-by-COPY/ +``` + All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_PROVIDER_KEY`, `NEMOCLAW_INFERENCE_BASE_URL`, etc.) are injected as `ARG` overrides at build time, so declare them in your Dockerfile if you need to reference them. -In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DOCKERFILE` environment variable: +In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DOCKERFILE` environment variable. +You must also supply a sandbox name via `--name ` or `NEMOCLAW_SANDBOX_NAME` so a `--from` build cannot silently clobber the default `my-assistant` sandbox. ```console -$ NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile nemoclaw onboard +$ NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build nemoclaw onboard ``` If a `--resume` is attempted with a different `--from` path than the original session, onboarding exits with a conflict error rather than silently building from the wrong image. +#### `--name ` + +Set the sandbox name without going through the interactive prompt. +The same RFC 1123 and reserved-name rules that the wizard enforces apply here too — names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front. + +```console +$ nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile +``` + +The flag wins over `NEMOCLAW_SANDBOX_NAME`. +When prompting is impossible (no TTY or `--non-interactive`), the env var is also honoured so existing CI scripts keep working. +Combining `--from ` with non-interactive onboarding requires one of `--name` or `NEMOCLAW_SANDBOX_NAME`; otherwise onboarding exits rather than silently defaulting to `my-assistant` and clobbering the default sandbox. + ### `nemoclaw onboard --from` Use a custom Dockerfile for the sandbox image. @@ -169,6 +200,7 @@ $ nemoclaw onboard --from ./Dockerfile.custom List all registered sandboxes with their model, provider, and policy presets. 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. ```console $ nemoclaw list @@ -221,8 +253,10 @@ The command probes every inference provider and reports one of three states on t Local providers (Ollama, vLLM) probe the host-side health endpoint. Remote providers (NVIDIA Endpoints, OpenAI, Anthropic, Gemini) use a lightweight reachability check; any HTTP response, including `401` or `403`, counts as reachable. No API keys are sent. +For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running. A `Connected` line reports whether the sandbox has any active SSH sessions and, if so, how many. +The sandbox list in the status output includes the dashboard port suffix for sandboxes with a recorded dashboard port. The Policy section displays the live enforced policy (fetched via `openshell policy get --full`), which reflects presets added or removed after sandbox creation. If the sandbox is running an outdated agent version, the output includes an `Update` line with the available version and a `nemoclaw rebuild` hint. @@ -238,6 +272,8 @@ $ nemoclaw my-assistant status View sandbox logs. Use `--follow` to stream output in real time. +The command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear alongside the gateway log stream. +If one log source is unavailable, NemoClaw prints a warning and keeps reading the remaining source. ```console $ nemoclaw my-assistant logs [--follow] @@ -444,6 +480,8 @@ $ nemoclaw my-assistant skill install ./my-skill/ The skill directory must contain a `SKILL.md` file with YAML frontmatter that includes a `name` field. Skill names must contain only alphanumeric characters, dots, hyphens, and underscores. OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see Install OpenClaw Plugins (use the `nemoclaw-user-deploy-remote` skill). +Run `nemoclaw skill install --help` to print usage for this subcommand. +If you pass a plugin-shaped directory to `skill install`, the CLI prints a plugin-specific hint instead of treating it as a missing skill file. Files with names starting with `.` (dotfiles) are skipped and listed in the output. Files with unsafe path characters are rejected to prevent shell injection. @@ -753,6 +791,8 @@ $ nemoclaw onboard These overrides apply to onboarding, status checks, health probes, and the uninstaller. Defaults are unchanged when no variable is set. +If `NEMOCLAW_DASHBOARD_PORT` or the port from `CHAT_UI_URL` is already occupied by another sandbox, onboarding scans `18789` through `18799` and uses the next free dashboard port. +Pass `--control-ui-port ` to require a specific port. ### Legacy `nemoclaw setup` diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 521fa792f3..d9bbd274a7 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -15,6 +15,10 @@ The `nemoclaw` binary is installed but the shell session does not know where to Run `source ~/.bashrc` (or `source ~/.zshrc` for zsh), or open a new terminal window. +When installing from a source checkout with `npm install`, NemoClaw first tries `npm link`. +If the global npm prefix is not writable, it writes a managed shim to `~/.local/bin/nemoclaw` instead. +Add `~/.local/bin` to your `PATH` if the command is still not found. + ### Installer fails on unsupported platform The installer checks for a supported OS and architecture before proceeding. @@ -134,8 +138,10 @@ When the lookup returns an answer, retry onboarding. ### Port already in use The NemoClaw dashboard uses port `18789` by default and the gateway uses port `8080`. -If another process is already bound to one of these ports, onboarding fails. -Identify the conflicting process, verify it is safe to stop, and terminate it: +If another sandbox already owns the dashboard port, onboarding scans ports `18789` through `18799` and uses the next free port. +If all ports in that range are occupied, the error lists the owner for each port and suggests using `--control-ui-port` with a port outside the range. + +If a non-NemoClaw process is already bound to the dashboard port or the gateway port, identify the conflicting process, verify it is safe to stop, and terminate it: ```console $ sudo lsof -i :18789 @@ -146,7 +152,13 @@ If the process does not exit, use `kill -9 ` to force-terminate it. Then retry onboarding. Alternatively, override the conflicting port instead of stopping the other process. -Set `CHAT_UI_URL` with the desired port — the dashboard port is derived automatically: +Pass `--control-ui-port` with the desired dashboard port: + +```console +$ nemoclaw onboard --control-ui-port 19000 +``` + +You can also set `CHAT_UI_URL` with the desired port: ```console $ CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard @@ -163,15 +175,15 @@ See Environment Variables (use the `nemoclaw-user-reference` skill) for the full ### Running multiple sandboxes simultaneously Each sandbox requires its own dashboard port. -If you onboard a second sandbox without overriding the port, onboarding fails with a clear error because port `18789` is already forwarded to the first sandbox. +If you onboard a second sandbox without overriding the port, onboarding uses the next free port in the `18789` to `18799` range. `onboard` checks `openshell forward list` before starting a new forward, so a second onboard cannot silently take over the first sandbox's port. -Assign a distinct port to each sandbox at onboard time. -Set `CHAT_UI_URL` with the desired port — the dashboard port is derived automatically: +Assign a distinct port only when you want a specific value: ```console -$ nemoclaw onboard # first sandbox — uses default 18789 -$ CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard # second sandbox — uses 19000 +$ nemoclaw onboard # first sandbox uses default 18789 +$ nemoclaw onboard # second sandbox uses the next free port +$ nemoclaw onboard --control-ui-port 19000 # explicit port override ``` Each sandbox then has its own SSH tunnel and its own dashboard URL: @@ -185,8 +197,11 @@ You can verify which tunnel belongs to which sandbox with: ```console $ openshell forward list +$ nemoclaw list ``` +`nemoclaw list` prints the recorded dashboard URL for each sandbox. + ## Onboarding ### Cgroup v2 errors during onboard @@ -484,6 +499,16 @@ If they are missing on an older sandbox, upgrade NemoClaw and run: $ nemoclaw rebuild ``` +### Sandbox creation reports a TLS certificate mismatch + +If sandbox creation reports a TLS or certificate mismatch, the OpenShell gateway certificate may have changed since the CLI last trusted it. +Refresh the gateway trust and then resume onboarding: + +```console +$ openshell gateway trust -g nemoclaw +$ nemoclaw onboard --resume +``` + ### `openclaw update` hangs or times out inside the sandbox This is expected for the current NemoClaw deployment model. @@ -511,7 +536,7 @@ If that line shows `unreachable`, start the local backend first and then retry t If the endpoint is correct but requests still fail, check for network policy rules that may block the connection. Then verify the credential and base URL for the provider you selected during onboarding. -For local providers (Ollama, vLLM, NIM), the default timeout is 180 seconds. +For Ollama, vLLM, NIM, and compatible-endpoint setup, the default timeout is 180 seconds. If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` before re-running onboard: ```console @@ -519,6 +544,9 @@ $ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 $ 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 all attempts fail, the error includes container reachability diagnostics such as HTTP status and host gateway resolution. + ### Agent fails at runtime after onboarding succeeds with a compatible endpoint Some OpenAI-compatible servers (such as SGLang) expose `/v1/responses` but their @@ -580,9 +608,10 @@ NemoClaw's sandbox entrypoint installs a guard that intercepts `openclaw config To change your configuration, exit the sandbox and rerun onboarding: ```console -$ nemoclaw onboard --resume +$ nemoclaw onboard ``` +If NemoClaw reports a resumable failed onboarding session, run `nemoclaw onboard --resume` instead. This rebuilds the sandbox with your updated settings. ### `openclaw doctor --fix` cannot repair Discord channel config inside the sandbox @@ -680,6 +709,9 @@ $ nemoclaw onboard These are build-time settings baked into the sandbox image. Changing them after onboarding requires re-running `nemoclaw onboard` to rebuild the image. +When `HTTP_PROXY` or `HTTPS_PROXY` is set on the host, NemoClaw adds `localhost` and `127.0.0.1` to `NO_PROXY` for managed subprocesses. +This keeps local Ollama health checks and model pulls from being routed through a corporate or desktop proxy while preserving the proxy for external hosts. + ### Agent cannot reach a host-side HTTP service When a sandbox needs to call an HTTP service running on the host, use the normal OpenShell network policy path. diff --git a/.agents/skills/nemoclaw-user-workspace/SKILL.md b/.agents/skills/nemoclaw-user-workspace/SKILL.md index ca2f5b264d..210f907e15 100644 --- a/.agents/skills/nemoclaw-user-workspace/SKILL.md +++ b/.agents/skills/nemoclaw-user-workspace/SKILL.md @@ -47,6 +47,8 @@ $ nemoclaw my-assistant snapshot restore 2026-04-14T ``` The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. +Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that were created by older images. +Unsafe symlinks and hard links inside sandbox state are rejected during backup creation before they can enter a snapshot. For full details, see the Commands reference (use the `nemoclaw-user-reference` skill). ## Step 3: Manual Backup diff --git a/.agents/skills/nemoclaw-user-workspace/references/workspace-files.md b/.agents/skills/nemoclaw-user-workspace/references/workspace-files.md index 6e575057bf..8638d97707 100644 --- a/.agents/skills/nemoclaw-user-workspace/references/workspace-files.md +++ b/.agents/skills/nemoclaw-user-workspace/references/workspace-files.md @@ -91,5 +91,6 @@ You can edit them in two ways: ## Next Steps +- Set Up Task-Specific Sub-Agents (use the `nemoclaw-user-configure-inference` skill) - Backup and Restore workspace files (use the `nemoclaw-user-workspace` skill) - Commands reference (use the `nemoclaw-user-reference` skill)