跳到主要内容

插件（扩展）

快速开始（刚接触插件？）​

插件可以是以下两种之一：

  • 原生 OpenClaw 插件（openclaw.plugin.json + 运行时模块），或
  • 兼容的 bundle（.codex-plugin/plugin.json 或 .claude-plugin/plugin.json）

两者都会显示在 openclaw plugins 下，但只有原生 OpenClaw 插件会在进程内执行运行时代码。

大多数情况下，当你想要某项核心 OpenClaw 尚未内置的功能时，就会使用插件（或者你希望将可选功能保留在主安装之外）。

快捷路径：

  1. 查看当前已加载的内容：
openclaw plugins list
  1. 安装官方插件（示例：Voice Call）：
openclaw plugins install @openclaw/voice-call

Npm 规格仅支持 registry-only（包名 + 可选的 精确版本 或 dist-tag）。

Git/URL/file 规格和 semver 范围都会被拒绝。

裸规格和 @latest 会停留在稳定通道。如果 npm 将其中任一解析为预发布版本，OpenClaw 会停止并要求你通过预发布标签（例如 @beta/@rc）或精确的预发布版本显式选择加入。

  1. 重启 Gateway 网关，然后在 plugins.entries.<id>.config 下进行配置。

查看 Voice Call 获取一个具体的插件示例。 想找第三方列表？请查看 Community plugins。 需要了解 bundle 兼容性细节？请查看 Plugin bundles。

对于兼容的 bundle，可从本地目录或归档文件安装：

openclaw plugins install ./my-bundle
openclaw plugins install ./my-bundle.tgz

架构​

OpenClaw 的插件系统有四层：

  1. 清单 + 发现 OpenClaw 会从已配置路径、工作区根目录、全局扩展根目录以及随附扩展中查找候选插件。发现过程会先读取原生 openclaw.plugin.json 清单以及受支持的 bundle 清单。
  2. 启用 + 验证 核心会决定某个已发现插件是启用、禁用、阻止，还是被选用于某个独占插槽（例如内存）。
  3. 运行时加载 原生 OpenClaw 插件通过 jiti 在进程内加载，并将功能注册到一个中央注册表中。兼容的 bundle 会被规范化为注册表记录，而不会导入运行时代码。
  4. 表面消费 OpenClaw 的其余部分会读取注册表，以公开工具、渠道、提供商设置、hooks、HTTP 路由、CLI 命令和服务。

重要的设计边界：

  • 发现 + 配置验证应基于 manifest/schema 元数据 运行，而不执行插件代码
  • 原生运行时行为来自插件模块的 register(api) 路径

这种拆分让 OpenClaw 能够在完整运行时激活之前，就验证配置、解释缺失/被禁用的插件，并构建 UI/schema 提示。

兼容的 bundle​

OpenClaw 还识别两种兼容的外部 bundle 布局：

  • Codex 风格 bundle：.codex-plugin/plugin.json
  • Claude 风格 bundle：.claude-plugin/plugin.json，或者没有清单的默认 Claude 组件布局
  • Cursor 风格 bundle：.cursor-plugin/plugin.json

它们会在插件列表中显示为 format=bundle，并在详细/info 输出中显示 codex 或 claude 子类型。

有关精确的检测规则、映射行为和当前支持矩阵，请参阅 Plugin bundles。

