Thiết kế API của OpenClaw App SDK

Trang này là thiết kế tham chiếu API chi tiết cho OpenClaw App SDK công khai. Nó được tách riêng có chủ ý khỏi Plugin SDK.

SDK ứng dụng công khai nên được xây dựng thành hai lớp:

1. Máy khách Gateway cấp thấp được sinh tự động.
2. Lớp bọc cấp cao, thuận tiện với các đối tượng OpenClaw, Agent, Session, Run, Task, Artifact, Approval, và Environment.

Thiết kế namespace

Các namespace cấp thấp nên bám sát tài nguyên Gateway:

oc.agents.list();oc.agents.get("main");oc.agents.create(...);oc.agents.update(...); oc.sessions.list();oc.sessions.create(...);oc.sessions.resolve(...);oc.sessions.send(...);oc.sessions.messages(...);oc.sessions.fork(...);oc.sessions.compact(...);oc.sessions.abort(...); oc.runs.create(...);oc.runs.get(runId);oc.runs.events(runId, { after });oc.runs.wait(runId);oc.runs.cancel(runId); oc.tasks.list({ status: "running" });oc.tasks.get(taskId);oc.tasks.cancel(taskId, { reason });oc.tasks.events(taskId, { after }); // future API oc.models.list();oc.models.status(); // Gateway models.authStatus oc.tools.list();oc.tools.invoke("tool-name", { sessionKey, idempotencyKey }); oc.artifacts.list({ runId });oc.artifacts.get(artifactId, { runId });oc.artifacts.download(artifactId, { runId }); oc.approvals.list();oc.approvals.respond(approvalId, ...); oc.environments.list();oc.environments.create(...); // future API: current SDK throws unsupportedoc.environments.status(environmentId);oc.environments.delete(environmentId); // future API: current SDK throws unsupported

Các lớp bọc cấp cao nên trả về những đối tượng giúp các luồng phổ biến dễ dùng:

