How do I let current agent spawn a subagent? | Friends of the Crustacean 🦞🤝 | Page 1

weary cypress Apr 17, 2026, 4:40 AM

#

please tell me how to do that

abstract plinthBOT Apr 17, 2026, 4:40 AM

#

terse scrollBOT Apr 17, 2026, 4:40 AM

#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

abstract plinthBOT Apr 17, 2026, 4:40 AM

#

lime mesaBOT Apr 17, 2026, 4:42 AM

#

If you mean “let this agent use sessions_spawn”, there are 3 knobs:

Allow the tool
Easiest is giving the agent a profile that includes session tools:

{
  tools: {
    profile: "coding"
  }
}

or explicitly:

#

{
  tools: {
    allow: ["group:sessions"]
    // or just: ["sessions_spawn"]
  }
}

Allow which agent IDs it may spawn
By default it can usually only spawn itself. To allow others:

{
  agents: {
    defaults: {

#

      subagents: {
        allowAgents: ["*"] // or ["research", "main"]
      }
    }
  }
}

If you want a subagent to spawn another subagent
Default is no. Enable nesting with:

{
  agents: {
    defaults: {

#

      subagents: {
        maxSpawnDepth: 2
      }
    }
  }
}

If you want the full per-agent version:

{
  agents: {
    list: [
      {

#

        id: "main",
        tools: { profile: "coding" },
        subagents: {
          allowAgents: ["*"]
        }
      }
    ]
  }
}

Then restart the gateway:

openclaw gateway restart

#

If this is for Discord thread-bound subagent sessions, also enable:

{
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnSubagentSessions: true
      }
    }
  }
}

Docs:

https://docs.openclaw.ai/tools/subagents

#

https://docs.openclaw.ai/gateway/configuration-reference

If you want, paste your current agents / tools config and I can point to the exact line to change.

weary cypress Apr 17, 2026, 5:06 AM

#

"channels": {
"discord": {
"enabled": true,
"spawnSubagentSessions": true,
"token": "TOKEN",
"groupPolicy": "open",
"dmPolicy": "allowlist",
"dm": {
"enabled": true
},
"allowFrom": [
"920199943136874506"
]
}
},

this is channels setting in my config file, but I got this error.
12:04:02 [reload] config reload skipped (invalid config): channels.discord: invalid config: must NOT have additional properties
when I told the AI to spawn subagent

lime mesaBOT Apr 17, 2026, 5:07 AM

#

Yep, the error is because spawnSubagentSessions is in the wrong place.

It is not a direct channels.discord.* key. It must live under:

channels.discord.threadBindings.spawnSubagentSessions

So your config should look like this:

{
  channels: {
    discord: {
      enabled: true,
      token: "TOKEN",
      groupPolicy: "open",
      dmPolicy: "allowlist",

#

      dm: {
        enabled: true,
      },
      allowFrom: ["920199943136874506"],
      threadBindings: {
        enabled: true,
        spawnSubagentSessions: true,
      },
    },
  },
}

A couple important notes:

spawnSubagentSessions only matters if the agent is doing sessions_spawn({ thread: true })

#

if you just want normal subagent spawning, you can remove that key entirely
if you want a subagent to spawn another subagent, also set:

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2,
      },
    },
  },
}

After fixing the config, restart the gateway:

#

openclaw gateway restart

Docs:

If you paste your agents block too, I can check whether the current agent is actually allowed to call sessions_spawn.

weary cypress Apr 17, 2026, 5:11 AM

#

when I told ai to spawn subagent to do things, it keep restarting my gateway, resulting in gateway stopped and never restart back again..

lime mesaBOT Apr 17, 2026, 5:12 AM

#

That is not normal. sessions_spawn itself should not restart the gateway.

What’s probably happening is one of these:

the model is using the gateway tool or /restart
the model is using exec to run openclaw gateway restart
it restarted after writing an invalid config, so the gateway never came back

