OpenClaw Node Pairing Guide: Connect Phones and Computers Safely
OpenClaw nodes let a phone, laptop, or other paired device act as a peripheral for your Gateway. That can unlock useful workflows—camera capture, Canvas, voice features, or device actions—without moving the whole Gateway onto every device. It also introduces a trust decision: a node is not merely another browser tab. It is a client that can receive Gateway-directed requests and expose capabilities you should understand before approving it.
The safe pairing pattern is simple: get the Gateway reachable, create a pairing request from the node, inspect the pending request on the Gateway, approve only the device you recognize, then test one capability at a time. Pairing does not create a hostile-user security boundary, and it does not make an untrusted person safe to share with. Treat every approved node as part of the same operator trust boundary as the Gateway.
This guide focuses on the repeatable workflow rather than a particular mobile UI. OpenClaw evolves quickly, so use the command help and current official documentation installed with your version if a flag or prompt differs.
What an OpenClaw node is
OpenClaw runs one Gateway as the control plane. The Gateway owns sessions, authentication profiles, channel connections, and state. A node connects to that Gateway over its WebSocket; it does not become a second Gateway and it does not independently own your conversations.
That architecture explains the direction of a typical request:
- A message arrives at the Gateway through a configured channel.
- The Gateway runs the agent and decides whether a node tool is appropriate.
- The Gateway invokes the selected node capability.
- The node returns a result to the Gateway, which sends the response back through the channel.
Pairing is the approval step that allows a particular device to join this relationship. It should answer two questions before you click approve: Which physical device is requesting access? and What authority will I allow it to exercise? A friendly device name is useful, but it is not a substitute for checking the request in the Gateway and confirming that the node belongs to you.
For a broader view of the control plane, see LobsterDome’s OpenClaw Remote Access Guide. If you are changing network exposure at the same time, run the checks in the OpenClaw Security Audit Guide.
1. Pre-flight the Gateway before pairing
Pairing is easiest when you separate transport problems from approval problems. First confirm that the Gateway is running and that your operator client can reach it.
openclaw health
openclaw status --deep
If the node is on another machine, choose a deliberate transport. The Gateway WebSocket binds to loopback on port 18789 by default, but your configured gateway.port, --port, or OPENCLAW_GATEWAY_PORT may differ. An SSH local forward is the universal fallback:
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
With that tunnel open, a local client can target the forwarded Gateway without publishing the Gateway port to the internet. A trusted LAN or tailnet path can also work, but changing the bind address changes the exposure surface. Do not assume that “inside the home network” means “private enough.” Verify authentication, firewall rules, tailnet ACLs, and the devices that can reach the host.
Before approving a new device, run the security audit if you recently changed the Gateway, tools, groups, plugins, or remote access configuration:
openclaw security audit
The official security guidance describes a personal-assistant trust model: one trusted operator boundary per Gateway. If mutually untrusted users need separate authority, use separate Gateways and preferably separate OS users or hosts. Pairing a node is not a replacement for that isolation.
2. Create and inspect a pairing request
Start the pairing flow from the node you want to connect. The exact button or menu depends on the node client, but the outcome is a pending request at the Gateway. Keep the node’s display name, device type, and any request identifier visible while you switch to the operator terminal.
List the requests waiting for approval:
openclaw nodes pending
Then inspect the node inventory and metadata:
openclaw nodes status
openclaw nodes describe
Do not approve the first item just because it appeared recently. Compare the pending request with the physical device in your hand or the machine you just configured. If you see two requests and expected one, stop and investigate. A stale request, duplicate registration, or unfamiliar device is a reason to reject rather than guess.
A useful approval checklist is:
- The request appeared immediately after you initiated pairing.
- The device name and type match the device you intended to add.
- You know who controls the device and its operating-system account.
- The Gateway endpoint is the one you intended to use, not an accidental public or shared endpoint.
- You understand which capabilities the node advertises.
- You are not using one shared Gateway as a boundary between people who should not share tools, sessions, or credentials.
3. Approve exactly the intended device
Once the request is verified, approve it by its request identifier:
openclaw nodes approve <requestId>
Use the identifier shown by your installed openclaw nodes pending output. Never copy a token or secret into a public issue, chat, or shell history just to make pairing easier. If the request is not yours, reject it explicitly:
openclaw nodes reject <requestId>
After approval, refresh the inventory and confirm that the node changed state:
openclaw nodes status
openclaw nodes describe
The node may still show as offline if its app is closed, the network changed, or the Gateway endpoint is unreachable. Approval and connectivity are separate states. An approved node that is currently offline is not necessarily a failed pairing; it is a clue to check transport and the node client’s connection status.
If the node was approved by mistake, do not try to “hide” the problem by pairing it again under a new name. Remove or revoke it using the current node-management flow exposed by your installed CLI, then rerun the status and security checks. Keep a short note of what changed so a later audit has context.
4. Verify capabilities conservatively
A successful connection is not the same as a successful end-to-end workflow. Start with the least sensitive test available. Confirm the node responds, then test one capability at a time. For example, verify that the Gateway sees the node and that a harmless request returns to the correct device before trying camera, microphone, filesystem, or computer-use features.
This staged approach makes failures legible:
- If the node is absent from
nodes status, investigate pairing or Gateway reachability. - If it is approved but offline, investigate the client process, network path, endpoint, and authentication.
- If it is online but one capability fails, inspect that capability’s permission and platform requirements rather than re-pairing blindly.
- If a capability works but exposes more than expected, stop and tighten the node or tool policy before continuing.
Remember that the Gateway agent may be able to invoke tools through the node. A prompt arriving from a group chat, a webpage, or another external source should not automatically be trusted with sensitive device actions. Keep channel access policies, tool policy, sandboxing, and node permissions aligned. For runtime boundaries, see the OpenClaw Sandboxing Guide.
5. Troubleshoot the common states
The request never appears
First confirm that you started pairing on the intended device. Then check that the node can reach the Gateway’s configured WebSocket endpoint and that the Gateway process is healthy. If you are using SSH, confirm the tunnel is still running and that the local port matches the Gateway port. If you are using a tailnet, verify both devices are connected to the expected network and that its access rules allow the path.
The request is pending but approval fails
Refresh the pending list and copy the current request identifier rather than reusing an old terminal line. Check that your operator client is authenticated to the same Gateway that received the request. If multiple Gateways or profiles are running, verify the target explicitly; a request in one Gateway will not be approved from another.
The node is approved but offline
Check whether the node application is running, whether the device has network access, and whether its configured Gateway URL is still correct. Use openclaw health and openclaw status --deep from the operator side. Re-pairing is not the first fix for a transport outage.
The node is online but a feature is unavailable
Device permissions and platform support matter. Check the node’s description and the capability-specific documentation. Grant only the operating-system permission required for the feature you are testing. A camera or microphone permission is a separate sensitivity decision from merely allowing the node to connect.
The device is unfamiliar
Reject the request, then audit who can reach the Gateway and which channels can trigger it. If you suspect the Gateway or its credentials are exposed, rotate credentials according to the current authentication guidance and inspect the security audit output. Do not continue pairing while the trust boundary is unclear.
6. Review and remove access
Treat node inventory as operational state. Periodically review:
openclaw nodes status
openclaw nodes describe
openclaw security audit
Remove devices you no longer control, no longer use, or cannot positively identify. Keep the Gateway itself private where practical, and avoid using node pairing to create a pseudo-multi-user deployment. If a household, team, or customer needs a different authority boundary, design separate Gateway cells instead of sharing one tool-enabled agent and relying on device names.
FAQ
Does pairing give a node access to every OpenClaw session?
The Gateway remains the owner of sessions and routing, but pairing makes the device part of the trusted Gateway topology. Do not treat the node as an isolated tenant. Configure the Gateway, channels, tools, and node capabilities for the trust boundary you actually intend.
Is an approved node the same thing as a second Gateway?
No. A node is a client/peripheral. The Gateway remains the control plane and continues to own state, channels, and agent execution.
Should I expose port 18789 publicly for mobile access?
Usually not as a first choice. Keep the Gateway on loopback when practical and use an SSH tunnel, Tailscale Serve, or another deliberately authenticated private path. Confirm your configured port instead of assuming 18789.
What should I do with a stale pairing request?
Reject requests you cannot identify. Then check the Gateway’s reachability and access policies. Do not approve a stale request merely to clear the pending list.
Comments
Loading comments…