OpenClaw App SDK

概述

OpenClaw App SDK（@openclaw/sdk）是面向 OpenClaw 进程外部应用的公共客户端 API。适用于脚本、仪表盘、CI 任务、IDE 扩展等外部应用，用于连接 Gateway、启动 Agent 运行、流式接收事件、等待结果、取消任务或检查 Gateway 资源。

与 Plugin SDK 的区别：App SDK 从外部与 Gateway 通信；Plugin SDK 仅用于在 OpenClaw 内部运行的插件（注册 provider、channel、tool、hook 等）。

核心要点

主要接口：OpenClaw 客户端、oc.agents、oc.runs、oc.sessions、oc.tasks、oc.models、oc.tools、oc.artifacts、oc.approvals
事件流：Run.events() 过滤到单个 run ID，支持快速运行的事件重放
标准化事件：normalizeGatewayEvent() 将原始 Gateway 事件转为稳定的 OpenClawEvent 信封
模型引用：provider/model 格式（如 openai/gpt-5.5）自动拆分为 Gateway 的 provider 和 model 参数
等待语义：run.wait() 超时返回 status: "accepted" 而非假装 run 超时
工具调用：oc.tools.invoke() 返回类型化信封，不对策略或审批拒绝抛出异常

配置/使用

连接 Gateway：

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();

运行 Agent：

const agent = await oc.agents.get("main");
const run = await agent.run({
  input: "Review this pull request.",
  model: "openai/gpt-5.5",
  sessionKey: "main",
  timeoutMs: 30_000,
});
 
for await (const event of run.events()) {
  if (event.type === "assistant.delta") {
    process.stdout.write(event.data.delta);
  }
}
const result = await run.wait({ timeoutMs: 120_000 });

会话管理：

const session = await oc.sessions.create({ agentId: "main", label: "review" });
const run = await session.send("Prepare release notes.");
await run.wait();

常用事件类型：run.started、run.completed、assistant.delta、tool.call.started、approval.requested、session.created

相关页面

agent-loop — Agent 执行路径
agent-runtimes — 运行时类型
session — 会话管理
streaming — 流式输出机制