Appearance
Plugin SDK 子路径按功能域精确暴露，插件开发应优先使用活跃子路径，避免导入 deprecated 的广泛桶和兼容性子路径。审计公共导出数使用 pnpm plugin-sdk:surface，检查保留辅助路径使用 pnpm plugins:boundary-report:summary。新插件代码应直接从 zod 包导入 zod，而非 plugin-sdk/zod。
OpenClaw Plugin SDK 子路径全览：插件开发怎么选路径
Plugin SDK 通过一组窄公共子路径暴露在 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 检查活跃保留辅助路径；未使用的保留辅助导出会触发 CI 报告失败，而不会留在公共 SDK 中成为休眠兼容债。
插件编写指南见 Plugin SDK 概述。
Plugin 入口
| 子路径 | 关键导出 |
|---|---|
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 | 迁移 provider 项辅助，如 createMigrationItem、原因常量、项状态标记、脱敏辅助、summarizeMigrationItems |
plugin-sdk/migration-runtime | 运行时迁移辅助，如 copyMigrationFileItem、withCachedMigrationConfigRuntime、writeMigrationReport |
plugin-sdk/health | Doctor 健康检查注册、检测、修复、严重程度、查找类型 |
弃用兼容性和测试辅助
以下子路径仍作为包导出供旧插件和 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 仍是一个活跃的聚焦测试辅助子路径。
保留的捆绑插件辅助子路径
这些子路径是插件拥有的兼容性表面，仅为其拥有的捆绑插件保留，不是通用 SDK API：plugin-sdk/codex-mcp-projection 和 plugin-sdk/codex-native-task-runtime。跨所有者的扩展导入被包合同防护阻止。
弃用但未使用的公共子路径
这些公共子路径至少存在了一个月，目前没有捆绑扩展的生产导入。为保持兼容性仍可导入，但新插件代码应使用活跃的、被消费的 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 检查当前预算。
弃用的广泛桶
以下广泛重新导出桶仍可构建用于 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 仅向后兼容；应使用聚焦的 channel/runtime 子路径、config-contracts、string-coerce-runtime、text-chunking、text-utility-runtime 和 logging-core。
Channel 子路径
| 子路径 | 关键导出 |
|---|---|
plugin-sdk/channel-core | defineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase |
plugin-sdk/config-schema | 根 openclaw.json Zod schema 导出 (OpenClawSchema) |
plugin-sdk/json-schema-runtime | 插件拥有 schema 的缓存 JSON Schema 校验辅助 |
plugin-sdk/channel-setup | createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, 及 DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries |
plugin-sdk/setup | 共享 setup wizard 辅助、setup 翻译器、allowlist 提示、setup 状态构造器 |
plugin-sdk/setup-runtime | createSetupTranslator, 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 | 多账号 config/action-gate 辅助、默认账号回退辅助 |
plugin-sdk/account-id | DEFAULT_ACCOUNT_ID, 账号 ID 规范化辅助 |
plugin-sdk/account-resolution | 账号查找 + 默认回退辅助 |
plugin-sdk/account-helpers | 窄账号列表/账号操作辅助 |
plugin-sdk/access-groups | 访问组 allowlist 解析和脱敏组诊断辅助 |
plugin-sdk/channel-pairing | createChannelPairingController |
plugin-sdk/channel-reply-pipeline | 遗留回复管道辅助。新 channel 回复管道代码应使用 plugin-sdk/channel-message 的 createChannelMessageReplyPipeline 和 resolveChannelMessageSourceReplyDeliveryMode。 |
plugin-sdk/channel-config-helpers | createHybridChannelConfigAdapter, resolveChannelDmAccess, resolveChannelDmAllowFrom, resolveChannelDmPolicy, normalizeChannelDmPolicy, normalizeLegacyDmAliases |
plugin-sdk/channel-config-schema | 共享 channel config schema 原语 + Zod 和直接 JSON/TypeBox 构造器 |
plugin-sdk/bundled-channel-config-schema | 仅为维护的捆绑插件提供的 OpenClaw channel config schema |
plugin-sdk/channel-config-schema-legacy | 弃用兼容别名（捆绑 channel config schema） |
plugin-sdk/telegram-command-config | Telegram 自定义命令规范化/校验辅助，含捆绑合同回退 |
plugin-sdk/command-gating | 窄命令授权门控辅助 |
plugin-sdk/channel-policy | resolveChannelGroupRequireMention |
plugin-sdk/channel-ingress | 弃用低级 channel 入口兼容外观。新接收路径应使用 plugin-sdk/channel-ingress-runtime。 |
plugin-sdk/channel-ingress-runtime | 实验性高层 channel 入口运行时解析器和路由事实构造器（用于迁移的 channel 接收路径）。优先使用此路径而非在每个插件中组装有效 allowlist、命令 allowlist 和遗留投影。见 Channel 入口 API。 |
plugin-sdk/channel-lifecycle | createAccountStatusSink, createChannelRunQueue 和遗留草稿流生命周期辅助。新预览最终化代码应使用 plugin-sdk/channel-message。 |
plugin-sdk/channel-message | 轻量消息生命周期合同辅助，如 defineChannelMessageAdapter, createChannelMessageAdapterFromOutbound, createChannelMessageReplyPipeline, createReplyPrefixContext, resolveChannelMessageSourceReplyDeliveryMode, 持久最终能力推导、发送/回执/副作用能力证明、MessageReceiveContext、接收 ACK 策略证明、defineFinalizableLivePreviewAdapter, deliverWithFinalizableLivePreviewAdapter、实时预览和最终化能力证明、持久恢复状态、RenderedMessageBatch、消息回执类型和回执 ID 辅助。见 Channel 消息 API。遗留回复分发外观仅作为弃用兼容保留。 |
plugin-sdk/channel-message-runtime | 运行时投递辅助（可能加载出站投递），包括 deliverInboundReplyWithMessageSendContext, sendDurableMessageBatch, withDurableMessageSendContext。弃用回复分发桥仅兼容导入；在 monitor/send 运行时模块使用，不要在热插件引导文件中使用。 |
plugin-sdk/inbound-envelope | 共享入站路由 + 信封构造器辅助 |
plugin-sdk/inbound-reply-dispatch | 遗留共享入站记录和分发辅助、可见/最终分发谓词和弃用 deliverDurableInboundReplyPayload 兼容性（用于预构建 channel 分发器）。新 channel 接收/分发代码应从 plugin-sdk/channel-message-runtime 导入运行时生命周期辅助。 |
plugin-sdk/messaging-targets | 目标解析/匹配辅助 |
plugin-sdk/outbound-media | 共享出站媒体加载辅助 |
plugin-sdk/outbound-send-deps | 轻量出站发送依赖查找（用于 channel 适配器） |
plugin-sdk/outbound-runtime | 出站身份、发送委托、会话、格式化和负载规划辅助。直接投递辅助（如 deliverOutboundPayloads）是弃用兼容基板；新发送路径应使用 plugin-sdk/channel-message-runtime。 |
plugin-sdk/poll-runtime | 窄轮询规范化辅助 |
plugin-sdk/thread-bindings-runtime | 线程绑定生命周期和适配器辅助 |
plugin-sdk/agent-media-payload | 遗留 agent 媒体负载构造器 |
plugin-sdk/conversation-runtime | 会话/线程绑定、配对和配置绑定辅助 |
plugin-sdk/runtime-config-snapshot | 运行时配置快照辅助 |
plugin-sdk/runtime-group-policy | 运行时组策略解析辅助 |
plugin-sdk/channel-status | 共享 channel 状态快照/摘要辅助 |
plugin-sdk/channel-config-primitives | 窄 channel config schema 原语 |
plugin-sdk/channel-config-writes | Channel config 写入授权辅助 |
plugin-sdk/channel-plugin-common | 共享 channel plugin 前奏导出 |
plugin-sdk/allowlist-config-edit | Allowlist 配置编辑/读取辅助 |
plugin-sdk/group-access | 共享组访问决策辅助 |
plugin-sdk/direct-dm | 共享直接 DM 认证/守卫辅助 |
plugin-sdk/discord | 弃用 Discord 兼容外观（用于已发布 @openclaw/discord@2026.3.13 和跟踪所有者兼容性）；新插件应使用通用 channel SDK 子路径 |
plugin-sdk/telegram-account | 弃用 Telegram 账号解析兼容外观（用于跟踪所有者兼容性）；新插件应使用注入的运行时辅助或通用 channel SDK 子路径 |
plugin-sdk/zalouser | 弃用 Zalo Personal 兼容外观（用于仍导入发送者命令授权的已发布 Lark/Zalo 包）；新插件应使用 plugin-sdk/command-auth |
plugin-sdk/interactive-runtime | 语义消息展示、投递和遗留交互回复辅助。见 消息展示。 |
plugin-sdk/channel-inbound | 共享入站辅助：事件分类、上下文构建、防抖、提及匹配、提及策略、信封格式化 |
plugin-sdk/channel-inbound-debounce | 窄入站防抖辅助 |
plugin-sdk/channel-mention-gating | 窄提及策略、提及标记和提及文本辅助（不包含更广的入站运行时表面） |
plugin-sdk/channel-envelope | 窄入站信封格式化辅助 |
plugin-sdk/channel-location | Channel 位置上下文和格式化辅助 |
plugin-sdk/channel-logging | Channel 日志辅助：入站丢弃和 typing/ack 失败 |
plugin-sdk/channel-send-result | 回复结果类型 |
plugin-sdk/channel-actions | Channel 消息操作辅助，以及为插件兼容性保留的弃用原生 schema 辅助 |
plugin-sdk/channel-route | 共享路由规范化、解析器驱动的目标解析、线程 ID 字符串化、去重/紧凑路由键、解析目标类型、路由/目标比较辅助 |
plugin-sdk/channel-targets | 目标解析辅助；路由比较调用者应使用 plugin-sdk/channel-route |
plugin-sdk/channel-contract | Channel 合同类型 |
plugin-sdk/channel-feedback | 反馈/反应接线 |
plugin-sdk/channel-secret-runtime | 窄 secret 合同辅助，如 collectSimpleChannelFieldAssignments, getChannelSurface, pushAssignment, secret 目标类型 |
Provider 子路径
| 子路径 | 关键导出 |
|---|---|
plugin-sdk/provider-entry | defineSingleProviderPluginEntry |
plugin-sdk/lmstudio | 支持的 LM Studio provider 外观（setup、catalog 发现、运行时模型准备） |
plugin-sdk/lmstudio-runtime | 支持的 LM Studio 运行时外观（本地服务器默认值、模型发现、请求头、已加载模型辅助） |
plugin-sdk/provider-setup | 精选本地/自托管 provider setup 辅助 |
plugin-sdk/self-hosted-provider-setup | 聚焦 OpenAI 兼容自托管 provider setup 辅助 |
plugin-sdk/cli-backend | CLI 后端默认值 + watchdog 常量 |
plugin-sdk/provider-auth-runtime | 运行时 API 密钥解析辅助（用于 provider 插件） |
plugin-sdk/provider-auth-api-key | API 密钥 onboarding/profile 写入辅助，如 upsertApiKeyProfile |
plugin-sdk/provider-auth-result | 标准 OAuth auth-result 构造器 |
plugin-sdk/provider-env-vars | Provider auth 环境变量查找辅助 |
plugin-sdk/provider-auth | createProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile, upsertApiKeyProfile, writeOAuthCredentials, 弃用 resolveOpenClawAgentDir 兼容导出 |
plugin-sdk/provider-model-shared | ProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, 共享 replay 策略构造器、provider 端点辅助、共享模型 ID 规范化辅助 |
plugin-sdk/provider-catalog-runtime | Provider catalog 增强运行时钩子和插件 provider 注册接缝（用于合同测试） |
plugin-sdk/provider-catalog-shared | findCatalogTemplate, buildSingleProviderApiKeyCatalog, buildManifestModelProviderConfig, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat |
plugin-sdk/provider-http | 通用 provider HTTP/端点能力辅助、provider HTTP 错误、音频转录 multipart 表单辅助 |
plugin-sdk/provider-web-fetch-contract | 窄 web-fetch 配置/选择合同辅助，如 enablePluginInConfig 和 WebFetchProviderPlugin |
plugin-sdk/provider-web-fetch | Web-fetch provider 注册/缓存辅助 |
plugin-sdk/provider-web-search-config-contract | 窄 web-search 配置/凭据辅助（适用于不需要 plugin-enable 接线的 provider） |
plugin-sdk/provider-web-search-contract | 窄 web-search 配置/凭据合同辅助，如 createWebSearchProviderContractFields, enablePluginInConfig, resolveProviderWebSearchPluginConfig, 作用域凭据 setter/getter |
plugin-sdk/provider-web-search | Web-search provider 注册/缓存/运行时辅助 |
plugin-sdk/embedding-providers | 通用 embedding provider 类型和读取辅助，包括 EmbeddingProviderAdapter, getEmbeddingProvider(...), listEmbeddingProviders(...)；插件通过 api.registerEmbeddingProvider(...) 注册 provider，因此清单所有权被强制 |
plugin-sdk/provider-tools | ProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, DeepSeek/Gemini/OpenAI schema 清理 + 诊断 |
plugin-sdk/provider-usage | fetchClaudeUsage 等 |
plugin-sdk/provider-stream | ProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, stream wrapper 类型，共享 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper 辅助 |
plugin-sdk/provider-transport-runtime | 原生 provider 传输辅助：受保护 fetch、传输消息转换、可写传输事件流 |
plugin-sdk/provider-onboard | Onboarding 配置补丁辅助 |
plugin-sdk/global-singleton | 进程本地单例/映射/缓存辅助 |
plugin-sdk/group-activation | 窄组激活模式和命令解析辅助 |
认证与安全子路径
| 子路径 | 关键导出 |
|---|---|
plugin-sdk/command-auth | resolveControlCommandGate, 命令注册辅助（含动态参数菜单格式化）、发送者授权辅助 |
plugin-sdk/command-status | 命令/帮助消息构造器：buildCommandsMessagePaginated, buildHelpMessage |
plugin-sdk/approval-auth-runtime | 批准人解析和同聊天操作授权辅助 |
plugin-sdk/approval-client-runtime | 原生执行批准 profile/过滤辅助 |
plugin-sdk/approval-delivery-runtime | 原生批准能力/投递适配器 |
plugin-sdk/approval-gateway-runtime | 共享批准网关解析辅助 |
plugin-sdk/approval-handler-adapter-runtime | 轻量原生批准适配器加载辅助（用于热 channel 入口点） |
plugin-sdk/approval-handler-runtime | 更广的批准处理器运行时辅助；当窄适配器/网关接缝足够时优先使用它们 |
plugin-sdk/approval-native-runtime | 原生批准目标 + 账号绑定辅助 |
plugin-sdk/approval-reply-runtime | 执行/插件批准回复负载辅助 |
plugin-sdk/approval-runtime | 执行/插件批准负载辅助、原生批准路由/运行时辅助、结构化批准展示辅助（如 formatApprovalDisplayPath） |
plugin-sdk/reply-dedupe | 窄入站回复去重重置辅助 |
plugin-sdk/channel-contract-testing | 窄 channel 合同测试辅助（不含广泛测试桶） |
plugin-sdk/command-auth-native | 原生命令授权、动态参数菜单格式化、原生会话目标辅助 |
plugin-sdk/command-detection | 共享命令检测辅助 |
plugin-sdk/command-primitives-runtime | 轻量命令文本谓词（用于热 channel 路径） |
plugin-sdk/command-surface | 命令体规范化和命令表面辅助 |
plugin-sdk/allow-from | formatAllowFromLowercase |
plugin-sdk/channel-secret-runtime | 窄 secret 合同收集辅助（channel/plugin secret 表面） |
plugin-sdk/secret-ref-runtime | 窄 coerceSecretRef 和 SecretRef 类型辅助（secret 合同/配置解析） |
plugin-sdk/security-runtime | 共享信任、DM 门控、根受限文件/路径辅助：仅创建写入、同步/异步原子文件替换、同级临时写入、跨设备移动回退、私有文件存储辅助、符号链接父目录守卫、外部内容、敏感文本脱敏、常量时间 secret 比较、secret 收集辅助 |
plugin-sdk/ssrf-policy | 主机 allowlist 和私有网络 SSRF 策略辅助 |
plugin-sdk/ssrf-dispatcher | 窄固定分发器辅助（不含广泛 infra 运行时表面） |
plugin-sdk/ssrf-runtime | 固定分发器、SSRF 保护的 fetch、SSRF 错误、SSRF 策略辅助 |
plugin-sdk/secret-input | Secret 输入解析辅助 |
plugin-sdk/webhook-ingress | Webhook 请求/目标辅助和原始 websocket/body 强制转换 |
plugin-sdk/webhook-request-guards | 请求体大小/超时辅助 |
运行时与存储子路径
| 子路径 | 关键导出 |
|---|---|
plugin-sdk/runtime | 广泛运行时/日志/备份/插件安装辅助 |
plugin-sdk/runtime-env | 窄运行时 env、日志器、超时、重试、退避辅助 |
plugin-sdk/browser-config | 支持的 browser config 外观（规范化 profile/默认值、CDP URL 解析、browser 控制认证辅助） |
plugin-sdk/codex-mcp-projection | 保留的捆绑 Codex 辅助（将用户 MCP 服务器配置投影到 Codex 线程配置）；不供第三方插件使用 |
plugin-sdk/codex-native-task-runtime | 保留的捆绑 Codex 辅助（原生任务镜像/运行时接线）；不供第三方插件使用 |
plugin-sdk/channel-runtime-context | 通用 channel 运行时上下文注册和查找辅助 |
plugin-sdk/matrix | 弃用 Matrix 兼容外观（用于旧第三方 channel 包）；新插件应直接导入 plugin-sdk/run-command |
plugin-sdk/mattermost | 弃用 Mattermost 兼容外观（用于旧第三方 channel 包）；新插件应直接导入通用 SDK 子路径 |
plugin-sdk/runtime-store | createPluginRuntimeStore |
plugin-sdk/plugin-runtime | 共享 plugin 命令/钩子/HTTP/交互辅助 |
plugin-sdk/hook-runtime | 共享 webhook/内部钩子管道辅助 |
plugin-sdk/lazy-runtime | 惰性运行时导入/绑定辅助：createLazyRuntimeModule, createLazyRuntimeMethod, createLazyRuntimeSurface |
plugin-sdk/process-runtime | 进程执行辅助 |
plugin-sdk/cli-runtime | CLI 格式化、等待、版本、参数调用、惰性命令组辅助 |
plugin-sdk/gateway-method-runtime | 保留的 Gateway 方法分发辅助（用于声明 contracts.gatewayMethodDispatch: ["authenticated-request"] 的 plugin HTTP 路由） |
plugin-sdk/gateway-runtime | Gateway 客户端、事件循环就绪客户端启动辅助、Gateway CLI RPC、Gateway 协议错误、channel 状态补丁辅助 |
plugin-sdk/config-contracts | 聚焦纯类型配置表面（plugin 配置形状，如 OpenClawConfig 及 channel/provider 配置类型） |
plugin-sdk/plugin-config-runtime | 运行时 plugin 配置查找辅助：requireRuntimeConfig, resolvePluginConfigObject, resolveLivePluginConfigObject |
plugin-sdk/config-mutation | 事务性配置变更辅助：mutateConfigFile, replaceConfigFile, logConfigUpdated |
plugin-sdk/runtime-config-snapshot | 当前进程配置快照辅助：getRuntimeConfig, getRuntimeConfigSnapshot, 测试快照 setter |
plugin-sdk/telegram-command-config | Telegram 命令名称/描述规范化和重复/冲突检查（即使捆绑 Telegram 合同表面不可用） |
plugin-sdk/text-autolink-runtime | 文件引用自动链接检测（不含广泛文本桶） |
plugin-sdk/approval-runtime | 执行/插件批准辅助、批准能力构造器、认证/profile 辅助、原生路由/运行时辅助、结构化批准展示路径格式化 |
plugin-sdk/reply-runtime | 共享入站/回复运行时辅助：分块、分发、心跳、回复规划器 |
plugin-sdk/reply-dispatch-runtime | 窄回复分发/最终化和会话标签辅助 |
plugin-sdk/reply-history | 共享短窗口回复历史辅助。新消息轮次代码应使用 createChannelHistoryWindow；底层映射辅助仅作为弃用兼容导出保留 |
plugin-sdk/reply-reference | createReplyReferencePlanner |
plugin-sdk/reply-chunking | 窄文本/markdown 分块辅助 |
plugin-sdk/session-store-runtime | 会话工作流辅助 (getSessionEntry, listSessionEntries, patchSessionEntry, upsertSessionEntry)、遗留会话存储路径/会话键辅助、更新读取、弃用整个存储变更辅助 |
plugin-sdk/cron-store-runtime | Cron 存储路径/加载/保存辅助 |
plugin-sdk/state-paths | 状态/OAuth 目录路径辅助 |
plugin-sdk/routing | 路由/会话键/账号绑定辅助：resolveAgentRoute, buildAgentSessionKey, resolveDefaultAgentBoundAccountId |
plugin-sdk/status-helpers | 共享 channel/账号状态摘要辅助、运行时状态默认值、问题元数据辅助 |
plugin-sdk/target-resolver-runtime | 共享目标解析器辅助 |
plugin-sdk/string-normalization-runtime | slug/字符串规范化辅助 |
plugin-sdk/request-url | 从 fetch/request 类似输入提取字符串 URL |
plugin-sdk/run-command | 带标准 stdout/stderr 结果的定时命令运行器 |
plugin-sdk/param-readers | 常用工具/CLI 参数读取器 |
plugin-sdk/tool-plugin | 定义简单类型化 agent-tool 插件并暴露静态元数据（用于清单生成） |
plugin-sdk/tool-payload | 从工具结果对象提取规范化负载 |
plugin-sdk/tool-send | 从工具参数提取规范发送目标字段 |
plugin-sdk/temp-path | 共享临时下载路径辅助和私有安全临时工作区 |
plugin-sdk/logging-core | 子系统日志器和脱敏辅助 |
plugin-sdk/markdown-table-runtime | Markdown 表格模式和转换辅助 |
plugin-sdk/model-session-runtime | 模型/会话覆盖辅助：applyModelOverrideToSessionEntry, resolveAgentMaxConcurrent |
plugin-sdk/talk-config-runtime | Talk provider 配置解析辅助 |
plugin-sdk/json-store | 小型 JSON 状态读写辅助 |
plugin-sdk/file-lock | 可重入文件锁辅助 |
plugin-sdk/persistent-dedupe | 磁盘支持的去重缓存辅助 |
plugin-sdk/acp-runtime | ACP 运行时/会话和回复分发辅助 |
plugin-sdk/acp-runtime-backend | 轻量 ACP 后端注册和回复分发辅助（用于启动时加载的插件） |
plugin-sdk/acp-binding-resolve-runtime | 只读 ACP 绑定解析（不含生命周期启动导入） |
plugin-sdk/agent-config-primitives | 窄 agent 运行时 config schema 原语 |
plugin-sdk/boolean-param | 松散布尔参数读取器 |
plugin-sdk/dangerous-name-runtime | 危险名称匹配解析辅助 |
plugin-sdk/device-bootstrap | 设备引导和配对令牌辅助 |
plugin-sdk/extension-shared | 共享被动 channel、状态和环境代理辅助原语 |
plugin-sdk/models-provider-runtime | /models 命令/provider 回复辅助 |
plugin-sdk/skill-commands-runtime | 技能命令列出辅助 |
plugin-sdk/native-command-registry | 原生命令注册/构建/序列化辅助 |
plugin-sdk/agent-harness | 实验性可信插件表面（低级 agent harness）：harness 类型、活跃运行 steer/abort 辅助、OpenClaw 工具桥接辅助、运行时计划工具策略辅助、终端结果分类、工具进度格式化/详情辅助、尝试结果实用程序 |
plugin-sdk/provider-zai-endpoint | 弃用 Z.AI provider 拥有端点检测外观；使用 Z.AI 插件公共 API |
plugin-sdk/async-lock-runtime | 进程本地异步锁辅助（用于小型运行时状态文件） |
plugin-sdk/channel-activity-runtime | Channel 活动遥测辅助 |
plugin-sdk/concurrency-runtime | 有界异步任务并发辅助 |
plugin-sdk/dedupe-runtime | 内存去重缓存辅助 |
plugin-sdk/delivery-queue-runtime | 出站待处理投递排空辅助 |
plugin-sdk/file-access-runtime | 安全本地文件和媒体源路径辅助 |
plugin-sdk/heartbeat-runtime | 心跳唤醒、事件和可见性辅助 |
plugin-sdk/number-runtime | 数值强制转换辅助 |
plugin-sdk/secure-random-runtime | 安全令牌/UUID 辅助 |
plugin-sdk/system-event-runtime | 系统事件队列辅助 |
plugin-sdk/transport-ready-runtime | 传输就绪等待辅助 |
plugin-sdk/infra-runtime | 弃用兼容填充；使用上述聚焦运行时子路径 |
plugin-sdk/collection-runtime | 小型有界缓存辅助 |
plugin-sdk/diagnostic-runtime | 诊断标志、事件和追踪上下文辅助 |
plugin-sdk/error-runtime | 错误图、格式化、共享错误分类辅助、isApprovalNotFoundError |
plugin-sdk/fetch-runtime | 包装 fetch、代理、EnvHttpProxyAgent 选项、固定查找辅助 |
plugin-sdk/runtime-fetch | 分发器感知运行时 fetch（无代理/受保护 fetch 导入） |
plugin-sdk/response-limit-runtime | 有界响应体读取器（不含广泛媒体运行时表面） |
plugin-sdk/session-binding-runtime | 当前会话绑定状态（不含配置绑定路由或配对存储） |
plugin-sdk/session-store-runtime | 会话存储辅助（不含广泛配置写入/维护导入） |
plugin-sdk/context-visibility-runtime | 上下文可见性解析和补充上下文过滤（不含广泛配置/安全导入） |
plugin-sdk/string-coerce-runtime | 窄原始记录/字符串强制转换和规范化辅助（不含 markdown/日志导入） |
plugin-sdk/host-runtime | 主机名和 SCP 主机规范化辅助 |
plugin-sdk/retry-runtime | 重试配置和重试运行器辅助 |
plugin-sdk/agent-runtime | Agent 目录/身份/工作区辅助，包括 resolveAgentDir, resolveDefaultAgentDir, 弃用 resolveOpenClawAgentDir 兼容导出 |
plugin-sdk/directory-runtime | 配置支持的目录查询/去重 |
plugin-sdk/keyed-async-queue | KeyedAsyncQueue |
能力与测试子路径
| 子路径 | 关键导出 |
|---|---|
plugin-sdk/media-runtime | 共享媒体 fetch/转换/存储辅助：saveRemoteMedia, saveResponseMedia, readRemoteMediaBuffer, 弃用 fetchRemoteMedia；当 URL 应成为 OpenClaw 媒体时优先使用存储辅助再缓冲区读取 |
plugin-sdk/media-mime | 窄 MIME 规范化、文件扩展名映射、MIME 检测、媒体种类辅助 |
plugin-sdk/media-store | 窄媒体存储辅助：saveMediaBuffer, saveMediaStream |
plugin-sdk/media-generation-runtime | 共享媒体生成故障切换辅助、候选选择、缺失模型消息 |
plugin-sdk/media-understanding | 媒体理解 provider 类型 + provider 面向的图像/音频/结构化提取辅助导出 |
plugin-sdk/text-chunking | 文本和 markdown 分块/渲染辅助、markdown 表格转换、指令标签剥离、安全文本实用程序 |
plugin-sdk/text-chunking | 出站文本分块辅助 |
plugin-sdk/speech | 语音 provider 类型 + provider 面向的指令、注册、校验、OpenAI 兼容 TTS 构造器和语音辅助导出 |
plugin-sdk/speech-core | 共享语音 provider 类型、注册、指令、规范化、语音辅助导出 |
plugin-sdk/realtime-transcription | 实时转录 provider 类型、注册辅助、共享 WebSocket 会话辅助 |
plugin-sdk/realtime-bootstrap-context | 实时 profile 引导辅助（有界 IDENTITY.md, USER.md, SOUL.md 上下文注入） |
plugin-sdk/realtime-voice | 实时语音 provider 类型和注册辅助 |
plugin-sdk/image-generation | 图像生成 provider 类型 + 图像资产/数据 URL 辅助和 OpenAI 兼容图像 provider 构造器 |
plugin-sdk/image-generation-core | 共享图像生成类型、故障切换、认证、注册辅助 |
plugin-sdk/music-generation | 音乐生成 provider/请求/结果类型 |
plugin-sdk/music-generation-core | 共享音乐生成类型、故障切换辅助、provider 查找、模型引用解析 |
plugin-sdk/video-generation | 视频生成 provider/请求/结果类型 |
plugin-sdk/video-generation-core | 共享视频生成类型、故障切换辅助、provider 查找、模型引用解析 |
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 | 仓库本地原生 agent 运行时适配器合同 fixture（认证、投递、回退、工具钩子、提示覆盖、schema、转录投影测试） |
plugin-sdk/channel-test-helpers | 仓库本地 channel 导向测试辅助（通用操作/setup/状态合同、目录断言、账号启动生命周期、发送配置线程化、运行时 mock、状态问题、出站投递、钩子注册） |
plugin-sdk/channel-target-testing | 仓库本地共享目标解析错误用例套件（用于 channel 测试） |
plugin-sdk/plugin-test-contracts | 仓库本地插件包、注册、公共工件、直接导入、运行时 API、导入副作用合同辅助 |
plugin-sdk/provider-test-contracts | 仓库本地 provider 运行时、认证、发现、onboard、catalog、wizard、媒体能力、replay 策略、实时 STT 实时音频、web-search/fetch、流合同辅助 |
plugin-sdk/provider-http-test-mocks | 仓库本地可选 Vitest HTTP/auth mock（用于练习 plugin-sdk/provider-http 的 provider 测试） |
plugin-sdk/test-fixtures | 仓库本地通用 CLI 运行时捕获、沙箱上下文、技能写入器、agent 消息、系统事件、模块重载、捆绑插件路径、终端文本、分块、认证令牌、类型化 case fixture |
plugin-sdk/test-node-mocks | 仓库本地聚焦 Node 内置 mock 辅助（用于在 Vitest vi.mock("node:*") 工厂内使用） |
记忆子路径
| 子路径 | 关键导出 |
|---|---|
plugin-sdk/memory-core | 捆绑记忆核心辅助表面（manager/config/文件/CLI 辅助） |
plugin-sdk/memory-core-engine-runtime | 记忆索引/搜索运行时外观 |
plugin-sdk/memory-core-host-engine-foundation | 记忆主机基础引擎导出 |
plugin-sdk/memory-core-host-engine-embeddings | 记忆主机 embedding 合同、注册访问、本地 provider、通用批处理/远程辅助 |
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 清单中跟踪以保证包构建和别名确定性，但并非通用插件编写 API。新的可复用宿主合同应使用通用 SDK 子路径，如 plugin-sdk/gateway-runtime、plugin-sdk/security-runtime 和 plugin-sdk/plugin-config-runtime。
| 子路径 | 所有者和用途 |
|---|---|
plugin-sdk/codex-mcp-projection | 捆绑 Codex 插件辅助：将用户 MCP 服务器配置投影到 Codex 应用服务器线程配置 |
plugin-sdk/codex-native-task-runtime | 捆绑 Codex 插件辅助：镜像 Codex 应用服务器原生子代理到 OpenClaw 任务状态 |
相关
常见问题
如何选择正确的 plugin-sdk 子路径？
根据你的插件类型和需要调用的功能选择对应功能域的子路径。例如 channel 插件优先使用 plugin-sdk/channel-core、plugin-sdk/channel-message 等；provider 插件使用 plugin-sdk/provider-entry、plugin-sdk/provider-auth 等。避免使用标记为 deprecated 的广泛桶和兼容性子路径。可用 pnpm plugin-sdk:surface 查看当前活跃的公共导出。
哪些子路径已经弃用，新代码不应该使用？
弃用的子路径包括：zod（应直接使用 zod 包）、compat、config-types、infra-runtime、text-runtime 等广泛桶，以及 discord、matrix、mattermost 等渠道特定兼容外观。完整的弃用列表见本页“弃用但未使用的公共子路径”和“弃用稀有公共子路径”部分。
如何审计插件 SDK 公共导出和保留辅助路径？
使用 pnpm plugin-sdk:surface 查看公共导出数量和具体子路径；使用 pnpm plugins:boundary-report:summary 检查保留辅助路径的状态。未使用的保留辅助导出会触发 CI 失败，确保维护者及时清理。