Chuyển đến nội dung chính
OpenClaw đã thay thế một lớp tương thích ngược rộng bằng kiến trúc plugin hiện đại được xây dựng từ các import nhỏ và tập trung. Nếu plugin của bạn có từ trước thay đổi đó, hướng dẫn này sẽ giúp plugin chuyển sang các hợp đồng hiện tại.

​
Những thay đổi

Trước đây, một số bề mặt import mở rộng cho phép plugin truy cập gần như mọi thứ từ một điểm vào duy nhất:
  • openclaw/plugin-sdk và openclaw/plugin-sdk/compat - tái xuất hàng chục trình trợ giúp trong khi SDK tập trung đang được xây dựng. Cả hai gốc hiện đã bị loại bỏ; hãy import một đường dẫn con đã được ghi tài liệu để thay thế.
  • openclaw/plugin-sdk/infra-runtime - một barrel rộng kết hợp các 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 cấu hình rộng chỉ được giữ lại trong khoảng thời gian tương thích sau đó; các trình trợ giúp tải/ghi trực tiếp lúc chạy đã bị loại bỏ.
  • openclaw/extension-api - một cầu nối đã bị loại bỏ, từng cho phép plugin truy cập trực tiếp vào các trình trợ giúp phía máy chủ như trình chạy tác nhân nhúng.
  • api.registerEmbeddedExtensionFactory(...) - một hook chỉ dành cho trình chạy nhúng đã bị loại bỏ, từng quan sát các sự kiện của trình chạy nhúng như tool_result. Thay vào đó, hãy dùng middleware kết quả công cụ của tác nhân (xem Di chuyển các phần mở rộng kết quả công cụ nhúng sang middleware).
SDK gốc, barrel tương thích, cầu nối phần mở rộng và factory phần mở rộng nhúng đã bị loại bỏ. infra-runtime và config-runtime chỉ còn tồn tại trong các khoảng thời gian sau đó được ghi nhận riêng; plugin mới nên dùng các đường dẫn con tập trung.
Các plugin import bề mặt gốc, tương thích hoặc phần mở rộng đã bị loại bỏ sẽ không còn tải được. Hãy làm theo các ánh xạ bên dưới trước khi nâng cấp.
OpenClaw không loại bỏ hoặc diễn giải lại hành vi plugin đã được ghi tài liệu trong cùng thay đổi giới thiệu phương án thay thế. Các thay đổi hợp đồng gây phá vỡ trước tiên phải trải qua bộ điều hợp tương thích, chẩn đoán, tài liệu và một khoảng thời gian ngừng hỗ trợ. Điều này áp dụng cho các import SDK, trường manifest, API thiết lập, hook và hành vi đăng ký lúc chạy.

​
Lý do

  • Khởi động chậm - việc import một trình trợ giúp đã tải hàng chục mô-đun không liên quan.
  • Phụ thuộc vòng - các lần tái xuất rộng khiến chu trình import dễ phát sinh.
  • Bề mặt API không rõ ràng - không có cách phân biệt các phần xuất ổn định với phần nội bộ.
Mỗi openclaw/plugin-sdk/<subpath> giờ đây là một mô-đun nhỏ, độc lập với hợp đồng được ghi tài liệu. Các bề mặt tiện ích nhà cung cấp cũ dành cho kênh đi kèm cũng đã bị loại bỏ - các lối tắt trình trợ giúp mang thương hiệu kênh là tiện ích riêng của mono-repo, không phải hợp đồng plugin ổn định. Thay vào đó, hãy dùng các đường dẫn con SDK chung và hẹp. Bên trong không gian làm việc plugin đi kèm, hãy giữ các trình trợ giúp do nhà cung cấp sở hữu trong api.ts hoặc runtime-api.ts của chính plugin đó:
  • Anthropic giữ các trình trợ giúp luồng dành riêng cho Claude trong bề mặt api.ts / contract-api.ts của riêng mình.
  • OpenAI giữ các trình dựng nhà cung cấp, trình trợ giúp mô hình mặc định và trình dựng nhà cung cấp thời gian thực trong api.ts của riêng mình.
  • OpenRouter giữ trình dựng nhà cung cấp và các trình trợ giúp nhập môn/cấu hình trong api.ts của riêng mình.

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

