Chuyển đến nội dung chính

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 App SDK là API client công khai cho các ứng dụng bên ngoài tiến trình OpenClaw. Dùng @openclaw/sdk khi một script, bảng điều khiển, tác vụ CI, tiện ích mở rộng IDE, hoặc ứng dụng bên ngoài khác muốn kết nối tới Gateway, bắt đầu các lượt chạy tác tử, truyền sự kiện theo luồng, chờ kết quả, hủy công việc, hoặc kiểm tra tài nguyên Gateway.
App SDK khác với Plugin SDK. @openclaw/sdk giao tiếp với Gateway từ bên ngoài OpenClaw. openclaw/plugin-sdk/* chỉ dành cho các Plugin chạy bên trong OpenClaw và đăng ký provider, kênh, công cụ, hook, hoặc runtime tin cậy.

Nội dung hiện có

@openclaw/sdk hiện có:
Giao diệnTrạng tháiChức năng
OpenClawSẵn sàngĐiểm vào client chính. Sở hữu transport, kết nối, yêu cầu và sự kiện.
GatewayClientTransportSẵn sàngTransport WebSocket dựa trên Gateway client.
oc.agentsSẵn sàngLiệt kê, tạo, cập nhật, xóa và lấy handle tác tử.
Agent.run()Sẵn sàngBắt đầu một lượt chạy Gateway agent và trả về một Run.
oc.runsSẵn sàngTạo, lấy, chờ, hủy và truyền lượt chạy theo luồng.
Run.events()Sẵn sàngTruyền các sự kiện chuẩn hóa theo từng lượt chạy, có phát lại cho lượt chạy nhanh.
Run.wait()Sẵn sàngGọi agent.wait và trả về một RunResult ổn định.
Run.cancel()Sẵn sàngGọi sessions.abort theo id lượt chạy, kèm khóa phiên khi có.
oc.sessionsSẵn sàngTạo, phân giải, gửi tới, vá, compact và lấy handle phiên.
Session.send()Sẵn sàngGọi sessions.send và trả về một Run.
oc.tasksSẵn sàngLiệt kê, đọc và hủy các mục sổ cái tác vụ Gateway.
oc.modelsSẵn sàngGọi models.list và RPC trạng thái models.authStatus hiện tại.
oc.toolsSẵn sàngLiệt kê, xác định phạm vi và gọi các công cụ Gateway qua pipeline chính sách.
oc.artifactsSẵn sàngLiệt kê, lấy và tải xuống các artifact bản ghi Gateway.
oc.approvalsSẵn sàngLiệt kê và xử lý phê duyệt exec qua RPC phê duyệt Gateway.
oc.environmentsMột phầnLiệt kê ứng viên môi trường cục bộ Gateway và node; tạo/xóa chưa được nối dây.
oc.rawEvents()Sẵn sàngCung cấp sự kiện Gateway thô cho người dùng nâng cao.
normalizeGatewayEvent()Sẵn sàngChuyển sự kiện Gateway thô thành dạng sự kiện SDK ổn định.
SDK cũng xuất các kiểu lõi được các giao diện đó dùng: 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, và các kiểu kết quả liên quan.

Kết nối tới Gateway

Tạo client với URL Gateway rõ ràng, hoặc tiêm một transport tùy chỉnh cho kiểm thử và runtime ứng dụng nhúng.
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://..." }) tương đương với url. Tùy chọn gateway: "auto" được constructor chấp nhận, nhưng tự động phát hiện Gateway chưa phải là một tính năng SDK riêng; hãy truyền url khi ứng dụng chưa biết cách phát hiện Gateway. Cho kiểm thử, hãy truyền một đối tượng triển khai OpenClawTransport:
const oc = new OpenClaw({
  transport: {
    async request(method, params) {
      return { method, params };
    },
    async *events() {},
  },
});

Chạy một tác tử

Dùng oc.agents.get(id) khi ứng dụng muốn có handle tác tử, rồi gọi 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);
Tham chiếu model có provider như openai/gpt-5.5 được tách thành các override providermodel của Gateway. timeoutMs vẫn là mili giây trong SDK và được chuyển thành giây timeout của Gateway cho RPC agent. run.wait() dùng RPC Gateway agent.wait. Hạn chờ hết hạn trong khi lượt chạy vẫn đang hoạt động sẽ trả về status: "accepted" thay vì giả vờ rằng chính lượt chạy đã hết thời gian. Timeout runtime, lượt chạy bị abort và lượt chạy bị hủy được chuẩn hóa thành timed_out hoặc cancelled.

Tạo và tái sử dụng phiên

Dùng phiên khi ứng dụng cần trạng thái bản ghi bền vững.
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() gọi sessions.send và trả về một Run. Handle phiên cũng hỗ trợ:
await session.abort(run.id);
await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });

Truyền sự kiện theo luồng

SDK chuẩn hóa sự kiện Gateway thô thành một envelope OpenClawEvent ổn định:
type OpenClawEvent = {
  version: 1;
  id: string;
  ts: number;
  type: OpenClawEventType;
  runId?: string;
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  agentId?: string;
  data: unknown;
  raw?: GatewayEvent;
};
Các loại sự kiện thường gặp gồm:
Loại sự kiệnSự kiện Gateway nguồn
run.startedBắt đầu vòng đời agent
run.completedKết thúc vòng đời agent
run.failedLỗi vòng đời agent
run.cancelledKết thúc vòng đời bị abort/hủy
run.timed_outKết thúc vòng đời do timeout
assistant.deltaDelta truyền luồng của trợ lý
assistant.messageTin nhắn của trợ lý
thinking.deltaLuồng suy nghĩ hoặc kế hoạch
tool.call.startedBắt đầu công cụ/mục/lệnh
tool.call.deltaCập nhật công cụ/mục/lệnh
tool.call.completedHoàn tất công cụ/mục/lệnh
tool.call.failedCông cụ/mục/lệnh thất bại hoặc bị chặn
approval.requestedYêu cầu phê duyệt exec hoặc Plugin
approval.resolvedKết quả phê duyệt exec hoặc Plugin
session.createdTạo sessions.changed
session.updatedCập nhật sessions.changed
session.compactedCompaction sessions.changed
task.updatedSự kiện cập nhật tác vụ
artifact.updatedSự kiện luồng patch
rawBất kỳ sự kiện nào chưa có ánh xạ SDK ổn định
Run.events() lọc sự kiện theo một id lượt chạy và phát lại các sự kiện đã thấy cho lượt chạy nhanh. Điều đó nghĩa là luồng được ghi trong tài liệu là an toàn:
const run = await agent.run("Summarize the latest session.");

for await (const event of run.events()) {
  if (event.type === "run.completed") {
    break;
  }
}
Với các luồng toàn ứng dụng, dùng oc.events(). Với frame Gateway thô, dùng oc.rawEvents().

Model, công cụ, artifact và phê duyệt

Helper model ánh xạ tới các phương thức Gateway hiện tại:
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
Helper công cụ cung cấp danh mục Gateway, chế độ xem công cụ hiệu lực và lời gọi công cụ Gateway trực tiếp. oc.tools.invoke() trả về một envelope có kiểu thay vì ném lỗi khi chính sách hoặc phê duyệt từ chối.
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",
});
Helper artifact cung cấp projection artifact Gateway cho ngữ cảnh phiên, lượt chạy hoặc tác vụ. Mỗi lời gọi yêu cầu một phạm vi sessionKey, runId hoặc taskId rõ ràng:
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);
}
Helper phê duyệt dùng RPC phê duyệt exec:
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });
Helper tác vụ dùng sổ cái tác vụ bền vững, cũng là nền tảng cho 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" });
Helper môi trường cung cấp phát hiện chỉ đọc cho Gateway cục bộ và node:
const { environments } = await oc.environments.list();
await oc.environments.status(environments[0].id);

Hiện chưa được hỗ trợ rõ ràng

SDK bao gồm các tên cho mô hình sản phẩm mà chúng ta muốn, nhưng không âm thầm giả vờ rằng RPC Gateway tồn tại. Các lời gọi này hiện ném lỗi không được hỗ trợ một cách rõ ràng:
await oc.environments.create({});
await oc.environments.delete("environment-id");
Các trường theo từng lượt chạy workspace, runtime, environmentapprovals được định kiểu theo dạng tương lai, nhưng Gateway hiện tại không hỗ trợ các override đó trên RPC agent. Nếu caller truyền chúng, SDK sẽ ném lỗi trước khi gửi lượt chạy để công việc không vô tình thực thi với workspace, runtime, môi trường hoặc hành vi phê duyệt mặc định.

App SDK so với Plugin SDK

Dùng App SDK khi mã nằm ngoài OpenClaw:
  • Các script Node bắt đầu hoặc quan sát lượt chạy tác tử
  • Tác vụ CI gọi Gateway
  • bảng điều khiển và panel quản trị
  • tiện ích mở rộng IDE
  • cầu nối bên ngoài không cần trở thành Plugin kênh
  • kiểm thử tích hợp với transport Gateway giả hoặc thật
Dùng Plugin SDK khi mã chạy bên trong OpenClaw:
  • Plugin provider
  • Plugin kênh
  • hook công cụ hoặc vòng đời
  • Plugin agent harness
  • helper runtime tin cậy
Mã App SDK nên import từ @openclaw/sdk. Mã Plugin nên import từ các subpath openclaw/plugin-sdk/* đã được tài liệu hóa. Không trộn lẫn hai hợp đồng này.

Liên quan