That last one matches your earlier bad spawnSubagentSessions placement pretty well.

First, fix the config

Use:

channels: {
  discord: {

#

    threadBindings: {
      enabled: true,
      spawnSubagentSessions: true,
    },
  },
}

not channels.discord.spawnSubagentSessions.

Then, block the agent from restarting the gateway

While debugging, I’d lock this down:

#

  commands: {
    restart: false
  },
  tools: {
    deny: ["gateway"],
    subagents: {
      tools: {
        deny: ["gateway", "cron", "exec", "process"]
      }
    }
  }
}

If your subagents need shell access, then at least keep:

#

tools: {
  deny: ["gateway"]
}

and preferably spawn them sandboxed:

sandbox: "require"

Important

If the agent can use exec, it may still be able to run restart commands through the shell. So the safest debug move is to deny exec/process for subagents until this is stable.

Please check these next

Paste the output of:

#

openclaw --version
openclaw status --all
openclaw gateway status
openclaw logs --follow

If you want, paste your tools, commands, and agents blocks and I’ll tell you exactly which line is letting it restart the gateway.

weary cypress Apr 17, 2026, 5:13 AM

#

no, I mean the subagent never spawn out and the main agent restarted my gateway

lime mesaBOT Apr 17, 2026, 5:14 AM

#

Ah, got it. Then this is not “subagent thread config”, it’s the main agent failing to call sessions_spawn and doing something dumb instead.

So the fix is:

1. Make sure the main agent can actually spawn

It needs session tools, plus permission to target the child agent:

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          profile: "coding",
          deny: ["gateway"],

#

        },
        subagents: {
          allowAgents: ["*"] // or ["research"] etc
        },
      },
    ],
  },
  tools: {
    subagents: {
      tools: {
        deny: ["gateway", "cron"],
      },
    },
  },
  commands: {

#

    restart: false,
  },
}

2. Important: block gateway restart while testing

If the main agent has gateway access, or can reach restart paths, it can go off the rails. So I’d definitely keep:

tools.deny: ["gateway"]
commands.restart: false

3. If the agent edits config, that can also trigger a restart

Especially if it writes a bad config and your reload mode restarts on changes. So if this keeps happening, also check:

#

gateway: {
  reload: {
    mode: "off"
  }
}

while debugging.

What this means

If the subagent never appears, the real problem is usually one of:

sessions_spawn not allowed for the main agent
target agentId blocked by subagents.allowAgents
model/tool-calling failure, so it never chooses sessions_spawn

#

Please paste these

To narrow it down fast:

openclaw --version
openclaw status --all
openclaw gateway status

and, if possible, the log lines right around the failed spawn attempt.

If you paste your agents, tools, and gateway.reload blocks, I can tell you the exact reason it’s falling back instead of spawning.

weary cypress Apr 17, 2026, 5:37 AM

#

the AI told me that gateway has pairing issue so it can't spawn the subagent to do tasks

lime mesaBOT Apr 17, 2026, 5:37 AM

#

That sounds like the AI is probably misdiagnosing it.

A subagent spawn does not normally require pairing. sessions_spawn is an internal tool call, not a Discord/device pairing flow.

So there are 2 cases:

If you actually see this exact error

disconnected (1008): pairing required

then yes, fix the pending device/operator pairing first:

openclaw devices list
openclaw devices approve <requestId>

If you’re in Docker, use the compose wrapper instead.

#

If you do not see that exact error

then pairing is probably not the real blocker. The real issue is more likely one of:

sessions_spawn not allowed for the main agent
subagents.allowAgents blocking the target
the model/tool call went off the rails and invented a wrong reason

Please check these

openclaw --version
openclaw status --all
openclaw gateway status

And if possible, paste the exact tool error / log line around the failed spawn.

If you want, paste that error text here and I’ll tell you whether it’s a real pairing problem or the model hallucinating the cause.

