OpenClaw App SDK

先听这页的人话版

这一页不是在堆术语，它像把“OpenClaw App SDK”这台小机器搬到桌上，当着你的面拆开给你看。你先不用全记住，先抓住它到底在忙什么：The **OpenClaw App SDK** is the public 来帮忙的小伙伴对话接口 for apps outside the OpenClaw process. Use…。

如果把这页当成“给普通人看的版本”，你最应该带走的是：它到底在教你一件什么事、什么时候要这样做、以及哪里最容易踩坑。

原始路径：/concepts/openclaw-sdk 章节数量：10 查看原文

第 1 站

Start Here

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

这段在解决什么

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

为什么值得看

你理解的是能力边界，不只是功能名字。

真要动手时

如果这节里同时出现命令、配置和例子，优先先看例子，再回头看配置。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The **OpenClaw App SDK** is the public 来帮忙的小伙伴对话接口 for apps outside the OpenClaw process. Use @openclaw/sdk when a scr…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The **OpenClaw App SDK** is the public 来帮忙的小伙伴对话接口 for apps outside the OpenClaw process. Use @openclaw/sdk when a scr…。

原文小纸条

The **OpenClaw App SDK** is the public client API for apps outside the OpenClaw process. Use @openclaw/sdk when a script, dashboard, CI job, IDE extension, or other external app wants to connect to the Gateway, start agent runs, stream events, wait for results, cancel work, or inspect Gateway resources.

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Note。

原文小纸条

Note

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The App SDK is different from the 新本领插件 SDK. @openclaw/sdk talks to the 门口的小门卫 from outside OpenClaw. openclaw/新本领插件-sd…。

原文小纸条

