openclaw-client

library2.1.1jsnpmunverified

Lightweight TypeScript client for the OpenClaw Gateway WebSocket RPC protocol. Current stable version is 2.1.1, released with a focus on device identity management and auto-reconnection. Ships TypeScript types, requires Node.js ≥18.0.0. Key differentiators include built-in Ed25519 device signing, optional auto-reconnect with exponential backoff, and comprehensive browser support via Web Crypto API. The library is actively maintained with a clear migration path from earlier versions.

messaging

npm install openclaw-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENCLAW-CLIENT

openclaw-client

messagingjavascriptv2.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OpenClawClient

✓ import { OpenClawClient } from 'openclaw-client'

✗ const OpenClawClient = require('openclaw-client')

ESM-only; CommonJS require will fail. Named export only.

DeviceIdentityRecord

✓ import type { DeviceIdentityRecord } from 'openclaw-client'

✗ import DeviceIdentityRecord from 'openclaw-client'

TypeScript type, use `import type` for correct runtime erasure.

DeviceIdentityStore

✓ import type { DeviceIdentityStore } from 'openclaw-client'

✗ import { DeviceIdentityStore } from 'openclaw-client'

Interface, not a value; import as type.

DeviceTokenStore

✓ import type { DeviceTokenStore } from 'openclaw-client'

✗ const { DeviceTokenStore } = require('openclaw-client')

TypeScript interface, use import type.

Connects to a local OpenClaw Gateway, lists sessions, and disconnects. Requires a valid token.

import { OpenClawClient } from 'openclaw-client'; const client = new OpenClawClient({ gatewayUrl: 'ws://localhost:18789', token: process.env.OPENCLAW_TOKEN ?? '', }); const result = await client.connect(); console.log('Connected:', result.server.connId); const sessions = await client.listSessions(); console.log('Sessions:', sessions); client.disconnect();

Debug

Known issues

breakingIn v2.0, the constructor option `deviceIdentity` was introduced and `connectParams` behavior changed. If `deviceIdentity` is set and `connectParams` is a function, the function is NOT called (device identity takes precedence). Previously the function was always called.

fix

If you use both `deviceIdentity` and a `connectParams` function, refactor to either use only device identity or merge logic into `deviceIdentity` callbacks.

affects: >=2.0.0

gotchaDevice identity features (Ed25519) require Node.js 20+ or modern browsers (Chrome 113+, Safari 17+, Firefox 130+). The library still works on Node 18+ without device identity, but will throw runtime errors if you pass `deviceIdentity` or `deviceToken` stores on older runtimes.

fix

Use Node.js 20+ or a browser with Web Crypto Ed25519 support when using device identity. Optionally, wrap device identity setup in a runtime check.

affects: >=1.0.0

deprecatedThe `reconnect.maxAttempts` default changed from `null` to `Infinity` in v2.1.0. Code that relied on `null` meaning infinite may break if strict equality checks are used.

fix

Check for `reconnect.maxAttempts === null` might fail; use `!reconnect.maxAttempts` instead.

affects: >=2.1.0

Errors

Common errors & fixes

TypeError: openclaw_client_1.OpenClawClient is not a constructor

Using CommonJS require() with an ESM-only package.

fix

Change to `import { OpenClawClient } from 'openclaw-client'` or use dynamic import.

Error: Web Crypto Ed25519 not available in this runtime

Device identity features used on Node.js <20 or unsupported browser.

fix

Upgrade to Node.js 20+ or use a supported browser. If not needed, omit `deviceIdentity` and `deviceToken` options.

Error: connect() called multiple times without disconnect

Calling connect() while a connection is already open or pending.

fix

Ensure you call `client.disconnect()` before calling `connect()` again, or check client connection state.

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/stugreen13/openclaw-client ↗

packageopenclaw-client ↗

homepagehttps://github.com/stugreen13/openclaw-client#readme ↗