Quickstart

Install the SDK and make your first RPC call in under 5 minutes.

Install

bun add moltlazy

The SDK exports are available from moltlazy/sdk:

import { createClient } from 'moltlazy/sdk';

Pattern 1: Direct client calls

Use the typed RPC client when you need fine-grained control over individual gateway operations.

import { createClient } from 'moltlazy/sdk';

const client = createClient({
  baseUrl: 'http://localhost:18789',
  token: process.env.OPENCLAW_GATEWAY_TOKEN!,
});

// Read full config
const config = await client.config.get();
if (config.ok) {
  console.log(config.payload);
}

// Apply a config fragment (raw JSON string)
await client.config.set({ raw: JSON.stringify({ session: { dmScope: 'per-channel-peer' } }) });

// List agents
const agents = await client.agents.list();

// Approve a device pairing request
await client.devices.approve({ requestId: 'request-id-123' });

// Restart the gateway
await client.gateway.restart();

Pattern 2: Config Module (startup patching)

The Config Module runs at container startup before the gateway starts. It generates moltlazy.json with all mandatory config and injects $include: "./moltlazy.json" into openclaw.json.

# In start-openclaw.sh:
moltlazy patch

This reads MOLTLAZY_FEATURE_FLAGS from the environment, generates /home/openclaw/.openclaw/moltlazy.json, and ensures the $include directive exists in openclaw.json.

Auth

All RPC calls require a Bearer token matching the gateway’s gateway.auth.token config value:

const client = createClient({
  baseUrl: 'http://localhost:18789',
  token: process.env.OPENCLAW_GATEWAY_TOKEN!,
});

The token is never included in RPC call parameters — it’s sent as an HTTP Authorization: Bearer header.

Retry behavior

The client retries on HTTP 503 (Service Unavailable) up to maxRetries times (default: 3) with retryDelay ms between attempts (default: 1000ms).

const client = createClient({
  baseUrl: 'http://localhost:18789',
  token: '...',
  timeout: 15_000, // 15s request timeout
  maxRetries: 5, // retry up to 5 times on 503
  retryDelay: 2_000, // 2s between retries
});

Handling responses

Every call returns RpcResponse<T> — always check ok before using payload:

const result = await client.agents.list();

if (result.ok) {
  for (const agent of result.payload) {
    console.log(agent.name);
  }
} else {
  console.error(`Error ${result.error.code}: ${result.error.message}`);
}