openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 05:18:44 +00:00
parent 532ba3a300
commit e1285ea6d8
5 changed files with 913 additions and 884 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
docs/zh-CN/ci.md
View File

@ -1,98 +1,100 @@
---
read_when:
- 你需要了解某个 CI 作业为什么会运行或不会运行
- 你正在调试失败的 GitHub Actions 检查
- 你需要了解为什么某个 CI 作业运行了或没有运行。
- 你正在调试失败的 GitHub Actions 检查。
summary: CI 作业图、作用域门禁，以及本地等效命令
title: CI 流水线
x-i18n:
generated_at: "2026-04-23T05:04:48Z"
generated_at: "2026-04-23T05:14:57Z"
model: gpt-5.4
provider: openai
source_hash: 345fd6200405e8b3f4ba9baadbbd491aa506f889c38631685aa5a8392e082109
source_hash: b3c2cf85b45405fdd5cc1d74c7cc07c4f16c3d9dcf8ca93286a0ba78ba4b6dd1
source_path: ci.md
workflow: 15
---
# CI 流水线
CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域划分，在仅有不相关区域发生变更时跳过高成本作业。
CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能作用域划分，在只有不相关区域发生变更时跳过高开销作业。
QA Lab 在主智能作用域工作流之外还有两条专用的 CI 通道。`Parity gate` 工作流会在匹配的 PR 变更、`main` 上的每夜运行以及手动触发时运行；它会构建私有 QA 运行时，并比较模拟的 GPT-5.4 和 Opus 4.6 智能体包。`QA-Lab - Live Telegram, Live Frontier` 工作流会在 `main` 上每夜运行以及手动触发时运行；它使用 `qa-live-shared` 环境，并为实时 Telegram 通道使用 Convex 租约。`OpenClaw Release Checks` 也会在发布批准前运行这两条 QA Lab 通道。
## 作业概览
| 作业 | 目的 | 运行时机 |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| `preflight` | 检测仅文档变更、变更作用域、已变更扩展，并构建 CI 清单 | 在所有非草稿推送和 PR 上始终运行 |
| `preflight` | 检测仅文档变更、变更作用域、变更的扩展，并构建 CI 清单 | 在所有非草稿推送和 PR 上始终运行 |
| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 在所有非草稿推送和 PR 上始终运行 |
| `security-dependency-audit` | 针对 npm 安全公告执行无依赖的生产 lockfile 审计 | 在所有非草稿推送和 PR 上始终运行 |
| `security-fast` | 快速安全作业的必需聚合项 | 在所有非草稿推送和 PR 上始终运行 |
| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用的下游产物 | 与 Node 相关的变更 |
| `checks-fast-core` | 快速 Linux 正确性分支，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 |
| `security-dependency-audit` | 针对 npm 安全通告执行无依赖的生产锁文件审计 | 在所有非草稿推送和 PR 上始终运行 |
| `security-fast` | 快速安全作业的必需聚合作业 | 在所有非草稿推送和 PR 上始终运行 |
| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查，以及可复用的下游构建产物 | 与 Node 相关的变更 |
| `checks-fast-core` | 快速 Linux 正确性通道，例如内置/plugin-contract/protocol 检查 | 与 Node 相关的变更 |
| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | 与 Node 相关的变更 |
| `checks-node-extensions` | 覆盖整个扩展套件的完整内置插件测试分片 | 与 Node 相关的变更 |
| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置、契约和扩展分支 | 与 Node 相关的变更 |
| `extension-fast` | 仅针对已变更内置插件的定向测试 | 带有扩展变更的拉取请求 |
| `check` | 分片后的主本地门禁等效项：生产类型、lint、守卫、测试类型和严格 smoke | 与 Node 相关的变更 |
| `check-additional` | 架构、边界、扩展表面守卫、包边界，以及 gateway-watch 分片 | 与 Node 相关的变更 |
| `build-smoke` | 已构建 CLI 的 smoke 测试和启动内存 smoke | 与 Node 相关的变更 |
| `checks` | 已构建产物的渠道测试验证器，以及仅在推送时运行的 Node 22 兼容性 | 与 Node 相关的变更 |
| `check-docs` | 文档格式、lint 和失效链接检查 | 文档发生变更 |
| `skills-python` | 针对 Python 支持的 Skills 运行 Ruff + pytest | 与 Python Skills 相关的变更 |
| `checks-windows` | Windows 特定测试分支 | 与 Windows 相关的变更 |
| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试分支 | 与 macOS 相关的变更 |
| `checks-node-core-test` | Core Node 测试分片，不包含渠道、内置、契约和扩展通道 | 与 Node 相关的变更 |
| `extension-fast` | 仅针对已变更的内置插件执行聚焦测试 | 具有扩展变更的拉取请求 |
| `check` | 分片的主本地门禁等效项：生产类型、lint、守卫、测试类型以及严格 smoke | 与 Node 相关的变更 |
| `check-additional` | 架构、边界、扩展表面守卫、包边界以及 gateway-watch 分片 | 与 Node 相关的变更 |
| `build-smoke` | 已构建 CLI 的 smoke 测试以及启动内存 smoke | 与 Node 相关的变更 |
| `checks` | 已构建构件渠道测试的验证器，以及仅推送时启用的 Node 22 兼容性 | 与 Node 相关的变更 |
| `check-docs` | 文档格式、lint 和坏链检查 | 文档发生变更 |
| `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 |
| `checks-windows` | Windows 专用测试通道 | 与 Windows 相关的变更 |
| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 |
| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 |
| `android` | 两种 flavor 的 Android 单元测试，以及一次 debug APK 构建 | 与 Android 相关的变更 |
| `android` | 两种 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 |
## 快速失败顺序
作业的排列顺序经过设计，使廉价检查能在高成本作业运行前先失败：
作业顺序经过安排，使低成本检查先失败，避免高成本作业继续运行：
1. `preflight` 决定究竟存在哪些分支。`docs-scope` 和 `changed-scope` 逻辑是这个作业中的步骤，而不是独立作业。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不会等待更重的产物和平台矩阵作业。
3. `build-artifacts` 与快速 Linux 分支并行进行，这样下游消费者可以在共享构建就绪后立即开始。
4. 更重的平台和运行时分支会在此之后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、仅限 PR 的 `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。
1. `preflight` 决定哪些通道会存在。`docs-scope` 和 `changed-scope` 逻辑是这个作业内部的步骤，不是独立作业。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，无需等待更重的构建产物和平台矩阵作业。
3. `build-artifacts` 与快速 Linux 通道并行执行，这样下游消费者可以在共享构建准备好后立即开始。
4. 随后更重的平台和运行时通道再展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、仅 PR 的 `extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。
作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。
CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但它们本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台分支仍仅限于平台源码变更。
Windows Node 检查仅针对 Windows 特定的进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该分支的 CI 工作流表面进行作用域划分；不相关的源码、插件、安装 smoke 和仅测试变更仍保留在 Linux Node 分支上，因此不会为了已经由常规测试分片覆盖的内容而占用一台 16 vCPU 的 Windows worker。
单独的 `install-smoke` 工作流会通过其自己的 `preflight` 作业复用同一个作用域脚本。它根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装 smoke 会针对安装、打包、与容器相关的变更、内置扩展生产变更，以及 Docker smoke 作业所覆盖的 core plugin/channel/gateway/插件 SDK 表面运行。仅测试和仅文档编辑不会占用 Docker workers。它的 QR 包 smoke 会强制 Docker `pnpm install` 层重新运行，同时保留 BuildKit pnpm store 缓存，因此仍能覆盖安装过程，而无需每次运行都重新下载依赖。它的 gateway-network e2e 会复用作业前面构建好的运行时镜像，因此在不增加额外 Docker 构建的情况下，增加了真实的容器到容器 WebSocket 覆盖。本地 `test:docker:all` 会预构建一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，并在 E2E 容器 smoke 运行器之间复用；可复用的 live/E2E 工作流也遵循这一模式，会在 Docker 矩阵之前构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行矩阵。QR 和安装器 Docker 测试则保留各自以安装为重点的 Dockerfile。另有一个独立的 `docker-e2e-fast` 作业，在 120 秒命令超时下运行受限的内置插件 Docker 配置：setup-entry 依赖修复加上 synthetic bundled-loader failure isolation。完整的内置更新/渠道矩阵仍保留为手动/完整套件，因为它会重复执行真实的 npm update 和 doctor repair 过程。
CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但它们本身不会强制触发 Windows、Android 或 macOS 原生构建；这些平台通道仍然只针对平台源码变更启用。
Windows Node 检查的作用域限定在 Windows 专用的进程/路径包装器、npm/pnpm/UI 运行器辅助工具、包管理器配置，以及执行该通道的 CI 工作流表面；不相关的源码、插件、安装 smoke 和仅测试变更仍然留在 Linux Node 通道中，因此不会为了已由常规测试分片覆盖的内容占用一个 16 vCPU 的 Windows worker。
单独的 `install-smoke` 工作流会通过它自己的 `preflight` 作业复用同一个作用域脚本。它会基于更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装 smoke 会在安装、打包、与容器相关的变更、内置扩展生产变更，以及 Docker smoke 作业所覆盖的 core plugin/channel/Gateway 网关/插件 SDK 表面发生变化时运行。仅测试和仅文档编辑不会占用 Docker worker。它的 QR 包 smoke 会强制 Docker `pnpm install` 层重新运行，同时保留 BuildKit 的 pnpm store 缓存，因此仍会覆盖安装流程，而不必在每次运行时重新下载依赖。它的 gateway-network e2e 会复用该作业前面构建的运行时镜像，因此增加了真实的容器到容器 WebSocket 覆盖，而无需再增加一次 Docker 构建。本地 `test:docker:all` 会预构建一个共享的 `scripts/e2e/Dockerfile` built-app 镜像，并在 E2E 容器 smoke 运行器之间复用；可复用的 live/E2E 工作流也采用同样的模式，在 Docker 矩阵之前先构建并推送一个带 SHA 标签的 GHCR Docker E2E 镜像，然后以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行矩阵。QR 和 installer Docker 测试保留各自以安装为重点的 Dockerfile。单独的 `docker-e2e-fast` 作业会在 120 秒命令超时限制下运行有界的内置插件 Docker 配置：setup-entry 依赖修复加上合成的 bundled-loader 故障隔离。完整的内置更新/渠道矩阵仍然是手动/完整套件，因为它会执行多次真实的 npm update 和 doctor 修复流程。
本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比较宽泛的 CI 平台作用域更严格：core 生产变更会运行 core 生产 typecheck 加 core 测试，core 仅测试变更只运行 core 测试 typecheck/测试，扩展生产变更会运行扩展生产 typecheck 加扩展测试，而扩展仅测试变更只运行扩展测试 typecheck/测试。公共插件 SDK 或 plugin-contract 变更会扩展为扩展验证，因为扩展依赖这些 core 契约。仅发布元数据的版本提升会运行定向的版本/配置/根依赖检查。未知的根目录/配置变更会以安全优先方式回退到所有分支。
本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地门禁在架构边界方面比宽泛的 CI 平台作用域更严格：core 生产变更会运行 core 生产 typecheck 加 core 测试，core 仅测试变更只运行 core 测试 typecheck/测试，扩展生产变更会运行扩展生产 typecheck 加扩展测试，而扩展仅测试变更只运行扩展测试 typecheck/测试。公开的插件 SDK 或 plugin-contract 变更会扩大到扩展验证，因为扩展依赖这些核心契约。仅发布元数据的版本号变更会运行有针对性的版本/配置/root 依赖检查。未知的 root/配置变更会以保守方式回退到所有通道。
在推送时，`checks` 矩阵会加入仅推送时运行的 `compat-node22` 分支。在拉取请求中，该分支会被跳过，矩阵会聚焦于常规测试/渠道分支。
在推送时，`checks` 矩阵会增加仅推送启用的 `compat-node22` 通道。在拉取请求上，这个通道会被跳过，矩阵仍专注于常规测试/渠道通道。
最慢的 Node 测试族已被拆分或平衡，以便每个作业都保持较小规模：渠道契约将 registry 和 core 覆盖拆分为总共六个加权分片，内置插件测试在六个扩展 workers 之间平衡分配，自动回复以三个平衡 workers 运行而不是六个很小的 workers，而 agentic gateway/plugin 配置则分布到现有仅源码的 agentic Node 作业中，而不是等待构建产物。广泛的 browser、QA、media 和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。广泛的 agents 分支使用共享的 Vitest 文件并行调度器，因为它主要受导入/调度影响，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片承担尾部耗时。`check-additional` 将包边界 compile/canary 工作放在一起，并将运行时拓扑架构与 gateway watch 覆盖分开；边界守卫分片会在一个作业内并发运行其小型独立守卫。Gateway watch、渠道测试以及 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成之后，于 `build-artifacts` 内并发运行，保留它们原有的检查名称作为轻量级验证作业，同时避免再占用两个额外的 Blacksmith workers 和第二个产物消费者队列。
Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或清单；它的单元测试分支仍会使用 SMS/通话日志 BuildConfig 标志来编译该 flavor，同时避免在每次与 Android 相关的推送中重复执行 debug APK 打包作业。
`extension-fast` 仅限 PR，因为 push 运行已经会执行完整的内置插件分片。这样既能为评审提供已变更插件的反馈，又不会在 `main` 上额外占用一个 Blacksmith worker 去覆盖已经存在于 `checks-node-extensions` 中的内容。
最慢的 Node 测试家族已经被拆分或平衡，因此每个作业都保持较小规模：渠道契约将 registry 和 core 覆盖拆成总计六个加权分片，内置插件测试在六个扩展 worker 之间平衡，自动回复以三个平衡 worker 运行而不是六个很小的 worker，而 agentic Gateway 网关/plugin 配置会分散到现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的 browser、QA、media 和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。宽泛的 agents 通道使用共享的 Vitest 文件级并行调度器，因为它主要受 import/调度影响，而不是由单个慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享 runtime 分片成为尾部瓶颈。`check-additional` 将 package-boundary compile/canary 工作保持在一起，并将 runtime topology 架构与 gateway watch 覆盖分开；边界守卫分片会在一个作业内部并发运行其体量较小且彼此独立的守卫。Gateway 网关 watch、渠道测试以及 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，在 `build-artifacts` 内部并发运行；这样既保留了它们原有的检查名称作为轻量级验证作业，又避免了额外两个 Blacksmith worker 和第二个构建产物消费者队列。
Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试通道仍会在启用 SMS/通话记录 BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的推送中重复执行 debug APK 打包作业。
`extension-fast` 仅在 PR 上运行，因为 push 已经会执行完整的内置插件分片。这样可以在评审时保留已变更插件的反馈，同时避免在 `main` 上为 `checks-node-extensions` 已经覆盖的内容额外占用一个 Blacksmith worker。
当同一 PR 或 `main` 引用上有更新的推送到达时，GitHub 可能会将已被取代的作业标记为 `cancelled`。除非同一引用上的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被更新运行取代后继续排队。
CI 并发键带有版本号（`CI-v7-*`），因此 GitHub 端旧队列组中的僵尸任务不会无限期阻塞较新的 main 运行。
当同一个 PR 或 `main` 引用上有较新的推送到达时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一引用上的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会正常报告分片失败，但不会在整个工作流已经被更新版本取代后继续排队。
CI 并发键带有版本号（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞新的 `main` 运行。
## 运行器
| 运行器 | 作业 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`、快速安全作业及其聚合项（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol/contract/bundled 检查、分片的渠道契约检查、除 lint 之外的 `check` 分片、`check-additional` 分片及其聚合项、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、自动响应；`install-smoke` 的 preflight 也使用 GitHub 托管的 Ubuntu，以便 Blacksmith 矩阵能更早排队 |
| `ubuntu-24.04` | `preflight`、快速安全作业及其聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol/contract/bundled 检查、分片的渠道契约检查、除 lint 之外的 `check` 分片、`check-additional` 分片及聚合、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；`install-smoke` 的 preflight 也使用 GitHub 托管的 Ubuntu，这样 Blacksmith 矩阵可以更早开始排队 |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它对 CPU 仍然足够敏感，以至于 8 vCPU 的成本高于收益；以及 `install-smoke` 的 Docker 构建，在那里 32 vCPU 的排队时间成本高于收益 |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它仍然对 CPU 足够敏感，以至于 8 vCPU 的成本高于节省；`install-smoke` Docker 构建，其中 32 vCPU 的排队时间成本高于节省 |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | 在 `openclaw/openclaw` 上运行的 `macos-node`；fork 会回退到 `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | 在 `openclaw/openclaw` 上运行的 `macos-swift`；fork 会回退到 `macos-latest` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 会回退到 `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 会回退到 `macos-latest` |
## 本地等效命令
```bash
pnpm changed:lanes # 检查针对 origin/main...HEAD 的本地 changed-lane 分类器
pnpm check:changed # 智能本地门禁：按边界分支运行变更范围内的 typecheck/lint/测试
pnpm check # 快速本地门禁：生产 `tsgo` + 分片 lint + 并行快速守卫
pnpm changed:lanes # 检查本地针对 origin/main...HEAD 的 changed-lane 分类器
pnpm check:changed # 智能本地门禁：按边界通道运行变更范围内的 typecheck/lint/测试
pnpm check # 快速本地门禁：生产 tsgo + 分片 lint + 并行快速守卫
pnpm check:test-types
pnpm check:timed # 相同门禁，但带有各阶段耗时
pnpm check:timed # 相同门禁，并附带各阶段耗时
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # Vitest 测试
pnpm test # vitest 测试
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs # 文档格式 + lint + 失效链接
pnpm build # 当 CI 产物/build-smoke 分支相关时，构建 `dist`
node scripts/ci-run-timings.mjs <run-id> # 汇总总耗时、排队耗时以及最慢的作业
pnpm check:docs # 文档格式 + lint + 坏链检查
pnpm build # 当 CI 构建产物/build-smoke 通道相关时，构建 dist
node scripts/ci-run-timings.mjs <run-id> # 汇总总耗时、排队时间以及最慢的作业
```

