Reachable from anywhere
Work in a device folder
Run the agent on your Gateway while it works directly in a folder on your laptop. Nothing is copied to the server.
Read when: Your files are on your laptop and your Gateway runs somewhere else.
A session's workspace can be an existing folder on a paired computer, called a node. The laptop connects to the Gateway; the agent's file and shell tools then run in that folder on the laptop, while model calls, the transcript, web search and memory stay on the Gateway. Nothing in the folder is prepared, reset or copied, and deleting the session never deletes the folder.
How it works
What runs where
| On the laptop | On the Gateway |
|---|---|
| File reads and writes, shell commands, git, in the chosen folder | Model calls, the transcript, web search, memory, finding other sessions, the tool policy and approvals |
Pairing the laptop
- An admin makes a join code. It is single-use, lasts about 10 minutes and is shown as a command.
- The laptop runs the command. It pairs, saves
nodeHost.workerRuns.enabled = trueand installs a background service. - A join code counts as approval for the device and its first commands. Later, the laptop uses its own device token; the join code is never stored.
Opening a folder
- The Gateway checks the laptop is connected and supports folders.
- It asks the laptop to check the path, with a 15-second limit. The path must be absolute or start with
~, must not be the disk root, and must sit inside an allowed root. - The laptop returns the real path, which the session keeps. The first message is sent after that.
From docs/nodes/session-hosting.md:376-432, src/gateway/session-device-folder.ts, src/node-host/node-worker-device-folder.ts, docs/cli/connect.md.
What you need
| What | Why |
|---|---|
| A Gateway reachable over HTTPS | Join addresses must use TLS. Set gateway.publicOrigin when the Gateway sits behind a proxy. |
| Admin rights on the Gateway | To make the join code. |
| A laptop with Node.js 24.16+ or 26.1+ | macOS, Linux or Windows as a headless node, or the macOS menu bar app. |
| A model on the OpenClaw runtime | Codex remote execution and other harnesses cannot use device folders. |
| The laptop awake and online | The session waits for it otherwise. |
Turn it on
- Gateway, terminalCheck that node hosting is possible:
openclaw doctor - Control UIClick + (New session), open the destination picker and click Connect a device. Copy the command. Or in a terminal:
openclaw devices join-code - Laptop, terminalPaste the command. It looks like this:
npx -y openclaw@<version> connect https://<gateway>/j/<code> --service --session-host - Laptop, terminal (optional)Allow only some folders, then restart the node. Leave it unset to allow any folder; set it to
[]to switch device folders off.openclaw config set nodeHost.workerRuns.folders '["~/Projects"]' --strict-jsonopenclaw node restart - Control UINew session → pick the laptop under Your devices (not Auto) → Existing folder on {laptop}. Browse and click Use this folder, or type an absolute path.
- Control UISend your first message. You see "Checking the selected device…" then "Preparing device…".
- ChatAsk the agent to run
pwd > proof.txt. Open the folder on the laptop:proof.txtis there.
A laptop paired earlier without session hosting needs:
openclaw config set nodeHost.workerRuns.enabled true
openclaw node install --force
Check it works
| Where | What you see |
|---|---|
openclaw nodes status | The laptop, paired and connected. |
openclaw gateway call environments.list | The laptop's row with sessionHost: true and deviceFolders: true. |
| Settings → Devices | "Device software {version}". |
| New session | The row Existing folder on {laptop}. |
| Chat details | The folder's path and the device's short ID. |
Limits
| Not available | Why |
|---|---|
| Attachments | The folder lives on the laptop only. The composer says "Existing device folders can't receive attachments." |
| The Files panel | Use the agent's file tools instead. |
| Auto and cloud placement | The session must go to its own device. |
| Move, or Continue on Gateway | The folder cannot move. |
| Codex remote execution and other harnesses | Device folders need the OpenClaw runtime. |
| A sandbox | The folder list is a guardrail. Anyone allowed to run commands on the laptop already can. |
| Locking | Files can still change from outside while the agent works. |
| Capacity | One session slot per CPU core by default (nodeHost.workerRuns.capacity). |
| Long absence | After 14 days offline the old environment is treated as gone; the pairing stays. |
If something goes wrong
| You see | What it means | What to do |
|---|---|---|
| "Device disconnected" · "Waiting for the device to reconnect. Retry when it's connected." | The laptop slept or lost its connection. | Wake it; it reconnects by itself. Then retry. The interrupted turn is not replayed. |
| "Selected device is disconnected or does not support existing-folder sessions; connect an updated session host and retry." | The laptop is offline, too old, or hosting is off. | Update OpenClaw on the laptop and enable session hosting. |
| "Not available with this model" | The model does not use the OpenClaw runtime. | Pick another model. |
| "Attachments are not supported in sessions that use an existing device folder…" | See Limits. | Send without attachments. |
| "Files access is unavailable for existing folders on paired devices…" | See Limits. | Ask the agent to read the file. |
On Urbicana today
| Step | Today | Why | Fix and cost |
|---|---|---|---|
| Join address | Set | The seed sets gateway.publicOrigin (agent-proxy/src/proxy.ts:651). | None. |
Laptop opens /j/<code> | Refused | The door refuses any request without its browser cookie (proxy.ts:1152-1161). | Pass /j/* without the cookie. It carries its own short-lived code. |
| Node socket and worker routes | Refused | Same door check. The laptop needs its main socket, /__openclaw__/worker, /__openclaw__/worker-bundle/* and /__openclaw__/worker-transfer/*. | Pass them without the cookie and keep WebSocket upgrades. The Gateway checks the device token. A small agent-proxy change and a security decision. |
| Gateway accepts the node | Not tried | The docs say new nodes cannot authenticate to a trusted-proxy Gateway (docs/nodes/node-host.md:31); the code accepts the join code's token (auth-context.ts:192-231). | Join one laptop after the door fix and see. |
| Worker archives | Check | Workspace transfers can be up to 512 MiB (src/shared/worker-bundle-limits.ts). | Make sure the door does not cap request size or time. |
Videos to record
Record on a Gateway you run with OpenClaw's default token auth and reach over HTTPS, plus a laptop.
6 · Connect a laptop
Gateway and laptop- New session → destination picker → Connect a device. The command and "This link is single-use and expires at {time}."
- Copy it, paste it in the laptop's terminal.
- The laptop appears under Your devices.
7 · Work in a laptop folder
Gateway and laptop- New session → the laptop → Existing folder on {laptop}.
- Browse to the folder, Use this folder.
- Ask: "List the files here." "Checking the selected device…", then the list.
8 · Edits land on the laptop
Gateway and laptop side by side- Ask the agent to create
notes.mdwith a short summary of the project. - Open the folder in Finder on the laptop.
notes.mdis there. - Open it.
9 · The laptop goes to sleep
Gateway and laptop- Close the laptop's lid during a session.
- "Device disconnected".
- Open the lid, wait for it to reconnect, retry the message.
10 · Limit the allowed folders
Laptop terminal and Gateway- On the laptop, set
nodeHost.workerRuns.foldersto["~/Projects"]and restart the node. - Try a folder outside
~/Projects. It is refused. - Try one inside. It opens.