Set Up Task-Specific Sub-Agents

OpenClaw documents the sub-agent behavior, sessions_spawn tool, agents.list configuration, tool policy, nesting, and auth model in Sub-Agents. Use that page as the source of truth for how OpenClaw sub-agents work.

This page covers the sandbox-specific pieces of a sub-agent setup. It explains where the OpenClaw config lives, where to put per-agent credentials, and which writable workspace path agents should use. It also shows how the Omni VLM demo maps onto those paths.

NemoClaw Sandbox Paths

NemoClaw runs OpenClaw inside an OpenShell sandbox. Use these paths inside the sandbox when you adapt an OpenClaw sub-agent setup:

For file-based tasks, instruct agents to use /sandbox/.openclaw/workspace/. Avoid relying on legacy .openclaw-data paths or read-only OpenClaw paths in delegation instructions.

Omni Vision Sub-Agent Example

The vlm-demo applies the OpenClaw sub-agent pattern to a vision task. It keeps the primary main agent on the normal NemoClaw inference route. It adds a vision-operator sub-agent backed by an Omni vision model.

The sub-agent uses Omni as the specialist model for image tasks. The primary orchestration model remains responsible for conversation, planning, and deciding when to delegate.

Update the Sandbox Config

Fetch the current OpenClaw config from the sandbox. Patch it with your auxiliary provider and agents.list changes, then apply those values in one native OpenClaw config patch. Run the following commands from the host that owns the sandbox containers when you use Docker-driver sandboxes.

Export the Current Config

The container name includes a runtime suffix, so discover it from the OpenShell sandbox label:

export SANDBOX=my-assistant
export SANDBOX_CTR=$(docker ps --filter "label=openshell.ai/sandbox-name=$SANDBOX" --format "{{.Names}}" | sed -n '1p')
if [ -z "$SANDBOX_CTR" ]; then
  echo "No running sandbox container found for $SANDBOX. Start the sandbox before editing its config."
  exit 1
fi
NEMOCLAW_SUBAGENT_UMASK=$(umask)
umask 077
NEMOCLAW_SUBAGENT_TMP=$(mktemp -d)
chmod 700 "$NEMOCLAW_SUBAGENT_TMP"
cleanup_nemoclaw_subagent_files() {
  if [ -n "${NEMOCLAW_SUBAGENT_TMP:-}" ] && [ -d "$NEMOCLAW_SUBAGENT_TMP" ]; then
    rm -rf -- "$NEMOCLAW_SUBAGENT_TMP"
  fi
  umask "$NEMOCLAW_SUBAGENT_UMASK"
}
trap cleanup_nemoclaw_subagent_files EXIT
docker exec --user sandbox "$SANDBOX_CTR" \
  cat /sandbox/.openclaw/openclaw.json > "$NEMOCLAW_SUBAGENT_TMP/openclaw.json"

If SANDBOX_CTR is empty, the sandbox is not running on this host. Start the sandbox, confirm that docker ps shows the matching openshell.ai/sandbox-name label, then rerun the export commands before continuing.

Prepare the Updated Config

Create openclaw.updated.json in the private temporary directory with the OpenClaw sub-agent config. For the Omni example, the demo provides vlm-demo/vlm-subagent/openclaw-patch.py. The helper expects strict JSON, so first use OpenClaw’s pinned JSON5 parser to normalize the exported config without putting its contents in an argument or environment variable. The wrapper reads the key without echoing it and keeps the value out of the child process’s operating-system argument list. Set VLM_DEMO_DIR to the local vlm-demo directory from the demo assets, then run the patch helper.

export VLM_DEMO_DIR=/path/to/nemoclaw-demos/vlm-demo
docker exec --user sandbox -i "$SANDBOX_CTR" \
  node -e '
const JSON5 = require("/usr/local/lib/node_modules/openclaw/node_modules/json5");
let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => { input += chunk; });
process.stdin.on("end", () => {
  process.stdout.write(`${JSON.stringify(JSON5.parse(input), null, 2)}\n`);
});
' < "$NEMOCLAW_SUBAGENT_TMP/openclaw.json" \
  > "$NEMOCLAW_SUBAGENT_TMP/openclaw.strict.json"
(
  read -rsp "NVIDIA API key: " NVIDIA_API_KEY
  printf '\n'
  export NVIDIA_API_KEY
  python3 -c '
import os
import runpy
import sys
helper = sys.argv[1]
sys.argv = [helper, os.environ["NVIDIA_API_KEY"]]
runpy.run_path(helper, run_name="__main__")
' "$VLM_DEMO_DIR/vlm-subagent/openclaw-patch.py" \
    < "$NEMOCLAW_SUBAGENT_TMP/openclaw.strict.json" \
    > "$NEMOCLAW_SUBAGENT_TMP/openclaw.updated.json"
)

