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 23:29:34 +00:00
parent 35f8c20f25
commit a319837e6b
12 changed files with 2666 additions and 2584 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1614
docs/zh-CN/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

@ -1,399 +1,139 @@
---
read_when:
- 你需要知道应从哪个 SDK 子路径导入】【：】【“】【analysis to=functions.read 娱乐总代理 天天众json 801 content omitted due to length?
- 你想要一份关于 OpenClawPluginApi 上所有注册方法的参考文档
- 你正在查找某个特定的 SDK 导出
- 你需要知道应从哪个 SDK 子路径导入
- 你想要一份关于 OpenClaw 上所有注册方法的参考资料
- 你正在查找特定的 SDK 导出项
sidebarTitle: SDK overview
summary: 导入映射、注册 API 参考和 SDK 架构
title: 插件 SDK 概览
summary: Import map、注册 API 参考和 SDK 架构
title: 插件 SDK SDK 概览
x-i18n:
generated_at: "2026-04-23T20:57:51Z"
generated_at: "2026-04-23T23:21:57Z"
model: gpt-5.4
provider: openai
source_hash: efe676e4907428459ed3e30dd2e1df891eae0f0f1e87b0a850eb45140572a348
source_hash: 7090e13508382a68988f3d345bf12d6f3822c499e01a3affb1fa7a277b22f276
source_path: plugins/sdk-overview.md
workflow: 15
---
插件 SDK 是插件与 core 之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考文档。
插件 SDK 是插件与核心之间的类型化契约。本页是关于**应导入什么**以及**你可以注册什么**的参考资料。
<Tip>
在找操作指南而不是参考文档？
想找操作指南而不是参考文档？
- 第一个插件？从 [Building plugins](/zh-CN/plugins/building-plugins) 开始。
- 渠道插件？参见 [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins)。
- 提供商插件？参见 [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins)。
- 第一个插件？从 [构建插件](/zh-CN/plugins/building-plugins) 开始。
- 渠道插件？参见 [频道插件](/zh-CN/plugins/sdk-channel-plugins)。
- 提供者插件？参见 [提供商插件](/plugins.sdk/provider-plugins)。
</Tip>
## 导入约定
始终从某个特定子路径导入：
始终从特定子路径导入：
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
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`。
<Warning>
不要导入带有提供商或渠道品牌的便捷接缝（例如
`openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。
不要导入面向提供者或渠道品牌的便捷接缝（例如
`openclaw/plugin_sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。
内置插件会在它们自己的 `api.ts` /
`runtime-api.ts` barrel 中组合通用 SDK 子路径；core 使用方要么应使用这些插件本地的
barrel，要么在需求确实跨渠道时添加一个狭义的通用 SDK 契约。
`runtime-api.ts` barrel 中组合通用 SDK 子路径；核心使用者应改为使用这些插件本地的
barrel，或者在需求确实跨渠道时添加一个狭义的通用 SDK 契约。
一小部分内置插件辅助接缝（`plugin-sdk/feishu`、
`plugin-sdk/zalo`、`plugin-sdk/matrix*` 等）仍会出现在
生成的导出映射中。它们仅供内置插件维护使用，并
不推荐作为新的第三方插件导入路径。
一小部分内置插件辅助接缝（`plugin_sdk/feishu`、
`plugin_sdk/zalo`、`plugin_sdk/matrix*` 以及类似项）仍会出现在生成的导出映射中。它们仅用于内置插件维护，不推荐作为新的第三方插件导入路径。
</Warning>
## 子路径参考
下面列出最常用的子路径，并按用途分组。完整的 200+
个子路径的生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；保留的
内置插件辅助子路径也会出现在那里，但除非某个文档页面明确推荐，
否则它们属于实现细节。
插件 SDK 以一组按领域分组的狭义子路径公开（插件入口、渠道、提供者、传输、能力以及保留的内置插件辅助项）。完整目录——按组整理并带链接——请参见
[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。
### 插件入口
| 子路径 | 关键导出 |
| ------ | -------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="渠道子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `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/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/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/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-runtime` | 出站 identity、发送委托和负载规划辅助工具 |
| `plugin-sdk/poll-runtime` | 狭义 poll 规范化辅助工具 |
| `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` | 语义消息呈现、交付和旧版交互式回复辅助工具。参见 [Message Presentation](/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-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈/reaction 接线 |
| `plugin-sdk/channel-secret-runtime` | 狭义 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 |
</Accordion>
<Accordion title="提供商子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 经过整理的本地/自托管提供商设置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管提供商设置的辅助工具 |
| `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-result` | 标准 OAuth auth-result 构建器 |
| `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` 之类的模型 id 规范化辅助工具 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-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/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 辅助工具 |
</Accordion>
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 |
| `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Approver 解析和同聊天 action-auth 辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec approval profile/filter 辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 原生 approval 能力/交付适配器 |
| `plugin-sdk/approval-gateway-runtime` | 共享 approval gateway 解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量原生 approval 适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的 approval handler 运行时辅助工具；当狭义 adapter/gateway 接缝已足够时，应优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 原生 approval 目标 + 账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | Exec/plugin approval 回复负载辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助工具 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret 表面的狭义 secret 契约收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 用于 secret-contract/配置解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助工具 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不引入广泛 infra 运行时表面的狭义 pinned-dispatcher 辅助工具 |
| `plugin-sdk/ssrf-runtime` | Pinned-dispatcher、受 SSRF 防护的 fetch，以及 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | Secret 输入解析辅助工具 |
| `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
</Accordion>
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 狭义运行时环境、logger、超时、重试和退避辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享插件命令/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-sdk/telegram-command-config` | Telegram 命令名/描述规范化及重复/冲突检查，即使内置 Telegram 契约表面不可用时也适用 |
| `plugin-sdk/text-autolink-runtime` | 不引入广泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | Exec/plugin approval 辅助工具、approval 能力构建器、认证/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/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/json-store` | 小型 JSON 状态读写辅助工具 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
| `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和 reply-dispatch 辅助工具 |
| `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 和配对 token 辅助工具 |
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/build/serialize 辅助工具 |
| `plugin-sdk/agent-harness` | 面向可信插件的实验性低层智能体 harness 表面：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具，以及尝试结果工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 |
| `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装过的 fetch、代理和 pinned lookup 辅助工具 |
| `plugin-sdk/runtime-fetch` | 不引入 proxy/guarded-fetch 的 dispatcher-aware 运行时 fetch |
| `plugin-sdk/response-limit-runtime` | 不引入广泛 media 运行时表面的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 |
| `plugin-sdk/session-store-runtime` | 不引入广泛配置写入/维护导入的会话存储读取辅助工具 |
| `plugin-sdk/context-visibility-runtime` | 不引入广泛配置/安全导入的上下文可见性解析和补充上下文过滤 |
| `plugin-sdk/string-coerce-runtime` | 不引入 markdown/logging 的狭义原语 record/string 强制转换与规范化辅助工具 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
| `plugin-sdk/agent-runtime` | 智能体目录/identity/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/日志辅助工具，例如去除 assistant 可见文本、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具，以及安全文本工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | Speech 提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 |
| `plugin-sdk/speech-core` | 共享 speech 提供商类型、注册表、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` |
</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 host foundation 引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host storage 引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 |
| `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 core 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 面向供应商中立的 memory host core 运行时辅助工具别名 |
| `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` | 面向搜索管理器访问的活动 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 插件支持辅助工具（`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-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-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
生成的 300 多个子路径列表位于 `scripts/lib/plugin_sdk_entrypoints.json`。
## 注册 API
`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，其中包含以下
方法：
`register(api)` 回调会收到一个带有以下方法的 `OpenClaw/TalkTo` 对象：
### 能力注册
| 方法 | 注册内容 |
| ---- | -------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerAgentHarness(...)` | 实验性的低层智能体执行器 |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | Text-to-speech / 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.registerCliChannel(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息通道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `dialog.registerReal-timeTranscriptionProvider(...)` | 流式实时转写 |
| `context.registerReal-timeVoiceProvider(...)` | 复用实时语音会话 |
| `available.registerMediaUnderstandingProvider(...)` | 图像 / 音频 / 视频分析 |
| `context.registerImageGenerationProvider(...)` | 图像生成 |
| `context.registerMusicGenerationProvider(...)` | 音乐生成 |
| `context.registerVideoGenerationProvider(...)` | 视频生成 |
| `context.registerWebProvider(...)` | Web 获取 / 抓取提供者 |
| `context.registerWebSearchProvider(...)` | Web 搜索 |
### 工具与命令
### 工具和命令
| 方法 | 注册内容 |
| ---- | -------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必选或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
| 方法 | 注册内容 |
| ------------------------------- | --------------------------------------------- |
| `ctx.registerTool(tool, opts?)` | 智能体工具（必需或使用 `{ optional: true }`） |
| `ctx.registerCommand(def)` | 自定义命令（绕过 LLM） |
### 基础设施
| 方法 | 注册内容 |
| ---- | -------- |
| `api.registerHook(events, handler, opts?)` | 事件 hook |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
| `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 搜索/读取语料库 |
| 方法 | 注册内容 |
| ----------------------------------------------- | ----------------------------------------- |
| `ctx.registerHook(events, handler, opts?)` | 事件钩子 |
|
| `dialog.registerHttpRoute(params)` | Gateway 网关的 HTTP |
| `timity.registerGatewayMethod(name, handler)` | Gateway 远程方法 |
| `act.registerCl(registrar, opts?)` | CLI 子命令 |
| `network.registerSurface(surface)` | 后台外 |
| `operator.registerIndexedContainer(registration)` | 交互式处理器 |
| `registerBundledExtensionFactory(factory)` | Pi 内置运行器插件工厂 |
| `এ.registerMemoryPromptSupplement(builder)` | 添加式内存邻接提示区段 |
| `at.registerMemoryCorpusSupplement(adapter)` | 添加式内存搜索 / 读取语料 |
<Note>
保留的 core 管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、
`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的
gateway method scope 也是如此。对于插件自有的方法，请优先使用插件专用前缀。
保留的核心管理命名空间（`config.*`、`agents/approvals.*`、`gateway.*`、
`upgrade.*`）始终保留在 `operator.administration` 下，即使插件尝试分配更窄的
Gateway 操限作用域也是如此。对于插件拥有的方法，优先使用插件特定前缀。
</Note>
<Accordion title="何时使用 registerEmbeddedExtensionFactory">
当插件需要在 OpenClaw 嵌入式运行期间获得 Pi 原生事件时序时，请使用 `api.registerEmbeddedExtensionFactory(...)`
—— 例如必须在最终 tool-result 消息发出之前完成的异步 `tool_result`
重写。
<Accordion title="何时使用 registerBundledExtensionFactory">
当插件在 OpenClaw 内置运行期间需要 Pi 原生的发出时序时，请使用
`api.registerEmbeddedExtensionFactory(...)` —— 例如那些必须在最终工具结果消息发出之前发生的异步
`tool_result` 重写。
这目前是一个内置插件专用接缝：只有内置插件可以注册它，
并且它们必须在
`openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。
对于一切不需要这种更底层接缝的情况，请继续使用普通的 OpenClaw 插件 hook。
这是当前的内置插件接缝：只有内置插件可以注册它，并且它们必须在
`openclaw.plugin.json` 中声明 `contracts.embeddedFactories: ["cli"]`。
对于所有不需要该更低层接缝的场景，请继续使用普通的 OpenClaw 钩子。
</Accordion>
### CLI 注册元数据
`api.registerCli(registrar, opts?)` 接受两类顶层元数据：
`ctx.registerCl(registrar, opts?)` 接受两类顶层元数据：
- `commands`：由 registrar 拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符
- `commands`：由注册器拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和懒加载插件 CLI 注册的解析时命令描述符
如果你希望某个插件命令在普通根 CLI 路径中保持延迟加载，
请提供 `descriptors`，覆盖该 registrar 暴露的每一个顶层命令根。
如果你希望插件命令在正常根 CLI 路径中保持懒加载，请提供覆盖该注册器暴露的每个顶层命令根的 `descriptors`。
```typescript
api.registerCli(
ctx.registerCl(
async ({ program }) => {
const { registerMatrixCli } = await import("./src/cli.js");
registerMatrixCli({ program });
registerMatrixCLI({ program });
},
{
descriptors: [
{
name: "matrix",
description: "Manage Matrix accounts, verification, devices, and profile state",
description: "管理 Matrix 账户、验证、设备和配置文件状态",
hasSubcommands: true,
},
],
@ -401,147 +141,142 @@ api.registerCli(
);
```
仅当你不需要延迟根 CLI 注册时，才单独使用 `commands`。
这种急切兼容路径仍然受支持，但它不会为解析时延迟加载安装
descriptor 支持的占位符。
只有在你不需要懒加载根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会为解析时懒加载安装带描述符支撑的占位符。
### CLI 后端注册
### CLI 执行器注册
`api.registerCliBackend(...)` 允许插件拥有本地
AI CLI 后端（如 `codex-cli`）的默认配置。
`ctx.registerCliBackend(...)` 让插件拥有像 `codex-cli` 这样的本地 AI CLI 后端的默认配置。
- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。
- 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的结构。
- 用户配置仍然优先。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.<id>` 合并覆盖到
插件默认值之上。
- 当某个后端在合并后需要兼容性重写时（例如规范化旧版 flag 结构），请使用 `normalizeConfig`。
- 该后端的 `id` 会成为诸如 `codex-cli/gpt-5` 这类模型引用中的提供者前缀。
- 该后端的 `config` 与 `providers.defaults.cliBackends.<id>` 采用相同结构。
- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将
`providers.defaults.cliBackends.<id>` 合并到插件默认值之上。
- 当某个后端在合并后需要兼容性重写时，请使用 `normalizeConfig`
（例如标准化旧的标志形状）。
### 排他 slot
### 独占槽位
| 方法 | 注册内容 |
| ---- | -------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（同一时间只能激活一个）。`assemble()` 回调会收到 `availableTools` 和 `citationsMode`，以便引擎能定制提示附加内容。 |
| `api.registerMemoryCapability(capability)` | 统一 memory 能力 |
| `api.registerMemoryPromptSection(builder)` | Memory 提示段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | Memory flush 计划解析器 |
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
| 方法 | 注册内容 |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctx.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个活动项）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便该引擎定制提示补充。 |
| `ctx.registerMemoryCapability(capability)` | 统一内存能力 |
| `tool.registerMemoryPromptSection(builder)` | 内存提示区段构建器 |
| `ctx.registerMemoryFlushPlan(resolver)` | 内存刷新计划解析器 |
| `ctx.registerMemoryRuntime(runtime)` | 内存运行时适配器 |
### Memory embedding 适配器
### 内存嵌入适配器
| 方法 | 注册内容 |
| ---- | -------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | 供活动插件使用的 memory embedding 适配器 |
| 方法 | 注册内容 |
| ---------------------------------------------- | ---------------------------------------------- |
| `ctx.registerMemoryEmbeddingProvider(adapter)` | 活动插件的内存嵌入适配器 |
- `registerMemoryCapability` 是首选的排他型 memory 插件 API。
- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`，
- `registerMemoryCapability` 是首选的独占内存-插件 API。
- `registerMemoryCapability` 也可以公开 `publicArtifacts.listArtifacts(...)`，
以便配套插件可以通过
`openclaw/plugin-sdk/memory-host-core` 消费已导出的 memory 产物，而不是深入某个
memory 插件的私有布局。
`openclaw/plugin_sdk/memory/core` 使用导出的内存工件，而不是深入某个特定
内存插件的私有布局。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和
`registerMemoryRuntime` 是兼容 legacy 的排他型 memory 插件 API。
- `registerMemoryEmbeddingProvider` 允许活动 memory 插件注册一个
或多个 embedding 适配器 id（例如 `openai`、`gemini` 或某个自定义
插件定义 id）。
- 像 `agents.defaults.memorySearch.provider` 和
`agents.defaults.memorySearch.fallback` 这样的用户配置，
会针对这些已注册的适配器 id 进行解析。
`registerMemoryRuntime` 是兼容旧版的独占内存-插件 API。
- `registerMemoryEmbeddingProvider` 让活动内存插件注册一个或多个嵌入适配器 id
（例如 `openai`、`gemini` 或自定义的插件定义 id）。
- 用户配置（如 `providers.defaults.memorySearch.provider` 和
`providers.defaults.memorySearch.fallback`）会解析到这些已注册的
适配器 id。
### 事件与生命周期
| 方法 | 作用 |
| ---- | ---- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
| `api.onConversationBindingResolved(handler)` | 会话绑定解析回调 |
| 方法 | 它的作用 |
| -------------------------------------------- | ----------------------------- |
| `ctx.on(hookName, handler, opts?)` | 类型化生命周期钩子 |
| `ctx.onConversationBindingResolved(handler)` | 会话绑定回调 |
### Hook 决策语义
### 钩子决策语义
- `before_tool_call`：返回 `{ block: true }` 是终结性决策。一旦任意 handler 设置了它，就会跳过更低优先级的 handler。
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决策（等同于省略 `block`），而不是覆盖前面的决策。
- `before_install`：返回 `{ block: true }` 是终结性决策。一旦任意 handler 设置了它，就会跳过更低优先级的 handler。
- `before_install`：返回 `{ block: false }` 会被视为未作决策（等同于省略 `block`），而不是覆盖前面的决策。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终结性决策。一旦任意 handler 声明已处理分发，就会跳过更低优先级的 handler 以及默认的模型分发路径。
- `message_sending`：返回 `{ cancel: true }` 是终结性决策。一旦任意 handler 设置了它，就会跳过更低优先级的 handler。
- `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`：在回退到特定渠道 `metadata` 之前，优先使用类型化的 `replyToId` / `threadId` 路由字段。
- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 来处理插件拥有的的启动状态，而不要依赖内部的 `section:startup` 钩子。
### 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` | [Runtime helpers](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动前的轻量 setup 窗口 |
| `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` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） |
| `api.setupMode` | `PluginSetupMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动 / 设置之前的轻量级预启动 / 设置窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
## 内部模块约定
在你的插件内部，请使用本地 barrel 文件进行内部导入：
在你的插件中，使用本地 barrel 文件进行内部导入：
```
my-plugin/
api.ts # 供外部使用方使用的公共导出
runtime-api.ts # 仅限内部使用的运行时导出
api.ts # 面向外部使用者的公共导出
runtime-api.ts # 仅限内部的运行时导出
index.ts # 插件入口点
setup-entry.ts # 仅 setup 的轻量入口（可选）
setup-entry.ts # 仅设置的轻量级入口（可选）
```
<Warning>
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
导入你自己的插件。请通过 `./api.ts` 或
`./runtime-api.ts` 进行内部导入。SDK 路径只应该作为外部契约使用。
永远不要在生产代码中通过 `openclaw/plugin_sdk/<your-plugin>`
导入你自己的插件。内部导入应通过 `./api.ts` 或
`./runtime-api.ts`。SDK 路径只是外部契约。
</Warning>
以门面方式加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、
`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）会在 OpenClaw 已运行时
优先使用活动运行时配置快照。如果运行时快照尚不存在，
则回退到磁盘上已解析的配置文件。
由门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、
`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）在 OpenClaw 已经运行时，
会优先使用活动运行时配置快照。如果运行时快照尚不存在，
它们会回退到磁盘上解析得到的配置文件。
当某个辅助工具确实属于提供商专用、而尚不适合进入通用 SDK
子路径时，提供商插件可以暴露一个狭义的插件本地契约 barrel。内置示例：
提供者插件可以公开一个狭义的插件本地契约 barrel，当某个辅助函数明确是提供者特定的、且暂时不属于通用 SDK 子路径时。内置示例：
- **Anthropic**：公共 `api.ts` / `contract-api.ts` 接缝，用于 Claude
beta-header 和 `service_tier` 流辅助工具。
- **`@openclaw/openai-provider`**：`api.ts` 导出 provider 构建器、
默认模型辅助工具以及 realtime provider 构建器。
- **`@openclaw/openrouter-provider`**：`api.ts` 导出 provider 构建器
以及 onboarding/config 辅助工具。
- **Anthropic**：用于 Claude
beta header 和 `service_tier` 流辅助函数的公共 `api.ts` / `contract-api.ts` 接缝。
- **`@openclaw/openai-provider`**：`api.ts` 导出提供者构建器、
默认模型辅助函数和实时提供者构建器。
- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供者构建器，
以及新手引导 / 配置辅助函数。
<Warning>
Extension 生产代码也应避免导入 `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>
## 相关内容
<CardGroup cols={2}>
<Card title="Entry Points" icon="door-open" href="/zh-CN/plugins/sdk-entrypoints">
<Card title="入口点" icon="door-open" href="/zh-CN/plugins/sdk-entrypoints">
`definePluginEntry` 和 `defineChannelPluginEntry` 选项。
</Card>
<Card title="Runtime helpers" icon="gears" href="/zh-CN/plugins/sdk-runtime">
<Card title="运行时辅助函数" icon="gears" href="/zh-CN/plugins/sdk-runtime">
完整的 `api.runtime` 命名空间参考。
</Card>
<Card title="Setup and config" icon="sliders" href="/zh-CN/plugins/sdk-setup">
打包、manifest 和配置 schema。
<Card title="设置和配置" icon="sliders" href="/zh-CN/plugins/sdk-setup">
打包、清单和配置模式。
</Card>
<Card title="Testing" icon="vial" href="/zh-CN/plugins/sdk-testing">
<Card title="测试" icon="vial" href="/zh-CN/plugins/sdk-testing">
测试工具和 lint 规则。
</Card>
<Card title="SDK migration" icon="arrows-turn-right" href="/zh-CN/plugins/sdk-migration">
<Card title="SDK 迁移" icon="arrows-turn-right" href="/zh-CN/plugins/sdk-migration">
从已弃用表面迁移。
</Card>
<Card title="Plugin internals" icon="diagram-project" href="/zh-CN/plugins/architecture">
深入架构和能力模型。
<Card title="插件内部机制" icon="diagram-project" href="/zh-CN/plugins/architecture">
深入了解架构和能力模型。
</Card>
</CardGroup>

