古法编程

Appearance

OpenClaw App SDK (@openclaw/sdk) 允许外部应用（脚本、CI 任务、仪表盘、IDE 扩展）通过 WebSocket 连接 Gateway，执行智能体运行、流式事件、创建会话、调用工具及管理工件和审批。快速上手：new OpenClaw({ url: 'ws://127.0.0.1:18789', token: '...' }) 创建客户端，调用 oc.connect() 建立连接，再用 oc.agents.get('main').run() 启动智能体。注意：environments.create 和 delete 当前不可用，会抛出明确错误；workspace、runtime、environment 等参数在 agent RPC 中暂不支持，传递后 SDK 会提前报错，避免误执行。

OpenClaw App SDK 外部应用接入指南 ​

OpenClaw App SDK 是面向 OpenClaw 进程外部应用（脚本、仪表盘、CI 任务、IDE 扩展等）的公开客户端 API。当你需要从外部程序连接 Gateway、启动智能体运行、流式接收事件、等待结果、取消任务或查询 Gateway 资源时，使用 @openclaw/sdk。

INFO

App SDK 与 Plugin SDK 不同：@openclaw/sdk 从 OpenClaw 外部与 Gateway 对话；openclaw/plugin-sdk/* 仅用于在 OpenClaw 内部运行的插件（注册 provider、channel、tool、hook 或 trusted runtime）。

目前已交付的功能 ​

@openclaw/sdk 包含以下能力：

表面状态说明
OpenClawReady主客户端入口，管理传输层、连接、请求和事件
GatewayClientTransportReady基于 Gateway 客户端的 WebSocket 传输
oc.agentsReady列出、创建、更新、删除、获取智能体句柄
Agent.run()Ready启动 Gateway agent 运行，返回一个 Run 对象
oc.runsReady创建、获取、等待、取消和流式读取运行实例
Run.events()Ready流式返回该运行实例的规范化事件，快速运行时重放已看到的事件
Run.wait()Ready调用 agent.wait，返回稳定的 RunResult
Run.cancel()Ready通过 run id 调用 sessions.abort，有 session 键时一并传入
oc.sessionsReady创建、解析、发送、patch、压缩、获取会话句柄
Session.send()Ready调用 sessions.send，返回一个 Run
oc.tasksReady列出、读取、取消 Gateway 任务账本条目
oc.modelsReady调用 models.list 和当前 models.authStatus 状态 RPC
oc.toolsReady列出、作用域内调用、调用 Gateway 工具（通过策略管道）
oc.artifactsReady列出、获取、下载 Gateway 转录工件
oc.approvalsReady列出和解决执行审批（通过 Gateway approval RPCs）
oc.environmentsPartial列出 Gateway 本地和节点环境候选；create / delete 暂未接入
oc.rawEvents()Ready暴露原始 Gateway 事件，供高级消费者使用
normalizeGatewayEvent()Ready将原始 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
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();

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

Provider 限定的模型引用（如 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.startedagent 生命周期开始
run.completedagent 生命周期结束
run.failedagent 生命周期错误
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执行或插件审批请求
approval.resolved执行或插件审批解决
session.createdsessions.changed 创建
session.updatedsessions.changed 更新
session.compactedsessions.changed 压缩
task.updated任务更新事件
artifact.updatedPatch 流事件
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 }); // 调用 models.authStatus

工具助手暴露 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);
}

审批助手使用执行审批 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 会在提交运行之前抛出错误，避免意外使用默认的工作区、运行环境或审批行为来执行任务。

App SDK 与 Plugin SDK 对比 ​

何时使用 App SDK（代码运行在 OpenClaw 外部）：

  • Node 脚本：启动或观测智能体运行
  • CI 任务：调用 Gateway
  • 仪表盘和管理面板
  • IDE 扩展
  • 外部桥接（不需要成为 channel 插件）
  • 集成测试：使用假或真实的 Gateway 传输层

何时使用 Plugin SDK（代码运行在 OpenClaw 内部）：

  • provider 插件
  • channel 插件
  • 工具或生命周期钩子
  • agent harness 插件
  • trusted runtime 助手

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

相关文档 ​

常见问题 ​

OpenClaw App SDK 和 Plugin SDK 有什么区别？ ​

App SDK (@openclaw/sdk) 用于外部程序访问 Gateway，脚本、CI 或仪表盘场景；Plugin SDK 用于在 OpenClaw 内部编写插件（注册 provider、channel、tool 等）。两者不互通，不要混用。

如何使用 App SDK 运行一个智能体并获取流式输出？ ​

创建 OpenClaw 客户端并连接：new OpenClaw({ url: 'ws://...', token })，然后 const agent = await oc.agents.get('main')，调用 agent.run({ input: '...' }) 返回一个 Run 对象，通过 for await (const event of run.events()) 流式读取事件，判断 event.type === 'assistant.delta' 获取增量内容。

App SDK 支持哪些事件类型？如何监听应用级别事件？ ​

所有事件类型见上文表格，包括 run.started、assistant.delta、tool.call.completed 等。使用 run.events() 监听单个运行事件；使用 oc.events() 监听应用级别的事件流；使用 oc.rawEvents() 获取原始 Gateway 帧。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策