Thiết kế SDK OpenClaw

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.

​

Trạng thái

​

Mục tiêu

• Cung cấp cho nhà phát triển ứng dụng một API cấp cao rất nhỏ để chạy agent OpenClaw.
• Giữ OpenClaw ưu tiên cục bộ làm runtime mặc định.
• Biến môi trường đám mây hoặc được quản lý thành một provider môi trường bổ sung, không phải một API agent khác.
• Duy trì các ranh giới OpenClaw hiện có: Gateway sở hữu giao thức công khai, SDK Plugin sở hữu phần mở rộng trong tiến trình, ACP sở hữu khả năng tương tác harness bên ngoài.
• Hỗ trợ stream, wait, cancel, resume, fork, artifact, phê duyệt và tác vụ nền như các thao tác hạng nhất.
• Phơi bày sự kiện chuẩn hóa ổn định đồng thời giữ lại sự kiện thô nguyên bản theo runtime cho người dùng nâng cao.
• Làm rõ quyền của SDK, chuyển tiếp bí mật, phê duyệt, sandboxing và môi trường từ xa.
• Giữ hợp đồng công khai đủ nhỏ để tài liệu hóa, kiểm thử, định phiên bản và sinh mã.

​

Không phải mục tiêu

• Không phơi bày openclaw/plugin-sdk/* làm SDK ứng dụng.
• Không biến ACP thành mô hình runtime duy nhất.
• Không yêu cầu dịch vụ đám mây trước khi SDK trở nên hữu ích.
• Không sao chép chính xác API của Cursor, Claude, OpenAI, ADK, OpenCode, Codex hoặc ACP.
• Không phơi bày payload sự kiện any không giới hạn làm hợp đồng công khai duy nhất.
• Không hứa hẹn cách ly sandbox hoặc mạng cho harness bên ngoài trừ khi môi trường được chọn thực sự có thể thực thi điều đó.
• Không khiến tác giả Plugin phụ thuộc vào đối tượng SDK ứng dụng bên trong mã runtime Plugin.

​

Mức độ phù hợp hiện tại của OpenClaw

​

Mô hình cốt lõi

​

Hình thái sản phẩm

import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({ gateway: "auto" });
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",
});

for await (const event of run.events()) {
  if (event.type === "assistant.delta") {
    process.stdout.write(event.text);
  }
}

const result = await run.wait();
console.log(result.status);

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

const run = await oc.runs.create({
  input: "Deep review this repository and return only high-risk findings.",
  workspace: { cwd: process.cwd() },
  runtime: { type: "acp", harness: "claude" },
  mode: "task",
});

const run = await agent.run({
  input: "Run the full changed gate and summarize failures.",
  workspace: { repo: "openclaw/openclaw", ref: "main" },
  runtime: {
    type: "managed",
    provider: "testbox",
    timeoutMinutes: 90,
  },
});

​

Lựa chọn runtime

type RuntimeSelection =
  | "auto"
  | { type: "embedded"; id: "pi" | "codex" | string }
  | { type: "cli"; id: "claude-cli" | string }
  | { type: "acp"; harness: "claude" | "cursor" | "gemini" | "opencode" | string }
  | { type: "managed"; provider: "local" | "node" | "testbox" | "cloud" | string };

• auto tuân theo các quy tắc lựa chọn runtime của OpenClaw.
• embedded nhắm tới harness trong tiến trình đáng tin cậy được đăng ký thông qua SDK Plugin, như pi hoặc codex.
• cli nhắm tới thực thi backend CLI do OpenClaw sở hữu khi có sẵn.
• acp nhắm tới harness bên ngoài thông qua ACP/acpx.
• managed nhắm tới một provider môi trường và vẫn có thể chạy runtime nhúng, CLI hoặc ACP bên trong môi trường đó.

​

Mô hình môi trường

type EnvironmentSelection =
  | { type: "local"; cwd?: string }
  | { type: "gateway"; url?: string; cwd?: string }
  | { type: "node"; nodeId: string; cwd?: string }
  | { type: "managed"; provider: string; repo?: string; ref?: string }
  | { type: "ephemeral"; provider: string; repo?: string; ref?: string };

• chuẩn bị checkout hoặc workspace
• quyền truy cập tiến trình và tệp
• thực thi sandbox và mạng
• biến môi trường và tham chiếu bí mật
• log, trace và artifact
• dọn dẹp và lưu giữ
• tính sẵn có của runtime

​

Kế hoạch sổ tay

​

Triển khai theo giai đoạn

​

Giai đoạn 0: RFC và từ vựng

• Thống nhất các danh từ và tên công khai.
• Quyết định tên gói.
• Định nghĩa phân loại sự kiện đầu tiên.
• Đánh dấu plugin SDK hiện tại là tách biệt có chủ đích trong tài liệu.

​

Giai đoạn 1: Client được tạo ở cấp thấp

• Tạo client TypeScript từ các schema giao thức Gateway.
• Bao phủ agent, agent.wait, phiên, đăng ký, hủy và tác vụ trước.
• Thêm smoke test để xác nhận các phương thức được tạo khớp với tên phương thức Gateway và hình dạng schema.
• Phát hành dưới dạng gói thử nghiệm hoặc nội bộ.

​

Giai đoạn 2: API run cấp cao

• Thêm OpenClaw, Agent, Session và Run.
• Hỗ trợ run.events(), run.wait() và run.cancel().
• Hỗ trợ phát hiện Gateway cục bộ và URL Gateway tường minh.
• Hỗ trợ phiên bền vững và gửi phiên.

​

Giai đoạn 3: Phép chiếu sự kiện đã chuẩn hóa

• Thêm phép chiếu sự kiện đã chuẩn hóa phía Gateway bên cạnh các sự kiện thô hiện có.
• Giữ lại sự kiện runtime thô khi chính sách cho phép.
• Thêm con trỏ phát lại và hành vi kết nối lại.
• Ánh xạ các sự kiện PI, Codex, ACP và tác vụ vào phân loại ổn định.

​

Giai đoạn 4: Artifact và phê duyệt

• Thêm danh sách và tải xuống artifact.
• Thêm helper đăng ký và phản hồi phê duyệt.
• Thêm helper đăng ký và phản hồi câu hỏi.
• Thêm cookbook bảng điều khiển phê duyệt.

​

Giai đoạn 5: Nhà cung cấp môi trường

• Giới thiệu các hợp đồng nhà cung cấp môi trường cục bộ, Node và quản lý.
• Bắt đầu với một môi trường đã tồn tại trong vận hành.
• Thêm chuẩn bị workspace, nhật ký, artifact, thời gian chờ, dọn dẹp và lưu giữ.

​

Giai đoạn 6: Quy trình làm việc kiểu cloud

• Thêm lượt chạy hướng theo kho lưu trữ và nhánh.
• Thêm artifact pull request.
• Thêm bảng lượt chạy được nhóm theo repo, nhánh, trạng thái và người được giao.
• Thêm phiên quản lý chạy dài và chính sách lưu giữ.

​

Lựa chọn thiết kế nên sao chép

• Từ Cursor: Agent cộng với Run, tính đối xứng giữa cục bộ và cloud, phát hiện mô hình, artifact và onboarding dựa trên cookbook.
• Từ Claude Agent SDK: client hai chiều, ngắt, quyền, hook, công cụ tùy chỉnh, kho lưu phiên và ngữ nghĩa tiếp tục.
• Từ OpenAI Agents: chuyển giao, guardrail, tiếp tục phê duyệt của con người, tracing và đối tượng kết quả stream có cấu trúc.
• Từ Google ADK: dịch vụ phía sau runner, hành động sự kiện, bộ nhớ, artifact, dịch vụ thông tin xác thực và Plugin chặn quanh vòng đời lượt chạy.
• Từ OpenCode: client giao thức được tạo, REST cộng SSE, phiên, workspace, câu hỏi, quyền, tệp, VCS, PTY, MCP, tác tử và Skills.
• Từ Codex: sandbox, phê duyệt, mạng, thực thi cục bộ và từ xa tường minh, và ranh giới luồng máy chủ ứng dụng.
• Từ ACP và acpx: khả năng tương tác harness bên ngoài dựa trên adapter và hàng đợi prompt có tên.

​

Lựa chọn thiết kế cần tránh

• SDK công khai chỉ là bản đổ mỏng của nội bộ Gateway.
• SDK công khai import các subpath của plugin SDK.
• SDK công khai nơi sự kiện chỉ là stream cộng với data.
• API ưu tiên cloud khiến OpenClaw cục bộ có cảm giác như chế độ kế thừa.
• Lựa chọn runtime bị ẩn trong tiền tố id mô hình.
• Chuyển tiếp bí mật bị ẩn trong map môi trường.
• Tùy chọn riêng của ACP ở cấp cao nhất của mọi lượt chạy.
• Cờ sandbox không thể được runtime đã chọn thực thi.
• Một đối tượng SDK cố gắng vừa là Plugin nhà cung cấp, Plugin kênh, client ứng dụng, vừa là runner quản lý cùng lúc.

​

Câu hỏi mở

• Gói ban đầu nên nằm trong repo này hay một repo SDK riêng?
• Client cấp thấp được tạo có nên được phát hành công khai trước khi wrapper cấp cao ổn định không?
• Cơ chế xác thực ứng dụng được hỗ trợ đầu tiên là gì: token cục bộ, token quản trị, luồng thiết bị OAuth hay đăng ký ứng dụng đã ký?
• SDK nên mặc định hiển thị bao nhiêu lịch sử tin nhắn phiên?
• Môi trường quản lý chỉ nên được cấu hình trong cấu hình Gateway, hay caller SDK có thể yêu cầu trực tiếp bằng token có phạm vi?
• Quy tắc lưu giữ nào áp dụng cho artifact được tạo bởi lượt chạy cục bộ?
• Payload sự kiện nào cần được biên tập trước khi gửi cho ứng dụng?
• Run nên bao phủ các lượt chat thông thường và tác vụ tách rời, hay công việc nền tách rời luôn nên trả về wrapper Task với Run lồng bên trong?

​

Tài liệu liên quan

• Vòng lặp tác tử
• Runtime tác tử
• Phiên
• Tác tử phụ
• Tác vụ nền
• Tác tử ACP
• Plugin harness tác tử
• Tổng quan Plugin SDK