快速开始

OpenClaw 应用 SDK

OpenClaw 应用 SDK 是面向 OpenClaw 进程外应用的公开客户端 API。当脚本、仪表板、CI 作业、IDE 扩展或其他外部应用需要连接到 Gateway 网关、启动智能体运行、流式传输事件、等待结果、取消工作或检查 Gateway 网关资源时，请使用 @openclaw/sdk。

当前提供的内容

@openclaw/sdk 提供：

表面	Status	作用
`OpenClaw`	就绪	主客户端入口点。负责传输、连接、请求和事件。
`GatewayClientTransport`	就绪	由 Gateway 网关客户端支持的 WebSocket 传输。
`oc.agents`	就绪	列出、创建、更新、删除并获取智能体句柄。
`Agent.run()`	就绪	启动 Gateway 网关 `agent` 运行并返回一个 `Run`。
`oc.runs`	就绪	创建、获取、等待、取消并流式传输运行。
`Run.events()`	就绪	使用重放机制为快速运行流式传输规范化的单次运行事件。
`Run.wait()`	就绪	调用 `agent.wait` 并返回稳定的 `RunResult`。
`Run.cancel()`	就绪	按运行 ID 调用 `sessions.abort`，可用时带上会话键。
`oc.sessions`	就绪	创建、解析、发送到、修补、压缩并获取会话句柄。
`Session.send()`	就绪	调用 `sessions.send` 并返回一个 `Run`。
`oc.tasks`	就绪	列出、读取并取消 Gateway 网关任务账本条目。
`oc.models`	就绪	调用 `models.list` 和当前的 `models.authStatus` 状态 RPC。
`oc.tools`	就绪	通过策略管线列出、限定作用域并调用 Gateway 网关工具。
`oc.artifacts`	就绪	列出、获取并下载 Gateway 网关转录产物。
`oc.approvals`	就绪	通过 Gateway 网关审批 RPC 列出并处理 exec 审批。
`oc.environments`	部分支持	列出 Gateway 网关本地和节点环境候选项；创建/删除尚未接线。
`oc.rawEvents()`	就绪	为高级消费者暴露原始 Gateway 网关事件。
`normalizeGatewayEvent()`	就绪	将原始 Gateway 网关事件转换为稳定的 SDK 事件形状。

SDK 还导出这些表面使用的核心类型： AgentRunParams、RunResult、RunStatus、OpenClawEvent、OpenClawEventType、GatewayEvent、OpenClawTransport、GatewayRequestOptions、SessionCreateParams、SessionSendParams、ArtifactSummary、ArtifactQuery、ArtifactsListResult、ArtifactsGetResult、ArtifactsDownloadResult、TaskSummary、TaskStatus、TasksListParams、TasksListResult、TasksGetResult、TasksCancelResult、RuntimeSelection、EnvironmentSelection、WorkspaceSelection、ApprovalMode 以及相关结果类型。

连接到 Gateway 网关

使用显式 Gateway 网关 URL 创建客户端，或为测试和嵌入式应用运行时注入自定义传输。

typescript

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

new OpenClaw({ gateway: "ws://..." }) 等同于 url。构造函数接受 gateway: "auto" 选项，但自动 Gateway 网关发现目前还不是独立的 SDK 功能；当应用还不知道如何发现 Gateway 网关时，请传入 url。

对于测试，请传入实现 OpenClawTransport 的对象：

typescript

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

运行智能体

当应用需要智能体句柄时，使用 oc.agents.get(id)，然后调用 agent.run()。

typescript

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

像 openai/gpt-5.5 这样的提供商限定模型引用会拆分为 Gateway 网关的 provider 和 model 覆盖项。timeoutMs 在 SDK 中保持为毫秒，并会转换为 agent RPC 的 Gateway 网关超时秒数。

run.wait() 使用 Gateway 网关的 agent.wait RPC。如果等待截止时间到期时运行仍处于活动状态，会返回 status: "accepted"，而不是假装运行本身已超时。运行时超时、中止的运行和取消的运行会规范化为 timed_out 或 cancelled。

创建并复用会话

当应用需要持久转录状态时使用会话。

typescript

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