The helper reads the normalized config from standard input. It adds the Omni provider and vision-operator entry. It writes the patched config inside the private temporary directory.

For a sub-agent other than the Omni example, copy the exported config to openclaw.updated.json in the private temporary directory. Use cp "$NEMOCLAW_SUBAGENT_TMP/openclaw.json" "$NEMOCLAW_SUBAGENT_TMP/openclaw.updated.json". Before applying the file, add your provider under models.providers and your sub-agent under agents.list. Set AUX_PROVIDER_ID to that provider key before you apply the config. The command below defaults to nvidia-omni for the Omni example. Do not commit the temporary files or any other file that contains a real API key.

Apply the Updated Config

Stream the prepared JSON5 config into the sandbox as the sandbox user. The first process builds one minimal JSON patch, and the second process applies it with one native OpenClaw command.

(
  set -euo pipefail
  : "${AUX_PROVIDER_ID:=nvidia-omni}"
  docker exec --user sandbox -i "$SANDBOX_CTR" \
    node -e '
const JSON5 = require("/usr/local/lib/node_modules/openclaw/node_modules/json5");
let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => { input += chunk; });
process.stdin.on("end", () => {
  const config = JSON5.parse(input);
  const providerId = process.argv[1];
  const provider = config.models?.providers?.[providerId];
  const defaults = config.agents?.defaults;
  const agents = config.agents?.list;
  if (provider === undefined || defaults?.timeoutSeconds === undefined || !Array.isArray(agents)) {
    throw new Error("Prepared config is missing the provider, timeoutSeconds, or agents.list");
  }
  const patch = {
    models: { providers: { [providerId]: provider } },
    agents: { defaults: { timeoutSeconds: defaults.timeoutSeconds }, list: agents },
  };
  if (Object.hasOwn(defaults, "subagents")) {
    patch.agents.defaults.subagents = defaults.subagents;
  }
  process.stdout.write(JSON.stringify(patch));
});
' "$AUX_PROVIDER_ID" < "$NEMOCLAW_SUBAGENT_TMP/openclaw.updated.json" |
    docker exec --user sandbox -i "$SANDBOX_CTR" \
      /usr/bin/env HOME=/sandbox openclaw config patch --stdin
)

For ordinary key changes, connect to the sandbox and use openclaw configure, openclaw config set, or openclaw config unset.

Node parses the prepared JSON5 and sends only the selected provider, optional agents.defaults.subagents, agents.defaults.timeoutSeconds, and agents.list to OpenClaw through standard input. OpenClaw validates the requested changes before applying them. A parsing or validation error prevents the requested update. A write failure or lost Docker connection can leave completion uncertain; do not assume the original configuration remains unchanged. Do not restart the gateway while the update result is uncertain. Reconnect and inspect the intended non-secret settings. Resolve the reported error before repeating this section. Restart the gateway only after the update succeeds. On success, OpenClaw serializes the complete config as standard JSON, so JSON5 comments and formatting in the original file are removed.

After the patch succeeds, restart the managed gateway. The restart verifies gateway health before it exits successfully. Then confirm that OpenClaw loaded the agents.list change:

nemoclaw "$SANDBOX" gateway restart
nemoclaw "$SANDBOX" agents list --json

The agents list output should include vision-operator. If the restart fails, correct the reported gateway error and rerun nemoclaw "$SANDBOX" gateway restart before you use the sub-agent.

Add Sub-Agent Credentials

Put the provider key in the sub-agent auth profile when the auxiliary model uses a provider outside the normal NemoClaw inference route. For the Omni example:

/sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json

Use the same provider ID that appears in models.providers, such as nvidia-omni. Create auth-profiles.json in $NEMOCLAW_SUBAGENT_TMP from vlm-demo/vlm-subagent/auth-profiles.template.json. Replace YOUR_NVIDIA_API_KEY_HERE with the provider key. The private directory and restrictive umask limit access to the host copy until you install it in the sandbox. Installation runs as the sandbox user and creates a random temporary file with mode 0600 before replacing the destination. Other processes running as the sandbox user can read the credential; file permissions do not isolate sub-agents from each other.

docker exec --user sandbox "$SANDBOX_CTR" \
  install -d -m 700 /sandbox/.openclaw/agents/vision-operator/agent
