OpenClaw App SDK

Most beginners hit the same fork in the road. They want to connect something new to OpenClaw, and suddenly every option sounds similar: App SDK, Plugin SDK, MCP, CLI, raw Gateway calls. That is where wasted weekends begin.

The short version is simple. Use the OpenClaw App SDK when your code lives outside OpenClaw and needs a safe, typed way to talk to the Gateway. Think dashboards, CI jobs, IDE helpers, review bots, and internal tools. If your code needs to live inside OpenClaw and register new native capabilities, that is Plugin SDK work instead.

What the App SDK is actually for

The official OpenClaw App SDK docs describe @openclaw/sdk as the public client API for apps outside the OpenClaw process. It is built for software that wants to connect to the Gateway, start runs, stream events, wait for results, cancel work, inspect resources, and handle approvals without pretending to be a plugin.

A good mental model: the App SDK is a remote control, not a screwdriver. You are operating the system from outside. You are not opening the case and adding new circuits.

App SDK vs Plugin SDK

The Plugin SDK overview makes the split explicit: plugin subpaths are for in-process extension authors, while external apps should use the App SDK. That separation is healthy. It keeps app builders from accidentally owning runtime internals they never wanted in the first place.

What ships today

This is the part that matters if you are deciding whether to build now or wait. The App SDK is not just a placeholder package. The official docs list a solid working surface already.

• Client connection: OpenClaw plus Gateway transport
• Agent runs: start runs, wait for them, cancel them, and stream their events
• Sessions: create, resolve, send, patch, and compact durable conversations
• Tools: list effective tools and invoke them through policy gates
• Tasks and artifacts: inspect background work and download outputs
• Approvals: list and resolve exec approval requests
• Models: inspect model inventory and auth status
• Environment helpers: partially available, not the finished story yet

In other words, the useful middle of the product is there already. You can build real control surfaces today without dropping straight into raw WebSocket plumbing.

The shape of a simple external app

A minimal app usually does four things: connect, get an agent or session, start work, and stream or wait for the result. That is pleasantly boring, which is exactly what you want in integration code.

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

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

await oc.connect();

const agent = await oc.agents.get("main");
const run = await agent.run({
  input: "Review this deploy plan and flag the risky step.",
  sessionKey: "main",
  timeoutMs: 30_000,
});

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

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

That is enough for a surprisingly large class of tools. If you can start a run, reuse a session, and react to normalized events, you can build more than a toy.

Good real-world app ideas

This is where the App SDK starts to click. You do not need a grand platform strategy. You need one useful external surface.

• Review dashboard: trigger runs against selected sessions, then show artifacts and approval state in one UI.
• CI release assistant: send release diffs to an agent, wait for a result, and fail the pipeline if a required checklist is missing.
• IDE side panel: let developers push focused prompts into a named session instead of losing everything in disposable chats.
• Ops console: inspect running tasks, view stuck approvals, and cancel work without logging into the host box.
• Internal request form: collect structured business inputs from teammates, then hand them to OpenClaw through a durable session.

Notice the pattern. These apps do not replace OpenClaw. They give one group of users a narrower, cleaner doorway into it.

Why the event model matters more than people think

A lot of homegrown integrations stop at request in, text out. That works until you need progress, approvals, cancellation, or artifacts. Then the whole thing feels like a blindfold.

The App SDK design fixes that with normalized events like run starts, assistant deltas, tool-call updates, approval requests, and task changes. That matters because external apps usually fail on visibility, not on raw connectivity. A dashboard that can explain what the agent is doing is worth much more than one that only shows a final paragraph after two minutes of silence.

When the App SDK is better than raw Gateway calls

Could you speak to the Gateway directly? Sure. But that is like choosing raw SQL for every tiny list page. Sometimes it is justified. Often it is just self-inflicted friction.

• Use the App SDK when you want typed objects, stable flows, normalized events, and less glue code.
• Use raw Gateway calls when you are debugging protocol details or building something the high-level wrapper does not expose yet.
• Use the Plugin SDK when you need to register new runtime capability rather than consume existing capability.

Where people choose the wrong tool

They reach for a plugin too early

If your real goal is “I want a web app that can launch runs and show status,” a plugin is often overkill. You do not need to move into the engine room just to press the starter button.

They build a pile of scripts with no session model

The docs make sessions first-class for a reason. If your external app needs continuity, use sessions instead of treating every call as a disposable one-shot. Otherwise your “app” becomes a fancy wrapper around amnesia.

They ignore approvals and artifact handling

Coding and operations flows regularly cross safety boundaries. The App SDK already has approval and artifact surfaces. Pretending those do not exist just means you will rebuild worse versions later.

Practical decision rule

Ask one blunt question: does this code need to extend OpenClaw, or does it need to drive OpenClaw?

• Extend it → Plugin SDK
• Drive it → App SDK

That simple split saves a lot of architecture theater.