Session.send() 调用 sessions.send 并返回一个 Run。会话句柄还支持：

typescript

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

流式传输事件

SDK 将原始 Gateway 网关事件规范化为稳定的 OpenClawEvent 信封：

typescript

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

常见事件类型包括：

事件类型	来源 Gateway 网关事件
`run.started`	`agent` 生命周期开始
`run.completed`	`agent` 生命周期结束
`run.failed`	`agent` 生命周期错误
`run.cancelled`	中止/取消的生命周期结束
`run.timed_out`	超时生命周期结束
`assistant.delta`	助手流式增量
`assistant.message`	助手消息
`thinking.delta`	思考或计划流
`tool.call.started`	工具/项目/命令开始
`tool.call.delta`	工具/项目/命令更新
`tool.call.completed`	工具/项目/命令完成
`tool.call.failed`	工具/项目/命令失败或被阻止状态
`approval.requested`	Exec 或插件审批请求
`approval.resolved`	Exec 或插件审批处理结果
`session.created`	`sessions.changed` 创建
`session.updated`	`sessions.changed` 更新
`session.compacted`	`sessions.changed` 压缩
`task.updated`	任务更新事件
`artifact.updated`	补丁流事件
`raw`	尚无稳定 SDK 映射的任何事件

Run.events() 会将事件过滤到一个运行 ID，并为快速运行重放已经看到的事件。这意味着文档中的流程是安全的：

typescript

const run = await agent.run("Summarize the latest session."); for await (const event of run.events()) {  if (event.type === "run.completed") {    break;  }}

对于应用级流，请使用 oc.events()。对于原始 Gateway 网关帧，请使用 oc.rawEvents()。

模型、工具、产物和审批

模型辅助方法映射到当前 Gateway 网关方法：

typescript

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

工具辅助方法暴露 Gateway 网关目录、有效工具视图和直接 Gateway 网关工具调用。oc.tools.invoke() 会返回一个类型化信封，而不是因策略或审批拒绝而抛出异常。

typescript

await oc.tools.list();await oc.tools.effective({ sessionKey: "main" });await oc.tools.invoke("tool-name", {  args: { input: "value" },  sessionKey: "main",  confirm: false,  idempotencyKey: "tool-call-1",});

产物辅助方法为会话、运行或任务上下文暴露 Gateway 网关产物投影。每次调用都需要一个显式的 sessionKey、runId 或 taskId 作用域：

typescript

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

审批辅助方法使用 exec 审批 RPC：

typescript

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

任务辅助方法使用也支撑 openclaw tasks 的持久任务账本：

typescript

const tasks = await oc.tasks.list({ status: "running", sessionKey: "agent:main:main" });const task = await oc.tasks.get(tasks.tasks[0].id);await oc.tasks.cancel(task.task.id, { reason: "user stopped task" });

环境辅助方法暴露只读的 Gateway 网关本地和节点发现：

typescript

const { environments } = await oc.environments.list();await oc.environments.status(environments[0].id);

当前明确不支持

SDK 包含我们期望的产品模型名称，但它不会静默假装 Gateway 网关 RPC 存在。这些调用目前会抛出明确的不支持错误：

typescript

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

每次运行的 workspace、runtime、environment 和 approvals 字段被类型化为未来形状，但当前 Gateway 网关不支持在 agent RPC 上使用这些覆盖项。如果调用方传入这些字段，SDK 会在提交运行前抛出异常，确保工作不会意外使用默认工作区、运行时、环境或审批行为执行。

应用 SDK 与插件 SDK

当代码位于 OpenClaw 外部时，使用应用 SDK：

启动或观察智能体运行的 Node 脚本
调用 Gateway 网关的 CI 作业
仪表板和管理面板
IDE 扩展
不需要成为渠道插件的外部桥接
使用虚假或真实 Gateway 网关传输的集成测试

当代码在 OpenClaw 内部运行时，使用插件 SDK：

提供商插件
渠道插件
工具或生命周期钩子
Agent harness plugins
可信运行时辅助方法

应用 SDK 代码应从 @openclaw/sdk 导入。插件代码应从文档化的 openclaw/plugin-sdk/* 子路径导入。不要混用这两套契约。