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 17:33:47 +00:00
parent e50137dbe9
commit 39fb319454
2 changed files with 591 additions and 586 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

694
docs/zh-CN/plugins/sdk-overview.md
View File

@ -2,68 +2,63 @@
read_when:
- 你需要知道应从哪个 SDK 子路径导入
- 你想查看 OpenClawPluginApi 上所有注册方法的参考文档
- 你正在查找某个特定的 SDK 导出内容
sidebarTitle: SDK Overview
- 你正在查找某个特定的 SDK 导出项
sidebarTitle: SDK overview
summary: Import map、注册 API 参考和 SDK 架构
title: 插件 SDK 概览
x-i18n:
generated_at: "2026-04-23T03:31:38Z"
generated_at: "2026-04-23T17:31:44Z"
model: gpt-5.4
provider: openai
source_hash: 5f9608fa3194b1b1609d16d7e2077ea58de097e9e8d4cedef4cb975adfb92938
source_hash: 8635973d4c4081675ef104b9079667882ff1c6f8f7f73bcd1516222259bc1569
source_path: plugins/sdk-overview.md
workflow: 15
---
# 插件 SDK 概览
插件 SDK 是插件与核心之间的类型化契约。本页面是关于**导入什么**以及**你可以注册什么**的参考文档。
插件 SDK 是 plugins 与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考文档。
<Tip>
**在找操作指南？**
- 第一个插件？从[入门指南](/zh-CN/plugins/building-plugins)开始
- 渠道插件？参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins)
- 提供商插件？参见[提供商插件](/zh-CN/plugins/sdk-provider-plugins)
</Tip>
在找操作指南而不是参考文档？
- 第一个 plugin？从 [构建 plugins](/zh-CN/plugins/building-plugins) 开始。
- 渠道插件？参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
- 提供商插件？参见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
</Tip>
## 导入约定
始终从特定子路径导入：
始终从特定的子路径导入：
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性接口和共享辅助函数，例如 `buildChannelConfigSchema`。
每个子路径都是一个小型、自包含模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总入口表面和共享辅助工具，例如 `buildChannelConfigSchema`。
不要添加或依赖带有提供商名称的便捷接口，例如
`openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、
`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或
带有渠道品牌的辅助接口。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用
SDK 子路径，而核心在确实存在跨渠道需求时，要么使用这些插件本地 barrel，要么添加一个精简的通用 SDK
契约。
<Warning>
不要导入带有 provider 或 channel 品牌的便捷接缝层（例如
`openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。
内置插件会在它们自己的 `api.ts` /
`runtime-api.ts` barrel 中组合通用 SDK 子路径；核心使用方应使用这些 plugin 本地
barrel，或者在需求确实跨渠道时添加一个窄范围的通用 SDK 契约。
生成的导出映射仍然包含一小组内置插件辅助接口，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、
`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些
子路径仅用于内置插件维护和兼容性；它们被有意省略在下面的常用表格之外，也不是新第三方插件的推荐导入路径。
少量内置插件辅助接缝层（`plugin-sdk/feishu`、
`plugin-sdk/zalo`、`plugin-sdk/matrix*` 等）仍会出现在生成的导出映射中。它们仅用于内置插件维护，不推荐作为新的第三方插件导入路径。
</Warning>
## 子路径参考
最常用的子路径，按用途分组。完整的 200+ 子路径生成列表位于
`scripts/lib/plugin-sdk-entrypoints.json`。
最常用的子路径，按用途分组。完整的 200+ 子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；保留给内置插件辅助工具的子路径也会出现在其中，但除非文档页面明确推荐，否则它们属于实现细节。
保留的内置插件辅助子路径仍会出现在该生成列表中。
除非某个文档页面明确将其推广为公开接口，否则请将它们视为实现细节/兼容性接口。
### 插件入口
### 插件入口点
| 子路径 | 关键导出 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| 子路径 | 关键导出 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `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/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="渠道子路径">
@ -71,306 +66,310 @@ SDK 子路径，而核心在确实存在跨渠道需求时，要么使用这些
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `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` | 共享设置向导辅助函数、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
| `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`、account-id 规范化辅助函数 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 |
| `plugin-sdk/account-helpers` | 精简的账户列表/账户操作辅助函数 |
| `plugin-sdk/setup-tools` | `formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR` |
| `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/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化/验证辅助函数 |
| `plugin-sdk/command-gating` | 精简的命令授权门控辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带内置契约回退 |
| `plugin-sdk/command-gating` | 窄范围命令授权门控辅助工具 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/最终化辅助函数 |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + 信封构建器辅助函数 |
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 |
| `plugin-sdk/messaging-targets` | 目标解析/匹配辅助函数 |
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 |
| `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` | 共享渠道状态快照/摘要辅助函数 |
| `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 原语 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
| `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 |
| `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时接口的精简提及策略辅助函数 |
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 |
| `plugin-sdk/channel-logging` | 用于入站丢弃及 typing/ack 失败的渠道日志辅助函数 |
| `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-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` | 共享渠道状态快照/摘要辅助工具 |
| `plugin-sdk/channel-config-primitives` | 窄范围渠道配置 schema 原语 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前置导出 |
| `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` | 用于入站防抖、提及匹配、提及策略辅助工具和 envelope 辅助工具的兼容性 barrel |
| `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时表面的窄范围提及策略辅助工具 |
| `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` | 渠道消息操作辅助工具，以及为保持 plugin 兼容性而保留的已弃用原生 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` | 窄范围密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 以及密钥目标类型 |
</Accordion>
<Accordion title="提供商子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助函数 |
| `plugin-sdk/provider-setup` | 精选的本地/自托管 provider 设置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管 provider 的聚焦设置辅助工具 |
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
| `plugin-sdk/provider-auth-runtime` | 用于提供商插件的运行时 API key 解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助函数，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
| `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`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/endpoint 能力辅助函数，包括音频转录 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 搜索提供商注册/缓存/运行时辅助函数 |
| `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/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/provider-auth-login` | 提供商插件共享的交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | provider 认证环境变量查找辅助工具 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`、`upsertApiKeyProfile`、`writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、provider endpoint 辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用 provider HTTP/endpoint 能力辅助工具，包括音频转录 multipart form 辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 窄范围 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | web-fetch provider 注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 适用于不需要 plugin 启用连接的 provider 的窄范围 web-search 配置/凭证辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 窄范围 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及带作用域的凭证设置器/获取器 |
| `plugin-sdk/provider-web-search` | web-search provider 注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + diagnostics，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
| `plugin-sdk/provider-transport-runtime` | 原生 provider 传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 |
</Accordion>
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送方授权辅助工具 |
| `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助函数 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助函数 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助工具 |
| `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 审批回复载荷辅助函数 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 |
| `plugin-sdk/command-detection` | 共享命令检测辅助函数 |
| `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助函数 |
| `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 审批回复负载辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
| `plugin-sdk/command-surface` | 命令正文规范化和命令表面辅助工具 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/plugin 密钥接口的精简密钥契约收集辅助函数 |
| `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助函数 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和密钥收集辅助函数 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-dispatcher` | 不包含广泛基础设施运行时接口的精简 pinned-dispatcher 辅助函数 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助函数 |
| `plugin-sdk/secret-input` | 密钥输入解析辅助函数 |
| `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助函数 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助函数 |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/plugin 密钥表面的窄范围密钥契约收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的窄范围 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和密钥收集辅助工具 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不含广泛基础设施运行时表面的窄范围 pinned-dispatcher 辅助工具 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 防护的 fetch 和 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | 密钥输入解析辅助工具 |
| `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
</Accordion>
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/plugin 安装辅助函数 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、记录器、超时、重试和退避辅助函数 |
| `plugin-sdk/channel-runtime-context` | 通用渠道 runtime-context 注册和查找辅助函数 |
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/plugin 安装辅助工具 |
| `plugin-sdk/runtime-env` | 窄范围运行时环境、logger、超时、重试和回退辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享 plugin 命令/hook/http/交互式辅助函数 |
| `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 流水线辅助函数 |
| `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助函数 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 |
| `plugin-sdk/config-runtime` | 配置加载/写入辅助函数和 plugin 配置查找辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名/描述规范化以及重复/冲突检查，即使内置的 Telegram 契约接口不可用也可使用 |
| `plugin-sdk/text-autolink-runtime` | 不依赖广泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec/plugin 审批辅助函数、审批能力构建器、认证/profile 辅助函数、原生路由/运行时辅助函数 |
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/最终化辅助函数 |
| `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/plugin-runtime` | 共享 plugin 命令/hook/http/交互式辅助工具 |
| `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助工具 |
| `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助工具 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 |
| `plugin-sdk/config-runtime` | 配置加载/写入辅助工具和 plugin 配置查找辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置的 Telegram 契约表面不可用时也可使用 |
| `plugin-sdk/text-autolink-runtime` | 不依赖广泛 `text-runtime` barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec/plugin 审批辅助工具、审批能力构建器、认证/profile 辅助工具、原生路由/运行时辅助工具 |
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、heartbeat、回复规划器 |
| `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/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/reply-chunking` | 窄范围文本/Markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 |
| `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-payload` | 从工具结果对象中提取规范化负载 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 |
| `plugin-sdk/logging-core` | 子系统记录器和脱敏辅助函数 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助函数 |
| `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` | 设备 bootstrap 和配对令牌辅助函数 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 |
| `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` | 共享被动渠道、状态和环境代理辅助原语 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助函数 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助函数 |
| `plugin-sdk/agent-harness` | 面向低级智能体 harness 的实验性可信 plugin 接口：harness 类型、活动运行 steer/abort 辅助函数、OpenClaw 工具桥接辅助函数和尝试结果工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI endpoint 检测辅助函数 |
| `plugin-sdk/infra-runtime` | 系统事件/心跳辅助函数 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和固定查找辅助函数 |
| `plugin-sdk/runtime-fetch` | 不引入代理/受保护 fetch 导入的 dispatcher 感知运行时 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/models-provider-runtime` | `/models` 命令/provider 回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向低层智能体 harness 的实验性可信 plugin 表面：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具和尝试结果实用工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 |
| `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned 查找辅助工具 |
| `plugin-sdk/runtime-fetch` | 具备 dispatcher 感知能力的运行时 fetch，不包含 proxy/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` | 智能体目录/身份/workspace 辅助工具 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="能力与测试子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数以及媒体载荷构建器 |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助函数、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如助手可见文本剥离、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助函数 |
| `plugin-sdk/speech` | 语音提供商类型以及面向提供商的 directive、注册表和验证辅助函数 |
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助函数 |
| `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/zod` | 为插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体负载构建器 |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助工具、候选项选择和缺失模型消息 |
| `plugin-sdk/media-understanding` | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助工具导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如对 assistant 可见文本的剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音 provider 类型，以及面向 provider 的 directive、注册表和校验辅助工具 |
| `plugin-sdk/speech-core` | 共享语音 provider 类型、注册表、directive 和规范化辅助工具 |
| `plugin-sdk/realtime-transcription` | 实时转录 provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音 provider 类型和注册表辅助工具 |
| `plugin-sdk/image-generation` | 图像生成 provider 类型 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障切换、认证和注册表辅助工具 |
| `plugin-sdk/music-generation` | 音乐生成 provider/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成 provider/请求/结果类型 |
| `plugin-sdk/video-generation-core` | 共享视频生成类型、故障切换辅助工具、provider 查找和 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` |
</Accordion>
<Accordion title="Memory 子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `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 主机状态辅助函数 |
| `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 主机状态辅助函数的供应商中立别名 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 |
| `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 host 基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地 provider 以及通用批处理/远程辅助工具 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory host 密钥辅助工具 |
| `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 面向厂商中立的 memory host 核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | 面向厂商中立的 memory host 事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | 面向厂商中立的 memory host 文件/运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 用于 memory 相邻插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时外观 |
| `plugin-sdk/memory-host-status` | 面向厂商中立的 memory host 状态辅助工具别名 |
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 |
</Accordion>
<Accordion title="保留的内置辅助子路径">
| 系列 | 当前子路径 | 预期用途 |
| 家族 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| 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-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/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助接口 |
| 认证/plugin 专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/plugin 辅助接口；`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` | 内置 browser 插件支持辅助工具（`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/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助接缝层 |
| 认证/plugin 专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/plugin 辅助接缝层；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## 注册 API
`register(api)` 回调会接收一个带有以下方法的 `OpenClawPluginApi` 对象：
`register(api)` 回调会接收一个 `OpenClawPluginApi` 对象，包含以下方法：
### 能力注册
| 方法 | 注册内容 |
| ---------------------------------------------- | --------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerAgentHarness(...)` | 实验性的低层智能体执行器 |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | Web 抓取 / 抓取提供商 |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
| 方法 | 注册内容 |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerAgentHarness(...)` | 实验性的低层智能体执行器 |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
| `api.registerRealtimeVoiceProvider(...)` | 双向实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取 provider |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
### 工具和命令
### 工具与命令
| 方法 | 注册内容 |
| ----------------------------- | ------------------------------------------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
| 方法 | 注册内容 |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
### 基础设施
| 方法 | 注册内容 |
| --------------------------------------------- | -------------------------------- |
| `api.registerHook(events, handler, opts?)` | 事件 hook |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP endpoint |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
| `api.registerEmbeddedExtensionFactory(factory)` | Pi 嵌入式运行器扩展工厂 |
| `api.registerMemoryPromptSupplement(builder)` | 附加型 Memory 相关提示区段 |
| `api.registerMemoryCorpusSupplement(adapter)` | 附加型 Memory 搜索/读取语料库 |
| 方法 | 注册内容 |
| ----------------------------------------------- | --------------------------------------- |
| `api.registerHook(events, handler, opts?)` | 事件 hook |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP endpoint |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
| `api.registerEmbeddedExtensionFactory(factory)` | Pi 内嵌运行器扩展工厂 |
| `api.registerMemoryPromptSupplement(builder)` | 追加式 memory 相邻提示词段落 |
| `api.registerMemoryCorpusSupplement(adapter)` | 追加式 memory 搜索/读取语料库 |
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、
`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的
Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用
插件专属前缀。
<Note>
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、
`update.*`）始终保持为 `operator.admin`，即使 plugin 尝试分配更窄范围的
Gateway 网关方法作用域也是如此。对于 plugin 自有方法，优先使用特定于 plugin 的前缀。
</Note>
当插件在 OpenClaw 嵌入式运行期间需要 Pi 原生事件时序时，使用 `api.registerEmbeddedExtensionFactory(...)`，
例如那些必须在最终工具结果消息发出之前发生的异步 `tool_result`
重写。当前这是一个内置插件接口：只有内置插件可以注册它，并且
它们必须在 `openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。
对于不需要该更低层接口的所有场景，请继续使用普通的 OpenClaw 插件 hook。
<Accordion title="何时使用 registerEmbeddedExtensionFactory">
当某个 plugin 在 OpenClaw 内嵌运行期间需要 Pi 原生事件时序时，请使用 `api.registerEmbeddedExtensionFactory(...)`
—— 例如必须在最终工具结果消息发出之前完成的异步 `tool_result`
重写。
这目前是一个内置 plugin 接缝层：只有内置插件可以注册它，
并且它们必须在 `openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。
对于所有不需要这种更低层接缝层的情况，继续使用普通的 OpenClaw plugin hooks。
</Accordion>
### CLI 注册元数据
`api.registerCli(registrar, opts?)` 接受两类顶层元数据：
- `commands`：由注册器拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符
- `commands`：由 registrar 拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和惰性 plugin CLI 注册的解析时命令描述符
如果你希望插件命令在普通根 CLI 路径中保持延迟加载，请提供 `descriptors`，
覆盖该注册器暴露的每个顶层命令根。
如果你希望某个 plugin 命令在普通根 CLI 路径中保持惰性加载，请提供覆盖该 registrar 暴露的每个顶层命令根的 `descriptors`。
```typescript
api.registerCli(
@ -390,85 +389,82 @@ api.registerCli(
);
```
仅在你不需要延迟根 CLI 注册时才单独使用 `commands`。
这种预加载兼容路径仍受支持，但它不会安装由描述符支持的占位符来实现解析时延迟加载。
仅在你不需要惰性根 CLI 注册时，才单独使用 `commands`。
这种急切兼容路径仍受支持，但它不会为解析时惰性加载安装基于 descriptor 的占位符。
### CLI 后端注册
`api.registerCliBackend(...)` 允许插件拥有本地
AI CLI 后端（例如 `codex-cli`）的默认配置。
`api.registerCliBackend(...)` 允许某个 plugin 拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。
- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。
- 后端 `id` 会成为模型引用中的 provider 前缀，例如 `codex-cli/gpt-5`。
- 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的结构。
- 用户配置仍然优先生效。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.<id>` 合并到
插件默认值之上。
- 当后端在合并后需要进行兼容性重写时，使用 `normalizeConfig`
- 用户配置仍然优先。OpenClaw 会先将 `agents.defaults.cliBackends.<id>` 合并到 plugin 默认值之上，再运行 CLI。
- 当某个后端在合并后需要兼容性重写时，请使用 `normalizeConfig`
（例如规范化旧版 flag 结构）。
### 独占槽位
| 方法 | 注册内容 |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个处于激活状态）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便该引擎定制提示附加内容。 |
| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 |
| `api.registerMemoryPromptSection(builder)` | Memory 提示区段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | Memory flush plan 解析器 |
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
| 方法 | 注册内容 |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个处于活动状态）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎按需定制提示词补充内容。 |
| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 |
| `api.registerMemoryPromptSection(builder)` | Memory 提示词段落构建器 |
| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
### Memory 嵌入适配器
### Memory embedding 适配器
| 方法 | 注册内容 |
| -------------------------------------------- | -------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | 当前活动插件的 Memory 嵌入适配器 |
| 方法 | 注册内容 |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动 plugin 的 Memory embedding 适配器 |
- `registerMemoryCapability` 是首选的独占式 Memory 插件 API。
- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`，
这样配套插件就能通过 `openclaw/plugin-sdk/memory-host-core`
使用导出的 Memory 工件，而不必深入某个特定 Memory 插件的私有布局。
- `registerMemoryCapability` 是首选的独占 Memory 插件 API。
- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，
以便配套插件通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 Memory 工件，
而不是深入访问某个特定 Memory 插件的私有布局。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和
`registerMemoryRuntime` 是兼容旧版本的独占式 Memory 插件 API。
- `registerMemoryEmbeddingProvider` 允许活动中的 Memory 插件注册一个
或多个嵌入适配器 id（例如 `openai`、`gemini` 或插件自定义 id）。
`registerMemoryRuntime` 是兼容旧版的独占 Memory 插件 API。
- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个
或多个 embedding 适配器 ID（例如 `openai`、`gemini` 或 plugin 自定义 ID）。
- 用户配置（例如 `agents.defaults.memorySearch.provider` 和
`agents.defaults.memorySearch.fallback`）会根据这些已注册的
适配器 id 进行解析。
`agents.defaults.memorySearch.fallback`）会基于这些已注册的适配器 ID 进行解析。
### 事件与生命周期
| 方法 | 作用 |
| -------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
### Hook 决策语义
- `before_tool_call`：返回 `{ block: true }` 即为终局决定。一旦任一处理器设置该值，就会跳过更低优先级的处理器。
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖已有决定。
- `before_install`：返回 `{ block: true }` 即为终局决定。一旦任一处理器设置该值，就会跳过更低优先级的处理器。
- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖已有决定。
- `reply_dispatch`：返回 `{ handled: true, ... }` 即为终局决定。一旦任一处理器声明处理了分发，就会跳过更低优先级的处理器以及默认模型分发路径。
- `message_sending`：返回 `{ cancel: true }` 即为终局决定。一旦任一处理器设置该值，就会跳过更低优先级的处理器。
- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖已有决定。
- `message_received`：当你需要入站线程/话题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的附加信息。
- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道特定的 `metadata`。
- `gateway_start`：对于 Gateway 网关自有的启动状态，请使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，而不要依赖内部 `gateway:startup` hook。
- `before_tool_call`：返回 `{ block: true }` 为终止性决定。一旦任一处理器设置它，将跳过优先级更低的处理器。
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
- `before_install`：返回 `{ block: true }` 为终止性决定。一旦任一处理器设置它，将跳过优先级更低的处理器。
- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
- `reply_dispatch`：返回 `{ handled: true, ... }` 为终止性决定。一旦任一处理器声明已处理分发，将跳过优先级更低的处理器以及默认模型分发路径。
- `message_sending`：返回 `{ cancel: true }` 为终止性决定。一旦任一处理器设置它，将跳过优先级更低的处理器。
- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。
- `message_received`：当你需要入站线程/主题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给特定于渠道的附加信息。
- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到特定于渠道的 `metadata`。
- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 获取 Gateway 网关自有的启动状态，而不要依赖内部 `gateway:startup` hooks。
### API 对象字段
| 字段 | 类型 | 描述 |
| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------- |
| `api.id` | `string` | 插件 id |
| `api.name` | `string` | 显示名称 |
| `api.version` | `string?` | 插件版本（可选） |
| `api.description` | `string?` | 插件描述（可选） |
| `api.source` | `string` | 插件源路径 |
| `api.rootDir` | `string?` | 插件根目录（可选） |
| `api.config` | `OpenClawConfig` | 当前配置快照（如果可用，则为活动的内存中运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域记录器（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量级启动/设置窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
| 字段 | 类型 | 说明 |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | 插件 ID |
| `api.name` | `string` | 显示名称 |
| `api.version` | `string?` | 插件版本（可选） |
| `api.description` | `string?` | 插件描述（可选） |
| `api.source` | `string` | 插件源路径 |
| `api.rootDir` | `string?` | 插件根目录（可选） |
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存中运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量预启动窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
## 内部模块约定
@ -476,7 +472,7 @@ AI CLI 后端（例如 `codex-cli`）的默认配置。
```
my-plugin/
api.ts # 供外部使用者使用的公开导出
api.ts # 面向外部使用方的公共导出
runtime-api.ts # 仅供内部使用的运行时导出
index.ts # 插件入口点
setup-entry.ts # 仅用于轻量设置的入口点（可选）
@ -488,35 +484,45 @@ my-plugin/
`./runtime-api.ts` 进行内部导入。SDK 路径仅是对外契约。
</Warning>
当 OpenClaw 已经运行时，由外观模式加载的内置插件公开接口（`api.ts`、`runtime-api.ts`、
`index.ts`、`setup-entry.ts` 以及类似的公开入口文件）现在会优先使用活动运行时配置快照。
如果运行时快照尚不存在，它们会回退到磁盘上已解析的配置文件。
通过 facade 加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、
`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）在 OpenClaw 已经运行时会优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析得到的配置文件。
当某个辅助函数有意保持提供商专属，且暂时还不适合放入通用 SDK
子路径时，提供商插件也可以暴露一个精简的插件本地契约 barrel。当前内置示例：Anthropic
提供商将其 Claude 流辅助函数保留在自己的公开 `api.ts` / `contract-api.ts`
接口中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升为通用
`plugin-sdk/*` 契约的一部分。
当某个辅助工具有意保持提供商专属，且暂时还不适合放入通用 SDK
子路径时，provider 插件可以暴露一个窄范围的 plugin 本地契约 barrel。内置示例：
其他当前的内置示例：
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、
默认模型辅助函数和实时提供商构建器
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及
新手引导/配置辅助函数
- **Anthropic**：用于 Claude
beta-header 和 `service_tier` 流辅助工具的公共 `api.ts` / `contract-api.ts` 接缝层。
- **`@openclaw/openai-provider`**：`api.ts` 导出 provider 构建器、
默认模型辅助工具和实时 provider 构建器。
- **`@openclaw/openrouter-provider`**：`api.ts` 导出 provider 构建器，
以及新手引导/配置辅助工具。
<Warning>
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
如果某个辅助函数确实应被共享，请将其提升到中立的 SDK 子路径，
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他
面向能力的接口，而不是将两个插件耦合在一起。
扩展的生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
如果某个辅助工具确实是共享的，请将它提升到一个中立的 SDK 子路径，
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他
面向能力的表面，而不是让两个插件彼此耦合。
</Warning>
## 相关内容
- [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项
- [运行时辅助函数](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考
- [设置与配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema
- [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用接口迁移
- [插件内部机制](/zh-CN/plugins/architecture) — 深入的架构和能力模型
<CardGroup cols={2}>
<Card title="入口点" icon="door-open" href="/zh-CN/plugins/sdk-entrypoints">
`definePluginEntry` 和 `defineChannelPluginEntry` 选项。
</Card>
<Card title="运行时辅助工具" icon="gears" href="/zh-CN/plugins/sdk-runtime">
完整的 `api.runtime` 命名空间参考。
</Card>
<Card title="设置与配置" icon="sliders" href="/zh-CN/plugins/sdk-setup">
打包、manifest 和配置 schema。
</Card>
<Card title="测试" icon="vial" href="/zh-CN/plugins/sdk-testing">
测试实用工具和 lint 规则。
</Card>
<Card title="SDK 迁移" icon="arrows-turn-right" href="/zh-CN/plugins/sdk-migration">
从已弃用表面迁移。
</Card>
<Card title="插件内部机制" icon="diagram-project" href="/zh-CN/plugins/architecture">
深入架构和能力模型。
</Card>
</CardGroup>

483
docs/zh-CN/tools/exec-approvals.md
View File

@ -1,69 +1,69 @@
---
read_when:
- 配置执行审批或允许列表
- 在 macOS 应用中实现执行审批 UX
- 配置执行批准或允许列表
- 在 macOS 应用中实现执行批准 UX
- 审查沙箱逃逸提示及其影响
summary: 执行审批、允许列表和沙箱逃逸提示
title: 执行审批
summary: 执行批准、允许列表和沙箱逃逸提示
title: 执行批准
x-i18n:
generated_at: "2026-04-23T17:12:46Z"
generated_at: "2026-04-23T17:31:43Z"
model: gpt-5.4
provider: openai
source_hash: 3b86106d3a145047ab2400d45aece0a66c7ec5ea4785e7538476c55477aab087
source_hash: edfc53f7f343969411f9cda848933e7a1ab80076257e4a0802910a910b3a47ea
source_path: tools/exec-approvals.md
workflow: 15
---
# 执行审批
# 执行批准
执行审批是让经过沙箱隔离的智能体在真实主机（`gateway` 或 `node`）上运行命令时的**配套应用 / 节点主机护栏**。它是一种安全联锁机制：只有当策略 + 允许列表 +（可选）用户审批全部同意时，命令才会被允许。执行审批叠加在工具策略和提权门控**之上**（除非提权设置为 `full`，此时会跳过审批）。
执行批准是**配套应用 / 节点宿主机防护机制**，用于让处于沙箱隔离的智能体在真实宿主机（`gateway` 或 `node`）上运行命令。它是一种安全联锁：只有当策略 + 允许列表 +（可选的）用户批准全部一致同意时，命令才会被允许执行。执行批准叠加在工具策略和 elevated 门控**之上**（除非 elevated 设置为 `full`，此时会跳过批准）。
<Note>
生效策略是 `tools.exec.*` 与审批默认值中**更严格**的那个；如果审批字段被省略，则使用 `tools.exec` 的值。主机执行还会使用该机器上的本地审批状态——如果 `~/.openclaw/exec-approvals.json` 中主机本地设置了 `ask: "always"`，即使会话或配置默认值请求 `ask: "on-miss"`，也仍然会持续提示。
生效策略取 `tools.exec.*` 与批准默认值中**更严格**的一方；如果某个批准字段被省略，则使用 `tools.exec` 中的值。宿主机执行还会使用该机器上的本地批准状态 —— 即使会话或配置默认值请求 `ask: "on-miss"`，`~/.openclaw/exec-approvals.json` 中宿主机本地的 `ask: "always"` 仍会持续提示。
</Note>
## 检查生效策略
- `openclaw approvals get`、`... --gateway`、`... --node <id|name|ip>` —— 显示请求的策略、主机策略来源以及生效结果。
- `openclaw exec-policy show` —— 本地机器上的合并视图。
- `openclaw exec-policy set|preset` —— 一步将本地请求策略与本地主机审批文件同步。
- `openclaw approvals get`、`... --gateway`、`... --node <id|name|ip>` — 显示请求的策略、宿主机策略来源和最终生效结果。
- `openclaw exec-policy show` — 本地机器的合并视图。
- `openclaw exec-policy set|preset` — 一步将本地请求策略与本地宿主机批准文件同步。
当本地作用域请求 `host=node` 时，`exec-policy show` 会在运行时将该作用域报告为由节点管理，而不是假装本地审批文件是真实来源。
当本地作用域请求 `host=node` 时，`exec-policy show` 会在运行时将该作用域报告为由节点管理，而不是假装本地批准文件才是真实来源。
如果配套应用 UI **不可用**，任何通常会触发提示的请求都会由 **ask fallback** 处理（默认值：deny）。
如果配套应用 UI **不可用**，任何原本通常会触发提示的请求都会由 **ask 回退** 处理（默认值：deny）。
<Tip>
原生聊天审批客户端可以为待处理的审批消息预置特定渠道的交互方式。例如，Matrix 会预置反应快捷方式（`✅` 允许一次、`❌` 拒绝、`♾️` 始终允许），同时仍保留消息中的 `/approve ...` 命令作为后备方案。
原生聊天批准客户端可以在待处理的批准消息上预置渠道特定的交互方式。例如，Matrix 会预置表情快捷方式（`✅` 允许一次、`❌` 拒绝、`♾️` 始终允许），同时仍在消息中保留 `/approve ...` 命令作为回退方案。
</Tip>
## 适用范围
## 适用位置
执行审批会在执行所在主机上本地强制实施：
执行批准会在执行宿主机本地强制执行：
- **Gateway 网关主机** → Gateway 网关机器上的 `openclaw` 进程
- **节点主机** → 节点运行器（macOS 配套应用或无头节点主机）
- **Gateway 网关宿主机** → Gateway 网关机器上的 `openclaw` 进程
- **node 宿主机** → 节点运行器（macOS 配套应用或无头 node 宿主机）
信任模型说明：
- 通过 Gateway 网关认证的调用方，是该 Gateway 网关的受信操作员。
- 已配对节点会将这种受信操作员能力扩展到节点主机。
- 执行审批可降低意外执行风险，但不是按用户划分的认证边界。
- 已批准的节点主机运行会绑定规范执行上下文：规范 cwd、精确 argv、存在时的环境变量绑定，以及适用时固定的可执行文件路径。
- 对于 shell 脚本和直接解释器 / 运行时文件调用，OpenClaw 还会尝试绑定一个具体的本地文件操作数。如果该绑定文件在批准后、执行前发生变化，将拒绝运行，而不是执行已漂移的内容。
- 这种文件绑定有意采用尽力而为方式，并不是对每一种解释器 / 运行时加载路径的完整语义模型。如果审批模式无法准确识别并绑定**唯一一个**具体本地文件，它会拒绝签发基于审批的运行，而不是假装实现了完整覆盖。
- 通过 Gateway 网关认证的调用方，是该 Gateway 网关的受信任操作员。
- 已配对节点会将这种受信任操作员能力扩展到 node 宿主机。
- 执行批准可降低意外执行风险，但它不是按用户划分的认证边界。
- 已批准的 node 宿主机运行会绑定规范化执行上下文：规范化 cwd、精确 argv、存在时的 env 绑定，以及适用时固定的可执行文件路径。
- 对于 shell 脚本和直接解释器 / 运行时文件调用，OpenClaw 还会尝试绑定一个具体的本地文件操作数。如果该绑定文件在批准后、执行前发生变化，运行将被拒绝，而不是执行已漂移的内容。
- 这种文件绑定有意设计为尽力而为，并不是对每一种解释器 / 运行时加载路径的完整语义模型。如果批准模式无法识别并精确绑定唯一一个具体本地文件，它会拒绝签发基于批准的运行，而不是假装已完整覆盖。
macOS 拆分：
- **节点主机服务** 通过本地 IPC 将 `system.run` 转发给 **macOS 应用**。
- **macOS 应用** 负责执行审批 + 在 UI 上下文中执行命令。
- **node 宿主服务** 通过本地 IPC 将 `system.run` 转发给 **macOS 应用**。
- **macOS 应用** 在 UI 上下文中执行批准检查并运行命令。
## 设置与存储
审批存储在执行主机上的本地 JSON 文件中：
批准保存在执行宿主机上的本地 JSON 文件中：
`~/.openclaw/exec-approvals.json`
示例结构：
示例 schema：
```json
{
@ -98,30 +98,30 @@ macOS 拆分：
}
```
## 无审批的 “YOLO” 模式
## 无批准的 “YOLO” 模式
如果你希望主机执行在没有审批提示的情况下运行，你必须同时放开**两层**策略：
如果你希望宿主机执行在没有批准提示的情况下运行，你必须同时放开**两层**策略：
- OpenClaw 配置中的请求执行策略（`tools.exec.*`）
- `~/.openclaw/exec-approvals.json` 中主机本地的审批策略
- `~/.openclaw/exec-approvals.json` 中宿主机本地的批准策略
这现在是默认的主机行为，除非你显式收紧它：
现在这是默认的宿主机行为，除非你显式收紧它：
- `tools.exec.security`：在 `gateway` / `node` 上设为 `full`
- `tools.exec.ask`：设为 `off`
- 主机 `askFallback`：设为 `full`
- `tools.exec.security`: 在 `gateway` / `node` 上使用 `full`
- `tools.exec.ask`: `off`
- 宿主机 `askFallback`: `full`
重要区别：
- `tools.exec.host=auto` 选择执行运行的位置：如果有沙箱则在沙箱中，否则在 Gateway 网关上。
- YOLO 选择主机执行如何获批：`security=full` 加 `ask=off`。
- 在 YOLO 模式下，OpenClaw 不会在已配置的主机执行策略之上，再额外添加独立的启发式命令混淆审批门控或脚本预检拒绝层。
- `auto` 不会让来自沙箱会话的 Gateway 网关路由变成一个免费覆盖项。允许在 `auto` 下按次请求 `host=node`；只有在没有活动沙箱运行时时，才允许在 `auto` 下请求 `host=gateway`。如果你想使用稳定的非 auto 默认值，请设置 `tools.exec.host`，或显式使用 `/exec host=...`。
- `tools.exec.host=auto` 选择执行运行位置：有沙箱时在沙箱中运行，否则在 gateway 上运行。
- YOLO 决定宿主机执行如何被批准：`security=full` 且 `ask=off`。
- 在 YOLO 模式下，OpenClaw 不会在已配置的宿主机执行策略之上，额外增加单独的启发式命令混淆批准门控或脚本预检拒绝层。
- `auto` 不会让来自沙箱隔离会话的 gateway 路由成为免费覆盖项。每次调用的 `host=node` 请求在 `auto` 下是允许的，而 `host=gateway` 仅在没有活动沙箱运行时时，才允许从 `auto` 发起。如果你想要稳定的非 auto 默认值，请设置 `tools.exec.host`，或显式使用 `/exec host=...`。
如果你想使用更保守的设置，可将任一层重新收紧为 `allowlist` / `on-miss`
如果你想要更保守的设置，可将任意一层收紧回 `allowlist` / `on-miss`
或 `deny`。
持久的 Gateway 网关主机“永不提示”设置：
持久化的 gateway 宿主机 “永不提示” 设置：
```bash
openclaw config set tools.exec.host gateway
@ -130,7 +130,7 @@ openclaw config set tools.exec.ask off
openclaw gateway restart
```
然后将主机审批文件设为匹配：
然后将宿主机批准文件设置为匹配值：
```bash
openclaw approvals set --stdin <<'EOF'
@ -145,7 +145,7 @@ openclaw approvals set --stdin <<'EOF'
EOF
```
在当前机器上应用相同 Gateway 网关主机策略的本地快捷方式：
在当前机器上应用相同 gateway 宿主机策略的本地快捷方式：
```bash
openclaw exec-policy preset yolo
@ -156,10 +156,11 @@ openclaw exec-policy preset yolo
- 本地 `tools.exec.host/security/ask`
- 本地 `~/.openclaw/exec-approvals.json` 默认值
它有意仅作用于本地。如果你需要远程修改 Gateway 网关主机或节点主机审批，请继续使用 `openclaw approvals set --gateway` 或
它有意仅限本地使用。如果你需要远程更改 gateway 宿主机或 node 宿主机的批准，
请继续使用 `openclaw approvals set --gateway` 或
`openclaw approvals set --node <id|name|ip>`。
对于节点主机，请改为在该节点上应用相同的审批文件：
对于 node 宿主机，请在该节点上应用相同的批准文件：
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
@ -174,45 +175,45 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
EOF
```
重要的仅本地限制：
重要的仅限本地限制：
- `openclaw exec-policy` 不会同步节点审批
- `openclaw exec-policy` 不会同步节点批准
- `openclaw exec-policy set --host node` 会被拒绝
- 节点执行审批会在运行时从节点拉取，因此面向节点的更新必须使用 `openclaw approvals --node ...`
- node 执行批准会在运行时从节点获取，因此面向节点的更新必须使用 `openclaw approvals --node ...`
仅会话快捷方式：
- `/exec security=full ask=off` 仅更改当前会话。
- `/elevated full` 是一种破窗应急快捷方式，也会对该会话跳过执行审批。
- `/exec security=full ask=off` 只会更改当前会话。
- `/elevated full` 是一种紧急放行快捷方式，同时也会跳过该会话的执行批准。
如果主机审批文件仍比配置更严格，则更严格的主机策略仍然优先。
如果宿主机批准文件仍比配置更严格，则仍以更严格的宿主机策略为准。
## 策略选项
## 策略旋钮
### 安全级别（`exec.security`）
### 安全性（`exec.security`）
- **deny**：阻止所有主机执行请求。
- **allowlist**：只允许允许列表中的命令。
- **deny**：阻止所有宿主机执行请求。
- **allowlist**：仅允许允许列表中的命令。
- **full**：允许所有内容（等同于 elevated）。
### 询问方式（`exec.ask`）
### 询问（`exec.ask`）
- **off**：从不提示。
- **on-miss**：仅在允许列表未匹配时提示。
- **always**：每条命令都提示。
- 当生效的询问模式为 `always` 时，`allow-always` 持久信任不会抑制提示
- **on-miss**：仅在允许列表不匹配时提示。
- **always**：每个命令都提示。
- 当生效的询问模式为 `always` 时，`allow-always` 的持久信任不会抑制提示
### 提示后备（`askFallback`）
### 询问回退（`askFallback`）
如果需要提示但没有可访问的 UI，则由后备策略决定：
如果需要提示但没有可达的 UI，则由回退决定：
- **deny**：阻止。
- **allowlist**：仅当允许列表匹配时允许。
- **allowlist**：仅在允许列表匹配时允许。
- **full**：允许。
### 内联解释器 eval 加固（`tools.exec.strictInlineEval`）
当 `tools.exec.strictInlineEval=true` 时，OpenClaw 会将内联代码 eval 形式视为仅可通过审批运行，即使解释器二进制本身已在允许列表中。
当 `tools.exec.strictInlineEval=true` 时，即使解释器二进制文件本身已在允许列表中，OpenClaw 也会将内联代码 eval 形式视为仅可通过批准执行。
示例：
@ -224,15 +225,17 @@ EOF
- `lua -e`
- `osascript -e`
这是针对无法清晰映射到单一稳定文件操作数的解释器加载器所做的纵深防御。在严格模式下：
这是对无法干净映射到单一稳定文件操作数的解释器加载器所做的纵深防御。在严格模式下：
- 这些命令仍然需要显式审批；
- 这些命令仍然需要显式批准；
- `allow-always` 不会自动为它们持久化新的允许列表条目。
## 允许列表（按智能体）
允许列表是**按智能体**划分的。如果存在多个智能体，请在 macOS 应用中切换你正在编辑的智能体。模式采用**不区分大小写的 glob 匹配**。模式应解析为**二进制路径**（仅包含 basename 的条目会被忽略）。旧版 `agents.default` 条目会在加载时迁移到 `agents.main`。
像 `echo ok && pwd` 这样的 shell 链仍要求每个顶层片段都满足允许列表规则。
允许列表是**按智能体**划分的。如果存在多个智能体，请在 macOS 应用中切换你正在编辑的智能体。模式采用**大小写不敏感的 glob 匹配**。
模式应解析为**二进制文件路径**（仅文件名的条目会被忽略）。
旧版 `agents.default` 条目会在加载时迁移到 `agents.main`。
Shell 链（例如 `echo ok && pwd`）仍然要求每个顶层片段都满足允许列表规则。
示例：
@ -245,28 +248,29 @@ EOF
- **id**：用于 UI 标识的稳定 UUID（可选）
- **上次使用**
- **上次使用的命令**
- **上次解析出的路径**
- **上次解析到的路径**
## 自动允许 Skills CLI
## 自动允许 skill CLI
启用 **Auto-allow skill CLIs** 后，已知 Skills 引用的可执行文件会在节点上（macOS 节点或无头节点主机）被视为已加入允许列表。它通过 Gateway RPC 中的 `skills.bins` 获取 skill bin 列表。如果你想使用严格的手动允许列表，请禁用此功能。
启用 **自动允许 skill CLI** 后，已知 Skills 引用的可执行文件会在节点上（macOS 节点或无头 node 宿主机）被视为已加入允许列表。这会通过 Gateway 网关 RPC 使用
`skills.bins` 获取 skill bin 列表。如果你想要严格的手动允许列表，请禁用此功能。
重要信任说明：
- 这是一个**隐式的便捷允许列表**，与手动路径允许列表条目分开。
- 它面向 Gateway 网关与节点处于同一信任边界中的受信操作环境。
- 如果你要求严格的显式信任，请保持 `autoAllowSkills: false`，并仅使用手动路径允许列表条目。
- 这是一个**隐式的便利允许列表**，与手动路径允许列表条目分离。
- 它适用于 Gateway 网关与 node 位于同一信任边界内的受信任操作员环境。
- 如果你需要严格的显式信任，请保持 `autoAllowSkills: false`，并且只使用手动路径允许列表条目。
## 安全二进制（仅 stdin）
## 安全二进制文件（仅 stdin）
`tools.exec.safeBins` 定义了一小组**仅 stdin** 的二进制文件（例如 `cut`），它们可以在 `allowlist` 模式下**无需**显式允许列表条目运行。安全二进制会拒绝位置文件参数和类似路径的 token，因此它们只能处理传入的数据流。应将其视为流过滤器的狭窄快速通道，而不是通用信任列表。
`tools.exec.safeBins` 定义了一小组**仅 stdin** 的二进制文件（例如 `cut`），它们可以在 allowlist 模式下**无需**显式允许列表条目运行。安全二进制文件会拒绝位置文件参数和类似路径的 token，因此它们只能处理输入流。应将它视为面向流过滤器的狭义快速通道，而不是通用信任列表。
<Warning>
**不要**将解释器或运行时二进制（例如 `python3`、`node`、
`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins`。如果某个命令按设计可以执行代码求值、执行子命令或读取文件，应优先使用显式允许列表条目，并保持审批提示启用。自定义安全二进制必须在 `tools.exec.safeBinProfiles.<bin>` 中定义显式配置。
**不要**将解释器或运行时二进制文件（例如 `python3`、`node`、
`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins` 中。如果命令按设计可以求值代码、执行子命令或读取文件，请优先使用显式允许列表条目，并保持批准提示启用。自定义安全二进制文件必须在 `tools.exec.safeBinProfiles.<bin>` 中定义显式 profile。
</Warning>
默认安全二进制：
默认安全二进制文件：
[//]: # "SAFE_BIN_DEFAULTS:START"
@ -274,13 +278,14 @@ EOF
[//]: # "SAFE_BIN_DEFAULTS:END"
`grep` 和 `sort` 不在默认列表中。如果你选择启用它们，请为其非 stdin 工作流保留显式允许列表条目。对于处于安全二进制模式下的 `grep`，请使用 `-e` / `--regexp` 提供模式；位置模式形式会被拒绝，因此无法将文件操作数伪装成有歧义的位置参数。
`grep` 和 `sort` 不在默认列表中。如果你选择启用它们，请为其非 stdin 工作流保留显式允许列表条目。对于安全二进制文件模式下的 `grep`，
请使用 `-e` / `--regexp` 提供模式；位置模式形式会被拒绝，这样文件操作数就无法伪装成含糊的位置参数。
<AccordionGroup>
<Accordion title="Argv 验证和被拒绝的标志">
验证仅依据 argv 形状进行确定性判断（不检查主机文件系统中的文件是否存在），从而避免因允许 / 拒绝差异而产生文件存在性预言机行为。默认安全二进制会拒绝面向文件的选项；长选项采用失败关闭方式验证（未知标志和有歧义的缩写都会被拒绝）。
验证仅基于 argv 形状进行确定性判断（不检查宿主机文件系统中的存在性），这可防止因允许 / 拒绝差异而产生文件存在性预言机行为。默认安全二进制文件会拒绝面向文件的选项；长选项采用失败即关闭的验证方式（未知标志和有歧义的缩写都会被拒绝）。
按安全二进制配置划分的被拒绝标志：
按安全二进制文件 profile 列出的被拒绝标志：
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
@ -291,247 +296,241 @@ EOF
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
安全二进制还会在执行时强制将 argv token 视为**字面文本**来处理（对仅 stdin 片段不进行 glob 展开，也不进行 `$VARS` 展开），因此像 `*` 或 `$HOME/...` 这样的模式无法被用来伪装文件读取。
安全二进制文件还会在执行时强制将 argv token 视为**字面文本**（对仅 stdin 片段不进行 glob 展开，也不进行 `$VARS` 扩展），因此像 `*` 或 `$HOME/...` 这样的模式无法被用来伪装文件读取。
</Accordion>
<Accordion title="受信任的二进制目录">
安全二进制必须从受信任的二进制目录解析（系统默认目录
<Accordion title="受信任的二进制文件目录">
安全二进制文件必须解析自受信任的二进制文件目录（系统默认值
加上可选的 `tools.exec.safeBinTrustedDirs`）。`PATH` 条目绝不会
自动视为受信任。默认受信任目录有意保持最小范围：
`/bin`、`/usr/bin`。如果你的安全二进制可执行文件位于
被自动视为受信任。默认受信任目录有意保持最小化：
`/bin`、`/usr/bin`。如果你的安全二进制文件可执行程序位于
包管理器 / 用户路径中（例如 `/opt/homebrew/bin`、
`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`），请将它们显式添加到
`tools.exec.safeBinTrustedDirs`。
</Accordion>
<Accordion title="Shell 链接、包装器和多路复用器">
允许使用 shell 链接（`&&`、`||`、`;`），前提是每个顶层片段
都满足允许列表要求（包括安全二进制或 Skills 自动允许）。
在 `allowlist` 模式下，重定向仍不受支持。命令替换
（`$()` / 反引号）会在允许列表解析期间被拒绝，包括双引号内部；
如果你需要字面量 `$()` 文本，请使用单引号。
允许使用 Shell 链接（`&&`、`||`、`;`），前提是每个顶层片段
都满足允许列表要求（包括安全二进制文件或 skill 自动允许）。
在 allowlist 模式下，重定向仍不受支持。命令替换
（`$()` / 反引号）会在 allowlist 解析期间被拒绝，包括在
双引号内；如果你需要字面量 `$()` 文本，请使用单引号。
在 macOS 配套应用审批中，包含 shell 控制符
或展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、
`)`）的原始 shell 文本会被视为允许列表未命中，除非 shell 二进制本身已在
允许列表中。
在 macOS 配套应用批准中，包含 Shell 控制
或扩展语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、
`)`）的原始 Shell 文本会被视为 allowlist 未命中，除非 Shell 二进制文件
本身已在允许列表中。
对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求作用域的 env
覆盖会被缩减为一个小型显式允许列表（`TERM`、`LANG`、
对于 Shell 包装器（`bash|sh|zsh ... -c/-lc`），请求作用域的 env
覆盖会被收缩为一个小型显式允许列表（`TERM`、`LANG`、
`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。
对于 `allowlist` 模式下的 `allow-always` 决策，已知分发包装器
对于 allowlist 模式下的 `allow-always` 决策，已知的分发包装器
（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件
路径，而不是包装器路径。Shell 多路复用器（`busybox`、`toybox`）
对 shell applet（`sh`、`ash` 等）也会以相同方式解包。如果某个
包装器或多路复用器无法被安全解包，就不会自动持久化任何允许列表条目。
对其 Shell applet（`sh`、`ash` 等）也会以相同方式解包。如果某个
包装器或多路复用器无法被安全解包，则不会自动持久化任何允许列表条目。
如果你将 `python3` 或 `node` 之类的解释器加入允许列表，建议优先设置
`tools.exec.strictInlineEval=true`，这样内联 eval 仍然需要显式审批。
在严格模式下，`allow-always` 仍可持久化无害的
解释器 / 脚本调用，但内联 eval 载体不会被自动持久化。
如果你将 `python3` 或 `node` 之类的解释器加入允许列表，建议启用
`tools.exec.strictInlineEval=true`，这样内联 eval 仍然需要
显式批准。在严格模式下，`allow-always` 仍然可以持久化无害的
解释器 / 脚本调用，但内联 eval 承载形式不会被自动持久化。
</Accordion>
</AccordionGroup>
</AccordionGroup>
### 安全二进制与允许列表
### 安全二进制文件与 allowlist 的区别
| 主题 | `tools.exec.safeBins` | 允许列表（`exec-approvals.json`） |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| 目标 | 自动允许狭义的 stdin 过滤器 | 显式信任特定可执行文件 |
| 匹配类型 | 可执行文件名 + 安全二进制 argv 策略 | 已解析的可执行文件路径 glob 模式 |
| 参数范围 | 受安全二进制配置和字面 token 规则限制 | 仅匹配路径；其他参数由你自行负责 |
| 主题 | `tools.exec.safeBins` | allowlist（`exec-approvals.json`） |
| ---- | --------------------- | ---------------------------------- |
| 目标 | 自动允许受限的 stdin 过滤器 | 显式信任特定可执行文件 |
| 匹配类型 | 可执行文件名 + 安全二进制文件 argv 策略 | 已解析的可执行文件路径 glob 模式 |
| 参数范围 | 受安全二进制文件 profile 和字面 token 规则限制 | 仅匹配路径；参数的其余部分由你自行负责 |
| 典型示例 | `head`、`tail`、`tr`、`wc` | `jq`、`python3`、`node`、`ffmpeg`、自定义 CLI |
| 最佳用途 | 管道中的低风险文本转换 | 任何具有更广泛行为或副作用的工具 |
| 最佳用途 | 管道中的低风险文本转换 | 任何行为更广泛或具有副作用的工具 |
配置位置：
- `safeBins` 来自配置（`tools.exec.safeBins` 或按智能体的 `agents.list[].tools.exec.safeBins`）。
- `safeBinTrustedDirs` 来自配置（`tools.exec.safeBinTrustedDirs` 或按智能体的 `agents.list[].tools.exec.safeBinTrustedDirs`）。
- `safeBinProfiles` 来自配置（`tools.exec.safeBinProfiles` 或按智能体的 `agents.list[].tools.exec.safeBinProfiles`）。按智能体的配置键会覆盖全局键。
- 允许列表条目存储在主机本地 `~/.openclaw/exec-approvals.json` 的 `agents.<id>.allowlist` 下（或通过 Control UI / `openclaw approvals allowlist ...`）。
- 当解释器 / 运行时二进制出现在 `safeBins` 中但没有显式配置时，`openclaw security audit` 会通过 `tools.exec.safe_bins_interpreter_unprofiled` 发出警告。
- `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles.<bin>` 条目生成 `{}` 脚手架（之后请审查并收紧）。解释器 / 运行时二进制不会被自动生成脚手架。
- `safeBinProfiles` 来自配置（`tools.exec.safeBinProfiles` 或按智能体的 `agents.list[].tools.exec.safeBinProfiles`）。按智能体的 profile 键会覆盖全局键。
- allowlist 条目位于宿主机本地 `~/.openclaw/exec-approvals.json` 中的 `agents.<id>.allowlist` 下（或通过 Control UI / `openclaw approvals allowlist ...`）。
- 当解释器 / 运行时二进制文件出现在 `safeBins` 中但没有显式 profile 时，`openclaw security audit` 会发出 `tools.exec.safe_bins_interpreter_unprofiled` 警告。
- `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles.<bin>` 条目生成 `{}` 骨架（之后请审查并收紧）。解释器 / 运行时二进制文件不会被自动生成骨架。
自定义配置示例：
自定义 profile 示例：
__OC_I18N_900005__
如果你显式将 `jq` 加入 `safeBins`，OpenClaw 在安全二进制
模式下仍会拒绝 `env` 内建命令，因此 `jq -n env` 无法在没有显式允许列表路径
或审批提示的情况下转储主机进程环境。
如果你显式将 `jq` 选择加入 `safeBins`，OpenClaw 在安全二进制文件
模式下仍会拒绝 `env` 内建，因此 `jq -n env` 无法在没有显式 allowlist 路径
或批准提示的情况下转储宿主进程环境。
## 在 Control UI 中编辑
使用 **Control UI → Nodes → 执行审批** 卡片来编辑默认值、按智能体
覆盖项和允许列表。选择一个作用域（默认值或某个智能体），调整策略，
添加 / 删除允许列表模式，然后点击 **Save**。UI 会显示每个模式的**上次使用**
元数据，便于你保持列表整洁。
使用 **Control UI → Nodes → Exec approvals** 卡片来编辑默认值、按智能体的
覆盖项以及 allowlist。选择一个作用域（默认值或某个智能体），调整策略，
添加 / 删除 allowlist 模式，然后点击 **Save**。UI 会显示每个模式的
**上次使用** 元数据，以便你保持列表整洁。
目标选择器可选择 **Gateway**（本地审批）或 **Node**。节点
必须声明 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
如果某个节点尚未声明执行审批，请直接编辑其本地
目标选择器可选择 **Gateway**（本地批准）或 **Node**。节点
必须声明 `system.execApprovals.get/set`（macOS 应用或无头 node 宿主机）。
如果某个节点尚未声明执行批准，请直接编辑它本地的
`~/.openclaw/exec-approvals.json`。
CLI：`openclaw approvals` 支持编辑 Gateway 网关或节点（参见 [Approvals CLI](/cli/approvals)）。
CLI：`openclaw approvals` 支持编辑 gateway 或 node（参见 [Approvals CLI](/cli/approvals)）。
## 审批流程
## 批准流程
当需要提示时，Gateway 网关会向操作员客户端广播 `exec.approval.requested`。
Control UI 和 macOS 应用通过 `exec.approval.resolve` 处理该请求，然后 Gateway 网关再将
已批准的请求转发到节点主机。
当需要提示时，gateway 会向操作员客户端广播 `exec.approval.requested`。
Control UI 和 macOS 应用通过 `exec.approval.resolve` 处理它，然后 gateway 将
已批准的请求转发给 node 宿主机。
对于 `host=node`，审批请求包含一个规范的 `systemRunPlan` 载荷。Gateway 网关会在转发已批准的 `system.run`
请求时，将该计划作为权威的 command / cwd / session 上下文。
对于 `host=node`，批准请求会包含规范化的 `systemRunPlan` 负载。gateway 会在转发已批准的 `system.run`
请求时，将该 plan 作为权威的命令 / cwd / 会话上下文。
这对异步审批延迟很重要：
这对异步批准延迟很重要：
- 节点执行路径会预先准备一个规范计划
- 审批记录会存储该计划及其绑定元数据
- 一旦获批，最终转发的 `system.run` 调用会复用已存储的计划
，而不是信任之后调用方的修改
- 如果调用方在创建审批请求后更改了 `command`、`rawCommand`、`cwd`、`agentId` 或
`sessionKey`，Gateway 网关会将转发的运行拒绝为审批不匹配
- node 执行路径会预先准备一个规范化 plan
- 批准记录会存储该 plan 及其绑定元数据
- 一旦获得批准，最终转发的 `system.run` 调用会复用已存储的 plan
而不是信任调用方之后的修改
- 如果调用方在批准请求创建后更改了 `command`、`rawCommand`、`cwd`、`agentId` 或
`sessionKey`，gateway 会以批准不匹配为由拒绝
该转发执行
## 解释器 / 运行时命令
基于审批的解释器 / 运行时执行有意采用保守策略：
基于批准的解释器 / 运行时执行刻意采取保守策略：
- 始终绑定精确的 argv / cwd / env 上下文。
- 直接 shell 脚本和直接运行时文件形式会尽力绑定到一个具体的本地
- 精确的 argv / cwd / env 上下文始终会被绑定。
- 直接 Shell 脚本和直接运行时文件形式会尽力绑定到一个具体的本地
文件快照。
- 常见的包管理器包装形式如果最终仍解析到一个直接本地文件（例如
`pnpm exec`、`pnpm node`、`npm exec`、`npx`），则会在绑定前解包。
- 如果 OpenClaw 无法为解释器 / 运行时命令准确识别**唯一一个**具体本地文件
（例如包脚本、eval 形式、运行时特定加载链或含糊的多文件
形式），则会拒绝基于审批的执行，而不是声称提供了并不具备的语义覆盖。
- 对于这些工作流，建议优先使用沙箱隔离、单独的主机边界，或显式的受信任
- 仍会解析为单个直接本地文件的常见包管理器包装形式（例如
`pnpm exec`、`pnpm node`、`npm exec`、`npx`）会在绑定前被解包。
- 如果 OpenClaw 无法为某个解释器 / 运行时命令精确识别出唯一一个具体本地文件
（例如包脚本、eval 形式、运行时特定的加载器链，或含糊的多文件
形式），则基于批准的执行会被拒绝，而不是声称具备它实际上并不具备的
语义覆盖能力。
- 对于这些工作流，优先考虑沙箱隔离、单独的宿主边界，或显式受信任的
allowlist / full 工作流，由操作员接受更宽泛的运行时语义。
当需要审批时，执行工具会立即返回一个审批 id。使用该 id 来关联后续系统事件
（`Exec finished` / `Exec denied`）。如果在超时前没有收到决策，
该请求会被视为审批超时，并显示为一个拒绝原因。
当需要批准时，exec 工具会立即返回一个批准 id。使用该 id 来
关联后续系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有收到决定，
该请求会被视为批准超时，并作为拒绝原因呈现。
### 后续消息投递行为
在已批准的异步执行完成后，OpenClaw 会向同一会话发送一个后续 `agent` 轮次。
已批准的异步 exec 完成后，OpenClaw 会向同一会话发送一个后续 `agent` 回合。
- 如果存在有效的外部投递目标（可投递渠道加目标 `to`），后续消息会通过该渠道投递。
- 在仅 webchat 或无外部目标的内部会话流中，后续消息仅保留在会话内（`deliver: false`）。
- 如果调用方显式请求严格的外部投递，但没有可解析的外部渠道，则请求会以 `INVALID_REQUEST` 失败。
- 如果启用了 `bestEffortDeliver` 且无法解析任何外部渠道，投递将降级为仅会话内，而不是失败。
- 如果存在有效的外部投递目标（可投递的渠道加目标 `to`），后续投递会使用该渠道。
- 在仅 webchat 或无外部目标的内部会话流中，后续投递会保持仅会话内（`deliver: false`）。
- 如果调用方显式请求严格的外部投递，但无法解析出外部渠道，则请求会以 `INVALID_REQUEST` 失败。
- 如果启用了 `bestEffortDeliver` 且无法解析出外部渠道，则投递会降级为仅会话内，而不是失败。
确认对话框包含：
确认对话框包括：
- command + args
- cwd
- 智能体 id
- 已解析的可执行文件路径
- host + 策略元数据
- host + policy 元数据
操作：
- **Allow once** → 立即运行
- **Always allow** → 加入允许列表 + 运行
- **Always allow** → 添加到 allowlist + 运行
- **Deny** → 阻止
## 将审批转发到聊天渠道
## 将批准转发到聊天渠道
你可以将执行审批提示转发到任意聊天渠道（包括渠道插件），并通过 `/approve` 完成审批。
这使用的是正常的出站投递流水线。
你可以将执行批准提示转发到任何聊天渠道（包括渠道插件），并通过
`/approve` 批准它们。这使用正常的出站投递管道。
配置：
__OC_I18N_900006__
在聊天中回复：
__OC_I18N_900007__
`/approve` 命令同时处理执行审批和插件审批。如果该 ID 不匹配任何待处理的执行审批，它会自动继续检查插件审批。
`/approve` 命令同时处理执行批准和插件批准。如果该 ID 与待处理的执行批准不匹配，它会自动改为检查插件批准。
### 插件审批转发
### 插件批准转发
插件审批转发使用与执行审批相同的投递流水线，但它在 `approvals.plugin` 下拥有自己
独立的配置。启用或禁用一方不会影响另一方。
插件批准转发使用与执行批准相同的投递管道，但在 `approvals.plugin` 下拥有自己独立的配置。启用或禁用其中一方不会影响另一方。
__OC_I18N_900008__
其配置结构与 `approvals.exec` 完全一致：`enabled`、`mode`、`agentFilter`、
其配置结构与 `approvals.exec` 完全相同：`enabled`、`mode`、`agentFilter`、
`sessionFilter` 和 `targets` 的工作方式相同。
支持共享交互式回复的渠道，会为执行审批和插件
审批都渲染相同的审批按钮。不支持共享交互式 UI 的渠道会回退为纯文本，并附带 `/approve`
说明。
支持共享交互式回复的渠道会为执行批准和插件批准都渲染相同的批准按钮。没有共享交互式 UI 的渠道则会回退为带 `/approve`
说明的纯文本。
### 任意渠道中的同聊天审批
### 任意渠道中的同聊天批准
当执行或插件审批请求来自一个可投递的聊天界面时，现在默认可以在同一聊天中
通过 `/approve` 完成审批。这适用于 Slack、Matrix 和 Microsoft Teams 等渠道，
同时也适用于现有的 Web UI 和终端 UI 流程。
当执行或插件批准请求来自可投递的聊天界面时，现在默认可以在同一聊天中使用 `/approve` 进行批准。这适用于 Slack、Matrix 和 Microsoft Teams 等渠道，以及现有的 Web UI 和终端 UI 流程。
这条共享的文本命令路径使用该会话的正常渠道认证模型。如果发起聊天本来就可以发送命令并接收回复，那么审批请求就不再需要单独的原生投递适配器来保持待处理状态。
这种共享文本命令路径使用该会话的正常渠道认证模型。如果发起聊天本来就可以发送命令并接收回复，那么批准请求就不再需要单独的原生投递适配器才能保持待处理状态。
Discord 和 Telegram 也支持同聊天 `/approve`，但即使禁用了原生审批投递，这些渠道在授权时仍会使用其
已解析的 approver 列表。
Discord 和 Telegram 也支持在同一聊天中使用 `/approve`，但即使禁用了原生批准投递，这些渠道在授权时仍会使用其已解析的批准人列表。
对于 Telegram 以及其他直接调用 Gateway 网关的原生审批客户端，
这种后备路径有意仅限于“未找到审批”失败。真正的
执行审批拒绝 / 错误不会被静默重试为插件审批。
对于 Telegram 和其他直接调用 Gateway 网关的原生批准客户端，
这种回退有意仅限于“未找到批准”失败。真正的
执行批准拒绝 / 错误不会被静默重试为插件批准。
### 原生审批投递
### 原生批准投递
某些渠道也可以充当原生审批客户端。原生客户端会在共享的同聊天 `/approve`
流程之上，增加 approver 私信、原始聊天扇出以及渠道特定的交互式审批 UX。
某些渠道还可以充当原生批准客户端。原生客户端会在共享的同聊天 `/approve`
流程之上，增加批准人私信、来源聊天扇出以及渠道特定的交互式批准 UX。
当原生审批卡片 / 按钮可用时，该原生 UI 是面向
智能体的主要路径。除非工具结果说明聊天审批不可用或
手动审批是唯一剩余路径，否则智能体不应再额外回显重复的纯聊天
当原生批准卡片 / 按钮可用时，该原生 UI 是主要的
智能体面向路径。除非工具结果表明聊天批准不可用，或手动批准是唯一剩余路径，否则智能体不应再额外回显一条重复的纯聊天
`/approve` 命令。
通用模型：
- 主机执行策略仍决定是否需要执行审批
- `approvals.exec` 控制是否将审批提示转发到其他聊天目标
- `channels.<channel>.execApprovals` 控制该渠道是否充当原生审批客户端
- 宿主机执行策略仍决定是否需要执行批准
- `approvals.exec` 控制是否将批准提示转发到其他聊天目标
- `channels.<channel>.execApprovals` 控制该渠道是否充当原生批准客户端
当满足以下所有条件时，原生审批客户端会自动启用私信优先投递：
当以下条件全部满足时，原生批准客户端会自动启用私信优先投递：
- 该渠道支持原生审批投递
- approver 可通过显式 `execApprovals.approvers` 或该
渠道文档说明的后备来源进行解析
- 该渠道支持原生批准投递
- 可以从显式的 `execApprovals.approvers` 或该
渠道文档说明的回退来源解析出批准人
- `channels.<channel>.execApprovals.enabled` 未设置或为 `"auto"`
将 `enabled: false` 设为显式禁用某个原生审批客户端。将 `enabled: true` 设为在 approver 可解析时强制
启用。公共原始聊天投递仍通过
将 `enabled: false` 设为显式禁用某个原生批准客户端。将 `enabled: true` 设为在批准人可解析时强制启用它。公开的来源聊天投递仍通过
`channels.<channel>.execApprovals.target` 显式控制。
常见问题：[为什么聊天审批有两个执行审批配置？](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
FAQ：[为什么聊天批准会有两个执行批准配置？](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
- Discord：`channels.discord.execApprovals.*`
- Slack：`channels.slack.execApprovals.*`
- Telegram：`channels.telegram.execApprovals.*`
这些原生审批客户端会在共享的
同聊天 `/approve` 流程和共享审批按钮之上，增加私信路由和可选的渠道扇出。
这些原生批准客户端会在共享的同聊天 `/approve` 流程和共享批准按钮之上，
增加私信路由和可选的渠道扇出。
共享行为：
- Slack、Matrix、Microsoft Teams 以及类似的可投递聊天会对同聊天 `/approve` 使用正常的渠道认证模型
- 当原生审批客户端自动启用时，默认的原生投递目标是 approver 私信
- 对于 Discord 和 Telegram，只有已解析的 approver 才能批准或拒绝
- Discord approver 可以是显式配置（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断
- Telegram approver 可以是显式配置（`execApprovals.approvers`），也可以从现有 owner 配置推断（`allowFrom`，以及在支持时用于私信的 `defaultTo`）
- Slack approver 可以是显式配置（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断
- Slack 原生按钮会保留审批 id 类型，因此 `plugin:` id 可以解析插件审批，
无需第二层 Slack 本地后备逻辑
- Matrix 原生私信 / 渠道路由和反应快捷方式同时处理执行审批和插件审批；
- Slack、Matrix、Microsoft Teams 以及类似的可投递聊天使用正常的渠道认证模型
处理同聊天 `/approve`
- 当原生批准客户端自动启用时，默认的原生投递目标是批准人私信
- 对于 Discord 和 Telegram，只有已解析的批准人可以批准或拒绝
- Discord 批准人可以显式指定（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断
- Telegram 批准人可以显式指定（`execApprovals.approvers`），也可以从现有的所有者配置推断（`allowFrom`，以及在支持时的私信 `defaultTo`）
- Slack 批准人可以显式指定（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断
- Slack 原生按钮会保留批准 id 类型，因此 `plugin:` id 可以解析为插件批准，
而无需第二层 Slack 本地回退
- Matrix 原生私信 / 渠道路由和表情快捷方式同时处理执行批准和插件批准；
插件授权仍来自 `channels.matrix.dm.allowFrom`
- 请求者不需要是 approver
- 当原始聊天本身已支持命令和回复时，该聊天可以直接通过 `/approve` 完成审批
- 原生 Discord 审批按钮按审批 id 类型路由：`plugin:` id 会
直接进入插件审批，其余所有内容进入执行审批
- 原生 Telegram 审批按钮遵循与 `/approve` 相同的、受限的 exec 到插件后备逻辑
- 当原生 `target` 启用原始聊天投递时，审批提示会包含命令文本
- 待处理的执行审批默认会在 30 分钟后过期
- 如果没有操作员 UI 或已配置的审批客户端可以接受请求，提示将回退到 `askFallback`
- 请求者不需要是批准人
- 如果来源聊天已支持命令和回复，则可直接在该聊天中通过 `/approve` 批准
- 原生 Discord 批准按钮按批准 id 类型路由：`plugin:` id 会
直接进入插件批准，其他所有内容都进入执行批准
- 原生 Telegram 批准按钮遵循与 `/approve` 相同的有界执行到插件回退
- 当原生 `target` 启用来源聊天投递时，批准提示会包含命令文本
- 待处理的执行批准默认在 30 分钟后过期
- 如果没有操作员 UI 或已配置的批准客户端可接受请求，则提示会回退到 `askFallback`
Telegram 默认发送到 approver 私信（`target: "dm"`）。当你
希望审批提示也出现在发起的 Telegram 聊天 / 话题中时，可以切换为 `channel` 或 `both`。对于 Telegram 论坛
话题，OpenClaw 会为审批提示和审批后的后续消息保留该话题。
Telegram 默认发送到批准人私信（`target: "dm"`）。如果你希望批准提示也显示在来源 Telegram 聊天 / 话题中，可以切换为 `channel` 或 `both`。对于 Telegram 论坛话题，OpenClaw 会保留该话题用于批准提示和批准后的后续消息。
参见：
@ -543,36 +542,36 @@ __OC_I18N_900009__
安全说明：
- Unix socket 模式为 `0600`，token 存储在 `exec-approvals.json` 中。
- 同 UID 对端检查。
- 同 UID 对等端检查。
- 质询 / 响应（nonce + HMAC token + 请求哈希）+ 短 TTL。
## 系统事件
执行生命周期会显示为系统消息：
执行生命周期会以系统消息的形式呈现：
- `Exec running`（仅当命令超过运行中通知阈值时）
- `Exec finished`
- `Exec denied`
这些消息会在节点报告事件后发布到智能体的会话中。
Gateway 网关主机执行审批在命令完成时也会发出相同的生命周期事件（如果运行时间超过阈值，还会可选发出运行中事件）。
受审批门控的执行会在这些消息中复用审批 id 作为 `runId`，便于关联。
这些事件会在节点上报该事件后发布到智能体的会话中。
Gateway 宿主机执行批准在命令完成时也会发出相同的生命周期事件（如果运行时间超过阈值，也可选择在运行中发出）。
受批准门控的执行会在这些消息中复用批准 id 作为 `runId`，便于关联。
## 审批被拒绝时的行为
## 批准被拒绝时的行为
当异步执行审批被拒绝时，OpenClaw 会阻止智能体复用
该会话中此前同一命令任何早期运行的输出。拒绝原因
会连同明确说明一起传递，指出没有可用的命令输出，从而阻止
智能体声称存在新的输出，或使用先前成功运行留下的陈旧结果
当异步执行批准被拒绝时，OpenClaw 会阻止智能体复用
该会话中此前相同命令的任何运行输出。拒绝原因
会附带明确指引，说明没有可用的命令输出，从而阻止
智能体声称有新的输出，或使用先前成功运行的陈旧结果
重复被拒绝的命令。
## 影响
- **full** 权限很强；如果可能，优先使用允许列表。
- **ask** 让你保持在流程中，同时仍支持快速审批。
- 按智能体划分的允许列表可防止某个智能体的审批泄漏到其他智能体。
- 审批仅适用于来自**已授权发送方**的主机执行请求。未授权发送方无法发出 `/exec`。
- `/exec security=full` 是已授权操作员的会话级便捷方式，并且按设计会跳过审批。要硬性阻止主机执行，请将审批安全级别设为 `deny`，或通过工具策略拒绝 `exec` 工具。
- **full** 很强大；尽可能优先使用 allowlist。
- **ask** 让你保持在决策环中，同时仍支持快速批准。
- 按智能体划分的 allowlist 可防止某个智能体的批准泄漏给其他智能体。
- 批准仅适用于来自**已授权发送方**的宿主机执行请求。未授权发送方无法发出 `/exec`。
- `/exec security=full` 是面向已授权操作员的会话级便捷方式，并且按设计会跳过批准。若要硬性阻止宿主机执行，请将批准安全性设为 `deny`，或通过工具策略拒绝 `exec` 工具。
## 相关内容
@ -580,19 +579,19 @@ Gateway 网关主机执行审批在命令完成时也会发出相同的生命周
<Card title="Exec 工具" href="/zh-CN/tools/exec" icon="terminal">
Shell 命令执行工具。
</Card>
<Card title="提权模式" href="/zh-CN/tools/elevated" icon="shield-exclamation">
同时跳过审批的破窗应急路径。
<Card title="Elevated 模式" href="/zh-CN/tools/elevated" icon="shield-exclamation">
同样会跳过批准的紧急放行路径。
</Card>
<Card title="沙箱隔离" href="/zh-CN/gateway/sandboxing" icon="box">
沙箱模式和工作区访问。
</Card>
<Card title="安全" href="/zh-CN/gateway/security" icon="lock">
安全模型和加固。
安全模型与加固。
</Card>
<Card title="沙箱 vs 工具策略 vs 提权" href="/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated" icon="sliders">
何时使用每种控制方式。
<Card title="沙箱隔离 vs 工具策略 vs elevated" href="/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated" icon="sliders">
何时应使用各项控制。
</Card>
<Card title="Skills" href="/zh-CN/tools/skills" icon="sparkles">
由 Skills 支持的自动允许行为。
由 skill 支持的自动允许行为。
</Card>
</CardGroup>