How to setup subagents (coder, searcher, academic,git,tester...) for main agent | Friends of the Crustacean 🦞🤝 | Page 1

tawdry wind Apr 26, 2026, 6:50 PM

#

I don't know much about having multiple sub-agents on OpenClaw while you talk to the main one

jovial lodgeBOT Apr 26, 2026, 6:50 PM

#

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

tawdry wind Apr 26, 2026, 6:52 PM

#

@quick glen i want to make a sub agent scenario where I talk to an agent and that agent decides to launch multiple specialiced subagents if needed.

#

It's not like a full agent that I want to have his own personality towards me, just a subagent meant to do what it's meant to do. The main agent then will respond back to the user with the info of the subagent(s)

tawdry wind Apr 26, 2026, 10:08 PM

#

@quick glen You up?

tawdry wind Apr 26, 2026, 10:54 PM

#

@quick glen

loud marsh Apr 27, 2026, 6:02 AM

#

tawdry wind <@1457407575476801641>

I think I can help you. I have a subagent running

quick glenBOT Apr 27, 2026, 6:03 AM

#

Yep — bobo’s right. Subagents can run in parallel while you keep talking to the main agent.

Quick mental model:

Main agent = orchestrator you talk to.
Subagents = background workers spawned for one task.
They finish and announce results back to the original chat/thread.
Default is isolated context; use forked context only when the subagent truly needs the current conversation.

For setup, define specialized agents in agents.list, then allow the main agent to spawn them:

{
  agents: {
    defaults: {
      subagents: {

#

        allowAgents: ["coder", "searcher", "academic", "tester"],
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60
      }
    },
    list: [
      { id: "main", default: true },
      { id: "coder", workspace: "~/.openclaw/workspaces/coder" },
      { id: "searcher", workspace: "~/.openclaw/workspaces/searcher" },
      { id: "academic", workspace: "~/.openclaw/workspaces/academic" },
      { id: "tester", workspace: "~/.openclaw/workspaces/tester" }
    ]
  }
}

#

Then use:

/subagents spawn coder implement X
/subagents list
/subagents log 1
/subagents steer 1 add tests too
/subagents kill 1

Or just ask the main agent: “spawn a coder subagent to do X and a tester subagent to verify it.”

For Discord thread-bound subagent sessions, enable thread bindings:

#

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

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

#

https://docs.openclaw.ai/concepts/session-tool
https://docs.openclaw.ai/channels/discord#thread-bound-sessions-for-subagents

One caveat: for Claude Code / Gemini CLI / OpenCode / Cursor-style external coding agents, use ACP agents, not native subagents. Native subagents are OpenClaw child sessions.

tawdry wind Apr 27, 2026, 7:16 AM

#