926
docs/zh-CN/help/testing.md
View File

File diff suppressed because it is too large Load Diff

329
docs/zh-CN/plugins/manifest.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你正在构建一个 OpenClaw 插件
- 你需要提供插件配置 schema，或调试插件校验错误
- 你需要交付一个插件配置 schema，或调试插件校验错误
summary: 插件清单 + JSON schema 要求（严格配置校验）
title: 插件清单
x-i18n:
generated_at: "2026-04-22T07:00:33Z"
generated_at: "2026-04-23T05:14:53Z"
model: gpt-5.4
provider: openai
source_hash: 085c1baccb96b8e6bd4033ad11bdd5f79bdb0daec470e977fce723c3ae38cc99
source_hash: 4da8ce35aca4c12bf49a4c3e352fb7fc2b5768cb34157a00dabd247fe60b4f04
source_path: plugins/manifest.md
workflow: 15
---
@ -17,40 +17,40 @@ x-i18n:
本页仅适用于**原生 OpenClaw 插件清单**。
如需了解兼容的 bundle 布局，请参阅 [插件 bundles](/zh-CN/plugins/bundles)。
关于兼容的 bundle 布局，请参见 [插件 bundle](/zh-CN/plugins/bundles)。
兼容的 bundle 格式使用不同的清单文件：
- Codex bundle：`.codex-plugin/plugin.json`
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局
- Claude bundle：`.claude-plugin/plugin.json` 或不带清单的默认 Claude 组件布局
- Cursor bundle：`.cursor-plugin/plugin.json`
OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处介绍的 `openclaw.plugin.json` schema 进行校验。
OpenClaw 也会自动检测这些 bundle 布局，但不会根据这里描述的 `openclaw.plugin.json` schema 对它们进行校验。
对于兼容 bundle，如果其布局符合 OpenClaw 运行时预期，OpenClaw 当前会读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook packs。
对于兼容 bundle，当其布局符合 OpenClaw 运行时预期时，OpenClaw 当前会读取 bundle 元数据、已声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook pack。
每个原生 OpenClaw 插件**必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码**的情况下校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
每个原生 OpenClaw 插件都**必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码**的情况下校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
完整的插件系统指南请参阅：[插件](/zh-CN/tools/plugin)。
如需了解原生能力模型及当前外部兼容性指南，请参阅：
参见完整的插件系统指南：[插件](/zh-CN/tools/plugin)。
关于原生能力模型和当前外部兼容性指引，请参见：
[能力模型](/zh-CN/plugins/architecture#public-capability-model)。
## 此文件的作用
`openclaw.plugin.json` 是 OpenClaw 在加载你的插件代码之前读取的元数据。
将它用于：
用途包括：
- 插件标识
- 配置校验
- 无需启动插件运行时即可获取的认证与新手引导元数据
- 控制平面界面可在运行时加载前检查的轻量激活提示
- 设置 / 新手引导界面可在运行时加载前检查的轻量设置描述符
- 应在插件运行时加载前解析的别名与自动启用元数据
- 应在插件运行时加载前自动激活插件的简写模型家族归属元数据
- 用于内置兼容接线与契约覆盖的静态能力归属快照
- 共享 `openclaw qa` 主机可在插件运行时加载前检查的轻量 QA 运行器元数据
- 应合并到目录与校验界面、且无需加载运行时的渠道专属配置元数据
- 无需启动插件运行时即可获取的认证和新手引导元数据
- 可供控制平面界面在运行时加载前检查的低成本激活提示
- 可供设置 / 新手引导界面在运行时加载前检查的低成本设置描述符
- 应在插件运行时加载前解析的别名和自动启用元数据
- 应在运行时加载前自动激活插件的简写模型族归属元数据
- 用于内置兼容性接线和契约覆盖的静态能力归属快照
- 共享 `openclaw qa` 主机可在插件运行时加载前检查的低成本 QA 运行器元数据
- 应在不加载运行时的情况下合并到目录和校验界面中的渠道特定配置元数据
- 配置 UI 提示
不要将它用于：
@ -59,7 +59,7 @@ OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处介
- 声明代码入口点
- npm 安装元数据
这些应放在你的插件代码和 `package.json` 中。
这些内容应放在你的插件代码和 `package.json` 中。
## 最小示例
@ -142,29 +142,29 @@ OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处介
| 字段 | 必填 | 类型 | 含义 |
| ------------------------------------ | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | 是 | `string` | 规范插件 id。这是 `plugins.entries.<id>` 中使用的 id。 |
| `configSchema` | 是 | `object` | 该插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略该字段，或将其设为任何非 `true` 的值，可使插件默认保持禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会规范化到该规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明用于 `plugins.slots.*` 的互斥插件类型。 |
| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于设备发现和配置校验。 |
| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 |
| `modelSupport` | 否 | `object` | 由清单持有的简写模型家族元数据，用于在运行时之前自动加载插件。 |
| `providerEndpoints` | 否 | `object[]` | 由清单持有的端点主机 / `baseUrl` 元数据，用于 core 在提供商运行时加载前对提供商路由进行分类。 |
| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 |
| `syntheticAuthRefs` | 否 | `string[]` | 提供商或 CLI 后端引用；在运行时加载前的冷启动模型发现期间，应探测其由插件持有的 synthetic auth hook。 |
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件持有的占位 API key 值，表示非机密的本地、OAuth 或环境凭证状态。 |
| `commandAliases` | 否 | `object[]` | 此插件拥有的命令名称；在运行时加载前，它们应生成带有插件感知的配置和 CLI 诊断信息。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 无需加载插件代码即可检查的轻量提供商认证环境变量元数据。 |
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个提供商 id 进行认证查找的提供商 id，例如与基础提供商 API key 和认证配置文件共享的 coding 提供商。 |
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 无需加载插件代码即可检查的轻量渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或认证界面，以便通用启动 / 配置辅助工具能够识别。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量认证选择元数据。 |
| `activation` | 否 | `object` | 面向提供商、命令、渠道、路由和能力触发加载的轻量激活提示。仅为元数据；实际行为仍由插件运行时负责。 |
| `setup` | 否 | `object` | 设备发现和设置界面可在不加载插件运行时的情况下检查的轻量设置 / 新手引导描述符。 |
| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量 QA 运行器描述符。 |
| `contracts` | 否 | `object` | 用于语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 |
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量媒体理解默认值。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单持有的渠道配置元数据，在运行时加载前合并到设备发现和校验界面中。 |
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或设置为任何非 `true` 的值，以使该插件默认禁用。 |
| `legacyPluginIds` | 否 | `string[]` | 会被规范化为此规范插件 id 的旧版 id。 |
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些 provider id 时，应自动启用此插件。 |
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的排他性插件类型。 |
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于发现和配置校验。 |
| `providers` | 否 | `string[]` | 由此插件拥有的 provider id。 |
| `modelSupport` | 否 | `object` | 由清单拥有的简写模型族元数据，用于在运行时之前自动加载插件。 |
| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint host/baseUrl 元数据，用于核心层在 provider 运行时加载前对 provider 路由进行分类。 |
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 |
| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前的冷启动模型发现期间，应探测其插件自有 synthetic auth hook 的 provider 或 CLI backend 引用。 |
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，用于表示非秘密的本地、OAuth 或环境凭证状态。 |
| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，这些命令应在运行时加载前生成具备插件感知能力的配置和 CLI 诊断信息。 |
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的低成本 provider 认证环境变量元数据。 |
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个 provider id 进行认证查找的 provider id，例如与基础 provider API key 和认证配置文件共享的 coding provider。 |
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的低成本渠道环境变量元数据。将其用于通用启动 / 配置辅助程序需要识别的、由环境变量驱动的渠道设置或认证界面。 |
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选 provider 解析和简单 CLI 标志接线的低成本认证选项元数据。 |
| `activation` | 否 | `object` | 用于 provider、命令、渠道、路由和由能力触发的加载的低成本激活提示。仅为元数据；插件运行时仍拥有实际行为。 |
| `setup` | 否 | `object` | 发现和设置界面可在不加载插件运行时的情况下检查的低成本设置 / 新手引导描述符。 |
| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的低成本 QA 运行器描述符。 |
| `contracts` | 否 | `object` | 适用于 speech、realtime transcription、realtime voice、media-understanding、image-generation、music-generation、video-generation、web-fetch、web search 和工具归属的静态内置能力快照。 |
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的 provider id 提供的低成本 media-understanding 默认元数据。 |
| `channelConfigs` | 否 | `Record<string, object>` | 由清单拥有的渠道配置元数据，会在运行时加载前合并到发现和校验界面中。 |
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
| `name` | 否 | `string` | 人类可读的插件名称。 |
| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 |
@ -174,30 +174,30 @@ OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处介
## `providerAuthChoices` 参考
每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。
OpenClaw 会在提供商运行时加载之前读取这些内容。
OpenClaw 会在 provider 运行时加载前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `provider` | 是 | `string` | 此选项所属的提供商 id。 |
| `method` | 是 | `string` | 要分发到的认证方式 id。 |
| `choiceId` | 是 | `string` | 由新手引导和 CLI 流程使用的稳定认证选项 id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如省略，OpenClaw 会回退到 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器中显示的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动通过 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 旧版选项 id；应将用户重定向到当前替代选项。 |
| `groupId` | 否 | `string` | 用于对相关选项分组的可选分组 id。 |
| `provider` | 是 | `string` | 此选项所属的 provider id。 |
| `method` | 是 | `string` | 要分发到的认证方法 id。 |
| `choiceId` | 是 | `string` | 供新手引导和 CLI 流程使用的稳定 auth-choice id。 |
| `choiceLabel` | 否 | `string` | 面向用户的标签。如省略，OpenClaw 会回退为 `choiceId`。 |
| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 |
| `assistantPriority` | 否 | `number` | 在由智能体驱动的交互式选择器中，值越小排序越靠前。 |
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在智能体选择器中隐藏该选项，同时仍允许手动 CLI 选择。 |
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 |
| `groupId` | 否 | `string` | 用于对相关选项分组的可选组 id。 |
| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 |
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 |
| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 |
| `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
| `cliDescription` | 否 | `string` | 用于 CLI 帮助信息中的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 该选项应出现在哪些新手引导界面中。如省略，默认值为 `["text-inference"]`。 |
| `cliDescription` | 否 | `string` | 用于 CLI 帮助的说明。 |
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应显示在哪些新手引导界面中。如省略，默认值为 `["text-inference"]`。 |
## `commandAliases` 参考
当插件拥有某个运行时命令名称，而用户可能错误地将它放入 `plugins.allow` 中，或尝试将其作为根级 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用这些元数据生成诊断信息，而无需导入插件运行时代码。
当插件拥有某个运行时命令名称，而用户可能误将其放入 `plugins.allow`，或尝试将其作为根级 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据提供诊断信息，而无需导入插件运行时代码。
```json
{
@ -215,15 +215,15 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
| `name` | 是 | `string` | 属于此插件的命令名称。 |
| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根级 CLI 命令。 |
| `cliCommand` | 否 | `string` | 若存在，用于 CLI 操作时建议的相关根级 CLI 命令。 |
| `cliCommand` | 否 | `string` | 若存在相关的根级 CLI 命令，则建议用于 CLI 操作。 |
## `activation` 参考
当插件可以低成本声明哪些控制平面事件应在之后激活它时，请使用 `activation`。
当插件可以以低成本声明哪些控制平面事件应在之后激活它时，请使用 `activation`。
## `qaRunners` 参考
当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。请保持这些元数据轻量且静态；实际的 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 接口负责。
当插件向共享的 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。请将此元数据保持为低成本且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 接口拥有实际的 CLI 注册逻辑。
```json
{
@ -238,10 +238,11 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 |
| `description` | 否 | `string` | 当共享主机需要一个 stub 命令时使用的回退帮助文本。 |
| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 之下的子命令，例如 `matrix`。 |
| `description` | 否 | `string` | 当共享主机需要一个存根命令时使用的回退帮助文本。 |
此区块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。当前使用方会在更广泛的插件加载前将其用作缩小范围的提示，因此缺少激活元数据通常只会带来性能成本；在旧版清单归属回退机制仍存在时，它不应改变正确性。
此区块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。
当前使用方将其作为在更广泛插件加载之前进行范围收窄的提示，因此缺少激活元数据通常只会带来性能损失；在旧版清单归属回退机制仍存在的情况下，它不应改变正确性。
```json
{
@ -257,21 +258,21 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 必填 | 类型 | 含义 |
| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| `onProviders` | 否 | `string[]` | 请求这些提供商 id 时，应激活此插件。 |
| `onProviders` | 否 | `string[]` | 请求这些 provider id 时应激活此插件。 |
| `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 |
| `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 |
| `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 |
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划所用的宽泛能力提示。 |
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 供控制平面激活规划使用的广义能力提示。 |
当前在线使用方：
- 由命令触发的 CLI 规划会回退到旧版 `commandAliases[].cliCommand` 或 `commandAliases[].name`
- 当缺少显式渠道激活元数据时，渠道触发的设置 / 渠道规划会回退到旧版 `channels[]` 归属
- 当缺少显式提供商激活元数据时，提供商触发的设置 / 运行时规划会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属
- 当缺少显式 provider 激活元数据时，由 provider 触发的设置 / 运行时规划会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属
## `setup` 参考
当设置和新手引导界面需要在运行时加载前获取由插件持有的轻量元数据时，请使用 `setup`。
当设置和新手引导界面需要在运行时加载前获取低成本的插件自有元数据时，请使用 `setup`。
```json
{
@ -290,32 +291,32 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
}
```
顶层 `cliBackends` 依然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是设置专用的描述符界面，供应保持为纯元数据的控制平面 / 设置流程使用。
顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面 / 设置流程的设置专用描述符界面，应保持仅为元数据。
当存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现的首选“描述符优先”查找界面。如果描述符只能缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。
存在 `setup.providers` 和 `setup.cliBackends` 时，它们是设置发现的首选“描述符优先”查找界面。如果描述符仅用于缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook，请设置 `requiresRuntime: true`，并保留 `setup-api` 作为回退执行路径。
由于设置查找可能执行插件持有的 `setup-api` 代码，因此规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。若归属存在歧义，系统会以保守方式失败，而不是按发现顺序挑选一个赢家。
由于设置查找可能执行插件自有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。若归属存在歧义，系统会以关闭方式失败，而不是按发现顺序选出一个胜者。
### `setup.providers` 参考
| 字段 | 必填 | 类型 | 含义 |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
| `id` | 是 | `string` | 在设置或新手引导期间公开的提供商 id。请保持规范化 id 在全局范围内唯一。 |
| `authMethods` | 否 | `string[]` | 此提供商在无需加载完整运行时的情况下支持的设置 / 认证方式 id。 |
| `id` | 是 | `string` | 在设置或新手引导期间暴露的 provider id。请保持规范化 id 在全局唯一。 |
| `authMethods` | 否 | `string[]` | 此 provider 在不加载完整运行时的情况下支持的设置 / 认证方法 id。 |
| `envVars` | 否 | `string[]` | 通用设置 / 状态界面可在插件运行时加载前检查的环境变量。 |
### `setup` 字段
| 字段 | 必填 | 类型 | 含义 |
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `providers` | 否 | `object[]` | 在设置和新手引导期间公开的提供商设置描述符。 |
| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。请保持规范化 id 在全局范围内唯一。 |
| `configMigrations` | 否 | `string[]` | 由该插件设置界面持有的配置迁移 id。 |
| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 |
| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的 provider 设置描述符。 |
| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。请保持规范化 id 在全局唯一。 |
| `configMigrations` | 否 | `string[]` | 由此插件设置界面拥有的配置迁移 id。 |
| `requiresRuntime` | 否 | `boolean` | 描述符查找之后，设置是否仍需要执行 `setup-api`。 |
## `uiHints` 参考
`uiHints` 是一个从配置字段名映射到小型渲染提示的映射表。
`uiHints` 是一个从配置字段名称映射到小型渲染提示的映射表。
```json
{
@ -337,13 +338,13 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| `label` | `string` | 面向用户的字段标签。 |
| `help` | `string` | 简短辅助文本。 |
| `tags` | `string[]` | 可选的 UI 标签。 |
| `advanced` | `boolean` | 将该字段标记为高级选项。 |
| `sensitive` | `boolean` | 将该字段标记为机密或敏感。 |
| `advanced` | `boolean` | 将该字段标记为高级项。 |
| `sensitive` | `boolean` | 将该字段标记为秘密或敏感信息。 |
| `placeholder` | `string` | 表单输入的占位文本。 |
## `contracts` 参考
仅在 OpenClaw 无需导入插件运行时即可读取的静态能力归属元数据场景中使用 `contracts`。
仅在 OpenClaw 可以不导入插件运行时就读取的静态能力归属元数据场景下使用 `contracts`。
```json
{
@ -367,19 +368,19 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 类型 | 含义 |
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
| `embeddedExtensionFactories` | `string[]` | 内置插件可为其注册工厂的嵌入式运行时 id。 |
| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的 Web 抓取提供商 id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索提供商 id。 |
| `tools` | `string[]` | 在内置契约检查中，此插件拥有的智能体工具名称。 |
| `speechProviders` | `string[]` | 此插件拥有的 speech provider id。 |
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的 realtime-transcription provider id。 |
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的 realtime-voice provider id。 |
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的 media-understanding provider id。 |
| `imageGenerationProviders` | `string[]` | 此插件拥有的 image-generation provider id。 |
| `videoGenerationProviders` | `string[]` | 此插件拥有的 video-generation provider id。 |
| `webFetchProviders` | `string[]` | 此插件拥有的 web-fetch provider id。 |
| `webSearchProviders` | `string[]` | 此插件拥有的 web-search provider id。 |
| `tools` | `string[]` | 此插件拥有的智能体工具名称，用于内置契约检查。 |
## `mediaUnderstandingProviderMetadata` 参考
当媒体理解提供商具有默认模型、自动认证回退优先级，或 generic core 辅助工具在运行时加载前所需的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键名也必须在 `contracts.mediaUnderstandingProviders` 中声明。
当某个 media-understanding provider 具有默认模型、自动认证回退优先级，或通用核心辅助程序在运行时加载前需要的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键名也必须在 `contracts.mediaUnderstandingProviders` 中声明。
```json
{
@ -402,18 +403,18 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
}
```
每个提供商条目可以包含：
每个 provider 条目可以包含：
| 字段 | 类型 | 含义 |
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商公开的媒体能力。 |
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认映射。 |
| `autoPriority` | `Record<string, number>` | 用于基于凭证的自动提供商回退时，数值越小排序越靠前。 |
| `nativeDocumentInputs` | `"pdf"[]` | 该提供商支持的原生文档输入。 |
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此 provider 提供的媒体能力。 |
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认值。 |
| `autoPriority` | `Record<string, number>` | 用于基于凭证的自动 provider 回退时，数字越小排序越靠前。 |
| `nativeDocumentInputs` | `"pdf"[]` | 该 provider 支持的原生文档输入。 |
## `channelConfigs` 参考
当渠道插件在运行时加载前需要轻量配置元数据时，请使用 `channelConfigs`。
当渠道插件在运行时加载前需要低成本配置元数据时，请使用 `channelConfigs`。
```json
{
@ -444,7 +445,7 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
| 字段 | 类型 | 含义 |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。对每个已声明的渠道配置条目来说都是必填。 |
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 |
| `uiHints` | `Record<string, object>` | 该渠道配置区块可选的 UI 标签 / 占位符 / 敏感性提示。 |
| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 |
| `description` | `string` | 用于检查和目录界面的简短渠道描述。 |
@ -452,7 +453,7 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
## `modelSupport` 参考
当 OpenClaw 应在插件运行时加载前，根据诸如 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的简写模型 id 推断你的提供商插件时，请使用 `modelSupport`。
当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 这类简写模型 id 推断你的 provider 插件时，请使用 `modelSupport`。
```json
{
@ -463,66 +464,72 @@ OpenClaw 会在提供商运行时加载之前读取这些内容。
}
```
OpenClaw 采用以下优先级：
OpenClaw 会按以下优先级处理：
- 显式 `provider/model` 引用使用所属 `providers` 清单元数据
- 显式的 `provider/model` 引用使用所属 `providers` 清单元数据
- `modelPatterns` 优先于 `modelPrefixes`
- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出
- 剩余歧义会被忽略，直到用户或配置显式指定提供商
- 若仍存在歧义，在用户或配置明确指定 provider 之前将忽略该歧义
字段：
| 字段 | 类型 | 含义 |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | 使用 `startsWith` 对简写模型 id 进行匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除配置文件后缀后，对简写模型 id 进行匹配的正则表达式源码。 |
| `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 匹配的前缀。 |
| `modelPatterns` | `string[]` | 在移除 profile 后缀后，对简写模型 id 进行匹配的正则表达式源码。 |
旧版顶层能力字段已弃用。请使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；正常清单加载已不再将这些顶层字段视为能力归属。
旧版顶层能力键已弃用。请使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属。
## 清单与 `package.json` 的区别
这两个文件承担不同职责：
这两个文件承担的职责不同：
| 文件 | 用途 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | 设备发现、配置校验、认证选项元数据，以及在插件代码运行前必须存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 |
| `openclaw.plugin.json` | 发现、配置校验、认证选项元数据，以及在插件代码运行前必须存在的 UI 提示 |
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 区块 |
如果你不确定某条元数据应放在哪里，请使用以下规则：
如果你不确定某条元数据应放在哪里，请遵循这条规则：
- 如果 OpenClaw 必须在加载插件代码前知道它，就放入 `openclaw.plugin.json`
- 如果它与打包、入口文件或 npm 安装行为有关，就放入 `package.json`
- 如果 OpenClaw 必须在加载插件代码前知道它，请将其放入 `openclaw.plugin.json`
- 如果它与打包、入口文件或 npm 安装行为有关，请将其放入 `package.json`
### 会影响设备发现的 `package.json` 字段
### 会影响发现流程的 `package.json` 字段
某些运行时前插件元数据被有意放在 `package.json` 的 `openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。
有些运行时前插件元数据有意放在 `package.json` 的 `openclaw` 区块下，而不是 `openclaw.plugin.json` 中。
重要示例：
| 字段 | 含义 |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保持在插件包目录内。 |
| `openclaw.setupEntry` | 在新手引导、延迟渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量仅设置入口点。必须保持在插件包目录内。 |
| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保持在插件包目录内。 |
| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅基于环境变量的设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何内容处于已登录状态？”。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置插件和外部发布插件的安装 / 更新提示。 |
| `openclaw.extensions` | 声明原生插件入口点。必须保留在插件包目录内。 |
| `openclaw.runtimeExtensions` | 为已安装包声明已构建的 JavaScript 运行时入口点。必须保留在插件包目录内。 |
| `openclaw.setupEntry` | 在新手引导、延迟渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量级仅设置入口点。必须保留在插件包目录内。 |
| `openclaw.runtimeSetupEntry` | 为已安装包声明已构建的 JavaScript 设置入口点。必须保留在插件包目录内。 |
| `openclaw.channel` | 低成本渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
| `openclaw.channel.configuredState` | 轻量级 configured-state 检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量方式的设置？”。 |
| `openclaw.channel.persistedAuthState` | 轻量级 persisted-auth 检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已经有任何登录状态？”。 |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置和外部发布插件的安装 / 更新提示。 |
| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许使用一条受限的内置插件重新安装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间先加载仅设置的渠道界面，再加载完整渠道插件。 |
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用如 `>=2026.3.22` 这样的 semver 下限。 |
| `openclaw.install.expectedIntegrity` | 预期的 npm 发行包完整性字符串，例如 `sha512-...`；安装和更新流程会根据它验证获取到的构件。 |
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个受限的内置插件重新安装恢复路径。 |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅设置用的渠道界面在启动期间先于完整渠道插件加载。 |
`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；在较旧主机上，较新但有效的值会导致跳过该插件。
清单元数据决定了在运行时加载前，新手引导中会出现哪些 provider / channel / setup 选项。`package.json#openclaw.install` 则告诉新手引导：当用户选择其中某个选项时，应如何获取或启用该插件。不要将安装提示移到 `openclaw.plugin.json` 中。
渠道插件应提供 `openclaw.setupEntry`，以便在状态、渠道列表或 SecretRef 扫描需要识别已配置账户时，无需加载完整运行时。设置入口点应公开渠道元数据，以及适用于设置阶段的安全配置、状态和密钥适配器；网络客户端、Gateway 网关监听器和传输运行时应保留在主扩展入口点中。
`openclaw.install.minHostVersion` 会在安装期间和清单注册表加载期间强制执行。无效值会被拒绝；对于较旧主机，较新但有效的值会跳过该插件。
运行时入口点字段不会绕过源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。
精确的 npm 版本锁定已通过 `npmSpec` 提供，例如
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。当你希望在获取到的 npm 构件不再匹配已锁定发布版本时，让更新流程以关闭方式失败，可将它与 `expectedIntegrity` 搭配使用。交互式新手引导仅会在 `npmSpec` 是精确版本且存在 `expectedIntegrity` 时，从受信任的目录元数据中提供 npm 安装选项；否则会回退到本地来源或跳过。
`openclaw.install.allowInvalidConfigRecovery` 的设计刻意保持为窄范围。它不会让任意损坏的配置都变得可安装。当前它仅允许安装流程从某些特定的陈旧内置插件升级故障中恢复，例如缺失的内置插件路径，或同一个内置插件对应的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作人员引导到 `openclaw doctor --fix`。
当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，渠道插件应提供 `openclaw.setupEntry`。设置入口点应暴露渠道元数据以及适用于设置阶段的配置、状态和 secrets 适配器；请将网络客户端、Gateway 网关监听器和传输运行时保留在主扩展入口点中。
`openclaw.channel.persistedAuthState` 是针对一个微型检查模块的包元数据：
运行时入口点字段不会覆盖针对源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能使一个越界的 `openclaw.extensions` 路径变为可加载。
`openclaw.install.allowInvalidConfigRecovery` 的适用范围是有意保持狭窄的。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并将操作人员引导至 `openclaw doctor --fix`。
`openclaw.channel.persistedAuthState` 是用于微型检查模块的包元数据：
```json
{
@ -538,9 +545,9 @@ OpenClaw 采用以下优先级：
}
```
当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行一个低成本的“是 / 否”认证探测时，请使用它。目标导出应是一个仅读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。
当设置、Doctor 或 configured-state 流程需要在完整渠道插件加载前进行低成本的是 / 否认证探测时，请使用它。目标导出应是一个仅读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。
`openclaw.channel.configuredState` 也采用相同结构，用于低成本的仅环境变量已配置检查：
`openclaw.channel.configuredState` 采用相同的结构，用于低成本的仅环境变量 configured 检查：
```json
{
@ -556,62 +563,64 @@ OpenClaw 采用以下优先级：
}
```
当一个渠道可以仅通过环境变量或其他微型非运行时输入来回答已配置状态时，请使用它。如果检查需要完整配置解析或真实的渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
当渠道可以通过环境变量或其他微小的非运行时输入来回答 configured-state 时，请使用它。如果检查需要完整的配置解析或真实渠道运行时，请改为将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
## 设备发现优先级（重复插件 id）
## 发现优先级（重复插件 id）
OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两次发现共享同一个 `id`，则只保留**优先级最高**的清单；较低优先级的重复项会被丢弃，而不是与其并行加载。
OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、配置中显式选定的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；优先级较低的重复项会被丢弃，而不是与其并行加载。
优先级从高到低如下：
1. **配置选定** —— 在 `plugins.entries.<id>` 中显式固定的路径
2. **内置** —— 随 OpenClaw 一同发布的插件
2. **内置** —— 随 OpenClaw 一起发布的插件
3. **全局安装** —— 安装到全局 OpenClaw 插件根目录中的插件
4. **工作区** —— 相对于当前工作区发现的插件
影响：
影响如下：
- 工作区中某个内置插件的 fork 或陈旧副本不会遮蔽内置构建。
- 如果你确实要用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它，使其凭借优先级获胜，而不是依赖工作区发现。
- 重复项被丢弃会记录日志，以便 Doctor 和启动诊断可以指出被舍弃的副本。
- 工作区中某个内置插件的 fork 或陈旧副本不会遮蔽内置版本。
- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它，使其依靠优先级获胜，而不是依赖工作区发现。
- 被丢弃的重复项会记录日志，以便 Doctor 和启动诊断能指出被舍弃的副本。
## JSON Schema 要求
- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。
- 空 schema 也是允许的（例如 `{ "type": "object", "additionalProperties": false }`）。
- 接受空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。
- Schema 会在配置读写时校验，而不是在运行时校验。
## 校验行为
- 未知的 `channels.*` 键是**错误**，除非该渠道 id 已由某个插件清单声明。
- 未知的 `channels.*` 键是**错误**，除非该 channel id 已由某个插件清单声明。
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 属于**错误**。
- 如果某个插件已安装，但其清单或 schema 缺失或损坏，校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件处于**禁用**状态，则配置会被保留，并且 Doctor 与日志中会显示一条**警告**。
- 如果插件已安装，但清单或 schema 缺失或损坏，校验会失败，Doctor 会报告该插件错误。
- 如果插件配置存在，但插件**已禁用**，配置会被保留，并且 Doctor + 日志中会显示**警告**。
完整的 `plugins.*` schema 请参阅[配置参考](/zh-CN/gateway/configuration)。
有关完整的 `plugins.*` schema，请参见[配置参考](/zh-CN/gateway/configuration)。
## 注意事项
## 说明
- 清单对于**原生 OpenClaw 插件**是**必需的**，包括本地文件系统加载。
- 运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。
- 原生清单使用 JSON5 解析，因此只要最终值仍是一个对象，就接受注释、尾随逗号和未加引号的键。
- 清单加载器只读取已文档化的清单字段。避免在此添加自定义顶层键。
- `providerAuthEnvVars` 是用于认证探测、环境变量标记校验，以及类似提供商认证界面的轻量元数据路径；这些场景不应仅为了检查环境变量名称而启动插件运行时。
- `providerAuthAliases` 允许提供商变体复用另一个提供商的认证环境变量、认证配置文件、基于配置的认证以及 API key 新手引导选项，而无需在 core 中硬编码这种关系。
- `providerEndpoints` 允许提供商插件持有简单的端点主机 / `baseUrl` 匹配元数据。仅将其用于 core 已支持的端点类别；实际运行时行为仍由插件负责。
- `syntheticAuthRefs` 是用于提供商持有的 synthetic auth hook 的轻量元数据路径；这些 hook 必须在运行时注册表存在之前，对冷启动模型发现可见。只列出那些其运行时提供商或 CLI 后端实际实现了 `resolveSyntheticAuth` 的引用。
- `nonSecretAuthMarkers` 是用于内置插件持有的占位 API key 的轻量元数据路径，例如本地、OAuth 或环境凭证标记。Core 会将这些值视为非机密，用于认证显示和密钥审计，而无需硬编码其所属提供商。
- `channelEnvVars` 是用于 shell 环境变量回退、设置提示以及类似渠道界面的轻量元数据路径；这些场景不应仅为了检查环境变量名称而启动插件运行时。环境变量名称只是元数据，本身不构成激活：状态、审计、定时任务投递校验以及其他只读界面，在将某个环境变量视为已配置渠道前，仍会应用插件信任与有效激活策略。
- `providerAuthChoices` 是用于认证选项选择器、`--auth-choice` 解析、首选提供商映射，以及在提供商运行时加载前注册简单新手引导 CLI 标志的轻量元数据路径。对于需要提供商代码的运行时向导元数据，请参阅[提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
- 互斥插件类型通过 `plugins.slots.*` 选择。
- `kind: "memory"` 通过 `plugins.slots.memory` 选择。
- `kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择（默认值：内置 `legacy`）。
- 对于原生 OpenClaw 插件，清单是**必需的**，包括本地文件系统加载。
- 运行时仍会单独加载插件模块；清单仅用于发现 + 校验。
- 原生清单使用 JSON5 解析，因此支持注释、尾随逗号和未加引号的键，只要最终值仍然是对象即可。
- 清单加载器只会读取文档中说明的清单字段。避免在此添加自定义顶层键。
- `providerAuthEnvVars` 是用于认证探测、环境变量标记校验以及类似 provider 认证界面的低成本元数据路径，这些场景不应仅为检查环境变量名称而启动插件运行时。
- `providerAuthAliases` 允许 provider 变体复用另一个 provider 的认证环境变量、认证配置文件、基于配置的认证，以及 API key 新手引导选项，而无需在核心中硬编码这种关系。
- `providerEndpoints` 允许 provider 插件拥有简单的 endpoint host/baseUrl 匹配元数据。仅在核心已支持的 endpoint class 上使用它；插件仍拥有运行时行为。
- `syntheticAuthRefs` 是一种低成本元数据路径，用于 provider 自有的 synthetic auth hook，这些 hook 必须在运行时注册表存在之前，对冷启动模型发现可见。只列出那些其运行时 provider 或 CLI backend 实际实现了 `resolveSyntheticAuth` 的引用。
- `nonSecretAuthMarkers` 是一种低成本元数据路径，用于内置插件自有的占位 API key，例如本地、OAuth 或环境凭证标记。核心会将这些值视为非秘密信息，以用于认证显示和 secret 审计，而无需硬编码所属 provider。
- `channelEnvVars` 是 shell 环境变量回退、设置提示以及类似渠道界面的低成本元数据路径，这些场景不应仅为检查环境变量名称而启动插件运行时。环境变量名称只是元数据，本身并不构成激活：状态、审计、cron 投递校验以及其他只读界面，在将环境变量视为已配置渠道之前，仍会应用插件信任和有效激活策略。
- `providerAuthChoices` 是认证选项选择器、`--auth-choice` 解析、首选 provider 映射，以及在 provider 运行时加载前进行简单新手引导 CLI 标志注册的低成本元数据路径。对于需要 provider 代码的运行时向导元数据，请参见
[Provider 运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
- 排他性插件类型通过 `plugins.slots.*` 选择。
- `kind: "memory"` 由 `plugins.slots.memory` 选择。
- `kind: "context-engine"` 由 `plugins.slots.contextEngine`
选择（默认：内置 `legacy`）。
- 当插件不需要 `channels`、`providers`、`cliBackends` 和 `skills` 时，可以省略这些字段。
- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts`
- `pnpm rebuild <package>`）。
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins) — 插件快速开始
- [插件架构](/zh-CN/plugins/architecture) — 内部架构
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考
- [构建插件](/zh-CN/plugins/building-plugins) —— 插件入门指南
- [插件架构](/zh-CN/plugins/architecture) —— 内部架构
- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 插件 SDK 参考

263
docs/zh-CN/plugins/sdk-setup.md
View File

@ -1,33 +1,33 @@
---
read_when:
- 你正在为一个插件添加设置向导
- 你需要理解 `setup-entry.ts` 与 `index.ts` 的区别
- 你正在定义插件配置模式或 `package.json` 中的 OpenClaw 元数据
- 你需要了解 `setup-entry.ts` 与 `index.ts` 的区别
- 你正在定义插件配置 schema 或 `package.json` 中的 OpenClaw 元数据
sidebarTitle: Setup and Config
summary: 设置向导、setup-entry.ts、配置模式和 package.json 元数据
summary: 设置向导、`setup-entry.ts`、配置 schema，以及 `package.json` 元数据
title: 插件设置和配置
x-i18n:
generated_at: "2026-04-20T16:50:01Z"
generated_at: "2026-04-23T05:14:54Z"
model: gpt-5.4
provider: openai
source_hash: 5de51b55c04b4f05947bc2d4de9c34e24a26e4ca8b3ff9b1711288a8e5b63273
source_hash: ccdafb9a562353a7851fcd47bbc382961a449f5d645362c800f64c60579ce7b2
source_path: plugins/sdk-setup.md
workflow: 15
---
# 插件设置和配置
关于插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置模式的参考。
关于插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置 schema 的参考。
<Tip>
**在找操作指南吗？** 操作指南会结合上下文介绍打包流程：
**想看操作演练？** 操作指南会结合上下文讲解打包流程：
[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和
[提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。
</Tip>
## 包元数据
你的 `package.json` 需要包含一个 `openclaw` 字段，用来告诉插件系统你的插件提供了什么：
你的 `package.json` 需要有一个 `openclaw` 字段，用来告诉插件系统你的插件提供了什么：
**渠道插件：**
@ -42,7 +42,7 @@ x-i18n:
"channel": {
"id": "my-channel",
"label": "My Channel",
"blurb": "Short description of the channel."
"blurb": "渠道的简短描述。"
}
}
}
@ -69,46 +69,44 @@ x-i18n:
}
```
如果你要在 ClawHub 上对外发布该插件，这些 `compat` 和 `build`
字段是必需的。规范的发布代码片段位于
`docs/snippets/plugin-publish/`。
如果你要在 ClawHub 上对外发布插件，则这些 `compat` 和 `build` 字段是必需的。规范的发布片段位于 `docs/snippets/plugin-publish/` 中。
### `openclaw` 字段
| 字段 | 类型 | 说明 |
| ------------ | ---------- | -------------------------------------------------------------------- |
| `extensions` | `string[]` | 入口点文件（相对于包根目录） |
| `setupEntry` | `string` | 仅用于设置的轻量入口（可选） |
| `channel` | `object` | 用于设置、选择器、快速开始和状态界面的渠道目录元数据 |
| `providers` | `string[]` | 该插件注册的提供商 id |
| `install` | `object` | 安装提示：`npmSpec`、`localPath`、`defaultChoice`、`minHostVersion`、`allowInvalidConfigRecovery` |
| `startup` | `object` | 启动行为标志 |
| 字段 | 类型 | 描述 |
| ------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `extensions` | `string[]` | 入口点文件（相对于包根目录） |
| `setupEntry` | `string` | 仅用于设置的轻量入口（可选） |
| `channel` | `object` | 用于设置、选择器、快速开始和状态界面的渠道目录元数据 |
| `providers` | `string[]` | 由该插件注册的提供商 id |
| `install` | `object` | 安装提示：`npmSpec`、`localPath`、`defaultChoice`、`minHostVersion`、`expectedIntegrity`、`allowInvalidConfigRecovery` |
| `startup` | `object` | 启动行为标志 |
### `openclaw.channel`
`openclaw.channel` 是低成本的包元数据，用于在运行时加载之前支持渠道发现和设置界面。
`openclaw.channel` 是低成本的包元数据，用于在运行时加载前支持渠道发现和设置界面。
| 字段 | 类型 | 含义 |
| -------------------------------------- | ---------- | ----------------------------------------------------- |
| `id` | `string` | 规范的渠道 id。 |
| `label` | `string` | 主要渠道标签。 |
| 字段 | 类型 | 含义 |
| -------------------------------------- | ---------- | ------------------------------------------------- |
| `id` | `string` | 规范的渠道 id。 |
| `label` | `string` | 主要渠道标签。 |
| `selectionLabel` | `string` | 当需要与 `label` 不同时，在选择器 / 设置中显示的标签。 |
| `detailLabel` | `string` | 用于更丰富渠道目录和状态界面的次级详情标签。 |
| `docsPath` | `string` | 用于设置和选择链接的文档路径。 |
| `docsLabel` | `string` | 当需要与渠道 id 不同时，用作文档链接标签的覆盖值。 |
| `blurb` | `string` | 简短的新手引导 / 目录描述。 |
| `order` | `number` | 在渠道目录中的排序顺序。 |
| `aliases` | `string[]` | 用于渠道选择的额外查找别名。 |
| `preferOver` | `string[]` | 该渠道应优先于的较低优先级插件 / 渠道 id。 |
| `systemImage` | `string` | 渠道 UI 目录中可选的图标 / system-image 名称。 |
| `selectionDocsPrefix` | `string` | 在选择界面中文档链接前显示的前缀文本。 |
| `detailLabel` | `string` | 用于更丰富的渠道目录和状态界面的次级详情标签。 |
| `docsPath` | `string` | 用于设置和选择链接的文档路径。 |
| `docsLabel` | `string` | 当文档链接标签需要与渠道 id 不同时使用的覆盖标签。 |
| `blurb` | `string` | 简短的新手引导 / 目录描述。 |
| `order` | `number` | 在渠道目录中的排序顺序。 |
| `aliases` | `string[]` | 用于渠道选择的额外查找别名。 |
| `preferOver` | `string[]` | 该渠道应优先于的低优先级插件 / 渠道 id。 |
| `systemImage` | `string` | 用于渠道 UI 目录的可选图标 / system-image 名称。 |
| `selectionDocsPrefix` | `string` | 在选择界面中，文档链接前显示的前缀文本。 |
| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 |
| `selectionExtras` | `string[]` | 附加在选择文案中的额外短文本。 |
| `markdownCapable` | `boolean` | 将该渠道标记为支持 Markdown，用于出站格式决策。 |
| `exposure` | `object` | 渠道在设置、已配置列表和文档界面中的可见性控制。 |
| `quickstartAllowFrom` | `boolean` | 让该渠道加入标准快速开始 `allowFrom` 设置流程。 |
| `forceAccountBinding` | `boolean` | 即使只有一个账户存在，也要求显式账户绑定。 |
| `preferSessionLookupForAnnounceTarget` | `boolean` | 为该渠道解析公告目标时，优先使用会话查找。 |
| `selectionExtras` | `string[]` | 附加在选择文案中的额外短文本。 |
| `markdownCapable` | `boolean` | 将该渠道标记为支持 Markdown，用于出站格式决策。 |
| `exposure` | `object` | 渠道在设置、已配置列表和文档界面中的可见性控制。 |
| `quickstartAllowFrom` | `boolean` | 让该渠道加入标准快速开始 `allowFrom` 设置流程。 |
| `forceAccountBinding` | `boolean` | 即使只存在一个账户，也要求显式账户绑定。 |
| `preferSessionLookupForAnnounceTarget` | `boolean` | 在为该渠道解析公告目标时，优先使用会话查找。 |
示例：
@ -122,11 +120,11 @@ x-i18n:
"detailLabel": "My Channel Bot",
"docsPath": "/channels/my-channel",
"docsLabel": "my-channel",
"blurb": "Webhook-based self-hosted chat integration.",
"blurb": "基于 Webhook 的自托管聊天集成。",
"order": 80,
"aliases": ["mc"],
"preferOver": ["my-channel-legacy"],
"selectionDocsPrefix": "Guide:",
"selectionDocsPrefix": "指南：",
"selectionExtras": ["Markdown"],
"markdownCapable": true,
"exposure": {
@ -144,10 +142,9 @@ x-i18n:
- `configured`：在已配置 / 状态类列表界面中包含该渠道
- `setup`：在交互式设置 / 配置选择器中包含该渠道
- `docs`：将该渠道标记为面向公开的文档 / 导航界面内容
- `docs`：将该渠道标记为在文档 / 导航界面中面向公开展示
`showConfigured` 和 `showInSetup` 仍然作为旧别名受支持。优先使用
`exposure`。
`showConfigured` 和 `showInSetup` 仍然作为旧版别名受到支持。请优先使用 `exposure`。
### `openclaw.install`
@ -157,15 +154,30 @@ x-i18n:
| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
| `npmSpec` | `string` | 用于安装 / 更新流程的规范 npm spec。 |
| `localPath` | `string` | 本地开发或内置安装路径。 |
| `defaultChoice` | `"npm"` \| `"local"` | 当两者都可用时，优先使用的安装来源。 |
| `defaultChoice` | `"npm"` \| `"local"` | 当两者都可用时的首选安装来源。 |
| `minHostVersion` | `string` | 支持的最低 OpenClaw 版本，格式为 `>=x.y.z`。 |
| `expectedIntegrity` | `string` | 预期的 npm dist 完整性字符串，通常为 `sha512-...`，用于固定版本安装。 |
| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重装流程从特定的过期配置失败中恢复。 |
如果设置了 `minHostVersion`，安装和清单注册表加载都会强制执行它。
较旧的宿主会跳过该插件；无效的版本字符串会被拒绝。
交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载前就暴露提供商认证选项，或暴露渠道设置 / 目录元数据，则新手引导可以显示该选项、提示用户选择 npm 还是本地安装、安装或启用插件，然后继续执行所选流程。npm 新手引导选项要求可信的目录元数据，其中必须包含精确版本的 `npmSpec` 和 `expectedIntegrity`；未固定版本的包名和 dist-tag 不会用于自动新手引导安装。请将“显示什么”的元数据保留在 `openclaw.plugin.json` 中，将“如何安装”的元数据保留在 `package.json` 中。
`allowInvalidConfigRecovery` 不是针对损坏配置的通用绕过方式。它仅用于内置插件的狭义恢复场景，使重装 / 设置可以修复已知的升级遗留问题，例如缺失的内置插件路径，或该插件对应的过期 `channels.<id>`
条目。如果配置因无关原因损坏，安装仍会以关闭方式失败，并提示操作员运行 `openclaw doctor --fix`。
如果设置了 `minHostVersion`，则安装和清单注册表加载都会强制执行它。较旧的宿主会跳过该插件；无效的版本字符串会被拒绝。
对于固定版本的 npm 安装，请在 `npmSpec` 中保留精确版本，并添加预期的制品完整性：
```json
{
"openclaw": {
"install": {
"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",
"expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
"defaultChoice": "npm"
}
}
}
```
`allowInvalidConfigRecovery` 并不是对损坏配置的一般性绕过。它仅用于狭窄范围内的内置插件恢复，以便重装 / 设置可以修复已知的升级遗留问题，例如缺失的内置插件路径，或同一插件对应的过期 `channels.<id>` 条目。如果配置因无关原因损坏，安装仍会默认拒绝，并提示操作者运行 `openclaw doctor --fix`。
### 延迟完整加载
@ -183,39 +195,38 @@ x-i18n:
}
```
启用后，OpenClaw 在监听前的启动阶段只会加载 `setupEntry`，即使对于已配置的渠道也是如此。完整入口会在 Gateway 网关开始监听后再加载。
启用后，在监听前的启动阶段，OpenClaw 即使对已经配置的渠道也只会加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后再加载。
<Warning>
仅当你的 `setupEntry` 注册了 Gateway 网关在开始监听前所需的一切内容时，才应启用延迟加载（渠道注册、HTTP 路由、Gateway 网关方法）。如果完整入口拥有必需的启动能力，请保持默认行为。
只有在你的 `setupEntry` 已经注册了 Gateway 网关在开始监听前所需的一切内容时，才应启用延迟加载（渠道注册、HTTP 路由、Gateway 网关方法）。如果完整入口拥有必需的启动能力，请保持默认行为。
</Warning>
如果你的设置 / 完整入口会注册 Gateway 网关 RPC 方法，请保持使用插件专属前缀。保留的核心管理命名空间（`config.*`、
`exec.approvals.*`、`wizard.*`、`update.*`）仍由核心拥有，并始终解析到 `operator.admin`。
如果你的设置 / 完整入口会注册 Gateway 网关 RPC 方法，请保持使用插件专属前缀。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍归核心所有，并始终解析到 `operator.admin`。
## 插件清单
每个原生插件都必须在包根目录提供一个 `openclaw.plugin.json`。
OpenClaw 使用它在不执行插件代码的情况下验证配置。
每个原生插件都必须在包根目录中提供一个 `openclaw.plugin.json`。
OpenClaw 会用它在不执行插件代码的情况下验证配置。
```json
{
"id": "my-plugin",
"name": "My Plugin",
"description": "Adds My Plugin capabilities to OpenClaw",
"description": "为 OpenClaw 增加 My Plugin 功能",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"webhookSecret": {
"type": "string",
"description": "Webhook verification secret"
"description": "Webhook 验证密钥"
}
}
}
}
```
对于渠道插件，添加 `kind` 和 `channels`：
对于渠道插件，请添加 `kind` 和 `channels`：
```json
{
@ -230,7 +241,7 @@ OpenClaw 使用它在不执行插件代码的情况下验证配置。
}
```
即使插件没有任何配置，也必须提供一个模式。空模式也是有效的：
即使插件没有任何配置，也必须提供一个 schema。空 schema 是有效的：
```json
{
@ -242,22 +253,22 @@ OpenClaw 使用它在不执行插件代码的情况下验证配置。
}
```
完整模式参考请见 [插件清单](/zh-CN/plugins/manifest)。
完整的 schema 参考请参阅 [插件清单](/zh-CN/plugins/manifest)。
## ClawHub 发布
对于插件包，请使用包专用的 ClawHub 命令：
对于插件包，请使用针对包的 ClawHub 命令：
```bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
旧版仅适用于 skill 的发布别名是给 Skills 使用的。插件包应始终使用 `clawhub package publish`。
旧的仅限 Skills 的发布别名用于 Skills。插件包应始终使用 `clawhub package publish`。
## 设置入口
`setup-entry.ts` 文件是 `index.ts` 的轻量替代方案，当 OpenClaw 只需要设置界面时（新手引导、配置修复、禁用渠道检查），会加载它。
`setup-entry.ts` 文件是 `index.ts` 的轻量替代方案，当 OpenClaw 只需要设置界面时（新手引导、配置修复、已禁用渠道检查），会加载它。
```typescript
// setup-entry.ts
@ -267,14 +278,14 @@ import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
这可以避免在设置流程中加载重量级运行时代码（加密库、CLI 注册、后台服务）。
这可以避免在设置流程中加载沉重的运行时代码（加密库、CLI 注册、后台服务）。
对于将设置安全导出保存在 sidecar 模块中的内置工作区渠道，可以使用
`openclaw/plugin-sdk/channel-entry-contract` 中的
`defineBundledChannelSetupEntry(...)`，而不是
`defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，从而让设置阶段的运行时接线保持轻量且明确。
`defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，以便让设置时的运行时接线保持轻量且明确。
**OpenClaw 在以下情况下会使用 `setupEntry` 而不是完整入口：**
**OpenClaw 何时使用 `setupEntry` 而不是完整入口：**
- 渠道已禁用，但仍需要设置 / 新手引导界面
- 渠道已启用，但尚未配置
@ -283,8 +294,8 @@ export default defineSetupPluginEntry(myChannelPlugin);
**`setupEntry` 必须注册的内容：**
- 渠道插件对象（通过 `defineSetupPluginEntry`）
- 在 Gateway 网关监听前所需的任何 HTTP 路由
- 启动期间所需的任何 Gateway 网关方法
- 任何在 Gateway 网关开始监听前所需的 HTTP 路由
- 启动期间需要的任何 Gateway 网关方法
这些启动期 Gateway 网关方法仍应避免使用保留的核心管理命名空间，例如 `config.*` 或 `update.*`。
@ -292,45 +303,41 @@ export default defineSetupPluginEntry(myChannelPlugin);
- CLI 注册
- 后台服务
- 重量级运行时导入（加密库、SDK）
- 沉重的运行时导入（加密库、SDK）
- 仅在启动后才需要的 Gateway 网关方法
### 窄化设置辅助导入
### 精简的设置辅助导入
对于仅设置的热点路径，如果你只需要设置界面的一部分，优先使用窄化的设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口：
对于仅设置的热路径，当你只需要部分设置功能时，应优先使用更精简的设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口：
| 导入路径 | 适用场景 | 关键导出 |
| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动中仍可用的设置期运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | 感知环境的账户设置适配器 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置 / 安装 CLI / 归档 / 文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| 导入路径 | 适用场景 | 关键导出 |
| ---------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动期间仍可用的设置时运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | 识别环境的账户设置适配器 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置 / 安装 CLI / 归档 / 文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
当你需要完整的共享设置工具箱时，请使用更宽泛的 `plugin-sdk/setup`
接缝，其中包括配置补丁辅助工具，例如
当你需要完整的共享设置工具箱时，请使用更宽泛的 `plugin-sdk/setup` 接缝，其中包括配置补丁辅助工具，例如
`moveSingleAccountChannelSectionToDefaultAccount(...)`。
这些设置补丁适配器在导入时仍然对热点路径安全。它们对内置单账户提升契约界面的查找是惰性的，因此导入
`plugin-sdk/setup-runtime` 不会在实际使用适配器之前急切加载内置契约界面发现逻辑。
这些设置补丁适配器在导入时仍然对热路径安全。它们对内置单账户提升契约面的查找是惰性的，因此导入
`plugin-sdk/setup-runtime` 不会在适配器真正使用前，急切加载内置契约面发现逻辑。
### 渠道自有的单账户提升
当一个渠道从单账户顶层配置升级到
`channels.<id>.accounts.*` 时，默认的共享行为会将被提升的账户作用域值移动到
`accounts.default` 中。
当渠道从单账户顶层配置升级到
`channels.<id>.accounts.*` 时，默认的共享行为会把提升后的账户作用域值移入 `accounts.default`。
内置渠道可以通过其设置契约界面缩小或覆盖该提升行为：
内置渠道可以通过其设置契约面来收窄或覆盖这一提升行为：
- `singleAccountKeysToMove`：应移动到被提升账户中的额外顶层键
- `namedAccountPromotionKeys`：当已存在命名账户时，只有这些键会移动到被提升账户中；共享的策略 / 投递键会保留在渠道根级别
- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账户接收被提升的值
- `singleAccountKeysToMove`：应移入提升后账户的额外顶层键
- `namedAccountPromotionKeys`：如果已存在具名账户，则仅将这些键移入提升后的账户；共享的 policy / delivery 键保留在渠道根级别
- `resolveSingleAccountPromotionTarget(...)`：选择由哪个现有账户接收提升后的值
Matrix 是当前的内置示例。如果恰好已经存在一个命名的 Matrix 账户，或者
`defaultAccount` 指向一个现有的非规范键（例如 `Ops`），提升过程会保留该账户，而不是创建新的
`accounts.default` 条目。
Matrix 是当前的内置示例。如果恰好已经存在一个具名 Matrix 账户，或者如果 `defaultAccount` 指向现有的非规范键名（例如 `Ops`），那么提升会保留该账户，而不是创建新的 `accounts.default` 条目。
## 配置模式
## 配置 schema
插件配置会根据清单中的 JSON Schema 进行验证。用户通过以下方式配置插件：
插件配置会根据你的清单中的 JSON Schema 进行验证。用户通过以下方式配置插件：
```json5
{
@ -346,9 +353,9 @@ Matrix 是当前的内置示例。如果恰好已经存在一个命名的 Matrix
}
```
你的插件会在注册期间通过 `api.pluginConfig` 接收这份配置。
你的插件会在注册期间通过 `api.pluginConfig` 收到该配置。
对于特定渠道的配置，请改用渠道配置区段：
对于渠道专属配置，请改用渠道配置部分：
```json5
{
@ -361,10 +368,10 @@ Matrix 是当前的内置示例。如果恰好已经存在一个命名的 Matrix
}
```
### 构建渠道配置模式
### 构建渠道配置 schema
使用 `openclaw/plugin-sdk/core` 中的 `buildChannelConfigSchema` 将一个
Zod 模式转换为 OpenClaw 用于验证的 `ChannelConfigSchema` 包装器：
使用 `openclaw/plugin-sdk/core` 中的 `buildChannelConfigSchema`，将
Zod schema 转换为 OpenClaw 可验证的 `ChannelConfigSchema` 包装器：
```typescript
import { z } from "zod";
@ -391,8 +398,8 @@ import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
const setupWizard: ChannelSetupWizard = {
channel: "my-channel",
status: {
configuredLabel: "Connected",
unconfiguredLabel: "Not configured",
configuredLabel: "已连接",
unconfiguredLabel: "未配置",
resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
},
credentials: [
@ -401,9 +408,9 @@ const setupWizard: ChannelSetupWizard = {
providerHint: "my-channel",
credentialLabel: "Bot token",
preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
keepPrompt: "Keep current token?",
inputPrompt: "Enter your bot token:",
envPrompt: "使用环境中的 MY_CHANNEL_BOT_TOKEN 吗？",
keepPrompt: "保留当前 token 吗？",
inputPrompt: "输入你的 bot token：",
inspect: ({ cfg, accountId }) => {
const token = (cfg.channels as any)?.["my-channel"]?.token;
return {
@ -417,23 +424,21 @@ const setupWizard: ChannelSetupWizard = {
```
`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、
`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize`
等。完整示例请参阅内置插件包（例如 Discord 插件中的 `src/channel.setup.ts`）。
`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等等。
完整示例请参阅内置插件包（例如 Discord 插件的 `src/channel.setup.ts`）。
对于只需要标准
`note -> prompt -> parse -> merge -> patch`
流程的私信 allowlist 提示，优先使用
`note -> prompt -> parse -> merge -> patch` 流程的私信白名单提示，应优先使用
`openclaw/plugin-sdk/setup` 中的共享设置辅助工具：
`createPromptParsedAllowFromForAccount(...)`、
`createTopLevelChannelParsedAllowFromPrompt(...)` 和
`createNestedChannelParsedAllowFromPrompt(...)`。
对于仅在标签、分数和可选附加行上有所不同的渠道设置状态块，优先使用
对于仅在标签、分数和可选附加行方面有所不同的渠道设置状态块，应优先使用
`openclaw/plugin-sdk/setup` 中的
`createStandardChannelSetupStatus(...)`，而不是在每个插件中手动重复构建相同的
`status` 对象。
`createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。
对于只应在特定上下文中显示的可选设置界面，使用
对于只应在某些上下文中显示的可选设置界面，请使用
`openclaw/plugin-sdk/channel-setup` 中的
`createOptionalChannelSetupSurface`：
@ -446,30 +451,26 @@ const setupSurface = createOptionalChannelSetupSurface({
npmSpec: "@myorg/openclaw-my-channel",
docsPath: "/channels/my-channel",
});
// Returns { setupAdapter, setupWizard }
// 返回 { setupAdapter, setupWizard }
```
`plugin-sdk/channel-setup` 还暴露了更底层的
`createOptionalChannelSetupAdapter(...)` 和
`createOptionalChannelSetupWizard(...)` 构建器，用于你只需要该可选安装界面其中一半的情况。
`createOptionalChannelSetupWizard(...)` 构建器，用于你只需要该可选安装界面其中一半能力的场景。
生成的可选适配器 / 向导在真正写入配置时会以关闭方式失败。它们会在
`validateInput`、`applyAccountConfig` 和 `finalize`
之间复用同一条“需要安装”的消息，并在设置了 `docsPath`
时附加一个文档链接。
生成的可选适配器 / 向导在真实配置写入时会默认拒绝失败关闭。它们会在
`validateInput`、`applyAccountConfig` 和 `finalize` 之间复用一条“需要安装”的提示信息，并在设置了 `docsPath` 时附加文档链接。
对于基于二进制文件的设置 UI，优先使用共享的委托辅助工具，而不是在每个渠道中复制相同的二进制 / 状态粘合逻辑：
对于由二进制驱动的设置 UI，应优先使用共享的委托辅助工具，而不是在每个渠道中复制相同的二进制 / 状态粘合逻辑：
- `createDetectedBinaryStatus(...)`：用于仅在标签、提示、分数和二进制检测上变化的状态块
- `createDetectedBinaryStatus(...)`：用于仅在标签、提示、分数和二进制检测上有所不同的状态块
- `createCliPathTextInput(...)`：用于基于路径的文本输入
- `createDelegatedSetupWizardStatusResolvers(...)`、
`createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和
`createDelegatedResolveConfigured(...)`：用于当 `setupEntry`
需要惰性转发到更重量级的完整向导时
- `createDelegatedTextInputShouldPrompt(...)`：用于当 `setupEntry`
只需要委托一个 `textInputs[*].shouldPrompt` 判断时
`createDelegatedResolveConfigured(...)`：用于当 `setupEntry` 需要惰性转发到更重的完整向导时
- `createDelegatedTextInputShouldPrompt(...)`：用于当 `setupEntry` 只需要委托 `textInputs[*].shouldPrompt` 决策时
## 发布和安装
## 发布与安装
**外部插件：** 发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，然后安装：
@ -480,16 +481,16 @@ openclaw plugins install @myorg/openclaw-my-plugin
OpenClaw 会先尝试 ClawHub，并在失败后自动回退到 npm。你也可以显式强制使用 ClawHub：
```bash
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub only
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # 仅 ClawHub
```
没有对应的 `npm:` 覆盖方式。当你希望在 ClawHub 回退后走 npm 路径时，请使用普通的 npm 包 spec：
没有对应的 `npm:` 覆盖写法。当你希望在 ClawHub 回退后走 npm 路径时，请使用普通的 npm 包 spec：
```bash
openclaw plugins install @myorg/openclaw-my-plugin
```
**仓库内插件：** 放在内置插件工作区目录树下，它们会在构建期间自动被发现。
**仓库内插件：** 放在内置插件工作区树下，构建期间会自动发现。
**用户可以安装：**
@ -499,13 +500,13 @@ openclaw plugins install <package-name>
<Info>
对于来源于 npm 的安装，`openclaw plugins install` 会运行
`npm install --ignore-scripts`（不执行生命周期脚本）。请保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
`npm install --ignore-scripts`（不执行 lifecycle scripts）。请保持插件依赖树为纯 JS / TS，并避免使用需要 `postinstall` 构建的包。
</Info>
内置的 OpenClaw 自有插件是唯一的启动修复例外：当打包安装检测到某个插件因插件配置、旧版渠道配置或其内置默认启用清单而处于启用状态时，启动过程会在导入前为该插件安装缺失的运行时依赖。第三方插件不应依赖启动时安装；请继续使用显式的插件安装器。
内置的 OpenClaw 自有插件是唯一的启动修复例外：当打包安装检测到某个插件已通过插件配置、旧版渠道配置或其内置默认启用清单启用时，启动流程会在导入前为该插件安装缺失的运行时依赖。第三方插件不应依赖启动期安装；请继续使用显式的插件安装器。
## 相关内容
- [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) -- `definePluginEntry` 和 `defineChannelPluginEntry`
- [插件清单](/zh-CN/plugins/manifest) -- 完整清单模式参考
- [SDK 概览 入口点](/zh-CN/plugins/sdk-entrypoints) -- `definePluginEntry` 和 `defineChannelPluginEntry`
- [插件清单](/zh-CN/plugins/manifest) -- 完整清单 schema 参考
- [构建插件](/zh-CN/plugins/building-plugins) -- 分步入门指南

181
docs/zh-CN/reference/RELEASING.md
View File

@ -5,165 +5,182 @@ read_when:
summary: 公开发布渠道、版本命名和发布节奏
title: 发布策略
x-i18n:
generated_at: "2026-04-21T04:34:57Z"
generated_at: "2026-04-23T05:14:53Z"
model: gpt-5.4
provider: openai
source_hash: 356844708f6ecdae4acfcce853ce16ae962914a9fdd1cfc38a22ac4c439ba172
source_hash: edb86d97a37e400a4041f1e087c90d9a4f26087cc5da5c37d11f7ca58dba9404
source_path: reference/RELEASING.md
workflow: 15
---
# 发布策略
OpenClaw 有三个公开发布通道：
OpenClaw 有三个公开发布渠道：
- stable：带标签的发布，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest`
- stable：带标签的发布，默认发布到 npm `beta`，或在明确指定时发布到 npm `latest`
- beta：预发布标签，发布到 npm `beta`
- dev：`main` 的持续更新头部版本
## 版本命名
- stable 发布版本：`YYYY.M.D`
- 稳定版发布版本：`YYYY.M.D`
- Git 标签：`vYYYY.M.D`
- stable 修正版发布版本：`YYYY.M.D-N`
- 稳定版修正版发布版本：`YYYY.M.D-N`
- Git 标签：`vYYYY.M.D-N`
- beta 预发布版本：`YYYY.M.D-beta.N`
- Beta 预发布版本：`YYYY.M.D-beta.N`
- Git 标签：`vYYYY.M.D-beta.N`
- 月和日不要补零
- `latest` 表示当前已提升为正式版的 stable npm 发布
- `latest` 表示当前已提升的稳定版 npm 发布
- `beta` 表示当前 beta 安装目标
- stable 和 stable 修正版发布默认发布到 npm `beta`；发布操作人员可以明确指定目标为 `latest`，或稍后再将经过验证的 beta 构建提升过去
- 每个 stable OpenClaw 发布都会同时发布 npm 包和 macOS 应用；
beta 发布通常会先验证并发布 npm/包路径，而 mac 应用的构建/签名/公证通常保留给 stable，除非有明确请求
- 稳定版和稳定版修正版默认发布到 npm `beta`；发布操作人员可以明确指定目标为 `latest`，或者稍后再将已验证的 beta 构建提升过去
- 每个稳定版 OpenClaw 发布都会同时交付 npm 包和 macOS 应用；
beta 发布通常会先验证并发布 npm/package 路径，而 mac 应用的构建 / 签名 / 公证则保留给稳定版，除非有明确要求
## 发布节奏
- 发布采用 beta 优先
- 只有在最新 beta 验证通过后，才会跟进 stable
- 发布先走 beta
- 只有在最新 beta 完成验证后，才会跟进 stable
- 维护者通常会从当前 `main` 创建 `release/YYYY.M.D` 分支来切发布，
这样发布验证和修复就不会阻塞 `main` 上的新开发
- 如果 beta 标签已经推送或发布但需要修复，维护者会切下一个
`-beta.N` 标签，而不是删除或重建旧的 beta 标签
- 详细的发布流程、审批、凭证和恢复说明仅供维护者使用
- 如果某个 beta 标签已经被推送或发布且需要修复，维护者会切下一个
`-beta.N` 标签，而不是删除或重新创建旧的 beta 标签
- 详细的发布流程、审批、凭证和恢复说明仅面向维护者
## 发布预检
- 在发布预检前运行 `pnpm check:test-types`，这样测试 TypeScript 就能在更快的本地 `pnpm check` 门禁之外继续受到覆盖
- 在发布预检前运行 `pnpm check:architecture`，这样更广泛的导入循环和架构边界检查就能在更快的本地门禁之外保持通过
- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，这样打包验证步骤所需的
`dist/*` 发布产物和 Control UI bundle 就会存在
- 每次带标签发布前都要运行 `pnpm release:check`
- 在发布预检前运行 `pnpm check:test-types`，这样测试 TypeScript 也能获得覆盖，
不会被更快的本地 `pnpm check` 检查门槛遗漏
- 在发布预检前运行 `pnpm check:architecture`，这样更全面的导入循环和架构边界检查
就能在更快的本地检查之外保持绿色
- 在运行 `pnpm release:check` 之前先运行 `pnpm build && pnpm ui:build`，
以确保打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在
- 每次带标签的发布前都要运行 `pnpm release:check`
- 发布检查现在在单独的手动工作流中运行：
`OpenClaw Release Checks`
- `OpenClaw Release Checks` 还会在发布审批前运行 QA Lab 模拟一致性门槛和实时
Telegram QA 通道。实时通道使用
`qa-live-shared` 环境和 Convex CI 凭证租约。
- 跨操作系统的安装和升级运行时验证由私有调用方工作流
`openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`
发起，该工作流会调用可复用的公开工作流
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意为之：让真正的 npm 发布路径保持简短、
确定且以产物为中心，而较慢的在线检查保留在独立通道中，
这样它们就不会拖慢或阻塞发布
- 这种拆分是有意为之：让真实的 npm 发布路径保持简短、
可预测且聚焦产物，而较慢的实时检查保留在它们自己的通道中，
这样就不会拖慢或阻塞发布
- 发布检查必须从 `main` 工作流引用或
`release/YYYY.M.D` 工作流引用发起，这样工作流逻辑和密钥始终受控
- 该工作流接受现有发布标签，或当前完整的
`release/YYYY.M.D` 工作流引用发起，这样工作流逻辑和密钥才能保持受控
- 该工作流接受已有的发布标签，或当前完整的
40 字符工作流分支提交 SHA
- 在 commit-SHA 模式下，它只接受当前工作流分支的 HEAD；较早的发布提交请使用发布标签
- 在提交 SHA 模式下，它只接受当前工作流分支的 HEAD；较旧的发布提交请使用
发布标签
- `OpenClaw NPM Release` 的仅验证预检也接受当前完整的
40 字符工作流分支提交 SHA，而不要求已推送标签
40 字符工作流分支提交 SHA，无需先推送标签
- 该 SHA 路径仅用于验证，不能提升为真实发布
- 在 SHA 模式下，工作流只会为包元数据检查合成 `v<package.json version>`；真实发布仍然需要真实的发布标签
- 这两个工作流都将真实发布和提升路径保留在 GitHub 托管的 runner 上，
而不改动状态的验证路径可以使用更大的
- 在 SHA 模式下，工作流只会为包元数据检查临时生成
`v<package.json version>`；真实发布仍然需要真实的发布标签
- 这两个工作流都会将真实发布和提升路径保留在 GitHub 托管的
runner 上，而非变更性的验证路径则可以使用更大的
Blacksmith Linux runner
- 该工作流运行
- 该工作流会运行
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
并同时使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流密钥
- npm 发布预检不再等待单独的发布检查通道
- 在批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
（或对应的 beta/修正版标签）
- 在审批前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
（或对应的 beta / 修正版标签）
- npm 发布后，运行
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
（或对应的 beta/修正版版本）以在全新的临时前缀中验证已发布注册表安装路径
- 维护者发布自动化现在采用先预检再提升：
（或对应的 beta / 修正版版本），以在新的临时前缀中验证已发布的注册表安装路径
- 维护者发布自动化现在采用先预检后提升的方式：
- 真实 npm 发布必须通过成功的 npm `preflight_run_id`
- 真实 npm 发布必须从与成功预检运行相同的 `main` 或
`release/YYYY.M.D` 分支发起
- stable npm 发布默认目标为 `beta`
- stable npm 发布可以通过工作流输入明确将目标设为 `latest`
- 稳定版 npm 发布默认使用 `beta`
- 稳定版 npm 发布可以通过工作流输入明确指定目标为 `latest`
- 基于令牌的 npm dist-tag 变更现在位于
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
中，以增强安全性，因为 `npm dist-tag add` 仍然需要 `NPM_TOKEN`，而公开仓库保持仅使用 OIDC 发布
中，以提升安全性，因为 `npm dist-tag add` 仍然需要 `NPM_TOKEN`，
而公开仓库保留仅 OIDC 的发布方式
- 公开的 `macOS Release` 仅用于验证
- 真实的私有 mac 发布必须通过成功的私有 mac
`preflight_run_id` 和 `validate_run_id`
- 真实发布路径会提升已准备好的产物，而不是再次重新构建
- 对于像 `YYYY.M.D-N` 这样的 stable 修正版发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同临时前缀升级路径，
这样发布修正就不能悄悄让旧的全局安装仍停留在基础 stable 载荷上
- npm 发布预检默认失败关闭，除非 tarball 同时包含
`dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 载荷，
这样我们就不会再次发布一个空的浏览器仪表盘
- `pnpm test:install:smoke` 还会对候选更新 tarball 强制执行 npm 打包 `unpackedSize` 预算，
因此安装器端到端测试会在发布路径之前捕获意外的包体膨胀
- 如果此次发布工作涉及 CI 规划、扩展时间清单或扩展测试矩阵，
请在批准前从 `.github/workflows/ci.yml` 重新生成并审查由规划器负责的
- 对于像 `YYYY.M.D-N` 这样的稳定版修正版发布，发布后验证器
还会检查从 `YYYY.M.D` 升级到 `YYYY.M.D-N` 的同一临时前缀升级路径，
这样发布修正就不会在无声无息中让旧的全局安装停留在基础稳定版负载上
- npm 发布预检会默认失败关闭，除非 tarball 同时包含
`dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 负载，
以避免我们再次发布空的浏览器仪表盘
- `pnpm test:install:smoke` 还会对候选更新 tarball 的 npm pack `unpackedSize` 预算执行强制检查，
这样安装器 e2e 就能在发布路径之前捕获意外的打包膨胀
- 如果发布工作涉及 CI 规划、扩展 timing 清单或
扩展测试矩阵，请在审批前重新生成并审查
来自 `.github/workflows/ci.yml` 的、由 planner 负责的
`checks-node-extensions` 工作流矩阵输出，
这样发布说明就不会描述过时的 CI 布局
- stable macOS 发布就绪还包括更新器相关界面：
以避免发布说明描述的是过时的 CI 布局
- 稳定版 macOS 发布就绪还包括更新器相关界面：
- GitHub 发布最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip
- 打包后的应用必须保留非调试 bundle id、非空的 Sparkle feed
- 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定版 zip
- 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed
URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion`
## NPM 工作流输入
`OpenClaw NPM Release` 接受以下由操作人员控制的输入：
- `tag`：必填发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前完整的
40 字符工作流分支提交 SHA，用于仅验证的预检
- `preflight_only`：`true` 表示仅验证/构建/打包，`false` 表示真实发布路径
- `preflight_run_id`：在真实发布路径中必填，这样工作流会复用成功预检运行中准备好的 tarball
- `tag`：必填的发布标签，例如 `v2026.4.2`、`v2026.4.2-1`，或
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前
完整的 40 字符工作流分支提交 SHA，用于仅验证的预检
- `preflight_only`：`true` 表示仅进行验证 / 构建 / 打包，`false` 表示进入
真实发布路径
- `preflight_run_id`：在真实发布路径中必填，这样工作流就会复用成功预检运行中准备好的 tarball
- `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta`
`OpenClaw Release Checks` 接受以下由操作人员控制的输入：
- `ref`：现有发布标签，或在从 `main` 发起时用于验证的当前完整
40 字符 `main` 提交 SHA；如果从发布分支发起，则使用现有发布标签或当前完整的
40 字符发布分支提交 SHA
- `ref`：已有发布标签，或从 `main` 发起时要验证的当前完整
40 字符 `main` 提交 SHA；如果从发布分支发起，请使用已有的发布标签
或当前完整的 40 字符发布分支提交 SHA
规则：
- stable 和修正版标签可以发布到 `beta` 或 `latest`
- beta 预发布标签只能发布到 `beta`
- 稳定版和修正版标签可以发布到 `beta` 或 `latest`
- Beta 预发布标签只能发布到 `beta`
- 对于 `OpenClaw NPM Release`，只有在
`preflight_only=true` 时才允许使用完整提交 SHA 作为输入
- `OpenClaw Release Checks` 始终仅用于验证，也接受当前工作流分支提交 SHA
- 发布检查的 commit-SHA 模式还要求当前工作流分支 HEAD
- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；
- `OpenClaw Release Checks` 始终仅用于验证，也接受
当前工作流分支提交 SHA
- 发布检查的提交 SHA 模式还要求必须是当前工作流分支 HEAD
- 真实发布路径必须使用与预检期间相同的 `npm_dist_tag`；
工作流会在继续发布前验证该元数据
## Stable npm 发布顺序
## 稳定版 npm 发布顺序
在切一个 stable npm 发布时：
在切稳定版 npm 发布时：
1. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`
1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true`
- 在标签尚不存在时，你可以使用当前完整的工作流分支提交
SHA，对预检工作流执行一次仅验证的干运行
2. 为正常的 beta 优先流程选择 `npm_dist_tag=beta`，或仅在你明确希望直接发布 stable 时选择 `latest`
3. 单独运行 `OpenClaw Release Checks`，使用相同的标签，或在你希望获得在线 prompt cache 覆盖时使用完整的当前工作流分支提交 SHA
- 这样刻意拆分，是为了在不把长时间运行或易波动检查重新耦合回发布工作流的前提下，继续提供在线覆盖
SHA，对预检工作流进行仅验证的试运行
2. 按照正常的先 beta 后 stable 流程选择 `npm_dist_tag=beta`，或者仅在你有意直接发布稳定版时选择 `latest`
3. 单独运行 `OpenClaw Release Checks`，使用相同的标签，或者在你想获得实时 prompt cache、
QA Lab 一致性和实时 Telegram 覆盖时，使用当前完整的工作流分支提交 SHA
- 之所以刻意分离，是为了在不重新耦合长时间运行或不稳定检查到发布工作流的前提下，
仍然保留实时覆盖能力
4. 保存成功的 `preflight_run_id`
5. 再次运行 `OpenClaw NPM Release`，这次使用 `preflight_only=false`，并带上相同的
`tag`、相同的 `npm_dist_tag`，以及保存下来的 `preflight_run_id`
6. 如果该发布先落在 `beta`，使用私有的
5. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`，同时使用相同的
`tag`、相同的 `npm_dist_tag`，以及已保存的 `preflight_run_id`
6. 如果该发布先落在 `beta`，请使用私有的
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
工作流将该 stable 版本从 `beta` 提升到 `latest`
7. 如果该发布有意直接发布到 `latest`，并且 `beta`
也应立即跟随相同的 stable 构建，请使用同一个私有工作流让两个 dist-tag 都指向该 stable 版本，或让其计划内的自修复同步稍后再移动 `beta`
工作流，将该稳定版从 `beta` 提升到 `latest`
7. 如果该发布是有意直接发布到 `latest`，并且 `beta`
也应立即跟随同一个稳定版构建，请使用同一个私有工作流
将两个 dist-tag 都指向该稳定版，或者交由其定时
自愈同步稍后再推动 `beta`
dist-tag 变更位于私有仓库中是出于安全考虑，因为它仍然需要
`NPM_TOKEN`，而公开仓库保持仅使用 OIDC 发布。
dist-tag 变更之所以放在私有仓库中，是出于安全考虑，因为它仍然
需要 `NPM_TOKEN`，而公开仓库保留仅 OIDC 的发布方式。
这样，直接发布路径和 beta 优先提升路径都保持了文档化且对操作人员可见。
这样既记录了直接发布路径，也记录了先 beta 再提升的路径，并且两者
都对操作人员可见。
## 公开参考
@ -176,4 +193,4 @@ dist-tag 变更位于私有仓库中是出于安全考虑，因为它仍然需
维护者会使用私有发布文档
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
作为实际操作手册。
作为实际运行手册。