Công việc tương thích plugin bên ngoài tuân theo thứ tự sau:
  1. Thêm hợp đồng mới.
  2. Duy trì hành vi cũ thông qua bộ điều hợp tương thích.
  3. Phát chẩn đoán hoặc cảnh báo nêu rõ đường dẫn cũ và phương án thay thế.
  4. Kiểm thử cả hai đường dẫn.
  5. Ghi tài liệu về việc ngừng hỗ trợ và lộ trình di chuyển.
  6. Chỉ loại bỏ sau khoảng thời gian di chuyển đã công bố, thường là trong một bản phát hành lớn.
Nếu một trường manifest vẫn được chấp nhận, hãy tiếp tục sử dụng trường đó cho đến khi tài liệu và chẩn đoán cho biết điều ngược lại. Mã mới nên ưu tiên phương án thay thế đã được ghi tài liệu; plugin hiện có không nên bị hỏng trong các bản phát hành nhỏ thông thường. Kiểm tra hàng đợi di chuyển hiện tại bằng pnpm plugins:boundary-report: pnpm plugins:boundary-report:ci chạy với cả ba cờ gây lỗi. Mỗi bản ghi tương thích có một ngày removeAfter rõ ràng (không phải cụm từ mơ hồ “bản phát hành lớn tiếp theo”) - báo cáo nhóm các bản ghi đã ngừng hỗ trợ theo ngày đó, đếm các tham chiếu mã/tài liệu cục bộ, chỉ ra các import SDK dành riêng giữa các chủ sở hữu và tóm tắt cầu nối SDK máy chủ bộ nhớ riêng. Các đường dẫn con SDK dành riêng phải có mức sử dụng của chủ sở hữu được theo dõi; các phần xuất dành riêng không được sử dụng nên bị loại bỏ khỏi SDK công khai.

​
Cách di chuyển

1

Di chuyển các trình trợ giúp tải/ghi cấu hình lúc chạy

Plugin đi kèm nên ngừng gọi trực tiếp api.runtime.config.loadConfig() và api.runtime.config.writeConfigFile(...). Ưu tiên cấu hình đã được truyền vào đường dẫn gọi đang hoạt động. Các trình xử lý tồn tại lâu cần ảnh chụp nhanh hiện tại của tiến trình có thể dùng api.runtime.config.current(). Các công cụ tác nhân tồn tại lâu nên đọc ctx.getRuntimeConfig() bên trong execute để công cụ được tạo trước một lần ghi cấu hình vẫn thấy cấu hình đã làm mới.Việc ghi cấu hình đi qua trình trợ giúp giao dịch với chính sách sau khi ghi rõ ràng:
Dùng afterWrite: { mode: "restart", reason: "..." } khi thay đổi yêu cầu khởi động lại Gateway sạch và chỉ dùng afterWrite: { mode: "none", reason: "..." } khi bên gọi sở hữu bước tiếp theo và chủ ý vô hiệu hóa trình lập kế hoạch tải lại. Kết quả đột biến bao gồm bản tóm tắt followUp có kiểu cho kiểm thử và ghi nhật ký; Gateway vẫn chịu trách nhiệm áp dụng hoặc lên lịch khởi động lại.loadConfig và writeConfigFile đã bị loại bỏ khỏi môi trường chạy plugin. Plugin đi kèm và mã môi trường chạy của kho lưu trữ được bảo vệ bởi pnpm check:deprecated-api-usage và pnpm check:no-runtime-action-load-config: việc sử dụng mới trong plugin sản xuất sẽ thất bại hoàn toàn, ghi cấu hình trực tiếp sẽ thất bại, các phương thức máy chủ Gateway phải dùng ảnh chụp nhanh môi trường chạy của yêu cầu, các trình trợ giúp gửi/hành động/máy khách của kênh lúc chạy phải nhận cấu hình từ ranh giới của chúng và các mô-đun môi trường chạy tồn tại lâu không cho phép bất kỳ lệnh gọi loadConfig() ngầm nào.Mã plugin mới nên tránh barrel openclaw/plugin-sdk/config-runtime rộng. Hãy dùng đường dẫn con hẹp cho từng tác vụ:Plugin đi kèm và kiểm thử của chúng được trình quét bảo vệ khỏi barrel rộng để các import và mock duy trì cục bộ theo hành vi cần thiết. Barrel vẫn tồn tại để tương thích bên ngoài, nhưng mã mới không nên phụ thuộc vào nó.
2

Di chuyển các phần mở rộng kết quả công cụ nhúng sang middleware