docker exec --user sandbox -i "$SANDBOX_CTR" sh -ceu '
target=$1
umask 077
temporary=$(mktemp "${target}.nemoclaw.XXXXXX")
trap '\''rm -f -- "$temporary"'\'' 0
cat > "$temporary"
chmod 600 "$temporary"
mv -fT -- "$temporary" "$target"
trap - 0
' sh /sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json \
  < "$NEMOCLAW_SUBAGENT_TMP/auth-profiles.json"
trap - EXIT
cleanup_nemoclaw_subagent_files
unset NEMOCLAW_SUBAGENT_TMP NEMOCLAW_SUBAGENT_UMASK

The cleanup removes the host copies of the full config and credentials after the sandbox installation. If you stop before this step, exit the shell or run cleanup_nemoclaw_subagent_files yourself.

Credential Access and Removal

The Omni demo helper stores the real provider key in two persistent sandbox files:

• models.providers.nvidia-omni.apiKey in /sandbox/.openclaw/openclaw.json.
• providers.nvidia-omni.apiKey in /sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json.

OpenClaw and any other process running as the sandbox user can read these files. Container root and administrators of the Docker host can also read them. The files remain across gateway restarts and for the life of the current sandbox container until you replace the key, remove the provider, or delete the sandbox. A rebuild inspects the complete native home and fails before replacement when it finds these credential values; it does not strip them from an otherwise published transfer. Remove both copies or move the credential into supported OpenShell storage before rebuilding, then provision the auxiliary provider again after rebuild. The retired selective snapshot restore flow is not available.

When you remove vision-operator, first remove it from agents.list. Then remove the provider and the retired agent’s credential file, and restart the gateway:

docker exec --user sandbox "$SANDBOX_CTR" \
  /usr/bin/env HOME=/sandbox openclaw config unset models.providers.nvidia-omni
docker exec --user sandbox "$SANDBOX_CTR" \
  rm -f -- /sandbox/.openclaw/agents/vision-operator/agent/auth-profiles.json
nemoclaw "$SANDBOX" gateway restart

If you retarget vision-operator to another provider, do not delete the whole credential file. Remove only the retired providers.nvidia-omni entry and preserve every other provider entry. Then remove the retired provider from the native config with the openclaw config unset command above and restart the gateway.

Removing the two active entries does not remove credentials from OpenClaw backups or rejected payloads. Replace the key in any other clients that still need it. Then revoke the retired key with its provider. Rotate the provider key if any active or retained copy may have been exposed.

Allow Auxiliary Provider Egress

Update the OpenShell network policy for the binary that makes the request when the sub-agent calls a provider directly. In the Omni demo, the OpenClaw gateway runs as /usr/local/bin/node. The NVIDIA endpoint policy must allow that binary.

Refer to Customize the Network Policy for policy update workflows.

Sub-Agent Gateway Connectivity

Spawned agents connect to the selected sandbox’s gateway through OpenClaw’s native loopback endpoint. NemoClaw leaves OPENCLAW_GATEWAY_URL unset by default, so the gateway, CLI, daemon RPC, and spawned agents share OpenClaw’s configured local port without routing sandbox-local traffic through the external proxy. An explicit operator endpoint remains authoritative.

Troubleshoot Gateway Connectivity

The local path is unhealthy if sessions_spawn returns gateway closed (1006 abnormal closure (no close frame)) and the gateway log shows no connection attempt. Check the following:

1. The gateway and client resolve the same NEMOCLAW_DASHBOARD_PORT.
2. No unexpected OPENCLAW_GATEWAY_URL override is present.
3. Gateway authentication and device pairing are healthy for the selected sandbox.

Add Delegation Instructions

OpenClaw handles sessions_spawn. The primary agent still needs task instructions. Place those instructions in the writable workspace, for example:

/sandbox/.openclaw/workspace/TOOLS.md

The Omni demo includes vlm-demo/vlm-subagent/TOOLS.md. It tells main to delegate image tasks to vision-operator. It tells the sub-agent to read the image path it receives. Adapt that file for other task-specific models.

Demo Assets

Use the vlm-demo repository for runnable Omni assets:

• vlm-subagent-guide.md for a command-by-command walkthrough.
• vlm-subagent/openclaw-patch.py for patching openclaw.json.
• vlm-subagent/auth-profiles.template.json for the sub-agent auth profile.
• vlm-subagent/TOOLS.md for delegation instructions.

Next Steps

Continue with these resources:

• Refer to OpenClaw Sub-Agents for sessions_spawn, agents.list, nesting, tool policy, and auth behavior.
• Refer to Switch Inference Providers to change the primary orchestration model instead of adding a sub-agent model.
• Refer to Understand Sandbox State to understand per-agent workspace directories.