本页内容
本页内容
构建插件
通道设置和配置
有线通道设置、帐户配置模式和狭窄的 SDK 子路径使入口点的导入成本低廉。 构建频道插件指南的一部分。
设置子路径
openclaw/plugin-sdk/setup-runtime覆盖运行时安全的设置 helper：createSetupTranslator、可安全导入的 setup patch 适配器 (createPatchedAccountSetupAdapter、createEnvPatchedAccountSetupAdapter、createSetupInputPresenceValidator)、lookup-note 输出、promptResolvedAllowFrom、splitSetupEntries，以及委托式 setup-proxy builders。openclaw/plugin-sdk/channel-setup覆盖可选安装的设置 builders，以及少量设置安全原语：createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、createOptionalChannelSetupWizard、DEFAULT_ACCOUNT_ID、createTopLevelChannelDmPolicy、setSetupChannelEnabled和splitSetupEntries。- 仅当您还需要较重的共享 setup/config 帮助程序（例如
moveSingleAccountChannelSectionToDefaultAccount(...)）时，才使用更广泛的openclaw/plugin-sdk/setup接口。
如果您的频道只想在设置界面中宣传“首先安装此插件”，请首选 createOptionalChannelSetupSurface(...)。生成的 adapter/wizard 拒绝配置写入和最终确定，并且它们在验证、最终确定和文档链接副本中重复使用相同的安装所需消息。
如果你的通道支持由环境变量驱动的设置或身份验证，请通过通道配置 schema 和设置描述符公开这些能力。将通道运行时的 envVars 或本地常量仅用于面向操作员的文案。
如果您的频道可以在插件运行时启动之前出现在 status、channels list、channels status 或 SecretRef 扫描中，请将 openclaw.setupEntry 添加到 package.json 中。该入口点应该可以安全地导入到只读命令路径中，并且应该返回这些摘要所需的通道元数据、设置安全的配置适配器、状态适配器和通道秘密目标元数据。不要从设置条目启动客户端、侦听器或传输运行时。
主通道入口导入路径也要保持精简。Discovery 可以在不激活通道的情况下评估入口和通道插件模块来注册能力。像 channel-plugin-api.ts 这样的文件应导出通道插件对象，而不要导入 setup wizard、传输客户端、socket 监听器、子进程启动器或服务启动模块。把这些运行时组件放到由 registerFull(...)、运行时 setter 或 lazy capability adapter 加载的模块中。
Account 架构和继承
使用 openclaw/plugin-sdk/channel-config-schema 中的 buildChannelAccountSchemaParts。它的 accountShape 使 dmPolicy 和 groupPolicy 可选，因此省略的帐户策略会继承通道根。仅将其 rootPolicyShape 传播到根架构中：它默认 DM 为 pairing，组为 allowlist。不要将这些默认值应用于帐户条目或将其从根目录中删除；前者隐藏操作员设置，后者可以使组访问保持开放状态。这取代了 buildCommonChannelAccountShape 及其默认标志。
使用同一子路径中的 refineChannelDmPolicy({ channelId, value, ctx }) 根据 allowFrom 验证根策略。传递 accountId 以使用根策略和白名单继承来验证一个帐户，包括显式空数组覆盖。该帮助程序发出 open 和 allowlist 策略的标准 root/account 错误路径和消息。保持帐户迭代、禁用帐户过滤和相对于通道中其他改进的排序，因为这些规则在插件之间有所不同。
通过现有的 openclaw/plugin-sdk/account-helpers 导出使用 mergeAccountConfig 或 resolveMergedAccountConfig 进行运行时继承。他们的共享实现位于 src/config/channel-account-config.ts；插件必须使用 SDK 导入。帐户字段替换根字段，包括显式空集合。 nestedObjectKeys 选择浅层对象合并；当此类帐户集合为空时，inheritEmptyKeys 将字段映射到 "array" 或 "object" 以继承根。当根包含限制性发件人条目、保留显式帐户发件人或回退到根列表时，preserveRootAllowFrom: true 会删除帐户通配符。这些收集和许可名单规则是所有者选择的，而不是通用渠道默认值。将凭证、传输选择和其他特定于渠道的帐户问题保留在插件中。
存储帐户密钥选择
从 openclaw/plugin-sdk/account-resolution 导入 resolveAccountKey、resolveNormalizedAccountEntry 和 ChannelAccountKeyPolicy。使用选定的存储键进行写入，以便编辑保留操作员的键拼写并更新读者使用的相同条目。
对于已注册的通道回调，请使用 resolveAccountKey(accounts, accountId, undefined, undefined, { channelId }) 从拥有的操作或网关快照中使用所选的清单策略。通过读取、设置和删除来保持元数据范围处于活动状态。不要从运行时插件的清单中导入第二个策略：另一个清单可能拥有该通道策略。
resolveAccountKey(accounts, accountId, normalizeAccountId?, policy?, options?) 返回存储的密钥或 undefined：
| 争论 | 含义 |
|---|---|
accounts |
创作帐户图，或undefined。 |
accountId |
请求的帐户 ID。通过策略，路由规范化首先运行，并且精确的规范化密钥获胜。如果没有策略，则正确请求的密钥将获胜。 |
normalizeAccountId |
当未提供策略时，应用于请求的 id 和存储的密钥的可选函数。对于不区分大小写的查找，请忽略两者。策略选择路由标准化。 |
policy |
可选的 ChannelAccountKeyPolicy 和 canonicalAliasesRequireOwnField，帐户字段必须在标准化后识别的别名之前包含自己的非空字符串。现有的不区分大小写的匹配仍然符合条件。 |
options.channelId |
其所选清单提供策略的可选渠道。显式的 policy 优先。如果没有通道或选定的策略，规范化器和不区分大小写的行为将保持不变。 |
options.allowMissing |
当没有存储的密钥符合条件时，返回创建目标。保留的对象键在编写者创建不可读的帐户之前抛出。 |
发货的v2026.9.4 SDK不导出resolveAccountKey；仅将这些选项与提供此选择器和通道上下文的主机 SDK 一起使用。这不会改变旧条目返回助手的行为。
resolveNormalizedAccountEntry(accounts, accountId, normalizeAccountId, policy?) 采用相同的参数，需要规范化器，并返回选定的条目而不是其键。不匹配或不合格的别名返回 undefined；然后可以应用正常的通道继承。
resolveMergedAccountConfig 采用 channelConfig（根默认值）、accounts（创作的地图）和 accountId，以及可选的 normalizeAccountId、channelId 和 accountKeyPolicy。 channelId 从当前操作准备的插件元数据快照或已发布的网关快照中选择规则。 accountKeyPolicy 对于具有明确提供的策略的调用者仍然可用。它无需 channelId 或 normalizeAccountId 即可工作，并且优先于快照规则。帐户密钥选择优先于现有字段合并和集合继承规则。
设置和配置适配器工厂接受相同的可选 accountKeyPolicy。注册的适配器使用准备好的通道策略。作用域设置、帐户名称、启用、删除和字段清除帮助程序也接受 accountKeyPolicy；它们的 accountId 是标准化路由 ID，而不是存储的拼写。注册的适配器在调用这些助手之前规范操作员输入。 clearAccountEntryFields 另外接受 channelId 来选择准备好的元数据，或没有 channelId 的显式策略。
在 channelAccountKeyPolicies 中声明规则，以便通用通道读取器和写入器接收相同的策略。删除会在建议的剩余映射上重新运行选择器，并拒绝会激活冲突行的删除。使用 allowMissing: true 创建会拒绝保留的对象密钥，而不是写入读者无法选择的帐户。
其他窄通道子路径
对于其他高频通道路径，在不需要更宽泛的遗留接入面时，优先使用更窄的帮助器：
openclaw/plugin-sdk/account-core、openclaw/plugin-sdk/account-id、openclaw/plugin-sdk/account-resolution和openclaw/plugin-sdk/account-helpers，用于多账户配置和默认账户回退openclaw/plugin-sdk/inbound-envelope和openclaw/plugin-sdk/channel-inbound用于入站 route/envelope 和记录和调度接线readAgentRunTerminalOutcome(dispatchResult)与openclaw/plugin-sdk/channel-inbound时，终端反应或状态 UI 必须区分已完成的核心代理运行和已恢复的失败运行。仅当核心运行实际启动时，它才返回"completed"或"failed"，对于命令、重复数据删除、繁忙、预运行中止和自定义调度结果，它返回undefined。交付计数和可见性仍然是传输事实，包括错误有效负载的成功交付；进程本地载体未序列化为 JSON。- 当成功的出站发送必须取消活动的入站事件标记时，
createInboundEventDeliveryCorrelation(...)来自openclaw/plugin-sdk/inbound-event-delivery；每个通道创建一个跟踪器并在通道插件中保持目标匹配 openclaw/plugin-sdk/channel-targets，用于目标解析帮助器openclaw/plugin-sdk/channel-outbound用于出站 identity/send 代表和类型化有效负载规划- 当出站路由应保留显式
replyToId/threadId或在基本会话密钥仍然匹配后恢复当前:thread:会话时，buildThreadAwareOutboundSessionRoute(...)来自openclaw/plugin-sdk/channel-core。当其平台具有本机线程传递语义时，提供程序插件可以覆盖优先级、后缀行为和线程 ID 规范化。 openclaw/plugin-sdk/thread-bindings-runtime，用于线程绑定生命周期和适配器注册
threading.resolveReplyTransport 钩子与 replyToIsExplicit 分开接收有效负载的可选 replyToCurrent 意图。本机 API 需要线程根的通道可以解析针对已接纳线程的当前消息回复，而无需重定向任意显式 replyToId 目标。省略的意图保留现有的显式目标行为。
对于对原始通道的排队回复，挂钩还可以接收 currentMessageId，即队列所有者捕获的外部入站消息 ID。它是可选上下文，而不是显式回复目标：核心不会将其附加为 replyToId。通道决定是否将其用于隐式关联，同时保留显式目标、空选择退出和回复模式过滤。内部和会话间轮流不提供此外部消息事实。
仅授权通道通常可以停止在默认路径：核心处理批准，插件仅公开 outbound/auth 功能。本机审批通道（例如 Matrix、Slack、Telegram 和自定义聊天传输）应使用共享的本机帮助程序，而不是滚动自己的审批生命周期。