设置和配置

Wire 渠道设置、账户配置模式，以及保持入口导入轻量的窄 SDK 子路径。属于构建渠道插件指南的一部分。

设置子路径¶

• openclaw/plugin-sdk/setup-runtime 涵盖运行时安全的设置辅助函数：createSetupTranslator、导入安全的设置补丁适配器（createPatchedAccountSetupAdapter、createEnvPatchedAccountSetupAdapter、createSetupInputPresenceValidator）、lookup-note 输出、promptResolvedAllowFrom、splitSetupEntries 以及委托的设置代理构建器。
• openclaw/plugin-sdk/channel-setup 涵盖可选安装设置构建器及一些设置安全原语：createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、createOptionalChannelSetupWizard、DEFAULT_ACCOUNT_ID、createTopLevelChannelDmPolicy、setSetupChannelEnabled 和 splitSetupEntries。
• 仅当还需要更重的共享设置/配置辅助函数（如 moveSingleAccountChannelSectionToDefaultAccount(...)）时，才使用更宽泛的 openclaw/plugin-sdk/setup 接缝。

如果你的渠道只想在设置界面中提示“先安装此插件”，请优先使用 createOptionalChannelSetupSurface(...)。生成的适配器/向导在配置写入和最终确定时故障关闭（fail closed），并在验证、最终确定和文档链接文案中复用相同的“需要安装”消息。

如果你的渠道支持环境变量驱动的设置或认证，请通过渠道配置模式和设置描述符将其暴露。渠道运行时的 envVars 或本地常量仅用于面向操作者的文案。

如果你的渠道可能会在插件运行时启动之前出现在 status、channels list、channels status 或 SecretRef 扫描中，请在 package.json 中添加 openclaw.setupEntry。该入口应可在只读命令路径中安全导入，并返回这些摘要所需的渠道元数据、设置安全配置适配器、状态适配器和渠道密钥目标元数据。不要从设置入口启动客户端、监听器或传输运行时。

同时保持主渠道入口的导入路径也很窄。Discovery 可以评估入口和渠道插件模块来注册能力，而无需激活渠道。诸如 channel-plugin-api.ts 之类的文件应导出渠道插件对象，但不要导入设置向导、传输客户端、socket 监听器、子进程启动器或服务启动模块。请将这些运行时部分放入从 registerFull(...)、运行时设置器或懒加载能力适配器加载的模块中。

账户模式与继承¶

使用来自 openclaw/plugin-sdk/channel-config-schema 的 buildChannelAccountSchemaParts。其 accountShape 将 dmPolicy 和 groupPolicy 保留为可选，因此省略的账户策略会继承渠道根策略。仅将其 rootPolicyShape 展开到根模式中：它将 DM 默认设置为 pairing，将群组默认设置为 allowlist。不要将这些默认值应用于账户条目，也不要将它们从根中移除；前者会遮蔽操作者设置，后者可能导致群组访问开放。这将取代 buildCommonChannelAccountShape 及其默认标志。

使用来自同一子路径的 refineChannelDmPolicy({ channelId, value, ctx }) 根据 allowFrom 校验根策略。传入 accountId 可校验单个账户的根策略和 allowlist 继承，包括显式空数组覆盖。该辅助函数会为 open 和 allowlist 策略发出标准的根/账户错误路径及消息。账户迭代、禁用账户过滤以及与渠道内其他细化校验相关的排序请保留在渠道插件中，因为这些规则在不同插件间有所差异。

通过现有的 openclaw/plugin-sdk/account-helpers 导出使用 mergeAccountConfig 或 resolveMergedAccountConfig 进行运行时继承。它们的共享实现位于 src/config/channel-account-config.ts；插件必须使用 SDK 导入。账户字段会替换根字段，包括显式空集合。nestedObjectKeys 选择浅层对象合并；inheritEmptyKeys 将字段映射为 "array" 或 "object"，以便在该类账户集合为空时继承根。preserveRootAllowFrom: true 会在根包含限制性发送者条目时移除账户通配符，同时保留账户的显式发送者，或回退到根列表。这些集合和 allowlist 规则由所有者选择，不是渠道通用默认值。请将凭据、传输选择和其他渠道特定的账户关注点保留在插件中。

已存储账户键的选择¶

从 openclaw/plugin-sdk/account-resolution 导入 resolveAccountKey、resolveNormalizedAccountEntry 和 ChannelAccountKeyPolicy。写入时使用所选存储键，以便编辑保留操作者的键拼写，并更新读者所使用的同一条目。

对于已注册的渠道回调，请使用 resolveAccountKey(accounts, accountId, undefined, undefined, { channelId }) 从所属操作或 Gateway 快照中消费所选的 manifest 策略。在读取、设置和删除期间保持该元数据作用域有效。不要从运行时插件的 manifest 中导入第二个策略：另一个 manifest 可能拥有渠道策略。

resolveAccountKey(accounts, accountId, normalizeAccountId?, policy?, options?) 返回一个已存储键或 undefined：

随附的 v2026.9.4 SDK 未导出 resolveAccountKey；仅在使用提供此选择器和通道上下文的宿主 SDK 时使用这些选项。这不会改变旧版返回条目辅助函数的行为。

resolveNormalizedAccountEntry(accounts, accountId, normalizeAccountId, policy?) 接受相同参数，要求提供规范化器，并返回所选条目而不是其键。未匹配或不符合条件的别名返回 undefined；随后可以应用正常的通道继承。

resolveMergedAccountConfig 接受 channelConfig（根默认值）、accounts （已编写的映射）和 accountId，以及可选的 normalizeAccountId、 channelId 和 accountKeyPolicy。channelId 从当前 操作的已准备插件元数据快照，或已发布的 Gateway 快照中选择规则。 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，用于入站路由/信封以及 记录与分发接线
• 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，用于出站身份/发送委托 和类型化负载规划
• buildThreadAwareOutboundSessionRoute(...)，来自 openclaw/plugin-sdk/channel-core，当出站路由应保留 显式 replyToId/threadId，或在基础会话键仍然匹配时恢复当前 :thread: 会话。当平台具有原生线程投递语义时，提供商插件可以 覆盖优先级、后缀行为和线程 ID 规范化。
• openclaw/plugin-sdk/thread-bindings-runtime，用于线程绑定生命周期 和适配器注册

threading.resolveReplyTransport 钩子会单独接收负载中可选的 replyToCurrent 意图，与 replyToIsExplicit 分开。原生 API 要求线程根节点的通道，可以将当前消息回复解析到已接纳的线程，而不会重定向任意显式 replyToId 目标。 省略意图时，保留现有显式目标行为。

对于发往源通道的排队回复，hook 也可能收到 currentMessageId，即由队列所有者捕获的外部入站消息 ID。 它是可选上下文，而不是显式回复目标：core 不会将其附加为 replyToId。通道决定是否使用它进行隐式关联， 同时保留显式目标、null 退出和回复模式过滤。 内部和跨会话轮次不提供此外部消息事实。

仅认证通道通常可以停留在默认路径：core 处理 审批，插件只需暴露出站/认证能力。Matrix、Slack、Telegram 以及自定义聊天传输等原生 审批通道应使用共享的原生辅助函数，而不是自行实现审批 生命周期。