chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
3666cd2096
commit
de700d9e99
@ -2,26 +2,26 @@
|
||||
read_when:
|
||||
- 为插件导入选择合适的 plugin-sdk 子路径
|
||||
- 审查 bundled-plugin 子路径和辅助接口
|
||||
summary: 插件 SDK 子路径目录：按领域分组说明各导入项所在位置
|
||||
title: 插件 SDK 子路径
|
||||
summary: 插件 SDK 子路径目录：按领域分组说明各个导入位于何处
|
||||
title: Plugin SDK 子路径
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T04:20:43Z"
|
||||
generated_at: "2026-04-24T04:27:27Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2436ef1e2ecba9e5d29947819871763a7ca2fafc6cc220676d6147dad8a78247
|
||||
source_hash: 753c7202a8a59ae9e420d436c7f3770ea455d810f2af52b716d438b84b8b986e
|
||||
source_path: plugins/sdk-subpaths.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
plugin SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。
|
||||
本页按用途分组，汇总了常用子路径。生成的完整列表（200 多个子路径）位于 `scripts/lib/plugin-sdk-entrypoints.json`；
|
||||
其中也会出现为 bundled-plugin 预留的辅助子路径，但除非某个文档页面明确将其推广为公开接口，否则它们都属于实现细节。
|
||||
插件 SDK 以 `openclaw/plugin-sdk/` 下的一组窄子路径形式公开。
|
||||
本页按用途对常用子路径进行归类整理。生成的完整 200+ 子路径列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；
|
||||
其中也包含保留给 bundled-plugin 辅助接口的子路径，但除非某个文档页面明确将其作为公开能力推荐，否则它们都属于实现细节。
|
||||
|
||||
关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
|
||||
有关插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
|
||||
|
||||
## 插件入口
|
||||
|
||||
| 子路径 | 关键导出 |
|
||||
| 子路径 | 关键导出 |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
@ -33,180 +33,183 @@ x-i18n:
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
|
||||
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 |
|
||||
| `plugin-sdk/setup` | 共享的设置向导辅助函数、allowlist 提示、设置状态构建器 |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助工具，以及默认账户回退辅助工具 |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 |
|
||||
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 |
|
||||
| `plugin-sdk/account-helpers` | 精简的账户列表 / 账户操作辅助工具 |
|
||||
| `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助函数，以及默认账户回退辅助函数 |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 |
|
||||
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 |
|
||||
| `plugin-sdk/account-helpers` | 窄范围的账户列表 / 账户操作辅助函数 |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助工具，并带有 bundled-contract 回退 |
|
||||
| `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助函数，并在需要时回退到 bundled contract |
|
||||
| `plugin-sdk/command-gating` | 窄范围的命令授权门控辅助函数 |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 收尾辅助工具 |
|
||||
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建器辅助工具 |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 |
|
||||
| `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助工具 |
|
||||
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 |
|
||||
| `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助工具 |
|
||||
| `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 |
|
||||
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助工具 |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助函数 |
|
||||
| `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助函数 |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助函数 |
|
||||
| `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 |
|
||||
| `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助函数 |
|
||||
| `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助函数 |
|
||||
| `plugin-sdk/poll-runtime` | 窄范围的投票规范化辅助函数 |
|
||||
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 |
|
||||
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
|
||||
| `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对以及已配置绑定辅助工具 |
|
||||
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
|
||||
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
|
||||
| `plugin-sdk/channel-status` | 共享渠道状态快照 / 摘要辅助工具 |
|
||||
| `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 基元 |
|
||||
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
|
||||
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
|
||||
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助工具 |
|
||||
| `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
|
||||
| `plugin-sdk/direct-dm` | 共享直接私信认证 / 守卫辅助工具 |
|
||||
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助工具。参阅 [消息呈现](/zh-CN/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | 兼容性 barrel，包含入站去抖、提及匹配、提及策略辅助工具以及 envelope 辅助工具 |
|
||||
| `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖辅助工具 |
|
||||
| `plugin-sdk/channel-mention-gating` | 不包含更宽泛入站运行时接口的精简提及策略辅助工具 |
|
||||
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 |
|
||||
| `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助工具 |
|
||||
| `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对以及已配置绑定辅助函数 |
|
||||
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 |
|
||||
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 |
|
||||
| `plugin-sdk/channel-status` | 共享的渠道状态快照 / 摘要辅助函数 |
|
||||
| `plugin-sdk/channel-config-primitives` | 窄范围的渠道配置 schema 原语 |
|
||||
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 |
|
||||
| `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 |
|
||||
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 |
|
||||
| `plugin-sdk/group-access` | 共享的群组访问决策辅助函数 |
|
||||
| `plugin-sdk/direct-dm` | 共享的直接私信认证 / 守卫辅助函数 |
|
||||
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助函数。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | 面向兼容性的 barrel，包含入站防抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 |
|
||||
| `plugin-sdk/channel-inbound-debounce` | 窄范围的入站防抖辅助函数 |
|
||||
| `plugin-sdk/channel-mention-gating` | 不包含更大范围入站运行时接口的窄范围提及策略和提及文本辅助函数 |
|
||||
| `plugin-sdk/channel-envelope` | 窄范围的入站 envelope 格式化辅助函数 |
|
||||
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 |
|
||||
| `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助函数 |
|
||||
| `plugin-sdk/channel-send-result` | 回复结果类型 |
|
||||
| `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 |
|
||||
| `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助工具 |
|
||||
| `plugin-sdk/channel-contract` | 渠道契约类型 |
|
||||
| `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 |
|
||||
| `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 |
|
||||
| `plugin-sdk/channel-contract` | 渠道 contract 类型 |
|
||||
| `plugin-sdk/channel-feedback` | 反馈 / reaction 接线 |
|
||||
| `plugin-sdk/channel-secret-runtime` | 精简的 secret-contract 辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 |
|
||||
| `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/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-runtime` | 面向提供商插件的运行时 API key 解析辅助函数 |
|
||||
| `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置档写入辅助函数，例如 `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
|
||||
| `plugin-sdk/provider-auth-login` | 用于提供商插件的共享交互式登录辅助工具 |
|
||||
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
|
||||
| `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助函数 |
|
||||
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | 通用提供商 HTTP / 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 辅助工具 |
|
||||
| `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助函数，包括音频转写 multipart form 辅助函数 |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | 窄范围的 web-fetch 配置 / 选择 contract 辅助函数，例如 `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 配置 / 凭证 contract 辅助函数，例如 `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 辅助函数 |
|
||||
| `plugin-sdk/group-activation` | 窄范围的群组激活模式和命令解析辅助函数 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="认证与安全子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送方授权辅助工具 |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 |
|
||||
| `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助工具 |
|
||||
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile / filter 辅助工具 |
|
||||
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助函数 |
|
||||
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置档 / 过滤器辅助函数 |
|
||||
| `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/channel-contract-testing` | 不包含宽泛 testing barrel 的精简渠道契约测试辅助工具 |
|
||||
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
|
||||
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
|
||||
| `plugin-sdk/command-primitives-runtime` | 用于高频渠道路径的轻量级命令文本谓词 |
|
||||
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助工具 |
|
||||
| `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助函数 |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助函数 |
|
||||
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；如果更窄的 adapter / gateway 接口已经足够，优先使用它们 |
|
||||
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 |
|
||||
| `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助函数 |
|
||||
| `plugin-sdk/reply-dedupe` | 窄范围的入站回复去重重置辅助函数 |
|
||||
| `plugin-sdk/channel-contract-testing` | 不包含宽泛 testing barrel 的窄范围渠道 contract 测试辅助函数 |
|
||||
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 |
|
||||
| `plugin-sdk/command-detection` | 共享的命令检测辅助函数 |
|
||||
| `plugin-sdk/command-primitives-runtime` | 用于热渠道路径的轻量级命令文本谓词 |
|
||||
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助函数 |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | 用于渠道 / 插件 secret surface 的精简 secret-contract 收集辅助工具 |
|
||||
| `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` | 请求体大小 / 超时辅助工具 |
|
||||
| `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的窄范围 secret-contract 收集辅助函数 |
|
||||
| `plugin-sdk/secret-ref-runtime` | 面向 secret-contract / 配置解析的窄范围 `coerceSecretRef` 和 SecretRef 类型辅助函数 |
|
||||
| `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和 secret 收集辅助函数 |
|
||||
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 |
|
||||
| `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时接口的窄范围固定 dispatcher 辅助函数 |
|
||||
| `plugin-sdk/ssrf-runtime` | 固定 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` | 精简的运行时环境、日志器、超时、重试和退避辅助工具 |
|
||||
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 |
|
||||
| `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助函数 |
|
||||
| `plugin-sdk/runtime-env` | 窄范围的运行时环境、日志器、超时、重试和退避辅助函数 |
|
||||
| `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/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 接口不可用也可使用 |
|
||||
| `plugin-sdk/text-autolink-runtime` | 不依赖宽泛 text-runtime barrel 的文件引用自动链接检测 |
|
||||
| `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / 配置档辅助函数、原生路由 / 运行时辅助函数 |
|
||||
| `plugin-sdk/reply-runtime` | 共享的入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | 窄范围的回复分发 / 完成辅助函数 |
|
||||
| `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | 精简的文本 / Markdown 分块辅助工具 |
|
||||
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 |
|
||||
| `plugin-sdk/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/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` | 子系统日志器和脱敏辅助工具 |
|
||||
| `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/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` | 子系统日志器和脱敏辅助函数 |
|
||||
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助函数 |
|
||||
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 |
|
||||
| `plugin-sdk/file-lock` | 可重入文件锁辅助函数 |
|
||||
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 |
|
||||
| `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助函数 |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 |
|
||||
| `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 基元 |
|
||||
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
|
||||
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
|
||||
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
|
||||
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 |
|
||||
| `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助工具 |
|
||||
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
|
||||
| `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助工具 |
|
||||
| `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层智能体 harness 接口：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 运行时接口的有界响应体读取器 |
|
||||
| `plugin-sdk/agent-config-primitives` | 窄范围的智能体运行时 config-schema 原语 |
|
||||
| `plugin-sdk/boolean-param` | 宽松的布尔参数读取器 |
|
||||
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 |
|
||||
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 |
|
||||
| `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助原语 |
|
||||
| `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 |
|
||||
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 |
|
||||
| `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助函数 |
|
||||
| `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层 agent harness 接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数，以及 attempt 结果工具函数 |
|
||||
| `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、代理和固定查找辅助函数 |
|
||||
| `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入 proxy / guarded-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 / 日志导入的精简原始记录 / 字符串强制转换与规范化辅助工具 |
|
||||
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
|
||||
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
|
||||
| `plugin-sdk/agent-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>
|
||||
@ -214,63 +217,64 @@ x-i18n:
|
||||
<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/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 |
|
||||
| `plugin-sdk/media-store` | 窄范围媒体存储辅助函数，例如 `saveMediaBuffer` |
|
||||
| `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障切换辅助函数、候选项选择和缺失模型提示 |
|
||||
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图片 / 音频辅助导出 |
|
||||
| `plugin-sdk/text-runtime` | 共享的文本 / Markdown / 日志辅助函数，例如对智能体可见文本的剥离、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数以及安全文本工具函数 |
|
||||
| `plugin-sdk/text-chunking` | 出站文本分块辅助函数 |
|
||||
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 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/image-generation-core` | 共享的图像生成类型、故障切换、认证和注册表辅助函数 |
|
||||
| `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 |
|
||||
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 |
|
||||
| `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` | 为 plugin SDK 使用方重新导出的 `zod` |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` |
|
||||
| `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` | bundled memory-core 辅助接口，用于 manager / config / file / CLI 辅助函数 |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时门面 |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地 provider，以及通用批处理 / 远程辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding contract、注册表访问、本地提供商以及通用批处理 / 远程辅助函数 |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 |
|
||||
| `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 核心运行时辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助工具 |
|
||||
| `plugin-sdk/memory-host-core` | 面向厂商中立的别名，用于 memory host 核心运行时辅助工具 |
|
||||
| `plugin-sdk/memory-host-events` | 面向厂商中立的别名，用于 memory host 事件日志辅助工具 |
|
||||
| `plugin-sdk/memory-host-files` | 面向厂商中立的别名，用于 memory host 文件 / 运行时辅助工具 |
|
||||
| `plugin-sdk/memory-host-markdown` | 面向 memory 相邻插件的共享托管 Markdown 辅助工具 |
|
||||
| `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时门面 |
|
||||
| `plugin-sdk/memory-host-status` | 面向厂商中立的别名，用于 memory host 状态辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储 engine 导出 |
|
||||
| `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 核心运行时辅助函数 |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助函数 |
|
||||
| `plugin-sdk/memory-host-core` | 面向厂商中立的 memory host 核心运行时辅助函数别名 |
|
||||
| `plugin-sdk/memory-host-events` | 面向厂商中立的 memory host 事件日志辅助函数别名 |
|
||||
| `plugin-sdk/memory-host-files` | 面向厂商中立的 memory host 文件 / 运行时辅助函数别名 |
|
||||
| `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助函数 |
|
||||
| `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 |
|
||||
| `plugin-sdk/memory-host-status` | 面向厂商中立的 memory host 状态辅助函数别名 |
|
||||
| `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="保留的 bundled-helper 子路径">
|
||||
| 分类 | 当前子路径 | 预期用途 |
|
||||
| 家族 | 当前子路径 | 预期用途 |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser 插件支持辅助工具（`browser-support` 仍为兼容性 barrel） |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser 插件支持辅助函数（`browser-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` |
|
||||
| 渠道专用辅助函数 | `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>
|
||||
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想通过浏览器操作 Gateway 网关
|
||||
- 你想在不使用 SSH 隧道的情况下获得 Tailnet 访问权限
|
||||
summary: 用于 Gateway 网关的基于浏览器的控制界面（聊天、节点、配置）
|
||||
- 你想在不使用 SSH 隧道的情况下获得 Tailnet 访问能力
|
||||
summary: Gateway 网关的基于浏览器的控制界面（聊天、节点、配置）
|
||||
title: 控制界面
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T02:37:00Z"
|
||||
generated_at: "2026-04-24T04:27:24Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: edf6beb9c485720b6811d9d348bbb4752cf6aae929a9fbc62fc8c4770e762490
|
||||
source_hash: 3dd1234ef8c7fbb753cdb1015426323b75916833d4245b212793a7ee66cfa86f
|
||||
source_path: web/control-ui.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -35,11 +35,11 @@ Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单
|
||||
- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份标头
|
||||
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用 trusted-proxy 身份标头
|
||||
|
||||
仪表板设置面板会为当前浏览器标签页会话保存一个 token 和所选的 gateway URL；不会持久化保存密码。新手引导通常会在首次连接时为共享密钥认证生成一个 gateway token，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证也可使用。
|
||||
仪表板设置面板会为当前浏览器标签页会话保存一个 token 和所选的 Gateway 网关 URL；密码不会被持久化。新手引导通常会在首次连接时为共享密钥认证生成一个 gateway token，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证也可以使用。
|
||||
|
||||
## 设备配对（首次连接）
|
||||
|
||||
当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关会要求进行**一次性配对批准**——即使你位于同一个 Tailnet 中，且设置了 `gateway.auth.allowTailscale: true` 也是如此。这是一项安全措施，用于防止未经授权的访问。
|
||||
当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关会要求你进行**一次性配对批准**——即使你位于同一个 Tailnet 中并启用了 `gateway.auth.allowTailscale: true`。这是为了防止未授权访问的安全措施。
|
||||
|
||||
**你会看到：** “disconnected (1008): pairing required”
|
||||
|
||||
@ -53,98 +53,99 @@ openclaw devices list
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
|
||||
如果浏览器使用变更后的认证详情（角色 / scopes / 公钥）重试配对，之前的待处理请求会被替代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。
|
||||
如果浏览器在重试配对时更改了认证详情（角色/作用域/公钥），之前的待处理请求会被替代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。
|
||||
|
||||
如果浏览器已经完成配对，而你将其权限从只读更改为写入 / 管理员访问，这会被视为批准升级，而不是静默重连。OpenClaw 会保留旧批准的有效状态，阻止更宽权限的重连，并要求你显式批准新的权限范围集合。
|
||||
如果浏览器已经配对，而你将其从只读访问更改为写入/管理员访问，这会被视为批准升级，而不是静默重连。OpenClaw 会保持旧批准仍然有效，阻止更高权限的重连，并要求你显式批准新的作用域集合。
|
||||
|
||||
批准后，设备会被记住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它，否则无需再次批准。有关 token 轮换和撤销，请参阅 [Devices CLI](/zh-CN/cli/devices)。
|
||||
一旦获得批准，该设备就会被记住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它，否则不需要再次批准。有关 token 轮换和撤销，请参见 [Devices CLI](/zh-CN/cli/devices)。
|
||||
|
||||
**注意：**
|
||||
|
||||
- 直接的本地 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会被自动批准。
|
||||
- 直接的 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。
|
||||
- Tailnet 和 LAN 浏览器连接仍然需要显式批准，即使它们来自同一台机器。
|
||||
- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据都需要重新配对。
|
||||
|
||||
## 个人身份（浏览器本地）
|
||||
|
||||
Control UI 支持按浏览器分别设置个人身份（显示名称和头像），该身份会附加到发出的消息上，用于共享会话中的归属标识。它保存在浏览器存储中，仅限当前浏览器配置文件使用，不会同步到其他设备，也不会在服务端持久化保存，除了你实际发送的消息中正常的对话记录作者元数据。清除站点数据或切换浏览器会将其重置为空。
|
||||
Control UI 支持按浏览器区分的个人身份（显示名称和头像），并会将其附加到发出的消息中，以便在共享会话中标明归属。它存储在浏览器存储中，作用域仅限当前浏览器配置文件，不会同步到其他设备，也不会在服务端持久化，除了你实际发送的消息中正常的对话记录作者元数据。清除站点数据或切换浏览器会将其重置为空。
|
||||
|
||||
## 运行时配置端点
|
||||
|
||||
Control UI 会从 `\/__openclaw/control-ui-config.json` 获取其运行时设置。该端点与其他 HTTP 接口一样受相同的 gateway 认证保护：未认证的浏览器无法获取它，成功获取需要已有效的 gateway token / password、Tailscale Serve 身份，或 trusted-proxy 身份。
|
||||
Control UI 会从 ` /__openclaw/control-ui-config.json` 获取其运行时设置。该端点受与其余 HTTP 接口相同的 Gateway 网关认证保护：未认证的浏览器无法获取它，成功获取需要已有效的 gateway token/密码、Tailscale Serve 身份，或 trusted-proxy 身份之一。
|
||||
|
||||
## 语言支持
|
||||
|
||||
Control UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要稍后覆盖，请打开 **Overview -> Gateway Access -> Language**。区域设置选择器位于 Gateway Access 卡片中，而不在 Appearance 下。
|
||||
Control UI 可以在首次加载时根据你的浏览器语言环境进行本地化。若要稍后覆盖，请打开 **Overview -> Gateway Access -> Language**。语言选择器位于 Gateway Access 卡片中，而不在 Appearance 下。
|
||||
|
||||
- 支持的区域设置：`en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th`
|
||||
- 非英文翻译会在浏览器中按需懒加载。
|
||||
- 所选区域设置会保存在浏览器存储中，并在之后访问时重复使用。
|
||||
- 缺失的翻译键会回退到英文。
|
||||
- 支持的语言环境：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`tr`、`uk`、`id`、`pl`、`th`
|
||||
- 非英语翻译会在浏览器中按需懒加载。
|
||||
- 所选语言环境会保存到浏览器存储中，并在未来访问时复用。
|
||||
- 缺失的翻译键会回退到英语。
|
||||
|
||||
## 它目前能做什么
|
||||
|
||||
- 通过 Gateway WS 与模型聊天（`chat.history`, `chat.send`, `chat.abort`, `chat.inject`）
|
||||
- 通过 WebRTC 直接从浏览器连接到 OpenAI Realtime。Gateway 网关使用 `talk.realtime.session` 签发短期有效的 Realtime 客户端密钥；浏览器将麦克风音频直接发送给 OpenAI，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用中继回更大、已配置的 OpenClaw 模型。
|
||||
- 在聊天中流式显示工具调用和实时工具输出卡片（智能体事件）
|
||||
- 渠道：内置渠道以及内置 / 外部插件渠道的状态、QR 登录和按渠道配置（`channels.status`, `web.login.*`, `config.patch`）
|
||||
- 实例：在线状态列表 + 刷新（`system-presence`）
|
||||
- 会话：列表 + 按会话设置模型 / thinking / fast / verbose / trace / reasoning 覆盖项（`sessions.list`, `sessions.patch`）
|
||||
- Dreams：Dreaming 状态、启用 / 禁用切换，以及 Dream Diary 阅读器（`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`）
|
||||
- Cron 作业：列出 / 添加 / 编辑 / 运行 / 启用 / 禁用 + 运行历史（`cron.*`）
|
||||
- Skills：状态、启用 / 禁用、安装、API key 更新（`skills.*`）
|
||||
- 通过 Gateway WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）
|
||||
- 通过 WebRTC 直接从浏览器连接到 OpenAI Realtime。Gateway 网关使用 `talk.realtime.session` 签发短时有效的 Realtime 客户端密钥；浏览器将麦克风音频直接发送给 OpenAI，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用中继回配置好的更大 OpenClaw 模型
|
||||
- 在聊天中流式显示工具调用 + 实时工具输出卡片（智能体事件）
|
||||
- 渠道：内置以及内置/外部插件渠道的状态、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）
|
||||
- 实例：在线列表 + 刷新（`system-presence`）
|
||||
- 会话：列表 + 按会话设置模型/思考/快速/详细/追踪/推理覆盖项（`sessions.list`、`sessions.patch`）
|
||||
- Dreams：Dreaming 状态、启用/禁用切换和 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）
|
||||
- Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）
|
||||
- Skills：状态、启用/禁用、安装、API 密钥更新（`skills.*`）
|
||||
- 节点：列表 + 能力上限（`node.list`）
|
||||
- Exec 批准：编辑 gateway 或节点 allowlists + 为 `exec host=gateway/node` 询问策略（`exec.approvals.*`）
|
||||
- 配置：查看 / 编辑 `~/.openclaw/openclaw.json`（`config.get`, `config.set`）
|
||||
- 配置：带验证地应用并重启（`config.apply`），并唤醒最近活跃的会话
|
||||
- Exec 批准：编辑 gateway 或节点允许列表 + 对 `exec host=gateway/node` 的询问策略（`exec.approvals.*`）
|
||||
- 配置：查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）
|
||||
- 配置：带验证的应用 + 重启（`config.apply`），并唤醒最后一个活跃会话
|
||||
- 配置写入包含 base-hash 保护，以防覆盖并发编辑
|
||||
- 配置写入（`config.set` / `config.apply` / `config.patch`）还会预检已提交配置负载中引用的活动 SecretRef 解析；未解析的活动已提交引用会在写入前被拒绝
|
||||
- 配置 schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象 / wildcard / 数组 / 组合节点上的文档元数据，以及在可用时的插件 + 渠道 schema）；仅当快照具备安全的原始往返能力时，才提供原始 JSON 编辑器
|
||||
- 如果某个快照无法安全地进行原始文本往返，Control UI 会强制使用表单模式，并为该快照禁用原始模式
|
||||
- 原始 JSON 编辑器中的“Reset to saved”会保留原始编写的结构（格式、注释、`$include` 布局），而不是重新渲染扁平化后的快照，因此在快照可安全往返时，外部编辑在重置后仍会保留
|
||||
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防止意外将对象破坏性地转换为字符串
|
||||
- 调试：状态 / 健康 / 模型快照 + 事件日志 + 手动 RPC 调用（`status`, `health`, `models.list`）
|
||||
- 日志：实时 tail gateway 文件日志，并支持过滤 / 导出（`logs.tail`）
|
||||
- 更新：运行包 / git 更新并重启（`update.run`），附带重启报告
|
||||
- 配置写入（`config.set` / `config.apply` / `config.patch`）还会在写入前对提交配置负载中的 ref 执行活跃 SecretRef 解析预检查；无法解析的活跃已提交 ref 会在写入前被拒绝
|
||||
- 配置 schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及在可用时的插件 + 渠道 schema）；仅当快照可以安全进行原始往返时，Raw JSON 编辑器才可用
|
||||
- 如果快照无法安全进行原始往返，Control UI 会强制使用表单模式，并为该快照禁用原始模式
|
||||
- Raw JSON 编辑器中的“Reset to saved”会保留原始编写形态（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全进行原始往返时，外部编辑在重置后仍会保留
|
||||
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防意外把对象损坏为字符串
|
||||
- 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）
|
||||
- 日志：带过滤/导出的 gateway 文件日志实时尾部查看（`logs.tail`）
|
||||
- 更新：运行 package/git 更新 + 重启（`update.run`），并附带重启报告
|
||||
|
||||
Cron 作业面板说明：
|
||||
|
||||
- 对于隔离作业，默认投递方式为公告摘要。如果你希望仅限内部运行，可以切换为 none。
|
||||
- 选择 announce 时会显示 channel / target 字段。
|
||||
- 对于隔离作业，默认投递方式为播报摘要。如果你只想内部运行，可以切换为 none。
|
||||
- 选择 announce 时，会显示渠道/目标字段。
|
||||
- Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。
|
||||
- 对于主会话作业，可用的投递模式包括 webhook 和 none。
|
||||
- 高级编辑控件包括运行后删除、清除智能体覆盖项、cron 精确 / 错开选项、智能体 model / thinking 覆盖项，以及尽力投递切换项。
|
||||
- 表单验证为内联验证，并带有字段级错误；在修复之前，无效值会禁用保存按钮。
|
||||
- 设置 `cron.webhookToken` 可发送专用 bearer token；若省略，则 webhook 发送时不带 auth 标头。
|
||||
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/思考覆盖，以及尽力投递切换。
|
||||
- 表单验证为内联字段级错误；无效值会禁用保存按钮，直到修复为止。
|
||||
- 设置 `cron.webhookToken` 可发送专用 bearer token；如果省略，发送 webhook 时不会带认证标头。
|
||||
- 已弃用的回退：带有 `notify: true` 的旧版已存储作业在迁移前仍可使用 `cron.webhook`。
|
||||
|
||||
## 聊天行为
|
||||
|
||||
- `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，随后响应通过 `chat` 事件流式传输。
|
||||
- 使用相同的 `idempotencyKey` 重新发送时，如果仍在运行中会返回 `{ status: "in_flight" }`，完成后返回 `{ status: "ok" }`。
|
||||
- 出于 UI 安全考虑，`chat.history` 响应有大小限制。当对话记录条目过大时，Gateway 网关可能会截断长文本字段、省略较重的元数据块，并用占位符替换超大消息（`[chat.history omitted: message too large]`）。
|
||||
- 助手 / 生成的图像会作为受管媒体引用持久化，并通过已认证的 Gateway 媒体 URL 返回，因此重新加载不依赖聊天记录响应中原始 base64 图像负载继续存在。
|
||||
- `chat.history` 还会从可见的助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块）、以及泄露的 ASCII / 全角模型控制 token，并省略那些整个可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。
|
||||
- `chat.inject` 会向会话对话记录追加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（不运行智能体，不投递到渠道）。
|
||||
- 聊天头部中的 model 和 thinking 选择器会立即通过 `sessions.patch` 修补当前活动会话；它们是持久的会话覆盖项，而不是仅单轮发送选项。
|
||||
- 通话模式使用已注册的实时语音提供商。请使用 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey` 配置 OpenAI，或者复用 Voice Call 实时提供商配置。浏览器永远不会收到标准 OpenAI API key；它只会收到临时 Realtime 客户端密钥。
|
||||
- `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，随后响应会通过 `chat` 事件进行流式传输。
|
||||
- 使用相同的 `idempotencyKey` 重新发送时，运行中会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。
|
||||
- 出于 UI 安全考虑，`chat.history` 响应有大小限制。当对话记录条目过大时，Gateway 网关可能会截断较长的文本字段、省略较重的元数据块，并用占位符替换过大的消息（`[chat.history omitted: message too large]`）。
|
||||
- 助手/生成的图片会以托管媒体引用的形式持久化，并通过经过认证的 Gateway 网关媒体 URL 返回，因此重新加载时不依赖原始 base64 图片负载仍保留在 `chat.history` 响应中。
|
||||
- `chat.history` 还会从可见助手文本中去除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块），以及泄露的 ASCII/全角模型控制 token，并省略其全部可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。
|
||||
- `chat.inject` 会向会话对话记录附加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（不会运行智能体，也不会向渠道投递）。
|
||||
- 聊天头部中的模型和思考选择器会通过 `sessions.patch` 立即修补当前活跃会话；它们是持久的会话覆盖项，而不是仅单轮发送选项。
|
||||
- Talk 模式使用已注册的实时语音提供商。请通过 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey` 配置 OpenAI，或复用 Voice Call 的实时 provider 配置。浏览器绝不会收到标准 OpenAI API 密钥；它只会收到临时的 Realtime 客户端密钥。
|
||||
- 在 Chat 输入框中，Talk 控件是位于麦克风听写按钮旁边的波形按钮。Talk 启动后，输入框状态行会显示 `Connecting Talk...`，音频连接后显示 `Talk live`，当实时工具调用通过 `chat.send` 咨询已配置的更大 OpenClaw 模型时，则显示 `Asking OpenClaw...`。
|
||||
- 停止：
|
||||
- 点击 **Stop**（调用 `chat.abort`）
|
||||
- 当某次运行处于活跃状态时，普通后续消息会排队。点击已排队消息上的 **Steer** 可将该后续消息注入当前运行轮次。
|
||||
- 输入 `/stop`（或独立的中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可进行带外中止
|
||||
- `chat.abort` 支持 `{ sessionKey }`（无需 `runId`）来中止该会话的所有活跃运行
|
||||
- 当某次运行处于活跃状态时，普通后续消息会排队。点击已排队消息上的 **Steer**，可将该后续消息注入到当前运行中的轮次
|
||||
- 输入 `/stop`（或单独的中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可进行带外中止
|
||||
- `chat.abort` 支持 `{ sessionKey }`（不带 `runId`）来中止该会话的所有活跃运行
|
||||
- 中止后的部分保留：
|
||||
- 当某次运行被中止时，部分助手文本仍可能显示在 UI 中
|
||||
- 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到对话记录历史中
|
||||
- 持久化条目包含中止元数据，因此对话记录消费者可以将中止的部分内容与正常完成输出区分开来
|
||||
- 持久化条目会包含中止元数据，以便对话记录使用方区分中止的部分内容与正常完成输出
|
||||
|
||||
## 托管嵌入
|
||||
|
||||
助手消息可以通过 `[embed ...]` 短代码内联渲染托管的网页内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
|
||||
助手消息可以使用 `[embed ...]` 简码以内联方式渲染托管网页内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
|
||||
|
||||
- `strict`：禁用托管嵌入中的脚本执行
|
||||
- `scripts`：允许交互式嵌入，同时保持源隔离；这是默认值，通常足以支持自包含的浏览器游戏 / 小部件
|
||||
- `trusted`：在 `allow-scripts` 之外再添加 `allow-same-origin`，用于有意需要更高权限的同站文档
|
||||
- `scripts`：允许交互式嵌入，同时保持源隔离；这是默认值，通常足以满足自包含的浏览器游戏/小组件
|
||||
- `trusted`：在 `allow-scripts` 之上再添加 `allow-same-origin`，用于同站点且确实需要更高权限的文档
|
||||
|
||||
示例：
|
||||
|
||||
@ -160,13 +161,13 @@ Cron 作业面板说明：
|
||||
|
||||
仅当嵌入文档确实需要同源行为时才使用 `trusted`。对于大多数由智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。
|
||||
|
||||
绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你确实希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
|
||||
绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你确实想让 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
|
||||
|
||||
## Tailnet 访问（推荐）
|
||||
|
||||
### 集成的 Tailscale Serve（首选）
|
||||
### 集成式 Tailscale Serve（首选）
|
||||
|
||||
让 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 使用 HTTPS 为其提供代理：
|
||||
将 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 通过 HTTPS 为其代理：
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -176,9 +177,9 @@ openclaw gateway --tailscale serve
|
||||
|
||||
- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
|
||||
|
||||
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI / WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行认证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与该标头匹配来验证身份，并且仅当请求通过 Tailscale 的 `x-forwarded-*` 标头命中 loopback 时才接受这些标头。如果你希望即使对于 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"``。
|
||||
对于该异步 Serve 身份路径，来自同一客户端 IP 和认证范围的失败认证尝试会在写入速率限制之前被串行化。因此，同一浏览器发起的并发错误重试在第二个请求上可能会显示 `retry later`，而不是两个普通不匹配并行竞争。
|
||||
无 token 的 Serve 认证假定 gateway 主机是可信的。如果该主机上可能运行不受信任的本地代码，请要求使用 token / password 认证。
|
||||
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket 的 Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行认证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并与该标头匹配来验证身份，并且仅在请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时才接受这些请求。如果你希望即使对 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"``。
|
||||
对于该异步 Serve 身份路径，来自同一客户端 IP 和认证范围的失败认证尝试会在写入速率限制之前被串行化。因此，同一浏览器并发发起的错误重试，在第二个请求上可能会显示 `retry later`，而不是两个普通不匹配请求并行竞争。
|
||||
无 token 的 Serve 认证假定 gateway 主机是可信的。如果该主机上可能运行不受信任的本地代码，请要求使用 token/密码认证。
|
||||
|
||||
### 绑定到 tailnet + token
|
||||
__OC_I18N_900003__
|
||||
@ -190,13 +191,13 @@ __OC_I18N_900003__
|
||||
|
||||
## 不安全的 HTTP
|
||||
|
||||
如果你通过明文 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），浏览器会运行在**非安全上下文**中，并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。
|
||||
如果你通过纯 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），浏览器会运行在**非安全上下文**中，并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。
|
||||
|
||||
文档说明的例外情况：
|
||||
文档化的例外情况：
|
||||
|
||||
- 仅限 localhost 的不安全 HTTP 兼容模式，使用 `gateway.controlUi.allowInsecureAuth=true`
|
||||
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功进行 operator Control UI 认证
|
||||
- 紧急兜底模式 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- 通过 `gateway.controlUi.allowInsecureAuth=true` 启用仅限 localhost 的不安全 HTTP 兼容性
|
||||
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功进行的操作员 Control UI 认证
|
||||
- 应急开关 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**推荐修复方式：** 使用 HTTPS（Tailscale Serve），或在本地打开 UI：
|
||||
|
||||
@ -205,77 +206,78 @@ __OC_I18N_900003__
|
||||
|
||||
**不安全认证开关行为：**
|
||||
__OC_I18N_900004__
|
||||
`allowInsecureAuth` 只是本地兼容性开关：
|
||||
`allowInsecureAuth` 只是一个本地兼容性开关：
|
||||
|
||||
- 它允许 localhost Control UI 会话在非安全 HTTP 上下文中无设备身份继续进行。
|
||||
- 它允许 localhost 的 Control UI 会话在非安全 HTTP 上下文中无设备身份继续进行。
|
||||
- 它不会绕过配对检查。
|
||||
- 它不会放宽远程（非 localhost）设备身份要求。
|
||||
|
||||
**仅限紧急兜底：**
|
||||
**仅限紧急情况：**
|
||||
__OC_I18N_900005__
|
||||
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，这是严重的安全降级。紧急使用后请尽快恢复。
|
||||
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 的设备身份检查，这是一次严重的安全降级。紧急使用后请尽快恢复。
|
||||
|
||||
trusted-proxy 说明：
|
||||
trusted-proxy 注意事项：
|
||||
|
||||
- 成功的 trusted-proxy 认证可以允许**operator** Control UI 会话在无设备身份的情况下接入
|
||||
- 这**不**适用于 node-role Control UI 会话
|
||||
- 同主机上的 loopback 反向代理仍然不能满足 trusted-proxy 认证；请参阅 [Trusted Proxy Auth](/gateway/trusted-proxy-auth)
|
||||
- 成功的 trusted-proxy 认证可以允许**操作员** Control UI 会话在没有设备身份的情况下接入
|
||||
- 这**不**适用于节点角色的 Control UI 会话
|
||||
- 同主机的 loopback 反向代理仍然不能满足 trusted-proxy 认证；参见 [Trusted Proxy Auth](/gateway/trusted-proxy-auth)
|
||||
|
||||
有关 HTTPS 设置指导，请参阅 [Tailscale](/gateway/tailscale)。
|
||||
有关 HTTPS 设置指导，请参见 [Tailscale](/gateway/tailscale)。
|
||||
|
||||
## 内容安全策略
|
||||
|
||||
Control UI 使用了严格的 `img-src` 策略：只允许**同源**资源和 `data:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，也不会发起网络请求。
|
||||
Control UI 附带严格的 `img-src` 策略：仅允许**同源**资源和 `data:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，也不会发起网络请求。
|
||||
|
||||
这在实际中的含义是：
|
||||
这在实践中的含义：
|
||||
|
||||
- 在相对路径下提供的头像和图片（例如 `/avatars/<id>`）仍然可以渲染。
|
||||
- 内联 `data:image/...` URL 仍然可以渲染（适用于协议内负载）。
|
||||
- 由渠道元数据输出的远程头像 URL 会在 Control UI 的头像辅助函数中被剥离，并替换为内置 logo / badge，因此被攻陷或恶意的渠道无法强制 operator 浏览器发起任意远程图片请求。
|
||||
- 内联 `data:image/...` URL 仍然可以渲染（对协议内负载很有用）。
|
||||
- 渠道元数据输出的远程头像 URL 会在 Control UI 的头像辅助函数中被剥离，并替换为内置 logo/badge，因此即使某个渠道遭到入侵或是恶意的，也无法强制操作员浏览器发起任意远程图片请求。
|
||||
|
||||
你无需做任何改动即可获得此行为——它始终开启，且不可配置。
|
||||
你无需做任何更改即可获得此行为——它始终启用，且不可配置。
|
||||
|
||||
## 头像路由认证
|
||||
|
||||
配置了 gateway 认证后，Control UI 头像端点需要与 API 其余部分相同的 gateway token：
|
||||
当 gateway 认证已配置时，Control UI 的头像端点要求使用与其余 API 相同的 gateway token：
|
||||
|
||||
- `GET /avatar/<agentId>` 仅向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 在相同规则下返回头像元数据。
|
||||
- 对这两个路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由一致）。这可以防止头像路由在原本受保护的主机上泄露智能体身份。
|
||||
- Control UI 本身在获取头像时会以 bearer 标头转发 gateway token，并使用已认证的 blob URL，因此图片仍可在仪表板中渲染。
|
||||
- `GET /avatar/<agentId>` 仅向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 会在相同规则下返回头像元数据。
|
||||
- 对任一路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由一致）。这可防止头像路由在其他部分受保护的主机上泄露智能体身份。
|
||||
- Control UI 本身在获取头像时会将 gateway token 作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍可在仪表板中渲染。
|
||||
|
||||
如果你禁用了 gateway 认证（不建议在共享主机上这样做），头像路由也会变为无需认证，这与 gateway 的其余部分保持一致。
|
||||
如果你禁用了 gateway 认证（不建议在共享主机上这样做），头像路由也会像 Gateway 网关的其他部分一样变为未认证。
|
||||
|
||||
## 构建 UI
|
||||
|
||||
Gateway 网关从 `dist/control-ui` 提供静态文件服务。使用以下命令构建：
|
||||
Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建它们：
|
||||
__OC_I18N_900006__
|
||||
可选的绝对 base 路径（当你希望使用固定资源 URL 时）：
|
||||
可选的绝对 base（当你想要固定资源 URL 时）：
|
||||
__OC_I18N_900007__
|
||||
用于本地开发（独立开发服务器）：
|
||||
用于本地开发（单独的开发服务器）：
|
||||
__OC_I18N_900008__
|
||||
然后将 UI 指向你的 Gateway WS URL（例如 `ws://127.0.0.1:18789`）。
|
||||
|
||||
## 调试 / 测试：开发服务器 + 远程 Gateway
|
||||
## 调试/测试：开发服务器 + 远程 Gateway
|
||||
|
||||
Control UI 是静态文件；WebSocket 目标是可配置的，并且可以不同于 HTTP 源。当你希望本地运行 Vite 开发服务器，而 Gateway 运行在其他地方时，这会非常方便。
|
||||
Control UI 是静态文件；WebSocket 目标可配置，并且可以与 HTTP 源不同。当你希望在本地使用 Vite 开发服务器，而 Gateway 网关运行在其他地方时，这会非常方便。
|
||||
|
||||
1. 启动 UI 开发服务器：`pnpm ui:dev`
|
||||
2. 打开如下 URL：
|
||||
__OC_I18N_900009__
|
||||
可选的一次性认证（如果需要）：
|
||||
可选的一次性认证（如需要）：
|
||||
__OC_I18N_900010__
|
||||
说明：
|
||||
注意：
|
||||
|
||||
- `gatewayUrl` 会在加载后存储到 localStorage 中，并从 URL 中移除。
|
||||
- `token` 应尽可能通过 URL 片段（`#token=...`）传递。片段不会发送到服务器，这样可以避免请求日志和 Referer 泄露。为了兼容性，旧版 `?token=` 查询参数仍会被一次性导入，但仅作为后备方案，并会在引导后立即移除。
|
||||
- `gatewayUrl` 会在加载后存储到 `localStorage` 中，并从 URL 中移除。
|
||||
- 尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这可以避免请求日志和 Referer 泄漏。出于兼容性考虑，旧版 `?token=` 查询参数仍会被一次性导入，但仅作为回退方式，并会在引导后立即剥离。
|
||||
- `password` 仅保存在内存中。
|
||||
- 设置了 `gatewayUrl` 后，UI 不会回退到配置或环境凭证。
|
||||
请显式提供 `token`（或 `password`）。缺少显式凭证会报错。
|
||||
- 当 Gateway 位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
|
||||
- `gatewayUrl` 仅在顶层窗口中接受（不可嵌入），以防止点击劫持。
|
||||
你需要显式提供 `token`（或 `password`）。缺少显式凭证会报错。
|
||||
- 当 Gateway 网关位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
|
||||
- `gatewayUrl` 仅在顶层窗口中被接受（不允许嵌入），以防止点击劫持。
|
||||
- 非 loopback 的 Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整 origin）。这也包括远程开发设置。
|
||||
- 除非是严格受控的本地测试，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任意浏览器 origin，而不是“匹配我当前使用的任意主机”。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头 origin 回退模式，但这是危险的安全模式。
|
||||
- 除非是在严格受控的本地测试中，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。
|
||||
这表示允许任意浏览器 origin，而不是“匹配我正在使用的任意主机”。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头 origin 回退模式，但这是一种危险的安全模式。
|
||||
|
||||
示例：
|
||||
|
||||
@ -289,11 +291,11 @@ __OC_I18N_900010__
|
||||
}
|
||||
```
|
||||
|
||||
远程访问设置详情：[Remote access](/zh-CN/gateway/remote)。
|
||||
远程访问设置详情： [Remote access](/zh-CN/gateway/remote)。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [Dashboard](/zh-CN/web/dashboard) — gateway 仪表板
|
||||
- [Dashboard](/zh-CN/web/dashboard) — Gateway 网关仪表板
|
||||
- [WebChat](/zh-CN/web/webchat) — 基于浏览器的聊天界面
|
||||
- [TUI](/zh-CN/web/tui) — 终端用户界面
|
||||
- [Health Checks](/zh-CN/gateway/health) — gateway 健康监控
|
||||
- [Health Checks](/zh-CN/gateway/health) — Gateway 网关健康监控
|
||||
|
||||
Loading…
Reference in New Issue
Block a user