Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ flowchart TB
| Layer | What it protects | Enforcement point | Changeable at runtime |
| --- | --- | --- | --- |
| Network | Unauthorized outbound connections and data exfiltration. | OpenShell gateway | Yes. Use `openshell policy set` or operator approval. |
| Filesystem | System binary tampering, credential theft, config manipulation. | Landlock LSM + container mounts | Landlock layout: no. Requires sandbox re-creation. Config lockdown posture: yes, with host-side shields commands. |
| Filesystem | System binary tampering, credential theft, config manipulation. | Landlock LSM + container mounts | Landlock layout: no. Requires sandbox re-creation. Use host-side NemoClaw commands for durable config changes. |
| Process | Privilege escalation, fork bombs, syscall abuse. | Container runtime (Docker/K8s `securityContext`) | No. Requires sandbox re-creation. |
| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use `nemoclaw inference set`. |

Expand Down
1 change: 0 additions & 1 deletion .agents/skills/nemoclaw-user-manage-policy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,6 @@ Available presets:
| `pypi` | Python Package Index |
| `slack` | Slack API and webhooks |
| `telegram` | Telegram Bot API |
| `wechat` | WeChat messaging |
| `whatsapp` | WhatsApp Web messaging |

To apply a preset to a running sandbox:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,6 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr
| Python Package Index | `pypi` |
| Slack messaging | `slack` |
| Telegram Bot API | `telegram` |
| WeChat messaging | `wechat` |
| WhatsApp Web messaging | `whatsapp` |

Preview the endpoints before applying:
Expand Down Expand Up @@ -111,7 +110,7 @@ If delivery fails, open the TUI and send a test message to the bot:
$ openshell term
```

The matching preset for each supported messaging channel is the channel name (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`).
The matching preset for each supported messaging channel is the channel name (`telegram`, `discord`, `slack`, or `whatsapp`).

## Slack or Discord Messaging

Expand Down Expand Up @@ -257,5 +256,5 @@ Use `nemoclaw my-assistant policy-add` for maintained NemoClaw presets.

- Approve or Deny Agent Network Requests (use the `nemoclaw-user-manage-policy` skill) for the interactive OpenShell TUI flow.
- Customize the Sandbox Network Policy (use the `nemoclaw-user-manage-policy` skill) for static policy edits and raw OpenShell policy files.
- Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) for Telegram, Discord, Slack, WeChat, and WhatsApp channel configuration.
- Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) for Telegram, Discord, Slack, and WhatsApp channel configuration.
- Commands (use the `nemoclaw-user-reference` skill) for the full `policy-add`, `policy-list`, `policy-remove`, and `channels` command reference.
6 changes: 3 additions & 3 deletions .agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: "nemoclaw-user-manage-sandboxes"
description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, nemoclaw shields, shields up, shields down, shields status, sandbox mutability, sandbox runtime configuration, sandbox lockdown, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence."
description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw whatsapp, openshell channel messaging, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence."
---

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
Expand Down Expand Up @@ -272,9 +272,9 @@ For a full comparison of the two forms, including what they fetch, what they tru

## References

