OpenClaw Node.js Client

Use Cases

• Building custom web dashboards that interact with OpenClaw agents
• Automation scripts that send tasks to OpenClaw and process results programmatically
• Custom chat UIs with real-time streaming and tool execution visibility
• Integration bridges connecting OpenClaw to other platforms not covered by channel plugins
• Testing and development tools for OpenClaw plugin/skill development
• Multi-user platforms (like Pinchy) that wrap OpenClaw with additional features

Tips

• Use chatSync() for simple scripts that just need a complete response, and chat() for UIs that want real-time streaming
• Pass sessionKey to continue existing conversations — sessions persist on the gateway across connections
• Use agentId to target specific agents if your gateway runs multiple agent configurations
• The config.get() method returns a hash — use it as baseHash in config.patch() for optimistic locking
• For production apps, handle the auto-reconnect events to show connection status in your UI
• Study this library's source code as a reference implementation if you're building Gateway clients in other languages

Known Issues & Gotchas

• This is NOT an OpenClaw plugin — don't try to install it with 'openclaw plugins install'. Use 'npm install openclaw-node' in your own project
• Node.js 20-21 users MUST also install the 'ws' package: npm install openclaw-node ws
• The client auto-reconnects by default (maxReconnectAttempts: 10) — disable with autoReconnect: false if you want manual control
• Gateway auth token must match between client and server — if you get auth errors, check OPENCLAW_GATEWAY_TOKEN on both sides
• Streaming responses are async iterators — you must use 'for await...of' syntax, not regular for loops
• The 'done' chunk type signals stream completion — always handle it to know when the response is finished
• chatSync() returns a plain string, not a stream — use chat() for real-time streaming

Alternatives

• Direct WebSocket connection
• OpenClaw REST API (Control UI)
• OpenClaw Studio

Community Feedback

Almost forgot — we also extracted Pinchy's WebSocket bridge into a standalone npm package: openclaw-node. It's the first Node.js client for OpenClaw's Gateway protocol.

— Pinchy Blog

Let's be honest: it's a Trojan Horse. A genuinely useful utility that happens to live under the heypinchy GitHub org. Every npm install openclaw-node is a breadcrumb back here. Not sneaky — just strategic.

— Pinchy Blog

A Node.js client for OpenClaw — connect your app to AI agents in a few lines of code. OpenClaw is an open-source AI agent platform. This package lets you talk to those agents from Node.js.

— GitHub

Frequently Asked Questions

Configuration Examples

Basic chat with streaming

import { OpenClawClient } from 'openclaw-node';

const client = new OpenClawClient({
  url: 'ws://localhost:18789',
  token: process.env.OPENCLAW_GATEWAY_TOKEN,
});

await client.connect();

for await (const chunk of client.chat('What is on my calendar today?')) {
  if (chunk.type === 'text') process.stdout.write(chunk.text);
  if (chunk.type === 'tool_use') console.log(`\n🔧 ${chunk.text}`);
}

await client.disconnect();

Session management

const sessions = await client.sessions.list({ limit: 10 });
console.log(sessions);

const history = await client.sessions.history('session-key', { limit: 20 });
for (const msg of history) {
  console.log(`[${msg.role}] ${msg.content}`);
}

Runtime config management

// Read current config with hash for optimistic locking
const { config, hash } = await client.config.get();
console.log(config);

// Patch config safely
await client.config.patch({ models: { default: 'anthropic/claude-sonnet-4-20250514' } }, hash);

Installation

npm install openclaw-node