OpenClaw App SDK API design

This page is the detailed API reference design for the public OpenClaw App SDK. It is intentionally separate from the Plugin SDK.

The public app SDK should be built in two layers:

1. A low-level generated Gateway client.
2. A high-level ergonomic wrapper with
   text

   Copy

   OpenClaw
   ,
   text

   Copy

   Agent
   ,
   text

   Copy

   Session
   ,
   text

   Copy

   Run
   ,
   text

   Copy

   Task
   ,
   text

   Copy

   Artifact
   ,
   text

   Copy

   Approval
   , and
   text

   Copy

   Environment
   objects.

Namespace design

The low-level namespaces should closely follow Gateway resources:

typescript
Copy
oc.agents.list();
oc.agents.get("main");
oc.agents.create(...);
oc.agents.update(...);

oc.sessions.list();
oc.sessions.create(...);
oc.sessions.resolve(...);
oc.sessions.send(...);
oc.sessions.messages(...);
oc.sessions.fork(...);
oc.sessions.compact(...);
oc.sessions.abort(...);

oc.runs.create(...);
oc.runs.get(runId);
oc.runs.events(runId, { after });
oc.runs.wait(runId);
oc.runs.cancel(runId);

oc.tasks.list(); // future API: current SDK throws unsupported
oc.tasks.get(taskId); // future API: current SDK throws unsupported
oc.tasks.cancel(taskId); // future API: current SDK throws unsupported
oc.tasks.events(taskId, { after }); // future API

oc.models.list();
oc.models.status(); // Gateway models.authStatus

oc.tools.list();
oc.tools.invoke(...); // future API: current SDK throws unsupported

oc.artifacts.list({ runId }); // future API: current SDK throws unsupported
oc.artifacts.get(artifactId); // future API: current SDK throws unsupported
oc.artifacts.download(artifactId); // future API: current SDK throws unsupported

oc.approvals.list();
oc.approvals.respond(approvalId, ...);

oc.environments.list(); // future API: current SDK throws unsupported
oc.environments.create(...); // future API: current SDK throws unsupported
oc.environments.status(environmentId); // future API: current SDK throws unsupported
oc.environments.delete(environmentId); // future API: current SDK throws unsupported

High-level wrappers should return objects that make common flows pleasant:

typescript
Copy
const run = await agent.run(inputOrParams);
await run.cancel();
await run.wait();

for await (const event of run.events()) {
  // normalized event stream
}

const artifacts = await run.artifacts.list();
const session = await run.session();

Event contract

The public SDK should expose versioned, replayable, normalized events.

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?: unknown;
};

is a replay cursor. Consumers should be able to reconnect with and receive missed events when retention allows.

Recommended normalized event families:

Runtime-native payloads should be available through

, but apps should not have to parse for normal UI.

Result contract

should return a stable result envelope:

typescript
Copy
type RunResult = {
  runId: string;
  status: "accepted" | "completed" | "failed" | "cancelled" | "timed_out";
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  startedAt?: string | number;
  endedAt?: string | number;
  output?: {
    text?: string;
    messages?: SDKMessage[];
  };
  usage?: {
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
    costUsd?: number;
  };
  artifacts?: ArtifactSummary[];
  error?: SDKError;
};

The result should be boring and stable. Timestamp values preserve the Gateway shape, so current lifecycle-backed runs usually report epoch millisecond numbers while adapters may still surface ISO strings. Rich UI, tool traces, and runtime-native details belong in events and artifacts.

is a non-terminal wait result: it means the Gateway wait deadline expired before the run produced a lifecycle end/error. It must not be treated as ; is reserved for a run that exceeded its own runtime timeout.

Approvals and questions

Approvals must be first-class because coding agents constantly cross safety boundaries.

typescript
Copy
run.onApproval(async (request) => {
  if (request.kind === "tool" && request.toolName === "exec") {
    return request.approveOnce({ reason: "CI command allowed by policy" });
  }

  return request.askUser();
});

Approval events should carry:

• approval id
• run id and session id
• request kind
• requested action summary
• tool name or environment action
• risk level
• available decisions
• expiration
• whether the decision can be reused

Questions are separate from approvals. A question asks the user or host app for information. An approval asks for permission to perform an action.

ToolSpace model

Apps need to understand the tool surface without importing plugin internals.

typescript
Copy
const tools = await run.toolSpace();

for (const tool of tools.list()) {
  console.log(tool.name, tool.source, tool.requiresApproval);
}

The SDK should expose:

• normalized tool metadata
• source: OpenClaw, MCP, plugin, channel, runtime, or app
• schema summary
• approval policy
• runtime compatibility
• whether a tool is hidden, readonly, write capable, or host capable

Tool invocation through the SDK should be explicit and scoped. Most apps should run agents, not call arbitrary tools directly.

Artifact model

Artifacts should cover more than files.

typescript
Copy
type ArtifactSummary = {
  id: string;
  runId?: string;
  sessionId?: string;
  type:
    | "file"
    | "patch"
    | "diff"
    | "log"
    | "media"
    | "screenshot"
    | "trajectory"
    | "pull_request"
    | "workspace";
  title?: string;
  mimeType?: string;
  sizeBytes?: number;
  createdAt: string;
  expiresAt?: string;
};

Common examples:

• file edits and generated files
• patch bundles
• VCS diffs
• screenshots and media outputs
• logs and trace bundles
• pull request links
• runtime trajectories
• managed environment workspace snapshots

Artifact access should support redaction, retention, and download URLs without assuming every artifact is a normal local file.

Security model

The app SDK must be explicit about authority.

Recommended token scopes:

Defaults:

• no secret forwarding by default
• no unrestricted environment variable pass-through
• secret references instead of secret values
• explicit sandbox and network policy
• explicit remote environment retention
• approvals for host execution unless policy proves otherwise
• raw runtime events redacted before they leave Gateway unless the caller has a stronger diagnostic scope

Managed environment provider

Managed agents should be implemented as environment providers.

typescript
Copy
type EnvironmentProvider = {
  id: string;
  capabilities: {
    checkout?: boolean;
    sandbox?: boolean;
    networkPolicy?: boolean;
    secrets?: boolean;
    artifacts?: boolean;
    logs?: boolean;
    pullRequests?: boolean;
    longRunning?: boolean;
  };
};

The first implementation does not need to be a hosted SaaS. It can target existing node hosts, ephemeral workspaces, CI-style runners, or Testbox-style environments. The important contract is:

1. prepare workspace
2. bind safe environment and secrets
3. start run
4. stream events
5. collect artifacts
6. clean up or retain by policy

Once this is stable, a hosted cloud service can implement the same provider contract.

Package structure

Recommended packages:

The repo already has

for plugins. Keep that namespace separate to avoid confusing plugin authors with app developers.

Generated client strategy

The low-level client should be generated from versioned Gateway protocol schemas, then wrapped by handwritten ergonomic classes.

Layering:

1. Gateway schema source of truth.
2. Generated low-level TypeScript client.
3. Runtime validators for external inputs and event payloads.
4. High-level
   text

   Copy

   OpenClaw
   ,
   text

   Copy

   Agent
   ,
   text

   Copy

   Session
   ,
   text

   Copy

   Run
   ,
   text

   Copy

   Task
   , and
   text

   Copy

   Artifact
   wrappers.
5. Cookbook examples and integration tests.

Benefits:

• protocol drift is visible
• tests can compare generated methods with Gateway exports
• App SDK stays independent from Plugin SDK internals
• low-level consumers still have full protocol access
• high-level consumers get the small product API

Related docs

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