# nodes

# `openclaw nodes`

Manage paired devices and enable invocation of node capabilities.

## Overview

The `openclaw nodes` command manages paired devices and enables invocation of node capabilities. This includes listing nodes, approving pending connections, checking status, and executing commands remotely.

## Key Commands

**Listing and Status:**

```bash
openclaw nodes list
openclaw nodes list --pending
openclaw nodes list --connected
openclaw nodes status <id|name|ip>
```

The tool provides commands to display pending and paired nodes, with options to filter by connection status or timeframe. Users can retrieve only currently-connected nodes or those connecting within specified durations like 24 hours or 7 days.

**Execution:**

Remote command execution is available through two approaches:

```bash
openclaw nodes invoke <id|name|ip> --method <method> --params <json>
openclaw nodes run <id|name|ip> -- <command>
```

The `invoke` command uses structured parameters, while the `run` command uses shell-style syntax. The system supports both direct commands and raw shell strings.

## Important Features

**Exec-style Defaults:**
The `nodes run` command mirrors standard execution behavior by reading configuration from `tools.exec.*` settings and implementing approval workflows before invoking system commands.

**Customization Options:**
Users can specify working directories, environment variables, command timeouts, and security levels. Additional flags allow requiring screen recording permissions and agent-scoped approvals.

**Node Identification:**
Commands accept node references by ID, name, or IP address for flexible targeting.

## Notes

A compatible node must advertise `system.run` capabilities, such as a macOS companion application or headless node host.