Di chuyển Plugin SDK

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.

​

Điều gì đang thay đổi

• openclaw/plugin-sdk/compat - một import duy nhất tái xuất hàng chục trình trợ giúp. Nó được giới thiệu để giữ cho các Plugin cũ dựa trên hook tiếp tục hoạt động trong khi kiến trúc Plugin mới đang được xây dựng.
• openclaw/plugin-sdk/infra-runtime - một barrel trình trợ giúp runtime rộng trộn lẫn sự kiện hệ thống, trạng thái Heartbeat, hàng đợi phân phối, trình trợ giúp fetch/proxy, trình trợ giúp tệp, kiểu phê duyệt và các tiện ích không liên quan.
• openclaw/plugin-sdk/config-runtime - một barrel tương thích cấu hình rộng vẫn mang các trình trợ giúp load/write trực tiếp đã bị loại bỏ trong giai đoạn di chuyển.
• openclaw/extension-api - một cầu nối cho phép Plugin truy cập trực tiếp vào các trình trợ giúp phía host như trình chạy agent nhúng.
• api.registerEmbeddedExtensionFactory(...) - một hook extension đóng gói chỉ dành cho Pi đã bị gỡ bỏ, từng có thể quan sát các sự kiện embedded-runner như tool_result.

​

Vì sao thay đổi này được thực hiện

• Khởi động chậm - import một trình trợ giúp đã load hàng chục mô-đun không liên quan
• Phụ thuộc vòng - các tái xuất rộng khiến việc tạo vòng import trở nên dễ dàng
• Bề mặt API không rõ ràng - không có cách nào biết export nào ổn định và export nào là nội bộ

• Anthropic giữ các trình trợ giúp stream dành riêng cho Claude trong seam api.ts / contract-api.ts của chính nó
• OpenAI giữ các provider builder, trình trợ giúp mô hình mặc định và realtime provider builder trong api.ts của chính nó
• OpenRouter giữ provider builder và trình trợ giúp onboarding/cấu hình trong chính api.ts của nó

​

Kế hoạch di chuyển Talk và giọng nói realtime

1. Giữ các primitive runtime/bộ điều khiển dùng chung trong plugin-sdk/realtime-voice.
2. Chuyển các bề mặt đóng gói sẵn sang bộ điều khiển dùng chung: relay trình duyệt, handoff phòng được quản lý, realtime cuộc gọi thoại, STT streaming cuộc gọi thoại, Google Meet realtime và native push-to-talk.
3. Thay thế các họ RPC Talk cũ bằng API cuối cùng talk.session.* và talk.client.*.
4. Quảng bá một kênh sự kiện Talk trực tiếp trong Gateway hello-ok.features.events: talk.event.
5. Xóa endpoint HTTP realtime cũ và mọi đường dẫn ghi đè hướng dẫn theo thời điểm yêu cầu.

// Gateway-owned Talk session API.
await gateway.request("talk.session.create", {
  mode: "realtime",
  transport: "gateway-relay",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });
await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "working" },
  options: { willContinue: true },
});
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "already_delivered" },
  options: { suppressResponse: true },
});
await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });
await gateway.request("talk.session.close", { sessionId });

// Client-owned provider session API.
await gateway.request("talk.client.create", {
  mode: "realtime",
  transport: "webrtc",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });

​

Chính sách tương thích

1. thêm contract mới
2. giữ hành vi cũ được nối qua một adapter tương thích
3. phát ra diagnostic hoặc cảnh báo nêu tên đường dẫn cũ và phần thay thế
4. bao phủ cả hai đường dẫn trong kiểm thử
5. ghi tài liệu về việc ngừng hỗ trợ và đường dẫn di trú
6. chỉ gỡ bỏ sau cửa sổ di trú đã công bố, thường trong một bản phát hành major

​

Cách di trú

await api.runtime.config.mutateConfigFile({
  afterWrite: { mode: "auto" },
  mutate(draft) {
    draft.plugins ??= {};
  },
});

// Pi and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"]
  }
}

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Only set this for trusted compatibility callers that intentionally
  // accept shell-mediated fallback.
  allowShellFallback: true,
});

grep -r "plugin-sdk/compat" my-plugin/
grep -r "plugin-sdk/infra-runtime" my-plugin/
grep -r "plugin-sdk/config-runtime" my-plugin/
grep -r "openclaw/extension-api" my-plugin/

// Before (deprecated backwards-compatibility layer)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// After (modern focused imports)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";

// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

​

Tham chiếu đường dẫn import

​

Các mục ngừng hỗ trợ đang hoạt động

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

​

Lịch trình gỡ bỏ

​

Tạm thời chặn các cảnh báo

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

​

Liên quan

• Bắt đầu - xây dựng Plugin đầu tiên của bạn
• Tổng quan SDK - tham chiếu import subpath đầy đủ
• Plugin kênh - xây dựng Plugin kênh
• Plugin provider - xây dựng Plugin provider
• Nội bộ Plugin - đào sâu kiến trúc
• Manifest Plugin - tham chiếu schema manifest