#

Docs:

weary cypress Apr 17, 2026, 5:38 AM

#

12:35:58 [tools] agents.main.tools.allow allowlist contains unknown entries (browser, nodes). These entries are shipped core tools but unavailable in the current runtime/provider/model/config.
I only saw this printed in the gateway

lime mesaBOT Apr 17, 2026, 5:39 AM

#

Nice, that warning helps. It is not a pairing error.

It means:

your agents.main.tools.allow includes browser and nodes
but those tools are not available in your current setup
so OpenClaw warns and those entries won’t do anything

That warning by itself does not stop subagents.

What actually matters for subagent spawn

Your main agent must have either:

group:sessions, or
sessions_spawn

in its allowed tools.

#

Easiest fix

Instead of hand-maintaining a weird allowlist, use:

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          profile: "coding",
          deny: ["gateway"],
        },
        subagents: {
          allowAgents: ["*"],
        },

#

      },
    ],
  },
}

profile: "coding" already includes group:sessions, which includes sessions_spawn.

If you want a custom allowlist instead

Then make sure it includes group:sessions and remove the unavailable stuff:

{
  agents: {
    list: [

#

      {
        id: "main",
        tools: {
          allow: ["group:sessions", "read", "write", "edit", "exec", "process"],
          deny: ["gateway"],
        },
        subagents: {
          allowAgents: ["*"],
        },
      },
    ],
  },
}

So in short

#

browser, nodes unknown = warning only
not a pairing problem
check whether sessions_spawn / group:sessions is actually allowed
I’d also keep gateway denied so the model can’t restart things

If you paste your full agents.main block, I can tell you exactly what to change.

weary cypress Apr 17, 2026, 5:43 AM

#

I already added that, it still shutdown my gateway eventhough I already turn off it's ability to control gateway on canvas

lime mesaBOT Apr 17, 2026, 5:44 AM

#

Yeah, canvas is the wrong knob here, unfortunately.

Turning off canvas does not stop the agent from:

calling exec
using /restart
editing config and triggering gateway.reload

So if it still shuts down the gateway, it’s almost certainly doing it through one of those paths, not canvas.

Safest setup

Make the main agent an orchestrator only, and let a separate worker agent do the real work.

{
  commands: {
    restart: false,

#

    config: false,
    bash: false,
  },

  gateway: {
    reload: {
      mode: "off",
    },
  },

  agents: {
    list: [
      {
        id: "main",
        tools: {

#

          allow: ["group:sessions", "read", "web_search", "web_fetch"],
          deny: ["gateway", "exec", "process", "browser", "canvas", "nodes", "cron"],
        },
        subagents: {
          allowAgents: ["worker"],
          requireAgentId: true,
        },
      },
      {
        id: "worker",
        tools: {
          profile: "coding",
          deny: ["gateway", "cron"],
        },
      },

#

    ],
  },

  tools: {
    subagents: {
      tools: {
        deny: ["gateway", "cron"],
      },
    },
  },
}

Why this works

main can spawn
main cannot restart or reconfigure the gateway

#

worker can do the task
worker still cannot touch the gateway

Important

If the main agent still shuts the gateway down after this, then I’m pretty sure it is either:

editing config directly somewhere unexpected, or
you have another restart path enabled outside this config

At that point, please paste:

openclaw --version
openclaw status --all
openclaw gateway status

and the shutdown log lines right before it dies.

#

If you want, paste your current full commands, gateway, and agents blocks and I’ll rewrite them into a safe working version.

weary cypress Apr 17, 2026, 5:47 AM

#

I got so many issue, can you tell me how to reset everything about openclaw? like reinstall everything, delete all data

lime mesaBOT Apr 17, 2026, 5:49 AM

#

Yep. If you want the cleanest official reset, use the built-in commands, not manual file deletion.

Safer first step

Make a backup before nuking it:

openclaw backup create

Option A, reset config/state and start fresh

