README.md

---
title: NemoClaw Developer Guide
emoji: 🦞
colorFrom: blue
colorTo: green
sdk: static
pinned: false
---
<p align="center"><table align="center"><tr><td align="center"><img src="images/logo_HP_Electric_Blue_keyline.png" alt="HP" width="80"></td><td width="40"></td><td align="center"><img src="images/nvidia-logo-vert.png" alt="NVIDIA" width="80"></td></tr></table></p>

<p align="center"><em>Company logos are used for identification purposes only and do not imply endorsement or official partnership unless otherwise stated.</em></p>

# Agentic AI with NemoClaw — Developer Guide

**Building Multi-Agent Pipelines on the HP ZGX Nano AI Station**

*Written and prepared by Curtis Burkhalter, Ph.D. | Technical Product Marketing Manager, AI Solutions at HP*

---

## What This Guide Covers

This guide documents how to build a multi-agent AI pipeline using NVIDIA NemoClaw and OpenShell on the HP ZGX Nano AI Station. It covers the real-world setup, the problems you'll hit, and the solutions that actually work — not the theory, the practice.

The reference implementation is a four-agent "Autonomous Software Factory" that takes a plain-English specification and produces a working city infrastructure health dashboard. Each agent runs in an isolated NemoClaw sandbox backed by local LLM inference via Ollama.

**Pipeline:** Architect → Coder → Reviewer → Analyst

**Hardware:** HP ZGX Nano AI Station (NVIDIA GB10 Grace Blackwell, ARM64, 128GB unified memory)

**Models:** Qwen3-32B (Architect), Qwen3-Coder-30B-A3B (Coder, Reviewer, Analyst)