"agents": {
    "defaults": {
      "subagents": {
        "allowAgents": [
          "go-4-coder",
          "go-4-git"
        ],
        "runTimeoutSeconds": 900,
        "archiveAfterMinutes": 60
      },
      "workspace": "/home/alejandro/.openclaw/workspace",
    "list": [
      {
        "id": "main",
        "name": "AUTO",
        "model": {
          "primary": "github-copilot/gemini-3-flash-preview",
          "fallbacks": [
            "github-copilot/claude-haiku-4.5",
            "github-copilot/gemini-2.5-pro"
          ]
        }
      },
      {
        "id": "go-4-git",
        "name": "GO-4-git",
        "workspace": "/home/alejandro/.openclaw/workspace/go-4/go-4-git",
        "agentDir": "/home/alejandro/.openclaw/agents/go-4-git/agent",
        "model": {
          "primary": "github-copilot/gemini-3-flash-preview",
          "fallbacks": [
            "github-copilot/claude-haiku-4.5",
            "google/gemini-3.1-pro-preview",
            "google/gemini-2.0-flash"
          ]
        }
      },
      {
        "id": "go-4-coder",
        "name": "GO-4-coder",
        "workspace": "/home/alejandro/.openclaw/workspace/go-4/go-4-coder",
        "agentDir": "/home/alejandro/.openclaw/agents/go-4-coder/agent",
        "model": {
          "primary": "github-copilot/gpt-5.2-codex",
          "fallbacks": [
            "github-copilot/claude-haiku-4.5"
          ]
        }
      }
    ]

@quick glen This good?

quick glenBOT Apr 27, 2026, 7:17 AM

#

Looks close, but as pasted there’s one big structural issue: list is accidentally inside agents.defaults. It should be a sibling of defaults.

Use this shape:

{
  agents: {
    defaults: {
      workspace: "/home/alejandro/.openclaw/workspace",
      subagents: {
        allowAgents: ["go-4-coder", "go-4-git"],
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60
      }
    },

#

    list: [
      {
        id: "main",
        name: "AUTO",
        default: true,
        model: { /* your model block */ }
      },
      {
        id: "go-4-git",
        name: "GO-4-git",
        workspace: "/home/alejandro/.openclaw/workspace/go-4/go-4-git",
        agentDir: "/home/alejandro/.openclaw/agents/go-4-git/agent",
        model: { /* your model block */ }
      },
      {

#

        id: "go-4-coder",
        name: "GO-4-coder",
        workspace: "/home/alejandro/.openclaw/workspace/go-4/go-4-coder",
        agentDir: "/home/alejandro/.openclaw/agents/go-4-coder/agent",
        model: { /* your model block */ }
      }
    ]
  }
}

Notes:

✅ Separate workspace per subagent: good.
✅ Separate agentDir per subagent: good.
✅ allowAgents with those IDs: good.

#

I’d add default: true to main for clarity.
If only main should spawn those agents, you can move subagents.allowAgents onto the main agent instead of agents.defaults.

After editing:

openclaw doctor
openclaw gateway restart
openclaw status

If anything weird happens, first paste openclaw --version too — version mismatch causes a lot of config confusion. Docs: https://docs.openclaw.ai/tools/subagents

tawdry wind Apr 27, 2026, 7:19 AM

#

openclaw --version
OpenClaw 2026.4.23 (a979721)

quick glenBOT Apr 27, 2026, 7:20 AM

#

Yep — 2026.4.23 is good for this. That version has the subagent config you’re using.

I’d do two checks after fixing the list nesting:

openclaw doctor
openclaw gateway restart
openclaw status

Then test with:

/subagents spawn go-4-coder say hello and explain what agent id you are
/subagents list

#

If you want main → coder/git only, your config is enough.

If you want coder → tester/searcher/etc. nested orchestration, add:

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

Otherwise leave maxSpawnDepth alone — default is simpler/safer.

Model refs aside, the agent/subagent shape looks right once agents.list is moved outside agents.defaults. Docs: https://docs.openclaw.ai/tools/subagents

tawdry wind Apr 27, 2026, 7:25 AM

#

Agents: main (default), go-4-git, go-4-coder
Heartbeat interval: 30m (main)
Session store (main): /home/alejandro/.openclaw/agents/main/sessions/sessions.json (6 entries)

agent:main:dreaming-narrative-rem-5deff94c943a-1777251600471 (381m ago)
agent:main:dreaming-narrative-light-5deff94c943a-1777251600471 (381m ago)
agent:main:main (382m ago)
agent:main:discord:direct:475630980321771551 (468m ago)
agent:main:cron:fd604531-9481-49ac-ad26-4bd153604c24 (910m ago)
gateway connect failed: GatewayClientRequestError: scope upgrade pending approval (requestId: 56b60af0-0979-4067-b115-7eee180bcb4e)
│
◇ Device pairing ───────────────────────────────────────────────────────────────────────────╮
│ │
│ - Pending scope upgrade 56b60af0-0979-4067-b115-7eee180bcb4e for │
│ gateway:device.pair.list │
│ (159d4eaad3d0944fdce75417fcf206754154e06f9c2d7d0e7ea8e76769d571a5): approved scopes │
│ [operator.read], requested scopes [operator.pairing]. Review with openclaw devices │
│ list, then approve with openclaw devices approve 56b60af0-0979-4067-b115-7eee180bcb4e. │
│ │
├────────────────────────────────────────────────────────────────────────────────────────────╯

quick glenBOT Apr 27, 2026, 7:25 AM

#

Good news: your agents are being detected:

Agents: main (default), go-4-git, go-4-coder

So the subagent config is loading. This new error is separate: your CLI/device token currently only has operator.read, but it’s trying to use pairing/device commands that need operator.pairing.

Do this:

openclaw devices list
openclaw devices approve 56b60af0-0979-4067-b115-7eee180bcb4e
openclaw status

If you want to preview first:

#

openclaw devices approve --latest

Note: --latest only previews; approval still needs the exact request id.

If devices list itself complains because it lacks pairing scope, try the exact approve command anyway on the local machine — local loopback has a fallback for this case. If you’re connecting to a remote gateway with --url, pass the gateway token/password explicitly.

Docs: https://docs.openclaw.ai/cli/devices

tawdry wind Apr 27, 2026, 7:44 AM

#

change from 2026.4.24 to 2026.4.23

quick glenBOT Apr 27, 2026, 7:45 AM

#

Yep, downgrade like this:

openclaw update --tag 2026.4.23 --dry-run
openclaw update --tag 2026.4.23 --yes
openclaw doctor
openclaw gateway restart
openclaw --version
openclaw status

If openclaw update itself is broken, use the installer pinned to that version:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version 2026.4.23 --no-onboard

#

Then restart/check again.

Small note: --tag is for npm/package installs. If you’re running from a git checkout, say so and the rollback steps are different.

Docs: https://docs.openclaw.ai/install/updating

tawdry wind Apr 27, 2026, 8:02 AM

#

Krill, I'm using tailscale to conect the webui, is there some limitations my main agent ca do because of this? says it can't deploy sub agents

quick glenBOT Apr 27, 2026, 8:02 AM

#

Tailscale itself shouldn’t stop subagents. Subagents spawn inside the Gateway, not through your browser’s network path.

The two likely issues are:

WebUI over Tailscale needs device pairing/scopes
Tailnet/LAN access is not treated like localhost. If you see PAIRING_REQUIRED / scope-upgrade, run:
```
openclaw devices list
openclaw devices approve <requestId>
```
Your main agent may not have session tools enabled
sessions_spawn is in group:sessions. Make sure your config allows it:

#

   {
     tools: {
       profile: "coding",
       allow: ["group:sessions", "group:agents"]
     }
   }

Then:

openclaw doctor
openclaw gateway restart

Also: from WebUI, don’t ask for thread-bound Discord-style subagent sessions. Just ask: “spawn go-4-coder as a subagent to do X.” Thread binding is channel-specific; plain subagent spawning should work.

#

If it still says it can’t deploy them, paste the exact error text from the main agent/gateway log.

#How to setup subagents (coder, searcher, academic,git,tester...) for main agent