Skip to main content

Documentation Index

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

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

OpenClaw App SDK คือ API ไคลเอนต์สาธารณะสำหรับแอปที่อยู่นอกกระบวนการ OpenClaw ใช้ @openclaw/sdk เมื่อสคริปต์ แดชบอร์ด งาน CI ส่วนขยาย IDE หรือแอปภายนอกอื่นต้องการเชื่อมต่อกับ Gateway, เริ่มการรันของเอเจนต์, สตรีมอีเวนต์, รอผลลัพธ์, ยกเลิกงาน หรือตรวจสอบทรัพยากรของ Gateway
App SDK แตกต่างจาก Plugin SDK @openclaw/sdk คุยกับ Gateway จากภายนอก OpenClaw openclaw/plugin-sdk/* ใช้สำหรับ Plugin ที่รันอยู่ภายใน OpenClaw เท่านั้น และ ลงทะเบียนผู้ให้บริการ ช่องทาง เครื่องมือ ฮุก หรือรันไทม์ที่เชื่อถือได้

สิ่งที่มีให้วันนี้

@openclaw/sdk มาพร้อมกับ:
ส่วนติดต่อสถานะทำอะไร
OpenClawพร้อมใช้งานจุดเริ่มต้นไคลเอนต์หลัก ดูแลทรานสปอร์ต การเชื่อมต่อ คำขอ และอีเวนต์
GatewayClientTransportพร้อมใช้งานทรานสปอร์ต WebSocket ที่รองรับโดยไคลเอนต์ Gateway
oc.agentsพร้อมใช้งานแสดงรายการ สร้าง อัปเดต ลบ และรับแฮนเดิลเอเจนต์
Agent.run()พร้อมใช้งานเริ่มการรัน Gateway agent และคืนค่า Run
oc.runsพร้อมใช้งานสร้าง รับ รอ ยกเลิก และสตรีมการรัน
Run.events()พร้อมใช้งานสตรีมอีเวนต์ต่อการรันที่ถูกปรับให้อยู่ในรูปแบบมาตรฐาน พร้อมรีเพลย์สำหรับการรันที่เร็ว
Run.wait()พร้อมใช้งานเรียก agent.wait และคืนค่า RunResult ที่เสถียร
Run.cancel()พร้อมใช้งานเรียก sessions.abort ด้วยรหัสการรัน พร้อมคีย์เซสชันเมื่อมี
oc.sessionsพร้อมใช้งานสร้าง แก้ไข ส่งไปยัง แพตช์ Compaction และรับแฮนเดิลเซสชัน
Session.send()พร้อมใช้งานเรียก sessions.send และคืนค่า Run
oc.tasksพร้อมใช้งานแสดงรายการ อ่าน และยกเลิกรายการบัญชีแยกประเภทงานของ Gateway
oc.modelsพร้อมใช้งานเรียก models.list และ RPC สถานะ models.authStatus ปัจจุบัน
oc.toolsพร้อมใช้งานแสดงรายการ กำหนดขอบเขต และเรียกใช้เครื่องมือ Gateway ผ่านไปป์ไลน์นโยบาย
oc.artifactsพร้อมใช้งานแสดงรายการ รับ และดาวน์โหลดอาร์ทิแฟกต์ทรานสคริปต์ของ Gateway
oc.approvalsพร้อมใช้งานแสดงรายการและแก้ไขการอนุมัติ exec ผ่าน RPC การอนุมัติของ Gateway
oc.environmentsบางส่วนแสดงรายการตัวเลือกสภาพแวดล้อมแบบ Gateway-local และโหนด; create/delete ยังไม่ได้เชื่อมต่อ
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

สร้างไคลเอนต์ด้วย URL ของ 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();
new OpenClaw({ gateway: "ws://..." }) เทียบเท่ากับ url ตัวเลือก gateway: "auto" ได้รับการยอมรับโดยคอนสตรักเตอร์ แต่การค้นหา Gateway อัตโนมัติ ยังไม่ใช่ฟีเจอร์ SDK แยกต่างหาก; ให้ส่ง url เมื่อแอปยังไม่รู้วิธีค้นหา Gateway สำหรับการทดสอบ ให้ส่งออบเจ็กต์ที่อิมพลีเมนต์ 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);
refs ของโมเดลที่ระบุผู้ให้บริการ เช่น openai/gpt-5.5 จะถูกแยกเป็นการ override provider และ model ของ Gateway timeoutMs ยังคงเป็นมิลลิวินาทีใน SDK และ ถูกแปลงเป็นวินาทีของ timeout ของ Gateway สำหรับ RPC agent run.wait() ใช้ RPC agent.wait ของ Gateway กำหนดเวลารอที่หมดอายุขณะที่การรัน ยังทำงานอยู่จะคืนค่า status: "accepted" แทนการทำเหมือนว่าการรันเองหมดเวลา timeout ของรันไทม์ การรันที่ถูก abort และการรันที่ถูกยกเลิกจะถูกปรับให้อยู่ในรูปแบบ 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.startedจุดเริ่มต้น lifecycle ของ agent
run.completedจุดสิ้นสุด lifecycle ของ agent
run.failedข้อผิดพลาด lifecycle ของ agent
run.cancelledจุดสิ้นสุด lifecycle ที่ถูก abort/ยกเลิก
run.timed_outจุดสิ้นสุด lifecycle เนื่องจาก timeout
assistant.deltadelta การสตรีมของผู้ช่วย
assistant.messageข้อความของผู้ช่วย
thinking.deltaสตรีมการคิดหรือแผน
tool.call.startedจุดเริ่มต้นเครื่องมือ/รายการ/คำสั่ง
tool.call.deltaการอัปเดตเครื่องมือ/รายการ/คำสั่ง
tool.call.completedการเสร็จสมบูรณ์ของเครื่องมือ/รายการ/คำสั่ง
tool.call.failedความล้มเหลวหรือสถานะถูกบล็อกของเครื่องมือ/รายการ/คำสั่ง
approval.requestedคำขออนุมัติ exec หรือ Plugin
approval.resolvedการแก้ไขผลอนุมัติ exec หรือ Plugin
session.createdการสร้าง sessions.changed
session.updatedการอัปเดต sessions.changed
session.compactedCompaction ของ sessions.changed
task.updatedอีเวนต์อัปเดตงาน
artifact.updatedอีเวนต์สตรีมแพตช์
rawอีเวนต์ใดๆ ที่ยังไม่มีการแมป SDK ที่เสถียร
Run.events() กรองอีเวนต์ให้เหลือรหัสการรันเดียว และรีเพลย์อีเวนต์ที่เห็นแล้วสำหรับ การรันที่เร็ว ซึ่งหมายความว่าโฟลว์ที่บันทึกไว้ปลอดภัย:
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);
}
ตัวช่วยการอนุมัติใช้ RPC การอนุมัติ exec:
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-local และโหนด:
const { environments } = await oc.environments.list();
await oc.environments.status(environments[0].id);

สิ่งที่ไม่รองรับอย่างชัดเจนในวันนี้

SDK รวมชื่อสำหรับโมเดลผลิตภัณฑ์ที่เราต้องการ แต่จะไม่แกล้งทำเงียบๆ ว่า RPC ของ Gateway มีอยู่ การเรียกเหล่านี้ปัจจุบันจะโยนข้อผิดพลาด unsupported อย่างชัดเจน:
await oc.environments.create({});
await oc.environments.delete("environment-id");
ฟิลด์ workspace, runtime, environment และ approvals ต่อการรันถูกกำหนดชนิด เป็นรูปแบบในอนาคต แต่ Gateway ปัจจุบันยังไม่รองรับการ override เหล่านั้นบน RPC agent หากผู้เรียกส่งฟิลด์เหล่านี้ SDK จะโยนข้อผิดพลาดก่อนส่งการรัน เพื่อไม่ให้งาน ถูกดำเนินการโดยไม่ตั้งใจด้วยพฤติกรรม workspace, runtime, environment หรือ approval ค่าเริ่มต้น

App SDK เทียบกับ Plugin SDK

ใช้ App SDK เมื่อโค้ดอยู่นอก OpenClaw:
  • สคริปต์ Node ที่เริ่มหรือสังเกตการรันของเอเจนต์
  • งาน CI ที่เรียก Gateway
  • แดชบอร์ดและแผงผู้ดูแล
  • ส่วนขยาย IDE
  • บริดจ์ภายนอกที่ไม่จำเป็นต้องกลายเป็น Plugin ช่องทาง
  • การทดสอบอินทิเกรชันด้วยทรานสปอร์ต Gateway ปลอมหรือจริง
ใช้ Plugin SDK เมื่อโค้ดรันอยู่ภายใน OpenClaw:
  • Plugin ผู้ให้บริการ
  • Plugin ช่องทาง
  • ฮุกเครื่องมือหรือ lifecycle
  • Plugin ฮาร์เนสเอเจนต์
  • ตัวช่วยรันไทม์ที่เชื่อถือได้
โค้ด App SDK ควร import จาก @openclaw/sdk โค้ด Plugin ควร import จาก subpath openclaw/plugin-sdk/* ที่บันทึกไว้ในเอกสาร อย่าผสมสัญญาทั้งสองนี้

ที่เกี่ยวข้อง