OpenClaw Mobile Node Pairing: iOS and Android Connection Guide

Introduction

OpenClaw not only supports AI interaction through third-party platforms like Telegram and WhatsApp, but also provides native mobile pairing functionality. By pairing your iOS or Android device with the OpenClaw server, you can use the AI assistant directly from your phone without relying on third-party apps. This article covers the mobile node pairing process and common configurations in detail.

Mobile Node Overview

OpenClaw's Mobile Node is a lightweight client connection method. Your phone connects to the OpenClaw gateway via a secure WebSocket, gaining AI interaction capabilities identical to other channels, while enjoying native push notifications and offline message synchronization.

Core Advantages

No third-party apps required: Use directly through the OpenClaw mobile app or PWA
End-to-end encryption: Keys established during pairing protect communication security
Offline sync: Messages during device offline periods are automatically synced upon reconnection
Multi-device support: A single user can pair multiple devices with automatic session sync
Push notifications: Supports APNs (iOS) and FCM (Android) push

Prerequisites

Before starting the pairing process, confirm the following:

OpenClaw server is up and running, version >= 1.2.0
The gateway is configured to allow external connections or port forwarding is set up
The phone and server are on the same network, or the server is accessible from the public internet
Mobile node functionality is enabled on the server side

Enabling Mobile Nodes

Confirm the following configuration in openclaw.json:

{
  "gateway": {
    "host": "0.0.0.0",
    "port": 18789
  },
  "channels": {
    "mobile": {
      "enabled": true,
      "maxDevices": 5,
      "pairingTimeout": 300,
      "pushNotifications": {
        "enabled": true,
        "apns": {
          "keyFile": "~/.openclaw/certs/apns-key.p8",
          "keyId": "YOUR_KEY_ID",
          "teamId": "YOUR_TEAM_ID"
        },
        "fcm": {
          "credentialsFile": "~/.openclaw/certs/fcm-credentials.json"
        }
      }
    }
  }
}

Push notification configuration is optional. Without push configured, the mobile app still works normally — you just won't receive notifications when the app is in the background.

Pairing Process

Step 1: Generate a Pairing Code

Generate a temporary pairing code on the server:

# Generate pairing code, valid for 5 minutes
openclaw mobile pair --generate

# Example output:
# Pairing code: AXKF-9M2P-RTLQ
# Valid until: 2026-03-14 15:05:00
# Pairing link: https://your-server:18789/pair/AXKF-9M2P-RTLQ

You can also click the "Generate Pairing Code" button on the "Device Management" page in the Web Dashboard.

Step 2: Enter the Pairing Code on Your Phone

iOS Pairing

Search for "OpenClaw" in the App Store and install (or open the Dashboard PWA version in Safari)
Open the app and tap "Connect to Server"
Enter the server address: your-server-ip:18789
Enter the pairing code: AXKF-9M2P-RTLQ
Wait for verification to complete

Android Pairing

Search for "OpenClaw" on Google Play and install
Open the app and tap "Add Server"
You can choose to manually enter the address and pairing code, or scan the QR code displayed on the Dashboard
Confirm the connection

Step 3: Verify Pairing

After successful pairing, the server will display a confirmation message:

[INFO] New device paired: iPhone 15 Pro (iOS 19.0)
[INFO] Device ID: mob_a3f2c1d8
[INFO] User identifier: mobile_user_001

On the phone, you should see the connection status indicator turn green, and you can start sending messages.

QR Code Quick Pairing

In addition to manually entering the pairing code, OpenClaw also supports more convenient QR code pairing:

# Generate QR code in terminal (requires Unicode support)
openclaw mobile pair --qrcode

# Generate in Dashboard
# Go to Dashboard → Device Management → Generate QR Code

The QR code encodes the server address, port, and pairing code, allowing one-step connection by scanning from the phone.

Device Management

View Paired Devices

openclaw mobile list

# Example output:
# ID            Device Name        Platform    Last Active
# mob_a3f2c1d8  iPhone 15 Pro     iOS 19      2 minutes ago
# mob_b7e9f4a2  Pixel 9           Android     1 hour ago

Remove a Device

# Remove a specific device
openclaw mobile remove mob_a3f2c1d8

# Remove all devices
openclaw mobile remove --all

After removing a device, the OpenClaw app on that device will automatically disconnect and will require re-pairing to use again.

Mobile-Specific Configuration

You can configure independent behavior parameters for the mobile channel:

{
  "channels": {
    "mobile": {
      "enabled": true,
      "sessionIsolation": true,
      "persona": {
        "systemPrompt": "You are the user's personal AI assistant. Keep responses concise and suitable for mobile reading.",
        "tone": "casual"
      },
      "mediaSupport": {
        "image": true,
        "audio": true,
        "document": false
      },
      "offlineSync": {
        "enabled": true,
        "maxPendingMessages": 100,
        "syncOnConnect": true
      }
    }
  }
}

Parameter Descriptions

Parameter	Description
`sessionIsolation`	Whether mobile sessions are isolated from other channels
`persona`	Mobile-specific AI persona
`offlineSync`	Offline message sync configuration
`maxPendingMessages`	Maximum number of pending sync messages

Network and Security Configuration

LAN Pairing

If the phone and server are on the same local network, you can connect directly using the internal IP:

Server address: 192.168.1.100:18789

Public Network Pairing

When connecting over the public internet, it is strongly recommended to enable HTTPS:

{
  "security": {
    "tls": {
      "enabled": true,
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem"
    }
  }
}

Or use a reverse proxy (such as Nginx or Caddy) to provide TLS termination at the front end.

Pairing Security Mechanisms

OpenClaw's pairing process has multiple layers of built-in security:

Pairing codes expire after 5 minutes by default
Each pairing code can only be used once
After successful pairing, a TLS-based persistent connection is established between the device and server
Device access can be revoked from the server at any time

Common Issue Troubleshooting

Q: Pairing code is correct but connection fails?

Check whether the firewall allows port 18789, and confirm that host is set to "0.0.0.0" rather than "127.0.0.1".

Q: Push notifications not working?

Verify that APNs or FCM certificates are configured correctly. iOS requires a valid APNs Key file, and Android requires Firebase project Service Account credentials.

Q: Messages not syncing between multiple devices?

Confirm that all devices are connected to the same Agent and that sessionIsolation is not set to isolation mode.

Summary

OpenClaw's mobile node pairing feature frees you from dependency on third-party platforms, allowing direct AI assistant access from your phone. The pairing process is simple and secure — generate a pairing code, scan or enter it, confirm the connection — three steps and you're done. Combined with push notifications and offline sync, the mobile experience can be indistinguishable from a native app.