Plugin đi kèm phải thay thế các trình xử lý kết quả công cụ api.registerEmbeddedExtensionFactory(...) chỉ dành cho trình chạy nhúng bằng middleware không phụ thuộc môi trường chạy:
Đồng thời cập nhật manifest plugin:
Plugin đã cài đặt cũng có thể đăng ký middleware kết quả công cụ khi được bật rõ ràng và mọi môi trường chạy đích đều được khai báo trong contracts.agentToolResultMiddleware. Các đăng ký middleware đã cài đặt nhưng chưa khai báo sẽ bị từ chối.
3

Di chuyển trình xử lý phê duyệt gốc sang dữ kiện năng lực

Plugin kênh hỗ trợ phê duyệt cung cấp hành vi phê duyệt gốc thông qua approvalCapability.nativeRuntime cùng registry ngữ cảnh môi trường chạy dùng chung:
  • Thay approvalCapability.handler.loadRuntime(...) bằng approvalCapability.nativeRuntime.
  • Chuyển xác thực/phân phối dành riêng cho phê duyệt khỏi hệ thống dây nối plugin.auth / plugin.approvals cũ sang approvalCapability.
  • ChannelPlugin.approvals đã bị loại bỏ khỏi hợp đồng plugin kênh công khai; chuyển các trường phân phối/gốc/kết xuất sang approvalCapability.
  • plugin.auth chỉ còn dành cho các luồng đăng nhập/đăng xuất kênh; lõi không còn đọc các hook xác thực phê duyệt tại đó.
  • Đăng ký các đối tượng môi trường chạy do kênh sở hữu (máy khách, token, ứng dụng Bolt) thông qua openclaw/plugin-sdk/channel-runtime-context.
  • Không gửi thông báo định tuyến lại do plugin sở hữu từ trình xử lý phê duyệt gốc; lõi sở hữu các thông báo đã định tuyến sang nơi khác dựa trên kết quả phân phối thực tế.
  • Khi truyền channelRuntime vào createChannelManager(...), hãy cung cấp một bề mặt createPluginRuntime().channel thực sự - các stub không đầy đủ sẽ bị từ chối.
Xem Plugin kênh để biết bố cục năng lực phê duyệt hiện tại.
4

Kiểm tra hành vi dự phòng của trình bao bọc Windows

Nếu plugin của bạn dùng openclaw/plugin-sdk/windows-spawn, các trình bao bọc Windows .cmd/.bat không phân giải được giờ đây sẽ đóng khi lỗi trừ khi bạn truyền rõ ràng allowShellFallback: true:
Nếu bên gọi của bạn không chủ ý phụ thuộc vào phương án dự phòng qua shell, đừng đặt allowShellFallback và thay vào đó hãy xử lý lỗi được ném ra.
5

Tìm các import đã ngừng hỗ trợ

6

Thay thế bằng các import tập trung

Mỗi phần xuất từ bề mặt cũ ánh xạ đến một đường dẫn import hiện đại cụ thể:
Đối với các trình trợ giúp phía máy chủ, hãy dùng runtime Plugin được chèn thay vì nhập trực tiếp:
Áp dụng cùng một mẫu cho các trình trợ giúp cầu nối cũ khác:
7

Thay thế các lệnh nhập infra-runtime phạm vi rộng

openclaw/plugin-sdk/infra-runtime vẫn tồn tại để duy trì khả năng tương thích bên ngoài, nhưng mã mới nên nhập bề mặt tập trung mà mã đó thực sự cần:Các Plugin đi kèm được trình quét bảo vệ khỏi infra-runtime, vì vậy mã trong kho lưu trữ không thể quay lại barrel phạm vi rộng.
8

Di chuyển các trình trợ giúp định tuyến kênh

Mã định tuyến kênh mới sử dụng openclaw/plugin-sdk/channel-route. Các tên khóa định tuyến cũ vẫn được giữ dưới dạng bí danh tương thích:Các trình trợ giúp định tuyến hiện đại chuẩn hóa { channel, to, accountId, threadId } một cách nhất quán trên phê duyệt gốc, chặn phản hồi, chống trùng lặp đầu vào, phân phối cron và định tuyến phiên.Không thêm cách sử dụng mới của ChannelMessagingAdapter.parseExplicitTarget hoặc resolveChannelRouteTargetWithParser(...) từ plugin-sdk/channel-route — chúng đã ngừng dùng và chỉ còn được giữ cho các Plugin cũ. Các Plugin kênh mới nên sử dụng messaging.targetResolver.resolveTarget(...) để chuẩn hóa mã định danh đích và dự phòng khi không tìm thấy trong thư mục, messaging.inferTargetChatType(...) khi lõi cần xác định sớm loại đối tác, và messaging.resolveOutboundSessionRoute(...) cho danh tính phiên và luồng gốc của nhà cung cấp.
9