Keeps the CLI installed:

openclaw reset --scope full --yes --non-interactive

Option B, wipe basically everything OpenClaw manages

#

Removes service + state + workspace + app, while keeping the CLI command itself:

openclaw uninstall --all --yes --non-interactive

If you want to preview first:

openclaw uninstall --all --dry-run

Then reinstall / onboard again

Usually:

#

openclaw onboard --install-daemon

If you originally installed via the installer script, you can also rerun that first.

Important

If you use a named profile or --dev, run the same command with that flag too, for example:

openclaw --dev uninstall --all --yes --non-interactive

My recommendation

For your case, I’d do:

openclaw backup create

#

openclaw uninstall --all --dry-run
openclaw uninstall --all --yes --non-interactive
openclaw onboard --install-daemon

Docs:

If you want, tell me your OS + install method, and I’ll give you the exact reset/reinstall sequence for that setup.

weary cypress Apr 17, 2026, 5:51 AM

#

I'm on windows

lime mesaBOT Apr 17, 2026, 5:51 AM

#

Got it. On Windows, I’d do it in PowerShell like this.

Clean reset / reinstall

openclaw backup create
openclaw uninstall --all --dry-run
openclaw uninstall --all --yes --non-interactive
openclaw onboard --install-daemon

If you only want a fresh config/state, not full uninstall

openclaw reset --scope full --yes --non-interactive
openclaw onboard --install-daemon

If you used `--dev` or a named profile

#

Run the same command with that flag too, for example:

openclaw --dev uninstall --all --yes --non-interactive

Manual fallback, only if uninstall did not clean everything

Native Windows state is usually under:

$env:USERPROFILE\.openclaw

So the manual nuke would be:

#

Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"

If you used profiles, also check for folders like:

$env:USERPROFILE\.openclaw-dev
$env:USERPROFILE\.openclaw-*

Important

If you are actually running OpenClaw in WSL, then the data is not in %USERPROFILE%\.openclaw, it is inside the Linux home dir instead.

If you want, I can give you the exact Windows native reset flow or the WSL reset flow, depending on how you installed it.

weary cypress Apr 17, 2026, 10:55 AM

#

17:55:07 [ws] unauthorized conn=c257ea97-f7c7-40c2-a4f7-5800bf2a498d peer=127.0.0.1:60978->127.0.0.1:18789 remote=127.0.0.1 client=openclaw-control-ui webchat v2026.4.15 role=operator scopes=5 auth=token device=yes platform=Win32 instance=222f5977-4a7f-44a8-8f28-58d13e2574b2 host=127.0.0.1:18789 origin=http://127.0.0.1:18789 ua=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36 reason=device_token_mismatch
17:55:07 [ws] closed before connect conn=c257ea97-f7c7-40c2-a4f7-5800bf2a498d peer=127.0.0.1:60978->127.0.0.1:18789 remote=127.0.0.1 fwd=n/a origin=http://127.0.0.1:18789 host=127.0.0.1:18789 ua=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36 code=1008 reason=unauthorized: device token mismatch (rotate/reissue device token)

#

what is this error?

lime mesaBOT Apr 17, 2026, 10:56 AM

#

Yep, this is the real issue.

It is not a subagent problem and not the earlier pairing guess.

Your browser Control UI is presenting a stale device token, and the gateway is rejecting it:

reason=device_token_mismatch

That usually happens after a reset/reinstall, token rotation, or browser-stored auth drift.

Fix

Run these locally:

openclaw config get gateway.auth.token
openclaw devices list

#

openclaw devices rotate --device <deviceId> --role operator

If that does not fix it, do the full drift recovery:

openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>

Then

close the Control UI tab
reopen with:

#

openclaw dashboard

if it still keeps using stale browser auth, clear site data for 127.0.0.1:18789 and retry

Important

Do not paste your gateway token here.

Docs:

