OpenClaw 모바일 노드 페어링: iOS 및 Android 연결 가이드

서문

OpenClaw은 Telegram, WhatsApp 등 서드파티 플랫폼을 통한 AI 상호작용뿐만 아니라, 네이티브 모바일 페어링 기능도 제공합니다. iOS 또는 Android 기기를 OpenClaw 서버에 페어링하면 서드파티 앱에 의존하지 않고 스마트폰에서 직접 AI 어시스턴트를 사용할 수 있습니다. 이 글에서는 모바일 노드의 페어링 프로세스와 일반적인 설정을 상세히 소개합니다.

모바일 노드 개요

OpenClaw의 모바일 노드(Mobile Node)는 경량 클라이언트 연결 방식입니다. 스마트폰이 안전한 WebSocket 연결을 통해 OpenClaw 게이트웨이에 연결되어, 다른 채널과 완전히 동일한 AI 상호작용 능력을 얻으면서 네이티브 푸시 알림과 오프라인 메시지 동기화를 제공합니다.

핵심 장점

서드파티 앱 불필요: OpenClaw 모바일 앱 또는 PWA를 통해 직접 사용
종단간 암호화: 페어링 과정에서 설정된 키로 통신 보안 보호
오프라인 동기화: 기기가 오프라인인 동안의 메시지가 재연결 시 자동 동기화
멀티 디바이스 지원: 한 사용자가 여러 기기를 페어링하고, 세션이 자동 동기화
푸시 알림: APNs(iOS)와 FCM(Android) 푸시 지원

사전 요구사항

페어링을 시작하기 전에 다음 조건을 확인하세요:

OpenClaw 서버가 시작되어 실행 중, 버전 >= 1.2.0
게이트웨이가 외부 연결을 허용하도록 설정되었거나 포트 포워딩이 설정됨
스마트폰과 서버가 같은 네트워크에 있거나 서버가 공인 인터넷에서 접근 가능
서버에서 모바일 노드 기능이 활성화됨

모바일 노드 활성화

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"
        }
      }
    }
  }
}

푸시 알림 설정은 선택 사항입니다. 푸시를 설정하지 않아도 모바일은 정상적으로 작동하지만, 앱이 백그라운드에 있을 때 알림을 받을 수 없습니다.

페어링 프로세스

1단계: 페어링 코드 생성

서버에서 임시 페어링 코드를 생성합니다:

# 페어링 코드 생성, 유효기간 5분
openclaw mobile pair --generate

# 출력 예시:
# 페어링 코드: AXKF-9M2P-RTLQ
# 만료 시간: 2026-03-14 15:05:00
# 페어링 링크: https://your-server:18789/pair/AXKF-9M2P-RTLQ

Web Dashboard의 "디바이스 관리" 페이지에서 "페어링 코드 생성" 버튼을 클릭할 수도 있습니다.

2단계: 스마트폰에서 페어링 코드 입력

iOS 페어링

App Store에서 "OpenClaw"을 검색하여 설치합니다(또는 Safari에서 Dashboard의 PWA 버전을 엽니다)
앱을 열고 "서버 연결"을 클릭합니다
서버 주소를 입력합니다: your-server-ip:18789
페어링 코드를 입력합니다: AXKF-9M2P-RTLQ
검증 완료를 기다립니다

Android 페어링

Google Play에서 "OpenClaw"을 검색하여 설치합니다
앱을 열고 "서버 추가"를 클릭합니다
수동으로 주소와 페어링 코드를 입력하거나, Dashboard에 표시된 QR 코드를 스캔합니다
연결을 확인합니다

3단계: 페어링 확인

페어링 성공 후 서버에 확인 정보가 표시됩니다:

[INFO] 새 디바이스 페어링 완료: iPhone 15 Pro (iOS 19.0)
[INFO] 디바이스 ID: mob_a3f2c1d8
[INFO] 사용자 식별자: mobile_user_001

스마트폰에서는 연결 상태 인디케이터가 초록색으로 바뀌고, 메시지를 보낼 수 있게 됩니다.

QR 코드 빠른 페어링

수동으로 페어링 코드를 입력하는 것 외에도, OpenClaw은 더 편리한 QR 코드 페어링을 지원합니다:

# 터미널에서 QR 코드 생성(터미널이 Unicode를 지원해야 함)
openclaw mobile pair --qrcode

# Dashboard에서 생성
# Dashboard → 디바이스 관리 → QR 코드 생성

QR 코드에는 서버 주소, 포트, 페어링 코드가 인코딩되어 있어, 스마트폰으로 스캔하면 한 단계로 연결이 완료됩니다.

디바이스 관리

페어링된 디바이스 확인

openclaw mobile list

# 출력 예시:
# ID            디바이스 이름        플랫폼      최근 활동
# mob_a3f2c1d8  iPhone 15 Pro     iOS 19    2분 전
# mob_b7e9f4a2  Pixel 9           Android   1시간 전

디바이스 제거

# 특정 디바이스 제거
openclaw mobile remove mob_a3f2c1d8

# 모든 디바이스 제거
openclaw mobile remove --all

디바이스를 제거하면 해당 기기의 OpenClaw 앱이 자동으로 연결 해제되며, 다시 페어링해야 사용할 수 있습니다.

모바일 전용 설정

모바일 채널에 독립적인 동작 매개변수를 설정할 수 있습니다:

{
  "channels": {
    "mobile": {
      "enabled": true,
      "sessionIsolation": true,
      "persona": {
        "systemPrompt": "당신은 사용자의 개인 AI 어시스턴트입니다. 스마트폰 화면에 맞게 간결하게 응답하세요.",
        "tone": "casual"
      },
      "mediaSupport": {
        "image": true,
        "audio": true,
        "document": false
      },
      "offlineSync": {
        "enabled": true,
        "maxPendingMessages": 100,
        "syncOnConnect": true
      }
    }
  }
}

매개변수 설명

매개변수	설명
`sessionIsolation`	모바일 세션이 다른 채널과 격리되는지 여부
`persona`	모바일 전용 AI 페르소나
`offlineSync`	오프라인 메시지 동기화 설정
`maxPendingMessages`	최대 대기 동기화 메시지 수

네트워크 및 보안 설정

로컬 네트워크 페어링

스마트폰과 서버가 같은 로컬 네트워크에 있으면 내부 IP로 직접 연결할 수 있습니다:

서버 주소: 192.168.1.100:18789

공인 인터넷 페어링

공인 인터넷을 통해 연결할 때는 HTTPS 활성화를 강력히 권장합니다:

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

또는 리버스 프록시(Nginx, Caddy 등)를 사용하여 프론트엔드에서 TLS 종료를 제공합니다.

페어링 보안 메커니즘

OpenClaw의 페어링 과정에는 다층 보안 보호가 내장되어 있습니다:

페어링 코드 유효기간은 기본 5분이며, 만료 시 자동 무효화
각 페어링 코드는 한 번만 사용 가능
페어링 성공 후 기기와 서버 간에 TLS 기반 장기 연결 설정
서버에서 언제든 기기의 접근 권한 취소 가능

자주 묻는 질문

Q: 페어링 코드를 올바르게 입력했는데 연결이 실패합니다?

방화벽이 18789 포트를 허용하는지 확인하고, host 설정이 "127.0.0.1"이 아닌 "0.0.0.0"인지 확인하세요.

Q: 푸시 알림이 작동하지 않습니다?

APNs 또는 FCM 인증서 설정이 올바른지 확인하세요. iOS는 유효한 APNs Key 파일이 필요하고, Android는 Firebase 프로젝트의 Service Account 자격 증명이 필요합니다.

Q: 여러 기기 간 메시지가 동기화되지 않습니다?

모든 기기가 동일한 Agent에 연결되어 있는지, sessionIsolation이 격리 모드로 설정되지 않았는지 확인하세요.

정리

OpenClaw의 모바일 노드 페어링 기능을 통해 서드파티 플랫폼에 대한 의존 없이 스마트폰에서 직접 AI 어시스턴트를 사용할 수 있습니다. 페어링 과정은 간결하고 안전합니다. 페어링 코드 생성, 스캔 또는 입력, 연결 확인, 3단계로 완료됩니다. 푸시 알림과 오프라인 동기화를 결합하면 모바일 경험을 네이티브 앱과 다를 바 없이 만들 수 있습니다.