Xây dựng và kiểm thử

​
Tham chiếu đường dẫn nhập

Bản đồ xuất gói công khai là nguồn đáng tin cậy cho các đường dẫn con SDK có thể nhập. Hãy dùng các hướng dẫn SDK theo chủ đề được liên kết từ tổng quan SDK và ưu tiên đường dẫn con công khai được ghi tài liệu có phạm vi hẹp nhất. Danh mục của trình biên dịch trong scripts/lib/plugin-sdk-entrypoints.json cũng chứa các mục riêng tư-cục bộ dùng để xây dựng các Plugin đi kèm; sự hiện diện của chúng tại đó không biến chúng thành các thành phần xuất công khai của gói. Bảng này là tập hợp con di chuyển thường dùng, không phải toàn bộ bề mặt SDK. Danh mục điểm vào của trình biên dịch nằm trong scripts/lib/plugin-sdk-entrypoints.json; các thành phần xuất của gói được tạo từ tập hợp con công khai. Các đường nối trình trợ giúp dành riêng cho Plugin đi kèm đã bị loại bỏ khỏi bản đồ xuất SDK công khai, ngoại trừ các facade tương thích được ghi tài liệu rõ ràng, chẳng hạn như shim plugin-sdk/discord đã ngừng dùng nhưng được giữ lại cho các Plugin bên ngoài vẫn nhập trực tiếp gói @openclaw/discord đã phát hành. Các trình trợ giúp dành riêng cho chủ sở hữu nằm trong gói Plugin sở hữu chúng; hành vi máy chủ dùng chung được chuyển qua các hợp đồng SDK chung như plugin-sdk/gateway-runtime, plugin-sdk/security-runtime và API Plugin được chèn. Hãy dùng lệnh nhập có phạm vi hẹp nhất phù hợp với công việc. Nếu không tìm thấy thành phần xuất, hãy kiểm tra mã nguồn tại src/plugin-sdk/ hoặc hỏi người bảo trì xem hợp đồng chung nào nên sở hữu thành phần đó.

​
Các bề mặt tương thích đã bị loại bỏ

Đợt rà soát tháng 7 năm 2026 đã loại bỏ SDK gốc và các barrel compat, cầu nối API tiện ích mở rộng, các bí danh đường dẫn con SDK đã hết hạn, các đường dẫn con SDK không dùng đến và các thành phần xuất công khai của những mô-đun SDK chỉ dành cho Plugin đi kèm. Các mô-đun chỉ dành cho Plugin đi kèm vẫn khả dụng cho chủ sở hữu của chúng trong kho lưu trữ thông qua ánh xạ bản dựng riêng tư-cục bộ; chúng không thể được nhập từ gói đã phát hành.

​
Công bố nhà cung cấp API toàn cục trong tiến trình

registerApiProvider(...) và unregisterApiProviders(...) đã bị loại bỏ khỏi openclaw/plugin-sdk/llm. Chúng công bố các phương thức truyền tải API vào trạng thái toàn cục trong tiến trình, khiến các runtime mô hình do vòng đời sở hữu sau đó phải sao chép chúng vào từng registry đã chuẩn bị. Các Plugin nhà cung cấp nên đăng ký nhà cung cấp suy luận văn bản thông qua api.registerProvider(...). Mã và kiểm thử do máy chủ sở hữu tạo ApiRegistry nên đăng ký trực tiếp trên registry đó để quyền sở hữu nhà cung cấp và quá trình tháo dỡ vẫn nằm trong phạm vi của runtime đã chuẩn bị.

​
Barrel kiểm thử riêng tư

openclaw/plugin-sdk/testing chỉ dùng cục bộ trong kho lưu trữ và bị loại khỏi các thành phần tạo tác của gói đã phát hành, vì vậy thành phần này đã bị loại bỏ trước ngày removeAfter 2026-07-28. Các kiểm thử trong kho lưu trữ sử dụng các đường dẫn con tập trung như plugin-sdk/plugin-test-runtime, plugin-sdk/channel-test-helpers, plugin-sdk/channel-target-testing, plugin-sdk/test-env và plugin-sdk/test-fixtures.