If you want, paste the output of openclaw devices list here, and I’ll tell you which device entry to rotate/remove.

#

It means:

your browser / Control UI is trying to connect with an old saved device token, but the gateway expects a different one.

So the WebSocket auth is rejected before the UI can connect.

In plain English:

browser says: “here is my device token”
gateway says: “that token no longer matches this paired device”
result: 1008 unauthorized: device token mismatch

Common causes:

you reset/reinstalled OpenClaw
you rotated auth/device tokens
the browser kept stale Control UI auth from an older session

#

So this is basically stale browser device auth, not a subagent error.

Fix is:

rotate or remove/reapprove the device token
reopen the dashboard
if needed, clear site data for 127.0.0.1:18789

If you want, I can give you the exact 2-3 commands to fix it on Windows.

weary cypress Apr 17, 2026, 10:59 AM

#

17:58:47 [agent/embedded] embedded run agent end: runId=2d1ab8b9-38a0-4e32-95b1-95e88cb1ed02 isError=true model=qwen/qwen3.5-9b provider=lmstudio error=LLM request timed out. rawError=Request timed out.
17:59:01 [lmstudio/stream] LM Studio inference preload failed for "qwen/qwen3.5-9b" (1 consecutive failure, next preload attempt skipped for ~5s); continuing without preload: Error: LM Studio model discovery failed: TypeError: fetch failed

lime mesaBOT Apr 17, 2026, 11:00 AM

#

That one means your LM Studio local model stopped responding in time, and then OpenClaw also failed to talk to LM Studio at all a few seconds later.

So:

LLM request timed out = OpenClaw sent a request to qwen/qwen3.5-9b, but LM Studio did not answer fast enough
model discovery failed: fetch failed = OpenClaw then tried to query LM Studio again, and the HTTP request itself failed

In plain English, this usually means one of these:

LM Studio is not running anymore
its local server/API is off
the model is overloaded / hung / too slow for the timeout
wrong LM Studio URL / broken connection
LM Studio crashed or the model unloaded

So this is not a subagent-specific error, it is mainly LM Studio connectivity / local model stability.

#

Quick checks

openclaw status --all
openclaw models status

And in LM Studio, check:

server mode is enabled
the model is actually loaded
the OpenAI-compatible endpoint is still running

If you want stable agent/subagent behavior, local LM Studio models can be pretty flaky for tool-heavy workflows. If you paste your LM Studio config block, I can sanity-check it.

#

Yep. Since you’re on Windows, the official full wipe is:

openclaw uninstall --all --yes --non-interactive

If you want to preview what it will remove first:

openclaw uninstall --all --dry-run

That removes the OpenClaw-managed service + state + workspace + app.

Optional, but smart first

#

openclaw backup create

Important

If you used a profile like --dev, run it for that profile too:

openclaw --dev uninstall --all --yes --non-interactive

One nuance

The official uninstall --all still leaves the CLI command installed.

So if you also want the openclaw command gone, uninstall it the same way you originally installed it after running the command above.

Docs:

#How do I let current agent spawn a subagent?

First, fix the config

Then, block the agent from restarting the gateway

Important

Please check these next

1. Make sure the main agent can actually spawn

2. Important: block gateway restart while testing

3. If the agent edits config, that can also trigger a restart

What this means

Please paste these

If you actually see this exact error

If you do not see that exact error

Please check these

What actually matters for subagent spawn

Easiest fix

If you want a custom allowlist instead

So in short

Safest setup

Why this works

Important

Safer first step

Option A, reset config/state and start fresh

Option B, wipe basically everything OpenClaw manages

Then reinstall / onboard again

Important

My recommendation

Clean reset / reinstall

If you only want a fresh config/state, not full uninstall

If you used --dev or a named profile

Manual fallback, only if uninstall did not clean everything

Important

Fix

Then

Important

Quick checks

Optional, but smart first

Important

One nuance

If you used `--dev` or a named profile