目前，OpenClaw 将这些内容视为 能力包，而不是原生运行时插件：

  • 当前支持：捆绑的 skills
  • 当前支持：Claude commands/ markdown 根目录，映射到常规 OpenClaw 技能加载器
  • 当前支持：Claude bundle settings.json 默认值，用于嵌入式 Pi 智能体设置（会清理 shell override 键）
  • 当前支持：Cursor .cursor/commands/*.md 根目录，映射到常规 OpenClaw 技能加载器
  • 当前支持：使用 OpenClaw hook-pack 布局的 Codex bundle hook 目录（HOOK.md + handler.ts/handler.js）
  • 已检测但尚未接线：其他已声明的 bundle 能力，例如 agents、Claude hook 自动化、Cursor rules/hooks/MCP 元数据、MCP/app/LSP 元数据、输出样式

这意味着 bundle 的安装/发现/列表/info/启用都可正常工作，并且当 bundle 被启用时，bundle skills、Claude command-skills、Claude bundle settings 默认值以及兼容的 Codex hook 目录都会被加载，但 bundle 运行时代码不会在进程内执行。

Bundle hook 支持仅限于常规 OpenClaw hook 目录格式（在声明的 hook 根目录下使用 HOOK.md 加上 handler.ts/handler.js）。 供应商特定的 shell/JSON hook 运行时，包括 Claude hooks.json，当前仅会被检测，不会被直接执行。

执行模型​

原生 OpenClaw 插件与 Gateway 网关 在同一进程内 运行。它们不会进行沙箱隔离。已加载的原生插件与核心代码处于相同的进程级信任边界。

这意味着：

  • 原生插件可以注册工具、网络处理器、hooks 和服务
  • 原生插件中的 bug 可能导致 gateway 崩溃或不稳定
  • 恶意原生插件等同于在 OpenClaw 进程内部执行任意代码

兼容的 bundle 默认更安全，因为 OpenClaw 目前将它们视为元数据/内容包。在当前版本中，这主要意味着捆绑的技能。

对于非捆绑插件，请使用 allowlist 和显式安装/加载路径。将工作区插件视为开发期代码，而不是生产默认项。

重要信任说明：

  • plugins.allow 信任的是 plugin id，而不是来源出处。
  • 如果某个工作区插件与某个捆绑插件具有相同 id，那么启用/加入 allowlist 后，工作区插件会有意覆盖捆绑副本。
  • 这是一种正常且有用的行为，适合本地开发、补丁测试和热修复。

可用插件（官方）​

  • Microsoft Teams 自 2026.1.15 起仅以插件形式提供；如果你使用 Teams，请安装 @openclaw/msteams。
  • Memory（Core）— 捆绑的内存搜索插件（默认通过 plugins.slots.memory 启用）
  • Memory（LanceDB）— 捆绑的长期记忆插件（自动召回/捕获；设置 plugins.slots.memory = "memory-lancedb"）
  • Voice Call — @openclaw/voice-call
  • Zalo Personal — @openclaw/zalouser
  • Matrix — @openclaw/matrix
  • Nostr — @openclaw/nostr
  • Zalo — @openclaw/zalo
  • Microsoft Teams — @openclaw/msteams
  • Anthropic provider 运行时 — 以 anthropic 形式捆绑（默认启用）
  • BytePlus provider catalog — 以 byteplus 形式捆绑（默认启用）
  • Cloudflare AI Gateway provider catalog — 以 cloudflare-ai-gateway 形式捆绑（默认启用）
  • Google 网络搜索 + Gemini CLI OAuth — 以 google 形式捆绑（网页搜索会自动加载；provider 身份验证仍需选择启用）
  • GitHub Copilot provider 运行时 — 以 github-copilot 形式捆绑（默认启用）
  • Hugging Face provider catalog — 以 huggingface 形式捆绑（默认启用）
  • Kilo Gateway provider 运行时 — 以 kilocode 形式捆绑（默认启用）
  • Kimi Coding provider catalog — 以 kimi-coding 形式捆绑（默认启用）
  • MiniMax provider catalog + usage + OAuth — 以 minimax 形式捆绑（默认启用；拥有 minimax 和 minimax-portal）
  • Mistral provider 能力 — 以 mistral 形式捆绑（默认启用）
  • Model Studio provider catalog — 以 modelstudio 形式捆绑（默认启用）
  • Moonshot provider 运行时 — 以 moonshot 形式捆绑（默认启用）
  • NVIDIA provider catalog — 以 nvidia 形式捆绑（默认启用）
  • OpenAI provider 运行时 — 以 openai 形式捆绑（默认启用；同时拥有 openai 和 openai-codex）
  • OpenCode Go provider 能力 — 以 opencode-go 形式捆绑（默认启用）
  • OpenCode Zen provider 能力 — 以 opencode 形式捆绑（默认启用）
  • OpenRouter provider 运行时 — 以 openrouter 形式捆绑（默认启用）
  • Qianfan provider catalog — 以 qianfan 形式捆绑（默认启用）
  • Qwen OAuth（provider 身份验证 + catalog）— 以 qwen-portal-auth 形式捆绑（默认启用）
  • Synthetic provider catalog — 以 synthetic 形式捆绑（默认启用）
  • Together provider catalog — 以 together 形式捆绑（默认启用）
  • Venice provider catalog — 以 venice 形式捆绑（默认启用）
  • Vercel AI Gateway provider catalog — 以 vercel-ai-gateway 形式捆绑（默认启用）
  • Volcengine provider catalog — 以 volcengine 形式捆绑（默认启用）
  • Xiaomi provider catalog + usage — 以 xiaomi 形式捆绑（默认启用）
  • Z.AI provider 运行时 — 以 zai 形式捆绑（默认启用）
  • Copilot Proxy（provider 身份验证）— 本地 VS Code Copilot Proxy 桥接；不同于内置的 github-copilot 设备登录（已捆绑，默认禁用）

原生 OpenClaw 插件是通过 jiti 在运行时加载的 TypeScript 模块。 配置验证不会执行插件代码；它使用的是插件 manifest 和 JSON Schema。请参阅 Plugin manifest。

原生 OpenClaw 插件可以注册：

  • Gateway RPC 方法
  • Gateway HTTP 路由
  • 智能体工具
  • CLI 命令
  • 后台服务
  • 上下文引擎
  • provider 身份验证流程和模型目录
  • 用于动态模型 id、传输规范化、能力元数据、流包装、缓存 TTL 策略、缺失身份验证提示、内置模型抑制、目录增强、运行时身份验证交换以及 usage/billing 身份验证 + 快照解析的 provider 运行时 hooks
  • 可选配置验证
  • Skills（通过在插件 manifest 中列出 skills 目录）
  • 自动回复命令（无需调用 AI 智能体即可执行）

原生 OpenClaw 插件与 Gateway 网关 在同一进程内 运行，因此应将其视为受信任代码。 工具编写指南：Plugin agent tools。

Provider 运行时 hooks​

Provider 插件现在有两层：

  • manifest 元数据：providerAuthEnvVars，用于在运行时加载前进行低成本的环境身份验证查找
  • 配置时 hooks：catalog / 旧版 discovery
  • 运行时 hooks：resolveDynamicModel、prepareDynamicModel、normalizeResolvedModel、capabilities、prepareExtraParams、wrapStreamFn、formatApiKey、refreshOAuth、buildAuthDoctorHint、isCacheTtlEligible、buildMissingAuthMessage、suppressBuiltInModel、augmentModelCatalog、isBinaryThinking、supportsXHighThinking、resolveDefaultThinkingLevel、isModernModelRef、prepareRuntimeAuth、resolveUsageAuth、fetchUsageSnapshot

OpenClaw 仍然负责通用的智能体循环、故障切换、转录处理和工具策略。这些 hooks 是 provider 特定行为的接缝，而无需整个自定义推理传输层。

当 provider 具有基于环境变量的凭据，并且你希望通用 auth/status/model-picker 路径在不加载插件运行时的情况下就能看到这些凭据时，请使用 manifest providerAuthEnvVars。 保留 provider 运行时 envVars 用于面向操作员的提示，例如新手引导标签或 OAuth client-id/client-secret 设置环境变量。

Hook 顺序​

对于 model/provider 插件，OpenClaw 大致按以下顺序使用 hooks：

  1. catalog 在生成 models.json 期间，将 provider 配置发布到 models.providers 中。
  2. 内置/已发现模型查找 OpenClaw 会先尝试常规注册表/目录路径。
  3. resolveDynamicModel 对于本地注册表中尚不存在的 provider 自有 model id，进行同步后备解析。
  4. prepareDynamicModel 仅在异步模型解析路径上执行异步预热，然后再次运行 resolveDynamicModel。
  5. normalizeResolvedModel 在嵌入式运行器使用已解析模型之前进行最终重写。
  6. capabilities 由共享核心逻辑使用的 provider 自有转录/工具元数据。
  7. prepareExtraParams 在通用流选项包装器之前执行 provider 自有请求参数规范化。
  8. wrapStreamFn 在应用通用包装器之后执行 provider 自有流包装器。
  9. formatApiKey 当存储的 auth profile 需要转换为运行时 apiKey 字符串时，使用 provider 自有身份验证配置器。
  10. refreshOAuth 对自定义刷新端点或刷新失败策略执行 provider 自有 OAuth 刷新覆盖。
  11. buildAuthDoctorHint 当 OAuth 刷新失败时，追加 provider 自有修复提示。
  12. isCacheTtlEligible 为代理/backhaul provider 提供 provider 自有提示词缓存策略。
  13. buildMissingAuthMessage 用 provider 自有内容替换通用的缺失身份验证恢复消息。
  14. suppressBuiltInModel 执行 provider 自有的过时上游模型抑制，并可返回面向用户的错误提示。
  15. augmentModelCatalog 在发现后附加 provider 自有的合成/最终目录行。
  16. isBinaryThinking 为二元 thinking provider 提供 provider 自有的开/关推理切换。
  17. supportsXHighThinking 为选定模型提供 provider 自有的 xhigh 推理支持。
  18. resolveDefaultThinkingLevel 为特定模型家族提供 provider 自有的默认 /think 级别。
  19. isModernModelRef 提供 provider 自有的现代模型匹配器，用于 live profile 过滤器和 smoke 选择。
  20. prepareRuntimeAuth 在推理前将已配置的凭据交换为实际的运行时令牌/密钥。
  21. resolveUsageAuth 为 /usage 及相关状态表面解析 usage/billing 凭据。
  22. fetchUsageSnapshot 在身份验证解析完成后，抓取并规范化 provider 特定的 usage/quota 快照。

应该使用哪个 hook​

  • catalog：将 provider 配置和模型目录发布到 models.providers
  • resolveDynamicModel：处理本地注册表中尚未存在的透传或前向兼容 model id
  • prepareDynamicModel：在重试动态解析之前执行异步预热（例如刷新 provider 元数据缓存）
  • normalizeResolvedModel：在推理前重写已解析模型的传输/base URL/兼容性
  • capabilities：发布 provider 家族和转录/工具差异，而不在核心中硬编码 provider id
  • prepareExtraParams：在通用流包装之前设置 provider 默认值或规范化 provider 特定的每模型参数
  • wrapStreamFn：在仍使用常规 pi-ai 执行路径时，添加 provider 特定的 header/payload/model 兼容补丁
  • formatApiKey：将存储的 auth profile 转换为运行时 apiKey 字符串，而不在核心中硬编码 provider 令牌 blob
  • refreshOAuth：为不适配共享 pi-ai 刷新器的 provider 自主管理 OAuth 刷新
  • buildAuthDoctorHint：在刷新失败时追加 provider 自有的身份验证修复指导
  • isCacheTtlEligible：决定 provider/模型组合是否应使用 cache TTL 元数据
  • buildMissingAuthMessage：用 provider 特定恢复提示替换通用 auth-store 错误
  • suppressBuiltInModel：隐藏过时上游条目，并可在直接解析失败时返回 provider 自有错误
  • augmentModelCatalog：在发现和配置合并后附加合成/最终目录行
  • isBinaryThinking：在 /think 中公开二元开/关推理 UX，而不硬编码 provider id
  • supportsXHighThinking：让特定模型启用 xhigh 推理级别
  • resolveDefaultThinkingLevel：将 provider/模型默认推理策略移出核心
  • isModernModelRef：将 live/smoke 模型家族包含规则保留在 provider 中
  • prepareRuntimeAuth：将已配置凭据交换为请求所用的实际短期运行时令牌/密钥
  • resolveUsageAuth：为 usage/billing 端点解析 provider 自有凭据，而不在核心中硬编码令牌解析
  • fetchUsageSnapshot：由 provider 自主管理 usage 端点抓取/解析，而核心继续负责摘要扇出和格式化

经验法则：

  • provider 拥有目录或 base URL 默认值：使用 catalog
  • provider 接受任意上游 model id：使用 resolveDynamicModel
  • provider 在解析未知 id 前需要网络元数据：添加 prepareDynamicModel
  • provider 需要传输重写但仍使用核心传输：使用 normalizeResolvedModel
  • provider 需要转录/provider 家族差异：使用 capabilities
  • provider 需要默认请求参数或按 provider 清理参数：使用 prepareExtraParams
  • provider 需要请求 header/body/model 兼容包装而不使用自定义传输：使用 wrapStreamFn
  • provider 在 auth profile 中存储额外元数据并需要自定义运行时令牌格式：使用 formatApiKey
  • provider 需要自定义 OAuth 刷新端点或刷新失败策略：使用 refreshOAuth
  • provider 在刷新失败后需要 provider 自有身份验证修复指导：使用 buildAuthDoctorHint
  • provider 需要特定于代理的 cache TTL 门控：使用 isCacheTtlEligible
  • provider 需要 provider 特定的缺失身份验证恢复提示：使用 buildMissingAuthMessage
  • provider 需要隐藏过时上游条目或用厂商提示替换它们：使用 suppressBuiltInModel
  • provider 需要在 models list 和选择器中添加合成的前向兼容条目：使用 augmentModelCatalog
  • provider 仅提供二元 thinking 开/关：使用 isBinaryThinking
  • provider 只希望部分模型启用 xhigh：使用 supportsXHighThinking
  • provider 拥有某个模型家族默认 /think 策略：使用 resolveDefaultThinkingLevel
  • provider 拥有 live/smoke 首选模型匹配：使用 isModernModelRef
  • provider 需要令牌交换或短期请求凭据：使用 prepareRuntimeAuth
  • provider 需要自定义 usage/quota 令牌解析或不同的 usage 凭据：使用 resolveUsageAuth
  • provider 需要 provider 特定的 usage 端点或负载解析器：使用 fetchUsageSnapshot

如果 provider 需要完全自定义的线协议或自定义请求执行器，那属于另一类扩展。这些 hooks 适用于仍运行在 OpenClaw 常规推理循环上的 provider 行为。

Provider 示例​

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

内置示例​

  • Anthropic 使用 resolveDynamicModel、capabilities、buildAuthDoctorHint、resolveUsageAuth、fetchUsageSnapshot、isCacheTtlEligible、resolveDefaultThinkingLevel 和 isModernModelRef，因为它拥有 Claude 4.6 前向兼容、provider 家族提示、身份验证修复指导、usage 端点集成、提示词缓存资格以及 Claude 默认/自适应 thinking 策略。
  • OpenAI 使用 resolveDynamicModel、normalizeResolvedModel 和 capabilities，以及 buildMissingAuthMessage、suppressBuiltInModel、augmentModelCatalog、supportsXHighThinking 和 isModernModelRef，因为它拥有 GPT-5.4 前向兼容、直接 OpenAI openai-completions -> openai-responses 规范化、支持 Codex 的身份验证提示、Spark 抑制、合成 OpenAI 列表行以及 GPT-5 thinking / live-model 策略。
  • OpenRouter 使用 catalog 以及 resolveDynamicModel 和 prepareDynamicModel，因为该 provider 是透传型的，可能会在 OpenClaw 静态目录更新之前暴露新的 model id。
  • GitHub Copilot 使用 catalog、auth、resolveDynamicModel 和 capabilities，以及 prepareRuntimeAuth 和 fetchUsageSnapshot，因为它需要 provider 自有设备登录、模型回退行为、Claude 转录差异、GitHub token -> Copilot token 交换，以及 provider 自有 usage 端点。
  • OpenAI Codex 使用 catalog、resolveDynamicModel、normalizeResolvedModel、refreshOAuth 和 augmentModelCatalog，以及 prepareExtraParams、resolveUsageAuth 和 fetchUsageSnapshot，因为它仍运行在核心 OpenAI 传输之上，但拥有自己的传输/base URL 规范化、OAuth 刷新后备策略、默认传输选择、合成 Codex 目录行以及 ChatGPT usage 端点集成。
  • Google AI Studio 和 Gemini CLI OAuth 使用 resolveDynamicModel 和 isModernModelRef，因为它们拥有 Gemini 3.1 前向兼容后备和现代模型匹配；Gemini CLI OAuth 还使用 formatApiKey、resolveUsageAuth 和 fetchUsageSnapshot 来处理令牌格式化、令牌解析和 quota 端点接线。
  • OpenRouter 使用 capabilities、wrapStreamFn 和 isCacheTtlEligible，以便将 provider 特定的请求头、路由元数据、reasoning 补丁和提示词缓存策略从核心中移出。
  • Moonshot 使用 catalog 和 wrapStreamFn，因为它仍使用共享 OpenAI 传输，但需要 provider 自有 thinking 负载规范化。
  • Kilocode 使用 catalog、capabilities、wrapStreamFn 和 isCacheTtlEligible，因为它需要 provider 自有请求头、reasoning 负载规范化、Gemini 转录提示和 Anthropic cache-TTL 门控。
  • Z.AI 使用 resolveDynamicModel、prepareExtraParams、wrapStreamFn、isCacheTtlEligible、isBinaryThinking、isModernModelRef、resolveUsageAuth 和 fetchUsageSnapshot，因为它拥有 GLM-5 后备、tool_stream 默认值、二元 thinking UX、现代模型匹配，以及 usage 身份验证 + quota 抓取。
  • Mistral、OpenCode Zen 和 OpenCode Go 仅使用 capabilities，以便将转录/工具差异移出核心。
  • 仅目录型的捆绑 provider，例如 byteplus、cloudflare-ai-gateway、huggingface、kimi-coding、modelstudio、nvidia、qianfan、synthetic、together、venice、vercel-ai-gateway 和 volcengine，仅使用 catalog。
  • Qwen portal 使用 catalog、auth 和 refreshOAuth。
  • MiniMax 和 Xiaomi 使用 catalog 加 usage hooks，因为尽管推理仍通过共享传输运行，但它们的 /usage 行为由插件拥有。

加载流水线​

启动时，OpenClaw 大致会执行以下步骤：

  1. 发现候选插件根目录
  2. 读取原生或兼容 bundle 的 manifest 和包元数据
  3. 拒绝不安全的候选项
  4. 规范化插件配置（plugins.enabled、allow、deny、entries、slots、load.paths）
  5. 决定每个候选项的启用状态
  6. 通过 jiti 加载已启用的原生模块
  7. 调用原生 register(api) hooks，并将注册内容收集到插件注册表中
  8. 将注册表暴露给命令/运行时表面

安全门会在运行时执行 之前 发生。 当条目逃逸出插件根目录、路径对所有人可写，或对于非捆绑插件来说路径所有权看起来可疑时，候选项会被阻止。

清单优先行为​

Manifest 是控制面的事实来源。OpenClaw 用它来：

  • 识别插件
  • 发现声明的渠道/skills/配置 schema 或 bundle 能力
  • 验证 plugins.entries.<id>.config
  • 增强 Control UI 标签/占位符
  • 显示安装/目录元数据

对于原生插件，运行时模块是数据面部分。它注册实际行为，例如 hooks、工具、命令或 provider 流程。

加载器缓存了什么​

OpenClaw 会保留短期进程内缓存，用于：

  • 发现结果
  • manifest 注册表数据
  • 已加载的插件注册表

这些缓存可以减少突发启动和重复命令开销。你可以将它们理解为短生命周期的性能缓存，而不是持久化存储。

运行时辅助工具​

插件可以通过 api.runtime 访问部分核心辅助工具。对于电话 TTS：

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

说明：

  • 使用核心 messages.tts 配置（OpenAI 或 ElevenLabs）。
  • 返回 PCM 音频缓冲区 + 采样率。插件必须为 provider 重新采样/编码。
  • Edge TTS 不支持电话场景。

对于 STT/转录，插件可以调用：

const { text } = await api.runtime.stt.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // 当无法可靠推断 MIME 时可选：
  mime: "audio/ogg",
});

说明：

  • 使用核心媒体理解音频配置（tools.media.audio）和 provider 后备顺序。
  • 当没有生成转录输出时（例如输入被跳过/不受支持），返回 { text: undefined }。

Gateway HTTP 路由​

插件可以使用 api.registerHttpRoute(...) 公开 HTTP 端点。

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

路由字段：

  • path：Gateway 网关 HTTP 服务器下的路由路径。
  • auth：必填。使用 "gateway" 以要求常规 gateway 身份验证，或使用 "plugin" 以进行插件管理的身份验证/webhook 验证。
  • match：可选。"exact"（默认）或 "prefix"。
  • replaceExisting：可选。允许同一插件替换自身现有的路由注册。
  • handler：当路由处理了请求时返回 true。

说明：

  • api.registerHttpHandler(...) 已过时。请使用 api.registerHttpRoute(...)。
  • 插件路由必须显式声明 auth。
  • 除非设置 replaceExisting: true，否则精确 path + match 冲突会被拒绝，而且一个插件不能替换另一个插件的路由。
  • 具有不同 auth 级别的重叠路由会被拒绝。请仅在相同 auth 级别上保留 exact/prefix 贯穿链。

Plugin SDK 导入路径​

编写插件时，请使用 SDK 子路径，而不是单体式 openclaw/plugin-sdk 导入：

  • openclaw/plugin-sdk/core 用于通用插件 API、provider 身份验证类型和共享辅助工具。
  • openclaw/plugin-sdk/compat 用于比 core 需要更广泛共享运行时辅助工具的捆绑/内部插件代码。
  • openclaw/plugin-sdk/telegram 用于 Telegram 渠道插件。
  • openclaw/plugin-sdk/discord 用于 Discord 渠道插件。
  • openclaw/plugin-sdk/slack 用于 Slack 渠道插件。
  • openclaw/plugin-sdk/signal 用于 Signal 渠道插件。
  • openclaw/plugin-sdk/imessage 用于 iMessage 渠道插件。
  • openclaw/plugin-sdk/whatsapp 用于 WhatsApp 渠道插件。
  • openclaw/plugin-sdk/line 用于 LINE 渠道插件。
  • openclaw/plugin-sdk/msteams 用于捆绑的 Microsoft Teams 插件表面。
  • 也提供捆绑扩展专用子路径： openclaw/plugin-sdk/acpx、openclaw/plugin-sdk/bluebubbles、 openclaw/plugin-sdk/copilot-proxy、openclaw/plugin-sdk/device-pair、 openclaw/plugin-sdk/diagnostics-otel、openclaw/plugin-sdk/diffs、 openclaw/plugin-sdk/feishu、openclaw/plugin-sdk/googlechat、 openclaw/plugin-sdk/irc、openclaw/plugin-sdk/llm-task、 openclaw/plugin-sdk/lobster、openclaw/plugin-sdk/matrix、 openclaw/plugin-sdk/mattermost、openclaw/plugin-sdk/memory-core、 openclaw/plugin-sdk/memory-lancedb、 openclaw/plugin-sdk/minimax-portal-auth、 openclaw/plugin-sdk/nextcloud-talk、openclaw/plugin-sdk/nostr、 openclaw/plugin-sdk/open-prose、openclaw/plugin-sdk/phone-control、 openclaw/plugin-sdk/qwen-portal-auth、openclaw/plugin-sdk/synology-chat、 openclaw/plugin-sdk/talk-voice、openclaw/plugin-sdk/test-utils、 openclaw/plugin-sdk/thread-ownership、openclaw/plugin-sdk/tlon、 openclaw/plugin-sdk/twitch、openclaw/plugin-sdk/voice-call、 openclaw/plugin-sdk/zalo 和 openclaw/plugin-sdk/zalouser。

Provider 目录​

Provider 插件可以使用 registerProvider({ catalog: { run(...) { ... } } }) 定义用于推理的模型目录。

catalog.run(...) 返回与 OpenClaw 写入 models.providers 相同的结构：

  • { provider } 表示一个 provider 条目
  • { providers } 表示多个 provider 条目

当插件拥有 provider 特定的 model id、base URL 默认值或由身份验证控制的模型元数据时，请使用 catalog。

catalog.order 控制插件目录相对于 OpenClaw 内置隐式 provider 的合并时机：

  • simple：纯 API 密钥或环境变量驱动的 provider
  • profile：当存在 auth profile 时出现的 provider
  • paired：会合成多个相关 provider 条目的 provider
  • late：最后一轮，在其他隐式 provider 之后

后出现的 provider 会在键冲突时胜出，因此插件可以有意用相同 provider id 覆盖内置 provider 条目。

兼容性：

  • discovery 仍可作为旧版别名使用
  • 如果同时注册了 catalog 和 discovery，OpenClaw 会使用 catalog

兼容性说明：

  • openclaw/plugin-sdk 仍支持现有外部插件。
  • 新的和已迁移的捆绑插件应使用渠道或扩展专用子路径；通用表面使用 core，只有在确实需要更广泛共享辅助工具时才使用 compat。

只读渠道检查​

如果你的插件注册了一个渠道，建议与 resolveAccount(...) 一起实现 plugin.config.inspectAccount(cfg, accountId)。

原因：

  • resolveAccount(...) 是运行时路径。它可以假定凭据已完全实体化，并在缺少所需 secret 时快速失败。
  • 只读命令路径，例如 openclaw status、openclaw status --all、 openclaw channels status、openclaw channels resolve 以及 Doctor/配置修复流程，不应仅为了描述配置就必须实体化运行时凭据。

推荐的 inspectAccount(...) 行为：

  • 仅返回描述性的账户状态。
  • 保留 enabled 和 configured。
  • 在相关时包含凭据来源/状态字段，例如：
    • tokenSource、tokenStatus
    • botTokenSource、botTokenStatus
    • appTokenSource、appTokenStatus
    • signingSecretSource、signingSecretStatus
  • 你无需为了报告只读可用性而返回原始令牌值。返回 tokenStatus: "available"（以及匹配的 source 字段）就足够支持状态类命令。
  • 当凭据通过 SecretRef 配置，但在当前命令路径中不可用时，请使用 configured_unavailable。

这使得只读命令可以报告“已配置，但在此命令路径中不可用”，而不是崩溃或错误地将账户报告为未配置。

性能说明：

  • 插件发现和 manifest 元数据使用短期进程内缓存，以减少突发启动/重载工作。
  • 设置 OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 或 OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 可禁用这些缓存。
  • 使用 OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS 和 OPENCLAW_PLUGIN_MANIFEST_CACHE_MS 调整缓存窗口。

设备发现 + 传输协议优先级​

OpenClaw 按以下顺序扫描：

  1. 配置路径
  • plugins.load.paths（文件或目录）
  1. 工作区扩展
  • <workspace>/.openclaw/extensions/*.ts
  • <workspace>/.openclaw/extensions/*/index.ts
  1. 全局扩展
  • ~/.openclaw/extensions/*.ts
  • ~/.openclaw/extensions/*/index.ts
  1. 捆绑扩展（随 OpenClaw 一起提供；默认开启/关闭混合）
  • <openclaw>/extensions/*

许多捆绑的 provider 插件默认启用，这样模型目录/运行时 hooks 无需额外设置即可使用。其他插件仍需要通过 plugins.entries.<id>.enabled 或 openclaw plugins enable <id> 显式启用。

默认开启的捆绑插件示例：

  • byteplus
  • cloudflare-ai-gateway
  • device-pair
  • github-copilot
  • huggingface
  • kilocode
  • kimi-coding
  • minimax
  • minimax
  • modelstudio
  • moonshot
  • nvidia
  • ollama
  • openai
  • openrouter
  • phone-control
  • qianfan
  • qwen-portal-auth
  • sglang
  • synthetic
  • talk-voice
  • together
  • venice
  • vercel-ai-gateway
  • vllm
  • volcengine
  • xiaomi
  • 活跃的 memory 插槽插件（默认插槽：memory-core）

已安装的插件默认启用，但也可以用同样方式禁用。

工作区插件 默认禁用，除非你显式启用它们或将其加入 allowlist。这是有意设计的：已检出的仓库不应悄悄变成生产 gateway 代码。

加固说明：

  • 如果 plugins.allow 为空且可发现非捆绑插件，OpenClaw 会在启动时记录一条警告，其中包含 plugin id 和来源。
  • 候选路径在被接受进入发现流程前会经过安全检查。当出现以下情况时，OpenClaw 会阻止候选项：
    • 扩展条目解析到插件根目录之外（包括符号链接/路径遍历逃逸），
    • 插件根目录/来源路径对所有人可写，
    • 对于非捆绑插件来说，路径所有权可疑（POSIX owner 既不是当前 uid 也不是 root）。
  • 对于缺少安装/加载路径来源信息的已加载非捆绑插件，会发出警告，以便你固定信任（plugins.allow）或安装跟踪（plugins.installs）。

每个原生 OpenClaw 插件都必须在其根目录中包含一个 openclaw.plugin.json 文件。 如果某条路径指向一个文件，则插件根目录是该文件所在目录，并且该目录必须包含该 manifest。

兼容的 bundle 可以改为提供以下之一：

  • .codex-plugin/plugin.json
  • .claude-plugin/plugin.json

Bundle 目录会从与原生插件相同的根目录中被发现。

如果多个插件解析为同一个 id，则以上顺序中的第一个匹配项胜出，优先级更低的副本会被忽略。

这意味着：

  • 工作区插件会有意覆盖具有相同 id 的捆绑插件
  • plugins.allow: ["foo"] 按 id 授权活动的 foo 插件，即使活动副本来自工作区而非捆绑扩展根目录
  • 如果你需要更严格的来源控制，请使用显式安装/加载路径，并在启用前检查解析后的插件来源

启用规则​

启用状态在发现后解析：

  • plugins.enabled: false 会禁用所有插件
  • plugins.deny 总是优先
  • plugins.entries.<id>.enabled: false 会禁用该插件
  • 来源于工作区的插件默认禁用
  • 当 plugins.allow 非空时，allowlist 会限制活动集合
  • allowlist 是 基于 id 的，而不是基于来源
  • 捆绑插件默认禁用，除非：
    • 捆绑 id 位于内置默认开启集合中，或
    • 你显式启用了它，或
    • 渠道配置隐式启用了捆绑渠道插件
  • 独占插槽可强制启用为该插槽选择的插件

在当前核心中，默认开启的捆绑 id 包括上面的本地/provider 辅助工具以及当前活跃的 memory 插槽插件。

包集合​

插件目录可以包含带有 openclaw.extensions 的 package.json：

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

每个条目都会成为一个插件。如果该集合列出多个扩展，则插件 id 将变为 name/<fileBase>。

如果你的插件导入 npm 依赖，请在该目录中安装它们，以便 node_modules 可用（npm install / pnpm install）。

安全护栏：每个 openclaw.extensions 条目在解析符号链接后都必须保持在插件目录内。逃逸出包目录的条目会被拒绝。

安全说明：openclaw plugins install 会使用 npm install --ignore-scripts 安装插件依赖（不会运行生命周期脚本）。 请保持插件依赖树为“纯 JS/TS”，并避免需要 postinstall 构建的包。

可选项：openclaw.setupEntry 可以指向一个轻量级、仅用于 setup 的模块。 当 OpenClaw 需要为一个已禁用的渠道插件提供 setup 表面，或某个渠道插件虽然已启用但仍未配置时，它会加载 setupEntry，而不是完整插件入口。 当你的主插件入口还连接了工具、hooks 或其他仅运行时代码时，这能让启动和 setup 更轻量。

渠道目录元数据​

渠道插件可以通过 openclaw.channel 公布 setup/discovery 元数据，并通过 openclaw.install 公布安装提示。这使核心目录保持无数据化。

示例：

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "通过 Nextcloud Talk webhook bot 提供的自托管聊天。",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

OpenClaw 还可以合并 外部渠道目录（例如 MPM registry 导出）。 将 JSON 文件放到以下任一位置：

  • ~/.openclaw/mpm/plugins.json
  • ~/.openclaw/mpm/catalog.json
  • ~/.openclaw/plugins/catalog.json

或者将 OPENCLAW_PLUGIN_CATALOG_PATHS（或 OPENCLAW_MPM_CATALOG_PATHS）指向一个或多个 JSON 文件（用逗号/分号/PATH 分隔）。 每个文件应包含 { "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }。

Plugin ID​

默认 plugin id：

  • 包集合：package.json 中的 name
  • 独立文件：文件基础名（~/.../voice-call.ts → voice-call）

如果插件导出 id，OpenClaw 会使用它，但如果它与配置的 id 不匹配，则会发出警告。

注册表模型​

已加载的插件不会直接修改任意核心全局对象。它们会注册到一个中央插件注册表中。

该注册表跟踪：

  • 插件记录（身份、来源、出处、状态、诊断）
  • 工具
  • 旧版 hooks 和类型化 hooks
  • 渠道
  • providers
  • Gateway RPC 处理器
  • HTTP 路由
  • CLI 注册器
  • 后台服务
  • 插件自有命令

然后，核心功能会从这个注册表中读取，而不是直接与插件模块交互。这样可以保持单向加载：

  • 插件模块 -> 注册表注册
  • 核心运行时 -> 注册表消费

这种分离对可维护性非常重要。这意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“为每个插件模块做特殊处理”。

配置​

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

字段：

  • enabled：总开关（默认：true）
  • allow：allowlist（可选）
  • deny：denylist（可选；deny 优先）
  • load.paths：额外的插件文件/目录
  • slots：独占插槽选择器，例如 memory 和 contextEngine
  • entries.<id>：每插件开关 + 配置

配置更改 需要重启 gateway。

验证规则（严格）：

  • entries、allow、deny 或 slots 中出现未知 plugin id 都是 错误。
  • 未知的 channels.<id> 键都是 错误，除非某个插件 manifest 声明了该渠道 id。
  • 原生插件配置使用嵌入在 openclaw.plugin.json 中的 JSON Schema（configSchema）进行验证。
  • 兼容的 bundle 当前不公开原生 OpenClaw 配置 schema。
  • 如果某个插件被禁用，其配置会被保留，并发出 警告。

禁用 vs 缺失 vs 无效​

这些状态有意区分：

  • disabled：插件存在，但启用规则将其关闭
  • missing：配置引用了某个 plugin id，但发现过程没有找到它
  • invalid：插件存在，但其配置与声明的 schema 不匹配

OpenClaw 会保留已禁用插件的配置，因此重新启用它们不会造成破坏。

Plugin 插槽（独占类别）​

某些插件类别是 独占的（一次只能有一个处于活动状态）。使用 plugins.slots 选择由哪个插件拥有该插槽：

{
  plugins: {
    slots: {
      memory: "memory-core", // 或 "none" 以禁用 memory 插件
      contextEngine: "legacy", // 或某个 plugin id，例如 "lossless-claw"
    },
  },
}

支持的独占插槽：

  • memory：活动 memory 插件（"none" 会禁用 memory 插件）
  • contextEngine：活动上下文引擎插件（"legacy" 是内置默认值）

如果多个插件声明了 kind: "memory" 或 kind: "context-engine"，则只有为该插槽选中的插件会加载。其他插件会被禁用并附带诊断信息。

上下文引擎插件​

上下文引擎插件拥有会话上下文编排能力，包括摄取、组装和压缩。 通过插件中的 api.registerContextEngine(id, factory) 注册它们，然后使用 plugins.slots.contextEngine 选择活动引擎。

当你的插件需要替换或扩展默认上下文流水线，而不是仅添加内存搜索或 hooks 时，请使用此方式。

Control UI（schema + 标签）​

Control UI 使用 config.schema（JSON Schema + uiHints）来渲染更好的表单。

OpenClaw 会在运行时根据已发现的插件增强 uiHints：

  • 为 plugins.entries.<id> / .enabled / .config 添加每插件标签
  • 合并可选的插件提供配置字段提示，路径为： plugins.entries.<id>.config.<field>

如果你希望插件配置字段显示更好的标签/占位符（并将 secret 标记为敏感），请在插件 manifest 中连同 JSON Schema 一起提供 uiHints。

示例：

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true },
    "region": { "label": "Region", "placeholder": "us-east-1" }
  }
}

CLI​

openclaw plugins list
openclaw plugins info <id>
openclaw plugins install <path>                 # 将本地文件/目录复制到 ~/.openclaw/extensions/<id>
openclaw plugins install ./extensions/voice-call # 支持相对路径
openclaw plugins install ./plugin.tgz           # 从本地 tarball 安装
openclaw plugins install ./plugin.zip           # 从本地 zip 安装
openclaw plugins install -l ./extensions/voice-call # link（不复制），用于开发
openclaw plugins install @openclaw/voice-call # 从 npm 安装
openclaw plugins install @openclaw/voice-call --pin # 存储精确解析后的 name@version
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

openclaw plugins list 会将顶层格式显示为 openclaw 或 bundle。 详细列表/info 输出还会显示 bundle 子类型（codex 或 claude）以及已检测到的 bundle 能力。

plugins update 仅适用于在 plugins.installs 下跟踪的 npm 安装。 如果更新之间存储的完整性元数据发生变化，OpenClaw 会发出警告并要求确认（使用全局 --yes 可绕过提示）。

插件也可以注册自己的顶层命令（例如：openclaw voicecall）。

Plugin API（概览）​

插件导出形式可以是：

  • 一个函数：(api) => { ... }
  • 一个对象：{ id, name, configSchema, register(api) { ... } }

register(api) 是插件挂接行为的地方。常见注册包括：

  • registerTool
  • registerHook
  • on(...) 用于类型化生命周期 hooks
  • registerChannel
  • registerProvider
  • registerHttpRoute
  • registerCommand
  • registerCli
  • registerContextEngine
  • registerService

上下文引擎插件还可以注册一个由运行时拥有的上下文管理器：

export default function (api) {
  api.registerContextEngine("lossless-claw", () => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

如果你的引擎并不拥有压缩算法，仍然要实现 compact()，并显式委托给运行时：

import { delegateCompactionToRuntime } from "openclaw/plugin-sdk";

export default function (api) {
  api.registerContextEngine("my-memory-engine", () => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

ownsCompaction: false 不会自动回退到 legacy 压缩路径。 只要该引擎处于激活状态，它自己的 compact() 仍然会处理 /compact 和溢出恢复。

然后在配置中启用它：

{
  plugins: {
    slots: {
      contextEngine: "lossless-claw",
    },
  },
}

Plugin hooks​

插件可以在运行时注册 hooks。这让插件能够打包事件驱动自动化，而无需单独安装 hook pack。

示例​

export default function register(api) {
  api.registerHook(
    "command:new",
    async () => {
      // Hook 逻辑写在这里。
    },
    {
      name: "my-plugin.command-new",
      description: "当 /new 被调用时运行",
    },
  );
}

说明：

  • 通过 api.registerHook(...) 显式注册 hooks。
  • Hook 资格规则仍然适用（OS/bins/env/config 要求）。
  • 插件管理的 hooks 会在 openclaw hooks list 中显示为 plugin:<id>。
  • 你不能通过 openclaw hooks 启用/禁用插件管理的 hooks；应改为启用/禁用插件本身。

智能体生命周期 hooks（api.on）​

对于类型化运行时生命周期 hooks，请使用 api.on(...)：

export default function register(api) {
  api.on(
    "before_prompt_build",
    (event, ctx) => {
      return {
        prependSystemContext: "Follow company style guide.",
      };
    },
    { priority: 10 },
  );
}

用于提示词构建的重要 hooks：

  • before_model_resolve：在加载会话之前运行（messages 不可用）。用它来确定性地覆盖 modelOverride 或 providerOverride。
  • before_prompt_build：在加载会话之后运行（messages 可用）。用它来塑造提示词输入。
  • before_agent_start：旧版兼容 hook。优先使用上面两个更明确的 hooks。

核心强制执行的 hook 策略：

  • 操作员可以通过 plugins.entries.<id>.hooks.allowPromptInjection: false 按插件禁用提示词变更 hooks。
  • 禁用后，OpenClaw 会阻止 before_prompt_build，并忽略旧版 before_agent_start 返回的提示词变更字段，同时保留旧版 modelOverride 和 providerOverride。

before_prompt_build 结果字段：

  • prependContext：为本次运行在用户提示词前插入文本。最适合按轮次变化或动态内容。
  • systemPrompt：完整的系统提示词覆盖。
  • prependSystemContext：在当前系统提示词前插入文本。
  • appendSystemContext：在当前系统提示词后追加文本。

嵌入式运行时中的提示词构建顺序：

  1. 将 prependContext 应用到用户提示词。
  2. 如果提供了 systemPrompt，则应用其覆盖。
  3. 应用 prependSystemContext + 当前系统提示词 + appendSystemContext。

合并与优先级说明：

  • Hook 处理器按优先级运行（高者优先）。
  • 对于合并型上下文字段，值会按执行顺序拼接。
  • before_prompt_build 的值会在旧版 before_agent_start 后备值之前应用。

迁移指导：

  • 将静态指导从 prependContext 移到 prependSystemContext（或 appendSystemContext），这样 provider 就可以缓存稳定的系统前缀内容。
  • 将 prependContext 保留给每轮动态上下文，这类内容应继续与用户消息绑定。

Provider 插件（模型身份验证）​

插件可以注册 模型 providers，从而让用户能够在 OpenClaw 内完成 OAuth 或 API 密钥设置、在新手引导/模型选择器中显示 provider 设置，并参与隐式 provider 发现。

Provider 插件现在是模型 provider 设置的模块化扩展接缝。它们不再只是“OAuth 辅助工具”。

Provider 插件生命周期​

一个 provider 插件可以参与五个不同阶段：

  1. 身份验证 auth[].run(ctx) 执行 OAuth、API 密钥采集、设备码或自定义设置，并返回 auth profile 以及可选的配置补丁。
  2. 非交互式设置 auth[].runNonInteractive(ctx) 处理 openclaw onboard --non-interactive，且不进行提示。当 provider 需要超出内置简单 API 密钥路径之外的自定义无头设置时，请使用它。
  3. 向导集成 wizard.setup 会向 openclaw onboard 添加一个条目。 wizard.modelPicker 会向模型选择器添加一个 setup 条目。
  4. 隐式发现 discovery.run(ctx) 可以在模型解析/列出期间自动贡献 provider 配置。
  5. 选择后跟进 onModelSelected(ctx) 会在模型被选中后运行。可用于 provider 特定的后续工作，例如下载本地模型。

这是推荐的拆分方式，因为这些阶段具有不同的生命周期要求：

  • auth 是交互式的，并会写入凭据/配置
  • 非交互式设置由 flag/env 驱动，且不能提示
  • 向导元数据是静态且面向 UI 的
  • discovery 应安全、快速且能容忍失败
  • 选择后 hooks 是与所选模型绑定的副作用

Provider 身份验证契约​

auth[].run(ctx) 返回：

  • profiles：要写入的 auth profile
  • configPatch：可选的 openclaw.json 变更
  • defaultModel：可选的 provider/model 引用
  • notes：可选的面向用户备注

然后核心会：

  1. 写入返回的 auth profile
  2. 应用 auth-profile 配置接线
  3. 合并配置补丁
  4. 可选地应用默认模型
  5. 在适当时运行 provider 的 onModelSelected hook

这意味着 provider 插件拥有 provider 特定的设置逻辑，而核心拥有通用的持久化和配置合并路径。

Provider 非交互式契约​

auth[].runNonInteractive(ctx) 是可选的。当 provider 需要无法通过内置通用 API 密钥流表达的无头设置时，请实现它。

非交互式上下文包括：

  • 当前配置和基础配置
  • 解析后的 onboarding CLI 选项
  • 运行时日志/错误辅助工具
  • 智能体/工作区目录，以便 provider 将 auth 持久化到与其余 onboarding 相同的作用域存储中
  • resolveApiKey(...)：在遵守 --secret-input-mode 的同时，从 flags、环境变量或现有 auth profile 中读取 provider 密钥
  • toApiKeyCredential(...)：将解析后的密钥转换为 auth-profile 凭据，并使用正确的明文或 secret-ref 存储方式

适合使用此表面的 provider 包括：

  • 需要 --custom-base-url + --custom-model-id 的自托管 OpenAI 兼容运行时
  • 需要 provider 特定非交互式验证或配置合成的场景

不要从 runNonInteractive 中发出提示。对于缺失输入，请改为返回可操作的错误。

Provider 向导元数据​

wizard.setup 控制 provider 在分组新手引导中的显示方式：

  • choiceId：auth-choice 值
  • choiceLabel：选项标签
  • choiceHint：简短提示
  • groupId：分组桶 id
  • groupLabel：分组标签
  • groupHint：分组提示
  • methodId：要运行的身份验证方法

wizard.modelPicker 控制 provider 在模型选择中作为“现在设置它”条目的显示方式：

  • label
  • hint
  • methodId

当 provider 具有多种身份验证方法时，向导可以显式指向其中一种方法，也可以让 OpenClaw 为每种方法自动生成选择项。

在插件注册时，OpenClaw 会验证 provider 向导元数据：

  • 重复或空白的 auth-method id 会被拒绝
  • 当 provider 没有身份验证方法时，向导元数据会被忽略
  • 无效的 methodId 绑定会降级为警告，并回退到 provider 剩余的身份验证方法

Provider discovery 契约​

discovery.run(ctx) 返回以下之一：

  • { provider }
  • { providers }
  • null

当插件拥有一个 provider id 时，请使用 { provider } 这一常见情况。 当插件发现多个 provider 条目时，请使用 { providers }。

Discovery 上下文包括：

  • 当前配置
  • 智能体/工作区目录
  • 进程环境变量
  • 一个用于解析 provider API 密钥以及发现安全 API 密钥值的辅助工具

Discovery 应该：

  • 快速
  • 尽力而为
  • 在失败时可安全跳过
  • 谨慎处理副作用

它不应依赖提示或长时间运行的设置。

发现顺序​

Provider discovery 按有序阶段运行：

  • simple
  • profile
  • paired
  • late

使用建议：

  • simple：用于廉价的纯环境变量发现
  • profile：当发现依赖 auth profile 时使用
  • paired：用于需要与另一步发现协作的 provider
  • late：用于昂贵或本地网络探测

大多数自托管 provider 应使用 late。

良好的 provider-plugin 边界​

适合做成 provider 插件的情况：

  • 具有自定义设置流程的本地/自托管 providers
  • provider 特定的 OAuth/设备码登录
  • 对本地模型服务器的隐式发现
  • 选择后的副作用，例如拉取模型

不太有说服力的情况：

  • 仅在 env var、base URL 和一个默认模型上不同的简单 API 密钥型 provider

这些仍然可以做成插件，但最大的模块化收益来自先抽离那些行为丰富的 providers。

通过 api.registerProvider(...) 注册 provider。每个 provider 暴露一个或多个身份验证方法（OAuth、API key、device code 等）。这些方法可以驱动：

  • openclaw models auth login --provider <id> [--method <id>]
  • openclaw onboard
  • 模型选择器中的“自定义 provider”设置条目
  • 模型解析/列出期间的隐式 provider 发现

示例：

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // 运行 OAuth 流并返回 auth profile。
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
  wizard: {
    setup: {
      choiceId: "acme",
      choiceLabel: "AcmeAI",
      groupId: "acme",
      groupLabel: "AcmeAI",
      methodId: "oauth",
    },
    modelPicker: {
      label: "AcmeAI（自定义）",
      hint: "连接一个自托管 AcmeAI 端点",
      methodId: "oauth",
    },
  },
  discovery: {
    order: "late",
    run: async () => ({
      provider: {
        baseUrl: "https://acme.example/v1",
        api: "openai-completions",
        apiKey: "${ACME_API_KEY}",
        models: [],
      },
    }),
  },
});

说明：

  • run 会接收一个 ProviderAuthContext，其中包含 prompter、runtime、 openUrl、oauth.createVpsAwareHandlers、secretInputMode 和 allowSecretRefPrompt 辅助工具/状态。新手引导/配置流程可以用它们来遵守 --secret-input-mode，或提供 env/file/exec secret-ref 采集，而 openclaw models auth 会保持更严格的提示表面。
  • runNonInteractive 会接收一个 ProviderAuthMethodNonInteractiveContext， 其中包含 opts、agentDir、resolveApiKey 和 toApiKeyCredential 辅助工具，用于无头 onboarding。
  • 当你需要添加默认模型或 provider 配置时，请返回 configPatch。
  • 返回 defaultModel，这样 --set-default 就能更新智能体默认值。
  • wizard.setup 会向 openclaw onboard 添加一个 provider 选项。
  • wizard.modelPicker 会向模型选择器添加一个“设置此 provider”条目。
  • discovery.run 对于插件自有 provider id 返回 { provider }，对于多 provider 发现返回 { providers }。
  • discovery.order 控制该 provider 相对于内置发现阶段的运行时机：simple、profile、paired 或 late。
  • onModelSelected 是选择后的 hook，用于 provider 特定的后续工作，例如拉取本地模型。

注册一个消息渠道​

插件可以注册 渠道插件，其行为类似内置渠道 （WhatsApp、Telegram 等）。渠道配置位于 channels.<id> 下，并由你的渠道插件代码进行验证。

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "演示渠道插件。",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

说明：

  • 将配置放在 channels.<id> 下（而不是 plugins.entries）。
  • meta.label 用于 CLI/UI 列表中的标签。
  • meta.aliases 会为规范化和 CLI 输入添加备用 id。
  • meta.preferOver 列出当两者都已配置时应跳过自动启用的渠道 id。
  • meta.detailLabel 和 meta.systemImage 让 UI 能显示更丰富的渠道标签/图标。

渠道 setup hooks​

推荐的 setup 拆分：

  • plugin.setup 负责账户 id 规范化、验证和配置写入。
  • plugin.setupWizard 让宿主运行通用向导流程，而渠道只提供状态、凭据、私信 allowlist 和渠道访问描述符。

plugin.setupWizard 最适合符合共享模式的渠道：

  • 一个由 plugin.config.listAccountIds 驱动的账户选择器
  • 在提示前执行可选的预检/准备步骤（例如安装器/引导工作）
  • 为捆绑凭据集提供可选的环境变量快捷提示（例如成对 bot/app token）
  • 一个或多个凭据提示，每一步要么通过 plugin.setup.applyAccountConfig 写入，要么通过渠道自有部分补丁写入
  • 可选的非 secret 文本提示（例如 CLI 路径、base URL、账户 id）
  • 可选的由宿主解析的渠道/群组访问 allowlist 提示
  • 可选的私信 allowlist 解析（例如 @username -> 数字 id）
  • setup 完成后的可选完成说明

编写一个新的消息渠道（分步说明）​

当你想要一个 新的聊天表面（即“消息渠道”），而不是模型 provider 时，请使用本节。 模型 provider 文档位于 /providers/*。

  1. 选择一个 id + 配置结构
  • 所有渠道配置都位于 channels.<id> 下。
  • 对于多账户设置，优先使用 channels.<id>.accounts.<accountId>。
  1. 定义渠道元数据
  • meta.label、meta.selectionLabel、meta.docsPath、meta.blurb 控制 CLI/UI 列表。
  • meta.docsPath 应指向类似 /channels/<id> 的文档页面。
  • meta.preferOver 允许一个插件替换另一个渠道（自动启用时优先它）。
  • meta.detailLabel 和 meta.systemImage 供 UI 用于详情文字/图标。
  1. 实现所需适配器
  • config.listAccountIds + config.resolveAccount
  • capabilities（聊天类型、媒体、线程等）
  • outbound.deliveryMode + outbound.sendText（基础发送）
  1. 视需要添加可选适配器
  • setup（验证 + 配置写入）、setupWizard（宿主拥有的向导）、security（私信策略）、status（健康/诊断）
  • gateway（启动/停止/登录）、mentions、threading、streaming
  • actions（消息动作）、commands（原生命令行为）
  1. 在你的插件中注册该渠道
  • api.registerChannel({ plugin })

最小配置示例：

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "ACME_TOKEN", enabled: true },
      },
    },
  },
}

最小渠道插件（仅出站）：

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat 消息渠道。",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // 在这里将 `text` 发送到你的渠道
      return { ok: true };
    },
  },
};

export default function (api) {
  api.registerChannel({ plugin });
}

加载插件（扩展目录或 plugins.load.paths），重启 gateway， 然后在配置中设置 channels.<id>。

智能体工具​

请参阅专门指南：Plugin agent tools。

注册一个 Gateway RPC 方法​

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

注册 CLI 命令​

export default function (api) {
  api.registerCli(
    ({ program }) => {
      program.command("mycmd").action(() => {
        console.log("Hello");
      });
    },
    { commands: ["mycmd"] },
  );
}

注册自动回复命令​

插件可以注册自定义 slash 命令，这些命令 无需调用 AI 智能体 即可执行。 这对开关命令、状态检查或不需要 LLM 处理的快捷操作非常有用。

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "显示插件状态",
    handler: (ctx) => ({
      text: `插件正在运行！渠道：${ctx.channel}`,
    }),
  });
}

命令处理器上下文：

  • senderId：发送者的 ID（如果可用）
  • channel：发送命令的渠道
  • isAuthorizedSender：发送者是否为已授权用户
  • args：命令后的参数（如果 acceptsArgs: true）
  • commandBody：完整命令文本
  • config：当前 OpenClaw 配置

命令选项：

  • name：命令名（不含前导 /）
  • nativeNames：可选的原生命令别名，用于 slash/menu 表面。对所有原生 provider 使用 default，或使用如 discord 这样的 provider 特定键
  • description：在命令列表中显示的帮助文本
  • acceptsArgs：命令是否接受参数（默认：false）。如果为 false 且提供了参数，则命令不会匹配，消息会继续传递给其他处理器
  • requireAuth：是否要求发送者已授权（默认：true）
  • handler：返回 { text: string } 的函数（可以是异步）

带授权和参数的示例：

api.registerCommand({
  name: "setmode",
  description: "设置插件模式",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    const mode = ctx.args?.trim() || "default";
    await saveMode(mode);
    return { text: `模式已设置为：${mode}` };
  },
});

说明：

  • 插件命令会在内置命令和 AI 智能体 之前 处理
  • 命令是全局注册的，适用于所有渠道
  • 命令名不区分大小写（/MyStatus 可匹配 /mystatus）
  • 命令名必须以字母开头，并且只能包含字母、数字、连字符和下划线
  • 保留命令名（如 help、status、reset 等）不能被插件覆盖
  • 插件间重复注册命令会因诊断错误而失败

注册后台服务​

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

命名约定​

  • Gateway 方法：pluginId.action（例如：voicecall.status）
  • 工具：snake_case（例如：voice_call）
  • CLI 命令：kebab 或 camel，但避免与核心命令冲突

Skills​

插件可以在仓库中附带一个 skill（skills/<name>/SKILL.md）。 通过 plugins.entries.<id>.enabled（或其他配置门控）启用它，并确保它存在于你的工作区/托管 skills 位置中。

分发（npm）​

推荐打包方式：

  • 主包：openclaw（本仓库）
  • 插件：位于 @openclaw/* 下的独立 npm 包（例如：@openclaw/voice-call）

发布契约：

  • 插件 package.json 必须包含 openclaw.extensions，并指向一个或多个入口文件。
  • 可选：openclaw.setupEntry 可指向一个轻量级的仅 setup 入口，用于已禁用或尚未配置完成的渠道 setup。
  • 入口文件可以是 .js 或 .ts（jiti 会在运行时加载 TS）。
  • openclaw plugins install <npm-spec> 会使用 npm pack，提取到 ~/.openclaw/extensions/<id>/，并在配置中启用它。
  • 配置键稳定性：带 scope 的包会被规范化为 无 scope 的 id，用于 plugins.entries.*。

示例插件：Voice Call​

本仓库包含一个 voice-call 插件（Twilio 或日志回退）：

  • 源码：extensions/voice-call
  • Skill：skills/voice-call
  • CLI：openclaw voicecall start|status
  • 工具：voice_call
  • RPC：voicecall.start、voicecall.status
  • 配置（twilio）：provider: "twilio" + twilio.accountSid/authToken/from（可选 statusCallbackUrl、twimlUrl）
  • 配置（开发）：provider: "log"（无网络）

有关设置和用法，请参阅 Voice Call 和 extensions/voice-call/README.md。

安全说明​

插件与 Gateway 网关在同一进程内运行。请将它们视为受信任代码：

  • 只安装你信任的插件。
  • 优先使用 plugins.allow allowlist。
  • 请记住，plugins.allow 是基于 id 的，因此已启用的工作区插件可以有意覆盖具有相同 id 的捆绑插件。
  • 更改后请重启 Gateway 网关。

测试插件​

插件可以（也应该）附带测试：

  • 仓库内插件可以将 Vitest 测试放在 src/** 下（例如：src/plugins/voice-call.plugin.test.ts）。
  • 单独发布的插件应运行自己的 CI（lint/build/test），并验证 openclaw.extensions 指向构建后的入口点（dist/index.js）。