Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw 应用 SDK 是面向 OpenClaw 进程外应用的公开客户端 API。当脚本、仪表板、CI 作业、IDE 扩展或其他外部应用需要连接到 Gateway 网关、启动智能体运行、流式传输事件、等待结果、取消工作或检查 Gateway 网关资源时，请使用 @openclaw/sdk。
应用 SDK 不同于 插件 SDK。 @openclaw/sdk 从 OpenClaw 外部与 Gateway 网关通信。 openclaw/plugin-sdk/* 仅用于在 OpenClaw 内部运行并注册提供商、渠道、工具、钩子或可信运行时的插件。

​
当前提供的内容

@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 创建客户端，或为测试和嵌入式应用运行时注入自定义传输。 
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 的对象： 
const oc = new OpenClaw({
  transport: {
    async request(method, params) {
      return { method, params };
    },
    async *events() {},
  },
});

​
运行智能体

当应用需要智能体句柄时，使用 oc.agents.get(id)，然后调用 agent.run()。 
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。

​
创建并复用会话

当应用需要持久转录状态时使用会话。 
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。会话句柄还支持： 
await session.abort(run.id);
await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });

​
流式传输事件

SDK 将原始 Gateway 网关事件规范化为稳定的 OpenClawEvent 信封： 
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.requestedExec 或插件审批请求
approval.resolvedExec 或插件审批处理结果
session.createdsessions.changed 创建
session.updatedsessions.changed 更新
session.compactedsessions.changed 压缩
task.updated任务更新事件
artifact.updated补丁流事件
raw尚无稳定 SDK 映射的任何事件
Run.events() 会将事件过滤到一个运行 ID，并为快速运行重放已经看到的事件。这意味着文档中的流程是安全的： 
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 网关方法： 
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
工具辅助方法暴露 Gateway 网关目录、有效工具视图和直接 Gateway 网关工具调用。oc.tools.invoke() 会返回一个类型化信封，而不是因策略或审批拒绝而抛出异常。 
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 作用域： 
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： 
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });
任务辅助方法使用也支撑 openclaw tasks 的持久任务账本： 
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 网关本地和节点发现： 
const { environments } = await oc.environments.list();
await oc.environments.status(environments[0].id);

​
当前明确不支持

SDK 包含我们期望的产品模型名称，但它不会静默假装 Gateway 网关 RPC 存在。这些调用目前会抛出明确的不支持错误： 
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/* 子路径导入。不要混用这两套契约。

​
相关