openclaw-agent-sdk

Agent SDK for connecting to openclaw Hub — session management, tool registration, and streaming.

Installation

npm install openclaw-agent-sdk

Quick Start

import { AgentClient } from "openclaw-agent-sdk";

const client = AgentClient.connect({
  baseUrl: "https://your-hub-instance.example.com",
  projectId: "your-project-id",
  apiKey: "your-api-key",
});

// Register host tools
client.registerTool({
  id: "file-read",
  displayName: "Read File",
  description: "Read a local file by path",
  inputSchema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
  outputSchema: { type: "object", properties: { content: { type: "string" } } },
  capabilities: ["filesystem"],
  availability: { installed: true, enabled: true, hostLocalOnly: true },
  canHandle: () => true,
  invoke: async (_ctx, input: { path: string }) => {
    const fs = await import("node:fs/promises");
    return { content: await fs.readFile(input.path, "utf-8") };
  },
});

// Create a session and run a turn
const session = await client.createSession();
const result = await session.run("What files are in the current directory?", {
  onDelta: (packet) => process.stdout.write(packet.payload.chunk),
});
console.log("\n\nFinal:", result.text);
await session.dispose();

Features

• AgentClient — Connection factory, tool registration, session creation
• AgentSession — Session state management, tool invocation, approval handling
• AgentSessionTransport — WebSocket-based packet routing
• HostToolAdapter — Pluggable host tool interface with capability manifests
• Bootstrap resolver — Runtime endpoint discovery (explicit, bootstrap API, or derived)

Environment Support

• Node.js ≥ 20 (uses ws for WebSocket)
• Browser — provide a custom transportWebSocketFactory using the native WebSocket API

API Documentation

Generate the API reference locally:

npm run docs
# → docs/api/index.html

Dependencies

• openclaw-proxy-protocol — Protocol message types
• openclaw-agent-runtime-contracts — Runtime capability contracts
• ws (peer, optional) — Node.js WebSocket client

License

MIT