openclaw-node

library0.12.1jsnpmunverified

A Node.js client for the OpenClaw Gateway WebSocket protocol, enabling communication with AI agents. Version 0.12.1 is the latest stable release, with frequent updates as the project is actively developed. Differentiators include streaming and sync chat APIs, built-in auto-reconnect, and first-class TypeScript support. Requires Node.js 20+ (22+ for built-in WebSocket) and a running OpenClaw Gateway server. The library handles WebSocket handshake, authentication, and keepalive automatically. Compared to alternatives like LangChain or Vercel AI SDK, OpenClaw focuses on persistent agents with tools and memory, running locally via a gateway.

ai-ml

npm install openclaw-node

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENCLAW-NODE

openclaw-node

ai-mljavascriptv0.12.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-node"

✗ const OpenClawClient = require("openclaw-node")

The package is ESM-only. Named import is required; there is no default export.

Demonstrates connecting to the gateway, sending a streaming chat request, iterating over chunks, using sync chat, and disconnecting.

import { OpenClawClient } from "openclaw-node"; const client = new OpenClawClient({ url: "ws://localhost:18789", token: process.env.OPENCLAW_GATEWAY_TOKEN ?? "", }); await client.connect(); // Streaming chat const stream = client.chat("What's the weather like in Vienna?"); for await (const chunk of stream) { if (chunk.type === "text") { process.stdout.write(chunk.text); } } // Sync chat const response = await client.chatSync("Summarize my last 3 meetings"); console.log(response); await client.disconnect();

Debug

Known issues

breakingNode.js 20-21 require installing the 'ws' package; only Node 22+ has built-in WebSocket support.

fix

For Node 20-21, install 'ws' alongside openclaw-node: npm install openclaw-node ws. For Node 22+, no extra step needed.

affects: >=0.0.0

gotchaThe client does not validate the WebSocket URL or token at construction time; errors only surface on connect().

fix

Wrap client.connect() in try/catch to handle connection or authentication failures.

affects: >=0.0.0

gotchaUsing chat() without awaiting the stream's async iteration may lead to unhandled promise rejections if the connection drops mid-stream.

fix

Always use for await...of on the stream, or consume it via a try/catch block to catch errors from the WebSocket.

affects: >=0.0.0

deprecatedThe constructor option 'reconnect' was renamed to 'autoReconnect' in v0.10.0.

fix

Use 'autoReconnect: true' instead of 'reconnect: true'.

affects: >=0.10.0

breakingIn v0.8.0, the chunk type 'tool_call' was renamed to 'tool_use'. Older code checking for 'tool_call' will miss events.

fix

Update your switch/case to handle 'tool_use' instead of 'tool_call'.

affects: >=0.8.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'endsWith')

The WebSocket URL is missing or invalid, causing internal parsing failure.

fix

Ensure the URL ends with '/ws' or is a valid WebSocket endpoint. Example: 'ws://localhost:18789'.

Error: Connection refused: ws://localhost:18789

The OpenClaw Gateway is not running at the specified URL.

fix

Start the gateway: npx openclaw gateway start (or openclaw gateway start if installed globally).

Error: Authentication failed: invalid token

The token provided to the client does not match the gateway's OPENCLAW_GATEWAY_TOKEN.

fix

Set the same token on both sides: gateway environment variable and client constructor option.

TypeError: client.chat is not a function

The import is incorrect (maybe default import instead of named import).

fix

Use: import { OpenClawClient } from 'openclaw-node'.

Upgrade

Version history

0.12.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/heypinchy/openclaw-node ↗

packageopenclaw-node ↗

homepagehttps://heypinchy.com ↗