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-27 21:06:35 +00:00
parent 5719845b79
commit 680f7a893e
3 changed files with 486 additions and 513 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

446
docs/zh-CN/plugins/sdk-subpaths.md
View File

@ -1,91 +1,91 @@
---
read_when:
- 为插件导入选择正确的 plugin-sdk 子路径
- 审查 bundled-plugin 子路径和辅助接口
summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于何处
- 为插件导入选择合适的 plugin-sdk 子路径
- 审计 bundled-plugin 子路径和辅助接口
summary: 插件 SDK 子路径目录：按领域分组，各个导入路径分别位于何处
title: 插件 SDK 子路径
x-i18n:
generated_at: "2026-04-27T20:10:07Z"
generated_at: "2026-04-27T21:04:55Z"
model: gpt-5.4
provider: openai
source_hash: b55ce02a25cfe9fe1bea2263bad31b50cc72c06affa451cc9cecac4404e70d79
source_hash: ceab4e0a5ecceacbb06584fcc8fe47b394511822d9435cc1fd7bba1572492a63
source_path: plugins/sdk-subpaths.md
workflow: 15
---
插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外公开。
本页按用途分组，汇总了常用子路径。完整的 200 多个子路径的生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；
其中也会出现保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们属于实现细节。
plugin SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。
本页按用途分组，整理了常用子路径。完整的 200 多个子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；
其中也会出现为 bundled-plugin 预留的辅助子路径，但除非某个文档页面明确将其作为公开能力推荐，否则它们都属于实现细节。
关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
关于插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
## 插件入口
| 子路径 | 关键导出 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具，以及 `summarizeMigrationItems` |
| `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/migration` | 迁移提供商条目辅助函数，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助函数，以及 `summarizeMigrationItems` |
| `plugin-sdk/migration-runtime` | 运行时迁移辅助函数，例如 `copyMigrationFileItem` 和 `writeMigrationReport` |
<AccordionGroup>
<Accordion title="渠道子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | 共享设置向导辅助工具、允许列表提示、设置状态构建器 |
| `plugin-sdk/setup` | 共享设置向导辅助函数、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账号配置/操作门控辅助工具、默认账号回退辅助工具 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账号 ID 规范化辅助工具 |
| `plugin-sdk/account-resolution` | 账号查找 + 默认回退辅助工具 |
| `plugin-sdk/account-helpers` | 精简的账号列表/账号操作辅助工具 |
| `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助函数、默认账户回退辅助函数 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 |
| `plugin-sdk/account-helpers` | 精简的账户列表 / 账户操作辅助函数 |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 共享渠道配置 schema 原语和通用构建器 |
| `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置渠道配置 schema，仅用于内置兼容性 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带内置契约回退 |
| `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 |
| `plugin-sdk/channel-config-schema-legacy` | 已弃用的 bundled-channel 配置 schema，仅用于 bundled 兼容性 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 验证辅助函数，并带有 bundled-contract 回退 |
| `plugin-sdk/command-gating` | 精简的命令授权门控辅助函数 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/收尾辅助工具 |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建器辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 |
| `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 |
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 |
| `plugin-sdk/outbound-send-deps` | 用于渠道适配器的轻量级出站发送依赖查找 |
| `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和载荷规划辅助工具 |
| `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完结辅助函数 |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 |
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 |
| `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 |
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 |
| `plugin-sdk/outbound-send-deps` | 面向渠道适配器的轻量级出站发送依赖查找 |
| `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和载荷规划辅助函数 |
| `plugin-sdk/poll-runtime` | 精简的投票规范化辅助函数 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 |
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 |
| `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
| `plugin-sdk/channel-status` | 共享渠道 Status 快照/摘要辅助工具 |
| `plugin-sdk/conversation-runtime` | 对话 / 线程绑定、配对和已配置绑定辅助函数 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 |
| `plugin-sdk/channel-status` | 共享渠道状态快照 / 摘要辅助函数 |
| `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 原语 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
| `plugin-sdk/allowlist-config-edit` | 允许列表配置编辑/读取辅助工具 |
| `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 共享直接私信认证/保护辅助工具 |
| `plugin-sdk/interactive-runtime` | 语义消息展示、投递和旧版交互式回复辅助工具。请参阅 [消息展示](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 兼容性 barrel，包含入站去抖、提及匹配、提及策略辅助工具和 envelope 辅助工具 |
| `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖辅助工具 |
| `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时接口的精简提及策略和提及文本辅助工具 |
| `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助工具 |
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 |
| `plugin-sdk/channel-logging` | 用于入站丢弃和输入中/确认失败的渠道日志辅助工具 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 |
| `plugin-sdk/group-access` | 共享群组访问判定辅助函数 |
| `plugin-sdk/direct-dm` | 共享直接私信认证 / 守卫辅助函数 |
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助函数。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 兼容性 barrel，包含入站去抖、提及匹配、提及策略辅助函数和 envelope 辅助函数 |
| `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖辅助函数 |
| `plugin-sdk/channel-mention-gating` | 精简的提及策略和提及文本辅助函数，不包含更广泛的入站运行时接口 |
| `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助函数 |
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 |
| `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助函数 |
| `plugin-sdk/channel-send-result` | 回复结果类型 |
| `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 |
| `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 |
| `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 |
| `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 |
| `plugin-sdk/channel-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈/反应接线 |
| `plugin-sdk/channel-secret-runtime` | 精简的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 |
| `plugin-sdk/channel-feedback` | 反馈 / reaction 连接逻辑 |
| `plugin-sdk/channel-secret-runtime` | 精简的 secret-contract 辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment`，以及 secret target 类型 |
</Accordion>
<Accordion title="提供商子路径">
@ -93,213 +93,213 @@ x-i18n:
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/lmstudio` | 受支持的 LM Studio 提供商门面，用于设置、目录发现和运行时模型准备 |
| `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时门面，用于本地服务器默认值、模型发现、请求头和已加载模型辅助工具 |
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的聚焦设置辅助工具 |
| `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时门面，用于本地服务器默认值、模型发现、请求头和已加载模型辅助函数 |
| `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的聚焦设置辅助函数 |
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置档案写入辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置文件写入辅助函数，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
| `plugin-sdk/provider-auth-login` | 提供商插件共享的交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
| `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助函数 |
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商端点辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的模型 ID 规范化辅助工具 |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart form 辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精简 web-search 配置/凭证辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter/getter |
| `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助工具 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似能力 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 |
| `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助工具 |
| `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助函数、提供商 HTTP 错误，以及音频转写 multipart form 辅助函数 |
| `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助函数 |
| `plugin-sdk/provider-web-search-config-contract` | 针对不需要插件启用连接逻辑的提供商而设计的精简 web-search 配置 / 凭证辅助函数 |
| `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及带作用域的凭证 setter / getter |
| `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助函数 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似内容 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / DeepSeek V4 / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换和可写传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 |
| `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 |
| `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助函数 |
</Accordion>
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具（包括动态参数菜单格式化）、发送者授权辅助工具 |
| `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置档案/过滤器辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 用于高频渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更精简的 adapter/gateway 接口已足够，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账号绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | exec/插件审批回复载荷辅助工具 |
| `plugin-sdk/approval-runtime` | exec/插件审批载荷辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示辅助工具，例如 `formatApprovalDisplayPath` |
| `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 |
| `plugin-sdk/channel-contract-testing` | 精简的渠道契约测试辅助工具，不含宽泛的测试 barrel |
| `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化和原生会话目标辅助工具 |
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
| `plugin-sdk/command-primitives-runtime` | 用于高频渠道路径的轻量级命令文本谓词 |
| `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助工具 |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数（包括动态参数菜单格式化）、发送者授权辅助函数 |
| `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助函数 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助函数 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助函数 |
| `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生审批适配器加载辅助函数 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；如果更精简的 adapter / gateway 接口已足够，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 |
| `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复载荷辅助函数 |
| `plugin-sdk/approval-runtime` | exec / 插件审批载荷辅助函数、原生审批路由 / 运行时辅助函数，以及结构化审批显示辅助函数，例如 `formatApprovalDisplayPath` |
| `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助函数 |
| `plugin-sdk/channel-contract-testing` | 精简的渠道契约测试辅助函数，不包含宽泛的测试 barrel |
| `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标辅助函数 |
| `plugin-sdk/command-detection` | 共享命令检测辅助函数 |
| `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本判定辅助函数 |
| `plugin-sdk/command-surface` | 命令主体规范化和命令表面辅助函数 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件密钥接口的精简密钥契约收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间密钥比较和密钥收集辅助工具 |
| `plugin-sdk/ssrf-policy` | 主机允许列表和私有网络 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 精简的固定 dispatcher 辅助工具，不包含宽泛的基础设施运行时接口 |
| `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch、SSRF 错误和 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | 密钥输入解析辅助工具 |
| `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具，以及原始 websocket/body 强制转换 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
| `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 表面的精简 secret-contract 收集辅助函数 |
| `plugin-sdk/secret-ref-runtime` | 面向 secret-contract / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助函数 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间 secret 比较和 secret 收集辅助函数 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-dispatcher` | 精简的固定 dispatcher 辅助函数，不包含宽泛的基础设施运行时接口 |
| `plugin-sdk/ssrf-runtime` | 固定 dispatcher、带 SSRF 防护的 fetch、SSRF 错误和 SSRF 策略辅助函数 |
| `plugin-sdk/secret-input` | secret 输入解析辅助函数 |
| `plugin-sdk/webhook-ingress` | Webhook 请求 / 目标辅助函数，以及原始 websocket / body 强制转换 |
| `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 |
</Accordion>
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 宽泛的运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和退避辅助工具 |
| `plugin-sdk/browser-config` | 受支持的浏览器配置门面，用于规范化的 profile/默认值、CDP URL 解析和浏览器控制认证辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 |
| `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助函数 |
| `plugin-sdk/runtime-env` | 精简的运行时环境变量、日志记录器、超时、重试和退避辅助函数 |
| `plugin-sdk/browser-config` | 受支持的浏览器配置门面，用于规范化配置文件 / 默认值、CDP URL 解析和浏览器控制认证辅助函数 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助函数 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享插件命令/钩子/http/交互式辅助工具 |
| `plugin-sdk/hook-runtime` | 共享 webhook/内部钩子流水线辅助工具 |
| `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助工具 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和延迟命令组辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道 Status 补丁辅助工具 |
| `plugin-sdk/config-types` | 仅类型配置接口，用于插件配置形状，例如 `OpenClawConfig` 以及渠道/提供商配置类型 |
| `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助工具，例如 `requireRuntimeConfig`、`resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` |
| `plugin-sdk/config-mutation` | 事务性配置变更辅助工具，例如 `mutateConfigFile`、`replaceConfigFile` 和 `logConfigUpdated` |
| `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助工具，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照 setter |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约接口不可用时也可使用 |
| `plugin-sdk/text-autolink-runtime` | 不依赖宽泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/profile 辅助工具、原生路由/运行时辅助工具，以及结构化审批显示路径格式化 |
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/收尾和会话标签辅助工具 |
| `plugin-sdk/reply-history` | 共享短时间窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/plugin-runtime` | 共享插件命令 / hook / http / 交互辅助函数 |
| `plugin-sdk/hook-runtime` | 共享 webhook / 内部钩子流水线辅助函数 |
| `plugin-sdk/lazy-runtime` | 惰性运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助函数 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和惰性命令组辅助函数 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道状态补丁辅助函数 |
| `plugin-sdk/config-types` | 仅类型的配置接口，用于插件配置形状，例如 `OpenClawConfig` 以及渠道 / 提供商配置类型 |
| `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助函数，例如 `requireRuntimeConfig`、`resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` |
| `plugin-sdk/config-mutation` | 事务性配置变更辅助函数，例如 `mutateConfigFile`、`replaceConfigFile` 和 `logConfigUpdated` |
| `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助函数，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照 setter |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使 bundled Telegram 契约接口不可用时也可使用 |
| `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，不包含宽泛的 text-runtime barrel |
| `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / 配置文件辅助函数、原生路由 / 运行时辅助函数，以及结构化审批显示路径格式化 |
| `plugin-sdk/reply-runtime` | 共享入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发 / 完结和对话标签辅助函数 |
| `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 精简的文本/Markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、updated-at 和存储变更辅助工具 |
| `plugin-sdk/cron-store-runtime` | Cron 存储路径/加载/保存辅助工具 |
| `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 |
| `plugin-sdk/routing` | 路由/会话键/账号绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享渠道/账号 Status 摘要辅助工具、运行时状态默认值和问题元数据辅助工具 |
| `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 |
| `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 |
| `plugin-sdk/request-url` | 从类似 fetch/request 的输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout/stderr 结果 |
| `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
| `plugin-sdk/reply-chunking` | 精简的文本 / Markdown 分块辅助函数 |
| `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、updated-at 和存储变更辅助函数 |
| `plugin-sdk/cron-store-runtime` | Cron 存储路径 / 加载 / 保存辅助函数 |
| `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助函数 |
| `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享渠道 / 账户状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 |
| `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 |
| `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 |
| `plugin-sdk/request-url` | 从 fetch / 类 request 输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带计时功能的命令运行器，输出规范化的 stdout / stderr 结果 |
| `plugin-sdk/param-readers` | 常用工具 / CLI 参数读取器 |
| `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化载荷 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 |
| `plugin-sdk/model-session-runtime` | 模型/会话覆盖辅助工具，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` |
| `plugin-sdk/talk-config-runtime` | Talk 提供商配置解析辅助工具 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 |
| `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 |
| `plugin-sdk/tool-send` | 从工具参数中提取标准发送目标字段 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 |
| `plugin-sdk/logging-core` | 子系统日志记录器和脱敏辅助函数 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助函数 |
| `plugin-sdk/model-session-runtime` | 模型 / 会话覆盖辅助函数，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` |
| `plugin-sdk/talk-config-runtime` | 对话提供商配置解析辅助函数 |
| `plugin-sdk/json-store` | 小型 JSON 状态读 / 写辅助函数 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助函数 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 |
| `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助函数 |
| `plugin-sdk/acp-binding-resolve-runtime` | 只读 ACP 绑定解析，不引入生命周期启动导入 |
| `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 原语 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
| `plugin-sdk/extension-shared` | 共享被动渠道、Status 和环境代理辅助原语 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表构建/序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向低层 Agent harness 的实验性受信任插件接口：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化/详情辅助工具，以及尝试结果实用工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 |
| `plugin-sdk/async-lock-runtime` | 面向小型运行时状态文件的进程本地异步锁辅助工具 |
| `plugin-sdk/channel-activity-runtime` | 渠道活动遥测辅助工具 |
| `plugin-sdk/concurrency-runtime` | 有界异步任务并发辅助工具 |
| `plugin-sdk/dedupe-runtime` | 内存去重缓存辅助工具 |
| `plugin-sdk/delivery-queue-runtime` | 出站待投递排空辅助工具 |
| `plugin-sdk/file-access-runtime` | 安全本地文件和媒体源路径辅助工具 |
| `plugin-sdk/heartbeat-runtime` | 心跳事件和可见性辅助工具 |
| `plugin-sdk/number-runtime` | 数值强制转换辅助工具 |
| `plugin-sdk/secure-random-runtime` | 安全令牌/UUID 辅助工具 |
| `plugin-sdk/system-event-runtime` | 系统事件队列辅助工具 |
| `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助工具 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 |
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 |
| `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 |
| `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助函数 |
| `plugin-sdk/agent-harness` | 面向可信插件的实验性底层 agent harness 接口：harness 类型、活动运行转向 / 中止辅助函数、OpenClaw 工具桥接辅助函数、运行时计划工具策略辅助函数、终端结果分类、工具进度格式化 / 详情辅助函数，以及尝试结果实用函数 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 |
| `plugin-sdk/async-lock-runtime` | 面向小型运行时状态文件的进程本地异步锁辅助函数 |
| `plugin-sdk/channel-activity-runtime` | 渠道活动遥测辅助函数 |
| `plugin-sdk/concurrency-runtime` | 有界异步任务并发辅助函数 |
| `plugin-sdk/dedupe-runtime` | 内存去重缓存辅助函数 |
| `plugin-sdk/delivery-queue-runtime` | 出站待投递清空辅助函数 |
| `plugin-sdk/file-access-runtime` | 安全本地文件和媒体源路径辅助函数 |
| `plugin-sdk/heartbeat-runtime` | 心跳事件和可见性辅助函数 |
| `plugin-sdk/number-runtime` | 数值强制转换辅助函数 |
| `plugin-sdk/secure-random-runtime` | 安全令牌 / UUID 辅助函数 |
| `plugin-sdk/system-event-runtime` | 系统事件队列辅助函数 |
| `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助函数 |
| `plugin-sdk/infra-runtime` | 已弃用的兼容性 shim；请使用上方更聚焦的运行时子路径 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和 trace-context 辅助工具 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助工具 |
| `plugin-sdk/runtime-fetch` | 具备 dispatcher 感知能力的运行时 fetch，不引入代理/受保护 fetch 导入 |
| `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不依赖宽泛媒体运行时接口 |
| `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 |
| `plugin-sdk/session-store-runtime` | 会话存储辅助工具，不引入宽泛配置写入/维护导入 |
| `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不引入宽泛配置/安全导入 |
| `plugin-sdk/string-coerce-runtime` | 精简的原始记录/字符串强制转换与规范化辅助工具，不引入 Markdown/日志导入 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
| `plugin-sdk/agent-runtime` | 智能体目录/身份/Agent 工作区辅助工具 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和 trace-context 辅助函数 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和固定查找辅助函数 |
| `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入代理 / guarded-fetch 导入 |
| `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不包含宽泛的媒体运行时接口 |
| `plugin-sdk/session-binding-runtime` | 当前对话绑定状态，不包含已配置绑定路由或配对存储 |
| `plugin-sdk/session-store-runtime` | 会话存储辅助函数，不引入宽泛配置写入 / 维护导入 |
| `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不引入宽泛配置 / 安全导入 |
| `plugin-sdk/string-coerce-runtime` | 精简的原始记录 / 字符串强制转换和规范化辅助函数，不引入 Markdown / 日志导入 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 |
| `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="能力与测试子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体载荷构建器 |
| `plugin-sdk/media-store` | 精简媒体存储辅助工具，例如 `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助工具、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助工具导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具和安全文本实用工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的指令、注册表、校验和语音辅助工具导出 |
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令、规范化和语音辅助工具导出 |
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 |
| `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助函数，以及媒体载荷构建器 |
| `plugin-sdk/media-store` | 精简的媒体存储辅助函数，例如 `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助函数、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本 / Markdown / 日志辅助函数，例如剥离仅供助手可见的文本、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本实用工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助函数 |
| `plugin-sdk/speech` | Speech 提供商类型，以及面向提供商的指令、注册表、验证和语音辅助导出 |
| `plugin-sdk/speech-core` | 共享 Speech 提供商类型、注册表、指令、规范化和语音辅助导出 |
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助函数和共享 WebSocket 会话辅助函数 |
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 |
| `plugin-sdk/image-generation` | 图像生成提供商类型 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障切换、认证和注册表辅助工具 |
| `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助工具 |
| `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 |
| `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助函数 |
| `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助函数 |
| `plugin-sdk/webhook-path` | Webhook 路径规范化辅助函数 |
| `plugin-sdk/web-media` | 共享远程 / 本地媒体加载辅助函数 |
| `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` |
| `plugin-sdk/testing` | 公开扩展测试辅助工具，包括 `installCommonResolveTargetErrorCases`、`shouldAckReaction`、`writeSkill`、`createTestRegistry` 和实时生成环境加载 |
| `plugin-sdk/testing` | 公开的扩展测试辅助函数，包括插件注册表 / 运行时 mock、schema / 媒体 / 实时测试辅助函数、`installCommonResolveTargetErrorCases`、`writeSkill`、`createTestRegistry` 和实时生成环境变量加载 |
</Accordion>
<Accordion title="Memory 子路径">
<Accordion title="记忆子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager/config/file/CLI 辅助工具 |
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机嵌入契约、注册表访问、本地提供商以及通用批处理/远程辅助工具 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | Memory 主机查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory 主机密钥辅助工具 |
| `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | Memory 主机 Status 辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 面向供应商中立的 memory 主机核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | 面向供应商中立的 memory 主机事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | 面向供应商中立的 memory 主机文件/运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 面向与 memory 相邻插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 用于访问搜索管理器的活动 Memory 运行时门面 |
| `plugin-sdk/memory-host-status` | 面向供应商中立的 memory 主机 Status 辅助工具别名 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 |
| `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于管理器 / 配置 / 文件 / CLI 辅助函数 |
| `plugin-sdk/memory-core-engine-runtime` | 记忆索引 / 搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | 记忆主机基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | 记忆主机嵌入契约、注册表访问、本地提供商和通用批处理 / 远程辅助函数 |
| `plugin-sdk/memory-core-host-engine-qmd` | 记忆主机 QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | 记忆主机存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | 记忆主机多模态辅助函数 |
| `plugin-sdk/memory-core-host-query` | 记忆主机查询辅助函数 |
| `plugin-sdk/memory-core-host-secret` | 记忆主机 secret 辅助函数 |
| `plugin-sdk/memory-core-host-events` | 记忆主机事件日志辅助函数 |
| `plugin-sdk/memory-core-host-status` | 记忆主机状态辅助函数 |
| `plugin-sdk/memory-core-host-runtime-cli` | 记忆主机 CLI 运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-core` | 记忆主机核心运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-files` | 记忆主机文件 / 运行时辅助函数 |
| `plugin-sdk/memory-host-core` | 面向供应商中立的记忆主机核心运行时辅助函数别名 |
| `plugin-sdk/memory-host-events` | 面向供应商中立的记忆主机事件日志辅助函数别名 |
| `plugin-sdk/memory-host-files` | 面向供应商中立的记忆主机文件 / 运行时辅助函数别名 |
| `plugin-sdk/memory-host-markdown` | 面向记忆相关插件的共享托管 Markdown 辅助函数 |
| `plugin-sdk/memory-host-search` | 面向搜索管理器访问的活动记忆运行时门面 |
| `plugin-sdk/memory-host-status` | 面向供应商中立的记忆主机状态辅助函数别名 |
| `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 |
</Accordion>
<Accordion title="保留的内置辅助子路径">
| 系列 | 当前子路径 | 预期用途 |
<Accordion title="预留 bundled-helper 子路径">
| 分类 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置浏览器插件支持辅助工具。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`browser-support` 仍是兼容性 barrel。 |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 |
| 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容性/辅助接口。新插件应导入通用 SDK 子路径或插件本地 barrel。 |
| 认证/插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled Browser 插件支持辅助函数。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和用于规范化 `browser.tabCleanup` 形状的 `ResolvedBrowserTabCleanupConfig`。`browser-support` 仍然是兼容性 barrel。 |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | bundled Matrix 辅助 / 运行时接口 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE 辅助 / 运行时接口 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled IRC 辅助接口 |
| 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的 bundled 渠道兼容性 / 辅助接口。新插件应导入通用 SDK 子路径或插件本地 barrel。 |
| 认证 / 插件专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled 功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>

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

@ -1,170 +1,152 @@
---
read_when:
- 正在查找公开发布渠道定义
- 运行发布验证或软件包验收
- 正在查找版本命名和节奏
summary: 发布通道、操作员检查清单、验证框、版本命名和节奏
- 正在运行发布验证或软件包验收
- 正在查找版本命名和发布节奏
summary: 发布流程通道、运维人员检查清单、验证框、版本命名和发布节奏
title: 发布策略
x-i18n:
generated_at: "2026-04-27T19:38:38Z"
generated_at: "2026-04-27T21:04:56Z"
model: gpt-5.4
provider: openai
source_hash: 1ad73d75e54bd21cb740b64af0b33cc9d38283de8917544d5795990d3f0aacb6
source_hash: f3ff3c7887c59005a977522e3a0e80ea3458e29d12f6976397b0749d8001d914
source_path: reference/RELEASING.md
workflow: 15
---
OpenClaw 有三个公开发布通道：
OpenClaw 有三个公开发布流程通道：
- stable：打标签的发布，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest`
- stable：带标签的发布，默认发布到 npm `beta`，或在明确要求时发布到 npm `latest`
- beta：预发布标签，发布到 npm `beta`
- dev：`main` 的持续移动头部版本
- dev：`main` 的持续更新头部版本
## 版本命名
- Stable 发布版本：`YYYY.M.D`
- Git 标签：`vYYYY.M.D`
- Stable 修正版发布版本：`YYYY.M.D-N`
- Stable 修正发布版本：`YYYY.M.D-N`
- Git 标签：`vYYYY.M.D-N`
- Beta 预发布版本：`YYYY.M.D-beta.N`
- Git 标签：`vYYYY.M.D-beta.N`
- 不要为月份或日期补零
- `latest` 表示当前已提升的 stable npm 发布版本
- 月份或日期不要补零
- `latest` 表示当前已提升为正式版本的 stable npm 发布
- `beta` 表示当前 beta 安装目标
- Stable 和 stable 修正版发布默认发布到 npm `beta`；发布操作员可以显式指定 `latest`，或稍后再提升经过验证的 beta 构建
- 每个 stable OpenClaw 发布都会同时交付 npm 软件包和 macOS 应用；
beta 发布通常会先验证并发布 npm/软件包路径，而 macOS 应用的构建/签名/公证通常保留给 stable，除非有明确请求
- Stable 和 stable 修正发布默认发布到 npm `beta`；发布运维人员可以显式指定 `latest`，或在之后提升一个经过验证的 beta 构建
- 每个 stable OpenClaw 发布都会同时发布 npm 软件包和 macOS 应用；
beta 发布通常会先验证并发布 npm/软件包路径，而 macOS 应用的构建/签名/公证通常保留给 stable，除非有明确要求
## 发布节奏
- 发布先走 beta
- 只有在最新 beta 完成验证后，才会进入 stable
- 维护者通常会从当前 `main` 创建 `release/YYYY.M.D` 分支来进行发布，
- 发布采用 beta 优先
- 只有在最新 beta 完成验证后，才会继续 stable
- 维护者通常会从当前 `main` 创建 `release/YYYY.M.D` 分支来切发布，
这样发布验证和修复就不会阻塞 `main` 上的新开发
- 如果某个 beta 标签已经推送或发布且需要修复，维护者会切出下一个 `-beta.N` 标签，而不是删除或重建旧的 beta 标签
- 详细的发布流程、审批、凭证和恢复说明仅面向维护者
- 如果某个 beta 标签已经推送或发布但需要修复，维护者会切下一个 `-beta.N` 标签，而不是删除或重建旧的 beta 标签
- 详细的发布流程、审批、凭证和恢复说明仅对维护者开放
## 发布操作员检查清单
## 发布运维人员检查清单
此检查清单是发布流程的公开形态。私有凭证、
签名、公证、dist-tag 恢复以及紧急回滚细节保留在
仅维护者可见的发布运行手册中。
这份检查清单展示了发布流程的公开形态。私有凭证、
签名、公证、dist-tag 恢复以及紧急回滚细节保留在仅维护者可见的发布运行手册中。
1. 从当前 `main` 开始：拉取最新代码，确认目标提交已推送，
并确认当前 `main` 的 CI 足够绿色，可以从它切分支。
2. 使用 `/changelog` 基于真实提交历史重写 `CHANGELOG.md` 的顶部章节，
保持条目面向用户，提交它，推送它，并在分支前再执行一次 rebase/pull。
3. 审查
1. 从当前 `main` 开始：拉取最新内容，确认目标提交已经推送，
并确认当前 `main` 的 CI 足够绿色，可以基于它创建分支。
2. 使用 `/changelog` 根据真实提交历史重写 `CHANGELOG.md` 顶部章节，
保持条目面向用户，提交并推送它，然后在创建分支前再执行一次 rebase/pull。
3. 检查
`src/plugins/compat/registry.ts` 和
`src/commands/doctor/shared/deprecation-compat.ts`
中的发布兼容性记录。只有在升级路径仍有保障时才移除已过期的兼容性，
否则要记录为什么仍需保留。
`src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍被覆盖时才移除已过期的兼容项，否则记录为什么要有意保留它。
4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上进行常规发布工作。
5. 为目标标签更新所有必需的版本位置，然后运行本地确定性预检：
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build`，以及 `pnpm release:check`。
6. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签尚不存在时，
可以使用完整的 40 字符发布分支 SHA 进行仅验证用途的预检。保存成功的
`preflight_run_id`。
7. 针对发布分支、标签或完整提交 SHA，使用 `Full Release Validation`
启动所有预发布测试。这是四个大型发布验证框的唯一手动入口：
Vitest、Docker、QA Lab 和 Package。
8. 如果验证失败，在发布分支上修复，并重新运行能证明修复有效的最小失败范围，
比如单个文件、通道、workflow 作业、软件包配置、提供商或模型 allowlist。
只有在改动范围使先前证据失效时，才重新运行完整总流程。
9. 对于 beta，打上 `vYYYY.M.D-beta.N` 标签，使用 npm dist-tag `beta` 发布，
然后针对已发布的 `openclaw@YYYY.M.D-beta.N`
或 `openclaw@beta` 软件包运行发布后软件包验收。如果已推送或已发布的 beta 需要修复，
则切出下一个 `-beta.N`；不要删除或改写旧的 beta。
10. 对于 stable，只有在经过验证的 beta 或候选发布已具备所需验证证据后才继续。
Stable 的 npm 发布会通过 `preflight_run_id` 复用成功的预检产物；stable 的 macOS 发布就绪
还要求 `main` 上存在已打包的 `.zip`、`.dmg`、`.dSYM.zip` 以及更新后的
`appcast.xml`。
11. 发布后，运行 npm 发布后验证器；当你需要发布后的渠道证明时，可选择运行独立的
已发布 npm Telegram E2E；并在需要时执行 dist-tag 提升、基于完整匹配
`CHANGELOG.md` 章节生成 GitHub release/prerelease 说明，以及发布公告步骤。
`pnpm check:test-types`、`pnpm check:architecture`、
`pnpm build && pnpm ui:build` 和 `pnpm release:check`。
6. 以 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签尚不存在时，可以使用完整的 40 位发布分支 SHA 仅进行验证预检。保存成功的 `preflight_run_id`。
7. 针对发布分支、标签或完整提交 SHA，启动 `Full Release Validation` 的所有预发布测试。这是四个大型发布验证框的唯一手动入口：Vitest、Docker、QA Lab 和 Package。
8. 如果验证失败，在发布分支上修复，并重新运行能证明修复有效的最小失败文件、通道、工作流任务、软件包配置、提供商或模型允许列表。只有当变更范围使之前的证据失效时，才重新运行完整的总体验证。
9. 对于 beta，打上 `vYYYY.M.D-beta.N` 标签，使用 npm dist-tag `beta` 发布，然后针对已发布的 `openclaw@YYYY.M.D-beta.N` 或 `openclaw@beta` 软件包运行发布后软件包验收。如果已推送或已发布的 beta 需要修复，切下一个 `-beta.N`；不要删除或重写旧的 beta。
10. 对于 stable，只有在经过审查的 beta 或候选发布具备所需验证证据后才能继续。Stable 的 npm 发布会通过 `preflight_run_id` 复用成功的预检产物；stable macOS 发布就绪还要求 `main` 上存在已打包的 `.zip`、`.dmg`、`.dSYM.zip` 以及更新后的 `appcast.xml`。
11. 发布后，运行 npm 发布后验证器；在你需要发布后渠道证明时，可选运行独立的已发布 npm Telegram E2E；然后在需要时进行 dist-tag 提升、基于完整匹配的 `CHANGELOG.md` 章节生成 GitHub release/prerelease 说明，以及执行发布公告步骤。
## 发布预检
- 在发布预检之前运行 `pnpm check:test-types`，这样测试 TypeScript 也能在更快的本地 `pnpm check` 门禁之外得到覆盖
- 在发布预检之前运行 `pnpm check:architecture`，这样更广泛的导入循环和架构边界检查也能在更快的本地门禁之外保持绿色
- 在运行 `pnpm release:check` 之前执行 `pnpm build && pnpm ui:build`，这样打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 就会存在
- 在发布审批之前运行手动 `Full Release Validation` workflow，从一个入口点启动所有预发布测试框。它接受分支、标签或完整提交 SHA，分发手动 `CI`，并分发 `OpenClaw Release Checks`，用于安装冒烟测试、软件包验收、Docker 发布路径测试套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 通道。只有在软件包已经发布且还需要运行发布后 Telegram E2E 时，才提供 `npm_telegram_package_spec`。示例：
- 在发布预检之前运行 `pnpm check:test-types`，以便在更快的本地 `pnpm check` 门禁之外，测试 TypeScript 仍然得到覆盖
- 在发布预检之前运行 `pnpm check:architecture`，以便在更快的本地门禁之外，更广泛的导入循环和架构边界检查保持绿色
- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，以便打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在
- 在发布审批前运行手动 `Full Release Validation` 工作流，以便通过一个入口点启动所有预发布验证框。它接受分支、标签或完整提交 SHA，会派发手动 `CI`，并派发 `OpenClaw Release Checks`，用于安装冒烟测试、软件包验收、Docker 发布路径测试套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram 通道。只有在软件包已经发布且还需要运行发布后的 Telegram E2E 时，才提供 `npm_telegram_package_spec`。当私有证据报告需要证明验证与某个已发布的 npm 软件包匹配、但又不强制运行 Telegram E2E 时，提供 `evidence_package_spec`。
示例：
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- 当你希望在发布工作继续进行的同时，为某个软件包候选版本获得旁路证明时，运行手动 `Package Acceptance` workflow。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 时，可用当前 `workflow_ref` harness 打包可信的 `package_ref` 分支/标签/SHA；对带有必需 SHA-256 的 HTTPS tarball 使用 `source=url`；对由其他 GitHub Actions 运行上传的 tarball 使用 `source=artifact`。该 workflow 会将候选版本解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可使用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 对同一个 tarball 运行 Telegram QA。示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai`
- 当你希望在发布工作继续进行时，为某个候选软件包获得旁路证明，请运行手动 `Package Acceptance` 工作流。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 时，会用当前 `workflow_ref` harness 打包一个可信的 `package_ref` 分支/标签/SHA；对带必填 SHA-256 的 HTTPS tarball 使用 `source=url`；对由其他 GitHub Actions 运行上传的 tarball 使用 `source=artifact`。该工作流会将候选解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并且可使用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一 tarball 运行 Telegram QA。
示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai`
常见配置：
- `smoke`：安装/渠道/智能体、Gateway 网关网络和配置热重载通道
- `package`：原生制品软件包/更新/插件通道，不含 OpenWebUI 或 live ClawHub
- `product`：在 package 配置基础上增加 MCP 渠道、cron/subagent 清理、OpenAI web search 和 OpenWebUI
- `full`：带 OpenWebUI 的 Docker 发布路径分块
- `package`：原生产物软件包/更新/插件通道，不包含 OpenWebUI 或 live ClawHub
- `product`：在 package 配置基础上增加 MCP 渠道、cron/subagent 清理、OpenAI Web 搜索和 OpenWebUI
- `full`：包含 OpenWebUI 的 Docker 发布路径分块
- `custom`：精确选择 `docker_lanes`，用于聚焦重跑
- 当你只需要发布候选版本具备完整常规 CI 覆盖时，直接运行手动 `CI` workflow。手动 CI 分发会绕过 changed 范围限制，并强制运行 Linux Node 分片、bundled-plugin 分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟测试、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n 通道。
- 当你只需要对发布候选进行完整的常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动触发的 CI 会绕过 changed 范围限制，并强制运行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟测试、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n 通道。
示例：`gh workflow run ci.yml --ref release/YYYY.M.D`
- 在验证发布遥测时运行 `pnpm qa:otel:smoke`。它会通过本地 OTLP/HTTP 接收器驱动 QA-lab，并验证导出的 trace span 名称、受限属性以及内容/标识符脱敏，无需 Opik、Langfuse 或其他外部收集器。
- 在每次打标签发布之前运行 `pnpm release:check`
- 发布检查现在在单独的手动 workflow 中运行：
- 在验证发布遥测时运行 `pnpm qa:otel:smoke`。它会通过本地 OTLP/HTTP 接收器运行 QA-lab，并验证导出的 trace span 名称、有界属性以及内容/标识符脱敏，而不需要 Opik、Langfuse 或其他外部采集器。
- 在每次带标签的发布之前运行 `pnpm release:check`
- 发布检查现在在单独的手动工作流中运行：
`OpenClaw Release Checks`
- `OpenClaw Release Checks` 还会在发布审批之前运行 QA Lab mock 一致性门禁，以及快速 live Matrix 配置和 Telegram QA 通道。live 通道使用 `qa-live-shared` 环境；Telegram 还会使用 Convex CI 凭证租约。若你想并行运行完整的 Matrix 传输、媒体和 E2EE 清单，请使用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` workflow。
- 跨操作系统的安装和升级运行时验证属于公开的 `OpenClaw Release Checks` 和 `Full Release Validation`，它们会直接调用可复用 workflow
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意为之：保持真实 npm 发布路径简短、确定性强，并聚焦于制品；而较慢的 live 检查则保留在独立通道中，这样它们就不会拖慢或阻塞发布
- 含有秘密信息的发布检查应通过 `Full Release Validation` 分发，或从 `main`/release workflow ref 分发，以确保 workflow 逻辑和 secrets 受到控制
- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析后的提交可从某个 OpenClaw 分支或发布标签到达
- `OpenClaw NPM Release` 的仅验证预检也接受当前完整的 40 字符 workflow 分支提交 SHA，而不要求已有已推送的标签
- `OpenClaw Release Checks` 也会在发布审批前运行 QA Lab mock parity 门禁，以及快速 live Matrix 配置和 Telegram QA 通道。live 通道使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。当你希望并行运行完整的 Matrix 传输、媒体和 E2EE 清单时，请运行手动 `QA-Lab - All Lanes` 工作流，并设置 `matrix_profile=all` 和 `matrix_shards=true`。
- 跨操作系统的安装和升级运行时验证属于公开的 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意为之：让真正的 npm 发布路径保持简短、确定性强并聚焦产物，而较慢的 live 检查留在它们自己的通道中，这样就不会拖慢或阻塞发布
- 含有密钥的发布检查应通过 `Full Release Validation` 派发，或者从 `main`/发布工作流引用派发，以便工作流逻辑和密钥保持受控
- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析出的提交可从某个 OpenClaw 分支或发布标签到达即可
- `OpenClaw NPM Release` 的仅验证预检也接受当前工作流分支的完整 40 位提交 SHA，而不要求已有推送的标签
- 该 SHA 路径仅用于验证，不能提升为真实发布
- 在 SHA 模式下，workflow 仅为软件包元数据检查合成 `v<package.json version>`；真实发布仍然需要真实的发布标签
- 两个 workflow 都会将真实发布和提升路径保留在 GitHub-hosted runners 上，而非变更性的验证路径则可使用更大的 Blacksmith Linux runners
- 该 workflow 会运行
- 在 SHA 模式下，工作流仅为软件包元数据检查合成 `v<package.json version>`；真实发布仍然需要真实的发布标签
- 两个工作流都会将真正的发布和提升路径保留在 GitHub 托管 runner 上，而非变更性的验证路径可以使用更大的 Blacksmith Linux runner
- 该工作流会使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流密钥运行
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
并使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 两个 workflow secrets
- npm 发布预检不再等待单独的发布检查通道
- 在审批前运行
`RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
（或匹配的 beta/修正版标签）
（或对应的 beta/修正标签）
- npm 发布后，运行
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
（或匹配的 beta/修正版版本），以在全新的临时前缀中验证已发布注册表安装路径
（或对应的 beta/修正版本），以在新的临时前缀中验证已发布的 registry 安装路径
- beta 发布后，运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
来验证基于已发布 npm 软件包的已安装软件包新手引导、Telegram 设置以及真实 Telegram E2E，使用共享的租赁 Telegram 凭证池。本地维护者的一次性运行可以省略 Convex 变量，直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。
- 维护者也可以通过 GitHub Actions 中的手动 `NPM Telegram Beta E2E` workflow 运行相同的发布后检查。它有意仅支持手动运行，不会在每次合并时执行。
- 维护者发布自动化现在采用先预检再提升：
以验证针对已发布 npm 软件包的已安装软件包新手引导、Telegram 设置和真实 Telegram E2E，并使用共享租赁的 Telegram 凭证池。本地维护者的一次性运行可省略 Convex 变量，直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。
- 维护者也可以通过 GitHub Actions 中的手动 `NPM Telegram Beta E2E` 工作流运行相同的发布后检查。它被有意设为仅手动运行，不会在每次合并时执行。
- 维护者发布自动化现在使用“先预检再提升”：
- 真实 npm 发布必须通过成功的 npm `preflight_run_id`
- 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支分发
- 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支派发
- stable npm 发布默认指向 `beta`
- stable npm 发布可以通过 workflow 输入显式指定 `latest`
- 基于 token 的 npm dist-tag 变更现在位于
- stable npm 发布可以通过工作流输入显式指定 `latest`
- 基于 token 的 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/` 载荷，这样我们就不会再次发布一个空的浏览器仪表板
- 发布后验证还会检查已发布注册表安装在根 `dist/*` 布局下是否包含非空的内置插件运行时依赖。若发布产物缺失或内置插件依赖载荷为空，发布后验证器就会失败，且不能被提升到 `latest`。
- `pnpm test:install:smoke` 还会对候选更新 tarball 的 npm pack `unpackedSize` 预算进行强制检查，因此安装器 e2e 能在发布路径之前捕获意外的软件包膨胀
- 如果发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在审批前重新生成并审查来自 `.github/workflows/ci.yml` 的、由规划器拥有的 `checks-node-extensions` workflow 矩阵输出，以免发布说明描述了过时的 CI 布局
- stable macOS 发布就绪还包括更新器相关界面：
- GitHub release 最终必须包含已打包的 `.zip`、`.dmg` 和 `.dSYM.zip`
- 真实发布路径会提升已准备好的产物，而不是再次重新构建它们
- 对于像 `YYYY.M.D-N` 这样的 stable 修正发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，这样发布修正就不会悄悄让旧的全局安装仍停留在基础 stable 负载上
- npm 发布预检会以失败关闭，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 内容，这样我们就不会再次发布一个空的浏览器仪表盘
- 发布后验证还会检查已发布的 registry 安装是否在根级 `dist/*` 布局下包含非空的内置插件运行时依赖。若某个发布缺少这些依赖负载，或其内容为空，将无法通过发布后验证器，也不能被提升到 `latest`。
- `pnpm test:install:smoke` 还会对候选更新 tarball 强制执行 npm pack 的 `unpackedSize` 预算，因此安装器 e2e 能在发布路径之前捕获意外的打包膨胀
- 如果发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在审批前重新生成并审查来自 `.github/workflows/ci.yml` 的 planner 管理 `checks-node-extensions` 工作流矩阵输出，以免发布说明描述的是过时的 CI 布局
- stable macOS 发布就绪还包括更新器相关表面：
- GitHub release 最终必须包含打包好的 `.zip`、`.dmg` 和 `.dSYM.zip`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip
- 打包后的应用必须保持非调试 bundle id、非空 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建底线的 `CFBundleVersion`
- 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle build 基线的 `CFBundleVersion`
## 发布测试框
## 发布验证框
`Full Release Validation` 是操作员从一个入口点启动所有预发布测试的方式。从可信的 `main` workflow ref 运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入：
`Full Release Validation` 是运维人员通过单一入口点启动所有预发布测试的方式。从可信的 `main` 工作流引用运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入：
```bash
gh workflow run full-release-validation.yml \
--ref main \
-f ref=release/YYYY.M.D \
-f provider=openai \
-f mode=both
-f mode=both \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
该 workflow 会解析目标 ref，使用
`target_ref=<release-ref>` 分发手动 `CI`，分发 `OpenClaw Release Checks`，并在设置了
`npm_telegram_package_spec` 时可选择分发独立的发布后 Telegram E2E。随后，`OpenClaw Release Checks` 会进一步展开安装冒烟测试、跨操作系统发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 软件包 QA 的 Package Acceptance、QA Lab 一致性、live Matrix 和 live Telegram。只有当 `Full Release Validation` 摘要中 `normal_ci` 和 `release_checks` 均显示成功，且任何可选的 `npm_telegram` 子任务要么成功要么被有意跳过时，完整运行才可接受。
子 workflow 会从运行 `Full Release Validation` 的可信 ref 分发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签也是如此。没有单独的 Full Release Validation workflow-ref 输入；通过选择 workflow 运行 ref 来选择可信 harness。
该工作流会解析目标 ref，使用 `target_ref=<release-ref>` 派发手动 `CI`，派发 `OpenClaw Release Checks`，并且在设置了 `npm_telegram_package_spec` 时可选派发独立的发布后 Telegram E2E。随后，`OpenClaw Release Checks` 会展开安装冒烟测试、跨操作系统发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 软件包 QA 的 Package Acceptance、QA Lab parity、live Matrix 和 live Telegram。只有当 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功，并且任何可选的 `npm_telegram` 子任务要么成功、要么被有意跳过时，完整运行才算可接受。
子工作流会从运行 `Full Release Validation` 的可信 ref 派发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签也是如此。不存在单独的 Full Release Validation workflow-ref 输入；通过选择工作流运行 ref 来选择可信 harness。
根据发布阶段使用以下变体：
@ -176,37 +158,38 @@ gh workflow run full-release-validation.yml \
-f provider=openai \
-f mode=both
# 验证一个已推送的精确提交。
# 验证某个已推送的精确提交。
gh workflow run full-release-validation.yml \
--ref main \
-f ref=<40-char-sha> \
-f provider=openai \
-f mode=both
# 发布 beta 后，增加针对已发布软件包的 Telegram E2E。
# beta 发布后，增加针对已发布软件包的 Telegram E2E。
gh workflow run full-release-validation.yml \
--ref main \
-f ref=release/YYYY.M.D \
-f provider=openai \
-f mode=both \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N \
-f npm_telegram_package_spec=openclaw@YYYY.M.D-beta.N \
-f npm_telegram_provider_mode=mock-openai
```
不要在针对某个聚焦修复的首次重跑时使用完整总流程。如果某个测试框失败，请使用失败的子 workflow、作业、Docker 通道、软件包配置、模型提供商或 QA 通道作为下一次证明。只有当修复更改了共享发布编排，或使早先的全框证据失效时，才再次运行完整总流程。总流程的最终验证器会重新检查已记录的子 workflow 运行 id，因此在某个子 workflow 成功重跑后，只需重跑失败的 `Verify full validation` 父作业。
不要在聚焦修复之后，把完整总体验证作为第一次重跑。如果某个验证框失败，请使用失败的子工作流、任务、Docker 通道、软件包配置、模型提供商或 QA 通道来获取下一轮证明。只有当修复改变了共享发布编排，或者让先前的全框证据失效时，才再次运行完整总体验证。总体验证的最终校验器会重新检查已记录的子工作流运行 id，因此在某个子工作流成功重跑后，只需重新运行失败的 `Verify full validation` 父任务。
### Vitest
Vitest 测试框是手动 `CI` 子 workflow。手动 CI 会有意绕过 changed 范围限制，并对发布候选版本强制运行常规测试图：Linux Node 分片、bundled-plugin 分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟测试、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。
Vitest 验证框是手动 `CI` 子工作流。手动 CI 会有意绕过 changed 范围限制，并对发布候选强制执行常规测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟测试、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。
使用此测试框来回答“源码树是否通过了完整的常规测试套件？”这个问题。它不同于发布路径产品验证。需要保留的证据：
使用这个验证框来回答“源代码树是否通过了完整的常规测试套件？”它不同于发布路径的产品验证。需要保留的证据：
- 显示已分发 `CI` 运行 URL 的 `Full Release Validation` 摘要
- 在精确目标 SHA 上呈绿色的 `CI` 运行
- 在调查回归时，CI 作业中的失败或缓慢分片名称
- 当某次运行需要性能分析时，像 `.artifacts/vitest-shard-timings.json` 这样的 Vitest 计时产物
- 显示已派发 `CI` 运行 URL 的 `Full Release Validation` 摘要
- 在精确目标 SHA 上为绿色的 `CI` 运行
- 在调查回归问题时，CI 任务中的失败或缓慢分片名称
- 当某次运行需要性能分析时，保留诸如 `.artifacts/vitest-shard-timings.json` 这样的 Vitest 时序产物
只有当发布需要确定性的常规 CI，而不需要 Docker、QA Lab、live、跨操作系统或软件包测试框时，才直接运行手动 CI：
只有当发布需要确定性的常规 CI，但不需要 Docker、QA Lab、live、跨操作系统或 Package 验证框时，才直接运行手动 CI：
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -214,66 +197,58 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Docker 测试框位于 `OpenClaw Release Checks` 中，通过
`openclaw-live-and-e2e-checks-reusable.yml` 以及发布模式的
`install-smoke` workflow 提供。它会通过已打包的 Docker 环境来验证发布候选版本，而不仅仅是源码级测试。
Docker 验证框位于 `OpenClaw Release Checks` 中，通过 `openclaw-live-and-e2e-checks-reusable.yml` 以及发布模式的 `install-smoke` 工作流提供。它通过打包后的 Docker 环境来验证发布候选，而不仅仅是源码级测试。
发布 Docker 覆盖包括：
- 启用了较慢 Bun 全局安装冒烟测试的完整安装冒烟测试
- 启用了慢速 Bun 全局安装冒烟测试的完整安装冒烟测试
- 仓库 E2E 通道
- 发布路径 Docker 分块：`core`、`package-update-openai`、
`package-update-anthropic`、`package-update-core`、`plugins-runtime-core`、
`plugins-runtime-install-a`、`plugins-runtime-install-b` 和
`bundled-channels`
- 在请求时，于 `plugins-runtime-core` 分块中包含 OpenWebUI 覆盖
- 将 bundled-channel 依赖通道拆分到独立的 `bundled-channels` 分块中，
而不是串行的一体式 bundled-channel 通道
- 拆分后的 bundled plugin 安装/卸载通道
- 在需要时，于 `plugins-runtime-core` 分块内覆盖 OpenWebUI
- 将内置渠道依赖通道拆分到各自的 `bundled-channels` 分块中，
而不是使用串行的一体化内置渠道通道
- 将内置插件安装/卸载通道拆分为
`bundled-plugin-install-uninstall-0` 到
`bundled-plugin-install-uninstall-7`
- 当发布检查包含 live 套件时，live/E2E provider 套件和 Docker live 模型覆盖
- 当发布检查包含 live 测试套件时，提供商 live/E2E 测试套件和 Docker live 模型覆盖
重跑前先使用 Docker 产物。发布路径调度器会上传
`.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、`failures.json`、
阶段计时、调度器计划 JSON 和重跑命令。若要进行聚焦恢复，请在可复用的 live/E2E workflow 上使用
`docker_lanes=<lane[,lane]>`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含先前的
`package_artifact_run_id` 和已准备好的 Docker 镜像输入，因此失败的通道可以复用相同的 tarball 和 GHCR 镜像。
重跑前先使用 Docker 产物。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON 以及重跑命令。对于聚焦恢复，请在可复用的 live/E2E 工作流上使用 `docker_lanes=<lane[,lane]>`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含先前的 `package_artifact_run_id` 和已准备好的 Docker 镜像输入，因此失败的通道可以复用同一个 tarball 和 GHCR 镜像。
### QA Lab
QA Lab 测试框也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级别的发布门禁，与 Vitest 和 Docker 软件包机制分开。
QA Lab 验证框也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级别的发布门禁，与 Vitest 以及 Docker 软件包机制分离。
发布 QA Lab 覆盖包括：
- 使用 agentic parity pack，将 OpenAI 候选通道与 Opus 4.6 基线进行比较的 mock 一致性门禁
- 使用 agentic parity 包，将 OpenAI 候选通道与 Opus 4.6 基线进行比较的 mock parity 门禁
- 使用 `qa-live-shared` 环境的快速 live Matrix QA 配置
- 使用 Convex CI 凭证租约的 live Telegram QA 通道
- 当发布遥测需要显式本地证明时运行 `pnpm qa:otel:smoke`
- 当发布遥测需要明确的本地证明时，运行 `pnpm qa:otel:smoke`
使用这个测试框来回答“该发布在 QA 场景和 live 渠道流程中的行为是否正确？”批准发布时，请保留 parity、Matrix 和 Telegram 通道的产物 URL。完整的 Matrix 覆盖仍可作为手动分片 QA-Lab 运行来获得，而不是默认的发布关键通道。
使用这个验证框来回答“该发布在 QA 场景和 live 渠道流程中是否表现正确？”在批准发布时，保留 parity、Matrix 和 Telegram 通道的产物 URL。完整 Matrix 覆盖仍可通过手动分片的 QA-Lab 运行获得，而不是作为默认的发布关键通道。
### Package
Package 测试框是可安装产品门禁。它由
`Package Acceptance` 和解析器
`scripts/resolve-openclaw-package-candidate.mjs` 支持。该解析器会将候选版本标准化为供 Docker E2E 使用的 `package-under-test` tarball，验证软件包清单，记录软件包版本和 SHA-256，并将 workflow harness ref 与软件包源 ref 分离。
Package 验证框是可安装产品的门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 提供支持。该解析器会将候选统一规范为供 Docker E2E 使用的 `package-under-test` tarball，验证软件包清单，记录软件包版本和 SHA-256，并将工作流 harness ref 与软件包来源 ref 分开。
支持的候选来源：
- `source=npm`：`openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本
- `source=ref`：使用所选 `workflow_ref` harness 打包可信的 `package_ref` 分支、标签或完整提交 SHA
- `source=url`：下载带有必需 `package_sha256` 的 HTTPS `.tgz`
- `source=artifact`：复用由其他 GitHub Actions 运行上传的 `.tgz`
- `source=ref`：使用选定的 `workflow_ref` harness 打包可信的 `package_ref` 分支、标签或完整提交 SHA
- `source=url`：下载带必填 `package_sha256` 的 HTTPS `.tgz`
- `source=artifact`：复用由另一条 GitHub Actions 运行上传的 `.tgz`
`OpenClaw Release Checks` 会以 `source=ref`、
`package_ref=<release-ref>`、`suite_profile=custom`、
`docker_lanes=bundled-channel-deps-compat plugins-offline` 和
`telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker 分块覆盖了其中重叠的安装、更新和插件更新通道；Package Acceptance 则保留了原生制品的 bundled-channel 兼容性、离线插件夹具，以及针对同一个已解析 tarball 的 Telegram 软件包 QA。它是 GitHub 原生方案，用来替代此前大多数依赖 Parallels 的软件包/更新覆盖。跨操作系统发布检查对特定操作系统的新手引导、安装器和平台行为仍然重要，但软件包/更新产品验证应优先使用 Package Acceptance。
`telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker 分块会覆盖重叠的安装、更新和插件更新通道；Package Acceptance 则会针对同一个已解析 tarball，保留原生产物的内置渠道兼容性、离线插件夹具以及 Telegram 软件包 QA。它是 GitHub 原生方案，用于替代此前大多数需要 Parallels 的软件包/更新覆盖。跨操作系统发布检查对于特定操作系统的新手引导、安装器和平台行为仍然重要，但软件包/更新产品验证应优先使用 Package Acceptance。
旧版 package-acceptance 的宽松处理被有意限制了时效。直到 `2026.4.25` 的软件包，仍可对已发布到 npm 的元数据缺口使用兼容路径：tarball 中缺失的私有 QA inventory 条目、缺失的 `gateway install --wrapper`、tarball 派生 git 夹具中缺失的补丁文件、缺失的持久化 `update.channel`、旧版插件安装记录位置、缺失的 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。`2026.4.25` 之后的软件包必须满足现代软件包契约；同样的缺口会导致发布验证失败。
旧版 package-acceptance 宽容路径被刻意限制为有时限。直到 `2026.4.25` 的软件包可以使用兼容路径来处理已发布到 npm 的元数据缺口：tarball 中缺失的私有 QA 清单条目、缺失的 `gateway install --wrapper`、源自 tarball 的 git 夹具中缺失的补丁文件、缺失的持久化 `update.channel`、旧版插件安装记录位置、缺失的 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。`2026.4.25` 之后的软件包必须满足现代软件包契约；这些同样的缺口会导致发布验证失败。
当发布问题涉及实际可安装的软件包时，请使用更广泛的 Package Acceptance 配置：
当发布问题涉及真实可安装软件包时，请使用更广范围的 Package Acceptance 配置：
```bash
gh workflow run package-acceptance.yml \
@ -284,63 +259,59 @@ gh workflow run package-acceptance.yml \
-f suite_profile=product
```
常见软件包配置：
常见的软件包配置：
- `smoke`：快速软件包安装/渠道/智能体、Gateway 网关网络和配置热重载通道
- `package`：不含 live ClawHub 的安装/更新/插件软件包契约；这是发布检查默认值
- `product`：在 `package` 基础上增加 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI
- `full`：带 OpenWebUI 的 Docker 发布路径分块
- `package`：不包含 live ClawHub 的安装/更新/插件软件包契约；这是发布检查默认值
- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI Web 搜索和 OpenWebUI
- `full`：包含 OpenWebUI 的 Docker 发布路径分块
- `custom`：用于聚焦重跑的精确 `docker_lanes` 列表
若要获取软件包候选版本的 Telegram 证明，请在 Package Acceptance 上启用
`telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该 workflow 会将已解析的
`package-under-test` tarball 传入 Telegram 通道；独立的 Telegram workflow 仍然接受已发布的 npm 规格以进行发布后检查。
若要获取软件包候选的 Telegram 证明，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该工作流会将已解析的 `package-under-test` tarball 传入 Telegram 通道；独立的 Telegram 工作流仍然接受已发布的 npm 规格用于发布后检查。
## NPM workflow 输入
## NPM 工作流输入
`OpenClaw NPM Release` 接受以下由操作员控制的输入：
`OpenClaw NPM Release` 接受以下由运维人员控制的输入：
- `tag`：必需的发布标签，如 `v2026.4.2`、`v2026.4.2-1` 或
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前完整的 40 字符 workflow 分支提交 SHA，用于仅验证的预检
- `preflight_only`：`true` 表示仅验证/构建/打包，`false` 表示真实发布路径
- `preflight_run_id`：真实发布路径上必需，以便 workflow 复用成功预检运行中准备好的 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` 接受以下由操作员控制的输入：
`OpenClaw Release Checks` 接受以下由运维人员控制的输入：
- `ref`：要验证的分支、标签或完整提交 SHA。含 secrets 的检查要求解析后的提交可从某个 OpenClaw 分支或发布标签到达。
- `ref`：要验证的分支、标签或完整提交 SHA。含密钥的检查要求解析出的提交必须可从某个 OpenClaw 分支或发布标签到达。
规则：
- Stable 和修正版标签可以发布到 `beta` 或 `latest`
- Stable 和修正标签可以发布到 `beta` 或 `latest`
- Beta 预发布标签只能发布到 `beta`
- 对于 `OpenClaw NPM Release`，只有在 `preflight_only=true` 时才允许输入完整提交 SHA
- `OpenClaw Release Checks` 和 `Full Release Validation` 始终仅用于验证
- 真实发布路径必须使用与预检期间相同的 `npm_dist_tag`；workflow 会在继续发布前验证该元数据
- 真实发布路径必须使用与预检时相同的 `npm_dist_tag`；工作流会在继续发布前验证该元数据
## Stable npm 发布顺序
在切 stable npm 发布时：
1. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`
- 在标签尚不存在时，你可以使用当前完整 workflow 分支提交 SHA，对预检 workflow 进行仅验证的演练
2. 对于正常的 beta 优先流程，选择 `npm_dist_tag=beta`；只有在你有意直接发布 stable 时，才选择 `latest`
3. 当你希望从一个手动 workflow 获得常规 CI 加上 live prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖时，对发布分支、发布标签或完整提交 SHA 运行 `Full Release Validation`
4. 如果你有意只需要确定性的常规测试图，则改为在发布 ref 上运行手动 `CI` workflow
1. 以 `preflight_only=true` 运行 `OpenClaw NPM Release`
- 在标签尚不存在前，你可以使用当前工作流分支的完整提交 SHA，对预检工作流进行仅验证的 dry run
2. 在正常的 beta 优先流程中选择 `npm_dist_tag=beta`，只有在你明确想要直接发布 stable 时才选择 `latest`
3. 当你希望通过一个手动工作流获得常规 CI 加 live prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整提交 SHA 上运行 `Full Release Validation`
4. 如果你明确只需要确定性的常规测试图，则改为在发布 ref 上运行手动 `CI` 工作流
5. 保存成功的 `preflight_run_id`
6. 再次运行 `OpenClaw NPM Release`，设置 `preflight_only=false`，并使用相同的
`tag`、相同的 `npm_dist_tag` 和保存的 `preflight_run_id`
7. 如果发布落在 `beta` 上，使用私有
6. 再次运行 `OpenClaw NPM Release`，设置 `preflight_only=false`，并使用相同的 `tag`、相同的 `npm_dist_tag` 以及保存的 `preflight_run_id`
7. 如果发布落在 `beta` 上，请使用私有的
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
workflow 将该 stable 版本从 `beta` 提升到 `latest`
8. 如果该发布有意直接发布到 `latest`，并且 `beta` 应立即跟随同一个 stable 构建，则使用同一个私有 workflow 将两个 dist-tag 都指向该 stable 版本，或者让其计划的自愈同步稍后再移动 `beta`
工作流，将该 stable 版本从 `beta` 提升到 `latest`
8. 如果该发布是有意直接发布到 `latest`，并且 `beta` 应立即跟随同一个 stable 构建，请使用同一个私有工作流将两个 dist-tag 都指向该 stable 版本，或者让其定时自愈同步稍后再更新 `beta`
dist-tag 变更位于私有仓库中以保证安全，因为它仍需要
`NPM_TOKEN`，而公开仓库保持仅使用 OIDC 的发布方式。
dist-tag 修改位于私有仓库中以确保安全，因为它仍然需要 `NPM_TOKEN`，而公开仓库保持仅使用 OIDC 发布。
这使得直接发布路径和 beta 优先提升路径都得到了文档记录，并且对操作员可见。
这样既记录了直接发布路径，也记录了 beta 优先提升路径，并且两者都对运维人员可见。
如果维护者必须回退到本地 npm 身份验证，请仅在专用 tmux 会话中运行任何 1Password CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；将其限制在 tmux 内可以让提示、警报和 OTP 处理保持可观察，并防止重复的主机警报。
如果维护者必须退回到本地 npm 身份验证，只能在专用 tmux 会话中运行任何 1Password CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；将其限制在 tmux 中可以让提示、警报和 OTP 处理保持可观察，并防止重复的主机警报。
## 公开参考

244
docs/zh-CN/tools/slash-commands.md
View File

@ -3,20 +3,20 @@ read_when:
- 使用或配置聊天命令
- 调试命令路由或权限
sidebarTitle: Slash commands
summary: 斜杠命令：文本与原生、配置和支持的命令
summary: 斜杠命令：文本与原生、配置以及支持的命令
title: 斜杠命令
x-i18n:
generated_at: "2026-04-26T08:13:44Z"
generated_at: "2026-04-27T21:04:56Z"
model: gpt-5.4
provider: openai
source_hash: 75bf58d02738e30bfdc00ad1c264b2f066eebd2819f4ea0209f504f279755993
source_hash: ce0d9d28e74cd81d0484990dab6a4c83ea03a84d267f78f0488c53552ddcba38
source_path: tools/slash-commands.md
workflow: 15
---
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是它的别名）。
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是别名）。
当某个对话或线程绑定到 ACP 会话时，普通的后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 总是会到达 OpenClaw ACP 命令处理器，而 `/status` 和 `/unfocus` 只要该界面启用了命令处理，就会保持本地处理。
当某个对话或线程绑定到 ACP 会话时，普通的后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终会到达 OpenClaw ACP 命令处理器，而 `/status` 和 `/unfocus` 只要该界面启用了命令处理，就始终保持本地处理。
这里有两个相关系统：
@ -28,15 +28,15 @@ x-i18n:
`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
- 指令会在模型看到消息之前从消息中剥离。
- 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“行内提示”，并且**不会**持久化会话设置。
- 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话，并回复一个确认消息。
- 指令只会对**已授权的发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则，授权来源于渠道允许列表/配对加上 `commands.useAccessGroups`。未授权的发送者会看到这些指令被当作普通文本处理。
- 在普通聊天消息中（非纯指令消息），它们会被视为“内联提示”，并且**不会**持久化为会话设置。
- 在纯指令消息中（消息只包含指令），它们会持久化到会话中，并回复确认信息。
- 指令只会对**已授权的发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权的发送者看到的指令会被当作普通文本处理。
</Accordion>
<Accordion title="行内快捷命令">
仅限已列入允许列表/已授权的发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
<Accordion title="内联快捷方式">
仅限允许列表中的 / 已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它们会立即运行，并在模型看到消息之前被剥离，剩余文本会继续按正常流程处理。
它们会立即运行，在模型看到消息之前被剥离，剩余文本继续走正常流程。
</Accordion>
</AccordionGroup>
@ -69,28 +69,28 @@ x-i18n:
```
<ParamField path="commands.text" type="boolean" default="true">
启用在聊天消息中解析 `/...`。在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将此项设置为 `false`，文本命令仍然可用。
启用在聊天消息中解析 `/...`。在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。
</ParamField>
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生能力的提供商会忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除之前已在 Discord/Telegram 上注册的命令。Slack 命令由 Slack 应用管理，不会自动移除。
注册原生命令。Auto：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生命令的提供商忽略。可设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 按提供商覆盖（布尔值或 `"auto"`）。在 Discord/Telegram 上设为 `false` 会在启动时清除先前已注册的命令。Slack 命令在 Slack 应用中管理，不会被自动移除。
</ParamField>
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
在支持时以原生方式注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
在支持时以原生方式注册 **skill** 命令。Auto：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 单独创建一个斜杠命令）。可设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 按提供商覆盖（布尔值或 `"auto"`）。
</ParamField>
<ParamField path="commands.bash" type="boolean" default="false">
启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
</ParamField>
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
控制 bash 在切换到后台模式之前等待多长时间（`0` 表示立即转入后台）。
控制 bash 在切换到后台模式前等待多长时间（`0` 表示立即转入后台）。
</ParamField>
<ParamField path="commands.config" type="boolean" default="false">
启用 `/config`（读取/写入 `openclaw.json`）。
启用 `/config`（读取 / 写入 `openclaw.json`）。
</ParamField>
<ParamField path="commands.mcp" type="boolean" default="false">
启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
启用 `/mcp`（读取 / 写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
</ParamField>
<ParamField path="commands.plugins" type="boolean" default="false">
启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。
启用 `/plugins`（插件发现 / 状态，以及安装 + 启用 / 禁用控制）。
</ParamField>
<ParamField path="commands.debug" type="boolean" default="false">
启用 `/debug`（仅运行时覆盖）。
@ -99,47 +99,47 @@ x-i18n:
启用 `/restart` 以及 Gateway 网关重启工具操作。
</ParamField>
<ParamField path="commands.ownerAllowFrom" type="string[]">
为仅限所有者的命令/工具界面设置显式的所有者允许列表。它独立于 `commands.allowFrom`。
为仅限所有者的命令 / 工具界面设置显式所有者允许列表。独立于 `commands.allowFrom`。
</ParamField>
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
按渠道设置：使该界面上的仅限所有者命令必须由**所有者身份**来运行。当为 `true` 时，发送者必须匹配一个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目，或提供商原生的所有者元数据），或者在内部消息渠道上拥有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或者空的/未解析的所有者候选列表，**都不足以**满足条件——该渠道上的仅限所有者命令会以关闭方式失败。如果你希望仅限所有者命令只由 `ownerAllowFrom` 和标准命令允许列表来限制，请保持此项关闭。
按渠道设置：使该界面上的仅限所有者命令必须要求**所有者身份**才能运行。当为 `true` 时，发送者必须与已解析的所有者候选匹配（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上拥有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的 / 无法解析的所有者候选列表，**都不足以**满足要求——仅限所有者命令会在该渠道上默认拒绝。若你希望仅限所有者命令只由 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。
</ParamField>
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
控制所有者 id 在系统提示中的显示方式。
</ParamField>
<ParamField path="commands.ownerDisplaySecret" type="string">
可选设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
</ParamField>
<ParamField path="commands.allowFrom" type="object">
用于命令授权的按提供商划分的允许列表。配置后，它就是命令和指令唯一的授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。
用于命令授权的按提供商划分的允许列表。配置后，它将成为命令和指令唯一的授权来源（渠道允许列表 / 配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 表示全局默认；提供商专用键会覆盖它。
</ParamField>
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
当未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。
当未设置 `commands.allowFrom` 时，对命令强制执行允许列表 / 策略。
</ParamField>
## 命令列表
当前事实来源：
当前权威来源：
- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts`
- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
- 插件命令来自插件 `registerCommand()` 调用
- 你的 Gateway 网关上实际可用的命令仍然取决于配置标志、渠道界面，以及已安装/已启用的插件
- 插件命令来自插件的 `registerCommand()` 调用
- 你的 Gateway 网关上实际是否可用仍取决于配置标志、渠道界面以及已安装 / 已启用的插件
### 核心内置命令
<AccordionGroup>
<Accordion title="会话和运行">
<Accordion title="会话与运行">
- `/new [model]` 启动一个新会话；`/reset` 是重置别名。
- `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并在原地重新运行启动/系统提示加载。
- `/compact [instructions]` 压缩会话上下文。参见 [压缩](/zh-CN/concepts/compaction)。
- `/reset soft [message]` 保留当前对话记录，丢弃复用的 CLI 后端会话 id，并在原位重新运行启动 / 系统提示加载。
- `/compact [instructions]` 压缩会话上下文。参见 [Compaction](/zh-CN/concepts/compaction)。
- `/stop` 中止当前运行。
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
- `/export-trajectory [path]` 为当前会话导出一个 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。别名：`/trajectory`。
</Accordion>
<Accordion title="模型和运行控制">
- `/think <level>` 设置思考级别。可选项来自当前模型的提供商配置文件；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也支持诸如 `xhigh`、`adaptive`、`max` 或仅在支持时提供的二元 `on` 等自定义级别。别名：`/thinking`、`/t`。
<Accordion title="模型与运行控制">
- `/think <level>` 设置思考级别。可选项来自当前模型的提供商配置文件；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也包括仅在支持时提供的自定义级别，例如 `xhigh`、`adaptive`、`max`，或二元的 `on`。别名：`/thinking`、`/t`。
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
- `/trace on|off` 为当前会话切换插件跟踪输出。
- `/fast [status|on|off]` 显示或设置快速模式。
@ -147,16 +147,16 @@ x-i18n:
- `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
- `/model [name|#|status]` 显示或设置模型。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商，或列出某个提供商的模型。
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及类似 `debounce:2s cap:25 drop:summarize` 的选项。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商，或列出某提供商的模型。
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及像 `debounce:2s cap:25 drop:summarize` 这样的选项。
</Accordion>
<Accordion title="发现和状态">
<Accordion title="发现与状态">
- `/help` 显示简短帮助摘要。
- `/commands` 显示生成的命令目录。
- `/tools [compact|verbose]` 显示当前智能体现在可使用的内容。
- `/status` 显示执行/运行时状态，包括 `Execution`/`Runtime` 标签，以及可用时的提供商使用量/配额。
- `/tools [compact|verbose]` 显示当前智能体此刻可用的内容。
- `/status` 显示执行 / 运行时状态，包括 `Execution` / `Runtime` 标签，以及可用时的提供商使用情况 / 配额。
- `/crestodian <request>` 从所有者私信中运行 Crestodian 设置和修复助手。
- `/tasks` 列出当前会话中活动的/最近的后台任务。
- `/tasks` 列出当前会话的活动 / 最近后台任务。
- `/context [list|detail|json]` 解释上下文是如何组装的。
- `/whoami` 显示你的发送者 id。别名：`/id`。
- `/usage off|tokens|full|cost` 控制每次响应的用量页脚，或打印本地成本摘要。
@ -165,29 +165,29 @@ x-i18n:
- `/skill <name> [input]` 按名称运行一个 skill。
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
- `/approve <id> <decision>` 处理 exec 审批提示。
- `/btw <question>` 提出一个侧边问题，而不改变后续会话上下文。参见 [BTW](/zh-CN/tools/btw)。
- `/btw <question>` 提出一个侧边问题，而不改变未来的会话上下文。参见 [BTW](/zh-CN/tools/btw)。
</Accordion>
<Accordion title="子智能体和 ACP">
<Accordion title="子智能体与 ACP">
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题/对话绑定到一个会话目标。
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题 / 对话绑定到某个会话目标。
- `/unfocus` 移除当前绑定。
- `/agents` 列出当前会话中线程绑定的智能体。
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
- `/steer <id|#> <message>` 向正在运行的子智能体发送引导。别名：`/tell`。
</Accordion>
<Accordion title="仅限所有者的写操作和管理">
<Accordion title="仅限所有者的写操作与管理">
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写操作仅限所有者。需要 `commands.plugins: true`。
- `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。
- `/debug show|set|unset|reset` 管理仅运行时配置覆盖。仅限所有者。需要 `commands.debug: true`。
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用。
- `/send on|off|inherit` 设置发送策略。仅限所有者。
</Accordion>
<Accordion title="语音、TTS、渠道控制">
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。
- `/activation mention|always` 设置群组激活模式。
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 加上 `tools.elevated` 允许列表。
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
- `!poll [sessionId]` 检查后台 bash 作业。
- `!stop [sessionId]` 停止后台 bash 作业。
</Accordion>
@ -202,17 +202,19 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
- `/dock-slack`（别名：`/dock_slack`）
- `/dock-telegram`（别名：`/dock_telegram`）
在私聊中使用 dock 命令，可将当前会话的回复路由切换到另一个已链接渠道。源发送者和目标对端必须位于同一个 `session.identityLinks` 分组中，例如 `["telegram:123", "discord:456"]`。
### 内置插件命令
内置插件可以添加更多斜杠命令。此仓库中当前内置的命令有：
内置插件可以添加更多斜杠命令。本仓库当前内置的命令有：
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [配对](/zh-CN/channels/pairing)。
- `/dreaming [on|off|status|help]` 切换 memory dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对 / 设置流程。参见 [Pairing](/zh-CN/channels/pairing)。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置的 Codex app-server harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。
- 仅 QQBot 命令：
- 仅 QQ Bot 命令：
- `/bot-ping`
- `/bot-version`
- `/bot-help`
@ -221,81 +223,81 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
### 动态 skill 命令
可由用户调用的 Skills 也会暴露为斜杠命令：
用户可调用的 Skills 也会作为斜杠命令暴露：
- `/skill <name> [input]` 始终可作为通用入口点使用。
- 当 skill/插件注册它们时，skills 也可能显示为像 `/prose` 这样的直接命令。
- 当 skill / 插件注册了直接命令时，它们也可能显示为像 `/prose` 这样的直接命令。
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
<AccordionGroup>
<Accordion title="参数和解析器说明">
- 命令接受命令与参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。
- 如需完整的提供商使用量明细，请使用 `openclaw status --usage`。
<Accordion title="参数与解析器说明">
- 命令与参数之间可选使用 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，则文本会被当作消息正文处理。
- 如需查看完整的提供商使用情况细分，请使用 `openclaw status --usage`。
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
- 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
- `/usage` 控制每次响应的用量页脚；`/usage cost` 会根据 OpenClaw 会话日志打印本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规范：本地路径/归档、npm 包或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新插件配置，并可能提示你重启。
- `/usage` 控制每次响应的用量页脚；`/usage cost` 会从 OpenClaw 会话日志中输出本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径 / 压缩包、npm 包，或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新插件配置，并且可能提示重启。
</Accordion>
<Accordion title="渠道特定行为">
- 仅 Discord 原生命令：`/vc join|leave|status` 控制语音频道（不提供文本形式）。`join` 需要 guild 和所选语音/舞台频道。需要 `channels.discord.voice` 和原生命令。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求实际线程绑定已启用（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- ACP 命令参考和运行时行为：参见 [ACP 智能体](/zh-CN/tools/acp-agents)。
- 仅 Discord 原生命令：`/vc join|leave|status` 控制语音频道（不提供文本形式）。`join` 需要 guild 和已选择的语音 / stage 频道。需要 `channels.discord.voice` 和原生命令。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求有效启用线程绑定（`session.threadBindings.enabled` 和 / 或 `channels.discord.threadBindings.enabled`）。
- ACP 命令参考和运行时行为：参见 [ACP agents](/zh-CN/tools/acp-agents)。
</Accordion>
<Accordion title="verbose / trace / fast / reasoning 安全性">
- `/verbose` 用于调试和提供更多可见性；正常使用时请保持**关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具输出关闭。
- `/fast on|off` 会持久化一个会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除它并回退到配置默认值。
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将它映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公共 Anthropic 请求（包括经 OAuth 认证的流量）则会将它映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 当相关时，仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能暴露你无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
- `/verbose` 用于调试和额外可见性；正常使用时请保持**关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace / debug 行，并保持普通 verbose 工具输出关闭。
- `/fast on|off` 会持久化一个会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除该设置，并回退到配置默认值。
- `/fast` 与提供商相关：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括经 OAuth 验证的流量）会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 相关时仍会显示工具失败摘要，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时才包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能暴露你本不打算公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
</Accordion>
<Accordion title="模型切换">
- `/model` 会立即持久化新的会话模型。
- 如果智能体处于空闲状态，下一次运行会立即使用它。
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续的重试机会或下一次用户轮次。
- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这与消息渠道救援模式分离，并且不会授予远程配置权限。
- 如果智能体处于空闲状态，下次运行会立即使用它。
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在一个干净的重试点重启进入新模型。
- 如果工具活动或回复输出已经开始，则待处理切换可能会一直排队到稍后的重试机会，或下一个用户轮次。
- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这与消息渠道救援模式分离，也不会授予远程配置权限。
</Accordion>
<Accordion title="快速路径和行内快捷命令">
<Accordion title="快速路径与内联快捷方式">
- **快速路径：** 来自允许列表发送者的纯命令消息会被立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。
- **行内快捷命令（仅限允许列表发送者）：** 某些命令即使嵌入在普通消息中也能生效，并会在模型看到其余内容之前被剥离。
- 示例：`hey /status` 会触发状态回复，剩余文本会继续按正常流程处理。
- **内联快捷方式（仅允许列表发送者）：** 某些命令在嵌入普通消息时也可使用，并会在模型看到剩余文本前被剥离。
- 示例：`hey /status` 会触发状态回复，而剩余文本会继续走正常流程。
- 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
- 未授权的纯命令消息会被静默忽略，而行内 `/...` 标记会被当作普通文本处理。
- 未授权的纯命令消息会被静默忽略，而内联 `/...` 标记会被当作普通文本处理。
</Accordion>
<Accordion title="skill 命令和原生参数">
- **skill 命令：** `user-invocable` skills 会暴露为斜杠命令。名称会被规范化为 `a-z0-9_`（最多 32 个字符）；冲突时会加数字后缀（例如 `_2`）。
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止为每个 skill 创建命令时很有用）。
<Accordion title="Skill 命令与原生参数">
- **Skill 命令：** `user-invocable` Skills 会作为斜杠命令暴露。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；发生冲突时会追加数字后缀（例如 `_2`）。
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 单独生成命令时很有用）。
- 默认情况下，skill 命令会作为普通请求转发给模型。
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型参与）。
- Skills 也可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性执行，无需模型）。
- 示例：`/prose`（OpenProse 插件）——参见 [OpenProse](/zh-CN/prose)。
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时也会显示按钮菜单）。当命令支持选项而你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会根据目标会话模型解析，因此像 `/think` 级别这样的模型特定选项会遵循该会话的 `/model` 覆盖设置。
- **原生命令参数：** Discord 对动态选项使用自动补全（而当你省略必填参数时则使用按钮菜单）。Telegram 和 Slack 在某个命令支持选项且你省略参数时，会显示按钮菜单。动态选项是根据目标会话模型解析的，因此像 `/think` 级别这样的模型特定选项会遵循该会话的 `/model` 覆盖。
</Accordion>
</AccordionGroup>
## `/tools`
`/tools` 回答的是一个运行时问题，而不是一个配置问题：**这个智能体现在在这个对话中可以使用什么**。
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体此刻在这个对话中可以使用什么**。
- 默认的 `/tools` 是紧凑模式，针对快速浏览进行了优化。
- `/tools verbose` 会添加简短说明。
- 支持参数的原生命令界面会暴露相同的模式切换，即 `compact|verbose`。
- 默认的 `/tools` 为紧凑模式，适合快速浏览。
- `/tools verbose` 会添加简短描述。
- 支持带参数的原生命令界面也会暴露相同的模式切换，即 `compact|verbose`。
- 结果是会话范围的，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
- `/tools` 包含运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。
- `/tools` 包括运行时实际可达的工具，包括核心工具、已连接的插件工具以及渠道拥有的工具。
对于配置文件和覆盖编辑，请使用 Control UI Tools 面板或配置/目录界面，而不要把 `/tools` 当成静态目录。
对于配置文件和覆盖编辑，请使用控制 UI 的 Tools 面板或配置 / 目录界面，而不要把 `/tools` 当作静态目录。
## 使用量界面（哪些内容显示在哪里）
## 使用情况界面（各处显示什么）
- **提供商使用量/配额**（例如：“Claude 剩余 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一标准化为“剩余百分比”；对于 MiniMax，只有剩余值的百分比字段会在显示前取反，而 `model_remains` 响应会优先选择 chat-model 条目并附带带模型标签的 plan 标签。
- `/status` 中的 **Token/cache 行** 可以在实时会话快照信息稀疏时回退到最新的转录使用量条目。现有的非零实时值仍然优先，而转录回退也可以在存储总量缺失或更小时恢复当前活动运行时模型标签以及更偏向 prompt 的总量。
- **Execution 与 runtime：** `/status` 会将有效沙箱路径报告为 `Execution`，并将实际运行该会话的对象报告为 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、某个 CLI 后端或某个 ACP 后端。
- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到普通回复之后）。
- `/model status` 关注的是**模型/认证/端点**，而不是使用量。
- **提供商使用情况 / 配额**（例如：“Claude 剩余 80%”）会在启用使用情况跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商时间窗口统一为“剩余百分比”；对于 MiniMax，仅含剩余值的百分比字段会在显示前取反，而 `model_remains` 响应会优先使用聊天模型条目以及带模型标签的套餐标签。
- 当实时会话快照较稀疏时，`/status` 中的**token / cache 行**可以回退到最新对话记录中的 usage 条目。现有的非零实时值仍然优先，而对话记录回退还可以在存储总量缺失或更小时，恢复当前运行时模型标签以及更偏向 prompt 的总量。
- **Execution 与 Runtime：** `/status` 会对生效的沙箱路径显示 `Execution`，并对实际运行会话的一方显示 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、某个 CLI 后端，或 ACP 后端。
- **每次响应的 token / 成本** 由 `/usage off|tokens|full` 控制（附加到普通回复后）。
- `/model status` 关注的是**模型 / 认证 / 端点**，而不是使用情况。
## 模型选择（`/model`）
@ -315,13 +317,13 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
说明：
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，包含提供商和模型下拉框以及一个 Submit 步骤。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，包含提供商和模型下拉菜单以及提交步骤。
- `/model <#>` 会从该选择器中进行选择（并在可能时优先使用当前提供商）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`）（如果可用）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）以及可用时的 API 模式（`api`）。
## Debug 覆盖
`/debug` 允许你设置**仅运行时**的配置覆盖（存储在内存中，不写入磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。
`/debug` 允许你设置**仅运行时**的配置覆盖（存于内存，不写入磁盘）。仅限所有者。默认禁用；通过 `commands.debug: true` 启用。
示例：
@ -334,12 +336,12 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
```
<Note>
覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 可清除所有覆盖并恢复到磁盘上的配置。
覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 可清除所有覆盖并恢复为磁盘上的配置。
</Note>
## 插件 trace 输出
`/trace` 允许你切换**会话范围的插件 trace/debug 行**，而无需开启完整的 verbose 模式。
`/trace` 让你在不启用完整 verbose 模式的情况下，切换**会话范围的插件 trace / debug 行**。
示例：
@ -353,14 +355,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
- 不带参数的 `/trace` 会显示当前会话的 trace 状态。
- `/trace on` 会为当前会话启用插件 trace 行。
- `/trace off` 会再次禁用它们。
- 插件 trace 行可能会显示在 `/status` 中，也可能作为普通助手回复之后的后续诊断消息出现。
- `/trace` 不能替代 `/debug`；`/debug` 仍然用于管理仅运行时的配置覆盖。
- `/trace` 不能替代 `/verbose`；普通的 verbose 工具/状态输出仍属于 `/verbose`。
- `/trace off` 会再次将其禁用。
- 插件 trace 行可能会出现在 `/status` 中，也可能作为普通助手回复后的后续诊断消息出现。
- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时配置覆盖。
- `/trace` 也不能替代 `/verbose`；普通 verbose 工具 / 状态输出仍属于 `/verbose`。
## 配置更新
`/config` 会写入你磁盘上的配置（`openclaw.json`）。仅限所有者。默认禁用；使用 `commands.config: true` 启用。
`/config` 会写入你磁盘上的配置（`openclaw.json`）。仅限所有者。默认禁用；通过 `commands.config: true` 启用。
示例：
@ -373,12 +375,12 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
```
<Note>
配置会在写入前进行验证；无效更改会被拒绝。`/config` 更新会在重启后保留。
写入前会验证配置；无效更改会被拒绝。`/config` 更新会在重启后保留。
</Note>
## MCP 更新
`/mcp` 会将由 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers` 下。仅限所有者。默认禁用；使用 `commands.mcp: true` 启用。
`/mcp` 会将由 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers`。仅限所有者。默认禁用；通过 `commands.mcp: true` 启用。
示例：
@ -390,12 +392,12 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
```
<Note>
`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输方式实际上可执行。
`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输实际上可执行。
</Note>
## 插件更新
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；通过 `commands.plugins: true` 启用。
示例：
@ -408,9 +410,9 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
```
<Note>
- `/plugins list` 和 `/plugins show` 会根据当前工作区和磁盘上的配置执行真实的插件发现。
- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。
- 启用/禁用更改后，重启 Gateway 网关以应用它们。
- `/plugins list` 和 `/plugins show` 会基于当前工作区以及磁盘上的配置执行真实的插件发现。
- `/plugins enable|disable` 只更新插件配置；不会安装或卸载插件。
- 在启用 / 禁用更改后，请重启 Gateway 网关以应用它们。
</Note>
## 界面说明
@ -418,16 +420,16 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
<AccordionGroup>
<Accordion title="每个界面的会话">
- **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有各自独立的会话）。
- **原生命令** 使用隔离会话：
- **原生命令** 使用隔离的会话：
- Discord：`agent:<agentId>:discord:slash:<userId>`
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位到聊天会话）
- **`/stop`** 以当前活动聊天会话为目标，因此它可以中止当前运行。
- **`/stop`** 以活动聊天会话为目标，因此可以中止当前运行。
</Accordion>
<Accordion title="Slack 细节">
`channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格的命令。如果你启用了 `commands.native`，则必须为每个内置命令在 Slack 中创建一个斜杠命令（名称与 `/help` 等相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮的形式发送。
<Accordion title="Slack 特性">
`channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 中显示的相同）。Slack 的命令参数菜单以临时性的 Block Kit 按钮形式提供。
Slack 原生命令例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
Slack 原生命令例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本形式的 `/status` 在 Slack 消息中仍然可用。
</Accordion>
</AccordionGroup>
@ -439,23 +441,23 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
与普通聊天不同：
- 它使用当前会话作为背景上下文，
- 它会作为一个独立的**无工具**一次性调用运行，
- 它不会改变后续会话上下文，
- 它不会写入转录历史，
- 它会以实时侧边结果的形式传递，而不是作为普通助手消息。
- 它作为一次独立的**无工具**单次调用运行，
- 它不会改变未来的会话上下文，
- 它不会写入对话记录历史，
- 它会作为实时侧边结果交付，而不是普通助手消息。
这使得 `/btw` 在你希望获取临时澄清、同时主任务继续进行时非常有用。
这使得 `/btw` 在你希望获得临时说明、同时主任务继续进行时非常有用。
示例：
```text
/btw what are we doing right now?
/btw 我们现在正在做什么？
```
完整行为和客户端 UX 细节请参见 [BTW 侧边问题](/zh-CN/tools/btw)。
完整行为和客户端 UX 细节，请参见 [BTW Side Questions](/zh-CN/tools/btw)。
## 相关内容
- [创建 Skills](/zh-CN/tools/creating-skills)
- [Creating skills](/zh-CN/tools/creating-skills)
- [Skills](/zh-CN/tools/skills)
- [Skills 配置](/zh-CN/tools/skills-config)