|
| 1 | +# Declarative Multi-Agent Manifest |
| 2 | + |
| 3 | +NemoClaw can bake a multi-agent OpenClaw layout into a sandbox image from a single checked-in manifest. |
| 4 | +Supply the manifest at onboard time with `--agents <path>` and NemoClaw embeds the resulting `agents.list` entries, per-agent overrides, and `agents.defaults.subagents` block into `openclaw.json` during the image build. |
| 5 | + |
| 6 | +The schema mirrors OpenClaw's own `agents.list[]` field names, so the same keys you read in [OpenClaw's sub-agents reference](https://docs.openclaw.ai/tools/subagents) appear verbatim in the manifest. |
| 7 | + |
| 8 | +## When To Use This |
| 9 | + |
| 10 | +Use `--agents` when: |
| 11 | + |
| 12 | +- You want a repeatable, GitOps-friendly multi-agent sandbox (manager + workers, or a research / writing split). |
| 13 | +- A secondary agent needs its own model (different size, different capability profile). |
| 14 | +- You want OpenClaw's `sessions_spawn` validator to enforce a fixed spawn allowlist, not the broad default. |
| 15 | + |
| 16 | +For a single primary agent on the configured inference route, no manifest is required — the canonical `main` agent is always baked in as the default. |
| 17 | + |
| 18 | +## Invocation |
| 19 | + |
| 20 | +```bash |
| 21 | +nemoclaw onboard --agents ./agents.yaml --name my-assistant |
| 22 | +``` |
| 23 | + |
| 24 | +NemoClaw reads the manifest on the host, sets `NEMOCLAW_EXTRA_AGENTS_JSON` for the Dockerfile patcher, and the build-time validator in `scripts/generate-openclaw-config.mts` is the single source of truth for structured errors. |
| 25 | +A malformed manifest fails the image build with a clear error message. |
| 26 | + |
| 27 | +## Manifest Shape |
| 28 | + |
| 29 | +```yaml |
| 30 | +defaults: |
| 31 | + subagents: |
| 32 | + maxSpawnDepth: 2 # optional; OpenClaw allows 1..5 |
| 33 | + |
| 34 | +main: # optional augments to the canonical "main" agent |
| 35 | + tools: |
| 36 | + profile: minimal |
| 37 | + allow: [read] |
| 38 | + subagents: |
| 39 | + allowAgents: [logs-reader, writer] |
| 40 | + delegationMode: prefer |
| 41 | + requireAgentId: true |
| 42 | + |
| 43 | +agents: # required when secondary agents are needed |
| 44 | + - id: logs-reader |
| 45 | + description: "Reads sandbox logs" |
| 46 | + model: nvidia/nemotron-3-nano-30b |
| 47 | + tools: |
| 48 | + allow: [read, exec] |
| 49 | + subagents: |
| 50 | + requireAgentId: true |
| 51 | + |
| 52 | + - id: writer |
| 53 | + model: nvidia/nemotron-3-super-120b-a12b |
| 54 | + tools: |
| 55 | + allow: [read, write] |
| 56 | +``` |
| 57 | +
|
| 58 | +### Top-Level Fields |
| 59 | +
|
| 60 | +| Field | Purpose | Bakes Into | |
| 61 | +|---|---|---| |
| 62 | +| `defaults.subagents.maxSpawnDepth` | Maximum nesting depth for sub-agent spawning. Integer 1..5. | `agents.defaults.subagents.maxSpawnDepth` | |
| 63 | +| `main.tools` | Per-agent tool policy for the canonical `main` agent. | `agents.list[id=main].tools` | |
| 64 | +| `main.subagents` | Sub-agent delegation policy for `main`. Same shape as a secondary agent's `subagents` block. | `agents.list[id=main].subagents` | |
| 65 | +| `agents[]` | Secondary agents to append after `main` in `agents.list`. | `agents.list[]` | |
| 66 | + |
| 67 | +The `main` agent is always written first into `agents.list` with `default: true`. |
| 68 | +Operators cannot set `default: true` on a secondary agent and cannot rename the primary slot. |
| 69 | + |
| 70 | +### Per-Agent Fields |
| 71 | + |
| 72 | +| Field | Required | Purpose | |
| 73 | +|---|---|---| |
| 74 | +| `id` | yes | Lowercase alphanumeric + `_`/`-`, 1-32 chars, must start with a letter. Cannot be `main`. | |
| 75 | +| `workspace` | auto-filled | Defaults to `/sandbox/.openclaw/workspace-<id>`. Must match the canonical sandbox layout if supplied. | |
| 76 | +| `agentDir` | auto-filled | Defaults to `/sandbox/.openclaw/agents/<id>`. Must match the canonical sandbox layout if supplied. | |
| 77 | +| `tools` | yes | `{profile?, allow?, deny?}`. Must declare a non-empty `allow[]` or `deny[]` — secondary agents inherit no tools by default. | |
| 78 | +| `description` | no | Human-readable. Baked verbatim. | |
| 79 | +| `model` | no | `provider/model` reference. The provider must match the onboard provider; cross-provider manifests are not supported. | |
| 80 | +| `subagents` | no | OpenClaw-native sub-agent delegation policy. See below. | |
| 81 | + |
| 82 | +### Sub-Agent Delegation Block |
| 83 | + |
| 84 | +Both `main.subagents` and `agents[].subagents` use the same shape, which mirrors OpenClaw's [`agents.list[].subagents`](https://docs.openclaw.ai/gateway/config-agents). |
| 85 | + |
| 86 | +| Field | Type | Purpose | |
| 87 | +|---|---|---| |
| 88 | +| `delegationMode` | `"suggest"` or `"prefer"` | Prompt-only steering for how strongly this agent should delegate. No enforcement. | |
| 89 | +| `allowAgents` | `string[]` | Allowlist of agent ids this agent may target via `sessions_spawn`. `["*"]` allows any configured target; omit for self-only. | |
| 90 | +| `model` | `provider/model` | Default model for spawned sub-agents. Provider must match the onboard provider. | |
| 91 | +| `thinking` | string | Default thinking level for spawned sub-agents. | |
| 92 | +| `requireAgentId` | boolean | Force the model to pass `agentId` explicitly to `sessions_spawn` rather than defaulting to self. | |
| 93 | + |
| 94 | +`maxSpawnDepth` is **not accepted per-agent** — OpenClaw only honours it on `agents.defaults.subagents`, so the manifest exposes it only under the top-level `defaults` block. |
| 95 | + |
| 96 | +### Multi-Model Sandboxes |
| 97 | + |
| 98 | +When a secondary agent declares its own `model` (or `subagents.model`), NemoClaw widens the baked `models.providers[<onboard-provider>].models[]` array with one entry per unique `provider/model` reference. |
| 99 | +The base `contextWindow`, `maxTokens`, `reasoning`, and `input` settings from the onboard route apply to each appended entry. |
| 100 | +Per-model overrides beyond these defaults are out of scope for v1 — edit the generated `openclaw.json` in-place if you need finer control. |
| 101 | + |
| 102 | +## Manager-Worker Example |
| 103 | + |
| 104 | +```yaml |
| 105 | +defaults: |
| 106 | + subagents: |
| 107 | + maxSpawnDepth: 2 |
| 108 | +
|
| 109 | +main: |
| 110 | + subagents: |
| 111 | + allowAgents: [logs-reader] |
| 112 | + delegationMode: prefer |
| 113 | + requireAgentId: true |
| 114 | +
|
| 115 | +agents: |
| 116 | + - id: logs-reader |
| 117 | + description: "Reads /var/log and surfaces error lines" |
| 118 | + tools: |
| 119 | + allow: [read] |
| 120 | +``` |
| 121 | + |
| 122 | +What this produces in the baked `openclaw.json`: |
| 123 | + |
| 124 | +- `agents.list[0]` is `main` with `default: true`, the operator-supplied `tools`/`subagents` merged in. |
| 125 | +- `agents.list[1]` is `logs-reader` at the canonical workspace/agentDir paths. |
| 126 | +- The primary model stays whatever was selected at onboard. |
| 127 | +- `agents.defaults.subagents.maxSpawnDepth` is `2`. |
| 128 | +- `sessions_spawn` from `main` resolves to `logs-reader` only. |
| 129 | + |
| 130 | +## Iterating |
| 131 | + |
| 132 | +Edit `agents.yaml`, re-run `nemoclaw onboard --agents ./agents.yaml --recreate-sandbox`. |
| 133 | +Workspaces under `/sandbox/.openclaw/workspace-<id>` are preserved across rebuilds because the runtime startup script provisions them on first boot rather than baking their contents. |
| 134 | + |
| 135 | +For ad-hoc per-agent edits inside an existing sandbox (no rebuild), use the in-sandbox CLI: `nemoclaw <name> agents add|delete|list`. |
| 136 | +The manifest path is for fixed, checked-in layouts; the CLI passthrough is for interactive work. |
| 137 | + |
| 138 | +## Apply To An Existing Sandbox |
| 139 | + |
| 140 | +`nemoclaw <name> agents apply -f <agents.yaml>` reconciles the live sandbox roster against the manifest **without a rebuild**. |
| 141 | +The verb lists current agents via `openclaw agents list --json`, diffs them against the manifest, and drives `openclaw agents add|delete` per item. |
| 142 | +Per-agent `model`, `subagents.*`, top-level `defaults`, and `main` overrides require a sandbox rebuild and are reported as warnings the verb prints before exit; rerun `nemoclaw onboard --agents <file> --recreate-sandbox` to bake those. |
| 143 | + |
| 144 | +```bash |
| 145 | +nemoclaw my-assistant agents apply -f ./agents.yaml --yes |
| 146 | +``` |
| 147 | + |
| 148 | +The flag pair `--yes / --non-interactive` is required for scripted use: `--yes` confirms the printed roster diff, and `--non-interactive` makes the verb fail fast when `--yes` is absent rather than waiting for an interactive prompt that scripted callers cannot deliver. |
| 149 | + |
| 150 | +## Next Steps |
| 151 | + |
| 152 | +Use the following resources for more information: |
| 153 | + |
| 154 | +- Refer to [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for the runtime semantics of `sessions_spawn`, `subagents.allowAgents`, and nesting depth. |
| 155 | +- Refer to [Set Up Task-Specific Sub-Agents](set-up-sub-agent.md) for the in-sandbox path that edits `agents.list` directly without a rebuild. |
| 156 | +- Refer to [Switch Inference Providers](switch-inference-providers.md) before swapping the primary onboard provider — per-agent `model` refs must share that provider. |
| 157 | +- Refer to Workspace Files (use the `nemoclaw-user-manage-sandboxes` skill) to understand how per-agent `workspace-<id>` directories are provisioned and persisted across rebuilds. |
0 commit comments