OpenClaw App SDK

The OpenClaw App SDK is the public client API for apps outside the OpenClaw process. Use

when a script, dashboard, CI job, IDE extension, or other external app wants to connect to the Gateway, start agent runs, stream events, wait for results, cancel work, or inspect Gateway resources.

What Ships Today

ships with:

The SDK also exports the core types used by those surfaces:

, , , , , , , , , , , , , , , , , , , and related result types.

Connect To A Gateway

Create a client with an explicit Gateway URL, or inject a custom transport for tests and embedded app runtimes.

typescript
Copy
import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({
  url: "ws://127.0.0.1:14565",
  token: process.env.OPENCLAW_GATEWAY_TOKEN,
  requestTimeoutMs: 30_000,
});

await oc.connect();

is equivalent to . The option is accepted by the constructor, but automatic Gateway discovery is not a separate SDK feature yet; pass when the app does not already know how to discover the Gateway.

For tests, pass an object that implements

:

typescript
Copy
const oc = new OpenClaw({
  transport: {
    async request(method, params) {
      return { method, params };
    },
    async *events() {},
  },
});

Run An Agent

Use

when the app wants an agent handle, then call .

typescript
Copy
const agent = await oc.agents.get("main");

const run = await agent.run({
  input: "Review this pull request and suggest the smallest safe fix.",
  model: "openai/gpt-5.5",
  sessionKey: "main",
  timeoutMs: 30_000,
});

for await (const event of run.events()) {
  const data = event.data as { delta?: unknown };
  if (event.type === "assistant.delta" && typeof data.delta === "string") {
    process.stdout.write(data.delta);
  }
}

const result = await run.wait({ timeoutMs: 120_000 });
console.log(result.status);

Provider-qualified model refs such as

are split into Gateway and overrides. stays milliseconds in the SDK and is converted to Gateway timeout seconds for the RPC.

uses the Gateway RPC. A wait deadline that expires while the run is still active returns instead of pretending the run itself timed out. Runtime timeouts, aborted runs, and cancelled runs are normalized into or .

Create And Reuse Sessions

Use sessions when the app wants durable transcript state.

typescript
Copy
const session = await oc.sessions.create({
  agentId: "main",
  label: "release-review",
});

const run = await session.send("Prepare release notes from the current diff.");
await run.wait();

calls and returns a . Session handles also support:

typescript
Copy
await session.abort(run.id);
await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });

Stream Events

The SDK normalizes raw Gateway events into a stable

envelope:

typescript
Copy
type OpenClawEvent = {
  version: 1;
  id: string;
  ts: number;
  type: OpenClawEventType;
  runId?: string;
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  agentId?: string;
  data: unknown;
  raw?: GatewayEvent;
};

Common event types include:

filters events to one run id and replays already-seen events for fast runs. That means the documented flow is safe:

typescript
Copy
const run = await agent.run("Summarize the latest session.");

for await (const event of run.events()) {
  if (event.type === "run.completed") {
    break;
  }
}

For app-wide streams, use

. For raw Gateway frames, use .

Models, Tools, Artifacts, And Approvals

Model helpers map to current Gateway methods:

typescript
Copy
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus

Tool helpers expose the Gateway catalog and effective tool view:

typescript
Copy
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });

Artifact helpers expose the Gateway artifact projection for session, run, or task context. Each call requires one explicit

, , or scope:

typescript
Copy
const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });
const first = artifacts[0];

if (first) {
  const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });
  const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });
  console.log(download.encoding, download.url);
}

Approval helpers use the exec approval RPCs:

typescript
Copy
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });

Explicitly Unsupported Today

The SDK includes names for the product model we want, but it does not silently pretend Gateway RPCs exist. These calls currently throw explicit unsupported errors:

typescript
Copy
await oc.tasks.list();
await oc.tasks.get("task-id");
await oc.tasks.cancel("task-id");

await oc.tools.invoke("tool-name", {});

await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
await oc.environments.delete("environment-id");

Per-run

, , , and fields are typed as future shape, but the current Gateway does not support those overrides on the RPC. If callers pass them, the SDK throws before submitting the run so work does not accidentally execute with default workspace, runtime, environment, or approval behavior.

App SDK Versus Plugin SDK

Use the App SDK when code lives outside OpenClaw:

• Node scripts that start or observe agent runs
• CI jobs that call a Gateway
• dashboards and admin panels
• IDE extensions
• external bridges that do not need to become channel plugins
• integration tests with fake or real Gateway transports

Use the Plugin SDK when code runs inside OpenClaw:

• provider plugins
• channel plugins
• tool or lifecycle hooks
• agent harness plugins
• trusted runtime helpers

App SDK code should import from

. Plugin code should import from documented subpaths. Do not mix the two contracts.

Related Docs

• OpenClaw App SDK API design
• Gateway RPC reference
• Agent loop
• Agent runtimes
• Sessions
• Background tasks
• ACP agents
• Plugin SDK overview