插件 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.
openclaw/plugin-sdk/ 下的一组窄公共子路径公开。本页按用途分组列出常用子路径。生成的编译器入口点清单位于 scripts/lib/plugin-sdk-entrypoints.json;包导出是在减去 scripts/lib/plugin-sdk-private-local-only-subpaths.json 中列出的仓库本地测试/内部子路径之后的公共子集。维护者可以用 pnpm plugin-sdk:surface 审计公共导出数量,并用 pnpm plugins:boundary-report:summary 审计活跃的保留 helper 子路径;未使用的保留 helper 导出会让 CI 报告失败,而不是作为休眠的兼容性债务留在公共 SDK 中。
有关插件编写指南,请参阅 插件 SDK 概览。
插件入口
| 子路径 | 主要导出 |
|---|---|
plugin-sdk/plugin-entry | definePluginEntry |
plugin-sdk/core | defineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema, buildJsonChannelConfigSchema |
plugin-sdk/config-schema | OpenClawSchema |
plugin-sdk/provider-entry | defineSingleProviderPluginEntry |
plugin-sdk/migration | Migration 提供商条目 helper,例如 createMigrationItem、原因常量、条目状态标记、密文遮蔽 helper 和 summarizeMigrationItems |
plugin-sdk/migration-runtime | 运行时 migration helper,例如 copyMigrationFileItem、withCachedMigrationConfigRuntime 和 writeMigrationReport |
已弃用的兼容性和测试 helper
这些子路径仍作为旧插件和 OpenClaw 测试套件的包导出保留,但新代码不应再从它们添加导入:agent-runtime-test-contracts、channel-contract-testing、channel-target-testing、channel-test-helpers、plugin-test-api、plugin-test-contracts、provider-http-test-mocks、provider-test-contracts、test-env、test-fixtures、test-node-mocks、testing、channel-runtime、compat、config-types、infra-runtime、text-runtime 和 zod。新的插件代码应直接从 zod 导入 zod。plugin-test-runtime 仍是活跃的聚焦测试 helper 子路径。
已弃用的未使用公共子路径
这些公共子路径已存在至少一个月,并且目前没有内置插件生产导入。它们仍可导入以保持兼容性,但新的插件代码应改用聚焦且正在被积极使用的 SDK 子路径:agent-config-primitives、channel-config-schema-legacy、channel-reply-pipeline、channel-runtime、channel-secret-runtime、command-auth、compat、config-runtime、config-schema、discord、group-access、infra-runtime、matrix、mattermost、media-generation-runtime-shared、memory-core-engine-runtime、memory-core-host-multimodal、memory-core-host-query、music-generation-core、self-hosted-provider-setup、telegram-account、telegram-command-config 和 zalouser。
已弃用的少用公共子路径
目前仅被一两个内置插件所有者使用的公共子路径,也已对新的插件代码弃用。它们仍作为包导出保留以保持兼容性,但新代码应优先使用正在被积极共享的 SDK 接口,或插件自有的包 API。维护者会在scripts/lib/plugin-sdk-deprecated-public-subpaths.json 中跟踪准确集合,并用 pnpm plugin-sdk:surface 跟踪当前预算。
已弃用的宽泛 barrel
这些宽泛的重新导出 barrel 对 OpenClaw 源代码和兼容性检查仍可构建,但新代码应优先使用聚焦的 SDK 子路径:agent-runtime、channel-lifecycle、channel-runtime、cli-runtime、compat、config-types、conversation-runtime、hook-runtime、infra-runtime、media-runtime、plugin-runtime、security-runtime 和 text-runtime。channel-runtime、compat、config-types、infra-runtime 和 text-runtime 仅为向后兼容而继续作为包导出保留;请改用聚焦的频道/运行时子路径、config-contracts、string-coerce-runtime、text-chunking、text-utility-runtime 和 logging-core。
渠道子路径
渠道子路径
| 子路径 | 关键导出 |
|---|---|
plugin-sdk/channel-core | defineChannelPluginEntry、defineSetupPluginEntry、createChatChannelPlugin、createChannelPluginBase |
plugin-sdk/config-schema | 根 openclaw.json Zod 模式导出(OpenClawSchema) |
plugin-sdk/json-schema-runtime | 用于插件自有模式的缓存 JSON Schema 验证辅助工具 |
plugin-sdk/channel-setup | createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、createOptionalChannelSetupWizard,以及 DEFAULT_ACCOUNT_ID、createTopLevelChannelDmPolicy、setSetupChannelEnabled、splitSetupEntries |
plugin-sdk/setup | 共享设置向导辅助工具、允许列表提示、设置状态构建器 |
plugin-sdk/setup-runtime | createPatchedAccountSetupAdapter、createEnvPatchedAccountSetupAdapter、createSetupInputPresenceValidator、noteChannelLookupFailure、noteChannelLookupSummary、promptResolvedAllowFrom、splitSetupEntries、createAllowlistSetupWizardProxy、createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | 已弃用的兼容别名;请使用 plugin-sdk/setup-runtime |
plugin-sdk/setup-tools | formatCliCommand、detectBinary、extractArchive、resolveBrewExecutable、formatDocsLink、CONFIG_DIR |
plugin-sdk/account-core | 多账号配置/操作门控辅助工具、默认账号回退辅助工具 |
plugin-sdk/account-id | DEFAULT_ACCOUNT_ID、账号 ID 规范化辅助工具 |
plugin-sdk/account-resolution | 账号查找 + 默认回退辅助工具 |
plugin-sdk/account-helpers | 精简账号列表/账号操作辅助工具 |
plugin-sdk/access-groups | 访问组允许列表解析和已脱敏组诊断辅助工具 |
plugin-sdk/channel-pairing | createChannelPairingController |
plugin-sdk/channel-reply-pipeline | 旧版回复管线辅助工具。新的渠道回复管线代码应使用 plugin-sdk/channel-message 中的 createChannelMessageReplyPipeline 和 resolveChannelMessageSourceReplyDeliveryMode。 |
plugin-sdk/channel-config-helpers | createHybridChannelConfigAdapter、resolveChannelDmAccess、resolveChannelDmAllowFrom、resolveChannelDmPolicy、normalizeChannelDmPolicy、normalizeLegacyDmAliases |
plugin-sdk/channel-config-schema | 共享渠道配置模式基元,以及 Zod 和直接 JSON/TypeBox 构建器 |
plugin-sdk/bundled-channel-config-schema | 仅供维护的内置插件使用的内置 OpenClaw 渠道配置模式 |
plugin-sdk/channel-config-schema-legacy | 内置渠道配置模式的已弃用兼容别名 |
plugin-sdk/telegram-command-config | Telegram 自定义命令规范化/验证辅助工具,带内置契约回退 |
plugin-sdk/command-gating | 精简命令授权门控辅助工具 |
plugin-sdk/channel-policy | resolveChannelGroupRequireMention |
plugin-sdk/channel-ingress | 已弃用的低层渠道入口兼容门面。新的接收路径应使用 plugin-sdk/channel-ingress-runtime。 |
plugin-sdk/channel-ingress-runtime | 实验性的高层渠道入口运行时解析器和路由事实构建器,用于已迁移的渠道接收路径。优先使用它,而不是在每个插件中组装有效允许列表、命令允许列表和旧版投影。参见 频道入口 API。 |
plugin-sdk/channel-lifecycle | createAccountStatusSink、createChannelRunQueue 和旧版草稿流生命周期辅助工具。新的预览终结代码应使用 plugin-sdk/channel-message。 |
plugin-sdk/channel-message | 低成本消息生命周期契约辅助工具,例如 defineChannelMessageAdapter、createChannelMessageAdapterFromOutbound、createChannelMessageReplyPipeline、createReplyPrefixContext、resolveChannelMessageSourceReplyDeliveryMode、持久最终能力派生、发送/回执/副作用能力的能力证明辅助工具、MessageReceiveContext、接收确认策略证明、defineFinalizableLivePreviewAdapter、deliverWithFinalizableLivePreviewAdapter、实时预览和实时终结器能力证明、持久恢复状态、RenderedMessageBatch、消息回执类型和回执 ID 辅助工具。参见 频道消息 API。旧版回复分发门面仅作为已弃用兼容项。 |
plugin-sdk/channel-message-runtime | 可能加载出站投递的运行时投递辅助工具,包括 deliverInboundReplyWithMessageSendContext、sendDurableMessageBatch 和 withDurableMessageSendContext。已弃用的回复分发桥仍可导入,但仅用于兼容调度器。请在监控/发送运行时模块中使用,而不是在热插件启动文件中使用。 |
plugin-sdk/inbound-envelope | 共享入站路由 + 信封构建器辅助工具 |
plugin-sdk/inbound-reply-dispatch | 旧版共享入站记录并分发辅助工具、可见/最终分发谓词,以及用于预备渠道调度器的已弃用 deliverDurableInboundReplyPayload 兼容项。新的渠道接收/分发代码应从 plugin-sdk/channel-message-runtime 导入运行时生命周期辅助工具。 |
plugin-sdk/messaging-targets | 目标解析/匹配辅助工具 |
plugin-sdk/outbound-media | 共享出站媒体加载辅助工具 |
plugin-sdk/outbound-send-deps | 面向渠道适配器的轻量出站发送依赖查找 |
plugin-sdk/outbound-runtime | 出站身份、发送委托、会话、格式化和负载规划辅助工具。deliverOutboundPayloads 等直接投递辅助工具是已弃用的兼容底层;新的发送路径请使用 plugin-sdk/channel-message-runtime。 |
plugin-sdk/poll-runtime | 精简投票规范化辅助工具 |
plugin-sdk/thread-bindings-runtime | 线程绑定生命周期和适配器辅助工具 |
plugin-sdk/agent-media-payload | 旧版智能体媒体负载构建器 |
plugin-sdk/conversation-runtime | 对话/线程绑定、配对和已配置绑定辅助工具 |
plugin-sdk/runtime-config-snapshot | 运行时配置快照辅助工具 |
plugin-sdk/runtime-group-policy | 运行时组策略解析辅助工具 |
plugin-sdk/channel-status | 共享渠道状态快照/摘要辅助工具 |
plugin-sdk/channel-config-primitives | 精简渠道配置模式基元 |
plugin-sdk/channel-config-writes | 渠道配置写入授权辅助工具 |
plugin-sdk/channel-plugin-common | 共享渠道插件前置导出 |
plugin-sdk/allowlist-config-edit | 允许列表配置编辑/读取辅助工具 |
plugin-sdk/group-access | 共享组访问决策辅助工具 |
plugin-sdk/direct-dm | 共享直接私信认证/守卫辅助工具 |
plugin-sdk/discord | 已弃用的 Discord 兼容门面,用于已发布的 @openclaw/discord@2026.3.13 和跟踪的所有者兼容性;新插件应使用通用渠道 SDK 子路径 |
plugin-sdk/telegram-account | 已弃用的 Telegram 账号解析兼容门面,用于跟踪的所有者兼容性;新插件应使用注入的运行时辅助工具或通用渠道 SDK 子路径 |
plugin-sdk/zalouser | 已弃用的 Zalo Personal 兼容门面,用于仍在导入发送者命令授权的已发布 Lark/Zalo 包;新插件应使用 plugin-sdk/command-auth |
plugin-sdk/interactive-runtime | 语义消息呈现、投递和旧版交互式回复辅助工具。参见 Message Presentation |
plugin-sdk/channel-inbound | 入站防抖、提及匹配、提及策略辅助工具和信封辅助工具的兼容桶 |
plugin-sdk/channel-inbound-debounce | 精简入站防抖辅助工具 |
plugin-sdk/channel-mention-gating | 精简提及策略、提及标记和提及文本辅助工具,不包含更宽泛的入站运行时表面 |
plugin-sdk/channel-envelope | 精简入站信封格式化辅助工具 |
plugin-sdk/channel-location | 渠道位置上下文和格式化辅助工具 |
plugin-sdk/channel-logging | 用于入站丢弃和输入/确认失败的渠道日志辅助工具 |
plugin-sdk/channel-send-result | 回复结果类型 |
plugin-sdk/channel-actions | 渠道消息操作辅助工具,以及为插件兼容性保留的已弃用原生模式辅助工具 |
plugin-sdk/channel-route | 共享路由规范化、解析器驱动的目标解析、线程 ID 字符串化、去重/紧凑路由键、已解析目标类型,以及路由/目标比较辅助工具 |
plugin-sdk/channel-targets | 目标解析辅助工具;路由比较调用方应使用 plugin-sdk/channel-route |
plugin-sdk/channel-contract | 渠道契约类型 |
plugin-sdk/channel-feedback | 反馈/反应接线 |
plugin-sdk/channel-secret-runtime | 精简密钥契约辅助工具,例如 collectSimpleChannelFieldAssignments、getChannelSurface、pushAssignment 和密钥目标类型 |
提供商子路径
提供商子路径
认证和安全子路径
认证和安全子路径
| 子路径 | 主要导出 |
|---|---|
plugin-sdk/command-auth | resolveControlCommandGate,命令注册表辅助函数,包括动态参数菜单格式化、发送者授权辅助函数 |
plugin-sdk/command-status | 命令/帮助消息构建器,例如 buildCommandsMessagePaginated 和 buildHelpMessage |
plugin-sdk/approval-auth-runtime | 审批者解析和同聊天操作认证辅助函数 |
plugin-sdk/approval-client-runtime | 原生 exec 审批配置文件/过滤器辅助函数 |
plugin-sdk/approval-delivery-runtime | 原生审批能力/投递适配器 |
plugin-sdk/approval-gateway-runtime | 共享审批 Gateway 网关解析辅助函数 |
plugin-sdk/approval-handler-adapter-runtime | 用于热渠道入口点的轻量级原生审批适配器加载辅助函数 |
plugin-sdk/approval-handler-runtime | 更宽泛的审批处理器运行时辅助函数;当更窄的适配器/Gateway 网关接缝足够时,优先使用它们 |
plugin-sdk/approval-native-runtime | 原生审批目标 + 账号绑定辅助函数 |
plugin-sdk/approval-reply-runtime | Exec/插件审批回复载荷辅助函数 |
plugin-sdk/approval-runtime | Exec/插件审批载荷辅助函数、原生审批路由/运行时辅助函数,以及结构化审批显示辅助函数,例如 formatApprovalDisplayPath |
plugin-sdk/reply-dedupe | 窄范围入站回复去重重置辅助函数 |
plugin-sdk/channel-contract-testing | 不带宽泛测试 barrel 的窄范围渠道契约测试辅助函数 |
plugin-sdk/command-auth-native | 原生命令认证、动态参数菜单格式化,以及原生会话目标辅助函数 |
plugin-sdk/command-detection | 共享命令检测辅助函数 |
plugin-sdk/command-primitives-runtime | 用于热渠道路径的轻量级命令文本谓词 |
plugin-sdk/command-surface | 命令正文规范化和命令表面辅助函数 |
plugin-sdk/allow-from | formatAllowFromLowercase |
plugin-sdk/channel-secret-runtime | 用于渠道/插件密钥表面的窄范围密钥契约收集辅助函数 |
plugin-sdk/secret-ref-runtime | 用于密钥契约/配置解析的窄范围 coerceSecretRef 和 SecretRef 类型辅助函数 |
plugin-sdk/security-runtime | 共享的信任、私信门控、根目录边界文件/路径辅助函数,包括仅创建写入、同步/异步原子文件替换、同级临时写入、跨设备移动回退、私有文件存储辅助函数、符号链接父级防护、外部内容、敏感文本脱敏、常量时间密钥比较,以及密钥收集辅助函数 |
plugin-sdk/ssrf-policy | 主机允许列表和私有网络 SSRF 策略辅助函数 |
plugin-sdk/ssrf-dispatcher | 不带宽泛基础设施运行时表面的窄范围固定调度器辅助函数 |
plugin-sdk/ssrf-runtime | 固定调度器、SSRF 保护的 fetch、SSRF 错误,以及 SSRF 策略辅助函数 |
plugin-sdk/secret-input | 密钥输入解析辅助函数 |
plugin-sdk/webhook-ingress | Webhook 请求/目标辅助函数和原始 websocket/body 强制转换 |
plugin-sdk/webhook-request-guards | 请求正文大小/超时辅助函数 |
运行时和存储子路径
运行时和存储子路径
能力和测试子路径
能力和测试子路径
| 子路径 | 主要导出 |
|---|---|
plugin-sdk/media-runtime | 共享媒体获取/转换/存储辅助工具、基于 ffprobe 的视频尺寸探测,以及媒体载荷构建器 |
plugin-sdk/media-mime | 精准 MIME 规范化、文件扩展名映射、MIME 检测,以及媒体类型辅助工具 |
plugin-sdk/media-store | 精准媒体存储辅助工具,例如 saveMediaBuffer |
plugin-sdk/media-generation-runtime | 共享媒体生成故障转移辅助工具、候选项选择,以及缺失模型消息 |
plugin-sdk/media-understanding | 媒体理解提供商类型,以及面向提供商的图像/音频/结构化提取辅助工具导出 |
plugin-sdk/text-chunking | 文本和 markdown 分块/渲染辅助工具、markdown 表格转换、指令标签剥离,以及安全文本实用工具 |
plugin-sdk/text-chunking | 出站文本分块辅助工具 |
plugin-sdk/speech | 语音提供商类型,以及面向提供商的指令、注册表、校验、OpenAI 兼容 TTS 构建器和语音辅助工具导出 |
plugin-sdk/speech-core | 共享语音提供商类型、注册表、指令、规范化,以及语音辅助工具导出 |
plugin-sdk/realtime-transcription | 实时转录提供商类型、注册表辅助工具,以及共享 WebSocket 会话辅助工具 |
plugin-sdk/realtime-voice | 实时语音提供商类型和注册表辅助工具 |
plugin-sdk/image-generation | 图像生成提供商类型,以及图像资源/data URL 辅助工具和 OpenAI 兼容图像提供商构建器 |
plugin-sdk/image-generation-core | 共享图像生成类型、故障转移、认证,以及注册表辅助工具 |
plugin-sdk/music-generation | 音乐生成提供商/请求/结果类型 |
plugin-sdk/music-generation-core | 共享音乐生成类型、故障转移辅助工具、提供商查找,以及模型引用解析 |
plugin-sdk/video-generation | 视频生成提供商/请求/结果类型 |
plugin-sdk/video-generation-core | 共享视频生成类型、故障转移辅助工具、提供商查找,以及模型引用解析 |
plugin-sdk/webhook-targets | Webhook 目标注册表和路由安装辅助工具 |
plugin-sdk/webhook-path | 已弃用的兼容性别名;请使用 plugin-sdk/webhook-ingress |
plugin-sdk/web-media | 共享远程/本地媒体加载辅助工具 |
plugin-sdk/zod | 已弃用的兼容性重新导出;请直接从 zod 导入 zod |
plugin-sdk/testing | 面向旧版 OpenClaw 测试的仓库本地已弃用兼容性汇总导出。新的仓库测试应改为导入聚焦的本地测试子路径,例如 plugin-sdk/agent-runtime-test-contracts、plugin-sdk/plugin-test-runtime、plugin-sdk/channel-test-helpers、plugin-sdk/test-env 或 plugin-sdk/test-fixtures |
plugin-sdk/plugin-test-api | 仓库本地最小 createTestPluginApi 辅助工具,用于不导入仓库测试辅助桥接的直接插件注册单元测试 |
plugin-sdk/agent-runtime-test-contracts | 仓库本地原生智能体运行时适配器契约夹具,用于认证、投递、回退、工具钩子、提示词覆盖层、schema 和 transcript 投影测试 |
plugin-sdk/channel-test-helpers | 仓库本地面向渠道的测试辅助工具,用于通用操作/设置/状态契约、目录断言、账号启动生命周期、发送配置线程化、运行时 mock、状态问题、出站投递和钩子注册 |
plugin-sdk/channel-target-testing | 仓库本地共享目标解析错误用例套件,用于渠道测试 |
plugin-sdk/plugin-test-contracts | 仓库本地插件包、注册、公共工件、直接导入、运行时 API 和导入副作用契约辅助工具 |
plugin-sdk/provider-test-contracts | 仓库本地提供商运行时、认证、设备发现、新手引导、目录、向导、媒体能力、重放策略、实时 STT 现场音频、Web 搜索/获取,以及流契约辅助工具 |
plugin-sdk/provider-http-test-mocks | 仓库本地可选启用的 Vitest HTTP/auth mock,用于覆盖 plugin-sdk/provider-http 的提供商测试 |
plugin-sdk/test-fixtures | 仓库本地通用 CLI 运行时捕获、沙箱上下文、技能写入器、智能体消息、系统事件、模块重载、内置插件路径、终端文本、分块、认证令牌和类型化用例夹具 |
plugin-sdk/test-node-mocks | 仓库本地聚焦的 Node 内置 mock 辅助工具,用于 Vitest vi.mock("node:*") 工厂内部 |
记忆子路径
记忆子路径
| 子路径 | 主要导出 |
|---|---|
plugin-sdk/memory-core | 面向管理器/配置/文件/CLI 辅助工具的内置 memory-core 辅助表面 |
plugin-sdk/memory-core-engine-runtime | 记忆索引/搜索运行时门面 |
plugin-sdk/memory-core-host-engine-foundation | 记忆宿主基础引擎导出 |
plugin-sdk/memory-core-host-engine-embeddings | 记忆宿主嵌入契约、注册表访问、本地提供商,以及通用批处理/远程辅助工具 |
plugin-sdk/memory-core-host-engine-qmd | 记忆宿主 QMD 引擎导出 |
plugin-sdk/memory-core-host-engine-storage | 记忆宿主存储引擎导出 |
plugin-sdk/memory-core-host-multimodal | 记忆宿主多模态辅助工具 |
plugin-sdk/memory-core-host-query | 记忆宿主查询辅助工具 |
plugin-sdk/memory-core-host-secret | 记忆宿主 secret 辅助工具 |
plugin-sdk/memory-core-host-events | 已弃用的兼容性别名;请使用 plugin-sdk/memory-host-events |
plugin-sdk/memory-core-host-status | 记忆宿主状态辅助工具 |
plugin-sdk/memory-core-host-runtime-cli | 记忆宿主 CLI 运行时辅助工具 |
plugin-sdk/memory-core-host-runtime-core | 记忆宿主核心运行时辅助工具 |
plugin-sdk/memory-core-host-runtime-files | 记忆宿主文件/运行时辅助工具 |
plugin-sdk/memory-host-core | 面向记忆宿主核心运行时辅助工具的供应商中立别名 |
plugin-sdk/memory-host-events | 面向记忆宿主事件日志辅助工具的供应商中立别名 |
plugin-sdk/memory-host-files | 已弃用的兼容性别名;请使用 plugin-sdk/memory-core-host-runtime-files |
plugin-sdk/memory-host-markdown | 面向记忆相邻插件的共享托管 markdown 辅助工具 |
plugin-sdk/memory-host-search | 用于搜索管理器访问的主动记忆运行时门面 |
plugin-sdk/memory-host-status | 已弃用的兼容性别名;请使用 plugin-sdk/memory-core-host-status |
保留的内置辅助工具子路径
保留的内置辅助工具子路径
目前没有保留的内置辅助工具 SDK 子路径。所有者特定的
辅助工具位于所属插件包内,而可复用的宿主契约
使用通用 SDK 子路径,例如
plugin-sdk/gateway-runtime、
plugin-sdk/security-runtime 和 plugin-sdk/plugin-config-runtime。