{"id":45155082,"url":"https://github.com/heypinchy/openclaw-node","last_synced_at":"2026-05-20T11:02:51.360Z","repository":{"id":339457240,"uuid":"1161991342","full_name":"heypinchy/openclaw-node","owner":"heypinchy","description":"Node.js client for the OpenClaw Gateway WebSocket protocol","archived":false,"fork":false,"pushed_at":"2026-05-05T04:36:14.000Z","size":268,"stargazers_count":11,"open_issues_count":5,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-05T06:28:13.432Z","etag":null,"topics":["ai-agents","client","nodejs","openclaw","typescript","websocket"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heypinchy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-19T18:47:49.000Z","updated_at":"2026-05-05T04:33:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/heypinchy/openclaw-node","commit_stats":null,"previous_names":["heypinchy/openclaw-node"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/heypinchy/openclaw-node","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heypinchy%2Fopenclaw-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heypinchy%2Fopenclaw-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heypinchy%2Fopenclaw-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heypinchy%2Fopenclaw-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heypinchy","download_url":"https://codeload.github.com/heypinchy/openclaw-node/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heypinchy%2Fopenclaw-node/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33254728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-20T04:48:54.280Z","status":"ssl_error","status_checked_at":"2026-05-20T04:48:10.851Z","response_time":356,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","client","nodejs","openclaw","typescript","websocket"],"created_at":"2026-02-20T04:03:09.747Z","updated_at":"2026-05-20T11:02:51.350Z","avatar_url":"https://github.com/heypinchy.png","language":"TypeScript","funding_links":[],"categories":["Skills \u0026 Plugins"],"sub_categories":["Third-Party Platforms"],"readme":"# openclaw-node\n\nA Node.js client for [OpenClaw](https://github.com/openclaw/openclaw) — connect your app to AI agents in a few lines of code.\n\n## What is OpenClaw?\n\nOpenClaw is an open-source AI agent platform. You run a **Gateway** (a local server) that manages AI agents — think of them as persistent AI assistants that can use tools, remember context, and connect to services like Slack, Telegram, or your own app.\n\nThis package lets you talk to those agents from Node.js.\n\n## Prerequisites\n\nBefore using this client, you need a running OpenClaw Gateway:\n\n```bash\n# Install OpenClaw\nnpm install -g openclaw\n\n# Start the gateway\nopenclaw gateway start\n```\n\nThe gateway runs on `ws://localhost:18789` by default. If you've set an auth token (via `OPENCLAW_GATEWAY_TOKEN`), you'll need it for the client too.\n\n→ [Full OpenClaw setup guide](https://docs.openclaw.ai)\n\n## Installation\n\n```bash\nnpm install openclaw-node\n```\n\n\u003e **Node.js 22+** works out of the box (built-in WebSocket). For Node.js 20–21, also install `ws`:\n\u003e\n\u003e ```bash\n\u003e npm install openclaw-node ws\n\u003e ```\n\n## Quick Start\n\n```typescript\nimport { OpenClawClient } from \"openclaw-node\";\n\nconst client = new OpenClawClient({\n  url: \"ws://localhost:18789\",\n  // Only needed if your gateway has a token set:\n  // token: process.env.OPENCLAW_GATEWAY_TOKEN,\n});\n\nawait client.connect();\n\n// Send a message and stream the response\nconst stream = client.chat(\"What's the weather like in Vienna?\");\n\nfor await (const chunk of stream) {\n  if (chunk.type === \"text\") {\n    process.stdout.write(chunk.text);\n    // Prints token by token: \"The current weather in Vienna is...\"\n  }\n}\n// Final chunk has type \"done\"\n\nawait client.disconnect();\n```\n\n### Get a complete response (no streaming)\n\n```typescript\nconst response = await client.chatSync(\"Summarize my last 3 meetings\");\nconsole.log(response);\n// \"Here's a summary of your recent meetings: ...\"\n```\n\n## Core Concepts\n\n**Gateway** — The local server that runs your agents. This client connects to it via WebSocket. Default address: `ws://localhost:18789`.\n\n**Agent** — A configured AI assistant with its own personality, tools, and memory. The gateway can run multiple agents. Each has an `agentId`.\n\n**Session** — A conversation thread with an agent. Sessions persist across connections, so you can pick up where you left off. Each session has a `sessionKey`.\n\n**Token** — An optional auth string that protects your gateway from unauthorized access. Set it via `OPENCLAW_GATEWAY_TOKEN` on the gateway, then pass the same value to this client.\n\n## API Reference\n\n### Constructor\n\n```typescript\nconst client = new OpenClawClient({\n  url: \"ws://localhost:18789\", // Gateway address (required)\n  token: \"my-secret-token\", // Auth token (optional, must match gateway)\n  autoReconnect: true, // Reconnect on disconnect (default: true)\n  maxReconnectAttempts: 10, // Give up after N retries (default: 10)\n});\n```\n\n### Connecting\n\n```typescript\nawait client.connect(); // Connect and authenticate\nawait client.disconnect(); // Gracefully close\n\nclient.isConnected; // true/false\n```\n\nThe client handles all protocol details (challenge-response handshake, authentication, keepalive) automatically.\n\n### Chat — Streaming\n\n```typescript\nconst stream = client.chat(\"Your message here\", {\n  sessionKey: \"optional-session-id\", // Continue a specific conversation\n  agentId: \"optional-agent-id\", // Talk to a specific agent\n});\n\nfor await (const chunk of stream) {\n  switch (chunk.type) {\n    case \"text\":\n      process.stdout.write(chunk.text); // Partial response text\n      break;\n    case \"tool_use\":\n      console.log(`\\n🔧 Using tool: ${chunk.text}`);\n      break;\n    case \"tool_result\":\n      console.log(`✅ Tool result: ${chunk.text}`);\n      break;\n    case \"agent_start\":\n      // Optional: fired when a run begins. Useful for progress indicators.\n      break;\n    case \"agent_end\":\n      // Optional: fired when a run ends (successfully). Pair with `error` for\n      // full terminal coverage.\n      break;\n    case \"error\":\n      // Terminal failure. Includes provider-level errors (auth, quota,\n      // rate limits) in addition to RPC errors.\n      console.error(`\\n❌ ${chunk.text}`);\n      break;\n    case \"done\":\n      // End of one assistant turn. Multi-turn streams (e.g. with tool\n      // loops) emit several `done` chunks — not a terminator for the stream.\n      console.log(\"\\n--- Turn complete ---\");\n      break;\n  }\n}\n```\n\n### Chat — Complete Response\n\n```typescript\nconst reply = await client.chatSync(\"What's on my calendar today?\");\n// Returns the full response as a string\n```\n\n### Sessions\n\nSessions are conversation threads. They persist on the gateway, so you can resume them later.\n\n```typescript\n// List all sessions\nconst sessions = await client.sessions.list({ limit: 10 });\n\n// Get message history for a session\nconst history = await client.sessions.history(\"session-key-here\", {\n  limit: 20,\n});\n\n// Send a message into an existing session\nawait client.sessions.send(\"session-key-here\", \"Follow up on yesterday's task\");\n```\n\n### Configuration\n\nRead and update the Gateway configuration at runtime without restarting.\n\n```typescript\n// Get the current config and its hash (for optimistic locking)\nconst result = await client.config.get();\nconsole.log(result.config); // full config object\nconsole.log(result.hash); // use this as baseHash for patch/apply\n\n// Patch config (JSON merge patch: objects merge, null deletes, arrays replace)\nawait client.config.patch(\n  JSON.stringify({ channels: { telegram: { enabled: true } } }),\n  result.hash,\n  { note: \"Enable Telegram channel\" },\n);\n\n// Replace the full config\nawait client.config.apply(JSON.stringify(fullConfig), result.hash);\n```\n\nBoth `patch` and `apply` accept optional parameters:\n\n- `sessionKey` — associate the change with a session\n- `note` — human-readable description of the change\n- `restartDelayMs` — delay before the Gateway restarts affected services\n\n### Channels\n\nCheck the status of configured channels (Telegram, Slack, WhatsApp, etc.):\n\n```typescript\nconst status = await client.channels.status();\nconsole.log(status);\n// { telegram: { connected: true }, slack: { connected: false } }\n```\n\n### Pairing\n\nManage channel pairing requests (e.g., approve Telegram users who want to link their account):\n\n```typescript\n// List pending pairing requests for a channel\nconst pending = await client.pairing.list(\"telegram\");\n\n// Approve a pairing request\nawait client.pairing.approve(\"telegram\", \"ABC123\");\n```\n\n\u003e **Note:** Pairing RPC methods are inferred from CLI behavior and may not be available on all Gateway versions. Use `client.request()` with error handling, or check availability before calling.\n\n### Events\n\n```typescript\n// Connection lifecycle\nclient.on(\"connected\", (info) =\u003e console.log(\"Connected to gateway\"));\nclient.on(\"disconnected\", ({ reason }) =\u003e console.log(\"Disconnected:\", reason));\nclient.on(\"error\", (err) =\u003e console.error(\"Error:\", err));\n\n// Gateway events (exec approvals, presence changes, etc.)\nclient.on(\"event\", (event) =\u003e {\n  console.log(\"Gateway event:\", event.event, event.payload);\n});\n```\n\n### Low-Level Protocol Access\n\nFor advanced use cases, you can send raw protocol requests:\n\n```typescript\nconst response = await client.request(\"status\", {});\nconsole.log(response.payload);\n```\n\n## Examples\n\n### Express API with AI backend\n\n```typescript\nimport express from \"express\";\nimport { OpenClawClient } from \"openclaw-node\";\n\nconst app = express();\nconst client = new OpenClawClient({ url: \"ws://localhost:18789\" });\n\nawait client.connect();\n\napp.post(\"/api/ask\", express.json(), async (req, res) =\u003e {\n  const answer = await client.chatSync(req.body.question);\n  res.json({ answer });\n});\n\napp.listen(3000);\n```\n\n### CLI chatbot\n\n```typescript\nimport readline from \"readline\";\nimport { OpenClawClient } from \"openclaw-node\";\n\nconst client = new OpenClawClient({ url: \"ws://localhost:18789\" });\nawait client.connect();\n\nconst rl = readline.createInterface({ input: process.stdin, output: process.stdout });\n\nrl.on(\"line\", async (input) =\u003e {\n  for await (const chunk of client.chat(input)) {\n    if (chunk.type === \"text\") process.stdout.write(chunk.text);\n  }\n  console.log();\n});\n```\n\n## Compatibility\n\n| openclaw-node | Gateway Protocol | OpenClaw Gateway | What's new           |\n| ------------- | ---------------- | ---------------- | -------------------- |\n| 0.2.x         | v3               | 0.x (current)    | Tool event streaming |\n| 0.1.x         | v3               | 0.x              | Initial release      |\n\nIf the OpenClaw Gateway bumps its protocol version, you'll need a matching openclaw-node release. Check this table to find the right version.\n\n## Features\n\n- **Streaming** — AsyncIterator-based, get responses token by token\n- **Tool events** — See which tools agents use and what they return (`tool_use` / `tool_result` chunks)\n- **Auto-reconnect** — Exponential backoff, configurable retries\n- **TypeScript-first** — Full type definitions for all protocol messages\n- **Zero config** — Handles the full WebSocket protocol (handshake, auth, keepalive) for you\n- **Lightweight** — Zero required dependencies on Node.js 22+\n\n## Built for Pinchy\n\nThis client was extracted from [Pinchy](https://github.com/heypinchy/pinchy), an open-source web UI for OpenClaw with multi-user support, agent permissions, and a dashboard. It works great standalone — use it to build your own OpenClaw integrations.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE)\n\n## Links\n\n- [OpenClaw](https://github.com/openclaw/openclaw) — The AI agent platform\n- [Pinchy](https://heypinchy.com) — Open-source web UI for OpenClaw\n- [OpenClaw Docs](https://docs.openclaw.ai) — Gateway setup and configuration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheypinchy%2Fopenclaw-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheypinchy%2Fopenclaw-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheypinchy%2Fopenclaw-node/lists"}