- **Load [references/runtime-controls.md](references/runtime-controls.md)** when an operator needs to temporarily lower or restore the sandbox security posture, or when a user is trying to figure out whether a config change needs a rebuild. Single page that answers 'what can I change at runtime vs. what requires a rebuild' for NemoClaw sandboxes, and documents the operator-only shields lockdown commands (shields up, shields down with timeout/reason/policy, shields status).
- **[references/runtime-controls.md](references/runtime-controls.md)** Single page that answers what can change at runtime versus what requires a rebuild for NemoClaw sandboxes.
- **Load [references/backup-restore.md](references/backup-restore.md)** when downloading workspace files from a sandbox, uploading restored files into a new sandbox, or preserving sandbox state across rebuilds. Backs up and restores OpenClaw workspace files before destructive operations such as sandbox rebuilds.
- **Load [references/messaging-channels.md](references/messaging-channels.md)** when setting up messaging channels, chat interfaces, or integrations without relying on nemoclaw tunnel start for bridges. Explains how Telegram, Discord, Slack, WeChat, and WhatsApp reach sandboxed OpenClaw and Hermes agents through OpenShell-managed processes and NemoClaw channel commands.
- **Load [references/messaging-channels.md](references/messaging-channels.md)** when setting up messaging channels, chat interfaces, or integrations without relying on nemoclaw tunnel start for bridges. Explains how Telegram, Discord, Slack, and WhatsApp reach sandboxed OpenClaw and Hermes agents through OpenShell-managed processes and NemoClaw channel commands.
- **Load [references/workspace-files.md](references/workspace-files.md)** when users ask about `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, or other workspace files, or when preparing to back up or restore workspace state. Explains what workspace personality and configuration files are, where they live, and how they persist across sandbox restarts.

## Related Skills
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Messaging Channels

Telegram, Discord, Slack, WeChat, and WhatsApp reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway constructs.
For token-based channels, NemoClaw registers credentials with OpenShell providers; WeChat captures a static token through a host-side QR scan; WhatsApp pairs inside the sandbox via QR scan and intentionally stores mutable session state there.
Telegram, Discord, Slack, and WhatsApp reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway constructs.
For token-based channels, NemoClaw registers credentials with OpenShell providers; WhatsApp pairs inside the sandbox via QR scan and intentionally stores mutable session state there.
NemoClaw bakes the selected channel configuration into the sandbox image and keeps runtime delivery under OpenShell control.

You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw <sandbox> channels` commands.
Expand All @@ -16,7 +16,7 @@ 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 token for each token-based messaging platform you want to enable, or a phone you can use to scan the QR code for WeChat or WhatsApp pairing.
- A token for each token-based messaging platform you want to enable, or a phone you can use to scan the QR code for WhatsApp pairing.
- A network policy preset for each enabled channel, or equivalent custom egress rules.

## Channel Requirements
Expand All @@ -26,7 +26,6 @@ For details, refer to Commands (use the `nemoclaw-user-reference` skill).
| Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies |
| Discord | `DISCORD_BOT_TOKEN` | `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION` |
| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `SLACK_ALLOWED_USERS` for DM and channel `@mention` user allowlisting |
| WeChat | Captured by host-side QR during interactive setup | `WECHAT_ALLOWED_IDS` for DM allowlisting |
| WhatsApp | None. Pair via QR after rebuild | None |