const run = await agent.run(inputOrParams);await run.cancel();await run.wait(); for await (const event of run.events()) {  // normalized event stream} const artifacts = await run.artifacts.list();const session = await run.session();

Hợp đồng sự kiện

SDK công khai nên cung cấp các sự kiện có phiên bản, có thể phát lại và đã chuẩn hóa.

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

id là con trỏ phát lại. Người dùng nên có thể kết nối lại bằng events({ after: id }) và nhận các sự kiện đã bỏ lỡ khi chính sách lưu giữ cho phép.

Các nhóm sự kiện đã chuẩn hóa được khuyến nghị:

Payload gốc của runtime nên có sẵn qua raw, nhưng ứng dụng không nên phải phân tích raw cho giao diện người dùng thông thường.

Hợp đồng kết quả

Run.wait() nên trả về một phong bì kết quả ổn định:

type RunResult = {  runId: string;  status: "accepted" | "completed" | "failed" | "cancelled" | "timed_out";  sessionId?: string;  sessionKey?: string;  taskId?: string;  startedAt?: string | number;  endedAt?: string | number;  output?: {    text?: string;    messages?: SDKMessage[];  };  usage?: {    inputTokens?: number;    outputTokens?: number;    totalTokens?: number;    costUsd?: number;  };  artifacts?: ArtifactSummary[];  error?: SDKError;};

Kết quả nên đơn giản và ổn định. Giá trị timestamp giữ nguyên hình dạng của Gateway, nên các run hiện tại dựa trên vòng đời thường báo cáo số mili giây epoch, trong khi adapter vẫn có thể hiển thị chuỗi ISO. Giao diện người dùng giàu thông tin, trace công cụ, và chi tiết gốc của runtime thuộc về sự kiện và artifact.

accepted là kết quả chờ không kết thúc: nó có nghĩa là hạn chờ của Gateway đã hết trước khi run tạo ra kết thúc/lỗi vòng đời. Không được coi nó là timed_out; timed_out được dành riêng cho một run vượt quá timeout runtime của chính nó.

Phê duyệt và câu hỏi

Phê duyệt phải là đối tượng hạng nhất vì các agent lập trình liên tục vượt qua các ranh giới an toàn.

run.onApproval(async (request) => {  if (request.kind === "tool" && request.toolName === "exec") {    return request.approveOnce({ reason: "CI command allowed by policy" });  }   return request.askUser();});

Sự kiện phê duyệt nên mang:

• id phê duyệt
• id run và id phiên
• loại yêu cầu
• tóm tắt hành động được yêu cầu
• tên công cụ hoặc hành động môi trường
• mức rủi ro
• các quyết định có sẵn
• thời điểm hết hạn
• liệu quyết định có thể được tái sử dụng hay không

Câu hỏi tách biệt với phê duyệt. Một câu hỏi yêu cầu người dùng hoặc ứng dụng host cung cấp thông tin. Một phê duyệt yêu cầu quyền thực hiện một hành động.

Mô hình ToolSpace

Ứng dụng cần hiểu bề mặt công cụ mà không nhập phần nội bộ của Plugin.

const tools = await run.toolSpace(); for (const tool of tools.list()) {  console.log(tool.name, tool.source, tool.requiresApproval);}

SDK nên cung cấp:

• siêu dữ liệu công cụ đã chuẩn hóa
• nguồn: OpenClaw, MCP, Plugin, kênh, runtime, hoặc ứng dụng
• tóm tắt schema
• chính sách phê duyệt
• khả năng tương thích runtime
• liệu một công cụ là ẩn, chỉ đọc, có khả năng ghi, hoặc có khả năng host

Việc gọi công cụ qua SDK nên rõ ràng và có phạm vi. Hầu hết ứng dụng nên chạy agent, không gọi trực tiếp các công cụ tùy ý.

Mô hình artifact

Artifact nên bao quát nhiều thứ hơn tệp.

type ArtifactSummary = {  id: string;  runId?: string;  sessionId?: string;  type:    | "file"    | "patch"    | "diff"    | "log"    | "media"    | "screenshot"    | "trajectory"    | "pull_request"    | "workspace";  title?: string;  mimeType?: string;  sizeBytes?: number;  createdAt: string;  expiresAt?: string;};

Các ví dụ phổ biến:

• chỉnh sửa tệp và tệp được tạo
• gói patch
• diff VCS
• ảnh chụp màn hình và đầu ra media
• log và gói trace
• liên kết pull request
• trajectory runtime
• snapshot workspace môi trường được quản lý

Truy cập artifact nên hỗ trợ biên tập, lưu giữ, và URL tải xuống mà không giả định mọi artifact đều là tệp cục bộ thông thường.

Mô hình bảo mật

SDK ứng dụng phải rõ ràng về thẩm quyền.

Các phạm vi token được khuyến nghị:

Mặc định:

• không chuyển tiếp bí mật theo mặc định
• không truyền qua biến môi trường không hạn chế
• tham chiếu bí mật thay vì giá trị bí mật
• chính sách sandbox và mạng rõ ràng
• lưu giữ môi trường từ xa rõ ràng
• phê duyệt cho thực thi host trừ khi chính sách chứng minh điều ngược lại
• sự kiện runtime thô được biên tập trước khi rời Gateway trừ khi bên gọi có phạm vi chẩn đoán mạnh hơn

Nhà cung cấp môi trường được quản lý

Agent được quản lý nên được triển khai dưới dạng nhà cung cấp môi trường.

type EnvironmentProvider = {  id: string;  capabilities: {    checkout?: boolean;    sandbox?: boolean;    networkPolicy?: boolean;    secrets?: boolean;    artifacts?: boolean;    logs?: boolean;    pullRequests?: boolean;    longRunning?: boolean;  };};

Triển khai đầu tiên không cần là SaaS được host. Nó có thể nhắm tới các host Node hiện có, workspace tạm thời, runner kiểu CI, hoặc môi trường kiểu Testbox. Hợp đồng quan trọng là:

1. chuẩn bị workspace
2. ràng buộc môi trường và bí mật an toàn
3. bắt đầu run
4. truyền sự kiện
5. thu thập artifact
6. dọn dẹp hoặc lưu giữ theo chính sách

Khi phần này ổn định, một dịch vụ cloud được host có thể triển khai cùng hợp đồng nhà cung cấp.

Cấu trúc gói

Các gói được khuyến nghị:

Repo đã có openclaw/plugin-sdk/* cho Plugin. Giữ namespace đó tách biệt để tránh gây nhầm lẫn giữa tác giả Plugin và nhà phát triển ứng dụng.

Chiến lược máy khách được sinh tự động

Máy khách cấp thấp nên được sinh từ các schema giao thức Gateway có phiên bản, sau đó được bao bọc bởi các lớp tiện dụng viết tay.

Phân lớp:

1. Nguồn chân lý của schema Gateway.
2. Client TypeScript cấp thấp được tạo.
3. Bộ xác thực runtime cho đầu vào bên ngoài và payload sự kiện.
4. Các wrapper cấp cao OpenClaw, Agent, Session, Run, Task và Artifact .
5. Ví dụ hướng dẫn thực hành và kiểm thử tích hợp.

Lợi ích:

• sai lệch giao thức sẽ dễ nhận thấy
• kiểm thử có thể so sánh các phương thức được tạo với các export của Gateway
• App SDK vẫn độc lập với nội bộ Plugin SDK
• người dùng cấp thấp vẫn có toàn quyền truy cập giao thức
• người dùng cấp cao nhận được API sản phẩm nhỏ gọn

Liên quan

• OpenClaw App SDK
• Tài liệu tham khảo RPC của Gateway
• Vòng lặp tác tử
• Runtime của tác tử
• Tác vụ nền
• Tác tử ACP
• Tổng quan Plugin SDK