跳转至

defineSetupPluginEntry

轻量级 setup-entry.ts 文件的入口辅助函数,以及与之配套的精简 setup 辅助函数族。属于 插件入口点 参考的一部分。

defineSetupPluginEntry

导入: openclaw/plugin-sdk/channel-core

用于轻量级 setup-entry.ts 文件。仅返回 { plugin },不包含运行时或 CLI 接线。

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

当频道被禁用或未配置时,OpenClaw 会加载此入口而不是完整入口。有关何时重要,请参阅 设置和配置。

Doctor 在完成延迟插件升级时也会检查此公开 setup 入口。如果提供了 plugin.lifecycle.detectLegacyStateMigrations,它会使用该函数。只要某个已发布版本仍可能需要旧版迁移,就应将该检测器保留在此轻量级入口上;省略它并不能证明完整入口没有迁移,因此 Doctor 会保持升级义务待定。缺失或损坏的 setup 入口也会使义务保持待定。

将 defineSetupPluginEntry(...) 与以下精简 setup 辅助函数族搭配使用:

导入 用途
openclaw/plugin-sdk/setup-runtime 运行时安全的 setup 辅助函数:createSetupTranslator、导入安全的 setup 补丁适配器、lookup-note 输出、promptResolvedAllowFrom、splitSetupEntries、委托 setup 代理
openclaw/plugin-sdk/channel-setup 可选安装 setup 界面
openclaw/plugin-sdk/channel-dm-policy 用于 setup 流程的账户感知 DM 策略描述符
openclaw/plugin-sdk/setup-tools setup/安装 CLI、归档和文档辅助函数
openclaw/plugin-sdk/archive 有界 TAR/gzip 成员检查、归档提取和单条目读取
openclaw/plugin-sdk/root-walk 有预算、根目录受限的目录遍历
openclaw/plugin-sdk/secret-file 固定密钥读取和先写者胜创建

inspectTarArchive({ archivePath, timeoutMs, limits, entryFilter, onFiltered }) 返回一个有界的、冻结的已接受 { path, kind, size } TAR/gzip 成员列表,而不会创建已提取的树。它使用 fs-safe 的完整准入和零剥离提取策略,而不是 tar 显示输出。路径使用现有的规范归档标识;LF 和 Unicode 拼写会保留。请使用匹配的 filter/limit 设置,并在后续提取时保留或验证相同的归档字节:检查结果不是可复用的写入权限。只有已解析的结果才是完整准入证据;filter 回调可能先于后续策略失败发生。成员清单不会合成隐式父目录,因此整树消费者必须单独授权这些父路径。

将重量级 SDK、CLI 注册和长期运行时服务保留在完整入口中。

拆分 setup 和运行时界面的捆绑工作区频道可以改用 openclaw/plugin-sdk/channel-entry-contract 中的 defineBundledChannelSetupEntry(...)。它允许 setup 入口保留 setup 安全的 plugin/secrets 导出,同时仍暴露一个运行时 setter:

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* setup-safe route */
      },
    });
  },
});

仅当 setup 流程确实需要为未配置频道提供轻量级运行时 setter 或 setup 安全的 gateway 界面时,才使用此方法。 registerSetupRuntime 仅在 "setup-runtime" 加载时运行;请将其 限制为仅配置路由或该 setup 流程所需的方法。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw