react-native-openclaw

Run OpenClaw AI agent gateway headlessly on Android — no Termux, no root, no proot. Any React Native app can install this package and start an OpenClaw gateway process on-device.

How It Works

The package bundles a glibc dynamic loader and shared libraries. At first run, it downloads Node.js and installs OpenClaw via npm. The gateway runs as an Android foreground service.

APK ships:     libld_linux.so (JNI) + 7 glibc libs (assets)
First run:     Downloads Node.js → npm install openclaw
Runtime:       ld-linux → node.bin → openclaw gateway (foreground service)

Installation

yarn add react-native-openclaw
# or
npm install react-native-openclaw

That's it. Autolinking handles the native module registration, AndroidManifest merging, and asset packaging.

Requirements

• React Native 0.73+ (bare workflow)
• Android device/emulator (arm64)
• ~40MB download on first run (Node.js)
• Android 7.0+ (API 24)

Usage

Setup (First Run)

Downloads Node.js and installs OpenClaw. Call once, typically in an onboarding screen.

import { openclaw, onSetupProgress } from 'react-native-openclaw'

// Listen to setup progress
const unsub = onSetupProgress(({ step, percent }) => {
  console.log(`${step} (${percent}%)`)
})

await openclaw.runSetup()
unsub.remove()

Start Gateway

import { openclaw, onLog, onGatewayExit } from 'react-native-openclaw'

// Stream logs
const logUnsub = onLog((line) => console.log(line))

// Handle unexpected exits
const exitUnsub = onGatewayExit((code) => {
  console.log(`Gateway exited with code ${code}`)
})

// Start with environment variables
await openclaw.startGateway({
  envVars: {
    ZAI_API_KEY: 'your-api-key',
    TELEGRAM_BOT_TOKEN: 'your-bot-token',
  },
})

Stop Gateway

await openclaw.stopGateway()
logUnsub.remove()
exitUnsub.remove()

Check State

const running = await openclaw.isRunning()
const setup = await openclaw.isSetupComplete()
const info = await openclaw.getRuntimeInfo()
const version = await openclaw.getNodeVersion()

API Reference

openclaw — Core API

Method	Returns	Description
runSetup()	Promise<{success, nodeVersion}>	Full glibc + Node.js + OpenClaw setup
isSetupComplete()	Promise<boolean>	Check if setup has been completed
startGateway(options?)	Promise<string>	Start gateway with optional env vars
stopGateway()	Promise<string>	Kill gateway + children + cleanup
isRunning()	Promise<boolean>	Process alive check
getNodeVersion()	Promise<string>	Installed Node.js version
verifyRuntime()	Promise<RuntimeVerify>	Diagnostic info (glibc, node, openclaw)
getRuntimeInfo()	Promise<RuntimeInfo>	Full runtime environment info
runCommand(cmd)	Promise<string>	Run a shell command via Node.js

Vault (Optional)

Method	Returns	Description
initVault(path)	Promise<string>	Create vault directory structure
migrateToVault(path)	Promise<boolean>	Copy workspace to vault
getVaultPath()	Promise<string | null>	Get current vault path
setVaultEnabled(bool)	Promise<boolean>	Toggle vault
isVaultEnabled()	Promise<boolean>	Check vault enabled

Boot Auto-Start

Method	Returns	Description
setAutoStartOnBoot(bool)	Promise<boolean>	Toggle boot auto-start
getAutoStartOnBoot()	Promise<boolean>	Check boot auto-start

Events

import { onSetupProgress, onLog, onGatewayExit } from 'react-native-openclaw'

Event	Callback Signature	Description
onSetupProgress	(progress: SetupProgress) => void	Setup progress {step, percent}
onLog	(line: string) => void	Gateway stdout lines (batched 20/100ms)
onGatewayExit	(code: number) => void	Gateway process exit code

Each returns { remove: () => void } for unsubscribing.

Types

interface StartOptions {
  envVars?: Record<string, string>
}

interface SetupProgress {
  step: string
  percent: number
}

interface RuntimeInfo {
  filesDir: string
  nativeLibDir: string
  glibcReady: boolean
  nodeReady: boolean
  openclawReady: boolean
  setupComplete: boolean
}