The App SDK is different from the Plugin SDK. @openclaw/sdk talks to the Gateway from outside OpenClaw. openclaw/plugin-sdk/* is only for plugins that run inside OpenClaw and register providers, channels, tools, hooks, or trusted runtimes.

第 2 站

What ships today

这一节主要在解释“What ships today”到底是干什么的，以及你什么时候会遇到它。

这段在解决什么

这一节主要在解释“What ships today”到底是干什么的，以及你什么时候会遇到它。

为什么值得看

如果你是第一次接触 OpenClaw，这一节最值得看的不是术语本身，而是它背后的使用场景和限制。

真要动手时

真正动手时，先看它有没有默认值、有没有必须打开的选项、以及会不会影响安全边界。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：@openclaw/sdk ships with: The SDK also exports the core types used by those surfaces: 机器人朋友RunParams, RunResult, RunSta…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：@openclaw/sdk ships with:。

原文小纸条

@openclaw/sdk ships with:

像整理表格

这段是在把几种选项排成表格，左边像标签，右边像说明。手机上可以横向滑动原文表格。

原文表格

Surface	Status	What it does
`OpenClaw`	Ready	Main client entry point. Owns transport, connection, requests, and events.
`GatewayClientTransport`	Ready	WebSocket transport backed by the Gateway client.
`oc.agents`	Ready	Lists, creates, updates, deletes, and gets agent handles.
`Agent.run()`	Ready	Starts a Gateway `agent` run and returns a `Run`.
`oc.runs`	Ready	Creates, gets, waits for, cancels, and streams runs.
`Run.events()`	Ready	Streams normalized per-run events with replay for fast runs.
`Run.wait()`	Ready	Calls `agent.wait` and returns a stable `RunResult`.
`Run.cancel()`	Ready	Calls `sessions.abort` by run id, with session key when available.
`oc.sessions`	Ready	Creates, resolves, sends to, patches, compacts, and gets session handles.
`Session.send()`	Ready	Calls `sessions.send` and returns a `Run`.
`oc.tasks`	Ready	Lists, reads, and cancels Gateway task ledger entries.
`oc.models`	Ready	Calls `models.list` and the current `models.authStatus` status RPC.
`oc.tools`	Ready	Lists, scopes, and invokes Gateway tools through the policy pipeline.
`oc.artifacts`	Ready	Lists, gets, and downloads Gateway transcript artifacts.
`oc.approvals`	Ready	Lists and resolves exec approvals through Gateway approval RPCs.
`oc.environments`	Partial	Lists Gateway-local and node environment candidates; create/delete are not wired.
`oc.rawEvents()`	Ready	Exposes raw Gateway events for advanced consumers.
`normalizeGatewayEvent()`	Ready	Converts raw Gateway events into the stable SDK event shape.

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The SDK also exports the core types used by those surfaces: 机器人朋友RunParams, RunResult, RunStatus, OpenClawEvent, OpenCl…。

原文小纸条

The SDK also exports the core types used by those surfaces: 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, and related result types.

第 3 站

Connect to a 门口的小门卫

这一节主要在解释“Connect to a 门口的小门卫”到底是干什么的，以及你什么时候会遇到它。

这段在解决什么

这一节主要在解释“Connect to a 门口的小门卫”到底是干什么的，以及你什么时候会遇到它。

为什么值得看

如果你是第一次接触 OpenClaw，这一节最值得看的不是术语本身，而是它背后的使用场景和限制。

真要动手时

真正动手时，先看它有没有默认值、有没有必须打开的选项、以及会不会影响安全边界。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Create a 来帮忙的小伙伴 with an explicit 门口的小门卫 URL, or inject a custom transport for tests and embedded app runtimes. new Ope…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Create a 来帮忙的小伙伴 with an explicit 门口的小门卫 URL, or inject a custom transport for tests and embedded app runtimes.

原文小纸条

Create a client with an explicit Gateway URL, or inject a custom transport for tests and embedded app runtimes.

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“const oc = new OpenClaw({”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这里在给“url”挂牌子，告诉系统它该指向“ws://127.0.0.1:18789”。
这里在给“token”挂牌子，告诉系统它该指向“process.env.OPENCLAW_GATEWAY_TOKEN”。

原文代码块


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({ 门口的小门卫: "ws://..." }) is equivalent to url. The 门口的小门卫: "auto" option is accepted by the constructor, bu…。

原文小纸条

new OpenClaw({ gateway: "ws://..." }) is equivalent to url. The gateway: "auto" option is accepted by the constructor, but automatic Gateway discovery is not a separate SDK feature yet; pass url when the app does not already know how to discover the Gateway.

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：For tests, pass an object that implements OpenClawTransport:。

原文小纸条

For tests, pass an object that implements OpenClawTransport:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“const oc = new OpenClaw({”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这里在给“transport”挂牌子，告诉系统它该指向“{”。
这一行“async request(method, params) {”是在给电脑递一张小纸条，告诉它眼下该做哪一步。

原文代码块

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

第 4 站

Run an 机器人朋友

这一节主要在解释“Run an 机器人朋友”到底是干什么的，以及你什么时候会遇到它。

这段在解决什么

这一节主要在解释“Run an 机器人朋友”到底是干什么的，以及你什么时候会遇到它。

为什么值得看

如果你是第一次接触 OpenClaw，这一节最值得看的不是术语本身，而是它背后的使用场景和限制。

真要动手时

真正动手时，先看它有没有默认值、有没有必须打开的选项、以及会不会影响安全边界。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use oc.机器人朋友s.get(id) when the app wants an 机器人朋友 handle, then call 机器人朋友.run(). Provider-qualified 聪明脑袋模型 refs such as…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use oc.机器人朋友s.get(id) when the app wants an 机器人朋友 handle, then call 机器人朋友.run().

原文小纸条

Use oc.agents.get(id) when the app wants an agent handle, then call 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.”。

原文代码块

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-qualified 聪明脑袋模型 refs such as openai/gpt-5.5 are split into 门口的小门卫 provider and 聪明脑袋模型 overrides. timeoutMs st…。

原文小纸条

Provider-qualified model refs such as openai/gpt-5.5 are split into Gateway provider and model overrides. timeoutMs stays milliseconds in the SDK and is converted to Gateway timeout seconds for the agent RPC.

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：run.wait() uses the 门口的小门卫机器人朋友.wait RPC. A wait deadline that expires while the run is still active returns status: "…。

原文小纸条

run.wait() uses the Gateway agent.wait RPC. A wait deadline that expires while the run is still active returns status: "accepted" instead of pretending the run itself timed out. Runtime timeouts, aborted runs, and cancelled runs are normalized into timed_out or cancelled.

第 5 站

Create and reuse sessions

这一节主要在解释“Create and reuse sessions”到底是干什么的，以及你什么时候会遇到它。

这段在解决什么

这一节主要在解释“Create and reuse sessions”到底是干什么的，以及你什么时候会遇到它。

为什么值得看

如果你是第一次接触 OpenClaw，这一节最值得看的不是术语本身，而是它背后的使用场景和限制。

真要动手时

真正动手时，先看它有没有默认值、有没有必须打开的选项、以及会不会影响安全边界。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use sessions when the app wants durable transcript state. Session.send() calls sessions.send and returns a Run. Session…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use sessions when the app wants durable transcript state.

原文小纸条

Use sessions when the app wants durable transcript state.

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“const session = await oc.sessions.create({”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这里在给“agentId”挂牌子，告诉系统它该指向“main”。
这里在给“label”挂牌子，告诉系统它该指向“release-review”。

原文代码块

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() calls sessions.send and returns a Run. Session handles also support:。

原文小纸条

Session.send() calls sessions.send and returns a Run. Session handles also support:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“await session.abort(run.id);”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这里在给“await session.patch({ label”挂牌子，告诉系统它该指向“renamed-session });”。
这里在给“await session.compact({ maxLines”挂牌子，告诉系统它该指向“200 });”。

原文代码块

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

第 6 站

一边说一边送 events

这一节主要在解释“一边说一边送 events”到底是干什么的，以及你什么时候会遇到它。

这段在解决什么

这一节主要在解释“一边说一边送 events”到底是干什么的，以及你什么时候会遇到它。

为什么值得看

如果你是第一次接触 OpenClaw，这一节最值得看的不是术语本身，而是它背后的使用场景和限制。

真要动手时

真正动手时，先看它有没有默认值、有没有必须打开的选项、以及会不会影响安全边界。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The SDK normalizes raw 门口的小门卫 events into a stable OpenClawEvent envelope: Common event types include: Run.events() fil…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The SDK normalizes raw 门口的小门卫 events into a stable OpenClawEvent envelope:。

原文小纸条

The SDK normalizes raw Gateway events into a stable OpenClawEvent envelope:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“type OpenClawEvent = {”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这里在给“version”挂牌子，告诉系统它该指向“1;”。
这里在给“id”挂牌子，告诉系统它该指向“string;”。

原文代码块

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

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Common event types include:。

原文小纸条

Common event types include:

像整理表格

这段是在把几种选项排成表格，左边像标签，右边像说明。手机上可以横向滑动原文表格。

原文表格

Event type	Source Gateway event
`run.started`	`agent` lifecycle start
`run.completed`	`agent` lifecycle end
`run.failed`	`agent` lifecycle error
`run.cancelled`	Aborted/cancelled lifecycle end
`run.timed_out`	Timeout lifecycle end
`assistant.delta`	Assistant streaming delta
`assistant.message`	Assistant message
`thinking.delta`	Thinking or plan stream
`tool.call.started`	Tool/item/command start
`tool.call.delta`	Tool/item/command update
`tool.call.completed`	Tool/item/command completion
`tool.call.failed`	Tool/item/command failure or blocked status
`approval.requested`	Exec or plugin approval request
`approval.resolved`	Exec or plugin approval resolution
`session.created`	`sessions.changed` create
`session.updated`	`sessions.changed` update
`session.compacted`	`sessions.changed` compaction
`task.updated`	Task update events
`artifact.updated`	Patch stream events
`raw`	Any event without a stable SDK mapping yet

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Run.events() filters events to one run id and replays already-seen events for fast runs. That means the documented flow…。

原文小纸条

Run.events() filters events to one run id and replays already-seen events for fast runs. That means the documented flow is safe:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“const run = await agent.run("Summarize the latest session.");”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这一行“for await (const event of run.events()) {”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这一行“if (event.type === "run.completed") {”是在给电脑递一张小纸条，告诉它眼下该做哪一步。

原文代码块

const run = await agent.run("Summarize the latest session.");

for await (const event of run.events()) {
  if (event.type === "run.completed") {
    break;
  }
}

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：For app-wide 一边说一边送s, use oc.events(). For raw 门口的小门卫 frames, use oc.rawEvents().

原文小纸条

For app-wide streams, use oc.events(). For raw Gateway frames, use oc.rawEvents().

第 7 站

聪明脑袋模型s, 工具小帮手s, artifacts, and approvals

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

这段在解决什么

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

为什么值得看

这种内容决定了 OpenClaw 是“能做”还是“现在还不能做”，读懂它比记术语更重要。

真要动手时

你可以把这一节当成权限说明书，真正配置时优先盯住 default、required、allow、deny 这几个词。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：聪明脑袋模型 helpers map to current 门口的小门卫 methods: 工具小帮手 helpers expose the 门口的小门卫 catalog, effective 工具小帮手 view, and direct…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：聪明脑袋模型 helpers map to current 门口的小门卫 methods:。

原文小纸条

Model helpers map to current Gateway methods:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“await oc.models.list();”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这里在给“await oc.models.status({ probe”挂牌子，告诉系统它该指向“false }); // calls models.authStatus”。

原文代码块

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

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：工具小帮手 helpers expose the 门口的小门卫 catalog, effective 工具小帮手 view, and direct 门口的小门卫工具小帮手 invocation. oc.工具小帮手s.invoke() r…。

原文小纸条

Tool helpers expose the Gateway catalog, effective tool view, and direct Gateway tool invocation. oc.tools.invoke() returns a typed envelope instead of throwing for policy or approval refusals.

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“await oc.tools.list();”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这里在给“await oc.tools.effective({ sessionKey”挂牌子，告诉系统它该指向“main });”。
这一行“await oc.tools.invoke("tool-name", {”是在给电脑递一张小纸条，告诉它眼下该做哪一步。

原文代码块

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

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Artifact helpers expose the 门口的小门卫 artifact projection for session, run, or task context. Each call requires one explic…。

原文小纸条

Artifact helpers expose the Gateway artifact projection for session, run, or task context. Each call requires one explicit sessionKey, runId, or taskId scope:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这里在给“const { artifacts } = await oc.artifacts.list({ sessionKey”挂牌子，告诉系统它该指向“main });”。
这一行“const first = artifacts[0];”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这一行“if (first) {”是在给电脑递一张小纸条，告诉它眼下该做哪一步。

原文代码块

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

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Approval helpers use the exec approval RPCs:。

原文小纸条

Approval helpers use the exec approval RPCs:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“const approvals = await oc.approvals.list();”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这里在给“await oc.approvals.respond(approval-id { decision”挂牌子，告诉系统它该指向“approve });”。

原文代码块

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

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Task helpers use the durable task ledger that also backs openclaw tasks:。

原文小纸条

Task helpers use the durable task ledger that also backs 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 });”。

原文代码块

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

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Environment helpers expose read-only 门口的小门卫-local and node discovery:。

原文小纸条

Environment helpers expose read-only Gateway-local and node discovery:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“const { environments } = await oc.environments.list();”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这一行“await oc.environments.status(environments[0].id);”是在给电脑递一张小纸条，告诉它眼下该做哪一步。

原文代码块

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

第 8 站

Explicitly unsupported today

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

这段在解决什么

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

为什么值得看

这种内容决定了 OpenClaw 是“能做”还是“现在还不能做”，读懂它比记术语更重要。

真要动手时

你可以把这一节当成权限说明书，真正配置时优先盯住 default、required、allow、deny 这几个词。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The SDK includes names for the product 聪明脑袋模型 we want, but it does not silently pretend 门口的小门卫 RPCs exist. These calls…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The SDK includes names for the product 聪明脑袋模型 we want, but it does not silently pretend 门口的小门卫 RPCs exist. These calls…。

原文小纸条

The SDK includes names for the product model we want, but it does not silently pretend Gateway RPCs exist. These calls currently throw explicit unsupported errors:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一行“await oc.environments.create({});”是在给电脑递一张小纸条，告诉它眼下该做哪一步。
这一行“await oc.environments.delete("environment-id");”是在给电脑递一张小纸条，告诉它眼下该做哪一步。

原文代码块

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

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Per-run workspace, runtime, environment, and approvals fields are typed as future shape, but the current 门口的小门卫 does no…。

原文小纸条

Per-run workspace, runtime, environment, and approvals fields are typed as future shape, but the current Gateway does not support those overrides on the agent RPC. If callers pass them, the SDK throws before submitting the run so work does not accidentally execute with default workspace, runtime, environment, or approval behavior.

第 9 站

App SDK vs 新本领插件 SDK

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

这段在解决什么

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

为什么值得看

你理解的是能力边界，不只是功能名字。

真要动手时

如果这节里同时出现命令、配置和例子，优先先看例子，再回头看配置。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use the App SDK when code lives outside OpenClaw: Use the 新本领插件 SDK when code runs inside OpenClaw: App SDK code should…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use the App SDK when code lives outside OpenClaw:。

原文小纸条

Use the App SDK when code lives outside OpenClaw:

像准备清单

这一串条目别硬背，把它当成“App SDK vs Plugin SDK”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：Node scripts that start or observe 机器人朋友…、CI jobs that call a 门口的小门卫、dashboards and admin panels、IDE extensions。

原文小纸条

Node scripts that start or observe agent runs
CI jobs that call a Gateway
dashboards and admin panels
IDE extensions
external bridges that do not need to become channel plugins
integration tests with fake or real Gateway transports

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use the 新本领插件 SDK when code runs inside OpenClaw:。

原文小纸条

Use the Plugin SDK when code runs inside OpenClaw:

像准备清单

这一串条目别硬背，把它当成“App SDK vs Plugin SDK”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：provider 新本领插件s、消息通道新本领插件s、工具小帮手 or lifecycle hooks、机器人朋友 harness 新本领插件s。

原文小纸条

provider plugins
channel plugins
tool or lifecycle hooks
agent harness plugins
trusted runtime helpers

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：App SDK code should import from @openclaw/sdk. 新本领插件 code should import from documented openclaw/新本领插件-sdk/* subpaths.…。

原文小纸条

App SDK code should import from @openclaw/sdk. Plugin code should import from documented openclaw/plugin-sdk/* subpaths. Do not mix the two contracts.

第 10 站

OpenClaw App SDK：先把底下那条暗线看见

OpenClaw App SDK

Start Here

What ships today

Connect to a 门口的小门卫

Run an 机器人朋友

Create and reuse sessions

一边说一边送 events

聪明脑袋模型s, 工具小帮手s, artifacts, and approvals

Explicitly unsupported today

App SDK vs 新本领插件 SDK

Related