Reachable from anywhere
Spawn on a paired device
Let an agent start a child session on another paired computer and get the result back in the parent chat.
Read when: A task needs the tools, files or hardware of a specific computer.
The agent's sessions_spawn tool takes placement: { kind: "device", deviceId }. The Gateway creates the child session, sends it to the paired computer with the same checks as sessions.dispatch, and only then gives it the task. Model calls stay on the Gateway; file and shell tools run on the device, in a copy of a managed git worktree that is reconciled back. If the device is not available, the spawn fails and nothing runs anywhere else.
How it works
The call
{
"task": "Run the macOS UI tests and report failures",
"visible": true,
"worktree": true,
"placement": { "kind": "device", "deviceId": "<paired-device-id>" }
}
| Field | Value |
|---|---|
task | What the child should do. Required. |
visible | Must be true: the child is a normal session you can open. |
worktree | Must be true: the child works in a managed git worktree. |
placement.deviceId | The device's exact node ID, as the nodes tool reports it. Names are not looked up. |
label | Optional title in the sidebar. |
agentId, model, runTimeoutSeconds, cwd, projectId | Optional, as for any spawn. |
Step by step
- The tool checks it runs in a live Gateway session and that the placement is valid.
- It creates the child session, without a task yet.
- It dispatches the child to the device. The device must be paired, connected, hosting sessions and have a free slot.
- Only when the placement is active does it send the task.
- The child is registered as a subagent run that reports back to the parent.
From commit 6b99e934c650 (#197469): src/agents/tools/sessions-spawn-visible.ts, sessions-spawn-cloud.ts, docs/tools/subagents/tool-reference.md:148-168.
What you need
| What | Why |
|---|---|
| A paired laptop with session hosting | Pair it as on the Device folder page. |
| A model on the OpenClaw runtime | Or Codex with its exec server allowed on the node. |
| A git repository with at least one commit | The child works in a managed worktree made from it. |
sessions_spawn in the agent's tools | It is in the coding and messaging profiles. |
The nodes tool, to find device IDs | It is in no profile; add it with tools.alsoAllow. |
| A Gateway built from main after 12 Nov | The feature is not in a release yet. |
Turn it on
- Gateway and laptopPair the laptop with session hosting. Follow steps 1 to 3 on the Device folder page.
- Gateway configLet the agent look up devices:
tools: { alsoAllow: ["nodes"] } - ChatAsk: "Run the test suite on my laptop and tell me what fails."
- ChatThe agent checks
nodes, then callssessions_spawnwith the device placement. Its reply starts with the child's link and an "Owner:" line.
The same dispatch without the agent:
openclaw gateway call sessions.dispatch --timeout 1500000 --params '{"key":"agent:main:device-work","deviceId":"<id>"}'
Check it works
| Where | What you see |
|---|---|
| The tool's result | placement.runner.kind: "device" and the device ID. |
| Sidebar | The child nested under the parent, with a count. |
| The child's chat | "Preparing device…", then Runs on device; "Device · syncing files" while files move. |
| The machine panel | Connected, with ID, Service, Profile, Inference, State and Disk. |
| The parent | The child's result, announced when it finishes. |
Limits
| Limit | Value |
|---|---|
| Required fields | visible: true, worktree: true, runtime subagent |
| Not allowed with a device | os, machineClass, attachments, thinking, thread, delegated tool grants |
| Slots | One per CPU core by default; a launch waits up to 10 seconds for one |
| Depth and fan-out | Spawn depth 5; 5 children per agent |
| Who can choose a device | Only spawns made on the Gateway; a child already on a cloud worker cannot |
| Required cloud profile | If cloudWorkers.requiredProfile is set, every device is refused |
| Device folders | A spawn cannot use an existing device folder; only New session can |
If something goes wrong
| You see | What it means | What to do |
|---|---|---|
| "device worker is not a paired node host" | The ID is wrong or the device is not paired. | Check with openclaw nodes status. |
| "…node is not connected…; reconnect it before retrying" | The laptop is offline. | Wake it, then ask again. |
| "…connected but cannot host sessions; enable session hosting (nodeHost.workerRuns.enabled)…" | Hosting is off on the laptop. | openclaw config set nodeHost.workerRuns.enabled true, then openclaw node install --force. |
| "…at capacity (all worker slots in use)…" | Every slot is busy. | Wait, or raise nodeHost.workerRuns.capacity. |
| "Cloud and device placement require visible=true and worktree=true." | A required field is missing. | The message includes the corrected call. |
| "Child kept for placement recovery…" | The hand-off failed; nothing ran elsewhere. | Open the child and check its placement before asking again. |
On Urbicana today
| Step | Today | Why | Fix and cost |
|---|---|---|---|
| Code on member computers | Next image | It arrived with the merge 0717635 on 13 Nov; images built before do not have it. | The next member image build. |
| Pairing a laptop | Refused | The same door blocks as on the Device folder page. | The same door change. |
| Git source | Check | The child needs a git repository with a commit; plain workspaces are not supported. | Use a project with a git repository. |
Videos to record
Record on a Gateway built from main after 12 Nov, with a paired laptop hosting sessions.
11 · Run the tests on my laptop
Gateway and laptop- In chat: "Run the test suite on my laptop and tell me what fails."
- The agent calls
nodes, thensessions_spawnwith the device. - The reply shows the child's link and "Owner:".
- Open the child. Runs on device.
12 · Results come home
Gateway and laptop- Ask the laptop child to change a file.
- "Device · syncing files".
- Back in the parent. The result is announced; the change is in the Gateway's worktree.
13 · The device goes offline
Gateway and laptop- Start a device child.
- On the laptop:
openclaw node stop. "Device disconnected" and Keep the session going. openclaw node start. Back to Connected.
14 · Hosting switched off: error and fix
Gateway and laptop- Use a laptop paired without
--session-host. - Ask the agent to run something on it. "…cannot host sessions; enable session hosting…".
- Run the two fix commands on the laptop.
- Ask again. It runs.