Telegram uses a bot token from [BotFather](https://t.me/BotFather).
Expand All @@ -47,11 +46,6 @@ Use `SLACK_BOT_TOKEN` for the bot user OAuth token (`xoxb-...`) and `SLACK_APP_T
Set `SLACK_ALLOWED_USERS` to comma-separated Slack member IDs to authorize those users for DMs and for channel `@mention` events in channels where the Slack app is present.
Channel messages still require an explicit bot mention.

WeChat uses a host-side QR flow.
When you enable it interactively, NemoClaw shows a QR code; scan it with WeChat on your phone.
NemoClaw saves the captured token as `WECHAT_BOT_TOKEN`, stores account metadata for rebuilds, and adds the scanning user's ID to `WECHAT_ALLOWED_IDS` unless you provide an allowlist.
Fresh WeChat setup cannot run non-interactively because it requires QR login.

WhatsApp Web does not use a host-side token or OpenShell credential provider.
NemoClaw advertises WhatsApp for both OpenClaw and Hermes sandboxes, and each agent completes pairing with its own in-sandbox command.
Pairing happens inside the sandbox after the rebuild completes and creates mutable session credentials there.
Expand All @@ -69,10 +63,9 @@ Pair only one sandbox per WhatsApp account at a time.

## Enable Channels During Onboarding

When the wizard reaches **Messaging channels**, it lists Telegram, Discord, Slack, WeChat, and WhatsApp.
When the wizard reaches **Messaging channels**, it lists Telegram, Discord, Slack, and WhatsApp.
Press a channel number to toggle it on or off, then press **Enter** when done.
If a token-based channel token is not already in the environment or credential store, the wizard prompts for it and saves it.
WeChat uses host-side QR pairing, so the wizard displays a QR code to scan.
WhatsApp uses QR pairing instead of a host-side token, so the wizard does not prompt.
It prints pairing instructions and you complete the pairing inside the sandbox after rebuild.
NemoClaw also selects the matching network policy preset during policy setup so the channel can reach its provider API.
Expand Down Expand Up @@ -112,15 +105,14 @@ Add the channel you want:
$ nemoclaw my-assistant channels add telegram
$ nemoclaw my-assistant channels add discord
$ nemoclaw my-assistant channels add slack
$ nemoclaw my-assistant channels add wechat
$ nemoclaw my-assistant channels add whatsapp
```

`channels add` collects whatever each channel needs (token prompts for Telegram, Discord, and Slack; a host-side QR scan for WeChat; nothing for WhatsApp because pairing happens in-sandbox after rebuild), registers bridge providers with the OpenShell gateway when tokens were captured, records the channel in the sandbox registry, and asks whether to rebuild immediately.
`channels add` collects whatever each channel needs (token prompts for Telegram, Discord, and Slack; nothing for WhatsApp because pairing happens in-sandbox after rebuild), registers bridge providers with the OpenShell gateway when tokens were captured, records the channel in the sandbox registry, and asks whether to rebuild immediately.
The command accepts mixed-case input such as `Telegram`, then stores and prints the canonical lowercase channel name.
If a matching built-in network policy preset exists, `channels add` applies it to the sandbox automatically before the rebuild so the bridge has egress to its upstream API; if applying the preset fails, NemoClaw warns and tells you to re-apply manually with `nemoclaw <sandbox> policy-add <channel>` after the rebuild.
Choose the rebuild so the running sandbox image picks up the new channel.
If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION`, or `WECHAT_ALLOWED_IDS`, export them before the rebuild starts.
If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, or `DISCORD_REQUIRE_MENTION`, export them before the rebuild starts.
If you defer the rebuild, apply the change later:

```console
Expand Down Expand Up @@ -174,13 +166,13 @@ If NemoClaw only has legacy channel metadata and cannot compare credential hashe

Use `channels stop` when you want to pause one bridge and keep the sandbox running.
Use `nemoclaw tunnel stop` or its deprecated alias `nemoclaw stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the OpenClaw gateway inside the selected sandbox.
Stopping the in-sandbox gateway stops Telegram, Discord, Slack, WeChat, and WhatsApp polling for that sandbox until you restart the sandbox or gateway.
Stopping the in-sandbox gateway stops Telegram, Discord, Slack, and WhatsApp polling for that sandbox until you restart the sandbox or gateway.

## Confirm Delivery

After the sandbox is running, send a message to the configured bot or app.
If delivery fails, use `openshell term` on the host, check gateway logs, and verify network policy allows the channel API.
Use the matching policy preset (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`) or review Common Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill).
Use the matching policy preset (`telegram`, `discord`, `slack`, or `whatsapp`) or review Common Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill).

## Tunnel Command

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,7 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Runtime Controls and Sandbox Mutability

This page is the single reference for two related operator questions about a running NemoClaw sandbox:

1. *Which parts of my sandbox can I change while it is running, and which require a rebuild or re-onboard?*
2. *How do I temporarily lower or restore the sandbox security posture for an operator session?*

The mutability table below answers question 1.
The shields commands answer question 2.
This page explains which parts of a running NemoClaw sandbox can change immediately and which changes require a rebuild or re-onboard.

## What you can change at runtime