interface RuntimeVerify {
  glibcExists: boolean
  glibcExecutable: boolean
  nodeInstalled: boolean
  openclawInstalled: boolean
  setupComplete: boolean
}

Architecture

┌─────────────────────────────────────────────────────────┐
│                  Consumer React Native App               │
│                                                         │
│  Consumer code imports:                                 │
│  import { openclaw, onLog } from 'react-native-openclaw'│
│                                                         │
│         ┌──────────────────┐                            │
│         │  openclaw.start  │                            │
│         │  onLog / onExit  │                            │
│         └────────┬─────────┘                            │
│                  │ NativeModules bridge                 │
├──────────────────┼──────────────────────────────────────┤
│                  ▼                                       │
│  OpenClawProcessModule (Kotlin native module)            │
│         │                                                │
│         ├── OpenClawRuntime.kt (process mgmt)            │
│         ├── OpenClawGatewayService.kt (foreground svc)   │
│         └── LocalConnectProxy.kt (npm DNS bypass)        │
│         │                                                │
├─────────┼────────────────────────────────────────────────┤
│         ▼  Android OS (Linux kernel + Bionic libc)       │
│                                                         │
│  Process: ld-linux → node.bin → openclaw gateway        │
└─────────────────────────────────────────────────────────┘

The glibc-on-Android Problem

Android uses Bionic libc, but official Node.js binaries are compiled for glibc. This package solves it by bundling a glibc dynamic loader:

Component	Location	Permission	Why
libld_linux.so (loader)	nativeLibraryDir (JNI)	exec	Android extracts JNI libs to a dir with exec permission
glibc shared libs	filesDir/glibc/ (APK assets)	read/mmap	Only need mmap for dlopen, not exec
Node.js binary	filesDir/node/ (downloaded)	read/mmap	Loaded by ld-linux via mmap
hijack.js preload	filesDir/	read	Patches DNS, process.execPath, child_process

DNS Resolution

glibc's getaddrinfo() needs /etc/resolv.conf (doesn't exist on Android). The package uses a two-layer strategy:

1. hijack.js c-ares patch — patches dns.lookup() to use c-ares with explicit DNS servers (8.8.8.8, 1.1.1.1). Handles all runtime API calls.
2. LocalConnectProxy — HTTP CONNECT proxy for npm's TLS handshake during setup. Only runs when plugin deps aren't staged yet.

Child Process Spawning

When Node.js runs via ld-linux, process.execPath returns the ld-linux path. The hijack.js preload script patches process.execPath, child_process.spawn, child_process.execFile, and child_process.exec to redirect node invocations through ld-linux.

Environment Variables

Pass these via startGateway({ envVars }). OpenClaw reads them at runtime:

Variable	Purpose
ZAI_API_KEY	GLM/z.ai model provider
ANTHROPIC_API_KEY	Anthropic models
OPENAI_API_KEY	OpenAI/Custom provider
OPENROUTER_API_KEY	OpenRouter
GROQ_API_KEY	Groq
TELEGRAM_BOT_TOKEN	Telegram channel
MATTERMOST_BOT_TOKEN	Mattermost channel
MATTERMOST_BASE_URL	Mattermost server URL

AndroidManifest

The library's manifest declares these (merged into your app automatically):

• Permissions: INTERNET, FOREGROUND_SERVICE, FOREGROUND_SERVICE_SPECIAL_USE, WAKE_LOCK, POST_NOTIFICATIONS, RECEIVE_BOOT_COMPLETED
• Service: OpenClawGatewayService (foreground, specialUse type)
• Receiver: BootReceiver (auto-start on boot, requires user opt-in via setAutoStartOnBoot(true))

No manual manifest changes needed in your app.

Known Limitations

• arm64 only — glibc libs and Node.js binary are aarch64-specific
• No x86 emulator support — use a physical device or arm64 emulator
• Plugin staging — some OpenClaw plugins need npm install on first start (a few seconds each)
• Android 16 stricter SELinux — handled by hijack.js spawn patching

License

MIT