OpenClaw SubAgents Creator

This skill should be used when the user wants to configure, spawn, or manage OpenClaw (formerly Clawdbot) subagents. It covers the full setup workflow: editi...

Security Scan

The skill's declared purpose (creating and managing OpenClaw subagents) matches the instructions, but the docs instruct storing and using sensitive session keys, running shells/browser/cron/pm2, and using external CLIs (Convex) without declaring the credentials or clear sandboxing — these gaps increase risk and deserve attention before installing.

Purpose & Capability

The name and description match what the SKILL.md and reference files actually instruct: editing ~/.openclaw/openclaw.json, creating workspace files (SOUL.md, AGENTS.md, HEARTBEAT.md, memory files), using the sessions_spawn tool, and managing cron/pm2 daemons. All required commands and paths are coherent with an OpenClaw subagent-management skill.

Instruction Scope

The instructions go beyond simple config examples: they explicitly direct agents/operators to run shells and browser scraping, run arbitrary scripts in ~/.openclaw/workspace-<agentId>/scripts/, run npx convex commands, add cron jobs, and run a pm2 notification daemon that reads an AGENT_SESSIONS mapping and uses clawdbot.sessions.send. That scope is plausible for managing subagents but also grants the ability to execute arbitrary code and access local files. The docs also instruct storing and using session keys (sensitive values) inside AGENTS.md/workspace files which can lead to credential exposure if not handled carefully.

Install Mechanism

No install spec is present (instruction-only skill). That lowers installation risk — nothing will be fetched or written by the registry installer itself. All persistent actions are operator-driven (cron, pm2, CLI), not implicit installs by the skill bundle.

Credentials

The SKILL.md shows commands that require external credentials (Convex CLI via npx convex, gateway/agent session keys used for sessions.send) but the skill declares no required environment variables or primary credential. The documentation suggests storing session keys in AGENTS.md (and using AGENT_SESSIONS mapping in the notification daemon), which is sensitive. In short: credential access is necessary for full operation but is not declared or guided safely in the skill; that mismatch is a security concern.

Persistence & Privilege

The skill itself is not always-enabled and has no install hooks, but the instructions guide the operator to create persistent background processes (cron heartbeats, pm2 notification daemon, gateway daemon). Those persistent services increase the runtime blast radius (they run continuously and can perform actions over time) — this is expected for an orchestration skill but users should recognise they are being instructed to create persistent system services.

What to consider before installing

This skill appears to implement exactly what it claims, but it instructs you to create persistent cron/pm2 jobs, run shell/browser actions, and store/use session keys and Convex CLI credentials. Before installing/using it: (1) Confirm where and how session keys and Convex/gateway credentials will be stored — avoid plaintext in shared files; (2) Limit subagent tool permissions and enable per-agent sandboxing (use tools.deny / allowAgents / sandbox settings) so subagents cannot exec arbitrary host commands or read unrelated files; (3) Treat AGENTS.md and workspace directories as sensitive — rotate and restrict access to session keys; (4) Run the notification daemon and crons in a controlled environment (container or restricted user account) if possible; (5) If you need stronger assurance, ask the skill author for explicit documentation of required environment variables/credentials and an audited example deploy manifest showing least-privilege sandboxing. Providing those details would move this assessment toward 'benign'.

OpenClaw Subagents Configuration Skill

Overview

Configure and manage OpenClaw subagents — background agent runs spawned from a main agent that operate in isolated sessions and report results back upon completion. This skill covers everything from a single subagent spawn to full multi-agent squad orchestration.

References

Load these files as needed during configuration:

• references/config-reference.md — Full openclaw.json schema for subagents (all fields, defaults, per-agent overrides)
• references/sessions-spawn-tool.md — sessions_spawn tool parameters, slash commands, and behavior details
• references/agent-files.md — SOUL.md, AGENTS.md, HEARTBEAT.md, and memory file templates
• references/multi-agent-architecture.md — Depth levels, tool access rules, announce chain, Mission Control integration

---

Step 1: Determine Setup Type

Ask or infer from context which pattern the user needs:

Pattern	Description	maxSpawnDepth
Single subagent	Main agent spawns one background worker	1 (default)
Orchestrator	Main -> orchestrator -> workers (nested)	2
Multi-agent squad	Multiple independent agents sharing a task DB	1 per agent

---

Step 2: Configure openclaw.json

