How NemoClaw Works Under the Hood

You've built the sandbox. You've sent a Slack message from inside it. Now let's talk about why things work the way they do — and why certain things that seem like they should work, don't.

This post is about the architecture. Once you understand it, everything clicks.

Two Types of Agents — and Why It Matters

NemoClaw runs two fundamentally different kinds of agents. Most people don't realise this until something breaks.

Your main agent — the one you talk to inside the sandbox — is a subagent. It's deliberately limited.

ACP agents are different. They run outside the sandbox entirely, on your host machine. They have real access to your filesystem, the internet, and your tools.

When a subagent hits a wall, it can ask an ACP agent for help. That's the design.

The Security Model: Why Config Is Read-Only in the Sandbox

Here's something that trips up almost everyone:

You find a config file inside your sandbox. You edit it. You restart. Nothing changes.

This isn't a bug. It's intentional.

NemoClaw builds sandbox config from your host at startup time:

~/.nemoclaw/sandboxes.json   ← generated by NemoClaw on host

When the sandbox spins up, it reads from the host config and constructs the isolated environment. Anything you change inside the sandbox is overwritten the next time it starts.

The rule is simple: sandbox config flows one way — from host to sandbox, never the reverse.

This is a security decision. If a compromised agent could modify its own sandbox config, it could escalate its own permissions. By making config read-only from inside, NemoClaw ensures an agent can never grant itself more access than it was given at boot.

Where the Config Actually Lives

Two locations matter. Know them.

Host-side (persistent, authoritative):

~/.nemoclaw/             ← NemoClaw's own config
~/.config/openclaw/      ← OpenClaw gateway config (plugins, ACP agents)

Sandbox-side (ephemeral, read-only):

/sandbox/.openclaw/      ← Injected at startup, read-only inside sandbox

When you want to change something — a plugin setting, an API token, an ACP agent config — you change it on the host side, then restart the sandbox. Editing inside /sandbox/.openclaw/ is pointless.

Policy Presets: NemoClaw's Permission System

NemoClaw ships with policy presets that control what a sandbox is allowed to do. You saw these during nemoclaw onboard.

Common presets:

Most default installs use standard. This is why your sandbox can send Slack messages (through a plugin) but can't browse arbitrary URLs or edit your files.

To see your current policy:

nemoclaw kaav-assistant config get

To change it (on the host, before restarting):

nemoclaw kaav-assistant config set policy permissive
nemoclaw restart kaav-assistant

How ACP Connects Everything

Here's the full architecture — the thing that makes sense of all the above:

┌────────────────────────────────────────────┐
│  YOUR MAC (Host)                           │
│                                            │
│  ~/.nemoclaw/          ← NemoClaw config   │
│  ~/.config/openclaw/   ← ACP/gateway cfg   │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │  OpenClaw Gateway                   │  │
│  │  ┌───────────┐  ┌─────────────────┐ │  │
│  │  │ ACPX Plugin│  │ ACP Agents      │ │  │
│  │  │           │  │ (codex, claude) │ │  │
│  │  └───────────┘  └─────────────────┘ │  │
│  └──────────────────────────────────┬───┘  │
│                                     │       │
│  ┌──────────────────────────────────▼───┐  │
│  │  NemoClaw Sandbox                    │  │
│  │                                      │  │
│  │  /sandbox/.openclaw/  ← read-only    │  │
│  │                                      │  │
│  │  ┌──────────────────────────────┐    │  │
│  │  │  Subagent "main"             │    │  │
│  │  │  (sends requests to gateway) │    │  │
│  │  └──────────────────────────────┘    │  │
│  └──────────────────────────────────────┘  │
└────────────────────────────────────────────┘

The subagent can request things from the gateway. The gateway decides whether to fulfil them based on policy. ACP agents sit on the other side of the gateway with full access.

The sandbox itself never gets more powerful. The system around it does the heavy lifting.

The ACPX Plugin: The Bridge

ACPX is the plugin that connects your sandboxed subagent to the ACP layer. You may have seen it when running:

openclaw plugins list

It's often listed but disabled. That's expected on a default install.

To check if ACP is actually reachable from inside your sandbox:

/acp doctor

• Healthy → the host gateway is running and ACP is connected
• Error / no response → the gateway isn't running on the host yet

If it's not healthy, you need to start the gateway on your host:

# On your Mac, outside the sandbox
openclaw gateway

Keep that process running. Your subagent will now be able to dispatch tasks to ACP agents.

Putting It All Together

Here's the mental model that ties everything together:

NemoClaw is a trust hierarchy.

• The host is fully trusted. It holds real config, real credentials, real tools.
• The gateway is selectively trusted. It decides what requests from the sandbox are allowed.
• The sandbox is minimally trusted. It can only do what the host explicitly permits.
• The subagent lives in the sandbox. It's the least trusted component in the chain.

This isn't a limitation. It's a feature. You can build powerful, capable AI workflows while maintaining clear boundaries about what each piece is allowed to do.

Understanding this hierarchy is the difference between fighting NemoClaw and working with it.

Quick Reference

Host config      →  ~/.nemoclaw/ and ~/.config/openclaw/
Sandbox config   →  /sandbox/.openclaw/ (read-only, injected at boot)
Change settings  →  Always on host, then nemoclaw restart
Check ACP        →  /acp doctor (from inside sandbox)
Start gateway    →  openclaw gateway (on host, outside sandbox)
Check policy     →  nemoclaw <name> config get