278
docs/zh-CN/plugins/sdk-subpaths.md Normal file
View File

@ -0,0 +1,278 @@
---
read_when:
- 为插件导入选择合适的 plugin-sdk 子路径
- 审查 bundled-plugin 子路径和辅助接口 surface
summary: 插件 SDK 子路径目录：按领域分组，各导入位于何处
title: 插件 SDK 子路径
x-i18n:
generated_at: "2026-04-23T23:21:51Z"
model: gpt-5.4
provider: openai
source_hash: b0a1d4c2e2d4af147a21716e5240cb3be35ccde9f1d8dea3fc98ae87d3e6ca40
source_path: plugins/sdk-subpaths.md
workflow: 15
---
插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径公开。
本页按用途对常用子路径进行归类。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；
其中也会出现为 bundled-plugin 预留的辅助子路径，但除非文档页面明确将其作为正式能力介绍，否则它们属于实现细节。
关于插件编写指南，请参见 [插件 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` |
<AccordionGroup>
<Accordion title="渠道子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `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/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户配置 / action-gate 辅助函数，以及默认账户回退辅助函数 |
| `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 自定义命令规范化 / 校验辅助函数，带 bundled-contract 回退 |
| `plugin-sdk/command-gating` | 精简的命令授权 gate 辅助函数 |
| `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-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-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈 / reaction 连接 |
| `plugin-sdk/channel-secret-runtime` | 精简的 secret-contract 辅助函数，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 |
</Accordion>
<Accordion title="提供商子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商设置的专用辅助函数 |
| `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-result` | 标准 OAuth auth-result 构建器 |
| `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 辅助函数，以及模型 ID 规范化辅助函数，例如 `normalizeNativeXaiModelId` |
| `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-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 / 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 辅助函数 |
</Accordion>
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 |
| `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | approver 解析和同聊天 action-auth 辅助函数 |
| `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-sdk/command-auth-native` | 原生命令认证 + 原生 session-target 辅助函数 |
| `plugin-sdk/command-detection` | 共享命令检测辅助函数 |
| `plugin-sdk/command-surface` | 命令正文规范化和命令接口辅助函数 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret surface 的精简 secret-contract 收集辅助函数 |
| `plugin-sdk/secret-ref-runtime` | 面向 secret-contract / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助函数 |
| `plugin-sdk/security-runtime` | 共享信任、私信 gate、外部内容和 secret 收集辅助函数 |
| `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` | secret 输入解析辅助函数 |
| `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助函数 |
| `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 |
</Accordion>
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广泛的运行时 / 日志 / 备份 / 插件安装辅助函数 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和退避辅助函数 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助函数 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享插件命令 / 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-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化，以及重复 / 冲突检查，即使 bundled Telegram contract surface 不可用时也可使用 |
| `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/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 精简的文本 / Markdown 分块辅助函数 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 |
| `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助函数 |
| `plugin-sdk/routing` | 路由 / session-key / 账户绑定辅助函数，例如 `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/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` | 精简的智能体运行时 config-schema 基元 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 |
| `plugin-sdk/device-bootstrap` | 设备 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` | 面向受信任插件的实验性低层智能体 harness 接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数，以及尝试结果工具函数 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 |
| `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned lookup 辅助函数 |
| `plugin-sdk/runtime-fetch` | 不引入 proxy / guarded-fetch 的 dispatcher-aware 运行时 fetch |
| `plugin-sdk/response-limit-runtime` | 不依赖广泛 media-runtime 接口的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 不包含已配置绑定路由或配对存储的当前会话绑定状态 |
| `plugin-sdk/session-store-runtime` | 不引入广泛配置写入 / 维护导入的会话存储读取辅助函数 |
| `plugin-sdk/context-visibility-runtime` | 不引入广泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 |
| `plugin-sdk/string-coerce-runtime` | 不引入 markdown / logging 的精简原始记录 / 字符串强制转换与规范化辅助函数 |
| `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-generation-runtime` | 共享媒体生成故障转移辅助函数、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本 / Markdown / 日志辅助函数，例如面向 assistant 可见文本剥离、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` |
</Accordion>
<Accordion title="Memory 子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于 manager / config / file / CLI 辅助函数 |
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时 facade |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机 embedding 契约、注册表访问、本地 provider，以及通用批处理 / 远程辅助函数 |
| `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 主机 secret 辅助函数 |
| `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` | 用于 search-manager 访问的活动 memory 运行时 facade |
| `plugin-sdk/memory-host-status` | 面向供应商中立的 memory 主机状态辅助函数别名 |
| `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 |
</Accordion>
<Accordion title="预留的 bundled-helper 子路径">
| 分类 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| 浏览器 | `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-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/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` | bundled 渠道兼容性 / 辅助接口 |
| 认证 / 插件专用辅助函数 | `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` | bundled 功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## 相关内容
- [插件 SDK 概览](/zh-CN/plugins/sdk-overview)
- [插件 SDK 设置](/zh-CN/plugins/sdk-setup)
- [构建插件](/zh-CN/plugins/building-plugins)

88
docs/zh-CN/reference/test.md
View File

@ -1,51 +1,51 @@
---
read_when:
- 运行或修复测试
summary: 如何在本地运行测试（vitest），以及何时使用 force/coverage 模式
summary: 如何在本地运行测试（vitest），以及何时使用 force / coverage 模式
title: 测试
x-i18n:
generated_at: "2026-04-23T22:14:42Z"
generated_at: "2026-04-23T23:21:48Z"
model: gpt-5.4
provider: openai
source_hash: 3753fd6f29598318f15a34e623a06fac80430cae34d6b42ad06657a46c72fc54
source_hash: 1224c2c0fc4b96a6631ba238e4e9b13ed61e918282db393df7a9db93b3fbf8cf
source_path: reference/test.md
workflow: 15
---
- 完整测试工具包（测试套件、实时测试、Docker）：[测试](/zh-CN/help/testing)
- 完整测试工具包（测试套件、live、Docker）：[测试](/zh-CN/help/testing)
- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，这样服务端测试就不会与正在运行的实例发生冲突。当先前的 Gateway 网关运行导致端口 `18789` 仍被占用时，使用此命令。
- `pnpm test:coverage`：通过 V8 覆盖率运行单元测试套件（使用 `vitest.unit.config.ts`）。这是一个针对已加载文件的单元覆盖率门禁，而不是整个仓库的全文件覆盖率。阈值为：行数/函数/语句 70%，分支 55%。由于 `coverage.all` 为 false，该门禁衡量的是单元覆盖率测试套件加载的文件，而不是将拆分测试通道中的每个源文件都视为未覆盖。
- `pnpm test:coverage:changed`：仅针对相对于 `origin/main` 发生变更的文件运行单元覆盖率。
- `pnpm test:changed`：当 diff 只涉及可路由的源文件/测试文件时，会将变更的 Git 路径展开为有作用域的 Vitest 通道。配置/设置变更仍会回退到原生根项目运行方式，这样在确有需要时，接线类改动仍会触发更广泛的重跑。
- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 所触发的架构通道。
- `pnpm check:changed`：针对相对于 `origin/main` 的 diff 运行智能变更门禁。它会将核心改动与核心测试通道一起运行，将扩展改动与扩展测试通道一起运行，将仅测试改动限制为仅做测试类型检查/测试，将公共 Plugin SDK 或插件契约变更扩展为扩展验证，并使仅含发布元数据的版本变更仍保持在有针对性的版本/配置/根依赖检查范围内。
- `pnpm test`：通过有作用域的 Vitest 通道路由显式指定的文件/目录目标。未指定目标时，会使用固定的分片组，并展开为叶子配置以便在本地并行执行；扩展组始终会展开为按扩展划分的分片配置，而不是使用一个庞大的根项目进程。
- 完整测试和扩展分片运行会更新 `.artifacts/vitest-shard-timings.json` 中的本地计时数据；后续运行会使用这些计时信息来平衡慢分片和快分片。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略该本地计时产物。
- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量通道运行，这些通道仅保留 `test/setup.ts`，而运行时开销较大的用例仍留在原有通道中。
- 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会将 `pnpm test:changed` 映射到这些轻量通道中的显式同级测试，因此对小型辅助文件的改动无需重新运行那些依赖重型运行时的测试套件。
- `auto-reply` 现在也被拆分为三个专用配置（`core`、`top-level`、`reply`），因此回复测试框架不会主导较轻量的顶层状态/token/辅助测试。
- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离运行器。
- `pnpm test:force`：终止任何仍在占用默认控制端口的残留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 测试套件，避免服务端测试与正在运行的实例发生冲突。当之前的 Gateway 网关运行导致端口 `18789` 仍被占用时，请使用它。
- `pnpm test:coverage`：通过 `vitest.unit.config.ts` 使用 V8 覆盖率运行单元测试套件。这是一个针对已加载文件的单元覆盖率门禁，而不是整个仓库所有文件的覆盖率。阈值为：行数 / 函数 / 语句 `70%`，分支 `55%`。由于 `coverage.all` 为 false，这个门禁会统计被单元覆盖率套件加载的文件，而不是把每个分拆测试 lane 中的源文件都视为未覆盖。
- `pnpm test:coverage:changed`：仅对自 `origin/main` 以来发生变更的文件运行单元覆盖率。
- `pnpm test:changed`：当 diff 只涉及可路由的源文件 / 测试文件时，会将 git 变更路径展开为有作用域的 Vitest 测试 lane。配置 / setup 变更仍会回退到原生 root projects 运行方式，以便在需要时对 wiring 变更执行更广泛的重跑。
- `pnpm changed:lanes`：显示相对于 `origin/main` 的 diff 所触发的架构 lane。
- `pnpm check:changed`：对相对于 `origin/main` 的 diff 运行智能变更门禁。它会将 core 相关工作与 core 测试 lane 一起运行，将 extension 相关工作与 extension 测试 lane 一起运行，将仅测试相关工作限制为测试类型检查 / 测试本身，对公开 Plugin SDK 或 plugin-contract 的变更扩展为一次 extension 验证，并将仅涉及发布元数据的版本变更限制在定向的版本 / 配置 / 根依赖检查中。
- `pnpm test`：通过有作用域的 Vitest 测试 lane 路由显式的文件 / 目录目标。未指定目标的运行会使用固定分片组，并展开为 leaf config，以便在本地并行执行；extension 组始终会展开为按 extension 划分的分片配置，而不是一个巨大的 root-project 进程。
- 完整测试和 extension 分片运行会更新 `.artifacts/vitest-shard-timings.json` 中的本地计时数据；后续运行会使用这些计时来平衡慢分片和快分片。设置 `OPENCLAW_TEST_PROJECTS_TIMINGS=0` 可忽略本地计时产物。
- 选定的 `plugin-sdk` 和 `commands` 测试文件现在会通过专用的轻量 lane 路由，这些 lane 只保留 `test/setup.ts`，而运行时负载较重的用例仍保留在现有 lane 中。
- 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会把 `pnpm test:changed` 映射到这些轻量 lane 中的显式同级测试，因此对小型辅助文件的修改无需重新运行重量级、依赖运行时的测试套件。
- `auto-reply` 现在也被拆分为三个专用配置（`core`、`top-level`、`reply`），这样 reply harness 就不会主导较轻量的 top-level 状态 / token / helper 测试。
- 基础 Vitest 配置现在默认使用 `pool: "threads"` 和 `isolate: false`，并在整个仓库配置中启用了共享的非隔离 runner。
- `pnpm test:channels` 运行 `vitest.channels.config.ts`。
- `pnpm test:extensions` 和 `pnpm test extensions` 运行所有扩展/插件分片。重量级渠道插件、浏览器插件以及 OpenAI 会作为专用分片运行；其他插件组仍保持批量运行。对单个内置插件通道，使用 `pnpm test extensions/<id>`。
- `pnpm test:perf:imports`：启用 Vitest 的导入时长 + 导入明细报告，同时仍对显式文件/目录目标使用有作用域的通道路由。
- `pnpm test:perf:imports:changed`：与上面相同的导入分析，但仅针对相对于 `origin/main` 已变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>`：针对同一组已提交 Git diff，将路由后的 changed 模式路径与原生根项目运行进行基准对比。
- `pnpm test:perf:changed:bench -- --worktree`：对当前工作树的变更集进行基准测试，无需先提交。
- `pnpm test:perf:profile:main`：为 Vitest 主线程写入 CPU profile（`.artifacts/vitest-main-profile`）。
- `pnpm test:perf:profile:runner`：为单元测试运行器写入 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个完整测试套件的 Vitest 叶子配置，并写入分组时长数据以及每个配置对应的 JSON/日志产物。Test Performance Agent 会在尝试修复慢测试之前，将此结果作为基线。
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：比较一次以性能为重点的改动前后两份分组报告。
- Gateway 网关集成：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择启用。
- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS/HTTP/节点配对）。在 `vitest.e2e.config.ts` 中默认使用 `threads` + `isolate: false` 与自适应 workers；可通过 `OPENCLAW_E2E_WORKERS=<n>` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。
- `pnpm test:live`：运行 provider 实时测试（minimax/zai）。需要 API key，并设置 `LIVE=1`（或 provider 专用的 `*_LIVE_TEST=1`）才会取消跳过。
- `pnpm test:docker:all`：先构建共享的实时测试镜像和 Docker E2E 镜像一次，然后在默认并发数 4 下以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 Docker 冒烟测试通道。可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` 调整。运行器会在首次失败后停止调度新的池化通道，除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`；每个通道默认有 120 分钟超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖。对启动敏感或 provider 敏感的通道会在并行池之后独占运行。每个通道的日志会写入 `.artifacts/docker-tests/<run-id>/`。
- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的实时模型 key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并不像常规单元/e2e 测试套件那样预期具备 CI 稳定性。
- `pnpm test:docker:mcp-channels`：启动一个带种子数据的 Gateway 网关容器和第二个客户端容器，后者会启动 `openclaw mcp serve`，然后验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及通过真实 stdio bridge 传输的 Claude 风格渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP 帧，因此该冒烟测试反映的是 bridge 实际发出的内容。
- `pnpm test:extensions` 和 `pnpm test extensions` 会运行所有 extension / plugin 分片。重量级渠道 plugin、browser plugin 和 OpenAI 会作为专用分片运行；其他 plugin 组则保持批量处理。对单个内置 plugin lane，请使用 `pnpm test extensions/<id>`。
- `pnpm test:perf:imports`：启用 Vitest 的导入耗时 + 导入明细报告，同时仍会对显式文件 / 目录目标使用有作用域的 lane 路由。
- `pnpm test:perf:imports:changed`：同样进行导入分析，但仅针对自 `origin/main` 以来发生变更的文件。
- `pnpm test:perf:changed:bench -- --ref <git-ref>`：针对同一份已提交的 git diff，对路由后的 changed 模式路径与原生 root-project 运行进行基准比较。
- `pnpm test:perf:changed:bench -- --worktree`：无需先提交，直接对当前 worktree 的变更集进行基准比较。
- `pnpm test:perf:profile:main`：为 Vitest 主线程写出 CPU profile（`.artifacts/vitest-main-profile`）。
- `pnpm test:perf:profile:runner`：为单元测试 runner 写出 CPU + 堆 profile（`.artifacts/vitest-runner-profile`）。
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`：串行运行每个完整测试套件的 Vitest leaf config，并写出分组耗时数据以及每个配置对应的 JSON / 日志产物。Test Performance Agent 会在尝试修复慢测试之前，将其作为基线。
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`：在面向性能的变更之后，对分组报告进行比较。
- Gateway 集成测试：通过 `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` 或 `pnpm test:gateway` 选择性启用。
- `pnpm test:e2e`：运行 Gateway 网关端到端冒烟测试（多实例 WS / HTTP / 节点配对）。默认在 `vitest.e2e.config.ts` 中使用 `threads` + `isolate: false` 和自适应 worker；可通过 `OPENCLAW_E2E_WORKERS=<n>` 调整，并设置 `OPENCLAW_E2E_VERBOSE=1` 以输出详细日志。
- `pnpm test:live`：运行 provider 的 live 测试（minimax / zai）。需要 API key，并设置 `LIVE=1`（或 provider 专用的 `*_LIVE_TEST=1`）才能取消跳过。
- `pnpm test:docker:all`：先构建共享的 live-test 镜像和 Docker E2E 镜像一次，然后以默认并发数 4、并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行 Docker 冒烟 lane。可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` 调整。除非设置 `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`，否则 runner 会在第一次失败后停止调度新的池化 lane；每个 lane 默认有 120 分钟超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖。对启动过程敏感或 provider 敏感的 lane 会在并行池之后独占运行。每个 lane 的日志会写入 `.artifacts/docker-tests/<run-id>/`。
- `pnpm test:docker:openwebui`：启动 Docker 化的 OpenClaw + Open WebUI，通过 Open WebUI 登录，检查 `/api/models`，然后通过 `/api/chat/completions` 运行一次真实的代理聊天。需要可用的 live model key（例如 `~/.profile` 中的 OpenAI），会拉取外部 Open WebUI 镜像，并不像常规单元 / e2e 测试套件那样被视为 CI 稳定测试。
- `pnpm test:docker:mcp-channels`：启动一个已植入数据的 Gateway 网关容器，以及第二个会启动 `openclaw mcp serve` 的客户端容器，然后验证经路由的会话发现、转录读取、附件元数据、live 事件队列行为、出站发送路由，以及通过真实 stdio bridge 发送的 Claude 风格渠道 + 权限通知。Claude 通知断言会直接读取原始 stdio MCP frame，因此这个冒烟测试反映的是 bridge 实际发出的内容。
## 本地 PR 门禁
在本地执行 PR 合并/门禁检查时，运行：
在本地执行 PR 合入 / 门禁检查时，请运行：
- `pnpm check:changed`
- `pnpm check`
@ -54,7 +54,7 @@ x-i18n:
- `pnpm test`
- `pnpm check:docs`
如果 `pnpm test` 在高负载主机上出现偶发失败，在将其视为回归之前先重跑一次，然后使用 `pnpm test <path/to/test>` 做隔离。对于内存受限的主机，使用：
如果 `pnpm test` 在负载较高的主机上出现偶发失败，请先重跑一次，再决定是否将其视为回归；之后可用 `pnpm test <path/to/test>` 进行隔离。在内存受限的主机上，请使用：
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
@ -67,9 +67,9 @@ x-i18n:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- 可选环境变量：`MINIMAX_API_KEY`、`MINIMAX_BASE_URL`、`MINIMAX_MODEL`、`ANTHROPIC_API_KEY`
- 默认提示词：“Reply with a single word: ok. No punctuation or extra text.”
- 默认提示词：“用一个单词回复：ok。不要标点或额外文本。”
上次运行（2025-12-31，20 次）：
最近一次运行（2025-12-31，20 次）：
- minimax 中位数 1279ms（最小 1114，最大 2431）
- opus 中位数 2454ms（最小 1224，最大 3170）
@ -99,37 +99,37 @@ x-i18n:
- `startup`：`--version`、`--help`、`health`、`health --json`、`status --json`、`status`
- `real`：`health`、`status`、`status --json`、`sessions`、`sessions --json`、`agents list --json`、`gateway status`、`gateway status --json`、`gateway health --json`、`config get gateway.port`
- `all`：两个预设都包含
- `all`：同时包含两个预设
输出内容包括每个命令的 `sampleCount`、平均值、p50、p95、最小/最大值、exit-code/signal 分布，以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写入 V8 profile，因此计时与 profile 采集使用的是同一套测试框架。
输出包括每个命令的 `sampleCount`、平均值、p50、p95、最小值 / 最大值、exit-code / signal 分布，以及最大 RSS 汇总。可选的 `--cpu-prof-dir` / `--heap-prof-dir` 会为每次运行写出 V8 profile，因此计时和 profile 采集使用的是同一套 harness。
已保存输出约定：
保存输出约定：
- `pnpm test:startup:bench:smoke` 会将定向冒烟产物写入 `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` 会使用 `runs=5` 和 `warmup=1` 将完整测试套件产物写入 `.artifacts/cli-startup-bench-all.json`
- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新已签入的基线夹具 `test/fixtures/cli-startup-bench.json`
- `pnpm test:startup:bench:update` 会使用 `runs=5` 和 `warmup=1` 刷新已提交的基线 fixture：`test/fixtures/cli-startup-bench.json`
已签入夹具：
已提交的 fixture：
- `test/fixtures/cli-startup-bench.json`
- 使用 `pnpm test:startup:bench:update` 刷新
- 使用 `pnpm test:startup:bench:check` 将当前结果与该夹具进行比较
- 使用 `pnpm test:startup:bench:check` 将当前结果与该 fixture 进行比较
## 新手引导 E2E（Docker）
Docker 是可选的；只有在运行容器化新手引导冒烟测试时才需要它。
在干净的 Linux 容器中执行完整冷启动流程：
在干净的 Linux 容器中运行完整冷启动流程：
```bash
scripts/e2e/onboard-docker.sh
```
该脚本会通过 pseudo-tty 驱动交互式向导，验证 config/workspace/session 文件，然后启动 Gateway 网关并运行 `openclaw health`。
该脚本会通过 pseudo-tty 驱动交互式向导，验证 config / workspace / session 文件，然后启动 Gateway 网关并运行 `openclaw health`。
## QR 导入冒烟测试（Docker）
确保维护中的 QR 运行时辅助程序可在受支持的 Docker Node 运行时中加载（默认 Node 24，兼容 Node 22）：
确保维护中的 QR 运行时辅助程序能在受支持的 Docker Node 运行时下加载（默认 Node 24，兼容 Node 22）：
```bash
pnpm test:docker:qr

209
docs/zh-CN/tools/exec-approvals-advanced.md Normal file
View File

@ -0,0 +1,209 @@
---
read_when:
- 配置安全二进制文件或自定义安全二进制文件配置档案
- 将批准转发到 Slack/Discord/Telegram 或其他聊天渠道
- 为渠道实现原生批准客户端
summary: 高级 exec 批准：安全二进制文件、解释器绑定、批准转发、本地交付
title: exec 批准——高级
x-i18n:
generated_at: "2026-04-23T23:21:49Z"
model: gpt-5.4
provider: openai
source_hash: 8a24a3539126b0f0fd11696c31efc8a6a9a4262fe4cd89bf456ff92a4f05c36c
source_path: tools/exec-approvals-advanced.md
workflow: 15
---
高级 exec 批准主题：`safeBins` 快速路径、解释器/运行时绑定，以及向聊天渠道转发批准（包括原生交付）。
有关核心策略和批准流程，请参见 [Exec approvals](/zh-CN/tools/exec-approvals)。
## 安全二进制文件（仅 stdin）
`tools.exec.safeBins` 定义了一小组**仅 stdin** 的二进制文件（例如 `cut`），它们在允许列表模式下**无需**显式允许列表条目即可运行。安全二进制文件会拒绝位置文件参数和类似路径的令牌，因此它们只能对输入流进行操作。请将其视为面向流过滤器的狭窄快速路径，而不是通用信任列表。
<Warning>
**不要**将解释器或运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins`。如果某个命令能够按设计执行代码求值、执行子命令或读取文件，请优先使用显式允许列表条目，并保持启用批准提示。自定义安全二进制文件必须在 `tools.exec.safeBinProfiles.<bin>` 中定义显式配置档案。
</Warning>
默认安全二进制文件：
[//]: # "SAFE_BIN_DEFAULTS:START"
`cut`, `uniq`, `head`, `tail`, `tr`, `wc`
[//]: # "SAFE_BIN_DEFAULTS:END"
`grep` 和 `sort` 不在默认列表中。如果你选择启用它们，请为其非 stdin 工作流保留显式允许列表条目。对于安全二进制文件模式下的 `grep`，请使用 `-e`/`--regexp` 提供模式；位置模式形式会被拒绝，这样文件操作数就不能伪装成含糊的位置参数。
### Argv 验证与被拒绝的标志
验证仅基于 argv 形状进行确定性判断（不检查主机文件系统中的存在性），这可以防止通过允许/拒绝差异形成文件存在性预言机行为。面向文件的选项会被默认安全二进制文件拒绝；长选项采用失败即关闭的验证方式（未知标志和含糊缩写都会被拒绝）。
按安全二进制文件配置档案划分的被拒绝标志：
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
- `grep`：`--dereference-recursive`、`--directories`、`--exclude-from`、`--file`、`--recursive`、`-R`、`-d`、`-f`、`-r`
- `jq`：`--argfile`、`--from-file`、`--library-path`、`--rawfile`、`--slurpfile`、`-L`、`-f`
- `sort`：`--compress-program`、`--files0-from`、`--output`、`--random-source`、`--temporary-directory`、`-T`、`-o`
- `wc`：`--files0-from`
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
安全二进制文件还会在执行时强制将 argv 令牌视为**字面文本**（不进行通配符展开，也不展开 `$VARS`），适用于仅 stdin 的命令段，因此像 `*` 或 `$HOME/...` 这样的模式不能被用来伪装文件读取。
### 受信任的二进制文件目录
安全二进制文件必须从受信任的二进制文件目录解析（系统默认目录，加上可选的 `tools.exec.safeBinTrustedDirs`）。`PATH` 条目绝不会被自动视为受信任。默认受信任目录刻意保持最小范围：`/bin`、`/usr/bin`。如果你的安全二进制文件可执行文件位于包管理器/用户路径中（例如 `/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`），请将它们显式添加到 `tools.exec.safeBinTrustedDirs`。
### Shell 链接、包装器与多路复用器
当每个顶层命令段都满足允许列表要求时，允许使用 shell 链接（`&&`、`||`、`;`），其中包括安全二进制文件或 Skills 自动允许。重定向在允许列表模式下仍然不受支持。命令替换（`$()` / 反引号）会在允许列表解析期间被拒绝，即使它位于双引号内部也是如此；如果你需要字面的 `$()` 文本，请使用单引号。
在 macOS 配套应用批准中，包含 shell 控制或展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 文本会被视为允许列表未命中，除非 shell 二进制文件本身已被加入允许列表。
对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求范围内的环境变量覆盖会被缩减为一个小型显式允许列表（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。
对于允许列表模式中的 `allow-always` 决策，已知的分发包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是包装器路径。Shell 多路复用器（`busybox`、`toybox`）对于 shell applet（`sh`、`ash` 等）也会以相同方式解包。如果某个包装器或多路复用器无法被安全解包，则不会自动持久化任何允许列表条目。
如果你将 `python3` 或 `node` 这样的解释器加入允许列表，建议启用 `tools.exec.strictInlineEval=true`，这样内联求值仍然需要显式批准。在严格模式下，`allow-always` 仍然可以持久化无害的解释器/脚本调用，但承载内联求值的调用不会被自动持久化。
### 安全二进制文件与允许列表
| 主题 | `tools.exec.safeBins` | 允许列表（`exec-approvals.json`） |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| 目标 | 自动允许狭窄的 stdin 过滤器 | 显式信任特定可执行文件 |
| 匹配类型 | 可执行文件名称 + 安全二进制文件 argv 策略 | 已解析可执行文件路径 glob 模式 |
| 参数范围 | 受安全二进制文件配置档案和字面令牌规则限制 | 仅匹配路径；参数的其他部分由你自行负责 |
| 典型示例 | `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>` 条目搭建 `{}` 骨架（之后请审查并收紧）。解释器/运行时二进制文件不会被自动搭建骨架。
自定义配置档案示例：
__OC_I18N_900000__
如果你显式选择将 `jq` 加入 `safeBins`，OpenClaw 在安全二进制文件模式下仍会拒绝 `env` 内建，因此 `jq -n env` 不能在没有显式允许列表路径或批准提示的情况下导出主机进程环境。
## 解释器/运行时命令
基于批准的解释器/运行时执行有意采取保守策略：
- 始终绑定精确的 argv/cwd/env 上下文。
- 直接 shell 脚本和直接运行时文件形式会尽力绑定到一个具体的本地文件快照。
- 仍然能够解析为单个直接本地文件的常见包管理器包装形式（例如 `pnpm exec`、`pnpm node`、`npm exec`、`npx`）会在绑定前被解包。
- 如果 OpenClaw 无法为解释器/运行时命令精确识别唯一一个具体本地文件（例如包脚本、eval 形式、运行时特定加载器链或含糊的多文件形式），则基于批准的执行会被拒绝，而不是声称自己覆盖了实际上并不具备的语义范围。
- 对于这些工作流，请优先考虑沙箱隔离、单独的主机边界，或显式受信任的允许列表/完整工作流，在这些场景中由操作员接受更广泛的运行时语义。
当需要批准时，exec 工具会立即返回一个批准 id。使用该 id 关联后续系统事件（`Exec finished` / `Exec denied`）。如果在超时之前没有收到决策，请求会被视为批准超时，并作为拒绝原因呈现。
### 后续交付行为
在已批准的异步 exec 完成后，OpenClaw 会向同一会话发送一个后续 `agent` 回合。
- 如果存在有效的外部交付目标（可交付渠道加上目标 `to`），后续交付会使用该渠道。
- 在仅 webchat 或仅内部会话流程中，如果没有外部目标，后续交付会保持为仅会话（`deliver: false`）。
- 如果调用方显式请求严格的外部交付，但没有可解析的外部渠道，请求会以 `INVALID_REQUEST` 失败。
- 如果启用了 `bestEffortDeliver` 且无法解析任何外部渠道，交付会降级为仅会话，而不是失败。
## 向聊天渠道转发批准
你可以将 exec 批准提示转发到任何聊天渠道（包括渠道插件），并使用 `/approve` 进行批准。这会使用正常的出站交付管道。
配置：
__OC_I18N_900001__
在聊天中回复：
__OC_I18N_900002__
`/approve` 命令同时处理 exec 批准和插件批准。如果该 ID 与待处理的 exec 批准不匹配，它会自动改为检查插件批准。
### 插件批准转发
插件批准转发使用与 exec 批准相同的交付管道，但它在 `approvals.plugin` 下拥有自己独立的配置。启用或禁用其中一个不会影响另一个。
__OC_I18N_900003__
该配置结构与 `approvals.exec` 相同：`enabled`、`mode`、`agentFilter`、`sessionFilter` 和 `targets` 的工作方式完全一致。
支持共享交互式回复的渠道会为 exec 批准和插件批准渲染相同的批准按钮。不支持共享交互式 UI 的渠道会回退为纯文本，并附带 `/approve` 说明。
### 任意渠道中的同聊天批准
当 exec 或插件批准请求来自可交付的聊天界面时，现在默认可以在同一聊天中通过 `/approve` 进行批准。这适用于 Slack、Matrix 和 Microsoft Teams 等渠道，也适用于现有的 Web UI 和终端 UI 流程。
这一路径共享的文本命令使用该会话的正常渠道身份验证模型。如果发起请求的聊天本来就能够发送命令并接收回复，那么批准请求不再需要单独的原生交付适配器才能保持待处理状态。
Discord 和 Telegram 也支持在同一聊天中使用 `/approve`，但即使禁用了原生批准交付，这些渠道在授权时仍然会使用其已解析的批准人列表。
对于 Telegram 和其他直接调用 Gateway 网关的原生批准客户端，这个回退有意被限制在“找不到批准”失败场景。真正的 exec 批准拒绝/错误不会被静默重试为插件批准。
### 原生批准交付
某些渠道还可以充当原生批准客户端。原生客户端会在共享的同聊天 `/approve` 流程之上增加批准人私信、原始聊天扇出以及渠道特定的交互式批准 UX。
当原生批准卡片/按钮可用时，该原生 UI 是面向智能体的主要路径。除非工具结果表明聊天批准不可用，或手动批准是唯一剩余路径，否则智能体不应再额外回显重复的纯聊天 `/approve` 命令。
通用模型：
- 主机 exec 策略仍然决定 exec 是否需要批准
- `approvals.exec` 控制将批准提示转发到其他聊天目标
- `channels.<channel>.execApprovals` 控制该渠道是否充当原生批准客户端
当以下条件全部满足时，原生批准客户端会自动启用优先发送到私信的交付方式：
- 该渠道支持原生批准交付
- 可以从显式的 `execApprovals.approvers` 或该渠道文档记录的回退来源中解析出批准人
- `channels.<channel>.execApprovals.enabled` 未设置或为 `"auto"`
设置 `enabled: false` 可以显式禁用原生批准客户端。设置 `enabled: true` 可以在批准人可解析时强制启用它。公开的原始聊天交付仍通过 `channels.<channel>.execApprovals.target` 显式控制。
常见问题：[为什么聊天批准会有两个 exec 批准配置？](/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` 流程和共享批准按钮的基础上，增加了私信路由和可选的渠道扇出。
共享行为：
- 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 原生私信/渠道路由和 reaction 快捷方式同时处理 exec 批准和插件批准；插件授权仍然来自 `channels.matrix.dm.allowFrom`
- 请求者不需要是批准人
- 当原始聊天本身已支持命令和回复时，可以直接通过 `/approve` 在该聊天中完成批准
- 原生 Discord 批准按钮按批准 id 类型进行路由：`plugin:` id 会直接进入插件批准，其余所有情况都会进入 exec 批准
- 原生 Telegram 批准按钮遵循与 `/approve` 相同的受限 exec 到插件回退逻辑
- 当原生 `target` 启用原始聊天交付时，批准提示会包含命令文本
- 待处理的 exec 批准默认会在 30 分钟后过期
- 如果没有操作员 UI 或已配置的批准客户端可以接受请求，提示会回退到 `askFallback`
Telegram 默认发送到批准人私信（`target: "dm"`）。如果你希望批准提示也出现在发起请求的 Telegram 聊天/话题中，可以切换为 `channel` 或 `both`。对于 Telegram 论坛话题，OpenClaw 会在批准提示和批准后的后续消息中保留该话题。
参见：
- [Discord](/channels/discord)
- [Telegram](/channels/telegram)
### macOS IPC 流程
__OC_I18N_900004__
安全说明：
- Unix socket 模式为 `0600`，token 存储在 `exec-approvals.json` 中。
- 同一 UID 对等方检查。
- 质询/响应（nonce + HMAC token + 请求哈希）+ 短 TTL。
## 相关内容
- [Exec approvals](/zh-CN/tools/exec-approvals) —— 核心策略和批准流程
- [Exec tool](/zh-CN/tools/exec)
- [Elevated mode](/zh-CN/tools/elevated)
- [Skills](/zh-CN/tools/skills) —— 基于 Skills 的自动允许行为

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

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

167
docs/zh-CN/tools/exec.md
View File

@ -5,17 +5,17 @@ read_when:
summary: Exec 工具用法、stdin 模式和 TTY 支持
title: Exec 工具
x-i18n:
generated_at: "2026-04-23T23:04:39Z"
generated_at: "2026-04-23T23:21:50Z"
model: gpt-5.4
provider: openai
source_hash: 4e2a7fc3b0570d59a6694d0a4ff9def1a5721c8a3d13abf7f947e7ea835535b3
source_hash: 4cad17fecfaf7d6a523282ef4f0090e4ffaab89ab53945b5cd831e426f3fc3ac
source_path: tools/exec.md
workflow: 15
---
在工作区中运行 shell 命令。通过 `process` 支持前台 + 后台执行。
如果 `process` 被禁止，`exec` 会同步运行，并忽略 `yieldMs`/`background`。
后台会话按智能体划分作用域；`process` 只能看到同一智能体下的会话。
如果 `process` 被禁用，`exec` 会同步运行，并忽略 `yieldMs`/`background`。
后台会话按智能体隔离；`process` 只能看到同一智能体的会话。
## 参数
@ -28,31 +28,31 @@ x-i18n:
</ParamField>
<ParamField path="env" type="object">
键/值形式的环境变量覆盖，会合并到继承环境之上。
叠加到继承环境之上的键/值环境变量覆盖。
</ParamField>
<ParamField path="yieldMs" type="number" default="10000">
在该延迟（毫秒）后自动将命令转为后台运行。
在这段延迟（毫秒）后自动将命令转入后台。
</ParamField>
<ParamField path="background" type="boolean" default="false">
立即将命令置于后台运行，而不是等待 `yieldMs`。
立即将命令转入后台，而不是等待 `yieldMs`。
</ParamField>
<ParamField path="timeout" type="number" default="1800">
在这么多秒后杀死命令。
在这么多秒后终止该命令。
</ParamField>
<ParamField path="pty" type="boolean" default="false">
在可用时于伪终端中运行。用于仅支持 TTY 的 CLI、编码智能体和终端 UI。
在可用时于伪终端中运行。适用于仅支持 TTY 的 CLI、编码智能体和终端 UI。
</ParamField>
<ParamField path="host" type="'auto' | 'sandbox' | 'gateway' | 'node'" default="auto">
执行位置。`auto` 会在沙箱运行时处于活动状态时解析为 `sandbox`，否则解析为 `gateway`。
执行位置。`auto` 会在当前会话启用了沙箱运行时时解析为 `sandbox`，否则解析为 `gateway`。
</ParamField>
<ParamField path="security" type="'deny' | 'allowlist' | 'full'">
`gateway` / `node` 执行的强制模式。
`gateway` / `node` 执行的强制策略模式。
</ParamField>
<ParamField path="ask" type="'off' | 'on-miss' | 'always'">
@ -60,48 +60,50 @@ x-i18n:
</ParamField>
<ParamField path="node" type="string">
当 `host=node` 时使用的节点 id/name。
当 `host=node` 时使用的节点 id/名称。
</ParamField>
<ParamField path="elevated" type="boolean" default="false">
请求提权模式 —— 从沙箱逃逸到已配置的宿主路径。只有当 elevated 最终解析为 `full` 时，才会强制 `security=full`。
请求提升模式——跳出沙箱并切换到已配置的主机路径。只有当 elevated 解析为 `full` 时，才会强制 `security=full`。
</ParamField>
说明：
- `host` 默认为 `auto`：当会话的沙箱运行时处于活动状态时为 sandbox，否则为 gateway。
- `auto` 是默认路由策略，不是通配符。单次调用时允许从 `auto` 切换到 `host=node`；只有在没有活动沙箱运行时时，才允许单次调用 `host=gateway`。
- 在没有额外配置的情况下，`host=auto` 仍然“开箱即用”：没有沙箱时会解析为 `gateway`；有活动沙箱时则保持在沙箱内。
- `elevated` 会从沙箱逃逸到已配置的宿主路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认值为 `host=node`）时为 `node`。它仅在当前会话/provider 启用了提权访问时可用。
- `gateway`/`node` 审批由 `~/.openclaw/exec-approvals.json` 控制。
- `node` 需要一个已配对的节点（配套应用或无头节点宿主）。
- `host` 默认为 `auto`：当会话启用了沙箱运行时时为 `sandbox`，否则为 `gateway`。
- `auto` 是默认路由策略，不是通配符。在 `auto` 下，每次调用都允许 `host=node`；只有在当前没有启用沙箱运行时时，每次调用才允许 `host=gateway`。
- 不做额外配置时，`host=auto` 依然能够“开箱即用”：没有沙箱时，它会解析为 `gateway`；存在活动沙箱时，它会保留在沙箱中。
- `elevated` 会跳出沙箱并切换到已配置的主机路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认值是 `host=node`）时为 `node`。只有当前会话/提供商启用了提升访问时，此选项才可用。
- `gateway`/`node` 的审批由 `~/.openclaw/exec-approvals.json` 控制。
- `node` 需要一个已配对的节点（配套应用或无头节点主机）。
- 如果有多个节点可用，请设置 `exec.node` 或 `tools.exec.node` 来选择其中一个。
- `exec host=node` 是节点唯一的 shell 执行路径；旧版 `nodes.run` 包装器已移除。
- 在非 Windows 宿主上，exec 会在设置了 `SHELL` 时使用它；如果 `SHELL` 是 `fish`，它会优先使用 `PATH` 中的 `bash`（或 `sh`），以避免 fish 不兼容脚本，然后在两者都不存在时回退到 `SHELL`。
- 在 Windows 宿主上，exec 会优先发现 PowerShell 7（依次检查 Program Files、ProgramW6432、然后 PATH），然后回退到 Windows PowerShell 5.1。
- 宿主执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖（`LD_*`/`DYLD_*`），以防止二进制劫持或注入代码。
- OpenClaw 会在生成的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），以便 shell/profile 规则检测 exec 工具上下文。
- 重要：沙箱隔离默认**关闭**。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会以失败关闭方式处理，而不是静默地在 gateway 宿主上运行。请启用沙箱隔离，或在审批下使用 `host=gateway`。
- 脚本预检（用于检测常见 Python/Node shell 语法错误）只会检查有效 `workdir` 边界内的文件。如果脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。
- 对于从现在开始的长时间运行工作，请启动一次，然后依赖启用后的自动完成唤醒机制，当命令输出内容或失败时唤醒。日志、状态、输入或人工干预请使用 `process`；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。
- 对于应在稍后执行或按计划执行的工作，请使用 cron，而不是 `exec` 的 sleep/延迟模式。
- 在非 Windows 主机上，exec 会优先使用已设置的 `SHELL`；如果 `SHELL` 是 `fish`，它会优先从 `PATH` 中选择 `bash`（或 `sh`）以避免与 fish 不兼容的脚本问题；如果两者都不存在，才会回退到 `SHELL`。
- 在 Windows 主机上，exec 会优先发现 PowerShell 7（Program Files、ProgramW6432，然后是 PATH），然后回退到 Windows PowerShell 5.1。
- 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖（`LD_*`/`DYLD_*`），以防止二进制劫持或注入代码。
- OpenClaw 会在生成的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），以便 shell/profile 规则识别 exec 工具上下文。
- 重要：默认情况下，沙箱隔离是**关闭**的。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会以关闭失败的方式处理，而不是静默在 Gateway 网关主机上运行。请启用沙箱隔离，或结合审批使用 `host=gateway`。
- 脚本预检（用于发现常见的 Python/Node shell 语法错误）只会检查有效 `workdir` 边界内的文件。如果脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。
- 对于现在开始的长时间运行任务，只需启动一次，并在启用了自动完成唤醒且命令输出内容或失败时依赖自动唤醒。
使用 `process` 处理日志、状态、输入或干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。
- 对于应稍后执行或按计划执行的任务，请使用 cron，而不是
`exec` 的 sleep/delay 模式。
## 配置
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，后台 exec 会话会在退出时排入一个系统事件并请求 heartbeat。
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行时间超过该值时，发出一次“running”通知（设为 0 可禁用）。
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，已后台化的 exec 会话在退出时会入队一个系统事件并请求一次 heartbeat。
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行超过该时长时发出一次“正在运行”通知（设为 0 可禁用）。
- `tools.exec.host`（默认：`auto`；当沙箱运行时处于活动状态时解析为 `sandbox`，否则为 `gateway`）
- `tools.exec.security`（默认：sandbox 为 `deny`，gateway + node 在未设置时为 `full`）
- `tools.exec.security`（默认：沙箱为 `deny`，未设置时 gateway + node 为 `full`）
- `tools.exec.ask`（默认：`off`）
- 无审批的宿主 exec 是 gateway + node 的默认行为。如果你希望启用审批/允许列表行为，请同时收紧 `tools.exec.*` 和宿主 `~/.openclaw/exec-approvals.json`；参见[Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。
- YOLO 来自宿主策略默认值（`security=full`、`ask=off`），而不是来自 `host=auto`。如果你想强制使用 gateway 或 node 路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。
- 在 `security=full` 加 `ask=off` 模式下，宿主 exec 会直接遵循已配置策略；没有额外的启发式命令混淆预过滤器，也没有脚本预检拒绝层。
- 对 gateway + node 来说，默认是无需审批的主机 exec。如果你想启用审批/allowlist 行为，请同时收紧 `tools.exec.*` 和主机上的 `~/.openclaw/exec-approvals.json`；参见 [Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。
- YOLO 来自主机策略默认值（`security=full`、`ask=off`），而不是 `host=auto`。如果你想强制使用 gateway 或 node 路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。
- 在 `security=full` 加 `ask=off` 模式下，主机 exec 会直接遵循已配置的策略；不会额外增加启发式命令混淆预过滤器或脚本预检拒绝层。
- `tools.exec.node`（默认：未设置）
- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器 eval 形式，例如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`，始终需要显式审批。`allow-always` 仍可持久信任无害的解释器/脚本调用，但内联 eval 形式每次仍会提示。
- `tools.exec.pathPrepend`：在 exec 运行前追加到 `PATH` 前部的目录列表（仅 gateway + sandbox）。
- `tools.exec.safeBins`：无需显式允许列表条目的仅 stdin 安全二进制文件。有关行为细节，请参见[Safe bins](/zh-CN/tools/exec-approvals#safe-bins-stdin-only)。
- `tools.exec.safeBinTrustedDirs`：为 `safeBins` 路径检查显式信任的额外目录。`PATH` 条目不会被自动信任。内置默认值为 `/bin` 和 `/usr/bin`。
- `tools.exec.safeBinProfiles`：为自定义 safe bin 提供可选的 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。
- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器求值形式，如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`，始终需要显式审批。`allow-always` 仍可持久放行无害的解释器/脚本调用，但内联求值形式每次仍会提示。
- `tools.exec.pathPrepend`：在 exec 运行时预置到 `PATH` 前部的目录列表（仅 gateway + sandbox）。
- `tools.exec.safeBins`：仅通过 stdin 使用、可在无需显式 allowlist 条目的情况下运行的安全二进制。有关行为细节，请参见 [Safe bins](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only)。
- `tools.exec.safeBinTrustedDirs`：用于 `safeBins` 路径检查的额外显式可信目录。`PATH` 条目永远不会被自动信任。内置默认值为 `/bin` 和 `/usr/bin`。
- `tools.exec.safeBinProfiles`：可选的每个 safe bin 自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。
示例：
@ -117,11 +119,13 @@ x-i18n:
### PATH 处理
- `host=gateway`：将你的登录 shell `PATH` 合并到 exec 环境中。宿主执行会拒绝 `env.PATH` 覆盖。守护进程本身仍以最小化 `PATH` 运行：
- `host=gateway`：将你的登录 shell `PATH` 合并进 exec 环境。主机执行会拒绝 `env.PATH` 覆盖。守护进程本身仍以最小化 `PATH` 运行：
- macOS：`/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/bin`
- Linux：`/usr/local/bin`、`/usr/bin`、`/bin`
- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。OpenClaw 会在 profile sourcing 之后通过内部环境变量将 `env.PATH` 追加到前面（不使用 shell 插值）；`tools.exec.pathPrepend` 在这里同样生效。
- `host=node`：只有你传入的未被阻止的环境变量覆盖会发送到节点。宿主执行会拒绝 `env.PATH` 覆盖，节点宿主也会忽略它。如果你需要在节点上添加更多 PATH 条目，请配置节点宿主服务环境（systemd/launchd），或将工具安装到标准位置。
- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。
OpenClaw 会在 profile 加载之后通过内部环境变量将 `env.PATH` 预置到前部（不进行 shell 插值）；`tools.exec.pathPrepend` 在这里同样适用。
- `host=node`：只有你传入的、未被拦截的环境覆盖会被发送到节点。主机执行会拒绝 `env.PATH` 覆盖，而节点主机也会忽略它。如果你需要在节点上添加额外的 PATH 条目，
请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。
按智能体绑定节点（在配置中使用智能体列表索引）：
@ -130,12 +134,12 @@ openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
```
控制 UI：Nodes 标签页中包含一个小型“Exec 节点绑定”面板，用于配置相同设置。
控制 UI：Nodes 选项卡包含一个小型“Exec 节点绑定”面板，用于设置相同的配置。
## 会话覆盖（`/exec`）
使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**按会话**默认值。
不带参数发送 `/exec` 可显示当前值。
使用 `/exec` 设置**按会话生效**的 `host`、`security`、`ask` 和 `node` 默认值。
发送不带参数的 `/exec` 可显示当前值。
示例：
@ -145,62 +149,69 @@ openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
## 授权模型
`/exec` 仅对**已授权发送者**生效（渠道允许列表/配对加上 `commands.useAccessGroups`）。
它只会更新**会话状态**，不会写入配置。若要硬禁用 exec，请通过工具策略拒绝它（`tools.deny: ["exec"]` 或按智能体配置）。
除非你显式设置 `security=full` 且 `ask=off`，否则宿主审批仍会生效。
`/exec` 仅对**已授权的发送方**生效（渠道 allowlist/配对 + `commands.useAccessGroups`）。
它只更新**会话状态**，不会写入配置。若要彻底禁用 exec，请通过工具
策略拒绝它（`tools.deny: ["exec"]` 或按智能体配置）。除非你显式设置
`security=full` 且 `ask=off`，否则主机审批仍然适用。
## Exec 审批（配套应用 / 节点宿主）
## Exec 审批（配套应用 / 节点主机）
沙箱隔离智能体可以要求在 `exec` 于 gateway 或节点宿主上运行前进行逐次请求审批。
有关策略、允许列表和 UI 流程，请参见[Exec 审批](/zh-CN/tools/exec-approvals)。
处于沙箱隔离中的智能体可以要求在 exec 在 Gateway 网关或节点主机上运行前进行逐次请求审批。
有关策略、allowlist 和 UI 流程，请参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
当需要审批时，exec 工具会立即返回，
`status: "approval-pending"` 和一个审批 id。一旦审批通过（或被拒绝 / 超时），Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在 `tools.exec.approvalRunningNoticeMs` 之后仍在运行，则会发出一次 `Exec running` 通知。
在支持原生审批卡片/按钮的渠道上，智能体应首先依赖该原生 UI，仅当工具结果明确说明聊天审批不可用，或手动审批是唯一途径时，才附带手动 `/approve` 命令。
其中包含 `status: "approval-pending"` 和一个审批 id。一旦获得批准（或被拒绝 / 超时），
Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在
`tools.exec.approvalRunningNoticeMs` 之后仍在运行，则会发出一次 `Exec running` 通知。
在原生支持审批卡片/按钮的渠道上，智能体应优先依赖该
原生 UI，只有当工具结果明确指出聊天审批不可用或手动审批是唯一
途径时，才应包含手动 `/approve` 命令。
## Allowlist + safe bins
手动允许列表强制只匹配**解析后的二进制路径**（不支持仅按 basename 匹配）。当
`security=allowlist` 时，只有在每个管道片段都在允许列表中或属于 safe bin 的情况下，shell 命令才会被自动允许。链式命令（`;`、`&&`、`||`）和重定向在
allowlist 模式下会被拒绝，除非每个顶层片段都满足允许列表条件（包括 safe bin）。
重定向仍然不受支持。
持久化的 `allow-always` 信任也不会绕过此规则：链式命令仍要求每个顶层片段都匹配。
手动 allowlist 强制仅匹配**解析后的二进制路径**（不匹配 basename）。当
`security=allowlist` 时，只有当管道中的每个片段都在
allowlist 中或属于 safe bin 时，shell 命令才会被自动允许。
在 allowlist 模式下，链式命令（`;`、`&&`、`||`）和重定向会被拒绝，除非每个顶层片段都满足 allowlist 要求（包括 safe bins）。
重定向仍不受支持。
持久化的 `allow-always` 信任也不会绕过这条规则：链式命令仍然要求每个
顶层片段都匹配。
`autoAllowSkills` 是 exec 审批中的一条单独的便捷路径。它不同于
手动路径允许列表条目。若要实现严格的显式信任，请保持
`autoAllowSkills` 关闭。
`autoAllowSkills` 是 exec 审批中的另一种便捷路径。它不同于
手动路径 allowlist 条目。若要实行严格的显式信任，请保持
`autoAllowSkills` 为禁用状态。
请将这两个控制项用于不同任务：
请将这两种控制分别用于不同场景：
- `tools.exec.safeBins`：小型、仅 stdin 的流过滤二进制文件。
- `tools.exec.safeBinTrustedDirs`：为 safe-bin 可执行路径显式信任的额外目录。
- `tools.exec.safeBinProfiles`：为自定义 safe bin 提供显式 argv 策略。
- `tools.exec.safeBins`：小型、仅 stdin 的流过滤二进制。
- `tools.exec.safeBinTrustedDirs`：用于 safe-bin 可执行路径的显式额外可信目录。
- `tools.exec.safeBinProfiles`：用于自定义 safe bin 的显式 argv 策略。
- allowlist：对可执行路径的显式信任。
不要将 `safeBins` 视为通用允许列表，也不要添加解释器/运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式允许列表条目，并保持审批提示开启。
当解释器/运行时 `safeBins` 条目缺少显式 profiles 时，`openclaw security audit` 会发出警告，而 `openclaw doctor --fix` 可为缺失的自定义 `safeBinProfiles` 条目生成脚手架。
当你显式将 `jq` 这类宽行为二进制文件重新加入 `safeBins` 时，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。
如果你显式允许列表解释器，请启用 `tools.exec.strictInlineEval`，以便内联代码 eval 形式仍需重新审批。
不要把 `safeBins` 当作通用 allowlist，也不要添加解释器/运行时二进制（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式 allowlist 条目，并保持审批提示启用。
当解释器/运行时的 `safeBins` 条目缺少显式 profile 时，`openclaw security audit` 会发出警告，`openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles` 条目生成脚手架。
如果你明确将像 `jq` 这样行为范围较广的二进制重新加入 `safeBins`，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。
如果你显式 allowlist 了解释器，请启用 `tools.exec.strictInlineEval`，这样内联代码求值形式仍然需要新的审批。
有关完整策略细节和示例，请参见[Exec 审批](/zh-CN/tools/exec-approvals#safe-bins-stdin-only)和[Safe bins versus allowlist](/zh-CN/tools/exec-approvals#safe-bins-versus-allowlist)。
有关完整策略细节和示例，请参见 [Exec 审批](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only) 和 [Safe bins 与 allowlist 的区别](/zh-CN/tools/exec-approvals-advanced#safe-bins-versus-allowlist)。
## 示例
前台：
前台执行：
```json
{ "tool": "exec", "command": "ls -la" }
```
后台 + 轮询：
后台执行 + 轮询：
```json
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
```
轮询用于按需查看状态，而不是等待循环。如果启用了自动完成唤醒，
命令可以在输出内容或失败时唤醒会话。
轮询用于按需查看状态，而不是用于等待循环。如果启用了自动完成唤醒，
当命令输出内容或失败时，它可以唤醒会话。
发送按键（tmux 风格）：
@ -225,7 +236,7 @@ allowlist 模式下会被拒绝，除非每个顶层片段都满足允许列表
## apply_patch
`apply_patch` 是 `exec` 的一个子工具，用于结构化的多文件编辑。
对于 OpenAI 和 OpenAI Codex 模型，它默认启用。只有在你想禁用它或将其限制为特定模型时，才需要使用配置：
对于 OpenAI 和 OpenAI Codex 模型，它默认启用。只有在你想禁用它或将其限制到特定模型时，才需要使用配置：
```json5
{
@ -242,12 +253,12 @@ allowlist 模式下会被拒绝，除非每个顶层片段都满足允许列表
- 仅适用于 OpenAI/OpenAI Codex 模型。
- 工具策略仍然适用；`allow: ["write"]` 会隐式允许 `apply_patch`。
- 配置位于 `tools.exec.applyPatch` 下。
- `tools.exec.applyPatch.enabled` 默认值为 `true`；设置为 `false` 可为 OpenAI 模型禁用该工具。
- `tools.exec.applyPatch.workspaceOnly` 默认值为 `true`（仅限工作区内）。只有在你明确希望 `apply_patch` 在工作区目录之外写入/删除时，才将其设为 `false`。
- `tools.exec.applyPatch.enabled` 默认为 `true`；如果要为 OpenAI 模型禁用该工具，请将其设为 `false`。
- `tools.exec.applyPatch.workspaceOnly` 默认为 `true`（限制在工作区内）。只有当你明确希望 `apply_patch` 在工作区目录之外执行写入/删除时，才将其设为 `false`。
## 相关内容
- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门禁
- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门控
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 在沙箱隔离环境中运行命令
- [后台进程](/zh-CN/gateway/background-process) — 长时间运行的 exec 和 process 工具
- [安全性](/zh-CN/gateway/security) — 工具策略和提权访问
- [安全](/zh-CN/gateway/security) — 工具策略和提升访问

162
docs/zh-CN/tools/image-generation.md
View File

@ -6,23 +6,23 @@ read_when:
summary: 使用已配置的提供商生成和编辑图像（OpenAI、OpenAI Codex OAuth、Google Gemini、fal、MiniMax、ComfyUI、Vydra、xAI）
title: 图像生成
x-i18n:
generated_at: "2026-04-23T23:04:52Z"
generated_at: "2026-04-23T23:22:30Z"
model: gpt-5.4
provider: openai
source_hash: 820829a009d48ccb23fbd9ee256bae27f6d7d9539fd75c2b0a7cef4b91c5c873
source_hash: 81d06d2be0d347be2aec54b02037c85fa4dcf71ccbc3c1b5d0aacac0b58892da
source_path: tools/image-generation.md
workflow: 15
---
`image_generate` 工具允许智能体使用你已配置的提供商来生成和编辑图像。生成的图像会自动作为媒体附件附加在智能体的回复中。
`image_generate` 工具允许智能体使用你已配置的提供商来创建和编辑图像。生成的图像会作为媒体附件自动随智能体的回复一起发送。
<Note>
只有当至少有一个图像生成提供商可用时，该工具才会出现。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。
只有在至少有一个图像生成提供商可用时，该工具才会显示。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API key，或使用 OpenAI Codex OAuth 登录。
</Note>
## 快速开始
1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`），或使用 OpenAI Codex OAuth 登录。
1. 为至少一个提供商设置 API key（例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`），或使用 OpenAI Codex OAuth 登录。
2. 可选：设置你偏好的模型：
```json5
@ -37,26 +37,26 @@ x-i18n:
}
```
Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当
配置了 `openai-codex` OAuth 配置文件时，OpenClaw 会通过该 OAuth 配置文件路由图像请求，而不是优先尝试 `OPENAI_API_KEY`。
如果显式配置了自定义 `models.providers.openai` 图像设置，例如 API 密钥或
自定义 / Azure base URL，则会重新切换回直接 OpenAI Images API 路径。
Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了
`openai-codex` OAuth 配置文件时，OpenClaw 会通过该 OAuth 配置文件路由图像请求，而不是优先尝试 `OPENAI_API_KEY`。
显式配置自定义的 `models.providers.openai` 图像设置（例如 API key 或
自定义 / Azure base URL）会切回直接使用 OpenAI Images API 路由。
3. 让智能体执行：_“生成一个友好的机器人吉祥物图像。”_
3. 向智能体发出请求：_“生成一张友好机器人吉祥物的图像。”_
智能体会自动调用 `image_generate`。不需要工具允许列表——当提供商可用时它默认启用。
智能体会自动调用 `image_generate`。无需设置工具允许列表——只要有可用提供商，它默认启用。
## 支持的提供商
| 提供商 | 默认模型 | 编辑支持 | Auth |
| -------- | -------------------------------- | ---------------------------------- | ----------------------------------------------------- |
| OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` 或 OpenAI Codex OAuth |
| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` |
| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） |
| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | `COMFY_API_KEY` 或云端环境下的 `COMFY_CLOUD_API_KEY` |
| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` |
| xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` |
| 提供商 | 默认模型 | 编辑支持 | 认证方式 |
| ------ | -------------------------------- | ---------------------------------- | ------------------------------------------------------- |
| OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` 或 OpenAI Codex OAuth |
| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` |
| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） |
| ComfyUI | `workflow` | 是（1 张图像，由 workflow 配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` |
| xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` |
使用 `action: "list"` 可在运行时检查可用的提供商和模型：
@ -79,11 +79,11 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当
</ParamField>
<ParamField path="image" type="string">
用于编辑模式的单个参考图像路径或 URL。
编辑模式下的单个参考图像路径或 URL。
</ParamField>
<ParamField path="images" type="string[]">
用于编辑模式的多个参考图像（最多 5 个）。
编辑模式下的多个参考图像（最多 5 张）。
</ParamField>
<ParamField path="size" type="string">
@ -98,17 +98,33 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当
分辨率提示。
</ParamField>
<ParamField path="quality" type="'low' | 'medium' | 'high' | 'auto'">
当提供商支持时使用的质量提示。
</ParamField>
<ParamField path="outputFormat" type="'png' | 'jpeg' | 'webp'">
当提供商支持时使用的输出格式提示。
</ParamField>
<ParamField path="count" type="number">
要生成的图像数量（1–4）。
</ParamField>
<ParamField path="timeoutMs" type="number">
可选的提供商请求超时时间（毫秒）。
</ParamField>
<ParamField path="filename" type="string">
输出文件名提示。
</ParamField>
并非所有提供商都支持所有参数。当某个回退提供商支持接近的几何选项，但不支持你精确请求的值时，OpenClaw 会在提交前重映射到最接近的受支持尺寸、宽高比或分辨率。真正不受支持的覆盖项仍会在工具结果中报告。
<ParamField path="openai" type="object">
仅适用于 OpenAI 的提示：`background`、`moderation`、`outputCompression` 和 `user`。
</ParamField>
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
并非所有提供商都支持所有参数。当回退提供商支持接近的几何选项而不是精确请求值时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。不受支持的输出提示（如 `quality` 或 `outputFormat`）会在不声明支持这些能力的提供商中被丢弃，并在工具结果中报告。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值反映的是实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
## 配置
@ -131,52 +147,71 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当
生成图像时，OpenClaw 会按以下顺序尝试提供商：
1. 工具调用中的 **`model` 参数**（如果智能体指定了它）
1. 工具调用中的 **`model` 参数**（如果智能体指定了）
2. 配置中的 **`imageGenerationModel.primary`**
3. 按顺序尝试 **`imageGenerationModel.fallbacks`**
4. **自动检测**——仅使用带 auth 支持的提供商默认值：
- 先尝试当前默认提供商
- 然后按提供商 ID 顺序尝试其余已注册图像生成提供商
3. 按顺序使用 **`imageGenerationModel.fallbacks`**
4. **自动检测**——仅使用有认证支持的提供商默认值：
- 当前默认提供商优先
- 其余已注册的图像生成提供商按 provider-id 顺序排列
如果某个提供商失败（auth 错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误信息中会包含每次尝试的详细信息。
如果某个提供商失败（认证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。
说明：
- 自动检测具备 auth 感知能力。只有当 OpenClaw 实际可以对某个提供商进行身份验证时，该提供商默认值才会进入候选列表。
- 默认启用自动检测。如果你希望图像生成只使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置
- 自动检测具备认证感知能力。只有当 OpenClaw 实际能够对某个提供商完成认证时，该提供商默认值才会进入候选列表。
- 自动检测默认启用。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置
`agents.defaults.mediaGenerationAutoProviderFallback: false`。
- 使用 `action: "list"` 可以检查当前已注册的提供商、它们的默认模型以及 auth 环境变量提示。
- 使用 `action: "list"` 可检查当前注册的提供商、它们的默认模型以及认证环境变量提示。
### 图像编辑
OpenAI、Google、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL：
```
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
"把这张照片生成为水彩风格版本" + image: "/path/to/photo.jpg"
```
OpenAI、Google 和 xAI 通过 `images` 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。
### OpenAI `gpt-image-2`
OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果配置了
`openai-codex` OAuth 配置文件，OpenClaw 会复用与 Codex 订阅聊天模型相同的 OAuth 配置文件，并通过 Codex Responses 后端发送图像请求；它不会为该请求静默回退到 `OPENAI_API_KEY`。
如需强制使用直接 OpenAI Images API 路由，请显式配置
`models.providers.openai`，并设置 API 密钥、自定义 base URL
或 Azure 端点。较旧的
OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果已配置
`openai-codex` OAuth 配置文件，OpenClaw 会复用 Codex 订阅聊天模型所使用的同一 OAuth 配置文件，并通过 Codex Responses 后端发送图像请求；它不会在该请求中静默回退到
`OPENAI_API_KEY`。如需强制使用直接的 OpenAI Images API 路由，请显式配置
`models.providers.openai`，例如设置 API key、自定义 base URL 或 Azure endpoint。较旧的
`openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI 图像生成和图像编辑请求应使用 `gpt-image-2`。
`gpt-image-2` 通过同一个 `image_generate` 工具同时支持文生图生成和参考图像编辑。OpenClaw 会将 `prompt`、
`count`、`size` 和参考图像转发给 OpenAI。OpenAI 不会直接接收
`aspectRatio` 或 `resolution`；在可能的情况下，OpenClaw 会将它们映射为受支持的 `size`，否则工具会将它们报告为被忽略的覆盖项。
`count`、`size`、`quality`、`outputFormat` 和参考图像转发给 OpenAI。
OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下，
OpenClaw 会将它们映射为受支持的 `size`，否则工具会将其报告为被忽略的覆盖项。
生成一张 4K 横版图像：
OpenAI 专用选项位于 `openai` 对象下：
```json
{
"quality": "low",
"outputFormat": "jpeg",
"openai": {
"background": "opaque",
"moderation": "low",
"outputCompression": 60,
"user": "end-user-42"
}
}
```
`openai.background` 接受 `transparent`、`opaque` 或 `auto`；透明输出要求
`outputFormat` 为 `png` 或 `webp`。`openai.outputCompression`
适用于 JPEG / WebP 输出。
生成一张 4K 横向图像：
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
```
生成两张方形图像：
生成两张正方形图像：
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
@ -194,48 +229,47 @@ OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果配置了
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
```
如需通过 Azure OpenAI 部署而不是 `api.openai.com` 路由 OpenAI 图像生成，
请参阅 OpenAI 提供商文档中的 [Azure OpenAI 端点](/zh-CN/providers/openai#azure-openai-endpoints)。
如果要通过 Azure OpenAI deployment 而不是 `api.openai.com` 来路由 OpenAI 图像生成，请参阅 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。
MiniMax 图像生成可通过两条内置 MiniMax auth 路径使用：
MiniMax 图像生成可通过两种内置的 MiniMax 认证路径使用：
- `minimax/image-01`：用于 API 密钥设置
- `minimax-portal/image-01`：用于 OAuth 设置
- `minimax/image-01` 用于 API key 配置
- `minimax-portal/image-01` 用于 OAuth 配置
## 提供商能力
| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（由工作流定义输出） | 是（1 张） | 是（最多 4 张） |
| 编辑 / 参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） |
| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 |
| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 |
| 分辨率（1K / 2K / 4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K / 2K） |
| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------ | -------------------- |
| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（由 workflow 定义输出） | 是（1 张） | 是（最多 4 张） |
| 编辑 / 参考图 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由 workflow 配置） | 否 | 是（最多 5 张图像） |
| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 |
| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 |
| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K/2K） |
### xAI `grok-imagine-image`
内置的 xAI 提供商对纯提示词请求使用 `/v1/images/generations`，
而当存在 `image` 或 `images` 时使用 `/v1/images/edits`。
内置的 xAI 提供商会对纯提示词请求使用 `/v1/images/generations`，
在存在 `image` 或 `images` 时使用 `/v1/images/edits`。
- 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-pro`
- 数量：最多 4 张
- 参考图像：一个 `image` 或最多五个 `images`
- 参考图：一个 `image` 或最多五个 `images`
- 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`
- 分辨率：`1K`、`2K`
- 输出：作为 OpenClaw 管理的图像附件返回
- 输出：以 OpenClaw 管理的图像附件形式返回
OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user` 或
其他仅限原生的额外宽高比，直到这些控制项出现在共享的跨提供商 `image_generate` 契约中。
在这些控制项出现在跨提供商共享的 `image_generate` 契约中之前，
OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user` 或其他仅原生支持的额外宽高比选项。
## 相关内容
- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
- [fal](/zh-CN/providers/fal) — fal 图像与视频提供商设置
- [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置
- [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置
- [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud workflow 设置
- [Google（Gemini）](/zh-CN/providers/google) — Gemini 图像提供商设置
- [MiniMax](/zh-CN/providers/minimax) — MiniMax 图像提供商设置
- [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置
- [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置
- [xAI](/zh-CN/providers/xai) — Grok 图像、视频、搜索、代码执行和 TTS 设置
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置
- [模型](/zh-CN/concepts/models) — 模型配置与回退
- [模型](/zh-CN/concepts/models) — 模型配置和故障切换

209
docs/zh-CN/tools/music-generation.md
View File

@ -1,40 +1,34 @@
---
read_when:
- 通过智能体生成音乐或音频
- 配置音乐生成 providers 和模型
- 理解 `music_generate` 工具参数
summary: |-
使用共享 providers 生成音乐，包括基于工作流的插件＿日本assistant to=functions.read in commentary 彩神争霸大发快ीjson_object
{"path":"/home/runner/work/docs/docs/source/AGENTS.md","offset":1,"limit":220} RTLUanalysis to=functions.read 天天彩票网json_object 天天中彩票派奖 иахьassistant to=functions.read in commentary 大发极速json_object
{"path":"/home/runner/work/docs/docs/source/docs/AGENTS.md","offset":1,"limit":220}
- 配置音乐生成提供商和模型
- 了解 `music_generate` 工具参数
summary: 使用共享提供商生成音乐，包括基于工作流的插件
title: 音乐生成
x-i18n:
generated_at: "2026-04-23T21:09:19Z"
generated_at: "2026-04-23T23:22:41Z"
model: gpt-5.4
provider: openai
source_hash: 5b03922bf032586f649e677d1d8c08250b1fd5dc95f1cdde050a058562feb3da
source_hash: 6010ee365e4b48b62eb20f3769aae4e409cb651fe7d5946b8c832f0fb120a1e4
source_path: tools/music-generation.md
workflow: 15
---
`music_generate` 工具让智能体能够通过
共享音乐生成能力，配合已配置的 providers（如 Google、
MiniMax 以及基于工作流配置的 ComfyUI）来创建音乐或音频。
`music_generate` 工具允许智能体通过共享音乐生成能力，并借助已配置的提供商（如 Google、MiniMax 以及通过工作流配置的 ComfyUI）来创建音乐或音频。
对于共享的、provider 支持的智能体会话，OpenClaw 会将音乐生成作为一个
后台任务启动，在任务账本中跟踪它，然后在曲目准备好之后再次唤醒智能体，以便智能体将完成的音频发回原始渠道。
对于基于共享提供商的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备就绪时再次唤醒智能体，以便智能体将生成完成的音频发回原始渠道。
<Note>
只有当至少有一个音乐生成 provider 可用时，内置共享工具才会出现。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置 provider API 密钥。
仅当至少有一个音乐生成提供商可用时，内置共享工具才会显示。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。
</Note>
## 快速开始
### 共享的 provider 支持生成
### 基于共享提供商的生成
1. 至少为一个 provider 设置 API 密钥，例如 `GEMINI_API_KEY` 或
1. 为至少一个提供商设置 API 密钥，例如 `GEMINI_API_KEY` 或
`MINIMAX_API_KEY`。
2. 可选地设置你偏好的模型：
2. 可选：设置你偏好的模型：
```json5
{
@ -48,14 +42,13 @@ MiniMax 以及基于工作流配置的 ComfyUI）来创建音乐或音频。
}
```
3. 让智能体：“_生成一首关于夜晚驾驶穿越霓虹城市的欢快 synthpop 曲目。_”
3. 向智能体提问：_“生成一段关于夜晚驾车穿过霓虹城市的轻快 synthpop 音轨。”_
智能体会自动调用 `music_generate`。无需加入工具允许列表。
智能体会自动调用 `music_generate`。无需单独将其加入工具允许列表。
对于没有会话支持智能体运行的直接同步上下文，内置
工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。
对于没有会话支撑的智能体运行的直接同步上下文，内置工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。
示例提示：
示例提示词：
```text
Generate a cinematic piano track with soft strings and no vocals.
@ -67,13 +60,11 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
### 基于工作流的 Comfy 生成
内置的 `comfy` 插件会通过
音乐生成 provider 注册表接入共享的 `music_generate` 工具。
内置的 `comfy` 插件会通过音乐生成提供商注册表接入共享 `music_generate` 工具。
1. 配置 `models.providers.comfy.music`，并提供工作流 JSON 以及
prompt/output 节点。
1. 使用工作流 JSON 以及提示 / 输出节点，配置 `models.providers.comfy.music`。
2. 如果你使用 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。
3. 让智能体生成音乐，或直接调用工具。
3. 向智能体请求生成音乐，或直接调用该工具。
示例：
@ -81,32 +72,31 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
## 共享内置 provider 支持
## 共享内置提供商支持
| Provider | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 |
| -------- | ------------------------ | -------------- | ------------------------------------------------------ | ---------------------------------------- |
| ComfyUI | `workflow` | 最多 1 张图像 | 由工作流定义的音乐或音频 | `COMFY_API_KEY`、`COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | 最多 10 张图像 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`、`GOOGLE_API_KEY` |
| MiniMax | `music-2.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` |
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 |
| ------ | ---------------------- | ------------ | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | 最多 1 张图片 | 由工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | 最多 10 张图片 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` |
### 已声明能力矩阵
### 已声明的能力矩阵
这是 `music_generate`、契约测试
和共享 live sweep 使用的显式模式契约。
这是 `music_generate`、契约测试以及共享实时测试所使用的显式模式契约。
| Provider | `generate` | `edit` | 编辑上限 | 共享 live lanes |
| -------- | ---------- | ------ | -------- | ----------------------------------------------------------------------- |
| ComfyUI | 是 | 是 | 1 张图像 | 不在共享 sweep 中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 |
| Google | 是 | 是 | 10 张图像| `generate`、`edit` |
| MiniMax | 是 | 否 | 无 | `generate` |
| 提供商 | `generate` | `edit` | 编辑上限 | 共享实时测试通道 |
| ------ | ---------- | ------ | ---------- | ------------------------------------------------------------------------- |
| ComfyUI | 是 | 是 | 1 张图片 | 不在共享测试范围中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 |
| Google | 是 | 是 | 10 张图片 | `generate`、`edit` |
| MiniMax | 是 | 否 | 无 | `generate` |
使用 `action: "list"` 可在运行时检查可用的共享 providers 和模型：
使用 `action: "list"` 可在运行时检查可用的共享提供商和模型：
```text
/tool music_generate action=list
```
使用 `action: "status"` 可检查当前活跃的基于会话的音乐任务：
使用 `action: "status"` 可检查当前处于活动状态、由会话支撑的音乐任务：
```text
/tool music_generate action=status
@ -120,44 +110,42 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## 内置工具参数
| 参数 | 类型 | 说明 |
| ------------------ | --------- | -------------------------------------------------------------------------------------------- |
| `prompt` | string | 音乐生成提示（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于查看 providers 的 `"list"` |
| `model` | string | Provider/模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` |
| `lyrics` | string | 当 provider 支持显式歌词输入时可选的歌词 |
| `instrumental` | boolean | 当 provider 支持时，请求纯伴奏输出 |
| `image` | string | 单张参考图像路径或 URL |
| `images` | string[] | 多张参考图像（最多 10 张） |
| `durationSeconds` | number | 当 provider 支持时，目标时长（秒）提示 |
| `format` | string | 当 provider 支持时，输出格式提示（`mp3` 或 `wav`） |
| `filename` | string | 输出文件名提示 |
| 参数 | 类型 | 说明 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `prompt` | string | 音乐生成提示词（当 `action: "generate"` 时为必填） |
| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于检查提供商的 `"list"` |
| `model` | string | 提供商 / 模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` |
| `lyrics` | string | 当提供商支持显式歌词输入时的可选歌词 |
| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 |
| `image` | string | 单张参考图片路径或 URL |
| `images` | string[] | 多张参考图片（最多 10 张） |
| `durationSeconds` | number | 当提供商支持时，以秒为单位指定目标时长提示 |
| `timeoutMs` | number | 可选的提供商请求超时时间（毫秒） |
| `format` | string | 当提供商支持时，输出格式提示（`mp3` 或 `wav`） |
| `filename` | string | 输出文件名提示 |
并非所有 providers 都支持所有参数。OpenClaw 仍会在提交前验证
诸如输入数量这类硬限制。当 provider 支持时长，但其最大值
低于请求值时，OpenClaw 会自动将时长压缩到最接近的受支持值。真正不受支持的可选提示
在所选 provider 或模型无法满足时，会被忽略并附带警告。
并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证硬性限制，例如输入数量。当提供商支持时长，但其最大时长短于请求值时，OpenClaw 会自动钳制到最接近的受支持时长。对于真正不受支持的可选提示，当所选提供商或模型无法满足时，会忽略该提示并给出警告。
工具结果会报告实际应用的设置。当 OpenClaw 在 provider 回退期间压缩时长时，返回的 `durationSeconds` 会反映实际提交值，而 `details.normalization.durationSeconds` 会显示从请求值到应用值的映射。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间钳制时长时，返回的 `durationSeconds` 反映的是提交值，而 `details.normalization.durationSeconds` 会显示从请求值到应用值的映射。
## 共享 provider 支持路径的异步行为
## 基于共享提供商路径的异步行为
- 基于会话的智能体运行：`music_generate` 会创建一个后台任务，立即返回一个 started/task 响应，并在稍后通过后续智能体消息发布完成曲目。
- 防重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中的后续 `music_generate` 调用会返回任务状态，而不是再次启动新的生成。
- 状态查询：使用 `action: "status"` 可在不启动新生成的情况下检查当前活跃的基于会话的音乐任务。
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 检查该生成任务的排队、运行和终态状态。
- 完成唤醒：OpenClaw 会向同一会话注入一个内部完成事件，这样模型就可以自己编写面向用户的后续回复。
- 提示提示：当音乐任务已在飞行中时，同一会话中的后续用户/手动轮次会收到一个小型运行时提示，这样模型就不会盲目再次调用 `music_generate`。
- 无会话回退：没有真实智能体会话的直接/本地上下文仍会以内联方式运行，并在同一轮中返回最终音频结果。
- 由会话支撑的智能体运行：`music_generate` 会创建后台任务，立即返回一个已启动 / 任务响应，并在稍后的智能体跟进消息中发布完成的音轨。
- 防重复：当该后台任务在同一会话中仍处于 `queued` 或 `running` 状态时，后续 `music_generate` 调用会返回任务状态，而不是再次启动新的生成。
- 状态查询：使用 `action: "status"` 可以在不启动新任务的情况下检查当前活动的、由会话支撑的音乐任务。
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可检查该生成任务的排队、运行中和终态状态。
- 完成唤醒：OpenClaw 会将一个内部完成事件注入回同一会话，以便模型自行编写面向用户的后续消息。
- 提示线索：当同一会话中已经有音乐任务在进行时，后续用户 / 手动轮次会得到一个小型运行时提示，防止模型再次盲目调用 `music_generate`。
- 无会话回退：在没有真实智能体会话的直接 / 本地上下文中，仍会以内联方式运行，并在同一轮返回最终音频结果。
### 任务生命周期
每个 `music_generate` 请求都会经历四种状态：
每个 `music_generate` 请求都会经过四个状态：
1. **queued** —— 任务已创建，等待 provider 接受。
2. **running** —— provider 正在处理（通常 30 秒到 3 分钟，取决于 provider 和时长）。
3. **succeeded** —— 曲目已准备好；智能体会被唤醒并将其发布到对话中。
4. **failed** —— provider 错误或超时；智能体会带着错误详情被唤醒。
1. **queued** —— 任务已创建，正在等待提供商接受。
2. **running** —— 提供商正在处理（通常为 30 秒到 3 分钟，取决于提供商和时长）。
3. **succeeded** —— 音轨已就绪；智能体被唤醒并将其发布到对话中。
4. **failed** —— 提供商错误或超时；智能体会带着错误详情被唤醒。
通过 CLI 检查状态：
@ -167,7 +155,7 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
防重复：如果当前会话已有音乐任务处于 `queued` 或 `running`，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可显式检查状态，而不会触发新生成。
防重复：如果当前会话中已经有音乐任务处于 `queued` 或 `running`，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查，而不会触发新的生成。
## 配置
@ -186,42 +174,41 @@ openclaw tasks cancel <taskId>
}
```
### Provider 选择顺序
### 提供商选择顺序
生成音乐时，OpenClaw 会按以下顺序尝试 providers：
生成音乐时，OpenClaw 会按以下顺序尝试提供商：
1. 工具调用中的 `model` 参数（如果智能体显式指定）
1. 工具调用中的 `model` 参数（如果智能体指定了）
2. 配置中的 `musicGenerationModel.primary`
3. 按顺序尝试 `musicGenerationModel.fallbacks`
4. 仅使用基于认证的 provider 默认值进行自动检测：
- 当前默认 provider 优先
- 其余已注册音乐生成 providers 按 provider-id 顺序排列
3. 按顺序使用 `musicGenerationModel.fallbacks`
4. 仅使用基于认证的提供商默认值进行自动检测：
- 当前默认提供商优先
- 然后是剩余已注册的音乐生成提供商，按 provider-id 顺序
如果某个 provider 失败，会自动尝试下一个候选项。如果全部失败，
错误中会包含每次尝试的详细信息。
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，
错误中会包含每次尝试的详情。
如果你希望
音乐生成仅使用显式 `model`、`primary` 和 `fallbacks`
如果你希望音乐生成仅使用显式的 `model`、`primary` 和 `fallbacks`
条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
## Provider 说明
## 提供商说明
- Google 使用 Lyria 3 批量生成。当前内置流程支持
prompt、可选歌词文本，以及可选参考图像。
提示词、可选歌词文本，以及可选参考图片。
- MiniMax 使用批量 `music_generation` 端点。当前内置流程
支持 prompt、可选歌词、纯伴奏模式、时长引导，以及
支持提示词、可选歌词、器乐模式、时长引导，以及
mp3 输出。
- ComfyUI 支持基于工作流驱动，具体取决于配置的图结构以及
prompt/output 字段的节点映射。
- ComfyUI 支持由工作流驱动，并取决于已配置的图以及
提示 / 输出字段的节点映射。
## Provider 能力模式
## 提供商能力模式
共享音乐生成契约现在支持显式模式声明：
- `generate` 用于仅提示的生成
- `edit` 用于请求中包含一张或多张参考图像时
- `generate` 用于仅基于提示词的生成
- `edit` 用于请求中包含一张或多张参考图片时
新的 provider 实现应优先使用显式模式块：
新的提供商实现应优先使用显式模式块：
```typescript
capabilities: {
@ -240,19 +227,19 @@ capabilities: {
```
旧版扁平字段，例如 `maxInputImages`、`supportsLyrics` 和
`supportsFormat`，不足以声明编辑支持。Providers 应当
显式声明 `generate` 和 `edit`，这样 live tests、契约测试以及
共享 `music_generate` 工具才能以确定性方式验证模式支持。
`supportsFormat`，不足以声明支持编辑。提供商应
显式声明 `generate` 和 `edit`，以便实时测试、契约测试以及
共享 `music_generate` 工具能够以确定方式验证模式支持。
## 如何选择正确路径
## 选择合适的路径
- 当你需要模型选择、provider 故障转移以及内置异步任务/状态流时，请使用共享 provider 支持路径。
- 当你需要自定义工作流图，或使用不属于共享内置音乐能力的 provider 时，请使用插件路径，例如 ComfyUI。
- 如果你在调试 ComfyUI 专用行为，请参阅 [ComfyUI](/zh-CN/providers/comfy)。如果你在调试共享 provider 行为，请从 [Google（Gemini）](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax) 开始。
- 当你需要模型选择、提供商故障切换和内置异步任务 / 状态流程时，使用基于共享提供商的路径。
- 当你需要自定义工作流图，或使用不属于共享内置音乐能力的提供商时，使用插件路径，例如 ComfyUI。
- 如果你在调试 ComfyUI 特有行为，请参阅 [ComfyUI](/zh-CN/providers/comfy)。如果你在调试共享提供商行为，请先查看 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax)。
## 实时测试
共享内置 providers 的选择加入 live 覆盖：
针对共享内置提供商的可选实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
@ -264,30 +251,30 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv
pnpm test:live:media music
```
该 live 文件会从 `~/.profile` 加载缺失的 provider 环境变量，
默认优先使用 live/env API 密钥，而不是已存储 auth profiles，并会在 provider 启用编辑模式时同时运行
这个实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用
实时 / 环境变量 API 密钥，而不是已存储的认证配置文件，并在提供商启用编辑模式时，同时运行
`generate` 和已声明的 `edit` 覆盖。
当前这意味着：
当前意味着：
- `google`：`generate` + `edit`
- `google`：`generate` 加 `edit`
- `minimax`：仅 `generate`
- `comfy`：单独的 Comfy live 覆盖，不在共享 provider sweep 中
- `comfy`：单独的 Comfy 实时覆盖，不属于共享提供商测试范围
内置 ComfyUI 音乐路径的选择加入 live 覆盖：
针对内置 ComfyUI 音乐路径的可选实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
Comfy live 文件在配置了相关部分时，也会覆盖 comfy 图像和视频工作流。
Comfy 实时测试文件在相应部分已配置时，也会覆盖 comfy 图片和视频工作流。
## 相关内容
- [后台任务](/zh-CN/automation/tasks) - 用于分离式 `music_generate` 运行的任务跟踪
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) - `musicGenerationModel` 配置
- [ComfyUI](/zh-CN/providers/comfy)
- [Google（Gemini）](/zh-CN/providers/google)
- [Google (Gemini)](/zh-CN/providers/google)
- [MiniMax](/zh-CN/providers/minimax)
- [模型](/zh-CN/concepts/models) - 模型配置与故障转移
- [模型](/zh-CN/concepts/models) - 模型配置与故障切换
- [工具概览](/zh-CN/tools)

229
docs/zh-CN/tools/tts.md
View File

@ -2,38 +2,43 @@
read_when:
- 为回复启用文本转语音
- 配置 TTS 提供商或限制
- 使用 /tts 命令
- 使用 `/tts` 命令
summary: 用于出站回复的文本转语音（TTS）
title: 文本转语音
x-i18n:
generated_at: "2026-04-23T23:06:08Z"
generated_at: "2026-04-23T23:22:41Z"
model: gpt-5.4
provider: openai
source_hash: ba760f48e203a090ddc8f18198439541de8886422fca07edb94a46295684da02
source_hash: 935fec2325a08da6f4ecd8ba5a9b889cd265025c5c7ee43bc4e0da36c1003d8f
source_path: tools/tts.md
workflow: 15
---
OpenClaw 可以使用 ElevenLabs、Google Gemini、Microsoft、MiniMax、OpenAI 或 xAI 将出站回复转换为音频。
OpenClaw 可以使用 ElevenLabs、Google Gemini、Microsoft、MiniMax、OpenAI 或 xAI，将出站回复转换为音频。
它适用于 OpenClaw 能发送音频的任何地方。
## 支持的服务
- **ElevenLabs**（主提供商或后备提供商）
- **Google Gemini**（主提供商或后备提供商；使用 Gemini API TTS）
- **Microsoft**（主提供商或后备提供商；当前内置实现使用 `node-edge-tts`）
- **MiniMax**（主提供商或后备提供商；使用 T2A v2 API）
- **OpenAI**（主提供商或后备提供商；也用于摘要）
- **xAI**（主提供商或后备提供商；使用 xAI TTS API）
- **ElevenLabs**（主提供商或回退提供商）
- **Google Gemini**（主提供商或回退提供商；使用 Gemini API TTS）
- **Microsoft**（主提供商或回退提供商；当前内置实现使用 `node-edge-tts`）
- **MiniMax**（主提供商或回退提供商；使用 T2A v2 API）
- **OpenAI**（主提供商或回退提供商；也用于摘要）
- **xAI**（主提供商或回退提供商；使用 xAI TTS API）
### Microsoft 语音说明
当前内置的 Microsoft speech 提供商通过 `node-edge-tts` 库使用 Microsoft Edge 在线神经 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 端点，并且不需要 API key。
`node-edge-tts` 暴露了语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然可用，并会被标准化为 `microsoft`。
当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库，使用 Microsoft Edge 在线神经网络 TTS 服务。它是托管服务（不是
本地服务），使用 Microsoft 端点，并且不需要 API key。
`node-edge-tts` 提供语音配置选项和输出格式，但
并非所有选项都被该服务支持。使用 `edge` 的旧版配置和指令输入
仍然有效，并会规范化为 `microsoft`。
由于这一路径是一个没有公开 SLA 或配额说明的公共 Web 服务，请将其视为尽力而为。如果你需要有保障的配额和支持，请使用 OpenAI 或 ElevenLabs。
由于这一路径是公共 Web 服务，且没有公开发布的 SLA 或配额，
请将其视为尽力而为的服务。如果你需要有保障的限额和支持，请使用 OpenAI
或 ElevenLabs。
## 可选密钥
## 可选键
如果你想使用 OpenAI、ElevenLabs、Google Gemini、MiniMax 或 xAI：
@ -43,34 +48,35 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Microsoft、MiniMax、OpenAI
- `OPENAI_API_KEY`
- `XAI_API_KEY`
Microsoft speech **不需要** API key。
Microsoft 语音**不**需要 API key。
如果配置了多个提供商，则会优先使用已选择的提供商，其他提供商作为后备选项。
如果配置了多个提供商，将优先使用所选提供商，其他提供商则作为回退选项。
自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），
因此如果你启用了摘要，该提供商也必须完成身份验证。
因此如果你启用了摘要，该提供商也必须已完成认证。
## 服务链接
- [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech)
- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio)
- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech)
- [OpenAI Audio API 参考](https://platform.openai.com/docs/api-reference/audio)
- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication)
- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2)
- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
- [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)
- [Microsoft Speech 输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
- [xAI 文本转语音](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)
## 默认启用吗？
不是。自动 TTS 默认**关闭**。可在配置中通过
`messages.tts.auto` 启用，或在本地通过 `/tts on` 启用。
不会。自动 TTS 默认是**关闭**的。请在配置中使用
`messages.tts.auto` 启用，或在本地使用 `/tts on` 启用。
当 `messages.tts.provider` 未设置时，OpenClaw 会按注册表自动选择顺序选择第一个已配置的 speech 提供商。
当 `messages.tts.provider` 未设置时，OpenClaw 会按注册表自动选择顺序挑选第一个已配置的
语音提供商。
## 配置
TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
完整模式请参阅 [Gateway 配置](/zh-CN/gateway/configuration)。
完整 schema 请见 [Gateway 网关配置](/zh-CN/gateway/configuration)。
### 最小配置（启用 + 提供商）
@ -85,7 +91,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
### OpenAI 为主，ElevenLabs 为后备
### OpenAI 作为主提供商，ElevenLabs 作为回退
```json5
{
@ -126,7 +132,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
### Microsoft 为主（无需 API key）
### Microsoft 作为主提供商（无需 API key）
```json5
{
@ -149,7 +155,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
### MiniMax 为主
### MiniMax 作为主提供商
```json5
{
@ -173,7 +179,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
### Google Gemini 为主
### Google Gemini 作为主提供商
```json5
{
@ -193,11 +199,11 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。
}
```
Google Gemini TTS 使用 Gemini API key 路径。一个仅限制到 Gemini API 的 Google Cloud Console API key 在这里也可用，并且它与内置 Google 图像生成提供商使用的是同一种密钥形式。解析顺序为
Google Gemini TTS 使用 Gemini API key 路径。这里可以使用限制为 Gemini API 的 Google Cloud Console API key，并且它与内置 Google 图像生成提供商使用的是同一种 key 样式。解析顺序为
`messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` ->
`GEMINI_API_KEY` -> `GOOGLE_API_KEY`。
### xAI 为主
### xAI 作为主提供商
```json5
{
@ -221,10 +227,9 @@ Google Gemini TTS 使用 Gemini API key 路径。一个仅限制到 Gemini API
xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。
解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。
当前可用语音包括 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认是 `eve`。
`language` 接受一个 BCP-47 标签或 `auto`。
当前可用的语音有 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值是 `eve`。`language` 接受 BCP-47 标记或 `auto`。
### 禁用 Microsoft speech
### 禁用 Microsoft 语音
```json5
{
@ -255,7 +260,7 @@ xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。
}
```
### 仅在入站语音消息后回复音频
### 仅在收到入站语音消息后回复音频
```json5
{
@ -267,7 +272,7 @@ xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。
}
```
### 对长回复禁用自动摘要
### 为长回复禁用自动摘要
```json5
{
@ -281,7 +286,7 @@ xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。
然后运行：
```text
```
/tts summary off
```
@ -289,32 +294,32 @@ xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。
- `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。
- `inbound` 仅在收到入站语音消息后发送音频。
- `tagged` 仅当回复中包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。
- `enabled`：旧版开关（Doctor 会将其迁移为 `auto`）。
- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。
- `provider`：speech 提供商 id，例如 `"elevenlabs"`、`"google"`、`"microsoft"`、`"minimax"` 或 `"openai"`（后备自动处理）。
- 如果 `provider` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的 speech 提供商。
- 旧版 `provider: "edge"` 仍可使用，并会被标准化为 `microsoft`。
- `summaryModel`：可选的低成本模型，用于自动摘要；默认使用 `agents.defaults.model.primary`。
- `tagged` 仅在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。
- `enabled`：旧版开关（Doctor 会将其迁移到 `auto`）。
- `mode`：`"final"`（默认）或 `"all"`（包含工具/分块回复）。
- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"microsoft"`、`"minimax"` 或 `"openai"`（回退自动处理）。
- 如果 `provider` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。
- 旧版 `provider: "edge"` 仍然可用，并会规范化为 `microsoft`。
- `summaryModel`：用于自动摘要的可选低成本模型；默认为 `agents.defaults.model.primary`。
- 接受 `provider/model` 或已配置的模型别名。
- `modelOverrides`：允许模型发出 TTS 指令（默认开启）。
- `allowProvider` 默认为 `false`（切换提供商需要显式选择加入）。
- `providers.<id>`：按 speech 提供商 id 键控的提供商自有设置。
- `modelOverrides`：允许模型为 TTS 输出指令（默认开启）。
- `allowProvider` 默认为 `false`（切换提供商需要显式启用）。
- `providers.<id>`：按语音提供商 id 键控的、由提供商拥有的设置。
- 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）会在加载时自动迁移到 `messages.tts.providers.<id>`。
- `maxTextLength`：TTS 输入的硬上限（字符数）。超出时 `/tts audio` 会失败。
- `maxTextLength`：TTS 输入的硬上限（字符数）。超过该限制时，`/tts audio` 会失败。
- `timeoutMs`：请求超时（毫秒）。
- `prefsPath`：覆盖本地 prefs JSON 路径（提供商/限制/摘要）。
- `apiKey` 值会回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`）。
- `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API 基础 URL。
- `providers.openai.baseUrl`：覆盖 OpenAI TTS 端点。
- 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1`
- 非默认值会被视为 OpenAI 兼容 TTS 端点，因此可接受自定义模型名和语音名。
- 非默认值会被视为与 OpenAI 兼容的 TTS 端点，因此接受自定义模型名和语音名。
- `providers.elevenlabs.voiceSettings`：
- `stability`、`similarityBoost`、`style`：`0..1`
- `useSpeakerBoost`：`true|false`
- `speed`：`0.5..2.0`（1.0 = 正常）
- `providers.elevenlabs.applyTextNormalization`：`auto|on|off`
- `providers.elevenlabs.languageCode`：2 字母 ISO 639-1 代码（例如 `en`、`de`）
- `providers.elevenlabs.languageCode`：2 位 ISO 639-1 代码（例如 `en`、`de`）
- `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力提供确定性）
- `providers.minimax.baseUrl`：覆盖 MiniMax API 基础 URL（默认 `https://api.minimax.io`，环境变量：`MINIMAX_API_HOST`）。
- `providers.minimax.model`：TTS 模型（默认 `speech-2.8-hd`，环境变量：`MINIMAX_TTS_MODEL`）。
@ -325,50 +330,49 @@ xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。
- `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。
- `providers.google.voiceName`：Gemini 预置语音名称（默认 `Kore`；也接受 `voice`）。
- `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。仅接受 `https://generativelanguage.googleapis.com`。
- 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以在回退到环境变量前复用 `models.providers.google.apiKey`。
- 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以在回退到环境变量之前复用 `models.providers.google.apiKey`。
- `providers.xai.apiKey`：xAI TTS API key（环境变量：`XAI_API_KEY`）。
- `providers.xai.baseUrl`：覆盖 xAI TTS 基础 URL（默认 `https://api.x.ai/v1`，环境变量：`XAI_BASE_URL`）。
- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前可用语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。
- `providers.xai.language`：BCP-47 语言代码或 `auto`（默认 `en`）。
- `providers.xai.responseFormat`：`mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`（默认 `mp3`）。
- `providers.xai.speed`：提供商原生速度覆盖。
- `providers.microsoft.enabled`：允许使用 Microsoft speech（默认 `true`；无 API key）。
- `providers.microsoft.voice`：Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。
- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无需 API key）。
- `providers.microsoft.voice`：Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。
- `providers.microsoft.lang`：语言代码（例如 `en-US`）。
- `providers.microsoft.outputFormat`：Microsoft 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。
- 有效值请参阅 Microsoft Speech 输出格式；并非所有格式都受内置的基于 Edge 的传输支持。
- 有效值请参见 Microsoft Speech 输出格式；并非所有格式都受内置 Edge 后端传输支持。
- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。
- `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。
- `providers.microsoft.proxy`：Microsoft speech 请求的代理 URL。
- `providers.microsoft.saveSubtitles`：将 JSON 字幕与音频文件一起写出。
- `providers.microsoft.proxy`：用于 Microsoft 语音请求的代理 URL。
- `providers.microsoft.timeoutMs`：请求超时覆盖（毫秒）。
- `edge.*`：相同 Microsoft 设置的旧版别名。
- `edge.*`：同一组 Microsoft 设置的旧版别名。
## 模型驱动覆盖（默认开启）
## 模型驱动的覆盖（默认开启）
默认情况下，模型**可以**为单条回复发出 TTS 指令。
当 `messages.tts.auto` 为 `tagged` 时，这些指令是触发音频所必需的。
默认情况下，模型**可以**为单条回复输出 TTS 指令。
当 `messages.tts.auto` 为 `tagged` 时，必须使用这些指令才能触发音频。
启用后，模型可以发出 `[[tts:...]]` 指令，为单条回复覆盖语音，
并可选提供一个 `[[tts:text]]...[[/tts:text]]` 块，
用于加入富表现力标签（笑声、歌唱提示等），这些内容只会出现在
启用后，模型可以输出 `[[tts:...]]` 指令来覆盖单条回复的语音，
还可以选择性输出 `[[tts:text]]...[[/tts:text]]` 块，以提供表达性标签（笑声、歌唱提示等），这些内容应只出现在
音频中。
除非设置了 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。
除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。
示例回复负载：
回复载荷示例：
```text
```
Here you go.
[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]
```
可用指令键（启用时）：
可用的指令键（启用时）：
- `provider`（已注册的 speech 提供商 id，例如 `openai`、`elevenlabs`、`google`、`minimax` 或 `microsoft`；需要 `allowProvider: true`）
- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`minimax` 或 `microsoft`；需要 `allowProvider: true`）
- `voice`（OpenAI 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音），或 `voiceId`（ElevenLabs / MiniMax / xAI）
- `model`（OpenAI TTS 模型、ElevenLabs model id 或 MiniMax 模型）或 `google_model`（Google TTS 模型）
- `model`（OpenAI TTS 模型、ElevenLabs 模型 id 或 MiniMax 模型），或 `google_model`（Google TTS 模型）
- `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost`
- `vol` / `volume`（MiniMax 音量，0-10）
- `pitch`（MiniMax 音高，-12 到 12）
@ -390,7 +394,7 @@ Here you go.
}
```
可选的允许列表（启用提供商切换，同时保持其他参数可配置）：
可选 allowlist（启用提供商切换，同时保持其他可调参数仍可配置）：
```json5
{
@ -406,75 +410,74 @@ Here you go.
}
```
## 按用户划分的偏好设置
## 按用户偏好
斜杠命令会将本地覆盖写入 `prefsPath`（默认：
`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或
`messages.tts.prefsPath` 覆盖）。
存储字段：
存储的字段：
- `enabled`
- `provider`
- `maxLength`（摘要阈值；默认 1500 字符）
- `maxLength`（摘要阈值；默认 1500 个字符）
- `summarize`（默认 `true`）
这些字段会覆盖该宿主上的 `messages.tts.*`。
这些字段会覆盖该主机上的 `messages.tts.*`。
## 输出格式（固定）
- **Feishu / Matrix / Telegram / WhatsApp**：Opus 语音消息（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。
- 48 kHz / 64 kbps 是较适合语音消息的折中方案。
- 48 kHz / 64 kbps 是语音消息较好的折中方案。
- **其他渠道**：MP3（ElevenLabs 使用 `mp3_44100_128`，OpenAI 使用 `mp3`）。
- 44.1 kHz / 128 kbps 是语音清晰度的默认平衡选择。
- **MiniMax**：MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。原生不支持语音便笺格式；如果你需要有保证的 Opus 语音消息，请使用 OpenAI 或 ElevenLabs。
- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，而在 Talk/电话场景下直接返回 PCM。该路径不支持原生 Opus 语音便笺格式。
- **xAI**：默认使用 MP3；`responseFormat` 可以是 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS 端点，并返回完整音频附件；此提供商路径不会使用 xAI 的流式 TTS WebSocket。该路径不支持原生 Opus 语音便笺格式。
- 44.1 kHz / 128 kbps 是语音清晰度的默认平衡。
- **MiniMax**：MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。原生不支持语音便签格式；如果你需要保证 Opus 语音消息，请使用 OpenAI 或 ElevenLabs。
- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 以供音频附件使用，并为 Talk/电话场景直接返回 PCM。此路径不支持原生 Opus 语音便签格式。
- **xAI**：默认使用 MP3；`responseFormat` 可为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS 端点，并返回完整音频附件；该提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便签格式。
- **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。
- 内置传输接受 `outputFormat`，但并非所有格式都能从该服务获得。
- 内置传输支持 `outputFormat`，但并非服务提供的所有格式都可用。
- 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。
- Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要
有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。
- 如果已配置的 Microsoft 输出格式失败，OpenClaw 会回退到 MP3 重试。
保证 Opus 语音消息，请使用 OpenAI/ElevenLabs。
- 如果配置的 Microsoft 输出格式失败，OpenClaw 会回退重试 MP3。
OpenAI/ElevenLabs 输出格式按渠道固定（见上文）。
OpenAI/ElevenLabs 输出格式会根据渠道固定（见上文）。
## 自动 TTS 行为
启用后，OpenClaw 会：
- 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。
- 如果回复已经包含媒体或 `MEDIA:` 指令，则跳过 TTS。
- 跳过非常短的回复（少于 10 个字符）。
- 在启用时使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复生成摘要。
- 在启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。
- 将生成的音频附加到回复中。
如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API key），则会跳过音频，
仅发送普通文本回复。
如果回复超过 `maxLength` 且摘要关闭（或摘要模型没有 API key），则会跳过音频，并发送普通文本回复。
## 流程图
```text
Reply -> TTS enabled?
no -> send text
yes -> has media / MEDIA: / short?
yes -> send text
no -> length > limit?
no -> TTS -> attach audio
yes -> summary enabled?
no -> send text
yes -> summarize (summaryModel or agents.defaults.model.primary)
-> TTS -> attach audio
```
回复 -> 是否启用 TTS？
否 -> 发送文本
是 -> 是否有媒体 / MEDIA: / 太短？
是 -> 发送文本
否 -> 长度 > 限制？
否 -> TTS -> 附加音频
是 -> 是否启用摘要？
否 -> 发送文本
是 -> 摘要（summaryModel 或 agents.defaults.model.primary）
-> TTS -> 附加音频
```
## 斜杠命令用法
只有一个命令：`/tts`。
启用细节请参阅 [Slash commands](/zh-CN/tools/slash-commands)。
启用细节请参见 [斜杠命令](/zh-CN/tools/slash-commands)。
Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会
在该平台上注册 `/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。
Discord 说明：`/tts` 是 Discord 内置命令，因此 OpenClaw 会在该平台上注册
`/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。
```text
```
/tts off
/tts on
/tts status
@ -486,26 +489,28 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会
说明：
- 命令要求发送者已获授权（允许列表/所有者规则仍然适用）。
- 命令要求发送方已获授权（allowlist/所有者规则仍然适用）。
- 必须启用 `commands.text` 或原生命令注册。
- 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。
- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。
- 当你希望默认值为 `inbound` 或 `tagged` 时，请使用配置。
- `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。
- `/tts audio` 会生成一次性音频回复（不会将 TTS 切换为开启）。
- `/tts status` 包含最近一次尝试的后备可见性：
- 成功后备：`Fallback: <primary> -> <used>` 加上 `Attempts: ...`
- 失败：`Error: ...` 加上 `Attempts: ...`
- `limit` 和 `summary` 存储在本地 prefs 中，而不是主配置中。
- `/tts audio` 会生成一次性音频回复（不会开启 TTS）。
- `/tts status` 包含最近一次尝试的回退可见性：
- 成功回退：`Fallback: <primary> -> <used>` 加 `Attempts: ...`
- 失败：`Error: ...` 加 `Attempts: ...`
- 详细诊断：`Attempt details: provider:outcome(reasonCode) latency`
- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回），这些信息会显示在 TTS 错误/日志中。
- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误细节和请求 id（当提供商返回时），并会显示在 TTS 错误/日志中。
## 智能体工具
`tts` 工具会将文本转换为语音，并返回一个用于回复投递的音频附件。
当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，
音频会作为语音消息投递，而不是文件附件。
当渠道是 Feishu、Matrix、Telegram 或 WhatsApp 时，
音频会以语音消息而不是文件附件的形式发送。
它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是
按次调用的提供商请求超时，单位为毫秒。
## Gateway RPC
## Gateway 网关 RPC
Gateway 网关方法：

278
docs/zh-CN/tools/video-generation.md
View File

@ -1,76 +1,76 @@
---
read_when:
- 通过智能体生成视频
- 配置视频生成 provider 和模型 +#+#+#+#+#+analysis to=functions.read 早点加盟_input={"path":"/home/runner/work/docs/docs/source/.agents/skills/openclaw-qa-testing/SKILL.md"} code
- 配置视频生成提供商和模型
- 了解 `video_generate` 工具参数
summary: 使用 14 个 provider 后端，通过文本、图像或现有视频生成视频
summary: 使用 14 个提供商后端，根据文本、图像或现有视频生成视频
title: 视频生成
x-i18n:
generated_at: "2026-04-23T21:10:46Z"
generated_at: "2026-04-23T23:22:42Z"
model: gpt-5.4
provider: openai
source_hash: 67b3b0c669489dca7c0903dbd2ddd7b0f3438a3a722c5cb2b78850ecd1906866
source_hash: 4fb4053d417e62d6145f6cd2bc2717ae120ca9a7cff34089ba65d4ba79ec8c75
source_path: tools/video-generation.md
workflow: 15
---
OpenClaw 智能体可以根据文本提示词、参考图像或现有视频生成视频。当前支持 14 个 provider 后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API key 自动选择合适的 provider。
OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。支持 14 个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API key 自动选择合适的提供商。
<Note>
`video_generate` 工具只有在至少有一个视频生成 provider 可用时才会出现。如果你在智能体工具中看不到它，请设置 provider API key，或配置 `agents.defaults.videoGenerationModel`。
只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你在智能体工具中看不到它，请设置提供商 API key 或配置 `agents.defaults.videoGenerationModel`。
</Note>
OpenClaw 将视频生成视为三种运行时模式：
- `generate`：用于不带参考媒体的文生视频请求
- `imageToVideo`：当请求中包含一个或多个参考图像时使用
- `videoToVideo`：当请求中包含一个或多个参考视频时使用
- `generate`：用于没有参考媒体的文生视频请求
- `imageToVideo`：当请求包含一个或多个参考图像时使用
- `videoToVideo`：当请求包含一个或多个参考视频时使用
Providers 可以支持这些模式中的任意子集。工具会在提交前校验当前模式，并在 `action=list` 中报告支持的模式。
提供商可以支持这些模式中的任意子集。工具会在提交前验证当前模式，并在 `action=list` 中报告支持的模式。
## 快速开始
1. 为任意支持的 provider 设置 API key：
1. 为任一受支持的提供商设置 API key：
```bash
export GEMINI_API_KEY="your-key"
```
2. 可选地固定一个默认模型：
2. 可选：固定默认模型：
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
```
3. 向智能体发出请求：
3. 向智能体提出请求：
> Generate a 5-second cinematic video of a friendly lobster surfing at sunset.
> 生成一段 5 秒钟、电影感十足的视频，内容是一只友善的龙虾在日落时分冲浪。
智能体会自动调用 `video_generate`。不需要工具 allowlist。
智能体会自动调用 `video_generate`。无需将该工具加入允许列表。
## 生成视频时会发生什么
视频生成是异步的。当智能体在会话中调用 `video_generate` 时：
视频生成是异步的。当智能体在一个会话中调用 `video_generate` 时：
1. OpenClaw 将请求提交给 provider，并立即返回一个任务 ID。
2. Provider 在后台处理该作业（通常需要 30 秒到 5 分钟，具体取决于 provider 和分辨率）。
3. 当视频准备就绪后，OpenClaw 会通过一个内部完成事件唤醒同一会话。
4. 智能体会将完成的视频发回原始对话中。
1. OpenClaw 将请求提交给提供商，并立即返回一个任务 ID。
2. 提供商在后台处理该任务（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。
3. 当视频准备就绪时，OpenClaw 会通过一个内部完成事件唤醒同一个会话。
4. 智能体会将生成完成的视频发布回原始对话中。
当某个作业正在进行时，同一会话中的重复 `video_generate` 调用会返回当前任务状态，而不是启动新的生成任务。你可以使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 在 CLI 中查看进度。
当任务正在进行时，如果同一会话中再次调用 `video_generate`，将返回当前任务状态，而不是启动另一个生成任务。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可以通过 CLI 检查进度。
在没有会话支持的智能体运行场景之外（例如直接工具调用），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。
在非会话支持的智能体运行之外（例如直接调用工具），该工具会回退为内联生成，并在同一轮返回最终媒体路径。
### 任务生命周期
每个 `video_generate` 请求会经历四个状态：
每个 `video_generate` 请求会经历四种状态：
1. **queued** —— 任务已创建，等待 provider 接收。
2. **running** —— provider 正在处理（通常需要 30 秒到 5 分钟，具体取决于 provider 和分辨率）。
3. **succeeded** —— 视频已准备就绪；智能体被唤醒并将其发布回对话。
4. **failed** —— provider 错误或超时；智能体被唤醒并附带错误详情。
1. **queued** —— 任务已创建，正在等待提供商接受。
2. **running** —— 提供商正在处理（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。
3. **succeeded** —— 视频已准备好；智能体被唤醒并将其发布到对话中。
4. **failed** —— 提供商错误或超时；智能体被唤醒并附带错误详情。
从 CLI 查看状态：
通过 CLI 检查状态：
```bash
openclaw tasks list
@ -78,153 +78,139 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
防止重复：如果当前会话中已有一个 `queued` 或 `running` 状态的视频任务，`video_generate` 会返回现有任务状态，而不是启动新任务。若要显式检查状态而不触发新生成，请使用 `action: "status"`。
防止重复：如果当前会话中已经有一个视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查状态，而不会触发新的生成任务。
## 支持的 providers
## 支持的提供商
| Provider | 默认模型 | 文本 | 图像参考 | 视频参考 | API key |
| 提供商 | 默认模型 | 文本 | 图像参考 | 视频参考 | API key |
| --------------------- | ------------------------------- | ---- | ---------------------------------------------------- | ---------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` |
| BytePlus 1.0 | `seedance-1-0-pro-250528` | 是 | 最多 2 张图（仅 I2V 模型；首帧 + 末帧） | 否 | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | 是 | 最多 2 张图（通过角色指定首帧 + 末帧） | 否 | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | 是 | 最多 9 张参考图 | 最多 3 个视频 | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | 是 | 1 张图 | 否 | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | 是 | 1 张图 | 否 | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | 是 | 1 张图 | 1 个视频 | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图 | 否 | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | 是 | 1 张图 | 1 个视频 | `OPENAI_API_KEY` |
| BytePlus（1.0） | `seedance-1-0-pro-250528` | 是 | 最多 2 张图像（仅 I2V 模型；首帧 + 末帧） | 否 | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | 是 | 最多 2 张图像（通过 role 指定首帧 + 末帧） | 否 | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | 是 | 最多 9 张参考图像 | 最多 3 个视频 | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | 是 | 1 张图像 | 否 | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | 是 | 1 张图像 | 否 | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | 是 | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图像 | 否 | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | 是 | 1 张图像 | 1 个视频 | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `QWEN_API_KEY` |
| Runway | `gen4.5` | 是 | 1 张图 | 1 个视频 | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | 是 | 1 张图 | 否 | `TOGETHER_API_KEY` |
| Vydra | `veo3` | 是 | 1 张图（`kling`） | 否 | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | 是 | 1 张图 | 1 个视频 | `XAI_API_KEY` |
| Runway | `gen4.5` | 是 | 1 张图像 | 1 个视频 | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | 是 | 1 张图像 | 否 | `TOGETHER_API_KEY` |
| Vydra | `veo3` | 是 | 1 张图像（`kling`） | 否 | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | 是 | 1 张图像 | 1 个视频 | `XAI_API_KEY` |
某些 provider 接受额外或替代的 API key 环境变量。详情请参阅各个[provider 页面](#related)。
某些提供商接受其他附加或替代的 API key 环境变量。详情请参见各个[提供商页面](#related)。
运行 `video_generate action=list` 可在运行时查看可用的 provider、模型和运行时模式。
运行 `video_generate action=list` 可在运行时查看可用提供商、模型和运行时模式。
### 声明式能力矩阵
### 声明的能力矩阵
这是 `video_generate`、契约测试和共享实时 sweep 所使用的显式模式契约。
这是 `video_generate`、契约测试以及共享实时扫描所使用的显式模式契约。
| Provider | `generate` | `imageToVideo` | `videoToVideo` | 当前共享实时 lanes |
| 提供商 | `generate` | `imageToVideo` | `videoToVideo` | 当前共享实时通道 |
| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该 provider 需要远程 `http(s)` 视频 URL |
| Alibaba | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为该提供商需要远程 `http(s)` 视频 URL |
| BytePlus | 是 | 是 | 否 | `generate`、`imageToVideo` |
| ComfyUI | 是 | 是 | 否 | 不在共享 sweep 中；工作流专用覆盖位于 Comfy 测试中 |
| ComfyUI | 是 | 是 | 否 | 不在共享扫描中；特定于 workflow 的覆盖范围由 Comfy 测试负责 |
| fal | 是 | 是 | 否 | `generate`、`imageToVideo` |
| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前基于缓冲区的 Gemini/Veo sweep 不接受该输入 |
| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享的 `videoToVideo` 已跳过，因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入 |
| MiniMax | 是 | 是 | 否 | `generate`、`imageToVideo` |
| OpenAI | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前该组织/输入路径需要 provider 侧的 inpaint/remix 访问 |
| Qwen | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该 provider 需要远程 `http(s)` 视频 URL |
| Runway | 是 | 是 | 是 | `generate`、`imageToVideo`；只有当所选模型为 `runway/gen4_aleph` 时才运行 `videoToVideo` |
| OpenAI | 是 | 是 | 是 | `generate`、`imageToVideo`；共享的 `videoToVideo` 已跳过，因为此组织/输入路径当前需要提供商侧的 inpaint/remix 访问 |
| Qwen | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为该提供商需要远程 `http(s)` 视频 URL |
| Runway | 是 | 是 | 是 | `generate`、`imageToVideo`；仅当所选模型为 `runway/gen4_aleph` 时才运行 `videoToVideo` |
| Together | 是 | 是 | 否 | `generate`、`imageToVideo` |
| Vydra | 是 | 是 | 否 | `generate`；共享 `imageToVideo` 被跳过，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL |
| xAI | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该 provider 当前需要远程 MP4 URL |
| Vydra | 是 | 是 | 否 | `generate`；共享的 `imageToVideo` 已跳过，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL |
| xAI | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为该提供商当前需要远程 MP4 URL |
## 工具参数
### 必填
| 参数 | 类型 | 描述 |
| 参数 | 类型 | 说明 |
| --------- | ------ | ----------------------------------------------------------------------------- |
| `prompt` | string | 要生成的视频文本描述（`action: "generate"` 时必填） |
### 内容输入
| 参数 | 类型 | 描述 |
| 参数 | 类型 | 说明 |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `image` | string | 单个参考图像（路径或 URL） |
| `images` | string[] | 多个参考图像（最多 9 张） |
| `imageRoles` | string[] | 与合并后的图像列表一一对应的可选位置角色提示。规范值：`first_frame`、`last_frame`、`reference_image` |
| `images` | string[] | 多个参考图像（最多 9 个） |
| `imageRoles` | string[] | 与合并后的图像列表按位置对应的可选角色提示。规范值：`first_frame`、`last_frame`、`reference_image` |
| `video` | string | 单个参考视频（路径或 URL） |
| `videos` | string[] | 多个参考视频（最多 4 个） |
| `videoRoles` | string[] | 与合并后的视频列表一一对应的可选位置角色提示。规范值：`reference_video` |
| `audioRef` | string | 单个参考音频（路径或 URL）。当 provider 支持音频输入时，可用于背景音乐或语音参考等 |
| `videoRoles` | string[] | 与合并后的视频列表按位置对应的可选角色提示。规范值：`reference_video` |
| `audioRef` | string | 单个参考音频（路径或 URL）。当提供商支持音频输入时，可用于例如背景音乐或语音参考 |
| `audioRefs` | string[] | 多个参考音频（最多 3 个） |
| `audioRoles` | string[] | 与合并后的音频列表一一对应的可选位置角色提示。规范值：`reference_audio` |
| `audioRoles` | string[] | 与合并后的音频列表按位置对应的可选角色提示。规范值：`reference_audio` |
角色提示会按原样转发给 provider。规范值来自
`VideoGenerationAssetRole` 联合类型，但 providers 也可能接受额外的
角色字符串。`*Roles` 数组的条目数不能超过对应参考列表；
一旦出现 off-by-one 错误，就会返回清晰错误。
使用空字符串可使某个槽位保持未设置。
角色提示会按原样转发给提供商。规范值来自 `VideoGenerationAssetRole` 联合类型，但提供商也可能接受额外的角色字符串。`*Roles` 数组的条目数不得多于对应的参考列表；这类 off-by-one 错误会以清晰的错误信息失败。使用空字符串可以将某个位置留空不设值。
### 风格控制
| 参数 | 类型 | 描述 |
| 参数 | 类型 | 说明 |
| ----------------- | ------- | --------------------------------------------------------------------------------------- |
| `aspectRatio` | string | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` 或 `adaptive` |
| `resolution` | string | `480P`、`720P`、`768P` 或 `1080P` |
| `durationSeconds` | number | 目标时长（秒），会四舍五入到最接近的 provider 支持值 |
| `size` | string | 当 provider 支持时使用的尺寸提示 |
| `audio` | boolean | 当支持时，在输出中启用生成音频。它与 `audioRef*`（输入）不同 |
| `watermark` | boolean | 当支持时，切换 provider 的水印功能 |
| `durationSeconds` | number | 目标时长（秒）（会四舍五入到提供商支持的最接近值） |
| `size` | string | 当提供商支持时使用的尺寸提示 |
| `audio` | boolean | 在支持时为输出启用生成音频。它不同于 `audioRef*`（输入） |
| `watermark` | boolean | 在支持时切换提供商水印 |
`adaptive` 是一个 provider 专用哨兵值：对于在其能力中声明了
`adaptive` 的 provider，会原样转发该值（例如 BytePlus
Seedance 使用它根据输入图像尺寸自动检测比例）。未声明该值的
provider 会通过工具结果中的 `details.ignoredOverrides` 报告该值，
从而让该忽略行为可见。
`adaptive` 是一个提供商特定的哨兵值：它会原样转发给在其能力中声明 `adaptive` 的提供商（例如 BytePlus Seedance 会用它根据输入图像尺寸自动检测比例）。未声明该能力的提供商会通过工具结果中的 `details.ignoredOverrides` 暴露该值，以便明确看到该值已被忽略。
### 高级
| 参数 | 类型 | 描述 |
| 参数 | 类型 | 说明 |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` |
| `model` | string | provider/模型覆盖值（例如 `runway/gen4.5`） |
| `model` | string | 提供商/模型覆盖（例如 `runway/gen4.5`） |
| `filename` | string | 输出文件名提示 |
| `providerOptions` | object | 作为 JSON 对象传递的 provider 专用选项（例如 `{"seed": 42, "draft": true}`）。如果 provider 声明了类型化 schema，则会校验键和值类型；未知键或不匹配项会导致该候选项在回退时被跳过。未声明 schema 的 provider 会按原样接收这些选项。运行 `video_generate action=list` 可查看每个 provider 接受哪些选项 |
| `timeoutMs` | number | 可选的提供商请求超时时间（毫秒） |
| `providerOptions` | object | 以 JSON 对象形式提供的提供商特定选项（例如 `{"seed": 42, "draft": true}`）。声明了类型化 schema 的提供商会验证键名和值类型；未知键或不匹配会在回退时跳过该候选项。未声明 schema 的提供商会原样接收这些选项。运行 `video_generate action=list` 可查看各个提供商接受哪些选项 |
并非所有 provider 都支持所有参数。OpenClaw 已经会将时长规范化到最接近的 provider 支持值；同时，当某个回退 provider 暴露不同的控制界面时，它还会重新映射诸如 size 到 aspect-ratio 之类的几何提示。真正不支持的覆盖项会尽最大努力被忽略，并在工具结果中以警告方式报告。硬性能力限制（例如参考输入过多）会在提交前直接失败。
并非所有提供商都支持所有参数。OpenClaw 已经会将时长规范化为提供商支持的最接近值，并且在回退提供商暴露不同控制界面时，也会重新映射像尺寸到纵横比这样的几何提示。真正不受支持的覆盖项会尽最大努力被忽略，并在工具结果中作为警告报告。硬性能力限制（例如参考输入过多）会在提交前失败。
工具结果会报告实际应用的设置。当 OpenClaw 在 provider 回退期间重新映射时长或几何参数时，返回的 `durationSeconds`、`size`、`aspectRatio` 和 `resolution` 值会反映实际提交的内容，而 `details.normalization` 则会记录从请求值到应用值的转换。
工具结果会报告已应用的设置。当 OpenClaw 在提供商回退期间重新映射时长或几何参数时，返回的 `durationSeconds`、`size`、`aspectRatio` 和 `resolution` 值会反映实际提交的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
参考输入也会选择运行时模式：
参考输入也会决定运行时模式：
- 无参考媒体：`generate`
- 没有参考媒体：`generate`
- 任意图像参考：`imageToVideo`
- 任意视频参考：`videoToVideo`
- 参考音频输入不会改变解析后的模式；它们会叠加在图像/视频参考所选的模式之上，并且仅对声明了 `maxInputAudios` 的 provider 生效
- 参考音频输入不会改变解析出的模式；它们会叠加在图像/视频参考所选定的模式之上，并且仅对声明了 `maxInputAudios` 的提供商有效
图像和视频参考混用并不是稳定的共享能力界面。
每次请求最好只使用一种参考类型。
图像和视频参考混用不是稳定的共享能力界面。
建议每个请求只使用一种参考类型。
#### 回退与类型化选项
某些能力检查是在回退层而不是工具边界上应用的，这样即使请求超出了主 provider 的限制，也仍有机会在一个有能力的回退 provider 上运行：
某些能力检查是在回退层而不是工具边界执行的，这样即使请求超出了主提供商的限制，也仍然可以在支持该能力的回退提供商上运行：
- 如果当前候选项未声明 `maxInputAudios`（或声明为
`0`），那么当请求中包含音频参考时，它会被跳过，并尝试下一个候选项。
- 如果当前候选项的 `maxDurationSeconds` 小于请求的
`durationSeconds`，并且候选项未声明
`supportedDurationSeconds` 列表，则该候选项会被跳过。
- 如果请求中包含 `providerOptions`，而当前候选项
显式声明了一个类型化 `providerOptions` schema，则当提供的键不在 schema 中，或值类型不匹配时，该候选项会被跳过。尚未声明 schema 的 provider 会按原样接收这些选项（向后兼容透传）。provider 还可以通过声明一个空 schema
（`capabilities.providerOptions: {}`）来显式拒绝所有 provider 选项，这种情况会产生与类型不匹配相同的跳过结果。
- 如果当前候选项未声明 `maxInputAudios`（或将其声明为 `0`），那么当请求包含音频参考时，该候选项会被跳过，并尝试下一个候选项。
- 如果当前候选项的 `maxDurationSeconds` 低于请求的 `durationSeconds`，并且该候选项未声明 `supportedDurationSeconds` 列表，则会被跳过。
- 如果请求包含 `providerOptions`，且当前候选项显式声明了类型化的 `providerOptions` schema，那么当提供的键不在 schema 中或值类型不匹配时，该候选项会被跳过。尚未声明 schema 的提供商会原样接收这些选项（向后兼容的透传）。提供商可以通过声明空 schema（`capabilities.providerOptions: {}`）来显式选择不接受任何提供商选项，这会产生与类型不匹配相同的跳过行为。
请求中的第一个跳过原因会以 `warn` 级别写入日志，以便运维人员看到
其主 provider 被跳过；后续跳过则以 `debug` 级别记录，以保持长回退链安静。如果所有候选项都被跳过，聚合错误会包含每个候选项的跳过原因。
请求中的第一个跳过原因会以 `warn` 级别记录，以便操作员看到主提供商为何被跳过；后续跳过会以 `debug` 级别记录，以避免冗长的回退链产生过多噪音。如果所有候选项都被跳过，聚合错误会包含每个候选项的跳过原因。
## 动作
## 操作
- **generate**（默认）—— 根据给定提示词和可选参考输入创建视频。
- **status** —— 检查当前会话中正在进行的视频任务状态，而不启动新的生成。
- **list** —— 显示可用的 providers、模型及其能力。
- **status** —— 检查当前会话中正在进行的视频任务状态，而不启动新的生成任务。
- **list** —— 显示可用提供商、模型及其能力。
## 模型选择
生成视频时，OpenClaw 会按以下顺序解析模型：
生成视频时，OpenClaw 按以下顺序解析模型：
1. **`model` 工具参数** —— 如果智能体在调用中显式指定了它。
1. **`model` 工具参数** —— 如果智能体在调用中指定了它。
2. **`videoGenerationModel.primary`** —— 来自配置。
3. **`videoGenerationModel.fallbacks`** —— 按顺序尝试。
4. **自动检测** —— 使用那些具有有效认证的 providers，先从当前默认 provider 开始，然后按字母顺序尝试剩余 providers。
4. **自动检测** —— 使用拥有有效身份验证的提供商，从当前默认提供商开始，然后按字母顺序尝试其余提供商。
如果某个 provider 失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详细信息。
如果某个提供商失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详细信息。
如果你希望视频生成仅使用显式的 `model`、`primary` 和 `fallbacks`
条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
如果你希望视频生成仅使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
```json5
{
@ -239,30 +225,28 @@ provider 会通过工具结果中的 `details.ignoredOverrides` 报告该值，
}
```
## Provider 说明
## 提供商说明
| Provider | 说明 |
| 提供商 | 说明 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 |
| BytePlus 1.0 | Provider id 为 `byteplus`。模型包括：`seedance-1-0-pro-250528`（默认）、`seedance-1-0-pro-t2v-250528`、`seedance-1-0-pro-fast-251015`、`seedance-1-0-lite-t2v-250428`、`seedance-1-0-lite-i2v-250428`。T2V 模型（`*-t2v-*`）不接受图像输入；I2V 模型和通用 `*-pro-*` 模型支持单张参考图像（首帧）。你可以按位置传入图像，或设置 `role: "first_frame"`。当提供了图像时，T2V 模型 ID 会自动切换到对应的 I2V 变体。支持的 `providerOptions` 键：`seed`（number）、`draft`（boolean，会强制 480p）、`camera_fixed`（boolean）。 |
| BytePlus Seedance 1.5 | 需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) 插件。Provider id 为 `byteplus-seedance15`。模型：`seedance-1-5-pro-251215`。使用统一的 `content[]` API。最多支持 2 张输入图像（first_frame + last_frame）。所有输入都必须是远程 `https://` URL。请在每张图像上设置 `role: "first_frame"` / `"last_frame"`，或按位置传入图像。`aspectRatio: "adaptive"` 会根据输入图像自动检测比例。`audio: true` 会映射到 `generate_audio`。`providerOptions.seed`（number）会被转发。 |
| BytePlus Seedance 2.0 | 需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) 插件。Provider id 为 `byteplus-seedance2`。模型：`dreamina-seedance-2-0-260128`、`dreamina-seedance-2-0-fast-260128`。使用统一的 `content[]` API。最多支持 9 张参考图像、3 个参考视频和 3 个参考音频。所有输入都必须是远程 `https://` URL。请为每个资源设置 `role` —— 支持值包括：`"first_frame"`、`"last_frame"`、`"reference_image"`、`"reference_video"`、`"reference_audio"`。`aspectRatio: "adaptive"` 会根据输入图像自动检测比例。`audio: true` 会映射到 `generate_audio`。`providerOptions.seed`（number）会被转发。 |
| ComfyUI | 由工作流驱动的本地或云执行。通过已配置图形支持文生视频和图生视频。 |
| fal | 对长时间运行作业使用基于队列的流程。仅支持单张图像参考。 |
| Google | 使用 Gemini/Veo。支持一张图像或一个视频参考。 |
| MiniMax | 仅支持单张图像参考。 |
| OpenAI | 仅会转发 `size` 覆盖值。其他风格覆盖值（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略，并附带警告。 |
| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会被提前拒绝。 |
| Runway | 支持通过 data URI 使用本地文件。视频转视频需要 `runway/gen4_aleph`。纯文本运行支持 `16:9` 和 `9:16` 宽高比。 |
| Together | 仅支持单张图像参考。 |
| Vydra | 直接使用 `https://www.vydra.ai/api/v1`，以避免认证被重定向丢失。内置 `veo3` 仅支持文生视频；`kling` 需要远程图像 URL。 |
| BytePlus（1.0） | 提供商 id 为 `byteplus`。模型：`seedance-1-0-pro-250528`（默认）、`seedance-1-0-pro-t2v-250528`、`seedance-1-0-pro-fast-251015`、`seedance-1-0-lite-t2v-250428`、`seedance-1-0-lite-i2v-250428`。T2V 模型（`*-t2v-*`）不接受图像输入；I2V 模型和通用 `*-pro-*` 模型支持单张参考图像（首帧）。可按位置传递图像，或设置 `role: "first_frame"`。当提供图像时，T2V 模型 ID 会自动切换到对应的 I2V 变体。支持的 `providerOptions` 键：`seed`（number）、`draft`（boolean，会强制 480p）、`camera_fixed`（boolean）。 |
| BytePlus Seedance 1.5 | 需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) 插件。提供商 id 为 `byteplus-seedance15`。模型：`seedance-1-5-pro-251215`。使用统一的 `content[]` API。最多支持 2 张输入图像（`first_frame` + `last_frame`）。所有输入都必须是远程 `https://` URL。为每张图像设置 `role: "first_frame"` / `"last_frame"`，或按位置传递图像。`aspectRatio: "adaptive"` 会根据输入图像自动检测比例。`audio: true` 会映射为 `generate_audio`。`providerOptions.seed`（number）会被转发。 |
| BytePlus Seedance 2.0 | 需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) 插件。提供商 id 为 `byteplus-seedance2`。模型：`dreamina-seedance-2-0-260128`、`dreamina-seedance-2-0-fast-260128`。使用统一的 `content[]` API。最多支持 9 张参考图像、3 个参考视频和 3 个参考音频。所有输入都必须是远程 `https://` URL。为每个资源设置 `role`——支持的值有：`"first_frame"`、`"last_frame"`、`"reference_image"`、`"reference_video"`、`"reference_audio"`。`aspectRatio: "adaptive"` 会根据输入图像自动检测比例。`audio: true` 会映射为 `generate_audio`。`providerOptions.seed`（number）会被转发。 |
| ComfyUI | 由 workflow 驱动的本地或云端执行。通过已配置的图形支持文生视频和图生视频。 |
| fal | 对长时间运行任务使用基于队列的流程。仅支持单张参考图像。 |
| Google | 使用 Gemini/Veo。支持一张图像参考或一个视频参考。 |
| MiniMax | 仅支持单张参考图像。 |
| OpenAI | 只会转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略，并附带警告。 |
| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会被预先拒绝。 |
| Runway | 通过 data URI 支持本地文件。视频转视频需要 `runway/gen4_aleph`。纯文本运行公开 `16:9` 和 `9:16` 两种纵横比。 |
| Together | 仅支持单张参考图像。 |
| Vydra | 直接使用 `https://www.vydra.ai/api/v1`，以避免身份验证在重定向中丢失。内置 `veo3` 仅支持文生视频；`kling` 需要远程图像 URL。 |
| xAI | 支持文生视频、图生视频，以及远程视频编辑/扩展流程。 |
## Provider 能力模式
## 提供商能力模式
共享视频生成契约现在允许 provider 声明按模式区分的
能力，而不仅仅是扁平的聚合限制。新的 provider
实现应优先使用显式模式块：
共享的视频生成契约现在允许提供商声明按模式划分的能力，而不仅仅是扁平化的聚合限制。新的提供商实现应优先使用显式模式块：
```typescript
capabilities: {
@ -286,47 +270,43 @@ capabilities: {
}
```
像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段，并不足以声明变换模式支持。Providers 应显式声明
`generate`、`imageToVideo` 和 `videoToVideo`，这样实时测试、
契约测试以及共享的 `video_generate` 工具才能确定性地校验模式支持。
像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段，不足以声明转换模式支持。提供商应显式声明 `generate`、`imageToVideo` 和 `videoToVideo`，这样实时测试、契约测试以及共享的 `video_generate` 工具才能以确定性方式验证模式支持。
## 实时测试
对共享内置 provider 的按需实时覆盖：
为共享内置提供商启用实时覆盖（可选）：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
```
仓库包装器：
仓库包装命令：
```bash
pnpm test:live:media video
```
该实时测试文件会从 `~/.profile` 中加载缺失的 provider 环境变量，默认优先使用
实时/环境变量 API key，而不是已存储的认证配置档案，并默认运行一个适合发布的 smoke 测试：
这个实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API key 而不是已存储的身份验证配置档案，并默认运行适合发布的烟雾测试：
- 对 sweep 中每个非 FAL provider 执行 `generate`
- 使用一秒钟的 lobster 提示词
- 每个 provider 的操作上限由 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 控制
（默认 `180000`）
- 对扫描中的每个非 FAL 提供商运行 `generate`
- 使用一秒钟的龙虾提示词
- 每个提供商的操作上限来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`
（默认值为 `180000`）
由于 provider 侧队列延迟可能主导发布时间，FAL 为按需启用：
FAL 需要显式启用，因为提供商侧的队列延迟可能主导发布时间：
```bash
pnpm test:live:media video --video-providers fal
```
设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 还会运行共享 sweep 能够通过本地媒体安全执行的已声明变换模式：
设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，还可以运行共享扫描能够使用本地媒体安全执行的已声明转换模式：
- 当 `capabilities.imageToVideo.enabled` 时运行 `imageToVideo`
- 当 `capabilities.videoToVideo.enabled` 且该 provider/模型
在共享 sweep 中接受基于 buffer 的本地视频输入时运行 `videoToVideo`
- 当 `capabilities.videoToVideo.enabled` 且提供商/模型在共享扫描中接受基于缓冲区的本地视频输入时运行 `videoToVideo`
当前共享的 `videoToVideo` 实时 lane 覆盖：
目前共享的 `videoToVideo` 实时通道覆盖：
- 仅当你选择 `runway/gen4_aleph` 时覆盖 `runway`
- 仅 `runway`，并且只有在你选择 `runway/gen4_aleph` 时
## 配置
@ -353,13 +333,13 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## 相关内容
- [工具概览](/zh-CN/tools)
- [后台任务](/zh-CN/automation/tasks) —— 异步视频生成的任务跟踪
- [Tools Overview](/zh-CN/tools)
- [Background Tasks](/zh-CN/automation/tasks) —— 异步视频生成的任务跟踪
- [Alibaba Model Studio](/zh-CN/providers/alibaba)
- [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international)
- [BytePlus](/zh-CN/concepts/model-providers#byteplus-international)
- [ComfyUI](/zh-CN/providers/comfy)
- [fal](/zh-CN/providers/fal)
- [Google（Gemini）](/zh-CN/providers/google)
- [Google (Gemini)](/zh-CN/providers/google)
- [MiniMax](/zh-CN/providers/minimax)
- [OpenAI](/zh-CN/providers/openai)
- [Qwen](/zh-CN/providers/qwen)
@ -367,5 +347,5 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
- [Together AI](/zh-CN/providers/together)
- [Vydra](/zh-CN/providers/vydra)
- [xAI](/zh-CN/providers/xai)
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults)
- [模型](/zh-CN/concepts/models)
- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults)
- [Models](/zh-CN/concepts/models)