Config lives at ~/.openclaw/openclaw.json. Load references/config-reference.md for the full schema.

Minimal subagents config:

{
  agents: {
    defaults: {
      subagents: {
        model: "anthropic/claude-haiku-4-5",  // use cheaper model for subagents
        maxSpawnDepth: 1,                      // set to 2 for orchestrator pattern
        maxChildrenPerAgent: 5,               // max active children per session (1-20)
        maxConcurrent: 8,                     // global concurrency limit
        runTimeoutSeconds: 900,               // abort after N seconds (0 = no limit)
        archiveAfterMinutes: 60               // auto-delete transcript after N minutes
      }
    },
    list: [
      {
        id: "main",
        workspace: "~/.openclaw/workspace-main"
      }
    ]
  }
}

For per-agent model overrides and tool restrictions, see references/config-reference.md.

---

Step 3: Create Agent Identity Files

Each agent workspace at ~/.openclaw/workspace-<agentId>/ needs identity files. Load references/agent-files.md for full templates.

File	Purpose	Injected into subagents?
SOUL.md	Personality, role, voice	No
AGENTS.md	Operational procedures, tools, Mission Control	Yes
HEARTBEAT.md	Wake-up checklist	Yes (via cron message)
memory/WORKING.md	Current task state	Agent maintains this
memory/MEMORY.md	Long-term curated facts	Agent maintains this

---

Step 4: Set Up Cron Heartbeats

Each agent wakes every 15 minutes via cron. Stagger agents by 2 minutes each:

openclaw cron add \
  --name "agent-heartbeat" \
  --cron "0,15,30,45 * * * *" \
  --session "isolated" \
  --message "You are <AgentName>, the <Role>. Read WORKING.md. Check Mission Control for @mentions and assigned tasks. If work exists, do it and update WORKING.md. If nothing to do, reply HEARTBEAT_OK."

Suggested stagger schedule for a squad:

:00 Agent 1 (e.g. Pepper)
:02 Agent 2 (e.g. Shuri)
:04 Agent 3 (e.g. Friday)
:06 Agent 4 (e.g. Loki)
:08 Agent 5 (e.g. Vision)

---

Step 5: Spawning Subagents

Subagents are spawned non-blocking — the tool returns a run ID immediately and the result is announced on completion.

From within an agent (agent calls sessions_spawn tool with these params):

task: "Research competitor pricing for task #42 and post findings as a comment"
agentId: "researcher"          // optional: target specific agent
label: "competitor-research"   // optional: human-readable name
model: "claude-haiku-4-5"     // optional: override model
thinking: "none"               // none | basic | deep
runTimeoutSeconds: 600         // optional: abort after N seconds
cleanup: "delete"              // delete = archive immediately after announce
mode: "run"                    // run = one-shot (default), session = persistent

Manually via slash command:

/subagents spawn researcher "Research competitor pricing for task #42"

Load references/sessions-spawn-tool.md for full parameter details.

---

Step 6: Verify and Monitor

openclaw agents list --bindings   # confirm agent routing
openclaw gateway start            # start the gateway daemon

In chat:

/subagents list                   # view active runs
/subagents info <id>              # status, timestamps, session key
/subagents log <id> [limit]       # execution logs
/subagents steer <id> <message>   # redirect mid-run
/subagents kill <id|all>          # stop subagent + cascade to children

---

Tool Access by Depth (Critical)

Depth	Session Key Format	Can Spawn	Session Tools Available
0	agent:<id>:main	Always	All tools
1	agent:<id>:subagent:<uuid>	Only if maxSpawnDepth >= 2	sessions_spawn, subagents, sessions_list, sessions_history (orchestrators only)
2	agent:<id>:subagent:<uuid>:subagent:<uuid>	Never	None

Blocked for all subagents by default: sessions_list, sessions_history, sessions_send, sessions_spawn

---

Common Pitfalls

• Never share agentDir across agents — auth profiles are per-agent and must remain isolated
• SOUL.md is not injected into subagents — put operational instructions in AGENTS.md instead
• Memory is files only — anything not written to disk is lost when a session ends
• Always stagger heartbeat crons — running all agents at :00 causes resource spikes
• Use cheaper models for heartbeats; reserve powerful models for creative or reasoning-heavy tasks
• Announce is best-effort — if the gateway restarts mid-run, the announce may be lost; design tasks to be resumable
• Max nesting depth is 5, but 2 is the recommended maximum for practical use