​
Tham chiếu di chuyển

Các ánh xạ này bao gồm cả những bề mặt bị loại bỏ vào tháng 7 năm 2026 và các thành phần đã ngừng dùng nhưng vẫn hoạt động trong khoảng thời gian sau đó. Một ánh xạ là hướng dẫn di chuyển, không phải bằng chứng cho thấy bề mặt cũ vẫn khả dụng; hãy tham khảo registry tương thích và tiến trình loại bỏ để biết trạng thái hiện tại.
Cũ (openclaw/plugin-sdk/command-auth): buildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage.Mới (openclaw/plugin-sdk/command-status): cùng chữ ký, được nhập từ đường dẫn con hẹp hơn. Các thành phần tái xuất tương thích command-auth đã bị loại bỏ.
Cũ: resolveMentionGating(params) và resolveMentionGatingWithBypass(params) từ openclaw/plugin-sdk/channel-inbound hoặc openclaw/plugin-sdk/channel-mention-gating.Mới: resolveInboundMentionDecision({ facts, policy }) — một đối tượng quyết định thay cho hai dạng lời gọi tách biệt.Đã được áp dụng trên Discord, iMessage, Matrix, MS Teams, QQBot, Signal, Telegram, WhatsApp và Zalo. Mô hình sự kiện app_mention riêng của Slack không sử dụng trình trợ giúp này.
openclaw/plugin-sdk/channel-runtime đã bị loại bỏ. Hãy dùng openclaw/plugin-sdk/channel-runtime-context để đăng ký các đối tượng runtime.Các trình trợ giúp lược đồ tin nhắn gốc trong openclaw/plugin-sdk/channel-actions đã bị loại bỏ cùng với các thành phần xuất hành động thô của kênh. Thay vào đó, hãy cung cấp các khả năng thông qua bề mặt ngữ nghĩa presentation — các Plugin kênh khai báo nội dung chúng kết xuất (thẻ, nút, trình chọn), thay vì tên hành động thô mà chúng chấp nhận.
Cũ: factory tool() từ openclaw/plugin-sdk/provider-web-search.Mới: triển khai trực tiếp createTool(...) trên Plugin nhà cung cấp. OpenClaw không còn cần trình trợ giúp SDK để đăng ký trình bao bọc công cụ.
Cũ: api.runtime.channel.reply.formatInboundEnvelope(...) (và trường channelEnvelope trên các đối tượng tin nhắn đầu vào) để xây dựng phong bì lời nhắc văn bản thuần dạng phẳng từ tin nhắn kênh đầu vào.Mới: BodyForAgent cùng các khối ngữ cảnh người dùng có cấu trúc. Các Plugin kênh đính kèm siêu dữ liệu định tuyến (luồng, chủ đề, phản hồi đến, biểu cảm) dưới dạng trường có kiểu thay vì nối chúng vào chuỗi lời nhắc. Trình trợ giúp formatAgentEnvelope(...) vẫn được hỗ trợ cho các phong bì tổng hợp hướng đến trợ lý, nhưng phong bì văn bản thuần đầu vào đang dần bị loại bỏ.Các khu vực bị ảnh hưởng: inbound_claim, message_received và mọi Plugin kênh tùy chỉnh đã hậu xử lý văn bản phong bì cũ.
Cũ: api.on("deactivate", handler).Mới: api.on("gateway_stop", handler). Cùng hợp đồng dọn dẹp khi tắt; chỉ tên hook thay đổi.
deactivate vẫn được nối dây dưới dạng bí danh tương thích đã ngừng dùng cho đến khi bị loại bỏ sau 2026-08-16.
Cũ: api.on("subagent_spawning", handler) trả về threadBindingReady hoặc deliveryOrigin.Mới: để lõi chuẩn bị các liên kết tác tử con thread: true thông qua bộ điều hợp liên kết phiên kênh. Chỉ dùng api.on("subagent_spawned", handler) để quan sát sau khi khởi chạy.
subagent_spawning, PluginHookSubagentSpawningEvent, PluginHookSubagentSpawningResult và SubagentLifecycleHookRunner.runSubagentSpawning(...) chỉ còn được giữ dưới dạng bề mặt tương thích đã ngừng dùng trong khi các Plugin bên ngoài di chuyển và sẽ bị loại bỏ sau 2026-08-30.
Bốn bí danh kiểu khám phá hiện là các trình bao bọc mỏng quanh những kiểu của thời kỳ danh mục:Các bí danh và túi tĩnh ProviderCapabilities cũ đã bị loại bỏ. Các Plugin nhà cung cấp nên sử dụng các hook nhà cung cấp rõ ràng như buildReplayPolicy, normalizeToolSchemas và wrapStreamFn thay vì một đối tượng tĩnh.
Cũ (ba hook riêng biệt trên ProviderThinkingPolicy): isBinaryThinking(ctx), supportsXHighThinking(ctx) và resolveDefaultThinkingLevel(ctx).Mới: một resolveThinkingProfile(ctx) duy nhất trả về một ProviderThinkingProfile với id chuẩn, label tùy chọn và một danh sách cấp độ được xếp hạng. OpenClaw tự động hạ cấp các giá trị cũ đã lưu theo thứ hạng hồ sơ.Ngữ cảnh bao gồm các dữ kiện provider, modelId, reasoning đã hợp nhất tùy chọn và compat mô hình đã hợp nhất tùy chọn. Các plugin nhà cung cấp có thể dùng những dữ kiện danh mục đó để chỉ cung cấp hồ sơ dành riêng cho mô hình khi hợp đồng yêu cầu đã cấu hình hỗ trợ hồ sơ đó.Triển khai một hook thay vì ba. Các hook cũ đã bị loại bỏ.
Cũ: triển khai các hook xác thực bên ngoài mà không khai báo nhà cung cấp trong manifest của plugin.Mới: khai báo contracts.externalAuthProviders trong manifest của plugin và triển khai resolveExternalAuthProfiles(...).
Trường manifest cũ: providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }.Mới: sao chép cùng cơ chế tra cứu biến môi trường vào setup.providers[].envVars trong manifest. Việc này hợp nhất siêu dữ liệu môi trường thiết lập/trạng thái tại một nơi và tránh phải khởi động runtime của plugin chỉ để xử lý tra cứu biến môi trường.providerAuthEnvVars không còn được chấp nhận.
Cũ: ba lệnh gọi riêng biệt - api.registerMemoryPromptSection(...), api.registerMemoryFlushPlan(...), api.registerMemoryRuntime(...).Mới: một lệnh gọi trên API trạng thái bộ nhớ - registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime }).Các vị trí như cũ, một lệnh gọi đăng ký duy nhất. Các trình trợ giúp bổ sung cho lời nhắc và kho ngữ liệu (registerMemoryPromptSupplement, registerMemoryCorpusSupplement) không bị ảnh hưởng.
Cũ: api.registerMemoryEmbeddingProvider(...) cùng với contracts.memoryEmbeddingProviders.Mới: api.registerEmbeddingProvider(...) cùng với contracts.embeddingProviders.Hợp đồng nhà cung cấp embedding chung có thể tái sử dụng bên ngoài bộ nhớ và là phương thức được hỗ trợ cho các nhà cung cấp mới. API đăng ký dành riêng cho bộ nhớ vẫn được kết nối dưới dạng tương thích không còn khuyến nghị trong khi các nhà cung cấp hiện có di chuyển. Hoạt động kiểm tra plugin báo cáo việc sử dụng không đi kèm gói là nợ tương thích.
Cũ: trả về { ok, messageId, error } thông qua ChannelSendRawResult và chuẩn hóa bằng createRawChannelSendResultAdapter(...).Mới: trả về các trường OutboundDeliveryResult và đính kèm kênh bằng createAttachedChannelResultAdapter(...). Các lần gửi thất bại phải phát sinh ngoại lệ thay vì trả về chuỗi lỗi. Kiểu kết quả thô vẫn khả dụng cho đến bản phát hành lớn tiếp theo của plugin-SDK.
Hai bí danh kiểu cũ vẫn được xuất từ src/plugins/runtime/types.ts:Phương thức runtime readSession không còn được khuyến nghị; hãy dùng getSessionMessages. Chữ ký giữ nguyên; phương thức cũ chuyển tiếp lệnh gọi sang phương thức mới.
Việc chuyển phiên/bản chép lời sang SQLite loại bỏ hoặc đánh dấu không còn khuyến nghị các API dành cho plugin từng cung cấp kho sessions.json đang hoạt động, đường dẫn bản chép lời JSONL hoặc danh sách tệp phiên. Các plugin runtime nên dùng danh tính phiên và các trình trợ giúp runtime của SDK thay vì phân giải hoặc sửa đổi các tệp đang hoạt động.Các tệp bản chép lời JSONL cũ vẫn hợp lệ dưới dạng hiện vật nhập, lưu trữ, xuất và hỗ trợ. Chúng không còn là hợp đồng runtime ổn định cho các phiên đang hoạt động.Các plugin chính thức được phát hành cùng v2026.7.1-beta.5 đã nhập bốn trình trợ giúp không còn được khuyến nghị ở trên. openclaw/plugin-sdk/session-store-runtime duy trì chính xác cầu nối đó đến hết 2026-10-12; các plugin mới phải dùng phương án thay thế. resolveStorePath(...) vẫn là một trình trợ giúp SDK được hỗ trợ và không thuộc phạm vi ngừng hỗ trợ này.openclaw plugins inspect --all --runtime báo cáo các plugin không đi kèm gói có lỗi tải hoặc chẩn đoán vẫn tham chiếu đến các API tệp đã bị loại bỏ này. Đợt quét tư vấn @openclaw/plugin-inspector phải dùng phiên bản 0.3.17 trở lên để quá trình quét gói bên ngoài cũng gắn cờ các trình trợ giúp phiên toàn kho, trình trợ giúp đường dẫn tệp phiên, đích tệp bản chép lời cũ và các trình trợ giúp bản chép lời cấp thấp trước khi phát hành.
Cũ: runtime.tasks.flow (số ít) trả về một trình truy cập luồng tác vụ trực tiếp.Mới: runtime.tasks.managedFlows duy trì runtime sửa đổi TaskFlow được quản lý cho các plugin tạo, cập nhật, hủy hoặc chạy tác vụ con từ một luồng. Dùng runtime.tasks.flows khi plugin chỉ cần thao tác đọc dựa trên DTO.
Các bí danh cũ đã bị loại bỏ vào tháng 7 năm 2026.
Đã trình bày trong phần Cách di chuyển ở trên. Nội dung này được đưa vào đây để đầy đủ: đường dẫn api.registerEmbeddedExtensionFactory(...) chỉ dành cho trình chạy nhúng đã bị loại bỏ được thay thế bằng api.registerAgentToolResultMiddleware(...) với danh sách runtime rõ ràng trong contracts.agentToolResultMiddleware.
Bí danh SDK gốc OpenClawSchemaType đã bị loại bỏ. Dùng tên chuẩn OpenClawConfig.
Các nội dung không còn được khuyến nghị ở cấp tiện ích mở rộng (bên trong các plugin kênh/nhà cung cấp đi kèm gói thuộc extensions/) được theo dõi trong các barrel api.ts và runtime-api.ts riêng. Chúng không ảnh hưởng đến hợp đồng plugin của bên thứ ba và không được liệt kê ở đây. Nếu sử dụng trực tiếp barrel cục bộ của một plugin đi kèm gói, hãy đọc các nhận xét về nội dung không còn được khuyến nghị trong barrel đó trước khi nâng cấp.

