debugging-nemoclaw-agents

name	debugging-nemoclaw-agents
description	Diagnoses NemoClaw agent issues across sandbox, policy, and inference layers. Use when agents behave unexpectedly, sandbox won't start, inference fails, network requests are blocked, or plugins report errors.

Debugging NemoClaw Agents

NemoClaw agents span three layers: the sandbox (OpenShell container), the policy engine (network and filesystem rules), and inference (NVIDIA API or local model). Debugging requires checking each layer in order, from the outermost (sandbox) to the innermost (inference).

Diagnostic Checklist

Copy and check off each step as it completes:

Diagnostic Progress:
- [ ] Step 1: Check sandbox status (HOST)
- [ ] Step 2: Review active policy (HOST)
- [ ] Step 3: Stream logs (HOST)
- [ ] Step 4: Run plugin doctor (SANDBOX)
- [ ] Step 5: Test inference (SANDBOX)

Step 1: Check Sandbox Status (HOST)

nemoclaw status
nemoclaw <name> status

Verify:

• The sandbox is listed and shows as Ready (via openshell sandbox list).
• The inference provider and model are correct (via openshell inference get).

For detailed sandbox info including full policy:

openshell sandbox get <name>
openshell inference get

If the sandbox is not running, check openshell sandbox list for its phase. If it's missing, recreate it with nemoclaw onboard or openshell sandbox create.

Step 2: Review Active Policy (HOST)

openshell policy get <sandbox-name>

Verify the policy is not blocking endpoints the agent needs. Common items to check:

• Each required API host has an entry under network_policies.<policy-name>.endpoints[].host.
• filesystem_policy.read_write includes all paths the agent writes to.
• No deny rules override the needed allow rules.

If the policy is missing an endpoint, update the policy YAML and re-apply:

openshell policy set <sandbox-name> --policy policy.yaml --wait

Or use the built-in preset system:

nemoclaw <name> policy-add

Step 3: Stream Logs (HOST)

nemoclaw <name> logs --follow

Or with more filtering via OpenShell:

openshell logs <name> --tail
openshell logs <name> -n 50
openshell logs <name> --since 5m --source sandbox --level debug

Look for these error patterns in the output:

• connection refused -- the OpenShell gateway is not running.
• network policy denied -- an endpoint was blocked by policy.
• inference timeout -- the inference provider did not respond.
• blueprint failed -- the sandbox bootstrap did not complete.

Step 4: Run Plugin Doctor (SANDBOX)

Connect to the sandbox, then run diagnostics:

nemoclaw <name> connect
openclaw plugins doctor

The doctor command reports the health of each installed plugin. Look for plugins in error or degraded state. If a plugin is missing entirely, install it:

openclaw plugins install <plugin-spec>

Step 5: Test Inference (SANDBOX)

Still inside the sandbox, send a test message to the agent:

openclaw agent --agent main --local -m "Test" --session-id debug

If the response fails, check:

• The inference provider is reachable from inside the sandbox (network policy must allow it).
• The API key or credentials are injected correctly via OpenShell providers.
• The model specified in the inference config exists and is available.

Verify inference configuration from the host:

openshell inference get

Quick Diagnostics

NemoClaw has built-in diagnostics:

nemoclaw debug              # Collect diagnostics
nemoclaw debug --quick      # Quick diagnostic check
nemoclaw debug --output FILE  # Save diagnostics tarball for bug reports

Common Errors Reference

For a table of common error patterns, symptoms, causes, and fixes, see common-errors.md.