**Source:** [github.com/curtburk/nemoclaw-demo](https://github.com/curtburk/nemoclaw-demo)

---

## Prerequisites

- HP ZGX Nano AI Station (or any NVIDIA GPU system with 64GB+ memory)
- NemoClaw installed (`nemoclaw --help` responds)
- OpenShell CLI installed (`openshell --help` responds)
- Ollama installed with your models pulled
- Python 3.10+ on the host

---

## 1. NemoClaw Setup

### 1.1 Onboarding a Sandbox

```bash
nemoclaw onboard
```

The wizard walks you through provider configuration and sandbox creation. Choose "Local Ollama" when prompted. You'll hit a **sandbox policy parsing error** on the current version (v0.1.0):

```
Error: failed to parse sandbox policy YAML
  network_policies.name: invalid type: string "github", expected struct
```

**Workaround:** The image builds successfully — the error is only on sandbox creation. Grab the image tag from the build output and create manually:

```bash
openshell sandbox create --name architect --from openshell/sandbox-from:<IMAGE_TAG>
```

### 1.2 Creating Multiple Sandboxes

NemoClaw's onboarding creates one sandbox at a time. For a multi-agent pipeline, run `nemoclaw onboard` once per agent, then use the image reuse trick for agents that share the same model:

```bash
# Build image once via onboard (select qwen3-coder:latest)
nemoclaw onboard  # → name it "coder", note the image tag

# Reuse that image for reviewer and analyst
openshell sandbox create --name reviewer --from openshell/sandbox-from:<SAME_TAG>
openshell sandbox create --name analyst --from openshell/sandbox-from:<SAME_TAG>
```

### 1.3 Verify Sandbox Connectivity

```bash
ssh -o BatchMode=yes openshell-architect "echo OK"
ssh -o BatchMode=yes openshell-coder "echo OK"
ssh -o BatchMode=yes openshell-reviewer "echo OK"
ssh -o BatchMode=yes openshell-analyst "echo OK"
```

---

## 2. Model Configuration

### 2.1 Using Different Models Per Sandbox

The gateway inference route is global — one model for all sandboxes. But each sandbox's `openclaw.json` specifies which model to request, and Ollama serves whichever model the request asks for. So you can run different models per agent even with a single provider.

To set this up, run `nemoclaw onboard` separately for the sandbox that needs a different model (e.g., Architect with `qwen3:32b`), then use `qwen3-coder:latest` for the rest.

### 2.2 The maxTokens Problem

**Critical:** NemoClaw hardcodes `maxTokens: 4096` in the Dockerfile that generates `openclaw.json`. This limits model output to ~3,000 characters — too short for code generation.

**Fix:** Patch the Dockerfile before building sandbox images:

```bash
sed -i "s/'maxTokens': 4096/'maxTokens': 16384/" \
  ~/.nvm/versions/node/v22.22.2/lib/node_modules/nemoclaw/Dockerfile
```

Verify:

```bash
grep "maxTokens" ~/.nvm/versions/node/v22.22.2/lib/node_modules/nemoclaw/Dockerfile
```

Then rebuild your sandboxes. The path may differ based on your Node.js version — use `which nemoclaw` to find it.

### 2.3 Model Output Limits

Even with `maxTokens: 16384`, Qwen3-Coder-30B-A3B naturally stops generating at ~2,000 characters. This is a model behavior, not a configuration issue. Design your prompts accordingly — see Section 4.

### 2.4 Thinking Tokens

Qwen3-Coder uses internal reasoning tokens by default. These consume output budget without producing visible output. Always pass `--thinking off`:

```bash
openclaw agent --agent main --local --thinking off --session-id my-session -m "your prompt"
```

---

## 3. Orchestrator Architecture

### 3.1 Sending Prompts to Sandboxes

`openclaw agent` requires `-m <text>` — it does not read from stdin. Long prompts with special characters break shell escaping. The solution: pipe the prompt into a file inside the sandbox, then use command substitution.

```python
# Step 1: Upload prompt via stdin → file
upload_cmd = ["ssh", ssh_host, "cat > /tmp/prompt.txt"]
subprocess.run(upload_cmd, input=prompt, text=True)

# Step 2: Run agent with file content
agent_cmd = ["ssh", ssh_host,
    'openclaw agent --agent main --local --thinking off '
    '--session-id my-session -m "$(cat /tmp/prompt.txt)"']
subprocess.run(agent_cmd, capture_output=True, text=True)
```

### 3.2 Session ID Management

**Use unique session IDs per call.** OpenClaw accumulates conversation history within a session. If the Coder retries three times with the same session ID, the context window fills with prior failed attempts, squeezing out output tokens.

```python
import uuid
call_session = f"pipeline-{agent_name}-{uuid.uuid4().hex[:8]}"
```

### 3.3 Cleaning Model Output

The model frequently emits OpenClaw tool-call artifacts in its output:

```
</parameter>
<parameter=file_path>
/sandbox/.openclaw/workspace/file.js
</parameter>
</function>
</tool_call>
```

Strip these before processing:

```python
import re
output = re.sub(r'</parameter>.*', '', output, flags=re.DOTALL)
output = re.sub(r'<parameter[^>]*>.*', '', output, flags=re.DOTALL)
output = re.sub(r'</function>.*', '', output, flags=re.DOTALL)
output = re.sub(r'</tool_call>.*', '', output, flags=re.DOTALL)
```

### 3.4 Streaming Output to a Live UI

When launching the orchestrator as a subprocess, Python buffers stdout. Force immediate flushing:

```python
# In the orchestrator — every print() call
print(line, flush=True)

# In the UI server — launch with unbuffered flag
env = dict(os.environ, PYTHONUNBUFFERED="1")
subprocess.Popen([sys.executable, "-u", "orchestrator.py"], env=env)
```

---

## 4. Prompt Engineering for Small Models

The most important lesson from this project: **a 3B-active-parameter MoE (Qwen3-Coder-30B-A3B) requires fundamentally different prompting than a frontier model.**

### 4.1 Be Prescriptive, Not Descriptive

Don't ask the model to design. Tell it exactly what to produce.

**Bad:** "Generate sensor data with realistic values for a city infrastructure system"

**Good:** "voltage: random.uniform(115, 125). NOT 220-240. NOT European voltage."

The model will substitute its training priors for your specifications unless you're explicit — and sometimes even then. Including "NOT X" alongside "use Y" is more reliable than "use Y" alone.

### 4.2 Provide Skeletons, Not Specs

Don't ask the model to write 120 lines from scratch. Give it 80 lines of skeleton with TODOs to fill in. The model contributes 15-30 lines of logic instead of generating boilerplate that blows the token budget.

```
Complete this skeleton. Fill in the TODO sections.
Do NOT modify the existing code. Do NOT add Pydantic models.

```python
def generate_sensors():
    data = {}
    for d in DISTRICTS:
        power = {"voltage": round(random.uniform(115,125),1), ...}
        # TODO: Override anomaly districts
        data[d] = {"power": power, "water": water, "traffic": traffic}
    return data

@app.get("/api/health")
def health():
    # TODO: compute overall status
    pass
```
```

### 4.3 Binary Reviews, Not Open-Ended Critique

A 3B-active model cannot reliably do nuanced code review. It will flag correct code as wrong if the review criteria are ambiguous. Reduce the Reviewer to binary checks:

1. Are all three endpoints present?
2. Do they return data (not `pass`)?
3. Is CORS enabled?
4. Does uvicorn bind to the right port?
5. Any syntax errors?

### 4.4 Template Injection for Large Outputs

The model caps output at ~2,000 characters. A full HTML dashboard with Chart.js is 5,000-8,000 characters. Don't fight the limit — work with it.

Have the model generate only the dynamic part (a `generateData()` function), then inject it into a pre-built template:

```python
template = open("dashboard_template.html").read()
gen_func = run_agent("analyst", "Output ONLY a generateData() function...")
dashboard = template.replace("%%GENERATE_DATA%%", gen_func)
```

### 4.5 Always Start with "Output ONLY..."

Every prompt to `openclaw agent` should begin with a forceful instruction:

```
Output ONLY raw HTML. No explanation. No markdown. Start with <!DOCTYPE html>.
```

```
Output ONLY a Python code block. Start with ```python end with ```. No explanation.
```

Without this, the agent wraps its output in conversational prose, markdown formatting, or tool-call XML.

---

## 5. Lessons Learned

| Problem | Root Cause | Solution |
|---------|-----------|----------|
| Model ignores explicit values | Training priors override prompt | Include "NOT X" alongside "use Y" |
| Output truncated mid-code | maxTokens: 4096 hardcoded | Patch NemoClaw Dockerfile |
| Output still truncated | Thinking tokens consume budget | `--thinking off` on every call |
| Output still short (~2K chars) | Model's natural stop behavior | Skeleton prompts, template injection |
| Retries produce worse output | Session context accumulates | Unique session ID per call |
| Tool-call XML in output | OpenClaw agent framework | Regex cleanup post-processing |
| Reviewer rejects valid code | Reviewing against drifted plan | Binary checks, not schema comparison |
| Sandbox creation fails | Policy YAML parsing bug | Create manually via `openshell sandbox create` |
| Live UI shows no output | Python stdout buffering | `flush=True` + `PYTHONUNBUFFERED=1` |
| Port 8080 in use | NemoClaw gateway occupies it | Use different port for UI server |

---

## 6. Project Structure

```
nemoclaw-demo/
├── orchestrator.py              # Main pipeline
├── ui_server.py                 # Live browser UI (port 8888)
├── prompts/
│   ├── architect.txt            # Spec → plan
│   ├── coder_initial.txt        # Plan → code (skeleton)
│   ├── coder_retry.txt          # Error → fixed code
│   ├── reviewer.txt             # Code → binary verdict
│   ├── analyst.txt              # → generateData() function
│   └── dashboard_template.html  # Pre-built dashboard UI
├── fallback/
│   ├── generated_app.py         # Known-good backend
│   └── dashboard.html           # Known-good dashboard
├── output/                      # Pipeline output
└── logs/                        # Per-run logs
```

---

## 7. Running the Demo

```bash
# Terminal 1: Start the live UI
python3 ui_server.py

# Open in browser (use the Network URL it prints)
# Click RUN PIPELINE
```

Or run the pipeline directly:

```bash
python3 orchestrator.py
# Open output/dashboard.html in a browser
```

---

## Security Architecture

Each NemoClaw sandbox enforces:

- **Landlock** filesystem restrictions — agents see only `/sandbox` and `/tmp`
- **seccomp** system call filtering — blocked syscalls fail silently
- **Network namespace isolation** — no direct egress, only `inference.local`
- **Inference routing** — agents hit `inference.local`, the gateway routes to Ollama; the agent never sees host IPs or ports

The orchestrator runs on the host as a trusted operator. Agents never communicate directly — every artifact passes through the host-side orchestrator. This is least-privilege at the agent level.

---

*Last updated: April 2026*
*NemoClaw v0.1.0 | OpenShell v0.0.16 | OpenClaw 2026.3.11*