​
Di chuyển Talk và giọng nói thời gian thực

Mã giọng nói thời gian thực, điện thoại, cuộc họp và Talk trên trình duyệt dùng chung một trình điều khiển phiên Talk được xuất bởi openclaw/plugin-sdk/realtime-voice. Trình điều khiển sở hữu phong bì sự kiện Talk chung, trạng thái lượt đang hoạt động, trạng thái thu âm, trạng thái âm thanh đầu ra, lịch sử sự kiện gần đây và cơ chế từ chối lượt cũ. Các plugin nhà cung cấp sở hữu phiên thời gian thực dành riêng cho nhà cung cấp. Các plugin cuộc họp trên trình duyệt dùng openclaw/plugin-sdk/meeting-runtime cho cơ chế phiên, trình duyệt, âm thanh, máy chủ node, tư vấn agent và cuộc gọi thoại, sau đó triển khai MeetingPlatformAdapter cho quy tắc URL, tập lệnh DOM, ánh xạ thao tác thủ công, phụ đề, tạo cuộc họp và kế hoạch quay số tham gia. API REST nền tảng, OAuth, hiện vật, bộ chọn và tên trên đường truyền vẫn nằm trong plugin. Kế hoạch quyền của trình duyệt nhận URL cuộc họp được yêu cầu để mỗi nền tảng chỉ có thể cấp quyền cho chính xác các nguồn được hỗ trợ. Runtime phiên cũng phải chuẩn hóa tình trạng hoạt động trực tiếp dành riêng cho nền tảng sau khi xác nhận rời trình duyệt; các trường bản chép lời lịch sử có thể được giữ lại, nhưng trạng thái sẵn sàng của phụ đề và âm thanh không được tiếp tục hoạt động sau khi rời đi. Tất cả bề mặt đi kèm gói đều chạy trên trình điều khiển dùng chung: chuyển tiếp trình duyệt, chuyển giao phòng được quản lý, thời gian thực của cuộc gọi thoại, STT phát trực tuyến của cuộc gọi thoại, thời gian thực của Google Meet và nhấn để nói nguyên bản. Gateway quảng bá một kênh sự kiện Talk trực tiếp trong hello-ok.features.events: talk.event. Mã mới không nên gọi trực tiếp createTalkEventSequencer(...) trừ khi triển khai bộ điều hợp cấp thấp hoặc fixture kiểm thử. Hãy dùng trình điều khiển dùng chung để các sự kiện theo phạm vi lượt không thể được phát mà thiếu id lượt, các lệnh gọi turnEnd / turnCancel cũ không thể xóa một lượt đang hoạt động mới hơn và các sự kiện vòng đời âm thanh đầu ra luôn nhất quán trên điện thoại, cuộc họp, chuyển tiếp trình duyệt, chuyển giao phòng được quản lý và các máy khách Talk nguyên bản. Hình dạng API công khai:
Các phiên WebRTC/websocket nhà cung cấp do trình duyệt sở hữu dùng talk.client.create, vì trình duyệt sở hữu việc thương lượng với nhà cung cấp và truyền tải phương tiện, còn Gateway sở hữu thông tin xác thực, chỉ dẫn và chính sách công cụ. talk.session.* là bề mặt chung do Gateway quản lý cho thời gian thực qua gateway-relay, phiên chép lời qua gateway-relay và các phiên STT/TTS nguyên bản trong phòng được quản lý. Các cấu hình cũ đặt bộ chọn thời gian thực cạnh talk.provider / talk.providers nên được sửa bằng openclaw doctor --fix; Talk runtime không diễn giải lại cấu hình nhà cung cấp giọng nói/TTS thành cấu hình nhà cung cấp thời gian thực. Các tổ hợp talk.session.create được hỗ trợ được chủ ý giới hạn: Bản đồ phương thức dành cho người đọc đang di chuyển từ các nhóm talk.realtime.* / talk.transcription.* / talk.handoff.* cũ (đều đã bị xóa): Tập thuật ngữ điều khiển hợp nhất cũng được chủ ý giới hạn: Không đưa các trường hợp đặc biệt theo nhà cung cấp hoặc nền tảng vào core để tính năng này hoạt động. Core sở hữu ngữ nghĩa phiên Talk. Các plugin nhà cung cấp sở hữu việc thiết lập phiên của nhà cung cấp. Voice-call và Google Meet sở hữu các adapter điện thoại/cuộc họp. Trình duyệt và ứng dụng native sở hữu UX thu/phát trên thiết bị.

​
Lịch trình loại bỏ

Các đường dẫn con SDK công khai còn lại bên dưới có thời hạn loại bỏ được registry hỗ trợ. Các hàng ngày 30 tháng 7 đã bị loại bỏ sau đợt rà soát sớm được người bảo trì cho phép: các đường dẫn con không được sử dụng đã bị xóa, các bí danh tương thích trước đó đã bị xóa và các mô-đun chỉ dành cho bản đi kèm đã được hạ xuống thành ánh xạ bản dựng cục bộ riêng tư. Tất cả plugin core đã được di chuyển. Các plugin bên ngoài nên di chuyển trước bản phát hành lớn tiếp theo. Chạy pnpm plugins:boundary-report để xem các bản ghi tương thích nào sắp đến hạn nhất đối với những bề mặt mà plugin của bạn sử dụng.

​
Tạm thời tắt các cảnh báo

Đây là lối thoát tạm thời, không phải giải pháp lâu dài.

​
Liên quan