Running Headless Nodes with OpenClaw

Setting up automation across multiple machines often feels like a chore. I usually find myself wanting to run specific commands on a remote Linux box or a build server without installing a heavy UI app on every single device. It gets messy when you have to manage different environments manually and keep everything secure.

I prefer a way to delegate tasks to other hosts while keeping the execution sandboxed and controlled. Using a headless node host solves this by connecting to your Gateway and exposing specific system functions to your agents.

What You’ll Need

• The openclaw CLI installed on your target machine.
• A running Gateway to connect to.
• Access to your local configuration files in ~/.openclaw/.
• Network connectivity between the node and the gateway host.

Quick Start

To get a node running in the foreground, I use the run command. This is the fastest way to see if your connection works.

openclaw node run --host <gateway-host> --port 18789

If you need the node to stay active after you close your terminal, I recommend installing it as a user service. You can specify the runtime, such as node or bun.

openclaw node install --host <gateway-host> --port 18789 --runtime node

Pairing the Node

The first time you connect, the Gateway creates a pending request. I use these commands to find the ID and approve the connection:

openclaw nodes pending
openclaw nodes approve <requestId>

Managing the Service

Once the service is installed, you can control it with these four commands:

• openclaw node status
• openclaw node stop
• openclaw node restart
• openclaw node uninstall

Configuration Options

The node host automatically handles a browser proxy. If you want to turn this off, you can update your configuration:

{
  nodeHost: {
    browserProxy: {
      enabled: false,
    },
  },
}

You can also use additional flags during setup to customize the connection:

• --tls: Use TLS for the gateway connection.
• --tls-fingerprint <sha256>: Set the expected certificate fingerprint.
• --node-id <id>: Override the node ID.
• --display-name <name>: Set a custom name for the node.

Troubleshooting

• Connection Pending: If the node doesn’t appear active, check openclaw nodes pending on the Gateway. You must manually approve the first connection.
• Permission Denied: Execution is gated by local approvals. Check your ~/.openclaw/exec-approvals.json file or run openclaw approvals --node <id|name|ip> from the Gateway to edit permissions.

For more help with your specific setup, visit the AI Setup Assistant.

What’s Next

• Exec approvals