Expand All @@ -30,62 +24,11 @@ The table below maps each commonly changed item to the layer that owns it and th
| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation** — no runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` |
| Sandbox name | **Locked at creation** | Re-onboard with a different `--name` |
| GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` |
| Shields posture (locked ↔ default mutable) | Runtime (operator-only) | `nemoclaw <name> shields up` / `shields down` — see the next section |
| Agents allow-list (`agents.list` in `openclaw.json`) | Runtime — hot-reloaded by OpenClaw on config change | Edit `openclaw.json` while shields are down |
| `openclaw.json` keys (general — model, agents.list, web.backend, channel config, etc.) | Mixed: locked under `shields up`, runtime-editable under `shields down`. Individual keys still follow the rebuild rules in the rows above (e.g. provider switch requires rebuild even after editing the JSON). | `nemoclaw <name> shields down`, edit `/opt/nemoclaw/openclaw.json` inside the sandbox, then `nemoclaw <name> shields up` |
| Agents allow-list (`agents.list` in `openclaw.json`) | Runtime — hot-reloaded by OpenClaw on config change | Prefer agent or NemoClaw commands that keep host and sandbox state aligned |
| `openclaw.json` keys (general — model, agents.list, web.backend, channel config, etc.) | Mixed. Individual keys still follow the rebuild rules in the rows above, such as provider switch requiring rebuild even after editing the JSON. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned |

If a row above conflicts with what you observe, the runtime source of truth inside the sandbox is `/opt/nemoclaw/openclaw.json`; the host registry caches metadata but the image and OpenClaw read from the in-sandbox file.

## Shields commands

Shields are an operator-only switch that toggles the sandbox between its default mutable state and a locked-down posture.
The sandbox itself cannot raise or lower its own shields — every transition is initiated from the host so a compromised agent cannot escape its policy by editing config.

Three commands manage the posture.
The commands are hidden from the standard `--help` output because they are operator workflows, not developer workflows; everything below documents the full surface.

### `shields status`

Print the current shields mode (`mutable_default`, `locked`, or `temporarily_unlocked`), the active policy preset, and any pending automatic restore timer.

```console
$ nemoclaw my-assistant shields status
Shields: locked
Policy: strict
Auto-restore: not scheduled (use `shields down --timeout 10m` to schedule)
```

### `shields up`

Raise shields: lock `openclaw.json` (and other mutable config files) against in-sandbox edits and apply the restrictive network policy that was captured the last time the sandbox was shielded.
This is the default expected state for a sandbox the operator has handed off to an agent.

```console
$ nemoclaw my-assistant shields up
✓ Shields raised: config locked, restrictive policy applied
```

`shields up` takes no flags.
If no saved snapshot exists yet (a fresh sandbox), the snapshot is taken from the current state.

### `shields down`

Lower shields: unlock config and apply a permissive (or operator-named) network policy so the operator can edit `openclaw.json`, swap presets, or run interactive maintenance.

```console
$ nemoclaw my-assistant shields down --timeout 10m --reason "rotating slack token"
✓ Shields lowered for 10m (policy: permissive); auto-restore at 14:32 UTC
```

| Flag | Default | Effect |
|---|---|---|
| `--timeout <duration>` | *no auto-restore* | After the duration elapses, a detached host-side timer re-runs `shields up` automatically. Accepts `5m`, `30s`, `1h`, etc. |
| `--reason <text>` | *empty* | Recorded in the shields audit log on the host. Required by some org policies; recommended for any cross-team session. |
| `--policy <name>` | `permissive` | Apply this named policy preset while shields are down instead of the default permissive set. Use a tighter preset (e.g. `messaging-only`) when the maintenance window only needs a subset of egress. |

The auto-restore timer is detached from the `shields down` invocation — closing your terminal does not cancel the restore.
If the timer process is killed before the deadline (e.g. host reboot), `shields status` will surface the inconsistency on the next check (see #3112 for the fail-open fix).

## See also

The mutability table above is a consolidated index of information that lives in more detail on per-topic pages:
Expand Down
Loading
Loading