diff --git a/.agents/skills/docs/nemoclaw-configure-inference/SKILL.md b/.agents/skills/docs/nemoclaw-configure-inference/SKILL.md deleted file mode 100644 index 47464994ed6..00000000000 --- a/.agents/skills/docs/nemoclaw-configure-inference/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: nemoclaw-configure-inference -description: Changes the active inference model without restarting the sandbox. Use when change inference runtime, inference routing, openclaw, openshell, switch nemoclaw inference model, switch nemoclaw inference models. ---- - -# Nemoclaw Configure Inference - -Change the active inference model without restarting the sandbox. - -## Prerequisites - -- A running NemoClaw sandbox. -- The OpenShell CLI on your `PATH`. - -Change the active inference model while the sandbox is running. -No restart is required. - -## Step 1: Switch to a Different Model - -Set the provider to `nvidia-nim` and specify a model from [build.nvidia.com](https://build.nvidia.com): - -```console -$ openshell inference set --provider nvidia-nim --model nvidia/nemotron-3-super-120b-a12b -``` - -This requires the `NVIDIA_API_KEY` environment variable. -The `nemoclaw onboard` command stores this key in `~/.nemoclaw/credentials.json` on first run. - -## Step 2: 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 3: Available Models - -The following table lists the models registered with the `nvidia-nim` provider. -You can switch to any of these models at runtime. - -| Model ID | Label | Context Window | Max Output | -|---|---|---|---| -| `nvidia/nemotron-3-super-120b-a12b` | Nemotron 3 Super 120B | 131,072 | 8,192 | -| `nvidia/llama-3.1-nemotron-ultra-253b-v1` | Nemotron Ultra 253B | 131,072 | 4,096 | -| `nvidia/llama-3.3-nemotron-super-49b-v1.5` | Nemotron Super 49B v1.5 | 131,072 | 4,096 | -| `nvidia/nemotron-3-nano-30b-a3b` | Nemotron 3 Nano 30B | 131,072 | 4,096 | - -## Related Skills - -- `nemoclaw-reference` — Inference Profiles for full profile configuration details diff --git a/.agents/skills/docs/nemoclaw-reference/references/inference-profiles.md b/.agents/skills/docs/nemoclaw-reference/references/inference-profiles.md deleted file mode 100644 index 9586246b68c..00000000000 --- a/.agents/skills/docs/nemoclaw-reference/references/inference-profiles.md +++ /dev/null @@ -1,53 +0,0 @@ -# Inference Profiles - -NemoClaw ships with an inference profile defined in `blueprint.yaml`. -The profile configures an OpenShell inference provider and model route. -The agent inside the sandbox uses whichever model is active. -Inference requests are routed transparently through the OpenShell gateway. - -## Profile Summary - -| Profile | Provider | Model | Endpoint | Use Case | -|---|---|---|---|---| -| `default` | NVIDIA Endpoint | `nvidia/nemotron-3-super-120b-a12b` | `integrate.api.nvidia.com` | Production. Requires an NVIDIA API key. | - -## Available Models - -The `nvidia-nim` provider registers the following models from [build.nvidia.com](https://build.nvidia.com): - -| Model ID | Label | Context Window | Max Output | -|---|---|---|---| -| `nvidia/nemotron-3-super-120b-a12b` | Nemotron 3 Super 120B | 131,072 | 8,192 | -| `nvidia/llama-3.1-nemotron-ultra-253b-v1` | Nemotron Ultra 253B | 131,072 | 4,096 | -| `nvidia/llama-3.3-nemotron-super-49b-v1.5` | Nemotron Super 49B v1.5 | 131,072 | 4,096 | -| `nvidia/nemotron-3-nano-30b-a3b` | Nemotron 3 Nano 30B | 131,072 | 4,096 | - -The default profile uses Nemotron 3 Super 120B. -You can switch to any model in the catalog at runtime. - -## `default` -- NVIDIA Endpoint - -The default profile routes inference to NVIDIA's hosted API through [build.nvidia.com](https://build.nvidia.com). - -- **Provider type:** `nvidia` -- **Endpoint:** `https://integrate.api.nvidia.com/v1` -- **Model:** `nvidia/nemotron-3-super-120b-a12b` -- **Credential:** `NVIDIA_API_KEY` environment variable - -Get an API key from [build.nvidia.com](https://build.nvidia.com). -The `nemoclaw onboard` command prompts for this key and stores it in `~/.nemoclaw/credentials.json`. - -```console -$ openshell inference set --provider nvidia-nim --model nvidia/nemotron-3-super-120b-a12b -``` - -## Switching Models at Runtime - -After the sandbox is running, switch models with the OpenShell CLI: - -```console -$ openshell inference set --provider nvidia-nim --model -``` - -The change takes effect immediately. -No sandbox restart is needed. diff --git a/.agents/skills/nemoclaw-configure-inference/SKILL.md b/.agents/skills/nemoclaw-configure-inference/SKILL.md new file mode 100644 index 00000000000..5c0521a8be7 --- /dev/null +++ b/.agents/skills/nemoclaw-configure-inference/SKILL.md @@ -0,0 +1,85 @@ +--- +name: nemoclaw-configure-inference +description: Changes the active inference model without restarting the sandbox. Use when change inference runtime, inference routing, openclaw, openshell, switch nemoclaw inference model, switch nemoclaw inference models. +--- + +# Nemoclaw Configure Inference + +Change the active inference model without restarting the sandbox. + +## Prerequisites + +- A running NemoClaw sandbox. +- The OpenShell CLI on your `PATH`. + +Change the active inference model while the sandbox is running. +No restart is required. + +## Step 1: 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`. + +## Step 2: 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 3: Notes + +- The host keeps provider credentials. +- The sandbox continues to use `inference.local`. +- Runtime switching changes the OpenShell route. It does not rewrite your stored credentials. + +## Related Skills + +- `nemoclaw-reference` — Inference Profiles for full profile configuration details diff --git a/.agents/skills/docs/nemoclaw-deploy-remote/SKILL.md b/.agents/skills/nemoclaw-deploy-remote/SKILL.md similarity index 100% rename from .agents/skills/docs/nemoclaw-deploy-remote/SKILL.md rename to .agents/skills/nemoclaw-deploy-remote/SKILL.md diff --git a/.agents/skills/docs/nemoclaw-get-started/SKILL.md b/.agents/skills/nemoclaw-get-started/SKILL.md similarity index 98% rename from .agents/skills/docs/nemoclaw-get-started/SKILL.md rename to .agents/skills/nemoclaw-get-started/SKILL.md index bb6e821c986..e1e8c1b32e4 100644 --- a/.agents/skills/docs/nemoclaw-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-get-started/SKILL.md @@ -70,7 +70,7 @@ When the install completes, a summary confirms the running environment: ```text ────────────────────────────────────────────────── Sandbox my-assistant (Landlock + seccomp + netns) -Model nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoint API) +Model nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints) ────────────────────────────────────────────────── Run: nemoclaw my-assistant connect Status: nemoclaw my-assistant status diff --git a/.agents/skills/docs/nemoclaw-manage-policy/SKILL.md b/.agents/skills/nemoclaw-manage-policy/SKILL.md similarity index 100% rename from .agents/skills/docs/nemoclaw-manage-policy/SKILL.md rename to .agents/skills/nemoclaw-manage-policy/SKILL.md diff --git a/.agents/skills/docs/nemoclaw-monitor-sandbox/SKILL.md b/.agents/skills/nemoclaw-monitor-sandbox/SKILL.md similarity index 100% rename from .agents/skills/docs/nemoclaw-monitor-sandbox/SKILL.md rename to .agents/skills/nemoclaw-monitor-sandbox/SKILL.md diff --git a/.agents/skills/docs/nemoclaw-overview/SKILL.md b/.agents/skills/nemoclaw-overview/SKILL.md similarity index 100% rename from .agents/skills/docs/nemoclaw-overview/SKILL.md rename to .agents/skills/nemoclaw-overview/SKILL.md diff --git a/.agents/skills/docs/nemoclaw-overview/references/how-it-works.md b/.agents/skills/nemoclaw-overview/references/how-it-works.md similarity index 94% rename from .agents/skills/docs/nemoclaw-overview/references/how-it-works.md rename to .agents/skills/nemoclaw-overview/references/how-it-works.md index 6b53ffa9c1b..253af7ed017 100644 --- a/.agents/skills/docs/nemoclaw-overview/references/how-it-works.md +++ b/.agents/skills/nemoclaw-overview/references/how-it-works.md @@ -93,7 +93,8 @@ After the sandbox starts, the agent runs inside it with all network, filesystem, Inference requests from the agent never leave the sandbox directly. OpenShell intercepts every inference call and routes it to the configured provider. -NemoClaw routes inference to NVIDIA Endpoints, specifically Nemotron 3 Super 120B through [build.nvidia.com](https://build.nvidia.com). You can switch models at runtime without restarting the sandbox. +During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell route, and bakes the matching model reference into the sandbox image. +The sandbox then talks to `inference.local`, while the host owns the actual provider credential and upstream endpoint. ## Network and Filesystem Policy diff --git a/.agents/skills/docs/nemoclaw-overview/references/overview.md b/.agents/skills/nemoclaw-overview/references/overview.md similarity index 100% rename from .agents/skills/docs/nemoclaw-overview/references/overview.md rename to .agents/skills/nemoclaw-overview/references/overview.md diff --git a/.agents/skills/docs/nemoclaw-overview/references/release-notes.md b/.agents/skills/nemoclaw-overview/references/release-notes.md similarity index 100% rename from .agents/skills/docs/nemoclaw-overview/references/release-notes.md rename to .agents/skills/nemoclaw-overview/references/release-notes.md diff --git a/.agents/skills/docs/nemoclaw-reference/SKILL.md b/.agents/skills/nemoclaw-reference/SKILL.md similarity index 69% rename from .agents/skills/docs/nemoclaw-reference/SKILL.md rename to .agents/skills/nemoclaw-reference/SKILL.md index 61230014944..09d2e829370 100644 --- a/.agents/skills/docs/nemoclaw-reference/SKILL.md +++ b/.agents/skills/nemoclaw-reference/SKILL.md @@ -1,6 +1,6 @@ --- name: nemoclaw-reference -description: Learns how NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Also covers fulls CLI reference for plugin and standalone NemoClaw commands; configurations reference for NVIDIA Endpoint inference profiles. Use when blueprints, cli, inference routing, llms, nemoclaw, nemoclaw architecture, nemoclaw architecture plugin blueprint, nemoclaw cli commands. +description: Learns how NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Also covers fulls CLI reference for plugin and standalone NemoClaw commands; configurations reference for NemoClaw routed inference providers. Use when blueprints, cli, inference routing, llms, nemoclaw, nemoclaw architecture, nemoclaw architecture plugin blueprint, nemoclaw cli commands. --- # Nemoclaw Reference @@ -11,6 +11,6 @@ Learn how NemoClaw combines a lightweight CLI plugin with a versioned blueprint - [NemoClaw Architecture — Plugin, Blueprint, and Sandbox Structure](references/architecture.md) - [NemoClaw CLI Commands Reference](references/commands.md) -- [NemoClaw Inference Profiles — NVIDIA Endpoint](references/inference-profiles.md) +- [NemoClaw Inference Profiles](references/inference-profiles.md) - [NemoClaw Network Policies — Baseline Rules and Operator Approval](references/network-policies.md) - [NemoClaw Troubleshooting Guide](references/troubleshooting.md) diff --git a/.agents/skills/docs/nemoclaw-reference/references/architecture.md b/.agents/skills/nemoclaw-reference/references/architecture.md similarity index 100% rename from .agents/skills/docs/nemoclaw-reference/references/architecture.md rename to .agents/skills/nemoclaw-reference/references/architecture.md diff --git a/.agents/skills/docs/nemoclaw-reference/references/commands.md b/.agents/skills/nemoclaw-reference/references/commands.md similarity index 93% rename from .agents/skills/docs/nemoclaw-reference/references/commands.md rename to .agents/skills/nemoclaw-reference/references/commands.md index 3cfc8f52c00..d43501ce538 100644 --- a/.agents/skills/docs/nemoclaw-reference/references/commands.md +++ b/.agents/skills/nemoclaw-reference/references/commands.md @@ -24,7 +24,9 @@ Use this command for new installs and for recreating a sandbox after changes to $ nemoclaw onboard ``` -The first run prompts for your NVIDIA API key and saves it to `~/.nemoclaw/credentials.json`. +The wizard prompts for a provider first, then collects the provider credential if needed. +Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints. +Credentials are stored in `~/.nemoclaw/credentials.json`. 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. diff --git a/.agents/skills/nemoclaw-reference/references/inference-profiles.md b/.agents/skills/nemoclaw-reference/references/inference-profiles.md new file mode 100644 index 00000000000..b2f141c1853 --- /dev/null +++ b/.agents/skills/nemoclaw-reference/references/inference-profiles.md @@ -0,0 +1,64 @@ +# Inference Profiles + +NemoClaw configures inference through the OpenShell gateway. +The agent inside the sandbox talks to `inference.local`, and OpenShell routes that traffic to the provider you selected during onboarding. + +## Routed Provider Model + +NemoClaw keeps provider credentials on the host. +The sandbox does not receive your raw OpenAI, Anthropic, Gemini, or NVIDIA API key. + +At onboard time, NemoClaw configures: + +- an OpenShell provider +- an OpenShell inference route +- the baked OpenClaw model reference inside the sandbox + +That means the sandbox knows which model family to use, while OpenShell owns the actual provider credential and upstream endpoint. + +## Supported Providers + +The following non-experimental provider paths are available through `nemoclaw onboard`. + +| Provider | Endpoint Type | Notes | +|---|---|---| +| NVIDIA Endpoints | OpenAI-compatible | Hosted models on `integrate.api.nvidia.com` | +| OpenAI | Native OpenAI-compatible | Uses OpenAI model IDs | +| Other OpenAI-compatible endpoint | Custom OpenAI-compatible | For compatible proxies and gateways | +| Anthropic | Native Anthropic | Uses `anthropic-messages` | +| Other Anthropic-compatible endpoint | Custom Anthropic-compatible | For Claude proxies and compatible gateways | +| Google Gemini | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint | + +## Validation During Onboarding + +NemoClaw validates the selected provider and model before it creates the sandbox. + +- OpenAI-compatible providers: + NemoClaw tries `/responses` first, then `/chat/completions`. +- Anthropic-compatible providers: + NemoClaw tries `/v1/messages`. +- NVIDIA Endpoints manual model entry: + NemoClaw also validates the model name against `https://integrate.api.nvidia.com/v1/models`. +- Compatible endpoint flows: + NemoClaw validates by sending a real inference request, because many proxies do not expose a reliable `/models` endpoint. + +If validation fails, the wizard does not continue to sandbox creation. + +## Local Providers + +Local providers use the same routed `inference.local` pattern, but the upstream runtime runs on the host rather than in the cloud. + +- Local Ollama +- Local NVIDIA NIM +- Local vLLM + +Ollama gets additional onboarding help: + +- if no models are installed, NemoClaw offers starter models +- it pulls the selected model +- it warms the model +- it validates the model before continuing + +## Runtime Switching + +For runtime switching guidance, refer to Switch Inference Models (see the `nemoclaw-configure-inference` skill). diff --git a/.agents/skills/docs/nemoclaw-reference/references/network-policies.md b/.agents/skills/nemoclaw-reference/references/network-policies.md similarity index 100% rename from .agents/skills/docs/nemoclaw-reference/references/network-policies.md rename to .agents/skills/nemoclaw-reference/references/network-policies.md diff --git a/.agents/skills/docs/nemoclaw-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-reference/references/troubleshooting.md similarity index 97% rename from .agents/skills/docs/nemoclaw-reference/references/troubleshooting.md rename to .agents/skills/nemoclaw-reference/references/troubleshooting.md index 8dd01774caa..12dd07c9e8f 100644 --- a/.agents/skills/docs/nemoclaw-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-reference/references/troubleshooting.md @@ -139,7 +139,8 @@ Check the active provider and endpoint: $ nemoclaw status ``` -If the endpoint is correct but requests still fail, check for network policy rules that may block the connection, and verify that your NVIDIA API key is valid. +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. ### Agent cannot reach an external host diff --git a/.agents/skills/nemoclaw-workspace/SKILL.md b/.agents/skills/nemoclaw-workspace/SKILL.md new file mode 100644 index 00000000000..de9f11a41f0 --- /dev/null +++ b/.agents/skills/nemoclaw-workspace/SKILL.md @@ -0,0 +1,169 @@ +--- +name: nemoclaw-workspace +description: Hows to back up and restore OpenClaw workspace files before destructive operations. Also covers whats workspace files are, where they live, and how they persist across sandbox restarts. Use when agents.md, back restore workspace files, backup, identity.md, memory.md, nemoclaw, nemoclaw backup, nemoclaw restore. +--- + +# Nemoclaw Workspace + +How to back up and restore OpenClaw workspace files before destructive operations. + +## Context + +OpenClaw stores agent identity, behavior, and memory in a set of Markdown files inside the sandbox. +These files live at `/sandbox/.openclaw/workspace/` and are read by the agent at the start of every session. + +## File Reference + +Each file controls a distinct aspect of the agent's behavior and memory. + +| File | Purpose | Upstream Docs | +|---|---|---| +| `SOUL.md` | Core personality, tone, and behavioral rules. | [SOUL template](https://docs.openclaw.ai/reference/templates/SOUL) | +| `USER.md` | Preferences, context, and facts the agent learns about you. | [USER template](https://docs.openclaw.ai/reference/templates/USER) | +| `IDENTITY.md` | Agent name, creature type, emoji, and self-presentation. | [IDENTITY template](https://docs.openclaw.ai/reference/templates/IDENTITY) | +| `AGENTS.md` | Multi-agent coordination, memory conventions, and safety guidelines. | [AGENTS template](https://docs.openclaw.ai/reference/templates/AGENTS) | +| `MEMORY.md` | Curated long-term memory distilled from daily notes. | — | +| `memory/` | Directory of daily note files (`YYYY-MM-DD.md`) for session continuity. | — | + +## Where They Live + +All workspace files reside inside the sandbox filesystem: + +```text +/sandbox/.openclaw/workspace/ +├── AGENTS.md +├── IDENTITY.md +├── MEMORY.md +├── SOUL.md +├── USER.md +└── memory/ + ├── 2026-03-18.md + └── 2026-03-19.md +``` + +> **Note:** The workspace directory is hidden (`.openclaw`). +> The files are not at `/sandbox/SOUL.md` — use the full path when downloading or uploading. + +## Persistence Behavior + +Understanding when these files persist and when they are lost is critical. + +| Event | Workspace files | +|---|---| +| Sandbox restart | **Preserved** — the sandbox PVC retains its data. | +| `nemoclaw destroy` | **Lost** — the sandbox and its PVC are deleted. | + +> **Warning:** Always back up your workspace files before running `nemoclaw destroy`. +> See Back Up and Restore (see the `nemoclaw-workspace` skill) for instructions. + +## Editing Workspace Files + +The agent reads these files at the start of every session. +You can edit them in two ways: + +1. **Let the agent do it** — Ask your agent to update its persona, memory, or user context during a session. +2. **Edit manually** — Use `openshell sandbox connect` to open a terminal inside the sandbox and edit files directly, or use `openshell sandbox upload` to push edited files from your host. + +## Prerequisites + +- A running NemoClaw sandbox (for backup) or a freshly created sandbox (for restore). +- The OpenShell CLI on your `PATH`. +- The sandbox name (shown by `nemoclaw list`). + +Workspace files define your agent's personality, memory, and user context. +They persist across sandbox restarts but are **permanently deleted** when you run `nemoclaw destroy`. + +This guide covers manual backup with CLI commands and an automated script. + +## Step 1: When to Back Up + +- Before running `nemoclaw destroy`. +- Before major NemoClaw version upgrades. +- Periodically, if you have invested time customizing your agent. + +## Step 2: Manual Backup + +Use `openshell sandbox download` to copy files from the sandbox to your host. + +```console +$ SANDBOX=my-assistant +$ BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) +$ mkdir -p "$BACKUP_DIR" + +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/IDENTITY.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/AGENTS.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/" +``` + +## Step 3: Manual Restore + +Use `openshell sandbox upload` to push files back into a sandbox. + +```console +$ SANDBOX=my-assistant +$ BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp + +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/USER.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/IDENTITY.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/AGENTS.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/ +``` + +## Step 4: Using the Backup Script + +The repository includes a convenience script at `scripts/backup-workspace.sh`. + +### Backup + +```console +$ ./scripts/backup-workspace.sh backup my-assistant +Backing up workspace from sandbox 'my-assistant'... +Backup saved to /home/user/.nemoclaw/backups/20260320-120000/ (6 items) +``` + +### Restore + +Restore from the most recent backup: + +```console +$ ./scripts/backup-workspace.sh restore my-assistant +``` + +Restore from a specific timestamp: + +```console +$ ./scripts/backup-workspace.sh restore my-assistant 20260320-120000 +``` + +## Step 5: Verifying a Backup + +List backed-up files to confirm completeness: + +```console +$ ls ~/.nemoclaw/backups/20260320-120000/ +AGENTS.md +IDENTITY.md +MEMORY.md +SOUL.md +USER.md +memory/ +``` + +## Step 6: Inspecting Files Inside the Sandbox + +Connect to the sandbox to list or view workspace files directly: + +```console +$ openshell sandbox connect my-assistant +$ ls -la /sandbox/.openclaw/workspace/ +``` + +## Related Skills + +- `nemoclaw-reference` — Commands reference +- `nemoclaw-monitor-sandbox` — Monitor Sandbox Activity diff --git a/.agents/skills/nemoclaw-workspace/references/workspace-files.md b/.agents/skills/nemoclaw-workspace/references/workspace-files.md new file mode 100644 index 00000000000..60e97b2add5 --- /dev/null +++ b/.agents/skills/nemoclaw-workspace/references/workspace-files.md @@ -0,0 +1,61 @@ +# Workspace Files + +OpenClaw stores agent identity, behavior, and memory in a set of Markdown files inside the sandbox. +These files live at `/sandbox/.openclaw/workspace/` and are read by the agent at the start of every session. + +## File Reference + +Each file controls a distinct aspect of the agent's behavior and memory. + +| File | Purpose | Upstream Docs | +|---|---|---| +| `SOUL.md` | Core personality, tone, and behavioral rules. | [SOUL template](https://docs.openclaw.ai/reference/templates/SOUL) | +| `USER.md` | Preferences, context, and facts the agent learns about you. | [USER template](https://docs.openclaw.ai/reference/templates/USER) | +| `IDENTITY.md` | Agent name, creature type, emoji, and self-presentation. | [IDENTITY template](https://docs.openclaw.ai/reference/templates/IDENTITY) | +| `AGENTS.md` | Multi-agent coordination, memory conventions, and safety guidelines. | [AGENTS template](https://docs.openclaw.ai/reference/templates/AGENTS) | +| `MEMORY.md` | Curated long-term memory distilled from daily notes. | — | +| `memory/` | Directory of daily note files (`YYYY-MM-DD.md`) for session continuity. | — | + +## Where They Live + +All workspace files reside inside the sandbox filesystem: + +```text +/sandbox/.openclaw/workspace/ +├── AGENTS.md +├── IDENTITY.md +├── MEMORY.md +├── SOUL.md +├── USER.md +└── memory/ + ├── 2026-03-18.md + └── 2026-03-19.md +``` + +> **Note:** The workspace directory is hidden (`.openclaw`). +> The files are not at `/sandbox/SOUL.md` — use the full path when downloading or uploading. + +## Persistence Behavior + +Understanding when these files persist and when they are lost is critical. + +| Event | Workspace files | +|---|---| +| Sandbox restart | **Preserved** — the sandbox PVC retains its data. | +| `nemoclaw destroy` | **Lost** — the sandbox and its PVC are deleted. | + +> **Warning:** Always back up your workspace files before running `nemoclaw destroy`. +> See Back Up and Restore (see the `nemoclaw-workspace` skill) for instructions. + +## Editing Workspace Files + +The agent reads these files at the start of every session. +You can edit them in two ways: + +1. **Let the agent do it** — Ask your agent to update its persona, memory, or user context during a session. +2. **Edit manually** — Use `openshell sandbox connect` to open a terminal inside the sandbox and edit files directly, or use `openshell sandbox upload` to push edited files from your host. + +## Next Steps + +- Back Up and Restore workspace files (see the `nemoclaw-workspace` skill) +- Commands reference (see the `nemoclaw-reference` skill) diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 00000000000..2b7a412b8fa --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file diff --git a/.gitignore b/.gitignore index 9ddd809b8ab..08a62b3afa0 100644 --- a/.gitignore +++ b/.gitignore @@ -14,7 +14,6 @@ desktop.ini Thumbs.db # Project-specific -.claude/ draft_newsletter_* vdr-notes/ diff --git a/scripts/docs-to-skills.py b/scripts/docs-to-skills.py index 285a8503e07..4425a571235 100755 --- a/scripts/docs-to-skills.py +++ b/scripts/docs-to-skills.py @@ -11,7 +11,7 @@ Make sure to run this script using the following command to generate the skills and keep the locations and names consistent. ```bash -python scripts/docs-to-skills.py docs/ .agents/skills/docs/ --prefix nemoclaw +python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw ``` What it does: @@ -40,16 +40,17 @@ override specific names when the heuristic doesn't produce the right result. Usage: - python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw - python scripts/docs-to-skills.py docs/ output/ --prefix nemoclaw --dry-run - python scripts/docs-to-skills.py docs/ output/ --strategy individual --prefix nemoclaw - python scripts/docs-to-skills.py docs/ output/ --prefix nemoclaw --name-map about=overview - python scripts/docs-to-skills.py docs/ output/ --exclude "release-notes.md" + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --dry-run + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --strategy individual --prefix nemoclaw + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --name-map about=overview + python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --exclude "release-notes.md" """ from __future__ import annotations import argparse +import os import re import sys import textwrap @@ -892,7 +893,7 @@ def _to_third_person(sentence: str) -> str: def generate_skill( name: str, pages: list[DocPage], - output_dir: Path, + output_dirs: list[Path], *, docs_dir: Path | None = None, doc_to_skill: dict[str, str] | None = None, @@ -900,6 +901,7 @@ def generate_skill( ) -> dict: """Generate a complete skill directory from a group of doc pages. + Writes identical output to each directory in *output_dirs*. Returns a summary dict for reporting. """ keywords = extract_trigger_keywords(pages) @@ -1074,10 +1076,9 @@ def _clean(text: str, source: DocPage) -> str: ref_files[ref_name] = body # --- Write output --- - skill_dir = output_dir / name summary = { "name": name, - "dir": str(skill_dir), + "dirs": [str(d / name) for d in output_dirs], "pages": [str(p.path) for p in pages], "skill_md_lines": len(skill_md.split("\n")), "reference_files": list(ref_files.keys()), @@ -1087,14 +1088,20 @@ def _clean(text: str, source: DocPage) -> str: summary["dry_run"] = True return summary - skill_dir.mkdir(parents=True, exist_ok=True) - (skill_dir / "SKILL.md").write_text(skill_md.rstrip("\n") + "\n", encoding="utf-8") + for output_dir in output_dirs: + skill_dir = output_dir / name + skill_dir.mkdir(parents=True, exist_ok=True) + (skill_dir / "SKILL.md").write_text( + skill_md.rstrip("\n") + "\n", encoding="utf-8" + ) - if ref_files: - refs_dir = skill_dir / "references" - refs_dir.mkdir(exist_ok=True) - for fname, content in ref_files.items(): - (refs_dir / fname).write_text(content.rstrip("\n") + "\n", encoding="utf-8") + if ref_files: + refs_dir = skill_dir / "references" + refs_dir.mkdir(exist_ok=True) + for fname, content in ref_files.items(): + (refs_dir / fname).write_text( + content.rstrip("\n") + "\n", encoding="utf-8" + ) return summary @@ -1201,17 +1208,20 @@ def main(): smart Group by directory, merge concept pages as context Examples: - %(prog)s docs/ .agents/skills/generated/ --prefix nemoclaw - %(prog)s docs/ output/ --strategy individual --prefix nemoclaw - %(prog)s docs/ output/ --prefix nemoclaw --name-map about=overview - %(prog)s docs/ output/ --strategy smart --dry-run + %(prog)s docs/ .agents/skills/ --prefix nemoclaw + %(prog)s docs/ .agents/skills/ --strategy individual --prefix nemoclaw + %(prog)s docs/ .agents/skills/ --prefix nemoclaw --name-map about=overview + %(prog)s docs/ .agents/skills/ --prefix nemoclaw --dry-run """), ) parser.add_argument( "docs_dir", type=Path, help="Path to the documentation directory" ) parser.add_argument( - "output_dir", type=Path, help="Output directory for generated skills" + "output_dirs", + type=Path, + nargs="+", + help="Output directories for generated skills (e.g. .agents/skills/ .claude/skills/)", ) parser.add_argument( "--strategy", @@ -1322,22 +1332,46 @@ def main(): pass # Generate skills - print( - f"\n{'[DRY RUN] ' if args.dry_run else ''}Generating skills to {args.output_dir}/" - ) + dirs_str = ", ".join(str(d) for d in args.output_dirs) + print(f"\n{'[DRY RUN] ' if args.dry_run else ''}Generating skills to {dirs_str}") summaries: list[dict] = [] for group_name, group_pages in sorted(groups.items()): name = skill_names[group_name] summary = generate_skill( name, group_pages, - args.output_dir, + args.output_dirs, docs_dir=docs_dir_resolved, doc_to_skill=doc_to_skill, dry_run=args.dry_run, ) summaries.append(summary) + # Ensure .claude/skills symlink exists + if not args.dry_run: + claude_skills = Path(".claude/skills") + for out_dir in args.output_dirs: + # Only create symlink if output is under .agents/skills + if ".agents/skills" in str(out_dir): + agents_skills = Path(out_dir) + if claude_skills.is_symlink(): + if claude_skills.resolve() == agents_skills.resolve(): + break # already correct + else: + claude_skills.unlink() + elif claude_skills.is_dir(): + print(f"\n⚠ {claude_skills} is a real directory, not a symlink.") + print( + f" Remove it and re-run, or manually symlink to {agents_skills}" + ) + break + # Create parent and symlink + claude_skills.parent.mkdir(parents=True, exist_ok=True) + rel = os.path.relpath(agents_skills, claude_skills.parent) + claude_skills.symlink_to(rel) + print(f"\n✔ Created symlink: {claude_skills} → {rel}") + break + # Report print("\n" + "=" * 60) print("Generation Summary") @@ -1364,7 +1398,7 @@ def main(): if args.dry_run: print("\nDry run complete. No files were written.") - print(f"Re-run without --dry-run to generate skills in {args.output_dir}/") + print(f"Re-run without --dry-run to generate skills in {dirs_str}") if __name__ == "__main__":