Chuyển đổi SDK Plugin

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.

​

Những gì đang thay đổi

• openclaw/plugin-sdk/compat — một import duy nhất re-export hàng chục helper. 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 helper 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, helper fetch/proxy, helper 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 còn mang các helper tải/ghi trực tiếp đã lỗi thời trong thời gian di chuyển.
• openclaw/extension-api — một cầu nối cho Plugin quyền truy cập trực tiếp vào các helper phía host như trình chạy tác tử nhúng.
• api.registerEmbeddedExtensionFactory(...) — một hook extension đóng gói chỉ dành cho Pi đã bị loại bỏ, 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 helper sẽ tải hàng chục mô-đun không liên quan
• Phụ thuộc vòng — các re-export 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 helper stream dành riêng cho Claude trong seam api.ts / contract-api.ts của riêng nó
• OpenAI giữ các builder provider, helper model mặc định và builder provider realtime trong api.ts của riêng nó
• OpenRouter giữ builder provider và helper onboarding/cấu hình trong api.ts của riêng nó

​

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

1. thêm hợp đồng mới
2. giữ hành vi cũ được nối qua adapter tương thích
3. phát chẩn đoán 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 khuyến nghị và đường dẫn di chuyển
6. chỉ loại bỏ sau thời gian di chuyển đã công bố, thường là trong một bản phát hành major

​

Cách di chuyển

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 API đang bị ngừng khuyến nghị

// 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 tắt 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 — đi sâu vào kiến trúc
• Manifest Plugin — tham chiếu schema manifest